stitchkit 0.57.0 → 0.59.0

package/dist/{index-1f4fcj0b.js → index-vtjgx3vv.js}

@@ -121,6 +121,7 @@ var AgentRunSchema = z.object({
   state: AgentRunStateSchema,
   revision: AgentRecordVersionSchema,
   ownerId: z.string().min(1).optional(),
+  fencingToken: AgentRecordVersionSchema.optional(),
   terminalReason: AgentTerminalReasonSchema.optional(),
   terminalPolicyName: z.string().min(1).optional(),
   createdAt: AgentTimestampSchema,

package/dist/testing/agent-store-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/agent-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAwCD,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CAuJf"}
+{"version":3,"file":"agent-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/agent-store-conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/D;AAwCD,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,IAAI,CAAC,CAmRf"}

package/dist/testing.d.ts

@@ -31,6 +31,7 @@ export declare function createHandlerTestClient<T extends Record<string, Endpoin
 export declare function createHandlerTestClients<T extends Record<string, ContractDef<Record<string, EndpointDef>, string>>, TServer = unknown, const K extends string = never>(config: HandlerTestClientsConfig<T, TServer, K>): {
     [P in keyof T]: ScopedHttpClient<T[P]['endpoints'], ScopedKeys<K>>;
 };
+export { type AgentRaceBarrier, type AgentRaceDriver, type AgentRaceTrace, type AgentRaceTraceEntry, createAgentRaceBarrier, createAgentRaceDriver, createAgentRaceTrace, } from './agent-runtime/testing';
 export { type AgentStoreConformanceConfig, runAgentStoreConformance, } from './testing/agent-store-conformance';
 export { assertSurfaceDiscovery, type ConformanceTransport, type CreateRealtimeProbeDriverConfig, createRealtimeProbeDriver, type DefineRealtimeProbeConfig, defineRealtimeProbe, type RealtimeDisconnectObservation, RealtimeDisconnectObservationSchema, type RealtimeProbeAdapter, type RealtimeProbeFixture, type RealtimeProbeScenario, type RealtimeRejectionObservation, RealtimeRejectionObservationSchema, type RunSurfaceProbesConfig, runSurfaceProbes, type SurfaceDiscoveryObservation, type SurfaceProbe, type SurfaceProbeDriver, type SurfaceRealtimeDiscoveryObservation, type SurfaceToolDiscoveryObservation, type TransportObservation, TransportObservationSchema, } from './testing/surface-conformance';
 export { assertSurfaceManifestSnapshot, buildSurfaceManifest, type IncompatibleSchemaPolicy, type McpSchemaValidationConfig, type SurfaceAgentProjection, type SurfaceManifest, type SurfaceManifestConfig, type SurfaceManifestExtension, SurfaceManifestExtensionSchema, type SurfaceManifestOperation, SurfaceManifestOperationSchema, type SurfaceManifestRealtimeEvent, SurfaceManifestRealtimeEventSchema, SurfaceManifestSchema, type SurfaceManifestTool, SurfaceManifestToolSchema, type SurfaceManifestToolSurface, SurfaceManifestToolSurfaceSchema, type SurfaceMcpPreparation, SurfaceRealtimeSchemaPairSchema, type SurfaceRuntimeToolDefinition, SurfaceSchemaDigestsSchema, type SurfaceToolDefinition, type SurfaceToolExtension, serializeSurfaceValue, } from './testing/surface-manifest';

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -1,7 +1,7 @@
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-1f4fcj0b.js";
+} from "./index-vtjgx3vv.js";
 import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
@@ -27,6 +27,81 @@ import {
 } from "./index-smpbdg6k.js";
 import"./index-1bx83sw4.js";
 
+// 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();
+    }
+  };
+}
 // src/testing/agent-store-conformance.ts
 function userMessage(conversationId, id) {
   return AgentMessageSchema.parse({
@@ -175,15 +250,131 @@ async function runAgentStoreConformance(config) {
     })
   });
   requireOutcome(stale, "conflict");
-  const abandoned = await store.recoverRun({
+  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"
+    })
+  });
+  requireOutcome(checkpoint, "applied");
+  const checkpointedRun = checkpoint.snapshot.runs.find((run) => run.id === running.id);
+  if (!checkpointedRun)
+    throw new Error("Checkpointed run disappeared");
+  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"
+  });
+  const terminalResults = await Promise.all([
+    store.commitRunTerminal({
+      conversationId,
+      runId: running.id,
+      expectedRevision: checkpointedRun.revision,
+      ownerId: "conformance-owner",
+      assistant: terminalAssistant,
+      reason: "success"
+    }),
+    store.commitRunTerminal({
+      conversationId,
+      runId: running.id,
+      expectedRevision: checkpointedRun.revision,
+      ownerId: "conformance-owner",
+      assistant: terminalAssistant,
+      reason: "success"
+    })
+  ]);
+  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 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");
+  }
+  const recoveryConversationId = `${conversationId}-recovery`;
+  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 === running.id);
-  const terminalMessage = abandoned.snapshot.messages.find((message) => message.id === running.assistantMessageId);
+  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");
   }
@@ -905,6 +1096,9 @@ export {
   assertSurfaceDiscovery,
   assertSurfaceManifestSnapshot,
   buildSurfaceManifest,
+  createAgentRaceBarrier,
+  createAgentRaceDriver,
+  createAgentRaceTrace,
   createHandlerTestClient,
   createHandlerTestClients,
   createRealtimeProbeDriver,

package/llms-full.txt

@@ -3427,7 +3427,10 @@ const prompt = composeAgentPrompt([
 const runtime = createAgentRuntime({
   protocol,
   store: createMemoryAgentRuntimeStore(),
-  models: { resolve: () => models.resolve('fast', ['tools']) },
+  models: {
+    preflight: () => models.preflight('fast', ['tools']),
+    resolve: () => models.resolve('fast', ['tools']),
+  },
   prompt: ({ context, signal, model }) =>
     prompt({
       context,
@@ -3497,29 +3500,40 @@ provide one database transaction driver:
 ```ts
 const store = createAgentRuntimeStore({
   transaction: work => db.transaction(tx => work(tx)),
-  state: {
-    load: (tx, conversationId) => loadRuntimeState(tx, conversationId),
-    compareAndSwap: (tx, operation) => casRuntimeState(tx, operation),
+  head: {
+    load: (tx, conversationId) => loadRuntimeHead(tx, conversationId),
+    compareAndSwap: (tx, operation) => casRuntimeHead(tx, operation),
+  },
+  runs: {
+    load: (tx, identity) => loadRun(tx, identity),
+    loadByAssistantMessageId: (tx, identity) => loadRunByAssistant(tx, identity),
+    loadMany: (tx, identities) => loadRuns(tx, identities),
+    listActive: (tx, conversationId) => listActiveRuns(tx, conversationId),
+    save: (tx, record) => saveRun(tx, record),
+  },
+  admissions: {
+    load: (tx, identity) => loadAdmission(tx, identity),
+    loadByInputMessageId: (tx, identity) => loadAdmissionByInput(tx, identity),
+    create: (tx, receipt) => createAdmission(tx, receipt),
   },
   history: {
     load: (tx, conversationId) => loadCanonicalMessages(tx, conversationId),
-    loadById: (tx, identity) => loadActiveOrArchivedMessage(tx, identity),
     apply: (tx, mutation) => applyCanonicalHistoryMutation(tx, mutation),
   },
   scanRecoverable: page => scanRecoverableRuns(page),
 })
 ```
 
-The same opaque `tx` reaches state and history callbacks. The adapter maps rows
+The same opaque `tx` reaches head, run, admission and history callbacks. The adapter maps rows
 and supplies atomicity; Stitchkit owns transition validation and revision
 arithmetic. The executable reference is
 [`examples/agent-store-prisma/adapter.ts`](../../examples/agent-store-prisma/adapter.ts).
 `compareAndSwap` returns either `{ outcome: 'applied' }` or
-`{ outcome: 'conflict', actualVersion }`; on a winning write it also persists the
-framework-provided `recoverable` descriptors in the same transaction. Recovery
-scans that bounded index instead of loading every aggregate. Compaction may hide
-rows from `history.load`, but `history.loadById` must retain canonical admitted
-inputs for durable duplicate receipts.
+`{ outcome: 'conflict', actualVersion }`. The head contains only schema version,
+conversation identity and monotonic version. Runs and admission receipts are normalized records;
+recovery queries active run states directly instead of maintaining a second projection.
+An admission receipt retains its canonical input, and a terminal run retains its canonical
+assistant, so physical product-history compaction cannot break idempotent retries.
 
 ## Durable order
 
@@ -3577,6 +3591,10 @@ Every mutation carries an expected run revision or snapshot version. Input
 assignment additionally carries an idempotency identity. A conflict is a
 control outcome; stale data is never silently overwritten.
 
+Acquisition increments an optional monotonic `fencingToken`. The managed runtime carries it through
+checkpoint/terminal CAS and tool context, so a distributed adapter can reject an old owner even if
+an owner label is reused. Lease expiry and renewal remain application-owned.
+
 On startup, `runtime.recover({ resolveContext })` consumes bounded lightweight
 pages. Its safe default resumes queued runs and reports acquired or
 `interrupt_requested` runs as skipped. A policy may requeue acquired work only
@@ -3613,6 +3631,12 @@ These are post-commit notifications, not a transactional outbox: a process can
 crash between the database commit and `publish`. Reconnect should load canonical
 state. Exactly-once external delivery remains an application-owned outbox.
 
+Durable event IDs are derived from run, event type and snapshot version. Use
+`advanceAgentRuntimeEventCursor` to classify accepted, duplicate and gap delivery; a gap triggers a
+snapshot reload. `createAgentRuntimeEventSink` adds a bounded failure-isolated lifecycle and typed
+projection/redaction hook. `onPublishError` records direct publisher failures without changing the
+already committed run.
+
 A named custom stop condition terminalizes with `policy_stop`; its `policyName`
 is persisted on the run and included in the terminal event/result. `max-steps`
 is the reserved built-in policy name. `loop.prepareStep` is the controlled AI
@@ -3643,6 +3667,14 @@ effect must be replay-safe.
 `projectAgentHistory` converts canonical engine records into provider-valid AI
 SDK messages and pairs tool calls/results. Provider-required metadata is kept
 in a versioned opaque envelope and omitted from product delivery by default.
+`projectAgentHistoryDetailed` additionally returns one inspectable decision per canonical record;
+leading assistant records, crash drafts and unmatched tool chronology are never silently passed to
+the provider.
+
+`selectAgentHistory` is the non-destructive context-window selector. It removes only whole oldest
+complete turns, protects system/summary, incomplete and configured recent turns, and reports every
+keep/remove reason with measured/estimated/unavailable token provenance. An oversized protected turn
+returns `oversized`; unavailable accounting returns `unavailable` without invented arithmetic.
 
 `ComposedAgentPrompt.instructions` accepts the AI SDK `Instructions` contract.
 Use `adaptInstructions` when a provider needs metadata on the system message:
@@ -3679,22 +3711,32 @@ provider system message. The consumer supplies the structured summary schema
 and prompt. Pass `previousSummary` for a direct call, or configure
 `readPreviousSummary` for runtime-managed compaction, to merge and atomically
 replace a leading summary on the next compaction.
+Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
+eligible range and recomputes the summary; the stale summary is never retried.
 
 ## Observability
 
 `createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
 reuses the same bounded sink lifecycle as request/tool observability without
 sending new event kinds to existing request sinks. Product events omit provider
-causes; the operator terminal event may include `internalCause`, so its sink
-must use internal retention and redaction policy.
+causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
+set `includeInternalCause` and own its retention policy.
 
 Usage values carry `provider-reported`, `computed`, `estimated` or
 `unavailable` provenance. Cost additionally carries an ISO currency code;
 OpenRouter-reported cost is normalized as USD. Missing values remain absent,
 never zero-filled.
 
-In-memory sink delivery is at-most-once per execution. Stable event IDs allow
-consumer dedupe; cross-crash exactly-once requires a durable outbox.
+The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
+outbox.
+
+## Deterministic race and adapter proof
+
+`stitchkit/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver` and
+`createAgentRaceTrace`. Barriers have bounded teardown, traces assert exact partial order, and the
+helpers are exercised from packed Bun and Node consumers. `runAgentStoreConformance` runs duplicate,
+coalescing, collision, stale checkpoint, replay safety, terminal race, compaction and recovery
+invariants against any fresh durable adapter.
 
 
 ==============================================================================
@@ -6545,33 +6587,43 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
-## Unreleased migration: complete agent admission identity
+## Unreleased migration: normalized agent runtime persistence
 
-Custom `AgentRuntimeStore` adapters must persist and return the input and
-assistant identities associated with an idempotency key:
+`AgentRuntimeStoreDriver` no longer reads and rewrites a lifetime `AgentStoredState` JSON
+aggregate. Migrate that row and its recoverable/archive projections once:
+
+1. Copy `conversationId` and `version` into the bounded runtime head.
+2. Write every `AgentStoredState.runs[]` entry as one normalized run record.
+3. Write every `AgentStoredState.admissions[]` entry as one admission receipt and copy its
+   canonical input into that receipt.
+4. For terminal runs, retain the canonical assistant on the run record before deleting any old
+   history/archive rows.
+5. Replace the recoverable projection with an index over normalized run `state`.
+6. Cut the adapter over atomically; there is no compatibility driver or dual-write mode.
 
 ```ts
 // before
-return { outcome: 'duplicate', runId, snapshot }
+createAgentRuntimeStore({
+  state: { load, compareAndSwap },
+  history: { load, loadById, apply },
+  scanRecoverable,
+})
 
 // after
-return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+createAgentRuntimeStore({
+  head: { load, compareAndSwap },
+  runs: { load, loadByAssistantMessageId, loadMany, listActive, save },
+  admissions: { load, loadByInputMessageId, create },
+  history: { load, apply },
+  scanRecoverable,
+})
 ```
 
-Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
-its `AgentStoredState.admissions` record and transaction driver implement this
-contract automatically. `history.loadById()` must retain access to compacted
-admitted inputs so the framework can return the canonical record.
-
-`AgentRuntimeEvent` also adds a post-commit `admission` variant. Add it to any
-exhaustive publisher switch. Its `assistant` is either the pending placeholder
-for a new assignment or the canonical persisted assistant for a duplicate:
-
-```ts
-case 'admission':
-  await persistProductProjection(event.input, event.run, event.assistant)
-  break
-```
+`AgentRuntimeHeadSchema`, `AgentStoredRunSchema` and `AgentAdmissionReceiptSchema` replace
+`AgentStoredStateSchema` and `AgentAdmissionIdentitySchema`. Run
+`runAgentStoreConformance()` against the migrated adapter before switching production traffic.
+If an application implements `AgentRuntimeStore` directly, its duplicate result must also include
+the canonical `run` and the retained `assistant` for a terminal run.
 
 ## Released migration: 0.56.0
 
@@ -8013,8 +8065,10 @@ Server-only optional application runtime. See the
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
-| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transactional state load/exact-version CAS, active-plus-archived history codec and bounded recoverable-run index scan |
-| `AgentStoredStateSchema` | schema | versioned runs and full idempotency admission identities without duplicated message history |
+| `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history and indexed run recovery |
+| `AgentRuntimeHeadSchema` | schema | constant-size conversation identity plus monotonic runtime version |
+| `AgentStoredRunSchema` | schema | canonical normalized run with an optional retained terminal assistant |
+| `AgentAdmissionReceiptSchema` | schema | durable idempotency receipt with canonical input and assigned run/assistant identities |
 | `AgentHistoryMutationSchema` | schema | typed canonical message mutation applied inside the winning state transaction |
 | `RecoverAgentRunSchema` | schema | explicit abandon/requeue recovery decision; acquired runs require replay-safe evidence |
 | `createMemoryAgentRuntimeStore` | function | process-local reference adapter, not production durability |
@@ -8036,6 +8090,70 @@ Server-only optional application runtime. See the
 | `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/terminal projections |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 
+### Complete runtime inventory
+
+The entrypoint deliberately exports the schemas beside their inferred types so persistence and
+transport adapters validate the same records. Runtime composition types are `AgentRuntime`,
+`AgentRuntimeConfig`, `AgentRuntimeInput`, `AgentRuntimeProtocolInput`, `AgentRuntimeRunContext`,
+`AgentRuntimeResult`, `AgentRuntimeInterruptInput`, `AgentRuntimeRecoveryInput`,
+`AgentRuntimeRecoveryDecision`, `AgentRuntimeRecoveryOutcome`, `AgentRuntimePublisher`,
+`AgentInputPolicy`, `AgentStopReason`, `AgentCoordinatedRun`, `AgentRunTicket`,
+`AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
+`StructuredCompactionConfig`.
+
+Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentRecordIdSchema`, `AgentRecordVersionSchema`,
+`AgentTimestampSchema`, `AgentJsonObjectSchema`, `AgentProviderEnvelopeSchema`,
+`AgentProviderEnvelope`, `AgentMessagePartSchema`, `AgentMessagePart`, `AgentTextPartSchema`,
+`AgentReasoningPartSchema`, `AgentFilePartSchema`, `AgentSourcePartSchema`,
+`AgentToolCallPartSchema`, `AgentToolResultPartSchema`, `AgentOpaquePartSchema`,
+`AgentControlPartSchema`, `AgentMessageRoleSchema`, `AgentMessageStatusSchema`, `AgentMessage`,
+`AgentAssistantPlaceholderSchema`, `AgentAssistantPlaceholder`, `AgentRunStateSchema`,
+`AgentTerminalReasonSchema`, `AgentTerminalReason`, `AgentRun`, `AgentSnapshot`,
+`AgentUsageValueSchema`, `AgentCostValueSchema`, `AgentUsageSchema`, `AgentUsage` and
+`AgentRunMetrics`.
+
+Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssignRunSchema`,
+`AcquireAgentRun`, `AcquireAgentRunSchema`, `CheckpointRunAssistant`,
+`CheckpointRunAssistantSchema`, `CommitRunTerminal`, `CommitRunTerminalSchema`,
+`RequestRunInterrupt`, `RequestRunInterruptSchema`, `RecoverAgentRun`, `ReplaceCompactedRange`,
+`ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
+`AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
+`AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,
+`AgentRuntimeHead`, `AgentStoredRun`, `AgentStoreCompareAndSwapResult`, `AgentHistoryMutation`,
+`AgentRecoverableDescriptor`, `AgentRecoverableDescriptorSchema`, `AgentRecoverablePage` and
+`AgentRecoverablePageSchema`.
+
+History and context-budget exports are `projectAgentHistoryDetailed`,
+`AgentHistoryProjectionDecision`, `AgentHistoryProjectionResult`, `selectAgentHistory`,
+`SelectAgentHistoryOptions`, `AgentHistoryBudgetDecision`, `AgentHistoryBudgetResult`,
+`AgentPromptBudget`, `AgentPromptSection`, `AgentPromptSectionContext`, `AgentTokenCount`,
+`AgentTokenCountSchema`, `ComposeAgentPromptOptions` and `ComposedAgentPrompt`. Whole-turn history
+selection never splits a tool chronology and reports why every canonical record was retained or
+removed.
+
+Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
+`AgentModelCapabilitySchema`, `AgentModelDeclaration`, `AgentModelDescriptor`,
+`AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,
+`AgentModelRegistrySnapshot`, `AgentModelRegistrySnapshotSchema`, `AgentModelSnapshotPolicy`,
+`AgentResolvedModel` and `validateAgentModelSnapshot`. Registry `preflight` validates availability,
+provider and required capabilities without constructing the model; runtime `models.preflight`
+runs before durable admission.
+
+Delivery exports are `AgentAdmissionEventSchema`, `AgentCheckpointEventSchema`,
+`AgentRunStateEventSchema`, `AgentTerminalEventSchema`, `AgentTransientDeltaEventSchema`,
+`AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
+`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentRuntimeEvent`,
+`AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,
+`advanceAgentRuntimeEventCursor`, `agentDurableEventId`, `AgentRuntimeEventSink`,
+`AgentRuntimeEventSinkConfig` and `createAgentRuntimeEventSink`. Cursor gaps require a canonical
+snapshot reload; the bounded sink isolates transport failure and supports a typed projection step.
+
+Managed effects and operator telemetry additionally export `AgentToolFenceConfig`,
+`AgentToolFenceContext`, `AgentObservability`, `AgentRunEvent`, `AgentRunEventSchema`,
+`AgentRunSinkConfig`, `AgentRunSinkDrop` and `AgentRunSinkError`. A monotonic run `fencingToken`
+may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
+operator-only observability sink explicitly opts in.
+
 ## `stitchkit/agent-runtime/openrouter`
 
 | Export | Kind | Summary |
@@ -8373,6 +8491,8 @@ handler pipeline without opening a TCP port.
 | `createHandlerTestClients` | function | exact contract-registry batch form |
 | `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
 | `AgentStoreConformanceConfig` | _type_ | factory configuration for running the same contract against a fresh adapter |
+| `createAgentRaceBarrier` / `createAgentRaceDriver` / `createAgentRaceTrace` | function | bounded named barriers and exact partial-order traces for deterministic runtime race probes |
+| `AgentRaceBarrier` / `AgentRaceDriver` / `AgentRaceTrace` / `AgentRaceTraceEntry` | _type_ | public packed-consumer types for the deterministic race harness |
 | `HandlerTestClientDefaults` | _type_ | ordinary bare-client defaults with handler-owned `baseUrl` and `fetch` removed |
 | `HandlerTestClientConfig` | _type_ | handler, contract, path prefix, scoped config and client request defaults |
 | `HandlerTestClientsConfig` | _type_ | batch helper configuration |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",