@proteinjs/db 1.47.2 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.47.2",
+  "version": "1.48.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "5811ffac3d235bce810460223eaa567b9f36a3a6"
+  "gitHead": "ec3fd54430dde18afd406ec70eccd857492272a0"
 }

package/src/Db.ts

@@ -95,6 +95,15 @@ export interface DbDriver {
   ): Promise<SerializedRecord[]>;
   runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement, transaction?: any): Promise<number>;
   runTransaction<T>(fn: (transaction: any) => Promise<T>): Promise<T>;
+  /**
+   * The driver's per-operation deadline, in milliseconds: the longest one statement it runs may
+   * take before the driver fails it — the bound the driver enforces, as configured. Not a whole
+   * transaction's budget (a transaction the database aborts and the driver re-runs may take
+   * longer in all). Code that waits on another request's write — a row it depends on whose insert
+   * may still be in flight — sizes its wait by this, so the wait follows what the deployment
+   * configured its database to tolerate rather than a number of its own.
+   */
+  getOperationDeadlineMs(): number;
 }
 
 export class Db<R extends Record = Record> implements DbService<R> {

package/src/Table.ts

@@ -452,11 +452,18 @@ export type SourceRecordOptions<T = any> = {
    */
   onSourceRemoved?: 'delete' | 'keep' | { update: Partial<T> };
   /**
-   * When set, the sync keys records on this column instead of `id` — matching, adoption, and
-   * the removed reconcile all use it. An existing row matched by natural key is ADOPTED in
-   * place: it keeps its id (the declared id is used only for fresh inserts — existing ids may
-   * be referenced from other tables), gets stamped `is_loaded_from_source = true`, and has its
-   * declared fields reverted to source. Drift comparison excludes `id`, so adoption converges.
+   * When set, the sync keys records on this column instead of `id` — matching and the removed
+   * reconcile both use it. A row the sync already owns (`is_loaded_from_source = true`) matched
+   * by natural key keeps its id (the declared id is used only for fresh inserts — an
+   * environment's own ids may be referenced from other tables) and has its declared fields
+   * reverted to source. Drift comparison excludes `id`, so the id difference converges.
+   *
+   * A row the sync does NOT own that holds the key is never taken over: a natural key is an
+   * identity the world shares (an email a person registered, say), unlike a declared id, which
+   * only the declaration mints. The declaration is REFUSED for that boot — the row left exactly
+   * as it is, the boot continuing, one warning naming the declaration and the key, counted
+   * `refused` in the load summary — and lands as a fresh insert on the first boot after that row
+   * is gone.
    *
    * Preconditions, validated at boot by the loader (loud failures):
    * - the column is declared unique (`ColumnOptions.unique` or a single-column unique index in

package/src/services/TransactionRunnerService.ts

@@ -5,6 +5,26 @@ export const getTransactionRunnerService = serviceFactory<TransactionRunnerServi
   '@proteinjs/db/TransactionRunnerService'
 );
 
+/**
+ * What a write declares about the rows it depends on.
+ *
+ * A client that releases a queued write because its page is going away cannot order that write
+ * behind the writes it depends on — the page is gone before their answers arrive. The server
+ * outlives the page, so the write DECLARES its dependencies and the server honours them.
+ */
+export type TransactionRunOptions = {
+  /**
+   * Ids of rows the operations depend on that may not exist yet: the row an update or a
+   * membership update targets while its insert is still in flight, the permission source a
+   * child row attaches to while the root's own insert (and the owner grant that commits with
+   * it) is still landing. Every id must be a row the operations themselves reference. The
+   * runner waits, bounded, for each to exist AND be visible to the caller before running the
+   * operations; a row that never appears fails the request with a plain clause — never a
+   * silent zero-row write, never a hang.
+   */
+  afterRows?: string[];
+};
+
 export interface TransactionRunnerService extends Service {
-  run(ops: Operation<any>[]): Promise<void>;
+  run(ops: Operation<any>[], options?: TransactionRunOptions): Promise<void>;
 }

package/src/source/SourceRecord.ts

@@ -123,7 +123,9 @@ type OptionalProperties<T> = Pick<
 /**
  * Use this to load a record from source into the db.
  *
- * On Db.init, the record will be inserted if it doesn't exist, and updated if it does exist to mirror what is in source.
+ * On Db.init, the record will be inserted if it doesn't exist, and updated if it does exist to mirror what is in source —
+ * except that a row the sync does not own is never taken over through the table's natural key: the declaration is
+ * refused while such a row holds the key (see `SourceRecordOptions.naturalKey`).
  *
  * If the SourceRecordLoader is deleted from source, the record will be deleted from the db on server startup (per the
  * table's `onSourceRemoved` policy) — by the next boot of a build that still carries the declaring package at its

package/src/source/SourceRecordLoader.ts

@@ -25,6 +25,12 @@ export type SourceRecordTableLoadSummary = {
   updates: number;
   unchanged: number;
   adopted: number;
+  /**
+   * Declarations whose natural key is held by a row the sync does not own (written at runtime —
+   * a person's own row, say): refused for this boot, that row left exactly as it is (see
+   * {@link SourceRecordOptions.naturalKey}).
+   */
+  refused: number;
   deletes: number;
   removedUpdates: number;
   /** Rows stamped by a newer version of their declaring package — left exactly as they are. */
@@ -59,6 +65,12 @@ export class SourceRecordLoader {
    *   tables it no longer declares anything for: dropping the last declaration is a removal.
    * - Rows with no owner stamp (written before `source_package` existed) are claimed by the
    *   declaration that still matches them; the rest are reported as unowned and left alone.
+   * - A declaration never takes over a row the sync does not own through a natural key: a
+   *   natural key (an email, say) is an identity the world shares, so a runtime row holding it
+   *   may be anyone's — that declaration is REFUSED for the boot (the row untouched, the boot
+   *   continuing, one warning naming the declaration, counted `refused`). A declared id, minted
+   *   by the declaration itself, still claims a runtime row holding it (see
+   *   {@link SourceRecordOptions.naturalKey}).
    * - The version stamp records the version that last WROTE the row (its insert or its last
    *   redefinition). A newer version whose declaration is unchanged writes nothing — it neither
    *   re-stamps the version nor bumps `updated` — so a release that touches no declaration
@@ -100,6 +112,7 @@ export class SourceRecordLoader {
       let updateCount = 0;
       let unchangedCount = 0;
       let adoptedCount = 0;
+      let refusedCount = 0;
       let skippedNewer = removed.skippedNewer;
       for (const { source, qualifiedName, name, record } of records) {
         let sourceRecord = record;
@@ -135,6 +148,21 @@ export class SourceRecordLoader {
         }
 
         if (existingRecord) {
+          if (existingRecord.isLoadedFromSource !== true && keyProperty !== 'id') {
+            // A natural key held by a row the sync does not own: never taken over (see load's
+            // ownership model). The row stays exactly as it is and the boot goes on.
+            refusedCount += 1;
+            this.logger.warn({
+              message: `(${table.name}) Refused declaration '${name}': a row the sync does not own holds ${keyProperty} '${(sourceRecord as any)[keyProperty]}' — the row is left untouched and the declaration does not load while it stands`,
+              obj: {
+                declaration: qualifiedName,
+                [keyProperty]: (sourceRecord as any)[keyProperty],
+                id: existingRecord.id,
+              },
+            });
+            continue;
+          }
+
           if (
             existingRecord.sourcePackage === source &&
             this.isNewerStamp(existingRecord.sourcePackageVersion, sourceVersion)
@@ -147,14 +175,16 @@ export class SourceRecordLoader {
           }
 
           if (existingRecord.id !== sourceRecord.id) {
-            // Adopt in place: the existing row keeps its id — other tables may reference it.
-            // The declared id is only ever used for fresh inserts.
+            // A natural-key match on a row the sync owns under an environment's own id (one an
+            // earlier build adopted): the row keeps its id — other tables may reference it. The
+            // declared id is only ever used for fresh inserts.
             sourceRecord = { ...sourceRecord, id: existingRecord.id };
           }
 
           if (existingRecord.isLoadedFromSource !== true) {
-            // A pre-existing (runtime-created) row is being taken over by a declaration —
-            // deliberate, but loud: a declaration asserts ownership of the row's identity.
+            // A runtime-created row holding the declaration's OWN id (natural-key tables never
+            // reach here — refused above) is being taken over by that declaration — deliberate,
+            // but loud: a declaration asserts ownership of the row's identity.
             adoptedCount += 1;
             this.logger.info({
               message: `(${table.name}) Adopting existing record into source ownership`,
@@ -196,6 +226,7 @@ export class SourceRecordLoader {
         updates: updateCount,
         unchanged: unchangedCount,
         adopted: adoptedCount,
+        refused: refusedCount,
         deletes: removed.deleteCount,
         removedUpdates: removed.removedUpdateCount,
         skippedNewer,

package/src/transaction/Transaction.ts

@@ -1,6 +1,7 @@
 import { Record } from '../Record';
 import { DbService, ObjectQuery } from '../services/DbService';
 import { getTransactionRunner } from './TransactionRunner';
+import { TransactionRunOptions } from '../services/TransactionRunnerService';
 import { addDefaultFieldValues, Table } from '../Table';
 import { isInstanceOf } from '@proteinjs/util';
 import { Condition, QueryBuilder } from '@proteinjs/db-query';
@@ -269,14 +270,22 @@ export class Transaction implements OperationQueue {
 
   /**
    * Run the operations in order (not a batch), as a single transaction.
+   *
+   * `options.afterRows` declares rows the operations depend on that may not exist yet (see
+   * {@link TransactionRunOptions}); the server waits for them before running. A run with nothing
+   * to declare hands the runner the operations alone — the request is the one it always was.
    */
-  async run(): Promise<void> {
+  async run(options?: TransactionRunOptions): Promise<void> {
     if (this.ops.length === 0) {
       return;
     }
 
     const runner = getTransactionRunner();
-    await runner.run(this.ops);
+    if (options?.afterRows && options.afterRows.length > 0) {
+      await runner.run(this.ops, { afterRows: options.afterRows });
+    } else {
+      await runner.run(this.ops);
+    }
     this.ops = [];
   }
 }

package/src/transaction/TransactionRunner.ts

@@ -1,10 +1,32 @@
-import { getDb } from '../Db';
-import { TransactionRunnerService, getTransactionRunnerService } from '../services/TransactionRunnerService';
+import { Logger } from '@proteinjs/logger';
+import { Db, getDb } from '../Db';
+import { Table, tableByName } from '../Table';
+import { getDefaultTransactionContextFactory } from './TransactionContextFactory';
+import {
+  TransactionRunnerService,
+  TransactionRunOptions,
+  getTransactionRunnerService,
+} from '../services/TransactionRunnerService';
 import { Operation } from './Transaction';
 
 export const getTransactionRunner = () =>
   typeof self === 'undefined' ? new TransactionRunner() : (getTransactionRunnerService() as TransactionRunner);
 
+/**
+ * Runs a client `Transaction`'s operations as one server-side transaction.
+ *
+ * A write may DECLARE the rows it depends on (`options.afterRows`): rows its operations
+ * reference whose own insert may still be in flight when this request arrives — a text update
+ * released by a page that was going away while its row's insert was still being served, a child
+ * row's insert whose root (its permission source, and the owner grant that commits with the
+ * root) is still landing. Without the declaration such a write ran to completion inside the
+ * insert's window and matched nothing, silently, or was refused at the door for a grant that was
+ * a moment from existing — and the page that could have retried was gone. The server outlives
+ * the page: it waits, bounded by the db driver's per-operation deadline, for every declared row to
+ * exist AND be visible to the caller (a read as the caller sees a row exactly when the caller's
+ * grant on its scope has committed), then runs the operations. A row that never appears fails the
+ * request with a plain clause.
+ */
 export class TransactionRunner implements TransactionRunnerService {
   public serviceMetadata = {
     auth: {
@@ -12,8 +34,17 @@ export class TransactionRunner implements TransactionRunnerService {
     },
   };
 
-  async run(ops: Operation<any>[]): Promise<void> {
+  private static readonly FIRST_POLL_INTERVAL_MS = 25;
+  private static readonly MAX_POLL_INTERVAL_MS = 250;
+
+  private logger = new Logger({ name: this.constructor.name });
+
+  async run(ops: Operation<any>[], options?: TransactionRunOptions): Promise<void> {
     const db = getDb();
+    const afterRows = options?.afterRows ?? [];
+    if (afterRows.length > 0) {
+      await this.awaitRows(ops, afterRows);
+    }
 
     await db.runTransaction(async () => {
       for (const op of ops) {
@@ -21,4 +52,144 @@ export class TransactionRunner implements TransactionRunnerService {
       }
     });
   }
+
+  /**
+   * Wait until every declared row exists and is visible to the caller, bounded by the db driver's
+   * per-operation deadline (`DbDriver.getOperationDeadlineMs`), read when the write waits. The
+   * bound is the ceiling for a row that NEVER comes — the named failure, never a hang. A
+   * dependency's insert lands in hundreds of milliseconds on a healthy link and in seconds on a
+   * degraded one (a root's birth of a few dozen sequential statements has taken 13 s), and the
+   * writes released behind it by a page that is gone have no second chance. The driver's deadline
+   * is how long the deployment lets one statement of that insert run before failing it: the wait
+   * takes its measure from there — one owner for the number, configured with the database — not
+   * from a number of its own. A write that waits here holds one request and a poll, nothing else.
+   *
+   * Each poll is a single-use strong read outside any transaction, so a commit is seen the moment
+   * it lands; the interval starts short and backs off so a dependency landing in hundreds of
+   * milliseconds is caught within tens.
+   */
+  private async awaitRows(ops: Operation<any>[], afterRows: string[]): Promise<void> {
+    if (getDefaultTransactionContextFactory()?.getTransactionContext().currentTransaction) {
+      throw new Error(
+        `TransactionRunner: afterRows cannot be honoured inside an ambient transaction — its reads would see the transaction's own snapshot, never a row committed after it began`
+      );
+    }
+
+    const tablesById = TransactionRunner.rowsTheOperationsReference(ops);
+    const unknown = afterRows.filter((id) => !tablesById.has(id));
+    if (unknown.length > 0) {
+      throw new Error(
+        `TransactionRunner: afterRows names rows none of the operations reference (${unknown.join(', ')}) — the write was not run`
+      );
+    }
+
+    const db = getDb();
+    const boundMs = Db.getDefaultDbDriver().getOperationDeadlineMs();
+    const started = Date.now();
+    const deadline = started + boundMs;
+    /** Per declared id, the (table, id) rows still absent. */
+    let waiting: { id: string; tables: Table<any>[] }[] = afterRows
+      .filter((id, index) => afterRows.indexOf(id) === index)
+      .map((id) => ({ id, tables: tablesById.get(id)!.slice() }));
+    let interval = TransactionRunner.FIRST_POLL_INTERVAL_MS;
+    let polls = 0;
+    for (;;) {
+      polls += 1;
+      for (const row of waiting) {
+        const stillAbsent: Table<any>[] = [];
+        for (const table of row.tables) {
+          if (!(await db.get(table, { id: row.id } as any))) {
+            stillAbsent.push(table);
+          }
+        }
+        row.tables = stillAbsent;
+      }
+      waiting = waiting.filter((row) => row.tables.length > 0);
+      if (waiting.length === 0) {
+        const waitedMs = Date.now() - started;
+        // One line when the seam did work (the row landed while this write waited); a row that
+        // was already there is the common case and stays quiet.
+        const line = { message: `Declared rows present`, obj: { afterRows, waitedMs, polls } };
+        if (polls > 1) {
+          this.logger.info(line);
+        } else {
+          this.logger.debug(line);
+        }
+        return;
+      }
+
+      const now = Date.now();
+      if (now >= deadline) {
+        const absent = waiting.map((row) => row.tables.map((table) => `${table.name}:${row.id}`).join(', ')).join(', ');
+        this.logger.warn({
+          message: `Declared rows absent at the bound — the write was not run`,
+          obj: { absent, boundMs, waitedMs: now - started, polls },
+        });
+        throw new Error(
+          `TransactionRunner: waited ${boundMs} ms for rows this write depends on to exist and be visible to the caller; still absent: ${absent} — the write was not run (the bound is the db driver's per-operation deadline)`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.min(interval, deadline - now)));
+      interval = Math.min(interval * 2, TransactionRunner.MAX_POLL_INTERVAL_MS);
+    }
+  }
+
+  /**
+   * The rows the operations reference, by id → the table(s) they are read from: the permission
+   * source a row attaches to (an insert whose `permissionSource` is another row), the row an
+   * update / preserving update / membership update / delete targets. The rows the operations
+   * insert themselves are not dependencies.
+   */
+  private static rowsTheOperationsReference(ops: Operation<any>[]): Map<string, Table<any>[]> {
+    const inserted: string[] = [];
+    const referenced = new Map<string, Table<any>[]>();
+    const reference = (table: Table<any> | undefined, id: unknown) => {
+      if (!table || typeof id !== 'string') {
+        return;
+      }
+      let tables = referenced.get(id);
+      if (!tables) {
+        tables = [];
+        referenced.set(id, tables);
+      }
+      if (tables.indexOf(table) === -1) {
+        tables.push(table);
+      }
+    };
+
+    for (const op of ops) {
+      const args = op.args as unknown[];
+      const table = args[0] as Table<any> | undefined;
+      if (op.name === 'insert') {
+        const record = args[1] as
+          | { id?: string; permissionSource?: { _table?: string; _id?: string }; permissionSourceTable?: string }
+          | undefined;
+        if (record?.id) {
+          inserted.push(record.id);
+        }
+        const source = record?.permissionSource;
+        if (source?._id && source._id !== record?.id) {
+          const sourceTableName = record?.permissionSourceTable ?? source._table;
+          reference(sourceTableName ? TransactionRunner.tableNamed(sourceTableName, table) : table, source._id);
+        }
+      } else if (op.name === 'update' || op.name === 'updatePreserving') {
+        const record = args[1] as { id?: string } | undefined;
+        const query = args[2] as { id?: unknown } | undefined;
+        reference(table, record?.id ?? (query && typeof query === 'object' && 'id' in query ? query.id : undefined));
+      } else if (op.name === 'updateArrayMembership') {
+        reference(table, (args[1] as { recordId?: string } | undefined)?.recordId);
+      } else if (op.name === 'delete') {
+        const query = args[1] as { id?: unknown } | undefined;
+        reference(table, query && typeof query === 'object' ? query.id : undefined);
+      }
+    }
+
+    inserted.forEach((id) => referenced.delete(id));
+    return referenced;
+  }
+
+  /** The table a permission source lives in: the insert's own table when it names the same one. */
+  private static tableNamed(tableName: string, inserting: Table<any> | undefined): Table<any> {
+    return inserting && inserting.name === tableName ? inserting : tableByName(tableName);
+  }
 }

package/test/reusable/SourceRecordSyncTests.ts

@@ -52,10 +52,11 @@ class RecordingMachineAccountWatcher implements TableWatcher<SyncMachineAccount>
 
 /**
  * Emulator-backed outcome tests for the source-record sync's mixed-table semantics:
- * declare-only ownership (human rows structurally untouchable), natural-key adoption
- * (existing row keeps its id and runtime fields), `onSourceRemoved` policies (flag-not-delete
- * through `Db.update` so watchers fire; default delete unchanged), boot-time natural-key
- * validation, and the unique-index duplicate preflight.
+ * declare-only ownership (human rows structurally untouchable), natural-key sync (an owned row
+ * keeps its id and runtime fields; a row the sync does not own refuses the declaration and is
+ * never taken over), `onSourceRemoved` policies (flag-not-delete through `Db.update` so
+ * watchers fire; default delete unchanged), boot-time natural-key validation, and the
+ * unique-index duplicate preflight.
  */
 export const sourceRecordSyncTests = (
   driver: DbDriver,
@@ -201,39 +202,171 @@ export const sourceRecordSyncTests = (
       expect(afterIdleBoot.updated.valueOf()).toBe(stampBefore);
     });
 
-    test('natural-key adoption: an existing row is adopted in place — id and runtime fields preserved', async () => {
+    test('a natural key held by a row the sync does not own refuses the declaration: the row untouched, the boot continues, the refusal counted and named', async () => {
       const db = getDbAsSystem();
-      // The hand-made bridge row: env-random id, runtime-provisioned fields, never flagged.
-      const handMade = await db.insert(machineTable, {
+      // A row written at runtime that happens to hold the declared natural key — a person's own
+      // row (a signup under the address before the declaration shipped): their fields, their
+      // credential (the runtime note stands in for the password hash), never source-owned.
+      const persons = await db.insert(machineTable, {
         email: 'bridge@test.local',
-        displayName: 'Hand-made bridge',
+        displayName: 'A person',
+        runtimeNote: 'their-password-hash',
+      });
+      const bridge = machineDeclaration({ id: 'declared-id', email: 'bridge@test.local', displayName: 'Ops bridge' });
+      const sibling = machineDeclaration({ id: 'sibling-id', email: 'sibling@test.local', displayName: 'Sibling' });
+
+      const logged: string[] = [];
+      const consoleSpies = (['log', 'info', 'warn', 'error'] as const).map((level) =>
+        jest.spyOn(console, level).mockImplementation((...parts: unknown[]) => {
+          logged.push(parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' '));
+        })
+      );
+      const summary = await boot([bridge, sibling]).finally(() => consoleSpies.forEach((spy) => spy.mockRestore()));
+
+      // The boot continued: the sibling declaration landed; the refused one is counted, not adopted.
+      expect(summary[machineTable.name]).toMatchObject({ inserts: 1, adopted: 0, refused: 1 });
+      expect(await db.get(machineTable, { id: 'sibling-id' })).toMatchObject({ isLoadedFromSource: true });
+      // The person's row is exactly as it was: no declared field, no ownership stamp, no write.
+      const after = await db.get(machineTable, { id: persons.id });
+      expect(after).toMatchObject({
+        email: 'bridge@test.local',
+        displayName: 'A person',
+        runtimeNote: 'their-password-hash',
+      });
+      expect(after.isLoadedFromSource).toBeFalsy();
+      expect(after.sourcePackage).toBeFalsy();
+      expect(after.status).toBeFalsy();
+      expect(after.updated.valueOf()).toBe(persons.updated.valueOf());
+      expect(RecordingMachineAccountWatcher.updates.filter((update) => update.id === persons.id)).toHaveLength(0);
+      // Nothing was inserted under the declared id, and nothing is registered as a source record.
+      expect(await db.get(machineTable, { id: 'declared-id' })).toBeUndefined();
+      expect(new SourceRecordRepo().getSourceRecord(machineTable.name, persons.id)).toBeUndefined();
+      expect(new SourceRecordRepo().getSourceRecord(machineTable.name, 'declared-id')).toBeUndefined();
+      // One plain line names the declaration and the reason.
+      const refusals = logged.filter((line) => line.includes('Refused declaration'));
+      expect(refusals).toHaveLength(1);
+      expect(refusals[0]).toContain('SeededLoader0');
+      expect(refusals[0]).toContain('bridge@test.local');
+      expect(refusals[0]).toContain('does not own');
+
+      // Idempotent: the next boot refuses again and still writes nothing to the row.
+      const again = await boot([bridge, sibling]);
+      expect(again[machineTable.name]).toMatchObject({ inserts: 0, refused: 1 });
+      expect((await db.get(machineTable, { id: persons.id })).updated.valueOf()).toBe(persons.updated.valueOf());
+
+      // Once the row is gone, the declaration lands as a fresh insert under its declared id.
+      await db.delete(machineTable, { id: persons.id });
+      const landed = await boot([bridge, sibling]);
+      expect(landed[machineTable.name]).toMatchObject({ inserts: 1, refused: 0 });
+      const fresh = await db.get(machineTable, { email: 'bridge@test.local' });
+      expect(fresh).toMatchObject({ id: 'declared-id', displayName: 'Ops bridge', isLoadedFromSource: true });
+      expect(fresh.runtimeNote).toBeFalsy();
+    });
+
+    test('a row the sync already owns keeps syncing by its natural key under an environment-random id — id and runtime fields kept, converged boots write nothing', async () => {
+      const db = getDbAsSystem();
+      // The shape of an account a deployed environment adopted in an earlier build: source-owned,
+      // stamped by its package, holding the id the environment gave it (not the declared one),
+      // with a provisioned credential and a declared field that has drifted.
+      const owned = await db.insert(machineTable, {
+        email: 'bridge@test.local',
+        displayName: 'Drifted',
         runtimeNote: 'the-password-hash',
+        status: 'active',
+        isLoadedFromSource: true,
+        sourcePackage: DEFAULT_TEST_SOURCE,
+      });
+      const bridge = machineDeclaration({
+        id: 'declared-owned-id',
+        email: 'bridge@test.local',
+        displayName: 'Ops bridge',
       });
 
-      await boot([machineDeclaration({ id: 'declared-id', email: 'bridge@test.local', displayName: 'Ops bridge' })]);
+      const summary = await boot([bridge]);
 
+      expect(summary[machineTable.name]).toMatchObject({ updates: 1, refused: 0, inserts: 0 });
       const rows = await machineRows({ email: 'bridge@test.local' });
       expect(rows).toHaveLength(1);
-      // Adopted: the existing id survives (scoped rows reference it); declared fields reverted;
-      // runtime fields (the credential) preserved; the row is now source-owned.
       expect(rows[0]).toMatchObject({
-        id: handMade.id,
+        id: owned.id,
         displayName: 'Ops bridge',
-        status: 'active',
         runtimeNote: 'the-password-hash',
         isLoadedFromSource: true,
       });
-      expect(await db.get(machineTable, { id: 'declared-id' })).toBeUndefined();
-
-      // The in-process repo registers the record under the ADOPTED id, not the declared one.
-      expect(new SourceRecordRepo().getSourceRecord(machineTable.name, handMade.id)).toBeDefined();
-      expect(new SourceRecordRepo().getSourceRecord(machineTable.name, 'declared-id')).toBeUndefined();
+      expect(await db.get(machineTable, { id: 'declared-owned-id' })).toBeUndefined();
+      // Registered under the row's own id, not the declared one.
+      expect(new SourceRecordRepo().getSourceRecord(machineTable.name, owned.id)).toBeDefined();
+      expect(new SourceRecordRepo().getSourceRecord(machineTable.name, 'declared-owned-id')).toBeUndefined();
 
-      // Adoption converges: the id difference is not perpetual drift.
+      // The id difference is not perpetual drift.
       const stampBefore = rows[0].updated.valueOf();
-      await boot([machineDeclaration({ id: 'declared-id', email: 'bridge@test.local', displayName: 'Ops bridge' })]);
-      const afterIdleBoot = await db.get(machineTable, { id: handMade.id });
-      expect(afterIdleBoot.updated.valueOf()).toBe(stampBefore);
+      await boot([bridge]);
+      expect((await db.get(machineTable, { id: owned.id })).updated.valueOf()).toBe(stampBefore);
+    });
+
+    test('an owned row that lost its ownership marker outside the sync is refused like any unowned row — never re-stamped, the row and its runtime fields standing; the marker set back is the recovery', async () => {
+      const db = getDbAsSystem();
+      const bridge = machineDeclaration({
+        id: 'declared-lost-id',
+        email: 'bridge@test.local',
+        displayName: 'Ops bridge',
+      });
+      // Boot 1: the declaration lands as a fresh insert — owned and stamped; a credential is minted at runtime.
+      expect((await boot([bridge]))[machineTable.name]).toMatchObject({ inserts: 1, refused: 0 });
+      const owned = await db.get(machineTable, { email: 'bridge@test.local' });
+      expect(owned).toMatchObject({
+        id: 'declared-lost-id',
+        isLoadedFromSource: true,
+        sourcePackage: DEFAULT_TEST_SOURCE,
+      });
+      await db.update(machineTable, { id: owned.id, runtimeNote: 'the-minted-hash' });
+
+      // The marker is cleared outside the sync (a migration, a hand edit — the service door protects it).
+      await db.update(machineTable, { id: owned.id, isLoadedFromSource: false });
+
+      // Boot 2: the sync no longer owns the row, so the declaration is refused and the row is left as
+      // it is — its declared fields, its credential and its status stand; nothing re-stamps it.
+      const refusedBoot = await boot([bridge]);
+      expect(refusedBoot[machineTable.name]).toMatchObject({ inserts: 0, updates: 0, adopted: 0, refused: 1 });
+      const after = await db.get(machineTable, { id: owned.id });
+      expect(after).toMatchObject({
+        email: 'bridge@test.local',
+        displayName: 'Ops bridge',
+        status: 'active',
+        runtimeNote: 'the-minted-hash',
+        isLoadedFromSource: false,
+      });
+      expect(await db.get(machineTable, { id: 'declared-lost-id-other' })).toBeUndefined();
+
+      // The recovery is the marker set back: the next boot owns the row again and writes nothing else.
+      await db.update(machineTable, { id: owned.id, isLoadedFromSource: true });
+      expect((await boot([bridge]))[machineTable.name]).toMatchObject({ inserts: 0, refused: 0, unchanged: 1 });
+      expect(await db.get(machineTable, { id: owned.id })).toMatchObject({
+        runtimeNote: 'the-minted-hash',
+        isLoadedFromSource: true,
+      });
+    });
+
+    test('an id-keyed declaration still claims a runtime row holding its own declared id — the id is minted by the declaration, never shared', async () => {
+      const db = getDbAsSystem();
+      // A row written before the table was source-loaded, under the id the declaration carries
+      // (the insert type omits `id`; the loader's own inserts pass it the same way).
+      await db.insert(defaultPolicyTable, {
+        id: 'legacy-id',
+        email: 'legacy@test.local',
+        displayName: 'Old name',
+      } as unknown as { email: string });
+
+      const summary = await boot([
+        { table: defaultPolicyTable, record: { id: 'legacy-id', email: 'legacy@test.local', displayName: 'Declared' } },
+      ]);
+
+      expect(summary[defaultPolicyTable.name]).toMatchObject({ adopted: 1, refused: 0 });
+      expect(await db.get(defaultPolicyTable, { id: 'legacy-id' })).toMatchObject({
+        displayName: 'Declared',
+        isLoadedFromSource: true,
+        sourcePackage: DEFAULT_TEST_SOURCE,
+      });
     });
 
     test('onSourceRemoved update: removed rows are flagged through Db.update (watchers fire), never deleted; re-declaring reverts', async () => {
@@ -520,10 +653,16 @@ export const sourceRecordSyncTests = (
         expect(deactivations).toHaveLength(0);
       });
 
-      test('cross-source boots leave a natural-key-adopted row in place — adopted id preserved', async () => {
+      test('cross-source boots leave a natural-key-synced row in place — its environment id preserved', async () => {
         const db = getDbAsSystem();
-        // Hand-made row with an environment-random id, adopted by pkg-b via natural key.
-        const handMade = await db.insert(machineTable, { email: 'bridge2@test.local', runtimeNote: 'cred' });
+        // A row pkg-b owns under an environment-random id (adopted by an earlier build), synced
+        // by natural key.
+        const handMade = await db.insert(machineTable, {
+          email: 'bridge2@test.local',
+          runtimeNote: 'cred',
+          isLoadedFromSource: true,
+          sourcePackage: '@test/pkg-b',
+        });
         await bootAsSource('@test/pkg-b', [
           { table: machineTable, record: { id: 'declared-bridge2', email: 'bridge2@test.local', status: 'active' } },
         ]);