footprintjs 9.48.2 → 10.0.0

package/dist/types/lib/time-travel/axis.d.ts

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

package/dist/types/lib/time-travel/bundles.d.ts

@@ -1,77 +0,0 @@
-/**
- * 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.
- */
-import type { CommitBundle, ExecutionTree } from '../memory/types.js';
-import type { LogGap } from './types.js';
-/** A plain object — not null, not an array, not a primitive. */
-export declare function isPlainish(value: unknown): value is Record<string, unknown>;
-/**
- * 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.
- */
-export declare function readTree(value: unknown): ExecutionTree | undefined;
-/**
- * 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.
- */
-export declare function bundleRefusal(row: unknown): string | undefined;
-/** `true` when `row` can be read as a {@link CommitBundle}. */
-export declare function isCommitBundle(row: unknown): row is CommitBundle;
-/** A log read row by row: the bundles, index-aligned, plus what was refused. */
-export interface ReadLog {
-    /** Same length and order as the input; a refused row holds a GAP stand-in. */
-    readonly log: readonly CommitBundle[];
-    /** The refused rows, in index order. Empty when the log was clean. */
-    readonly gaps: readonly LogGap[];
-}
-/**
- * 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)' }]
- * ```
- */
-export declare function readLog(raw: readonly unknown[] | undefined): ReadLog;

package/dist/types/lib/time-travel/chain.d.ts

@@ -1,93 +0,0 @@
-/**
- * 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 type { CommitBundle } from '../memory/types.js';
-import { type ReadSource } from './stateAt.js';
-import type { TimeTravelSource } from './types.js';
-/** One leg of a chain: a source, its read log, and where it sits in the run. */
-export interface ChainLeg {
-    readonly source: TimeTravelSource;
-    readonly log: readonly CommitBundle[];
-    /** Lowest execution index stamped in this leg; `undefined` for an id-less log. */
-    readonly firstExecutionIndex: number | undefined;
-    /** Highest execution index stamped in this leg. */
-    readonly lastExecutionIndex: number | undefined;
-}
-/** The execution-index span of one leg, read off its `runtimeStageId`s. */
-export declare function spanOf(log: readonly CommitBundle[]): {
-    first: number | undefined;
-    last: number | undefined;
-    ids: Set<string>;
-};
-/**
- * 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 declare function refuseChain(legs: readonly ReadSource[]): string | undefined;

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

@@ -1,55 +0,0 @@
-/**
- * commitStops — the one strategy footprintjs 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/types/lib/time-travel/index.d.ts

@@ -1,22 +0,0 @@
-/**
- * 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/types/lib/time-travel/stateAt.d.ts

@@ -1,102 +0,0 @@
-/**
- * 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;

package/dist/types/lib/time-travel/tagStops.d.ts

@@ -1,72 +0,0 @@
-/**
- * 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.
- */
-import type { TimeTravelStrategy } from './types.js';
-/**
- * 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 'footprintjs/trace';
- *
- * 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
- * ```
- */
-export declare function tagStops(tags?: readonly string[]): TimeTravelStrategy<readonly string[]>;

package/dist/types/lib/time-travel/timeTravel.d.ts

@@ -1,70 +0,0 @@
-/**
- * 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.
- */
-import type { TimeTravel, TimeTravelOptions, TimeTravelSource } from './types.js';
-/**
- * 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
- * ```
- */
-export declare function timeTravel<TMeta = unknown>(snapshot: TimeTravelSource | readonly TimeTravelSource[], options?: TimeTravelOptions<TMeta>): TimeTravel<TMeta>;