@proteinjs/db 1.47.2 → 1.47.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.47.2",
+  "version": "1.47.3",
   "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": "08154afae17a9a19c9e48520a3dd67ead7b997c6"
 }

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/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/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' } },
         ]);

package/test/util/tables/sourceRecordSyncTestTables.ts

@@ -9,7 +9,7 @@ import {
 
 /**
  * Fixtures for the source-record sync suites ({@link sourceRecordSyncTests}): a machine-account-
- * shaped mixed table (natural-key adoption + flag-on-removed), a default-policy table (removed =
+ * shaped mixed table (natural-key sync + flag-on-removed), a default-policy table (removed =
  * deleted), a misdeclared natural-key table (non-unique column), and the two-generation table
  * pair driving the unique-index duplicate preflight.
  *
@@ -27,7 +27,7 @@ export interface SyncMachineAccount extends SourceRecord {
   runtimeNote?: string | null;
 }
 
-/** The machine-account shape: natural-key adoption by email, removed rows flagged not deleted. */
+/** The machine-account shape: synced by email, removed rows flagged not deleted. */
 export class SyncMachineAccountTable extends Table<SyncMachineAccount> {
   name = 'db_test_sync_machine_account';
   columns: Table<SyncMachineAccount>['columns'] = withSourceRecordColumns<SyncMachineAccount>({