foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * bundles.ts — reading a log whose rows are not typed yet.
+ *
+ * WHY THIS FILE EXISTS. A LIVE snapshot hands time travel real
+ * {@link CommitBundle}s. A STORED recording hands it parsed JSON, and a
+ * careful consumer will not claim that what came back off disk is a
+ * `CommitBundle` — so it either casts (a lie with a comment on it) or cannot
+ * call the library at all. Since 9.18.0 the source takes `readonly unknown[]`
+ * and the narrowing happens here, per row, at the one place that actually
+ * reads one.
+ *
+ * A row that is not a bundle becomes a GAP rather than an exception: it KEEPS
+ * ITS INDEX — so every `commitIdx` in the axis still addresses the same
+ * position — contributes no state, gets no stop, and is reported with its
+ * index and a reason. One corrupt row in a stored recording loses that row,
+ * not the recording.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLog = exports.isCommitBundle = exports.bundleRefusal = exports.readTree = exports.isPlainish = void 0;
+const verbs_js_1 = require("../memory/verbs.js");
+/**
+ * The stand-in a gap leaves at its index: a commit that belongs to no stage
+ * and carries nothing.
+ *
+ * It is NOT invented evidence — every field is the empty value, and an id-less
+ * bundle is a shape the log already has (a root-context commit made before any
+ * stage ran). `commitStops` gives it no stop for exactly that reason, the fold
+ * folds nothing from it, and `changedSince` reads no keys off it. What it does
+ * is hold the index, so the arithmetic downstream never has to know.
+ */
+const GAP_BUNDLE = Object.freeze({
+    stage: '',
+    stageId: '',
+    runtimeStageId: '',
+    trace: Object.freeze([]),
+    redactedPaths: Object.freeze([]),
+    overwrite: Object.freeze({}),
+    updates: Object.freeze({}),
+});
+/** A plain object — not null, not an array, not a primitive. */
+function isPlainish(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+exports.isPlainish = isPlainish;
+/**
+ * Read a source's `executionTree` as an {@link ExecutionTree}, or as absent.
+ *
+ * The tree is only ever WALKED for mount ids (`subflowId` + `runtimeStageId`
+ * on each node), so the honest narrowing a reader can do is "a plain object";
+ * anything else — a stored field that came back as a string, a number, an
+ * array — is read as no tree at all, which sends `commitStops` down the same
+ * shape-heuristic path a log handed over without its tree already takes.
+ */
+function readTree(value) {
+    return isPlainish(value) ? value : undefined;
+}
+exports.readTree = readTree;
+/**
+ * Why `row` cannot be read as a commit bundle, or `undefined` when it can.
+ *
+ * DELIBERATELY LENIENT — but exactly as lenient as the readers are. It checks
+ * what the fold, the axis and `changedSince` actually touch:
+ *
+ * - `runtimeStageId` must be a string — the axis keys on it.
+ * - `trace` must be an ARRAY, and it must be PRESENT. It is the one field
+ *   every reader WALKS (`applySmartMerge` iterates it verb by verb;
+ *   `changedSince` reads its paths), so a row without one is not a bundle the
+ *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
+ *   declares it required, so no live log is affected.
+ * - `updates` / `overwrite`, when present, must be plain objects. They are
+ *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
+ *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.
+ *
+ * Being stricter than that — demanding `stage`, `stageId`, `idx` — would
+ * reject hand-built logs that have folded correctly since 9.17.0, which is a
+ * compatibility break dressed up as validation.
+ */
+function bundleRefusal(row) {
+    if (!isPlainish(row)) {
+        return `not an object (${row === null ? 'null' : Array.isArray(row) ? 'array' : typeof row})`;
+    }
+    if (typeof row.runtimeStageId !== 'string') {
+        return `runtimeStageId is ${row.runtimeStageId === undefined ? 'missing' : `a ${typeof row.runtimeStageId}`}, not a string`;
+    }
+    if (!Array.isArray(row.trace)) {
+        return `trace is ${row.trace === undefined ? 'missing' : `a ${typeof row.trace}`}, not an array`;
+    }
+    if (row.updates !== undefined && !isPlainish(row.updates))
+        return 'updates is not a plain object';
+    if (row.overwrite !== undefined && !isPlainish(row.overwrite))
+        return 'overwrite is not a plain object';
+    // The four verbs are the contract (9.27.0). The replay's switch used to
+    // treat anything else as `merge` — a silent coercion of a row a foreign
+    // producer got wrong; the readers now refuse it (`UnknownVerbError`), and
+    // this reader turns the same refusal into a gap that says which row.
+    for (let i = 0; i < row.trace.length; i++) {
+        const entry = row.trace[i];
+        const verb = isPlainish(entry) ? entry.verb : undefined;
+        if (!(0, verbs_js_1.isVerb)(verb)) {
+            return `trace[${i}].verb is ${verb === undefined ? 'missing' : JSON.stringify(verb)}, not ${verbs_js_1.VERBS.join(' | ')}`;
+        }
+    }
+    return undefined;
+}
+exports.bundleRefusal = bundleRefusal;
+/** `true` when `row` can be read as a {@link CommitBundle}. */
+function isCommitBundle(row) {
+    return bundleRefusal(row) === undefined;
+}
+exports.isCommitBundle = isCommitBundle;
+/** Nothing to read — shared, so the clean path allocates nothing extra. */
+const NO_GAPS = Object.freeze([]);
+/**
+ * Read an unvalidated array as a commit log.
+ *
+ * The clean case (a live snapshot, or a stored recording that round-tripped
+ * intact) returns the SAME array reference and no gaps: nothing is copied,
+ * nothing is allocated, and the fold behaves byte for byte as it did in
+ * 9.17.0. Only a log with a refused row is rebuilt, and only to keep the
+ * indices aligned.
+ *
+ * @example
+ * ```typescript
+ * const { log, gaps } = readLog(JSON.parse(stored).commitLog);
+ * gaps; // [{ index: 3, reason: 'not an object (null)' }]
+ * ```
+ */
+function readLog(raw) {
+    if (!raw || raw.length === 0)
+        return { log: [], gaps: NO_GAPS };
+    let gaps;
+    for (let i = 0; i < raw.length; i++) {
+        const reason = bundleRefusal(raw[i]);
+        if (reason !== undefined)
+            (gaps ??= []).push({ index: i, reason });
+    }
+    if (!gaps)
+        return { log: raw, gaps: NO_GAPS };
+    const log = raw.map((row) => (isCommitBundle(row) ? row : GAP_BUNDLE));
+    return { log, gaps: Object.freeze(gaps) };
+}
+exports.readLog = readLog;

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

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * chain.ts — reading a pause/resume as ONE axis.
+ *
+ * WHY THIS FILE EXISTS. A pause and its resume produce TWO snapshots. On a
+ * cross-executor resume (the checkpoint was persisted and a fresh executor
+ * picked it up) the second run gets a fresh runtime: its `commitLog` starts at
+ * index 0 and holds only the post-resume commits, and its `initialState` is
+ * the state at the pause. Two logs, two disjoint axes — so a reader scrubbing
+ * a resumed run saw only the second half unless the application had kept the
+ * paused snapshot and stitched the halves itself. Every application that
+ * pauses would write that stitching, and none of them own the arithmetic.
+ *
+ * THE HONEST BIT, up front: COMMIT INDICES ARE RUN-LOCAL. There is no global
+ * index across a chain and this file does not invent one — `commitIdx` and
+ * `lastCommitIdx` keep indexing their own source, and every stop carries the
+ * {@link Stop.sourceIdx} they belong to. The cursor's STEPS are what run
+ * across the whole chain.
+ *
+ * AND THE REFUSAL: a chain that is not ordered, or whose legs are not from one
+ * lineage, is REFUSED rather than guessed at. The record carries TWO signals
+ * and this file reads both:
+ *
+ * - The execution index the engine stamps into every `runtimeStageId` —
+ *   globally monotonic per run and, deliberately, NOT reset on resume. So a
+ *   later leg's first execution index must be past the earlier leg's last, and
+ *   no stage may appear in two legs. This catches a backwards chain, a fresh
+ *   run (which restarts at 0) and a same-executor resume (whose one snapshot
+ *   already holds both halves).
+ * - The later leg's `initialState`. On a resume the fresh runtime is seeded
+ *   from the checkpoint, so that base IS the state at the pause — and the
+ *   state the earlier legs FOLD TO must deep-equal it. This is what catches a
+ *   leg from some OTHER lineage whose indices merely happen to be higher: the
+ *   counters line up by accident, the state never does.
+ *
+ * A chart identity or a lineage id is NOT on the record, so nothing here
+ * pretends to check one. And where the state signal is not on the record
+ * either — a leg recorded before 9.17 carries no `initialState`; an earlier
+ * leg with no base folds `'log-only'`; a leg with unreadable rows folds an
+ * incomplete state — that check is SKIPPED, not faked: the chain then rests on
+ * the index checks alone, and every fold's `basis` still says what it stood
+ * on. That degradation is documented on `refuseChain`, on `timeTravel`'s
+ * `@throws`, and in the README.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refuseChain = exports.spanOf = void 0;
+const valueKinds_js_1 = require("../capture/valueKinds.js");
+const runtimeStageId_js_1 = require("../ids/runtimeStageId.js");
+const utils_js_1 = require("../memory/utils.js");
+const stateAt_js_1 = require("./stateAt.js");
+/** The execution-index span of one leg, read off its `runtimeStageId`s. */
+function spanOf(log) {
+    let first;
+    let last;
+    const ids = new Set();
+    for (const bundle of log) {
+        const id = bundle.runtimeStageId;
+        if (!id)
+            continue;
+        ids.add(id);
+        const { executionIndex } = (0, runtimeStageId_js_1.parseRuntimeStageId)(id);
+        if (Number.isNaN(executionIndex))
+            continue;
+        if (first === undefined || executionIndex < first)
+            first = executionIndex;
+        if (last === undefined || executionIndex > last)
+            last = executionIndex;
+    }
+    return { first, last, ids };
+}
+exports.spanOf = spanOf;
+/**
+ * Structural equality of two folded states, ignoring the paths the log was
+ * redacted at.
+ *
+ * The fold reproduces `'REDACTED'` wherever the engine scrubbed a write, while
+ * the checkpoint that seeded the resumed leg holds the real value — so those
+ * paths CANNOT agree, and are not asked to. Everything else is decided by the
+ * ONE equality law (`memory/equality.ts · deepEqual`, every value kind compared
+ * as the record holds it; 9.44.2 — this walk had a law of its own, which held
+ * any two RegExps, Errors or buffers equal). Both sides are copies of one
+ * record, so an opaque value compares as `'copies'`. Only the containers above
+ * a redacted path are walked here.
+ */
+function sameState(a, b, redacted, path) {
+    if (!redactedBelow(path, redacted))
+        return (0, utils_js_1.deepEqual)(a, b, 'copies');
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, i) => sameState(item, b[i], redacted, path === '' ? String(i) : `${path}${utils_js_1.DELIM}${i}`));
+    }
+    const plain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && (0, valueKinds_js_1.kindOf)(v) === 'plain';
+    if (!plain(a) || !plain(b))
+        return (0, utils_js_1.deepEqual)(a, b, 'copies');
+    const present = (o) => Object.keys(o).filter((k) => o[k] !== undefined);
+    const leftKeys = present(a);
+    const rightKeys = new Set(present(b));
+    if (leftKeys.length !== rightKeys.size || !leftKeys.every((k) => rightKeys.has(k)))
+        return false;
+    return leftKeys.every((k) => {
+        const childPath = path === '' ? k : `${path}${utils_js_1.DELIM}${k}`;
+        return redacted.has(childPath) || sameState(a[k], b[k], redacted, childPath);
+    });
+}
+/** Is `path`, or a path below it, one the log was redacted at? */
+function redactedBelow(path, redacted) {
+    if (redacted.size === 0)
+        return false;
+    if (path === '')
+        return true;
+    for (const r of redacted)
+        if (r === path || r.startsWith(`${path}${utils_js_1.DELIM}`))
+            return true;
+    return false;
+}
+/**
+ * Check that `legs` really are one run read in order, and say why not.
+ *
+ * Returns the refusal message, or `undefined` when the chain is sound. Three
+ * distinct failures, because they are three different mistakes, checked in
+ * this order:
+ *
+ * - REPEATED STAGE — one `runtimeStageId` appears in two legs. Ids are unique
+ *   within a run, so a repeat means the same execution was recorded twice: a
+ *   same-executor resume, whose snapshot ALREADY holds the whole log and needs
+ *   no chaining, is the usual cause.
+ * - OUT OF ORDER — a later leg's first execution index is not past the earlier
+ *   leg's last. Either the sources were handed over backwards, or the second
+ *   is not a continuation at all (a fresh run restarts the counter at 0, so an
+ *   unrelated snapshot fails here rather than silently interleaving).
+ * - WRONG LINEAGE — leg k's `initialState` is not the state legs 0..k-1 fold
+ *   to. On a resume the later leg is seeded from the checkpoint, so its base
+ *   IS the state at the pause; a leg that begins anywhere else is from some
+ *   other run, however its indices happen to line up.
+ *
+ * THE LINEAGE CHECK RUNS ONLY WHERE THE RECORD ALLOWS IT, and is skipped —
+ * never faked — otherwise: leg k must carry an `initialState` (a recording
+ * made before 9.17 has none), and the fold of the legs before it must stand on
+ * a real base (`basis: 'initial+log'`) with no unreadable rows (`skipped`
+ * absent) — a log-only or gapped fold is not a state a real base may be held
+ * against. On such a chain the two index checks are the whole defence, and
+ * `foldLegs`' leg rule then CONTINUES the fold across the seam, which is the
+ * right state for a real resume and is what `basis` reports. Paths the log
+ * was redacted at are excluded from the comparison: the fold holds
+ * `'REDACTED'` there and the checkpoint holds the value.
+ */
+function refuseChain(legs) {
+    if (legs.length === 0)
+        return 'timeTravel: a chain needs at least one source, got an empty array.';
+    const spans = legs.map((leg) => spanOf(leg.log));
+    const seen = new Map();
+    for (const [i, span] of spans.entries()) {
+        for (const id of span.ids) {
+            const earlier = seen.get(id);
+            if (earlier !== undefined) {
+                return (`timeTravel: sources ${earlier} and ${i} both record '${id}'. A runtimeStageId is unique ` +
+                    'within a run, so these are not two legs of one run — a same-executor resume already ' +
+                    'carries the whole log in ONE snapshot and must not be chained with the paused one.');
+            }
+            seen.set(id, i);
+        }
+    }
+    let previous;
+    for (const [i, span] of spans.entries()) {
+        if (span.first === undefined || span.last === undefined)
+            continue;
+        if (previous && span.first <= previous.last) {
+            return (`timeTravel: source ${i} starts at execution index ${span.first}, which is not past ` +
+                `source ${previous.idx}'s last (${previous.last}). Chain the sources in run order, and ` +
+                'only sources from ONE lineage — the engine never resets the execution counter across a ' +
+                'resume, so a fresh run restarting at 0 is a different run, not a continuation.');
+        }
+        previous = { idx: i, last: span.last };
+    }
+    for (let k = 1; k < legs.length; k++) {
+        const base = legs[k].base;
+        if (!base || typeof base !== 'object')
+            continue; // no signal on the record — documented degradation
+        const before = (0, stateAt_js_1.foldLegs)(legs, k - 1, Number.POSITIVE_INFINITY);
+        if (before.basis !== 'initial+log' || before.skipped)
+            continue; // not a state a real base can be held to
+        if (!sameState(before.state, base, new Set(before.redactedPaths), '')) {
+            return (`timeTravel: source ${k}'s initialState is not the state source ${k - 1} folds to. On a resume ` +
+                "the later leg's initialState IS the state at the pause, so a leg that begins anywhere else is " +
+                'not from one lineage — a different chart, or another run of this one — even when its execution ' +
+                'indices happen to be higher.');
+        }
+    }
+    return undefined;
+}
+exports.refuseChain = refuseChain;

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

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * commitStops — the one strategy foottrace ships.
+ *
+ * One stop per executed stage, in execution order, plus `'start'` / `'end'`
+ * bookends. It is the only stop grammar the substrate itself knows: the engine
+ * stamps one `runtimeStageId` per executed stage, and an empty commit is a
+ * deliberate cursor stop, not noise. Richer vocabularies (milestones, turns,
+ * tool calls) belong to the consumer that owns them — they plug in through
+ * `TimeTravelStrategy`, they do not go here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitStopsStrategy = exports.commitStops = void 0;
+const runtimeStageId_js_1 = require("../ids/runtimeStageId.js");
+const commitLogUtils_js_1 = require("../memory/commitLogUtils.js");
+/**
+ * Every `runtimeStageId` in the execution tree that the engine marked as a
+ * subflow mount. Authoritative, as is a bundle's recorded `phase: 'exit'`
+ * (9.39.0) — a mount with a merge-back records its exit as a continuation. A
+ * mount without one has a single bundle, its own (no `phase`), so only the
+ * tree names it. Only a log written before 9.39.0 AND handed over without its
+ * tree falls back to the legacy inference (`inferLegacyPhases`).
+ */
+function mountIdsFrom(tree) {
+    const ids = new Set();
+    if (!tree)
+        return ids;
+    const work = [tree];
+    while (work.length > 0) {
+        const node = work.pop();
+        if (node.subflowId && node.runtimeStageId)
+            ids.add(node.runtimeStageId);
+        if (node.next)
+            work.push(node.next);
+        if (node.children)
+            work.push(...node.children);
+    }
+    return ids;
+}
+/**
+ * Derive one stop per executed stage from a recorded commit log.
+ *
+ * **One stop per `runtimeStageId`.** A stage can commit MORE than one bundle:
+ * a subflow mount commits its output-mapping bundle and then its EXIT; a
+ * parallel fork child is committed by the stage funnel and again by the
+ * fan-out (its REPEAT), and siblings interleave. The writer names each
+ * continuation on its bundle (`phase: 'exit' | 'repeat'`, 9.39.0), so the
+ * grouping is read, never inferred: the axis shows the stage ONCE, at its
+ * first commit ({@link buildCommitIndex}), which keeps `runtimeStageId → stop`
+ * one-to-one — the property `jumpTo` and marks depend on. The FIRST bundle per
+ * `runtimeStageId` is the stage's own and never carries a `phase`; a stage
+ * whose bundles include an `'exit'` is a `'mount'`. A continuation is normally empty
+ * (the first commit released the staging buffer); one that carries a write is
+ * folded where it sits in the log, which is when it happened.
+ *
+ * **Stops PARTITION the log.** A stop's range runs from its own first commit
+ * up to (and including) the last commit before the NEXT stop begins —
+ * `lastCommitIdx`. Every bundle therefore belongs to exactly one stop, nothing
+ * is orphaned, and `stateAt(stop)` is precisely the state that existed just
+ * before the next stop's stage started. Folding through `commitIdx` instead
+ * would silently drop a mount's output mapping.
+ *
+ * **Bookends.** `'start'` is the position before the first commit — the fold
+ * base, which no commit index can otherwise address. `'end'` is "the run is
+ * over"; it folds the whole log, the same as the last stage's stop, because
+ * "after the last stage" and "the run finished" are the same state asked as
+ * two different questions.
+ *
+ * An EMPTY log yields NO stops at all — not two bookends around nothing. A
+ * cursor with nowhere to stand says so (`Move.reason === 'empty'`).
+ *
+ * **THE SHAPE IS A CONTRACT (9.18.0).** For a non-empty log the result is
+ * `[start, …stages, end]` — `'start'` first, `'end'` last, one stop per
+ * executed stage between them, in execution order — and for an empty log it
+ * is `[]`. A strategy that COMPOSES this one (keep some stages, drop the rest)
+ * rests on that shape; it is pinned by `test/lib/time-travel/`, and
+ * {@link splitAxis} is the one guard that reads it — a composer calls that, or
+ * {@link filterStops} which calls it, instead of writing its own.
+ */
+function commitStops(commitLog, executionTree, subflowResults) {
+    if (commitLog.length === 0)
+        return [];
+    // No tree? The snapshot's `subflowResults` still keys every mount EXECUTION
+    // by its runtimeStageId (9.39.0) — the mapper-less mounts whose one bundle
+    // carries no `phase` (fork / selector children, lazy mounts, `parallelForEach`
+    // branches) included.
+    const mountIds = executionTree ? mountIdsFrom(executionTree) : mountKeysOf(subflowResults);
+    const phases = phasesOf(commitLog, executionTree !== undefined);
+    // First commit of each distinct runtimeStageId, in execution order — the
+    // one index every reader shares (`buildCommitIndex`).
+    // A subflow's `inputMapper` seed is not one of the subflow's stages: it is
+    // the MOUNT's commit, made before any of them ran. It gets no stop of its
+    // own; it belongs to the `'start'` bookend, which is where a reader looks
+    // for "the input this chart began with" anyway. See {@link seedCommits}.
+    const seeds = seedCommits(commitLog, executionTree);
+    const firsts = [];
+    for (const [id, i] of (0, commitLogUtils_js_1.buildCommitIndex)(commitLog))
+        if (id && i >= seeds)
+            firsts.push(i);
+    const exits = new Set();
+    for (let i = seeds; i < commitLog.length; i++)
+        if (phases[i] === 'exit')
+            exits.add(commitLog[i].runtimeStageId);
+    const stops = [
+        {
+            step: 0,
+            runtimeStageId: '',
+            commitIdx: -1,
+            // Covers the subflow input seed, when the log opens with one.
+            lastCommitIdx: (firsts.length > 0 ? firsts[0] : commitLog.length) - 1,
+            stageId: '',
+            label: 'Run start',
+            kind: 'start',
+        },
+    ];
+    for (let g = 0; g < firsts.length; g++) {
+        const first = firsts[g];
+        const bundle = commitLog[first];
+        // Partition boundary: everything up to the next stage's first commit.
+        const last = g + 1 < firsts.length ? firsts[g + 1] - 1 : commitLog.length - 1;
+        stops.push({
+            step: stops.length,
+            runtimeStageId: bundle.runtimeStageId,
+            commitIdx: first,
+            lastCommitIdx: last,
+            stageId: bundle.stageId,
+            subflowPath: (0, runtimeStageId_js_1.parseRuntimeStageId)(bundle.runtimeStageId).subflowPath,
+            label: bundle.stage || bundle.stageId || bundle.runtimeStageId,
+            kind: mountIds.has(bundle.runtimeStageId) || exits.has(bundle.runtimeStageId) ? 'mount' : 'commit',
+        });
+    }
+    stops.push({
+        step: stops.length,
+        runtimeStageId: '',
+        commitIdx: commitLog.length - 1,
+        lastCommitIdx: commitLog.length - 1,
+        stageId: '',
+        label: 'Run end',
+        kind: 'end',
+    });
+    return stops;
+}
+exports.commitStops = commitStops;
+/** The per-execution mount keys of a snapshot's `subflowResults` (`'#'` keys; path keys skipped). */
+function mountKeysOf(subflowResults) {
+    const ids = new Set();
+    if (subflowResults === null || typeof subflowResults !== 'object')
+        return ids;
+    for (const key of Object.keys(subflowResults))
+        if ((0, runtimeStageId_js_1.isExecutionKey)(key))
+            ids.add(key);
+    return ids;
+}
+/**
+ * The phase of every bundle: as RECORDED when the log records any (9.39.0+).
+ * A log that records none is either free of continuations (nothing to read)
+ * or older than the field: with its execution tree the tree names the mounts,
+ * so nothing is inferred; without it, the one legacy reader infers what
+ * 9.38.0 inferred (`inferLegacyPhases`) — a stored recording keeps its axis.
+ */
+function phasesOf(commitLog, haveTree) {
+    if ((0, commitLogUtils_js_1.recordsPhases)(commitLog))
+        return commitLog.map((bundle) => bundle.phase);
+    return haveTree ? [] : (0, commitLogUtils_js_1.inferLegacyPhases)(commitLog);
+}
+/** `commitStops` as a {@link TimeTravelStrategy} — the default for `timeTravel`. */
+exports.commitStopsStrategy = { stopsFor: commitStops };
+/**
+ * How many commits at the head of a log are a subflow's input seed — 0 on a
+ * run's own log. The seed is `history[0]` of the subflow's log, committed by
+ * the MOUNT before any of the subflow's stages ran:
+ *
+ * - since R13 it carries the mount's runtimeStageId — and a mount's stage
+ *   address (the id before `#`) IS the subflow path of every stage in the
+ *   log it opens (`sub#2` opens `sub/in#3`; `outer/sub#5` opens
+ *   `outer/sub/in#6`), which no stage of that log can be;
+ * - through 9.33.0 it carried `''`, which is still read the same way, so an
+ *   old recording keeps its axis.
+ *
+ * A log that holds ONLY the seed (the subflow committed no stage — it paused
+ * or failed first) has no stage to compare with; the execution tree's root
+ * stands in for it: a subflow's tree is rooted at one of its own stages,
+ * whose id carries the same subflow path. Without a tree such a log reads as
+ * one stop.
+ */
+function seedCommits(commitLog, executionTree) {
+    const head = commitLog[0]?.runtimeStageId;
+    if (head === undefined)
+        return 0;
+    if (head === '') {
+        let n = 0;
+        while (n < commitLog.length && commitLog[n].runtimeStageId === '')
+            n++;
+        return n;
+    }
+    let next = 1;
+    while (next < commitLog.length && commitLog[next].runtimeStageId === head)
+        next++;
+    const address = (0, runtimeStageId_js_1.stageIdOf)(head);
+    if (next >= commitLog.length) {
+        const rootId = executionTree?.id;
+        return typeof rootId === 'string' && (0, runtimeStageId_js_1.isWithinSubflow)(rootId, address) ? next : 0;
+    }
+    return (0, runtimeStageId_js_1.parseRuntimeStageId)(commitLog[next].runtimeStageId).subflowPath === address ? next : 0;
+}

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

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * time-travel/ — the reader's cursor over a finished trace.
+ *
+ * Time travel here is READ-TIME: a cursor over a Trace that has already
+ * happened, with a Fold at each stop. It is not the Walker and never becomes a
+ * second live cursor — nothing in this folder can move, re-run or mutate an
+ * execution.
+ *
+ * See README.md for the five laws, the strategy seam, and a worked example of
+ * every export.
+ *
+ * DAG position: memory ← time-travel (plus `ids/runtimeStageId`, the
+ * zero-dependency id grammar).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeTravel = exports.tagStops = exports.stateAt = exports.commitStopsStrategy = exports.commitStops = exports.isCommitBundle = exports.splitAxis = exports.filterStops = void 0;
+var axis_js_1 = require("./axis.js");
+Object.defineProperty(exports, "filterStops", { enumerable: true, get: function () { return axis_js_1.filterStops; } });
+Object.defineProperty(exports, "splitAxis", { enumerable: true, get: function () { return axis_js_1.splitAxis; } });
+var bundles_js_1 = require("./bundles.js");
+Object.defineProperty(exports, "isCommitBundle", { enumerable: true, get: function () { return bundles_js_1.isCommitBundle; } });
+var commitStops_js_1 = require("./commitStops.js");
+Object.defineProperty(exports, "commitStops", { enumerable: true, get: function () { return commitStops_js_1.commitStops; } });
+Object.defineProperty(exports, "commitStopsStrategy", { enumerable: true, get: function () { return commitStops_js_1.commitStopsStrategy; } });
+var stateAt_js_1 = require("./stateAt.js");
+Object.defineProperty(exports, "stateAt", { enumerable: true, get: function () { return stateAt_js_1.stateAt; } });
+var tagStops_js_1 = require("./tagStops.js");
+Object.defineProperty(exports, "tagStops", { enumerable: true, get: function () { return tagStops_js_1.tagStops; } });
+var timeTravel_js_1 = require("./timeTravel.js");
+Object.defineProperty(exports, "timeTravel", { enumerable: true, get: function () { return timeTravel_js_1.timeTravel; } });