@adobe/data 0.9.61 → 0.9.63

package/dist/ecs/archetype/archetype.d.ts

@@ -20,12 +20,19 @@ interface BaseArchetype {
 }
 export interface ReadonlyArchetype<C extends RequiredComponents> extends BaseArchetype, ReadonlyTable<C> {
     readonly components: ComponentSet<StringKeyof<C>>;
-    toData: () => unknown;
+    /**
+     * Serialize the archetype. When `copy` is true each column buffer is
+     * detached (`.copy()`) so the snapshot survives later mutation of the live
+     * archetype; otherwise the snapshot references the live column buffers
+     * (faster, but only valid until the next mutation).
+     */
+    toData: (copy?: boolean) => unknown;
 }
 export interface Archetype<C extends RequiredComponents = RequiredComponents> extends BaseArchetype, Table<C> {
     readonly components: ComponentSet<StringKeyof<C>>;
     insert: <T extends EntityInsertValues<C>>(rowData: Exact<EntityInsertValues<C>, T>) => Entity;
-    toData: () => unknown;
+    /** See {@link ReadonlyArchetype.toData}. */
+    toData: (copy?: boolean) => unknown;
     fromData: (data: unknown) => void;
 }
 export type FromArchetype<T> = T extends ReadonlyArchetype<infer C> ? {

package/dist/ecs/archetype/archetype.js.map

@@ -1 +1 @@
-{"version":3,"file":"archetype.js","sourceRoot":"","sources":["../../../src/ecs/archetype/archetype.ts"],"names":[],"mappings":"AA+CA,gDAAgD;AAChD,CAAC;IAKG,2BAA2B;IAC3B,MAAM,eAAe,GAAG,CAAC,IAAmB,EAAE,EAAE;QAC5C,MAAM,SAAS,GAAoB,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAChF,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB;IAC7C,CAAC,CAAC;IAEF,2CAA2C;IAC3C,MAAM,iBAAiB,GAAG,CAAC,IAAmB,EAAE,EAAE;QAC9C,MAAM,WAAW,GAAoB,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAChG,oDAAoD;QACpD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"archetype.js","sourceRoot":"","sources":["../../../src/ecs/archetype/archetype.ts"],"names":[],"mappings":"AAsDA,gDAAgD;AAChD,CAAC;IAKG,2BAA2B;IAC3B,MAAM,eAAe,GAAG,CAAC,IAAmB,EAAE,EAAE;QAC5C,MAAM,SAAS,GAAoB,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAChF,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB;IAC7C,CAAC,CAAC;IAEF,2CAA2C;IAC3C,MAAM,iBAAiB,GAAG,CAAC,IAAmB,EAAE,EAAE;QAC9C,MAAM,WAAW,GAAoB,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAChG,oDAAoD;QACpD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC,CAAC;AACN,CAAC"}

package/dist/ecs/archetype/create-archetype.js

@@ -134,8 +134,11 @@ export const createArchetype = (components, id, entityLocationTable) => {
         ...table,
         components: componentSet,
         insert: createEntity,
-        toData: () => ({
-            columns: archetype.columns,
+        toData: (copy = false) => ({
+            columns: copy
+                ? Object.fromEntries(Object.entries(archetype.columns)
+                    .map(([name, column]) => [name, column.copy()]))
+                : archetype.columns,
             rowCount: archetype.rowCount,
             rowCapacity: archetype.rowCapacity,
         }),

package/dist/ecs/archetype/create-archetype.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-archetype.js","sourceRoot":"","sources":["../../../src/ecs/archetype/create-archetype.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create-archetype.js","sourceRoot":"","sources":["../../../src/ecs/archetype/create-archetype.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,KAAK,KAAK,MAAM,sBAAsB,CAAC;AAM9C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGhE,8EAA8E;AAC9E,6CAA6C;AAC7C,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,sEAAsE;AACtE,wEAAwE;AACxE,uDAAuD;AACvD,EAAE;AACF,wEAAwE;AACxE,wDAAwD;AACxD,4EAA4E;AAC5E,2EAA2E;AAC3E,0BAA0B;AAC1B,0EAA0E;AAC1E,yDAAyD;AACzD,EAAE;AACF,sBAAsB;AACtB,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E;AAC1E,uEAAuE;AACvE,yEAAyE;AACzE,4EAA4E;AAC5E,sEAAsE;AACtE,qBAAqB;AACrB,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,0EAA0E;AAC1E,wEAAwE;AACxE,2CAA2C;AAC3C,0EAA0E;AAC1E,+EAA+E;AAC/E,yEAAyE;AACzE,sEAAsE;AACtE,2EAA2E;AAC3E,0EAA0E;AAC1E,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,MAAM,UAAU,GAAG,4BAA4B,CAAC;AAahD,MAAM,sBAAsB,GAAG,CAC3B,WAAmB,EACnB,OAAyC,EACzC,mBAAwC,EACvB,EAAE;IACnB,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,8CAA8C;IAC9C,qEAAqE;IACrE,wEAAwE;IACxE,sEAAsE;IACtE,gEAAgE;IAChE,4DAA4D;IAC5D,oEAAoE;IACpE,kCAAkC;IAClC,sEAAsE;IACtE,iEAAiE;IACjE,qEAAqE;IACrE,oEAAoE;IACpE,aAAa;IACb,MAAM,mBAAmB,GAAa,EAAE,CAAC;IACzC,MAAM,oBAAoB,GAAuB,EAAE,CAAC;IACpD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAChC,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QAC5B,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;QACzB,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,WAAW,KAAK,qBAAqB,IAAI,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,WAAW,GAAG;;;;;;;;;;;;;EAatB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;KAUZ,CAAC;IACF,uCAAuC;IACvC,MAAM,OAAO,GAAG,IAAI,QAAQ,CACxB,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,EACL,GAAG,mBAAmB,EACtB,WAAW,CAOA,CAAC;IAEhB,OAAO,OAAO,CACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,OAAO,CAAC,EAAyB,EACjC,GAAG,oBAAoB,CAC1B,CAAC;AACN,CAAC,CAAC;AAEF,gEAAgE;AAChE,0EAA0E;AAC1E,qEAAqE;AACrE,aAAa;AACb,MAAM,kBAAkB,GAAG,CACvB,WAAmB,EACnB,mBAAwC,EAC9B,EAAE;IACZ,OAAO,CAAC,SAAc,EAAE,OAAY,EAAE,EAAE;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC;QAC3E,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC;IAClB,CAAC,CAAC;AACN,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAC3B,UAAa,EACb,EAAU,EACV,mBAAwC,EAC+B,EAAE;IACzE,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAEtD,uEAAuE;IACvE,sEAAsE;IACtE,IAAI,UAAsB,CAAC;IAC3B,MAAM,iBAAiB,GAAG,GAAG,EAAE;QAC3B,UAAU;YACN,sBAAsB,CAAC,EAAE,EAAE,SAAS,CAAC,OAA2C,EAAE,mBAAmB,CAAC;gBACtG,kBAAkB,CAAC,EAAE,EAAE,mBAAmB,CAAC,CAAC;IACpD,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,CAAC,OAA4D,EAAU,EAAE;QAC1F,+DAA+D;QAC/D,gDAAgD;QAChD,OAAO,UAAU,CAAC,SAAgB,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG;QACd,EAAE;QACF,GAAG,KAAK;QACR,UAAU,EAAE,YAAmC;QAC/C,MAAM,EAAE,YAAY;QACpB,MAAM,EAAE,CAAC,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;YACvB,OAAO,EAAE,IAAI;gBACT,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAkD,CAAC;qBACvE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CACtD;gBACD,CAAC,CAAC,SAAS,CAAC,OAAO;YACvB,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,WAAW,EAAE,SAAS,CAAC,WAAW;SACrC,CAAC;QACF,QAAQ,EAAE,CAAC,IAAa,EAAE,EAAE;YACxB,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAC/B,gEAAgE;YAChE,+DAA+D;YAC/D,0CAA0C;YAC1C,iBAAiB,EAAE,CAAC;YACpB,0FAA0F;QAC9F,CAAC;KAC6I,CAAC;IAEnJ,kEAAkE;IAClE,wCAAwC;IACxC,iBAAiB,EAAE,CAAC;IAEpB,OAAO,SAAS,CAAC;AACrB,CAAC,CAAA"}

package/dist/ecs/database/concurrency/concurrency-strategy.d.ts

@@ -0,0 +1,86 @@
+import type { Entity } from "../../entity/entity.js";
+import type { TransactionContext, TransactionResult } from "../transactional-store/index.js";
+import type { TransactionEnvelope } from "../reconciling/reconciling-database.js";
+/**
+ * The interface every concurrency strategy must satisfy.
+ *
+ * A strategy encapsulates all decisions about how locally-initiated
+ * transactions are applied and how inbound envelopes (from a sync service
+ * or another local source) are reconciled against the current store state.
+ *
+ * Two built-in strategies are provided:
+ *
+ *   - `createImmediateConcurrency()` — commits apply immediately, no
+ *     rollback queue. Use this as the base database for external wrappers
+ *     (e.g. a collaborative-editing layer that manages its own replay buffer).
+ *
+ *   - `createRebaseReplayConcurrency(userId)` — commits apply locally as
+ *     transients and wait for the sync server's echoed committed envelope to
+ *     promote them. Full rollback-and-replay queue, cross-peer id-determinism.
+ */
+export interface ConcurrencyStrategy {
+    /**
+     * When true, the dispatcher applies "commit" intents as transients
+     * (negative time) and waits for a server echo to promote them.
+     * When false, commits apply immediately with positive time.
+     */
+    readonly deferredCommit: boolean;
+    /**
+     * Peer/session identifier stamped on every outbound envelope.
+     * Required for strategies that participate in a multi-peer sync protocol.
+     */
+    readonly userId?: number | string;
+    /**
+     * Process a transaction envelope. Called by the dispatcher for each
+     * locally-initiated transaction and by sync services for inbound commits.
+     * Does NOT fire `observe.envelopes` (that is the dispatcher's job).
+     */
+    readonly apply: (envelope: TransactionEnvelope) => TransactionResult<unknown> | undefined;
+    /**
+     * Cancel a pending transient by compound (userId, id) key.
+     * No-op for strategies that have no transient queue.
+     */
+    readonly cancel: (id: number, userId?: number | string) => void;
+    /**
+     * Called by `db.reset()` before the store is cleared.
+     * Strategies with a transient queue should clear it here.
+     */
+    readonly onReset: () => void;
+    /**
+     * Called immediately before `db.toData()` serializes the store.
+     * Strategies with a transient queue should roll back transients here so
+     * the snapshot contains only committed state.
+     *
+     * When this hook (together with `onAfterToData`) is present, `db.toData()`
+     * serializes a detached copy of the store between the two hooks, so the
+     * `onAfterToData` replay cannot corrupt the returned snapshot. See
+     * `Database.toData()`.
+     */
+    readonly onBeforeToData?: () => void;
+    /**
+     * Called immediately after `db.toData()` serializes the store.
+     * Strategies that roll back in `onBeforeToData` should replay here to
+     * restore the in-progress transient state.
+     */
+    readonly onAfterToData?: () => void;
+    /**
+     * Called immediately after `db.fromData()` loads a snapshot into the
+     * store. Strategies with a transient queue should replay pending
+     * transients here so in-progress work is visible after a data load.
+     */
+    readonly onAfterFromData?: () => void;
+}
+/**
+ * Factory that creates a `ConcurrencyStrategy` bound to the given execute
+ * and transaction-lookup functions. Called once per database at construction.
+ *
+ * `execute` is the observed database's execute — it applies a transaction,
+ * fires observers, and returns the mutation record.
+ *
+ * `getTransaction` looks up a registered transaction function by name,
+ * returning undefined when the name has not yet been registered via extend.
+ */
+export type ConcurrencyStrategyFactory = (execute: (fn: (ctx: TransactionContext<any, any, any>) => void | Entity, options?: {
+    transient?: boolean;
+    userId?: number | string;
+}) => TransactionResult<unknown>, getTransaction: (name: string) => ((ctx: TransactionContext<any, any, any>, args: unknown) => void | Entity) | undefined) => ConcurrencyStrategy;

package/dist/ecs/database/concurrency/concurrency-strategy.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=concurrency-strategy.js.map

package/dist/ecs/database/concurrency/concurrency-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency-strategy.js","sourceRoot":"","sources":["../../../../src/ecs/database/concurrency/concurrency-strategy.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/ecs/database/concurrency/immediate-concurrency.d.ts

@@ -0,0 +1,22 @@
+import type { ConcurrencyStrategyFactory } from "./concurrency-strategy.js";
+/**
+ * Lighter-weight concurrency strategy that applies commits and transients
+ * immediately with no global rollback-and-replay cycle.
+ *
+ * Key differences from {@link createRebaseReplayConcurrency}:
+ *
+ *   - No deferred-commit mode — `db.transactions.X(args)` commits
+ *     synchronously with positive time.
+ *   - No global rebase: when an inbound committed envelope arrives, it is
+ *     applied directly without rolling back other pending transients. This
+ *     means entity-id allocation is NOT deterministic across peers under
+ *     concurrent edits — use this only when there is a single writer or
+ *     when an external layer manages replay (e.g. a collaborative-editing
+ *     wrapper).
+ *   - Async generator transients are still supported: each yield applies
+ *     the intermediate state immediately and rolls it back when the next
+ *     yield or the final commit arrives. Cancel rolls back the last
+ *     applied transient for that transaction. Transients from different
+ *     concurrent transactions do NOT interact (no cross-transaction rebase).
+ */
+export declare const createImmediateConcurrency: () => ConcurrencyStrategyFactory;

package/dist/ecs/database/concurrency/immediate-concurrency.js

@@ -0,0 +1,74 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { applyOperations } from "../transactional-store/apply-operations.js";
+/**
+ * Lighter-weight concurrency strategy that applies commits and transients
+ * immediately with no global rollback-and-replay cycle.
+ *
+ * Key differences from {@link createRebaseReplayConcurrency}:
+ *
+ *   - No deferred-commit mode — `db.transactions.X(args)` commits
+ *     synchronously with positive time.
+ *   - No global rebase: when an inbound committed envelope arrives, it is
+ *     applied directly without rolling back other pending transients. This
+ *     means entity-id allocation is NOT deterministic across peers under
+ *     concurrent edits — use this only when there is a single writer or
+ *     when an external layer manages replay (e.g. a collaborative-editing
+ *     wrapper).
+ *   - Async generator transients are still supported: each yield applies
+ *     the intermediate state immediately and rolls it back when the next
+ *     yield or the final commit arrives. Cancel rolls back the last
+ *     applied transient for that transaction. Transients from different
+ *     concurrent transactions do NOT interact (no cross-transaction rebase).
+ */
+export const createImmediateConcurrency = () => (execute, getTransaction) => {
+    // Per-transaction store of the last-applied transient result, keyed
+    // by compound `"userId:id"`. Used to roll back a transient when a
+    // newer transient, commit, or cancel arrives for the same transaction.
+    const pending = new Map();
+    const key = (id, userId) => `${userId}:${id}`;
+    const rollbackPending = (id, userId) => {
+        const k = key(id, userId);
+        const prior = pending.get(k);
+        if (prior) {
+            execute(t => applyOperations(t, prior.undo), { transient: true, userId: undefined });
+            pending.delete(k);
+        }
+    };
+    return {
+        deferredCommit: false,
+        apply(envelope) {
+            const { id, userId, time, args } = envelope;
+            if (time === 0) {
+                rollbackPending(id, userId);
+                return undefined;
+            }
+            if (time < 0) {
+                // Roll back the previous transient for this transaction (if any),
+                // then apply the new one. No interaction with other transactions.
+                rollbackPending(id, userId);
+                const fn = getTransaction(envelope.name);
+                if (!fn)
+                    throw new Error(`Unknown transaction: ${envelope.name}`);
+                const result = execute(t => fn(t, args), { transient: true, userId });
+                const isNoOp = result.redo.length === 0 && result.undo.length === 0;
+                if (!isNoOp)
+                    pending.set(key(id, userId), result);
+                return result;
+            }
+            // Positive time: commit. Roll back any pending transient for this
+            // transaction, then apply the committed state.
+            rollbackPending(id, userId);
+            const fn = getTransaction(envelope.name);
+            if (!fn)
+                throw new Error(`Unknown transaction: ${envelope.name}`);
+            return execute(t => fn(t, args), { transient: false, userId });
+        },
+        cancel(id, userId) {
+            rollbackPending(id, userId);
+        },
+        onReset() {
+            pending.clear();
+        },
+    };
+};
+//# sourceMappingURL=immediate-concurrency.js.map

package/dist/ecs/database/concurrency/immediate-concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"immediate-concurrency.js","sourceRoot":"","sources":["../../../../src/ecs/database/concurrency/immediate-concurrency.ts"],"names":[],"mappings":"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"}

package/dist/ecs/database/concurrency/index.d.ts

@@ -0,0 +1,4 @@
+export type { ConcurrencyStrategy, ConcurrencyStrategyFactory } from "./concurrency-strategy.js";
+export { createImmediateConcurrency } from "./immediate-concurrency.js";
+export { createRebaseReplayConcurrency } from "./rebase-replay-concurrency.js";
+export { createRollForwardConcurrency } from "./roll-forward-concurrency.js";

package/dist/ecs/database/concurrency/index.js

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { createImmediateConcurrency } from "./immediate-concurrency.js";
+export { createRebaseReplayConcurrency } from "./rebase-replay-concurrency.js";
+export { createRollForwardConcurrency } from "./roll-forward-concurrency.js";
+//# sourceMappingURL=index.js.map

package/dist/ecs/database/concurrency/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/ecs/database/concurrency/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/ecs/database/concurrency/rebase-replay-concurrency.d.ts

@@ -0,0 +1,20 @@
+import type { ConcurrencyStrategyFactory } from "./concurrency-strategy.js";
+/**
+ * Concurrency strategy that implements the optimistic rebase-replay protocol
+ * required for multi-peer synchronisation.
+ *
+ * Behaviour:
+ *   - Local "commit" intents are applied as transients (negative time) and
+ *     wait for the sync server's echoed committed envelope to promote them
+ *     via rollback-and-replay. This is required for cross-peer entity-id
+ *     determinism under concurrent edits.
+ *   - Every outbound envelope is stamped with `userId` so the reconciler's
+ *     compound `(userId, id)` key keeps concurrent peers' id counters from
+ *     colliding.
+ *   - `onBeforeToData` / `onAfterToData` roll back and replay the transient
+ *     queue around serialisation so snapshots always contain only committed state.
+ *
+ * @param userId Stable peer/session identifier unique across all peers
+ *   sharing the same sync server.
+ */
+export declare const createRebaseReplayConcurrency: (userId: number | string) => ConcurrencyStrategyFactory;

package/dist/ecs/database/concurrency/rebase-replay-concurrency.js

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createRebaseReplayApplier } from "../reconciling/create-rebase-replay-applier.js";
+/**
+ * Concurrency strategy that implements the optimistic rebase-replay protocol
+ * required for multi-peer synchronisation.
+ *
+ * Behaviour:
+ *   - Local "commit" intents are applied as transients (negative time) and
+ *     wait for the sync server's echoed committed envelope to promote them
+ *     via rollback-and-replay. This is required for cross-peer entity-id
+ *     determinism under concurrent edits.
+ *   - Every outbound envelope is stamped with `userId` so the reconciler's
+ *     compound `(userId, id)` key keeps concurrent peers' id counters from
+ *     colliding.
+ *   - `onBeforeToData` / `onAfterToData` roll back and replay the transient
+ *     queue around serialisation so snapshots always contain only committed state.
+ *
+ * @param userId Stable peer/session identifier unique across all peers
+ *   sharing the same sync server.
+ */
+export const createRebaseReplayConcurrency = (userId) => (...args) => {
+    const applier = createRebaseReplayApplier(...args);
+    return {
+        deferredCommit: true,
+        userId,
+        apply: applier.apply,
+        cancel: applier.cancel,
+        onReset: applier.onReset,
+        onBeforeToData: applier.rollbackAllTransients,
+        onAfterToData: applier.replayAllTransients,
+        onAfterFromData: applier.replayAllTransients,
+    };
+};
+//# sourceMappingURL=rebase-replay-concurrency.js.map

package/dist/ecs/database/concurrency/rebase-replay-concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebase-replay-concurrency.js","sourceRoot":"","sources":["../../../../src/ecs/database/concurrency/rebase-replay-concurrency.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gDAAgD,CAAC;AAG3F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,MAAuB,EAA8B,EAAE,CACjG,CAAC,GAAG,IAAI,EAAuB,EAAE;IAC7B,MAAM,OAAO,GAAG,yBAAyB,CAAC,GAAG,IAAI,CAAC,CAAC;IACnD,OAAO;QACH,cAAc,EAAE,IAAI;QACpB,MAAM;QACN,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,cAAc,EAAE,OAAO,CAAC,qBAAqB;QAC7C,aAAa,EAAE,OAAO,CAAC,mBAAmB;QAC1C,eAAe,EAAE,OAAO,CAAC,mBAAmB;KAC/C,CAAC;AACN,CAAC,CAAC"}

package/dist/ecs/database/concurrency/roll-forward-concurrency.d.ts

@@ -0,0 +1,33 @@
+import type { ConcurrencyStrategyFactory } from "./concurrency-strategy.js";
+/**
+ * Roll-forward reconciliation: a client-side optimistic concurrency model for
+ * collaborative / multi-peer editing. Provided to prove the
+ * {@link ConcurrencyStrategy} seam can host a fundamentally different
+ * reconciliation engine than {@link createRebaseReplayConcurrency} — it is
+ * not currently wired into a real transport.
+ *
+ * The defining difference from {@link createRebaseReplayConcurrency}:
+ *
+ *   - **Roll-forward, not re-execute.** On rebase, each pending local edit is
+ *     replayed by re-applying its captured post-image tuples, *not* by
+ *     re-running its transaction function. A transaction that reads current
+ *     state and derives a new value (e.g. "add 10 to whatever is there")
+ *     therefore preserves the value it originally produced, regardless of how
+ *     the confirmed base shifted underneath it. Re-execution would instead
+ *     recompute against the new base.
+ *
+ * The rebase sequence on a confirmed (positive-time) delta:
+ *   1. roll back all pending entries newest-to-oldest (apply their undo),
+ *   2. apply the confirmed delta,
+ *   3. replay the remaining pending entries oldest-to-newest by re-applying
+ *      their captured redo tuples, recapturing fresh undo against the new base.
+ *
+ * Local transients carry monotonically increasing |time| (they are appended
+ * as the user edits), so a newly-captured entry always sorts last; the buffer
+ * is kept in arrival order and a new entry is materialized on top of the
+ * replayed survivors.
+ *
+ * @param userId Stable peer/session identifier stamped on every outbound
+ *   envelope, unique across all peers sharing the same sync server.
+ */
+export declare const createRollForwardConcurrency: (userId: number | string) => ConcurrencyStrategyFactory;

package/dist/ecs/database/concurrency/roll-forward-concurrency.js

@@ -0,0 +1,115 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { applyOperations } from "../transactional-store/apply-operations.js";
+/**
+ * Roll-forward reconciliation: a client-side optimistic concurrency model for
+ * collaborative / multi-peer editing. Provided to prove the
+ * {@link ConcurrencyStrategy} seam can host a fundamentally different
+ * reconciliation engine than {@link createRebaseReplayConcurrency} — it is
+ * not currently wired into a real transport.
+ *
+ * The defining difference from {@link createRebaseReplayConcurrency}:
+ *
+ *   - **Roll-forward, not re-execute.** On rebase, each pending local edit is
+ *     replayed by re-applying its captured post-image tuples, *not* by
+ *     re-running its transaction function. A transaction that reads current
+ *     state and derives a new value (e.g. "add 10 to whatever is there")
+ *     therefore preserves the value it originally produced, regardless of how
+ *     the confirmed base shifted underneath it. Re-execution would instead
+ *     recompute against the new base.
+ *
+ * The rebase sequence on a confirmed (positive-time) delta:
+ *   1. roll back all pending entries newest-to-oldest (apply their undo),
+ *   2. apply the confirmed delta,
+ *   3. replay the remaining pending entries oldest-to-newest by re-applying
+ *      their captured redo tuples, recapturing fresh undo against the new base.
+ *
+ * Local transients carry monotonically increasing |time| (they are appended
+ * as the user edits), so a newly-captured entry always sorts last; the buffer
+ * is kept in arrival order and a new entry is materialized on top of the
+ * replayed survivors.
+ *
+ * @param userId Stable peer/session identifier stamped on every outbound
+ *   envelope, unique across all peers sharing the same sync server.
+ */
+export const createRollForwardConcurrency = (userId) => (execute, getTransaction) => {
+    const pending = [];
+    const indexOfEntry = (id, entryUserId) => pending.findIndex(e => e.id === id && e.userId === entryUserId);
+    const rollbackAll = () => {
+        for (let i = pending.length - 1; i >= 0; i--) {
+            execute(t => applyOperations(t, pending[i].undo), { transient: true, userId: undefined });
+        }
+    };
+    // Roll-forward: re-apply each pending entry's captured post-image
+    // tuples and recapture fresh undo against the (possibly changed) base.
+    const replayAll = () => {
+        for (const entry of pending) {
+            const result = execute(t => applyOperations(t, entry.redo), { transient: true, userId: entry.userId });
+            entry.undo = result.undo;
+        }
+    };
+    // Run a transaction function once to materialize its effect and capture
+    // the post-image. This is the only place a transaction function runs;
+    // every subsequent rebase rolls the captured tuples forward instead.
+    const runTransaction = (envelope) => {
+        const fn = getTransaction(envelope.name);
+        if (!fn)
+            throw new Error(`Unknown transaction: ${envelope.name}`);
+        return execute(t => fn(t, envelope.args), { transient: envelope.time < 0, userId: envelope.userId });
+    };
+    const removeAndRebuild = (id, entryUserId) => {
+        const idx = indexOfEntry(id, entryUserId);
+        if (idx === -1)
+            return;
+        rollbackAll();
+        pending.splice(idx, 1);
+        replayAll();
+    };
+    return {
+        deferredCommit: true,
+        userId,
+        apply(envelope) {
+            const { id, userId: envelopeUserId, time } = envelope;
+            // Cancel: drop the matching pending entry and rebuild.
+            if (time === 0) {
+                removeAndRebuild(id, envelopeUserId);
+                return undefined;
+            }
+            // Optimistic local transient: roll back, drop any prior version
+            // of this transaction, replay the survivors, then run the fn on
+            // top and capture its post-image tuples.
+            if (time < 0) {
+                rollbackAll();
+                const existing = indexOfEntry(id, envelopeUserId);
+                if (existing !== -1)
+                    pending.splice(existing, 1);
+                replayAll();
+                const result = runTransaction(envelope);
+                const isNoOp = result.redo.length === 0 && result.undo.length === 0;
+                if (!isNoOp) {
+                    pending.push({ id, userId: envelopeUserId, time, redo: result.redo, undo: result.undo });
+                }
+                return result;
+            }
+            // Confirmed delta (positive time): roll back all pending, drop
+            // our own echo (now authoritative), apply the confirmed delta,
+            // then roll the survivors forward.
+            rollbackAll();
+            const echo = indexOfEntry(id, envelopeUserId);
+            if (echo !== -1)
+                pending.splice(echo, 1);
+            const result = runTransaction(envelope);
+            replayAll();
+            return result;
+        },
+        cancel(id, cancelUserId) {
+            removeAndRebuild(id, cancelUserId);
+        },
+        onReset() {
+            pending.length = 0;
+        },
+        onBeforeToData: rollbackAll,
+        onAfterToData: replayAll,
+        onAfterFromData: replayAll,
+    };
+};
+//# sourceMappingURL=roll-forward-concurrency.js.map

package/dist/ecs/database/concurrency/roll-forward-concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll-forward-concurrency.js","sourceRoot":"","sources":["../../../../src/ecs/database/concurrency/roll-forward-concurrency.ts"],"names":[],"mappings":"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"}

package/dist/ecs/database/concurrency/roll-forward-concurrency.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ecs/database/concurrency/roll-forward-concurrency.test.js

@@ -0,0 +1,136 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Verifies the pluggable-concurrency seam by running a client-side
+// roll-forward replay strategy through the public `createDatabase` API, and
+// contrasting it with the built-in rebase-replay strategy on an identical
+// scenario.
+import { describe, it, expect, vi } from "vitest";
+import { Database } from "../database.js";
+import { createRollForwardConcurrency } from "./roll-forward-concurrency.js";
+import { createRebaseReplayConcurrency } from "./rebase-replay-concurrency.js";
+// A single numeric component is enough to expose the roll-forward vs
+// re-execute difference: one transaction derives its value from current state.
+const plugin = Database.Plugin.create({
+    components: {
+        counter: { type: "number" },
+    },
+    resources: {},
+    archetypes: {
+        Counter: ["counter"],
+    },
+    transactions: {
+        createCounter(t, args) {
+            return t.archetypes.Counter.insert({ counter: args.counter });
+        },
+        // Reads current value and adds 10 — its result depends on the base
+        // state it runs against. This is the transaction whose replay semantics
+        // distinguish roll-forward from re-execute.
+        bumpFromCurrent(t, args) {
+            const current = t.read(args.entity)?.counter ?? 0;
+            t.update(args.entity, { counter: current + 10 });
+        },
+        setAbsolute(t, args) {
+            t.update(args.entity, { counter: args.value });
+        },
+    },
+});
+const makeDb = (concurrency) => Database.create(plugin, { concurrency });
+// Seed a server-confirmed entity (positive time) so the entity exists in the
+// committed base before any optimistic local edit. Returns its id.
+const seedCommittedCounter = (db, value) => {
+    const result = db.apply({ id: 1, userId: "seed", name: "createCounter", args: { counter: value }, time: Date.now() });
+    return result.value;
+};
+describe("createRollForwardConcurrency — pluggable concurrency viability", () => {
+    it("plugs into createDatabase and exposes itself as the database concurrency strategy", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        expect(db.concurrency.deferredCommit).toBe(true);
+        expect(db.concurrency.userId).toBe("A");
+    });
+    it("applies a server-confirmed delta directly", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        const entity = seedCommittedCounter(db, 42);
+        expect(db.read(entity)?.counter).toBe(42);
+    });
+    it("makes a local optimistic transient visible immediately", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        const entity = seedCommittedCounter(db, 0);
+        db.transactions.bumpFromCurrent({ entity });
+        // Deferred-commit: applied locally as a transient before any echo.
+        expect(db.read(entity)?.counter).toBe(10);
+    });
+    it("replays pending edits by rolling captured post-images forward, not by re-executing", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        const entity = seedCommittedCounter(db, 0);
+        // Local optimistic edit: 0 -> 10, captured post-image = "set counter 10".
+        db.transactions.bumpFromCurrent({ entity });
+        expect(db.read(entity)?.counter).toBe(10);
+        // A peer's confirmed delta moves the base out from under the pending edit.
+        db.apply({ id: 99, userId: "B", name: "setAbsolute", args: { entity, value: 100 }, time: Date.now() + 1 });
+        // Roll-forward replays the *captured tuple* (set counter 10), so the
+        // pending edit's original post-image wins — NOT 110 (which is what
+        // re-executing bumpFromCurrent against the new base of 100 would give).
+        expect(db.read(entity)?.counter).toBe(10);
+    });
+    it("cancel discards a pending transient and restores committed state", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        const entity = seedCommittedCounter(db, 5);
+        // Drive a cancellable transient through the dispatcher via an async
+        // generator that yields once then throws (cleanly tears down).
+        const observer = vi.fn();
+        const unobserve = db.observe.entity(entity)(observer);
+        db.transactions.bumpFromCurrent({ entity });
+        expect(db.read(entity)?.counter).toBe(15);
+        // Cancel the pending entry by its dispatcher-assigned id. The first
+        // (and only) wrapped transaction gets id 1 from the dispatcher counter.
+        db.cancel(1, "A");
+        expect(db.read(entity)?.counter).toBe(5);
+        unobserve();
+    });
+    it("reset clears the pending buffer", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        const entity = seedCommittedCounter(db, 0);
+        db.transactions.bumpFromCurrent({ entity });
+        expect(db.read(entity)?.counter).toBe(10);
+        db.reset();
+        // Store is empty and the pending buffer is gone — re-seeding starts clean.
+        const reseeded = seedCommittedCounter(db, 7);
+        expect(db.read(reseeded)?.counter).toBe(7);
+    });
+    it("toData serializes only committed state and leaves the live transient intact", () => {
+        const db = makeDb(createRollForwardConcurrency("A"));
+        const entity = seedCommittedCounter(db, 0);
+        db.transactions.bumpFromCurrent({ entity });
+        expect(db.read(entity)?.counter).toBe(10);
+        const snapshot = db.toData();
+        // The live optimistic transient survives the rollback→serialize→replay.
+        expect(db.read(entity)?.counter).toBe(10);
+        // The snapshot is a detached copy of committed state only: loading it
+        // into a fresh database yields the committed base (0), not the pending
+        // optimistic value (10). This must hold even though `onAfterToData`
+        // replayed the transient back onto the live store after serialization.
+        const loaded = Database.create(plugin);
+        loaded.fromData(snapshot);
+        const loadedValues = loaded.select(["counter"]).map(e => loaded.read(e)?.counter);
+        expect(loadedValues).toEqual([0]);
+    });
+});
+describe("roll-forward vs rebase-replay — same seam, different replay semantics", () => {
+    // Identical scenario, swapping only the concurrency strategy factory. The
+    // divergent result proves the two engines are genuinely different and that
+    // the pluggable seam selects between them with no other changes.
+    const runRebaseScenario = (concurrency) => {
+        const db = makeDb(concurrency);
+        const entity = seedCommittedCounter(db, 0);
+        db.transactions.bumpFromCurrent({ entity });
+        db.apply({ id: 99, userId: "B", name: "setAbsolute", args: { entity, value: 100 }, time: Date.now() + 1 });
+        return db.read(entity)?.counter ?? NaN;
+    };
+    it("roll-forward preserves the captured post-image (10)", () => {
+        expect(runRebaseScenario(createRollForwardConcurrency("A"))).toBe(10);
+    });
+    it("rebase-replay re-executes against the new base (110)", () => {
+        expect(runRebaseScenario(createRebaseReplayConcurrency("A"))).toBe(110);
+    });
+});
+//# sourceMappingURL=roll-forward-concurrency.test.js.map