foottrace 0.0.0-stage → 1.0.0

package/dist/esm/lib/memory/commitLogUtils.js

@@ -0,0 +1,383 @@
+/**
+ * Typed utilities for querying the commit log.
+ *
+ * The commitLog is an ordered array of CommitBundle — one per stage commit.
+ * These helpers provide type-safe queries without (b: any) casts.
+ */
+import { queryWork, relation, rootOf, writesOnlyInside } from './keyPaths.js';
+import { leavesStringAbove, logModel, memoisedModel } from './logModel.js';
+import { nativeGet } from './pathOps.js';
+import { DELIM } from './paths.js';
+import { foldKey, isTotal, isVerb, UnknownVerbError } from './verbs.js';
+// Every key query here follows the writer rule and the value rule of `keyPaths.ts` (F3, 9.33.0):
+// a key is written by a row ON it, INSIDE it, or AROUND it when that changed it — never by an
+// exact path match alone, which called every subflow seed and merge-back "never written". The
+// read model that answers them at a cost proportional to the answer is `logModel.ts`; a frozen
+// log's model is memoised, and a single question on a log that is not frozen first tries a
+// backward scan that stops at the answer.
+/**
+ * Find the first commit by `stageId`, optionally the first one that WROTE `key` — under the writer
+ * rule: a row on the key, inside it, or around it that changed it (see {@link writersOf}).
+ */
+export function findCommit(commitLog, stageId, key) {
+    if (!key)
+        return commitLog.find((b) => b.stageId === stageId);
+    const writers = new Set(logModel(commitLog).writersOf(key));
+    return commitLog.find((b, i) => b.stageId === stageId && writers.has(i));
+}
+/** Find all commits by stageId. */
+export function findCommits(commitLog, stageId) {
+    return commitLog.filter((b) => b.stageId === stageId);
+}
+/**
+ * Find the last commit that WROTE `key` before `beforeIdx` (exclusive; default: the whole log) —
+ * the anchor of every backward question ("who made it this?").
+ *
+ * The writer rule (`keyPaths.ts`): a commit writes `key` when one of its rows is ON the key,
+ * INSIDE it (a subflow's input seed writes `cfg␟a`; an outputMapper merge-back writes `cfg␟b`;
+ * either is a write of `cfg`), or AROUND it with the value at the key different across the commit
+ * (a `set` of `cfg` writes `cfg␟a`; a `merge` of `cfg` that never reaches `a` does not). A write
+ * found through a row INSIDE the key wrote only PART of its value — the slice readers say so with
+ * the `'nested-rows'` note.
+ *
+ * @param key  A DELIM-joined path (`normalisePath`); a top-level key is a one-segment path.
+ */
+export function findLastWriter(commitLog, key, beforeIdx) {
+    const end = Math.min(beforeIdx ?? commitLog.length, commitLog.length);
+    const model = memoisedModel(commitLog);
+    if (model !== undefined) {
+        const at = model.lastWriterBefore(key, end);
+        return at >= 0 ? commitLog[at] : undefined;
+    }
+    // Not frozen: scan back and stop at the first write on or inside the key. A row AROUND the key
+    // (or a nested `delete`, which cannot replace a string container) needs a verdict — the model's.
+    const nested = rootOf(key) !== key;
+    for (let i = end - 1; i >= 0; i--) {
+        let write = false;
+        let needsVerdict = false;
+        queryWork.units += commitLog[i].trace.length;
+        for (const t of commitLog[i].trace) {
+            const r = relation(t.path, key);
+            if (r === 'around')
+                needsVerdict = true;
+            else if (r !== undefined) {
+                if (t.verb !== 'delete' || !nested)
+                    write = true;
+                else
+                    needsVerdict = true;
+            }
+        }
+        if (write && (!needsVerdict || !leavesStringAbove(commitLog[i], key)))
+            return commitLog[i];
+        if (needsVerdict) {
+            const at = logModel(commitLog).lastWriterBefore(key, end);
+            return at >= 0 ? commitLog[at] : undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * The ARRAY positions (ascending) of every commit in `commitLog[0..end]` that WROTE `key` — the
+ * writer rule of `keyPaths.ts`, the one definition every key query shares (`logModel.ts` applies it).
+ */
+export function writersOf(commitLog, key, options = {}) {
+    const end = options.end ?? commitLog.length - 1;
+    return logModel(commitLog)
+        .writersOf(key)
+        .filter((i) => i <= end);
+}
+/**
+ * Every row under `key`'s TOP-LEVEL key in `commitLog[0..end]`, in commit order — the rows the value
+ * rule folds ({@link foldKey}), each with its {@link Touch.relation} to `key` (absent for a sibling
+ * under the same top-level key: applied, not observed) — found through the log's index. A row whose
+ * verb is not one of the four is refused with {@link UnknownVerbError} naming the row — whether or
+ * not the fold would have reached it: the answer must not depend on where an optimisation starts.
+ */
+export function rowsUnderRoot(commitLog, key, end) {
+    return logModel(commitLog).rowsUnderRoot(key, end);
+}
+/**
+ * Reconstruct the FULL value of `key` as of commit array index `idx`
+ * (inclusive) — the migration helper for the "read `bundle.overwrite[key]`
+ * as the full value written" pattern (#13c-B).
+ *
+ * The value rule (`keyPaths.ts`, 9.33.0): every row under the key's TOP-LEVEL
+ * key in `commitLog[0..idx]` is folded, anchored at that key's last `set` /
+ * `delete`, with the SAME step and clone discipline the replay uses
+ * (`verbs.ts` · `foldKey`), and the result is read at `key`. So the answer is
+ * the value `stateAt` gives at that path when it folds the log alone — rows
+ * INSIDE the key (a subflow seed, an outputMapper merge-back) and AROUND it (a
+ * `set` of the container) count; before 9.33.0 only rows on the exact path did,
+ * and a seeded `cfg` read as `undefined`. Under `commitValues: 'delta'`, an
+ * `append` row's `overwrite[key]` holds only the TAIL; the fold puts the array
+ * back together. Two `merge` rows of one bundle see one copy of the bundle's
+ * delta, as the replay's do.
+ *
+ * @param key  A DELIM-joined path (`normalisePath`); a top-level key is a
+ *   one-segment path.
+ * @param idx  CommitBundle ARRAY index (the `bundle.idx` position),
+ *   inclusive. NOT the executionIndex from a runtimeStageId.
+ * @returns The reconstructed value (a detached clone), or `undefined` when no
+ *   row in `commitLog[0..idx]` is on, inside or around the key, or the fold
+ *   leaves it absent (its last write was a delete). Caveat: a key that held a
+ *   value in the run's INITIAL state folds from absent here — the log alone
+ *   cannot see the pre-run base, so merges and nested writes onto a seeded key
+ *   give only what they added. Since 9.17.0 the base TRAVELS with the log:
+ *   `stateAt(snapshot, idx)` (foottrace) folds from
+ *   `RuntimeSnapshot.initialState`, which this function never receives.
+ * @throws {@link UnknownVerbError} when a row under the key's top-level key
+ *   carries a verb other than `set | merge | append | delete` — a foreign or
+ *   corrupted log is refused, not folded as a `merge`. Engine-written logs
+ *   never carry one.
+ * @see commitValueAtWithBasis — the same answer, with the codes that say WHY it is
+ *   `undefined` or partial (and the `initialState` base this function never receives).
+ */
+export function commitValueAt(commitLog, idx, key) {
+    const end = Math.min(idx, commitLog.length - 1);
+    const model = memoisedModel(commitLog);
+    if (model !== undefined)
+        return model.valueAt(key, end);
+    return valueByScan(commitLog, end, key);
+}
+const VALUE_BASIS_ORDER = [
+    'never-written',
+    'deleted',
+    'nested-rows',
+    'from-initial-state',
+    'redacted',
+];
+/**
+ * {@link commitValueAt}, with the codes that say what the answer rests on. Without `options.initialState`
+ * the value IS `commitValueAt(commitLog, idx, key)` (pinned by a property); with it, a key that has no
+ * `set`/`delete` of itself or of a container around it in range folds from that base — the value
+ * `stateAt(snapshot, idx)` gives at the key. Refuses an unknown verb exactly as `commitValueAt` does.
+ *
+ * @example
+ * ```typescript
+ * const { value, basis } = commitValueAtWithBasis(snap.commitLog, i, 'cfg', { initialState: snap.initialState });
+ * for (const code of basis) console.log(code, HONESTY_CODES[code]);
+ * ```
+ */
+export function commitValueAtWithBasis(commitLog, idx, key, options = {}) {
+    const end = Math.min(idx, commitLog.length - 1);
+    const model = logModel(commitLog);
+    const rows = model.rowsUnderRoot(key, end);
+    // The last `set`/`delete` ON the key or AROUND it decides the value alone; rows inside after it refine it.
+    let anchor = -1;
+    let inside = false;
+    let lastRelated;
+    for (let i = 0; i < rows.length; i++) {
+        const r = rows[i].relation;
+        if (r === undefined)
+            continue;
+        lastRelated = rows[i];
+        if (r === 'inside')
+            inside = true;
+        else if (isTotal(rows[i].verb)) {
+            anchor = i;
+            inside = false;
+        }
+    }
+    const root = rootOf(key);
+    const base = options.initialState;
+    const baseHoldsRoot = base !== undefined && Object.prototype.hasOwnProperty.call(base, root);
+    const value = anchor === -1 && baseHoldsRoot
+        ? foldKey(rows, key.split(DELIM), { anchored: true, start: structuredClone(base[root]) })
+        : model.valueAt(key, end);
+    const codes = new Set();
+    // The writer rule decides 'never-written' (as it does for `findLastWriter` and the slice layer), with two
+    // corrections only the base and the redaction list can make:
+    //   - the run REMOVED a value the passed base held (a `delete` — full mode spells it a `set` — or a `set` of
+    //     a container without the key): the log-only verdict sees absent → absent, the truth is 'deleted';
+    //   - a redaction at or around the key HID the write (a placeholder string replaced the container): the
+    //     log cannot say whether the key was written, so the answer says 'redacted' and nothing else about it.
+    const segs = key.split(DELIM);
+    const red = redactionsInRange(commitLog, key, anchor === -1 ? 0 : rows[anchor].commitIdx, end);
+    const deletedByRow = lastRelated !== undefined && lastRelated.relation !== 'inside' && lastRelated.verb === 'delete';
+    const baseHeldKey = base !== undefined && nativeGet(base, segs) !== undefined;
+    const removedFromBase = baseHeldKey && value === undefined && !red.any && (anchor !== -1 || deletedByRow);
+    const written = (end >= 0 && model.lastWriterBefore(key, end + 1) !== -1) || removedFromBase;
+    if (!written) {
+        if (!red.hidden)
+            codes.add('never-written');
+    }
+    else if (value === undefined && (deletedByRow || removedFromBase || !red.any))
+        codes.add('deleted');
+    if (anchor === -1 && inside)
+        codes.add('nested-rows');
+    if (anchor === -1 && (base === undefined || baseHoldsRoot))
+        codes.add('from-initial-state');
+    if (red.any)
+        codes.add('redacted');
+    return { value, basis: VALUE_BASIS_ORDER.filter((c) => codes.has(c)) };
+}
+/**
+ * The redacted paths of the commits in `[from, end]` against `key`: `any` — one at, inside or around it;
+ * `hidden` — one AT or AROUND it (a placeholder replaced the key or its container, so the write is hidden).
+ */
+function redactionsInRange(commitLog, key, from, end) {
+    let any = false;
+    for (let c = from; c <= end; c++) {
+        for (const p of commitLog[c].redactedPaths ?? []) {
+            const r = relation(p, key);
+            if (r === undefined)
+                continue;
+            any = true;
+            if (r !== 'inside')
+                return { any, hidden: true };
+        }
+    }
+    return { any, hidden: false };
+}
+/**
+ * {@link findLastWriter}, with the code that says why: `writer` is `findLastWriter(commitLog, key, beforeIdx)`;
+ * `basis` is `['never-written']` when there is none and `['nested-rows']` when that commit wrote the key
+ * only through rows inside it.
+ */
+export function findLastWriterWithBasis(commitLog, key, beforeIdx) {
+    const writer = findLastWriter(commitLog, key, beforeIdx);
+    if (writer === undefined) {
+        const end = Math.min(beforeIdx ?? commitLog.length, commitLog.length) - 1;
+        return { basis: [redactionsInRange(commitLog, key, 0, end).hidden ? 'redacted' : 'never-written'] };
+    }
+    return { writer, basis: writesOnlyInside(writer, key) ? ['nested-rows'] : [] };
+}
+/**
+ * {@link commitValueAt} on a log that is not frozen: refuse an unknown verb under the top-level key,
+ * then scan back from `end` to the last `set` ON the key, keeping the rows on and inside it — enough
+ * while nothing AROUND the key was written in between (and, for a nested key, no `delete` on it: a
+ * `delete` cannot replace a string container). Otherwise the model folds the top-level key.
+ */
+function valueByScan(commitLog, end, key) {
+    const root = rootOf(key);
+    for (let c = 0; c <= end; c++) {
+        const trace = commitLog[c].trace;
+        queryWork.units += trace.length;
+        for (let row = 0; row < trace.length; row++) {
+            const { path, verb } = trace[row];
+            if ((path === root || relation(path, root) === 'inside') && !isVerb(verb)) {
+                throw new UnknownVerbError(verb, { path, row, commit: c });
+            }
+        }
+    }
+    const nested = root !== key;
+    const rows = [];
+    let anchored = false;
+    for (let c = end; c >= 0 && !anchored; c--) {
+        const trace = commitLog[c].trace;
+        for (let row = trace.length - 1; row >= 0; row--) {
+            const { path, verb } = trace[row];
+            const r = relation(path, key);
+            if (r === undefined)
+                continue;
+            if (r === 'around' || (nested && r === 'exact' && verb === 'delete')) {
+                return logModel(commitLog).valueAt(key, end);
+            }
+            rows.push({ verb: verb, bundle: commitLog[c], commitIdx: c, path, relation: r });
+            if (r === 'exact' && (verb === 'set' || verb === 'delete')) {
+                anchored = true;
+                break;
+            }
+        }
+    }
+    if (rows.length === 0)
+        return undefined;
+    return foldKey(rows.reverse(), key.split(DELIM));
+}
+/**
+ * Position index over a commit log: `runtimeStageId` → the ARRAY INDEX of the
+ * FIRST bundle that stage committed. The map's insertion order is the order
+ * the stages first committed — execution order.
+ *
+ * "First" is the contract, and it is load-bearing. A stage normally commits
+ * exactly one bundle, but some executions commit more under one
+ * `runtimeStageId`: a subflow MOUNT (the merge-back, then the exit), a fork
+ * child (its own commit, then the fan-out's). Since 9.39.0 the WRITER names
+ * each continuation on the bundle (`CommitBundle.phase`: `'exit'` /
+ * `'repeat'`), and every continuation is written after the execution's own
+ * bundle — so "where does this stage start?" is the first bundle, and the
+ * grouping every reader's axis uses (`commitStops`) is this index. No reader
+ * tells a continuation from the log's shape.
+ *
+ * Build this ONCE when resolving many ids; use {@link commitIndexOf} for a
+ * single lookup.
+ *
+ * @param commitLog Ordered commit bundles — `getSnapshot().commitLog`.
+ * @returns A fresh Map, owned by the caller.
+ */
+export function buildCommitIndex(commitLog) {
+    const index = new Map();
+    for (let i = 0; i < commitLog.length; i++) {
+        const id = commitLog[i].runtimeStageId;
+        if (!index.has(id))
+            index.set(id, i);
+    }
+    return index;
+}
+/**
+ * Whether a log RECORDS phases — any bundle carries `phase` — i.e. it was
+ * written by 9.39.0 or later and holds at least one continuation. A log that
+ * does not either has no continuation at all, or predates the field (see
+ * {@link inferLegacyPhases}).
+ */
+export function recordsPhases(commitLog) {
+    for (const bundle of commitLog)
+        if (bundle.phase !== undefined)
+            return true;
+    return false;
+}
+/**
+ * THE LEGACY READER — the one place a continuation's phase is INFERRED, for a
+ * log written before 9.39.0 (which carries no `phase` anywhere). Returns the
+ * phase each bundle would have been stamped with, by the rule every reader
+ * applied through 9.38.0: a stage's bundle that IMMEDIATELY follows its first
+ * bundle is a mount's exit; any later bundle of the same `runtimeStageId` is
+ * a fork child's repeat; a first bundle is the stage's own (`undefined`).
+ *
+ * The rule is a guess, and the guess has a known miss — a single-child fork
+ * whose child is a leaf looks exactly like a mount — which is why a reader
+ * asks it only when the log records no phase AND it has no execution tree to
+ * ask instead (`commitStops`). A log that records phases is never inferred.
+ */
+export function inferLegacyPhases(commitLog) {
+    const phases = new Array(commitLog.length).fill(undefined);
+    const firstOf = new Map();
+    for (let i = 0; i < commitLog.length; i++) {
+        const id = commitLog[i].runtimeStageId;
+        if (!id)
+            continue;
+        const first = firstOf.get(id);
+        if (first === undefined)
+            firstOf.set(id, i);
+        else
+            phases[i] = i === first + 1 ? 'exit' : 'repeat';
+    }
+    return phases;
+}
+/**
+ * The ARRAY INDEX of the first commit a given `runtimeStageId` produced, or
+ * `-1` when that stage is not in this log (`indexOf` semantics — the name's
+ * promise).
+ *
+ * This is the address translation every reader needs and nobody exported: a
+ * `runtimeStageId` is the id an event carries, a commit index is what
+ * `commitValueAt` / `stateAt` / `CommitRangeIndex` speak. O(n) — for many
+ * lookups build the map once with {@link buildCommitIndex}.
+ *
+ * A stage that ran inside a SUBFLOW is not in the run-level log (subflows
+ * commit to their own isolated log); look it up in that subflow's own
+ * `history` instead — see `getSubtreeSnapshot`.
+ *
+ * @example
+ * ```typescript
+ * const idx = commitIndexOf(snapshot.commitLog, 'score-risk#7');
+ * const before = idx > 0 ? commitValueAt(snapshot.commitLog, idx - 1, 'risk') : undefined;
+ * ```
+ */
+export function commitIndexOf(commitLog, runtimeStageId) {
+    for (let i = 0; i < commitLog.length; i++) {
+        if (commitLog[i].runtimeStageId === runtimeStageId)
+            return i;
+    }
+    return -1;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * deltaEncoding.ts — the delta encoding's pure helpers (`commitValues:
+ * 'delta'`, #13c-B; docs/design/13c-b-delta-commit-verb.md), out of
+ * `TransactionBuffer` since 9.30.0: the overlap families of rule 3 and the
+ * order rows are emitted in (which now also places the admitted record's
+ * re-encoded families), the append detection, and the row that carries a
+ * value. The verb CHOICE stays in `TransactionBuffer · deltaRows`; nothing
+ * here replays the verb law.
+ */
+import type { Rows } from './admission.js';
+/** Op-level verbs staged into `opTrace`. `'delete'` is staged distinctly so
+ *  delta-mode commits (#13c-B) can emit a real `delete` trace entry; under
+ *  the default `'full'` mode it commits as `'set'` (of `undefined`) —
+ *  byte-identical to the historical flattening. */
+export type OpVerb = 'set' | 'merge' | 'delete';
+/** A path that passed the net-change filter, with everything the delta
+ *  encoder needs to decide its verb — resolved once, then reused by the
+ *  overlap-family grouping (`toDeltaPayload` rule 3). */
+export type Survivor = {
+    path: string;
+    segments: string[];
+    verbs: OpVerb[];
+    readKeys?: string[];
+    /** Index in `opTrace` of this path's last op (its last touch). */
+    last: number;
+    /** Value at this path when the stage began (the append/diff base). */
+    before: unknown;
+    /** Value at this path after every staged op (read-your-writes view). */
+    after: unknown;
+};
+/**
+ * A delta row carrying a VALUE: an `append` of the tail when `before` is a
+ * strict prefix of `value` ({@link isStrictArrayPrefix}), else a `set` of it.
+ * The value is cloned here — the one copy the record takes.
+ *
+ * `marked` — a redaction mark sits BELOW this path (`list.1.token`): its
+ * indices count from the start of the WHOLE array, and an `append` row holds
+ * only the tail, where `scrubPatch` would find no element 1 and leave the
+ * secret in the log and the redacted mirror. Such a path always takes the
+ * `set` of the whole value, where the mark lands (9.30.0; the same gap was
+ * open in 9.29.0 for a hard write of base + tail).
+ */
+export declare function pushValueRow(rows: Rows, path: string, segments: string[], before: unknown, value: unknown, prov: {
+    readKeys: string[];
+} | undefined, marked?: boolean): void;
+/**
+ * Group survivors into OVERLAP FAMILIES (`toDeltaPayload` rule 3): each path's
+ * family is keyed by its SHALLOWEST surviving ancestor — walking prefixes
+ * shallow first means the first hit is that root, and a depth-1 path (the
+ * common case) never enters the loop at all. Any two paths sharing a root
+ * are exactly the paths whose patch storage overlaps.
+ */
+export declare function groupIntoFamilies(survivors: Survivor[], survivingPaths: Set<string>): {
+    rootOf: Map<string, string>;
+    byRoot: Map<string, Survivor[]>;
+};
+/**
+ * Emit survivors in last-touch order, with one exception: in an overlapping
+ * family the ROOT is emitted LAST — its whole-subtree set is what makes the
+ * replayed subtree exactly the family value (a descendant applied afterwards
+ * could only re-state a value already inside it, but would also leave behind
+ * the `key: undefined` shells 'full' mode never has). `before(touch)` runs
+ * ahead of each survivor with that survivor's last touch — where the
+ * re-encoded families of the admitted record take their places.
+ */
+export declare function emitInFamilyOrder(survivors: Survivor[], rootOf: Map<string, string>, byRoot: Map<string, Survivor[]>, emit: (s: Survivor) => void, before: (touch: number) => void): void;

package/dist/esm/lib/memory/deltaEncoding.js

@@ -0,0 +1,121 @@
+/**
+ * deltaEncoding.ts — the delta encoding's pure helpers (`commitValues:
+ * 'delta'`, #13c-B; docs/design/13c-b-delta-commit-verb.md), out of
+ * `TransactionBuffer` since 9.30.0: the overlap families of rule 3 and the
+ * order rows are emitted in (which now also places the admitted record's
+ * re-encoded families), the append detection, and the row that carries a
+ * value. The verb CHOICE stays in `TransactionBuffer · deltaRows`; nothing
+ * here replays the verb law.
+ */
+import { nativeSet as _set } from './pathOps.js';
+import { deepEqual, DELIM } from './utils.js';
+/**
+ * A delta row carrying a VALUE: an `append` of the tail when `before` is a
+ * strict prefix of `value` ({@link isStrictArrayPrefix}), else a `set` of it.
+ * The value is cloned here — the one copy the record takes.
+ *
+ * `marked` — a redaction mark sits BELOW this path (`list.1.token`): its
+ * indices count from the start of the WHOLE array, and an `append` row holds
+ * only the tail, where `scrubPatch` would find no element 1 and leave the
+ * secret in the log and the redacted mirror. Such a path always takes the
+ * `set` of the whole value, where the mark lands (9.30.0; the same gap was
+ * open in 9.29.0 for a hard write of base + tail).
+ */
+export function pushValueRow(rows, path, segments, before, value, prov, marked = false) {
+    if (!marked && isStrictArrayPrefix(before, value)) {
+        rows.trace.push({ path, verb: 'append', ...prov });
+        _set(rows.overwrite, segments, structuredClone(value.slice(before.length)));
+    }
+    else {
+        rows.trace.push({ path, verb: 'set', ...prov });
+        _set(rows.overwrite, segments, structuredClone(value));
+    }
+}
+/**
+ * Group survivors into OVERLAP FAMILIES (`toDeltaPayload` rule 3): each path's
+ * family is keyed by its SHALLOWEST surviving ancestor — walking prefixes
+ * shallow first means the first hit is that root, and a depth-1 path (the
+ * common case) never enters the loop at all. Any two paths sharing a root
+ * are exactly the paths whose patch storage overlaps.
+ */
+export function groupIntoFamilies(survivors, survivingPaths) {
+    const rootOf = new Map();
+    const byRoot = new Map();
+    for (const s of survivors) {
+        let root = s.path;
+        for (let i = 1; i < s.segments.length; i++) {
+            const ancestor = s.segments.slice(0, i).join(DELIM);
+            if (survivingPaths.has(ancestor)) {
+                root = ancestor;
+                break;
+            }
+        }
+        rootOf.set(s.path, root);
+        const family = byRoot.get(root);
+        if (family)
+            family.push(s);
+        else
+            byRoot.set(root, [s]);
+    }
+    return { rootOf, byRoot };
+}
+/**
+ * Emit survivors in last-touch order, with one exception: in an overlapping
+ * family the ROOT is emitted LAST — its whole-subtree set is what makes the
+ * replayed subtree exactly the family value (a descendant applied afterwards
+ * could only re-state a value already inside it, but would also leave behind
+ * the `key: undefined` shells 'full' mode never has). `before(touch)` runs
+ * ahead of each survivor with that survivor's last touch — where the
+ * re-encoded families of the admitted record take their places.
+ */
+export function emitInFamilyOrder(survivors, rootOf, byRoot, emit, before) {
+    for (const s of survivors) {
+        before(s.last);
+        const root = rootOf.get(s.path);
+        const family = byRoot.get(root);
+        if (family.length === 1) {
+            emit(s);
+            continue;
+        }
+        if (s.path !== root)
+            emit(s);
+        if (family[family.length - 1] === s)
+            emit(family.find((m) => m.path === root));
+    }
+}
+/**
+ * Append-detection predicate (#13c-B §2.2): both values are arrays, the
+ * final is strictly longer, and the base is a structural prefix of the
+ * final. Element compares short-circuit on reference identity (`deepEqual`'s
+ * `===` fast path) before walking structure, and bail at the first mismatch
+ * — worst case one structural compare of the base array, strictly cheaper
+ * than the full-value `structuredClone` the fallback pays.
+ *
+ * `before === undefined` (first write) fails `Array.isArray` → `set`, which
+ * keeps the first write as the causal anchor for "who initialized this key".
+ *
+ * BOTH arrays must also be plain and dense ({@link isIndexOnly}): replay
+ * reconstructs an append as `[...current, ...tail]`, and that spread carries
+ * ONLY indexed elements — a named property parked on an array (a nested write
+ * like `set(['history','note'], …)`, which `nativeSet` happily hangs off the
+ * array object) or a hole would be silently dropped, where `'full'` mode
+ * stores the value whole and keeps it.
+ */
+function isStrictArrayPrefix(before, after) {
+    if (!Array.isArray(before) || !Array.isArray(after))
+        return false;
+    if (after.length <= before.length)
+        return false;
+    for (let i = 0; i < before.length; i++) {
+        if (!deepEqual(before[i], after[i]))
+            return false;
+    }
+    return isIndexOnly(before) && isIndexOnly(after);
+}
+/** True when an array's own enumerable keys are exactly its indices — no
+ *  extra named properties and no holes, i.e. the array survives a spread
+ *  intact. One `Object.keys` pass, same order as the prefix compare above
+ *  and paid only after it succeeds. */
+function isIndexOnly(arr) {
+    return Object.keys(arr).length === arr.length;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * equality.ts — structural equality of committed-state values: THE owner of
+ * "what counts as a change". What `TransactionBuffer`'s net-change filter, the
+ * admitted record's compare, the read model's writer rule and the
+ * borrowed-mutation guard all ask. Its one import is the classifier of value
+ * kinds (`capture/valueKinds.ts`, a leaf); re-exported from `utils.ts`, so no
+ * importer moved.
+ */
+/**
+ * Structural deep equality for committed-state values.
+ *
+ * Used by {@link TransactionBuffer} to decide whether a stage actually CHANGED
+ * a path or merely re-wrote / reverted it to the value it already held (a
+ * "no-op write"), and by `borrowedMutation.firstDifferingPath` to find where a
+ * borrowed read moved. Committed state must survive `structuredClone`, so the
+ * values it can hold are the kinds the clone keeps, and two values are equal
+ * when a record holds the same thing for both. Every kind has ONE arm below
+ * (`equalPairs`' switch over `ValueKind` — a kind added to the union does not
+ * compile until it is compared). Before 9.22.0 a Date, Map or Set was compared
+ * as an object with no own keys, and until 9.44.2 so were a RegExp, an Error,
+ * a boxed primitive, an ArrayBuffer, a DataView and a Blob: any two of a kind
+ * were "equal", so `$setValue('re', /y/g)` over `/x/g` committed no row and
+ * live state kept the OLD value.
+ *
+ * Semantics:
+ *   - reference / identical-primitive short-circuits first (cheap fast path)
+ *   - `NaN` equals `NaN` (primitive compare falls back to `Object.is`)
+ *   - two values of different KINDS are never equal (a `Date` is never `{}`,
+ *     an array never `{ 0: … }`)
+ *   - `Date`: same `getTime()` (two invalid dates are equal)
+ *   - `RegExp`: same `source` and `flags` (the clone resets `lastIndex`)
+ *   - `Error`: the same restored kind (one of the six built-in error names,
+ *     else `Error`), own `message`, `stack` and own `cause` (deep) — what the
+ *     clone keeps; any other own field is dropped by it, so it never counts
+ *     (the admitted record's law)
+ *   - a boxed primitive: the same wrapper type and the same primitive inside
+ *   - an `ArrayBuffer`: length, resizability and bytes; a typed array or a
+ *     `DataView`: its type and the bytes IT views — never the rest of its
+ *     buffer (a Node `Buffer` views a slice of a shared pool, and the record
+ *     keeps the view's bytes only: `capture/freeze.ts · freezeRecord`)
+ *   - `Map`: same size AND, per key of `a`, `b` holds a deep-equal value —
+ *     keys by `Map` identity (`SameValueZero`), values deep
+ *   - `Set`: same size AND every member of `a` is deep-equal to SOME member
+ *     of `b` (order-insensitive — a Set has no order to compare by)
+ *   - an OPAQUE value (a Blob, a `DOMException` — content this library cannot
+ *     read): by the caller's {@link OpaqueRule} — equal only to itself by
+ *     default (replacing one is always a change), or, when both sides are
+ *     copies of one record, equal to any other of its kind
+ *   - arrays: equal length AND deep-equal element-wise (order-sensitive; an
+ *     array's expando keys are out of contract and not compared)
+ *   - objects: identical set of keys that HOLD a value AND deep-equal per key.
+ *     An own key whose value is `undefined` counts as ABSENT: it is this
+ *     library's other spelling of a deleted key (`'full'` mode flattens
+ *     `delete` into `key: undefined`; `'delta'` mode's `delete` verb removes
+ *     the key), and every consumer — JSON, the fold, `commitValueAt`, the
+ *     mirror — reads the two spellings as one state. So must the net-change
+ *     filter (9.19.1): `{}` and `{ k: undefined }` are not a change. Arrays
+ *     are untouched — a slot holding `undefined` is still a slot.
+ *
+ * Cost & safety:
+ *   - Allocates only transient `Object.keys` arrays, an error's property
+ *     descriptors and a byte view per compared buffer — no clones (but one
+ *     probe clone per class prototype, remembered: `capture/valueKinds.ts ·
+ *     kindOf`). It is strictly cheaper than the `structuredClone` the commit
+ *     already performs.
+ *   - Primitive comparisons (the bulk of state) are O(1) via the `===` /
+ *     `Object.is` fast paths; only nested objects/arrays incur a walk, bounded
+ *     by the value's own size.
+ *   - Terminates on CYCLIC values (9.18.1): a state value must survive
+ *     `structuredClone`, and `structuredClone` preserves cycles — so a
+ *     self-referencing value is a legal value, not an out-of-contract one. A
+ *     pair of objects already under comparison is treated as equal (the
+ *     structural answer, lodash `isEqual` semantics); acyclic inputs see no
+ *     change. Dev mode still warns about cycles at write time
+ *     (`ScopeFacade.setValue`) because they surprise narrative and JSON.
+ */
+export declare function deepEqual(a: any, b: any, opaque?: OpaqueRule): boolean;
+/**
+ * How {@link deepEqual} compares two OPAQUE values (a Blob, a `DOMException` —
+ * content this library cannot read):
+ *
+ *   - `'identity'` (the default) — equal only to itself. The answer when one
+ *     side is a value a stage handed in: the net-change filter
+ *     (`TransactionBuffer`), the append check (`deltaEncoding`). A new object
+ *     is a change, because nothing can say it is not.
+ *   - `'copies'` — equal to any other of its kind. The answer when BOTH sides
+ *     are copies of one recorded value — a fold's generations (`logModel`,
+ *     `elementProvenance`), a retained read against live state
+ *     (`borrowedMutation`), the record replayed against the read-back
+ *     (`admission`): copies never share identity, so identity would call every
+ *     opaque value changed.
+ */
+export type OpaqueRule = 'identity' | 'copies';