@proteinjs/db 1.55.1 → 1.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.55.1",
+  "version": "1.57.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": "c33ab303e81e366f73bb2cfac13f818567c37306"
 }

package/src/Db.ts

@@ -167,6 +167,16 @@ export class Db<R extends Record = Record> implements DbService<R> {
       : this.getDefaultTransactionContextFactory();
   }
 
+  /**
+   * Whether this Db writes as the SYSTEM (`getDbAsSystem()`: no table-auth gate, no scope) rather
+   * than as the session's user. The Db a write hands its hooks ({@link newHookDb}) answers for the
+   * invoking write, so a watcher that must tell a user's write from a system one (archive on a
+   * user's delete; stand aside on a purge) reads the write's mode here instead of the session.
+   */
+  isSystem(): boolean {
+    return this.runAsSystem;
+  }
+
   static getDefaultDbDriver(): DbDriver {
     if (!getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY]) {
       const defaultDbDriverFactory = SourceRepository.get().object<DefaultDbDriverFactory>(
@@ -241,7 +251,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 +279,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 +321,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 +353,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 +399,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 +422,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 +558,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 +1184,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/DbIsSystem.test.ts

@@ -0,0 +1,173 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { Statement } from '@proteinjs/db-query';
+import { Db, DbDriver, DbDriverDmlStatementConfig, getDb, getDbAsSystem } from '../src/Db';
+import { Table } from '../src/Table';
+import { Record, withRecordColumns } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { TableWatcher } from '../src/TableWatcher';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+
+/**
+ * `Db.isSystem()` — the public read of a write's MODE. A hook that must tell a user's write from
+ * the system's (a watcher that archives on a user's delete and stands aside on a purge) reads it
+ * off the Db the write hands it, instead of guessing from the session. Pinned both ways on the
+ * public factories, and — the pin that matters — on the Db the hook runner hands each watcher:
+ * that Db answers for the INVOKING write, whatever the session holds.
+ */
+
+interface Doc extends Record {
+  title: string;
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'is_system_doc';
+  /** Every door open to everyone: a session Db reaches the write with no user to resolve. */
+  public auth: Table<Doc>['auth'] = { db: { all: 'public' } };
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+/** What each hook was handed: the mode of its trailing Db. */
+const handed: { phase: string; mode: boolean | undefined }[] = [];
+
+class ModeRecordingWatcher implements TableWatcher<Doc> {
+  name(): string {
+    return 'ModeRecordingWatcher';
+  }
+
+  table(): Table<Doc> {
+    return docTable;
+  }
+
+  async beforeInsert<T extends Doc>(record: Omit<T, keyof Doc>, db?: Db): Promise<Omit<T, keyof Doc>> {
+    handed.push({ phase: 'beforeInsert', mode: db?.isSystem() });
+    return record;
+  }
+
+  async afterInsert<T extends Doc>(_record: T, db?: Db): Promise<void> {
+    handed.push({ phase: 'afterInsert', mode: db?.isSystem() });
+  }
+}
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+/** Accepts every statement; no database behind it. */
+class AcceptingDriver implements DbDriver {
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by these tests');
+  }
+
+  async runQuery(): Promise<never[]> {
+    return [];
+  }
+
+  async runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement): Promise<number> {
+    generateStatement({
+      useParams: true,
+      useNamedParams: true,
+      prefixTablesWithDb: false,
+      getDriverColumnType: () => 'STRING(MAX)',
+    });
+    return 1;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+}
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+const DEFAULT_DRIVER_GLOBAL = '__proteinjs_db_defaultDbDriver';
+
+const driver = new AcceptingDriver();
+const transactions = new TestTransactionContextFactory();
+const modesHandedBy = async (db: Db<Doc>): Promise<(boolean | undefined)[]> => {
+  handed.length = 0;
+  await db.insert(docTable, { title: 'row' });
+  expect(handed.map(({ phase }) => phase)).toEqual(['beforeInsert', 'afterInsert']);
+  return handed.map(({ mode }) => mode);
+};
+
+describe('Db.isSystem', () => {
+  let originalWatchers: unknown[] | undefined;
+  let originalFactories: unknown[] | undefined;
+  let originalTransactionFactories: unknown[] | undefined;
+
+  beforeAll(() => {
+    originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+    originalFactories = objectCache()['@proteinjs/db/DefaultDbDriverFactory'];
+    originalTransactionFactories = objectCache()['@proteinjs/db/DefaultTransactionContextFactory'];
+    objectCache()['@proteinjs/db/TableWatcher'] = [new ModeRecordingWatcher()];
+    // The public factories resolve their driver and transaction context through reflection.
+    objectCache()['@proteinjs/db/DefaultDbDriverFactory'] = [{ getDbDriver: () => driver }];
+    objectCache()['@proteinjs/db/DefaultTransactionContextFactory'] = [transactions];
+    delete (globalThis as { [key: string]: unknown })[DEFAULT_DRIVER_GLOBAL];
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  afterAll(() => {
+    const restore = (name: string, original: unknown[] | undefined) => {
+      if (original) {
+        objectCache()[name] = original;
+      } else {
+        delete objectCache()[name];
+      }
+    };
+    restore('@proteinjs/db/TableWatcher', originalWatchers);
+    restore('@proteinjs/db/DefaultDbDriverFactory', originalFactories);
+    restore('@proteinjs/db/DefaultTransactionContextFactory', originalTransactionFactories);
+    delete (globalThis as { [key: string]: unknown })[DEFAULT_DRIVER_GLOBAL];
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  test('a system Db answers true, a session Db false — on the public factories and on the constructor', () => {
+    expect(getDbAsSystem().isSystem()).toBe(true);
+    expect(getDb().isSystem()).toBe(false);
+    expect(new Db<Doc>(driver, () => docTable, transactions, true).isSystem()).toBe(true);
+    expect(new Db<Doc>(driver, () => docTable, transactions).isSystem()).toBe(false);
+  });
+
+  test("the Db a write hands its watchers answers for THAT write: a system write's hooks read true", async () => {
+    expect(await modesHandedBy(getDbAsSystem<Doc>())).toEqual([true, true]);
+  });
+
+  test("the Db a write hands its watchers answers for THAT write: a session write's hooks read false", async () => {
+    expect(await modesHandedBy(getDb<Doc>())).toEqual([false, false]);
+  });
+});

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';