@statelyai/agent 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/event-log-store-Ba2fsc4E.mjs

@@ -0,0 +1,576 @@
+import { H as AgentError, L as resolveMachineVersion, O as djb2Hex, t as AGENT_USAGE_TOKEN_FIELDS } from "./text-logic-Bl_ZRxDi.mjs";
+import "./usage-BdEjFuIi.mjs";
+import { initialTransition, transition } from "xstate";
+//#region src/event-log.ts
+/**
+* The event log: an append-only journal of the EXTERNAL inputs a machine
+* consumed, and the pure fold ({@link replay}) that turns that journal back
+* into a snapshot without executing anything.
+*
+* A journaled entry is always an external input — an invoke completion
+* (`xstate.done.actor`/`xstate.error.actor` carrying its output inline), a
+* user-sent event, a timer firing, a reserved `@agent.usage` record. Never a
+* raised/internal event: replay re-derives those from the machine's own logic,
+* so journaling them would double-apply them.
+*
+* A log is self-contained: its reserved first entry ({@link initEntry}) carries
+* either the machine `input` (a fresh start) or a persisted snapshot (a
+* continuation across a machine version, or from a log-less legacy snapshot),
+* so {@link replay} needs no side channel.
+* @module
+*/
+/** The durable entry envelope version. */
+const AGENT_EVENT_SCHEMA_VERSION = 1;
+/**
+* The reserved event type of the first entry of every log. It carries the
+* machine `input` (fresh start) or a persisted `snapshot` (continuation), so a
+* log replays with no side channel. Lives in the reserved `@agent.*` namespace
+* so it can never collide with a machine's own vocabulary; it is consumed by
+* {@link replay} and never fed to `transition`.
+*/
+const AGENT_INIT_EVENT_TYPE = "@agent.init";
+/** A malformed or internally inconsistent log. */
+var AgentEventLogError = class extends AgentError {
+	constructor(message) {
+		super("invalid-event-log", message);
+		this.name = "AgentEventLogError";
+	}
+};
+/** A precise failure when an entry would not survive a JSON round-trip. */
+var NonSerializableAgentEventError = class extends AgentError {
+	path;
+	valueType;
+	constructor(path, valueType) {
+		super("non-serializable-event", `Agent event field '${path}' is not JSON-serializable (${valueType}).`);
+		this.name = "NonSerializableAgentEventError";
+		this.path = path;
+		this.valueType = valueType;
+	}
+};
+/** Replay reached a state that does not match the entry's recorded hash. */
+var AgentReplayDivergenceError = class extends AgentError {
+	constructor(eventId, index, kind, expected, actual) {
+		super("replay-diverged", kind === "missing-verification" ? `Replay entry '${eventId}' at index ${index} has no recorded verification hash.` : `Replay diverged after '${eventId}' at index ${index}: expected state hash '${expected}', got '${actual}'.`);
+		this.eventId = eventId;
+		this.index = index;
+		this.kind = kind;
+		this.expected = expected;
+		this.actual = actual;
+		this.name = "AgentReplayDivergenceError";
+	}
+};
+/**
+* An entry was recorded against a different machine (id) or a different
+* machine version than the one replaying it. An init-with-snapshot entry is
+* exempt: that entry IS the bridge from the old version to the new one.
+*/
+var AgentMachineVersionMismatchError = class extends AgentError {
+	constructor(eventId, index, expected, actual) {
+		super("machine-version-mismatch", `Event log entry '${eventId}' at index ${index} targets machine '${actual.machineId}'@'${actual.machineVersion}', expected '${expected.machineId}'@'${expected.machineVersion}'.`);
+		this.eventId = eventId;
+		this.index = index;
+		this.expected = expected;
+		this.actual = actual;
+		this.name = "AgentMachineVersionMismatchError";
+	}
+};
+function assertNoHiddenKeys(value, path, isOwnKey) {
+	const symbols = Object.getOwnPropertySymbols(value);
+	if (symbols.length > 0) throw new NonSerializableAgentEventError(`${path}.[${String(symbols[0])}]`, "symbol key");
+	const hiddenKey = Object.getOwnPropertyNames(value).find((key) => !isOwnKey?.(key) && !Object.getOwnPropertyDescriptor(value, key)?.enumerable);
+	if (hiddenKey !== void 0) throw new NonSerializableAgentEventError(`${path}.${hiddenKey}`, "non-enumerable property");
+}
+const arrayIndexPattern = /^(?:0|[1-9]\d*)$/;
+/**
+* Rejects values JSON would drop or coerce. Unlike `JSON.stringify`, this does
+* not silently erase `undefined`/functions or turn non-finite numbers into
+* `null`; durable entries contain only plain JSON values.
+*/
+function assertJsonSerializable(value, path = "entry", ancestors = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || Object.is(value, -0)) throw new NonSerializableAgentEventError(path, Object.is(value, -0) ? "-0" : String(value));
+		return;
+	}
+	if (typeof value !== "object") throw new NonSerializableAgentEventError(path, typeof value);
+	if (ancestors.has(value)) throw new NonSerializableAgentEventError(path, "circular reference");
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index++) {
+				if (!Object.hasOwn(value, index)) throw new NonSerializableAgentEventError(`${path}[${index}]`, "array hole");
+				assertJsonSerializable(value[index], `${path}[${index}]`, ancestors);
+			}
+			const extraKey = Object.keys(value).find((key) => !arrayIndexPattern.test(key) || Number(key) >= value.length);
+			if (extraKey !== void 0) throw new NonSerializableAgentEventError(`${path}.${extraKey}`, "array property");
+			assertNoHiddenKeys(value, path, (key) => key === "length" || arrayIndexPattern.test(key));
+			return;
+		}
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw new NonSerializableAgentEventError(path, value.constructor?.name ?? "object");
+		assertNoHiddenKeys(value, path);
+		for (const [key, child] of Object.entries(value)) assertJsonSerializable(child, `${path}.${key}`, ancestors);
+	} finally {
+		ancestors.delete(value);
+	}
+}
+function requireNonEmptyString(value, label, qualifier = "") {
+	if (typeof value !== "string" || !value) throw new AgentEventLogError(`Agent event ${label} must be a non-empty string${qualifier}.`);
+}
+/** Validates the complete durable envelope before append/export/replay. */
+function assertAgentLogEntry(entry) {
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new AgentEventLogError("Agent event entry must be an object.");
+	assertJsonSerializable(entry);
+	const candidate = entry;
+	if (candidate.schemaVersion !== 1) throw new AgentEventLogError(`Unsupported agent event schema version '${String(candidate.schemaVersion)}'; expected '1'.`);
+	if (!Number.isInteger(candidate.index) || candidate.index < 0) throw new AgentEventLogError(`Agent event entry.index must be a non-negative integer; got ${String(candidate.index)}.`);
+	for (const field of [
+		"id",
+		"machineId",
+		"machineVersion"
+	]) requireNonEmptyString(candidate[field], `entry.${field}`);
+	if (typeof candidate.recordedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(candidate.recordedAt) || Number.isNaN(Date.parse(candidate.recordedAt))) throw new AgentEventLogError(`Agent event entry.recordedAt is not RFC 3339: '${String(candidate.recordedAt)}'.`);
+	if (candidate.event === null || typeof candidate.event !== "object" || Array.isArray(candidate.event) || typeof candidate.event.type !== "string" || !candidate.event.type) throw new AgentEventLogError("Agent event entry.event requires a non-empty string type.");
+	if (candidate.causationId !== void 0) requireNonEmptyString(candidate.causationId, "entry.causationId", " when present");
+	if (candidate.metadata !== void 0 && (candidate.metadata === null || typeof candidate.metadata !== "object" || Array.isArray(candidate.metadata))) throw new AgentEventLogError("Agent event entry.metadata must be an object when present.");
+	if (candidate.verification !== void 0 && (candidate.verification === null || typeof candidate.verification !== "object" || typeof candidate.verification.stateHash !== "string" || !candidate.verification.stateHash)) throw new AgentEventLogError("Agent event entry.verification requires a non-empty stateHash string.");
+}
+/**
+* Replaces `Error` instances with plain `{ name, message, cause? }` objects so
+* an `xstate.error.actor` payload survives the log's JSON round-trip. Cycles
+* are preserved by identity; non-plain objects are left alone (and are then
+* rejected by {@link assertJsonSerializable}).
+*/
+function normalizeEventErrors(value, seen = /* @__PURE__ */ new WeakMap()) {
+	if (value instanceof Error) {
+		const normalized = {
+			name: value.name,
+			message: value.message
+		};
+		seen.set(value, normalized);
+		if (value.cause !== void 0) normalized.cause = normalizeEventErrors(value.cause, seen);
+		return normalized;
+	}
+	if (value === null || typeof value !== "object") return value;
+	const existing = seen.get(value);
+	if (existing !== void 0) return existing;
+	if (Array.isArray(value)) {
+		const result = [];
+		seen.set(value, result);
+		for (const item of value) result.push(normalizeEventErrors(item, seen));
+		return result;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return value;
+	const result = {};
+	seen.set(value, result);
+	for (const [key, item] of Object.entries(value)) result[key] = normalizeEventErrors(item, seen);
+	return result;
+}
+const SNAPSHOT_VOLATILE_KEYS = new Set([
+	"sessionId",
+	"_nextTimerId",
+	"_nextActorIds"
+]);
+const CHILD_VOLATILE_KEYS = new Set(["sessionId"]);
+function positionOf(parent, key) {
+	if (parent === "snapshot") return key === "children" ? "children" : "data";
+	if (parent === "children") return "child";
+	if (parent === "child") return key === "snapshot" ? "snapshot" : "data";
+	return "data";
+}
+function canonicalizeForHash(value, seen = /* @__PURE__ */ new WeakSet(), position = "snapshot") {
+	if (value === void 0) return "[undefined]";
+	if (typeof value === "function") return "[function]";
+	if (typeof value === "bigint") return `[bigint:${String(value)}]`;
+	if (typeof value === "symbol") return `[symbol:${String(value)}]`;
+	if (value === null || typeof value !== "object") return value;
+	if (value instanceof Date) return `[Date:${value.toISOString()}]`;
+	if (value instanceof Error) {
+		if (seen.has(value)) return "[circular]";
+		seen.add(value);
+		try {
+			return {
+				errorName: value.name,
+				message: value.message,
+				...value.cause !== void 0 ? { cause: canonicalizeForHash(value.cause, seen, "data") } : {}
+			};
+		} finally {
+			seen.delete(value);
+		}
+	}
+	if (seen.has(value)) return "[circular]";
+	seen.add(value);
+	try {
+		if (value instanceof Set) return [...value].map((item) => canonicalizeForHash(item, seen, "data")).sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
+		if (value instanceof Map) return [...value.entries()].map(([key, item]) => [canonicalizeForHash(key, seen, "data"), canonicalizeForHash(item, seen, "data")]).sort(([a], [b]) => stableJson(a).localeCompare(stableJson(b)));
+		if (Array.isArray(value)) return value.map((item) => canonicalizeForHash(item, seen, "data"));
+		const volatileKeys = position === "snapshot" ? SNAPSHOT_VOLATILE_KEYS : position === "child" ? CHILD_VOLATILE_KEYS : void 0;
+		const result = {};
+		for (const key of Object.keys(value).sort()) {
+			if (volatileKeys?.has(key)) continue;
+			const child = value[key];
+			if (child === void 0) continue;
+			result[key] = canonicalizeForHash(child, seen, positionOf(position, key));
+		}
+		return result;
+	} finally {
+		seen.delete(value);
+	}
+}
+/**
+* Key-sorted JSON for comparing two events by content: key insertion order
+* does not count, so an entry read back from storage equals the one that was
+* appended.
+* @internal
+*/
+function canonicalEventJson(event) {
+	return stableJson(canonicalizeForHash(event, /* @__PURE__ */ new Set(), "data"));
+}
+function stableJson(value) {
+	return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+	if (Array.isArray(value)) return value.map(sortJson);
+	if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+	return value;
+}
+/**
+* The canonical hash of a PERSISTED snapshot (`machine.getPersistedSnapshot()`,
+* or {@link replay}'s `persistedSnapshot`) — the value recorded in an entry's
+* `verification.stateHash`.
+*
+* Stripped before hashing, because they are re-minted on every fold and would
+* otherwise make two identical runs hash differently: `sessionId`,
+* `_nextTimerId` and `_nextActorIds` at the snapshot root, `sessionId` on each
+* `children[*]` entry (recursively, through nested child snapshots), and
+* `undefined`-valued properties (so a snapshot hashes the same before and
+* after a JSON round-trip). Stripping is confined to those structural
+* positions: a `sessionId` inside `context`, `output`, `error` or an event
+* payload is application data and is hashed. Object keys are sorted, so key
+* order is irrelevant.
+*
+* A change detector, not a cryptographic digest.
+*/
+function getSnapshotStateHash(snapshot) {
+	return djb2Hex(stableJson(canonicalizeForHash(snapshot)));
+}
+function machineIdOf(machine) {
+	return machine.config.id ?? machine.id ?? "(machine)";
+}
+function toPersisted(machine, snapshot) {
+	return typeof snapshot.matches === "function" ? machine.getPersistedSnapshot(snapshot) : snapshot;
+}
+/**
+* Creates a JSON-safe, self-describing entry for `event` appended after
+* `entries` (which must be the complete prefix, so `index` and the recorded
+* state hash line up).
+*/
+function createReplayEntry(machine, entries, event, options = {}) {
+	const index = entries.length;
+	const machineVersion = options.machineVersion ?? resolveMachineVersion(machine);
+	const entry = {
+		schemaVersion: 1,
+		id: options.id ?? `evt_${String(index).padStart(8, "0")}`,
+		index,
+		recordedAt: options.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		machineId: machineIdOf(machine),
+		machineVersion,
+		event: normalizeEventErrors(event),
+		...options.causationId !== void 0 ? { causationId: options.causationId } : {},
+		...options.metadata !== void 0 ? { metadata: options.metadata } : {}
+	};
+	assertAgentLogEntry(entry);
+	if (options.verification !== false) entry.verification = { stateHash: getSnapshotStateHash(options.snapshot ? toPersisted(machine, options.snapshot) : replay(machine, [...entries, entry], {
+		machineVersion,
+		verify: false
+	}).persistedSnapshot) };
+	return entry;
+}
+function pruneUndefined(value) {
+	if (Array.isArray(value)) return value.map(pruneUndefined);
+	if (value === null || typeof value !== "object") return value;
+	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return value;
+	const result = {};
+	for (const [key, child] of Object.entries(value)) {
+		if (child === void 0) continue;
+		result[key] = pruneUndefined(child);
+	}
+	return result;
+}
+/**
+* The reserved first entry of a log. Pass EXACTLY one of:
+*
+* - `{ input }` — a fresh start; replay folds from `initialTransition`.
+* - `{ snapshot }` — a continuation from a persisted snapshot: a version
+*   bridge, or a legacy snapshot that predates the log. Replay restores it
+*   purely (no actors started) and folds the rest of the log onto it.
+*
+* `options.metadata.executionId` names the lineage; this library always sets
+* one, and readers must tolerate its absence in logs written elsewhere.
+*/
+function initEntry(machine, init = {}, options = {}) {
+	const hasSnapshot = init.snapshot !== void 0;
+	if (hasSnapshot && init.input !== void 0) throw new AgentEventLogError("initEntry accepts exactly one of `input` (fresh start) or `snapshot` (continuation).");
+	return createReplayEntry(machine, [], {
+		type: AGENT_INIT_EVENT_TYPE,
+		...hasSnapshot ? { snapshot: pruneUndefined(init.snapshot) } : init.input !== void 0 ? { input: init.input } : {}
+	}, options);
+}
+/** Whether `entry` is the reserved init entry. */
+function isInitEntry(entry) {
+	return entry?.event?.type === AGENT_INIT_EVENT_TYPE;
+}
+/** Whether `entry` is the version-bridging init-with-snapshot entry. */
+function isSnapshotInitEntry(entry) {
+	return isInitEntry(entry) && entry.event.snapshot !== void 0;
+}
+/**
+* The log's execution id: the lineage identity pinned in the init entry's
+* `metadata.executionId`.
+*
+* Minted once per run and inherited verbatim by every resume of that log, so
+* it names one lineage rather than one process. Entry ids cannot serve this
+* role — the built-in ids are index-derived, so every log's init entry is
+* `evt_00000000`. A fork copies the init entry, so it shares its parent's
+* execution id by construction.
+*
+* Returns `undefined` for a log with no init entry and for one written without
+* the field — callers must treat the id as optional.
+*/
+function getLogExecutionId(entries) {
+	const executionId = (entries.find((entry) => isInitEntry(entry))?.metadata)?.executionId;
+	return typeof executionId === "string" ? executionId : void 0;
+}
+/**
+* Validates a log before replay or append: every envelope well-formed, indices
+* contiguous from 0, ids unique, the first entry the reserved init entry, and
+* one consistent machine identity throughout.
+*
+* With `machine`, entries are also checked against that machine's id and
+* resolved version — a mismatch throws {@link AgentMachineVersionMismatchError}.
+* An init-with-snapshot entry is exempt from the version check: that entry is
+* itself the bridge from whatever version produced the snapshot.
+*/
+function validateReplayEntries(entries, options = {}) {
+	if (entries.length === 0) return;
+	const reference = entries.find((entry) => !isSnapshotInitEntry(entry)) ?? entries[0];
+	const expected = options.machine ? {
+		machineId: machineIdOf(options.machine),
+		machineVersion: options.machineVersion ?? resolveMachineVersion(options.machine)
+	} : {
+		machineId: reference.machineId,
+		machineVersion: options.machineVersion ?? reference.machineVersion
+	};
+	const ids = /* @__PURE__ */ new Set();
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		assertAgentLogEntry(entry);
+		if (entry.index !== index) throw new AgentEventLogError(`Event log must be contiguous from index 0; found entry.index ${entry.index} at position ${index}.`);
+		if (ids.has(entry.id)) throw new AgentEventLogError(`Event log contains duplicate entry id '${entry.id}'.`);
+		ids.add(entry.id);
+		if (index === 0 && !isInitEntry(entry)) throw new AgentEventLogError(`Event log must start with the reserved '${AGENT_INIT_EVENT_TYPE}' entry; found '${entry.event.type}'.`);
+		if (index > 0 && isInitEntry(entry)) throw new AgentEventLogError(`Event log has a second '${AGENT_INIT_EVENT_TYPE}' entry at index ${index}.`);
+		const versionMatches = entry.machineVersion === expected.machineVersion;
+		if (entry.machineId !== expected.machineId || !versionMatches && !isSnapshotInitEntry(entry)) throw new AgentMachineVersionMismatchError(entry.id, entry.index, expected, {
+			machineId: entry.machineId,
+			machineVersion: entry.machineVersion
+		});
+	}
+}
+/**
+* The prefix `[0, upToIndex)` of a log, as a new log. `upToIndex` is exclusive
+* and must leave the init entry in place, so the fork is still self-contained.
+*/
+function forkEventLog(entries, upToIndex) {
+	if (!Number.isInteger(upToIndex) || upToIndex < 1 || upToIndex > entries.length) throw new AgentEventLogError(`forkEventLog: upToIndex must be an integer in [1, ${entries.length}]; got ${String(upToIndex)}.`);
+	const forked = entries.slice(0, upToIndex);
+	if (!isInitEntry(forked[0])) throw new AgentEventLogError(`forkEventLog: the forked prefix must start with the reserved '${AGENT_INIT_EVENT_TYPE}' entry.`);
+	return forked;
+}
+const DONE_ACTOR_EVENT_TYPE = "xstate.done.actor";
+const ERROR_ACTOR_EVENT_TYPE = "xstate.error.actor";
+/** Normalizes a mixed `EventObject | AgentLogEntry` history into bare events. */
+function toEvents(history) {
+	if (!history) return [];
+	return history.map((item) => {
+		const candidate = item;
+		return candidate?.schemaVersion === 1 && typeof candidate.index === "number" && candidate.event !== null && typeof candidate.event === "object" ? candidate.event : item;
+	});
+}
+/**
+* The 1-based occurrence `n` for the NEXT call at invoke site `siteId`:
+* `1 + completions`, where a completion is a journaled `xstate.done.actor` OR
+* `xstate.error.actor` for that `actorId` (an error is a semantic completion).
+* The one counting rule behind every `${siteId}#${n}` call key, so a live run
+* and a replay derive the same `n` by construction.
+*/
+function agentCallOccurrence(history, siteId) {
+	let count = 0;
+	for (const event of toEvents(history)) if ((event.type === DONE_ACTOR_EVENT_TYPE || event.type === ERROR_ACTOR_EVENT_TYPE) && event.actorId === siteId) count++;
+	return count + 1;
+}
+/**
+* Folds the reserved `@agent.usage` entries of a log into one cumulative usage
+* total. The log is the source of truth, so the totals are a pure projection of
+* it: replay a log, fold it, and you get the numbers the run reported with no
+* host-side accumulator in between.
+*
+* Accepts entries or bare events. Token fields are partial sums: a field stays
+* `undefined` until some entry reports it, and non-finite values are ignored.
+*/
+function getUsageFromEvents(entries) {
+	const totals = {};
+	for (const event of toEvents(entries)) {
+		if (event.type !== "@agent.usage") continue;
+		const usage = event.usage;
+		if (!usage || typeof usage !== "object") continue;
+		for (const field of AGENT_USAGE_TOKEN_FIELDS) {
+			const value = usage[field];
+			if (typeof value === "number" && Number.isFinite(value)) totals[field] = (totals[field] ?? 0) + value;
+		}
+	}
+	return totals;
+}
+/**
+* Rewrites a journaled `xstate.done.actor`/`xstate.error.actor` event's
+* `sessionId` to the session the CURRENT fold minted for that `actorId`.
+*
+* Session ids are re-minted on every fold, and XState drops a completion event
+* whose `sessionId` does not match the live child — silently, as a no-op
+* transition. Rebinding is what makes a journaled completion replayable at all.
+* `sessions` caches the mapping per fold, so a later event referring to the
+* recorded session of an already-stopped child still resolves.
+*/
+function rebindActorSession(event, snapshot, sessions) {
+	const actorEvent = event;
+	if (typeof actorEvent.actorId !== "string" || typeof actorEvent.sessionId !== "string") return event;
+	const key = `${actorEvent.actorId}\0${actorEvent.sessionId}`;
+	let sessionId = sessions.get(key);
+	if (!sessionId) {
+		const child = snapshot.children[actorEvent.actorId];
+		if (typeof child?.sessionId !== "string") return event;
+		sessionId = child.sessionId;
+		sessions.set(key, sessionId);
+	}
+	return {
+		...event,
+		sessionId
+	};
+}
+function verifyEntry(entry, persisted, mode) {
+	if (mode === false) return;
+	if (!entry.verification) {
+		if (mode === "strict") throw new AgentReplayDivergenceError(entry.id, entry.index, "missing-verification");
+		return;
+	}
+	const actual = getSnapshotStateHash(persisted);
+	if (actual !== entry.verification.stateHash) throw new AgentReplayDivergenceError(entry.id, entry.index, "state", entry.verification.stateHash, actual);
+}
+/**
+* Folds a log through XState's pure `initialTransition`/`transition` WITHOUT
+* executing anything: no actor is started, no action runs, no model is called.
+* A journaled `xstate.done.actor` entry carries the completed actor's output
+* inline, so the invoke it belongs to is never re-run. Crash recovery, fork
+* resume, and time travel in one call.
+*
+* The first entry is the reserved {@link initEntry}: `input` folds from
+* `initialTransition`, `snapshot` restores the persisted snapshot purely
+* (`machine.restoreSnapshot`) and folds the rest of the log onto it.
+*/
+function replay(machine, entries, options = {}) {
+	validateReplayEntries(entries, {
+		machine,
+		machineVersion: options.machineVersion ?? resolveMachineVersion(machine)
+	});
+	if (entries.length === 0) throw new AgentEventLogError(`Cannot replay an empty event log; it must start with a '${AGENT_INIT_EVENT_TYPE}' entry.`);
+	const initEvent = entries[0].event;
+	let snapshot = initEvent.snapshot !== void 0 ? machine.restoreSnapshot(initEvent.snapshot) : initialTransition(machine, initEvent.input)[0];
+	let persisted = machine.getPersistedSnapshot(snapshot);
+	verifyEntry(entries[0], persisted, options.verify);
+	const sessions = /* @__PURE__ */ new Map();
+	for (let index = 1; index < entries.length; index++) {
+		const entry = entries[index];
+		const event = rebindActorSession(entry.event, snapshot, sessions);
+		[snapshot] = transition(machine, snapshot, event);
+		persisted = machine.getPersistedSnapshot(snapshot);
+		verifyEntry(entry, persisted, options.verify);
+	}
+	return {
+		snapshot,
+		persistedSnapshot: persisted
+	};
+}
+//#endregion
+//#region src/event-log-store.ts
+/**
+* Durable storage for {@link AgentLogEntry} logs: the one interface a host
+* implements, plus the in-memory reference implementation the conformance
+* suite is written against.
+* @module
+*/
+/**
+* Rejection from {@link AgentEventLogStore.append} when the thread's stored
+* length is not the `expectedIndex` the writer held — a concurrent writer
+* appended first. `actualIndex` is the next index the store would accept.
+*/
+var AgentEventLogConflictError = class extends AgentError {
+	threadId;
+	expectedIndex;
+	actualIndex;
+	constructor(threadId, expectedIndex, actualIndex) {
+		super("event-log-conflict", `AgentEventLogStore.append: index conflict on thread "${threadId}": expected index ${expectedIndex} but found ${actualIndex} — a concurrent writer won.`);
+		this.name = "AgentEventLogConflictError";
+		this.threadId = threadId;
+		this.expectedIndex = expectedIndex;
+		this.actualIndex = actualIndex;
+	}
+};
+/**
+* In-memory reference store, and the baseline the conformance suite runs
+* against. Per-thread entries are held in a contiguous, index-ordered list;
+* append's check-and-push runs synchronously (no `await` between reading the
+* length and writing), so two appends racing on the same `expectedIndex`
+* resolve to exactly one winner. Every stored and returned entry is
+* `structuredClone`d, so a caller can neither mutate stored state through a
+* value it appended nor through a value it read.
+*/
+function createInMemoryEventLogStore() {
+	const threads = /* @__PURE__ */ new Map();
+	const clone = (value) => structuredClone(value);
+	return {
+		async append({ threadId, expectedIndex, entries }) {
+			for (const entry of entries) assertAgentLogEntry(entry);
+			for (let i = 0; i < entries.length; i++) if (entries[i].index !== expectedIndex + i) throw new Error(`AgentEventLogStore.append: entry.index (${entries[i].index}) must be contiguous from expectedIndex (${expectedIndex}); expected ${expectedIndex + i} at position ${i} on thread "${threadId}".`);
+			const list = threads.get(threadId);
+			const length = list ? list.length : 0;
+			if (length !== expectedIndex) throw new AgentEventLogConflictError(threadId, expectedIndex, length);
+			const ids = new Set((list ?? []).map((entry) => entry.id));
+			for (const entry of entries) {
+				if (ids.has(entry.id)) throw new Error(`AgentEventLogStore.append: duplicate event id "${entry.id}" in thread "${threadId}".`);
+				ids.add(entry.id);
+			}
+			const cloned = entries.map((entry) => clone(entry));
+			if (list) for (const entry of cloned) list.push(entry);
+			else threads.set(threadId, cloned);
+		},
+		async read(threadId, options) {
+			const list = threads.get(threadId) ?? [];
+			const from = options?.from ?? 0;
+			return list.slice(from).map((entry) => clone(entry));
+		},
+		async length(threadId) {
+			return threads.get(threadId)?.length ?? 0;
+		},
+		async fork({ threadId, newThreadId, upToIndex }) {
+			if ((threads.get(newThreadId)?.length ?? 0) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
+			const source = threads.get(threadId);
+			if (!source) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
+			const upTo = upToIndex ?? source.length;
+			if (!Number.isInteger(upTo) || upTo < 1 || upTo > source.length) throw new Error(`AgentEventLogStore.fork: upToIndex must be an integer in [1, ${source.length}] on thread "${threadId}"; got ${String(upTo)}.`);
+			threads.set(newThreadId, source.slice(0, upTo).map((entry) => clone(entry)));
+		}
+	};
+}
+//#endregion
+export { getUsageFromEvents as _, AgentEventLogError as a, replay as b, NonSerializableAgentEventError as c, assertJsonSerializable as d, canonicalEventJson as f, getSnapshotStateHash as g, getLogExecutionId as h, AGENT_INIT_EVENT_TYPE as i, agentCallOccurrence as l, forkEventLog as m, createInMemoryEventLogStore as n, AgentMachineVersionMismatchError as o, createReplayEntry as p, AGENT_EVENT_SCHEMA_VERSION as r, AgentReplayDivergenceError as s, AgentEventLogConflictError as t, assertAgentLogEntry as u, initEntry as v, validateReplayEntries as x, rebindActorSession as y };