@proteinjs/db 1.41.0 → 1.43.0

package/index.ts

@@ -1,4 +1,5 @@
 export * from './src/Db';
+export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
 export * from './src/auth/TableAuth';

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.41.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": "149e538c8a05858b6eb7d3a2dc362e5ff196caf9"
+  "gitHead": "b9fcfe6efb85e76f68876f7b1f2c38e5fdab7932"
 }

package/src/DetachedDbOps.ts

@@ -0,0 +1,47 @@
+import { Logger } from '@proteinjs/logger';
+
+/**
+ * THE detachment idiom for deliberately fire-and-forget db work — one owner.
+ *
+ * Under node's default unhandled-rejection policy (node 15+ `--unhandled-rejections=throw`;
+ * node 24 in production), a detached db operation that REJECTS — e.g. a write that trips the
+ * driver's op deadline (`SpannerConfig.opDeadlineMs`, default 60s) — is an unhandled rejection
+ * that KILLS THE PROCESS (observed live: a detached write past the 60s driver deadline aborted
+ * the server). Detaching is a legitimate, named decision — the caller does not need the outcome
+ * to proceed — but the rejection still needs a terminal observer. This class is that observer:
+ * every deliberately un-awaited db operation routes through `run`, which invokes the work,
+ * terminally catches (synchronous throws included), and logs the failure WITH the caller's
+ * context — never process death, never a silent swallow.
+ *
+ * NOT for outcomes the caller depends on: work whose failure must alter behavior is awaited at
+ * the call site. `run` returns void by design, so a detached result cannot be accidentally
+ * consumed.
+ */
+export class DetachedDbOps {
+  private static logger = new Logger({ name: 'DetachedDbOps' });
+
+  /**
+   * Run `work` detached. Failures — a rejected promise or a synchronous throw — are terminally
+   * logged under `description` with `context`, never rethrown and never left unhandled.
+   */
+  static run(description: string, work: () => Promise<unknown>, context?: Record<string, unknown>): void {
+    let result: Promise<unknown>;
+    try {
+      result = work();
+    } catch (error) {
+      this.observe(description, error, context);
+      return;
+    }
+    result.catch((error) => this.observe(description, error, context));
+  }
+
+  // --- helpers last ---
+
+  private static observe(description: string, error: unknown, context?: Record<string, unknown>): void {
+    this.logger.error({
+      message: `Detached db operation failed: ${description}`,
+      error,
+      ...(context ? { obj: context } : {}),
+    });
+  }
+}

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/DetachedDbOps.test.ts

@@ -0,0 +1,90 @@
+import { Logger } from '@proteinjs/logger';
+import { DetachedDbOps } from '../src/DetachedDbOps';
+
+/**
+ * The detachment idiom's contract (the node-24 crash class): a deliberately fire-and-forget db
+ * operation that REJECTS — e.g. a write that trips the driver's 60s op deadline — must be
+ * terminally observed (logged with the caller's context), never left as an unhandled rejection
+ * for node's default policy to kill the process over. These tests run with no emulator: the
+ * simulated driver rejection IS the deadline failure's shape.
+ *
+ * Note: jest itself surfaces unhandled rejections as failures — so each green run here doubles
+ * as the no-escape assertion (a dropped catch turns the log pins red AND leaks the rejection).
+ */
+
+const flushDetached = async () => {
+  // The terminal catch attaches synchronously; the rejection lands on the microtask queue.
+  await Promise.resolve();
+  await new Promise((resolve) => setImmediate(resolve));
+};
+
+describe('DetachedDbOps', () => {
+  let errorLogs: Array<{ message: string; obj?: Record<string, unknown>; error?: unknown }>;
+  let errorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    errorLogs = [];
+    errorSpy = jest.spyOn(Logger.prototype, 'error').mockImplementation(function (log: any) {
+      errorLogs.push(log);
+    });
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  test('a rejecting detached operation is terminally observed — logged with the caller context, no escaping rejection', async () => {
+    const deadlineRejection = new Error(
+      '4 DEADLINE_EXCEEDED: spanner dml transaction (runTransactionAsync) exceeded the 60000ms op deadline'
+    );
+    DetachedDbOps.run('write flow-run heartbeat', () => Promise.reject(deadlineRejection), {
+      flowRunId: 'run-1',
+      table: 'flow_run',
+    });
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('Detached db operation failed');
+    expect(errorLogs[0].message).toContain('write flow-run heartbeat');
+    expect(errorLogs[0].obj).toEqual({ flowRunId: 'run-1', table: 'flow_run' });
+    expect(errorLogs[0].error).toBe(deadlineRejection);
+  });
+
+  test('a synchronously-throwing work function is contained the same way — the caller never sees the throw', async () => {
+    const boom = new Error('driver construction failed before any promise existed');
+    expect(() =>
+      DetachedDbOps.run(
+        'sync-throwing detached op',
+        () => {
+          throw boom;
+        },
+        { site: 'test' }
+      )
+    ).not.toThrow();
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('sync-throwing detached op');
+    expect(errorLogs[0].error).toBe(boom);
+  });
+
+  test('a resolving detached operation logs nothing', async () => {
+    let ran = false;
+    DetachedDbOps.run('healthy detached op', async () => {
+      ran = true;
+      return 'ok';
+    });
+    await flushDetached();
+
+    expect(ran).toBe(true);
+    expect(errorLogs).toHaveLength(0);
+  });
+
+  test('context is optional — a rejection without context still logs the description', async () => {
+    DetachedDbOps.run('context-free detached op', () => Promise.reject(new Error('deadline')));
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('context-free detached op');
+  });
+});

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).