foottrace 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,187 @@
+/**
+ * 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.
+ */
+import { kindOf } from '../capture/valueKinds.js';
+import { parseRuntimeStageId } from '../ids/runtimeStageId.js';
+import { deepEqual, DELIM } from '../memory/utils.js';
+import { foldLegs } from './stateAt.js';
+/** The execution-index span of one leg, read off its `runtimeStageId`s. */
+export 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 } = 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 };
+}
+/**
+ * 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 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}${DELIM}${i}`));
+    }
+    const plain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && kindOf(v) === 'plain';
+    if (!plain(a) || !plain(b))
+        return 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}${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}${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.
+ */
+export 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 = 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;
+}

package/dist/esm/lib/time-travel/commitStops.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+import type { CommitBundle, ExecutionTree } from '../memory/types.js';
+import type { Stop, TimeTravelStrategy } from './types.js';
+/**
+ * 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.
+ */
+export declare function commitStops(commitLog: readonly CommitBundle[], executionTree?: ExecutionTree, subflowResults?: unknown): Stop[];
+/** `commitStops` as a {@link TimeTravelStrategy} — the default for `timeTravel`. */
+export declare const commitStopsStrategy: TimeTravelStrategy;

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

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ */
+import { isExecutionKey, isWithinSubflow, parseRuntimeStageId, stageIdOf } from '../ids/runtimeStageId.js';
+import { buildCommitIndex, inferLegacyPhases, recordsPhases } from '../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.
+ */
+export 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 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: 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;
+}
+/** 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 (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 (recordsPhases(commitLog))
+        return commitLog.map((bundle) => bundle.phase);
+    return haveTree ? [] : inferLegacyPhases(commitLog);
+}
+/** `commitStops` as a {@link TimeTravelStrategy} — the default for `timeTravel`. */
+export const 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 = stageIdOf(head);
+    if (next >= commitLog.length) {
+        const rootId = executionTree?.id;
+        return typeof rootId === 'string' && isWithinSubflow(rootId, address) ? next : 0;
+    }
+    return parseRuntimeStageId(commitLog[next].runtimeStageId).subflowPath === address ? next : 0;
+}

package/dist/esm/lib/time-travel/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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).
+ */
+export type { StopFilter } from './axis.js';
+export { filterStops, splitAxis } from './axis.js';
+export { isCommitBundle } from './bundles.js';
+export { commitStops, commitStopsStrategy } from './commitStops.js';
+export { stateAt } from './stateAt.js';
+export { tagStops } from './tagStops.js';
+export { timeTravel } from './timeTravel.js';
+export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopKind, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './types.js';

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

@@ -0,0 +1,20 @@
+/**
+ * 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).
+ */
+export { filterStops, splitAxis } from './axis.js';
+export { isCommitBundle } from './bundles.js';
+export { commitStops, commitStopsStrategy } from './commitStops.js';
+export { stateAt } from './stateAt.js';
+export { tagStops } from './tagStops.js';
+export { timeTravel } from './timeTravel.js';

package/dist/esm/lib/time-travel/stateAt.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+import type { CommitBundle } from '../memory/types.js';
+import type { FoldedState, FoldSource, LogGap } from './types.js';
+/** One source, read: its log (gaps held in place) and its fold base. */
+export interface ReadSource {
+    readonly log: readonly CommitBundle[];
+    readonly gaps: readonly LogGap[];
+    readonly base: Record<string, unknown> | undefined;
+}
+/**
+ * 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).
+ */
+export declare function readSource(source: FoldSource | undefined): 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.
+ */
+export declare function foldLegs(legs: readonly ReadSource[], legIdx: number, through: number): FoldedState;
+/**
+ * What a fold leaves behind for the NEXT one (9.25.0): the private working
+ * copy and the facts accumulated so far. A cursor stepping forward on the
+ * same leg hands it back and only the bundles after `through` are applied —
+ * one bundle per step instead of a replay from the base. Any other ask (an
+ * earlier stop, another leg) folds from scratch; the memo is never a claim.
+ */
+export interface FoldMemo {
+    readonly legIdx: number;
+    readonly through: number;
+    readonly out: Record<string, unknown>;
+    readonly based: boolean;
+    readonly redactedPaths: ReadonlySet<string>;
+    readonly skipped: readonly LogGap[] | undefined;
+}
+/**
+ * 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.
+ */
+export declare function foldLegsFrom(legs: readonly ReadSource[], legIdx: number, through: number, memo?: FoldMemo): {
+    readonly folded: FoldedState;
+    readonly memo: FoldMemo;
+};
+/**
+ * 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
+ * ```
+ */
+export declare function stateAt(source: FoldSource | undefined, commitIdx: number): FoldedState;