stitchkit 0.56.5 → 0.58.0

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,
@@ -3482,7 +3485,8 @@ const terminal = await ticket.result
 
 `recordIds` is optional. Supply stable application record IDs when an accepted-response transport must
 return durable placeholders before the run finishes. `ticket.admission` resolves after the store
-acceptance CAS and reports the actually assigned `runId`, `assistantMessageId` and snapshot version.
+acceptance CAS and reports the canonical committed `input`, assigned `run`, a typed `pending`
+assistant projection, compatibility IDs and snapshot version.
 Those assigned IDs can differ from the proposal when an input coalesces into an existing queued
 successor. Reuse the same `inputMessageId` for retries carrying the same idempotency key; input
 identity is caller-stable, while the receipt reports the run/assistant identities that assignment
@@ -3490,8 +3494,35 @@ may change. Await `admission` first on the immediate accepted-response path. `ti
 remains the signal-only compatibility surface and additionally waits for admission publication.
 
 The in-memory store is a reference adapter and has process-local durability
-only. Production applications implement `AgentRuntimeStore` with their own
-database transaction and, when needed, distributed lease/fencing token.
+only. Production applications normally call `createAgentRuntimeStore()` and
+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),
+  },
+  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
+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.
 
 ## Durable order
 
@@ -3533,8 +3564,8 @@ hatch.
 
 ## Store operations
 
-An adapter implements the aggregate `AgentRuntimeStore`, not separate message
-and run CRUD stores:
+`AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
+implement the smaller `AgentRuntimeStoreDriver`, not these eight transitions:
 
 - `acceptInputAndAssignRun`
 - `acquireRun`
@@ -3549,13 +3580,17 @@ 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.
 
-On startup, `scanRecoverable` returns queued/acquired records. `recoverRun`
-may abandon them, or requeue an already acquired run only with explicit
-`replaySafe: true` evidence. The framework never guesses that an external
-side effect is replayable. After an application reconstructs its typed context,
-`runtime.resume({ conversationId, runId, context })` admits that queued record
-through the same acquisition CAS and coordinator lane; it never creates a
-second input message.
+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
+with explicit replay-safe evidence, or abandon it only with stale-owner
+evidence. Each attempted run returns its own outcome/error; `pageSize`,
+`maxRuns`, and `signal` bound the pass. `runtime.resume(...)` remains available
+for one known queued record.
 
 Canonical records currently write `schemaVersion: 1`. A durable adapter owns
 read-time migration of older rows: migrate to the current shape at its storage
@@ -3567,6 +3602,9 @@ or silently accept an unknown future version.
 
 `publish` receives event classes with different guarantees:
 
+- `admission` follows a successful acceptance CAS and carries the same complete
+  projection as `ticket.admission`;
+
 - `assistant-delta` is transient and ordered by
   `(runId, runtimeEpoch, sequence)`;
 - `reasoning-start`, `reasoning-delta` and `reasoning-end` are transient and
@@ -3578,6 +3616,16 @@ or silently accept an unknown future version.
   start and output on completion; internal tool failures remain generic;
 - `terminal` follows the winning terminal CAS.
 
+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
@@ -3608,6 +3656,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:
@@ -3644,22 +3700,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.
 
 
 ==============================================================================
@@ -5132,7 +5198,7 @@ never-leak-an-internal-message rule for a raw throw):
 
 ```ts
 const onError = createErrorHook({
-  // Map the codes you have an opinion about; the rest travel as themselves.
+  // Map the codes you have an opinion about.
   codeMap: {
     BAD_REQUEST: 'bad_request', VALIDATION_ERROR: 'bad_request',
     UNAUTHORIZED: 'unauthenticated', FORBIDDEN: 'forbidden',
@@ -5140,6 +5206,9 @@ const onError = createErrorHook({
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
   },
+  // Optional: one public vocabulary entry for every other stitchkit code.
+  // A resolver `(code) => ...` is also accepted for grouping code families.
+  unmappedCode: 'framework_error',
   // `ctx` is the request's RuntimeContext — read `ctx.traceId` for a
   // correlation id in the envelope. Declaring it is optional.
   render: (info, ctx) => ({
@@ -5152,10 +5221,13 @@ const onError = createErrorHook({
 createServer({ services, hooks: { onError } })
 ```
 
-`codeMap` is partial: map the codes you have an opinion about. A stitchkit code
-you did not list travels as itself — the same thing a code you threw yourself
-always did. That is what keeps a code added by a future release from being a
-compile break for every project that translates codes at all.
+`codeMap` is partial: map the codes you have an opinion about. By default a
+stitchkit code you did not list travels as itself. Set `unmappedCode` to one
+wire-code when your public vocabulary has a catch-all, or to a function such as
+`(code) => code.startsWith('FILE_') ? 'storage_error' : 'framework_error'` when
+framework code families need different buckets. An explicit `codeMap` entry
+always wins. Codes your project throws itself do not belong to Stitchkit's
+vocabulary, so they never pass through this fallback and remain unchanged.
 
 One `satisfies` is the **opt-in** to the stricter deal:
 
@@ -5167,9 +5239,7 @@ That makes the map exhaustive on your side, so a release that adds a code stops
 your build until you decide what the new code is called on your wire. Take it
 when your envelope is a published contract and a code surfacing in stitchkit's
 spelling would violate it; leave it off when passing one through is fine.
-Neither choice is silent — the changelog names every added code. For a single
-catch-all instead of either, decide it in `render`, where `info.code` is the
-resolved value.
+Neither choice is silent — the changelog names every added code.
 
 Both `onError` and `render` may be asynchronous and receive the matched endpoint
 as their final argument. The observer is awaited before rendering, so it can
@@ -6506,6 +6576,34 @@ 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
+
+Custom `AgentRuntimeStore` adapters must persist and return the input and
+assistant identities associated with an idempotency key:
+
+```ts
+// before
+return { outcome: 'duplicate', runId, snapshot }
+
+// after
+return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
+```
+
+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
+```
+
 ## Released migration: 0.56.0
 
 ### Surface manifests are version 2
@@ -7819,7 +7917,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `createAuthHook` | function | one scope gate for HTTP `authorize` and tool `beforeHandle` — [guide](../guide/auth-and-errors.md#createauthhook) |
 | `composeAuthHooks` | function | route multiple canonical auth domains by owned scope and atomically commit their typed contributions |
 | `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
-| `ErrorHookConfig` | _type_ | async observer/renderer config for `createErrorHook` |
+| `ErrorHookConfig` | _type_ | async observer/renderer config with partial `codeMap` and optional typed `unmappedCode` fallback |
 | `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
 | `createBearerResolver` | function | a bearer-token identity resolver |
 | `signJwt` | function | sign an HS256 JWT |
@@ -7945,6 +8043,10 @@ Server-only optional application runtime. See the
 | `defineAgentProtocol` | function | declare and validate context, input metadata and canonical message parts |
 | `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 |
+| `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 |
 | `projectAgentHistory` | function | asynchronously project canonical records and resolved multimodal files into provider-valid AI SDK messages |
@@ -7955,13 +8057,80 @@ Server-only optional application runtime. See the
 | `AgentRuntimeStopPolicy` | _type_ | named custom AI SDK stop condition persisted and published on policy stop |
 | `AgentRuntimePrepareStep` | _type_ | per-run controlled step callback with typed domain context and managed run signal/fence |
 | `AgentRuntimeRecordIds` | _type_ | optional caller-provided input, run and assistant IDs for stable application records |
-| `AgentRuntimeAdmission` | _type_ | actual assigned run/assistant identity and snapshot version after durable admission |
+| `AgentRuntimeAdmission` | _type_ | canonical committed input, assigned run, pending assistant projection, compatibility IDs and snapshot version |
+| `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
+| `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` distinguishes checkpoint from terminal totals |
+| `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with context resolver and explicit evidence policy |
 | `AgentSessionCloseOptions` | _type_ | natural `drainTimeoutMs` followed by shutdown abort and optional bounded `forceTimeoutMs` settlement wait |
 | `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver and explicit unresolved-file behavior |
 | `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent` |
-| `AgentRuntimeEventSchema` | schema | transient text/reasoning/tool lifecycle, durable checkpoint/run-state and terminal event union |
+| `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`, `AgentAdmissionIdentity`, `AgentAdmissionIdentitySchema`,
+`AgentStoredState`, `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 |
@@ -8297,6 +8466,10 @@ handler pipeline without opening a TCP port.
 |--------|------|---------|
 | `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
 | `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.56.5",
+  "version": "0.58.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",