stitchkit 0.93.0 → 0.94.1

package/dist/entrypoints/agent-runtime/testing.js

@@ -0,0 +1,1116 @@
+import {
+  createMemoryAgentRuntimeStore
+} from "../../index-sp1tzwnb.js";
+import"../../index-wsm5w4ee.js";
+import {
+  decodeAgentConversationArchive
+} from "../../index-gxrt5h6v.js";
+import {
+  AgentMessageSchema,
+  AgentRunSchema
+} from "../../index-gtj3zc53.js";
+import"../../index-k5hsfc3j.js";
+import"../../index-hffjpmq9.js";
+
+// src/agent-runtime/fault-bench.ts
+import { createServer } from "node:http";
+import { z } from "zod";
+var AgentFaultStepSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("pass"), text: z.string().default("ok") }).strict(),
+  z.object({ kind: z.literal("connection-refused") }).strict(),
+  z.object({ kind: z.literal("timeout-before-first-byte"), milliseconds: z.int().positive() }).strict(),
+  z.object({ kind: z.literal("stream-cut"), afterBytes: z.int().nonnegative() }).strict(),
+  z.object({ kind: z.literal("http-error"), status: z.int().min(400).max(599) }).strict(),
+  z.object({ kind: z.literal("bad-json") }).strict(),
+  z.object({
+    kind: z.literal("slow"),
+    text: z.string(),
+    tokensPerSecond: z.number().positive()
+  }).strict(),
+  z.object({ kind: z.literal("usage-missing"), text: z.string().default("ok") }).strict()
+]);
+function defineAgentFaultPlan(steps) {
+  if (steps.length === 0)
+    throw new TypeError("Fault plan must contain at least one step");
+  return steps.map((step) => AgentFaultStepSchema.parse(step));
+}
+function completionChunk(text, finishReason) {
+  return `data: ${JSON.stringify({
+    id: "fault-bench",
+    object: "chat.completion.chunk",
+    choices: [{ index: 0, delta: text ? { content: text } : {}, finish_reason: finishReason }]
+  })}
+
+`;
+}
+function completeSse(response, text, includeUsage) {
+  response.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "close"
+  });
+  response.write(completionChunk(text, null));
+  response.write(completionChunk("", "stop"));
+  if (includeUsage) {
+    response.write(`data: ${JSON.stringify({
+      id: "fault-bench",
+      object: "chat.completion.chunk",
+      choices: [],
+      usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 }
+    })}
+
+`);
+  }
+  response.end(`data: [DONE]
+
+`);
+}
+async function createFaultProviderServer(input) {
+  const scenario = defineAgentFaultPlan(input.scenario);
+  let calls = 0;
+  const server = createServer((request, response) => {
+    request.resume();
+    const step = scenario[Math.min(calls, scenario.length - 1)];
+    calls += 1;
+    if (!step)
+      throw new Error("Fault scenario disappeared");
+    if (step.kind === "connection-refused") {
+      request.socket.destroy();
+      return;
+    }
+    if (step.kind === "timeout-before-first-byte") {
+      setTimeout(() => completeSse(response, "late", true), step.milliseconds).unref();
+      return;
+    }
+    if (step.kind === "http-error") {
+      response.writeHead(step.status, { "content-type": "application/json" });
+      response.end(JSON.stringify({ error: { message: `fault ${step.status}` } }));
+      return;
+    }
+    if (step.kind === "bad-json") {
+      response.writeHead(200, { "content-type": "text/event-stream" });
+      response.end(`data: {not-json}
+
+data: [DONE]
+
+`);
+      return;
+    }
+    if (step.kind === "stream-cut") {
+      response.writeHead(200, { "content-type": "text/event-stream" });
+      const bytes = Buffer.from(completionChunk("partial response", null));
+      response.write(bytes.subarray(0, Math.min(step.afterBytes, bytes.byteLength)));
+      response.socket?.destroy();
+      return;
+    }
+    if (step.kind === "slow") {
+      response.writeHead(200, { "content-type": "text/event-stream" });
+      const tokens = step.text.split(/(?<=\s)/u).filter(Boolean);
+      const intervalMs = Math.max(1, Math.round(1000 / step.tokensPerSecond));
+      let index = 0;
+      const timer = setInterval(() => {
+        const token = tokens[index];
+        index += 1;
+        if (token !== undefined)
+          response.write(completionChunk(token, null));
+        if (index >= tokens.length) {
+          clearInterval(timer);
+          response.end(`${completionChunk("", "stop")}data: [DONE]
+
+`);
+        }
+      }, intervalMs);
+      timer.unref();
+      return;
+    }
+    completeSse(response, step.text, step.kind !== "usage-missing");
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address();
+  if (!address || typeof address === "string")
+    throw new Error("Fault server has no TCP address");
+  return {
+    url: `http://127.0.0.1:${address.port}/v1/chat/completions`,
+    calls: () => calls,
+    close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()))
+  };
+}
+function createReplayAgentProvider(input) {
+  const calls = new Map;
+  return {
+    create(modelId) {
+      const index = calls.get(modelId) ?? 0;
+      const attempts = input.attempts[modelId];
+      const model = attempts?.[index];
+      if (!model)
+        throw new TypeError(`Replay exhausted for model: ${modelId}`);
+      calls.set(modelId, index + 1);
+      return model;
+    },
+    calls: (modelId) => calls.get(modelId) ?? 0
+  };
+}
+// src/agent-runtime/store-conformance-support.ts
+function userMessage(conversationId, id) {
+  return AgentMessageSchema.parse({
+    schemaVersion: 1,
+    id,
+    conversationId,
+    role: "user",
+    status: "committed",
+    parts: [{ type: "text", text: id }],
+    createdAt: "2026-08-22T00:00:00.000Z",
+    updatedAt: "2026-08-22T00:00:00.000Z"
+  });
+}
+function queuedRun(conversationId, inputMessageId, id) {
+  return AgentRunSchema.parse({
+    schemaVersion: 1,
+    id,
+    conversationId,
+    inputMessageIds: [inputMessageId],
+    assistantMessageId: `${id}-assistant`,
+    state: "queued",
+    revision: 0,
+    createdAt: "2026-08-22T00:00:00.000Z",
+    updatedAt: "2026-08-22T00:00:00.000Z"
+  });
+}
+function requireOutcome(actual, expected) {
+  if (actual.outcome !== expected) {
+    throw new Error(`Agent store conformance expected ${expected}, received ${actual.outcome}`);
+  }
+}
+
+// src/agent-runtime/store-conformance-lifecycle.ts
+async function admissionPhase(store, conversationId) {
+  const firstInput = userMessage(conversationId, "input-1");
+  const firstRun = queuedRun(conversationId, firstInput.id, "run-1");
+  const accepted = await store.acceptInputAndAssignRun({
+    idempotencyKey: "request-1",
+    input: firstInput,
+    run: firstRun
+  });
+  requireOutcome(accepted, "applied");
+  const duplicate = await store.acceptInputAndAssignRun({
+    idempotencyKey: "request-1",
+    input: userMessage(conversationId, "discarded-input"),
+    run: queuedRun(conversationId, "discarded-input", "discarded-run")
+  });
+  requireOutcome(duplicate, "duplicate");
+  if (duplicate.input.id !== firstInput.id || duplicate.inputMessageId !== firstInput.id || duplicate.runId !== firstRun.id || duplicate.assistantMessageId !== firstRun.assistantMessageId) {
+    throw new Error("Duplicate admission did not return its original durable identity");
+  }
+  const secondInput = userMessage(conversationId, "input-2");
+  const coalesced = await store.acceptInputAndAssignRun({
+    idempotencyKey: "request-2",
+    input: secondInput,
+    run: queuedRun(conversationId, secondInput.id, "discarded-coalesced-run"),
+    coalesceIntoRunId: firstRun.id
+  });
+  requireOutcome(coalesced, "applied");
+  const assigned = coalesced.snapshot.runs.find((run) => run.id === firstRun.id);
+  if (assigned?.inputMessageIds.join(",") !== "input-1,input-2") {
+    throw new Error("Coalesced admission did not preserve ordered input identities");
+  }
+  const collidingInput = userMessage(conversationId, assigned.assistantMessageId);
+  await store.acceptInputAndAssignRun({
+    idempotencyKey: "request-collision",
+    input: collidingInput,
+    run: queuedRun(conversationId, collidingInput.id, "discarded-collision-run"),
+    coalesceIntoRunId: assigned.id
+  }).then(() => {
+    throw new Error("Coalesced input reused the reserved assistant identity");
+  }, (error) => {
+    if (!(error instanceof TypeError))
+      throw error;
+  });
+  await store.replaceCompactedRange({
+    conversationId,
+    expectedVersion: coalesced.snapshot.version,
+    replacedMessageIds: [firstInput.id, secondInput.id],
+    summary: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: assigned.assistantMessageId,
+      conversationId,
+      role: "summary",
+      status: "committed",
+      parts: [{ type: "text", text: "invalid reserved identity" }],
+      createdAt: "2026-08-22T00:00:02.000Z",
+      updatedAt: "2026-08-22T00:00:02.000Z"
+    })
+  }).then(() => {
+    throw new Error("Compaction reused a reserved assistant identity");
+  }, (error) => {
+    if (!(error instanceof TypeError))
+      throw error;
+  });
+  const compacted = await store.replaceCompactedRange({
+    conversationId,
+    expectedVersion: coalesced.snapshot.version,
+    replacedMessageIds: [firstInput.id, secondInput.id],
+    summary: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: "summary-1",
+      conversationId,
+      role: "summary",
+      status: "committed",
+      parts: [{ type: "text", text: "two inputs" }],
+      createdAt: "2026-08-22T00:00:02.000Z",
+      updatedAt: "2026-08-22T00:00:02.000Z"
+    })
+  });
+  requireOutcome(compacted, "applied");
+  const duplicateAfterCompaction = await store.acceptInputAndAssignRun({
+    idempotencyKey: "request-1",
+    input: userMessage(conversationId, "discarded-after-compaction"),
+    run: queuedRun(conversationId, "discarded-after-compaction", "discarded-run-2")
+  });
+  requireOutcome(duplicateAfterCompaction, "duplicate");
+  if (duplicateAfterCompaction.input.id !== firstInput.id) {
+    throw new Error("Compaction discarded the canonical duplicate admission input");
+  }
+  return assigned;
+}
+async function fencingPhase(store, conversationId, assigned) {
+  const acquired = await store.acquireRun({
+    conversationId,
+    runId: assigned.id,
+    expectedRevision: assigned.revision,
+    ownerId: "conformance-owner"
+  });
+  requireOutcome(acquired, "applied");
+  const running = acquired.snapshot.runs.find((run) => run.id === assigned.id);
+  if (!running)
+    throw new Error("Acquired run disappeared");
+  const stale = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision - 1,
+    ownerId: "conformance-owner",
+    assistant: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: running.assistantMessageId,
+      conversationId,
+      runId: running.id,
+      role: "assistant",
+      status: "streaming",
+      parts: [],
+      createdAt: "2026-08-22T00:00:00.000Z",
+      updatedAt: "2026-08-22T00:00:01.000Z"
+    })
+  });
+  requireOutcome(stale, "conflict");
+  await store.recoverRun({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    action: "requeue"
+  }).then(() => {
+    throw new Error("Acquired recovery replayed without explicit safety evidence");
+  }, (error) => {
+    if (!(error instanceof TypeError))
+      throw error;
+  });
+  const checkpoint = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "conformance-owner",
+    assistant: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: running.assistantMessageId,
+      conversationId,
+      runId: running.id,
+      role: "assistant",
+      status: "streaming",
+      parts: [{ type: "text", text: "checkpoint" }],
+      createdAt: "2026-08-22T00:00:00.000Z",
+      updatedAt: "2026-08-22T00:00:01.000Z"
+    }),
+    usage: {
+      inputTokens: { value: 1000, provenance: "provider-reported" },
+      outputTokens: { value: 100, provenance: "provider-reported" },
+      cost: { value: 0.25, currency: "USD", provenance: "provider-reported" }
+    }
+  });
+  requireOutcome(checkpoint, "applied");
+  const checkpointedRun = checkpoint.snapshot.runs.find((run) => run.id === running.id);
+  if (!checkpointedRun)
+    throw new Error("Checkpointed run disappeared");
+  if (checkpointedRun.usage?.cost?.value !== 0.25) {
+    throw new Error("Checkpoint did not persist the run usage it was given");
+  }
+  const terminalAssistant = AgentMessageSchema.parse({
+    schemaVersion: 1,
+    id: running.assistantMessageId,
+    conversationId,
+    runId: running.id,
+    role: "assistant",
+    status: "completed",
+    parts: [{ type: "text", text: "done" }],
+    createdAt: "2026-08-22T00:00:00.000Z",
+    updatedAt: "2026-08-22T00:00:02.000Z"
+  });
+  if (checkpointedRun.fencingToken === undefined) {
+    throw new Error("Acquisition must persist a fencing token the store can read back");
+  }
+  const staleFence = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision,
+    ownerId: "conformance-owner",
+    fencingToken: checkpointedRun.fencingToken + 1,
+    assistant: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: running.assistantMessageId,
+      conversationId,
+      runId: running.id,
+      role: "assistant",
+      status: "streaming",
+      parts: [{ type: "text", text: "stale fence" }],
+      createdAt: "2026-08-22T00:00:00.000Z",
+      updatedAt: "2026-08-22T00:00:01.500Z"
+    })
+  });
+  if (staleFence.outcome !== "conflict") {
+    throw new Error("A checkpoint with a stale fencing token must conflict");
+  }
+  const foreignOwner = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision,
+    ownerId: "a-different-runtime",
+    assistant: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: running.assistantMessageId,
+      conversationId,
+      runId: running.id,
+      role: "assistant",
+      status: "streaming",
+      parts: [{ type: "text", text: "foreign owner" }],
+      createdAt: "2026-08-22T00:00:00.000Z",
+      updatedAt: "2026-08-22T00:00:01.700Z"
+    })
+  });
+  if (foreignOwner.outcome !== "conflict") {
+    throw new Error("A checkpoint from another owner must conflict");
+  }
+  return { running, checkpoint, checkpointedRun, terminalAssistant };
+}
+async function boundedReadsPhase(store, conversationId, absentConversationId, checkpointed) {
+  const { running, checkpoint, checkpointedRun } = checkpointed;
+  const liveView = await store.loadRun({ conversationId, runId: running.id });
+  if (!liveView)
+    throw new Error("loadRun must find a run of this conversation");
+  if (liveView.run.id !== running.id || liveView.run.conversationId !== conversationId) {
+    throw new Error("loadRun returned a run it was not asked for");
+  }
+  if (liveView.run.revision !== checkpointedRun.revision) {
+    throw new Error("loadRun must return the run as the last mutation left it");
+  }
+  if (liveView.run.usage?.cost?.value !== 0.25) {
+    throw new Error("loadRun must carry the figure the run has spent so far");
+  }
+  if (liveView.snapshotVersion !== checkpoint.snapshot.version) {
+    throw new Error("loadRun must report the conversation version it read at");
+  }
+  if (liveView.assistant !== undefined) {
+    throw new Error("loadRun must not report a terminal answer for a live run");
+  }
+  if (await store.loadRun({ conversationId, runId: "no-such-run" })) {
+    throw new Error("loadRun must return undefined for an unknown run");
+  }
+  if (await store.loadRun({ conversationId: absentConversationId, runId: running.id })) {
+    throw new Error("loadRun must not cross conversation boundaries");
+  }
+  const activeRuns = await store.listActiveRuns(conversationId);
+  if (!activeRuns.some((run) => run.id === running.id)) {
+    throw new Error("listActiveRuns must report a run that is in flight");
+  }
+  if (activeRuns.some((run) => run.terminalReason !== undefined)) {
+    throw new Error("listActiveRuns must not report a run that has ended");
+  }
+  for (let index = 1;index < activeRuns.length; index += 1) {
+    const previous = activeRuns[index - 1];
+    const current = activeRuns[index];
+    if (!previous || !current)
+      continue;
+    const ordered = previous.createdAt === current.createdAt ? previous.id.localeCompare(current.id) < 0 : previous.createdAt < current.createdAt;
+    if (!ordered) {
+      throw new Error("listActiveRuns must order by createdAt and then by id");
+    }
+  }
+  if ((await store.listActiveRuns(absentConversationId)).length !== 0) {
+    throw new Error("listActiveRuns must be empty for an unknown conversation");
+  }
+}
+async function interruptPhase(store, conversationId, checkpointed) {
+  const { running, checkpointedRun } = checkpointed;
+  const recoverable = await store.scanRecoverable({ limit: 10 });
+  if (!recoverable.items.some((item) => item.run.id === running.id)) {
+    throw new Error("A running run must appear in a recoverable scan");
+  }
+  const operation = await store.recordRunOperation({
+    conversationId,
+    runId: running.id,
+    expectedRevision: checkpointedRun.revision,
+    ownerId: "conformance-owner",
+    fencingToken: checkpointedRun.fencingToken,
+    operation: {
+      operationId: "model-call-1:0",
+      kind: "model-request",
+      phase: "first-output",
+      step: 0,
+      startedAt: "2026-08-22T00:00:01.800Z",
+      firstOutputAt: "2026-08-22T00:00:01.900Z"
+    }
+  });
+  requireOutcome(operation, "applied");
+  const operatedRun = operation.snapshot.runs.find((run) => run.id === running.id);
+  if (operatedRun?.lastOperation?.operationId !== "model-call-1:0") {
+    throw new Error("Run operation identity did not survive its durable mutation");
+  }
+  const operatedView = await store.loadRun({ conversationId, runId: running.id });
+  if (operatedView?.run.lastOperation?.startedAt !== "2026-08-22T00:00:01.800Z") {
+    throw new Error("loadRun did not retain the original operation timestamp");
+  }
+  const interrupted = await store.requestRunInterrupt({
+    conversationId,
+    runId: running.id,
+    expectedRevision: operatedRun.revision
+  });
+  requireOutcome(interrupted, "applied");
+  const interruptedRun = interrupted.snapshot.runs.find((run) => run.id === running.id);
+  if (interruptedRun?.state !== "interrupt_requested") {
+    throw new Error("A durable interrupt must move the run to interrupt_requested");
+  }
+  if (interruptedRun.usage?.cost?.value !== 0.25) {
+    throw new Error("An interrupt must not discard the figure the run had already spent");
+  }
+  return interruptedRun;
+}
+
+// src/agent-runtime/store-conformance-ordering.ts
+async function assertInterruptPriorityOrder(store, conversationId) {
+  const inputs = ["priority-a", "priority-b", "priority-c"].map((id) => userMessage(conversationId, id));
+  const [inputA, inputB, inputC] = inputs;
+  if (!inputA || !inputB || !inputC)
+    throw new Error("Priority fixture is incomplete");
+  const runA = queuedRun(conversationId, inputA.id, "priority-run-a");
+  const runB = queuedRun(conversationId, inputB.id, "priority-run-b");
+  const runC = AgentRunSchema.parse({
+    ...queuedRun(conversationId, inputC.id, "priority-run-c"),
+    queuePriority: "interrupt-next"
+  });
+  requireOutcome(await store.acceptInputAndAssignRun({ idempotencyKey: runA.id, input: inputA, run: runA }), "applied");
+  const acquiredA = await store.acquireRun({
+    conversationId,
+    runId: runA.id,
+    expectedRevision: runA.revision,
+    ownerId: "priority-owner-a"
+  });
+  requireOutcome(acquiredA, "applied");
+  const runningA = acquiredA.snapshot.runs.find((run) => run.id === runA.id);
+  if (!runningA)
+    throw new Error("Priority lead run disappeared after acquisition");
+  requireOutcome(await store.acceptInputAndAssignRun({ idempotencyKey: runB.id, input: inputB, run: runB }), "applied");
+  requireOutcome(await store.acceptInputAndAssignRun({ idempotencyKey: runC.id, input: inputC, run: runC }), "applied");
+  const active = await store.listActiveRuns(conversationId);
+  if (active.map((run) => run.id).join(",") !== `${runA.id},${runC.id},${runB.id}`) {
+    throw new Error("Active runs did not place urgent work before ordinary pending work");
+  }
+  requireOutcome(await store.acquireRun({
+    conversationId,
+    runId: runB.id,
+    expectedRevision: runB.revision,
+    ownerId: "priority-owner-b"
+  }), "conflict");
+  const abandonedA = await store.recoverRun({
+    conversationId,
+    runId: runA.id,
+    expectedRevision: runningA.revision,
+    action: "abandon"
+  });
+  requireOutcome(abandonedA, "applied");
+  const queuedC = abandonedA.snapshot.runs.find((run) => run.id === runC.id);
+  if (!queuedC)
+    throw new Error("Urgent run disappeared after predecessor settlement");
+  const acquiredC = await store.acquireRun({
+    conversationId,
+    runId: runC.id,
+    expectedRevision: queuedC.revision,
+    ownerId: "priority-owner-c"
+  });
+  requireOutcome(acquiredC, "applied");
+  const runningC = acquiredC.snapshot.runs.find((run) => run.id === runC.id);
+  if (!runningC)
+    throw new Error("Urgent run disappeared after acquisition");
+  requireOutcome(await store.acquireRun({
+    conversationId,
+    runId: runB.id,
+    expectedRevision: runB.revision,
+    ownerId: "priority-owner-b"
+  }), "conflict");
+  const abandonedC = await store.recoverRun({
+    conversationId,
+    runId: runC.id,
+    expectedRevision: runningC.revision,
+    action: "abandon"
+  });
+  requireOutcome(abandonedC, "applied");
+  const queuedB = abandonedC.snapshot.runs.find((run) => run.id === runB.id);
+  if (!queuedB)
+    throw new Error("Ordinary run disappeared after urgent settlement");
+  const acquiredB = await store.acquireRun({
+    conversationId,
+    runId: runB.id,
+    expectedRevision: queuedB.revision,
+    ownerId: "priority-owner-b"
+  });
+  requireOutcome(acquiredB, "applied");
+  const ordered = acquiredB.snapshot.runs.map((run) => run.id).join(",");
+  if (ordered !== `${runA.id},${runC.id},${runB.id}`) {
+    throw new Error(`Durable execution order was not preserved: ${ordered}`);
+  }
+  const [sequenceA, sequenceC, sequenceB] = acquiredB.snapshot.runs.map((run) => run.executionSequence);
+  if (sequenceA === undefined || sequenceC === undefined || sequenceB === undefined || !(sequenceA < sequenceC && sequenceC < sequenceB)) {
+    throw new Error("Acquisition did not persist increasing execution sequence values");
+  }
+}
+async function assertActiveRunCausalOrder(store, conversationId) {
+  for (const id of ["z-causal-run", "a-causal-run"]) {
+    const input = userMessage(conversationId, `${id}-input`);
+    requireOutcome(await store.acceptInputAndAssignRun({
+      idempotencyKey: id,
+      input,
+      run: queuedRun(conversationId, input.id, id)
+    }), "applied");
+  }
+  const active = await store.listActiveRuns(conversationId);
+  if (active.map((run) => run.id).join(",") !== "z-causal-run,a-causal-run") {
+    throw new Error("listActiveRuns must preserve causal history order for timestamp ties");
+  }
+}
+async function assertCausalHistoryOrder(store, conversationId) {
+  const leadInput = userMessage(conversationId, "causal-input-1");
+  const leadRun = queuedRun(conversationId, leadInput.id, "causal-run-1");
+  requireOutcome(await store.acceptInputAndAssignRun({
+    idempotencyKey: "causal-request-1",
+    input: leadInput,
+    run: leadRun
+  }), "applied");
+  const acquired = await store.acquireRun({
+    conversationId,
+    runId: leadRun.id,
+    expectedRevision: leadRun.revision,
+    ownerId: "causal-owner"
+  });
+  requireOutcome(acquired, "applied");
+  const running = acquired.snapshot.runs.find((run) => run.id === leadRun.id);
+  if (!running)
+    throw new Error("Causal-order run disappeared after acquisition");
+  const successorInput = userMessage(conversationId, "causal-input-2");
+  const successorRun = queuedRun(conversationId, successorInput.id, "causal-run-2");
+  requireOutcome(await store.acceptInputAndAssignRun({
+    idempotencyKey: "causal-request-2",
+    input: successorInput,
+    run: successorRun
+  }), "applied");
+  const assistant = AgentMessageSchema.parse({
+    schemaVersion: 1,
+    id: running.assistantMessageId,
+    conversationId,
+    runId: running.id,
+    role: "assistant",
+    status: "streaming",
+    parts: [{ type: "text", text: "causal answer" }],
+    createdAt: "2026-08-28T00:00:00.000Z",
+    updatedAt: "2026-08-28T00:00:01.000Z"
+  });
+  const checkpoint = await store.checkpointRunAssistant({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "causal-owner",
+    ...running.fencingToken !== undefined && { fencingToken: running.fencingToken },
+    assistant
+  });
+  requireOutcome(checkpoint, "applied");
+  const order = checkpoint.snapshot.messages.map((message) => message.id).join(",");
+  if (order !== `${leadInput.id},${assistant.id},${successorInput.id}`) {
+    throw new Error(`Agent history is not in causal run order: ${order}`);
+  }
+}
+async function assertAbsorptionIsAtomic(store, conversationId) {
+  const leadInput = userMessage(conversationId, "absorb-input-1");
+  const leadRun = queuedRun(conversationId, leadInput.id, "absorb-run-1");
+  const lead = await store.acceptInputAndAssignRun({
+    idempotencyKey: "absorb-request-1",
+    input: leadInput,
+    run: leadRun
+  });
+  requireOutcome(lead, "applied");
+  const successorInput = userMessage(conversationId, "absorb-input-2");
+  const successorRun = queuedRun(conversationId, successorInput.id, "absorb-run-2");
+  const successor = await store.acceptInputAndAssignRun({
+    idempotencyKey: "absorb-request-2",
+    input: successorInput,
+    run: successorRun
+  });
+  requireOutcome(successor, "applied");
+  const acquired = await store.acquireRun({
+    conversationId,
+    runId: leadRun.id,
+    expectedRevision: 0,
+    ownerId: "absorb-owner"
+  });
+  requireOutcome(acquired, "applied");
+  const running = acquired.snapshot.runs.find((run) => run.id === leadRun.id);
+  if (!running)
+    throw new Error("Absorbing run disappeared after acquisition");
+  const answer = AgentMessageSchema.parse({
+    schemaVersion: 1,
+    id: running.assistantMessageId,
+    conversationId,
+    runId: running.id,
+    role: "assistant",
+    status: "completed",
+    parts: [{ type: "text", text: "answered both" }],
+    createdAt: "2026-08-26T00:00:00.000Z",
+    updatedAt: "2026-08-26T00:00:02.000Z"
+  });
+  await store.commitRunTerminal({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "absorb-owner",
+    assistant: AgentMessageSchema.parse({ ...answer, status: "interrupted" }),
+    reason: "interrupted",
+    absorb: [{ runId: successorRun.id, inputMessageIds: [successorInput.id] }]
+  }).then(() => {
+    throw new Error("A non-completing run absorbed a queued successor");
+  }, (error) => {
+    if (!(error instanceof TypeError))
+      throw error;
+  });
+  const committed = await store.commitRunTerminal({
+    conversationId,
+    runId: running.id,
+    expectedRevision: running.revision,
+    ownerId: "absorb-owner",
+    assistant: answer,
+    reason: "success",
+    absorb: [{ runId: successorRun.id, inputMessageIds: [successorInput.id] }]
+  });
+  requireOutcome(committed, "applied");
+  const absorbingView = await store.loadRun({ conversationId, runId: leadRun.id });
+  if (absorbingView?.run.inputMessageIds.join(",") !== "absorb-input-1,absorb-input-2") {
+    throw new Error("An absorbing run must record the inputs it answered");
+  }
+  const absorbedView = await store.loadRun({ conversationId, runId: successorRun.id });
+  if (absorbedView?.run.terminalReason !== "absorbed") {
+    throw new Error("An absorbed successor must be terminal in the same transaction");
+  }
+  if (absorbedView.run.absorbedIntoRunId !== leadRun.id) {
+    throw new Error("An absorbed run must name the run that answered its input");
+  }
+  if (absorbedView.assistant !== undefined) {
+    throw new Error("An absorbed run produced no answer and must retain none");
+  }
+  if ((await store.listActiveRuns(conversationId)).length !== 0) {
+    throw new Error("An absorbed successor must leave the active listing");
+  }
+  const retried = await store.acceptInputAndAssignRun({
+    idempotencyKey: "absorb-request-2",
+    input: userMessage(conversationId, "absorb-discarded"),
+    run: queuedRun(conversationId, "absorb-discarded", "absorb-discarded-run")
+  });
+  requireOutcome(retried, "duplicate");
+  if (retried.runId !== leadRun.id || retried.assistant?.id !== answer.id) {
+    throw new Error("A retried absorbed key must resolve to the run that answered it");
+  }
+  if (retried.inputMessageId !== successorInput.id) {
+    throw new Error("A retried absorbed key must still name its own input");
+  }
+}
+
+// src/agent-runtime/store-conformance-terminal.ts
+async function terminalPhase(store, conversationId, checkpointed, interruptedRun) {
+  const { running, terminalAssistant } = checkpointed;
+  const terminalUsage = {
+    inputTokens: { value: 3000, provenance: "computed" },
+    outputTokens: { value: 300, provenance: "computed" },
+    reasoningTokens: { value: 30, provenance: "computed" },
+    cacheReadTokens: { value: 200, provenance: "computed" },
+    cacheWriteTokens: { value: 100, provenance: "computed" },
+    cost: { value: 1.5, currency: "USD", provenance: "computed" }
+  };
+  const terminalResults = await Promise.all([
+    store.commitRunTerminal({
+      conversationId,
+      runId: running.id,
+      expectedRevision: interruptedRun.revision,
+      ownerId: "conformance-owner",
+      assistant: terminalAssistant,
+      reason: "success",
+      usage: terminalUsage
+    }),
+    store.commitRunTerminal({
+      conversationId,
+      runId: running.id,
+      expectedRevision: interruptedRun.revision,
+      ownerId: "conformance-owner",
+      assistant: terminalAssistant,
+      reason: "success",
+      usage: terminalUsage
+    })
+  ]);
+  const terminalOutcomes = terminalResults.map((result) => result.outcome).sort();
+  if (terminalOutcomes.join(",") !== "applied,conflict") {
+    throw new Error(`Terminal race was not linearized: ${terminalOutcomes.join(",")}`);
+  }
+  const terminalApplied = terminalResults.find((result) => result.outcome === "applied");
+  if (terminalApplied?.outcome !== "applied") {
+    throw new Error("Terminal race produced no applied result");
+  }
+  const settledRun = terminalApplied.snapshot.runs.find((run) => run.id === running.id);
+  if (JSON.stringify(settledRun?.usage) !== JSON.stringify(terminalUsage)) {
+    throw new Error("Terminal commit did not persist the run usage it was given");
+  }
+  const terminalView = await store.loadRun({ conversationId, runId: running.id });
+  if (terminalView?.run.terminalReason !== "success") {
+    throw new Error("loadRun must report the terminal reason a settled run ended with");
+  }
+  if (JSON.stringify(terminalView.run.usage) !== JSON.stringify(terminalUsage)) {
+    throw new Error("loadRun must return every persisted terminal usage field");
+  }
+  if (JSON.stringify(terminalView.assistant) !== JSON.stringify(terminalAssistant)) {
+    throw new Error("loadRun must retain the answer a settled run produced");
+  }
+  if ((await store.listActiveRuns(conversationId)).some((run) => run.id === running.id)) {
+    throw new Error("listActiveRuns must drop a run once it has ended");
+  }
+  const compactedTerminal = await store.replaceCompactedRange({
+    conversationId,
+    expectedVersion: terminalApplied.snapshot.version,
+    replacedMessageIds: ["summary-1", terminalAssistant.id],
+    summary: AgentMessageSchema.parse({
+      schemaVersion: 1,
+      id: "summary-2",
+      conversationId,
+      role: "summary",
+      status: "committed",
+      parts: [{ type: "text", text: "terminal history" }],
+      createdAt: "2026-08-22T00:00:03.000Z",
+      updatedAt: "2026-08-22T00:00:03.000Z"
+    })
+  });
+  requireOutcome(compactedTerminal, "applied");
+  const duplicateTerminal = await store.acceptInputAndAssignRun({
+    idempotencyKey: "request-1",
+    input: userMessage(conversationId, "discarded-terminal-input"),
+    run: queuedRun(conversationId, "discarded-terminal-input", "discarded-terminal-run")
+  });
+  requireOutcome(duplicateTerminal, "duplicate");
+  if (duplicateTerminal.run.terminalReason !== "success" || JSON.stringify(duplicateTerminal.assistant) !== JSON.stringify(terminalAssistant)) {
+    throw new Error("Compaction discarded the canonical duplicate terminal result");
+  }
+}
+async function abandonPhase(store, recoveryConversationId) {
+  const recoveryInput = userMessage(recoveryConversationId, "recovery-input");
+  const recoveryRun = queuedRun(recoveryConversationId, recoveryInput.id, "recovery-run");
+  const recoveryAccepted = await store.acceptInputAndAssignRun({
+    idempotencyKey: "recovery-request",
+    input: recoveryInput,
+    run: recoveryRun
+  });
+  requireOutcome(recoveryAccepted, "applied");
+  const recoveryAssigned = recoveryAccepted.snapshot.runs.find((run) => run.id === recoveryRun.id);
+  if (!recoveryAssigned)
+    throw new Error("Recovery run disappeared after admission");
+  const recoveryAcquired = await store.acquireRun({
+    conversationId: recoveryConversationId,
+    runId: recoveryAssigned.id,
+    expectedRevision: recoveryAssigned.revision,
+    ownerId: "abandoned-owner"
+  });
+  requireOutcome(recoveryAcquired, "applied");
+  const abandonedRun = recoveryAcquired.snapshot.runs.find((run) => run.id === recoveryRun.id);
+  if (!abandonedRun)
+    throw new Error("Recovery run disappeared after acquisition");
+  const abandoned = await store.recoverRun({
+    conversationId: recoveryConversationId,
+    runId: abandonedRun.id,
+    expectedRevision: abandonedRun.revision,
+    action: "abandon"
+  });
+  requireOutcome(abandoned, "applied");
+  const terminalRun = abandoned.snapshot.runs.find((run) => run.id === abandonedRun.id);
+  const terminalMessage = abandoned.snapshot.messages.find((message) => message.id === abandonedRun.assistantMessageId);
+  if (terminalRun?.state !== "abandoned" || terminalMessage?.status !== "failed") {
+    throw new Error("Abandon recovery did not atomically terminalize its assistant record");
+  }
+  const abandonedView = await store.loadRun({
+    conversationId: recoveryConversationId,
+    runId: abandonedRun.id
+  });
+  if (abandonedView?.run.state !== "abandoned" || abandonedView.run.terminalReason !== "abandoned" || abandonedView.assistant?.status !== "failed") {
+    throw new Error("The canonical run record disagrees with its abandoned index projection");
+  }
+  const afterAbandon = await store.scanRecoverable({ limit: 100 });
+  if (afterAbandon.items.some((item) => item.run.id === abandonedRun.id)) {
+    throw new Error("The recoverable index still exposes a canonically abandoned run");
+  }
+}
+
+// src/agent-runtime/store-conformance.ts
+async function runAgentStoreConformance(config) {
+  const run = `conformance-${crypto.randomUUID()}`;
+  const context = {
+    conversationIds: [
+      run,
+      `${run}-recovery`,
+      `${run}-absorb`,
+      `${run}-causal-history`,
+      `${run}-causal-active`,
+      `${run}-interrupt-priority`,
+      `${run}-ledger`,
+      `${run}-archive`,
+      `${run}-seed`
+    ]
+  };
+  const store = await config.createStore(context);
+  let failure;
+  try {
+    await conformanceScenario(store, context.conversationIds);
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    await config.cleanup?.(context);
+  } catch (cleanupError) {
+    if (failure === undefined)
+      throw cleanupError;
+    throw new AggregateError([failure, cleanupError], `${failure instanceof Error ? failure.message : String(failure)} (cleanup also failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)})`);
+  }
+  if (failure !== undefined)
+    throw failure;
+}
+async function seedScenario(store, conversationId) {
+  const input = {
+    conversationId,
+    seedKey: "brief",
+    inputs: [userMessage(conversationId, "seed-a"), userMessage(conversationId, "seed-b")]
+  };
+  const first = await store.seedConversationInput(input);
+  requireOutcome(first, "applied");
+  const before = await store.loadSnapshot(conversationId);
+  if (before.messages.map((message) => message.id).join(",") !== "seed-a,seed-b")
+    throw new Error("Seed conformance: complete ordered seed missing");
+  await Promise.all([store.seedConversationInput(input), store.seedConversationInput(input)]);
+  const repeated = await store.loadSnapshot(conversationId);
+  if (repeated.version !== before.version || repeated.messages.length !== 2)
+    throw new Error("Seed conformance: replay changed history");
+  const compacted = await store.replaceCompactedRange({
+    conversationId,
+    expectedVersion: repeated.version,
+    replacedMessageIds: ["seed-a", "seed-b"],
+    summary: AgentMessageSchema.parse({
+      ...userMessage(conversationId, "seed-summary"),
+      role: "summary"
+    })
+  });
+  requireOutcome(compacted, "applied");
+  await store.seedConversationInput(input);
+  const after = await store.loadSnapshot(conversationId);
+  if (after.messages.some((message) => message.id === "seed-a" || message.id === "seed-b"))
+    throw new Error("Seed conformance: compacted instructions resurrected");
+}
+async function conformanceScenario(store, conversationIds) {
+  const [
+    conversationId,
+    recoveryConversationId,
+    absorbConversationId,
+    causalHistoryConversationId,
+    causalActiveConversationId,
+    interruptPriorityConversationId,
+    ledgerConversationId,
+    archiveConversationId,
+    seedConversationId
+  ] = conversationIds;
+  if (seedConversationId)
+    await seedScenario(store, seedConversationId);
+  if (ledgerConversationId)
+    await ledgerScenario(store, ledgerConversationId);
+  if (archiveConversationId)
+    await archiveScenario(store, archiveConversationId);
+  if (!conversationId || !recoveryConversationId || !absorbConversationId || !causalHistoryConversationId || !causalActiveConversationId || !interruptPriorityConversationId) {
+    throw new Error("Agent store conformance requires six conversation identities");
+  }
+  const absentConversationId = `${conversationId}-absent`;
+  const assigned = await admissionPhase(store, conversationId);
+  const checkpointed = await fencingPhase(store, conversationId, assigned);
+  await boundedReadsPhase(store, conversationId, absentConversationId, checkpointed);
+  const interruptedRun = await interruptPhase(store, conversationId, checkpointed);
+  await terminalPhase(store, conversationId, checkpointed, interruptedRun);
+  await abandonPhase(store, recoveryConversationId);
+  await assertCausalHistoryOrder(store, causalHistoryConversationId);
+  await assertActiveRunCausalOrder(store, causalActiveConversationId);
+  await assertInterruptPriorityOrder(store, interruptPriorityConversationId);
+  await assertAbsorptionIsAtomic(store, absorbConversationId);
+}
+async function ledgerScenario(store, conversationId) {
+  const first = await store.appendEvent({
+    conversationId,
+    kind: "state/set",
+    payload: { n: 1 }
+  });
+  if (first.seq !== 1)
+    throw new Error(`Agent store conformance expected seq 1, received ${first.seq}`);
+  const appended = await Promise.all(Array.from({ length: 20 }, (_, index) => store.appendEvent({ conversationId, kind: "state/set", payload: { n: index + 2 } })));
+  const seqs = [first.seq, ...appended.map((event) => event.seq)].sort((a, b) => a - b);
+  for (let index = 0;index < seqs.length; index += 1) {
+    if (seqs[index] !== index + 1) {
+      throw new Error(`Agent store conformance expected contiguous seq, received ${seqs.join(",")}`);
+    }
+  }
+  const page = await store.readEvents({ conversationId, fromSeq: 5, toSeq: 9, limit: 3 });
+  if (page.items.map((event) => event.seq).join(",") !== "5,6,7" || page.nextSeq !== 8) {
+    throw new Error(`Agent store conformance expected events 5,6,7 then 8, received ${page.items.map((event) => event.seq).join(",")} then ${page.nextSeq}`);
+  }
+  const ignorable = await store.appendEvent({
+    conversationId,
+    kind: "state/set",
+    payload: { n: "ignorable" },
+    ignorable: true
+  });
+  if (ignorable.ignorable !== true) {
+    throw new Error("Agent store conformance expected the ignorable flag to persist");
+  }
+  const archive = await store.exportConversation(conversationId);
+  const again = await store.exportConversation(conversationId);
+  if (Buffer.compare(Buffer.from(archive), Buffer.from(again)) !== 0) {
+    throw new Error("Agent store conformance expected two exports of a quiet store to be byte-equal");
+  }
+  const decoded = decodeAgentConversationArchive(archive);
+  if (decoded.events.length !== 22) {
+    throw new Error(`Agent store conformance expected 22 archived events, received ${decoded.events.length}`);
+  }
+}
+async function archiveScenario(store, conversationId) {
+  const origin = createMemoryAgentRuntimeStore();
+  const inputMessage = userMessage(conversationId, "archived-input");
+  const run = queuedRun(conversationId, inputMessage.id, "archived-run");
+  requireOutcome(await origin.acceptInputAndAssignRun({
+    idempotencyKey: "archived-request",
+    input: inputMessage,
+    run
+  }), "applied");
+  await origin.appendEvent({
+    conversationId,
+    kind: "state/set",
+    payload: { name: "topic", value: "archive" }
+  });
+  const imported = await store.importConversation(await origin.exportConversation(conversationId));
+  if (imported.conversationId !== conversationId || imported.events !== 2) {
+    throw new Error(`Agent store conformance expected 2 imported events for ${conversationId}, received ${imported.events} for ${imported.conversationId}`);
+  }
+  const restored = await store.loadSnapshot(conversationId);
+  const expected = await origin.loadSnapshot(conversationId);
+  if (restored.version !== expected.version || restored.messages.map((message) => message.id).join(",") !== expected.messages.map((message) => message.id).join(",") || restored.runs.map((entry) => `${entry.id}:${entry.state}`).join(",") !== expected.runs.map((entry) => `${entry.id}:${entry.state}`).join(",")) {
+    throw new Error(`Agent store conformance expected the imported snapshot to match its archive, received version ${restored.version} with ${restored.messages.length} messages and ${restored.runs.length} runs`);
+  }
+  const events = await store.readEvents({ conversationId, limit: 10 });
+  if (events.items.map((event) => event.kind).join(",") !== "runtime/transition,state/set") {
+    throw new Error(`Agent store conformance expected the imported ledger to keep its kinds, received ${events.items.map((event) => event.kind).join(",")}`);
+  }
+}
+// src/agent-runtime/testing.ts
+function createAgentRaceBarrier(timeoutMs = 5000) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw new TypeError("Agent race barrier timeoutMs must be a positive safe integer");
+  }
+  const reached = Promise.withResolvers();
+  const released = Promise.withResolvers();
+  let announced = false;
+  return {
+    reached: reached.promise,
+    async wait() {
+      if (!announced) {
+        announced = true;
+        reached.resolve();
+      }
+      let timer;
+      try {
+        await Promise.race([
+          released.promise,
+          new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error(`Agent race barrier exceeded ${timeoutMs}ms teardown bound`)), timeoutMs);
+          })
+        ]);
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+      }
+    },
+    release: released.resolve
+  };
+}
+function createAgentRaceTrace() {
+  const recorded = [];
+  return {
+    record(name) {
+      const entry = { name, sequence: recorded.length };
+      recorded.push(entry);
+      return entry;
+    },
+    entries: () => recorded.map((entry) => ({ ...entry })),
+    assertBefore(first, second) {
+      const firstEntry = recorded.find((entry) => entry.name === first);
+      const secondEntry = recorded.find((entry) => entry.name === second);
+      if (!firstEntry || !secondEntry || firstEntry.sequence >= secondEntry.sequence) {
+        throw new Error(`Expected ${first} before ${second}`);
+      }
+    },
+    assertSequence(names) {
+      const actual = recorded.map((entry) => entry.name);
+      if (actual.length !== names.length || actual.some((name, index) => name !== names[index])) {
+        throw new Error(`Expected trace ${names.join(" -> ")}, received ${actual.join(" -> ")}`);
+      }
+    },
+    count: (name) => recorded.filter((entry) => entry.name === name).length
+  };
+}
+function createAgentRaceDriver(timeoutMs = 5000) {
+  const trace = createAgentRaceTrace();
+  const barriers = new Map;
+  return {
+    trace,
+    barrier(name) {
+      const existing = barriers.get(name);
+      if (existing)
+        return existing;
+      const created = createAgentRaceBarrier(timeoutMs);
+      barriers.set(name, created);
+      return created;
+    },
+    releaseAll() {
+      for (const barrier of barriers.values())
+        barrier.release();
+    }
+  };
+}
+export {
+  runAgentStoreConformance,
+  defineAgentFaultPlan,
+  createReplayAgentProvider,
+  createFaultProviderServer,
+  createAgentRaceTrace,
+  createAgentRaceDriver,
+  createAgentRaceBarrier,
+  AgentFaultStepSchema
+};