@@ -0,0 +1,51 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/platform-objects': minor
+'@objectstack/metadata-protocol': minor
+---
+
+fix(objectql,platform-objects,metadata-protocol)!: the platform's `sys_migration` primary-key lookups go through `findOne`, so an existing deployment no longer prints "Paged read of 'sys_migration' is NOT deterministic" on every boot and every `os migrate plan` (#20648)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (runtime-interface-only packages/platform-objects/src/system/migration-flag.ts#MigrationFlagEngine, packages/metadata-protocol/src/migrations/seed-tenancy-backfill.ts#SeedTenancyLedger) two duck-typed engine interfaces, each the parameter type of a published helper, whose one read method moves from `find` to `findOne`. Neither is a Zod schema, a `packages/spec` declaration or an object definition, neither is a projection of a schema, and no metadata surface references either, so `objectstack migrate meta` has nothing to rewrite. The body carries no migration prescription. The only party affected is the TypeScript author of a hand-written stand-in, and that author's fix is carried by the compiler at their own call site, which names the missing `findOne`. The other categories are closed on facts: both packages publish (not `unpublished`); no ADR-0087 id covers an engine interface's method set, and this diff adds none (not `registered` / `already-registered`); and both interfaces were concretely typed at the merge base, not erased (not `type-surface-only`). This category, not the broader `no-migration-prescription`, because the positive reading it verifies is available here: the named symbols have no metadata surface. -->
+
+The deployment ledger is read one row at a time, by primary key. Five readers
+spelled that read as `find(sys_migration, { where: { id }, limit: 1 })`: the
+engine's migration-gate read (`readMigrationFlagVerified`, behind
+`haveFileColumnsMoved`, `isFileReferencesMigrationVerified` and
+`isValueShapesMigrationVerified`), the engine's deviation marker and
+creation-attestation revocation, `readDataMigrationFlag` in
+`@objectstack/platform-objects/system`, and the seed-tenancy repair's receipt.
+The SQL driver cannot tell that read from page one of a walk. The engine's gate
+read runs at boot before the schema pass registers `sys_migration` with the
+driver, and on a table the driver has not registered an unsorted paged read
+warns that its pages may repeat or skip rows. Measured on a SQLite database
+created by 17.4.0: every 17.5.0 boot and every `os migrate plan` printed that
+warning once, for a lookup that cannot return two rows. All five readers now use
+`findOne`, the single-row route the driver already exempts. The driver's check is
+unchanged: an unsorted `limit` read on a table the driver did not create still
+warns.
+
+**BREAKING**: this narrows what two published engine interfaces accept. The
+first is `MigrationFlagEngine` in `@objectstack/platform-objects/system`. It is
+the parameter type of `readDataMigrationFlag`, `isDataMigrationVerified`,
+`mayActIrreversibly`, `recordDataMigrationRun`, `recordFileColumnMove` and
+`attestFreshDatastore`, and part of `FilesToReferencesEngine` in
+`@objectstack/service-storage`. The second is `SeedTenancyLedger` in
+`@objectstack/metadata-protocol`, the type of a `SeedTenancySeam`'s `ledger`.
+Each now requires `findOne` where it required `find`, so a hand-written stand-in
+that provides only `find` no longer satisfies either type. It ships as `minor`
+under the launch-window convention for accept-set narrowings. The ObjectQL engine
+has both methods, so a host that passes the engine needs no change.
+
+**Your fix:** a stand-in that implemented `find` for these helpers implements
+`findOne(object, options)` instead, answering the row whose `where.id` matches,
+or `null`.
+
+At run time, a stand-in that still provides only `find` fails the read.
+`readDataMigrationFlag` then answers `null`, the same answer as a missing row, so
+the gates it feeds stay closed. `resolveSeedTenancySeam` now attaches a `ledger`
+only for a host that has `getObject`, `findOne`, `insert` and `update`. For a
+find-only host the seam's `ledger` is `undefined`, and when the seed-tenancy
+repair applies, it says at `warn` that it could not record its receipt.
@@ -22,7 +22,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { assertEngineUpdateDispatch } from '@objectstack/metadata-core';
+import { assertEngineFindOnePredicate, assertEngineUpdateDispatch } from '@objectstack/metadata-core';
 import {
   backfillSeedTenancy,
   buildSeedTenancyReceipt,
@@ -579,13 +579,21 @@ describe('#9451 the seed-tenancy repair leaves a durable receipt', () => {
   function fakeLedger(options: { rows?: Record<string, unknown>[]; failWrites?: boolean } = {}) {
     const rows = options.rows ?? [];
     const calls: Array<{ op: string; data: Record<string, unknown> }> = [];
+    const reads: Array<Record<string, unknown>> = [];
     return {
       rows,
       calls,
+      reads,
       ledger: {
         getObject: (name: string) => (name === 'sys_migration' ? { name } : undefined),
-        find: async (_object: string, opts: any) =>
-          rows.filter((r) => r.id === opts?.where?.id).slice(0, opts?.limit ?? rows.length),
+        // The receipt's only read: its own row, through the single-row route
+        // (#20648), held to the real engine's refusal of a query that selects
+        // no particular record.
+        findOne: async (object: string, opts: any) => {
+          reads.push(opts);
+          assertEngineFindOnePredicate(object, opts);
+          return rows.find((r) => r.id === opts.where.id) ?? null;
+        },
         insert: async (_object: string, data: Record<string, unknown>) => {
           if (options.failWrites) throw new Error('no such table: sys_migration');
           calls.push({ op: 'insert', data });
@@ -674,6 +682,9 @@ describe('#9451 the seed-tenancy repair leaves a durable receipt', () => {
     );
 
     expect(result.status).toBe('applied');
+    // #20648: the existence check is a primary-key lookup through `findOne`,
+    // carrying the system context the old `find` read carried.
+    expect(store.reads).toEqual([{ where: { id: SEED_TENANCY_MIGRATION_ID }, context: { isSystem: true } }]);
     expect(store.calls.map((c) => c.op)).toEqual(['insert']);
     const written = store.calls[0].data;
     expect(written.id).toBe(SEED_TENANCY_MIGRATION_ID);
@@ -750,7 +761,10 @@ describe('#9451 the seed-tenancy repair leaves a durable receipt', () => {
     const log = createLogger();
     const noLedger = {
       getObject: () => undefined,
-      find: async () => [],
+      findOne: async (object: string, opts?: any) => {
+        assertEngineFindOnePredicate(object, opts);
+        return null;
+      },
       insert: async () => { throw new Error('must not be called'); },
       update: async (_object: string, data: Record<string, unknown>, opts?: Record<string, unknown>) => {
         assertEngineUpdateDispatch(data as any, opts as any);
@@ -802,7 +816,10 @@ describe('#9451 the seed-tenancy repair leaves a durable receipt', () => {
     const engine = {
       driver: { execute: async () => [], config: { client: 'better-sqlite3' } },
       getObject: () => ({}),
-      find: async () => [],
+      findOne: async (object: string, opts?: any) => {
+        assertEngineFindOnePredicate(object, opts);
+        return null;
+      },
       insert: async () => ({}),
       update: async (_object: string, data: Record<string, unknown>, opts?: Record<string, unknown>) => {
         assertEngineUpdateDispatch(data as any, opts as any);
@@ -814,7 +831,20 @@ describe('#9451 the seed-tenancy repair leaves a durable receipt', () => {
     // A driver-only host resolves an exec but no ledger — the repair still runs
     // and says, loudly, that it could not record itself.
     expect(resolveSeedTenancySeam({ driver: { execute: async () => [] } })?.ledger).toBeUndefined();
-    expect(resolveSeedTenancyLedger({ getObject: () => ({}), find: async () => [] })).toBeUndefined();
+    expect(resolveSeedTenancyLedger({ getObject: () => ({}), findOne: async () => null })).toBeUndefined();
+    // #20648: the receipt reads through `findOne`, so an engine-shaped host
+    // offering only `find` is not a ledger — its receipt read would throw.
+    expect(
+      resolveSeedTenancyLedger({
+        getObject: () => ({}),
+        find: async () => [],
+        insert: async () => ({}),
+        update: async (_object: string, data: Record<string, unknown>, opts?: Record<string, unknown>) => {
+          assertEngineUpdateDispatch(data as any, opts as any);
+          return {};
+        },
+      }),
+    ).toBeUndefined();
   });
 });
 
 
@@ -1001,7 +1001,13 @@ export const SEED_TENANCY_MIGRATION_ID = 'seed-tenancy-backfill';
  */
 export interface SeedTenancyLedger {
   getObject(name: string): unknown;
-  find(object: string, options: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+  /**
+   * The receipt's one read: its own row by primary key, through the engine's
+   * single-row route (#20648). ⛔ Not `find` with `limit: 1` — the SQL driver
+   * reads that as page one of a walk and, on a table it has not registered,
+   * warns that the walk is not deterministic, a false alarm for a key lookup.
+   */
+  findOne(object: string, options: Record<string, unknown>): Promise<Record<string, unknown> | null>;
   insert(object: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
   update(object: string, data: Record<string, unknown>, options: Record<string, unknown>): Promise<unknown>;
 }
@@ -1018,7 +1024,7 @@ export interface SeedTenancyLedger {
  */
 export function resolveSeedTenancyLedger(engine: unknown): SeedTenancyLedger | undefined {
   const candidate = engine as any;
-  for (const method of ['getObject', 'find', 'insert', 'update']) {
+  for (const method of ['getObject', 'findOne', 'insert', 'update']) {
     if (typeof candidate?.[method] !== 'function') return undefined;
   }
   return candidate as SeedTenancyLedger;
@@ -1051,7 +1057,8 @@ export function resolveSeedTenancyLedger(engine: unknown): SeedTenancyLedger | u
  * Verified by enumeration rather than assumed: every consumer of this ledger
  * (`ObjectQL.readMigrationFlagVerified`, `recordObservedDeviation`,
  * `retractCreationAttestation`, and `platform-objects`' `readDataMigrationFlag`)
- * reads `where: { id }, limit: 1`. There is no bulk or aggregate read of
+ * reads one row by `where: { id }` through the engine's `findOne` (#20648).
+ * There is no bulk or aggregate read of
  * `sys_migration` anywhere in the repo, so no reading of these fields under a
  * NEW id can reach another id's gate.
  *
@@ -1098,9 +1105,8 @@ async function persistSeedTenancyReceiptRow(
   flag: DataMigrationFlag,
 ): Promise<'inserted' | 'updated'> {
   const context = { isSystem: true };
-  const rows = await ledger.find(DATA_MIGRATION_FLAG_OBJECT, {
+  const existing = await ledger.findOne(DATA_MIGRATION_FLAG_OBJECT, {
     where: { id: flag.id },
-    limit: 1,
     context,
   });
   const row: Record<string, unknown> = { ...flag, updated_at: flag.last_run_at };
@@ -1110,7 +1116,7 @@ async function persistSeedTenancyReceiptRow(
   // probe finds nothing and later boots return `no-split` — but a run that could
   // only stamp some objects leaves a split behind, and the next boot's row
   // should describe the LATEST attempt.
-  if (rows?.[0]?.id === flag.id) {
+  if (existing?.id === flag.id) {
     await ledger.update(DATA_MIGRATION_FLAG_OBJECT, row, { context });
     return 'updated';
   }
 
@@ -349,7 +349,8 @@ describe('migration-flag memoization: a read that never happened is not an answe
     const store = newStore();
     const engine = boot(store, { created: false });
     const driver: any = (engine as any).drivers.get('default');
-    const find = vi.spyOn(driver, 'find');
+    // [#20648] The flag read is a primary-key lookup through `findOne`.
+    const findOne = vi.spyOn(driver, 'findOne');
 
     await engine.insert('showcase_task', { id: 't1', cover: 'file_01H0000000000000000000' });
     await engine.insert('showcase_task', { id: 't2', cover: 'file_01H0000000000000000001' });
@@ -359,7 +360,7 @@ describe('migration-flag memoization: a read that never happened is not an answe
     // are live — one read each, never one per write. The conclusive negative
     // (the ledger is readable and empty) IS memoized; only "could not ask" is
     // re-asked.
-    const flagReads = find.mock.calls.filter((c: unknown[]) => c[0] === 'sys_migration');
+    const flagReads = findOne.mock.calls.filter((c: unknown[]) => c[0] === 'sys_migration');
     expect(flagReads).toHaveLength(2);
     expect(flagReads.map((c: any) => c[1]?.where?.id).sort()).toEqual(
       [FILE_REFERENCES_MIGRATION_ID, VALUE_SHAPES_MIGRATION_ID].sort(),
 
@@ -2554,6 +2554,8 @@ describe('ObjectQL Engine', () => {
  * evidence cannot be read keeps writing rather than starting to reject.
  */
 describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
+  // [#20648] The flag read is a primary-key lookup through `findOne`, so the
+  // driver's `findOne` is what answers it in every case below.
   let engine: ObjectQL;
   let driver: IDataDriver;
 
@@ -2594,28 +2596,28 @@ describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
 
   it('a verified flag makes a malformed media value reject', async () => {
     withMediaObject();
-    vi.mocked(driver.find).mockResolvedValue([verifiedRow] as any);
+    vi.mocked(driver.findOne).mockResolvedValue(verifiedRow as any);
 
     await expect(engine.insert('note', { ...legacyBlob })).rejects.toThrow(/invalid file value/i);
   });
 
   it('no flag row → lenient (the write goes through)', async () => {
     withMediaObject();
-    vi.mocked(driver.find).mockResolvedValue([]);
+    vi.mocked(driver.findOne).mockResolvedValue(null);
 
     await expect(engine.insert('note', { ...legacyBlob })).resolves.toBeDefined();
   });
 
   it('a failed run (verified_at cleared) → lenient', async () => {
     withMediaObject();
-    vi.mocked(driver.find).mockResolvedValue([{ ...verifiedRow, verified_at: null, blocking: 3 }] as any);
+    vi.mocked(driver.findOne).mockResolvedValue({ ...verifiedRow, verified_at: null, blocking: 3 } as any);
 
     await expect(engine.insert('note', { ...legacyBlob })).resolves.toBeDefined();
   });
 
   it('an unreadable sys_migration → lenient, and the write is not failed by the probe', async () => {
     withMediaObject();
-    vi.mocked(driver.find).mockRejectedValue(new Error('no such table: sys_migration'));
+    vi.mocked(driver.findOne).mockRejectedValue(new Error('no such table: sys_migration'));
 
     await expect(engine.insert('note', { ...legacyBlob })).resolves.toBeDefined();
   });
@@ -2631,44 +2633,45 @@ describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
       if (name === 'sys_migration') return { name: 'sys_migration', fields: { id: { type: 'text' } } } as any;
       return undefined;
     });
-    vi.mocked(driver.find).mockResolvedValue([verifiedRow] as any);
+    vi.mocked(driver.findOne).mockResolvedValue(verifiedRow as any);
 
     await expect(engine.insert('invoice', { amount: 10 })).resolves.toBeDefined();
-    expect(vi.mocked(driver.find).mock.calls.filter((c) => c[0] === 'sys_migration')).toHaveLength(0);
+    expect(vi.mocked(driver.findOne).mock.calls.filter((c) => c[0] === 'sys_migration')).toHaveLength(0);
   });
 
   /** No storage service → no sys_migration object → not even a query. */
   it('costs no query on a kernel without the storage objects', async () => {
     vi.mocked(SchemaRegistry.getObject).mockImplementation((name: string) =>
       name === 'note' ? ({ name: 'note', fields: { doc: { type: 'file' } } } as any) : undefined,
     );
-    vi.mocked(driver.find).mockResolvedValue([]);
+    vi.mocked(driver.findOne).mockResolvedValue(null);
 
     await expect(engine.insert('note', { ...legacyBlob })).resolves.toBeDefined();
     expect(driver.find).not.toHaveBeenCalled();
+    expect(driver.findOne).not.toHaveBeenCalled();
   });
 
   it('reads the flag once per process, not once per write', async () => {
     withMediaObject();
-    vi.mocked(driver.find).mockResolvedValue([verifiedRow] as any);
+    vi.mocked(driver.findOne).mockResolvedValue(verifiedRow as any);
 
     await expect(engine.insert('note', { doc: 'file_01' })).resolves.toBeDefined();
     await expect(engine.insert('note', { doc: 'file_02' })).resolves.toBeDefined();
     await expect(engine.insert('note', { doc: 'file_03' })).resolves.toBeDefined();
 
-    const flagReads = vi.mocked(driver.find).mock.calls.filter((c) => c[0] === 'sys_migration');
+    const flagReads = vi.mocked(driver.findOne).mock.calls.filter((c) => c[0] === 'sys_migration');
     expect(flagReads).toHaveLength(1);
   });
 
   it('invalidateDataMigrationFlags forces a re-read', async () => {
     withMediaObject();
-    vi.mocked(driver.find).mockResolvedValue([verifiedRow] as any);
+    vi.mocked(driver.findOne).mockResolvedValue(verifiedRow as any);
 
     await engine.insert('note', { doc: 'file_01' });
     engine.invalidateDataMigrationFlags();
     await engine.insert('note', { doc: 'file_02' });
 
-    const flagReads = vi.mocked(driver.find).mock.calls.filter((c) => c[0] === 'sys_migration');
+    const flagReads = vi.mocked(driver.findOne).mock.calls.filter((c) => c[0] === 'sys_migration');
     expect(flagReads).toHaveLength(2);
   });
 
@@ -2735,7 +2738,7 @@ describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
         place: { name: 'place', fields: { spot: { type: 'location' } } },
         sys_migration: SYS_MIGRATION,
       });
-      vi.mocked(driver.find).mockResolvedValue([]); // no flag row → gate open
+      vi.mocked(driver.findOne).mockResolvedValue(null); // no flag row → gate open
       const info = vi.spyOn((engine as any).logger, 'info');
 
       await engine.announceOpenMigrationGates();
@@ -2748,7 +2751,7 @@ describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
         note: { name: 'note', fields: { doc: { type: 'file' } } },
         sys_migration: SYS_MIGRATION,
       });
-      vi.mocked(driver.find).mockResolvedValue([]);
+      vi.mocked(driver.findOne).mockResolvedValue(null);
       const info = vi.spyOn((engine as any).logger, 'info');
 
       await engine.announceOpenMigrationGates();
@@ -2763,7 +2766,7 @@ describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
         note: { name: 'note', fields: { doc: { type: 'file' } } },
         sys_migration: SYS_MIGRATION,
       });
-      vi.mocked(driver.find).mockResolvedValue([verifiedRow] as any);
+      vi.mocked(driver.findOne).mockResolvedValue(verifiedRow as any);
       const info = vi.spyOn((engine as any).logger, 'info');
 
       await engine.announceOpenMigrationGates();
@@ -2782,14 +2785,15 @@ describe('ObjectQL — file-as-reference migration flag (#3617)', () => {
 
       expect(lines(info)).not.toMatch(/os migrate/);
       expect(driver.find).not.toHaveBeenCalled();
+    expect(driver.findOne).not.toHaveBeenCalled();
     });
 
     it('announces once per process, not once per caller', async () => {
       registerObjects({
         place: { name: 'place', fields: { spot: { type: 'location' } } },
         sys_migration: SYS_MIGRATION,
       });
-      vi.mocked(driver.find).mockResolvedValue([]);
+      vi.mocked(driver.findOne).mockResolvedValue(null);
       const info = vi.spyOn((engine as any).logger, 'info');
 
       await engine.announceOpenMigrationGates();