stitchkit 0.58.0 → 0.59.0

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,CAmPf"}
+{"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.js

@@ -315,6 +315,35 @@ async function runAgentStoreConformance(config) {
   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");

package/llms-full.txt

@@ -3500,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
 
@@ -6576,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
+
+`AgentRuntimeStoreDriver` no longer reads and rewrites a lifetime `AgentStoredState` JSON
+aggregate. Migrate that row and its recoverable/archive projections once:
 
-Custom `AgentRuntimeStore` adapters must persist and return the input and
-assistant identities associated with an idempotency key:
+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
 
@@ -8044,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 |
@@ -8095,8 +8118,8 @@ Store command/result exports are `AcceptInputAndAssignRun`, `AcceptInputAndAssig
 `RequestRunInterrupt`, `RequestRunInterruptSchema`, `RecoverAgentRun`, `ReplaceCompactedRange`,
 `ReplaceCompactedRangeSchema`, `AgentStoreMutationResult`, `AgentStoreMutationResultSchema`,
 `AgentStoreAppliedSchema`, `AgentStoreConflictSchema`, `AgentStoreDuplicateSchema`,
-`AgentStoreNotFoundSchema`, `AgentAdmissionIdentity`, `AgentAdmissionIdentitySchema`,
-`AgentStoredState`, `AgentStoreCompareAndSwapResult`, `AgentHistoryMutation`,
+`AgentStoreNotFoundSchema`, `AgentAdmissionReceipt`, `AgentAdmissionReceiptSchema`,
+`AgentRuntimeHead`, `AgentStoredRun`, `AgentStoreCompareAndSwapResult`, `AgentHistoryMutation`,
 `AgentRecoverableDescriptor`, `AgentRecoverableDescriptorSchema`, `AgentRecoverablePage` and
 `AgentRecoverablePageSchema`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.58.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",