foottrace 0.0.0-stage → 1.0.1

package/dist/lib/slice/serialize.js

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTimeline = exports.formatForwardSlice = exports.forwardSliceToJSON = exports.formatSlice = exports.sliceToJSON = void 0;
+const backtrack_js_1 = require("../memory/backtrack.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`).
+ */
+function sliceToJSON(slice) {
+    const out = {
+        key: slice.key,
+        ...(slice.before !== undefined && { before: slice.before }),
+        ...(slice.missing !== undefined && { missing: slice.missing }),
+        keysReadKind: slice.keysReadKind,
+        ...(slice.readsCoverage !== undefined && { readsCoverage: slice.readsCoverage }),
+    };
+    if (!slice.root)
+        return out;
+    out.writerId = slice.root.runtimeStageId;
+    const nodes = {};
+    const edges = [];
+    for (const node of (0, backtrack_js_1.flattenCausalDAG)(slice.root)) {
+        nodes[node.runtimeStageId] = {
+            stageId: node.stageId,
+            stageName: node.stageName,
+            keysWritten: node.keysWritten,
+            depth: node.depth,
+            ...(node.incompleteSources !== undefined && { incompleteSources: node.incompleteSources }),
+            ...(node.preRunReads !== undefined && { preRunReads: node.preRunReads }),
+        };
+        for (const edge of node.parentEdges) {
+            edges.push({
+                from: node.runtimeStageId,
+                to: edge.parent.runtimeStageId,
+                kind: edge.kind,
+                ...(edge.key !== undefined && { key: edge.key }),
+                weight: edge.weight,
+                ...(edge.basis !== undefined && { basis: edge.basis }),
+            });
+        }
+    }
+    out.nodes = nodes;
+    out.edges = edges;
+    if (slice.root.truncated)
+        out.truncated = slice.root.truncated;
+    if (slice.notes !== undefined)
+        out.notes = slice.notes;
+    return out;
+}
+exports.sliceToJSON = sliceToJSON;
+/**
+ * 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.
+ */
+function formatSlice(slice) {
+    const lines = [];
+    const anchor = slice.before !== undefined ? ` (before commit ${slice.before})` : '';
+    lines.push(`SLICE for '${slice.key}'${anchor} — reads via: ${slice.keysReadKind}`);
+    if (slice.missing === 'empty-log') {
+        lines.push('no slice: the commit log is empty (nothing has executed).');
+        return lines.join('\n');
+    }
+    if (slice.missing === 'never-written') {
+        lines.push(`no slice: '${slice.key}' was never written in range — the value came from ` +
+            'initial state, frozen run input (args), or a closure; the commit log cannot see those.');
+        return lines.join('\n');
+    }
+    const cov = slice.readsCoverage;
+    if (cov && cov.steps > 1 && cov.stepsWithReads === 0) {
+        lines.push("⚠ reads were not recorded (readTracking may be 'off') — dependencies below are " + 'unknowable, NOT absent.');
+    }
+    if (slice.root)
+        lines.push((0, backtrack_js_1.formatCausalChain)(slice.root));
+    return [...lines, ...noteLines(slice.notes ?? [])].join('\n');
+}
+exports.formatSlice = formatSlice;
+// ── Forward projections ───────────────────────────────────────────────────
+/** How many reads one node lists before the renderer says "… and N more". */
+const READS_RENDERED = 5;
+/** BFS over the forward DAG, each node exactly once (shared nodes included). */
+function flattenForwardDAG(root) {
+    const out = [];
+    const seen = new Set();
+    const queue = [root];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        out.push(node);
+        for (const edge of node.fedEdges)
+            if (!seen.has(edge.child))
+                queue.push(edge.child);
+    }
+    return out;
+}
+/** `⚠ …` lines for the honesty envelope — same rendering for both doors. */
+function noteLines(notes) {
+    return notes.map((n) => `⚠ ${n.detail}`);
+}
+/** One node's headline: who wrote the value, and how long it lived. */
+function nodeHeadline(node) {
+    const life = node.nextWriteIdx !== undefined ? `live until commit ${node.nextWriteIdx}` : 'live to the end of the run';
+    if (node.origin === 'pre-run') {
+        return `'${node.key}' from BEFORE the run (initial state / input / closure) — ${life}`;
+    }
+    return `'${node.key}' ${node.verb ?? 'set'} by ${node.stageName} (${node.runtimeStageId}) @${node.commitIdx} — ${life}`;
+}
+/**
+ * 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.
+ */
+function forwardSliceToJSON(slice) {
+    const out = {
+        key: slice.key,
+        ...(slice.before !== undefined && { before: slice.before }),
+        ...(slice.missing !== undefined && { missing: slice.missing }),
+        keysReadKind: slice.keysReadKind,
+        ...(slice.readsCoverage !== undefined && { readsCoverage: slice.readsCoverage }),
+        notes: slice.notes,
+    };
+    if (!slice.root)
+        return out;
+    const flat = flattenForwardDAG(slice.root);
+    const ids = new Map();
+    flat.forEach((node, i) => ids.set(node, `n${i}`));
+    out.rootId = ids.get(slice.root);
+    out.nodes = flat.map((node) => ({
+        id: ids.get(node),
+        key: node.key,
+        origin: node.origin,
+        ...(node.runtimeStageId !== undefined && { runtimeStageId: node.runtimeStageId }),
+        ...(node.stageId !== undefined && { stageId: node.stageId }),
+        ...(node.stageName !== undefined && { stageName: node.stageName }),
+        ...(node.commitIdx !== undefined && { commitIdx: node.commitIdx }),
+        ...(node.verb !== undefined && { verb: node.verb }),
+        ...(node.nextWriteIdx !== undefined && { nextWriteIdx: node.nextWriteIdx }),
+        depth: node.depth,
+        reads: node.reads,
+        ...(node.incompleteSources !== undefined && { incompleteSources: node.incompleteSources }),
+    }));
+    out.edges = flat.flatMap((node) => node.fedEdges.map((edge) => ({ from: ids.get(node), to: ids.get(edge.child), basis: edge.basis })));
+    if (slice.root.truncated)
+        out.truncated = slice.root.truncated;
+    if (slice.notes !== undefined)
+        out.notes = slice.notes;
+    return out;
+}
+exports.forwardSliceToJSON = forwardSliceToJSON;
+/**
+ * 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.
+ */
+function formatForwardSlice(slice) {
+    const lines = [];
+    const anchor = slice.before !== undefined ? ` (as of before commit ${slice.before})` : '';
+    lines.push(`FORWARD SLICE for '${slice.key}'${anchor} — reads via: ${slice.keysReadKind}`);
+    if (slice.missing === 'empty-log') {
+        lines.push('no forward slice: the commit log is empty (nothing has executed).');
+        return [...lines, ...noteLines(slice.notes)].join('\n');
+    }
+    if (slice.missing === 'never-written') {
+        lines.push(`no forward slice: '${slice.key}' was never written and never read in this log.`);
+        return [...lines, ...noteLines(slice.notes)].join('\n');
+    }
+    const seen = new Set();
+    const walk = (node, indent, lead = '') => {
+        const pad = '  '.repeat(indent);
+        const head = `${pad}${lead}${nodeHeadline(node)}`;
+        if (seen.has(node)) {
+            lines.push(`${head} ↳ (see above)`);
+            return;
+        }
+        seen.add(node);
+        lines.push(head);
+        if (node.incompleteSources && node.incompleteSources.length > 0) {
+            lines.push(`${pad}  ⚠ its writer also consumed ${node.incompleteSources.join('/')} — untracked`);
+        }
+        if (node.reads.length === 0) {
+            lines.push(`${pad}  (no recorded read of this value)`);
+        }
+        for (const read of node.reads.slice(0, READS_RENDERED)) {
+            lines.push(`${pad}  read by ${read.stageName} (${read.runtimeStageId}) @${read.commitIdx}`);
+        }
+        if (node.reads.length > READS_RENDERED) {
+            lines.push(`${pad}  … and ${node.reads.length - READS_RENDERED} more reads`);
+        }
+        for (const edge of node.fedEdges) {
+            walk(edge.child, indent + 1, `→ fed ${edge.basis === 'per-write' ? '[exact]' : '[conservative]'} `);
+        }
+    };
+    if (slice.root)
+        walk(slice.root, 0);
+    return [...lines, ...noteLines(slice.notes)].join('\n');
+}
+exports.formatForwardSlice = formatForwardSlice;
+/** How many moments {@link formatTimeline} renders before it says "… and N more". */
+const MOMENTS_RENDERED = 60;
+/**
+ * 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.
+ */
+function formatTimeline(timeline) {
+    const lines = [];
+    const bound = timeline.before !== undefined ? ` (before commit ${timeline.before})` : '';
+    lines.push(`TIMELINE for '${timeline.key}'${bound} — reads via: ${timeline.keysReadKind}`);
+    if (timeline.missing === 'empty-log') {
+        lines.push('no timeline: the commit log is empty (nothing has executed).');
+        return [...lines, ...noteLines(timeline.notes)].join('\n');
+    }
+    if (timeline.missing === 'never-written') {
+        lines.push(`no timeline: '${timeline.key}' was never written and never read in this log.`);
+        return [...lines, ...noteLines(timeline.notes)].join('\n');
+    }
+    const moments = timeline.moments ?? [];
+    if (moments.length === 0)
+        lines.push('(no recorded moment for this key)');
+    for (const moment of moments.slice(0, MOMENTS_RENDERED)) {
+        const where = `${moment.stageName} (${moment.runtimeStageId})`;
+        if (moment.kind === 'write') {
+            lines.push(`@${moment.commitIdx} write ${moment.verb ?? 'set'} — ${where}`);
+        }
+        else {
+            const from = moment.fromWriteIdx !== undefined ? `value from commit ${moment.fromWriteIdx}` : 'value from BEFORE the run';
+            lines.push(`@${moment.commitIdx} read  — ${where} (${from})`);
+        }
+    }
+    if (moments.length > MOMENTS_RENDERED) {
+        lines.push(`… and ${moments.length - MOMENTS_RENDERED} more moments (bounded output)`);
+    }
+    return [...lines, ...noteLines(timeline.notes)].join('\n');
+}
+exports.formatTimeline = formatTimeline;

package/dist/lib/slice/sliceForKey.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sliceForKey = void 0;
+const backtrack_js_1 = require("../memory/backtrack.js");
+const commitLogUtils_js_1 = require("../memory/commitLogUtils.js");
+const paths_js_1 = require("../memory/paths.js");
+const keyIndex_js_1 = require("./keyIndex.js");
+const keysReadSources_js_1 = require("./keysReadSources.js");
+/**
+ * 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.
+ */
+function sliceForKey(commitLog, key, keysRead, options) {
+    const source = (0, keysReadSources_js_1.resolveKeysReadSource)(keysRead);
+    const normalisedKey = (0, paths_js_1.normaliseStateKey)(key);
+    const base = {
+        key: normalisedKey,
+        ...(options?.before !== undefined && { before: options.before }),
+        keysReadKind: source.kind,
+        ...(source.coverage !== undefined && { readsCoverage: source.coverage }),
+    };
+    if (commitLog.length === 0)
+        return { ...base, missing: 'empty-log' };
+    const { writer, basis } = (0, commitLogUtils_js_1.findLastWriterWithBasis)(commitLog, normalisedKey, options?.before);
+    // F4b: what the value at the slice's point rests on, from the value twin — a redaction, the pre-run base.
+    const end = Math.min(options?.before ?? commitLog.length, commitLog.length) - 1;
+    const value = end >= 0 ? (0, commitLogUtils_js_1.commitValueAtWithBasis)(commitLog, end, normalisedKey).basis : [];
+    if (!writer) {
+        // 'never-written' already says the value came from before the run; a redaction that hid the write does not.
+        return {
+            ...base,
+            missing: 'never-written',
+            ...(value.includes('redacted') && { notes: [(0, keyIndex_js_1.redactedValueNote)(normalisedKey)] }),
+        };
+    }
+    // A writer that reached the key only through rows inside it made part of the value — say so.
+    const notes = basis.includes('nested-rows') ? [(0, keyIndex_js_1.nestedRowsNote)(normalisedKey, [commitLog.indexOf(writer)])] : [];
+    if (value.includes('from-initial-state'))
+        notes.push((0, keyIndex_js_1.fromInitialStateNote)(normalisedKey));
+    if (value.includes('redacted'))
+        notes.push((0, keyIndex_js_1.redactedValueNote)(normalisedKey));
+    // INVARIANT: `writer` came FROM this commitLog, so its runtimeStageId is
+    // always present in causalChain's index — causalChain cannot return
+    // undefined here (it only does for ids absent from the log). The non-null
+    // assertion keeps the VariableSlice contract airtight: `missing` is the
+    // ONLY absent-root state. Options pass straight through (controlDeps /
+    // weigh / maxDepth / maxNodes keep their causalChain semantics).
+    //
+    // edgeAttribution defaults to 'per-write' HERE (unlike causalChain's
+    // 'stage' default): a variable-first slice knows exactly which written key
+    // anchors the question, and per-write attribution is strictly-safe — logs
+    // without `TraceEntry.readKeys` (the writeProvenance dial off) fall back
+    // to stage-level expansion per node, byte-identically. Consumers can force
+    // 'stage' via options.
+    // Preserve this exact writer's metadata/read prefix, even when it is a
+    // continuation. Causal expansion separately uses the execution's first commit.
+    const root = (0, backtrack_js_1.causalChainFromCommit)(commitLog, writer, source.lookup, {
+        ...options,
+        edgeAttribution: options?.edgeAttribution ?? 'per-write',
+        rootLinkKeys: options?.rootLinkKeys ?? [normalisedKey],
+    });
+    return { ...base, writer, root, ...(notes.length > 0 && { notes }) };
+}
+exports.sliceForKey = sliceForKey;

package/dist/lib/slice/types.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * slice/types.ts — data shapes of the variable-first slicing layer.
+ *
+ * WHY THIS LIBRARY EXISTS (context for future readers, human or LLM):
+ * `causalChain()` (memory/backtrack.ts) answers "what influenced this STEP?"
+ * — its address space is runtimeStageIds. But every triage consumer starts
+ * from a VARIABLE: a human clicks the key `creditTier` in a UI; an LLM tool
+ * call asks "where did history[7] come from?". This library is the address
+ * translation layer: variable in → slice out. It deliberately adds NO new
+ * capture and NO new graph algorithm — it composes the commit-log primitives
+ * (findLastWriter / causalChain / the per-key verb fold) so every surface
+ * (UI panel, LLM tool, offline autopsy agent) asks the question the same way
+ * and gets the same, honestly-labeled answer.
+ *
+ * Both directions live here: BACKWARD ("why is `key` what it is" —
+ * {@link VariableSlice}) and FORWARD ("who read it, and what did it feed" —
+ * {@link ForwardSlice}, {@link KeyTimeline}). Same anchor idiom, same
+ * `KeysReadSource` strategies, same honesty vocabulary.
+ *
+ * DAG position: memory ← slice. This module may import ONLY from memory/.
+ * Recorders, engine, and runner must never be imported here — that is what
+ * keeps it a tiny, separately-evolvable library (see README.md).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/time-travel/axis.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * axis.ts — the shape of an axis, and the one safe way to narrow it.
+ *
+ * WHY THIS FILE EXISTS. `commitStops` returns `Stop[]`, and every strategy
+ * that COMPOSES it (keep the stages my domain recognises, drop the rest) rests
+ * on a shape the type never stated: `[start, …stages, end]` for a non-empty
+ * log, empty for an empty one. Each composer therefore wrote its own runtime
+ * guard against its own reading of the contract, plus a mocked-substrate test
+ * to prove the guard fires. That is one invariant, discovered three times, and
+ * the library that owns the invariant should be the one that states it.
+ *
+ * {@link splitAxis} states it. {@link filterStops} then does the whole
+ * composition — check the shape, keep what the caller keeps, RE-PARTITION the
+ * log so the dropped stages' commits are still folded somewhere, and mark the
+ * `'start'` bookend as carrying a prologue — because getting the
+ * re-partitioning right by hand is the other thing every composer had to
+ * rediscover.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterStops = exports.splitAxis = void 0;
+/**
+ * Split a strategy's stops into `{ start, stages, end }`, or say why it cannot.
+ *
+ * THE INVARIANT, stated once: for a non-EMPTY log, `commitStops` returns at
+ * least the two bookends, `'start'` first and `'end'` last, with one stop per
+ * executed stage in execution order between them. For an EMPTY log it returns
+ * `[]` — no bookends around nothing, because a cursor with nowhere to stand
+ * should say `reason: 'empty'` rather than offer two positions that are the
+ * same position.
+ *
+ * The two refusals are different facts and must not be collapsed: `'empty'`
+ * means the run committed nothing, `'not-bookended'` means a strategy broke
+ * the contract. A composer that treats them alike reports a broken strategy as
+ * an empty run.
+ *
+ * @example
+ * ```typescript
+ * import { commitStops, splitAxis } from 'foottrace';
+ *
+ * const axis = splitAxis(commitStops(snapshot.commitLog, snapshot.executionTree));
+ * if (axis.ok) {
+ *   axis.start.commitIdx;          // -1 — the fold base
+ *   axis.stages.map((s) => s.label);
+ *   axis.end.lastCommitIdx;        // the last bundle in the log
+ * } else {
+ *   axis.reason;                   // 'empty' | 'not-bookended'
+ * }
+ * ```
+ */
+function splitAxis(stops) {
+    const kinds = Object.freeze(stops.map((stop) => stop.kind));
+    if (stops.length === 0)
+        return { ok: false, reason: 'empty', kinds };
+    const start = stops[0];
+    const end = stops[stops.length - 1];
+    if (start.kind !== 'start' || end.kind !== 'end' || stops.length < 2) {
+        return { ok: false, reason: 'not-bookended', kinds };
+    }
+    return { ok: true, start, stages: Object.freeze(stops.slice(1, -1)), end };
+}
+exports.splitAxis = splitAxis;
+/**
+ * `stop` retyped to the OUTPUT vocabulary, with any meta it already carried
+ * left behind. The input axis may itself be a filtered one (a Beat axis being
+ * narrowed into a Tag axis), and a `true` decision keeps the STOP, not the
+ * other strategy's classification: a `Stop<Tag>` whose `meta` is a Beat would
+ * be a lie the type could not catch. Only the decision may supply a meta.
+ */
+function retyped(stop) {
+    if (stop.meta === undefined)
+        return stop;
+    const out = {};
+    const fields = stop;
+    for (const key of Object.keys(fields))
+        if (key !== 'meta')
+            out[key] = fields[key];
+    return out;
+}
+/**
+ * Build a FILTERING strategy's axis out of another strategy's stops.
+ *
+ * The rule, in one sentence: keep the stages `keep` recognises, and give the
+ * survivors the log back.
+ *
+ * **Meta is the decision's, never inherited.** The input may already be a
+ * filtered axis carrying another strategy's `meta`; a `true` (or a meta-less
+ * object) keeps the stop and DROPS that meta, so a `Stop<TMeta>` never carries
+ * a value of some other type under `TMeta`. The bookends carry none either.
+ *
+ * **The survivors re-partition the log.** A dropped stage's commits still
+ * happened, so they fold into the stop that PRECEDES them: every kept stop's
+ * `lastCommitIdx` runs to just before the next kept stop begins. Nothing is
+ * orphaned and `stateAt(stop)` stays "the state that existed when the next
+ * kept stage started".
+ *
+ * **What that costs `'start'`, said out loud.** The commits before the first
+ * survivor have nowhere else to go, so `'start'` absorbs them: its fold is the
+ * run's base PLUS that prologue — the state the first stop READ, not the raw
+ * base. The returned start therefore carries `prologue: true` whenever it
+ * actually absorbed a stage, and a renderer that means "before anything ran"
+ * checks `kind === 'start' && !prologue`. That flag is the whole reason this
+ * helper exists rather than a `.filter()` call.
+ *
+ * **A log with nothing kept** yields the two bookends and nothing between
+ * them: `'start'` folds the whole log, `'end'` folds the whole log, and
+ * `jumpTo` on any stage id refuses with `reason: 'miss'`. An axis with nowhere
+ * meaningful to stand — which is the truthful shape for a run this strategy
+ * recognises nothing in, and NOT the `[]` that says the log was empty.
+ *
+ * @throws when `stops` is non-empty but not bookended — see {@link splitAxis}.
+ *   Only a strategy can cause that; a run cannot, so it is a contract error
+ *   and not a condition to fold into the data.
+ *
+ * @example
+ * ```typescript
+ * import { commitStops, filterStops } from 'foottrace';
+ * import type { Stop, TimeTravelStrategy } from 'foottrace';
+ *
+ * type Milestone = { kind: 'llm-turn' | 'tool-call'; label: string };
+ * declare function milestoneFor(runtimeStageId: string): Milestone | null;
+ *
+ * const milestoneStops: TimeTravelStrategy<Milestone> = {
+ *   stopsFor: (log, tree) =>
+ *     filterStops<Milestone>(commitStops(log, tree), (stop) => {
+ *       const m = milestoneFor(stop.runtimeStageId);
+ *       return m ? { label: m.label, meta: m } : null;
+ *     }),
+ * };
+ *
+ * const cursor = timeTravel(snapshot, { strategy: milestoneStops });
+ * cursor.at()?.meta?.kind;        // 'llm-turn' — no re-derivation
+ * cursor.stops[0].prologue;       // true when stages ran before the first turn
+ * ```
+ */
+function filterStops(stops, keep) {
+    const axis = splitAxis(stops);
+    if (!axis.ok) {
+        if (axis.reason === 'empty')
+            return [];
+        throw new Error('filterStops: expected a bookended axis — [start, …stages, end] — got kinds ' +
+            `[${axis.kinds.join(', ')}]. Only a strategy can produce that shape; a run cannot.`);
+    }
+    const kept = [];
+    for (const stop of axis.stages) {
+        const decision = keep(stop);
+        if (!decision)
+            continue;
+        if (decision === true)
+            kept.push({ stop });
+        else
+            kept.push({ stop, label: decision.label, meta: decision.meta });
+    }
+    // The log's last index, taken from the `'end'` bookend rather than a length:
+    // `end` is the one stop guaranteed to fold the whole log, and this function
+    // is never handed the log itself.
+    const lastIdx = axis.end.lastCommitIdx;
+    const first = kept[0];
+    const out = [
+        {
+            ...retyped(axis.start),
+            step: 0,
+            lastCommitIdx: first ? first.stop.commitIdx - 1 : lastIdx,
+            // Only when a STAGE was actually absorbed. An axis that kept everything
+            // has the same start it always had, and says nothing it need not say.
+            ...(first && first.stop.step > 1 ? { prologue: true } : {}),
+            ...(!first && axis.stages.length > 0 ? { prologue: true } : {}),
+        },
+    ];
+    for (const [i, row] of kept.entries()) {
+        const next = kept[i + 1];
+        out.push({
+            ...retyped(row.stop),
+            step: out.length,
+            lastCommitIdx: next ? next.stop.commitIdx - 1 : lastIdx,
+            ...(row.label !== undefined ? { label: row.label } : {}),
+            ...(row.meta !== undefined ? { meta: row.meta } : {}),
+        });
+    }
+    out.push({ ...retyped(axis.end), step: out.length });
+    return out;
+}
+exports.filterStops = filterStops;