foottrace 0.0.0-stage → 1.0.0

package/dist/types/lib/slice/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * slice/ — variable-first slicing, both directions (the triage query layer).
+ *
+ * One variable, one contract, every surface — asked identically by UI panels
+ * (explainable-ui / lens), LLM triage tools (trace toolpacks), and offline
+ * autopsy agents:
+ *
+ * - BACKWARD — "why is this VARIABLE what it is?" (`sliceForKey`,
+ *   `arrayProvenance` / `elementProvenance`).
+ * - FORWARD — "who READ it, and what did it FEED?" (`forwardSliceForKey`),
+ *   plus the flat chronological view (`keyTimeline`).
+ *
+ * See README.md for the algorithms (thin-slice composition, append-fold
+ * provenance, live-range walking), the honesty model, serialization rules,
+ * and the evolution path.
+ *
+ * DAG position: memory ← slice (leaf-adjacent; imports memory/ only).
+ */
+export { arrayProvenance, elementProvenance } from './elementProvenance.js';
+export { type ForwardSliceForKeyOptions, forwardSliceForKey } from './forwardSliceForKey.js';
+export { keysReadFromExecutionTree, keysReadFromMap, resolveKeysReadSource } from './keysReadSources.js';
+export { type KeyTimelineOptions, keyTimeline } from './keyTimeline.js';
+export { formatForwardSlice, formatSlice, formatTimeline, forwardSliceToJSON, sliceToJSON } from './serialize.js';
+export { type SliceForKeyOptions, sliceForKey } from './sliceForKey.js';
+export { normaliseStateKey } from '../memory/paths.js';
+export type { ArrayProvenance, AttributionBasis, ElementBirth, FedBasis, ForwardEdge, ForwardNode, ForwardRead, ForwardSlice, ForwardSliceJSON, HonestyNote, HonestyNoteCode, KeyMoment, KeysReadSource, KeyTimeline, MissingProvenanceReason, MissingSliceReason, ReadsCoverage, SliceJSON, StateKey, VariableSlice, } from './types.js';

package/dist/types/lib/slice/keyIndex.d.ts

@@ -0,0 +1,137 @@
+/**
+ * slice/keyIndex.ts — the one pass over the log both FORWARD queries share.
+ *
+ * WHY it exists: a backward slice only ever asks "who wrote key k before
+ * idx i" — `findLastWriter` answers that with a backward scan. A forward
+ * query asks the opposite, and the opposite is not symmetric: reads are NOT
+ * in the commit log, and `KeysReadSource` is a LOOKUP (runtimeStageId →
+ * keys), not an enumerable collection. So "who read k" cannot be looked up —
+ * it has to be inverted.
+ *
+ * THE INVERSION (and the law it rests on): the engine commits exactly ONE
+ * bundle per executed stage, so the commit log IS the list of execution
+ * steps. Calling the reads lookup once per bundle turns the strategy into a
+ * key → [commit indices that read it] index — and gives every read moment a
+ * commit position, the join key the whole library is addressed by.
+ *
+ * Consequence worth stating (documented, not silently absorbed): a reads
+ * provider naming a step that has no commit in THIS log contributes nothing.
+ * That is the same log↔reads pairing law the backward side has — a subflow
+ * runs in an isolated runtime, so its log and its tree must come from the
+ * same scope (see README.md § Subflow boundaries).
+ *
+ * Cost: one lookup call per bundle, once per query — O(N + total read keys).
+ * Both forward queries then run off sorted index arrays.
+ *
+ * DAG position: internal to slice/ (not exported from the barrel).
+ */
+import type { KeysReadLookup } from '../memory/backtrack.js';
+import { type WriterIndex } from '../memory/keyPaths.js';
+import type { CommitBundle, TraceEntry } from '../memory/types.js';
+import type { HonestyNote } from './types.js';
+/** How many known keys an unknown-key refusal lists before it says "+N more". */
+export declare const KNOWN_KEYS_LISTED = 10;
+/**
+ * The inverted view of one commit log + its reads provider.
+ *
+ * WRITES follow the writer rule every key query shares (`memory/keyPaths.ts`, 9.33.0): a commit
+ * writes a key with a row ON it, INSIDE it, or AROUND it when that changed it. READS follow the
+ * same path relation: a stage that read the key, a path inside it (part of its value) or a
+ * container around it (the whole of its value, and more) is a reader of the key. A read key is
+ * matched as the reads provider spelled it, as a DELIM path — the engine's own nested reads are
+ * spelled with dots (`StageContext · getValue`), and a dot is a legal character of a top-level key,
+ * so `'cfg.a'` stays the literal key it may be.
+ */
+export interface KeyIndex {
+    /** Where every path was written — the writer rule's index (`keyPaths · buildWriterIndex`). */
+    readonly writers: WriterIndex;
+    /** key → commit ARRAY positions that WROTE it under the writer rule, ascending. Memoised per key. */
+    writesOf(key: string): number[];
+    /**
+     * The writes that END a value's life: every write except one that reached the key only through paths
+     * inside it — that one changed part of the value, and a reader after it still read the rest. Memoised.
+     */
+    closingWritesOf(key: string): number[];
+    /** Read key, as the reads provider named it → commit ARRAY positions whose stage READ it, ascending. */
+    readonly readsByKey: Map<string, number[]>;
+    /** key → commit ARRAY positions whose stage read it, a path inside it or a container around it, ascending. Memoised. */
+    readsOf(key: string): number[];
+    /** Every key this log knows BY NAME: written paths ∪ recorded read keys — the list an unknown-key note shows. */
+    readonly knownKeys: Set<string>;
+    /** Does the log know `key` — a write of it (the writer rule), or a read on, inside or around it? */
+    isKnown(key: string): boolean;
+}
+/**
+ * Build the index. Indices go in ascending order by construction (we iterate
+ * the log forwards), which is what lets every range query below be a pair of
+ * binary searches instead of a scan.
+ */
+export declare function buildKeyIndex(commitLog: CommitBundle[], lookup: KeysReadLookup): KeyIndex;
+/**
+ * LAW — an unknown key is NAMED as unknown; it never renders as "no history".
+ *
+ * The failure this prevents: `forwardSliceForKey(log, 'recipId')` (typo) must
+ * not come back looking like a real variable that nothing happened to. The
+ * answer says so out loud AND lists the keys the log does know — bounded, so
+ * a 400-key agent state is a hint, not a wall.
+ *
+ * Why a NOTE and not a throw: the module's absence convention is a RESULT,
+ * not an exception (`VariableSlice.missing`) — one absence vocabulary across
+ * both doors. The loudness comes from the note + `missing: 'never-written'`,
+ * not from a stack trace a triage tool would have to catch.
+ */
+export declare function unknownKeyNote(index: Pick<KeyIndex, 'knownKeys'>, key: string): HonestyNote;
+/**
+ * Does this log carry ANY recorded read? The provider-agnostic version of
+ * `ReadsCoverage.stepsWithReads > 0` (map / custom-fn strategies carry no
+ * coverage), and the switch that decides whether "nobody read it" is a
+ * FINDING or a BLIND SPOT.
+ */
+export declare function hasRecordedReads(index: KeyIndex): boolean;
+/**
+ * Ascending indices in the INCLUSIVE range [from, to]. `to === undefined`
+ * means "to the end of the log".
+ */
+export declare function indicesInRange(sorted: number[] | undefined, from: number, to?: number): number[];
+/** The largest index in the ascending array that is < `before`, or undefined. */
+export declare function lastIndexBefore(sorted: number[] | undefined, before?: number): number | undefined;
+/** The smallest index in the ascending array that is > `after`, or undefined. */
+export declare function firstIndexAfter(sorted: number[] | undefined, after: number): number | undefined;
+/**
+ * The LAST trace entry for `path` in a bundle — the one that decides both the
+ * committed verb and (under the writeProvenance dial) the widest read prefix.
+ * Full mode can record several ops on one path in one commit; read prefixes
+ * only grow during a stage, so the last entry is the honest one to attribute
+ * with.
+ */
+export declare function lastTraceEntry(bundle: CommitBundle, path: string): TraceEntry | undefined;
+/**
+ * The trace entry that decides a WRITE of `key` in `bundle` — its verb, and the read prefix a
+ * fed edge is judged by: the LAST entry on the exact path when there is one (as before 9.33.0),
+ * otherwise the last entry inside or around the key (the commit wrote it through a nested row).
+ */
+export declare function writeEntry(bundle: CommitBundle, key: string): TraceEntry | undefined;
+/**
+ * The commits in `writes` that reached `key` ONLY through rows inside it — no row on the key and
+ * none around it — so each changed part of its value, not the whole. What a `'nested-rows'` note
+ * names.
+ */
+export declare function nestedOnlyWrites(commitLog: readonly CommitBundle[], key: string, writes: readonly number[]): number[];
+/** How many commit positions a `'nested-rows'` note lists before it says "+N more". */
+export declare const NESTED_WRITES_LISTED = 5;
+/** A write the answer rests on reached the key only through paths inside it. */
+export declare function nestedRowsNote(key: string, commits: readonly number[]): HonestyNote;
+/** The value a backward slice explains holds, or lost the key under, the log's redaction placeholder. */
+export declare function redactedValueNote(key: string): HonestyNote;
+/** No set or delete of the key, or of a container around it, is in range: the value rests on the pre-run state. */
+export declare function fromInitialStateNote(key: string): HonestyNote;
+/** The `readTracking: 'off'` signature — see the HonestyNoteCode docs. */
+export declare function readsNotRecordedNote(): HonestyNote;
+/** The value predates every write this log can see. */
+export declare function preRunOriginNote(key: string): HonestyNote;
+/** At least one fed edge rests on stage-level co-occurrence only. */
+export declare function conservativeEdgesNote(key: string): HonestyNote;
+/** A budget cut the walk — stated, never silent. */
+export declare function truncatedNote(byDepth: boolean, byNodes: boolean): HonestyNote;
+/** Distinct written paths of a bundle, in first-touch order. */
+export declare function writtenPaths(bundle: CommitBundle): string[];

package/dist/types/lib/slice/keyTimeline.d.ts

@@ -0,0 +1,49 @@
+/**
+ * slice/keyTimeline.ts — the whole life of ONE key, in commit order.
+ *
+ * The flat companion to {@link forwardSliceForKey}: no graph, no budgets,
+ * no anchor — every write of the key and every recorded read of it, as one
+ * chronological list. This is what a UI timeline row and an LLM's "walk me
+ * through what happened to `total`" both want, and what makes a forward
+ * slice checkable: the same facts, unfolded instead of walked.
+ *
+ * Every moment carries BOTH universal join keys — `runtimeStageId` (to
+ * recorders, execution trees, UIs) and `commitIdx` (to the commit log).
+ *
+ * ### LAW — read attribution is the walk's, exactly
+ *
+ * A read moment's `fromWriteIdx` is the write whose live range it sits in:
+ * the last write at a STRICTLY earlier commit index. That is the same
+ * `(writeIdx, nextWriteIdx]` rule `forwardSliceForKey` walks (reads fire
+ * PRE-commit), so the two doors can never disagree about which value a read
+ * saw — pinned by a cross-door property test. A read before ANY write has no
+ * `fromWriteIdx` and raises the `'pre-run-origin'` note: it saw initial
+ * state, frozen run `input`, or a closure.
+ *
+ * DAG position: memory ← slice. Imports memory/ only (see README.md).
+ */
+import type { KeysReadLookup } from '../memory/backtrack.js';
+import type { CommitBundle } from '../memory/types.js';
+import type { KeysReadSource, KeyTimeline, StateKey } from './types.js';
+/** Options for {@link keyTimeline}. */
+export interface KeyTimelineOptions {
+    /**
+     * Exclusive commit-array-index upper bound: only moments BEFORE this idx.
+     * Same word and semantics as `sliceForKey`'s `before` (note the sibling
+     * `arrayProvenance` uses an INCLUSIVE `atIdx` — this family follows the
+     * slice doors).
+     */
+    before?: number;
+}
+/**
+ * The life of one key as a chronological list of writes and reads.
+ *
+ * @param commitLog Ordered commit bundles — `getSnapshot().commitLog`.
+ * @param key A {@link StateKey} — normalised through the same
+ *   `normaliseStateKey` both slice doors use.
+ * @param keysRead A {@link KeysReadSource} or bare lookup (reads are not in
+ *   the commit log).
+ * @returns Always a {@link KeyTimeline}; absence carries its reason, and an
+ *   unknown key is NAMED as unknown with a bounded list of known keys.
+ */
+export declare function keyTimeline(commitLog: CommitBundle[], key: StateKey, keysRead: KeysReadSource | KeysReadLookup, options?: KeyTimelineOptions): KeyTimeline;

package/dist/types/lib/slice/keysReadSources.d.ts

@@ -0,0 +1,51 @@
+/**
+ * slice/keysReadSources.ts — the shipped {@link KeysReadSource} strategies.
+ *
+ * The canonical strategy list and rationale live on the KeysReadSource type
+ * (types.ts) — the doc consumers hover. This file holds the implementations.
+ *
+ * Deliberately NOT here: a QualityRecorder adapter. Importing recorder/ would
+ * drag this leaf library up the dependency DAG. The adapter is a one-liner at
+ * the call site instead: `(id) => recorder.getByKey(id)?.keysRead ?? []`.
+ */
+import type { KeysReadLookup } from '../memory/backtrack.js';
+import type { ExecutionTree } from '../memory/types.js';
+import type { KeysReadSource } from './types.js';
+/**
+ * Post-hoc reads from a finished run's execution tree — ZERO setup.
+ *
+ * WHY this works: a stage's `stageReads` records the keys it
+ * tracked-read whenever the `readTracking` dial ≠ 'off' ('full' is the
+ * engine default; 'summary' replaces VALUES with markers but keeps the
+ * KEYS — and keys are all a slice needs). Under 'off' this source returns
+ * empty read-sets — detectable via `coverage.stepsWithReads === 0`, which
+ * `sliceForKey` copies onto the slice so tools can say "reads were not
+ * recorded" instead of the lie "no dependencies".
+ *
+ * SUBFLOW PAIRING (important): a subflow runs in an ISOLATED runtime — its
+ * commits live in `snapshot.subflowResults[sfId].commitLog`, its reads in
+ * `snapshot.subflowResults[sfId].executionTree`. Trees and logs must be
+ * paired from the SAME scope: to slice a key inside a subflow, re-anchor
+ * there —
+ *
+ * ```ts
+ * const sf = snapshot.subflowResults['sf-tools'];
+ * sliceForKey(sf.commitLog, key, keysReadFromExecutionTree(sf.executionTree));
+ * ```
+ *
+ * Passing multiple trees widens READ resolution only (useful when one log
+ * genuinely spans them); it does not let a root-log slice cross a subflow
+ * mount — see README.md § Subflow boundaries.
+ */
+export declare function keysReadFromExecutionTree(tree: ExecutionTree | readonly ExecutionTree[]): KeysReadSource;
+/**
+ * Reads from a prebuilt map — e.g. collected live from
+ * `ScopeRecorder.onRead` events, or deserialized from a stored trace.
+ */
+export declare function keysReadFromMap(map: ReadonlyMap<string, readonly string[]> | Readonly<Record<string, readonly string[]>>): KeysReadSource;
+/**
+ * Normalize the ergonomic union: callers may pass a full strategy object or
+ * a bare lookup function (wrapped as kind 'custom-fn' so the honesty
+ * breadcrumb still says where reads came from).
+ */
+export declare function resolveKeysReadSource(src: KeysReadSource | KeysReadLookup): KeysReadSource;

package/dist/types/lib/slice/serialize.d.ts

@@ -0,0 +1,78 @@
+/**
+ * slice/serialize.ts — JSON-safe and LLM-safe projections of a slice.
+ *
+ * WHY (the failure this prevents): `VariableSlice.root` is an in-memory DAG.
+ * Nodes are SHARED — a diamond ancestor is one object reached through many
+ * paths, and each node appears in both `parents` and `parentEdges[].parent`.
+ * `JSON.stringify` knows nothing about sharing: it re-serializes every shared
+ * subtree per path, which explodes combinatorially on diamond-heavy slices.
+ * The two consumers that would naively stringify are exactly the ones this
+ * library exists for — wire transfer (persist / send a slice) and LLM tools
+ * (bounded context). Each gets a purpose-built projection:
+ *
+ * - {@link sliceToJSON}   — flat, id-referenced, LINEAR in node count.
+ * - {@link formatSlice}   — one bounded human/LLM-readable string that also
+ *   renders the honesty envelope (missing reason, reads coverage, truncation)
+ *   a raw `formatCausalChain` doesn't know about.
+ *
+ * The FORWARD half has exactly the same hazard and the same two projections:
+ * {@link forwardSliceToJSON} / {@link formatForwardSlice}. A forward DAG
+ * shares nodes just as readily — two values read by one stage feed the same
+ * child write — so a forward root must never be stringified either.
+ *
+ * {@link KeyTimeline} is the deliberate exception, stated so nobody adds a
+ * pointless twin: it is a FLAT list of plain fields holding no live
+ * references and no sharing, so `JSON.stringify(timeline)` is already
+ * correct and linear. What it still needs is the bounded LLM projection —
+ * {@link formatTimeline} — because "the whole life of a key" is unbounded in
+ * a long run.
+ */
+import type { ForwardSlice, ForwardSliceJSON, KeyTimeline, SliceJSON, VariableSlice } from './types.js';
+/**
+ * Flat, JSON-safe projection: every DAG node exactly once (keyed by
+ * runtimeStageId), edges as id references. Linear in node count — safe to
+ * persist, send, or feed to structured consumers. Lossless for everything
+ * except the in-memory object graph itself (rebuild adjacency from `edges`).
+ */
+export declare function sliceToJSON(slice: VariableSlice): SliceJSON;
+/**
+ * One bounded string for LLM triage tools (the `traceToolpack` consumption
+ * pattern: tools return plain strings, never recursive objects). Wraps
+ * `formatCausalChain` (which is budget-bounded by causalChain's
+ * maxDepth/maxNodes and renders shared nodes once as `↳ … (see above)`),
+ * and adds the honesty envelope the raw chain doesn't carry:
+ *
+ * - missing slices render their reason ("value came from initial state /
+ *   frozen args / a closure — the commit log cannot see those"),
+ * - a reads-less provider (`readTracking: 'off'` signature) renders an
+ *   explicit "⚠ reads were not recorded" instead of silently showing an
+ *   anchor with no dependencies,
+ * - truncation footers pass through from formatCausalChain.
+ */
+export declare function formatSlice(slice: VariableSlice): string;
+/**
+ * Flat, JSON-safe projection of a {@link ForwardSlice} — the forward twin of
+ * {@link sliceToJSON}, linear in node count.
+ *
+ * Node ids are OPAQUE (`n0`, `n1`, … in BFS order) rather than
+ * `runtimeStageId` as in `SliceJSON`, for a structural reason: a forward
+ * node is a (key, write) pair, so ONE stage that wrote two keys owns two
+ * nodes and a runtimeStageId cannot key the map. Never parse the ids — join
+ * on `runtimeStageId` / `commitIdx` / `key`, which every node carries.
+ */
+export declare function forwardSliceToJSON(slice: ForwardSlice): ForwardSliceJSON;
+/**
+ * One bounded string for LLM triage tools — the forward twin of
+ * {@link formatSlice}. Shared nodes render once (`↳ … (see above)`, the same
+ * convention `formatCausalChain` uses), read lists are capped, and every
+ * honesty note renders as a `⚠` line — including the one that says a `fed`
+ * edge is conservative, which is why edges print `[exact]` / `[conservative]`
+ * rather than looking alike.
+ */
+export declare function formatForwardSlice(slice: ForwardSlice): string;
+/**
+ * One bounded string for a {@link KeyTimeline} — the LLM/human projection.
+ * (The timeline's JSON needs no helper: it is already flat and JSON-safe —
+ * see the file header.) Truncation is stated, never silent.
+ */
+export declare function formatTimeline(timeline: KeyTimeline): string;

package/dist/types/lib/slice/sliceForKey.d.ts

@@ -0,0 +1,40 @@
+/**
+ * slice/sliceForKey.ts — the variable-first backward slice query.
+ *
+ * "Why is `key` what it is?" — the ONE question every triage surface asks:
+ * a human clicking a key in explainable-ui, an LLM calling a `backtrack`
+ * tool mid-conversation, an offline autopsy agent over a stored run.
+ *
+ * WHY this is deliberately a composition and not a new algorithm:
+ * `findLastWriter` already answers "who made the value what it is" and
+ * `causalChain` already answers "what influenced that step" (thin backward
+ * slicing, Weiser 1984). What was missing is the shared CONTRACT — without
+ * it, every surface hand-rolls the anchor step differently and their answers
+ * disagree. The value of this function is that they can't.
+ */
+import { type CausalChainOptions, type KeysReadLookup } from '../memory/backtrack.js';
+import type { CommitBundle } from '../memory/types.js';
+import type { KeysReadSource, StateKey, VariableSlice } from './types.js';
+/** Options for {@link sliceForKey} — causalChain's options plus anchoring. */
+export interface SliceForKeyOptions extends CausalChainOptions {
+    /**
+     * Exclusive commit-array-index upper bound: slice the value as it stood
+     * BEFORE this idx (time-travel triage — "why was it X at step 12?").
+     * Same contract as `findLastWriter`'s `beforeIdx`. Omit for the current
+     * value. Chained-triage idiom: to slice at an {@link ElementBirth}, pass
+     * `before: birth.commitIdx + 1` (birth idx is inclusive, this bound is
+     * exclusive — the +1 makes the birth commit itself the anchor).
+     */
+    before?: number;
+}
+/**
+ * Backward slice for one state key: anchor at the key's last writer, then
+ * walk read→write (and optional control) dependencies transitively.
+ *
+ * Honest-absence contract: a missing slice is a RESULT, not an error —
+ * `missing: 'never-written'` tells a triage tool (or its LLM caller) that
+ * the value came from initial state / frozen args / a closure, which is
+ * itself diagnostic information. See {@link VariableSlice} — including its
+ * SERIALIZATION WARNING before you stringify the result.
+ */
+export declare function sliceForKey(commitLog: CommitBundle[], key: StateKey, keysRead: KeysReadSource | KeysReadLookup, options?: SliceForKeyOptions): VariableSlice;