@proteinjs/db 1.42.0 → 1.44.0

package/test/reusable/SourceRecordSyncTests.ts

@@ -149,6 +149,7 @@ export const sourceRecordSyncTests = (
       await db.delete(machineTable, {});
       await db.delete(defaultPolicyTable, {});
       await db.delete(sourceRecordSyncTestTables.InheritedStamp, {});
+      await db.delete(sourceRecordSyncTestTables.SyncDerivedName, {});
       RecordingMachineAccountWatcher.updates = [];
     });
 
@@ -266,6 +267,51 @@ export const sourceRecordSyncTests = (
       expect((await db.get(machineTable, { id: 'machine-1' })).status).toBe('active');
     });
 
+    test('soft removal + re-declaration under a renamed natural key: the kept row is adopted by its declared id — reactivated and re-derived, never collided into', async () => {
+      const db = getDbAsSystem();
+      const keeper = machineDeclaration({ id: 'machine-keep', email: 'keeper@test.local' });
+      await boot([machineDeclaration({ id: 'machine-rn', email: 'rn-old@test.local', displayName: 'Ops' }), keeper]);
+      // Runtime-owned state the adoption must preserve (the credential stand-in).
+      await db.update(machineTable, { id: 'machine-rn', runtimeNote: 'provisioned' });
+
+      // The declaration is removed: the update policy KEEPS the row (soft removal).
+      await boot([keeper]);
+      expect((await db.get(machineTable, { id: 'machine-rn' })).status).toBe('deactivated');
+
+      // Re-declared under a NEW email: the natural-key match misses, but the soft-removed row
+      // still holds the declared id. The sync must adopt that row in place — pre-fix this boot
+      // crashed on a PK collision (insert of an id the kept row still occupies).
+      RecordingMachineAccountWatcher.updates = [];
+      const summary = await boot([
+        machineDeclaration({ id: 'machine-rn', email: 'rn-new@test.local', displayName: 'Ops' }),
+        keeper,
+      ]);
+
+      expect(summary[machineTable.name].adopted).toBe(1);
+      expect(await db.get(machineTable, { email: 'rn-old@test.local' })).toBeUndefined();
+      const adopted = await db.get(machineTable, { id: 'machine-rn' });
+      // Reactivated and re-derived from the declaration; runtime-owned state preserved.
+      expect(adopted).toMatchObject({
+        email: 'rn-new@test.local',
+        status: 'active',
+        runtimeNote: 'provisioned',
+        isLoadedFromSource: true,
+      });
+      // No duplicate row was minted: the account's history stays on the one row.
+      expect(await machineRows()).toHaveLength(2);
+      // The reactivation went through Db.update — watchers observed it.
+      const reactivations = RecordingMachineAccountWatcher.updates.filter(
+        (update) => update.id === 'machine-rn' && update.status === 'active'
+      );
+      expect(reactivations).toHaveLength(1);
+      expect(reactivations[0]).toMatchObject({ email: 'rn-new@test.local' });
+
+      // Adoption converges: the next boot writes nothing.
+      const stampBefore = adopted.updated.valueOf();
+      await boot([machineDeclaration({ id: 'machine-rn', email: 'rn-new@test.local', displayName: 'Ops' }), keeper]);
+      expect((await db.get(machineTable, { id: 'machine-rn' })).updated.valueOf()).toBe(stampBefore);
+    });
+
     test(`onSourceRemoved default: removed source rows are deleted; human rows survive`, async () => {
       const db = getDbAsSystem();
       const human = await db.insert(defaultPolicyTable, { email: 'human@test.local' });
@@ -279,6 +325,30 @@ export const sourceRecordSyncTests = (
       expect(await db.get(defaultPolicyTable, { id: human.id })).toBeDefined();
     });
 
+    test('the default lifecycle is rollback-idempotent: declare → remove (prune) → re-declare is a clean re-insert, never a collision', async () => {
+      const db = getDbAsSystem();
+      const keeper = { table: defaultPolicyTable, record: { id: 'default-keep', email: 'keeper@test.local' } };
+      const declared = { table: defaultPolicyTable, record: { id: 'rb-1', email: 'rb1@test.local' } };
+      await boot([declared, keeper]);
+      expect(await db.get(defaultPolicyTable, { id: 'rb-1' })).toBeDefined();
+
+      // Rollback: the declaration is removed — the default policy hard-deletes the row...
+      await boot([keeper]);
+      expect(await db.get(defaultPolicyTable, { id: 'rb-1' })).toBeUndefined();
+
+      // ...so rolling forward again is a plain re-insert under the declared id — no PK
+      // collision, no adoption needed. Tables that soft-remove (keep rows on removal) do not
+      // get this for free: they must adopt the kept row instead (pinned above on the machine
+      // table).
+      const summary = await boot([declared, keeper]);
+      expect(summary[defaultPolicyTable.name].inserts).toBe(1);
+      expect(await db.get(defaultPolicyTable, { id: 'rb-1' })).toMatchObject({
+        email: 'rb1@test.local',
+        isLoadedFromSource: true,
+        sourcePackage: DEFAULT_TEST_SOURCE,
+      });
+    });
+
     /**
      * Source-scoped pruning: multiple servers running DIFFERENT builds against ONE shared
      * database (the thought_type dev topology — two dev servers on one Spanner database).
@@ -660,6 +730,77 @@ export const sourceRecordSyncTests = (
       });
     });
 
+    describe('stamp hygiene: an unchanged declaration is never rewritten', () => {
+      const versioned = (displayName: string) => ({
+        table: defaultPolicyTable,
+        record: { id: 'v-1', email: 'v1@test.local', displayName },
+      });
+
+      test('a version bump alone re-stamps nothing: the next release leaves unchanged rows (and their updated stamp) alone', async () => {
+        const db = getDbAsSystem();
+        await bootAsSource('@test/pkg-a', [versioned('same')], '1.23.0');
+        const stamped = await db.get(defaultPolicyTable, { id: 'v-1' });
+        expect(stamped.sourcePackageVersion).toBe('1.23.0');
+
+        // The next release: the SAME declaration under a newer package version (every release
+        // bumps the declaring package). Pre-fix this counted the version stamp as drift and
+        // rewrote every row on every boot — `updated` churned on rows nobody changed.
+        const summary = await bootAsSource('@test/pkg-a', [versioned('same')], '1.24.0');
+        expect(summary[defaultPolicyTable.name]).toMatchObject({ updates: 0, unchanged: 1 });
+        const idle = await db.get(defaultPolicyTable, { id: 'v-1' });
+        expect(idle.updated.valueOf()).toBe(stamped.updated.valueOf());
+        // The stamp records the version that last WROTE the row's definition.
+        expect(idle.sourcePackageVersion).toBe('1.23.0');
+
+        // A genuine redefinition still lands, and moves the stamp with it.
+        const redefined = await bootAsSource('@test/pkg-a', [versioned('changed')], '1.24.0');
+        expect(redefined[defaultPolicyTable.name].updates).toBe(1);
+        const rewritten = await db.get(defaultPolicyTable, { id: 'v-1' });
+        expect(rewritten).toMatchObject({ displayName: 'changed', sourcePackageVersion: '1.24.0' });
+      });
+
+      test('a row with no version stamp is stamped exactly once', async () => {
+        const db = getDbAsSystem();
+        // Written before versions existed (or by a build that could not resolve its version).
+        await bootAsSource('@test/pkg-a', [versioned('same')]);
+        expect((await db.get(defaultPolicyTable, { id: 'v-1' })).sourcePackageVersion).toBeFalsy();
+
+        const first = await bootAsSource('@test/pkg-a', [versioned('same')], '2.0.0');
+        expect(first[defaultPolicyTable.name].updates).toBe(1);
+        expect((await db.get(defaultPolicyTable, { id: 'v-1' })).sourcePackageVersion).toBe('2.0.0');
+
+        const second = await bootAsSource('@test/pkg-a', [versioned('same')], '2.0.0');
+        expect(second[defaultPolicyTable.name]).toMatchObject({ updates: 0, unchanged: 1 });
+      });
+
+      test('fromDeclaration: derived fields land on insert, backfill existing rows exactly once, and never re-stamp', async () => {
+        const db = getDbAsSystem();
+        const derivedTable = sourceRecordSyncTestTables.SyncDerivedName;
+        // bootBuild names each seeded loader `${source}/SeededLoader${i}` — the declaration's
+        // own name is the part after the package, exactly what a migration's class name is.
+        const declaration = { table: derivedTable, record: { id: 'd-1', email: 'd1@test.local' } };
+
+        await boot([declaration]);
+        expect(await db.get(derivedTable, { id: 'd-1' })).toMatchObject({ name: 'SeededLoader0' });
+
+        // A row written before the derived field existed: backfilled ONCE by the next boot…
+        await db.update(derivedTable, { id: 'd-1', name: null });
+        const backfill = await boot([declaration]);
+        expect(backfill[derivedTable.name].updates).toBe(1);
+        const backfilled = await db.get(derivedTable, { id: 'd-1' });
+        expect(backfilled.name).toBe('SeededLoader0');
+
+        // …and never again: the derived value is part of the drift comparison like any field.
+        const idle = await boot([declaration]);
+        expect(idle[derivedTable.name]).toMatchObject({ updates: 0, unchanged: 1 });
+        expect((await db.get(derivedTable, { id: 'd-1' })).updated.valueOf()).toBe(backfilled.updated.valueOf());
+
+        // The derivation owns the field: a value typed into the record does not survive it.
+        await boot([{ table: derivedTable, record: { id: 'd-1', email: 'd1@test.local', name: 'typed-by-hand' } }]);
+        expect((await db.get(derivedTable, { id: 'd-1' })).name).toBe('SeededLoader0');
+      });
+    });
+
     test('a natural key without a unique guarantee fails boot loudly', async () => {
       // Local (unregistered, never created) on purpose: a registered table with an invalid
       // naturalKey would poison every loader run in the process — validation fires before any

package/test/util/tables/sourceRecordSyncTestTables.ts

@@ -97,8 +97,33 @@ export class InheritedStampTable extends Table<InheritedStampRecord> {
   });
 }
 
+export interface SyncDerivedNameRecord extends SourceRecord {
+  /** Derived by the sync from the DECLARATION (its loader's name) — never typed into the record. */
+  name?: string | null;
+  email: string;
+}
+
+/**
+ * The migration-ledger shape: a `name` column the sync fills from the declaration itself
+ * (`sourceRecordOptions.fromDeclaration` — the declaring loader's class name), kept on removal
+ * like the ledger. The options literal is cast so the suite compiles red-first against a
+ * loader that does not yet know the option.
+ */
+export class SyncDerivedNameTable extends Table<SyncDerivedNameRecord> {
+  name = 'db_test_sync_derived_name';
+  columns: Table<SyncDerivedNameRecord>['columns'] = withSourceRecordColumns<SyncDerivedNameRecord>({
+    name: new StringColumn('name'),
+    email: new StringColumn('email'),
+  });
+  sourceRecordOptions = {
+    onSourceRemoved: 'keep',
+    fromDeclaration: (declaration: { name: string }) => ({ name: declaration.name }),
+  } as Table<SyncDerivedNameRecord>['sourceRecordOptions'];
+}
+
 export const sourceRecordSyncTestTables = {
   SyncMachineAccount: new SyncMachineAccountTable() as Table<SyncMachineAccount>,
   SyncDefaultPolicy: new SyncDefaultPolicyTable() as Table<SyncDefaultPolicyRecord>,
   InheritedStamp: new InheritedStampTable() as Table<InheritedStampRecord>,
+  SyncDerivedName: new SyncDerivedNameTable() as Table<SyncDerivedNameRecord>,
 };