agentfootprint 9.87.1 → 9.89.0

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

@@ -0,0 +1,113 @@
+/**
+ * keyedFold — the value of ONE state key at one commit, folded from the run's
+ * own fold base.
+ *
+ * Role:  Fold. It reads a finished run's commit log plus the base that log
+ *        was recorded against, and answers "what was `key` at commit `idx`?"
+ *        It executes nothing, records nothing and stores nothing beside the
+ *        log. Its answers are DETACHED — deep-frozen before they are cached,
+ *        because a memo that hands out live references is a fold that lets a
+ *        reader rewrite the run (`keyedFold.ts` · `freezeDeep`).
+ * Reads: a `FoldSource` — a snapshot (`commitLog` + `initialState`) or a
+ *        subflow subtree (`history` + `initialState`), through footprintjs's
+ *        own `stateAt` (for the base) and `applySmartMerge` (for the replay).
+ * Emits: N/A.
+ *
+ * ── WHY THIS FILE EXISTS ───────────────────────────────────────────────────
+ * A commit log stores DIFFS. `commitValueAt` folds them for one key and says
+ * so in its own docstring: a value that came from the run's INITIAL state and
+ * was never `set` again folds to ABSENT, because the log alone cannot see the
+ * pre-run base.
+ *
+ * That is not an edge case here. A RESUMED agent run is a fresh executor
+ * seeded from `checkpoint.sharedState`, so the entire pre-pause world —
+ * `systemPromptInjections`, `history`, `dynamicToolSchemas`, every build-time
+ * constant `seed` wrote before the pause — is base, not log. Folding the
+ * resumed run with `commitValueAt` returns an empty system prompt and a
+ * truncated conversation and declares no gap: a confident falsehood about the
+ * one question this family exists to answer. footprintjs 9.17 shipped
+ * `RuntimeSnapshot.initialState` and `stateAt` for exactly this, and every
+ * read in `epochs.ts` goes through here so it lands on that base.
+ *
+ * ── WHY NOT JUST CALL `stateAt` PER READ ───────────────────────────────────
+ * `stateAt` folds the WHOLE state, and it clones that state once per bundle
+ * (`applySmartMerge` opens with a `structuredClone` of its base). One fold is
+ * therefore O(commits × state size) — measured on a real 100-turn agent
+ * (1,719 commits, 101 epochs): 323 ms for a single fold, and 11.7 s to fold
+ * once per epoch, against 78 ms for the whole per-epoch scrub before this
+ * release. A per-epoch reader cannot pay that.
+ *
+ * So `stateAt` is used for the ONE thing only it can give — the fold base and
+ * the honest `basis` verdict, at `commitIdx: -1`, where it folds nothing and
+ * clones the base once — and the forward replay is done per key, through
+ * footprintjs's own `applySmartMerge`. There is deliberately no second
+ * implementation of the trace verbs here: every `set` / `append` / `merge` /
+ * `delete` is applied by the same function the live commit uses.
+ * `keyed-fold-equivalence.test.ts` pins the result against `stateAt` itself on
+ * real runs, including a resumed one and a merge with no `set` anchor — the
+ * one shape that cannot be folded at all without the base.
+ */
+import type { CommitBundle } from 'footprintjs/advanced';
+/**
+ * How a fold was derived — footprintjs's own two answers, restated here so a
+ * caller of this module does not have to import the engine's trace barrel to
+ * name them.
+ *
+ * - `'initial+log'` — the recording carried its fold base, so a value seeded
+ *   before the run (or before a resume) folds correctly.
+ * - `'log-only'` — it did not. Anything the log never `set` reads as absent,
+ *   and a reader must say so rather than present the hole as a proof.
+ */
+export type FoldBasis = 'initial+log' | 'log-only';
+/**
+ * Anything that carries a commit log and, ideally, the base it was recorded
+ * against — the two field spellings footprintjs already has: `commitLog` on a
+ * run snapshot, `history` on a subflow subtree.
+ */
+export interface FoldSourceLike {
+    readonly commitLog?: readonly CommitBundle[];
+    readonly history?: readonly unknown[];
+    readonly initialState?: Record<string, unknown>;
+}
+/**
+ * One key's value at one commit — the question, and the answers already
+ * computed for it.
+ */
+export interface KeyedFold {
+    /** How this fold was derived — see {@link FoldBasis}. */
+    readonly basis: FoldBasis;
+    /** How many bundles the log holds. */
+    readonly length: number;
+    /**
+     * The value of `key` folded through commit ARRAY INDEX `idx`, inclusive.
+     * `-1` (or lower) folds nothing and returns the base's value — the state
+     * before the log's first commit.
+     *
+     * DEEP-FROZEN, and the same object on every call for the same question. It
+     * is detached from the engine's own bundles AND unmutable, so a caller
+     * cannot rewrite what a later index folds to — `keyedFold.ts` · `freezeDeep`
+     * says why that is a law here rather than a courtesy. Copy it
+     * (`structuredClone`, a spread) if you need something to edit.
+     */
+    valueAt(key: string, idx: number): unknown;
+}
+/**
+ * The keyed fold for one source, memoized on the source object.
+ *
+ * Memoized because a per-epoch reader asks the same source for the same keys
+ * at many different commits, and the index is the expensive half: building it
+ * is one pass over the log, and answering a read afterwards is a binary search
+ * plus a replay from the nearest full-value write (normally exactly one).
+ *
+ * @example
+ * ```ts
+ * import { keyedFold } from 'agentfootprint';
+ *
+ * const fold = keyedFold(agent.getSnapshot());
+ * fold.basis;                      // 'initial+log' — the base travelled
+ * fold.valueAt('history', 12);     // the conversation after the 13th commit
+ * fold.valueAt('history', -1);     // …and what the run STARTED from
+ * ```
+ */
+export declare function keyedFold(source: FoldSourceLike | undefined): KeyedFold;
+//# sourceMappingURL=keyedFold.d.ts.map

package/dist/types/lib/time-travel/keyedFold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedFold.d.ts","sourceRoot":"","sources":["../../../../src/lib/time-travel/keyedFold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAmCD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAqGD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,CAmGvE"}

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

@@ -8,16 +8,26 @@
  *        it), and `conventions.ts` · `milestoneFor` for the domain vocabulary.
  * Emits: N/A.
  *
- * WHY THIS FILE EXISTS. footprintjs 9.17 ships the reader's cursor
- * (`timeTravel`) and one stop grammar — `commitStops`, one stop per executed
- * stage — because that is the only grammar the substrate itself knows. It does
- * NOT know what an LLM turn is. agentfootprint does: `milestoneFor` has
- * classified a local stage id into an iteration / slot / llm-turn / tool-call /
- * decision since 9.x, and until now every consumer that wanted a milestone
- * slider mapped that classifier onto commits by hand. The Why Lens did it one
- * way; anyone else with a recording had to write it again. This is that
- * mapping, once, on the strategy seam the port opened — so the agent SUPPLIES
- * the stops for its own runs and every reader gets the same axis.
+ * WHY THIS FILE EXISTS. footprintjs ships the reader's cursor (`timeTravel`)
+ * and one stop grammar — `commitStops`, one stop per executed stage — because
+ * that is the only grammar the substrate itself knows. It does NOT know what an
+ * LLM turn is. agentfootprint does: `milestoneFor` has classified a local stage
+ * id into an iteration / slot / llm-turn / tool-call / decision since 9.x, and
+ * until 9.87 every consumer that wanted a milestone slider mapped that
+ * classifier onto commits by hand. This is that mapping, once, on the strategy
+ * seam the port opened — so the agent SUPPLIES the stops for its own runs and
+ * every reader gets the same axis.
+ *
+ * WHAT IT IS (9.89.0). A FILTER over the port's own axis. footprintjs 9.18
+ * shipped `filterStops(stops, keep)` — the bookend guard, the re-partition and
+ * a `meta` slot on the stop — because two consumers had each re-derived all
+ * three by hand against 9.17, this file among them. The hand-rolled copies are
+ * gone: the one owner of the `[start, …stages, end]` contract is the library
+ * that returns it, and this strategy is one expression over it. The axis is
+ * byte-for-byte the 9.88.0 axis (`test/lib/time-travel/milestone-stops-equivalence.test.ts` pins
+ * that against a verbatim copy of the 9.88.0 implementation); what is new is that the milestone now RIDES on the
+ * stop as `meta`, and that a start which absorbed pre-milestone stages says so
+ * with `prologue: true`.
  *
  * WHAT IT IS NOT. Not a second cursor. A strategy only says where the one
  * cursor may rest; `timeTravel` still owns the position, the folds and the
@@ -32,15 +42,14 @@ import { type Milestone } from '../../conventions.js';
  * The milestone a stop stands for, or `null` when it stands for none (the
  * `'start'` / `'end'` bookends).
  *
- * WHY A FUNCTION AND NOT A FIELD. footprintjs's `Stop` is a closed shape —
- * `step`, `runtimeStageId`, `commitIdx`, `lastCommitIdx`, `stageId`,
- * `subflowPath`, `label`, `kind` — with no extension slot a strategy may write
- * its own vocabulary into, and `kind` is the port's own `StopKind`
- * (`'commit' | 'mount' | 'start' | 'end'`), not ours to overload. So the
- * milestone kind travels the only way it honestly can: re-derived from the
- * stop's `runtimeStageId`, by the same classifier that put the stop on the
- * axis. Same input, same function, same answer — there is no second source of
- * truth here, only a second reading of the one there is.
+ * A stop that {@link milestoneStops} made carries its milestone as
+ * `stop.meta`, and that is what is read — the classification the strategy
+ * made when it put the stop on the axis, not a second run of the classifier.
+ * A stop from ANOTHER strategy — the port's own `commitStops`, or a consumer's
+ * filter that kept the stop without a milestone meta — has none, so the answer
+ * falls back to where it always came from: `milestoneFor` over the stop's
+ * `runtimeStageId`. Same classifier, same answer; a `meta` of some other
+ * vocabulary is not mistaken for ours.
  *
  * @example
  * ```ts
@@ -48,7 +57,7 @@ import { type Milestone } from '../../conventions.js';
  * milestoneOf(stop)?.kind;   // 'llm-turn'
  * ```
  */
-export declare function milestoneOf(stop: Stop): Milestone | null;
+export declare function milestoneOf(stop: Stop<unknown>): Milestone | null;
 /**
  * Derive one stop per committed MILESTONE from a recorded commit log.
  *
@@ -61,9 +70,11 @@ export declare function milestoneOf(stop: Stop): Milestone | null;
  * parallel fork child commits twice and siblings interleave — every repeat is
  * an empty bundle), the authoritative mount set read off the execution tree,
  * the `'start'` / `'end'` bookends, and the id-less leading commit that carries
- * a subflow's `inputMapper` seed. This function calls `commitStops` and filters
- * its result. A second implementation of that collapsing would be a second
- * chance to disagree with the library about what a stage is.
+ * a subflow's `inputMapper` seed. And since 9.89.0 the COMPOSITION itself is
+ * the port's too: `filterStops` checks the `[start, …stages, end]` shape,
+ * keeps what `keep` keeps, and re-partitions the log. A second implementation
+ * of any of that would be a second chance to disagree with the library about
+ * what a stage is.
  *
  * **The survivors re-partition the log.** A stage that classifies `null` is not
  * a stop, but its commits still happened, so they are folded into the stop that
@@ -74,14 +85,21 @@ export declare function milestoneOf(stop: Stop): Milestone | null;
  * so on a drilled cursor `'start'` reads as "what this subflow began with,
  * after its plumbing ran".
  *
- * **What that costs `'start'`.** On footprintjs's own axis `'start'` is the fold
- * base: the state before ANY stage ran. Here it absorbs every stage that ran
- * before the first milestone, so `stateAt(start)` is the state the first
- * milestone READ, not the run's raw base — a real agent seeds a couple of dozen
- * keys in `seed` before anything a reader would scrub to. That is the right
- * answer for this axis (the stops must still partition the log) and the wrong
- * one to assume from `kind: 'start'` alone, so it is said out loud here, in the
- * folder README, on the docs page and in a test.
+ * **What that costs `'start'`, and the flag that says so.** On footprintjs's
+ * own axis `'start'` is the fold base: the state before ANY stage ran. Here it
+ * absorbs every stage that ran before the first milestone, so `stateAt(start)`
+ * is the state the first milestone READ, not the run's raw base — a real agent
+ * seeds a couple of dozen keys in `seed` before anything a reader would scrub
+ * to. That is the right answer for this axis (the stops must still partition
+ * the log), and since 9.18 the port marks it: the returned start carries
+ * `prologue: true` whenever it absorbed a stage, so a renderer that means
+ * "before anything ran" checks `kind === 'start' && !prologue` instead of
+ * assuming it from the kind.
+ *
+ * **The milestone rides on the stop.** Every kept stop carries its
+ * classification as `meta` — `Stop<Milestone>` — so a reader asks
+ * `stop.meta?.kind` (or {@link milestoneOf}, which reads the same slot) rather
+ * than re-running the classifier over the id. The bookends carry none.
  *
  * **A log with no milestones in it at all.** A non-empty log the classifier
  * recognises nothing in — a non-agent chart handed this strategy — yields the
@@ -109,21 +127,24 @@ export declare function milestoneOf(stop: Stop): Milestone | null;
  * @example
  * ```ts
  * import { timeTravel } from 'footprintjs/trace';
- * import { milestoneStopsStrategy, milestoneOf } from 'agentfootprint';
+ * import { milestoneStopsStrategy } from 'agentfootprint';
  *
  * const cursor = timeTravel(agent.getSnapshot()!, { strategy: milestoneStopsStrategy });
- * cursor.stops.map((s) => [s.label, milestoneOf(s)?.kind]);
+ * cursor.stops.map((s) => [s.label, s.meta?.kind]);
  * // measured on a two-turn `dynamic` run — 42 commits, 15 stops:
  * // [['Run start', undefined], ['Iteration', 'iteration'],
  * //  ['System prompt', 'slot'], ['Messages', 'slot'], ['Tools', 'slot'],
  * //  ['LLM turn', 'llm-turn'], ['Route', 'decision'], ['Tool call', 'tool-call'],
  * //  … the second turn …, ['Run end', undefined]]
+ * cursor.stops[0].prologue; // true — `seed` and the plumbing ran before the first Iteration
  * ```
  */
-export declare function milestoneStops(commitLog: readonly CommitBundle[], executionTree?: StageSnapshot): Stop[];
+export declare function milestoneStops(commitLog: readonly CommitBundle[], executionTree?: StageSnapshot): Stop<Milestone>[];
 /**
  * `milestoneStops` as a footprintjs `TimeTravelStrategy` — what you hand
- * `timeTravel(snapshot, { strategy })`.
+ * `timeTravel(snapshot, { strategy })`. Typed over {@link Milestone}, so the
+ * cursor's stops are `Stop<Milestone>` and `cursor.at()?.meta?.kind` is typed;
+ * it is still assignable wherever a bare `TimeTravelStrategy` is expected.
  */
-export declare const milestoneStopsStrategy: TimeTravelStrategy;
+export declare const milestoneStopsStrategy: TimeTravelStrategy<Milestone>;
 //# sourceMappingURL=milestoneStops.d.ts.map

package/dist/types/lib/time-travel/milestoneStops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"milestoneStops.d.ts","sourceRoot":"","sources":["../../../../src/lib/time-travel/milestoneStops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,IAAI,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,EAAE,CAuDR;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAAiD,CAAC"}
+{"version":3,"file":"milestoneStops.d.ts","sourceRoot":"","sources":["../../../../src/lib/time-travel/milestoneStops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAgB,KAAK,SAAS,EAAsB,MAAM,sBAAsB,CAAC;AAiBxF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAAC,SAAS,CAAC,EAAE,CAKnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,CAAC,SAAS,CAAgC,CAAC"}