@proteinjs/db 1.48.0 → 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.48.0",
+  "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": "ec3fd54430dde18afd406ec70eccd857492272a0"
+  "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';
@@ -182,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/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/test/DurableTable.test.ts

@@ -0,0 +1,156 @@
+import { UserAuth } from '@proteinjs/user-auth';
+import { Table } from '../src/Table';
+import { withRecordColumns, Record } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { TableAuth } from '../src/auth/TableAuth';
+import { TableServiceAuth } from '../src/auth/TableServiceAuth';
+import { MigrationTable } from '../src/tables/MigrationTable';
+
+/**
+ * A DURABLE table (`Table.durable`) keeps its rows: the delete door is closed on both apis for
+ * every caller — break-glass included, whatever `auth` declares — and the refusal is a typed 403
+ * that names the table. Everything else about the table's doors is unchanged, and a table that
+ * does not declare it keeps its delete doors exactly as declared.
+ *
+ * The house's rule: the migration ledger's rows could be selected and deleted from the record
+ * table in a deployment — they are durable records; the migration table declares it.
+ *
+ * `UserAuth` reads from a static repo; tests stub it directly per identity — no server needed.
+ */
+
+type UserAuthInternals = {
+  userRepo?: { getUser: () => { email: string; roles: string[] } };
+  permissionRolesMapping?: { getRoles: (permission: string) => string[] | undefined };
+};
+
+const setUser = (roles: string[]) => {
+  (UserAuth as unknown as UserAuthInternals).userRepo = {
+    getUser: () => ({ email: 'user@test.local', roles }),
+  };
+};
+
+const setMapping = (mapping: { [permission: string]: string[] }) => {
+  (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = {
+    getRoles: (permission: string) => mapping[permission],
+  };
+};
+
+interface Entry extends Record {
+  title: string;
+}
+
+/** Every door open to the 'ledger' permission — the delete door included. */
+class OpenLedgerTable extends Table<Entry> {
+  public name = 'open_ledger_test';
+  public auth: Table<Entry>['auth'] = {
+    db: { all: { permission: 'ledger' } },
+    service: { all: { permission: 'ledger' } },
+  };
+  public columns = withRecordColumns<Entry>({
+    title: new StringColumn('title'),
+  });
+}
+
+/** The same doors, declared durable: the declared delete doors do not reopen what durability closes. */
+class DurableLedgerTable extends OpenLedgerTable {
+  public name = 'durable_ledger_test';
+  public durable = true;
+}
+
+/** Durable with no auth block at all: admin's break-glass default does not reach delete either. */
+class DurableNoAuthTable extends Table<Entry> {
+  public name = 'durable_no_auth_test';
+  public durable = true;
+  public columns = withRecordColumns<Entry>({
+    title: new StringColumn('title'),
+  });
+}
+
+/** What the refusal is, read by shape (the router reads a `ServiceRefusal` the same way). */
+const refusalOf = (act: () => unknown): { name?: string; status?: number; message?: string } | undefined => {
+  try {
+    act();
+  } catch (error: any) {
+    return { name: error?.name, status: error?.status, message: error?.message };
+  }
+  return undefined;
+};
+
+describe('a durable table keeps its rows', () => {
+  beforeEach(() => {
+    setMapping({ ledger: ['ledger-keeper'] });
+  });
+
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+    (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = undefined;
+  });
+
+  it('the delete door refuses every caller on both apis — a 403 refusal naming the table, whatever auth declares', () => {
+    const auth = new TableAuth();
+    for (const table of [new DurableLedgerTable(), new DurableNoAuthTable()]) {
+      for (const roles of [['ledger-keeper'], ['admin']]) {
+        setUser(roles);
+        for (const api of ['db', 'service'] as const) {
+          const refusal = refusalOf(() => auth.canDelete(table, api));
+          expect(refusal).toEqual({
+            name: 'ServiceRefusal',
+            status: 403,
+            message: `Table ${table.name} is durable: its rows are never deleted`,
+          });
+          // The capability read the record surfaces derive their acts from agrees with the door.
+          expect(auth.canPerform(table, 'delete', api)).toBe(false);
+        }
+      }
+    }
+  });
+
+  it('the service door passes the refusal to the caller as it is — not a generic denial, not a failure', () => {
+    setUser(['admin']);
+    const table = new DurableLedgerTable();
+    const refusal = refusalOf(() => new TableServiceAuth().canAccess('delete', [table, { id: 'entry-1' }]));
+    expect(refusal).toEqual({
+      name: 'ServiceRefusal',
+      status: 403,
+      message: 'Table durable_ledger_test is durable: its rows are never deleted',
+    });
+  });
+
+  it('the durable table keeps every other door it declares', () => {
+    setUser(['ledger-keeper']);
+    const auth = new TableAuth();
+    const table = new DurableLedgerTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).not.toThrow();
+      expect(() => auth.canInsert(table, api)).not.toThrow();
+      expect(() => auth.canUpdate(table, api)).not.toThrow();
+    }
+    expect(new TableServiceAuth().canAccess('query', [table, {}])).toBe(true);
+    expect(new TableServiceAuth().canAccess('update', [table, { id: 'entry-1', title: 't' }])).toBe(true);
+  });
+
+  it('a table that does not declare it keeps its delete doors exactly as declared', () => {
+    const auth = new TableAuth();
+    const table = new OpenLedgerTable();
+
+    setUser(['ledger-keeper']);
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canDelete(table, api)).not.toThrow();
+      expect(auth.canPerform(table, 'delete', api)).toBe(true);
+    }
+    expect(new TableServiceAuth().canAccess('delete', [table, { id: 'entry-1' }])).toBe(true);
+
+    setUser(['someone-else']);
+    expect(() => auth.canDelete(table, 'service')).toThrow(
+      'User is not authorized to delete records from table: open_ledger_test'
+    );
+  });
+
+  it('the migration ledger is durable', () => {
+    setUser(['admin']);
+    const table = new MigrationTable();
+    const refusal = refusalOf(() => new TableServiceAuth().canAccess('delete', [table, { id: 'migration-1' }]));
+    expect(refusal?.status).toBe(403);
+    expect(refusal?.message).toBe('Table migration is durable: its rows are never deleted');
+  });
+});