agentfootprint 9.87.1 → 9.89.0

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

@@ -0,0 +1,210 @@
+/**
+ * epochs — where one epoch's committed pieces live, in either chart shape.
+ *
+ * Role:  Fold. It reads a finished run's recording and answers one question:
+ *        "for iteration k, which commit log holds the call, at which index,
+ *        and against which fold base?" It executes nothing, records nothing
+ *        and stores nothing beside the log.
+ * Reads: a recording (`commitLog`, `initialState`, `subflowResults`), through
+ *        footprintjs's own id parsers and this folder's `keyedFold.ts`.
+ * Emits: N/A.
+ *
+ * ── WHY THIS FILE EXISTS ───────────────────────────────────────────────────
+ * An agent's iteration — an EPOCH — commits to a different place depending on
+ * how the chart was built. Under `reactMode: 'dynamic'` the `call-llm` stage is
+ * a parent-level stage and its bundle is in the run's own log. Under
+ * `'dynamic-grouped'` each turn runs inside an `sf-llm-call` subflow, which has
+ * its own isolated runtime and its own log, retained per iteration under
+ * `subflowResults['sf-llm-call#k'].treeContext.history`.
+ *
+ * That fork was written out THREE times — `contextLedger.ts` had a private
+ * `llmCallMountKeys`, `trajectory.ts` had a byte-twin of it, and a rebuild of
+ * what the model was served would have been the third. Three copies of "which
+ * log is this key in?" is three chances to disagree about which iteration a
+ * value belonged to, on the one question the whole family exists to answer.
+ * So the fork lives here once, and every reader asks it.
+ *
+ * ── WHAT AN EPOCH NUMBER IS ────────────────────────────────────────────────
+ * The committed `iteration` value in effect at the call — the same number
+ * `callLLM` put on the receipt's `basis.epoch` and on every `iteration_start`
+ * event. It starts at 1. It is READ, not counted: a run that pauses and
+ * resumes, or one whose first turn is not its first stage, still names its
+ * epochs the way the run itself named them.
+ *
+ * ── EVERY READ FOLDS FROM THE BASE ─────────────────────────────────────────
+ * A location carries the FOLD SOURCE its log was recorded against, not just
+ * the log, and every read below goes through `keyedFold.ts`. A resumed run is
+ * a fresh executor seeded from `checkpoint.sharedState`, so most of what the
+ * call read is base rather than log; a fold that could not see the base
+ * answered "absent" for the whole pre-pause world and said nothing about it.
+ * `EpochLocation.basis` is that fold's own verdict, carried out to the reader
+ * so a recording that travelled without its base declares a gap instead of a
+ * confident empty view.
+ */
+import type { CommitBundle } from 'footprintjs/advanced';
+import { type FoldBasis, type FoldSourceLike } from './keyedFold.js';
+/** The shape a recording has to have for any of this to work — a snapshot, or
+ *  anything that hands one over. */
+export interface RecordingLike {
+    readonly commitLog?: readonly CommitBundle[];
+    /** The log's fold base (`RuntimeSnapshot.initialState`, footprintjs 9.17+).
+     *  Absent on a recording that travelled without it — see
+     *  {@link EpochLocation.basis}. */
+    readonly initialState?: Record<string, unknown>;
+    readonly executionTree?: unknown;
+    readonly subflowResults?: Record<string, unknown>;
+}
+/** One epoch, located: which log holds its call, where in that log, and what
+ *  that log folds against. */
+export interface EpochLocation {
+    /**
+     * The committed `iteration` at the call. 1-based, and READ rather than
+     * counted — a run that pauses and resumes still names its epochs the way the
+     * run itself named them.
+     *
+     * ONE fallback, and it is a count: when the fold cannot read `iteration` at
+     * all (a recording whose base did not travel, on a run that never re-`set`
+     * it), this is the location's position in run order instead. The tell is
+     * {@link EpochLocation.basis} / {@link EpochLocation.runBasis} reading
+     * `'log-only'`, which is also what makes `servedView.ts` raise
+     * `no-fold-base`. A view must have some number to be addressed by; this one
+     * is the honest second choice, not a claim about the record.
+     */
+    readonly epoch: number;
+    /** The `call-llm` stage's `runtimeStageId` — the llm-turn stop's own id. */
+    readonly callRuntimeStageId: string;
+    /** The log the call committed to: the run's own under `'dynamic'`, the
+     *  turn's inner history under `'dynamic-grouped'`. */
+    readonly log: readonly CommitBundle[];
+    /** The call's ARRAY index in {@link EpochLocation.log}. */
+    readonly callIdx: number;
+    /** The RUN's log, always. Run constants (a build-time fact seeded once) are
+     *  read here, because a grouped turn's inner log never sees them unless the
+     *  boundary happens to carry them. */
+    readonly runLog: readonly CommitBundle[];
+    /** The `sf-llm-call` mount this epoch was projected from — set under
+     *  `'dynamic-grouped'` only, and the tell that `callIdx` is inner-relative. */
+    readonly subflowScope?: string;
+    /**
+     * The fold source {@link EpochLocation.log} belongs to — the log PLUS the
+     * base it was recorded against. Reads go through it, never through the bare
+     * array, so a value seeded before the run (every key of a resumed run) folds
+     * from where it actually came from.
+     */
+    readonly source: FoldSourceLike;
+    /** The same, for {@link EpochLocation.runLog}. */
+    readonly runSource: FoldSourceLike;
+    /**
+     * How {@link EpochLocation.source} folds. `'log-only'` means the recording
+     * travelled without its fold base, so anything the log never `set` reads as
+     * absent — `servedView.ts` turns that into a declared gap rather than an
+     * empty view.
+     */
+    readonly basis: FoldBasis;
+    /** The same, for {@link EpochLocation.runSource}. */
+    readonly runBasis: FoldBasis;
+    /** `false` when this recording carries no RUN log at all — a subtree handed
+     *  in on its own. Every run constant is then unreadable, which
+     *  `servedView.ts` declares rather than reads as absent. */
+    readonly hasRunLog: boolean;
+}
+/**
+ * A snapshot from whatever the caller had: a runner (`Agent`, `LLMCall`), or
+ * the snapshot itself. Duck-typed on purpose — a recording read back from JSON
+ * is a plain object and must work exactly like a live one.
+ */
+export declare function recordingOf(source: unknown): RecordingLike | undefined;
+/**
+ * The `sf-llm-call` mount keys in `subflowResults`, in loop order.
+ *
+ * Non-empty ⇒ the run is GROUPED and every turn's pieces are in its own inner
+ * log. Empty ⇒ flat, and the run's own log holds everything.
+ *
+ * @example
+ * ```ts
+ * llmCallMountKeys(snapshot.subflowResults); // ['sf-llm-call#4', 'sf-llm-call#9']
+ * ```
+ */
+export declare function llmCallMountKeys(subflowResults: Record<string, unknown> | undefined): string[];
+/**
+ * Every epoch in a recording, in run order — the ONE owner of the flat /
+ * grouped fork.
+ *
+ * Returns `[]` for a recording with no LLM call in it at all (an empty log, a
+ * chart with no `call-llm` stage). That is a different fact from "the epoch you
+ * asked for is not here", which is what {@link epochAt} says with `undefined`.
+ *
+ * MEMOIZED on the recording object, because the cost of locating epochs is a
+ * pass over the log and a per-epoch reader asks for one epoch at a time: before
+ * this, scrubbing a 600-turn run epoch by epoch relocated every epoch on every
+ * call and took 20.8 s. Holding the snapshot and asking it repeatedly is the
+ * shape a reader's UI actually has, so the memo is keyed on exactly that
+ * object; a caller that hands in a runner and gets a fresh snapshot each time
+ * pays the pass each time, which is the cost of asking a different question.
+ *
+ * FROZEN, because it is memoized: the array and each location on it are the
+ * very objects the next caller gets, so an edit here would be an edit to
+ * everybody's answer. The same law `keyedFold.ts` · `freezeDeep` states for a
+ * folded value. What is NOT frozen is what a location POINTS AT — `log`,
+ * `source`, `runSource` are the caller's own recording, and this file does not
+ * get to lock down an object it was merely handed.
+ *
+ * @example
+ * ```ts
+ * import { epochLocations } from 'agentfootprint';
+ *
+ * epochLocations(agent.getSnapshot()!).map((e) => [e.epoch, e.callRuntimeStageId]);
+ * // dynamic:         [[1, 'call-llm#12'], [2, 'call-llm#31']]
+ * // dynamic-grouped: [[1, 'sf-llm-call/call-llm#9'], [2, 'sf-llm-call/call-llm#28']]
+ * ```
+ */
+export declare function epochLocations(source: unknown): readonly EpochLocation[];
+/**
+ * One epoch by number, or `undefined` when the run has no such iteration.
+ *
+ * @example
+ * ```ts
+ * epochAt(agent.getSnapshot()!, 2)?.callRuntimeStageId; // 'call-llm#31'
+ * ```
+ */
+export declare function epochAt(source: unknown, epoch: number): EpochLocation | undefined;
+/**
+ * The value of `key` as the epoch's call READ it — folded to just BEFORE the
+ * call's own bundle, so a key the call itself writes back (`history` gains the
+ * assistant turn; `receipt` is minted) reads as it was on the way in.
+ *
+ * Folded from the run's base, not from the log alone: on a resumed run the
+ * call read values the log never wrote, and reading those as absent is the
+ * fiction `keyedFold.ts` exists to end. A call that is its log's FIRST commit
+ * (a grouped turn, or the first stage after a resume) therefore folds to the
+ * base rather than to nothing.
+ *
+ * @example
+ * ```ts
+ * const epoch = epochAt(snapshot, 1)!;
+ * (readAtCall(epoch, 'history') as unknown[]).length; // the turns that went out
+ * ```
+ */
+export declare function readAtCall(location: EpochLocation, key: string): unknown;
+/**
+ * The value of `key` the epoch's call itself COMMITTED — folded through the
+ * call's own bundle. The receipt is read this way, and only the receipt: it is
+ * the one value the call writes that describes the call.
+ */
+export declare function readAfterCall(location: EpochLocation, key: string): unknown;
+/**
+ * A RUN CONSTANT: a build-time fact `seed` put on the record once, read from
+ * the run's own log.
+ *
+ * It is read from the run log rather than the epoch's log because that is where
+ * `seed` runs in both chart shapes. Under `'dynamic-grouped'` the turn's inner
+ * log only ever holds what the boundary's `inputMapper` carried in, and a
+ * constant nobody inside the turn reads is not carried — so asking the inner
+ * log would answer "absent" for a fact the run plainly recorded.
+ *
+ * `undefined` has TWO causes and a caller must not blur them: the run never
+ * recorded this constant, or this recording carries no run log to read
+ * (`EpochLocation.hasRunLog` is `false` — a subtree handed in on its own).
+ * `servedView.ts` branches on that flag and declares a gap for the second.
+ */
+export declare function readRunConstant(location: EpochLocation, key: string): unknown;

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

@@ -0,0 +1,274 @@
+/**
+ * epochs — where one epoch's committed pieces live, in either chart shape.
+ *
+ * Role:  Fold. It reads a finished run's recording and answers one question:
+ *        "for iteration k, which commit log holds the call, at which index,
+ *        and against which fold base?" It executes nothing, records nothing
+ *        and stores nothing beside the log.
+ * Reads: a recording (`commitLog`, `initialState`, `subflowResults`), through
+ *        footprintjs's own id parsers and this folder's `keyedFold.ts`.
+ * Emits: N/A.
+ *
+ * ── WHY THIS FILE EXISTS ───────────────────────────────────────────────────
+ * An agent's iteration — an EPOCH — commits to a different place depending on
+ * how the chart was built. Under `reactMode: 'dynamic'` the `call-llm` stage is
+ * a parent-level stage and its bundle is in the run's own log. Under
+ * `'dynamic-grouped'` each turn runs inside an `sf-llm-call` subflow, which has
+ * its own isolated runtime and its own log, retained per iteration under
+ * `subflowResults['sf-llm-call#k'].treeContext.history`.
+ *
+ * That fork was written out THREE times — `contextLedger.ts` had a private
+ * `llmCallMountKeys`, `trajectory.ts` had a byte-twin of it, and a rebuild of
+ * what the model was served would have been the third. Three copies of "which
+ * log is this key in?" is three chances to disagree about which iteration a
+ * value belonged to, on the one question the whole family exists to answer.
+ * So the fork lives here once, and every reader asks it.
+ *
+ * ── WHAT AN EPOCH NUMBER IS ────────────────────────────────────────────────
+ * The committed `iteration` value in effect at the call — the same number
+ * `callLLM` put on the receipt's `basis.epoch` and on every `iteration_start`
+ * event. It starts at 1. It is READ, not counted: a run that pauses and
+ * resumes, or one whose first turn is not its first stage, still names its
+ * epochs the way the run itself named them.
+ *
+ * ── EVERY READ FOLDS FROM THE BASE ─────────────────────────────────────────
+ * A location carries the FOLD SOURCE its log was recorded against, not just
+ * the log, and every read below goes through `keyedFold.ts`. A resumed run is
+ * a fresh executor seeded from `checkpoint.sharedState`, so most of what the
+ * call read is base rather than log; a fold that could not see the base
+ * answered "absent" for the whole pre-pause world and said nothing about it.
+ * `EpochLocation.basis` is that fold's own verdict, carried out to the reader
+ * so a recording that travelled without its base declares a gap instead of a
+ * confident empty view.
+ */
+import { parseRuntimeStageId, splitStageId } from 'footprintjs/trace';
+import { STAGE_IDS, SUBFLOW_IDS } from '../../conventions.js';
+import { keyedFold } from './keyedFold.js';
+/**
+ * A snapshot from whatever the caller had: a runner (`Agent`, `LLMCall`), or
+ * the snapshot itself. Duck-typed on purpose — a recording read back from JSON
+ * is a plain object and must work exactly like a live one.
+ */
+export function recordingOf(source) {
+    const runner = source;
+    const accessor = runner?.getLastSnapshot ?? runner?.getSnapshot;
+    if (typeof accessor === 'function') {
+        return accessor.call(source);
+    }
+    return source;
+}
+/**
+ * The `sf-llm-call` mount keys in `subflowResults`, in loop order.
+ *
+ * Non-empty ⇒ the run is GROUPED and every turn's pieces are in its own inner
+ * log. Empty ⇒ flat, and the run's own log holds everything.
+ *
+ * @example
+ * ```ts
+ * llmCallMountKeys(snapshot.subflowResults); // ['sf-llm-call#4', 'sf-llm-call#9']
+ * ```
+ */
+export function llmCallMountKeys(subflowResults) {
+    if (!subflowResults)
+        return [];
+    return Object.keys(subflowResults)
+        .filter((k) => k.includes('#') && splitStageId(k.split('#')[0]).localStageId === SUBFLOW_IDS.LLM_CALL)
+        .sort((a, b) => parseRuntimeStageId(a).executionIndex - parseRuntimeStageId(b).executionIndex);
+}
+/**
+ * One `sf-llm-call` mount's own subtree — its log AND the base that log folds
+ * against. The subtree, not the array, because the whole point of a location
+ * is that a read lands on the base as well as the diffs.
+ */
+function innerSubtreeOf(subflowResults, key) {
+    const entry = subflowResults[key];
+    const tree = entry?.treeContext;
+    return tree !== null && typeof tree === 'object' && Array.isArray(tree.history)
+        ? tree
+        : undefined;
+}
+/**
+ * The FIRST commit of the `call-llm` stage in a log, or `-1`.
+ *
+ * First, not last, for the reason `commitStops` anchors there: one stage
+ * execution can flush more than one bundle under one `runtimeStageId`, and the
+ * call's own reads happened at the first.
+ */
+function callIndexIn(log) {
+    for (let i = 0; i < log.length; i++) {
+        const stageId = log[i]?.stageId;
+        if (stageId && splitStageId(stageId).localStageId === STAGE_IDS.CALL_LLM)
+            return i;
+    }
+    return -1;
+}
+/** Located epochs, memoized on the recording object. */
+const LOCATIONS = new WeakMap();
+/**
+ * Every epoch in a recording, in run order — the ONE owner of the flat /
+ * grouped fork.
+ *
+ * Returns `[]` for a recording with no LLM call in it at all (an empty log, a
+ * chart with no `call-llm` stage). That is a different fact from "the epoch you
+ * asked for is not here", which is what {@link epochAt} says with `undefined`.
+ *
+ * MEMOIZED on the recording object, because the cost of locating epochs is a
+ * pass over the log and a per-epoch reader asks for one epoch at a time: before
+ * this, scrubbing a 600-turn run epoch by epoch relocated every epoch on every
+ * call and took 20.8 s. Holding the snapshot and asking it repeatedly is the
+ * shape a reader's UI actually has, so the memo is keyed on exactly that
+ * object; a caller that hands in a runner and gets a fresh snapshot each time
+ * pays the pass each time, which is the cost of asking a different question.
+ *
+ * FROZEN, because it is memoized: the array and each location on it are the
+ * very objects the next caller gets, so an edit here would be an edit to
+ * everybody's answer. The same law `keyedFold.ts` · `freezeDeep` states for a
+ * folded value. What is NOT frozen is what a location POINTS AT — `log`,
+ * `source`, `runSource` are the caller's own recording, and this file does not
+ * get to lock down an object it was merely handed.
+ *
+ * @example
+ * ```ts
+ * import { epochLocations } from 'agentfootprint';
+ *
+ * epochLocations(agent.getSnapshot()!).map((e) => [e.epoch, e.callRuntimeStageId]);
+ * // dynamic:         [[1, 'call-llm#12'], [2, 'call-llm#31']]
+ * // dynamic-grouped: [[1, 'sf-llm-call/call-llm#9'], [2, 'sf-llm-call/call-llm#28']]
+ * ```
+ */
+export function epochLocations(source) {
+    const recording = recordingOf(source);
+    if (recording !== null && typeof recording === 'object') {
+        const memo = LOCATIONS.get(recording);
+        if (memo !== undefined)
+            return memo;
+    }
+    const located = Object.freeze(locate(recording).map((e) => Object.freeze(e)));
+    if (recording !== null && typeof recording === 'object')
+        LOCATIONS.set(recording, located);
+    return located;
+}
+/** The uncached pass — one walk of the log, one keyed fold per source. */
+function locate(recording) {
+    const runLog = (recording?.commitLog ?? []);
+    const runSource = recording ?? {};
+    const runFold = keyedFold(runSource);
+    const hasRunLog = runLog.length > 0;
+    const subflowResults = recording?.subflowResults;
+    const mounts = llmCallMountKeys(subflowResults);
+    if (mounts.length > 0 && subflowResults) {
+        const found = [];
+        for (const [ordinal, key] of mounts.entries()) {
+            const inner = innerSubtreeOf(subflowResults, key);
+            const log = (inner?.history ?? []);
+            const callIdx = callIndexIn(log);
+            if (inner === undefined || callIdx < 0)
+                continue;
+            const fold = keyedFold(inner);
+            const iteration = fold.valueAt('iteration', callIdx);
+            found.push({
+                epoch: typeof iteration === 'number' && Number.isFinite(iteration) ? iteration : ordinal + 1,
+                callRuntimeStageId: log[callIdx].runtimeStageId,
+                log,
+                callIdx,
+                runLog,
+                subflowScope: key,
+                source: inner,
+                runSource,
+                basis: fold.basis,
+                runBasis: runFold.basis,
+                hasRunLog,
+            });
+        }
+        return found;
+    }
+    // FLAT: every `call-llm` bundle in the run's own log, at its first commit.
+    const found = [];
+    const seen = new Set();
+    for (let i = 0; i < runLog.length; i++) {
+        const bundle = runLog[i];
+        if (splitStageId(bundle.stageId).localStageId !== STAGE_IDS.CALL_LLM)
+            continue;
+        if (seen.has(bundle.runtimeStageId))
+            continue;
+        seen.add(bundle.runtimeStageId);
+        const iteration = runFold.valueAt('iteration', i);
+        found.push({
+            epoch: typeof iteration === 'number' && Number.isFinite(iteration) ? iteration : found.length + 1,
+            callRuntimeStageId: bundle.runtimeStageId,
+            log: runLog,
+            callIdx: i,
+            runLog,
+            source: runSource,
+            runSource,
+            basis: runFold.basis,
+            runBasis: runFold.basis,
+            hasRunLog,
+        });
+    }
+    return found;
+}
+/**
+ * One epoch by number, or `undefined` when the run has no such iteration.
+ *
+ * @example
+ * ```ts
+ * epochAt(agent.getSnapshot()!, 2)?.callRuntimeStageId; // 'call-llm#31'
+ * ```
+ */
+export function epochAt(source, epoch) {
+    return epochLocations(source).find((e) => e.epoch === epoch);
+}
+/**
+ * The value of `key` as the epoch's call READ it — folded to just BEFORE the
+ * call's own bundle, so a key the call itself writes back (`history` gains the
+ * assistant turn; `receipt` is minted) reads as it was on the way in.
+ *
+ * Folded from the run's base, not from the log alone: on a resumed run the
+ * call read values the log never wrote, and reading those as absent is the
+ * fiction `keyedFold.ts` exists to end. A call that is its log's FIRST commit
+ * (a grouped turn, or the first stage after a resume) therefore folds to the
+ * base rather than to nothing.
+ *
+ * @example
+ * ```ts
+ * const epoch = epochAt(snapshot, 1)!;
+ * (readAtCall(epoch, 'history') as unknown[]).length; // the turns that went out
+ * ```
+ */
+export function readAtCall(location, key) {
+    if (location.callIdx < 0)
+        return undefined;
+    return keyedFold(location.source).valueAt(key, location.callIdx - 1);
+}
+/**
+ * The value of `key` the epoch's call itself COMMITTED — folded through the
+ * call's own bundle. The receipt is read this way, and only the receipt: it is
+ * the one value the call writes that describes the call.
+ */
+export function readAfterCall(location, key) {
+    if (location.callIdx < 0)
+        return undefined;
+    return keyedFold(location.source).valueAt(key, location.callIdx);
+}
+/**
+ * A RUN CONSTANT: a build-time fact `seed` put on the record once, read from
+ * the run's own log.
+ *
+ * It is read from the run log rather than the epoch's log because that is where
+ * `seed` runs in both chart shapes. Under `'dynamic-grouped'` the turn's inner
+ * log only ever holds what the boundary's `inputMapper` carried in, and a
+ * constant nobody inside the turn reads is not carried — so asking the inner
+ * log would answer "absent" for a fact the run plainly recorded.
+ *
+ * `undefined` has TWO causes and a caller must not blur them: the run never
+ * recorded this constant, or this recording carries no run log to read
+ * (`EpochLocation.hasRunLog` is `false` — a subtree handed in on its own).
+ * `servedView.ts` branches on that flag and declares a gap for the second.
+ */
+export function readRunConstant(location, key) {
+    if (!location.hasRunLog)
+        return undefined;
+    return keyedFold(location.runSource).valueAt(key, location.runLog.length - 1);
+}
+//# sourceMappingURL=epochs.js.map

package/dist/esm/lib/time-travel/epochs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epochs.js","sourceRoot":"","sources":["../../../../src/lib/time-travel/epochs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAuC,MAAM,gBAAgB,CAAC;AAqEhF;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAe;IACzC,MAAM,MAAM,GAAG,MAA8D,CAAC;IAC9E,MAAM,QAAQ,GAAG,MAAM,EAAE,eAAe,IAAI,MAAM,EAAE,WAAW,CAAC;IAChE,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,OAAQ,QAA0B,CAAC,IAAI,CAAC,MAAM,CAA8B,CAAC;IAC/E,CAAC;IACD,OAAO,MAAmC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAmD;IAClF,IAAI,CAAC,cAAc;QAAE,OAAO,EAAE,CAAC;IAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC;SAC/B,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,KAAK,WAAW,CAAC,QAAQ,CAC9F;SACA,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;AACnG,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CACrB,cAAuC,EACvC,GAAW;IAEX,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAA0C,CAAC;IAC3E,MAAM,IAAI,GAAG,KAAK,EAAE,WAAyC,CAAC;IAC9D,OAAO,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAC7E,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,GAA4B;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;QAChC,IAAI,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC,YAAY,KAAK,SAAS,CAAC,QAAQ;YAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,wDAAwD;AACxD,MAAM,SAAS,GAAG,IAAI,OAAO,EAAoC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC3F,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0EAA0E;AAC1E,SAAS,MAAM,CAAC,SAAoC;IAClD,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,SAAS,IAAI,EAAE,CAA4B,CAAC;IACvE,MAAM,SAAS,GAAmB,SAAS,IAAI,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACpC,MAAM,cAAc,GAAG,SAAS,EAAE,cAAc,CAAC;IAEjD,MAAM,MAAM,GAAG,gBAAgB,CAAC,cAAc,CAAC,CAAC;IAChD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,EAAE,CAAC;QACxC,MAAM,KAAK,GAAoB,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YAC9C,MAAM,KAAK,GAAG,cAAc,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YAClD,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,OAAO,IAAI,EAAE,CAA4B,CAAC;YAC9D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC;gBAAE,SAAS;YACjD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;YAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC;gBACT,KAAK,EACH,OAAO,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC;gBACvF,kBAAkB,EAAE,GAAG,CAAC,OAAO,CAAE,CAAC,cAAc;gBAChD,GAAG;gBACH,OAAO;gBACP,MAAM;gBACN,YAAY,EAAE,GAAG;gBACjB,MAAM,EAAE,KAAK;gBACb,SAAS;gBACT,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,OAAO,CAAC,KAAK;gBACvB,SAAS;aACV,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2EAA2E;IAC3E,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QAC1B,IAAI,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,KAAK,SAAS,CAAC,QAAQ;YAAE,SAAS;QAC/E,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC;YAAE,SAAS;QAC9C,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC;YACT,KAAK,EACH,OAAO,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YAC5F,kBAAkB,EAAE,MAAM,CAAC,cAAc;YACzC,GAAG,EAAE,MAAM;YACX,OAAO,EAAE,CAAC;YACV,MAAM;YACN,MAAM,EAAE,SAAS;YACjB,SAAS;YACT,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,KAAK;YACvB,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,MAAe,EAAE,KAAa;IACpD,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAC,QAAuB,EAAE,GAAW;IAC7D,IAAI,QAAQ,CAAC,OAAO,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,QAAuB,EAAE,GAAW;IAChE,IAAI,QAAQ,CAAC,OAAO,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,QAAuB,EAAE,GAAW;IAClE,IAAI,CAAC,QAAQ,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAChF,CAAC"}

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

@@ -1,8 +1,14 @@
 /**
- * time-travel/ — the agent's stops on a reader's cursor.
+ * time-travel/ — the agent's stops on a reader's cursor, and what the model
+ * was handed at each of them.
  *
- * Role: Fold. See README.md for what a milestone stop is, why the strategy is
- * composed from footprintjs's own per-stage axis rather than re-derived, and
- * how the same strategy serves both chart shapes.
+ * Role: Fold. See README.md for what a milestone stop is, what a receipt and a
+ * served view are, and how one strategy and one epoch owner serve both chart
+ * shapes.
  */
 export { milestoneOf, milestoneStops, milestoneStopsStrategy } from './milestoneStops.js';
+export { epochAt, epochLocations, llmCallMountKeys, readAfterCall, readAtCall, readRunConstant, recordingOf, type EpochLocation, type RecordingLike, } from './epochs.js';
+export { keyedFold, type FoldBasis, type FoldSourceLike, type KeyedFold } from './keyedFold.js';
+export { buildReceipt, messageDigestInput, toolDigestInput, receiptHash, stableJson, FORCED_OUTPUT_TOOL_KEY, RECEIPT_BOUNDARY, RECEIPT_HASH_CHARS, RECEIPT_KEY, UNSERIALIZABLE, type Receipt, type ReceiptAttentionOmission, type ReceiptCacheMarker, type ReceiptMessage, type ReceiptParams, type ReceiptPiece, type ReceiptRequestOnlyMessage, } from './receipt.js';
+export { sha256Hex } from './sha256.js';
+export { receiptAt, servedAt, servedViews, SERVED_GAPS, UNGAPPED_FIELDS, type ServedGap, type ServedGapCause, type ServedGapKind, type ServedPiece, type ServedRequestOnly, type ServedView, } from './servedView.js';

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

@@ -1,9 +1,15 @@
 /**
- * time-travel/ — the agent's stops on a reader's cursor.
+ * time-travel/ — the agent's stops on a reader's cursor, and what the model
+ * was handed at each of them.
  *
- * Role: Fold. See README.md for what a milestone stop is, why the strategy is
- * composed from footprintjs's own per-stage axis rather than re-derived, and
- * how the same strategy serves both chart shapes.
+ * Role: Fold. See README.md for what a milestone stop is, what a receipt and a
+ * served view are, and how one strategy and one epoch owner serve both chart
+ * shapes.
  */
 export { milestoneOf, milestoneStops, milestoneStopsStrategy } from './milestoneStops.js';
+export { epochAt, epochLocations, llmCallMountKeys, readAfterCall, readAtCall, readRunConstant, recordingOf, } from './epochs.js';
+export { keyedFold } from './keyedFold.js';
+export { buildReceipt, messageDigestInput, toolDigestInput, receiptHash, stableJson, FORCED_OUTPUT_TOOL_KEY, RECEIPT_BOUNDARY, RECEIPT_HASH_CHARS, RECEIPT_KEY, UNSERIALIZABLE, } from './receipt.js';
+export { sha256Hex } from './sha256.js';
+export { receiptAt, servedAt, servedViews, SERVED_GAPS, UNGAPPED_FIELDS, } from './servedView.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/time-travel/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/time-travel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,eAAe,EACf,WAAW,GAGZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAuD,MAAM,gBAAgB,CAAC;AAChG,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,GAQf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACX,eAAe,GAOhB,MAAM,iBAAiB,CAAC"}

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

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