footprintjs 9.29.0 → 9.30.0

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

@@ -45,6 +45,22 @@
  * 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 {
@@ -111,11 +127,24 @@ export declare class TransactionBuffer {
      * at or below one is committed state, so a later detach inside it is a no-op.
      */
     private detachedBase?;
-    constructor(base: any, commitValues?: CommitValuesMode, readKeysProvider?: () => string[]);
+    /**
+     * 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.
@@ -175,6 +204,14 @@ 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
@@ -228,9 +265,11 @@ export declare class TransactionBuffer {
      * 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: it is lost unless the stage
-     * writes the value back, and then it is recorded; committed state is never
-     * touched.
+     * 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
@@ -341,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
@@ -359,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:
@@ -377,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
@@ -427,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?
      *
@@ -472,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;
 }