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

package/dist/event-log-store-DvOcs10J.d.cts

@@ -0,0 +1,338 @@
+import { Z as AgentError, t as AgentCallUsage } from "./text-logic-BFEOxyxv.cjs";
+import { AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
+
+//#region src/event-log.d.ts
+/** The durable entry envelope version. */
+declare 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`.
+ */
+declare const AGENT_INIT_EVENT_TYPE: "@agent.init";
+/** Values that round-trip through JSON without adapters or silent coercion. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** A persisted (JSON-safe) machine snapshot, as `machine.getPersistedSnapshot()` returns. */
+type AgentPersistedSnapshot = Snapshot<unknown>;
+/** Recorded projection hash used by {@link replay} verification. */
+interface AgentLogVerification {
+  /** {@link getSnapshotStateHash} of the persisted snapshot after this entry is applied. */
+  stateHash: string;
+}
+/**
+ * One journaled external input, JSON-safe and stored verbatim.
+ */
+interface AgentLogEntry {
+  /** Version of this outer envelope, independent of the machine event type. */
+  schemaVersion: typeof AGENT_EVENT_SCHEMA_VERSION;
+  /** Stable identity within the log. Forked prefixes retain their ids. */
+  id: string;
+  /** 0-based position in the log. */
+  index: number;
+  /** RFC 3339 wall-clock time when the host accepted the entry. Metadata only. */
+  recordedAt: string;
+  /** The authored XState machine id. */
+  machineId: string;
+  /** Explicit version or structural hash of the machine that accepted the event. */
+  machineVersion: string;
+  event: EventObject;
+  /** Optional causal parent entry id, scoped to the same log. */
+  causationId?: string;
+  /** Host-owned, JSON-safe; stored verbatim, never interpreted. */
+  metadata?: Record<string, JsonValue>;
+  /** Recorded projection hash used by replay verification. */
+  verification?: AgentLogVerification;
+}
+/** The payload of the reserved {@link AGENT_INIT_EVENT_TYPE} first entry. */
+interface AgentInitEvent extends EventObject {
+  type: typeof AGENT_INIT_EVENT_TYPE;
+  /** Machine input for a fresh start. Mutually exclusive with `snapshot`. */
+  input?: unknown;
+  /** Persisted snapshot to continue from. Mutually exclusive with `input`. */
+  snapshot?: AgentPersistedSnapshot;
+}
+/** A malformed or internally inconsistent log. */
+declare class AgentEventLogError extends AgentError {
+  constructor(message: string);
+}
+/** A precise failure when an entry would not survive a JSON round-trip. */
+declare class NonSerializableAgentEventError extends AgentError {
+  readonly path: string;
+  readonly valueType: string;
+  constructor(path: string, valueType: string);
+}
+/** Replay reached a state that does not match the entry's recorded hash. */
+declare class AgentReplayDivergenceError extends AgentError {
+  readonly eventId: string;
+  readonly index: number;
+  readonly kind: "state" | "missing-verification";
+  readonly expected?: string | undefined;
+  readonly actual?: string | undefined;
+  constructor(eventId: string, index: number, kind: "state" | "missing-verification", expected?: string | undefined, actual?: string | undefined);
+}
+/**
+ * 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.
+ */
+declare class AgentMachineVersionMismatchError extends AgentError {
+  readonly eventId: string;
+  readonly index: number;
+  readonly expected: {
+    machineId: string;
+    machineVersion: string;
+  };
+  readonly actual: {
+    machineId: string;
+    machineVersion: string;
+  };
+  constructor(eventId: string, index: number, expected: {
+    machineId: string;
+    machineVersion: string;
+  }, actual: {
+    machineId: string;
+    machineVersion: string;
+  });
+}
+/**
+ * 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.
+ */
+declare function assertJsonSerializable(value: unknown, path?: string, ancestors?: WeakSet<object>): asserts value is JsonValue;
+/** Validates the complete durable envelope before append/export/replay. */
+declare function assertAgentLogEntry(entry: unknown): asserts entry is AgentLogEntry;
+/**
+ * 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.
+ */
+declare function getSnapshotStateHash(snapshot: AgentPersistedSnapshot | unknown): string;
+/** Options controlling the durable envelope created by {@link createReplayEntry}. */
+interface CreateReplayEntryOptions {
+  /** Explicit machine version; defaults to the machine's resolved version. */
+  machineVersion?: string;
+  /** Stable entry id; defaults to `evt_` plus the zero-padded index. */
+  id?: string;
+  /** RFC 3339 acceptance time; defaults to the current wall clock. */
+  recordedAt?: string;
+  causationId?: string;
+  metadata?: Record<string, JsonValue>;
+  /** Record `verification.stateHash` (default `true`). */
+  verification?: boolean;
+  /**
+   * The snapshot this entry folds to, when the caller already has it — avoids
+   * re-folding the whole prefix just to compute the hash. Accepts a live or a
+   * persisted snapshot.
+   */
+  snapshot?: AnyMachineSnapshot | AgentPersistedSnapshot;
+}
+/**
+ * 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).
+ */
+declare function createReplayEntry(machine: AnyStateMachine, entries: readonly AgentLogEntry[], event: EventObject, options?: CreateReplayEntryOptions): AgentLogEntry;
+/** How a log begins: from machine input, or from a persisted snapshot. */
+type AgentLogInit = {
+  input?: unknown;
+  snapshot?: never;
+} | {
+  snapshot: AgentPersistedSnapshot;
+  input?: never;
+};
+/**
+ * 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.
+ */
+declare function initEntry(machine: AnyStateMachine, init?: AgentLogInit, options?: CreateReplayEntryOptions): AgentLogEntry;
+/**
+ * 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.
+ */
+declare function getLogExecutionId(entries: readonly AgentLogEntry[]): string | undefined;
+/**
+ * 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.
+ */
+declare function validateReplayEntries(entries: readonly AgentLogEntry[], options?: {
+  machine?: AnyStateMachine;
+  machineVersion?: string;
+}): void;
+/**
+ * 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.
+ */
+declare function forkEventLog(entries: readonly AgentLogEntry[], upToIndex: number): AgentLogEntry[];
+/**
+ * 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.
+ */
+declare function agentCallOccurrence(history: readonly (EventObject | AgentLogEntry)[] | undefined, siteId: string): number;
+/**
+ * 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.
+ */
+declare function getUsageFromEvents(entries: readonly (EventObject | AgentLogEntry)[]): AgentCallUsage;
+/**
+ * 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.
+ */
+declare function rebindActorSession(event: EventObject, snapshot: AnyMachineSnapshot, sessions: Map<string, string>): EventObject;
+/** Options for {@link replay}. */
+interface ReplayOptions {
+  /** Explicit expected machine version; defaults to the machine's resolved version. */
+  machineVersion?: string;
+  /**
+   * `true` (default) checks the entries that carry a `verification.stateHash`;
+   * `'strict'` additionally requires every entry to carry one; `false` skips
+   * verification entirely.
+   */
+  verify?: boolean | "strict";
+}
+/** The result of a {@link replay}. */
+interface ReplayResult<TMachine extends AnyStateMachine> {
+  /** The folded live snapshot (no actors started, no effects run). */
+  snapshot: SnapshotFrom<TMachine>;
+  /** Its persisted projection — what a host stores, and what hashes. */
+  persistedSnapshot: AgentPersistedSnapshot;
+}
+/**
+ * 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.
+ */
+declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
+//#endregion
+//#region src/event-log-store.d.ts
+/**
+ * An append-only event log: the authoritative durability artifact of a thread.
+ * The journal of external inputs IS the source of truth — deterministic
+ * `replay` derives every snapshot from it, and a fork is a copied log prefix.
+ *
+ * Userland stores (a Postgres table with a `(thread_id, index)` primary key, an
+ * append-only object in blob storage, …) implement this one shape so they
+ * interoperate; {@link createInMemoryEventLogStore} is the reference, and
+ * `assertEventLogStoreConformance` checks an implementation against it.
+ */
+interface AgentEventLogStore {
+  /**
+   * Append `entries` starting at `expectedIndex` (the current length of the
+   * thread's log; 0 for a new thread). Atomic — all entries land or none do.
+   * Rejects with {@link AgentEventLogConflictError} when the thread's length
+   * differs from `expectedIndex`: a concurrent writer appended first. Each
+   * entry's `index` must be contiguous from `expectedIndex` (a plain `Error`
+   * otherwise: that is caller misuse, not a race).
+   */
+  append(input: {
+    threadId: string;
+    expectedIndex: number;
+    entries: AgentLogEntry[];
+  }): Promise<void>;
+  /**
+   * Read a thread's entries in log order. `from` (default 0) skips entries
+   * below that index for incremental catch-up. An unknown thread reads as an
+   * empty array.
+   */
+  read(threadId: string, options?: {
+    from?: number;
+  }): Promise<AgentLogEntry[]>;
+  /** The thread's current log length (0 for an unknown thread) — the next `expectedIndex`. */
+  length(threadId: string): Promise<number>;
+  /**
+   * Copy the prefix `[0, upToIndex)` onto a fresh, empty `newThreadId`.
+   * Without `upToIndex` the full source is copied. `upToIndex` is exclusive
+   * and must be an integer in `[1, length]`, so the fork keeps the reserved
+   * init entry and stays a self-contained log. The fork then appends
+   * independently. Rejects (plain `Error`) if `newThreadId` already has
+   * entries, the source is unknown, or `upToIndex` is out of range.
+   * Implementations may copy-on-write or physically copy; observable behavior
+   * must match a full copy.
+   */
+  fork(input: {
+    threadId: string;
+    newThreadId: string; /** Exclusive index cutoff. */
+    upToIndex?: number;
+  }): Promise<void>;
+}
+/**
+ * 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.
+ */
+declare class AgentEventLogConflictError extends AgentError {
+  readonly threadId: string;
+  readonly expectedIndex: number;
+  readonly actualIndex: number;
+  constructor(threadId: string, expectedIndex: number, actualIndex: number);
+}
+/**
+ * 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.
+ */
+declare function createInMemoryEventLogStore(): AgentEventLogStore;
+//#endregion
+export { validateReplayEntries as A, forkEventLog as C, initEntry as D, getUsageFromEvents as E, rebindActorSession as O, createReplayEntry as S, getSnapshotStateHash as T, ReplayOptions as _, AGENT_INIT_EVENT_TYPE as a, assertAgentLogEntry as b, AgentLogEntry as c, AgentMachineVersionMismatchError as d, AgentPersistedSnapshot as f, NonSerializableAgentEventError as g, JsonValue as h, AGENT_EVENT_SCHEMA_VERSION as i, replay as k, AgentLogInit as l, CreateReplayEntryOptions as m, AgentEventLogStore as n, AgentEventLogError as o, AgentReplayDivergenceError as p, createInMemoryEventLogStore as r, AgentInitEvent as s, AgentEventLogConflictError as t, AgentLogVerification as u, ReplayResult as v, getLogExecutionId as w, assertJsonSerializable as x, agentCallOccurrence as y };

package/dist/event-log-store-DxyVgnas.d.mts

@@ -0,0 +1,338 @@
+import { Z as AgentError, t as AgentCallUsage } from "./text-logic-hZSiRUo1.mjs";
+import { AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
+
+//#region src/event-log.d.ts
+/** The durable entry envelope version. */
+declare 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`.
+ */
+declare const AGENT_INIT_EVENT_TYPE: "@agent.init";
+/** Values that round-trip through JSON without adapters or silent coercion. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** A persisted (JSON-safe) machine snapshot, as `machine.getPersistedSnapshot()` returns. */
+type AgentPersistedSnapshot = Snapshot<unknown>;
+/** Recorded projection hash used by {@link replay} verification. */
+interface AgentLogVerification {
+  /** {@link getSnapshotStateHash} of the persisted snapshot after this entry is applied. */
+  stateHash: string;
+}
+/**
+ * One journaled external input, JSON-safe and stored verbatim.
+ */
+interface AgentLogEntry {
+  /** Version of this outer envelope, independent of the machine event type. */
+  schemaVersion: typeof AGENT_EVENT_SCHEMA_VERSION;
+  /** Stable identity within the log. Forked prefixes retain their ids. */
+  id: string;
+  /** 0-based position in the log. */
+  index: number;
+  /** RFC 3339 wall-clock time when the host accepted the entry. Metadata only. */
+  recordedAt: string;
+  /** The authored XState machine id. */
+  machineId: string;
+  /** Explicit version or structural hash of the machine that accepted the event. */
+  machineVersion: string;
+  event: EventObject;
+  /** Optional causal parent entry id, scoped to the same log. */
+  causationId?: string;
+  /** Host-owned, JSON-safe; stored verbatim, never interpreted. */
+  metadata?: Record<string, JsonValue>;
+  /** Recorded projection hash used by replay verification. */
+  verification?: AgentLogVerification;
+}
+/** The payload of the reserved {@link AGENT_INIT_EVENT_TYPE} first entry. */
+interface AgentInitEvent extends EventObject {
+  type: typeof AGENT_INIT_EVENT_TYPE;
+  /** Machine input for a fresh start. Mutually exclusive with `snapshot`. */
+  input?: unknown;
+  /** Persisted snapshot to continue from. Mutually exclusive with `input`. */
+  snapshot?: AgentPersistedSnapshot;
+}
+/** A malformed or internally inconsistent log. */
+declare class AgentEventLogError extends AgentError {
+  constructor(message: string);
+}
+/** A precise failure when an entry would not survive a JSON round-trip. */
+declare class NonSerializableAgentEventError extends AgentError {
+  readonly path: string;
+  readonly valueType: string;
+  constructor(path: string, valueType: string);
+}
+/** Replay reached a state that does not match the entry's recorded hash. */
+declare class AgentReplayDivergenceError extends AgentError {
+  readonly eventId: string;
+  readonly index: number;
+  readonly kind: "state" | "missing-verification";
+  readonly expected?: string | undefined;
+  readonly actual?: string | undefined;
+  constructor(eventId: string, index: number, kind: "state" | "missing-verification", expected?: string | undefined, actual?: string | undefined);
+}
+/**
+ * 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.
+ */
+declare class AgentMachineVersionMismatchError extends AgentError {
+  readonly eventId: string;
+  readonly index: number;
+  readonly expected: {
+    machineId: string;
+    machineVersion: string;
+  };
+  readonly actual: {
+    machineId: string;
+    machineVersion: string;
+  };
+  constructor(eventId: string, index: number, expected: {
+    machineId: string;
+    machineVersion: string;
+  }, actual: {
+    machineId: string;
+    machineVersion: string;
+  });
+}
+/**
+ * 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.
+ */
+declare function assertJsonSerializable(value: unknown, path?: string, ancestors?: WeakSet<object>): asserts value is JsonValue;
+/** Validates the complete durable envelope before append/export/replay. */
+declare function assertAgentLogEntry(entry: unknown): asserts entry is AgentLogEntry;
+/**
+ * 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.
+ */
+declare function getSnapshotStateHash(snapshot: AgentPersistedSnapshot | unknown): string;
+/** Options controlling the durable envelope created by {@link createReplayEntry}. */
+interface CreateReplayEntryOptions {
+  /** Explicit machine version; defaults to the machine's resolved version. */
+  machineVersion?: string;
+  /** Stable entry id; defaults to `evt_` plus the zero-padded index. */
+  id?: string;
+  /** RFC 3339 acceptance time; defaults to the current wall clock. */
+  recordedAt?: string;
+  causationId?: string;
+  metadata?: Record<string, JsonValue>;
+  /** Record `verification.stateHash` (default `true`). */
+  verification?: boolean;
+  /**
+   * The snapshot this entry folds to, when the caller already has it — avoids
+   * re-folding the whole prefix just to compute the hash. Accepts a live or a
+   * persisted snapshot.
+   */
+  snapshot?: AnyMachineSnapshot | AgentPersistedSnapshot;
+}
+/**
+ * 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).
+ */
+declare function createReplayEntry(machine: AnyStateMachine, entries: readonly AgentLogEntry[], event: EventObject, options?: CreateReplayEntryOptions): AgentLogEntry;
+/** How a log begins: from machine input, or from a persisted snapshot. */
+type AgentLogInit = {
+  input?: unknown;
+  snapshot?: never;
+} | {
+  snapshot: AgentPersistedSnapshot;
+  input?: never;
+};
+/**
+ * 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.
+ */
+declare function initEntry(machine: AnyStateMachine, init?: AgentLogInit, options?: CreateReplayEntryOptions): AgentLogEntry;
+/**
+ * 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.
+ */
+declare function getLogExecutionId(entries: readonly AgentLogEntry[]): string | undefined;
+/**
+ * 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.
+ */
+declare function validateReplayEntries(entries: readonly AgentLogEntry[], options?: {
+  machine?: AnyStateMachine;
+  machineVersion?: string;
+}): void;
+/**
+ * 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.
+ */
+declare function forkEventLog(entries: readonly AgentLogEntry[], upToIndex: number): AgentLogEntry[];
+/**
+ * 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.
+ */
+declare function agentCallOccurrence(history: readonly (EventObject | AgentLogEntry)[] | undefined, siteId: string): number;
+/**
+ * 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.
+ */
+declare function getUsageFromEvents(entries: readonly (EventObject | AgentLogEntry)[]): AgentCallUsage;
+/**
+ * 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.
+ */
+declare function rebindActorSession(event: EventObject, snapshot: AnyMachineSnapshot, sessions: Map<string, string>): EventObject;
+/** Options for {@link replay}. */
+interface ReplayOptions {
+  /** Explicit expected machine version; defaults to the machine's resolved version. */
+  machineVersion?: string;
+  /**
+   * `true` (default) checks the entries that carry a `verification.stateHash`;
+   * `'strict'` additionally requires every entry to carry one; `false` skips
+   * verification entirely.
+   */
+  verify?: boolean | "strict";
+}
+/** The result of a {@link replay}. */
+interface ReplayResult<TMachine extends AnyStateMachine> {
+  /** The folded live snapshot (no actors started, no effects run). */
+  snapshot: SnapshotFrom<TMachine>;
+  /** Its persisted projection — what a host stores, and what hashes. */
+  persistedSnapshot: AgentPersistedSnapshot;
+}
+/**
+ * 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.
+ */
+declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
+//#endregion
+//#region src/event-log-store.d.ts
+/**
+ * An append-only event log: the authoritative durability artifact of a thread.
+ * The journal of external inputs IS the source of truth — deterministic
+ * `replay` derives every snapshot from it, and a fork is a copied log prefix.
+ *
+ * Userland stores (a Postgres table with a `(thread_id, index)` primary key, an
+ * append-only object in blob storage, …) implement this one shape so they
+ * interoperate; {@link createInMemoryEventLogStore} is the reference, and
+ * `assertEventLogStoreConformance` checks an implementation against it.
+ */
+interface AgentEventLogStore {
+  /**
+   * Append `entries` starting at `expectedIndex` (the current length of the
+   * thread's log; 0 for a new thread). Atomic — all entries land or none do.
+   * Rejects with {@link AgentEventLogConflictError} when the thread's length
+   * differs from `expectedIndex`: a concurrent writer appended first. Each
+   * entry's `index` must be contiguous from `expectedIndex` (a plain `Error`
+   * otherwise: that is caller misuse, not a race).
+   */
+  append(input: {
+    threadId: string;
+    expectedIndex: number;
+    entries: AgentLogEntry[];
+  }): Promise<void>;
+  /**
+   * Read a thread's entries in log order. `from` (default 0) skips entries
+   * below that index for incremental catch-up. An unknown thread reads as an
+   * empty array.
+   */
+  read(threadId: string, options?: {
+    from?: number;
+  }): Promise<AgentLogEntry[]>;
+  /** The thread's current log length (0 for an unknown thread) — the next `expectedIndex`. */
+  length(threadId: string): Promise<number>;
+  /**
+   * Copy the prefix `[0, upToIndex)` onto a fresh, empty `newThreadId`.
+   * Without `upToIndex` the full source is copied. `upToIndex` is exclusive
+   * and must be an integer in `[1, length]`, so the fork keeps the reserved
+   * init entry and stays a self-contained log. The fork then appends
+   * independently. Rejects (plain `Error`) if `newThreadId` already has
+   * entries, the source is unknown, or `upToIndex` is out of range.
+   * Implementations may copy-on-write or physically copy; observable behavior
+   * must match a full copy.
+   */
+  fork(input: {
+    threadId: string;
+    newThreadId: string; /** Exclusive index cutoff. */
+    upToIndex?: number;
+  }): Promise<void>;
+}
+/**
+ * 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.
+ */
+declare class AgentEventLogConflictError extends AgentError {
+  readonly threadId: string;
+  readonly expectedIndex: number;
+  readonly actualIndex: number;
+  constructor(threadId: string, expectedIndex: number, actualIndex: number);
+}
+/**
+ * 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.
+ */
+declare function createInMemoryEventLogStore(): AgentEventLogStore;
+//#endregion
+export { validateReplayEntries as A, forkEventLog as C, initEntry as D, getUsageFromEvents as E, rebindActorSession as O, createReplayEntry as S, getSnapshotStateHash as T, ReplayOptions as _, AGENT_INIT_EVENT_TYPE as a, assertAgentLogEntry as b, AgentLogEntry as c, AgentMachineVersionMismatchError as d, AgentPersistedSnapshot as f, NonSerializableAgentEventError as g, JsonValue as h, AGENT_EVENT_SCHEMA_VERSION as i, replay as k, AgentLogInit as l, CreateReplayEntryOptions as m, AgentEventLogStore as n, AgentEventLogError as o, AgentReplayDivergenceError as p, createInMemoryEventLogStore as r, AgentInitEvent as s, AgentEventLogConflictError as t, AgentLogVerification as u, ReplayResult as v, getLogExecutionId as w, assertJsonSerializable as x, agentCallOccurrence as y };