@proteinjs/db 1.55.0 → 1.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.55.0",
+  "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": "e2cb123d846e60e8cddccbca06b5076a009817ed"
+  "gitHead": "469b64193ef5d4fc0faa74ebe1f6c2af04dfd6cb"
 }

package/src/Columns.ts

@@ -1,6 +1,6 @@
 import moment from 'moment';
 import { v1 as uuidv1 } from 'uuid';
-import { Column, ColumnOptions, getColumnPropertyName, Table, tableByName } from './Table';
+import { Column, ColumnOptions, getColumnPropertyName, Table } from './Table';
 import { Record } from './Record';
 import { ReferenceArray } from './reference/ReferenceArray';
 import { Db } from './Db';
@@ -263,17 +263,29 @@ export class ReferenceArrayColumn<T extends Record> extends ObjectColumn<Referen
     return new ReferenceArray(this.referenceTable, ids);
   }
 
-  async beforeDelete(table: Table<any>, columnPropertyName: string, records: any[]) {
+  /**
+   * Cascade: the referenced records go with the holder. Runs through the Db the firing write
+   * hands it — its driver, its transaction context, its authority — and off the ids the column
+   * stores; nothing here opens a Db of its own or re-reads the referenced rows, either of which
+   * would run as the session's user rather than as the write (a system delete's cascade must stay
+   * system: in a background context there is no session user at all).
+   */
+  async beforeDelete(
+    table: Table<any>,
+    columnPropertyName: string,
+    records: any[],
+    getTable?: (tableName: string) => Table<any>,
+    db?: Db
+  ): Promise<void> {
     if (!this.cascadeDelete) {
       return;
     }
 
     const recordIdsToDelete: string[] = [];
     for (const record of records) {
-      const referenceArray = record[columnPropertyName] as ReferenceArray<Record>;
-      const referenceRecords = await referenceArray.get();
-      for (const referenceRecord of referenceRecords) {
-        recordIdsToDelete.push(referenceRecord.id);
+      const referenceArray = record[columnPropertyName] as ReferenceArray<Record> | null | undefined;
+      if (referenceArray) {
+        recordIdsToDelete.push(...referenceArray._ids);
       }
     }
 
@@ -281,11 +293,12 @@ export class ReferenceArrayColumn<T extends Record> extends ObjectColumn<Referen
       return;
     }
 
-    const referenceTable = tableByName(this.referenceTable);
+    // Optional in the hook contract for implementers that need neither; the Db hands both to every hook.
+    const referenceTable = getTable!(this.referenceTable);
     const qb = new QueryBuilderFactory()
       .getQueryBuilder(referenceTable)
       .condition({ field: 'id', operator: 'IN', value: recordIdsToDelete });
-    await new Db().delete(referenceTable, qb);
+    await db!.delete(referenceTable, qb);
   }
 }
 
@@ -331,7 +344,18 @@ export class ReferenceColumn<T extends Record> extends StringColumn<Reference<T>
     return reference as Reference<T>;
   }
 
-  async beforeDelete(table: Table<any>, columnPropertyName: string, records: any[]) {
+  /**
+   * Cascade: the referenced record goes with the holder. Runs through the Db the firing write
+   * hands it (its driver, transaction context and authority) off the stored id — see
+   * `ReferenceArrayColumn.beforeDelete` for why the hook never opens a Db of its own.
+   */
+  async beforeDelete(
+    table: Table<any>,
+    columnPropertyName: string,
+    records: any[],
+    getTable?: (tableName: string) => Table<any>,
+    db?: Db
+  ): Promise<void> {
     if (!this.cascadeDelete) {
       return;
     }
@@ -348,11 +372,12 @@ export class ReferenceColumn<T extends Record> extends StringColumn<Reference<T>
       return;
     }
 
-    const referenceTable = tableByName(this.referenceTable);
+    // Optional in the hook contract for implementers that need neither; the Db hands both to every hook.
+    const referenceTable = getTable!(this.referenceTable);
     const qb = new QueryBuilderFactory()
       .getQueryBuilder(referenceTable)
       .condition({ field: 'id', operator: 'IN', value: recordIdsToDelete });
-    await new Db().delete(referenceTable, qb);
+    await db!.delete(referenceTable, qb);
   }
 }
 
@@ -508,6 +533,12 @@ export class DynamicReferenceColumn<T extends Record> extends StringColumn<Refer
     return new Reference<T>(tableName, serializedFieldValue);
   }
 
+  /**
+   * Cascade: the referenced record goes with the holder, whichever table the row names. Runs
+   * through the Db the firing write hands it (its driver, transaction context and authority) off
+   * the stored ids — see `ReferenceArrayColumn.beforeDelete` for why the hook never opens a Db of
+   * its own.
+   */
   async beforeDelete(
     table: Table<any>,
     columnPropertyName: string,
@@ -519,12 +550,8 @@ export class DynamicReferenceColumn<T extends Record> extends StringColumn<Refer
       return;
     }
 
-    const getTableFn = getTable ? getTable : tableByName;
-    const dbInstance = db ? db : new Db();
-
-    // Get all referenced record IDs grouped by table
+    // The referenced ids, grouped by the table each row names
     const recordsToDelete = new Map<string, string[]>();
-
     for (const record of records) {
       const reference = record[columnPropertyName] as Reference<Record>;
       if (!reference?._id || !reference._table) {
@@ -537,17 +564,13 @@ export class DynamicReferenceColumn<T extends Record> extends StringColumn<Refer
       recordsToDelete.get(reference._table)!.push(reference._id);
     }
 
-    // Delete records from each referenced table using Promise.all to properly await all deletions
-    const entries = Array.from(recordsToDelete.entries());
-    console.log(`entries to delete: ${JSON.stringify(entries)}`);
-    for (const [tableName, ids] of entries) {
-      if (ids.length > 0) {
-        const referenceTable = getTableFn(tableName);
-        const qb = new QueryBuilderFactory()
-          .getQueryBuilder(referenceTable)
-          .condition({ field: 'id', operator: 'IN', value: ids });
-        await dbInstance.delete(referenceTable, qb);
-      }
+    // Optional in the hook contract for implementers that need neither; the Db hands both to every hook.
+    for (const [tableName, ids] of Array.from(recordsToDelete.entries())) {
+      const referenceTable = getTable!(tableName);
+      const qb = new QueryBuilderFactory()
+        .getQueryBuilder(referenceTable)
+        .condition({ field: 'id', operator: 'IN', value: ids });
+      await db!.delete(referenceTable, qb);
     }
   }
 }

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,26 +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 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)
-        );
+        await column.beforeDelete(table, columnPropertyName, recordsToDelete, this.getTable, this.newHookDb());
       }
     }
   }
@@ -1163,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/CascadeDeleteTests.ts

@@ -6,6 +6,10 @@ import {
   GroupArr,
   GroupDyn,
   GroupRef,
+  GuardedHolderArr,
+  GuardedHolderDyn,
+  GuardedHolderRef,
+  GuardedMember,
   MemberArr,
   MemberArrRev,
   MemberDyn,
@@ -224,5 +228,91 @@ export const cascadeDeleteTests = (
         expect(missionsAfterPilot.length).toBe(0);
       });
     });
+
+    /**
+     * -------------------- Cascade Delete as system (holder → guarded referenced) --------------------
+     * A system delete's cascade runs with the authority of the write that fired it. The children's
+     * table refuses every non-system query (a scoped table's shape), and the delete runs in a fresh
+     * async context with no session — a background sweep's shape. Before the fix the cascade hooks
+     * ran as a non-system Db, and every case below failed with the guarded table's refusal.
+     */
+    describe('Cascade Delete as system', () => {
+      const systemDb = new Db(driver, undefined, transactionContextFactory, true);
+      const memberTable = cascadeDeleteTestTables.GuardedMember;
+
+      /** A fresh async context with nothing inherited from the test's own — a background sweep's shape. */
+      const inFreshContext = <T>(fn: () => Promise<T>): Promise<T> =>
+        new Promise<T>((resolve, reject) => {
+          setImmediate(() => {
+            fn().then(resolve, reject);
+          });
+        });
+
+      test('ReferenceColumn: a system delete of the holder deletes the guarded referenced record', async () => {
+        const holderTable = cascadeDeleteTestTables.GuardedHolderRef;
+
+        const m = await systemDb.insert(memberTable, { name: 'Gail' });
+        const h = await systemDb.insert(holderTable, {
+          holderName: 'H-Ref',
+          memberRef: new Reference<GuardedMember>(memberTable.name, m.id),
+        });
+
+        const delQb = new QueryBuilder<GuardedHolderRef>(holderTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: h.id,
+        });
+        const deleted = await inFreshContext(() => systemDb.delete(holderTable, delQb));
+        expect(deleted).toBe(1);
+
+        expect(await systemDb.query(memberTable, { id: m.id })).toHaveLength(0);
+      });
+
+      test('ReferenceArrayColumn: a system delete of the holder deletes every guarded referenced record', async () => {
+        const holderTable = cascadeDeleteTestTables.GuardedHolderArr;
+
+        const m1 = await systemDb.insert(memberTable, { name: 'Gus' });
+        const m2 = await systemDb.insert(memberTable, { name: 'Greta' });
+        const m3 = await systemDb.insert(memberTable, { name: 'Glen' });
+        const h = await systemDb.insert(holderTable, {
+          holderName: 'H-Arr',
+          memberRefs: new ReferenceArray<GuardedMember>(memberTable.name, [m1.id, m2.id]),
+        });
+
+        const delQb = new QueryBuilder<GuardedHolderArr>(holderTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: h.id,
+        });
+        const deleted = await inFreshContext(() => systemDb.delete(holderTable, delQb));
+        expect(deleted).toBe(1);
+
+        expect(await systemDb.query(memberTable, { id: m1.id })).toHaveLength(0);
+        expect(await systemDb.query(memberTable, { id: m2.id })).toHaveLength(0);
+        // The unreferenced member stands: the cascade is the stored ids, nothing wider.
+        expect(await systemDb.query(memberTable, { id: m3.id })).toHaveLength(1);
+      });
+
+      test('DynamicReferenceColumn: a system delete of the holder deletes the guarded dynamically referenced record', async () => {
+        const holderTable = cascadeDeleteTestTables.GuardedHolderDyn;
+
+        const m = await systemDb.insert(memberTable, { name: 'Gwen' });
+        const h = await systemDb.insert(holderTable, {
+          holderName: 'H-Dyn',
+          memberDynTableName: memberTable.name,
+          memberDynRef: new Reference<GuardedMember>(memberTable.name, m.id),
+        });
+
+        const delQb = new QueryBuilder<GuardedHolderDyn>(holderTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: h.id,
+        });
+        const deleted = await inFreshContext(() => systemDb.delete(holderTable, delQb));
+        expect(deleted).toBe(1);
+
+        expect(await systemDb.query(memberTable, { id: m.id })).toHaveLength(0);
+      });
+    });
   };
 };