@proteinjs/db 1.47.3 → 1.49.0

package/index.ts

@@ -15,10 +15,9 @@ export * from './src/RecordIterator';
 export * from './src/CursorWindowPager';
 export * from './src/source/SourceRecord';
 export * from './src/source/SourceRecordRepo';
-// The sync runner behind Db.init's source-record leg, aliased: its class name is taken in this
-// index by the SourceRecordLoader declaration interface. Public so consumer test harnesses can
-// run one boot of the sync directly (the exports map blocks deep dist imports).
-export { SourceRecordLoader as SourceRecordSyncRunner } from './src/source/SourceRecordLoader';
+// The sync runner behind Db.init's source-record leg. Public so consumer test harnesses can run
+// one boot of the sync directly (the exports map blocks deep dist imports).
+export { SourceRecordSyncRunner } from './src/source/SourceRecordSyncRunner';
 export * from './src/MigrationRunner';
 export * from './src/QueryBuilderFactory';
 export * from './src/TableWatcher';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.47.3",
+  "version": "1.49.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -42,11 +42,11 @@
   },
   "dependencies": {
     "@proteinjs/db-query": "^1.10.1",
-    "@proteinjs/logger": "^1.0.21",
+    "@proteinjs/logger": "^1.2.0",
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/serializer": "^1.1.10",
     "@proteinjs/server-api": "^3.0.11",
-    "@proteinjs/service": "^1.5.1",
+    "@proteinjs/service": "^1.6.0",
     "@proteinjs/user-auth": "^1.3.0",
     "@proteinjs/util": "^1.6.1",
     "moment": "2.29.4",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "08154afae17a9a19c9e48520a3dd67ead7b997c6"
+  "gitHead": "5ef7c5a2f3eb6ef3b774aa93cc74cc1754cfa011"
 }

package/src/Db.ts

@@ -12,7 +12,7 @@ import {
 import { ReverseCascadeEdgeIndex } from './ReverseCascadeEdgeIndex';
 import { Record, RecordSerializer, SerializedRecord } from './Record';
 import { Logger } from '@proteinjs/logger';
-import { SourceRecordLoader } from './source/SourceRecordLoader';
+import { SourceRecordSyncRunner } from './source/SourceRecordSyncRunner';
 import { ParameterizationConfig, ParamType, QueryBuilder, Statement, StatementFactory } from '@proteinjs/db-query';
 import { QueryBuilderFactory } from './QueryBuilderFactory';
 import { StatementConfigFactory } from './StatementConfigFactory';
@@ -95,6 +95,15 @@ export interface DbDriver {
   ): Promise<SerializedRecord[]>;
   runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement, transaction?: any): Promise<number>;
   runTransaction<T>(fn: (transaction: any) => Promise<T>): Promise<T>;
+  /**
+   * The driver's per-operation deadline, in milliseconds: the longest one statement it runs may
+   * take before the driver fails it — the bound the driver enforces, as configured. Not a whole
+   * transaction's budget (a transaction the database aborts and the driver re-runs may take
+   * longer in all). Code that waits on another request's write — a row it depends on whose insert
+   * may still be in flight — sizes its wait by this, so the wait follows what the deployment
+   * configured its database to tolerate rather than a number of its own.
+   */
+  getOperationDeadlineMs(): number;
 }
 
 export class Db<R extends Record = Record> implements DbService<R> {
@@ -173,7 +182,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     const { MigrationRunner } = await import('./MigrationRunner');
     await new MigrationRunner().runPreSchemaSyncMigrations(this.dbDriver.getTableManager());
     await this.dbDriver.getTableManager().loadTables();
-    await new SourceRecordLoader().load();
+    await new SourceRecordSyncRunner().load();
   }
 
   async tableExists<T extends R>(table: Table<T>): Promise<boolean> {

package/src/MigrationRunner.ts

@@ -2,7 +2,7 @@ import { Moment, moment } from './opt/moment';
 import { Db, getDb, getDbAsSystem } from './Db';
 import { Table } from './Table';
 import { SourceRecordRepo } from './source/SourceRecordRepo';
-import { SourceRecordLoader } from './source/SourceRecordLoader';
+import { SourceRecordSyncRunner } from './source/SourceRecordSyncRunner';
 import { getSourceRecordLoaders } from './source/SourceRecord';
 import { MigrationRunnerService, getMigrationRunnerService } from './services/MigrationRunnerService';
 import { Migration, MigrationTable } from './tables/MigrationTable';
@@ -139,7 +139,7 @@ export class MigrationRunner implements MigrationRunnerService {
     }
 
     await tableManager.loadTable(migrationTable);
-    await new SourceRecordLoader().load(migrationTable);
+    await new SourceRecordSyncRunner().load(migrationTable);
     this.logger.info({
       message: `Running ${flagged.length} pre-schema-sync migration${flagged.length === 1 ? '' : 's'} before schema sync`,
       obj: { ids: flagged.map((migration) => migration.id) },

package/src/Table.ts

@@ -140,6 +140,20 @@ export abstract class Table<T extends Record> implements Loadable, CustomSeriali
   public cascadeDeleteReferences: () => { table: string; referenceColumn: string }[] = () => [];
   /** Options for configuring SourceRecords (see {@link SourceRecordOptions}) */
   public sourceRecordOptions: SourceRecordOptions<T> = {};
+  /**
+   * A DURABLE table keeps its rows: no caller deletes them. The delete door is closed on both apis
+   * for everyone — break-glass included, whatever `auth` declares — and refuses with a 403
+   * `ServiceRefusal` naming the table (`TableAuth.canDelete`). The generic record surfaces derive
+   * the same verdict: the record table's seat carries no delete act (a declared `delete` action
+   * included), the record form no Delete.
+   *
+   * Declare it on ledgers — tables whose rows are the record of what happened (the migration
+   * ledger's runs, audit and usage events), where a deleted row is history lost. The platform's
+   * own system-context code (`getDbAsSystem`) is outside the doors here as everywhere: a durable
+   * table's rows leave only by a lifecycle the platform itself declares, or by hand in the
+   * database's own console.
+   */
+  public durable = false;
   /**
    * Presentation the table declares for the GENERIC record surfaces (@proteinjs/db-ui) — the
    * framework renders what tables declare; per-table display choices never hard-code into the
@@ -178,7 +192,8 @@ export abstract class Table<T extends Record> implements Loadable, CustomSeriali
        * insert doors, delete-on-selection from the delete doors — exactly as every table did
        * before this declaration existed. A declared entry CONFIGURES the act of its kind (door
        * and/or label); kinds left undeclared keep the derivation. The seat, not the table, owns
-       * placement: every declared act renders in the same seat on desktop and phone.
+       * placement: every declared act renders in the same seat on desktop and phone. A
+       * {@link Table.durable} table's seat carries no delete act, declared or derived.
        */
       actions?: RecordTableAction[];
     };

package/src/auth/TableAuth.ts

@@ -1,4 +1,5 @@
 import { UserAuth } from '@proteinjs/user-auth';
+import { ServiceRefusal } from '@proteinjs/service';
 import { Table } from '../Table';
 
 /**
@@ -100,7 +101,15 @@ export class TableAuth {
     }
   }
 
+  /**
+   * A durable table's delete door is refused before any identity is read (`Table.durable`): a 403
+   * refusal naming the table, for every caller on both apis — no declared door reopens it.
+   */
   canDelete(table: Table<any>, api: 'db' | 'service' = 'db'): void {
+    if (table.durable) {
+      throw new ServiceRefusal(403, `Table ${table.name} is durable: its rows are never deleted`);
+    }
+
     if (!this.canAccess(table, api, 'delete')) {
       throw new TableAuthError(`User is not authorized to delete records from table: ${table.name}`);
     }
@@ -111,6 +120,11 @@ export class TableAuth {
     api: 'db' | 'service',
     operation: 'query' | 'insert' | 'update' | 'delete'
   ): boolean {
+    // A durable table has no delete door for anyone (see `canDelete`); the capability read agrees.
+    if (operation === 'delete' && table.durable) {
+      return false;
+    }
+
     const tableAuth = table.auth ? table.auth[api] : undefined;
     if (!tableAuth || Object.keys(tableAuth).length == 0) {
       return UserAuth.hasRole('admin');

package/src/auth/TableServiceAuth.ts

@@ -1,5 +1,5 @@
 import { Logger } from '@proteinjs/logger';
-import { ServiceError } from '@proteinjs/service';
+import { ServiceError, ServiceRefusal } from '@proteinjs/service';
 import { Table, isTable } from '../Table';
 import { TableAuth, TableAuthError } from './TableAuth';
 
@@ -37,6 +37,11 @@ export class TableServiceAuth {
         throw new Error(`User is not authorized to access unsupported Db service api: ${methodName}`);
       }
     } catch (error: any) {
+      // A deliberate refusal (a durable table's delete door) reaches the caller as it is: the
+      // router answers with its status and message.
+      if (ServiceRefusal.is(error)) {
+        throw error;
+      }
       // A protected-column rejection carries a client-safe message — let it surface as the 400
       // body instead of collapsing into the generic authorization failure. Name check, not
       // instanceof: `ServiceError extends Error` loses its prototype chain under the service

package/src/schema/SchemaOperations.ts

@@ -3,9 +3,10 @@ import { Table } from '../Table';
 export interface SchemaOperations {
   /**
    * Create every table in `tables`, in the given order. The order is load-bearing: a table whose
-   * foreign keys reference another absent table must appear after it. Drivers that support batched
-   * DDL (Spanner) apply the whole set as ONE schema-update operation — statements inside a batch
-   * apply in order, so the ordering contract is preserved.
+   * foreign keys reference another absent table must appear after it — `TableManager` owns that
+   * order and hands the set over already sorted by reference, so drivers never re-order. Drivers
+   * that support batched DDL (Spanner) apply the whole set as ONE schema-update operation —
+   * statements inside a batch apply in order, so the ordering contract is preserved.
    */
   createTables(tables: Table<any>[]): Promise<void>;
   alterTable(table: Table<any>, changes: TableChanges): Promise<void>;

package/src/schema/TableManager.ts

@@ -72,9 +72,10 @@ export class TableManager {
   /**
    * Reconcile every registered table with the live schema. Absent tables are created as ONE
    * batch (a single schema-update operation on drivers that support it — the prod-boot win),
-   * preserving their registration order so foreign keys to other absent tables resolve; existing
-   * tables are altered individually after, so an alter that adds a foreign key to a
-   * just-created table sees it live.
+   * ordered by their foreign-key references ({@link orderByReferences}) so each table's foreign
+   * keys resolve against tables created before it — the registry's enumeration order carries no
+   * such guarantee; existing tables are altered individually after, so an alter that adds a
+   * foreign key to a just-created table sees it live.
    */
   async loadTables(): Promise<void> {
     const tables = this.prepareTablesForLoad(getTables());
@@ -90,13 +91,14 @@ export class TableManager {
     }
 
     if (absentTables.length > 0) {
-      this.logger.info({ message: `Creating tables: ${absentTables.map((table) => table.name).join(', ')}` });
+      const tablesToCreate = this.orderByReferences(absentTables);
+      this.logger.info({ message: `Creating tables: ${tablesToCreate.map((table) => table.name).join(', ')}` });
       try {
-        await this.schemaOperations.createTables(absentTables);
+        await this.schemaOperations.createTables(tablesToCreate);
       } catch (error) {
-        await this.reconcileConcurrentSchemaChange(absentTables, error);
+        await this.reconcileConcurrentSchemaChange(tablesToCreate, error);
       }
-      this.logger.info({ message: `Finished creating ${absentTables.length} tables` });
+      this.logger.info({ message: `Finished creating ${tablesToCreate.length} tables` });
     }
 
     for (const table of existingTables) {
@@ -152,6 +154,69 @@ export class TableManager {
     return prepared;
   }
 
+  /**
+   * The order to create `tables` in: every table after the tables its foreign keys reference
+   * (`ColumnOptions.references`), so each foreign key a CREATE declares resolves against a table
+   * already created — one statement batch or one statement at a time alike. Tables are grouped by
+   * rank (0: references no other table in the set; otherwise one more than the highest rank it
+   * references) and keep their given order within a rank, so a deterministic input gives a
+   * deterministic output. A reference to the table itself, or to a table outside the set (already
+   * created, or not registered), does not constrain the order. A cycle of references cannot be
+   * created in any order: it is refused, naming the cycle and every table it blocks.
+   */
+  private orderByReferences(tables: Table<any>[]): Table<any>[] {
+    const tableNames = new Set(tables.map((table) => table.name));
+    const referencedTables = new Map<string, string[]>();
+    for (const table of tables) {
+      const referenced = new Set<string>();
+      for (const column of Object.values(table.columns)) {
+        const referencedTable = column.options?.references?.table;
+        if (referencedTable && referencedTable !== table.name && tableNames.has(referencedTable)) {
+          referenced.add(referencedTable);
+        }
+      }
+      referencedTables.set(table.name, Array.from(referenced));
+    }
+
+    const ordered: Table<any>[] = [];
+    const created = new Set<string>();
+    let remaining = tables;
+    while (remaining.length > 0) {
+      // One rank: every remaining table whose references were all created by EARLIER ranks.
+      const rank = remaining.filter((table) => referencedTables.get(table.name)!.every((name) => created.has(name)));
+      if (rank.length === 0) {
+        throw new Error(this.referenceCycleMessage(remaining, referencedTables));
+      }
+
+      ordered.push(...rank);
+      rank.forEach((table) => created.add(table.name));
+      remaining = remaining.filter((table) => !created.has(table.name));
+    }
+
+    return ordered;
+  }
+
+  /**
+   * Every table in `blocked` references another table in `blocked`, so walking those references
+   * from any of them must revisit a table: the walk from the first yields one cycle to name.
+   */
+  private referenceCycleMessage(blocked: Table<any>[], referencedTables: Map<string, string[]>): string {
+    const blockedNames = blocked.map((table) => table.name);
+    const walk: string[] = [];
+    let current = blockedNames[0];
+    while (!walk.includes(current)) {
+      walk.push(current);
+      current = referencedTables.get(current)!.find((name) => blockedNames.includes(name))!;
+    }
+
+    const cycle = [...walk.slice(walk.indexOf(current)), current];
+    return (
+      `Cannot create tables whose foreign keys form a cycle: ${cycle.join(' -> ')}. A foreign key can only ` +
+      `reference a table created before it, so no creation order exists — declare one of these references ` +
+      `once the tables exist (an alter adds it). Tables it blocks: ${blockedNames.join(', ')}`
+    );
+  }
+
   private requireEncryptedDeclarations(): boolean {
     if (getEnvVar('DB_REQUIRE_ENCRYPTED_DECLARATIONS') === 'true') {
       return true;
@@ -207,6 +272,10 @@ export class TableManager {
    * never calls it). Every outcome that reaches the intended-definition gate is logged LOUDLY at
    * WARN — tolerance fired (treated as applied) OR the re-read failed (genuine conflict / still
    * absent, re-throwing) — so an unexpected activation is visible in prod logs rather than silent.
+   * Each of those lines carries the ERROR itself (`obj.error`), never text copied out of it: the
+   * backend words a schema error itself and can quote row data in it (a failed backfill names the
+   * duplicate key), and only an error OBJECT can be recognized by the logger as one its driver
+   * marked to print as a status and a sentence (`LogLineErrors`).
    */
   private async reconcileConcurrentSchemaChange(tables: Table<any>[], error: unknown): Promise<void> {
     if (!this.schemaOperations.isAlreadyExistsError?.(error)) {
@@ -214,14 +283,14 @@ export class TableManager {
     }
 
     const tableNames = tables.map((table) => table.name).join(', ');
-    const reason = this.schemaErrorReason(error);
 
     for (const table of tables) {
-      await this.verifyIntendedDefinition(table, tableNames, reason, error);
+      await this.verifyIntendedDefinition(table, tableNames, error);
     }
 
     this.logger.warn({
-      message: `[schema reconcile] tolerated concurrent ALREADY_EXISTS for table(s) '${tableNames}' — re-read verified the object present with the intended definition, treating as applied (a concurrent actor won the race). reason: ${reason}`,
+      message: `[schema reconcile] tolerated concurrent ALREADY_EXISTS for table(s) '${tableNames}' — re-read verified the object present with the intended definition, treating as applied (a concurrent actor won the race).`,
+      obj: { error },
     });
   }
 
@@ -237,12 +306,7 @@ export class TableManager {
    * success; only a definition still absent or mismatched after every attempt is a genuine
    * conflict — logged at WARN, then the ORIGINAL error re-throws.
    */
-  private async verifyIntendedDefinition(
-    table: Table<any>,
-    tableNames: string,
-    reason: string,
-    error: unknown
-  ): Promise<void> {
+  private async verifyIntendedDefinition(table: Table<any>, tableNames: string, error: unknown): Promise<void> {
     let remainingChanges: TableChanges | undefined;
     for (let attempt = 1; attempt <= TableManager.RECONCILE_VERIFY_ATTEMPTS; attempt++) {
       if (attempt > 1) {
@@ -264,7 +328,8 @@ export class TableManager {
       // Still absent after every re-read — not the concurrent-winner case; surface the original
       // error rather than masking it.
       this.logger.warn({
-        message: `[schema reconcile] caught ALREADY_EXISTS for table(s) '${tableNames}' but '${table.name}' is still absent after ${TableManager.RECONCILE_VERIFY_ATTEMPTS} re-reads — NOT a concurrent apply; re-throwing. reason: ${reason}`,
+        message: `[schema reconcile] caught ALREADY_EXISTS for table(s) '${tableNames}' but '${table.name}' is still absent after ${TableManager.RECONCILE_VERIFY_ATTEMPTS} re-reads — NOT a concurrent apply; re-throwing.`,
+        obj: { error },
       });
       throw error;
     }
@@ -272,19 +337,12 @@ export class TableManager {
     // The object exists but the live schema still differs from the intended definition, so a
     // concurrent actor did NOT apply our exact change (a genuine conflict). Propagate.
     this.logger.warn({
-      message: `[schema reconcile] caught ALREADY_EXISTS for table '${table.name}' but the live schema does NOT match the intended definition after ${TableManager.RECONCILE_VERIFY_ATTEMPTS} re-reads (genuine conflict) — re-throwing. reason: ${reason}`,
-      obj: { remainingChanges },
+      message: `[schema reconcile] caught ALREADY_EXISTS for table '${table.name}' but the live schema does NOT match the intended definition after ${TableManager.RECONCILE_VERIFY_ATTEMPTS} re-reads (genuine conflict) — re-throwing.`,
+      obj: { remainingChanges, error },
     });
     throw error;
   }
 
-  /** Concise, loggable reason from a schema-update error: the backend names the offending object
-   *  in `details` (validation phase) or `message` (apply phase). */
-  private schemaErrorReason(error: unknown): string {
-    const candidate = error as { details?: unknown; message?: unknown } | undefined;
-    return String(candidate?.details ?? candidate?.message ?? error);
-  }
-
   private delay(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }

package/src/services/TransactionRunnerService.ts

@@ -5,6 +5,26 @@ export const getTransactionRunnerService = serviceFactory<TransactionRunnerServi
   '@proteinjs/db/TransactionRunnerService'
 );
 
+/**
+ * What a write declares about the rows it depends on.
+ *
+ * A client that releases a queued write because its page is going away cannot order that write
+ * behind the writes it depends on — the page is gone before their answers arrive. The server
+ * outlives the page, so the write DECLARES its dependencies and the server honours them.
+ */
+export type TransactionRunOptions = {
+  /**
+   * Ids of rows the operations depend on that may not exist yet: the row an update or a
+   * membership update targets while its insert is still in flight, the permission source a
+   * child row attaches to while the root's own insert (and the owner grant that commits with
+   * it) is still landing. Every id must be a row the operations themselves reference. The
+   * runner waits, bounded, for each to exist AND be visible to the caller before running the
+   * operations; a row that never appears fails the request with a plain clause — never a
+   * silent zero-row write, never a hang.
+   */
+  afterRows?: string[];
+};
+
 export interface TransactionRunnerService extends Service {
-  run(ops: Operation<any>[]): Promise<void>;
+  run(ops: Operation<any>[], options?: TransactionRunOptions): Promise<void>;
 }

package/src/source/SourceRecord.ts

@@ -6,7 +6,7 @@ import { BooleanColumn, StringColumn } from '../Columns';
 /**
  * A source record declaration paired with its owning source: the package that compiled the
  * declaration into this build (from the declaration's reflection qualified name). The source is
- * the ownership grain of the sync — {@link SourceRecordLoader} stamps it on every row it writes
+ * the ownership grain of the sync — {@link SourceRecordSyncRunner} stamps it on every row it writes
  * and prunes only within it, so servers running different builds against one shared database
  * never delete each other's rows.
  */
@@ -60,7 +60,7 @@ export interface SourceRecord extends DbRecord {
   isLoadedFromSource?: boolean;
   /**
    * The package whose declaration owns this row (the declaring loader's package, from its
-   * reflection qualified name). Stamped by {@link SourceRecordLoader} on every row it writes;
+   * reflection qualified name). Stamped by {@link SourceRecordSyncRunner} on every row it writes;
    * the removed-reconcile prunes only rows whose `sourcePackage` matches a package the running
    * build actually declares from — so a build never deletes rows owned by a package it does not
    * carry (e.g. another server's types on a shared database). Rows written before this column

package/src/source/{SourceRecordLoader.ts → SourceRecordSyncRunner.ts}

@@ -41,7 +41,7 @@ export type SourceRecordTableLoadSummary = {
 
 export type SourceRecordLoadSummary = { [tableName: string]: SourceRecordTableLoadSummary };
 
-export class SourceRecordLoader {
+export class SourceRecordSyncRunner {
   private logger = new Logger({ name: this.constructor.name });
 
   /** Memo of resolved package versions — one resolution (and at most one warning) per source. */
@@ -516,7 +516,7 @@ export class SourceRecordLoader {
    * For object-valued fields (e.g. a `JsonColumn` blob), source is treated as
    * fully authoritative: any structural drift — extra keys in existing, missing
    * keys in existing, or value differences anywhere in the subtree — produces
-   * a mismatch. Comparison goes through {@link SourceRecordLoader.canonicalStringify}
+   * a mismatch. Comparison goes through {@link SourceRecordSyncRunner.canonicalStringify}
    * so that key ordering (which backing stores may canonicalize alphabetically)
    * does not cause false positives.
    *
@@ -617,11 +617,17 @@ export class SourceRecordLoader {
    * The declaring package's version, read from its own package.json at runtime. Resolution runs
    * from the process cwd — the booting server's package, the one dependency tree every declaring
    * package is reachable from (`@proteinjs/db` itself does not depend on the packages that
-   * declare records, so module-relative resolution could never find them). The package's entry
-   * is resolved (honoring exports maps, where `<pkg>/package.json` is usually not requireable),
-   * then the nearest package.json whose `name` matches is read walking up from it.
+   * declare records, so module-relative resolution could never find them).
    *
-   * Returns undefined where resolution is impossible — no Node `require` (browser bundles), or a
+   * Two roads, in order:
+   * 1. The booting package itself: `<cwd>/package.json`, when its `name` is `source`. A lookup by
+   *    name from cwd searches cwd's node_modules chain, which never contains the package cwd IS,
+   *    so without this read the server's own records would sync unversioned.
+   * 2. Any other package: its entry is resolved from cwd (honoring exports maps, where
+   *    `<pkg>/package.json` is usually not requireable), then the nearest package.json whose
+   *    `name` matches is read walking up from it.
+   *
+   * Returns undefined where neither road resolves — no Node `require` (browser bundles), or a
    * package not resolvable from cwd. The sync then has no place in the version order for that
    * package: it never touches its version-stamped rows, and what it writes is unversioned
    * (see {@link isNewerStamp}). Logged once per boot so a misconfigured cwd is visible.
@@ -636,18 +642,20 @@ export class SourceRecordLoader {
     const cwd = typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : undefined;
     if (nodeRequire && cwd) {
       try {
-        const entryPath = nodeRequire.resolve(source, { paths: [cwd] });
         const path = nodeRequire('path');
         const fs = nodeRequire('fs');
+        const ownVersion = this.packageVersionAt(fs, path.join(cwd, 'package.json'), source);
+        if (ownVersion) {
+          return ownVersion;
+        }
+
+        const entryPath = nodeRequire.resolve(source, { paths: [cwd] });
         // Walk up from the entry file to the package's own package.json (the name check skips
         // nested stubs like a dist/package.json); stop at the filesystem root.
         for (let directory = path.dirname(entryPath); ; directory = path.dirname(directory)) {
-          const candidate = path.join(directory, 'package.json');
-          if (fs.existsSync(candidate)) {
-            const packageJson = JSON.parse(fs.readFileSync(candidate, 'utf8'));
-            if (packageJson?.name === source && typeof packageJson.version === 'string') {
-              return packageJson.version;
-            }
+          const version = this.packageVersionAt(fs, path.join(directory, 'package.json'), source);
+          if (version) {
+            return version;
           }
 
           if (path.dirname(directory) === directory) {
@@ -665,6 +673,16 @@ export class SourceRecordLoader {
     return undefined;
   }
 
+  /** The `version` of the package.json at `packageJsonPath` when it exists and names `source`. */
+  private packageVersionAt(fs: typeof import('fs'), packageJsonPath: string, source: string): string | undefined {
+    if (!fs.existsSync(packageJsonPath)) {
+      return undefined;
+    }
+
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson?.name === source && typeof packageJson.version === 'string' ? packageJson.version : undefined;
+  }
+
   /**
    * Whether a row's version stamp is strictly newer than the reconciling build's version of the
    * same package — the guard that makes version skew of one package safe on a shared database:

package/src/tables/MigrationTable.ts

@@ -71,13 +71,21 @@ export class MigrationTable extends Table<Migration> {
    * the service api, and the runner writes run state via the db api as the calling user.
    * INSERT deliberately has no door — for anyone, break-glass included: ledger rows are born
    * from source declarations only (boot-time loading rides getDbAsSystem, which bypasses
-   * doors), so a caller-path insert could only mint a row no source owns. The generic record
-   * surfaces derive their affordances from these doors (db-ui renders no create button here).
+   * doors), so a caller-path insert could only mint a row no source owns. DELETE has no door
+   * either: the ledger is {@link MigrationTable.durable}. The generic record surfaces derive
+   * their affordances from these doors (db-ui renders no create button and no delete act here).
    */
   public auth: Table<Migration>['auth'] = {
-    db: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
-    service: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
+    db: { query: { permission: 'dev' }, update: { permission: 'dev' } },
+    service: { query: { permission: 'dev' }, update: { permission: 'dev' } },
   };
+  /**
+   * The ledger keeps every row: run history is the record of what ran against this database, so
+   * no caller deletes it (the house's rule: migration rows are durable records; a row that must go
+   * goes by hand in the database's own console). The source-record sync keeps
+   * removed migrations' rows too ({@link MigrationTable.sourceRecordOptions} `onSourceRemoved`).
+   */
+  public durable = true;
   /**
    * The row scan: WHICH migration (name — the loader's class name), what it does, how the run
    * went, WHEN it ran ("Ran at" = start_time, the one timestamp that answers "when did it

package/src/transaction/Transaction.ts

@@ -1,6 +1,7 @@
 import { Record } from '../Record';
 import { DbService, ObjectQuery } from '../services/DbService';
 import { getTransactionRunner } from './TransactionRunner';
+import { TransactionRunOptions } from '../services/TransactionRunnerService';
 import { addDefaultFieldValues, Table } from '../Table';
 import { isInstanceOf } from '@proteinjs/util';
 import { Condition, QueryBuilder } from '@proteinjs/db-query';
@@ -269,14 +270,22 @@ export class Transaction implements OperationQueue {
 
   /**
    * Run the operations in order (not a batch), as a single transaction.
+   *
+   * `options.afterRows` declares rows the operations depend on that may not exist yet (see
+   * {@link TransactionRunOptions}); the server waits for them before running. A run with nothing
+   * to declare hands the runner the operations alone — the request is the one it always was.
    */
-  async run(): Promise<void> {
+  async run(options?: TransactionRunOptions): Promise<void> {
     if (this.ops.length === 0) {
       return;
     }
 
     const runner = getTransactionRunner();
-    await runner.run(this.ops);
+    if (options?.afterRows && options.afterRows.length > 0) {
+      await runner.run(this.ops, { afterRows: options.afterRows });
+    } else {
+      await runner.run(this.ops);
+    }
     this.ops = [];
   }
 }