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

package/dist/ai-sdk.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_decision = require("./decision-C0cUKvNt.cjs");
+const require_decision = require("./decision-Ba8qrT8r.cjs");
 let ai = require("ai");
 //#region src/ai-sdk/mappers.ts
 /**

package/dist/ai-sdk.d.cts

@@ -1,5 +1,5 @@
-import { d as ChosenEvent } from "./types-rMe7x6NR.cjs";
-import { k as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-Jkilp1Ie.cjs";
+import { d as ChosenEvent } from "./types-pJ5Hn8fv.cjs";
+import { A as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-BFX5q7fM.cjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
-import { d as ChosenEvent } from "./types-9Bqg5rZB.mjs";
-import { k as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-C5kbjaDz.mjs";
+import { d as ChosenEvent } from "./types-DYpK3QF4.mjs";
+import { A as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-DQW8_DWW.mjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts

package/dist/ai-sdk.mjs

@@ -1,4 +1,4 @@
-import { V as isStandardSchema, i as renderDecisionAttempts, p as buildEnvelopeSchema, v as getAgentOutputMode } from "./decision-D9Zi7Xi5.mjs";
+import { H as isStandardSchema, _ as getAgentOutputMode, i as renderDecisionAttempts, p as buildEnvelopeSchema } from "./decision-Bt2HYYRo.mjs";
 import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText, tool } from "ai";
 //#region src/ai-sdk/mappers.ts
 /**

package/dist/{decision-C0cUKvNt.cjs → decision-Ba8qrT8r.cjs}

@@ -98,6 +98,12 @@ function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
 	seen.delete(obj);
 	return out;
 }
+/**
+* djb2 → unsigned 32-bit → 8-char hex. No dependencies. A change detector, not
+* a cryptographic digest.
+*
+* @internal
+*/
 function djb2Hex(input) {
 	let hash = 5381;
 	for (let i = 0; i < input.length; i++) hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
@@ -313,15 +319,26 @@ const AGENT_USAGE_TOKEN_FIELDS = [
 	"cachedInputTokens"
 ];
 /**
-* Reads a per-call {@link AgentCallUsage} off a raw executor result's `usage`
-* field, keeping only finite numbers. Returns `undefined` when the result
-* reports no usage at all. Works for our `{ output, usage }` envelope, for a
-* raw Vercel AI SDK result (its `LanguageModelUsage` carries the same flat
-* field names), and for any custom executor that follows the shape.
+* Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
+* result's `usage` field, keeping only finite numbers — the same normalization
+* `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
+* when the result reports no usage at all. Works for our `{ output, usage }`
+* envelope, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
+* the same flat field names), and for any custom executor that follows the
+* shape.
 *
-* @internal
+* The seam for the step-loop path, where the host holds the raw result itself:
+*
+* ```ts
+* const { output, raw } = await executeAgentRequest(effect, executors);
+* const usage = getCallUsage(raw);
+* if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
+* append(effect.toDoneEvent(output));
+* ```
+*
+* See "Token usage on this path" in docs/steps.md for the full loop.
 */
-function extractCallUsage(raw) {
+function getCallUsage(raw) {
 	const usage = raw?.usage;
 	if (!usage || typeof usage !== "object") return;
 	let out;
@@ -344,13 +361,14 @@ const agentTextInputSchema = { "~standard": {
 		return { value: request };
 	}
 } };
-const unknownOutputSchema = { "~standard": {
+const passthroughSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
 	validate(value) {
 		return { value };
 	}
 } };
+const unknownOutputSchema = passthroughSchema;
 const stringOutputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -358,13 +376,7 @@ const stringOutputSchema = { "~standard": {
 		return typeof value === "string" ? { value } : { issues: [{ message: "Expected string output" }] };
 	}
 } };
-const noInputSchema = { "~standard": {
-	version: 1,
-	vendor: "statelyai-agent",
-	validate(value) {
-		return { value };
-	}
-} };
+const noInputSchema = passthroughSchema;
 function createBuiltinTextActor(src, mode, outputSchema) {
 	const logic = (0, xstate.createAsyncLogic)({ run: async () => {
 		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actors: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
@@ -384,7 +396,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 			return validateSchemaSync(outputSchema, output);
 		},
 		withExecutor(execute) {
-			return Object.assign(createTextLogic({
+			return createTextLogic({
 				mode,
 				schemas: {
 					input: agentTextInputSchema,
@@ -405,7 +417,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				seed: ({ input }) => input.seed,
 				stopSequences: ({ input }) => input.stopSequences,
 				metadata: ({ input }) => input.metadata
-			}, execute));
+			}, execute);
 		}
 	});
 }
@@ -552,7 +564,7 @@ function isTextLogic(value) {
 * as `'text'`.
 */
 function getAgentOutputMode(schema) {
-	const jsonSchema = getStandardSchemaJson(schema);
+	const jsonSchema = getJsonSchemaSync(schema);
 	if (!jsonSchema) return "text";
 	if (jsonSchema.type === "object" || jsonSchema.type === "array") return "structured";
 	if (jsonSchema.type === void 0 && ("anyOf" in jsonSchema || "oneOf" in jsonSchema || "allOf" in jsonSchema)) return "structured";
@@ -616,10 +628,6 @@ function parseStructuredEnvelope(request, value) {
 	if (!request.outputSchema) throw new Error("parseStructuredEnvelope: the request declares no outputSchema.");
 	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }), value);
 }
-function getStandardSchemaJson(schema) {
-	const jsonSchema = (schema?.["~standard"])?.jsonSchema?.input?.();
-	return jsonSchema && !(jsonSchema instanceof Promise) ? jsonSchema : void 0;
-}
 /**
 * Merges request-declared and call-site `tools`, dispatches to the
 * `mode`-appropriate executor (`generateText`/`streamText`), and normalizes
@@ -1072,22 +1080,22 @@ Object.defineProperty(exports, "createTextLogic", {
 		return createTextLogic;
 	}
 });
-Object.defineProperty(exports, "executeAgentTextRequest", {
+Object.defineProperty(exports, "djb2Hex", {
 	enumerable: true,
 	get: function() {
-		return executeAgentTextRequest;
+		return djb2Hex;
 	}
 });
-Object.defineProperty(exports, "executorBoundLogics", {
+Object.defineProperty(exports, "executeAgentTextRequest", {
 	enumerable: true,
 	get: function() {
-		return executorBoundLogics;
+		return executeAgentTextRequest;
 	}
 });
-Object.defineProperty(exports, "extractCallUsage", {
+Object.defineProperty(exports, "executorBoundLogics", {
 	enumerable: true,
 	get: function() {
-		return extractCallUsage;
+		return executorBoundLogics;
 	}
 });
 Object.defineProperty(exports, "findNonSerializableContextPaths", {
@@ -1114,6 +1122,12 @@ Object.defineProperty(exports, "getAgentOutputMode", {
 		return getAgentOutputMode;
 	}
 });
+Object.defineProperty(exports, "getCallUsage", {
+	enumerable: true,
+	get: function() {
+		return getCallUsage;
+	}
+});
 Object.defineProperty(exports, "getJsonSchema", {
 	enumerable: true,
 	get: function() {

package/dist/{decision-D9Zi7Xi5.mjs → decision-Bt2HYYRo.mjs}

@@ -98,6 +98,12 @@ function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
 	seen.delete(obj);
 	return out;
 }
+/**
+* djb2 → unsigned 32-bit → 8-char hex. No dependencies. A change detector, not
+* a cryptographic digest.
+*
+* @internal
+*/
 function djb2Hex(input) {
 	let hash = 5381;
 	for (let i = 0; i < input.length; i++) hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
@@ -313,15 +319,26 @@ const AGENT_USAGE_TOKEN_FIELDS = [
 	"cachedInputTokens"
 ];
 /**
-* Reads a per-call {@link AgentCallUsage} off a raw executor result's `usage`
-* field, keeping only finite numbers. Returns `undefined` when the result
-* reports no usage at all. Works for our `{ output, usage }` envelope, for a
-* raw Vercel AI SDK result (its `LanguageModelUsage` carries the same flat
-* field names), and for any custom executor that follows the shape.
+* Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
+* result's `usage` field, keeping only finite numbers — the same normalization
+* `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
+* when the result reports no usage at all. Works for our `{ output, usage }`
+* envelope, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
+* the same flat field names), and for any custom executor that follows the
+* shape.
 *
-* @internal
+* The seam for the step-loop path, where the host holds the raw result itself:
+*
+* ```ts
+* const { output, raw } = await executeAgentRequest(effect, executors);
+* const usage = getCallUsage(raw);
+* if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
+* append(effect.toDoneEvent(output));
+* ```
+*
+* See "Token usage on this path" in docs/steps.md for the full loop.
 */
-function extractCallUsage(raw) {
+function getCallUsage(raw) {
 	const usage = raw?.usage;
 	if (!usage || typeof usage !== "object") return;
 	let out;
@@ -344,13 +361,14 @@ const agentTextInputSchema = { "~standard": {
 		return { value: request };
 	}
 } };
-const unknownOutputSchema = { "~standard": {
+const passthroughSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
 	validate(value) {
 		return { value };
 	}
 } };
+const unknownOutputSchema = passthroughSchema;
 const stringOutputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -358,13 +376,7 @@ const stringOutputSchema = { "~standard": {
 		return typeof value === "string" ? { value } : { issues: [{ message: "Expected string output" }] };
 	}
 } };
-const noInputSchema = { "~standard": {
-	version: 1,
-	vendor: "statelyai-agent",
-	validate(value) {
-		return { value };
-	}
-} };
+const noInputSchema = passthroughSchema;
 function createBuiltinTextActor(src, mode, outputSchema) {
 	const logic = createAsyncLogic({ run: async () => {
 		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actors: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
@@ -384,7 +396,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 			return validateSchemaSync(outputSchema, output);
 		},
 		withExecutor(execute) {
-			return Object.assign(createTextLogic({
+			return createTextLogic({
 				mode,
 				schemas: {
 					input: agentTextInputSchema,
@@ -405,7 +417,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				seed: ({ input }) => input.seed,
 				stopSequences: ({ input }) => input.stopSequences,
 				metadata: ({ input }) => input.metadata
-			}, execute));
+			}, execute);
 		}
 	});
 }
@@ -552,7 +564,7 @@ function isTextLogic(value) {
 * as `'text'`.
 */
 function getAgentOutputMode(schema) {
-	const jsonSchema = getStandardSchemaJson(schema);
+	const jsonSchema = getJsonSchemaSync(schema);
 	if (!jsonSchema) return "text";
 	if (jsonSchema.type === "object" || jsonSchema.type === "array") return "structured";
 	if (jsonSchema.type === void 0 && ("anyOf" in jsonSchema || "oneOf" in jsonSchema || "allOf" in jsonSchema)) return "structured";
@@ -616,10 +628,6 @@ function parseStructuredEnvelope(request, value) {
 	if (!request.outputSchema) throw new Error("parseStructuredEnvelope: the request declares no outputSchema.");
 	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }), value);
 }
-function getStandardSchemaJson(schema) {
-	const jsonSchema = (schema?.["~standard"])?.jsonSchema?.input?.();
-	return jsonSchema && !(jsonSchema instanceof Promise) ? jsonSchema : void 0;
-}
 /**
 * Merges request-declared and call-site `tools`, dispatches to the
 * `mode`-appropriate executor (`generateText`/`streamText`), and normalizes
@@ -1000,4 +1008,4 @@ async function resolveDecision(request, executor, options = {}) {
 	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
-export { isUnboundPlaceholder as A, getStateMeta as B, parseStructuredEnvelope as C, getMachineStaticTransitionTargets as D, executorBoundLogics as E, findNonSerializableContextPaths as F, userMessage as G, persistSnapshot as H, getAgentMessages as I, validateSchemaSync as K, getJsonSchema as L, machineSuspensionPredicates as M, missingActor as N, getMachineSuspensionPredicate as O, assistantMessage as P, getJsonSchemaSync as R, parseOutput as S, agentExecutionOptions as T, systemMessage as U, isStandardSchema as V, toolMessage as W, extractCallUsage as _, resolveDecision as a, normalizeGeneratorResult as b, AGENT_USAGE_TOKEN_FIELDS as c, USER_INPUT_ACTOR as d, bindRequestExecutor as f, executeAgentTextRequest as g, createTextLogic as h, renderDecisionAttempts as i, machineStaticTransitionTargets as j, getRegisteredAgentExecutionOptions as k, DECIDE_ACTOR as l, builtinTextActors as m, createDecideActor as n, getAcceptedEvents as o, buildEnvelopeSchema as p, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, INTERPRET_SOURCE as u, getAgentOutputMode as v, userInputActor as w, parseModelRef as x, isTextLogic as y, getMachineStructuralHash as z };
+export { isUnboundPlaceholder as A, getMachineStructuralHash as B, parseStructuredEnvelope as C, getMachineStaticTransitionTargets as D, executorBoundLogics as E, djb2Hex as F, toolMessage as G, isStandardSchema as H, findNonSerializableContextPaths as I, userMessage as K, getAgentMessages as L, machineSuspensionPredicates as M, missingActor as N, getMachineSuspensionPredicate as O, assistantMessage as P, getJsonSchema as R, parseOutput as S, agentExecutionOptions as T, persistSnapshot as U, getStateMeta as V, systemMessage as W, getAgentOutputMode as _, resolveDecision as a, normalizeGeneratorResult as b, AGENT_USAGE_TOKEN_FIELDS as c, USER_INPUT_ACTOR as d, bindRequestExecutor as f, executeAgentTextRequest as g, createTextLogic as h, renderDecisionAttempts as i, machineStaticTransitionTargets as j, getRegisteredAgentExecutionOptions as k, DECIDE_ACTOR as l, builtinTextActors as m, createDecideActor as n, getAcceptedEvents as o, buildEnvelopeSchema as p, validateSchemaSync as q, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, INTERPRET_SOURCE as u, getCallUsage as v, userInputActor as w, parseModelRef as x, isTextLogic as y, getJsonSchemaSync as z };

package/dist/{event-log-store-D7pWtIhb.mjs → event-log-store-B-1fcfkT.mjs}

@@ -1,146 +1,12 @@
 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;
-	}
-};
+//#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,4 +274,146 @@ async function assertEventLogStoreConformance(create) {
 	}
 }
 //#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 };
+//#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. `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)));
+		}
+	};
+}
+//#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 };

package/dist/{event-log-store-BkUNtyOF.d.mts → event-log-store-BrC9Q1xW.d.mts}

@@ -1,6 +1,19 @@
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
 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 };