@statelyai/agent 2.0.0-alpha.14 → 2.0.0-alpha.16

package/dist/{event-log-store-CVd2eyRy.d.cts → event-log-store-CQJq8_v4.d.cts}

@@ -1,6 +1,19 @@
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
 import { EventObject } from "xstate";
 
+//#region src/event-log-store-conformance.d.ts
+/** 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
 //#region src/event-log-store.d.ts
 /** The durable replay-entry envelope version. */
 declare const AGENT_EVENT_SCHEMA_VERSION: 1;
@@ -129,16 +142,5 @@ declare class AgentEventLogConflictError extends AgentError {
  * 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 };
+export { AgentLogVerification as a, assertAgentLogEntry as c, assertEventLogStoreConformance as d, AgentLogEntry as i, assertJsonSerializable as l, AgentEventLogConflictError as n, JsonValue as o, AgentEventLogStore as r, NonSerializableAgentEventError as s, AGENT_EVENT_SCHEMA_VERSION as t, createInMemoryEventLogStore as u };

package/dist/{event-log-store-CNT_7F0V.cjs → event-log-store-yquOV1TX.cjs}

@@ -1,146 +1,12 @@
 const require_errors = require("./errors-DUBBzRLP.cjs");
-//#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 require_errors.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 require_errors.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;
-	}
-};
+//#region src/event-log-store-conformance.ts
 /**
-* 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.
+* 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 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}`);
 }
@@ -408,6 +274,148 @@ async function assertEventLogStoreConformance(create) {
 	}
 }
 //#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 require_errors.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. `actualLength` is the length core found.
+*/
+var AgentEventLogConflictError = class extends require_errors.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)));
+		}
+	};
+}
+//#endregion
 Object.defineProperty(exports, "AGENT_EVENT_SCHEMA_VERSION", {
 	enumerable: true,
 	get: function() {