@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.23

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

@@ -1,427 +0,0 @@
-import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-//#region src/event-log-store-conformance.ts
-/**
-* The runner-agnostic conformance suite for {@link AgentEventLogStore}
-* implementations. Split out of `event-log-store.ts` so the store contract and
-* the reference implementation stay readable; re-exported from there (and from
-* the package root) so the public surface is unchanged.
-* @module
-*/
-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.actualIndex !== 1) fail("conflict error must carry threadId, expectedIndex, and the actual index");
-	}
-	{
-		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-2",
-			upToIndex: 2
-		});
-		assertJsonEqual((await store.read("fork-2")).map((e) => e.id), ["evt_0", "evt_1"], "fork with upToIndex 2 must copy entries 0 and 1 only");
-		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");
-		let caughtRange;
-		try {
-			await store.fork({
-				threadId: "src",
-				newThreadId: "fork-range",
-				upToIndex: 99
-			});
-		} catch (error) {
-			caughtRange = error;
-		}
-		if (!(caughtRange instanceof Error) || caughtRange instanceof AgentEventLogConflictError) fail("forking past the source length must reject with a plain Error");
-	}
-}
-//#endregion
-//#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;
-	}
-};
-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 Error(`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 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)}.`);
-	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 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.");
-	for (const field of ["causationId", "correlationId"]) if (candidate[field] !== void 0) requireNonEmptyString(candidate[field], `entry.${field}`, " 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. `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 (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)));
-		}
-	};
-}
-//#endregion
-export { assertJsonSerializable as a, assertAgentLogEntry as i, AgentEventLogConflictError as n, createInMemoryEventLogStore as o, NonSerializableAgentEventError as r, assertEventLogStoreConformance as s, AGENT_EVENT_SCHEMA_VERSION as t };