footprintjs 9.28.0 → 9.30.0

package/dist/esm/lib/memory/TransactionBuffer.d.ts

@@ -32,10 +32,45 @@
  * `set` path — detaches that value first ({@link detachHeldAncestors}), so
  * `workingCopy` and `overwritePatch` never share a container the engine
  * mutates on one side only.
+ *
+ * COPY-ON-WRITE (9.29.0 — docs/design/2026-10-copy-on-write-commit.md). The
+ * buffer no longer clones the committed state it starts from. `baseSnapshot`
+ * IS the committed generation the stage first touched (held by reference —
+ * committed state is immutable-after-swap), and `workingCopy` starts as a
+ * copy of its ROOT only: each write copies the containers on its own path
+ * ({@link ownSpine}), and the first READ after the stage's first write of a
+ * container still shared with committed state takes a private deep copy of
+ * it ({@link privatise}) — what the whole-state clone used to give every
+ * read, so an in-place edit of a read value stays private exactly as it did.
+ * A read the working copy cannot answer is served from live state by the
+ * caller, as before; the buffer then replaces that path of its diff base
+ * with a private copy ({@link detachBase}), as the clone had it.
+ *
+ * THE ADMITTED RECORD (9.30.0 — docs/design/2026-10-admitted-record.md). A
+ * commit is admitted only if its bundle folds back to the stage's
+ * read-your-writes view at every path the stage touched (and at every
+ * container its writes created on the way there, below the stage's address).
+ * Both encoders commit the value the stage read: a compact row — a `merge`
+ * delta, an `append` tail — is kept where it provably folds back; a family of
+ * rows that does not is recorded as `set` rows of the values the stage read
+ * ({@link admit}). Before 9.30.0 the one accumulated merge delta per path was
+ * replayed at every `merge` row of that path, which lied across a hard write
+ * (`$update(k,{x}); k = {y}; $update(k,{z})` committed `{y, x, z}` for a
+ * read-back of `{y, z}`), an `[]` clear, a kind change or an array union
+ * deduplicated by reference. Verified when the stage staged a `merge` or a
+ * nested op; a stage that staged only `set` / `delete` of keys directly under
+ * its address is coherent by construction — both trees receive the same
+ * write — and is admitted without the fold.
  */
 import type { CommitValuesMode, MemoryPatch, TraceEntry } from './types.js';
 export declare class TransactionBuffer {
-    private readonly baseSnapshot;
+    /**
+     * The net-change diff base: the committed generation the stage first
+     * touched, by reference — except where {@link detachBase} replaced a path
+     * of it with a private copy (its root and the containers on the way are
+     * then copies too, owned by {@link baseOwned}).
+     */
+    private baseSnapshot;
     private workingCopy;
     private overwritePatch;
     private updatePatch;
@@ -57,11 +92,59 @@ export declare class TransactionBuffer {
      *  keys tracked-read so far — the temporal-prefix attribution consumed by
      *  causal slicing. Undefined (default) = zero cost, byte-identical ops. */
     private readonly readKeysProvider?;
-    constructor(base: any, commitValues?: CommitValuesMode, readKeysProvider?: () => string[]);
+    /**
+     * The containers in `workingCopy` this buffer CREATED: its root copy, the
+     * path copies its writes made, the merge results it built, and every
+     * container of the private copies its reads took. A write edits these in
+     * place. Everything else in `workingCopy` is SHARED — with the committed
+     * generation the stage first touched, or with a value the stage staged —
+     * and is copied before a write passes through it ({@link ownSpine}).
+     */
+    private owned;
+    /**
+     * Container values the stage staged with {@link set} — its own objects,
+     * held by reference (9.23.0). A read hands them back as they are, exactly
+     * as the private working copy always did, and never privatises them: a
+     * private copy of a staged value would leave `workingCopy` and
+     * `overwritePatch` disagreeing about a value the stage wrote.
+     */
+    private staged;
+    /**
+     * Owned containers with no container still shared with committed state
+     * anywhere below them (a private deep copy, a merge result built on a
+     * private base, a path copy whose shared children were privatised). A read
+     * that lands on one needs no walk — see {@link privatiseBelow}.
+     */
+    private privateTrees;
+    /**
+     * The containers of {@link baseSnapshot} that {@link detachBase} created:
+     * its root copy and the copies on the way to a detached path. Allocated
+     * only by the first detach — the in-contract stage never pays for it.
+     */
+    private baseOwned?;
+    /**
+     * The private deep copies {@link detachBase} put into the diff base: nothing
+     * at or below one is committed state, so a later detach inside it is a no-op.
+     */
+    private detachedBase?;
+    /**
+     * Where the stage writes (9.30.0): `['runs', runId]` for a run-namespaced
+     * stage, `[]` otherwise. Its containers are the stage's ADDRESS, not a value
+     * the stage reads (every read it makes is a key below it), so a shell a
+     * write leaves there is no part of the read-back the record must hold.
+     */
+    private readonly address;
+    /** `merge` ops staged since the last commit — see {@link admit}. */
+    private stagedMerges;
+    /** Ops staged deeper than one key below the stage's address — see {@link admit}. */
+    private nestedOps;
+    constructor(base: any, commitValues?: CommitValuesMode, readKeysProvider?: () => string[], address?: readonly string[]);
     /** Stamp the current read prefix onto a staged op — only when the
      *  provenance dial is on (provider present), so the default path allocates
      *  nothing and commit bundles stay byte-identical. */
     private stampReadKeys;
+    /** Stage an op into `opTrace`, counting what decides whether {@link admit} must fold. */
+    private stage;
     /**
      * Hard overwrite at the specified path. Stores the REFERENCE in both trees
      * (9.23.0) — the record's copy is taken once, at commit; see the header.
@@ -101,7 +184,15 @@ export declare class TransactionBuffer {
     delete(path: (string | number)[], shouldRedact?: boolean): void;
     /** Deep union merge at the specified path. `deepSmartMerge` builds fresh
      *  containers, so neither tree ever holds the merge INPUT by reference;
-     *  the nested-op detach guards the ancestor it writes INTO. */
+     *  the nested-op detach guards the ancestor it writes INTO.
+     *
+     *  The value merged INTO is made private first (`privatise`), as the
+     *  whole-state clone made it before 9.29.0. Not only for the reads that
+     *  follow: `deepSmartMerge` unions arrays BY REFERENCE, so whether an
+     *  element the stage passes in is "already there" depends on which objects
+     *  the base holds — a committed array would dedup an element the stage
+     *  read from it before its first write, where the private copy (and
+     *  9.28.0) appends it. */
     merge(path: (string | number)[], value: any, shouldRedact?: boolean): void;
     /**
      * Field-level redaction (9.19.0): mark dot-paths INSIDE the value staged at
@@ -113,14 +204,99 @@ export declare class TransactionBuffer {
      * (see {@link survivingRedactedPaths}).
      */
     markRedactedFields(path: (string | number)[], fields: readonly string[]): void;
+    /**
+     * Does a redaction mark address an array ELEMENT right below `path`
+     * (`list.1.token`)? An `append` row re-bases the indices onto the tail, so
+     * such a path takes the whole-value `set` (`deltaEncoding · pushValueRow`).
+     * A mark by NAME below an array (`obj.y`) means the same thing on the tail
+     * as on the whole value, so the compact row stays (byte-identical).
+     */
+    private markedBelow;
     /**
      * The redacted paths that survive the net-change filter: a path survives
      * when it IS a surviving op path (a whole-key redaction) or sits UNDER one
      * (a field inside a surviving write). A dropped op takes its fields with it.
      */
     private survivingRedactedPaths;
-    /** Read current value at path (includes uncommitted changes). */
+    /**
+     * Read current value at path (includes uncommitted changes). The value is
+     * the stage's own — private to it, as the whole-state clone made every read
+     * after the first write before 9.29.0 (`privatise`).
+     */
     get(path: (string | number)[], defaultValue?: any): any;
+    /**
+     * Read the working copy at `path` WITHOUT taking a private copy — for a
+     * reader that only compares (the dev-mode borrowed-mutation report in
+     * `StageContext.commit`), never for a value handed to a stage.
+     */
+    peek(path: (string | number)[]): unknown;
+    /**
+     * Keep the diff base exact under a read the working copy cannot answer.
+     *
+     * When `workingCopy` holds nothing at `path` — the stage deleted or unset
+     * it, or a write replaced a container above it — `StageContext ·
+     * readState` serves the read from LIVE committed state, exactly as 9.28.0
+     * did, so the value it hands out is committed state itself. On 9.28.0 the
+     * diff base was a whole-state clone taken at the stage's first write, and
+     * an in-place edit of that value (out of contract — reads are borrowed)
+     * could not move it: written back, the edit was recorded. Here the diff
+     * base IS a committed generation, and it very often holds that same
+     * container at `path` — the edit would move the base with it, and the
+     * write-back would commit no change. So before the value goes out, the
+     * base's value at `path` is replaced by a private deep copy (the base's
+     * root and the containers on the way copied shallowly) — what 9.28.0's
+     * base held there. The commit's net-change test compares against it and
+     * the delta encoder replays from it; the value handed out stays the live
+     * one, so whatever else an edit of it reaches (live state, the next
+     * generation) behaves as on 9.28.0 too.
+     *
+     * Not `privatise`: a private copy handed to the stage would also keep the
+     * edit out of live state, where 9.28.0 let it in — a run-namespaced read
+     * that falls back to a global key would then end differently (the
+     * differential's NESTED family fails within 100 programs that way).
+     *
+     * Copies nothing when the base holds no container at `path`, and nothing
+     * twice: a path at or below an earlier detach is already private. O(path)
+     * otherwise, plus O(value) once per detached path.
+     */
+    detachBase(path: (string | number)[]): void;
+    /**
+     * Private reads (9.29.0): make the value at `path` the stage's own before
+     * a read hands it out — so a read after the stage's first write behaves
+     * exactly as it did when the buffer began with a deep clone of the whole
+     * state. An in-place edit of what the read returned (out of contract —
+     * reads are borrowed) stays inside the buffer, and committed state is never
+     * touched. Whether the RECORD keeps it is the admitted record's law
+     * (9.30.0, owner ruling R1 — the record keeps what the stage read back): it
+     * is kept when the edited value lies at or below a path the stage wrote in
+     * this stage — set, merged or written back alike — and lost otherwise.
+     *
+     * Walking the path from the (owned) root:
+     *  - a container still SHARED with committed state at the same position is
+     *    replaced by a private deep copy when it is the value read, or by a
+     *    shallow copy when it is a container on the way to it (so a read of
+     *    `runs/<id>/k` copies `k`, not every run's namespace);
+     *  - a container the stage STAGED (or anything else the buffer did not
+     *    take from committed state) is handed back by reference, as before;
+     *  - a container the buffer owns is walked on — and when it is the value
+     *    read, its still-shared descendants are privatised
+     *    ({@link privatiseBelow}).
+     *
+     * Cost: O(path) per read, plus O(value) ONCE per shared container a stage
+     * reads after its first write. A stage that never reads after writing pays
+     * nothing; a read before the first write never reaches the buffer.
+     */
+    private privatise;
+    /**
+     * An OWNED container is about to be read whole (a path copy a nested write
+     * made, say): its descendants still shared with committed state are
+     * replaced by private deep copies, so nothing the read hands out is
+     * committed state. Walks owned containers only; marks each one finished
+     * ({@link privateTrees}), so a container is scanned once per stage.
+     */
+    private privatiseBelow;
+    /** A private deep copy of a committed container — owned through and through. */
+    private privateCopyOf;
     /**
      * Did any staged op touch `path`, or a path above or below it?
      *
@@ -204,14 +380,14 @@ export declare class TransactionBuffer {
      * Paths are compared at the exact granularity they were written (each trace
      * entry's path), against `workingCopy` (final) vs `baseSnapshot` (start).
      * Surviving `set` paths copy their final value from `overwritePatch`;
-     * surviving `merge` paths copy their accumulated delta from `updatePatch` —
-     * preserving the set-vs-merge verb so replay ({@link applySmartMerge}) is
-     * byte-for-byte identical to recording only the real changes.
+     * surviving `merge` paths copy their accumulated delta from `updatePatch`,
+     * keeping the set-vs-merge verb — and the result is ADMITTED ({@link admit}):
+     * a family of rows whose replay does not give back what the stage read is
+     * recorded as `set` rows of the read-back instead (9.30.0).
      *
-     * This is the DEFAULT (`commitValues: 'full'`) payload — byte-identical to
-     * the historical behavior, including flattening staged `delete` ops into
-     * `set`-of-`undefined` trace entries. The delta encoding lives in
-     * {@link toDeltaPayload}.
+     * This is the DEFAULT (`commitValues: 'full'`) payload, including the
+     * historical flattening of staged `delete` ops into `set`-of-`undefined`
+     * trace entries. The delta encoding lives in {@link toDeltaPayload}.
      *
      * Work, not bytes (9.22.1): the net-change verdict is paid once per PATH
      * and the clone once per CONSECUTIVE run of ops on a path, not once per op
@@ -222,6 +398,8 @@ export declare class TransactionBuffer {
      * place the record is detached from them.
      */
     private toChangeOnlyPayload;
+    /** The 'full' rows; a family in `lossy` is written as its read-back, at its last touch ({@link emitReadBack}). */
+    private changeOnlyRows;
     /**
      * Delta-encoded payload (`commitValues: 'delta'`, #13c-B) — same net-change
      * filter as {@link toChangeOnlyPayload}, three encoding differences:
@@ -240,40 +418,78 @@ export declare class TransactionBuffer {
      *      the `'full'` flattening (`_set` of `undefined`) COERCES that parent
      *      into an object; when they would disagree we keep the flattening;
      *    - ONLY `'merge'` ops → `merge` with the accumulated `updatePatch`
-     *      delta (replaying the accumulated delta once ≡ the full mode's
-     *      k sequential replays — `deepSmartMerge` is reference-idempotent
-     *      within one replay pass);
-     *    - otherwise (`set`/mixed): the committed value is computed by
-     *      replaying the path's op sequence EXACTLY the way `applySmartMerge`
-     *      replays the full-mode bundle ({@link replayPathVerbs}) — for
-     *      pure-set paths that is simply the last set value; for mixed
-     *      set+merge interleavings it reproduces the full mode's quirk of
-     *      applying the ACCUMULATED merge delta at every merge position
-     *      (which can differ from the buffer's read-your-writes view; parity
-     *      with the `'full'` mode's committed state is the contract). If base
-     *      and that value are arrays and base is a STRICT PREFIX → `append`
-     *      storing only the tail; else `set` storing the full value.
+     *      delta;
+     *    - otherwise (`set`/mixed): the value the stage's 'full' rows give the
+     *      path ({@link fullRowsValue}). If base and that value are arrays and
+     *      base is a STRICT PREFIX → `append` storing only the tail; else `set`
+     *      storing the full value.
      * 3. **OVERLAP FAMILIES take the full-value fallback.** `overwrite` /
      *    `updates` are nested path TREES, so two surviving paths where one is
-     *    an ancestor of the other (`a` and `a.p`) share storage. The `'full'`
-     *    payload survives that because every entry stores the FULL value at its
-     *    path, drawn from one coherent tree — nested entries agree with their
-     *    ancestor by construction. Delta's per-path encodings do NOT: an
-     *    `append` ancestor stores only a TAIL (whose indices are shifted
-     *    relative to the whole array) and a `delete` ancestor stores
-     *    `undefined`, so whichever entry is written second silently destroys or
-     *    corrupts the other — the recorded write is LOST at replay. Therefore
-     *    every path that has a surviving ancestor/descendant is committed as a
-     *    plain `set` of the value it holds in the family's replayed value
-     *    ({@link replayFamilyVerbs}), and the family's shallowest path (whose
-     *    set covers the whole subtree) is emitted LAST. One coherent tree in,
-     *    one coherent tree out: entries can no longer clobber each other and
-     *    the replayed value is exact regardless of order.
+     *    an ancestor of the other (`a` and `a.p`) share storage. Delta's
+     *    per-path encodings would clobber each other there (an `append`
+     *    ancestor stores only a TAIL, a `delete` ancestor `undefined`), so every
+     *    path that has a surviving ancestor/descendant is committed as a plain
+     *    `set` of the value the 'full' rows give it, and the family's
+     *    shallowest path (whose set covers the whole subtree) is emitted LAST.
      *
-     * Losslessness never depends on detection succeeding — every fallback is
-     * today's full-value `set`.
+     * The result is ADMITTED ({@link admit}) like the 'full' payload: a compact
+     * row is kept only where the bundle provably folds back, and a family that
+     * does not is recorded as what the stage read. So both encodings commit the
+     * value the stage read; before 9.30.0 they shared a replay that did not
+     * (`replayPathVerbs` / `replayFamilyVerbs`, deleted).
      */
     private toDeltaPayload;
+    /** The delta rows; a family in `lossy` is written as its read-back, at its last touch ({@link emitReadBack}). */
+    private deltaRows;
+    /**
+     * THE ADMISSION — a commit is admitted only if its bundle folds back to the
+     * stage's read-your-writes view at every path the stage touched. `build`
+     * lays the rows out (one encoder: `'full'` or `'delta'`); the candidate is
+     * checked ({@link lossyFamilies}), and when some family's rows do not fold
+     * back the rows are laid out again with those families written as what the
+     * stage read ({@link emitReadBack}) — every other family's bytes exactly as
+     * the first layout made them.
+     */
+    private admit;
+    /**
+     * The families whose rows do not fold back to what the stage read —
+     * `undefined` when there are none (`admission.ts · lossyFamilies`: the
+     * candidate replayed onto the diff base by `dryFold`, every family of
+     * touched paths compared with the working copy at its root and on the way
+     * down to it).
+     *
+     * Without a fold, when the stage staged no `merge` and no nested op: its
+     * rows are `set` / `delete` of keys directly under its address, each
+     * writing the SAME value into `workingCopy` and `overwritePatch` — the
+     * record is the read-back by construction (the property's ROOT-ONLY arm
+     * pins this). That keeps the commit of the typed scope's root-key writes
+     * exactly as cheap as it was.
+     */
+    private lossyFamilies;
+    /**
+     * A family whose rows did not fold back, written as what the stage read:
+     * one `set` row per member that changed (descendants by last touch, each
+     * with its own read prefix), the ROOT last, and the root's read-back value
+     * in `overwrite` — one coherent tree, so no row can clobber another. The
+     * root's row is written even when the root itself did not change: it is the
+     * row that carries the family's read-back (and the containers L-1's dropped
+     * op left). A lone root under `'delta'` keeps the compact `append` when the
+     * value it read is its base plus a tail.
+     */
+    private emitReadBack;
+    /**
+     * The value the stage's 'full' rows give a path — what the delta encoder
+     * commits for a family member or a path with a `set` — read from ONE
+     * {@link dryFold} of those rows over the patch trees themselves, taken the
+     * first time it is asked. By reference, as the stage held them: an element
+     * a `set` and a `merge` of one path share stays one element. A stage that
+     * staged no `merge` and no nested op needs no fold — a path's value is its
+     * last staged value. (Before 9.30.0: two replicas of the verb law,
+     * `replayPathVerbs` and `replayFamilyVerbs`.)
+     */
+    private fullRowsValue;
+    /** The stage's 'full' rows: every op on a path the net-change filter keeps, a `delete` spelled `set`. */
+    private fullRows;
     /**
      * Did the stage change the value at `segments`? Base and final value are
      * fixed at commit, so this is the ONE net-change verdict both payload
@@ -290,40 +506,6 @@ export declare class TransactionBuffer {
     private opsByPath;
     /** The net-change filter — identical to 'full' ({@link changedSinceBase}). Survivors keep last-touch order. */
     private netChangeSurvivors;
-    /** Replay each overlapping family ONCE, lazily — most commits have none, and pay nothing. */
-    private memoisedFamilyValue;
-    /**
-     * Bucket the staged ops of every OVERLAPPING family by family root, in op
-     * order — the input {@link replayFamilyVerbs} folds. Ops on paths the
-     * net-change filter dropped are skipped (they are absent from `rootOf`),
-     * exactly as the `'full'` payload drops them from its trace. One pass over
-     * `opTrace`, and only when at least one family actually overlaps — commits
-     * that write no nested path pay nothing.
-     */
-    private opsByFamily;
-    /**
-     * Replay ONE overlapping family's staged ops onto the family root's base
-     * value — the multi-path generalisation of {@link replayPathVerbs}, and
-     * byte-for-byte what `applySmartMerge` produces for the corresponding
-     * `'full'`-mode entries: each `set`/`delete` position writes that path's
-     * `overwritePatch` value, each `merge` position deep-merges that path's
-     * accumulated `updatePatch` delta into the value replayed so far.
-     *
-     * (Both patches are single coherent trees, so a full-mode bundle's stored
-     * value at any recorded path always reads back as its `overwritePatch` /
-     * `updatePatch` value — which is why sourcing from them here reproduces the
-     * full-mode replay exactly, including its intermediate-coercion quirks.)
-     *
-     * The value is held in a `{ v }` box so the root itself (relative path `[]`)
-     * can be REPLACED by `_set` the same way `applySmartMerge` replaces it
-     * inside the state tree — including `nativeSet`'s coercion of primitive
-     * intermediates.
-     *
-     * A `set` op the next op sets again is skipped on the same law as
-     * `applySmartMerge` ({@link supersededByNextSet}) — this is the delta
-     * encoder's own replay loop, and it clones per op just as the fold does.
-     */
-    private replayFamilyVerbs;
     /**
      * May a staged `delete` at this path commit as the `'delete'` verb?
      *
@@ -335,16 +517,4 @@ export declare class TransactionBuffer {
      * so those (pathological) deletes keep the historical flattening.
      */
     private deleteReplaysAsFlattening;
-    /**
-     * Replay ONE path's op-verb sequence against its base value, exactly the
-     * way `applySmartMerge` replays the corresponding full-mode bundle: every
-     * `set`/`delete` position applies the LAST staged overwrite value (the
-     * bag holds one value per path — last writer wins), every `merge`
-     * position applies the ACCUMULATED `updatePatch` delta. This reproduces
-     * the full mode's committed value for any interleaving — including the
-     * mixed set+merge quirk where the accumulated delta re-applies pre-set
-     * merge keys (full-mode replay semantics, kept for byte-parity across
-     * modes; property-tested in delta-replay-equivalence).
-     */
-    private replayPathVerbs;
 }