foottrace 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,521 @@
+/**
+ * TransactionBuffer — Per-stage STAGING buffer for state mutations
+ *
+ * What it IS: a staging buffer with read-your-writes and net-change commits.
+ * - Changes are staged here during stage execution and flushed to
+ *   SharedMemory in ONE batch per stage (`commit()`) — other stages and
+ *   parallel siblings never observe a stage's half-finished writes.
+ * - Read-after-write consistency within a stage — a stage sees its own
+ *   staged writes immediately.
+ * - `commit()` records the stage's NET change (see {@link commit}), plus an
+ *   operation trace for deterministic replay.
+ *
+ * What it is NOT: a rollback mechanism. Despite the name, there is no
+ * abort/rollback path — when a stage THROWS, the engine still commits
+ * everything staged so far before re-throwing (commit-on-error in
+ * `FlowchartTraverser`). That is deliberate: the audit trail must record
+ * what the failing stage changed. Do not rely on "stage failed → its
+ * writes vanished".
+ *
+ * The patch trees hold REFERENCES until commit (9.23.0). A `set` stores the
+ * caller's own value in `overwritePatch` exactly as it always did in
+ * `workingCopy`; the copy the record needs is taken ONCE per surviving path
+ * when the payload leaves the buffer (`toChangeOnlyPayload` /
+ * `toDeltaPayload` — every value they emit passes through `structuredClone`
+ * there). The law "the record never aliases a caller's object" is kept at
+ * the commit boundary instead of at every write, which is what makes N
+ * writes to one path O(N) instead of O(N × size). Consequence, by design: a
+ * caller who mutates its own object AFTER the write and BEFORE the stage
+ * ends commits the value as the stage read it back — the record agrees with
+ * the stage (CLAUDE.md landmine 3's first bite, closed). The one place the
+ * engine itself edits THROUGH a staged value — a later nested op under a
+ * `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 {
+    /**
+     * 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;
+    private opTrace;
+    private redactedPaths;
+    /**
+     * Paths whose `overwritePatch` value is the caller's own object (9.23.0):
+     * a `set` of a container stores the reference, and this is the ledger of
+     * which ones are still shared with the caller (and with `workingCopy`).
+     * Consulted only by the engine's nested ops — see
+     * {@link detachHeldAncestors}; the commit payload clones every surviving
+     * value anyway and never asks. Cleared with the rest at `commit()`.
+     */
+    private heldRefs;
+    /** Commit-value encoding policy (#13c-B). `'full'` = historical bytes. */
+    private readonly commitValues;
+    /** Per-write read-provenance source (#P1). When set (the
+     *  `writeProvenance: 'reads-prefix'` dial), every staged op snapshots the
+     *  keys tracked-read so far — the temporal-prefix attribution consumed by
+     *  causal slicing. Undefined (default) = zero cost, byte-identical ops. */
+    private readonly readKeysProvider?;
+    /**
+     * 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): a path prefix its frame computed and
+     * hands over as data (C2 — for the engine, the frame's run namespace, or
+     * `[]` for the root). 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.
+     */
+    set(path: (string | number)[], value: any, shouldRedact?: boolean): void;
+    /**
+     * A nested op is about to write THROUGH a path whose `overwritePatch`
+     * value is a held reference (9.23.0). Today's law is that the two trees
+     * receive the same nested `set`/`delete` mutations but ONLY `workingCopy`
+     * receives a nested `merge`'s result (`updatePatch` gets the delta) — so a
+     * container shared between the trees would leak the merged value into the
+     * overwrite payload, and a shared container is also the caller's own
+     * object, which the engine must not edit on the record's behalf. Replacing
+     * the held ancestor with its clone in `overwritePatch` restores exactly
+     * the private tree the per-write clone used to give it, paid once per
+     * ancestor and only on the nested-op path the public surface never takes
+     * (the scope proxy writes ROOT keys). `workingCopy` keeps the reference,
+     * as it always did.
+     */
+    private detachHeldAncestors;
+    /**
+     * Explicit key deletion at the specified path (#13c-B; absorbs backlog B8).
+     *
+     * Stages EXACTLY the same buffer mutations as `set(path, undefined)` —
+     * `workingCopy`/`overwritePatch` get an own `undefined` at the path (the
+     * historical flattening, preserving read behavior and the dedup diff base
+     * across modes) — but records the op verb as `'delete'`. At commit:
+     * `'full'` mode maps it back to a `'set'` trace entry (byte-identical to
+     * today); `'delta'` mode emits a real `'delete'` entry whose replay
+     * REMOVES the key instead of leaving `key: undefined` behind.
+     *
+     * The net-change filter reads that staged own `undefined` as ABSENT
+     * (`deepEqual`, 9.19.1) — so under `'delta'`, whose committed state really
+     * lacks the key, deleting an absent key inside a container the stage also
+     * re-wrote is the no-op it is, not a `set` of the whole container.
+     */
+    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 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
+     * `path` as secret, so `scrubPatch` scrubs them in the commit log and the
+     * mirror the same way a whole-key redaction is scrubbed. A field is
+     * registered as a literal key AND, when dotted, as the nested path it
+     * names — whichever exists in the patch is the one `scrubPatch` finds.
+     * Marked paths survive commit only while the op path they sit under does
+     * (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). 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 — `RecordFrame · read`
+     * 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
+     *    `k` under a fork child's address copies `k`, not every child'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?
+     *
+     * The dev-mode borrowed-read check (`StageContext.commit`) asks this before
+     * accusing a stage of mutating a value in place: a key the stage legitimately
+     * WROTE is expected to differ from what it read, and writes reach the buffer
+     * from paths that bypass user-level write tracking too (the subflow seed,
+     * `outputMapper` merge-back, the resume re-seed). Dev-mode only — nothing on
+     * the hot path calls it.
+     */
+    wasStaged(path: (string | number)[]): boolean;
+    /**
+     * Flush all staged mutations and return the commit bundle — recording the
+     * stage's NET CHANGE, not its raw write log.
+     *
+     * ── WHY (the defect this fixes) ─────────────────────────────────────────
+     * Previously every `set`/`merge` was recorded verbatim, so the commit bundle
+     * was a log of *operations* rather than *changes*. Two operations produce no
+     * net change yet were still committed as "mutations":
+     *
+     *   1. No-op write   — writing a key the value it already holds (e.g. an
+     *                      agent context slot re-emitting identical content every
+     *                      turn). base K=1, stage writes K=1.
+     *   2. Write-revert  — changing then restoring a key within one stage.
+     *                      base K=1, stage writes K=2 then K=1.
+     *
+     * Recording these as mutations (a) bloated causal slicing / backtracking with
+     * spurious dependencies on intermediate values that never reach final state,
+     * and (b) made downstream "what changed here?" consumers light up stages that
+     * changed nothing — most visibly the lens highlight flagging every slot.
+     *
+     * ── HOW ─────────────────────────────────────────────────────────────────
+     * At commit we hold BOTH `baseSnapshot` (state when the stage began) and
+     * `workingCopy` (state after all its writes). For each path the stage touched
+     * we keep it in the bundle ONLY if its final value differs from the base
+     * value ({@link deepEqual}). No-op AND write-revert paths drop out, because
+     * both compare equal to base. This is a single net-delta diff at commit time
+     * — one deep compare per touched path, O(changed state), paid once per stage
+     * (NOT per write). A naive per-write deep-equal skip would be more expensive
+     * and would still miss write-revert (the intermediate write differs from the
+     * value present at the moment of writing).
+     *
+     * ── TWO HONEST TIERS (by design — do not "unify" them) ──────────────────
+     *   • commit (here)   = CHANGE-level — truthful net delta. Feeds the commit
+     *                       log, causal chain, narrative, and the lens highlight.
+     *   • `onWrite` event = OP-level — fires on EVERY write attempt regardless of
+     *                       net change. Feeds metrics / behavioural observability
+     *                       (a debugger wants to see "wrote 2, then reverted").
+     * `onWrite` is unchanged by this method; only the COMMIT becomes change-only.
+     *
+     * ── EMPTY COMMITS ARE INTENTIONAL ───────────────────────────────────────
+     * A stage that nets no change commits an EMPTY patch — NOT nothing.
+     * {@link StageContext.commit} still records the bundle unconditionally, so
+     * every executed stage remains a time-travel cursor stop (its `runtimeStageId`
+     * marker is preserved); only its PATCH is empty. This is what keeps the
+     * commit-indexed slider stable while making the highlight truthful.
+     *
+     * ── KNOWN LIMITATIONS / FUTURE ──────────────────────────────────────────
+     *   • Explicit key DELETION under the default 'full' mode is still
+     *     flattened to set-of-`undefined` (a removed key cannot be expressed
+     *     in MemoryPatch alone). CLOSED under `commitValues: 'delta'` (#13c-B):
+     *     {@link delete} stages a distinct op and the bundle carries a real
+     *     `delete` trace verb whose replay removes the key.
+     *   • Array-merge dedup in {@link deepSmartMerge} still uses reference equality
+     *     (`new Set`), so deep-equal *objects* in a merged array are not deduped.
+     *     Orthogonal to this change; tracked separately.
+     *
+     * Resets the buffer to empty state after commit.
+     */
+    commit(): {
+        overwrite: MemoryPatch;
+        updates: MemoryPatch;
+        redactedPaths: Set<string>;
+        trace: TraceEntry[];
+    };
+    /**
+     * Rebuild overwrite / updates / trace keeping ONLY paths whose final value
+     * differs from the base value — i.e. the stage's net change. See
+     * {@link TransactionBuffer.commit} for the rationale.
+     *
+     * 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`,
+     * 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, 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
+     * — see the two memos inside. Pinned by
+     * test/lib/memory/scenario/repeated-path-byte-identity.test.ts against the
+     * 9.22.0 bytes. Since 9.23.0 that clone is THE clone: the patch trees hold
+     * the caller's references (see the class header), so this loop is the one
+     * 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:
+     *
+     * 1. **One trace entry per surviving path** (the §2.5 dedup rule — `append`
+     *    is NOT idempotent on replay, so duplicate entries would multiply
+     *    tails). The verb is resolved from the path's op mix + base→final
+     *    relationship; entries are ordered by each path's LAST touch,
+     *    preserving last-writer-wins for nested/overlapping paths.
+     * 2. **Verb resolution per path** — for a path with NO surviving relative
+     *    (see 3):
+     *    - last op `'delete'` AND final value gone → `delete` (the path stays
+     *      enumerated in `overwrite` with `undefined` for key-set consumers).
+     *      Requires the parent to be a real container in the base — replay uses
+     *      `nativeDelete`, which is inert on a primitive/absent parent, whereas
+     *      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;
+     *    - 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. 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.
+     *
+     * 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
+     * encodings apply (a no-op write and a write-then-revert both fail it).
+     */
+    private changedSinceBase;
+    /**
+     * Path → its op-verb sequence, ordered by LAST touch (delete + re-insert
+     * moves a re-touched path to the end of the Map's insertion order —
+     * preserving last-writer-wins for nested/overlapping paths). Per-write
+     * provenance (#P1): the LAST op's readKeys is kept — read prefixes only grow
+     * within a stage, so last == union across the path.
+     */
+    private opsByPath;
+    /** The net-change filter — identical to 'full' ({@link changedSinceBase}). Survivors keep last-touch order. */
+    private netChangeSurvivors;
+    /**
+     * May a staged `delete` at this path commit as the `'delete'` verb?
+     *
+     * Only when removing the key and the `'full'` mode's flattening (`_set` of
+     * `undefined`) land in the same place. They diverge when the parent is not
+     * a container: `nativeDelete` walks away untouched, while `nativeSet`
+     * COERCES the primitive parent into an object to hold the key. Committing
+     * `delete` there would silently drop a state change the stage really made,
+     * so those (pathological) deletes keep the historical flattening.
+     */
+    private deleteReplaysAsFlattening;
+}