foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,81 @@
+/**
+ * admission.ts — the admitted record's check (9.30.0): does a commit's bundle
+ * fold back to what its stage read? (docs/design/2026-10-admitted-record.md)
+ *
+ * THE LAW: a commit is admitted only if its bundle, replayed onto the state
+ * the stage began from, gives back the stage's read-your-writes view at every
+ * path the stage touched — and at every container and array slot its writes
+ * made on the way there, below the stage's address.
+ *
+ * Pure: handed the candidate rows, the stage's diff base, its working copy,
+ * its op trace and its address, {@link lossyFamilies} answers which families
+ * of touched paths do not fold back. `TransactionBuffer · admit` asks once per
+ * commit that staged a `merge` or a nested op, and lays the rows out again
+ * with those families written as what the stage read. The fold is the one
+ * verb law ({@link dryFold}, no clone); the compare is {@link deepEqual}.
+ */
+import type { MemoryPatch, TraceEntry } from './types.js';
+/** The rows a payload is built from, before the commit names its redacted paths. */
+export type Rows = {
+    overwrite: MemoryPatch;
+    updates: MemoryPatch;
+    trace: TraceEntry[];
+};
+/** One staged op, as `TransactionBuffer` records it. */
+export type StagedOp = {
+    path: string;
+    verb: string;
+    readKeys?: string[];
+};
+/** A staged path in a {@link Family}, with its last op's read prefix. */
+export type Member = {
+    path: string;
+    readKeys?: string[];
+};
+/**
+ * A family of TOUCHED paths: every staged path under its shallowest staged
+ * ancestor-or-self — the unit the check verifies and, when it does not fold
+ * back, the unit re-encoded. Two families never overlap.
+ */
+export type Family = {
+    root: string;
+    rootSegments: string[];
+    /** Its staged paths, by last touch. */
+    members: Member[];
+    /** Index in the op trace of the family's last op: where its re-encoded rows go. */
+    slot: number;
+    /**
+     * The root's read-back as a record can hold it — its `structuredClone`,
+     * boxed — when the check took one ({@link foldsBack}); the re-encoding
+     * reuses it.
+     */
+    held?: {
+        value: unknown;
+    };
+};
+/** The families whose rows did not fold back, and which family every staged path is in. */
+export type Lossy = {
+    rootOf: Map<string, string>;
+    families: Map<string, Family>;
+};
+/**
+ * The families of `ops` whose candidate rows do not fold back to what the
+ * stage read — `undefined` when every family does. Each family ROOT is
+ * compared ({@link foldsBack}): its value and the way down to it.
+ */
+export declare function lossyFamilies(candidate: Rows, base: unknown, workingCopy: unknown, ops: readonly StagedOp[], address: readonly string[]): Lossy | undefined;
+/**
+ * Every staged path grouped under its SHALLOWEST staged ancestor-or-self —
+ * over TOUCHED paths, not surviving ones: an op the net-change filter drops
+ * can still have changed what the stage reads (L-1). Members are listed by
+ * last touch; a family's slot is its last op.
+ */
+export declare function touchedFamilies(ops: readonly StagedOp[]): {
+    rootOf: Map<string, string>;
+    families: Map<string, Family>;
+};
+/**
+ * How many leading segments of `path` are the stage's `address` — its length
+ * when `path` lies strictly below it, else 0.
+ */
+export declare function addressDepthOf(path: readonly (string | number)[], address: readonly string[]): number;

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

@@ -0,0 +1,152 @@
+/**
+ * admission.ts — the admitted record's check (9.30.0): does a commit's bundle
+ * fold back to what its stage read? (docs/design/2026-10-admitted-record.md)
+ *
+ * THE LAW: a commit is admitted only if its bundle, replayed onto the state
+ * the stage began from, gives back the stage's read-your-writes view at every
+ * path the stage touched — and at every container and array slot its writes
+ * made on the way there, below the stage's address.
+ *
+ * Pure: handed the candidate rows, the stage's diff base, its working copy,
+ * its op trace and its address, {@link lossyFamilies} answers which families
+ * of touched paths do not fold back. `TransactionBuffer · admit` asks once per
+ * commit that staged a `merge` or a nested op, and lays the rows out again
+ * with those families written as what the stage read. The fold is the one
+ * verb law ({@link dryFold}, no clone); the compare is {@link deepEqual}.
+ */
+import { isContainer, nativeGet as _get, ownChild } from './pathOps.js';
+import { deepEqual, DELIM, dryFold } from './utils.js';
+/**
+ * The families of `ops` whose candidate rows do not fold back to what the
+ * stage read — `undefined` when every family does. Each family ROOT is
+ * compared ({@link foldsBack}): its value and the way down to it.
+ */
+export function lossyFamilies(candidate, base, workingCopy, ops, address) {
+    const fold = dryFold(base, candidate.updates, candidate.overwrite, candidate.trace);
+    const { rootOf, families } = touchedFamilies(ops);
+    let lossy;
+    for (const family of families.values()) {
+        if (!foldsBack(fold, workingCopy, family, address))
+            (lossy ??= new Map()).set(family.root, family);
+    }
+    return lossy === undefined ? undefined : { rootOf, families: lossy };
+}
+/**
+ * Does the fold give back what the stage read at a family root? The way down
+ * ({@link spineHeld}), then the value by {@link deepEqual} (a root covers every
+ * descendant; an own `undefined` is a deleted key) — against the read-back as
+ * a record can hold it. A record holds `structuredClone`s of what a stage
+ * wrote (state values must survive one), and a few values do not survive one
+ * whole: an `Error`'s own fields are dropped. When the fold equals the
+ * read-back's clone, no row could hold more, and the family is admitted as it
+ * is; the clone, taken only for a root the cheap compare refused, is kept for
+ * the re-encoding.
+ */
+function foldsBack(fold, workingCopy, family, address) {
+    const segments = family.rootSegments;
+    if (!spineHeld(fold, workingCopy, segments, address))
+        return false;
+    const folded = _get(fold, segments);
+    const read = _get(workingCopy, segments);
+    // Both sides are the same values as a record holds them: an opaque one (a Blob) is never the same object.
+    if (deepEqual(folded, read, 'copies'))
+        return true;
+    family.held = { value: structuredClone(read) };
+    return deepEqual(folded, family.held.value, 'copies');
+}
+/**
+ * Every staged path grouped under its SHALLOWEST staged ancestor-or-self —
+ * over TOUCHED paths, not surviving ones: an op the net-change filter drops
+ * can still have changed what the stage reads (L-1). Members are listed by
+ * last touch; a family's slot is its last op.
+ */
+export function touchedFamilies(ops) {
+    const touches = new Map();
+    for (let i = 0; i < ops.length; i++) {
+        touches.delete(ops[i].path); // re-insert: the Map's order is last-touch order
+        touches.set(ops[i].path, { last: i, readKeys: ops[i].readKeys });
+    }
+    const rootOf = new Map();
+    const families = new Map();
+    for (const [path, touch] of touches) {
+        const root = shallowestIn(path, touches);
+        rootOf.set(path, root);
+        let family = families.get(root);
+        if (family === undefined) {
+            family = { root, rootSegments: root.split(DELIM), members: [], slot: touch.last };
+            families.set(root, family);
+        }
+        family.members.push({ path, readKeys: touch.readKeys });
+        if (touch.last > family.slot)
+            family.slot = touch.last;
+    }
+    return { rootOf, families };
+}
+/**
+ * How many leading segments of `path` are the stage's `address` — its length
+ * when `path` lies strictly below it, else 0.
+ */
+export function addressDepthOf(path, address) {
+    const depth = address.length;
+    if (depth === 0 || path.length <= depth)
+        return 0;
+    for (let i = 0; i < depth; i++)
+        if (String(path[i]) !== address[i])
+            return 0;
+    return depth;
+}
+/**
+ * L-1: a nested op through an absent or primitive parent makes that parent a
+ * container in the working copy — and when the op itself changes nothing (a
+ * delete of a key that was never there) no row is left to make it in the
+ * fold, so the stage reads back a container the record never mentions. The
+ * same op on an ARRAY parent past its end grows it (`delete a.0` on `[]`
+ * reads back `[undefined]`). Every container the working copy holds on the
+ * way to `segments`, and every array slot each step lands in, must be one the
+ * fold holds too — below the stage's address, whose containers are where it
+ * writes, not a value it reads.
+ */
+function spineHeld(fold, workingCopy, segments, address) {
+    const from = addressDepthOf(segments, address);
+    let f = fold;
+    let w = workingCopy;
+    for (let i = 0; i < segments.length; i++) {
+        if (i >= from && !slotHeld(f, w, segments[i]))
+            return false;
+        if (i === segments.length - 1)
+            return true;
+        f = ownChild(f, segments[i]);
+        w = ownChild(w, segments[i]);
+        if (!isContainer(w))
+            return true;
+        if (i >= from && (!isContainer(f) || Array.isArray(f) !== Array.isArray(w)))
+            return false;
+    }
+    return true;
+}
+/**
+ * Does the fold hold every array slot the working copy's container `w` holds
+ * at `key`? Only an array can be grown by a write that changes nothing else
+ * (an index past its end, set to `undefined`); an object's own `undefined`
+ * key is a deleted key to every reader, so objects always pass.
+ */
+function slotHeld(f, w, key) {
+    if (!Array.isArray(w))
+        return true;
+    const index = Number(key);
+    if (!Number.isInteger(index) || index < 0 || String(index) !== key || index >= w.length)
+        return true;
+    return Array.isArray(f) && index < f.length;
+}
+/** The shallowest of `path` and its ancestors that `touched` holds — its family's root. */
+function shallowestIn(path, touched) {
+    if (path.indexOf(DELIM) === -1)
+        return path;
+    const segments = path.split(DELIM);
+    for (let i = 1; i < segments.length; i++) {
+        const ancestor = segments.slice(0, i).join(DELIM);
+        if (touched.has(ancestor))
+            return ancestor;
+    }
+    return path;
+}

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