agentfootprint 10.3.0 → 10.4.0

package/dist/esm/time/zone.js

@@ -0,0 +1,344 @@
+/**
+ * time/zone — IANA zone names and offset arithmetic, through `Intl`.
+ *
+ * Pattern: the platform's tz database behind two small questions — "what is
+ *          the offset of this zone at this instant?" and "which instant is
+ *          this wall time in this zone?" — with Temporal's four DST words for
+ *          the second. No dependency: `Intl.DateTimeFormat` carries the
+ *          database the runtime ships.
+ * Role:    L0 leaf (the time layer's one owner). Imports `instant.ts` only.
+ * Emits:   N/A.
+ *
+ * ## A zone is an IANA name, never an abbreviation
+ *
+ * `Intl` is more forgiving than this layer: it accepts `PST` (and reads it as
+ * `America/Los_Angeles`, whose October offset is -07:00, not PST's -08:00),
+ * `EST` (as `America/Panama`), and a bare offset such as `+05:30`. Each of
+ * those turns a person's words into a zone without saying so, so
+ * {@link isZoneName} refuses them: a name is accepted when it has an
+ * `Area/Location` shape (`America/Los_Angeles`, `Etc/GMT+5`) or is `UTC` /
+ * `GMT`, AND `Intl` knows it. An abbreviation reaches a zone only through a
+ * recorded map (a later step), never here.
+ *
+ * ## Cost — one `formatToParts` per (zone, instant), memoised
+ *
+ * Asking `Intl` is the whole cost of this module (a `formatToParts` is
+ * microseconds; everything else is arithmetic), and a resolution asks the
+ * same instants again: every candidate a DST probe validates is then spelled
+ * with its offset. So the formatter is built once per zone and the reading of
+ * each (zone, instant) is kept — the tz database cannot change inside a
+ * process — in a bounded memo cleared when full, like the formatter cache.
+ * `readWall` also skips the one probe it can prove redundant: when the offset
+ * a day before, at, and a day after the wall time agree, no change falls in
+ * that window, so the one candidate needs no check. What this buys is pinned
+ * as a COUNT by the performance case of test/time/resolve.test.ts, not a
+ * duration.
+ *
+ * ## DST — the four words
+ *
+ * | Wall time | `compatible` | `earlier` | `later` | `reject` |
+ * |-----------|--------------|-----------|---------|----------|
+ * | exists once | it | it | it | it |
+ * | exists twice (fall back, `01:30`) | the first | the first | the second | `undefined` |
+ * | never exists (spring forward, `02:30`) | shifted forward by the gap (`03:30`) | shifted back (`01:30`) | shifted forward | `undefined` |
+ *
+ * @example
+ * ```ts
+ * isZoneName('America/Los_Angeles'); // true
+ * isZoneName('PST');                 // false — an abbreviation
+ * offsetAt('America/Los_Angeles', Date.parse('2026-10-09T15:00:00Z')); // -420
+ * readWall({ year: 2026, month: 11, day: 1, hour: 1, minute: 30 }, 'America/Los_Angeles');
+ * // { kind: 'overlap', earlier: …08:30Z, later: …09:30Z }
+ * ```
+ */
+import { daysInMonth, utcWallMs } from './instant.js';
+/** `Area/Location` (one or more `/`), or the two single-word names that are not abbreviations of anything. */
+const IANA_SHAPE = /^(?:[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)+|UTC|GMT)$/;
+const MAX_NAME = 64;
+const MAX_CACHED = 256;
+const formatters = new Map();
+/** The cached formatter for `zone`, or `undefined` when `Intl` does not know it. Bounded: the cache is cleared when full. */
+function formatterFor(zone) {
+    const hit = formatters.get(zone);
+    if (hit !== undefined)
+        return hit;
+    let formatter;
+    try {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: zone,
+            hourCycle: 'h23',
+            era: 'short',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (formatters.size >= MAX_CACHED)
+        formatters.clear();
+    formatters.set(zone, formatter);
+    return formatter;
+}
+/** Whether `value` is an IANA zone name this runtime's tz database knows — see the module header for what is refused. */
+export function isZoneName(value) {
+    if (typeof value !== 'string' || value.length > MAX_NAME || !IANA_SHAPE.test(value))
+        return false;
+    return formatterFor(value) !== undefined;
+}
+/** The runtime's canonical spelling of a zone (`america/los_angeles` → `America/Los_Angeles`), or `undefined` when it is not a zone name. */
+export function canonicalZone(value) {
+    if (!isZoneName(value))
+        return undefined;
+    return formatterFor(value).resolvedOptions().timeZone;
+}
+/** The wall time an instant shows in `zone` (milliseconds kept). Frozen: the reading is shared through the memo. */
+export function wallAt(zone, ms) {
+    return shownWall(zoneFormatter(zone, 'wallAt'), zone, ms);
+}
+const MAX_READINGS = 4096;
+/** zone → instant → the wall time `Intl` shows there; `readingCount` bounds the whole memo. */
+const readings = new Map();
+let readingCount = 0;
+/** The memoised reading of `ms` in `zone` (the module header's cost note); `formatter` is `zone`'s, already checked. */
+function shownWall(formatter, zone, ms) {
+    const hit = readings.get(zone)?.get(ms);
+    if (hit !== undefined)
+        return hit;
+    const wall = Object.freeze(formatWall(formatter, ms));
+    if (readingCount >= MAX_READINGS) {
+        readings.clear();
+        readingCount = 0;
+    }
+    let byInstant = readings.get(zone);
+    if (byInstant === undefined) {
+        byInstant = new Map();
+        readings.set(zone, byInstant);
+    }
+    byInstant.set(ms, wall);
+    readingCount += 1;
+    return wall;
+}
+/** One `Intl` reading — the only call in this module that costs. */
+function formatWall(formatter, ms) {
+    const parts = {};
+    for (const part of formatter.formatToParts(new Date(ms)))
+        parts[part.type] = part.value;
+    const shownYear = Number(parts.year);
+    return {
+        // `era: 'short'` spells year 0 as '1 BC': astronomical year = 1 - shown.
+        year: parts.era === 'BC' || parts.era === 'B' ? 1 - shownYear : shownYear,
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hour: Number(parts.hour),
+        minute: Number(parts.minute),
+        second: Number(parts.second),
+        millisecond: ((ms % 1000) + 1000) % 1000,
+    };
+}
+function zoneFormatter(zone, caller) {
+    if (!isZoneName(zone)) {
+        throw new TypeError(`${caller}: ${JSON.stringify(zone)} is not an IANA zone name.`);
+    }
+    return formatterFor(zone);
+}
+function wallMs(wall) {
+    return utcWallMs(wall.year, wall.month, wall.day, wall.hour, wall.minute, wall.second ?? 0, wall.millisecond ?? 0);
+}
+/** The offset of `zone` at the instant `ms`, in MILLISECONDS east of UTC. */
+function offsetMsAt(zone, ms) {
+    return wallMs(wallAt(zone, ms)) - ms;
+}
+/**
+ * The offset of `zone` at the instant `ms`, in minutes east of UTC
+ * (`America/Los_Angeles` in October: -420). A historical local-mean-time
+ * offset can be a fraction of a minute.
+ */
+export function offsetAt(zone, ms) {
+    return offsetMsAt(zone, ms) / 60_000;
+}
+/** Whether a wall time's fields name a real calendar time (any zone aside). */
+export function isWallTime(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const w = value;
+    const int = (v, lo, hi) => typeof v === 'number' && Number.isInteger(v) && v >= lo && v <= hi;
+    if (!int(w.year, 0, 9999) || !int(w.month, 1, 12))
+        return false;
+    const year = w.year;
+    const month = w.month;
+    return (int(w.day, 1, daysInMonth(year, month)) &&
+        int(w.hour, 0, 23) &&
+        int(w.minute, 0, 59) &&
+        (w.second === undefined || int(w.second, 0, 59)) &&
+        (w.millisecond === undefined || int(w.millisecond, 0, 999)));
+}
+/**
+ * What `wall` names in `zone`: one instant, two (a fall-back overlap:
+ * `earlier`, `later`), or none (a spring-forward gap: `earlier` is the wall
+ * time read with the offset after the change, `later` with the offset before
+ * it — Temporal's two readings). Throws a `TypeError` on a wall time that is
+ * not a calendar time or a zone that is not a zone name.
+ */
+export function readWall(wall, zone) {
+    if (!isWallTime(wall)) {
+        throw new TypeError(`readWall: ${JSON.stringify(wall)} is not a wall time.`);
+    }
+    zoneFormatter(zone, 'readWall');
+    const w = wallMs(wall);
+    // Every real zone changes offset at most once within a day either side.
+    const before = offsetMsAt(zone, w - 86_400_000);
+    const after = offsetMsAt(zone, w + 86_400_000);
+    const at = offsetMsAt(zone, w);
+    // One offset across the two days: no change in the window, so `w - at` (at
+    // most 14 h from `w`) shows `wall` — the check below would ask `Intl` for nothing.
+    if (before === at && at === after)
+        return { kind: 'unique', ms: w - at };
+    const offsets = [...new Set([before, at, after])];
+    const valid = offsets.map((o) => w - o).filter((t) => offsetMsAt(zone, t) === w - t);
+    const instants = [...new Set(valid)].sort((a, b) => a - b);
+    if (instants.length === 1)
+        return { kind: 'unique', ms: instants[0] };
+    if (instants.length >= 2) {
+        return {
+            kind: 'overlap',
+            earlier: instants[0],
+            later: instants[instants.length - 1],
+        };
+    }
+    return { kind: 'gap', earlier: w - after, later: w - before };
+}
+/**
+ * The instant `wall` names in `zone` under `disambiguation` (the module
+ * table), or `undefined` under `'reject'` when the wall time is doubled or
+ * skipped.
+ */
+export function wallToInstant(wall, zone, disambiguation) {
+    const reading = readWall(wall, zone);
+    if (reading.kind === 'unique')
+        return reading.ms;
+    if (disambiguation === 'reject')
+        return undefined;
+    if (reading.kind === 'overlap')
+        return disambiguation === 'later' ? reading.later : reading.earlier;
+    return disambiguation === 'earlier' ? reading.earlier : reading.later;
+}
+/**
+ * The tz database version this runtime's `Intl` carries — Node names it
+ * (`process.versions.tz`, e.g. `'2025b'`); any other runtime answers
+ * `'unknown'`. Recorded on every `time-reading` row: zone data changes
+ * between releases, so a reading is re-derivable only with it.
+ */
+export function tzdataVersion() {
+    const versions = globalThis.process
+        ?.versions;
+    const tz = versions?.tz;
+    return typeof tz === 'string' && tz.length > 0 && tz.length <= 32 ? tz : 'unknown';
+}
+// ─── Zones named in words (data from the tz database, never a word list) ─
+/** The areas a place's zone is looked up under (`Etc` and the legacy `US/…` links are not places). */
+const PLACE_AREAS = [
+    'Africa',
+    'America',
+    'Antarctica',
+    'Asia',
+    'Atlantic',
+    'Australia',
+    'Europe',
+    'Indian',
+    'Pacific',
+];
+const PLACE_KEY = /^[A-Za-z][A-Za-z'.-]*(?:_[A-Za-z][A-Za-z'.-]*){0,3}$/;
+const placeMemo = new Map();
+let placeIndex;
+/** Last segment (lower case) → the runtime's zones that end in it, from `Intl.supportedValuesOf`. */
+function placeIndexOf() {
+    if (placeIndex !== undefined)
+        return placeIndex;
+    const index = new Map();
+    const supported = Intl.supportedValuesOf;
+    let names = [];
+    try {
+        names = typeof supported === 'function' ? supported('timeZone') : [];
+    }
+    catch {
+        names = [];
+    }
+    for (const name of names) {
+        const area = name.slice(0, name.indexOf('/'));
+        if (!PLACE_AREAS.includes(area))
+            continue;
+        const last = name.slice(name.lastIndexOf('/') + 1).toLowerCase();
+        index.set(last, [...(index.get(last) ?? []), name]);
+    }
+    placeIndex = index;
+    return index;
+}
+/**
+ * The ONE zone a place name names in this runtime's tz database, or
+ * `undefined` when it names none or more than one. `London` → `Europe/London`,
+ * `New York` → `America/New_York`; `India`, `Pacific`, `Eastern` → `undefined`
+ * (no zone ends in them — a region is not a place). Looked up two ways, both
+ * the tz database's own data: the zones whose last segment is the place, and
+ * `Area/Place` under each geographic area (which admits a renamed city's link,
+ * `Kyiv`). Every hit is compared by its canonical name, so a link and its
+ * target are one zone. Memoised; the runtime's database does not change.
+ *
+ * @example
+ * ```ts
+ * zoneOfPlace('London');   // 'Europe/London'
+ * zoneOfPlace('New York'); // 'America/New_York'
+ * zoneOfPlace('India');    // undefined — asked, never guessed
+ * ```
+ */
+export function zoneOfPlace(place) {
+    const key = place.trim().replace(/\s+/g, '_');
+    if (key.length > 32 || !PLACE_KEY.test(key))
+        return undefined;
+    const memo = placeMemo.get(key.toLowerCase());
+    if (memo !== undefined)
+        return memo ?? undefined;
+    const found = new Set();
+    for (const name of placeIndexOf().get(key.toLowerCase()) ?? []) {
+        found.add(canonicalZone(name) ?? name);
+    }
+    for (const area of PLACE_AREAS) {
+        const name = canonicalZone(`${area}/${key}`);
+        if (name !== undefined)
+            found.add(name);
+    }
+    const zone = found.size === 1 ? [...found][0] : undefined;
+    if (placeMemo.size >= MAX_CACHED)
+        placeMemo.clear();
+    placeMemo.set(key.toLowerCase(), zone ?? null);
+    return zone;
+}
+/**
+ * The IANA zone that is a fixed offset, for a whole-hour offset the tz
+ * database names (`Etc/GMT+8` is −08:00 — POSIX signs, inverted), else
+ * `undefined`. How a window read at a literal offset, or typed with one no
+ * other zone shows, names its zone without claiming a place's.
+ *
+ * @example
+ * ```ts
+ * fixedOffsetZone(-480); // 'Etc/GMT+8'
+ * fixedOffsetZone(0);    // 'UTC'
+ * fixedOffsetZone(330);  // undefined — no Etc zone for +05:30
+ * ```
+ */
+export function fixedOffsetZone(minutes) {
+    if (minutes === 0)
+        return 'UTC';
+    if (!Number.isInteger(minutes) || minutes % 60 !== 0)
+        return undefined;
+    const hours = minutes / 60;
+    if (hours < -12 || hours > 14)
+        return undefined;
+    const name = `Etc/GMT${hours < 0 ? '+' : '-'}${Math.abs(hours)}`;
+    return isZoneName(name) ? name : undefined;
+}
+//# sourceMappingURL=zone.js.map

package/dist/esm/time/zone.js.map

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

package/dist/esm/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 'foottrace';
+import { STAGE_IDS, SUBFLOW_IDS } from '../lib/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/time-travel/epochs.js.map

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

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

@@ -0,0 +1,16 @@
+/**
+ * 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, 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, transformHashOf, TRANSFORM_HASH_PREFIX, FORCED_OUTPUT_TOOL_KEY, RECEIPT_BOUNDARY, RECEIPT_HASH_CHARS, UNSERIALIZABLE, type Receipt, type ReceiptAttentionOmission, type ReceiptCacheMarker, type ReceiptMessage, type ReceiptParams, type ReceiptPiece, type ReceiptRequestOnlyMessage, type RequestMeasurement, type RequestJsonSize, type StoredReceipt, } from '../core/agent/receipt/receipt.js';
+export { sha256Hex } from '../lib/sha256.js';
+export { stableJson } from '../lib/stableJson.js';
+export { RECEIPT_KEY } from '../lib/conventions.js';
+export { receiptAt, servedAt, servedViews, SERVED_GAPS, UNGAPPED_FIELDS, type ServedGap, type ServedGapCause, type ServedGapKind, type ServedPiece, type ServedRequestOnly, type ServedView, } from './servedView.js';