@proteinjs/db 1.42.0 → 1.43.0

package/jest.config.js

@@ -5,5 +5,13 @@ module.exports = {
   },
   testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  moduleNameMapper: {
+    // One copy per process in symlinked-workspace estates (the second-copy class —
+    // user-server/app-ui precedent, TRAIN_MANIFEST_5 §6.15): ServiceAuth and the suites must
+    // share ONE UserAuth class object for the static-stub idiom to reach the real gate, and
+    // reflection's SourceRepository is a process singleton. CI's npm dedupe makes these no-ops.
+    '^@proteinjs/reflection$': '<rootDir>/node_modules/@proteinjs/reflection',
+    '^@proteinjs/user-auth$': '<rootDir>/node_modules/@proteinjs/user-auth',
+  },
   testEnvironment: 'node',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.42.0",
+  "version": "1.43.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": "bbbbd77251d6c48bd4dd31331c2bbb8113337597"
+  "gitHead": "b9fcfe6efb85e76f68876f7b1f2c38e5fdab7932"
 }

package/src/Table.ts

@@ -355,6 +355,19 @@ export type SourceRecordOptions<T = any> = {
    *   `Db.update`, so table watchers observe the write. Re-declaring the record reverts the
    *   patch via normal drift reversion — removal is reversible in source.
    *
+   * THE SOFT-REMOVAL CONTRACT: a source-record table that soft-removes (keeps rows on removal —
+   * the `{ update }` policy) must adopt its soft-removed rows on re-declaration and re-derive
+   * their state from the declaration. Under the default (delete) lifecycle, re-declaration is a
+   * plain re-insert and naturally idempotent; a kept row instead still holds the declared id, so
+   * a re-declaration whose natural key no longer matches it (renamed while removed) would INSERT
+   * into a primary-key collision and fail the boot. The sync therefore widens adoption for these
+   * tables: a declaration whose natural key matches nothing re-claims the soft-removed row
+   * holding its declared id (same owning package only), reactivating it by re-deriving every
+   * declared field — declaration is the source of truth, so no removed-era state (grants,
+   * status, natural key) survives re-adoption, while runtime-owned fields the declaration never
+   * emits are preserved. Any future soft-removal table inherits this requirement; machine
+   * accounts (the `@proteinjs/user` user table) are the first implementer.
+   *
    * Rows never loaded from source are structurally untouchable by every policy: the removed
    * reconcile only ever matches `is_loaded_from_source = true`.
    */

package/src/source/SourceRecordLoader.ts

@@ -106,7 +106,20 @@ export class SourceRecordLoader {
         if (sourceVersion !== undefined) {
           sourceRecord.sourcePackageVersion = sourceVersion;
         }
-        const existingRecord = await db.get(table, { [keyProperty]: (sourceRecord as any)[keyProperty] });
+        let existingRecord = await db.get(table, { [keyProperty]: (sourceRecord as any)[keyProperty] });
+        let reclaimedSoftRemoved = false;
+        if (!existingRecord) {
+          existingRecord = await this.softRemovedRecordHoldingDeclaredId(
+            db,
+            table,
+            keyProperty,
+            sourceRecord.id,
+            source,
+            allDeclaredKeys
+          );
+          reclaimedSoftRemoved = existingRecord !== undefined;
+        }
+
         if (existingRecord) {
           if (
             existingRecord.sourcePackage === source &&
@@ -133,6 +146,18 @@ export class SourceRecordLoader {
               message: `(${table.name}) Adopting existing record into source ownership`,
               obj: { [keyProperty]: (sourceRecord as any)[keyProperty], id: existingRecord.id },
             });
+          } else if (reclaimedSoftRemoved) {
+            // A soft-removed row re-claimed by its declaration under a changed natural key:
+            // adopted in place and reactivated from the declaration by the update below.
+            adoptedCount += 1;
+            this.logger.info({
+              message: `(${table.name}) Adopting soft-removed record re-declared under a changed ${keyProperty}`,
+              obj: {
+                id: existingRecord.id,
+                [`removed_${keyProperty}`]: (existingRecord as any)[keyProperty],
+                [keyProperty]: (sourceRecord as any)[keyProperty],
+              },
+            });
           }
 
           if (await this.hasChanges(table, sourceRecord, existingRecord)) {
@@ -240,6 +265,60 @@ export class SourceRecordLoader {
     return { deleteCount: 0, removedUpdateCount, skippedNewer };
   }
 
+  /**
+   * The widened adoption match for tables that SOFT-remove (keep rows on removal via the
+   * `onSourceRemoved` update policy): a declaration whose natural key matched nothing may still
+   * be a RE-declaration of a removed-and-kept row — the same stable declared id under a changed
+   * natural key (e.g. a machine account renamed while decommissioned). Without this, the insert
+   * leg collides with the kept row's primary key and the boot fails.
+   *
+   * Returns the soft-removed row the declaration re-claims, or undefined. The match is
+   * deliberately strict — all of:
+   * - the table keeps removed rows (`onSourceRemoved` is an update patch — soft removal);
+   * - a row holds the DECLARED id;
+   * - that row is source-owned (`is_loaded_from_source = true`) by THIS declaration's package
+   *   (never adopt a human/runtime row, or another package's row, by id);
+   * - no declaration in this build claims the row by natural key (it is a removed row, not a
+   *   duplicate-id declaration — that case still fails the boot loudly at insert).
+   *
+   * The caller then reactivates the row by re-deriving every declared field from the current
+   * declaration (natural key included) through the normal drift-reversion update — declaration
+   * is the source of truth, so nothing removed-era (grants, status, natural key) survives
+   * re-adoption; runtime-owned fields the declaration never emits are untouched. The version
+   * guard is the caller's existing stamped-newer branch, which applies to the returned row
+   * verbatim (same package by construction).
+   *
+   * This is the one-off form of a future generic `softRemoval` hook (adopt-including-removed +
+   * reactivate-from-declaration): graduating it means lifting this method behind a table-level
+   * seam, not rewriting the semantics. The contract lives on
+   * {@link SourceRecordOptions.onSourceRemoved}.
+   */
+  private async softRemovedRecordHoldingDeclaredId(
+    db: Db,
+    table: Table<any>,
+    keyProperty: string,
+    declaredId: string,
+    source: string,
+    allDeclaredKeys: unknown[]
+  ): Promise<SourceRecord | undefined> {
+    const policy = table.sourceRecordOptions.onSourceRemoved;
+    if (typeof policy !== 'object') {
+      return undefined;
+    }
+
+    const holder: SourceRecord | undefined = await db.get(table, { id: declaredId });
+    if (
+      !holder ||
+      holder.isLoadedFromSource !== true ||
+      holder.sourcePackage !== source ||
+      allDeclaredKeys.includes((holder as any)[keyProperty])
+    ) {
+      return undefined;
+    }
+
+    return holder;
+  }
+
   /**
    * Source-loaded rows with no owner stamp that no declaration in this build claimed on this
    * boot (the stamp leg has already run). They predate `source_package`, or their declaring

package/test/reusable/SourceRecordSyncTests.ts

@@ -266,6 +266,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 +324,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).