agentfootprint 9.87.1 → 9.89.0

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

@@ -0,0 +1,286 @@
+/**
+ * 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 { applySmartMerge } from 'footprintjs/advanced';
+import { stateAt } from 'footprintjs/trace';
+/**
+ * The delimiter footprintjs joins nested trace paths with — the engine's own
+ * `DELIM`. Mirrored rather than imported because it is not on any public
+ * barrel.
+ *
+ * Today's scope facade records a nested write (`scope.profile.city = …`) as a
+ * MERGE on the top-level key rather than as a delimited path, so this is
+ * DEFENCE and not a hot path. It is still load-bearing: a delimited path must
+ * be attributed to its ROOT key, or a write to `history<DELIM>0<DELIM>content`
+ * would be filed under a key nobody asks for and dropped from every fold.
+ */
+const PATH_DELIM = '\u001F';
+/** The top-level state key a trace path belongs to. */
+function rootKeyOf(path) {
+    const cut = path.indexOf(PATH_DELIM);
+    return cut < 0 ? path : path.slice(0, cut);
+}
+/**
+ * Deep-freeze in place, skipping subtrees that are frozen already.
+ *
+ * ── A FOLD RESULT IS DETACHED, OR IT IS NOT A FOLD ─────────────────────────
+ * This module memoizes: `valueAt` hands the SAME object back on every call for
+ * the same question, and the forward cursor seeds the replay of every LATER
+ * index from that very object. Handing out a live reference therefore does not
+ * merely risk a surprise — a consumer that edits what it was handed silently
+ * rewrites what every later epoch reports was served, which is the one thing
+ * this family exists to be trusted about.
+ *
+ * It was not a hazard in the reader this module replaced. footprintjs's
+ * `commitValueAt` clones per call, so the same edit was harmless there; the
+ * memo is what introduced it, so the memo is where it is closed.
+ *
+ * FREEZING RATHER THAN CLONING PER READ, for two reasons. Cloning per read is
+ * exactly the cost the forward cursor exists to avoid — it puts an O(value)
+ * copy back on every question, on the hot path of a scrub. And freezing is the
+ * answer footprintjs itself already gives: `stateAt` returns
+ * `freezeDeep(structuredClone(out))`, so a caller that moves between the two
+ * folds meets one contract instead of two.
+ *
+ * The forward replay is unaffected: `applySmartMerge` opens with a
+ * `structuredClone` of its base, and a clone of a frozen value is not frozen.
+ *
+ * MEASURED, so the choice is not a guess, and reported because it is not free.
+ * On a 601-epoch run (10,219 commits) the whole per-epoch scrub — every
+ * epoch's system pieces, conversation and tool list, folded and rebuilt —
+ * costs 1,141 ms with the freeze and 930 ms without it: +211 ms, +23%, on a
+ * scrub that cost 20.8 s two fixes ago. The batch form moves 919 ms to
+ * 1,116 ms. The alternative is DEARER, not cheaper: on the same structure
+ * (1,200 messages) `structuredClone` costs 3.6x what this walk does — 0.94 ms
+ * against 0.26 ms — and a copy would have to run once per READ where the
+ * freeze runs once per memoized answer. A mutable answer is not worth 23%, and
+ * buying safety by copying would cost more than 23%.
+ */
+function freezeDeep(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    Object.freeze(value);
+    for (const key of Object.getOwnPropertyNames(value)) {
+        const inner = value[key];
+        if (inner !== null && typeof inner === 'object' && !Object.isFrozen(inner))
+            freezeDeep(inner);
+    }
+    return value;
+}
+/** The bundles, from whichever field this source spells them in. */
+function commitsOf(source) {
+    if (!source)
+        return [];
+    if (Array.isArray(source.commitLog))
+        return source.commitLog;
+    if (Array.isArray(source.history))
+        return source.history;
+    return [];
+}
+/** Build the per-key touch index in ONE pass over the log. */
+function indexTouches(log) {
+    const index = new Map();
+    for (let at = 0; at < log.length; at++) {
+        const bundle = log[at];
+        if (!bundle)
+            continue;
+        for (const entry of bundle.trace ?? []) {
+            const path = entry.path;
+            if (typeof path !== 'string')
+                continue;
+            const key = rootKeyOf(path);
+            const verb = entry.verb;
+            const touch = {
+                at,
+                bundle,
+                entry,
+                anchors: path === key && (verb === 'set' || verb === 'delete'),
+            };
+            const list = index.get(key);
+            if (list === undefined)
+                index.set(key, [touch]);
+            else
+                list.push(touch);
+        }
+    }
+    return index;
+}
+/** The last position in `touches` whose bundle index is `<= idx`, or `-1`. */
+function lastTouchAt(touches, idx) {
+    let lo = 0;
+    let hi = touches.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (touches[mid].at <= idx) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return found;
+}
+/** Memoized folds, one per source object. */
+const FOLDS = new WeakMap();
+/**
+ * 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 function keyedFold(source) {
+    if (source !== null && typeof source === 'object') {
+        const memo = FOLDS.get(source);
+        if (memo !== undefined)
+            return memo;
+    }
+    const log = commitsOf(source);
+    // `stateAt` at -1 folds NOTHING: it clones the base once and reports whether
+    // there was one. That is the whole reason to call the engine's own fold here
+    // rather than read `initialState` directly — the `basis` verdict is its
+    // answer to give, and a recording that travelled without its base must be
+    // able to say so.
+    const seed = stateAt(source, -1);
+    const index = indexTouches(log);
+    const answers = new Map();
+    /** Per key, the furthest replay position reached and the value there — see
+     *  the forward-cursor note in `compute`. */
+    const cursor = new Map();
+    /** One touch applied, through the ENGINE's verb switch, over a state
+     *  projected to this key alone. `applySmartMerge` navigates from the root,
+     *  so a delimited path lands exactly where it did in the real fold. */
+    const step = (key, value, touch) => applySmartMerge({ [key]: value }, touch.bundle.updates, touch.bundle.overwrite, [
+        touch.entry,
+    ])[key];
+    const compute = (key, idx) => {
+        const touches = index.get(key);
+        const last = touches === undefined ? -1 : lastTouchAt(touches, idx);
+        // The base's own value. `stateAt` already deep-freezes what it returns, so
+        // this is a no-op today — asserted rather than assumed, because the law
+        // this module states about its answers must not rest on another module
+        // continuing to keep it.
+        if (touches === undefined || last < 0)
+            return freezeDeep(seed.state[key]);
+        // Anchor at the latest write that fully determines the key on its own;
+        // everything before it — the base included — cannot be read back through
+        // it. With no anchor the base IS the starting value, which is the whole
+        // fix: `commitValueAt` starts from `undefined` here and folds a fiction.
+        let start = 0;
+        let anchored = false;
+        for (let i = last; i >= 0; i--) {
+            if (touches[i].anchors) {
+                start = i;
+                anchored = true;
+                break;
+            }
+        }
+        let from = start;
+        let value = anchored ? undefined : seed.state[key];
+        // THE FORWARD CURSOR, and why this module would be slower than the reader
+        // it replaces without it. An agent's `history` is `set` ONCE and appended
+        // to every turn, so a query at turn k has to replay k appends from the
+        // anchor — and a per-epoch scrub asks E times, which is O(E²) replays of a
+        // growing array. Resuming from the furthest position already reached makes
+        // the whole scrub O(E) replays instead, because a scrub walks forward.
+        // (Measured on a 96-turn run: 201 ms per scrub without this, 40 ms with.)
+        // A backward or out-of-order query simply falls back to the anchor, which
+        // is correct and no worse than never having cached anything.
+        const held = cursor.get(key);
+        if (held !== undefined && held.position >= start && held.position <= last) {
+            from = held.position + 1;
+            value = held.value;
+        }
+        for (let i = from; i <= last; i++)
+            value = step(key, value, touches[i]);
+        // Frozen HERE, before anything else can hold it: the cursor keeps this very
+        // object as the seed for every later index, and `valueAt` memoizes it. One
+        // freeze covers both — `keyedFold.ts` · `freezeDeep`.
+        freezeDeep(value);
+        cursor.set(key, { position: last, value });
+        return value;
+    };
+    const fold = {
+        basis: seed.basis,
+        length: log.length,
+        valueAt(key, idx) {
+            const at = Math.min(Math.floor(idx), log.length - 1);
+            let perKey = answers.get(key);
+            if (perKey === undefined) {
+                perKey = new Map();
+                answers.set(key, perKey);
+            }
+            if (perKey.has(at))
+                return perKey.get(at);
+            const value = compute(key, at);
+            perKey.set(at, value);
+            return value;
+        },
+    };
+    // The fold OBJECT is memoized too — the same one every caller of `keyedFold`
+    // gets for this source — so it is frozen for the same reason its answers are.
+    Object.freeze(fold);
+    if (source !== null && typeof source === 'object')
+        FOLDS.set(source, fold);
+    return fold;
+}
+//# sourceMappingURL=keyedFold.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyedFold.js","sourceRoot":"","sources":["../../../../src/lib/time-travel/keyedFold.ts"],"names":[],"mappings":"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"}

package/dist/esm/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,20 +127,23 @@ 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>;