@proteinjs/db 1.26.0 → 1.28.0

package/index.ts

@@ -11,6 +11,8 @@ export * from './src/UpdatePreserving';
 export * from './src/reference/ReferenceCache';
 export * from './src/RecordIterator';
 export * from './src/source/SourceRecord';
+export * from './src/source/SourceRecordRepo';
+export * from './src/MigrationRunner';
 export * from './src/QueryBuilderFactory';
 export * from './src/TableWatcher';
 export * from './src/transaction/Transaction';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,13 +41,13 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.5.0",
+    "@proteinjs/db-query": "^1.6.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.1.12",
     "@proteinjs/serializer": "^1.1.10",
     "@proteinjs/server-api": "^3.0.10",
-    "@proteinjs/service": "^1.4.1",
-    "@proteinjs/user-auth": "^1.2.0",
+    "@proteinjs/service": "^1.5.0",
+    "@proteinjs/user-auth": "^1.3.0",
     "@proteinjs/util": "^1.6.1",
     "moment": "2.29.4",
     "uuid": "8.3.0"

package/src/Db.ts

@@ -24,6 +24,7 @@ import {
   DefaultTransactionContextFactory,
   PostCommitHook,
   getDefaultTransactionContextFactory,
+  TransactionContextData,
 } from './transaction/TransactionContextFactory';
 import { isInstanceOf } from '@proteinjs/util';
 import { Reference } from './reference/Reference';
@@ -76,7 +77,6 @@ export class Db<R extends Record = Record> implements DbService<R> {
   private statementConfigFactory: StatementConfigFactory;
   private auth = new TableAuth();
   private tableWatcherRunner = new TableWatcherRunner<R>();
-  private currentTransaction?: any;
   private transactionContextFactory: DefaultTransactionContextFactory;
   public serviceMetadata: Service['serviceMetadata'] = {
     auth: {
@@ -96,10 +96,6 @@ export class Db<R extends Record = Record> implements DbService<R> {
     this.transactionContextFactory = transactionContextFactory
       ? transactionContextFactory
       : this.getDefaultTransactionContextFactory();
-    const transactionContext = this.transactionContextFactory.getTransactionContext();
-    if (transactionContext.currentTransaction) {
-      this.currentTransaction = transactionContext.currentTransaction;
-    }
   }
 
   static getDefaultDbDriver(): DbDriver {
@@ -159,7 +155,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         serializedRecord as Partial<T>,
         this.statementConfigFactory.getStatementConfig(config)
       );
-    await this.dbDriver.runDml(generateInsert, this.currentTransaction);
+    await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
     await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
     return recordCopy as T;
   }
@@ -202,7 +198,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         qb,
         this.statementConfigFactory.getStatementConfig(config)
       );
-    const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.currentTransaction);
+    const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
     await this.tableWatcherRunner.runAfterUpdateTableWatchers(table, recordUpdateCount, recordCopy, qb);
     return recordUpdateCount;
   }
@@ -219,7 +215,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * or the record no longer exists — a concurrently deleted record wins).
    */
   async updateArrayMembership<T extends R>(table: Table<T>, update: ArrayMembershipUpdate): Promise<number> {
-    if (!this.currentTransaction) {
+    if (!this.transactionContextFactory.getTransactionContext().currentTransaction) {
       const db = this.newSelfWrapDb();
       return await db.runTransaction(async () => await db.updateArrayMembership(table, update));
     }
@@ -261,7 +257,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * Self-wraps in a transaction when called outside one. Plain-JSON columns only.
    */
   async updatePreserving<T extends R>(table: Table<T>, record: Partial<T>, preserve: PreservedPath[]): Promise<number> {
-    if (!this.currentTransaction) {
+    if (!this.transactionContextFactory.getTransactionContext().currentTransaction) {
       const db = this.newSelfWrapDb();
       return await db.runTransaction(async () => await db.updatePreserving(table, record, preserve));
     }
@@ -316,7 +312,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
       new StatementFactory<T>().delete(table.name, deleteQb, this.statementConfigFactory.getStatementConfig(config));
     await this.runColumnBeforeDeletes(table, recordsToDelete);
     await this.tableWatcherRunner.runBeforeDeleteTableWatchers(table, recordsToDelete, qb, deleteQb);
-    const recordDeleteCount = await this.dbDriver.runDml(generateDelete, this.currentTransaction);
+    const recordDeleteCount = await this.dbDriver.runDml(generateDelete, this.transactionForDriver());
     await this.runCascadeDeletions(table, recordsToDelete);
     await this.runColumnReverseCascadeDeletions(table, recordsToDelete);
     await this.tableWatcherRunner.runAfterDeleteTableWatchers(table, recordDeleteCount, recordsToDelete, qb, deleteQb);
@@ -536,7 +532,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
 
     const generateQuery = (config: DbDriverQueryStatementConfig) =>
       qb.toSql(this.statementConfigFactory.getStatementConfig(config));
-    const serializedRecords = await this.dbDriver.runQuery(generateQuery, this.currentTransaction);
+    const serializedRecords = await this.dbDriver.runQuery(generateQuery, this.transactionForDriver());
     const recordSerializer = new RecordSerializer(table);
     const records = await Promise.all(
       serializedRecords.map(async (serializedRecord) => recordSerializer.deserialize(serializedRecord))
@@ -579,7 +575,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     await this.addColumnQueries(table, qb);
     const generateQuery = (config: DbDriverQueryStatementConfig) =>
       qb.toSql(this.statementConfigFactory.getStatementConfig(config));
-    const result = await this.dbDriver.runQuery(generateQuery, this.currentTransaction);
+    const result = await this.dbDriver.runQuery(generateQuery, this.transactionForDriver());
     return result[0]['count'];
   }
 
@@ -608,13 +604,19 @@ export class Db<R extends Record = Record> implements DbService<R> {
   /**
    * Run a transaction.
    *
-   * Use this db instance for any operation you want to include in the transaction.
-   *
-   * Note: This method uses Db instance state. Usually it is best to create a new instance
-   * of Db to run a transaction.
+   * Db instances are STATELESS with respect to transactions: every operation resolves the
+   * ambient transaction (AsyncLocalStorage) at call time, so any Db instance used inside the
+   * transaction body — whenever it was constructed — rides the transaction. There is no way
+   * to issue an operation outside a transaction from inside its body, and no second session
+   * is ever acquired inside one (the historical pool-wedge class is unrepresentable —
+   * plans/DB_PERF_PLAN.md P2, in the consumer repo).
    *
    * Note: Nested transactions are not supported; will throw.
    *
+   * Note: work spawned inside the body but NOT awaited by it escapes the transaction's
+   * lifetime while still holding its context — such work fails loudly on its next db
+   * operation (see TransactionContextData.ended). Await everything inside the body, or run
+   * it outside the transaction.
    *
    * Example:
    *
@@ -630,8 +632,8 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * ```
    */
   async runTransaction<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.currentTransaction) {
-      throw new Error(`Nested transactions are not supported. A transaction is already running on this Db instance.`);
+    if (this.transactionContextFactory.getTransactionContext().currentTransaction) {
+      throw new Error(`Nested transactions are not supported. A transaction is already running in this context.`);
     }
 
     // Reassigned fresh per driver attempt: drivers may retry `fn` on transient aborts (Spanner's
@@ -639,19 +641,18 @@ export class Db<R extends Record = Record> implements DbService<R> {
     // the attempt that actually commits. Only the committed attempt's queue is drained below.
     let postCommitHooks: PostCommitHook[] = [];
     const result = await this.dbDriver.runTransaction(async (transaction) => {
-      this.currentTransaction = transaction;
+      // A fresh ambient store per attempt: the transaction, the attempt's post-commit hook
+      // queue (shared by every Db instance created inside — see runAfterCommit), and the
+      // ended-tombstone below.
       postCommitHooks = [];
-
+      const contextData: TransactionContextData = { currentTransaction: transaction, postCommitHooks };
       try {
-        return await this.transactionContextFactory.runInContext(transaction, async () => {
-          // Seed the post-commit hook queue on the ambient context so every Db instance created
-          // inside this transaction shares it (see runAfterCommit).
-          this.transactionContextFactory.getTransactionContext().postCommitHooks = postCommitHooks;
-          const result = await fn();
-          return result;
-        });
+        return await this.transactionContextFactory.runInContext(contextData, fn);
       } finally {
-        this.currentTransaction = undefined;
+        // Tombstone the store: detached work spawned inside the body still holds it by
+        // reference — the flag turns its next db operation into a loud error instead of a
+        // silent op on a finished transaction (see transactionForDriver).
+        contextData.ended = true;
       }
     });
 
@@ -714,6 +715,24 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return new Db<R>(this.dbDriver, this.getTable, this.transactionContextFactory, this.runAsSystem);
   }
 
+  /**
+   * The transaction every driver call rides, resolved from the ambient context AT CALL TIME
+   * (statelessness is the safety property: operations inside a transaction body always ride
+   * it; operations outside always use the pool). The one remaining failure shape — work that
+   * escaped a finished transaction's body while holding its context — throws here by name;
+   * handing the driver an ended transaction would fail anyway, with a far worse error.
+   */
+  private transactionForDriver(): any {
+    const context = this.transactionContextFactory.getTransactionContext();
+    if (context.ended) {
+      throw new Error(
+        `Db operation issued in the context of a transaction that already ended: work spawned inside a runTransaction body (and not awaited by it) survived the transaction. Await the work inside the body, or run it outside the transaction.`
+      );
+    }
+
+    return context.currentTransaction;
+  }
+
   // Utility: simple chunker
   private chunk<T>(arr: T[], size: number): T[][] {
     if (size <= 0) {

package/src/MigrationRunner.ts

@@ -13,22 +13,34 @@ export const getMigrationRunner = () =>
 export class MigrationRunner implements MigrationRunnerService {
   private logger = new Logger({ name: this.constructor.name });
   public serviceMetadata: Service['serviceMetadata'] = {
-    // Explicit, not implicit: running migrations is admin-only. Omitting the auth block would
-    // fall back to the same default-deny (admin role), but every service is required to declare
-    // its auth intent explicitly.
+    // Running migrations rides the abstract 'dev' PERMISSION (the developer-surface slug the
+    // db-ui dev pages also declare), resolved through the consumer app's PermissionRolesMapping.
+    // Admin still passes as break-glass. Matches the migration table's doors below the service.
     auth: {
-      roles: ['admin'],
+      permission: 'dev',
     },
     doNotAwait: true,
   };
 
-  async runMigration(id: string): Promise<void> {
+  /**
+   * The service dispatches this fire-and-forget (`doNotAwait`). The method is split along that
+   * seam: everything knowable before the run starts (a bogus id) throws synchronously — the only
+   * path on which an error can still reach the client (the executor wraps it into a
+   * ServiceError -> 400). The returned promise MAY REJECT (infrastructure failure while recording
+   * run state); the caller owns that rejection — on the service path the executor terminally
+   * observes every doNotAwait rejection (logs with method identity, never process death).
+   */
+  runMigration(id: string): Promise<void> {
     const migrationTable: Table<Migration> = new MigrationTable();
     const migration = new SourceRecordRepo().getSourceRecord<Migration>(migrationTable.name, id);
     if (!migration) {
       throw new Error(`Unable to find migration source record for id: ${id}`);
     }
 
+    return this.runAndRecord(migrationTable, migration);
+  }
+
+  private async runAndRecord(migrationTable: Table<Migration>, migration: Migration): Promise<void> {
     const db = getDb();
     migration.status = 'running';
     migration.startTime = moment();
@@ -38,6 +50,9 @@ export class MigrationRunner implements MigrationRunnerService {
       migration.output = await migration.run();
       migration.status = 'success';
     } catch (error: any) {
+      // Domain bookkeeping, not containment: a migration that throws is a run OUTCOME, recorded
+      // as failure status on the record. Only infrastructure failures (the db.update calls
+      // themselves) reject the returned promise.
       migration.failureMessage = error.message;
       migration.failureStack = error.stack;
       migration.status = 'failure';

package/src/auth/TableAuth.ts

@@ -5,8 +5,16 @@ import { Table } from '../Table';
  * @public all users, including guests (do not need to be logged in), do not need any roles
  * @authenticated - users need to be logged in, do not need any roles
  * @roles string[] - authenticated users, having at least one of these roles
+ * @permission - authenticated users holding an abstract permission slug, resolved to roles at
+ * runtime through the consumer app's `PermissionRolesMapping` (see `UserAuth.hasPermission`).
+ * Generic tables declare permissions; only the consumer names roles.
  */
-export type Identity = 'public' | 'authenticated' | string[];
+export type PermissionIdentity = { permission: string };
+
+export type Identity = 'public' | 'authenticated' | string[] | PermissionIdentity;
+
+const isPermissionIdentity = (identity: Identity | undefined): identity is PermissionIdentity =>
+  !!identity && typeof identity === 'object' && !Array.isArray(identity) && typeof identity.permission === 'string';
 
 /**
  * These Identities can perform these operations on this table.
@@ -53,7 +61,10 @@ export class TableAuth {
       (tableAuth.all === 'authenticated' && UserAuth.isLoggedIn()) ||
       (tableAuth[operation] === 'authenticated' && UserAuth.isLoggedIn()) ||
       (Array.isArray(tableAuth.all) && UserAuth.hasRoles(tableAuth.all, 'at least one')) ||
-      (Array.isArray(tableAuth[operation]) && UserAuth.hasRoles(tableAuth[operation] as string[], 'at least one'))
+      (Array.isArray(tableAuth[operation]) && UserAuth.hasRoles(tableAuth[operation] as string[], 'at least one')) ||
+      (isPermissionIdentity(tableAuth.all) && UserAuth.hasPermission(tableAuth.all.permission)) ||
+      (isPermissionIdentity(tableAuth[operation]) &&
+        UserAuth.hasPermission((tableAuth[operation] as PermissionIdentity).permission))
     );
   }
 

package/src/tables/MigrationTable.ts

@@ -17,6 +17,16 @@ export interface Migration extends SourceRecord {
 
 export class MigrationTable extends Table<Migration> {
   public name = 'migration';
+  /**
+   * Both doors ride the 'dev' permission (consumer-mapped; admin passes as break-glass),
+   * matching MigrationRunner's serviceMetadata: the Migrations record table reads/edits via
+   * the service api, and the runner writes run state via the db api as the calling user.
+   * Boot-time source-record loading is a system path (getDbAsSystem) and bypasses doors.
+   */
+  public auth: Table<Migration>['auth'] = {
+    db: { all: { permission: 'dev' } },
+    service: { all: { permission: 'dev' } },
+  };
   public columns = withSourceRecordColumns<Migration>({
     description: new StringColumn('description', {}, 4000),
     status: new StringColumn('status', { defaultValue: async () => 'proposed' }),

package/src/transaction/TransactionContextFactory.ts

@@ -16,9 +16,16 @@ export interface TransactionContextData {
    * `Db.runTransaction` once the driver reports the commit durable.
    */
   postCommitHooks?: PostCommitHook[];
+  /**
+   * Set by `Db.runTransaction` when the transaction completes. Work spawned inside the
+   * transaction body but not awaited by it still holds this store by reference (the async
+   * context propagates) — the flag turns any later db operation from that escaped context
+   * into a loud, named error instead of silently handing the driver a finished transaction.
+   */
+  ended?: boolean;
 }
 
 export interface DefaultTransactionContextFactory extends Loadable {
   getTransactionContext(): TransactionContextData;
-  runInContext<T>(transaction: any, fn: () => Promise<T>): Promise<T>;
+  runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T>;
 }

package/test/MigrationAuth.test.ts

@@ -0,0 +1,87 @@
+import { UserAuth } from '@proteinjs/user-auth';
+// Deep dist path on purpose: the package index doesn't export the auth gate (it is framework
+// plumbing), but the test must exercise the REAL gate, not a re-implementation of its rules.
+import { ServiceAuth } from '@proteinjs/service/dist/src/ServiceAuth';
+import { Method } from '@proteinjs/reflection';
+import { MigrationRunner } from '../src/MigrationRunner';
+import { MigrationTable } from '../src/tables/MigrationTable';
+import { TableAuth } from '../src/auth/TableAuth';
+
+/**
+ * Migrations ride the 'dev' PERMISSION (plans/ROLES_AND_PERMISSIONS.md decision 4), not the
+ * admin role: the MigrationRunner service and the migration table doors resolve 'dev' through
+ * the consumer's PermissionRolesMapping, so a consumer-mapped dev-role holder can run
+ * migrations while admin still passes everything as break-glass. The mapping deliberately names
+ * a role that is NOT the slug ('dev-crew') to prove the indirection, mirroring the
+ * TableServiceAuth suite's stubbing idiom.
+ */
+
+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],
+  };
+};
+
+const canRunMigrations = () => {
+  const method = new Method('runMigration', undefined, true, false, false, false, 'public', []);
+  return ServiceAuth.canRunService(new MigrationRunner(), method, ['some-migration-id']);
+};
+
+describe('migrations ride the dev permission', () => {
+  beforeEach(() => {
+    setMapping({ dev: ['dev-crew'] });
+  });
+
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+    (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = undefined;
+  });
+
+  it(`a consumer-mapped dev-role holder can run migrations and use the migration table's doors`, () => {
+    setUser(['dev-crew']);
+    expect(canRunMigrations()).toBe(true);
+
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    // The record-table page reads via the service api; the runner updates via the db api.
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).not.toThrow();
+      expect(() => auth.canUpdate(table, api)).not.toThrow();
+    }
+  });
+
+  it('a permissionless user is denied the service and both table doors', () => {
+    setUser(['ops-team']);
+    expect(canRunMigrations()).toBe(false);
+
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).toThrow('User is not authorized to query table: migration');
+      expect(() => auth.canUpdate(table, api)).toThrow('User is not authorized to update records in table: migration');
+    }
+  });
+
+  it('admin passes everything as break-glass', () => {
+    setUser(['admin']);
+    expect(canRunMigrations()).toBe(true);
+
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).not.toThrow();
+      expect(() => auth.canUpdate(table, api)).not.toThrow();
+    }
+  });
+});

package/test/MigrationRunnerContainment.test.ts

@@ -0,0 +1,104 @@
+// EnvInfo.isDev() requires a GlobalDataStorage implementation that only exists in a running app
+// (same mock the @proteinjs/service executor suite uses).
+jest.mock('@proteinjs/server-api', () => ({
+  EnvInfo: { isDev: () => true },
+}));
+
+import { Logger, Log, DefaultLogWriter } from '@proteinjs/logger';
+import { Interface, Method } from '@proteinjs/reflection';
+import { Serializer } from '@proteinjs/serializer';
+// Deep dist path on purpose: the package index doesn't export the executor (framework plumbing),
+// but the executor check below must run the REAL BUILT owner of the doNotAwait seam.
+import { ServiceExecutor } from '@proteinjs/service/dist/src/ServiceExecutor';
+import { MigrationRunner } from '../src/MigrationRunner';
+import { Migration, MigrationTable } from '../src/tables/MigrationTable';
+import { SourceRecordRepo } from '../src/source/SourceRecordRepo';
+import { registerTestUser, clearTestUser } from './util/testUser';
+
+/**
+ * MigrationRunnerService is dispatched fire-and-forget (`doNotAwait`): ServiceExecutor calls
+ * runMigration WITHOUT awaiting, so its try/catch sees only SYNCHRONOUS throws and the detached
+ * promise's rejections are terminally observed by the executor itself (service c16645d — logged
+ * with method identity, never an unhandled rejection).
+ *
+ * MigrationRunner's own contract along that seam:
+ * - everything knowable BEFORE the run starts (a bogus id) throws synchronously, the only
+ *   path on which an error can still reach the client (executor wraps it -> 400);
+ * - migration.run() failures are run OUTCOMES, recorded as failure status on the migration
+ *   record (pinned on the emulator in @proteinjs/db-driver-spanner's MigrationRunner.test.ts);
+ * - infrastructure failures (recording run state itself) REJECT the returned promise — the
+ *   caller owns them. On the service path that caller is the executor.
+ */
+
+type ExecutorInternals = { logger: Logger };
+
+/**
+ * This harness loads no reflection graph and registers no DefaultDbDriverFactory, so the body's
+ * FIRST db access (`new Db()` constructing its table-watcher runner) throws this. The specific
+ * message is a harness accident standing in for any mid-run infrastructure failure (db.update
+ * rejecting); the contract under test is that the failure escapes as a rejection at all.
+ */
+const infrastructureFailure = 'Unable to find type: @proteinjs/db/TableWatcher';
+
+const plantMigration = (id: string): Migration => {
+  const migration = {
+    id,
+    description: 'containment test migration',
+    run: async () => undefined,
+  } as Migration;
+  new SourceRecordRepo().loadSourceRecord(new MigrationTable().name, migration);
+  return migration;
+};
+
+describe('MigrationRunner containment (doNotAwait dispatch)', () => {
+  it('throws synchronously on a bogus migration id, not through the detached promise', () => {
+    const runner = new MigrationRunner();
+    expect(() => runner.runMigration('bogus-migration-id')).toThrow(
+      'Unable to find migration source record for id: bogus-migration-id'
+    );
+  });
+
+  it('rejects the detached promise on a mid-run infrastructure failure — the caller owns it', async () => {
+    // The runner no longer swallows infrastructure failures: the rejection escapes to whoever
+    // holds the promise.
+    plantMigration('containment-test-migration');
+
+    const runner = new MigrationRunner();
+    await expect(runner.runMigration('containment-test-migration')).rejects.toThrow(infrastructureFailure);
+  });
+
+  it('through the real built executor, an infrastructure-failure rejection is terminally logged — not process death', async () => {
+    // Admin identity passes the service's 'dev' permission as break-glass (MigrationAuth.test.ts
+    // pins the mapping itself).
+    registerTestUser();
+    try {
+      plantMigration('containment-test-migration-executor');
+
+      const runner = new MigrationRunner();
+      const method = new Method('runMigration', undefined, true, false, false, false, 'public', []);
+      const _interface = new Interface('@proteinjs/db', 'MigrationRunnerService', [], [method]);
+      const executor = new ServiceExecutor(runner, _interface, method);
+      const entries: Log[] = [];
+      (executor as unknown as ExecutorInternals).logger = new Logger({
+        name: 'MigrationRunnerService.runMigration',
+        logWriter: { write: (log: Log) => entries.push(log) } as unknown as DefaultLogWriter,
+      });
+
+      // The client response does not carry the failure — execute resolves immediately.
+      await expect(
+        executor.execute(Serializer.serialize(['containment-test-migration-executor']))
+      ).resolves.toBeUndefined();
+      // The detached rejection settles after the microtask queue drains; flush macrotasks so the
+      // executor's terminal catch has written its log entry. Were the rejection unobserved, jest
+      // would surface it as a failure here — and a bare node process would die.
+      await new Promise((resolve) => setImmediate(resolve));
+      await new Promise((resolve) => setImmediate(resolve));
+
+      const errorEntry = entries.find((entry) => entry.logLevel === 'error');
+      expect(errorEntry?.error?.message).toContain(infrastructureFailure);
+      expect(errorEntry?.obj?.functionName).toBe('MigrationRunnerService.runMigration');
+    } finally {
+      clearTestUser();
+    }
+  });
+});

package/test/TableServiceAuth.test.ts

@@ -63,6 +63,25 @@ class NoAuthTable extends Table<Doc> {
   });
 }
 
+/**
+ * Mirrors the user table's shape: doors keyed to an abstract PERMISSION resolved through the
+ * consumer mapping, with a service-protected column reserved to a dedicated service.
+ */
+class PermissionGatedTable extends Table<Doc> {
+  public name = 'permission_gated_test';
+  public auth: Table<Doc>['auth'] = {
+    service: {
+      query: { permission: 'users' },
+      update: { permission: 'users' },
+    },
+    serviceProtectedColumns: ['owner'],
+  };
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    owner: new StringColumn('owner'),
+  });
+}
+
 /** Read-only intent: only `query` granted (the canDelete-regression shape). */
 class ReadOnlyTable extends Table<Doc> {
   public name = 'read_only_test';
@@ -76,7 +95,10 @@ class ReadOnlyTable extends Table<Doc> {
   });
 }
 
-type UserAuthInternals = { userRepo?: { getUser: () => { email: string; roles: string[] } } };
+type UserAuthInternals = {
+  userRepo?: { getUser: () => { email: string; roles: string[] } };
+  permissionRolesMapping?: { getRoles: (permission: string) => string[] | undefined };
+};
 
 const setUser = (roles: string[]) => {
   (UserAuth as unknown as UserAuthInternals).userRepo = {
@@ -84,6 +106,12 @@ const setUser = (roles: string[]) => {
   };
 };
 
+const setMapping = (mapping: { [permission: string]: string[] }) => {
+  (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = {
+    getRoles: (permission: string) => mapping[permission],
+  };
+};
+
 const auth = () => new TableServiceAuth();
 
 /** A denial must be a client-safe ServiceError naming the table and operation. */
@@ -142,6 +170,67 @@ describe('TableServiceAuth — per-operation service grants', () => {
   });
 });
 
+describe('TableServiceAuth — permission-keyed doors (the user table shape)', () => {
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+    (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = undefined;
+  });
+
+  it(`grants a holder of the consumer's mapped role; denies without the role`, () => {
+    const table = new PermissionGatedTable();
+    setMapping({ users: ['support'] });
+
+    setUser(['support']);
+    expect(auth().canAccess('query', [table, {}])).toBe(true);
+    expect(auth().canAccess('update', [table, { id: 'x', title: 't' }])).toBe(true);
+
+    setUser(['dev']);
+    expectDenied(
+      () => auth().canAccess('query', [table, {}]),
+      'User is not authorized to query table: permission_gated_test'
+    );
+  });
+
+  it('denies everyone but admin when no mapping is registered (default deny)', () => {
+    const table = new PermissionGatedTable();
+    setUser(['support']);
+    expectDenied(
+      () => auth().canAccess('query', [table, {}]),
+      'User is not authorized to query table: permission_gated_test'
+    );
+
+    setUser(['admin']);
+    expect(auth().canAccess('query', [table, {}])).toBe(true);
+  });
+
+  it('operations without a grant stay closed even for permission holders (and admin)', () => {
+    const table = new PermissionGatedTable();
+    setMapping({ users: ['support'] });
+    setUser(['support']);
+    expectDenied(
+      () => auth().canAccess('insert', [table, { title: 't' }]),
+      'User is not authorized to insert records into table: permission_gated_test'
+    );
+    // An auth block with no grant for the operation is a deliberate lock, not an admin default —
+    // the audit-table shape (role_grant_event) depends on this.
+    setUser(['admin']);
+    expectDenied(
+      () => auth().canAccess('delete', [table, { id: 'x' }]),
+      'User is not authorized to delete records from table: permission_gated_test'
+    );
+  });
+
+  it('the protected column stays unwritable even for a permission holder with the update grant', () => {
+    const table = new PermissionGatedTable();
+    setMapping({ users: ['support'] });
+    setUser(['support']);
+    expectDenied(
+      () => auth().canAccess('update', [table, { id: 'x', owner: 'someone' }]),
+      "Column 'owner' cannot be written via the db service on table: permission_gated_test"
+    );
+  });
+});
+
 describe('TableServiceAuth — default deny (no auth block)', () => {
   afterEach(() => {
     (UserAuth as unknown as UserAuthInternals).userRepo = undefined;

package/test/index.ts

@@ -5,6 +5,8 @@ export * from './reusable/DynamicReferenceColumnTests';
 export * from './reusable/TransactionTests';
 export * from './reusable/CascadeDeleteTests';
 
+export * from './util/testUser';
+
 export * from './util/tables/cascadeDeleteTestTables';
 export * from './util/tables/columnTypesTestTables';
 export * from './util/tables/crudTestTables';