@proteinjs/db 1.55.1 → 1.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.55.1",
+  "version": "1.56.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "195e4d8a6aae026ad6c6b8b0fbfa831a57ecb501"
+  "gitHead": "469b64193ef5d4fc0faa74ebe1f6c2af04dfd6cb"
 }

package/src/Db.ts

@@ -241,7 +241,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
 
     let recordCopy = Object.assign({}, record);
     await addDefaultFieldValues(table, recordCopy, this.runAsSystem);
-    recordCopy = await this.tableWatcherRunner.runBeforeInsertTableWatchers(table, recordCopy);
+    recordCopy = await this.tableWatcherRunner.runBeforeInsertTableWatchers(table, recordCopy, this.newHookDb());
     await this.addColumnInsertHooks(table, recordCopy);
     const encryptionContext = await this.encryptionWriteContext(table, recordCopy);
     const recordSerializer = new RecordSerializer(table, encryptionContext);
@@ -269,7 +269,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
       );
     }
     await this.runColumnAfterInsertHooks(table, recordCopy);
-    await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
+    await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T, this.newHookDb());
     return recordCopy as T;
   }
 
@@ -311,7 +311,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     for (const record of records) {
       let recordCopy = Object.assign({}, record);
       await addDefaultFieldValues(table, recordCopy, this.runAsSystem);
-      recordCopy = await this.tableWatcherRunner.runBeforeInsertTableWatchers(table, recordCopy);
+      recordCopy = await this.tableWatcherRunner.runBeforeInsertTableWatchers(table, recordCopy, this.newHookDb());
       await this.addColumnInsertHooks(table, recordCopy);
       const encryptionContext = await this.encryptionWriteContext(table, recordCopy);
       const serializedRecord = await new RecordSerializer(table, encryptionContext).serialize(recordCopy);
@@ -343,7 +343,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         );
       }
       await this.runColumnAfterInsertHooks(table, recordCopy);
-      await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
+      await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T, this.newHookDb());
     }
     return prepared.map((row) => row.recordCopy as T);
   }
@@ -389,7 +389,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
       qb.condition({ field: 'id', operator: '=', value: recordCopy.id as T[keyof T] });
     }
 
-    recordCopy = await this.tableWatcherRunner.runBeforeUpdateTableWatchers(table, recordCopy, qb);
+    recordCopy = await this.tableWatcherRunner.runBeforeUpdateTableWatchers(table, recordCopy, qb, this.newHookDb());
     let recordUpdateCount: number;
     if (await this.updateTouchesEncryptedColumns(table, recordCopy)) {
       recordUpdateCount = await this.updateEncrypted(table, recordCopy, qb, driverOptions);
@@ -412,7 +412,13 @@ export class Db<R extends Record = Record> implements DbService<R> {
         await this.runZeroRowFilteredWriteHooks(table, id, 'write');
       }
     }
-    await this.tableWatcherRunner.runAfterUpdateTableWatchers(table, recordUpdateCount, recordCopy, qb);
+    await this.tableWatcherRunner.runAfterUpdateTableWatchers(
+      table,
+      recordUpdateCount,
+      recordCopy,
+      qb,
+      this.newHookDb()
+    );
     return recordUpdateCount;
   }
 
@@ -542,34 +548,31 @@ export class Db<R extends Record = Record> implements DbService<R> {
     const generateDelete = (config: DbDriverDmlStatementConfig) =>
       new StatementFactory<T>().delete(table.name, deleteQb, this.statementConfigFactory.getStatementConfig(config));
     await this.runColumnBeforeDeletes(table, recordsToDelete);
-    await this.tableWatcherRunner.runBeforeDeleteTableWatchers(table, recordsToDelete, qb, deleteQb);
+    await this.tableWatcherRunner.runBeforeDeleteTableWatchers(table, recordsToDelete, qb, deleteQb, this.newHookDb());
     const recordDeleteCount = await this.dbDriver.runDml(generateDelete, this.transactionForDriver());
     await this.runCascadeDeletions(table, recordsToDelete);
     await this.runColumnReverseCascadeDeletions(table, recordsToDelete);
     await this.deleteEncryptionTokenRows(table, recordsToDeleteIds as string[]);
-    await this.tableWatcherRunner.runAfterDeleteTableWatchers(table, recordDeleteCount, recordsToDelete, qb, deleteQb);
+    await this.tableWatcherRunner.runAfterDeleteTableWatchers(
+      table,
+      recordDeleteCount,
+      recordsToDelete,
+      qb,
+      deleteQb,
+      this.newHookDb()
+    );
     return recordDeleteCount;
   }
 
   /**
-   * A column's `beforeDelete` hook runs with the authority of the write that fired it: the Db it
-   * is handed rides this instance's driver, tables and transaction context AND its system mode.
-   * The hooks cascade a delete through reference columns, and a system delete's cascade must stay
-   * system — handed a default (non-system) Db, the cascade ran as whoever the session held, which
-   * narrowed it to that user's rows inside a request and refused it outright in a background
-   * context, where a scoped table finds no user to scope the query to.
+   * A column's `beforeDelete` hook cascades the delete through reference columns, with the
+   * authority of the write that fired it ({@link newHookDb}).
    */
   private async runColumnBeforeDeletes(table: Table<any>, recordsToDelete: Record[]) {
     for (const columnPropertyName in table.columns) {
       const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
       if (typeof column.beforeDelete !== 'undefined') {
-        await column.beforeDelete(
-          table,
-          columnPropertyName,
-          recordsToDelete,
-          this.getTable,
-          new Db(this.dbDriver, this.getTable, this.transactionContextFactory, this.runAsSystem)
-        );
+        await column.beforeDelete(table, columnPropertyName, recordsToDelete, this.getTable, this.newHookDb());
       }
     }
   }
@@ -1171,6 +1174,22 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return new Db<any>(this.dbDriver, this.getTable, this.transactionContextFactory, true);
   }
 
+  /**
+   * The Db a hook is handed — a column's `beforeDelete`, a table watcher's six hooks: an instance
+   * riding THIS instance's driver, tables and transaction context AND its system mode, so the hook
+   * runs with the authority of the write that fired it. A hook that opened a Db of its own
+   * (`getDb()`, a session-scoped Db) ran as whoever the session held: a system write's follow-on
+   * narrowed to that user's rows inside a request, and refused outright in a background context
+   * (an account purge, a sweep, a deploy gate), where a scoped table finds no user to scope the
+   * query to — the cascade left orphans, the watcher left its rows (a message's topic links, a
+   * media row's file) and either swallowed or raised the "No user in scope context" error.
+   * Transaction state is instance state ({@link newSelfWrapDb}), so the hook rides the ambient
+   * transaction through the shared context and never this instance's own.
+   */
+  private newHookDb(): Db<any> {
+    return new Db<any>(this.dbDriver, this.getTable, this.transactionContextFactory, this.runAsSystem);
+  }
+
   /**
    * A fresh instance for self-wrapping RMW verbs (`updateArrayMembership`, `updatePreserving`)
    * in a transaction. `runTransaction` carries the open transaction as INSTANCE state, and these

package/src/TableWatcher.ts

@@ -2,6 +2,7 @@ import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { QueryBuilder } from '@proteinjs/db-query';
 import { Record } from './Record';
 import { Table } from './Table';
+import { Db } from './Db';
 
 type RequiredProps<T, K extends keyof T> = Omit<T, K> & {
   [P in K]-?: T[P];
@@ -65,22 +66,32 @@ export const getTableWatcherMap = <R extends Record = any>(): TableWatcherMap<R>
 export const getTableWatchers = <R extends Record = any>() =>
   SourceRepository.get().objects<TableWatcher<R>>('@proteinjs/db/TableWatcher');
 
+/**
+ * Hooks around a table's writes. Every hook's trailing `db` is the Db the invoking write made
+ * for its hooks — the write's driver, tables and transaction context AND its system mode — so a
+ * watcher's own reads and writes carry the authority of the write that fired it: a system write's
+ * follow-on runs as system (a background purge with no session user), a request's as its session.
+ * The Db hands it to every hook; a watcher never opens a Db of its own for the write's follow-on.
+ * Optional in the type so an implementer that ignores it still conforms.
+ */
 export interface TableWatcher<R extends Record = Record> extends Loadable {
   name(): string;
   table(): Table<R>;
-  beforeInsert?<T extends R>(record: Omit<T, keyof R>): Promise<Omit<T, keyof R>>;
-  afterInsert?<T extends R>(record: T): Promise<void>;
-  beforeUpdate?<T extends R>(record: Partial<T>, qb: QueryBuilder<T>): Promise<Partial<T>>;
-  afterUpdate?<T extends R>(recordUpdateCount: number, record: Partial<T>, qb: QueryBuilder<T>): Promise<void>;
+  beforeInsert?<T extends R>(record: Omit<T, keyof R>, db?: Db): Promise<Omit<T, keyof R>>;
+  afterInsert?<T extends R>(record: T, db?: Db): Promise<void>;
+  beforeUpdate?<T extends R>(record: Partial<T>, qb: QueryBuilder<T>, db?: Db): Promise<Partial<T>>;
+  afterUpdate?<T extends R>(recordUpdateCount: number, record: Partial<T>, qb: QueryBuilder<T>, db?: Db): Promise<void>;
   beforeDelete?<T extends R>(
     recordsToDelete: T[],
     initialQb: QueryBuilder<T>,
-    deleteQb: QueryBuilder<T>
+    deleteQb: QueryBuilder<T>,
+    db?: Db
   ): Promise<void>;
   afterDelete?<T extends R>(
     recordDeleteCount: number,
     deletedRecords: T[],
     initialQb: QueryBuilder<T>,
-    deleteQb: QueryBuilder<T>
+    deleteQb: QueryBuilder<T>,
+    db?: Db
   ): Promise<void>;
 }

package/src/TableWatcherRunner.ts

@@ -2,11 +2,19 @@ import { Logger } from '@proteinjs/logger';
 import { TableWatcherMap, getTableWatcherMap } from './TableWatcher';
 import { Record } from './Record';
 import { Table } from './Table';
+import { Db } from './Db';
 import { QueryBuilder } from '@proteinjs/db-query';
 
 const getEnvVar = (key: string): string | undefined =>
   typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
 
+/**
+ * Runs a table's watchers around a write. Every hook is handed `db`, the Db the invoking write
+ * made for its hooks (`Db.newHookDb`): the write's driver, tables and transaction context AND its
+ * system mode, so a watcher's own reads and writes carry the authority of the write that fired
+ * it. A watcher never opens a Db of its own for the write's follow-on — a session-scoped Db ran
+ * as whoever the session held, which refused a system write's follow-on in a background context.
+ */
 export class TableWatcherRunner<R extends Record = Record> {
   private static tableWatcherMap: TableWatcherMap;
   private logger = new Logger({ name: this.constructor.name, logLevel: getEnvVar('DB_LOG_LEVEL') as any });
@@ -19,7 +27,8 @@ export class TableWatcherRunner<R extends Record = Record> {
 
   async runBeforeInsertTableWatchers<T extends R>(
     table: Table<T>,
-    record: Omit<T, keyof R>
+    record: Omit<T, keyof R>,
+    db: Db
   ): Promise<Omit<T, keyof R>> {
     const tableWatcherMap = TableWatcherRunner.tableWatcherMap[table.name];
     if (!tableWatcherMap) {
@@ -35,7 +44,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     let updatedRecord: any = record;
     for (const tableWatcher of tableWatchers) {
       this.logger.info({ message: `(${table.name}) Running ${tableWatcher.name()}.beforeInsert` });
-      updatedRecord = await tableWatcher.beforeInsert(updatedRecord);
+      updatedRecord = await tableWatcher.beforeInsert(updatedRecord, db);
       this.logger.info({ message: `(${table.name}) Finished running ${tableWatcher.name()}.beforeInsert` });
     }
     this.logger.info({ message: `(${table.name}) Finished running before-insert table watchers` });
@@ -43,7 +52,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     return updatedRecord;
   }
 
-  async runAfterInsertTableWatchers<T extends R>(table: Table<T>, record: T): Promise<void> {
+  async runAfterInsertTableWatchers<T extends R>(table: Table<T>, record: T, db: Db): Promise<void> {
     const tableWatcherMap = TableWatcherRunner.tableWatcherMap[table.name];
     if (!tableWatcherMap) {
       return;
@@ -57,7 +66,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     this.logger.info({ message: `(${table.name}) Running after-insert table watchers` });
     for (const tableWatcher of tableWatchers) {
       this.logger.info({ message: `(${table.name}) Running ${tableWatcher.name()}.afterInsert` });
-      await tableWatcher.afterInsert(record);
+      await tableWatcher.afterInsert(record, db);
       this.logger.info({ message: `(${table.name}) Finished running ${tableWatcher.name()}.afterInsert` });
     }
     this.logger.info({ message: `(${table.name}) Finished running after-insert table watchers` });
@@ -66,7 +75,8 @@ export class TableWatcherRunner<R extends Record = Record> {
   async runBeforeUpdateTableWatchers<T extends R>(
     table: Table<T>,
     record: Partial<T>,
-    qb: QueryBuilder<T>
+    qb: QueryBuilder<T>,
+    db: Db
   ): Promise<Partial<T>> {
     const tableWatcherMap = TableWatcherRunner.tableWatcherMap[table.name];
     if (!tableWatcherMap) {
@@ -83,7 +93,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     let updatedRecord: any = record;
     for (const tableWatcher of tableWatchers) {
       this.logger.info({ message: `(${table.name}) Running ${tableWatcher.name()}.beforeUpdate` });
-      updatedRecord = await tableWatcher.beforeUpdate(updatedRecord, qbCopy);
+      updatedRecord = await tableWatcher.beforeUpdate(updatedRecord, qbCopy, db);
       this.logger.info({ message: `(${table.name}) Finished running ${tableWatcher.name()}.beforeUpdate` });
     }
     this.logger.info({ message: `(${table.name}) Finished running before-update table watchers` });
@@ -95,7 +105,8 @@ export class TableWatcherRunner<R extends Record = Record> {
     table: Table<T>,
     recordUpdateCount: number,
     record: Partial<T>,
-    qb: QueryBuilder<T>
+    qb: QueryBuilder<T>,
+    db: Db
   ): Promise<void> {
     const tableWatcherMap = TableWatcherRunner.tableWatcherMap[table.name];
     if (!tableWatcherMap) {
@@ -111,7 +122,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     const qbCopy = QueryBuilder.fromQueryBuilder(qb, table.name);
     for (const tableWatcher of tableWatchers) {
       this.logger.info({ message: `(${table.name}) Running ${tableWatcher.name()}.afterUpdate` });
-      await tableWatcher.afterUpdate(recordUpdateCount, record, qbCopy);
+      await tableWatcher.afterUpdate(recordUpdateCount, record, qbCopy, db);
       this.logger.info({ message: `(${table.name}) Finished running ${tableWatcher.name()}.afterUpdate` });
     }
     this.logger.info({ message: `(${table.name}) Finished running after-update table watchers` });
@@ -121,7 +132,8 @@ export class TableWatcherRunner<R extends Record = Record> {
     table: Table<T>,
     recordsToDelete: T[],
     initialQb: QueryBuilder<T>,
-    deleteQb: QueryBuilder<T>
+    deleteQb: QueryBuilder<T>,
+    db: Db
   ): Promise<void> {
     const tableWatcherMap = TableWatcherRunner.tableWatcherMap[table.name];
     if (!tableWatcherMap) {
@@ -137,7 +149,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     const initialQbCopy = QueryBuilder.fromQueryBuilder(initialQb, table.name);
     for (const tableWatcher of tableWatchers) {
       this.logger.info({ message: `(${table.name}) Running ${tableWatcher.name()}.beforeDelete` });
-      await tableWatcher.beforeDelete(recordsToDelete, initialQbCopy, deleteQb);
+      await tableWatcher.beforeDelete(recordsToDelete, initialQbCopy, deleteQb, db);
       this.logger.info({ message: `(${table.name}) Finished running ${tableWatcher.name()}.beforeDelete` });
     }
     this.logger.info({ message: `(${table.name}) Finished running before-delete table watchers` });
@@ -148,7 +160,8 @@ export class TableWatcherRunner<R extends Record = Record> {
     recordDeleteCount: number,
     deletedRecords: T[],
     initialQb: QueryBuilder<T>,
-    deleteQb: QueryBuilder<T>
+    deleteQb: QueryBuilder<T>,
+    db: Db
   ): Promise<void> {
     const tableWatcherMap = TableWatcherRunner.tableWatcherMap[table.name];
     if (!tableWatcherMap) {
@@ -164,7 +177,7 @@ export class TableWatcherRunner<R extends Record = Record> {
     const initialQbCopy = QueryBuilder.fromQueryBuilder(initialQb, table.name);
     for (const tableWatcher of tableWatchers) {
       this.logger.info({ message: `(${table.name}) Running ${tableWatcher.name()}.afterDelete` });
-      await tableWatcher.afterDelete(recordDeleteCount, deletedRecords, initialQbCopy, deleteQb);
+      await tableWatcher.afterDelete(recordDeleteCount, deletedRecords, initialQbCopy, deleteQb, db);
       this.logger.info({ message: `(${table.name}) Finished running ${tableWatcher.name()}.afterDelete` });
     }
     this.logger.info({ message: `(${table.name}) Finished running after-delete table watchers` });

package/test/index.ts

@@ -8,6 +8,7 @@ export * from './reusable/PreloadReferencesTests';
 export * from './reusable/RecordIteratorTests';
 export * from './reusable/SourceRecordSyncTests';
 export * from './reusable/StoredValueContractTests';
+export * from './reusable/TableWatcherAuthorityTests';
 
 export * from './util/testUser';
 
@@ -19,4 +20,5 @@ export * from './util/tables/recordIteratorTestTables';
 export * from './util/tables/sourceRecordSyncTestTables';
 export * from './util/tables/storedValueContractTestTables';
 export * from './util/tables/tableManagerTestTables';
+export * from './util/tables/tableWatcherAuthorityTestTables';
 export * from './util/tables/transactionTestTables';

package/test/reusable/TableWatcherAuthorityTests.ts

@@ -0,0 +1,204 @@
+import { Db, DbDriver, Table, TableWatcher, DefaultTransactionContextFactory } from '@proteinjs/db';
+import { QueryBuilder } from '@proteinjs/db-query';
+import { SourceRepository } from '@proteinjs/reflection';
+import { DbTestEnvironment } from '../util/DbTestEnvironment';
+import { TableWatcherRunner } from '../../src/TableWatcherRunner';
+import {
+  GuardedJournal,
+  tableWatcherAuthorityTestTables,
+  WATCHER_GUARDED_REFUSAL,
+  WatchedNote,
+} from '../util/tables/tableWatcherAuthorityTestTables';
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+const resetTableWatcherMap = () => {
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+};
+
+/** The watcher's refusal when a hook arrives without the write's Db — the contract's first half. */
+export const HOOK_HANDED_NO_DB = 'the hook was handed no Db';
+
+const HOOKS = ['beforeInsert', 'afterInsert', 'beforeUpdate', 'afterUpdate', 'beforeDelete', 'afterDelete'];
+
+/**
+ * Journals every hook run through the HANDED Db and nothing else — the way a watcher is written
+ * once the Db hands one (chat's topic watcher deleting a deleted message's topic links, the media
+ * watcher deleting a deleted row's file, the activity watcher bumping the chat a message landed
+ * in). The journal is a guarded table, so the hook's write and read succeed only with a system
+ * Db: the one the write made, carrying its own authority.
+ */
+class JournalingWatcher implements TableWatcher<WatchedNote> {
+  name(): string {
+    return 'JournalingWatcher';
+  }
+
+  table(): Table<WatchedNote> {
+    return tableWatcherAuthorityTestTables.WatchedNote;
+  }
+
+  async beforeInsert<T extends WatchedNote>(
+    record: Omit<T, keyof WatchedNote>,
+    db?: Db
+  ): Promise<Omit<T, keyof WatchedNote>> {
+    await this.journal(db, (record as unknown as WatchedNote).id, 'beforeInsert');
+    return record;
+  }
+
+  async afterInsert<T extends WatchedNote>(record: T, db?: Db): Promise<void> {
+    await this.journal(db, record.id, 'afterInsert');
+  }
+
+  async beforeUpdate<T extends WatchedNote>(record: Partial<T>, qb: QueryBuilder<T>, db?: Db): Promise<Partial<T>> {
+    for (const row of await this.handed(db).query(this.table(), qb as unknown as QueryBuilder<WatchedNote>)) {
+      await this.journal(db, row.id, 'beforeUpdate');
+    }
+    return record;
+  }
+
+  async afterUpdate<T extends WatchedNote>(
+    recordUpdateCount: number,
+    record: Partial<T>,
+    qb: QueryBuilder<T>,
+    db?: Db
+  ): Promise<void> {
+    for (const row of await this.handed(db).query(this.table(), qb as unknown as QueryBuilder<WatchedNote>)) {
+      await this.journal(db, row.id, 'afterUpdate');
+    }
+  }
+
+  async beforeDelete<T extends WatchedNote>(
+    recordsToDelete: T[],
+    _initialQb: QueryBuilder<T>,
+    _deleteQb: QueryBuilder<T>,
+    db?: Db
+  ): Promise<void> {
+    for (const row of recordsToDelete) {
+      await this.journal(db, row.id, 'beforeDelete');
+    }
+  }
+
+  async afterDelete<T extends WatchedNote>(
+    _recordDeleteCount: number,
+    deletedRecords: T[],
+    _initialQb: QueryBuilder<T>,
+    _deleteQb: QueryBuilder<T>,
+    db?: Db
+  ): Promise<void> {
+    for (const row of deletedRecords) {
+      await this.journal(db, row.id, 'afterDelete');
+      // The read half of the contract: a query through the handed Db over the guarded table.
+      await this.handed(db).query(tableWatcherAuthorityTestTables.GuardedJournal, { note: row.id });
+    }
+  }
+
+  private async journal(db: Db | undefined, note: string, hook: string): Promise<void> {
+    await this.handed(db).insert(tableWatcherAuthorityTestTables.GuardedJournal, {
+      note,
+      hook,
+      principal: 'the write',
+    });
+  }
+
+  private handed(db: Db | undefined): Db {
+    if (!db) {
+      throw new Error(HOOK_HANDED_NO_DB);
+    }
+    return db;
+  }
+}
+
+/**
+ * A table watcher's hooks run with the authority of the write that fired them: the Db hands every
+ * hook a Db carrying its driver, tables, transaction context and system mode. Before this the
+ * hooks were handed nothing and each watcher opened a session-scoped Db of its own, which a system
+ * write in a session-less context (an account purge, a sweep) could not use — the topic links of a
+ * purged message and the file of a system-deleted media row stayed behind, and the activity bump
+ * of a system-inserted message threw.
+ */
+export const tableWatcherAuthorityTests = (
+  driver: DbDriver,
+  transactionContextFactory: DefaultTransactionContextFactory,
+  dropTable: (table: Table<any>) => Promise<void>
+) => {
+  return () => {
+    const testEnv = new DbTestEnvironment(driver, dropTable);
+    const notes = tableWatcherAuthorityTestTables.WatchedNote;
+    const journal = tableWatcherAuthorityTestTables.GuardedJournal;
+    // Constructed in beforeAll, AFTER the watcher registration below: a Db's construction builds
+    // the runner's static watcher map, and the map must be built from the registered watcher.
+    let systemDb: Db;
+    let sessionDb: Db;
+    let originalWatchers: unknown[] | undefined;
+
+    /** A fresh async hop — the shape of a background context that inherits no caller's state. */
+    const inFreshContext = <T>(fn: () => Promise<T>): Promise<T> =>
+      new Promise<T>((resolve, reject) => {
+        setImmediate(() => {
+          fn().then(resolve, reject);
+        });
+      });
+
+    const journalHooksFor = async (noteId: string): Promise<string[]> =>
+      (await systemDb.query(journal, { note: noteId })).map((row: GuardedJournal) => row.hook).sort();
+
+    beforeAll(async () => {
+      originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+      objectCache()['@proteinjs/db/TableWatcher'] = [new JournalingWatcher()];
+      resetTableWatcherMap();
+      systemDb = new Db(driver, undefined, transactionContextFactory, true);
+      sessionDb = new Db(driver, undefined, transactionContextFactory);
+      await testEnv.beforeAll();
+    }, 120000);
+
+    afterAll(async () => {
+      await testEnv.afterAll();
+      if (originalWatchers) {
+        objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+      } else {
+        delete objectCache()['@proteinjs/db/TableWatcher'];
+      }
+      resetTableWatcherMap();
+    }, 120000);
+
+    beforeEach(async () => {
+      await systemDb.delete(journal, {});
+      await systemDb.delete(notes, {});
+    });
+
+    describe('Table watchers carry the write’s authority', () => {
+      test('a system insert, update and delete in a session-less context: all six hooks write and read the guarded journal through the handed Db', async () => {
+        const noteId = await inFreshContext(async () => {
+          const note = await systemDb.insert(notes, { title: 'Kept' });
+          await systemDb.update(notes, { title: 'Kept, renamed' }, { id: note.id });
+          await systemDb.delete(notes, { id: note.id });
+          return note.id;
+        });
+
+        expect(await systemDb.query(notes, { id: noteId })).toHaveLength(0);
+        expect(await journalHooksFor(noteId)).toEqual([...HOOKS].sort());
+      });
+
+      test('a session write’s hooks run as the session, never as system: the guarded journal refuses the first hook and the write with it', async () => {
+        await expect(sessionDb.insert(notes, { title: 'Refused' })).rejects.toThrow(WATCHER_GUARDED_REFUSAL);
+        expect(await systemDb.query(notes, { title: 'Refused' })).toHaveLength(0);
+      });
+
+      test('the handed Db rides the write’s transaction: a rolled-back system insert leaves no journal row', async () => {
+        let noteId: string | undefined;
+        await expect(
+          systemDb.runTransaction(async () => {
+            const note = await systemDb.insert(notes, { title: 'Rolled back' });
+            noteId = note.id;
+            throw new Error('roll back');
+          })
+        ).rejects.toThrow('roll back');
+
+        expect(noteId).toBeDefined();
+        expect(await systemDb.query(notes, { id: noteId })).toHaveLength(0);
+        expect(await journalHooksFor(noteId!)).toEqual([]);
+      });
+    });
+  };
+};

package/test/util/DbTestEnvironment.ts

@@ -8,6 +8,7 @@ import { recordIteratorTestTables } from './tables/recordIteratorTestTables';
 import { sourceRecordSyncTestTables } from './tables/sourceRecordSyncTestTables';
 import { storedValueContractTestTables } from './tables/storedValueContractTestTables';
 import { tableManagerTestTables } from './tables/tableManagerTestTables';
+import { tableWatcherAuthorityTestTables } from './tables/tableWatcherAuthorityTestTables';
 import { transactionTestTables } from './tables/transactionTestTables';
 
 const TABLES: Table<any>[] = [
@@ -20,6 +21,7 @@ const TABLES: Table<any>[] = [
   // The member tables are the stored-value suite's own: it builds each physical column order itself.
   storedValueContractTestTables.Mixed,
   ...Object.values(tableManagerTestTables),
+  ...Object.values(tableWatcherAuthorityTestTables),
   ...Object.values(transactionTestTables),
 ];
 

package/test/util/tables/tableWatcherAuthorityTestTables.ts

@@ -0,0 +1,61 @@
+import { StringColumn, Table, withRecordColumns, Record } from '@proteinjs/db';
+
+// --- Table watchers run with the authority of the write that fired them (WatchedNote -> GuardedJournal)
+
+/** The watched table: a plain row whose writes fire the suite's journaling watcher. */
+export interface WatchedNote extends Record {
+  title: string;
+}
+
+/** The watcher's journal: one row per hook run, writable and readable as system only. */
+export interface GuardedJournal extends Record {
+  /** The watched row's id. */
+  note: string;
+  /** The hook that wrote the row (`beforeInsert` … `afterDelete`). */
+  hook: string;
+  /** The scoped-table contract in miniature — see {@link GuardedJournalTable}. */
+  principal: string;
+}
+
+const WATCHED_NOTE_TABLE = 'db_test_tw_notes';
+const GUARDED_JOURNAL_TABLE = 'db_test_tw_guarded_journal';
+
+/** The journal's refusal of a non-system write or query, by name. */
+export const WATCHER_GUARDED_REFUSAL = 'no user in scope (journal)';
+
+export class WatchedNoteTable extends Table<WatchedNote> {
+  name = WATCHED_NOTE_TABLE;
+  columns: Table<WatchedNote>['columns'] = withRecordColumns<WatchedNote>({
+    title: new StringColumn('title'),
+  });
+}
+
+/**
+ * A scoped table's shape without a dependency on one: a non-system write needs the context's
+ * user to stamp the row with, a non-system query needs it to scope the query to — there is none
+ * in a session-less context, so both refuse by name. A system write supplies the principal itself
+ * and a system query is not scoped, exactly as `@proteinjs/user`'s ScopedRecord columns behave.
+ */
+export class GuardedJournalTable extends Table<GuardedJournal> {
+  name = GUARDED_JOURNAL_TABLE;
+  columns: Table<GuardedJournal>['columns'] = withRecordColumns<GuardedJournal>({
+    note: new StringColumn('note'),
+    hook: new StringColumn('hook'),
+    principal: new StringColumn('principal', {
+      defaultValue: async () => {
+        throw new Error(WATCHER_GUARDED_REFUSAL);
+      },
+      forceDefaultValue: (runAsSystem) => !runAsSystem,
+      addToQuery: async (qb, runAsSystem) => {
+        if (!runAsSystem) {
+          throw new Error(WATCHER_GUARDED_REFUSAL);
+        }
+      },
+    }),
+  });
+}
+
+export const tableWatcherAuthorityTestTables = {
+  WatchedNote: new WatchedNoteTable() as Table<WatchedNote>,
+  GuardedJournal: new GuardedJournalTable() as Table<GuardedJournal>,
+};