@proteinjs/db 1.25.2 → 1.26.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.26.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"

package/src/Db.ts

@@ -22,11 +22,14 @@ import { TableServiceAuth } from './auth/TableServiceAuth';
 import { TableWatcherRunner } from './TableWatcherRunner';
 import {
   DefaultTransactionContextFactory,
+  PostCommitHook,
   getDefaultTransactionContextFactory,
 } 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>() =>
@@ -204,6 +207,96 @@ export class Db<R extends Record = Record> implements DbService<R> {
     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.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.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);
@@ -541,11 +634,19 @@ export class Db<R extends Record = Record> implements DbService<R> {
       throw new Error(`Nested transactions are not supported. A transaction is already running on this Db instance.`);
     }
 
-    return await this.dbDriver.runTransaction(async (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) => {
       this.currentTransaction = transaction;
+      postCommitHooks = [];
 
       try {
         return await this.transactionContextFactory.runInContext(transaction, async () => {
+          // Seed the post-commit hook queue on the ambient context so every Db instance created
+          // inside this transaction shares it (see runAfterCommit).
+          this.transactionContextFactory.getTransactionContext().postCommitHooks = postCommitHooks;
           const result = await fn();
           return result;
         });
@@ -553,6 +654,64 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.currentTransaction = undefined;
       }
     });
+
+    // 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);
   }
 
   // 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}`
+      );
+    }
+  }
 }

package/src/reference/ArrayMembershipOps.ts

@@ -0,0 +1,155 @@
+/**
+ * Commutative membership operations for `ReferenceArrayColumn` values.
+ *
+ * Motivation (the write-side lost-update class): a client writer that persists a
+ * reference-array column as a FULL ID LIST snapshots its in-memory state — when two
+ * such writes race (fire-and-forget issuance + driver-level abort/retry can commit
+ * an earlier-issued transaction later), the last commit wins wholesale and erases
+ * the other writer's committed membership change. Expressing membership changes as
+ * ops (add/remove/move) applied read-modify-write against COMMITTED truth inside a
+ * transaction makes concurrent writes converge instead of clobber:
+ * `remove(x)` + `remove(y)` in any commit order removes both; `add(x)` + `add(y)`
+ * keeps both.
+ *
+ * `applyArrayMembershipOps` is the single applier used by `Db.updateArrayMembership`
+ * (server-side RMW) — and by any test that needs the committed rule as importable
+ * truth. `computeArrayMembershipOps` derives the minimal op set from a
+ * before/after id-list pair, for callers whose op layer only knows list states.
+ */
+
+export type ArrayMembershipOp =
+  /** Insert `id` after `afterId` (`null` = at the head). If `id` is already present it is repositioned. */
+  | { op: 'add'; id: string; afterId: string | null }
+  /** Remove `id`. No-op when absent. */
+  | { op: 'remove'; id: string }
+  /** Reposition `id` after `afterId` (`null` = at the head). No-op when `id` is absent (a concurrent remove wins). */
+  | { op: 'move'; id: string; afterId: string | null };
+
+export type ArrayMembershipUpdate = {
+  /** The record whose array column is being updated. */
+  recordId: string;
+  /** Property name of the `ReferenceArrayColumn` on the table. */
+  columnPropertyName: string;
+  /** Ops applied in order against the committed id list. */
+  ops: ArrayMembershipOp[];
+};
+
+/**
+ * Apply membership ops to an id list. Pure; returns a new array and whether it
+ * differs from the input.
+ *
+ * Anchor resolution (`afterId`) against a diverged committed list is
+ * convergence-by-anchor: a missing anchor appends at the end (the anchor was
+ * concurrently removed — the element still lands in the list, order is
+ * best-effort), `afterId: null` inserts at the head.
+ */
+export function applyArrayMembershipOps(
+  currentIds: string[],
+  ops: ArrayMembershipOp[]
+): { ids: string[]; changed: boolean } {
+  const ids = [...currentIds];
+  for (const op of ops) {
+    if (op.op === 'remove') {
+      const idx = ids.indexOf(op.id);
+      if (idx !== -1) {
+        ids.splice(idx, 1);
+      }
+      continue;
+    }
+
+    if (op.op === 'move' && ids.indexOf(op.id) === -1) {
+      // Move of a concurrently-removed element: the remove intent wins.
+      continue;
+    }
+
+    // add (insert or reposition) and move (reposition) share placement logic.
+    const existingIdx = ids.indexOf(op.id);
+    if (existingIdx !== -1) {
+      ids.splice(existingIdx, 1);
+    }
+    if (op.afterId === null) {
+      ids.unshift(op.id);
+    } else {
+      const anchorIdx = ids.indexOf(op.afterId);
+      if (anchorIdx === -1) {
+        ids.push(op.id);
+      } else {
+        ids.splice(anchorIdx + 1, 0, op.id);
+      }
+    }
+  }
+
+  const changed = ids.length !== currentIds.length || ids.some((id, i) => id !== currentIds[i]);
+  return { ids, changed };
+}
+
+/**
+ * Compute the op set that transforms `beforeIds` into `afterIds`.
+ *
+ * Removes first, then a single walk of `afterIds` emitting `add` for new
+ * elements and `move` for surviving elements whose relative order changed.
+ * Moves are minimized via the longest increasing subsequence of surviving
+ * elements (elements on the LIS stay put; everything else moves). Replaying
+ * the result on `beforeIds` yields exactly `afterIds`; replaying it on a
+ * DIVERGED committed list converges by anchor instead of clobbering.
+ */
+export function computeArrayMembershipOps(beforeIds: string[], afterIds: string[]): ArrayMembershipOp[] {
+  const before = beforeIds;
+  const after = afterIds;
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+
+  const ops: ArrayMembershipOp[] = [];
+  for (const id of before) {
+    if (!afterSet.has(id)) {
+      ops.push({ op: 'remove', id });
+    }
+  }
+
+  // Surviving elements, in after-order, with their positions in `before`.
+  const surviving = after.filter((id) => beforeSet.has(id));
+  const beforeIndex = new Map(before.map((id, i) => [id, i] as const));
+  const stable = longestIncreasingSubsequence(surviving.map((id) => beforeIndex.get(id) as number));
+  const stableIds = new Set(stable.map((i) => surviving[i]));
+
+  for (let i = 0; i < after.length; i++) {
+    const id = after[i];
+    const afterId = i === 0 ? null : after[i - 1];
+    if (!beforeSet.has(id)) {
+      ops.push({ op: 'add', id, afterId });
+    } else if (!stableIds.has(id)) {
+      ops.push({ op: 'move', id, afterId });
+    }
+  }
+
+  return ops;
+}
+
+/** Indices (into the input array) of one longest strictly-increasing subsequence. */
+function longestIncreasingSubsequence(values: number[]): number[] {
+  const tailIndices: number[] = [];
+  const prev: number[] = new Array(values.length).fill(-1);
+  for (let i = 0; i < values.length; i++) {
+    let lo = 0;
+    let hi = tailIndices.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (values[tailIndices[mid]] < values[i]) {
+        lo = mid + 1;
+      } else {
+        hi = mid;
+      }
+    }
+    if (lo > 0) {
+      prev[i] = tailIndices[lo - 1];
+    }
+    tailIndices[lo] = i;
+  }
+  const result: number[] = [];
+  let k = tailIndices.length > 0 ? tailIndices[tailIndices.length - 1] : -1;
+  while (k !== -1) {
+    result.unshift(k);
+    k = prev[k];
+  }
+  return result;
+}

package/src/services/DbService.ts

@@ -2,6 +2,8 @@ import { Service, serviceFactory } from '@proteinjs/service';
 import { Table } from '../Table';
 import { Record } from '../Record';
 import { QueryBuilder } from '@proteinjs/db-query';
+import { ArrayMembershipUpdate } from '../reference/ArrayMembershipOps';
+import { PreservedPath } from '../UpdatePreserving';
 
 export const getDbService = serviceFactory<DbService>('@proteinjs/db/DbService');
 
@@ -22,6 +24,42 @@ export interface DbService<R extends Record = Record> extends Service {
   get<T extends R>(table: Table<T>, query: Query<T>, options?: QueryOptions<T>): Promise<T>;
   insert<T extends R>(table: Table<T>, record: Omit<T, keyof R>): Promise<T>;
   update<T extends R>(table: Table<T>, record: Partial<T>, query?: Query<T>): Promise<number>;
+  /**
+   * Apply commutative membership ops (add/remove/move) to a `ReferenceArrayColumn`,
+   * read-modify-write against COMMITTED truth inside a server-side transaction, so concurrent
+   * membership writers converge instead of last-write-wins clobbering each other (the
+   * write-side lost-update class).
+   *
+   * Use when the column has a NAMED multi-writer split — more than one writer changes the
+   * list's membership concurrently. Use plain `update` when the column has a single writer,
+   * or when the intent genuinely is wholesale assignment of the entire list.
+   *
+   * Authorization is identical to `update`: the table's `update` grant gates the call, and
+   * scoped/column query injection applies to the server-side read-modify-write — a scoped
+   * caller can only touch rows they could already update (an out-of-scope record behaves as
+   * nonexistent: returns 0).
+   *
+   * @returns the update count (0 when the ops are a no-op against committed truth, or the
+   * record does not exist / is not visible to the caller)
+   */
+  updateArrayMembership<T extends R>(table: Table<T>, update: ArrayMembershipUpdate): Promise<number>;
+  /**
+   * Update with committed-truth preservation for column sub-paths the writer does not own:
+   * the payload's listed paths are overlaid with their committed values (read in the same
+   * server-side transaction), so this write commutes with the writers that own those paths.
+   * Plain-JSON columns only.
+   *
+   * Use when ownership of a column's VALUE is split across writers by sub-path (e.g. a
+   * structural editor op writes an object's styling while a debounced text save owns
+   * `content` — the structural payload's `content` is stale by construction). Use plain
+   * `update` when the writer owns the whole value it writes.
+   *
+   * Authorization is identical to `update` (update grant, scoped/column query injection,
+   * `serviceProtectedColumns` enforced on the payload).
+   *
+   * @returns the update count (0 when the record does not exist / is not visible to the caller)
+   */
+  updatePreserving<T extends R>(table: Table<T>, record: Partial<T>, preserve: PreservedPath[]): Promise<number>;
   delete<T extends R>(table: Table<T>, query: Query<T>): Promise<number>;
   query<T extends R>(table: Table<T>, query: Query<T>, options?: QueryOptions<T>): Promise<T[]>;
   getRowCount<T extends R>(table: Table<T>, query?: Query<T>): Promise<number>;