foottrace 0.0.0-stage → 1.0.0

package/dist/lib/memory/utils.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * utils.ts — nested-object helpers for the heap, and the memory leaves' one
+ * re-export surface.
+ *
+ * The helpers here (`setNestedValue`, `updateNestedValue`, `updateValue`,
+ * `getNestedValue`) walk a nested object by path with
+ * prototype-pollution protection. Everything else this file used to hold has an
+ * owner of its own and is re-exported, so no importer moved: the path codec
+ * (`paths.ts`), structural equality (`equality.ts`) and the union merge
+ * (`merge.ts`) at L0, and the verb law (`verbs.ts`) at L1 — `applySmartMerge`,
+ * `nextGeneration`, `applySmartMergeInto`, `dryFold`, `supersededByNextSet`.
+ * The log's scrub, `redactPatch`, moved out in 9.33.0; it is the record's own, `scrub.ts` (C4).
+ * The writers take an ADDRESS, a path prefix their caller computed, and never
+ * name one (C2: the engine decides where a stage writes, `runAddress.ts · runAddress`).
+ * Zero external dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestedValue = exports.updateValue = exports.updateNestedValue = exports.setNestedValue = exports.isDeniedWritePath = exports.getRunAndGlobalPaths = exports.supersededByNextSet = exports.nextGeneration = exports.dryFold = exports.applySmartMergeInto = exports.applySmartMerge = exports.pathSegments = exports.normalisePath = exports.DELIM = exports.deepSmartMerge = exports.deepEqual = void 0;
+const ownData_js_1 = require("../capture/ownData.js");
+const pathOps_js_1 = require("./pathOps.js");
+var equality_js_1 = require("./equality.js");
+Object.defineProperty(exports, "deepEqual", { enumerable: true, get: function () { return equality_js_1.deepEqual; } });
+var merge_js_1 = require("./merge.js");
+Object.defineProperty(exports, "deepSmartMerge", { enumerable: true, get: function () { return merge_js_1.deepSmartMerge; } });
+var paths_js_1 = require("./paths.js");
+Object.defineProperty(exports, "DELIM", { enumerable: true, get: function () { return paths_js_1.DELIM; } });
+Object.defineProperty(exports, "normalisePath", { enumerable: true, get: function () { return paths_js_1.normalisePath; } });
+Object.defineProperty(exports, "pathSegments", { enumerable: true, get: function () { return paths_js_1.pathSegments; } });
+var verbs_js_1 = require("./verbs.js");
+Object.defineProperty(exports, "applySmartMerge", { enumerable: true, get: function () { return verbs_js_1.applySmartMerge; } });
+Object.defineProperty(exports, "applySmartMergeInto", { enumerable: true, get: function () { return verbs_js_1.applySmartMergeInto; } });
+Object.defineProperty(exports, "dryFold", { enumerable: true, get: function () { return verbs_js_1.dryFold; } });
+Object.defineProperty(exports, "nextGeneration", { enumerable: true, get: function () { return verbs_js_1.nextGeneration; } });
+Object.defineProperty(exports, "supersededByNextSet", { enumerable: true, get: function () { return verbs_js_1.supersededByNextSet; } });
+/**
+ * The two places a value at `path` can sit: under `address` (`runPath`, absent
+ * for the root address `[]`) and at the root (`globalPath`). `address` is a
+ * path prefix the caller computed — for the engine, a frame's run namespace
+ * (`runAddress.ts · runAddress`, C2), held by its record frame (`RecordFrame · address`, C3).
+ */
+function getRunAndGlobalPaths(address = [], path = []) {
+    return {
+        runPath: addressOf(address).length > 0 ? pathUnder(address, path) : undefined,
+        globalPath: [...path],
+    };
+}
+exports.getRunAndGlobalPaths = getRunAndGlobalPaths;
+/** An address is an array. A run id still passed in its place (C2) is refused, never spread into its characters. */
+function addressOf(address) {
+    if (Array.isArray(address))
+        return address;
+    throw new TypeError(`footprintjs: an address is an array path prefix, got ${address === null ? 'null' : typeof address}`);
+}
+/**
+ * `address` then `path`, as one new array. An index loop, because the double
+ * spread `[...address, ...path]` costs twice as much and a frame builds one on
+ * every read it serves from live state (a fork child reading a root key).
+ */
+function pathUnder(address, path) {
+    const out = new Array(address.length + path.length);
+    for (let i = 0; i < address.length; i++)
+        out[i] = address[i];
+    for (let i = 0; i < path.length; i++)
+        out[address.length + i] = path[i];
+    return out;
+}
+/**
+ * Refuse the WHOLE selector before creating a container or copying a generation.
+ * The address's array contract is checked even when another selector is denied.
+ * Payload keys are data, not selectors, and are deliberately not inspected.
+ * @internal Shared by the nested writers and SharedMemory's pre-copy boundary.
+ */
+function isDeniedWritePath(address = [], path = [], field) {
+    const prefix = addressOf(address);
+    return prefix.some(pathOps_js_1.isDeniedSegment) || path.some(pathOps_js_1.isDeniedSegment) || (0, pathOps_js_1.isDeniedSegment)(field);
+}
+exports.isDeniedWritePath = isDeniedWritePath;
+/**
+ * The container at `address` + `path` inside `obj`, each missing one created
+ * on the way: the one AT the address from `defaultValues` when given, every
+ * other one empty. The one walk both nested writers share.
+ */
+function containerAt(obj, address = [], path = [], defaultValues) {
+    const segments = pathUnder(addressOf(address), path);
+    let current = obj;
+    for (let i = 0; i < segments.length; i++) {
+        const key = segments[i];
+        if (!Object.prototype.hasOwnProperty.call(current, key)) {
+            (0, ownData_js_1.setOwnValue)(current, key, i === address.length - 1 && defaultValues ? defaultValues : {});
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Sets a value at a nested path under `address`, creating intermediate objects as needed.
+ * A denied address/path/field leaves `obj` unchanged, including its prototype.
+ */
+function setNestedValue(obj, address, path, field, value, defaultValues) {
+    if (isDeniedWritePath(address, path, field))
+        return obj;
+    (0, ownData_js_1.setOwnValue)(containerAt(obj, address, path, defaultValues), field, value);
+    return obj;
+}
+exports.setNestedValue = setNestedValue;
+/**
+ * Updates a value in the object at a nested path under `address`.
+ * A denied address/path/field leaves `obj` unchanged, including its prototype.
+ * - Arrays: concatenate
+ * - Objects: shallow merge at each level
+ * - Primitives: replace
+ */
+function updateNestedValue(obj, address, path, field, value, defaultValues) {
+    if (isDeniedWritePath(address, path, field))
+        return obj;
+    updateValue(containerAt(obj, address, path, defaultValues), field, value);
+    return obj;
+}
+exports.updateNestedValue = updateNestedValue;
+/**
+ * In-place value update with merge semantics.
+ * - Arrays (non-empty): concatenate onto existing
+ * - Arrays (empty):     direct replace — writing `[]` clears the field
+ * - Objects (non-empty): shallow merge (spread)
+ * - Objects (empty):    direct replace — writing `{}` clears the field
+ * - Primitives: direct assignment
+ *
+ * Note on empty arrays: both `value && Array.isArray(value)` and
+ * `Array.isArray(value)` evaluate the same for arrays — `[]` is truthy in
+ * JavaScript, so the `&&` guard was never the issue. The actual bug was the
+ * concat path: `[...cur, ...[]]` silently returned `cur` unchanged when `value`
+ * was `[]`, making `updateValue(obj, 'tags', [])` a no-op instead of a clear.
+ * The fix is the explicit `value.length === 0` early-return branch.
+ */
+function updateValue(object, key, value) {
+    if ((0, pathOps_js_1.isDeniedSegment)(key))
+        return;
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            (0, ownData_js_1.setOwnValue)(object, key, value); // clear: [] replaces whatever was there
+        }
+        else {
+            const cur = Object.prototype.hasOwnProperty.call(object, key) ? object[key] : undefined;
+            (0, ownData_js_1.setOwnValue)(object, key, cur === undefined ? value : [...cur, ...value]);
+        }
+    }
+    else if (value && typeof value === 'object' && Object.keys(value).length) {
+        const cur = Object.prototype.hasOwnProperty.call(object, key) ? object[key] : undefined;
+        (0, ownData_js_1.setOwnValue)(object, key, cur === undefined ? value : { ...cur, ...value });
+    }
+    else {
+        (0, ownData_js_1.setOwnValue)(object, key, value);
+    }
+}
+exports.updateValue = updateValue;
+/**
+ * Gets a value at a nested path with prototype-pollution protection.
+ */
+function getNestedValue(root, path, field) {
+    const node = path && path.length > 0 ? (0, pathOps_js_1.nativeGet)(root, path) : root;
+    if (field === undefined || node === undefined)
+        return node;
+    if (node !== null && typeof node === 'object' && Object.prototype.hasOwnProperty.call(node, field)) {
+        return node[field];
+    }
+    return undefined;
+}
+exports.getNestedValue = getNestedValue;

package/dist/lib/memory/verbs.js

@@ -0,0 +1,443 @@
+"use strict";
+/**
+ * verbs.ts — THE VERB LAW (L1): the one place a commit row becomes a value.
+ *
+ * A row of a commit bundle's `trace` carries one of four verbs —
+ * `set | merge | append | delete` — and ONE step turns it into a value:
+ * {@link applyVerb}. State is a left fold of that step (the event-sourcing
+ * reducer): {@link foldRows} folds one bundle's rows into a state, and
+ * {@link foldKey} folds ONE KEY across a log — every row under the key's
+ * top-level key, read at the key (the value rule, `keyPaths.ts`). Every reader
+ * of the log runs one of the two —
+ *
+ *   - the live commit and the redacted mirror (`nextGeneration`),
+ *   - the public replay (`applySmartMerge`), the read-side folds
+ *     (`applySmartMergeInto` — `EventLog.materialise`, `stateAt`) and the
+ *     admitted record's comparison (`dryFold`): all {@link foldRows},
+ *   - `commitValueAt`, and `arrayProvenance` as an OBSERVER of the same fold:
+ *     {@link foldKey}.
+ *
+ * Three questions that used to be answered once per reader are answered here
+ * once: what a verb does to the value before it ({@link applyVerb}), how the
+ * result is placed ({@link placeVerb}), and how the log's own values are
+ * treated on the way in (the clone discipline — a PARAMETER of the fold, see
+ * {@link Discipline} and {@link RecordedPayload}). A new verb is one new arm of
+ * `applyVerb` and one row of the traits table; the compiler refuses either
+ * missing ({@link isTotal}, {@link recordsTail}, {@link VERBS}).
+ *
+ * An UNKNOWN verb is refused with {@link UnknownVerbError}, never folded as a
+ * `merge` (the old silent default). Engine-written logs carry the four, so
+ * every engine run folds byte-for-byte as before.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.foldKey = exports.dryFold = exports.applySmartMergeInto = exports.nextGeneration = exports.applySmartMerge = exports.foldRows = exports.supersededByNextSet = exports.placeVerb = exports.applyVerb = exports.RecordedPayload = exports.ABSENT = exports.UnknownVerbError = exports.recordsTail = exports.isTotal = exports.isVerb = exports.VERBS = void 0;
+const merge_js_1 = require("./merge.js");
+const pathOps_js_1 = require("./pathOps.js");
+const paths_js_1 = require("./paths.js");
+/**
+ * The vocabulary: each verb with the two traits readers branch on, in the
+ * order the contract names them. A `Record` over the union — the compiler
+ * refuses a table that misses (or invents) a verb, so a verb cannot be added
+ * without saying what it is.
+ *
+ *   `total` — the row decides the value ALONE; it reads nothing from what came
+ *     before it ({@link isTotal}).
+ *   `tail`  — the row records ONLY what it adds, not the whole value
+ *     ({@link recordsTail}).
+ */
+const TRAITS = {
+    set: { total: true, tail: false },
+    merge: { total: false, tail: false },
+    append: { total: false, tail: true },
+    delete: { total: true, tail: false },
+};
+/** The four verbs, in the order the contract names them. */
+exports.VERBS = Object.freeze(Object.keys(TRAITS));
+/** Is `value` one of the four? The question every reader of a foreign log asks first. */
+function isVerb(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(TRAITS, value);
+}
+exports.isVerb = isVerb;
+/**
+ * Does the verb decide the value ALONE — read nothing from what came before
+ * it? `set` and `delete`. A reader that only needs the final value may start
+ * at the last such row ({@link foldKey} `anchored`); one that tracks how the
+ * value grew (provenance) starts at the first. Pinned against
+ * {@link applyVerb} itself, so a new verb cannot misreport it.
+ */
+function isTotal(verb) {
+    return TRAITS[verb].total;
+}
+exports.isTotal = isTotal;
+/**
+ * Does the row record ONLY what it adds — a tail — rather than the whole
+ * value? `append`. What the row added is then known exactly: a reader that
+ * tracks where array elements came from attributes them to this row without
+ * comparing arrays, where every other verb has to be inferred from.
+ */
+function recordsTail(verb) {
+    return TRAITS[verb].tail;
+}
+exports.recordsTail = recordsTail;
+/**
+ * Thrown by the readers of a commit log — {@link foldRows} (behind
+ * `applySmartMerge`), `commitValueAt`, `arrayProvenance` — when a row carries a
+ * verb outside {@link VERBS}: a foreign or corrupted log fails loudly instead
+ * of being replayed as a `merge`. `verb`, `path`, `row` and `commit` name the
+ * row (`path` / `row` / `commit` are absent when the caller handed over a
+ * bare verb); `path` is the trace's own DELIM-joined form — take it apart with
+ * `pathSegments`. The message quotes `verb` and `path`, so a hostile log cannot
+ * reshape it.
+ */
+class UnknownVerbError extends Error {
+    verb;
+    path;
+    row;
+    commit;
+    constructor(verb, site) {
+        const named = typeof verb === 'string' ? JSON.stringify(verb) : verb === undefined ? 'undefined' : `of type ${typeof verb}`;
+        // The verb and the path come from a log nobody vetted: quoted (JSON), so a
+        // control character in either cannot reshape the message.
+        const where = site === undefined
+            ? ''
+            : ` on trace row ${site.row} (path ${JSON.stringify((0, paths_js_1.pathSegments)(site.path).join(' › '))}${site.commit === undefined ? '' : `, commit ${site.commit}`})`;
+        const one = exports.VERBS.join(' | ');
+        super(`unknown verb ${named}${where}: a commit row is one of ${one} — the log is refused, not replayed as a merge`);
+        this.name = 'UnknownVerbError';
+        this.verb = verb;
+        if (site !== undefined) {
+            this.path = site.path;
+            this.row = site.row;
+            if (site.commit !== undefined)
+                this.commit = site.commit;
+        }
+    }
+}
+exports.UnknownVerbError = UnknownVerbError;
+function refuseVerb(verb) {
+    throw new UnknownVerbError(verb);
+}
+// ─── The step ────────────────────────────────────────────────────────────────
+/**
+ * What a `delete` row leaves behind: the KEY IS GONE — which is not the value
+ * `undefined` (a root replay removes the key; a per-path fold reads it as
+ * `undefined`). {@link applyVerb} returns it, {@link placeVerb} acts on it.
+ */
+exports.ABSENT = Symbol('footprintjs.verbs.absent');
+/**
+ * One bundle's recorded payload, read by path under a clone discipline — the
+ * values {@link applyVerb} reads out of the log.
+ *
+ * `detach` — `true` for every fold that keeps its result: a `set` value or an
+ * `append` tail is a clone of what the log holds and the merge delta comes from
+ * ONE detached copy of `updates`, so the result never aliases the log. `false`
+ * only for the comparison fold ({@link dryFold}), which places recorded values
+ * as recorded and drops its result.
+ *
+ * The delta is detached ONCE per bundle, lazily — a bundle with no `merge` row
+ * pays nothing. `deepSmartMerge` dedups an array union BY REFERENCE and two
+ * `merge` rows of one bundle replay the same accumulated delta, so the rows
+ * must keep seeing the same objects; a clone per row duplicated their elements
+ * (the differential caught it in the replay; `commitValueAt` carried the bug
+ * until it folded through here). `only` narrows the copy to ONE path — a
+ * per-path fold reads nothing else, and must not pay for the rest of the
+ * bundle.
+ */
+class RecordedPayload {
+    updates;
+    overwrite;
+    detach;
+    only;
+    deltas;
+    constructor(updates, overwrite, detach, only) {
+        this.updates = updates;
+        this.overwrite = overwrite;
+        this.detach = detach;
+        this.only = only;
+    }
+    /** What a `set` places and an `append` adds: `overwrite[path]`, cloned when detaching. */
+    value(segs) {
+        const recorded = (0, pathOps_js_1.nativeGet)(this.overwrite, segs);
+        return this.detach ? structuredClone(recorded) : recorded;
+    }
+    /** The accumulated merge delta at `path`: `updates[path]`, from the bundle's one copy. */
+    delta(segs) {
+        if (this.deltas === undefined) {
+            const source = this.only === undefined ? this.updates : atPath(this.updates, this.only);
+            this.deltas = this.detach ? structuredClone(source) : source;
+        }
+        return (0, pathOps_js_1.nativeGet)(this.deltas, segs);
+    }
+}
+exports.RecordedPayload = RecordedPayload;
+/** `tree` reduced to ONE path: that sub-tree, by reference, under fresh containers. */
+function atPath(tree, segs) {
+    const leaf = (0, pathOps_js_1.nativeGet)(tree, segs);
+    return leaf === undefined ? {} : (0, pathOps_js_1.nativeSet)({}, segs, leaf);
+}
+/**
+ * ONE row, ONE step: the value at the row's path AFTER the row, given the
+ * value BEFORE it and the bundle's recorded payload. THE verb law — no other
+ * function in the library has an arm per verb.
+ *
+ *   - `'set'`    — the recorded value (`overwrite[path]`, the full final value).
+ *   - `'merge'`  — `deepSmartMerge` of the accumulated `updates[path]` delta onto
+ *     the value before.
+ *   - `'append'` — (delta mode) `overwrite[path]` holds ONLY the tail: concatenate
+ *     it onto the value before. When either is not an array (an out-of-order
+ *     replay base, or a REDACTED tail — `scrubPatch` replaces matched payloads
+ *     with the `'REDACTED'` string) the tail BECOMES the value — the same
+ *     terminal value a redacted or corrupt `set` produces.
+ *   - `'delete'` — {@link ABSENT}: the key is removed. The path stays enumerated
+ *     in `overwrite` (value `undefined`) for key-set consumers; the step ignores
+ *     that value.
+ *
+ * Pure: it reads the payload and never writes. `verb` must be a {@link Verb}
+ * (the folds check with {@link isVerb} first and name the row); anything else
+ * that reaches it is refused with {@link UnknownVerbError}.
+ */
+function applyVerb(verb, before, at, segs) {
+    if (verb === 'set')
+        return at.value(segs);
+    if (verb === 'append') {
+        const tail = at.value(segs);
+        return Array.isArray(before) && Array.isArray(tail) ? [...before, ...tail] : tail;
+    }
+    if (verb === 'delete')
+        return exports.ABSENT;
+    if (verb === 'merge')
+        return (0, merge_js_1.deepSmartMerge)(before, at.delta(segs));
+    return refuseVerb(verb); // `verb` is `never` here — a fifth verb in the union stops compiling
+}
+exports.applyVerb = applyVerb;
+/** Put a step's value at its path in `out` — or remove the key, for {@link ABSENT}. */
+function placeVerb(out, segs, next) {
+    if (next === exports.ABSENT)
+        (0, pathOps_js_1.nativeDelete)(out, segs);
+    else
+        (0, pathOps_js_1.nativeSet)(out, segs, next);
+}
+exports.placeVerb = placeVerb;
+/**
+ * Is row `i` a `set` that the NEXT row sets again — same path, same verb — so
+ * that applying it is work the next row redoes?
+ *
+ * The one skip every replay iterator shares (9.22.1). A `set` row writes a
+ * clone of the recorded value at its path; the next row, a `set` of the same
+ * path, writes a clone of the SAME recorded value over it (the bundle's patch
+ * tree is fixed), and nothing runs in between — so the first write is
+ * unobservable, container creation and key order included. Only CONSECUTIVE
+ * rows qualify: a row in between (an ancestor `merge`, a sibling `set` that
+ * creates a container) can see the intermediate value, and a `merge`,
+ * `append` or `delete` next row depends on what is there. Rows are never
+ * dropped from the log — the 9.22.0 element-write funnel records N
+ * whole-array `set` rows on one path, and this is what makes replaying them
+ * O(N) instead of O(N × rows).
+ *
+ * Asked by {@link foldRows} — live state and the redacted mirror through
+ * {@link nextGeneration}, `EventLog.materialise` and `stateAt` through
+ * {@link applySmartMergeInto}, the public {@link applySmartMerge}, and the
+ * admitted record's {@link dryFold}. {@link foldKey} needs no skip: it
+ * anchors at the top-level key's LAST `set`/`delete`, or (provenance) a
+ * repeated `set` of the one recorded value changes no birth.
+ */
+function supersededByNextSet(rows, i) {
+    const row = rows[i];
+    if (row.verb !== 'set')
+        return false;
+    const next = rows[i + 1];
+    return next !== undefined && next.verb === 'set' && next.path === row.path;
+}
+exports.supersededByNextSet = supersededByNextSet;
+/** Does any row write THROUGH a container (a delimited, nested path)? */
+function hasNestedRow(rows) {
+    for (let i = 0; i < rows.length; i++)
+        if (rows[i].path.indexOf(paths_js_1.DELIM) !== -1)
+            return true;
+    return false;
+}
+/**
+ * Fold one bundle's rows into `out`, in place: for each row (a `set` the next
+ * row sets again is skipped — {@link supersededByNextSet}) take the step
+ * ({@link applyVerb}) and put its value where it belongs ({@link placeVerb}).
+ * `out` is the caller's — see {@link Discipline} for what it must be.
+ *
+ * A row whose verb is not one of {@link VERBS} stops the fold with
+ * {@link UnknownVerbError} naming the row; the rows before it have been
+ * applied, to a state the caller discards (every in-tree caller does).
+ */
+function foldRows(out, updates, overwrite, rows, discipline) {
+    const detach = discipline !== 'byReference';
+    const owned = discipline !== 'private' && hasNestedRow(rows) ? new WeakSet() : undefined;
+    (0, pathOps_js_1.own)(out, owned);
+    const at = new RecordedPayload(updates, overwrite, detach);
+    for (let i = 0; i < rows.length; i++) {
+        if (supersededByNextSet(rows, i))
+            continue;
+        const { path, verb } = rows[i];
+        if (!isVerb(verb))
+            throw new UnknownVerbError(verb, { path, row: i });
+        const segs = path.split(paths_js_1.DELIM);
+        if (owned !== undefined && segs.length > 1)
+            (0, pathOps_js_1.ownSpine)(out, segs, owned);
+        // A total verb reads nothing from what came before it (isTotal) — so the
+        // fold does not look.
+        const next = applyVerb(verb, isTotal(verb) ? undefined : (0, pathOps_js_1.nativeGet)(out, segs), at, segs);
+        // A value this fold CREATED is its own to edit in place; a recorded value
+        // placed by reference is the log's.
+        if (detach || verb === 'merge')
+            (0, pathOps_js_1.own)(next, owned);
+        placeVerb(out, segs, next);
+    }
+    return out;
+}
+exports.foldRows = foldRows;
+/**
+ * Applies a commit bundle to a base state by replaying operations in order.
+ * Guarantees "last writer wins" semantics.
+ *
+ * Returns a FULLY DETACHED result: the base is deep-cloned first and every
+ * value the replay writes is its own (`set` / `append` clone the recorded
+ * value; the `merge` arm reads a detached copy of `updates`), so the result
+ * shares no container with `base`, `updates` or `overwrite`. This is the
+ * public (`foottrace`) contract, unchanged by copy-on-write
+ * (9.29.0) — byte-identical to 9.28.0 for every caller. The engine's own
+ * commit does NOT come here: `SharedMemory.applyPatch` builds the next
+ * generation with `nextGeneration`, which copies only the written
+ * paths. Both run the ONE fold, {@link foldRows}; the verbs are
+ * {@link applyVerb}'s.
+ *
+ * Verb arms — see {@link applyVerb}. A row with any other verb throws
+ * {@link UnknownVerbError}.
+ *
+ * Work, not bytes (9.22.1): a `set` row the NEXT row re-sets is skipped
+ * ({@link supersededByNextSet}) — the rows stay in the log, only the clone
+ * each would have paid is not. Every consumer inherits the skip from
+ * `foldRows`; there is no second replay loop to keep in step.
+ */
+function applySmartMerge(base, updates, overwrite, trace) {
+    return foldRows(structuredClone(base), updates, overwrite, trace, 'private');
+}
+exports.applySmartMerge = applySmartMerge;
+/**
+ * The engine's commit (copy-on-write, 9.29.0 — docs/design/2026-10-copy-on-
+ * write-commit.md): the NEXT committed generation. A copy of `base`'s ROOT
+ * plus a copy of every container on each written path; every other subtree
+ * is SHARED with `base`, which is never edited — committed state is
+ * immutable-after-swap, so sharing is safe, and a commit costs O(what it
+ * wrote), not O(state). `SharedMemory.applyPatch` (live state and the
+ * redacted mirror) is its caller. Internal: the public replay is
+ * {@link applySmartMerge}.
+ */
+function nextGeneration(base, updates, overwrite, trace) {
+    return foldRows((0, pathOps_js_1.ownedRootOf)(base), updates, overwrite, trace, 'pathCopy');
+}
+exports.nextGeneration = nextGeneration;
+/**
+ * The same replay, INTO `target` — no clone of its own. For a caller that
+ * already holds a private working copy (the read-side folds: `stateAt` in
+ * `time-travel/stateAt.ts` and `EventLog.materialise` clone their base ONCE
+ * and then apply every bundle here), so a fold over N bundles costs N row
+ * applications, not N clones of the whole state. Never hand it committed
+ * state: it mutates the ROOT in place. Below the root it follows the live
+ * commit's law ({@link nextGeneration}) — a container this call did not
+ * create is copied before a write passes through it — so a fold and the live
+ * state give the same value at every path, aliased subtrees included.
+ * The values it writes are its own, so `target` never aliases the log.
+ */
+function applySmartMergeInto(target, updates, overwrite, trace) {
+    return foldRows(target, updates, overwrite, trace, 'pathCopy');
+}
+exports.applySmartMergeInto = applySmartMergeInto;
+/**
+ * The fold, for COMPARISON only (9.30.0 — the admitted record): `base` with
+ * the bundle replayed by the one verb law, copy-on-write below the root,
+ * every recorded value placed BY REFERENCE — no clone, so it costs what the
+ * bundle wrote and nothing more. It aliases the payload and every subtree of
+ * `base` the bundle did not write, and edits neither. Never hand it out,
+ * store it or write through it: `TransactionBuffer` builds one to ask whether
+ * a bundle folds back to what the stage read, then drops it.
+ */
+function dryFold(base, updates, overwrite, trace) {
+    return foldRows((0, pathOps_js_1.ownedRootOf)(base), updates, overwrite, trace, 'byReference');
+}
+exports.dryFold = dryFold;
+/**
+ * The value of ONE key after `touches` — EVERY row under its top-level key, in
+ * commit order, each already checked with {@link isVerb} — folded from an absent
+ * key, read at the key (`segs`, its DELIM segments): the value rule of
+ * `keyPaths.ts`, the fold `stateAt` does restricted to one top-level key. Top-level
+ * keys never interact under the step, so the restriction is exact.
+ *
+ * The same step ({@link applyVerb}) and the same discipline as {@link foldRows}'s
+ * `'pathCopy'`: `set` / `append` values are clones, the merge delta is detached
+ * once per BUNDLE (narrowed to the top-level key), so two `merge` rows of one
+ * bundle see the same objects, and a row that writes through a container this
+ * fold did not create copies it first. Returns `undefined` for an absent key.
+ * O(the rows under the key's top-level key), not O(the log).
+ */
+function foldKey(touches, segs, options = {}) {
+    const root = segs[0];
+    let from = 0;
+    if (options.anchored === true) {
+        for (let i = touches.length - 1; i >= 0; i--) {
+            if (isTotal(touches[i].verb) && touches[i].path === root) {
+                from = i;
+                break;
+            }
+        }
+    }
+    const state = {};
+    if (options.start !== undefined)
+        state[root] = options.start;
+    let owned = new WeakSet();
+    owned.add(state);
+    const observe = options.observe;
+    const generations = options.generations;
+    let kept = -1;
+    let keptBefore;
+    /** Drop ownership of every container: the next write through one copies it, so a kept value stays as it is. */
+    const release = () => {
+        owned = new WeakSet();
+        owned.add(state);
+    };
+    let at;
+    let atCommit = -1;
+    for (let i = from; i < touches.length; i++) {
+        const touch = touches[i];
+        if (at === undefined || touch.commitIdx !== atCommit) {
+            if (kept !== -1) {
+                generations.keep(kept, keptBefore, (0, pathOps_js_1.nativeGet)(state, segs));
+                kept = -1;
+                release();
+            }
+            if (generations !== undefined && generations.at(touch.commitIdx, state)) {
+                release();
+                kept = touch.commitIdx;
+                keptBefore = (0, pathOps_js_1.nativeGet)(state, segs);
+            }
+            at = new RecordedPayload(touch.bundle.updates, touch.bundle.overwrite, true, [root]);
+            atCommit = touch.commitIdx;
+        }
+        const rowSegs = touch.path === root ? [root] : touch.path.split(paths_js_1.DELIM);
+        const watched = observe !== undefined && (touch.relation !== undefined || options.everyRow === true);
+        let before;
+        if (watched) {
+            before = (0, pathOps_js_1.nativeGet)(state, segs);
+            if (touch.relation === 'inside' && Array.isArray(before))
+                before = before.slice();
+        }
+        if (rowSegs.length > 1)
+            (0, pathOps_js_1.ownSpine)(state, rowSegs, owned);
+        // A total verb reads nothing from what came before it (isTotal).
+        const next = applyVerb(touch.verb, isTotal(touch.verb) ? undefined : (0, pathOps_js_1.nativeGet)(state, rowSegs), at, rowSegs);
+        (0, pathOps_js_1.own)(next, owned);
+        placeVerb(state, rowSegs, next);
+        if (watched)
+            observe(touch, before, (0, pathOps_js_1.nativeGet)(state, segs));
+    }
+    if (kept !== -1)
+        generations.keep(kept, keptBefore, (0, pathOps_js_1.nativeGet)(state, segs));
+    return (0, pathOps_js_1.nativeGet)(state, segs);
+}
+exports.foldKey = foldKey;