@proteinjs/db 1.25.2 → 1.27.0

package/index.ts

@@ -5,7 +5,9 @@ export * from './src/auth/TableServiceAuth';
 export * from './src/Columns';
 export * from './src/Record';
 export * from './src/reference/ReferenceArray';
+export * from './src/reference/ArrayMembershipOps';
 export * from './src/reference/Reference';
+export * from './src/UpdatePreserving';
 export * from './src/reference/ReferenceCache';
 export * from './src/RecordIterator';
 export * from './src/source/SourceRecord';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.25.2",
+  "version": "1.27.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.4.10",
+    "@proteinjs/db-query": "^1.5.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.0",
-    "@proteinjs/user-auth": "^1.1.15",
+    "@proteinjs/service": "^1.4.1",
+    "@proteinjs/user-auth": "^1.2.0",
     "@proteinjs/util": "^1.6.1",
     "moment": "2.29.4",
     "uuid": "8.3.0"
@@ -65,5 +65,6 @@
     "jest": "29.7.0",
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
-  }
+  },
+  "gitHead": "020e0d6b909cdd60925952aa05c23cfdecd8353d"
 }

package/src/Db.ts

@@ -22,11 +22,15 @@ import { TableServiceAuth } from './auth/TableServiceAuth';
 import { TableWatcherRunner } from './TableWatcherRunner';
 import {
   DefaultTransactionContextFactory,
+  PostCommitHook,
   getDefaultTransactionContextFactory,
+  TransactionContextData,
 } from './transaction/TransactionContextFactory';
 import { isInstanceOf } from '@proteinjs/util';
 import { Reference } from './reference/Reference';
 import { ReferenceArray } from './reference/ReferenceArray';
+import { ArrayMembershipUpdate, applyArrayMembershipOps } from './reference/ArrayMembershipOps';
+import { PreservedPath, overlayPreservedPaths } from './UpdatePreserving';
 
 /** get `Db` if on server, and `DbService` if on browser */
 export const getDb = <R extends Record = Record>() =>
@@ -73,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: {
@@ -93,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 {
@@ -156,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;
   }
@@ -199,11 +198,101 @@ 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;
   }
 
+  /**
+   * Apply commutative membership ops (add/remove/move) to a `ReferenceArrayColumn`
+   * read-modify-write against COMMITTED truth, so concurrent membership writers
+   * converge instead of last-write-wins clobbering each other (the write-side
+   * lost-update class). Self-wraps in a transaction when called outside one; the
+   * driver's abort/retry re-executes the read, so a retried transaction applies
+   * its ops to fresh truth rather than replaying a stale list snapshot.
+   *
+   * Returns the update count (0 when the ops are a no-op against committed truth
+   * 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.transactionContextFactory.getTransactionContext().currentTransaction) {
+      const db = this.newSelfWrapDb();
+      return await db.runTransaction(async () => await db.updateArrayMembership(table, update));
+    }
+
+    const column = (table.columns as any)[update.columnPropertyName];
+    if (!column || column.constructor?.name !== 'ReferenceArrayColumn') {
+      throw new Error(
+        `updateArrayMembership requires a ReferenceArrayColumn; '${update.columnPropertyName}' on table '${table.name}' is not one`
+      );
+    }
+
+    const qb = new QueryBuilderFactory().getQueryBuilder(table);
+    await this.addColumnQueries(table, qb, 'write');
+    qb.select({ fields: ['id', update.columnPropertyName] as any });
+    qb.condition({ field: 'id', operator: '=', value: update.recordId as T[keyof T] });
+    const rows = await this._query(table, qb);
+    if (rows.length === 0) {
+      return 0;
+    }
+
+    const currentRefArray = (rows[0] as any)[update.columnPropertyName] as ReferenceArray<any> | null | undefined;
+    const currentIds = currentRefArray?._ids ?? [];
+    const { ids, changed } = applyArrayMembershipOps(currentIds, update.ops);
+    if (!changed) {
+      return 0;
+    }
+
+    const record: Partial<T> = { id: update.recordId } as Partial<T>;
+    (record as any)[update.columnPropertyName] = new ReferenceArray((column as any).referenceTable, ids);
+    return await this.update(table, record);
+  }
+
+  /**
+   * Update with committed-truth preservation for column sub-paths the writer does
+   * not own (see `UpdatePreserving.ts`). The payload's listed paths are overlaid
+   * with their committed values read inside the same transaction, so this write
+   * commutes with the writers that own those paths (e.g. a structural editor op
+   * writing a JSON object's styling while a debounced text save owns `content`).
+   * 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.transactionContextFactory.getTransactionContext().currentTransaction) {
+      const db = this.newSelfWrapDb();
+      return await db.runTransaction(async () => await db.updatePreserving(table, record, preserve));
+    }
+
+    if (!record.id) {
+      throw new Error(`updatePreserving must be called with a record with an id property`);
+    }
+
+    const applicable = preserve.filter((p) => (record as any)[p.columnPropertyName] !== undefined);
+    if (applicable.length === 0) {
+      return await this.update(table, record);
+    }
+
+    const qb = new QueryBuilderFactory().getQueryBuilder(table);
+    await this.addColumnQueries(table, qb, 'write');
+    qb.select({ fields: ['id', ...applicable.map((p) => p.columnPropertyName)] as any });
+    qb.condition({ field: 'id', operator: '=', value: record.id as T[keyof T] });
+    const rows = await this._query(table, qb);
+    if (rows.length === 0) {
+      return 0;
+    }
+
+    const recordCopy: Partial<T> = Object.assign({}, record);
+    for (const p of applicable) {
+      (recordCopy as any)[p.columnPropertyName] = overlayPreservedPaths(
+        (rows[0] as any)[p.columnPropertyName],
+        (recordCopy as any)[p.columnPropertyName],
+        p.paths,
+        p.whenType
+      );
+    }
+
+    return await this.update(table, recordCopy);
+  }
+
   async delete<T extends R>(table: Table<T>, query: Query<T>): Promise<number> {
     if (!this.runAsSystem) {
       this.auth.canDelete(table);
@@ -223,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);
@@ -443,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))
@@ -486,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'];
   }
 
@@ -515,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:
    *
@@ -537,22 +632,105 @@ 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.`);
     }
 
-    return await this.dbDriver.runTransaction(async (transaction) => {
-      this.currentTransaction = transaction;
-
+    // Reassigned fresh per driver attempt: drivers may retry `fn` on transient aborts (Spanner's
+    // runTransactionAsync does), and hooks queued by a discarded attempt must not survive into
+    // 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) => {
+      // 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 () => {
-          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;
       }
     });
+
+    // COMMIT BOUNDARY: the driver resolves only after the transaction is durably committed (and
+    // rejects on rollback, in which case the queue above is never drained). Hook failures are
+    // logged, not thrown — the write already committed, and surfacing a hook error as a
+    // transaction failure would report a durable write as failed.
+    for (const postCommitHook of postCommitHooks) {
+      try {
+        await postCommitHook();
+      } catch (error: any) {
+        this.logger.error({ message: `Post-commit hook failed`, error });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Run `hook` once the write unit currently executing is durably committed.
+   *
+   * - Inside a `runTransaction` scope: the hook is queued on the ambient transaction context and
+   *   runs after the transaction COMMITS. Hooks never run on rollback.
+   * - Outside a transaction: every DML statement auto-commits when it resolves, so the hook runs
+   *   (awaited) immediately. Callers are responsible for invoking this only from points where
+   *   the triggering statement has already executed — e.g. `after*` table watchers, never
+   *   `before*` ones.
+   *
+   * For side effects that must observe committed truth — e.g. socket notifications that trigger
+   * client refetches: a pre-commit emission lets a client refetch read pre-commit rows and
+   * "resurrect" state the transaction is deleting.
+   */
+  async runAfterCommit(hook: PostCommitHook): Promise<void> {
+    const transactionContext = this.transactionContextFactory.getTransactionContext();
+    if (transactionContext.currentTransaction) {
+      if (!transactionContext.postCommitHooks) {
+        // runTransaction is the only opener of transaction scopes and always seeds the queue —
+        // an active transaction without one means a second scope owner appeared. Fail loudly
+        // rather than run the hook at (wrong) pre-commit time.
+        throw new Error(
+          `Active transaction context has no post-commit hook queue. Transaction scopes must be opened via Db.runTransaction.`
+        );
+      }
+      transactionContext.postCommitHooks.push(hook);
+      return;
+    }
+
+    await hook();
+  }
+
+  /**
+   * A fresh instance for self-wrapping RMW verbs (`updateArrayMembership`, `updatePreserving`)
+   * in a transaction. `runTransaction` carries the open transaction as INSTANCE state, and these
+   * verbs also serve the `DbService` RPC path, where one long-lived Db instance handles
+   * concurrent requests — self-wrapping on `this` would leak one request's transaction into
+   * another's ops (or spuriously reject it as a nested transaction). Same driver/tables/system
+   * mode; only the transaction state is isolated.
+   */
+  private newSelfWrapDb(): Db<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

package/src/MigrationRunner.ts

@@ -13,6 +13,12 @@ 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.
+    auth: {
+      roles: ['admin'],
+    },
     doNotAwait: true,
   };
 

package/src/UpdatePreserving.ts

@@ -0,0 +1,89 @@
+/**
+ * Support for `Db.updatePreserving` / `Transaction.updatePreserving`: an update
+ * whose payload carries a column value the writer only PARTIALLY owns — the
+ * listed sub-paths belong to other writers, so their committed values are
+ * preserved (overlaid into the payload read-modify-write) instead of being
+ * clobbered by whatever stale copy the writer's snapshot happened to hold.
+ *
+ * The motivating case: a structural editor operation changes non-text fields of
+ * a JSON object column (styling, child overrides) while a debounced text save
+ * owns the object's text content. The structural payload's `content` is stale
+ * by construction (text syncs into the record at save time, not per keystroke);
+ * writing it would erase a concurrently committed text save. Preserving
+ * `content` from the committed row makes the two writers commute.
+ */
+
+export type PreservedPath = {
+  /** Property name of the column whose payload value should have paths preserved. */
+  columnPropertyName: string;
+  /** Dot-separated paths inside the column value (plain-JSON columns only). */
+  paths: string[];
+  /**
+   * Only overlay a committed value whose `typeof` matches. Guards shape
+   * transitions: when the op legitimately changes the column's SHAPE (e.g. a
+   * text object becoming a composite wrapper), a committed value of a
+   * different type must not be dragged into the new shape.
+   */
+  whenType?: 'string' | 'number' | 'boolean' | 'object';
+};
+
+/**
+ * Overlay committed values at `paths` into a clone of `incomingValue`.
+ * Pure: returns the (possibly cloned) value to write. Only plain-JSON values
+ * are supported (the clone is JSON-based).
+ */
+export function overlayPreservedPaths(
+  committedValue: unknown,
+  incomingValue: unknown,
+  paths: string[],
+  whenType?: PreservedPath['whenType']
+): unknown {
+  if (incomingValue == null || committedValue == null) {
+    return incomingValue;
+  }
+
+  let result: unknown | undefined;
+  for (const path of paths) {
+    const committedAtPath = deepGet(committedValue, path);
+    if (committedAtPath === undefined) {
+      continue;
+    }
+    if (whenType && typeof committedAtPath !== whenType) {
+      continue;
+    }
+    if (deepGet(result ?? incomingValue, path) === committedAtPath) {
+      continue;
+    }
+    if (result === undefined) {
+      result = JSON.parse(JSON.stringify(incomingValue));
+    }
+    deepSet(result, path, committedAtPath);
+  }
+
+  return result === undefined ? incomingValue : result;
+}
+
+function deepGet(value: unknown, path: string): unknown {
+  let current: any = value;
+  for (const key of path.split('.')) {
+    if (current == null || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+function deepSet(value: unknown, path: string, pathValue: unknown): void {
+  const keys = path.split('.');
+  let current: any = value;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const next = current?.[keys[i]];
+    if (next == null || typeof next !== 'object') {
+      // The incoming value doesn't have this path's parent — nothing to preserve into.
+      return;
+    }
+    current = next;
+  }
+  current[keys[keys.length - 1]] = pathValue;
+}

package/src/auth/TableAuth.ts

@@ -20,6 +20,19 @@ export type TableOperationsAuth = {
   delete?: Identity;
 };
 
+/**
+ * A table-auth denial. The message names the table and operation and is safe to show the caller
+ * (it only echoes what they asked for). Name-tagged rather than relying on instanceof — the
+ * prototype chain is unreliable across package compile targets (same reason ServiceRouter's
+ * isServiceError checks `name`).
+ */
+export class TableAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TableAuthError';
+  }
+}
+
 /**
  * Util to check which table operations a user can perform
  */
@@ -46,25 +59,25 @@ export class TableAuth {
 
   canQuery(table: Table<any>, api: 'db' | 'service' = 'db'): void {
     if (!this.canAccess(table, api, 'query')) {
-      throw new Error(`User is not authorized to query table: ${table.name}`);
+      throw new TableAuthError(`User is not authorized to query table: ${table.name}`);
     }
   }
 
   canInsert(table: Table<any>, api: 'db' | 'service' = 'db'): void {
     if (!this.canAccess(table, api, 'insert')) {
-      throw new Error(`User is not authorized to insert records into table: ${table.name}`);
+      throw new TableAuthError(`User is not authorized to insert records into table: ${table.name}`);
     }
   }
 
   canUpdate(table: Table<any>, api: 'db' | 'service' = 'db'): void {
     if (!this.canAccess(table, api, 'update')) {
-      throw new Error(`User is not authorized to update records in table: ${table.name}`);
+      throw new TableAuthError(`User is not authorized to update records in table: ${table.name}`);
     }
   }
 
   canDelete(table: Table<any>, api: 'db' | 'service' = 'db'): void {
     if (!this.canAccess(table, api, 'delete')) {
-      throw new Error(`User is not authorized to delete records from table: ${table.name}`);
+      throw new TableAuthError(`User is not authorized to delete records from table: ${table.name}`);
     }
   }
 }

package/src/auth/TableServiceAuth.ts

@@ -1,7 +1,7 @@
 import { Logger } from '@proteinjs/logger';
 import { ServiceError } from '@proteinjs/service';
 import { Table, isTable } from '../Table';
-import { TableAuth } from './TableAuth';
+import { TableAuth, TableAuthError } from './TableAuth';
 
 export class TableServiceAuth {
   private logger = new Logger({ name: this.constructor.name });
@@ -22,6 +22,15 @@ export class TableServiceAuth {
       } else if (methodName === 'update') {
         tableAuth.canUpdate(table as Table<any>, 'service');
         this.checkServiceProtectedColumns(table as Table<any>, args[1]);
+      } else if (methodName === 'updateArrayMembership') {
+        // An update in RMW clothing: gated exactly like `update`. Row visibility is enforced
+        // inside the operation itself — scoped/column query injection runs on the server-side
+        // read-modify-write, so a caller can only touch rows they could already update.
+        tableAuth.canUpdate(table as Table<any>, 'service');
+        this.checkArrayMembershipProtectedColumn(table as Table<any>, args[1]);
+      } else if (methodName === 'updatePreserving') {
+        tableAuth.canUpdate(table as Table<any>, 'service');
+        this.checkServiceProtectedColumns(table as Table<any>, args[1]);
       } else if (methodName === 'delete') {
         tableAuth.canDelete(table as Table<any>, 'service');
       } else {
@@ -35,6 +44,13 @@ export class TableServiceAuth {
       if (error?.name === 'ServiceError') {
         throw error;
       }
+      // A table-auth denial is equally client-safe (it only names the table/operation the caller
+      // asked for). Cross the wire verbatim so the caller sees "not authorized to query table:
+      // session" rather than the generic run-service denial — a denied query must be
+      // distinguishable from an empty one at the surface that shows it.
+      if (error?.name === 'TableAuthError') {
+        throw new ServiceError(error.message);
+      }
       this.logger.error({ message: `Failed evaluating auth for method: ${methodName}`, error });
       return false;
     }
@@ -61,4 +77,23 @@ export class TableServiceAuth {
       }
     }
   }
+
+  /**
+   * `updateArrayMembership`'s payload names its target column (`columnPropertyName`) instead of
+   * carrying record fields, so the record-shaped protected-column check above can't see the
+   * write. Membership ops always SET real membership — there is no null-clearing form — so
+   * targeting a protected column is rejected outright.
+   */
+  private checkArrayMembershipProtectedColumn(table: Table<any>, update: any): void {
+    const protectedColumns: string[] | undefined = table.auth?.serviceProtectedColumns;
+    if (!protectedColumns?.length || !update || typeof update !== 'object') {
+      return;
+    }
+
+    if (protectedColumns.includes(update.columnPropertyName)) {
+      throw new ServiceError(
+        `Column '${update.columnPropertyName}' cannot be written via the db service on table: ${table.name}`
+      );
+    }
+  }
 }