foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * stateAt — the fold at a stop.
+ *
+ * The commit log stores DIFFS. Replaying them onto the run's fold base
+ * reproduces the state as it stood after any commit — byte-for-byte the state
+ * the next stage saw, in both `commitValues` encodings, because the replay
+ * runs through `applySmartMergeInto`, the one verb law (`memory/verbs.ts`) the
+ * live commit itself uses. There is deliberately no second implementation of
+ * the verbs here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateAt = exports.foldLegsFrom = exports.foldLegs = exports.readSource = void 0;
+const freeze_js_1 = require("../capture/freeze.js");
+const utils_js_1 = require("../memory/utils.js");
+const bundles_js_1 = require("./bundles.js");
+/**
+ * Read whichever shape the caller handed us — `commitLog` (a run snapshot) or
+ * `history` (a subflow's own log) — narrowing the rows to commit bundles as it
+ * goes (see `bundles.ts`: a row that is not one becomes an index-holding gap).
+ */
+function readSource(source) {
+    const base = source?.initialState;
+    if (!source)
+        return { log: [], gaps: [], base };
+    const withLog = source;
+    const raw = Array.isArray(withLog.commitLog)
+        ? withLog.commitLog
+        : Array.isArray(source.history)
+            ? source.history
+            : undefined;
+    const { log, gaps } = (0, bundles_js_1.readLog)(raw);
+    return { log, gaps, base };
+}
+exports.readSource = readSource;
+/**
+ * Fold one chain of legs: every leg BEFORE `legIdx` in full, then `legIdx`
+ * through `through`.
+ *
+ * THE LEG RULE. A leg that carries its own `initialState` RESTARTS the
+ * accumulation from it — on a pause/resume that base IS the state at the
+ * pause, recorded by the engine, and is authoritative over anything the
+ * previous leg's log rebuilt. A leg with no base (a pre-9.17 snapshot, a
+ * hand-built log) CONTINUES from what the earlier legs folded, which is the
+ * best honest answer available and is exactly what `basis` then reports.
+ *
+ * With a single leg this is the 9.17.0 fold, unchanged.
+ */
+function foldLegs(legs, legIdx, through) {
+    return foldLegsFrom(legs, legIdx, through).folded;
+}
+exports.foldLegs = foldLegs;
+/** Apply `log[from + 1 .. end]` of one leg into `out`, collecting the leg's facts. */
+function applyLeg(out, leg, from, end, redactedPaths, skipped) {
+    for (const gap of leg.gaps) {
+        if (gap.index > from && gap.index <= end)
+            (skipped ??= []).push(gap);
+    }
+    for (let i = from + 1; i <= end; i++) {
+        const bundle = leg.log[i];
+        if (!bundle)
+            continue;
+        for (const path of bundle.redactedPaths ?? [])
+            redactedPaths.add(path);
+        (0, utils_js_1.applySmartMergeInto)(out, bundle.updates, bundle.overwrite, bundle.trace);
+    }
+    return skipped;
+}
+/**
+ * The fold, resumable. ONE clone per fold: the base is cloned once (or `{}`
+ * stands in), every bundle is applied INTO that copy, and the state handed
+ * out is one more clone, frozen — so the working copy stays private and a
+ * later step can continue from it. Same answer as the 9.17.0 fold, pinned by
+ * test/lib/time-travel/fold-memo.test.ts against a fresh fold at every stop.
+ */
+function foldLegsFrom(legs, legIdx, through, memo) {
+    const last = legs[legIdx];
+    const endOnLeg = last ? Math.min(through, last.log.length - 1) : -1;
+    const lastThrough = endOnLeg < -1 ? -1 : endOnLeg;
+    const resumable = memo !== undefined && memo.legIdx === legIdx && lastThrough >= memo.through;
+    let based = resumable ? memo.based : false;
+    let out = resumable ? memo.out : {};
+    const redactedPaths = new Set(resumable ? memo.redactedPaths : []);
+    let skipped = resumable && memo.skipped ? [...memo.skipped] : undefined;
+    if (resumable) {
+        if (last)
+            skipped = applyLeg(out, last, memo.through, lastThrough, redactedPaths, skipped);
+    }
+    else {
+        for (let leg = 0; leg <= legIdx && leg < legs.length; leg++) {
+            const source = legs[leg];
+            if (source.base && typeof source.base === 'object') {
+                out = structuredClone(source.base);
+                based = true;
+            }
+            const end = leg === legIdx ? lastThrough : source.log.length - 1;
+            skipped = applyLeg(out, source, -1, end, redactedPaths, skipped);
+        }
+    }
+    const basis = based ? 'initial+log' : 'log-only';
+    const folded = {
+        // The one freeze walk (`capture/freeze.ts`): a typed array in state is skipped, not thrown on.
+        state: (0, freeze_js_1.deepFreeze)(structuredClone(out)),
+        basis,
+        redacted: redactedPaths.size > 0,
+        redactedPaths: Object.freeze([...redactedPaths].sort()),
+        throughCommitIdx: lastThrough,
+        ...(skipped ? { skipped: Object.freeze(skipped) } : {}),
+    };
+    return { folded, memo: { legIdx, through: lastThrough, out, based, redactedPaths, skipped } };
+}
+exports.foldLegsFrom = foldLegsFrom;
+/**
+ * Fold `source`'s log from its base up to and including `commitIdx`.
+ *
+ * @param source    A run snapshot (`commitLog` + `initialState`) or a subflow
+ *                  subtree (`history` + `initialState`). Both spellings work,
+ *                  and the rows may be unvalidated (`unknown[]`) — a row that
+ *                  is not a commit bundle is skipped and REPORTED, by index,
+ *                  in {@link FoldedState.skipped}, never crashed on.
+ * @param commitIdx ARRAY INDEX of the last bundle to fold, inclusive. `-1`
+ *                  (or any negative) folds nothing and returns the base —
+ *                  the state before the run's first commit. Past the end
+ *                  clamps to the end; the result's `throughCommitIdx` reports
+ *                  where the fold actually stopped.
+ *
+ * @returns A detached, deeply frozen state plus how it was derived: `basis`
+ *   says whether the real fold base was available, `redacted` /
+ *   `redactedPaths` say where the log was scrubbed at write time, and
+ *   `skipped` says which rows could not be read. The engine redacts values as
+ *   it records them, so a replay of a redacted run yields `'REDACTED'` in
+ *   those places — correct, and said out loud rather than presented as the
+ *   real value.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = executor.getSnapshot();
+ * const { state, basis } = stateAt(snapshot, 3);   // after the 4th commit
+ * console.log(basis, state);                        // 'initial+log' { ... }
+ *
+ * // A subflow's own log folds identically:
+ * const inner = getSubtreeSnapshot(snapshot, 'sf-payment')!;
+ * stateAt(inner, 0).state;                          // after the subflow's first commit
+ *
+ * // A STORED recording needs no cast — its rows are `unknown[]`:
+ * const stored = JSON.parse(await fs.readFile(path, 'utf8'));
+ * stateAt(stored, 3).skipped;                       // undefined, or the bad rows
+ * ```
+ */
+function stateAt(source, commitIdx) {
+    // `NaN` is out of contract; treat it as "fold nothing" rather than letting
+    // it flow through the arithmetic into `throughCommitIdx`, where it would
+    // serialize as `null` and tell a consumer nothing about where the fold
+    // stopped. (±Infinity needs no special case: it clamps like any index past
+    // either end.)
+    const asked = Number.isNaN(commitIdx) ? -1 : Math.floor(commitIdx);
+    return foldLegs([readSource(source)], 0, asked);
+}
+exports.stateAt = stateAt;

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

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * tagStops — the stops a chart DECLARED, read back off its commit log.
+ *
+ * WHY THIS FILE EXISTS. `commitStops` is the only stop grammar the substrate
+ * knows: one stop per executed stage. Every richer axis — milestones, turns,
+ * tool calls — was a consumer's classifier over `runtimeStageId`: a switch
+ * that parses `#` and `/`, lives outside the recording, and goes stale when
+ * a stage is renamed. Since 9.21.0 the author can put NAMES on a stage at
+ * build time (`FlowChartBuilder.tag` / `options.tags`) and the engine stamps
+ * them on the stage's commit bundle (`CommitBundle.tags`). This strategy
+ * reads them back: a stored recording from ANY chart scrubs by its own
+ * milestones, with no id conventions in the reader.
+ *
+ * WHAT IT IS. One expression over `filterStops(commitStops(...))`: keep the
+ * stops whose FIRST bundle carries a tag (any of the asked-for ones, or any
+ * tag at all when none are asked for), give the survivors the log back, and
+ * carry the bundle's whole tag array as `Stop.meta`. Everything a filtering
+ * axis owes — the bookend guard, the re-partition so a dropped stage's
+ * commits fold into the tagged stop BEFORE them, `prologue` on a start that
+ * absorbed stages — comes from `filterStops`, stated once, in `axis.ts`.
+ *
+ * WHAT IT IS NOT. Not a second vocabulary: the strings are the consumer's,
+ * carried verbatim. Not a derivation: a stage with no declared tag gets no
+ * stop here, however recognisable its id — a reader that wants ids classified
+ * writes that keep rule itself (`filterStops`), or reads the fold
+ * (`stateAt`) and keeps by what changed. And not a re-walk: only a tag the
+ * engine actually stamped can put a stop on this axis.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagStops = void 0;
+const axis_js_1 = require("./axis.js");
+const commitStops_js_1 = require("./commitStops.js");
+/**
+ * The tags a stop's first bundle carries, or `undefined` when it carries
+ * none. Reads the bundle at `stop.commitIdx` — the FIRST commit of the
+ * stage, which is where `StageContext.commit` records the stamp (a fork
+ * child's repeat and a mount's exit — the bundles with a `phase` — carry
+ * none).
+ */
+function tagsAt(log, stop) {
+    const raw = log[stop.commitIdx]?.tags;
+    // A stored row is `unknown[]`-shaped until narrowed: keep only the strings,
+    // so a damaged row can never put a non-name into `Stop.meta`.
+    const tags = Array.isArray(raw) ? raw.filter((t) => typeof t === 'string') : [];
+    return tags.length > 0 ? tags : undefined;
+}
+/**
+ * A {@link TimeTravelStrategy} whose stops are the stages that carry a
+ * declared tag.
+ *
+ * **Keep rule: any-of.** A stop survives when its bundle's `tags` shares at
+ * least one name with `tags`; with `tags` omitted (or empty), every tagged
+ * stop survives. All-of, or a rule over more than the tags, is a
+ * `filterStops` call away — the library owns no vocabulary, so it owns no
+ * richer rule either.
+ *
+ * **Attribution by precedence.** An untagged stage's commits fold into the
+ * tagged stop BEFORE it (what `filterStops` does); the commits before the
+ * first tagged stage are absorbed by `'start'`, which then says
+ * `prologue: true`. A run with no tagged stage yields the two bookends only.
+ *
+ * **`meta` is the array.** Each kept stop carries its bundle's full `tags`
+ * (not just the ones asked for), so a reader that filtered on
+ * `'milestone:llm-turn'` can still see the stage was also `'audit'`.
+ *
+ * **The equivalence law.** `stateAt(stop)` at every kept stop equals
+ * `commitStops`'s fold at the same commit index — a filtering axis moves the
+ * stops, never the log.
+ *
+ * @example
+ * ```typescript
+ * import { flowChart } from 'footprintjs';
+ * import { tagStops, timeTravel } from 'foottrace';
+ *
+ * const chart = flowChart<State>('Seed', seedFn, 'seed')
+ *   .addFunction('Call model', callFn, 'call-llm')
+ *   .tag('milestone:llm-turn')
+ *   .addFunction('Route', routeFn, 'route')
+ *   .tag('milestone:decision')
+ *   .build();
+ *
+ * // …run it, keep the snapshot…
+ * const cursor = timeTravel(snapshot, { strategy: tagStops(['milestone:llm-turn']) });
+ * cursor.stops.map((s) => s.label);   // ['Run start', 'Call model', 'Run end']
+ * cursor.stops[1].meta;               // ['milestone:llm-turn']
+ * cursor.stops[0].prologue;           // true — 'seed' ran before the first turn
+ * ```
+ */
+function tagStops(tags) {
+    const wanted = tags && tags.length > 0 ? new Set(tags) : undefined;
+    return {
+        stopsFor(commitLog, executionTree, subflowResults) {
+            return (0, axis_js_1.filterStops)((0, commitStops_js_1.commitStops)(commitLog, executionTree, subflowResults), (stop) => {
+                const stamped = tagsAt(commitLog, stop);
+                if (!stamped)
+                    return null;
+                if (wanted && !stamped.some((tag) => wanted.has(tag)))
+                    return null;
+                return { meta: stamped };
+            });
+        },
+    };
+}
+exports.tagStops = tagStops;

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

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * timeTravel — a reader's cursor over a finished trace.
+ *
+ * The five laws this file implements (and the folder README states with an
+ * example each):
+ *
+ *   1. ONE cursor. This object holds the only position. `drill()` returns a
+ *      separate cursor over a separate log, never a second position here.
+ *   2. A miss never moves. Every refusal returns the reason and leaves the
+ *      cursor exactly where it was.
+ *   3. A fold result is detached. `stateAt` returns frozen, cloned state that
+ *      shares nothing with the engine.
+ *   4. Marks live beside the log. They are the reader's notes, never written
+ *      into the run's record.
+ *   5. Stops are DERIVED from the recorded log — read-time queries over
+ *      collected data, never a re-walk that invents what was not recorded.
+ *
+ * A CHAIN (9.18.0) does not add a sixth law and does not bend these five: it
+ * is still one cursor, over sources that are still only read. What it adds is
+ * that the STEPS run across a pause/resume — see `chain.ts` for the ordering
+ * and lineage checks, and for why commit indices stay run-local.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeTravel = void 0;
+const runtimeStageId_js_1 = require("../ids/runtimeStageId.js");
+const bundles_js_1 = require("./bundles.js");
+const chain_js_1 = require("./chain.js");
+const commitStops_js_1 = require("./commitStops.js");
+const stateAt_js_1 = require("./stateAt.js");
+class Cursor {
+    stops;
+    path;
+    mountRuntimeStageId;
+    parent;
+    sourceCount;
+    legs;
+    sources;
+    options;
+    _marks;
+    step;
+    /** The last fold's working copy, so a step forward applies one bundle (9.25.0). */
+    foldMemo;
+    constructor(sources, options, path, parent, mountRuntimeStageId) {
+        this.sources = sources;
+        this.options = options;
+        this.path = path;
+        this.parent = parent;
+        this.mountRuntimeStageId = mountRuntimeStageId;
+        this.legs = sources.map((source) => (0, stateAt_js_1.readSource)(source));
+        this.sourceCount = sources.length;
+        // The shipped strategy has no vocabulary of its own (`meta` is never set),
+        // so it serves any `TMeta` a caller asked for.
+        const strategy = options.strategy ?? commitStops_js_1.commitStopsStrategy;
+        // ONE CALL PER SOURCE, with that source's own log and tree: a strategy
+        // never has to know it is part of a chain, and its indices stay local to
+        // the leg it was handed.
+        const perSource = this.legs.map((leg, i) => strategy.stopsFor(leg.log, (0, bundles_js_1.readTree)(sources[i].executionTree), sources[i].subflowResults));
+        this.stops = Object.freeze(sources.length === 1 ? perSource[0] : chainStops(perSource));
+        this._marks = [...(options.marks ?? [])];
+        this.step = 0;
+    }
+    // ── Position ─────────────────────────────────────────────────────────────
+    at() {
+        return this.stops[this.step];
+    }
+    moveTo(step) {
+        const from = this.at();
+        this.step = step;
+        return { moved: true, from, to: this.stops[step] };
+    }
+    /** Law 2: a refusal never touches `this.step`. */
+    refuse(reason, nearest) {
+        const at = this.at();
+        return nearest ? { moved: false, reason, at, nearest } : { moved: false, reason, at };
+    }
+    first() {
+        if (this.stops.length === 0)
+            return this.refuse('empty');
+        if (this.step === 0)
+            return this.refuse('clamped');
+        return this.moveTo(0);
+    }
+    last() {
+        if (this.stops.length === 0)
+            return this.refuse('empty');
+        const end = this.stops.length - 1;
+        if (this.step === end)
+            return this.refuse('clamped');
+        return this.moveTo(end);
+    }
+    prev() {
+        if (this.stops.length === 0)
+            return this.refuse('empty');
+        if (this.step === 0)
+            return this.refuse('clamped');
+        return this.moveTo(this.step - 1);
+    }
+    next() {
+        if (this.stops.length === 0)
+            return this.refuse('empty');
+        if (this.step >= this.stops.length - 1)
+            return this.refuse('clamped');
+        return this.moveTo(this.step + 1);
+    }
+    jumpTo(target) {
+        if (this.stops.length === 0)
+            return this.refuse('empty');
+        if (typeof target === 'number') {
+            const step = Math.trunc(target);
+            if (Number.isNaN(step))
+                return this.refuse('miss');
+            if (step < 0)
+                return this.refuse('clamped', this.stops[0]);
+            if (step > this.stops.length - 1)
+                return this.refuse('clamped', this.stops[this.stops.length - 1]);
+            if (step === this.step)
+                return this.refuse('clamped');
+            return this.moveTo(step);
+        }
+        // `''` is not an address: it is what the bookends and any pre-stage
+        // root commit carry. Those are reached by step, never by id.
+        if (target === '')
+            return this.refuse('miss');
+        const hit = this.stops.find((stop) => stop.runtimeStageId === target);
+        if (!hit)
+            return this.refuse('miss', this.nearestTo(target));
+        if (hit.step === this.step)
+            return this.refuse('clamped');
+        return this.moveTo(hit.step);
+    }
+    /**
+     * The closest namable stop for a `runtimeStageId` that is not on this axis:
+     * the last stop of the same STAGE (a different iteration of the same node),
+     * else the last stop whose commit precedes the missed id's execution index.
+     * Naming a neighbour is a courtesy for the UI — it never moves the cursor.
+     */
+    nearestTo(runtimeStageId) {
+        if (!(0, runtimeStageId_js_1.isExecutionKey)(runtimeStageId))
+            return undefined;
+        const stagePart = (0, runtimeStageId_js_1.stageIdOf)(runtimeStageId);
+        const wanted = (0, runtimeStageId_js_1.executionIndexOf)(runtimeStageId);
+        let sameStage;
+        let byIndex;
+        for (const stop of this.stops) {
+            if (!(0, runtimeStageId_js_1.isExecutionKey)(stop.runtimeStageId))
+                continue;
+            if ((0, runtimeStageId_js_1.stageIdOf)(stop.runtimeStageId) === stagePart)
+                sameStage = stop;
+            if (!Number.isNaN(wanted)) {
+                const idx = (0, runtimeStageId_js_1.executionIndexOf)(stop.runtimeStageId);
+                if (!Number.isNaN(idx) && idx <= wanted)
+                    byIndex = stop;
+            }
+        }
+        return sameStage ?? byIndex;
+    }
+    // ── Reading ──────────────────────────────────────────────────────────────
+    stateAt(stop) {
+        const target = stop ?? this.at();
+        const leg = target?.sourceIdx ?? 0;
+        const fold = (0, stateAt_js_1.foldLegsFrom)(this.legs, leg, target ? target.lastCommitIdx : -1, this.foldMemo);
+        this.foldMemo = fold.memo;
+        const folded = fold.folded;
+        // Which leg the index belongs to, but only when there is more than one —
+        // a single-source fold keeps the 9.17.0 shape exactly.
+        return this.legs.length > 1 ? { ...folded, sourceIdx: leg } : folded;
+    }
+    changedSince(from) {
+        const to = this.at();
+        if (!to)
+            return Object.freeze([]);
+        const start = from ?? this.stops[this.step - 1];
+        // No earlier stop (we are at `'start'`) ⇒ everything up to here: nothing
+        // on a run cursor, and the subflow's `inputMapper` seed on a drilled one
+        // (the start bookend covers the seed that precedes stage one — `commitStops`).
+        const toLeg = to.sourceIdx ?? 0;
+        const fromLeg = start ? start.sourceIdx ?? 0 : toLeg;
+        const afterIdx = start ? start.lastCommitIdx : -1;
+        const keys = new Set();
+        // A range that crosses a chain seam is walked leg by leg: the tail of the
+        // leg it started in, every leg in between whole, then the head of the leg
+        // it ends in. Backwards ranges walk nothing and give `[]`, as before.
+        for (let leg = fromLeg; leg <= toLeg && leg < this.legs.length; leg++) {
+            const log = this.legs[leg].log;
+            const lo = leg === fromLeg ? afterIdx + 1 : 0;
+            const hi = leg === toLeg ? to.lastCommitIdx : log.length - 1;
+            for (let i = lo; i <= hi; i++) {
+                const bundle = log[i];
+                if (!bundle)
+                    continue;
+                for (const entry of bundle.trace)
+                    keys.add(entry.path);
+            }
+        }
+        return Object.freeze([...keys].sort());
+    }
+    // ── Marks (law 4: beside the log, never in it) ───────────────────────────
+    mark(name, stop) {
+        const target = stop ?? this.at();
+        if (!target)
+            return undefined;
+        const entry = Object.freeze({ name, runtimeStageId: target.runtimeStageId, step: target.step });
+        const existing = this._marks.findIndex((m) => m.name === name);
+        if (existing >= 0)
+            this._marks[existing] = entry;
+        else
+            this._marks.push(entry);
+        return entry;
+    }
+    marks() {
+        return Object.freeze([...this._marks]);
+    }
+    jumpToMark(name) {
+        if (this.stops.length === 0)
+            return this.refuse('empty');
+        const entry = this._marks.find((m) => m.name === name);
+        if (!entry)
+            return this.refuse('miss');
+        // Resolve by runtimeStageId first — the address that survives a change of
+        // strategy — and fall back to the remembered step only for the bookends,
+        // which have no stage id of their own.
+        const byId = entry.runtimeStageId
+            ? this.stops.find((stop) => stop.runtimeStageId === entry.runtimeStageId)
+            : this.stops[entry.step];
+        if (!byId)
+            return this.refuse('miss', this.nearestTo(entry.runtimeStageId));
+        if (byId.step === this.step)
+            return this.refuse('clamped');
+        return this.moveTo(byId.step);
+    }
+    // ── Drilling (law 1: a separate cursor, not a second position) ───────────
+    drill(mountRuntimeStageId) {
+        // On a chain, the mount is looked for in every leg — a subflow that ran
+        // before the pause is in the first snapshot's results, one that ran after
+        // is in the second's. Ids are unique across a sound chain (chain.ts
+        // refuses one where they are not), so the first hit is the only hit.
+        let results;
+        let result;
+        for (const source of this.sources) {
+            // A stored recording's results are parsed JSON: read them as a map only
+            // when they are one, and as "no subflows" otherwise.
+            if (!(0, bundles_js_1.isPlainish)(source.subflowResults))
+                continue;
+            const hit = source.subflowResults[mountRuntimeStageId];
+            if (hit) {
+                results = source.subflowResults;
+                result = hit;
+                break;
+            }
+        }
+        const tree = result?.treeContext;
+        if (!results || !result || !tree || !Array.isArray(tree.history))
+            return undefined;
+        // `path` is the subflow PATH — the same string for every iteration of a
+        // mount inside a loop. `mountRuntimeStageId` is the iteration actually
+        // opened, so a UI can label and key three drill panels over `sfx#2`,
+        // `sfx#8`, `sfx#14` apart instead of calling all three 'sfx'.
+        const childPath = result.subflowId ?? mountRuntimeStageId;
+        const child = {
+            // Rows are narrowed per bundle when the child reads them — a stored
+            // recording's inner history needs no cast either.
+            commitLog: tree.history,
+            initialState: tree.initialState,
+            executionTree: tree.stageContexts,
+            // Nested subflow results are merged UP into one flat, dual-keyed map, so
+            // the child can drill further through the same map.
+            subflowResults: results,
+        };
+        return new Cursor([child], { strategy: this.options.strategy }, childPath, this, mountRuntimeStageId);
+    }
+}
+/**
+ * Re-step per-source stops into ONE axis.
+ *
+ * The INTERIOR bookends go: a `'start'` on any leg but the first, and an
+ * `'end'` on any leg but the last, are bookends of a leg and not of the run —
+ * keeping them would put "the run is over" in the middle of the axis. The
+ * commits they covered are not orphaned: a fold always replays its leg from
+ * that leg's own base, and `changedSince` walks a seam-crossing range leg by
+ * leg (including the head of the leg it ends in). The stops' `commitIdx` /
+ * `lastCommitIdx` ranges PARTITION EACH LEG, never span the seam: a stop's
+ * range ends at its own leg's last index, and the next leg's first stop opens
+ * at that leg's 0.
+ */
+function chainStops(perSource) {
+    // "Interior" is measured against the legs that actually CONTRIBUTE stops: a
+    // leg whose log was empty has no bookends to drop and must not make its
+    // neighbour's `'start'` or `'end'` interior — the chained axis still opens
+    // with the first stop that exists and closes with the last.
+    const contributing = perSource.map((stops) => stops.length > 0);
+    const firstLeg = contributing.indexOf(true);
+    const lastLeg = contributing.lastIndexOf(true);
+    const out = [];
+    for (const [sourceIdx, stops] of perSource.entries()) {
+        for (const stop of stops) {
+            if (sourceIdx > firstLeg && stop.kind === 'start')
+                continue;
+            if (sourceIdx < lastLeg && stop.kind === 'end')
+                continue;
+            out.push({ ...stop, step: out.length, sourceIdx });
+        }
+    }
+    return out;
+}
+/**
+ * Open a reader's cursor over a finished run.
+ *
+ * Nothing here executes anything: `snapshot` is a record of a run that already
+ * happened, and every question is answered by reading it. A stored JSON
+ * snapshot works exactly like a live one — since 9.18.0 its `commitLog` may be
+ * an unvalidated `unknown[]`, narrowed per bundle where the fold reads it, so
+ * a replayed recording needs no cast.
+ *
+ * @param snapshot `executor.getSnapshot()`, or any object with the same
+ *   shape — including one round-tripped through JSON, or a subflow subtree
+ *   (`getSubtreeSnapshot()`, whose log is spelled `history`). An ARRAY of them
+ *   is a CHAIN: a pause and its resume read as one axis (see below).
+ * @param options `strategy` chooses how stops are derived (default:
+ *   `commitStops`, one stop per executed stage); `marks` seeds the cursor with
+ *   bookmarks, e.g. restored from a saved reading session.
+ *
+ * @throws when a chain is not in run order, or its legs are not from one
+ *   lineage — three checks, each with its own reason (see `chain.ts`):
+ *   no `runtimeStageId` may appear in two legs; each leg's first execution
+ *   index must be past the previous leg's last (the engine never resets the
+ *   counter across a resume); and each leg's `initialState` must deep-equal
+ *   the state the legs before it fold to — on a resume that base IS the state
+ *   at the pause, so a foreign leg whose indices merely happen to be higher
+ *   is refused too. The third check runs only where the record allows it: the
+ *   later leg must carry an `initialState` and the earlier legs must fold from
+ *   a real base with no unreadable rows; otherwise (an older recording with
+ *   no base) the chain rests on the two index checks alone, and the fold's
+ *   `basis` says what it stood on.
+ *
+ * @example
+ * ```typescript
+ * const tt = timeTravel(executor.getSnapshot());
+ * tt.jumpTo('score-risk#4');
+ * console.log(tt.changedSince());        // ['riskScore', 'tier']
+ * console.log(tt.stateAt().state);       // state as that stage left it
+ * tt.mark('the bad one');
+ * const inner = tt.drill('sf-payment#7'); // a separate cursor, its own log
+ *
+ * // A pause and its resume, read as ONE axis:
+ * const chained = timeTravel([pausedSnapshot, resumedSnapshot]);
+ * chained.last();                         // the run's real end
+ * chained.at()!.sourceIdx;                // 1 — which leg the indices are in
+ * chained.jumpTo('approve#3');            // finds it in either leg
+ * ```
+ */
+function timeTravel(snapshot, options = {}) {
+    const sources = Array.isArray(snapshot) ? snapshot : [snapshot];
+    // A one-element array is not a chain: it is the plain cursor, and skips the
+    // lineage checks a single source cannot fail.
+    if (sources.length !== 1) {
+        const refusal = (0, chain_js_1.refuseChain)(sources.map((source) => (0, stateAt_js_1.readSource)(source)));
+        if (refusal)
+            throw new Error(refusal);
+    }
+    return new Cursor(sources, options);
+}
+exports.timeTravel = timeTravel;

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

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * time-travel/types.ts — the shapes of the reader's cursor.
+ *
+ * WHY THIS MODULE EXISTS (context for future readers, human or LLM):
+ * Time travel in foottrace is a READER'S cursor over a FINISHED trace, with
+ * a fold at each stop. It is not the Walker — the engine's traversal — and it
+ * must never become a second live cursor: nothing here can move, re-run or
+ * mutate an execution. Every consumer (a why-panel, a flow view, a chart
+ * dashboard) was writing the same commit-index arithmetic by hand, from the
+ * same commit log, and disagreeing about the answers. This is that arithmetic,
+ * once, in the library that owns the substrate.
+ *
+ * DAG position: memory ← time-travel. Every file here is a record file
+ * (ranked in scripts/layers.json): it may import only record
+ * files — memory/, the id grammar (`ids/runtimeStageId`), and the record's two
+ * capture/ leaves (`freeze`, `valueKinds`). Recorders, traversal and runner
+ * must never be imported here; the snapshot arrives as a plain structural
+ * shape ({@link FoldSource}, {@link TimeTravelSource}, the record's own
+ * `ExecutionTree` for the tree) so a stored JSON trace works exactly like a
+ * live `getSnapshot()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/paths.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateNestedValue = exports.setNestedValue = exports.nativeHas = exports.nativeGet = exports.isDeniedSegment = exports.pathSegments = exports.normaliseStateKey = void 0;
+/** Record-path decoding and safe nested writes. Values keep their existing merge law. */
+var paths_js_1 = require("./lib/memory/paths.js");
+Object.defineProperty(exports, "normaliseStateKey", { enumerable: true, get: function () { return paths_js_1.normaliseStateKey; } });
+Object.defineProperty(exports, "pathSegments", { enumerable: true, get: function () { return paths_js_1.pathSegments; } });
+var pathOps_js_1 = require("./lib/memory/pathOps.js");
+Object.defineProperty(exports, "isDeniedSegment", { enumerable: true, get: function () { return pathOps_js_1.isDeniedSegment; } });
+Object.defineProperty(exports, "nativeGet", { enumerable: true, get: function () { return pathOps_js_1.nativeGet; } });
+Object.defineProperty(exports, "nativeHas", { enumerable: true, get: function () { return pathOps_js_1.nativeHas; } });
+var utils_js_1 = require("./lib/memory/utils.js");
+Object.defineProperty(exports, "setNestedValue", { enumerable: true, get: function () { return utils_js_1.setNestedValue; } });
+Object.defineProperty(exports, "updateNestedValue", { enumerable: true, get: function () { return utils_js_1.updateNestedValue; } });