foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,333 @@
+/**
+ * verbs.ts — THE VERB LAW (L1): the one place a commit row becomes a value.
+ *
+ * A row of a commit bundle's `trace` carries one of four verbs —
+ * `set | merge | append | delete` — and ONE step turns it into a value:
+ * {@link applyVerb}. State is a left fold of that step (the event-sourcing
+ * reducer): {@link foldRows} folds one bundle's rows into a state, and
+ * {@link foldKey} folds ONE KEY across a log — every row under the key's
+ * top-level key, read at the key (the value rule, `keyPaths.ts`). Every reader
+ * of the log runs one of the two —
+ *
+ *   - the live commit and the redacted mirror (`nextGeneration`),
+ *   - the public replay (`applySmartMerge`), the read-side folds
+ *     (`applySmartMergeInto` — `EventLog.materialise`, `stateAt`) and the
+ *     admitted record's comparison (`dryFold`): all {@link foldRows},
+ *   - `commitValueAt`, and `arrayProvenance` as an OBSERVER of the same fold:
+ *     {@link foldKey}.
+ *
+ * Three questions that used to be answered once per reader are answered here
+ * once: what a verb does to the value before it ({@link applyVerb}), how the
+ * result is placed ({@link placeVerb}), and how the log's own values are
+ * treated on the way in (the clone discipline — a PARAMETER of the fold, see
+ * {@link Discipline} and {@link RecordedPayload}). A new verb is one new arm of
+ * `applyVerb` and one row of the traits table; the compiler refuses either
+ * missing ({@link isTotal}, {@link recordsTail}, {@link VERBS}).
+ *
+ * An UNKNOWN verb is refused with {@link UnknownVerbError}, never folded as a
+ * `merge` (the old silent default). Engine-written logs carry the four, so
+ * every engine run folds byte-for-byte as before.
+ */
+import type { CommitIdx } from '../ids/runtimeStageId.js';
+import type { PathRelation } from './keyPaths.js';
+import type { CommitBundle, MemoryPatch, TraceEntry } from './types.js';
+/** A commit row's verb — `TraceEntry['verb']`, the union the types file declares. */
+export type Verb = TraceEntry['verb'];
+/** The four verbs, in the order the contract names them. */
+export declare const VERBS: readonly Verb[];
+/** Is `value` one of the four? The question every reader of a foreign log asks first. */
+export declare function isVerb(value: unknown): value is Verb;
+/**
+ * Does the verb decide the value ALONE — read nothing from what came before
+ * it? `set` and `delete`. A reader that only needs the final value may start
+ * at the last such row ({@link foldKey} `anchored`); one that tracks how the
+ * value grew (provenance) starts at the first. Pinned against
+ * {@link applyVerb} itself, so a new verb cannot misreport it.
+ */
+export declare function isTotal(verb: Verb): boolean;
+/**
+ * Does the row record ONLY what it adds — a tail — rather than the whole
+ * value? `append`. What the row added is then known exactly: a reader that
+ * tracks where array elements came from attributes them to this row without
+ * comparing arrays, where every other verb has to be inferred from.
+ */
+export declare function recordsTail(verb: Verb): boolean;
+/** Where in a log a refused row sits. */
+export interface RowSite {
+    /** The row's `path`, DELIM-joined as the trace records it. */
+    readonly path: string;
+    /** The row's position in its bundle's `trace`. */
+    readonly row: number;
+    /** The bundle's position in the commit log, when the reader knows it. */
+    readonly commit?: number;
+}
+/**
+ * Thrown by the readers of a commit log — {@link foldRows} (behind
+ * `applySmartMerge`), `commitValueAt`, `arrayProvenance` — when a row carries a
+ * verb outside {@link VERBS}: a foreign or corrupted log fails loudly instead
+ * of being replayed as a `merge`. `verb`, `path`, `row` and `commit` name the
+ * row (`path` / `row` / `commit` are absent when the caller handed over a
+ * bare verb); `path` is the trace's own DELIM-joined form — take it apart with
+ * `pathSegments`. The message quotes `verb` and `path`, so a hostile log cannot
+ * reshape it.
+ */
+export declare class UnknownVerbError extends Error {
+    readonly verb: unknown;
+    readonly path?: string;
+    readonly row?: number;
+    readonly commit?: number;
+    constructor(verb: unknown, site?: RowSite);
+}
+/**
+ * What a `delete` row leaves behind: the KEY IS GONE — which is not the value
+ * `undefined` (a root replay removes the key; a per-path fold reads it as
+ * `undefined`). {@link applyVerb} returns it, {@link placeVerb} acts on it.
+ */
+export declare const ABSENT: unique symbol;
+/**
+ * One bundle's recorded payload, read by path under a clone discipline — the
+ * values {@link applyVerb} reads out of the log.
+ *
+ * `detach` — `true` for every fold that keeps its result: a `set` value or an
+ * `append` tail is a clone of what the log holds and the merge delta comes from
+ * ONE detached copy of `updates`, so the result never aliases the log. `false`
+ * only for the comparison fold ({@link dryFold}), which places recorded values
+ * as recorded and drops its result.
+ *
+ * The delta is detached ONCE per bundle, lazily — a bundle with no `merge` row
+ * pays nothing. `deepSmartMerge` dedups an array union BY REFERENCE and two
+ * `merge` rows of one bundle replay the same accumulated delta, so the rows
+ * must keep seeing the same objects; a clone per row duplicated their elements
+ * (the differential caught it in the replay; `commitValueAt` carried the bug
+ * until it folded through here). `only` narrows the copy to ONE path — a
+ * per-path fold reads nothing else, and must not pay for the rest of the
+ * bundle.
+ */
+export declare class RecordedPayload {
+    private readonly updates;
+    private readonly overwrite;
+    private readonly detach;
+    private readonly only?;
+    private deltas;
+    constructor(updates: MemoryPatch, overwrite: MemoryPatch, detach: boolean, only?: string[] | undefined);
+    /** What a `set` places and an `append` adds: `overwrite[path]`, cloned when detaching. */
+    value(segs: string[]): unknown;
+    /** The accumulated merge delta at `path`: `updates[path]`, from the bundle's one copy. */
+    delta(segs: string[]): unknown;
+}
+/**
+ * ONE row, ONE step: the value at the row's path AFTER the row, given the
+ * value BEFORE it and the bundle's recorded payload. THE verb law — no other
+ * function in the library has an arm per verb.
+ *
+ *   - `'set'`    — the recorded value (`overwrite[path]`, the full final value).
+ *   - `'merge'`  — `deepSmartMerge` of the accumulated `updates[path]` delta onto
+ *     the value before.
+ *   - `'append'` — (delta mode) `overwrite[path]` holds ONLY the tail: concatenate
+ *     it onto the value before. When either is not an array (an out-of-order
+ *     replay base, or a REDACTED tail — `scrubPatch` replaces matched payloads
+ *     with the `'REDACTED'` string) the tail BECOMES the value — the same
+ *     terminal value a redacted or corrupt `set` produces.
+ *   - `'delete'` — {@link ABSENT}: the key is removed. The path stays enumerated
+ *     in `overwrite` (value `undefined`) for key-set consumers; the step ignores
+ *     that value.
+ *
+ * Pure: it reads the payload and never writes. `verb` must be a {@link Verb}
+ * (the folds check with {@link isVerb} first and name the row); anything else
+ * that reaches it is refused with {@link UnknownVerbError}.
+ */
+export declare function applyVerb(verb: Verb, before: unknown, at: RecordedPayload, segs: string[]): unknown;
+/** Put a step's value at its path in `out` — or remove the key, for {@link ABSENT}. */
+export declare function placeVerb(out: any, segs: string[], next: unknown): void;
+/**
+ * Is row `i` a `set` that the NEXT row sets again — same path, same verb — so
+ * that applying it is work the next row redoes?
+ *
+ * The one skip every replay iterator shares (9.22.1). A `set` row writes a
+ * clone of the recorded value at its path; the next row, a `set` of the same
+ * path, writes a clone of the SAME recorded value over it (the bundle's patch
+ * tree is fixed), and nothing runs in between — so the first write is
+ * unobservable, container creation and key order included. Only CONSECUTIVE
+ * rows qualify: a row in between (an ancestor `merge`, a sibling `set` that
+ * creates a container) can see the intermediate value, and a `merge`,
+ * `append` or `delete` next row depends on what is there. Rows are never
+ * dropped from the log — the 9.22.0 element-write funnel records N
+ * whole-array `set` rows on one path, and this is what makes replaying them
+ * O(N) instead of O(N × rows).
+ *
+ * Asked by {@link foldRows} — live state and the redacted mirror through
+ * {@link nextGeneration}, `EventLog.materialise` and `stateAt` through
+ * {@link applySmartMergeInto}, the public {@link applySmartMerge}, and the
+ * admitted record's {@link dryFold}. {@link foldKey} needs no skip: it
+ * anchors at the top-level key's LAST `set`/`delete`, or (provenance) a
+ * repeated `set` of the one recorded value changes no birth.
+ */
+export declare function supersededByNextSet(rows: readonly {
+    path: string;
+    verb: string;
+}[], i: number): boolean;
+/**
+ * How {@link foldRows} treats the state it edits and the values it reads out of
+ * the log — the clone discipline, a parameter of the ONE loop:
+ *
+ *   - `'private'` — `out` is a private deep clone, edited in place; every
+ *     recorded value is cloned in. The public {@link applySmartMerge}.
+ *   - `'pathCopy'` — copy-on-write (9.29.0): before a row that writes THROUGH a
+ *     container (a nested path), the containers on its path that this fold did
+ *     not create are copied, so no row edits a container another generation
+ *     (or the log) holds; each value a row creates is marked owned, so later
+ *     rows of the bundle write into it in place. Every recorded value is cloned
+ *     in. The live commit ({@link nextGeneration}) and the read-side folds
+ *     ({@link applySmartMergeInto}).
+ *   - `'byReference'` — `'pathCopy'`, but recorded values are placed AS
+ *     RECORDED (no clone) and never marked owned — a later row that writes
+ *     through one copies it first, so the payload is never edited. For
+ *     COMPARISON only ({@link dryFold}): the result aliases the log.
+ */
+export type Discipline = 'private' | 'pathCopy' | 'byReference';
+/**
+ * Fold one bundle's rows into `out`, in place: for each row (a `set` the next
+ * row sets again is skipped — {@link supersededByNextSet}) take the step
+ * ({@link applyVerb}) and put its value where it belongs ({@link placeVerb}).
+ * `out` is the caller's — see {@link Discipline} for what it must be.
+ *
+ * A row whose verb is not one of {@link VERBS} stops the fold with
+ * {@link UnknownVerbError} naming the row; the rows before it have been
+ * applied, to a state the caller discards (every in-tree caller does).
+ */
+export declare function foldRows(out: any, updates: MemoryPatch, overwrite: MemoryPatch, rows: readonly TraceEntry[], discipline: Discipline): any;
+/**
+ * Applies a commit bundle to a base state by replaying operations in order.
+ * Guarantees "last writer wins" semantics.
+ *
+ * Returns a FULLY DETACHED result: the base is deep-cloned first and every
+ * value the replay writes is its own (`set` / `append` clone the recorded
+ * value; the `merge` arm reads a detached copy of `updates`), so the result
+ * shares no container with `base`, `updates` or `overwrite`. This is the
+ * public (`foottrace`) contract, unchanged by copy-on-write
+ * (9.29.0) — byte-identical to 9.28.0 for every caller. The engine's own
+ * commit does NOT come here: `SharedMemory.applyPatch` builds the next
+ * generation with `nextGeneration`, which copies only the written
+ * paths. Both run the ONE fold, {@link foldRows}; the verbs are
+ * {@link applyVerb}'s.
+ *
+ * Verb arms — see {@link applyVerb}. A row with any other verb throws
+ * {@link UnknownVerbError}.
+ *
+ * Work, not bytes (9.22.1): a `set` row the NEXT row re-sets is skipped
+ * ({@link supersededByNextSet}) — the rows stay in the log, only the clone
+ * each would have paid is not. Every consumer inherits the skip from
+ * `foldRows`; there is no second replay loop to keep in step.
+ */
+export declare function applySmartMerge(base: any, updates: MemoryPatch, overwrite: MemoryPatch, trace: TraceEntry[]): any;
+/**
+ * The engine's commit (copy-on-write, 9.29.0 — docs/design/2026-10-copy-on-
+ * write-commit.md): the NEXT committed generation. A copy of `base`'s ROOT
+ * plus a copy of every container on each written path; every other subtree
+ * is SHARED with `base`, which is never edited — committed state is
+ * immutable-after-swap, so sharing is safe, and a commit costs O(what it
+ * wrote), not O(state). `SharedMemory.applyPatch` (live state and the
+ * redacted mirror) is its caller. Internal: the public replay is
+ * {@link applySmartMerge}.
+ */
+export declare function nextGeneration(base: any, updates: MemoryPatch, overwrite: MemoryPatch, trace: TraceEntry[]): any;
+/**
+ * The same replay, INTO `target` — no clone of its own. For a caller that
+ * already holds a private working copy (the read-side folds: `stateAt` in
+ * `time-travel/stateAt.ts` and `EventLog.materialise` clone their base ONCE
+ * and then apply every bundle here), so a fold over N bundles costs N row
+ * applications, not N clones of the whole state. Never hand it committed
+ * state: it mutates the ROOT in place. Below the root it follows the live
+ * commit's law ({@link nextGeneration}) — a container this call did not
+ * create is copied before a write passes through it — so a fold and the live
+ * state give the same value at every path, aliased subtrees included.
+ * The values it writes are its own, so `target` never aliases the log.
+ */
+export declare function applySmartMergeInto(target: any, updates: MemoryPatch, overwrite: MemoryPatch, trace: TraceEntry[]): any;
+/**
+ * The fold, for COMPARISON only (9.30.0 — the admitted record): `base` with
+ * the bundle replayed by the one verb law, copy-on-write below the root,
+ * every recorded value placed BY REFERENCE — no clone, so it costs what the
+ * bundle wrote and nothing more. It aliases the payload and every subtree of
+ * `base` the bundle did not write, and edits neither. Never hand it out,
+ * store it or write through it: `TransactionBuffer` builds one to ask whether
+ * a bundle folds back to what the stage read, then drops it.
+ */
+export declare function dryFold(base: any, updates: MemoryPatch, overwrite: MemoryPatch, trace: TraceEntry[]): any;
+/**
+ * One row of the log under the folded key's TOP-LEVEL key — what {@link foldKey}
+ * applies, in commit order.
+ */
+export interface Touch {
+    readonly verb: Verb;
+    readonly bundle: CommitBundle;
+    /** The bundle's position in the commit log. */
+    readonly commitIdx: CommitIdx;
+    /** The row's own path (DELIM-joined `TraceEntry.path`). */
+    readonly path: string;
+    /**
+     * How the row sits against the folded key (`keyPaths · relation`). ABSENT for a
+     * row on another path under the same top-level key: such a row is APPLIED (an
+     * array union on a container above the key dedups the whole array, so a sibling
+     * changes where it leaves the key) but never observed.
+     */
+    readonly relation?: PathRelation;
+}
+/** What a reader asks of {@link foldKey}. */
+export interface KeyFold {
+    /**
+     * Start at the LAST row that sets or deletes the whole TOP-LEVEL key ({@link
+     * isTotal}, on the root path itself) — rows before it cannot change anything
+     * under that key, so a reader that wants only the value skips them. A `set` of
+     * a path below the root is NOT an anchor: an earlier sibling can still move
+     * the key through a later union. Off by default: a reader that tracks how the
+     * value GREW must see every row.
+     */
+    readonly anchored?: boolean;
+    /**
+     * Called after each applied row that has a {@link Touch.relation} — on, inside
+     * or around the key (every row, with `everyRow`) — with the value AT THE KEY before it and after it
+     * (`undefined` for an absent key). The seam a provenance track and the writer
+     * rule hang on: they watch the fold, they never have a verb switch of their
+     * own. For a row INSIDE the key, an array `before` is a shallow snapshot: that
+     * row edits the fold's own copy in place.
+     */
+    readonly observe?: (touch: Touch, before: unknown, after: unknown) => void;
+    /**
+     * Observe EVERY applied row, not only the key's own. The writer rule needs it: it compares the value at the
+     * key across a WHOLE commit, and a sibling under the same top-level key can move that value — a write
+     * through a container that holds a primitive replaces the container (`nativeSet`), and with it the key.
+     */
+    readonly everyRow?: boolean;
+    /**
+     * Keep GENERATIONS at chosen commits: `at` is asked before a commit's first row (with the fold's state as
+     * it stands); for a commit it accepts, `keep` is handed the value at the key before the commit and after
+     * it — copy-on-write around that commit (the fold drops ownership of every container before and after it),
+     * so no later row edits either value. The writer rule's memoised root fold (`commitLogUtils · LogModel`)
+     * keeps the commits a key's verdict needs, once per top-level key.
+     */
+    /**
+     * The value the top-level key holds BEFORE the first row — default: absent. Never edited: the fold copies
+     * it before writing through it. `commitValueAt` on a memoised log starts from a kept generation.
+     */
+    readonly start?: unknown;
+    readonly generations?: {
+        at(commitIdx: number, state: Readonly<Record<string, unknown>>): boolean;
+        keep(commitIdx: number, before: unknown, after: unknown): void;
+    };
+}
+/**
+ * The value of ONE key after `touches` — EVERY row under its top-level key, in
+ * commit order, each already checked with {@link isVerb} — folded from an absent
+ * key, read at the key (`segs`, its DELIM segments): the value rule of
+ * `keyPaths.ts`, the fold `stateAt` does restricted to one top-level key. Top-level
+ * keys never interact under the step, so the restriction is exact.
+ *
+ * The same step ({@link applyVerb}) and the same discipline as {@link foldRows}'s
+ * `'pathCopy'`: `set` / `append` values are clones, the merge delta is detached
+ * once per BUNDLE (narrowed to the top-level key), so two `merge` rows of one
+ * bundle see the same objects, and a row that writes through a container this
+ * fold did not create copies it first. Returns `undefined` for an absent key.
+ * O(the rows under the key's top-level key), not O(the log).
+ */
+export declare function foldKey(touches: readonly Touch[], segs: string[], options?: KeyFold): unknown;

package/dist/types/lib/recorder/CommitRangeIndex.d.ts

@@ -0,0 +1,147 @@
+/**
+ * CommitRangeIndex<TLabel> — interval index over commit indices.
+ *
+ * Built incrementally during traversal: `open(label, startIdx)` when a
+ * boundary begins, `close(token, endIdx)` when it ends. Query at any
+ * commit position with `enclosing(idx)` (returns ranges containing
+ * that index, ordered outer→inner) or `overlapping(start, end)`
+ * (returns ranges intersecting a slice).
+ *
+ * See `docs/design/commit-range-index.md` for the full contract. In
+ * one paragraph: this is a generic interval data structure for
+ * commit-range queries. footprintjs owns ZERO knowledge of what
+ * labels mean — consumers (agentfootprint, lens, OTel exporters)
+ * pick their own `TLabel` type. Open ranges (mid-run, no end yet)
+ * are first-class — query results carry `endIdx: undefined` for them.
+ *
+ * Pattern: incremental builder + interval query. Same "collect during
+ *          traversal, never post-process" rule footprintjs's CLAUDE.md
+ *          requires of every observer.
+ * Role:    structural primitive for time-travel UIs and per-boundary
+ *          aggregation.
+ * Channel: consumer-driven (no engine subscription).
+ *
+ * @example
+ * ```typescript
+ * import { CommitRangeIndex } from 'foottrace';
+ *
+ * const idx = new CommitRangeIndex<string>();
+ * const t = idx.open('LLMCall', executor.getCommitCount());
+ * // ... LLM call runs, scope writes happen ...
+ * idx.close(t, executor.getCommitCount());
+ *
+ * idx.enclosing(50);  // → ranges containing commit 50, outer→inner
+ * idx.overlapping(40, 60);  // → ranges sharing the slice [40,60]
+ * idx.clear();        // wipe (e.g., on new run)
+ * ```
+ *
+ * REDACTION NOTE: labels are stored verbatim and returned verbatim in
+ * query results — the index does NOT redact `TLabel` content. If a
+ * consumer attaches a label containing PII (user email, scope reads
+ * with sensitive keys, etc.) and then serializes the index for
+ * logging or telemetry, that data leaves the trust boundary. Use
+ * `RedactionPolicy` (or your own scrubbing) on the consumer side
+ * BEFORE attaching labels. The index follows the same contract as
+ * other footprintjs storage primitives (SequenceStore, KeyedStore):
+ * storage is verbatim; redaction is the caller's responsibility.
+ */
+/** Opaque token identifying an open range. Hold onto it; pass to `close()`.
+ *  Index-scoped — using a token from one CommitRangeIndex on another is
+ *  a silent no-op (verified by the per-index `_owner` symbol).
+ *
+ *  SECURITY NOTE: the `_owner` symbol is enumerable on the token object
+ *  via `Object.getOwnPropertySymbols(token)`. This means tokens are NOT
+ *  adversary-safe — a malicious caller with access to ANY token from
+ *  this index can recover the owner symbol and forge new tokens. The
+ *  index is designed for in-process trust boundaries (cooperative
+ *  recorders sharing one runner), not for hostile-input scenarios.
+ *  If adversary-safety becomes a requirement, switch to a WeakMap-
+ *  scoped token model (see security panel review Y2). */
+export interface RangeToken {
+    /** Per-index sequential id. Opaque to consumers — they shouldn't read it. */
+    readonly _id: number;
+    /** Per-index identity — prevents accidental cross-index token misuse. */
+    readonly _owner: symbol;
+}
+/** A single range as returned by query methods. Frozen-shape — readonly fields. */
+export interface RangeEntry<TLabel> {
+    readonly label: TLabel;
+    readonly startIdx: number;
+    /** Undefined while the range is still open (mid-run boundary). */
+    readonly endIdx?: number;
+}
+export declare class CommitRangeIndex<TLabel> {
+    private entries;
+    private byId;
+    private nextId;
+    /** Identity for token scoping — each index gets a fresh symbol so
+     *  tokens from one index can't accidentally close ranges in another.
+     *  ROTATED on `clear()` to invalidate stale tokens that survived a
+     *  run reset (would otherwise hit a recycled id and silently mutate
+     *  a different range — see DS+logic panel review RED #1). */
+    private owner;
+    /**
+     * Open a new range. Returns a token the caller MUST hold and pass
+     * to `close()` later. Each `open()` gets a fresh token; tokens
+     * cannot be reused or shared across indices (silent no-op if
+     * misused — see Law 2 in the design doc). Tokens from BEFORE
+     * the most recent `clear()` are also invalid (owner symbol
+     * rotates on clear).
+     */
+    open(label: TLabel, startIdx: number): RangeToken;
+    /**
+     * Close an open range at `endIdx` (inclusive). After close, the
+     * range is queryable with both bounds. Closing an already-closed
+     * token is a no-op. Closing an unknown token (from another index,
+     * or fabricated) is a no-op.
+     */
+    close(token: RangeToken, endIdx: number): void;
+    /**
+     * Returns ALL ranges enclosing `commitIdx`, ordered outer→inner.
+     * Includes both closed and open ranges. For a closed range to
+     * enclose: `startIdx <= commitIdx <= endIdx`. For an open range:
+     * `startIdx <= commitIdx` (no upper bound check).
+     *
+     * Ordering rule: ascending by `startIdx`, with TIES BROKEN BY
+     * descending `endIdx` (wider range = outer). Open ranges (endIdx
+     * undefined) are treated as `+Infinity` for tie-break — they
+     * always sort outer of any closed range starting at the same idx.
+     * This is the only deterministic outer→inner ordering when two
+     * boundaries open at the same commit (e.g., Parallel root +
+     * its first branch).
+     *
+     * Returns a SHALLOW IMMUTABLE COPY — caller mutations don't affect
+     * internal state.
+     */
+    enclosing(commitIdx: number): readonly RangeEntry<TLabel>[];
+    /**
+     * Returns all ranges OVERLAPPING the slice `[startIdx, endIdx]`. A
+     * range overlaps if it shares at least one commit position with the
+     * slice. Use for parallel-branch detection, time-window queries,
+     * or "what boundaries fired during this slice."
+     *
+     * Sorted by the SAME outer→inner comparator as `enclosing()`:
+     * ascending by `startIdx`, ties broken by descending `endIdx`
+     * (wider = outer; open ranges treated as +Infinity).
+     *
+     * Returns a SHALLOW IMMUTABLE COPY.
+     */
+    overlapping(startIdx: number, endIdx: number): readonly RangeEntry<TLabel>[];
+    /** Total range count (open + closed). */
+    get size(): number;
+    /**
+     * Wipe all ranges + reset the token counter AND rotate the owner
+     * symbol so any token from before this clear becomes invalid.
+     * Critical: without rotating the owner, a stale token whose `_id`
+     * happens to match a recycled id after clear would silently mutate
+     * the wrong entry. Owner rotation makes stale-token close a no-op
+     * via the `_owner !== this.owner` guard.
+     *
+     * Call from a consumer's runId guard when a new run starts (e.g.,
+     * agentfootprint's `observeRunId(onNewRun)` from Phase 2).
+     */
+    clear(): void;
+    /** O(1) lookup by token id. Always returns the entry that the token
+     *  references (or undefined if the id was never opened in this index). */
+    private findById;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * slice/elementProvenance.ts — APPEND-FOLD PROVENANCE.
+ *
+ * THE PROBLEM (why this file exists): in agent charts, almost all dataflow
+ * funnels through ONE array key (`history`). A key-level slice on it
+ * degenerates to "everything depends on history" — true and useless. The
+ * question that actually triages an agent run is element-level:
+ * "which stage produced history[7]?".
+ *
+ * THE INSIGHT: the commit log already contains the answer. Under
+ * `commitValues: 'delta'` every array growth is recorded as an `append` verb
+ * whose `overwrite[key]` holds exactly the new tail — each element has an
+ * explicit birth record. Under `'full'` mode, push-style growth appears as
+ * consecutive `set`s where the previous array is a strict prefix of the next
+ * — the tail is attributable by inference. No new capture is needed; this is
+ * a pure post-hoc query.
+ *
+ * THE ALGORITHM (append-fold): WATCH the per-key verb fold — the SAME fold
+ * `commitValueAt` runs (`memory/verbs.ts` · `foldKey`: one step, `applyVerb`,
+ * for every verb; this file has no verb switch of its own) — while carrying a
+ * births array kept index-aligned with the value. The observer is told, after
+ * each row on, inside or around the key, the value at the key before it and
+ * after it, and keeps the births — for the commits that WROTE the key under
+ * the writer rule (`commitLogUtils · writersOf`; since 9.33.0 a write inside
+ * the key or around it counts, as it does for every key query): a row that
+ * records only its tail (`append`) earns an exact attribution; every other row
+ * is a whole-value transition attributed by inference. One difference from
+ * `commitValueAt`: that helper ANCHORS at the latest `set`/`delete` as a skip
+ * optimization (earlier commits cannot change the final VALUE). Provenance
+ * must fold from the FIRST touch, because full-mode growth is a chain of
+ * `set`s and the anchor would erase every birth but the last. The final value
+ * is identical either way (the fold is deterministic left-to-right) — a
+ * property test pins this equivalence.
+ *
+ * INVARIANT (maintained on every branch): when the folded value is an array,
+ * `births.length === value.length` and `births[i]` describes `value[i]`.
+ *
+ * HONESTY: every birth is labeled with how it was determined
+ * ({@link AttributionBasis}) — `'append-verb'` is engine-recorded truth,
+ * `'prefix-inference'` is a heuristic (a wholesale replacement that happens
+ * to share the old prefix is indistinguishable from an append), and
+ * `'whole-value'` is an explicit reset. Absence is honest too: a missing
+ * provenance carries a {@link MissingProvenanceReason}, mirroring
+ * `VariableSlice.missing` — one absence pattern module-wide.
+ *
+ * COMPLEXITY: delta-mode logs need no equality checks — O(total elements).
+ * Full-mode logs pay a strict-prefix check (deepEqual per element) per
+ * full-value touch: O(touches × length) element comparisons worst case.
+ * Post-hoc query, off the hot path — acceptable; measured in the perf tests.
+ */
+import type { CommitBundle } from '../memory/types.js';
+import type { ArrayProvenance, ElementBirth, StateKey } from './types.js';
+/**
+ * Element-level provenance for one array-valued key: fold the key's commits
+ * and return index-aligned birth records for every element.
+ *
+ * @param key A {@link StateKey}: the top-level key string, or a path array
+ *   for nested keys (normalised internally — no engine delimiters needed).
+ * @param options.atIdx Inclusive commit array index to fold to (default: the
+ *   whole log). NOT the executionIndex from a runtimeStageId.
+ * @returns Always an {@link ArrayProvenance}; on failure `missing` says why
+ *   (`'not-an-array'` for scalar/deleted/degraded keys — those are
+ *   `sliceForKey` territory). Blind spot shared with the whole commit-log
+ *   family: elements present in the run's INITIAL state (seeded, never
+ *   re-set in range) are invisible here.
+ */
+export declare function arrayProvenance(commitLog: CommitBundle[], key: StateKey, options?: {
+    atIdx?: number;
+}): ArrayProvenance;
+/**
+ * Convenience over {@link arrayProvenance}: the birth of ONE element.
+ * Returns `undefined` when the key has no array provenance (any
+ * {@link MissingProvenanceReason}) or `index` is out of range at `atIdx` —
+ * Map.get-like semantics; use {@link arrayProvenance} directly when you need
+ * the missing reason.
+ *
+ * @see ElementBirth
+ */
+export declare function elementProvenance(commitLog: CommitBundle[], key: StateKey, index: number, options?: {
+    atIdx?: number;
+}): ElementBirth | undefined;

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

@@ -0,0 +1,88 @@
+/**
+ * slice/forwardSliceForKey.ts — the FORWARD half of variable-first slicing.
+ *
+ * `sliceForKey` answers "why is `key` what it is?" by walking backward from
+ * the value to its causes. This file answers the opposite question, which no
+ * query answered before: **"who READ this value, and what did it FEED?"**
+ * (the production shape: *who read `recipeId`, and what did it feed?* — one
+ * query, not a manual scan of a trace viewer).
+ *
+ * ## The algorithm: LIVE RANGES, not steps
+ *
+ * A backward slice hops writer→writer. Forward, the unit is a value's LIFE:
+ *
+ * 1. Anchor at a write of `key` — the SAME anchor idiom as `sliceForKey`
+ *    (the last writer, or the last writer before `before`).
+ * 2. That value lives until the key's NEXT write (`nextWriteIdx`). Every
+ *    stage that READ `key` inside that window saw THIS value — a `read`.
+ *    (9.33.0: a write that reached the key only through paths INSIDE it — a
+ *    subflow seed, an outputMapper merge-back — changed part of the value
+ *    and does NOT end its life: a reader after it still read the rest. Every
+ *    life such a write starts or crosses carries a `'nested-rows'` note.)
+ * 3. A reading stage that also WROTE something carried the value onward —
+ *    a `fed` edge to that write, which is itself the start of a new life.
+ * 4. Descend into fed lives breadth-first (visited-set guarded, budgeted).
+ *
+ * ### LAW — the live range is `(writeIdx, nextWriteIdx]`
+ *
+ * Open at the bottom, CLOSED at the top, and both ends follow from the
+ * engine's event order (`onRead` fires PRE-commit — see CLAUDE.md):
+ * - a read by the writing stage itself (`readIdx === writeIdx`) saw the
+ *   PREVIOUS value: read-modify-write reads belong to the previous life;
+ * - a read by the OVERWRITING stage (`readIdx === nextWriteIdx`) also fired
+ *   before its commit, so it still saw THIS value.
+ * A read after that commit attributes to the NEW write, never the old one.
+ * (Granularity limit, stated because it cannot be seen: a stage that writes
+ * `key` and then re-reads it within the SAME stage read its own value; at
+ * commit-index resolution that read is indistinguishable from the one that
+ * opened the stage.)
+ *
+ * ### LAW — a `fed` edge is EXACT only under recorded read provenance
+ *
+ * With `writeProvenance: 'reads-prefix'` on, the child write's
+ * `TraceEntry.readKeys` names the keys read before it: this key IN that list
+ * is an exact edge (`basis: 'per-write'`), and this key ABSENT from it is an
+ * exact *exclusion* — no edge at all. With the dial off there is no such
+ * evidence, only "the stage read this and wrote that": the edge is stamped
+ * `basis: 'stage'` and the slice carries a `'conservative-fed-edges'` note.
+ * A conservative edge is never presented as an exact one.
+ *
+ * Budgets mirror `causalChain`'s (maxDepth 20, maxNodes 100) and a cut is
+ * STATED — `root.truncated` plus a `'truncated'` note.
+ *
+ * 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 { ForwardSlice, KeysReadSource, StateKey } from './types.js';
+/** Options for {@link forwardSliceForKey} — anchoring plus walk budgets. */
+export interface ForwardSliceForKeyOptions {
+    /**
+     * Exclusive commit-array-index upper bound for the ANCHOR search: follow
+     * the value as it stood BEFORE this idx. Same contract as
+     * `sliceForKey`'s `before` / `findLastWriter`'s `beforeIdx`.
+     *
+     * It bounds the anchor ONLY — the walk then runs forward past it, because
+     * "what did the value at step 12 go on to feed?" is the whole question.
+     */
+    before?: number;
+    /** Maximum BFS depth in value-lives (default: 20 — causalChain's). */
+    maxDepth?: number;
+    /** Maximum total nodes (default: 100 — causalChain's). */
+    maxNodes?: number;
+}
+/**
+ * Forward slice for one state key: who read this value, and what did it feed?
+ *
+ * @param commitLog Ordered commit bundles — `getSnapshot().commitLog`.
+ * @param key A {@link StateKey}: the plain key string, or a path array
+ *   (normalised through the SAME `normaliseStateKey` the backward door uses,
+ *   so both doors accept identical inputs).
+ * @param keysRead A {@link KeysReadSource} strategy or a bare lookup — the
+ *   same reads providers `sliceForKey` takes. Reads are not in the commit
+ *   log; without a provider a forward walk can see nothing, which the
+ *   `'reads-not-recorded'` note says out loud.
+ * @returns Always a {@link ForwardSlice}. Absence is a RESULT with a reason
+ *   and, for an unknown key, a bounded list of the keys the log does know.
+ */
+export declare function forwardSliceForKey(commitLog: CommitBundle[], key: StateKey, keysRead: KeysReadSource | KeysReadLookup, options?: ForwardSliceForKeyOptions): ForwardSlice;