foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,456 @@
+/**
+ * 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 { findLastWriter } from './commitLogUtils.js';
+import { queryWork, relation, writesOnlyInside } from './keyPaths.js';
+import { logModel } from './logModel.js';
+// ── Staged optimization: writer lookup strategies ──────────────────────
+/**
+ * Threshold for switching from linear scan to reverse index.
+ * Below this, O(N) scan is faster (no index build cost).
+ * Above this, O(log N) binary search wins.
+ */
+const REVERSE_INDEX_THRESHOLD = 256;
+/** Strategy 1: Linear scan — O(N) per lookup, zero setup cost. */
+function linearScanLookup(commitLog) {
+    return (key, beforeIdx) => findLastWriter(commitLog, key, beforeIdx);
+}
+/**
+ * Strategy 2: Reverse index — one O(rows) build, O(depth + log N) per lookup.
+ * The log's read model (`logModel.ts`: a path trie, each top-level key folded at
+ * most once) answers the writer rule — rows on, inside or around the key — by
+ * binary search for the last write on or inside it, then a verdict only for the
+ * around-candidates after it. The same answer `findLastWriter` gives, so the
+ * strategy switch below never changes a slice.
+ */
+function reverseIndexLookup(commitLog) {
+    const model = logModel(commitLog);
+    return (key, beforeIdx) => {
+        const at = model.lastWriterBefore(key, beforeIdx);
+        return at >= 0 ? commitLog[at] : undefined;
+    };
+}
+/**
+ * The trace entries of `commit` that make it a writer of `linkKey` — the entries whose read
+ * prefix (`TraceEntry.readKeys`) a per-write edge expands through. The FIRST entry on the exact
+ * path when there is one (the #P1 behaviour, unchanged); otherwise every entry inside or around
+ * the key (9.33.0: the commit wrote the key through a nested row — a subflow seed, an
+ * outputMapper merge-back — and all of those rows wrote it).
+ */
+function linkingEntries(commit, linkKey) {
+    const exact = commit.trace.find((t) => t.path === linkKey);
+    if (exact !== undefined)
+        return [exact];
+    return commit.trace.filter((t) => relation(t.path, linkKey) !== undefined);
+}
+/**
+ * Staged optimization: pick the right writer-lookup strategy based on data size.
+ *
+ * Like a database query optimizer choosing between sequential scan and index scan:
+ *
+ * - **Small log (≤ 256):** Linear scan wins. Zero setup cost, good cache locality.
+ *   The overhead of building a reverse index isn't worth it for short logs.
+ *
+ * - **Large log (> 256):** Reverse index wins. O(N×U) upfront build cost is amortized
+ *   across all BFS hops. Each lookup becomes O(log N) via binary search instead of O(N).
+ *   For an agent loop with 500 iterations and 5 keys per hop, this is 500×5×log(500)≈22K ops
+ *   vs 500×5×500=1.25M ops with linear scan.
+ *
+ * The caller never sees this — `causalChain()` picks automatically.
+ */
+function createWriterLookup(commitLog) {
+    if (commitLog.length <= REVERSE_INDEX_THRESHOLD) {
+        return linearScanLookup(commitLog);
+    }
+    return reverseIndexLookup(commitLog);
+}
+// ── Core algorithm ─────────────────────────────────────────────────────
+/**
+ * RFC-003 D2: the `incompleteSources` node fragment for a commit — `{}`
+ * when the stage consumed no untracked read paths, keeping the field
+ * ABSENT (not empty-array-valued) for fully-tracked stages.
+ */
+function incompleteSourcesFragment(commit) {
+    if (!commit.untrackedSources || commit.untrackedSources.length === 0)
+        return {};
+    return { incompleteSources: commit.untrackedSources };
+}
+/**
+ * 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 function causalChain(commitLog, startId, getKeysRead, options) {
+    const maxDepth = options?.maxDepth ?? 20;
+    const maxNodes = options?.maxNodes ?? 100;
+    const controlDeps = options?.controlDeps;
+    const weigh = options?.weigh;
+    const perWrite = options?.edgeAttribution === 'per-write';
+    // RFC-003 D4 — truncation visibility. Set only when a limit actually
+    // cuts the slice; surfaced on the root as `truncated` so a consumer can
+    // never mistake a truncated slice for a complete one.
+    let truncatedByDepth = false;
+    let truncatedByNodes = false;
+    // Build position index: runtimeStageId → array position (O(n) once)
+    const idxMap = new Map();
+    for (let i = 0; i < commitLog.length; i++) {
+        idxMap.set(commitLog[i].runtimeStageId, i);
+    }
+    queryWork.units += commitLog.length;
+    const startIdx = idxMap.get(startId);
+    if (startIdx === undefined)
+        return undefined;
+    const startCommit = commitLog[startIdx];
+    // Pick writer lookup strategy based on log size
+    const findWriter = createWriterLookup(commitLog);
+    // Node dedup map: runtimeStageId → CausalNode (ensures DAG, not tree)
+    const nodeMap = new Map();
+    const root = {
+        runtimeStageId: startId,
+        stageId: startCommit.stageId,
+        stageName: startCommit.stage,
+        keysWritten: startCommit.trace.map((t) => t.path),
+        linkedBy: '',
+        depth: 0,
+        parents: [],
+        parentEdges: [],
+        ...incompleteSourcesFragment(startCommit),
+    };
+    nodeMap.set(startId, root);
+    // ── #P1 per-write attribution machinery (inert under 'stage') ──────────
+    // expandedReads: per node, the reads already queued for expansion — late
+    // links via additional keys re-enqueue only the DELTA, so the slice grows
+    // monotonically toward the stage-level ceiling and terminates (each key
+    // expands at most once per node). fullyExpanded: nodes that fell back to
+    // stage level (no readKeys on a linking entry) — nothing left to add.
+    const expandedReads = new Map();
+    const fullyExpanded = new Set();
+    /**
+     * Resolve a node's expansion read-set for the given linking WRITTEN keys.
+     * Per-write mode with provenance present → union of the linking writes'
+     * temporal-prefix `readKeys`. Any linking entry WITHOUT `readKeys` (or no
+     * linkKeys at all) → honest stage-level fallback, flagged via the second
+     * tuple member so the caller marks the node fully expanded.
+     */
+    function readsForLinks(commit, linkKeys) {
+        if (!perWrite || !linkKeys || linkKeys.length === 0) {
+            return [getKeysRead(commit.runtimeStageId), true];
+        }
+        const union = new Set();
+        for (const linkKey of linkKeys) {
+            const entries = linkingEntries(commit, linkKey);
+            if (entries.length === 0 || entries.some((e) => e.readKeys === undefined)) {
+                // Mixed/dial-off log — degrade THIS node to stage level, honestly.
+                return [getKeysRead(commit.runtimeStageId), true];
+            }
+            for (const entry of entries)
+                for (const rk of entry.readKeys)
+                    union.add(rk);
+        }
+        return [[...union], false];
+    }
+    // BFS/worklist queue: [node, commitIdx, depth, keysToExpand]
+    const [rootReads, rootIsFull] = perWrite
+        ? readsForLinks(startCommit, options?.rootLinkKeys)
+        : [getKeysRead(startId), true];
+    expandedReads.set(startId, new Set(rootReads));
+    if (rootIsFull)
+        fullyExpanded.add(startId);
+    const queue = [[root, startIdx, 0, rootReads]];
+    let visited = 1;
+    /**
+     * Link `node → parent` (creating + enqueueing the parent when new).
+     * Shared by data-edge expansion (read→write) and control-edge expansion
+     * (D3). One CausalEdge per distinct (parent, kind, key) link; `parents`
+     * keeps its historical one-entry-per-parent dedup.
+     */
+    function linkParent(node, parentCommit, kind, key, depth) {
+        const parentId = parentCommit.runtimeStageId;
+        // the dedup scans below, and the parent's trace when it is new — counted for the scaling test
+        queryWork.units += 1 + node.parents.length + node.parentEdges.length;
+        // #P1: the parent's expansion reads, resolved LAZILY (only for new nodes
+        // or per-write re-expansion — duplicate links under 'stage' pay nothing).
+        // Data links expand through the reads that fed the parent's write of
+        // `key`; control links expand the decider at stage level (a decision
+        // depends on everything it read).
+        const resolveLinkReads = () => kind === 'data'
+            ? readsForLinks(parentCommit, key !== undefined ? [key] : undefined)
+            : [getKeysRead(parentId), true];
+        let parentNode = nodeMap.get(parentId);
+        if (!parentNode) {
+            // New node — create and enqueue (respecting the node budget)
+            if (visited >= maxNodes) {
+                truncatedByNodes = true; // D4: a discovered parent was dropped
+                return;
+            }
+            const parentIdx = idxMap.get(parentId);
+            if (parentIdx === undefined)
+                return;
+            queryWork.units += parentCommit.trace.length;
+            parentNode = {
+                runtimeStageId: parentId,
+                stageId: parentCommit.stageId,
+                stageName: parentCommit.stage,
+                keysWritten: parentCommit.trace.map((t) => t.path),
+                // linkedBy stays a DATA-key concept (back-compat) — control-linked
+                // nodes carry their label on the edge instead.
+                linkedBy: kind === 'data' ? key ?? '' : '',
+                depth: depth + 1,
+                parents: [],
+                parentEdges: [],
+                ...incompleteSourcesFragment(parentCommit),
+            };
+            nodeMap.set(parentId, parentNode);
+            visited++;
+            const [linkReads, linkIsFull] = resolveLinkReads();
+            expandedReads.set(parentId, new Set(linkReads));
+            if (linkIsFull)
+                fullyExpanded.add(parentId);
+            queue.push([parentNode, parentIdx, depth + 1, linkReads]);
+        }
+        else if (perWrite && !fullyExpanded.has(parentId)) {
+            // #P1 worklist: an EXISTING node linked via another key may owe more
+            // expansion — enqueue only the reads not yet expanded (monotone; the
+            // node budget is untouched, no node is created). Re-expansion keeps
+            // the node's ORIGINAL depth so its parents get a consistent depth+1.
+            const [linkReads, linkIsFull] = resolveLinkReads();
+            const expanded = expandedReads.get(parentId);
+            const delta = linkReads.filter((k) => !expanded.has(k));
+            if (linkIsFull)
+                fullyExpanded.add(parentId);
+            if (delta.length > 0) {
+                for (const k of delta)
+                    expanded.add(k);
+                const parentIdx = idxMap.get(parentId);
+                if (parentIdx !== undefined)
+                    queue.push([parentNode, parentIdx, parentNode.depth, delta]);
+            }
+        }
+        // DAG merge: one parents[] entry per distinct parent (historical shape)
+        if (!node.parents.some((p) => p.runtimeStageId === parentId)) {
+            node.parents.push(parentNode);
+        }
+        // One edge per distinct (parent, kind, key) link. The weigher (D4)
+        // stamps the weight at creation; `undefined` → 1.0 — the engine never
+        // computes weights itself.
+        if (!node.parentEdges.some((e) => e.parent.runtimeStageId === parentId && e.kind === kind && e.key === key)) {
+            // Error isolation (review finding): a consumer weigher that throws
+            // must degrade to the default weight, never crash the slice — the
+            // same contract every other consumer callback in the library gets.
+            let weight = 1.0;
+            if (weigh) {
+                try {
+                    weight = weigh(node, parentNode, key, kind) ?? 1.0;
+                }
+                catch {
+                    /* weigher threw — keep 1.0, the slice stays usable */
+                }
+            }
+            const nested = kind === 'data' && key !== undefined && writesOnlyInside(parentCommit, key);
+            node.parentEdges.push({
+                parent: parentNode,
+                kind,
+                key,
+                weight,
+                ...(nested && { basis: 'nested-rows' }),
+            });
+        }
+    }
+    while (queue.length > 0) {
+        const [node, commitIdx, depth, keysToExpand] = queue.shift();
+        queryWork.units += 1 + keysToExpand.length;
+        if (depth >= maxDepth) {
+            // D4: only a node that still HAD something to expand counts as a cut
+            // (a leaf at the horizon truncates nothing).
+            if (keysToExpand.length > 0 || controlDeps?.(node.runtimeStageId) !== undefined) {
+                truncatedByDepth = true;
+            }
+            continue;
+        }
+        // Data edges: for each key in this expansion's read-set, find who wrote
+        // it. Under 'stage' this is the node's full read-set (historical
+        // behavior); under 'per-write' it is the linking writes' temporal prefix
+        // (or a worklist delta on re-expansion).
+        const keysRead = keysToExpand;
+        for (const key of keysRead) {
+            const writer = findWriter(key, commitIdx);
+            if (!writer) {
+                // F4b: say why there is no edge — no commit before this node wrote the key.
+                node.preRunReads ??= { code: 'pre-run-origin', keys: [] };
+                if (!node.preRunReads.keys.includes(key))
+                    node.preRunReads.keys.push(key);
+                continue;
+            }
+            linkParent(node, writer, 'data', key, depth);
+        }
+        // Control edge (RFC-003 D3): link the governing decider, labeled by the
+        // decide() rule label when present. The decider node then expands
+        // normally through its own data reads (and its own control parent).
+        if (controlDeps) {
+            const dep = controlDeps(node.runtimeStageId);
+            if (dep) {
+                const deciderIdx = idxMap.get(dep.deciderId);
+                if (deciderIdx !== undefined) {
+                    linkParent(node, commitLog[deciderIdx], 'control', dep.label, depth);
+                }
+            }
+        }
+    }
+    // RFC-003 D4 — truncation visibility on the root (absent when complete). It is DATA, and only
+    // data: a reader reads `root.truncated` (and `formatCausalChain` prints it); the record writes no
+    // console line (the dev-mode warning went in C6 — the record imports nothing outside itself).
+    if (truncatedByDepth || truncatedByNodes) {
+        root.truncated = { byDepth: truncatedByDepth, byNodes: truncatedByNodes };
+    }
+    return root;
+}
+// ── Utilities ──────────────────────────────────────────────────────────
+/**
+ * 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 function flattenCausalDAG(root) {
+    const result = [];
+    const visited = new Set();
+    const queue = [root];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (visited.has(node.runtimeStageId))
+            continue;
+        visited.add(node.runtimeStageId);
+        result.push(node);
+        for (const parent of node.parents) {
+            if (!visited.has(parent.runtimeStageId)) {
+                queue.push(parent);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 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 function formatCausalChain(root) {
+    const lines = [];
+    const visited = new Set();
+    const weightSuffix = (edge) => edge !== undefined && edge.weight !== 1 ? ` (${edge.weight})` : '';
+    function walk(node, indent, edgesFromChild) {
+        if (visited.has(node.runtimeStageId)) {
+            lines.push(`${'  '.repeat(indent)}↳ ${node.runtimeStageId} (see above)`);
+            return;
+        }
+        visited.add(node.runtimeStageId);
+        const linkParts = [];
+        if (node.linkedBy) {
+            const dataEdge = edgesFromChild?.find((e) => e.kind === 'data');
+            linkParts.push(`via ${node.linkedBy}${weightSuffix(dataEdge)}`);
+        }
+        const controlEdge = edgesFromChild?.find((e) => e.kind === 'control');
+        if (controlEdge) {
+            linkParts.push(`[control${controlEdge.key ? `: ${controlEdge.key}` : ''}]${weightSuffix(controlEdge)}`);
+        }
+        const link = linkParts.length > 0 ? ` ← ${linkParts.join(' ← ')}` : '';
+        const writes = node.keysWritten.length > 0 ? ` [wrote: ${node.keysWritten.join(', ')}]` : '';
+        lines.push(`${'  '.repeat(indent)}${node.stageName} (${node.runtimeStageId})${link}${writes}`);
+        if (node.incompleteSources && node.incompleteSources.length > 0) {
+            lines.push(`${'  '.repeat(indent + 1)}⚠ also consumed ${node.incompleteSources.join('/')} — slice may be incomplete here`);
+        }
+        for (const parent of node.parents) {
+            walk(parent, indent + 1, node.parentEdges.filter((e) => e.parent === parent));
+        }
+    }
+    walk(root, 0);
+    if (root.truncated) {
+        const causes = [root.truncated.byDepth && 'maxDepth reached', root.truncated.byNodes && 'maxNodes reached']
+            .filter(Boolean)
+            .join(', ');
+        lines.push(`⚠ slice truncated (${causes}) — older causes exist beyond this horizon`);
+    }
+    return lines.join('\n');
+}
+// ── Exported for testing (internal) ────────────────────────────────────
+/** @internal Exposed for testing the strategy selection. */
+export const _REVERSE_INDEX_THRESHOLD = REVERSE_INDEX_THRESHOLD;

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