@proteinjs/db 1.33.0 → 1.34.0

package/src/source/SourceRecordLoader.ts

@@ -2,12 +2,12 @@ import { Logger } from '@proteinjs/logger';
 import { QueryBuilder } from '@proteinjs/db-query';
 import { getSourceRecordLoaders, SourceRecord, getSourceRecordTables } from './SourceRecord';
 import { Table } from '../Table';
-import { getDbAsSystem } from '../Db';
+import { Db, getDbAsSystem } from '../Db';
 import { SourceRecordRepo } from './SourceRecordRepo';
 import { RecordSerializer } from '../Record';
 
 type SourceRecordsMap = {
-  [tableName: string]: { table: Table<any>; records: Omit<SourceRecord, 'created' | 'updated'>[]; recordIds: string[] };
+  [tableName: string]: { table: Table<any>; records: Omit<SourceRecord, 'created' | 'updated'>[] };
 };
 
 export class SourceRecordLoader {
@@ -17,26 +17,37 @@ export class SourceRecordLoader {
     const sourceRecordsMap = await this.getSourceRecordsMap();
     const db = getDbAsSystem();
     for (const tableName in sourceRecordsMap) {
+      const { table, records } = sourceRecordsMap[tableName];
+      // 'id' unless the table declares a natural key (validated: unique-indexed, present and
+      // unambiguous across declarations).
+      const keyProperty = this.validateSyncKey(table, records);
+      const declaredKeys = records.map((record) => (record as any)[keyProperty]);
+      const { deleteCount, removedUpdateCount } = await this.reconcileRemoved(db, table, keyProperty, declaredKeys);
+
       let insertCount = 0;
       let updateCount = 0;
       let unchangedCount = 0;
-      let deleteCount = 0;
-      const table = sourceRecordsMap[tableName].table;
-      const sourceRecordIds = sourceRecordsMap[tableName].recordIds;
-      if (!table.sourceRecordOptions.doNotDeleteSourceRecordsFromDb) {
-        const qb = QueryBuilder.fromObject<SourceRecord>({ isLoadedFromSource: true }, table.name);
-        if (sourceRecordIds.length > 0) {
-          qb.condition({ field: 'id', operator: 'NOT IN', value: sourceRecordIds });
-        }
-
-        deleteCount = await db.delete(table, qb);
-      }
-
-      const sourceRecords = sourceRecordsMap[tableName].records;
-      for (let sourceRecord of sourceRecords) {
+      let adoptedCount = 0;
+      for (let sourceRecord of records) {
         sourceRecord.isLoadedFromSource = true;
-        const existingRecord = await db.get(table, { id: sourceRecord.id });
+        const existingRecord = await db.get(table, { [keyProperty]: (sourceRecord as any)[keyProperty] });
         if (existingRecord) {
+          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.
+            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.
+            adoptedCount += 1;
+            this.logger.info({
+              message: `(${table.name}) Adopting existing record into source ownership`,
+              obj: { [keyProperty]: (sourceRecord as any)[keyProperty], id: existingRecord.id },
+            });
+          }
+
           if (await this.hasChanges(table, sourceRecord, existingRecord)) {
             await db.update(table, sourceRecord);
             updateCount += 1;
@@ -49,24 +60,125 @@ export class SourceRecordLoader {
           insertCount += 1;
         }
 
+        // Registered under the DB id (= the adopted id when an existing row matched by natural key).
         new SourceRecordRepo().loadSourceRecord(table.name, sourceRecord as any);
       }
 
       this.logger.info({
-        message: `(${table.name}) Loaded ${sourceRecords.length} ${sourceRecords.length == 1 ? 'record' : 'records'} from source`,
+        message: `(${table.name}) Loaded ${records.length} ${records.length == 1 ? 'record' : 'records'} from source`,
         obj: {
           inserts: insertCount,
           updates: updateCount,
           unchanged: unchangedCount,
+          adopted: adoptedCount,
           deletes: deleteCount,
+          removedUpdates: removedUpdateCount,
         },
       });
     }
   }
 
+  /**
+   * The removed-reconcile leg: rows previously loaded from source whose declaration no longer
+   * exists (`is_loaded_from_source = true AND <key> NOT IN declared`), handled per the table's
+   * `onSourceRemoved` policy — delete (default), keep, or update with a patch. The update leg
+   * applies the patch only to rows whose fields actually differ (idempotent boots), through
+   * `Db.update` so table watchers observe each write.
+   */
+  private async reconcileRemoved(
+    db: Db,
+    table: Table<any>,
+    keyProperty: string,
+    declaredKeys: unknown[]
+  ): Promise<{ deleteCount: number; removedUpdateCount: number }> {
+    const policy = table.sourceRecordOptions.onSourceRemoved ?? 'delete';
+    if (policy === 'keep') {
+      return { deleteCount: 0, removedUpdateCount: 0 };
+    }
+
+    const qb = QueryBuilder.fromObject<SourceRecord>({ isLoadedFromSource: true }, table.name);
+    if (declaredKeys.length > 0) {
+      qb.condition({ field: keyProperty as any, operator: 'NOT IN', value: declaredKeys as any });
+    }
+
+    if (policy === 'delete') {
+      return { deleteCount: await db.delete(table, qb), removedUpdateCount: 0 };
+    }
+
+    let removedUpdateCount = 0;
+    const removedRecords = await db.query(table, qb);
+    for (const removedRecord of removedRecords) {
+      if (await this.hasChanges(table, policy.update, removedRecord)) {
+        await db.update(table, { id: removedRecord.id, ...policy.update });
+        removedUpdateCount += 1;
+        this.logger.info({
+          message: `(${table.name}) Applied onSourceRemoved update to record removed from source`,
+          obj: { id: removedRecord.id, [keyProperty]: (removedRecord as any)[keyProperty] },
+        });
+      }
+    }
+
+    return { deleteCount: 0, removedUpdateCount };
+  }
+
+  /**
+   * Resolve and validate the property the sync keys on: `id` unless the table declares
+   * `sourceRecordOptions.naturalKey`. A natural key must be schema-unique (a `ColumnOptions.unique`
+   * column or a single-column unique index in `Table.indexes`), present on every declaration, and
+   * unambiguous across declarations — each violation fails boot loudly by name.
+   */
+  private validateSyncKey(table: Table<any>, records: Omit<SourceRecord, 'created' | 'updated'>[]): string {
+    const naturalKey = table.sourceRecordOptions.naturalKey;
+    if (!naturalKey) {
+      return 'id';
+    }
+
+    const column = (table.columns as any)[naturalKey];
+    if (!column) {
+      throw new Error(
+        `(${table.name}) sourceRecordOptions.naturalKey '${naturalKey}' is not a column property on the table`
+      );
+    }
+
+    const uniqueByColumn = column.options?.unique?.unique === true;
+    const uniqueByIndex = (table.indexes ?? []).some(
+      (index) => index.unique === true && index.columns.length === 1 && String(index.columns[0]) === naturalKey
+    );
+    if (!uniqueByColumn && !uniqueByIndex) {
+      throw new Error(
+        `(${table.name}) sourceRecordOptions.naturalKey '${naturalKey}' requires the column to be unique — ` +
+          `declare ColumnOptions.unique on it (or a single-column unique index in Table.indexes) so ` +
+          `natural-key adoption cannot match ambiguously`
+      );
+    }
+
+    const seen = new Map<unknown, true>();
+    for (const record of records) {
+      const value = (record as any)[naturalKey];
+      if (value === undefined || value === null) {
+        throw new Error(
+          `(${table.name}) A source record declaration is missing its natural key '${naturalKey}' (declared id: '${record.id}')`
+        );
+      }
+
+      if (seen.has(value)) {
+        throw new Error(
+          `(${table.name}) Two source record declarations share the natural key '${naturalKey}' = '${value}' — ` +
+            `declarations must be unique by natural key`
+        );
+      }
+
+      seen.set(value, true);
+    }
+
+    return naturalKey;
+  }
+
   /**
    * Compare source record fields against the existing DB record to detect actual changes.
-   * Only fields present on the source record are compared (ignoring `created`, `updated`).
+   * Only fields present on the source record are compared, ignoring `id`, `created`, `updated`
+   * (`id` because natural-key adoption keeps the existing row's id — the declared id must not
+   * register as perpetual drift; `Db.update` never writes id anyway).
    * Uses serialization to normalize values (e.g. Reference objects, Moment, JSON) before
    * comparison, then delegates to {@link findMismatchPath}.
    *
@@ -79,7 +191,7 @@ export class SourceRecordLoader {
     const serializedSource = await serializer.serialize(sourceRecord);
     const serializedExisting = await serializer.serialize(existingRecord);
     for (const columnName in serializedSource) {
-      if (columnName === 'created' || columnName === 'updated') {
+      if (columnName === 'id' || columnName === 'created' || columnName === 'updated') {
         continue;
       }
 
@@ -98,7 +210,7 @@ export class SourceRecordLoader {
     const sourceRecordTables = getSourceRecordTables();
     for (const sourceRecordTable of sourceRecordTables) {
       if (!sourceRecordsMap[sourceRecordTable.name]) {
-        sourceRecordsMap[sourceRecordTable.name] = { table: sourceRecordTable, records: [], recordIds: [] };
+        sourceRecordsMap[sourceRecordTable.name] = { table: sourceRecordTable, records: [] };
       }
     }
 
@@ -108,12 +220,10 @@ export class SourceRecordLoader {
         sourceRecordsMap[sourceRecordLoader.table.name] = {
           table: sourceRecordLoader.table,
           records: [],
-          recordIds: [],
         };
       }
 
       sourceRecordsMap[sourceRecordLoader.table.name].records.push(sourceRecordLoader.record);
-      sourceRecordsMap[sourceRecordLoader.table.name].recordIds.push(sourceRecordLoader.record.id);
     }
 
     return sourceRecordsMap;

package/src/tables/MigrationTable.ts

@@ -56,8 +56,9 @@ export class MigrationTable extends Table<Migration> {
     duration: new StringColumn('duration'),
     output: new ObjectColumn('output'),
   });
-  public sourceRecordOptions = {
-    doNotDeleteSourceRecordsFromDb: true,
+  public sourceRecordOptions: Table<Migration>['sourceRecordOptions'] = {
+    // The ledger outlives the migration class: run history stays when the source is deleted.
+    onSourceRemoved: 'keep',
     ui: {
       hideColumns: true,
     },

package/test/index.ts

@@ -6,6 +6,7 @@ export * from './reusable/TransactionTests';
 export * from './reusable/CascadeDeleteTests';
 export * from './reusable/PreloadReferencesTests';
 export * from './reusable/RecordIteratorTests';
+export * from './reusable/SourceRecordSyncTests';
 
 export * from './util/testUser';
 
@@ -14,5 +15,6 @@ export * from './util/tables/columnTypesTestTables';
 export * from './util/tables/crudTestTables';
 export * from './util/tables/dynamicReferenceColumnTestTables';
 export * from './util/tables/recordIteratorTestTables';
+export * from './util/tables/sourceRecordSyncTestTables';
 export * from './util/tables/tableManagerTestTables';
 export * from './util/tables/transactionTestTables';

package/test/reusable/CascadeDeleteTests.ts

@@ -24,7 +24,9 @@ import {
   MemberArrRev,
   MemberDyn,
   MemberRef,
+  Pilot,
   Post,
+  Robot,
   Worker,
 } from '../util/tables/cascadeDeleteTestTables';
 
@@ -191,6 +193,50 @@ export const cascadeDeleteTests = (
         const remainingTasks = await db.query(taskTable, {});
         expect(remainingTasks.length).toBe(0);
       });
+
+      test('DynamicReferenceColumn: edge applies to every target table, scoped per row', async () => {
+        const pilotTable = cascadeDeleteTestTables.Pilot;
+        const robotTable = cascadeDeleteTestTables.Robot;
+        const missionTable = cascadeDeleteTestTables.Mission;
+
+        const pilot = await db.insert(pilotTable, { name: 'Pia Pilot' });
+        const robot = await db.insert(robotTable, { name: 'Rusty Robot' });
+        const pilotMission = await db.insert(missionTable, {
+          title: 'Fly Cargo',
+          assigneeTableName: pilotTable.name,
+          assigneeRef: new Reference<Pilot>(pilotTable.name, pilot.id),
+        });
+        await db.insert(missionTable, {
+          title: 'Weld Hull',
+          assigneeTableName: robotTable.name,
+          assigneeRef: new Reference<Robot>(robotTable.name, robot.id),
+        });
+
+        // Deleting the robot deletes only the robot-assigned mission; the pilot's survives
+        const robotDelQb = new QueryBuilder<Robot>(robotTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: robot.id,
+        });
+        const robotsDeleted = await db.delete(robotTable, robotDelQb);
+        expect(robotsDeleted).toBe(1);
+
+        const missionsAfterRobot = await db.query(missionTable, {});
+        expect(missionsAfterRobot.length).toBe(1);
+        expect(missionsAfterRobot[0].id).toBe(pilotMission.id);
+
+        // The same column reverse-cascades off the other target table too
+        const pilotDelQb = new QueryBuilder<Pilot>(pilotTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: pilot.id,
+        });
+        const pilotsDeleted = await db.delete(pilotTable, pilotDelQb);
+        expect(pilotsDeleted).toBe(1);
+
+        const missionsAfterPilot = await db.query(missionTable, {});
+        expect(missionsAfterPilot.length).toBe(0);
+      });
     });
   };
 };

package/test/reusable/SourceRecordSyncTests.ts

@@ -0,0 +1,288 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import {
+  Db,
+  DbDriver,
+  DuplicateValuesForUniqueIndexError,
+  SourceRecord,
+  SourceRecordRepo,
+  StringColumn,
+  Table,
+  TableWatcher,
+  getDbAsSystem,
+  withSourceRecordColumns,
+} from '@proteinjs/db';
+import type { DefaultTransactionContextFactory } from '@proteinjs/db';
+// Relative on purpose: the class shares its name with the SourceRecordLoader declaration
+// interface exported from the package index, so it is not index-exported.
+import { SourceRecordLoader } from '../../src/source/SourceRecordLoader';
+import { TableWatcherRunner } from '../../src/TableWatcherRunner';
+import { DbTestEnvironment } from '../util/DbTestEnvironment';
+import {
+  DupePreflightTable,
+  DupePreflightUniqueEmailTable,
+  SyncMachineAccount,
+  sourceRecordSyncTestTables,
+} from '../util/tables/sourceRecordSyncTestTables';
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type DbStatics = { defaultDbDriver?: DbDriver };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+
+/** Records afterUpdate payloads on the machine table — the watcher-visibility contract probe. */
+class RecordingMachineAccountWatcher implements TableWatcher<SyncMachineAccount> {
+  static updates: Partial<SyncMachineAccount>[] = [];
+
+  name(): string {
+    return this.constructor.name;
+  }
+
+  table(): Table<SyncMachineAccount> {
+    return sourceRecordSyncTestTables.SyncMachineAccount;
+  }
+
+  async afterUpdate<T extends SyncMachineAccount>(recordUpdateCount: number, record: Partial<T>): Promise<void> {
+    RecordingMachineAccountWatcher.updates.push({ ...record });
+  }
+}
+
+/**
+ * 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.
+ */
+export const sourceRecordSyncTests = (
+  driver: DbDriver,
+  transactionContextFactory: DefaultTransactionContextFactory,
+  dropTable: (table: Table<any>) => Promise<void>
+) => {
+  return () => {
+    const testEnv = new DbTestEnvironment(driver, dropTable);
+    const machineTable = sourceRecordSyncTestTables.SyncMachineAccount;
+    const defaultPolicyTable = sourceRecordSyncTestTables.SyncDefaultPolicy;
+    const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+    let originalWatchers: unknown[] | undefined;
+
+    /** Seed the boot declarations and run the sync — one boot of `Db.init`'s loader leg. */
+    const boot = async (declarations: { table: Table<any>; record: any }[]) => {
+      objectCache()['@proteinjs/db/SourceRecordLoader'] = declarations;
+      await new SourceRecordLoader().load();
+    };
+
+    const machineDeclaration = (record: Partial<SyncMachineAccount> & { id: string; email: string }) => ({
+      table: machineTable,
+      record: { status: 'active', ...record },
+    });
+
+    const machineRows = async (query: Partial<SyncMachineAccount> = {}) =>
+      await getDbAsSystem().query(machineTable, query);
+
+    beforeAll(async () => {
+      // The suite drives the loader exactly the way Db.init does — through the DEFAULT driver —
+      // so the driver under test must be the resolvable default (and any previously cached
+      // default must not leak in from earlier suites in this process).
+      objectCache()['@proteinjs/db/DefaultDbDriverFactory'] = [{ getDbDriver: () => driver }];
+      objectCache()['@proteinjs/db/DefaultTransactionContextFactory'] = [transactionContextFactory];
+      (Db as unknown as DbStatics).defaultDbDriver = undefined;
+      // Only the recording watcher observes this run — and the runner's static map must be
+      // rebuilt from the seeded cache rather than whatever an earlier Db construction cached.
+      originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+      objectCache()['@proteinjs/db/TableWatcher'] = [new RecordingMachineAccountWatcher()];
+      (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+      await testEnv.beforeAll();
+    }, 60000);
+
+    afterAll(async () => {
+      await testEnv.afterAll();
+      delete objectCache()['@proteinjs/db/SourceRecordLoader'];
+      delete objectCache()['@proteinjs/db/DefaultDbDriverFactory'];
+      delete objectCache()['@proteinjs/db/DefaultTransactionContextFactory'];
+      if (originalWatchers) {
+        objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+      } else {
+        delete objectCache()['@proteinjs/db/TableWatcher'];
+      }
+      (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+      (Db as unknown as DbStatics).defaultDbDriver = undefined;
+    }, 60000);
+
+    beforeEach(async () => {
+      const db = getDbAsSystem();
+      await db.delete(machineTable, {});
+      await db.delete(defaultPolicyTable, {});
+      RecordingMachineAccountWatcher.updates = [];
+    });
+
+    test('declare-only on a mixed table: declared records insert; human rows are untouched', async () => {
+      const db = getDbAsSystem();
+      const human = await db.insert(machineTable, {
+        email: 'human@test.local',
+        displayName: 'A human',
+        runtimeNote: 'human-owned',
+      });
+
+      await boot([machineDeclaration({ id: 'machine-1', email: 'machine@test.local', displayName: 'Machine' })]);
+
+      const machine = await db.get(machineTable, { email: 'machine@test.local' });
+      expect(machine).toMatchObject({
+        id: 'machine-1',
+        displayName: 'Machine',
+        status: 'active',
+        isLoadedFromSource: true,
+      });
+
+      // The human row survives the boot byte-for-byte: not deleted, not flagged, fields intact.
+      const humanAfter = await db.get(machineTable, { id: human.id });
+      expect(humanAfter).toBeDefined();
+      expect(humanAfter.isLoadedFromSource).toBeFalsy();
+      expect(humanAfter).toMatchObject({ displayName: 'A human', runtimeNote: 'human-owned' });
+      expect(humanAfter.status).toBeFalsy();
+      expect(await machineRows()).toHaveLength(2);
+    });
+
+    test('declared fields revert on boot; runtime-owned fields survive; converged boots write nothing', async () => {
+      const declarations = [
+        machineDeclaration({ id: 'machine-1', email: 'machine@test.local', displayName: 'Machine' }),
+      ];
+      await boot(declarations);
+
+      // Runtime drift on a declared field + a runtime-owned write (the credential stand-in).
+      const db = getDbAsSystem();
+      await db.update(machineTable, { id: 'machine-1', displayName: 'Drifted', runtimeNote: 'provisioned' });
+
+      await boot(declarations);
+      const reverted = await db.get(machineTable, { id: 'machine-1' });
+      expect(reverted).toMatchObject({ displayName: 'Machine', runtimeNote: 'provisioned' });
+
+      // A converged boot is a no-op: the row's `updated` stamp does not churn.
+      const stampBefore = reverted.updated.valueOf();
+      await boot(declarations);
+      const afterIdleBoot = await db.get(machineTable, { id: 'machine-1' });
+      expect(afterIdleBoot.updated.valueOf()).toBe(stampBefore);
+    });
+
+    test('natural-key adoption: an existing row is adopted in place — id and runtime fields preserved', async () => {
+      const db = getDbAsSystem();
+      // The hand-made bridge row: env-random id, runtime-provisioned fields, never flagged.
+      const handMade = await db.insert(machineTable, {
+        email: 'bridge@test.local',
+        displayName: 'Hand-made bridge',
+        runtimeNote: 'the-password-hash',
+      });
+
+      await boot([machineDeclaration({ id: 'declared-id', email: 'bridge@test.local', displayName: 'Ops bridge' })]);
+
+      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,
+        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();
+
+      // Adoption converges: 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);
+    });
+
+    test('onSourceRemoved update: removed rows are flagged through Db.update (watchers fire), never deleted; re-declaring reverts', async () => {
+      const db = getDbAsSystem();
+      const human = await db.insert(machineTable, { email: 'human@test.local', displayName: 'A human' });
+      await boot([machineDeclaration({ id: 'machine-1', email: 'machine@test.local' })]);
+
+      RecordingMachineAccountWatcher.updates = [];
+      await boot([]);
+
+      const removed = await db.get(machineTable, { id: 'machine-1' });
+      expect(removed).toBeDefined();
+      expect(removed.status).toBe('deactivated');
+      expect(removed.isLoadedFromSource).toBe(true);
+      // The write went through Db.update — table watchers observed the deactivation.
+      expect(RecordingMachineAccountWatcher.updates).toHaveLength(1);
+      expect(RecordingMachineAccountWatcher.updates[0]).toMatchObject({ id: 'machine-1', status: 'deactivated' });
+      // The human row is structurally out of reach of the removed reconcile.
+      expect((await db.get(machineTable, { id: human.id })).status).toBeFalsy();
+
+      // Idempotent: an already-flagged row is not re-written on the next boot.
+      RecordingMachineAccountWatcher.updates = [];
+      await boot([]);
+      expect(RecordingMachineAccountWatcher.updates).toHaveLength(0);
+
+      // Removal is reversible in source: re-declaring reverts the patch via drift reversion.
+      await boot([machineDeclaration({ id: 'machine-1', email: 'machine@test.local' })]);
+      expect((await db.get(machineTable, { id: 'machine-1' })).status).toBe('active');
+    });
+
+    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' });
+      await boot([{ table: defaultPolicyTable, record: { id: 'default-1', email: 'temp@test.local' } }]);
+      expect(await db.get(defaultPolicyTable, { id: 'default-1' })).toBeDefined();
+
+      await boot([]);
+      expect(await db.get(defaultPolicyTable, { id: 'default-1' })).toBeUndefined();
+      expect(await db.get(defaultPolicyTable, { id: human.id })).toBeDefined();
+    });
+
+    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
+      // db access, so the schema is never needed.
+      interface Misdeclared extends SourceRecord {
+        nickname: string;
+      }
+      class MisdeclaredNaturalKeyTable extends Table<Misdeclared> {
+        name = 'db_test_sync_misdeclared_natural_key';
+        columns = withSourceRecordColumns<Misdeclared>({ nickname: new StringColumn('nickname') });
+        sourceRecordOptions = { naturalKey: 'nickname' } as Table<Misdeclared>['sourceRecordOptions'];
+      }
+
+      await expect(
+        boot([{ table: new MisdeclaredNaturalKeyTable(), record: { id: 'm-1', nickname: 'dupe-prone' } }])
+      ).rejects.toThrow(/naturalKey 'nickname' requires the column to be unique/);
+    });
+
+    test('two declarations sharing a natural key fail boot loudly', async () => {
+      await expect(
+        boot([
+          machineDeclaration({ id: 'machine-1', email: 'shared@test.local' }),
+          machineDeclaration({ id: 'machine-2', email: 'shared@test.local' }),
+        ])
+      ).rejects.toThrow(/share the natural key 'email' = 'shared@test.local'/);
+    });
+
+    test('unique-index preflight: adding a unique index over duplicate data fails by name; clean data proceeds', async () => {
+      const tableManager = driver.getTableManager();
+      const generationOne = new DupePreflightTable();
+      const generationTwo = new DupePreflightUniqueEmailTable();
+      try {
+        await tableManager.loadTable(generationOne);
+        const db = getDbAsSystem();
+        const first = await db.insert(generationOne, { email: 'dupe@test.local' });
+        await db.insert(generationOne, { email: 'dupe@test.local' });
+
+        // The pre-sync duplicate check turns the opaque index-backfill failure into a named error.
+        await expect(tableManager.loadTable(generationTwo)).rejects.toThrow(DuplicateValuesForUniqueIndexError);
+        await expect(tableManager.loadTable(generationTwo)).rejects.toThrow(/dupe@test\.local/);
+
+        // Resolve the duplicates and the same boot proceeds.
+        await db.delete(generationOne, { id: first.id });
+        await tableManager.loadTable(generationTwo);
+      } finally {
+        await dropTable(generationOne);
+      }
+    });
+  };
+};

package/test/util/DbTestEnvironment.ts

@@ -5,6 +5,7 @@ import { columnTypesTestTables } from './tables/columnTypesTestTables';
 import { crudTestTables } from './tables/crudTestTables';
 import { dynamicReferenceTestTables } from './tables/dynamicReferenceColumnTestTables';
 import { recordIteratorTestTables } from './tables/recordIteratorTestTables';
+import { sourceRecordSyncTestTables } from './tables/sourceRecordSyncTestTables';
 import { tableManagerTestTables } from './tables/tableManagerTestTables';
 import { transactionTestTables } from './tables/transactionTestTables';
 
@@ -14,6 +15,7 @@ const TABLES: Table<any>[] = [
   ...Object.values(crudTestTables),
   ...Object.values(dynamicReferenceTestTables),
   ...Object.values(recordIteratorTestTables),
+  ...Object.values(sourceRecordSyncTestTables),
   ...Object.values(tableManagerTestTables),
   ...Object.values(transactionTestTables),
 ];