@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13

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

@@ -0,0 +1,411 @@
+import { t as AgentError } from "./errors-CeSXQx0v.mjs";
+//#region src/event-log-store.ts
+/** The durable replay-entry envelope version. */
+const AGENT_EVENT_SCHEMA_VERSION = 1;
+/** 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;
+	}
+};
+/**
+* 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);
+	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) => !/^(?:0|[1-9]\d*)$/.test(key) || Number(key) >= value.length);
+		if (extraKey !== void 0) throw new NonSerializableAgentEventError(`${path}.${extraKey}`, "array property");
+		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) => key !== "length" && !/^(?:0|[1-9]\d*)$/.test(key) && !Object.getOwnPropertyDescriptor(value, key)?.enumerable);
+		if (hiddenKey !== void 0) throw new NonSerializableAgentEventError(`${path}.${hiddenKey}`, "non-enumerable property");
+		ancestors.delete(value);
+		return;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) {
+		const type = value.constructor?.name ?? "object";
+		ancestors.delete(value);
+		throw new NonSerializableAgentEventError(path, type);
+	}
+	const symbols = Object.getOwnPropertySymbols(value);
+	if (symbols.length > 0) {
+		ancestors.delete(value);
+		throw new NonSerializableAgentEventError(`${path}.[${String(symbols[0])}]`, "symbol key");
+	}
+	const hiddenKey = Object.getOwnPropertyNames(value).find((key) => !Object.getOwnPropertyDescriptor(value, key)?.enumerable);
+	if (hiddenKey !== void 0) {
+		ancestors.delete(value);
+		throw new NonSerializableAgentEventError(`${path}.${hiddenKey}`, "non-enumerable property");
+	}
+	for (const [key, child] of Object.entries(value)) assertJsonSerializable(child, `${path}.${key}`, ancestors);
+	ancestors.delete(value);
+}
+/** Validates the complete durable envelope before append/export/replay. */
+function assertAgentLogEntry(entry) {
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new Error("Agent event entry must be an object.");
+	assertJsonSerializable(entry);
+	const candidate = entry;
+	if (candidate.schemaVersion !== 1) throw new Error(`Unsupported agent event schema version '${String(candidate.schemaVersion)}'; expected '1'.`);
+	if (!Number.isInteger(candidate.index) || candidate.index < 0) throw new Error(`Agent event entry.index must be a non-negative integer; got ${String(candidate.index)}.`);
+	if (typeof candidate.id !== "string" || !candidate.id || typeof candidate.machineId !== "string" || !candidate.machineId || typeof candidate.machineVersion !== "string" || !candidate.machineVersion) throw new Error("Agent event entry requires non-empty id, machineId, and machineVersion.");
+	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 Error(`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 Error("Agent event entry.event requires a non-empty string type.");
+	if (candidate.causationId !== void 0 && (typeof candidate.causationId !== "string" || !candidate.causationId)) throw new Error("Agent event entry.causationId must be a non-empty string when present.");
+	if (candidate.correlationId !== void 0 && (typeof candidate.correlationId !== "string" || !candidate.correlationId)) throw new Error("Agent event entry.correlationId must be a non-empty string when present.");
+	if (candidate.metadata !== void 0 && (candidate.metadata === null || typeof candidate.metadata !== "object" || Array.isArray(candidate.metadata))) throw new Error("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 || typeof candidate.verification.effectsHash !== "string" || !candidate.verification.effectsHash)) throw new Error("Agent event entry.verification requires non-empty stateHash and effectsHash strings.");
+}
+/**
+* Rejection from {@link AgentEventLogStore.append} when the thread's stored
+* length is not the `expectedIndex` the writer held — a concurrent writer
+* appended first. `actualLength` is the length core found.
+*/
+var AgentEventLogConflictError = class extends AgentError {
+	threadId;
+	expectedIndex;
+	actualLength;
+	constructor(threadId, expectedIndex, actualLength) {
+		super("event-log-conflict", `AgentEventLogStore.append: length conflict on thread "${threadId}": expected length ${expectedIndex} but found ${actualLength} — a concurrent writer won.`);
+		this.name = "AgentEventLogConflictError";
+		this.threadId = threadId;
+		this.expectedIndex = expectedIndex;
+		this.actualLength = actualLength;
+	}
+};
+/**
+* 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, atEventId }) {
+			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}".`);
+			if (upToIndex !== void 0 && atEventId !== void 0) throw new Error("AgentEventLogStore.fork: pass either upToIndex or atEventId, not both.");
+			const eventIndex = atEventId === void 0 ? void 0 : source.findIndex((entry) => entry.id === atEventId);
+			if (atEventId !== void 0 && eventIndex === -1) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" has no event id "${atEventId}".`);
+			const upTo = eventIndex === void 0 ? upToIndex ?? source.length : eventIndex + 1;
+			if (upTo < 0 || upTo > source.length) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" (length ${source.length}) has no index ${upTo} to fork up to.`);
+			threads.set(newThreadId, source.slice(0, upTo).map((entry) => clone(entry)));
+		}
+	};
+}
+function fail(message) {
+	throw new Error(`event-log-store conformance: ${message}`);
+}
+function entry(index, type, metadata) {
+	return {
+		schemaVersion: 1,
+		id: `evt_${index}`,
+		index,
+		recordedAt: "2026-01-01T00:00:00.000Z",
+		machineId: "conformance",
+		machineVersion: "v1",
+		event: {
+			type,
+			seq: index
+		},
+		...metadata !== void 0 ? { metadata } : {}
+	};
+}
+function entriesFrom(start, count) {
+	return Array.from({ length: count }, (_unused, i) => entry(start + i, `e${start + i}`));
+}
+function assertJsonEqual(actual, expected, message) {
+	const a = JSON.stringify(actual);
+	const b = JSON.stringify(expected);
+	if (a !== b) fail(`${message} (expected ${b}, got ${a})`);
+}
+/**
+* Validates a store against the reference's semantics: empty read + zero length
+* for unknown threads; single and multi-entry append; contiguity misuse guard;
+* stale-`expectedIndex` conflict with correct fields; an interleaved concurrent
+* append race (exactly one winner); event-id uniqueness; `read({ from })`
+* incremental correctness; thread isolation; metadata round-trip; deep-copy
+* isolation on append and read; and the full fork contract.
+*/
+async function assertEventLogStoreConformance(create) {
+	{
+		const store = await create();
+		assertJsonEqual(await store.read("missing"), [], "read of an unknown thread must be empty");
+		if (await store.length("missing") !== 0) fail("length of an unknown thread must be 0");
+	}
+	{
+		const store = await create();
+		const e = entry(0, "start", { label: "first" });
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: [e]
+		});
+		assertJsonEqual(await store.read("t"), [e], "read must return the appended entry");
+		if (await store.length("t") !== 1) fail("length after a single append must be 1");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: entriesFrom(0, 3)
+		});
+		await store.append({
+			threadId: "t",
+			expectedIndex: 3,
+			entries: entriesFrom(3, 2)
+		});
+		if (await store.length("t") !== 5) fail("length after appending 3 then 2 entries must be 5");
+		assertJsonEqual((await store.read("t")).map((e) => e.index), [
+			0,
+			1,
+			2,
+			3,
+			4
+		], "reads must return entries in contiguous log order");
+	}
+	{
+		const store = await create();
+		let caught;
+		try {
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [entry(1, "gap")]
+			});
+		} catch (error) {
+			caught = error;
+		}
+		if (!(caught instanceof Error) || caught instanceof AgentEventLogConflictError) fail("a non-contiguous entry.index must throw a plain Error, not a conflict");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: [entry(0, "a")]
+		});
+		let caught;
+		try {
+			await store.append({
+				threadId: "t",
+				expectedIndex: 0,
+				entries: [entry(0, "b")]
+			});
+		} catch (error) {
+			caught = error;
+		}
+		if (!(caught instanceof AgentEventLogConflictError)) fail("a stale expectedIndex must throw AgentEventLogConflictError");
+		if (caught.threadId !== "t" || caught.expectedIndex !== 0 || caught.actualLength !== 1) fail("conflict error must carry threadId, expectedIndex, and the actual length");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: [entry(0, "a")]
+		});
+		let caught;
+		try {
+			await store.append({
+				threadId: "t",
+				expectedIndex: 1,
+				entries: [{
+					...entry(1, "b"),
+					id: "evt_0"
+				}]
+			});
+		} catch (error) {
+			caught = error;
+		}
+		if (!(caught instanceof Error) || caught instanceof AgentEventLogConflictError) fail("a duplicate event id within a thread must throw a plain Error");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: [entry(0, "a")]
+		});
+		const results = await Promise.allSettled([store.append({
+			threadId: "t",
+			expectedIndex: 1,
+			entries: [entry(1, "w-a")]
+		}), store.append({
+			threadId: "t",
+			expectedIndex: 1,
+			entries: [entry(1, "w-b")]
+		})]);
+		const winners = results.filter((r) => r.status === "fulfilled");
+		const conflicts = results.filter((r) => r.status === "rejected" && r.reason instanceof AgentEventLogConflictError);
+		if (winners.length !== 1) fail(`exactly one racing append must win, got ${winners.length}`);
+		if (conflicts.length !== 1) fail(`exactly one racing append must reject with a conflict, got ${conflicts.length}`);
+		if (await store.length("t") !== 2) fail("after the race the log length must be 2");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: entriesFrom(0, 5)
+		});
+		assertJsonEqual((await store.read("t", { from: 2 })).map((e) => e.index), [
+			2,
+			3,
+			4
+		], "read({ from }) must skip entries below `from`");
+		assertJsonEqual(await store.read("t", { from: 5 }), [], "read({ from }) at the log length must be empty");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "a",
+			expectedIndex: 0,
+			entries: [entry(0, "x")]
+		});
+		if (await store.length("b") !== 0) fail("an append to one thread must not create another");
+		await store.append({
+			threadId: "b",
+			expectedIndex: 0,
+			entries: entriesFrom(0, 2)
+		});
+		if (await store.length("a") !== 1 || await store.length("b") !== 2) fail("threads must grow independently");
+	}
+	{
+		const store = await create();
+		const metadata = {
+			source: "user",
+			nested: { attempt: 2 },
+			tags: ["x", "y"]
+		};
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: [entry(0, "e", metadata)]
+		});
+		assertJsonEqual((await store.read("t"))[0].metadata, metadata, "metadata must round-trip verbatim");
+	}
+	{
+		const store = await create();
+		const e = entry(0, "e", { tags: ["a"] });
+		await store.append({
+			threadId: "t",
+			expectedIndex: 0,
+			entries: [e]
+		});
+		e.metadata.tags.push("mutated-after-append");
+		e.event.seq = 999;
+		const read = await store.read("t");
+		read[0].metadata.tags.push("mutated-after-read");
+		read[0].event.seq = 888;
+		const reread = await store.read("t");
+		assertJsonEqual(reread[0].metadata, { tags: ["a"] }, "stored entry must be isolated from post-append and post-read mutation");
+		assertJsonEqual(reread[0].event, {
+			type: "e",
+			seq: 0
+		}, "stored event must be isolated from mutation of an appended or read copy");
+	}
+	{
+		const store = await create();
+		await store.append({
+			threadId: "src",
+			expectedIndex: 0,
+			entries: entriesFrom(0, 3)
+		});
+		await store.fork({
+			threadId: "src",
+			newThreadId: "fork-full"
+		});
+		if (await store.length("fork-full") !== 3) fail("fork with the default upToIndex must copy the full log");
+		await store.fork({
+			threadId: "src",
+			newThreadId: "fork-1",
+			upToIndex: 1
+		});
+		assertJsonEqual((await store.read("fork-1")).map((e) => e.index), [0], "fork with upToIndex 1 must copy only entry 0");
+		await store.fork({
+			threadId: "src",
+			newThreadId: "fork-id",
+			atEventId: "evt_1"
+		});
+		assertJsonEqual((await store.read("fork-id")).map((e) => e.id), ["evt_0", "evt_1"], "fork with atEventId must include the named entry");
+		await store.append({
+			threadId: "fork-1",
+			expectedIndex: 1,
+			entries: [entry(1, "branch")]
+		});
+		assertJsonEqual((await store.read("fork-1")).map((e) => e.event.type), ["e0", "branch"], "a forked thread must append independently from its copied length");
+		if (await store.length("src") !== 3) fail("appending to a fork must not touch the source thread");
+		let caughtExisting;
+		try {
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-full"
+			});
+		} catch (error) {
+			caughtExisting = error;
+		}
+		if (!(caughtExisting instanceof Error) || caughtExisting instanceof AgentEventLogConflictError) fail("forking onto a non-empty thread must reject with a plain Error");
+		let caughtUnknown;
+		try {
+			await store.fork({
+				threadId: "nope",
+				newThreadId: "fork-nope"
+			});
+		} catch (error) {
+			caughtUnknown = error;
+		}
+		if (!(caughtUnknown instanceof Error) || caughtUnknown instanceof AgentEventLogConflictError) fail("forking an unknown source thread must reject with a plain Error");
+	}
+}
+//#endregion
+export { assertEventLogStoreConformance as a, assertAgentLogEntry as i, AgentEventLogConflictError as n, assertJsonSerializable as o, NonSerializableAgentEventError as r, createInMemoryEventLogStore as s, AGENT_EVENT_SCHEMA_VERSION as t };

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

@@ -0,0 +1,144 @@
+import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
+import { EventObject } from "xstate";
+
+//#region src/event-log-store.d.ts
+/** The durable replay-entry envelope version. */
+declare const AGENT_EVENT_SCHEMA_VERSION: 1;
+/** Values that round-trip through JSON without adapters or silent coercion. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+interface AgentLogVerification {
+  /** Hash of the logical machine projection after this entry is applied. */
+  stateHash: string;
+  /** Hash of the serializable effects owed at that frontier. */
+  effectsHash: string;
+}
+/**
+ * One journaled entry: an EXTERNAL input to the machine — an effect completion
+ * (a `done`/`error` event carrying its output inline), a user-sent event, or a
+ * timer firing. Never a raised/internal event: deterministic replay re-derives
+ * those from the machine's own logic, so journaling them would double-apply.
+ * JSON-safe, 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 thread. Forked prefixes retain their ids. */
+  id: string;
+  /** 0-based position in the thread's 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 thread. */
+  causationId?: string;
+  /** Optional host-owned correlation id spanning threads/runs. */
+  correlationId?: string;
+  /** Recorded projection hashes used by strict replay verification. */
+  verification?: AgentLogVerification;
+  /** Host-owned, JSON-safe; stored verbatim, never interpreted. */
+  metadata?: Record<string, JsonValue>;
+}
+/** 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);
+}
+/**
+ * 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;
+/**
+ * An append-only event log: the authoritative durability artifact of a thread.
+ * The journal of external inputs IS the source of truth — deterministic machine
+ * replay derives every snapshot from it, a fork is a copied log prefix, and the
+ * type-only {@link AgentSnapshotStore} is a mere idle-point compaction cache
+ * over what the log already implies.
+ *
+ * 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 in-memory reference.
+ */
+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 a prefix onto a fresh, empty `newThreadId` — either `[0, upToIndex)`
+   * or through the inclusive `atEventId`. With neither cutoff the full source
+   * is copied. The fork then appends independently. Rejects (plain `Error`) if
+   * `newThreadId` already has entries, the source/id is unknown, or both cutoff
+   * forms are supplied. Implementations may copy-on-write or physically copy;
+   * observable behavior must match a full copy.
+   */
+  fork(input: {
+    threadId: string;
+    newThreadId: string;
+    upToIndex?: number; /** Inclusive event-id cutoff. Mutually exclusive with `upToIndex`. */
+    atEventId?: string;
+  }): 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. `actualLength` is the length core found.
+ */
+declare class AgentEventLogConflictError extends AgentError {
+  readonly threadId: string;
+  readonly expectedIndex: number;
+  readonly actualLength: number;
+  constructor(threadId: string, expectedIndex: number, actualLength: 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;
+/** Produces a fresh, empty store for one assertion. */
+type CreateStore = () => Promise<AgentEventLogStore> | AgentEventLogStore;
+/**
+ * Validates a store against the reference's semantics: empty read + zero length
+ * for unknown threads; single and multi-entry append; contiguity misuse guard;
+ * stale-`expectedIndex` conflict with correct fields; an interleaved concurrent
+ * append race (exactly one winner); event-id uniqueness; `read({ from })`
+ * incremental correctness; thread isolation; metadata round-trip; deep-copy
+ * isolation on append and read; and the full fork contract.
+ */
+declare function assertEventLogStoreConformance(create: CreateStore): Promise<void>;
+//#endregion
+export { AgentLogVerification as a, assertAgentLogEntry as c, createInMemoryEventLogStore as d, AgentLogEntry as i, assertEventLogStoreConformance as l, AgentEventLogConflictError as n, JsonValue as o, AgentEventLogStore as r, NonSerializableAgentEventError as s, AGENT_EVENT_SCHEMA_VERSION as t, assertJsonSerializable as u };