foottrace 0.0.0-stage → 1.0.0

package/dist/types/lib/memory/backtrack.d.ts

@@ -0,0 +1,286 @@
+/**
+ * backtrack.ts — Backward causal chain analysis on the commit log.
+ *
+ * Implements **backward program slicing** (Weiser 1984, thin-slice variant):
+ * given a starting execution step, walk backwards through read→write
+ * dependencies to build the causal DAG that produced the data at that step.
+ *
+ * ## Algorithm
+ *
+ * BFS on the implicit dependency graph where edges run from reader → writer.
+ *
+ * 1. Locate startId in commitLog → root node
+ * 2. Get keysRead for root via `getKeysRead` callback
+ * 3. For each key read, find who last wrote it before this step → parent commit
+ *    ("wrote" is the writer rule of `keyPaths.ts`, 9.33.0: a row on the key, inside it, or
+ *    around it that changed it — so a stage that read `cfg` links to the subflow seed or
+ *    merge-back that wrote `cfg␟b`)
+ * 4. Create parent CausalNode, link to root.parents
+ * 5. Enqueue parent. Repeat until queue empty or limits hit.
+ *
+ * Output is a **DAG** (not a linked list): a stage reading `creditScore` AND `dti`
+ * from different writers has two parents.
+ *
+ * ## Staged Optimization
+ *
+ * Two writer-lookup strategies, chosen automatically by commit log size:
+ *
+ * | Strategy | When | Complexity per lookup |
+ * |----------|------|----------------------|
+ * | Linear scan | N ≤ 256 | O(N) — simple backward scan |
+ * | Reverse index | N > 256 | O(K log N) — prebuilt key→[indices], binary search |
+ *
+ * The threshold (256) is chosen so the O(N) build cost of the reverse index
+ * is amortized over the BFS traversal. Below 256, linear scan wins because
+ * there's no index build overhead. The consumer never sees this — `causalChain()`
+ * picks the right strategy internally (like a query optimizer choosing between
+ * sequential scan vs index scan based on table size).
+ *
+ * ## Complexity
+ *
+ * - **Small logs (N ≤ 256):** O(V × K × N) total. V=visited, K=avg keys/node.
+ * - **Large logs (N > 256):** O(N × U) index build + O(V × K × log N) lookups.
+ *   U = unique keys. Amortized over all BFS hops.
+ *
+ * ## References
+ *
+ * - Weiser, M. (1984). "Program Slicing." IEEE TSE.
+ * - Sridharan, M. et al. (2007). "Thin Slicing." PLDI.
+ *
+ * @example
+ * ```typescript
+ * import { causalChain, flattenCausalDAG, formatCausalChain } from 'foottrace';
+ *
+ * const dag = causalChain(commitLog, 'decide#2', (id) => recorder.getKeysRead(id));
+ * const flat = flattenCausalDAG(dag);     // BFS-ordered flat list
+ * console.log(formatCausalChain(dag));     // human-readable
+ * ```
+ */
+import type { RegisteredCode } from './honesty.js';
+import type { CommitBundle, UntrackedSource } from './types.js';
+/** A single node in the causal DAG. */
+export interface CausalNode {
+    /** Unique execution step identifier. */
+    runtimeStageId: string;
+    /** Stable stage identifier. */
+    stageId: string;
+    /** Human-readable stage name. */
+    stageName: string;
+    /** Keys this stage wrote (from its CommitBundle.trace). */
+    keysWritten: string[];
+    /** The key whose read→write dependency linked this node to its child. Empty for the root. */
+    linkedBy: string;
+    /** BFS depth from the starting node (0 = start). */
+    depth: number;
+    /**
+     * Parent nodes — stages this node depends on. DAG: multiple parents
+     * possible. KEPT for compatibility; with the `controlDeps` option
+     * (RFC-003 D3) governing deciders appear here too. For typed/keyed/
+     * weighted detail use {@link parentEdges}.
+     */
+    parents: CausalNode[];
+    /**
+     * RFC-003 D3 — one edge per dependency LINK (not per parent): a node
+     * reading two keys from the same writer has ONE entry in {@link parents}
+     * but TWO `'data'` edges here. Control dependencies (via the
+     * `controlDeps` option) add a `'control'` edge to the governing decider.
+     */
+    parentEdges: CausalEdge[];
+    /**
+     * RFC-003 D2 honesty marker — stamped from the stage's
+     * `CommitBundle.untrackedSources`. Present when this stage ALSO consumed
+     * untracked read paths (`args` / `env` / unshadowed `silent` reads): the
+     * backward slice through this node may be incomplete, because those reads
+     * produce no read→write edge to follow. `formatCausalChain` renders this
+     * as a `⚠ … slice may be incomplete here` line. Absent when the stage's
+     * reads were fully tracked.
+     *
+     * Registry code: `'incomplete-sources'` (`memory/honesty.ts ·
+     * HONESTY_CODES`, served on `foottrace`) says what this field
+     * means. The field carries no `code` — its values are the
+     * {@link UntrackedSource}s.
+     */
+    incompleteSources?: ReadonlyArray<UntrackedSource>;
+    /**
+     * RFC-003 D4 truncation visibility — set on the ROOT node only, and only
+     * when a limit actually cut the slice: `byDepth` when a node at the
+     * `maxDepth` horizon still had edges to expand, `byNodes` when the
+     * `maxNodes` budget blocked creating a discovered parent. Absent when the
+     * slice is complete. `formatCausalChain` appends a `⚠ slice truncated …`
+     * line — a consumer must never mistake a truncated slice for a full one.
+     * (Until 9.48.0 dev mode also warned on the console; the field is the
+     * signal, read it.)
+     *
+     * Registry code: `'truncated'` (`memory/honesty.ts · HONESTY_CODES`, served
+     * on `foottrace`) says what this field means; the field carries no
+     * `code`.
+     */
+    truncated?: {
+        byDepth: boolean;
+        byNodes: boolean;
+    };
+    /**
+     * F4b (9.33.0) — the keys this node read that NO commit before it wrote (under the writer rule), so the
+     * walk has no edge to follow for them: their value came from the initial state, frozen run input or a
+     * closure — outside the commit log. The code says so (`'pre-run-origin'`, registered in
+     * `memory/honesty.ts · HONESTY_CODES`); `keys` are in the order the walk met them. ABSENT when every key
+     * the node expanded had a writer, so such a node keeps its 9.32.0 shape. Before 9.33.0 these reads were
+     * dropped without a word.
+     */
+    preRunReads?: {
+        code: RegisteredCode<'pre-run-origin'>;
+        keys: string[];
+    };
+}
+/**
+ * RFC-003 D3 — a typed dependency edge from a child node to one parent.
+ *
+ * - `kind: 'data'`    — read→write dependency; `key` is the state key.
+ * - `kind: 'control'` — the parent is the decider/selector whose decision
+ *   allowed the child to run; `key` is the decide() rule label when present.
+ *
+ * `weight` defaults to 1.0; the `weigh` hook (RFC-003 D4) can override it.
+ * The engine itself NEVER computes weights — semantics belong to the
+ * consumer-injected weigher.
+ */
+export interface CausalEdge {
+    parent: CausalNode;
+    kind: 'data' | 'control';
+    key?: string;
+    weight: number;
+    /**
+     * F4b (9.33.0) — present only on a `'data'` edge whose parent wrote `key` ONLY through rows inside it
+     * (a subflow's input seed, an outputMapper merge-back, a fork child's namespace): that write made part
+     * of the value, and earlier writers may account for the rest. Registered as `'nested-rows'` in
+     * `memory/honesty.ts · HONESTY_CODES`. Absent for a write on or around the key, so an exact edge keeps
+     * its 9.32.0 shape.
+     */
+    basis?: RegisteredCode<'nested-rows'>;
+}
+/**
+ * RFC-003 D3 — a control dependency resolved for one execution step:
+ * which decider/selector execution allowed this stage to run.
+ */
+export interface ControlDependency {
+    /** runtimeStageId of the governing decider/selector execution step. */
+    deciderId: string;
+    /** The decide() rule label for the chosen branch, when present. */
+    label?: string;
+}
+/**
+ * RFC-003 D3 — callback resolving the governing decider for an execution
+ * step. Return `undefined` when the step is not control-dependent on any
+ * recorded decision. Build one with `controlDepRecorder()` from
+ * `footprintjs/trace`, or supply your own.
+ */
+export type ControlDepLookup = (runtimeStageId: string) => ControlDependency | undefined;
+/**
+ * RFC-003 D4 — consumer-injected edge weigher. Called once per created
+ * edge; return a weight, or `undefined` to keep the default 1.0. The
+ * ENGINE never computes weights (zero new dependencies — semantics like
+ * embedding similarity or FDL influence belong to downstream libraries,
+ * the same plug-in pattern as `NarrativeFormatter`). Weights render in
+ * `formatCausalChain` as `← via systemPrompt (0.18)`.
+ */
+export type EdgeWeigher = (child: CausalNode, parent: CausalNode, key: string | undefined, kind: 'data' | 'control') => number | undefined;
+/** Options for causalChain(). */
+export interface CausalChainOptions {
+    /** Maximum BFS depth (default: 20). Prevents runaway traversal. */
+    maxDepth?: number;
+    /** Maximum total nodes to visit (default: 100). Hard cap for safety. */
+    maxNodes?: number;
+    /**
+     * RFC-003 D3 — control-dependence lookup. When provided, expanding a node
+     * ALSO links a `'control'` edge to its governing decider (labeled by the
+     * decide() rule label when present); the decider node then expands
+     * normally through its own data reads, so chains like
+     * `status ← [control] ClassifyRisk ← [data: creditScore] PullBureau`
+     * resolve end-to-end. Without this option behavior is unchanged.
+     */
+    controlDeps?: ControlDepLookup;
+    /**
+     * RFC-003 D4 — edge weigher. Stamps `CausalEdge.weight` at edge creation;
+     * `undefined` (or no weigher) → 1.0. See {@link EdgeWeigher}.
+     */
+    weigh?: EdgeWeigher;
+    /**
+     * #P1 — how a node's expansion read-set is derived:
+     *
+     * - `'stage'` (default, historical) — every visited node expands through
+     *   ALL of its stage's reads (`getKeysRead`). A stage reading `a,b` and
+     *   writing `x,y` links both reads as causes of both writes — a sound but
+     *   coarse over-approximation.
+     * - `'per-write'` — when the commit log carries per-write read provenance
+     *   (`TraceEntry.readKeys`, recorded under the executor's
+     *   `writeProvenance: 'reads-prefix'` dial), a node reached via key `k`
+     *   expands through ONLY the reads that preceded its write of `k`
+     *   (temporal prefix). Nodes linked later via additional keys are
+     *   incrementally re-expanded with just the new reads (worklist — the
+     *   slice only ever GROWS toward the stage-level ceiling). HONEST
+     *   FALLBACK: any link whose trace entry lacks `readKeys` expands that
+     *   node at stage level — mixed or dial-off logs degrade to `'stage'`
+     *   behavior exactly, never to silence.
+     */
+    edgeAttribution?: 'stage' | 'per-write';
+    /**
+     * #P1 — the written keys that anchor the ROOT's expansion under
+     * `'per-write'` (e.g. `sliceForKey` passes the sliced key, so the root
+     * expands through the reads that fed THAT write, not the whole stage).
+     * Ignored under `'stage'`. Unset → root expands at stage level.
+     */
+    rootLinkKeys?: string[];
+}
+/**
+ * Callback that returns the keys a stage read during execution.
+ * The backtracker calls this for each visited node to determine
+ * which read→write edges to follow.
+ *
+ * Implementors: QualityRecorder tracks keysRead per step,
+ * or build a Map<runtimeStageId, string[]> from ScopeRecorder.onRead events.
+ */
+export type KeysReadLookup = (runtimeStageId: string) => string[];
+/**
+ * Build the causal DAG rooted at `startId` by walking backwards
+ * through read→write dependencies in the commit log.
+ *
+ * Automatically selects the optimal writer lookup strategy:
+ * - Linear scan for small logs (≤ 256 commits)
+ * - Reverse index with binary search for large logs (> 256 commits)
+ *
+ * Produces a DAG (not a tree): if two children both read from the same
+ * parent, the parent node is shared (deduped by runtimeStageId).
+ *
+ * @param commitLog   Ordered commit bundles from executor.getSnapshot().commitLog
+ * @param startId     runtimeStageId to start backtracking from
+ * @param getKeysRead Callback returning keys read by a given execution step
+ * @param options     Depth and node limits
+ * @returns Root CausalNode with .parents forming the DAG, or undefined if startId not found
+ */
+export declare function causalChain(commitLog: CommitBundle[], startId: string, getKeysRead: KeysReadLookup, options?: CausalChainOptions): CausalNode | undefined;
+/**
+ * Flatten the causal DAG into a BFS-ordered list of nodes.
+ * Each node appears exactly once (first occurrence by BFS order).
+ * Useful for linear display or iteration.
+ */
+export declare function flattenCausalDAG(root: CausalNode): CausalNode[];
+/**
+ * Format a causal DAG as human-readable indented text.
+ * Shows the dependency chain with depth indentation and linked-by keys.
+ *
+ * RFC-003 D2: nodes that consumed untracked read paths render an extra
+ * `⚠ also consumed … — slice may be incomplete here` line, so a consumer
+ * (human or LLM) debugging from the slice is TOLD when it is incomplete.
+ *
+ * RFC-003 D3: control edges render as `← [control: <rule label>]`
+ * (label omitted when the decision carried none). Data rendering is
+ * byte-identical to the pre-D3 output — `← via <key>` from the node's
+ * discovery-time `linkedBy`.
+ *
+ * RFC-003 D4: edge weights from the `weigh` hook render as a suffix —
+ * `← via systemPrompt (0.18)` — only when ≠ 1.0, so unweighted output is
+ * unchanged. A truncated slice (root.truncated) appends a final
+ * `⚠ slice truncated …` line.
+ */
+export declare function formatCausalChain(root: CausalNode): string;
+/** @internal Exposed for testing the strategy selection. */
+export declare const _REVERSE_INDEX_THRESHOLD = 256;

package/dist/types/lib/memory/commitLogUtils.d.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 type { RegisteredCode } from './honesty.js';
+import type { CommitBundle, CommitPhase } from './types.js';
+import { type Touch } from './verbs.js';
+/**
+ * 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 declare function findCommit(commitLog: CommitBundle[], stageId: string, key?: string): CommitBundle | undefined;
+/** Find all commits by stageId. */
+export declare function findCommits(commitLog: CommitBundle[], stageId: string): CommitBundle[];
+/**
+ * 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 declare function findLastWriter(commitLog: CommitBundle[], key: string, beforeIdx?: number): CommitBundle | undefined;
+/** What {@link writersOf} is asked. */
+export interface WritersOptions {
+    /** The last commit ARRAY index considered, inclusive. Default: the whole log. */
+    readonly end?: number;
+}
+/**
+ * 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 declare function writersOf(commitLog: readonly CommitBundle[], key: string, options?: WritersOptions): number[];
+/**
+ * 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 declare function rowsUnderRoot(commitLog: readonly CommitBundle[], key: string, end: number): Touch[];
+/**
+ * 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 declare function commitValueAt(commitLog: CommitBundle[], idx: number, key: string): unknown;
+/**
+ * Why {@link commitValueAtWithBasis} answered what it did. Each code is registered, with the one
+ * sentence that says what it means, in `memory/honesty.ts · HONESTY_CODES` (served on
+ * `foottrace`); the union declares its members through `RegisteredCode`.
+ *
+ * - `'never-written'`      — no commit in range wrote the key (the writer rule — the answer
+ *                            `findLastWriter` and the slice layer give), unless the run removed a value
+ *                            the passed `initialState` held (then `'deleted'`), or a redaction at or
+ *                            around the key hid the write (then `'redacted'` alone).
+ * - `'deleted'`            — the answer is `undefined` and the key WAS written: its last write left it
+ *                            absent.
+ * - `'nested-rows'`        — the value rests on rows INSIDE the key (a subflow seed, an outputMapper
+ *                            merge-back, a fork child's namespace) with no `set`/`delete` of the key or
+ *                            of a container around it in range.
+ * - `'from-initial-state'` — no `set`/`delete` of the key or around it in range, so the value rests on
+ *                            the pre-run base: folded from `options.initialState` when it holds the
+ *                            key's top-level key, partial when no `initialState` was passed.
+ * - `'redacted'`           — a path at, inside or around the key is in the `redactedPaths` of a commit
+ *                            the value rests on (from its last `set`/`delete` on, or the whole range).
+ */
+export type ValueBasis = RegisteredCode<'never-written' | 'deleted' | 'nested-rows' | 'from-initial-state' | 'redacted'>;
+/** What {@link commitValueAtWithBasis} is asked besides the log, the index and the key. */
+export interface ValueBasisOptions {
+    /**
+     * The state before the run — `RuntimeSnapshot.initialState` (or a subflow's
+     * `treeContext.initialState`). When given, a key with no `set`/`delete` in range folds from it, as
+     * `stateAt` does; when absent, such an answer is the log-only fold and carries `'from-initial-state'`.
+     */
+    readonly initialState?: Readonly<Record<string, unknown>>;
+}
+/** A key's value read off the log, and the codes that say what it rests on — absent codes = an exact answer. */
+export interface ValueWithBasis {
+    readonly value: unknown;
+    /** In the order of {@link ValueBasis}'s list; EMPTY when a `set`/`delete` of the key or around it anchors the value and no redaction touched it. */
+    readonly basis: ValueBasis[];
+}
+/**
+ * {@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 declare function commitValueAtWithBasis(commitLog: CommitBundle[], idx: number, key: string, options?: ValueBasisOptions): ValueWithBasis;
+/**
+ * Why {@link findLastWriterWithBasis} answered what it did — registered in `HONESTY_CODES`:
+ * `'never-written'` (no writer before the bound), `'nested-rows'` (the writer reached the key only
+ * through rows inside it, so it wrote part of the value), `'redacted'` (no writer the log can see, because a
+ * redaction at or around the key hid the write — the rule `commitValueAtWithBasis` follows).
+ */
+export type WriterBasis = RegisteredCode<'never-written' | 'nested-rows' | 'redacted'>;
+/** The last writer of a key, and the codes that say what kind of write it was — absent codes = a write on or around the key. */
+export interface WriterWithBasis {
+    /** Absent exactly when `basis` holds `'never-written'` or `'redacted'`. */
+    readonly writer?: CommitBundle;
+    readonly basis: WriterBasis[];
+}
+/**
+ * {@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 declare function findLastWriterWithBasis(commitLog: CommitBundle[], key: string, beforeIdx?: number): WriterWithBasis;
+/**
+ * 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 declare function buildCommitIndex(commitLog: readonly CommitBundle[]): Map<string, number>;
+/**
+ * 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 declare function recordsPhases(commitLog: readonly CommitBundle[]): boolean;
+/**
+ * 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 declare function inferLegacyPhases(commitLog: readonly CommitBundle[]): (CommitPhase | undefined)[];
+/**
+ * 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 declare function commitIndexOf(commitLog: readonly CommitBundle[], runtimeStageId: string): number;

package/dist/types/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/types/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';