@proteinjs/db 1.25.2 → 1.27.0

package/dist/generated/test/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../generated/test/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;;;;;;;;;;;;;;AAEpC,+BAA6B;AAC7B,6BAA2B;AAC3B,iCAA+B;AAC/B,iCAA+B;AAC/B,iCAA+B;AAC/B,8BAA4B;AAC5B,gCAA8B;AAC9B,2BAAyB;AACzB,kBAAgB;AAChB,gBAAc;AAGd,4BAA4B;AAE5B,IAAM,WAAW,GAAG,uj0FAAuj0F,CAAC;AAG5k0F,4BAA4B;AAE5B,0FAAgF;AAChF,yCAAwC;AACxC,0FAA+E;AAC/E,0FAAgF;AAChF,0FAA+E;AAC/E,0FAAgF;AAChF,0FAA+E;AAC/E,0FAA2E;AAC3E,0FAA8E;AAC9E,0FAAmF;AACnF,2FAAkF;AAClF,2FAA6E;AAC7E,2FAA2E;AAC3E,sFAAyE;AACzE,wEAA0E;AAC1E,wEAA8E;AAC9E,4GAAiG;AACjG,4GAAwF;AACxF,4GAAwF;AACxF,4GAA8F;AAC9F,wFAA8E;AAC9E,wFAAqF;AACrF,wFAAiF;AACjF,sFAA4F;AAC5F,sFAAgG;AAChG,mCAAkC;AAClC,iEAAgE;AAChE,6DAA4D;AAC5D,2FAA0F;AAC1F,iFAAgF;AAChF,yEAAwE;AACxE,2DAA0D;AAC1D,qEAAoE;AACpE,0EAAyE;AACzE,kEAAiE;AACjE,6EAA4E;AAE5E,IAAM,WAAW,GAAG;IACnB,8BAA8B,EAAE,wCAAc;IAC9C,qBAAqB,EAAE,aAAK;IAC5B,6BAA6B,EAAE,uCAAa;IAC5C,8BAA8B,EAAE,wCAAc;IAC9C,6BAA6B,EAAE,uCAAa;IAC5C,8BAA8B,EAAE,wCAAc;IAC9C,6BAA6B,EAAE,uCAAa;IAC5C,yBAAyB,EAAE,mCAAS;IACpC,4BAA4B,EAAE,sCAAY;IAC1C,iCAAiC,EAAE,2CAAiB;IACpD,gCAAgC,EAAE,2CAAgB;IAClD,2BAA2B,EAAE,sCAAW;IACxC,yBAAyB,EAAE,oCAAS;IACpC,yBAAyB,EAAE,iCAAS;IACpC,iCAAiC,EAAE,kCAAiB;IACpD,qCAAqC,EAAE,sCAAqB;IAC5D,sCAAsC,EAAE,yDAAsB;IAC9D,6BAA6B,EAAE,gDAAa;IAC5C,6BAA6B,EAAE,gDAAa;IAC5C,mCAAmC,EAAE,sDAAmB;IACxD,6BAA6B,EAAE,sCAAa;IAC5C,oCAAoC,EAAE,6CAAoB;IAC1D,gCAAgC,EAAE,yCAAgB;IAClD,4CAA4C,EAAE,oDAA4B;IAC1E,gDAAgD,EAAE,wDAAgC;IAClF,kBAAkB,EAAE,OAAE;IACtB,iCAAiC,EAAE,qCAAiB;IACpD,+BAA+B,EAAE,iCAAe;IAChD,wCAAwC,EAAE,mDAAwB;IAClE,mCAAmC,EAAE,yCAAmB;IACxD,+BAA+B,EAAE,iCAAe;IAChD,yBAAyB,EAAE,qBAAS;IACpC,8BAA8B,EAAE,+BAAc;IAC9C,kCAAkC,EAAE,uCAAkB;IACtD,8BAA8B,EAAE,+BAAc;IAC9C,iCAAiC,EAAE,qCAAiB;CACpD,CAAC;AAGF,kCAAkC;AAElC,oDAAyD;AACzD,6BAAgB,CAAC,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAGjD,mDAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../generated/test/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;;;;;;;;;;;;;;AAEpC,+BAA6B;AAC7B,6BAA2B;AAC3B,iCAA+B;AAC/B,iCAA+B;AAC/B,iCAA+B;AAC/B,8BAA4B;AAC5B,gCAA8B;AAC9B,2BAAyB;AACzB,kBAAgB;AAChB,gBAAc;AAGd,4BAA4B;AAE5B,IAAM,WAAW,GAAG,gj8FAAgj8F,CAAC;AAGrk8F,4BAA4B;AAE5B,0FAAgF;AAChF,yCAAwC;AACxC,0FAA+E;AAC/E,0FAAgF;AAChF,0FAA+E;AAC/E,0FAAgF;AAChF,0FAA+E;AAC/E,0FAA2E;AAC3E,0FAA8E;AAC9E,0FAAmF;AACnF,2FAAkF;AAClF,2FAA6E;AAC7E,2FAA2E;AAC3E,sFAAyE;AACzE,wEAA0E;AAC1E,wEAA8E;AAC9E,4GAAiG;AACjG,4GAAwF;AACxF,4GAAwF;AACxF,4GAA8F;AAC9F,wFAA8E;AAC9E,wFAAqF;AACrF,wFAAiF;AACjF,sFAA4F;AAC5F,sFAAgG;AAChG,mCAAkC;AAClC,iEAAgE;AAChE,6DAA4D;AAC5D,2DAA0D;AAC1D,qEAAoE;AACpE,2FAA0F;AAC1F,iFAAgF;AAChF,yEAAwE;AACxE,0EAAyE;AACzE,kEAAiE;AACjE,6EAA4E;AAE5E,IAAM,WAAW,GAAG;IACnB,8BAA8B,EAAE,wCAAc;IAC9C,qBAAqB,EAAE,aAAK;IAC5B,6BAA6B,EAAE,uCAAa;IAC5C,8BAA8B,EAAE,wCAAc;IAC9C,6BAA6B,EAAE,uCAAa;IAC5C,8BAA8B,EAAE,wCAAc;IAC9C,6BAA6B,EAAE,uCAAa;IAC5C,yBAAyB,EAAE,mCAAS;IACpC,4BAA4B,EAAE,sCAAY;IAC1C,iCAAiC,EAAE,2CAAiB;IACpD,gCAAgC,EAAE,2CAAgB;IAClD,2BAA2B,EAAE,sCAAW;IACxC,yBAAyB,EAAE,oCAAS;IACpC,yBAAyB,EAAE,iCAAS;IACpC,iCAAiC,EAAE,kCAAiB;IACpD,qCAAqC,EAAE,sCAAqB;IAC5D,sCAAsC,EAAE,yDAAsB;IAC9D,6BAA6B,EAAE,gDAAa;IAC5C,6BAA6B,EAAE,gDAAa;IAC5C,mCAAmC,EAAE,sDAAmB;IACxD,6BAA6B,EAAE,sCAAa;IAC5C,oCAAoC,EAAE,6CAAoB;IAC1D,gCAAgC,EAAE,yCAAgB;IAClD,4CAA4C,EAAE,oDAA4B;IAC1E,gDAAgD,EAAE,wDAAgC;IAClF,kBAAkB,EAAE,OAAE;IACtB,iCAAiC,EAAE,qCAAiB;IACpD,+BAA+B,EAAE,iCAAe;IAChD,yBAAyB,EAAE,qBAAS;IACpC,8BAA8B,EAAE,+BAAc;IAC9C,wCAAwC,EAAE,mDAAwB;IAClE,mCAAmC,EAAE,yCAAmB;IACxD,+BAA+B,EAAE,iCAAe;IAChD,kCAAkC,EAAE,uCAAkB;IACtD,8BAA8B,EAAE,+BAAc;IAC9C,iCAAiC,EAAE,qCAAiB;CACpD,CAAC;AAGF,kCAAkC;AAElC,oDAAyD;AACzD,6BAAgB,CAAC,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAGjD,mDAAiC"}

package/dist/index.d.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/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,6CAA6C,CAAC;AAE5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAE1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AAExD,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,6CAA6C,CAAC;AAE5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAE1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AAExD,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -21,7 +21,9 @@ __exportStar(require("./src/auth/TableServiceAuth"), exports);
 __exportStar(require("./src/Columns"), exports);
 __exportStar(require("./src/Record"), exports);
 __exportStar(require("./src/reference/ReferenceArray"), exports);
+__exportStar(require("./src/reference/ArrayMembershipOps"), exports);
 __exportStar(require("./src/reference/Reference"), exports);
+__exportStar(require("./src/UpdatePreserving"), exports);
 __exportStar(require("./src/reference/ReferenceCache"), exports);
 __exportStar(require("./src/RecordIterator"), exports);
 __exportStar(require("./src/source/SourceRecord"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B;AAC5B,uDAAqC;AACrC,8DAA4C;AAC5C,gDAA8B;AAC9B,+CAA6B;AAC7B,iEAA+C;AAC/C,4DAA0C;AAC1C,iEAA+C;AAC/C,uDAAqC;AACrC,4DAA0C;AAC1C,4DAA0C;AAC1C,qDAAmC;AACnC,gEAA8C;AAC9C,sEAAoD;AACpD,8EAA4D;AAE5D,gEAA8C;AAC9C,8DAA4C;AAC5C,4DAA0C;AAE1C,sDAAoC;AACpC,8DAA4C;AAE5C,2DAAyC;AACzC,wEAAsD;AACtD,0EAAwD;AAExD,sDAAoC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B;AAC5B,uDAAqC;AACrC,8DAA4C;AAC5C,gDAA8B;AAC9B,+CAA6B;AAC7B,iEAA+C;AAC/C,qEAAmD;AACnD,4DAA0C;AAC1C,yDAAuC;AACvC,iEAA+C;AAC/C,uDAAqC;AACrC,4DAA0C;AAC1C,4DAA0C;AAC1C,qDAAmC;AACnC,gEAA8C;AAC9C,sEAAoD;AACpD,8EAA4D;AAE5D,gEAA8C;AAC9C,8DAA4C;AAC5C,4DAA0C;AAE1C,sDAAoC;AACpC,8DAA4C;AAE5C,2DAAyC;AACzC,wEAAsD;AACtD,0EAAwD;AAExD,sDAAoC"}

package/dist/src/Db.d.ts

@@ -5,7 +5,9 @@ import { Table } from './Table';
 import { Record, SerializedRecord } from './Record';
 import { ParameterizationConfig, Statement } from '@proteinjs/db-query';
 import { TableManager } from './schema/TableManager';
-import { DefaultTransactionContextFactory } from './transaction/TransactionContextFactory';
+import { DefaultTransactionContextFactory, PostCommitHook } from './transaction/TransactionContextFactory';
+import { ArrayMembershipUpdate } from './reference/ArrayMembershipOps';
+import { PreservedPath } from './UpdatePreserving';
 /** get `Db` if on server, and `DbService` if on browser */
 export declare const getDb: <R extends Record = Record>() => Db<R>;
 export declare const getDbAsSystem: <R extends Record = Record>() => Db<R>;
@@ -40,7 +42,6 @@ export declare class Db<R extends Record = Record> implements DbService<R> {
     private statementConfigFactory;
     private auth;
     private tableWatcherRunner;
-    private currentTransaction?;
     private transactionContextFactory;
     serviceMetadata: Service['serviceMetadata'];
     constructor(dbDriver?: DbDriver, getTable?: (tableName: string) => Table<any>, transactionContextFactory?: DefaultTransactionContextFactory, runAsSystem?: boolean);
@@ -51,6 +52,27 @@ export declare class Db<R extends Record = Record> implements DbService<R> {
     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, 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).
+     */
+    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 (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.
+     */
+    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>;
     private runColumnBeforeDeletes;
     private runCascadeDeletions;
@@ -79,13 +101,19 @@ export declare 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:
      *
@@ -101,6 +129,38 @@ export declare class Db<R extends Record = Record> implements DbService<R> {
      * ```
      */
     runTransaction<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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.
+     */
+    runAfterCommit(hook: PostCommitHook): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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;
     private chunk;
 }
 //# sourceMappingURL=Db.d.ts.map

package/dist/src/Db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Db.d.ts","sourceRoot":"","sources":["../../src/Db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Db.d.ts","sourceRoot":"","sources":["../../src/Db.ts"],"names":[],"mappings":"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"}

package/dist/src/Db.js

@@ -35,6 +35,15 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Db = exports.getDbAsSystem = exports.getDb = void 0;
 var DbService_1 = require("./services/DbService");
@@ -53,6 +62,8 @@ var TransactionContextFactory_1 = require("./transaction/TransactionContextFacto
 var util_1 = require("@proteinjs/util");
 var Reference_1 = require("./reference/Reference");
 var ReferenceArray_1 = require("./reference/ReferenceArray");
+var ArrayMembershipOps_1 = require("./reference/ArrayMembershipOps");
+var UpdatePreserving_1 = require("./UpdatePreserving");
 /** get `Db` if on server, and `DbService` if on browser */
 var getDb = function () {
     return typeof self === 'undefined' ? new Db() : (0, DbService_1.getDbService)();
@@ -81,10 +92,6 @@ var Db = /** @class */ (function () {
         this.transactionContextFactory = transactionContextFactory
             ? transactionContextFactory
             : this.getDefaultTransactionContextFactory();
-        var transactionContext = this.transactionContextFactory.getTransactionContext();
-        if (transactionContext.currentTransaction) {
-            this.currentTransaction = transactionContext.currentTransaction;
-        }
     }
     Db.getDefaultDbDriver = function () {
         if (!Db.defaultDbDriver) {
@@ -168,7 +175,7 @@ var Db = /** @class */ (function () {
                         generateInsert = function (config) {
                             return new db_query_1.StatementFactory().insert(table.name, serializedRecord, _this.statementConfigFactory.getStatementConfig(config));
                         };
-                        return [4 /*yield*/, this.dbDriver.runDml(generateInsert, this.currentTransaction)];
+                        return [4 /*yield*/, this.dbDriver.runDml(generateInsert, this.transactionForDriver())];
                     case 5:
                         _a.sent();
                         return [4 /*yield*/, this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy)];
@@ -225,7 +232,7 @@ var Db = /** @class */ (function () {
                         generateUpdate = function (config) {
                             return new db_query_1.StatementFactory().update(table.name, serializedRecord, qb, _this.statementConfigFactory.getStatementConfig(config));
                         };
-                        return [4 /*yield*/, this.dbDriver.runDml(generateUpdate, this.currentTransaction)];
+                        return [4 /*yield*/, this.dbDriver.runDml(generateUpdate, this.transactionForDriver())];
                     case 5:
                         recordUpdateCount = _b.sent();
                         return [4 /*yield*/, this.tableWatcherRunner.runAfterUpdateTableWatchers(table, recordUpdateCount, recordCopy, qb)];
@@ -236,6 +243,121 @@ var Db = /** @class */ (function () {
             });
         });
     };
+    /**
+     * 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).
+     */
+    Db.prototype.updateArrayMembership = function (table, update) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function () {
+            var db_1, column, qb, rows, currentRefArray, currentIds, _c, ids, changed, record;
+            var _this = this;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        if (!!this.transactionContextFactory.getTransactionContext().currentTransaction) return [3 /*break*/, 2];
+                        db_1 = this.newSelfWrapDb();
+                        return [4 /*yield*/, db_1.runTransaction(function () { return __awaiter(_this, void 0, void 0, function () { return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0: return [4 /*yield*/, db_1.updateArrayMembership(table, update)];
+                                    case 1: return [2 /*return*/, _a.sent()];
+                                }
+                            }); }); })];
+                    case 1: return [2 /*return*/, _d.sent()];
+                    case 2:
+                        column = table.columns[update.columnPropertyName];
+                        if (!column || ((_a = column.constructor) === null || _a === void 0 ? void 0 : _a.name) !== 'ReferenceArrayColumn') {
+                            throw new Error("updateArrayMembership requires a ReferenceArrayColumn; '".concat(update.columnPropertyName, "' on table '").concat(table.name, "' is not one"));
+                        }
+                        qb = new QueryBuilderFactory_1.QueryBuilderFactory().getQueryBuilder(table);
+                        return [4 /*yield*/, this.addColumnQueries(table, qb, 'write')];
+                    case 3:
+                        _d.sent();
+                        qb.select({ fields: ['id', update.columnPropertyName] });
+                        qb.condition({ field: 'id', operator: '=', value: update.recordId });
+                        return [4 /*yield*/, this._query(table, qb)];
+                    case 4:
+                        rows = _d.sent();
+                        if (rows.length === 0) {
+                            return [2 /*return*/, 0];
+                        }
+                        currentRefArray = rows[0][update.columnPropertyName];
+                        currentIds = (_b = currentRefArray === null || currentRefArray === void 0 ? void 0 : currentRefArray._ids) !== null && _b !== void 0 ? _b : [];
+                        _c = (0, ArrayMembershipOps_1.applyArrayMembershipOps)(currentIds, update.ops), ids = _c.ids, changed = _c.changed;
+                        if (!changed) {
+                            return [2 /*return*/, 0];
+                        }
+                        record = { id: update.recordId };
+                        record[update.columnPropertyName] = new ReferenceArray_1.ReferenceArray(column.referenceTable, ids);
+                        return [4 /*yield*/, this.update(table, record)];
+                    case 5: return [2 /*return*/, _d.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * 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.
+     */
+    Db.prototype.updatePreserving = function (table, record, preserve) {
+        return __awaiter(this, void 0, void 0, function () {
+            var db_2, applicable, qb, rows, recordCopy, _i, applicable_1, p;
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!!this.transactionContextFactory.getTransactionContext().currentTransaction) return [3 /*break*/, 2];
+                        db_2 = this.newSelfWrapDb();
+                        return [4 /*yield*/, db_2.runTransaction(function () { return __awaiter(_this, void 0, void 0, function () { return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0: return [4 /*yield*/, db_2.updatePreserving(table, record, preserve)];
+                                    case 1: return [2 /*return*/, _a.sent()];
+                                }
+                            }); }); })];
+                    case 1: return [2 /*return*/, _a.sent()];
+                    case 2:
+                        if (!record.id) {
+                            throw new Error("updatePreserving must be called with a record with an id property");
+                        }
+                        applicable = preserve.filter(function (p) { return record[p.columnPropertyName] !== undefined; });
+                        if (!(applicable.length === 0)) return [3 /*break*/, 4];
+                        return [4 /*yield*/, this.update(table, record)];
+                    case 3: return [2 /*return*/, _a.sent()];
+                    case 4:
+                        qb = new QueryBuilderFactory_1.QueryBuilderFactory().getQueryBuilder(table);
+                        return [4 /*yield*/, this.addColumnQueries(table, qb, 'write')];
+                    case 5:
+                        _a.sent();
+                        qb.select({ fields: __spreadArray(['id'], applicable.map(function (p) { return p.columnPropertyName; }), true) });
+                        qb.condition({ field: 'id', operator: '=', value: record.id });
+                        return [4 /*yield*/, this._query(table, qb)];
+                    case 6:
+                        rows = _a.sent();
+                        if (rows.length === 0) {
+                            return [2 /*return*/, 0];
+                        }
+                        recordCopy = Object.assign({}, record);
+                        for (_i = 0, applicable_1 = applicable; _i < applicable_1.length; _i++) {
+                            p = applicable_1[_i];
+                            recordCopy[p.columnPropertyName] = (0, UpdatePreserving_1.overlayPreservedPaths)(rows[0][p.columnPropertyName], recordCopy[p.columnPropertyName], p.paths, p.whenType);
+                        }
+                        return [4 /*yield*/, this.update(table, recordCopy)];
+                    case 7: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
     Db.prototype.delete = function (table, query) {
         return __awaiter(this, void 0, void 0, function () {
             var qb, recordsToDelete, recordsToDeleteIds, deleteQb, generateDelete, recordDeleteCount;
@@ -268,7 +390,7 @@ var Db = /** @class */ (function () {
                         return [4 /*yield*/, this.tableWatcherRunner.runBeforeDeleteTableWatchers(table, recordsToDelete, qb, deleteQb)];
                     case 4:
                         _a.sent();
-                        return [4 /*yield*/, this.dbDriver.runDml(generateDelete, this.currentTransaction)];
+                        return [4 /*yield*/, this.dbDriver.runDml(generateDelete, this.transactionForDriver())];
                     case 5:
                         recordDeleteCount = _a.sent();
                         return [4 /*yield*/, this.runCascadeDeletions(table, recordsToDelete)];
@@ -581,7 +703,7 @@ var Db = /** @class */ (function () {
                         generateQuery = function (config) {
                             return qb.toSql(_this.statementConfigFactory.getStatementConfig(config));
                         };
-                        return [4 /*yield*/, this.dbDriver.runQuery(generateQuery, this.currentTransaction)];
+                        return [4 /*yield*/, this.dbDriver.runQuery(generateQuery, this.transactionForDriver())];
                     case 1:
                         serializedRecords = _a.sent();
                         recordSerializer = new Record_1.RecordSerializer(table);
@@ -660,7 +782,7 @@ var Db = /** @class */ (function () {
                         generateQuery = function (config) {
                             return qb.toSql(_this.statementConfigFactory.getStatementConfig(config));
                         };
-                        return [4 /*yield*/, this.dbDriver.runQuery(generateQuery, this.currentTransaction)];
+                        return [4 /*yield*/, this.dbDriver.runQuery(generateQuery, this.transactionForDriver())];
                     case 2:
                         result = _a.sent();
                         return [2 /*return*/, result[0]['count']];
@@ -736,13 +858,19 @@ var Db = /** @class */ (function () {
     /**
      * 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:
      *
@@ -759,46 +887,130 @@ var Db = /** @class */ (function () {
      */
     Db.prototype.runTransaction = function (fn) {
         return __awaiter(this, void 0, void 0, function () {
+            var postCommitHooks, result, _i, postCommitHooks_1, postCommitHook, error_1;
             var _this = this;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        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.");
                         }
+                        postCommitHooks = [];
                         return [4 /*yield*/, this.dbDriver.runTransaction(function (transaction) { return __awaiter(_this, void 0, void 0, function () {
-                                var _this = this;
+                                var contextData;
                                 return __generator(this, function (_a) {
                                     switch (_a.label) {
                                         case 0:
-                                            this.currentTransaction = 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 = [];
+                                            contextData = { currentTransaction: transaction, postCommitHooks: postCommitHooks };
                                             _a.label = 1;
                                         case 1:
                                             _a.trys.push([1, , 3, 4]);
-                                            return [4 /*yield*/, this.transactionContextFactory.runInContext(transaction, function () { return __awaiter(_this, void 0, void 0, function () {
-                                                    var result;
-                                                    return __generator(this, function (_a) {
-                                                        switch (_a.label) {
-                                                            case 0: return [4 /*yield*/, fn()];
-                                                            case 1:
-                                                                result = _a.sent();
-                                                                return [2 /*return*/, result];
-                                                        }
-                                                    });
-                                                }); })];
+                                            return [4 /*yield*/, this.transactionContextFactory.runInContext(contextData, fn)];
                                         case 2: return [2 /*return*/, _a.sent()];
                                         case 3:
-                                            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;
                                             return [7 /*endfinally*/];
                                         case 4: return [2 /*return*/];
                                     }
                                 });
                             }); })];
-                    case 1: return [2 /*return*/, _a.sent()];
+                    case 1:
+                        result = _a.sent();
+                        _i = 0, postCommitHooks_1 = postCommitHooks;
+                        _a.label = 2;
+                    case 2:
+                        if (!(_i < postCommitHooks_1.length)) return [3 /*break*/, 7];
+                        postCommitHook = postCommitHooks_1[_i];
+                        _a.label = 3;
+                    case 3:
+                        _a.trys.push([3, 5, , 6]);
+                        return [4 /*yield*/, postCommitHook()];
+                    case 4:
+                        _a.sent();
+                        return [3 /*break*/, 6];
+                    case 5:
+                        error_1 = _a.sent();
+                        this.logger.error({ message: "Post-commit hook failed", error: error_1 });
+                        return [3 /*break*/, 6];
+                    case 6:
+                        _i++;
+                        return [3 /*break*/, 2];
+                    case 7: return [2 /*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.
+     */
+    Db.prototype.runAfterCommit = function (hook) {
+        return __awaiter(this, void 0, void 0, function () {
+            var transactionContext;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        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 [2 /*return*/];
+                        }
+                        return [4 /*yield*/, hook()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
                 }
             });
         });
     };
+    /**
+     * 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.
+     */
+    Db.prototype.newSelfWrapDb = function () {
+        return new Db(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.
+     */
+    Db.prototype.transactionForDriver = function () {
+        var 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
     Db.prototype.chunk = function (arr, size) {
         if (size <= 0) {