stitchkit 0.70.1 → 0.70.3

package/llms-full.txt

@@ -1218,10 +1218,18 @@ createServer({
   preconditions here, not authentication.
 - **`afterHandle`** — receives the handler result; return a replacement to
   transform it.
-- **`onError`** — receives any thrown error; return a `Response` to customise
-  the error body. Without it, errors render through the standard envelope. A
-  confirmed client disconnect is a transport cancellation rather than an
-  application error and deliberately bypasses this hook.
+- **`onError`** — for a matched contract route, the group's hook runs first,
+  then the global hook, then the standard error envelope. The first returned
+  `Response` wins (including its status and headers); an absent hook, `undefined`
+  return or thrown/rejected hook continues to the next level with the **original
+  error** and the same context and endpoint. A failing hook is diagnosed through
+  `logging.logger.error` (or the internal console fallback), never substituted
+  into the client response. This covers path/body validation, authorization,
+  before/after hooks and handler errors, including raw-response contract handlers.
+  Global `onRequest` failures, `rawRoutes` and unmatched 404/405 have no matched
+  contract group and use only the global hook. A confirmed client disconnect
+  deliberately bypasses both hooks; errors after streaming headers have been
+  sent keep their existing stream-error path.
 
 Hooks see `RuntimeContext` (loose types); handlers see `HandlerContext` (typed).
 That split is deliberate — see [ADR 0003](../decisions/0003-two-context-types.md).
@@ -1779,6 +1787,14 @@ for a custom raw transport. It uses the same descriptor and returns
 `{ files, fields, rollback }`; contract endpoints should prefer the automatic
 dispatcher path.
 
+Both delivery modes preserve UTF-8 `filename` metadata, including browser `FormData` names. For
+interoperability, a UTF-8 percent-encoded `filename*` parameter takes precedence over `filename`;
+unsupported charsets or malformed encoding are rejected rather than falling back silently. Literal
+percent sequences in ordinary `filename` are not decoded. Filenames remain untrusted metadata,
+not safe filesystem paths. Part headers have a 64 KiB byte limit, are case-insensitive and reject
+duplicates, folding, invalid header names and control characters. Disposition parameters reject
+duplicates and unsafe field names; declared part sizes must be nonnegative safe decimal integers.
+
 ### Rate limiting
 
 ```ts
@@ -4068,6 +4084,12 @@ revalidates the signature/tool call/input before the original direct tool reache
 fence. Reconnect and SQLite reopen require no promise registry. Remembered policy and a stronger
 cross-crash exactly-once guarantee remain application concerns.
 
+Approval requests suspend a call; they do not settle its result. History carries exact call and
+approval identity across assistant/tool records, so an approved result can precede the next signed
+request in a successor run. Automatic decisions follow the same chronology. Unknown/duplicate
+responses and results with a different call or tool name are invalid; dropping an invalid active
+approval input fails the run with a private diagnostic rather than starting a fresh model turn.
+
 `stitchkit/agent-runtime/coding-tools` returns ordinary direct runtime tools named `read_file`,
 `write_file`, `search_files`, `apply_patch`, `run_command` and optional `read_output`. Every call passes a
 required host authorization callback. File paths are relative, bounded and contained after
@@ -6332,6 +6354,171 @@ The bound handle intentionally has no `connect()` or `disconnect()`. Its
 `on`/`emit`/`request`, rejection and timeout semantics are exactly the path used
 by `createRealtimeClient`; only transport construction/lifecycle differs.
 
+## Snapshot + event state synchronization
+
+`createLiveStateController` is the optional browser-safe state machine between a
+validated transport binding and any renderer. It solves one problem: install a
+snapshot and every event after that snapshot's consistency point without a race.
+It does not create a socket, choose a cursor, retry a transport, store history or
+invent ordering for the application.
+
+```ts
+import {
+  createLiveStateController,
+  type LiveStateEventDecision,
+  type LiveStateSource,
+} from 'stitchkit'
+
+type View = { revision: number; rows: readonly Row[] }
+type Change = { revision: number; row: Row }
+
+const applyChange = (state: View, event: Change): LiveStateEventDecision<View> => {
+  if (event.revision <= state.revision) return { outcome: 'duplicate' }
+  if (event.revision !== state.revision + 1) return { outcome: 'gap' }
+  return {
+    outcome: 'applied',
+    state: { revision: event.revision, rows: [...state.rows, event.row] },
+  }
+}
+
+const live = createLiveStateController({
+  source,
+  applyEvent: applyChange,
+  maxBufferedEvents: 128,
+  maxBufferedBytes: 256 * 1024,
+  sizeOfEvent: encodedChangeBytes,
+})
+
+const unsubscribe = live.subscribe(render)
+await live.start()
+// On a gap/overflow or source loss, choose when the UI should resync.
+const status = live.getSnapshot()
+if (status.phase === 'resync-required' || status.phase === 'unavailable') {
+  await live.resync()
+}
+
+unsubscribe()
+await live.close()
+```
+
+The source boundary is the important part:
+
+```ts
+interface LiveStateSource<State, Event> {
+  open(input: {
+    signal: AbortSignal
+    onEvent(event: Event): void
+    onUnavailable(): void
+  }): Promise<{ snapshot: State; close(): void | Promise<void> }>
+}
+```
+
+`onEvent` is available before `open()` begins asynchronous work. By the time
+`open()` resolves, the source guarantees that every event after the returned
+snapshot's consistency point has already been or will be passed to that callback.
+The controller buffers early events within both explicit limits, installs the
+snapshot, drains in order, then becomes `live`. A late result from an earlier
+`resync()` generation is fenced. Non-cooperative caller-owned cleanup is asked to
+stop but cannot hold controller settlement.
+
+`subscribe()` listeners are synchronous external-store notifications: read the
+published snapshot and schedule rendering elsewhere. A listener that returns a
+Promise is removed after its first call, preventing unresolved UI work from
+accumulating per event. Source `close()` must be idempotent because an abort-aware
+binding may have started cleanup before the controller calls it.
+
+At most two physical source `open()` / `close()` operations in total may remain
+unsettled. If a caller-owned source ignores cancellation beyond that operation
+bound, `resync()` returns
+`unavailable/controller-capacity` without opening another generation. When a slot
+settles, the controller publishes `resync-required/controller-capacity`; the host
+may retry explicitly. This bounds controller-retained work without inventing a
+transport retry loop.
+
+### Socket.IO binding
+
+Use an acknowledged operation whose server handler establishes the subscription
+before it captures/returns the snapshot. For example, the server can join the
+socket to the resource room, capture revision `N`, then acknowledge that snapshot;
+ordered Socket.IO frames after that point reach the already-installed handler:
+
+```ts
+const source: LiveStateSource<View, Change> = {
+  async open({ signal, onEvent, onUnavailable }) {
+    const offEvent = socket.on('view:changed', onEvent)
+    const offConnection = socket.onConnectionChange((connected) => {
+      if (!connected) onUnavailable()
+    })
+    let closed = false
+    const close = () => {
+      if (closed) return
+      closed = true
+      offEvent()
+      offConnection()
+    }
+    signal.addEventListener('abort', close, { once: true })
+
+    try {
+      const snapshot = await socket.request('view:open', { timeoutMs: 5_000 })
+      return { snapshot, close }
+    } catch (error) {
+      close()
+      throw error
+    }
+  },
+}
+```
+
+Socket.IO still owns physical reconnect. A reconnected transport only means the
+connection is open; call `resync()` when application state needs a fresh
+generation. If the application has replay, its source may resume from its opaque
+cursor and return an accepted consistency point. If history expired or a cursor is
+incompatible, the source must acquire a fresh authoritative snapshot or reject the
+open; the controller does not classify or compare opaque cursors itself.
+
+### One-way HTTP stream binding
+
+NDJSON/SSE can use the same receiver semantics when **one response generation**
+starts with a schema-validated snapshot frame and every later frame is a validated
+event. Attach `parseNDJSON` or the typed contract-stream reader, parse the first
+frame before resolving `open()`, and pump remaining frames into `onEvent`. Abort
+that response in `close()`.
+
+A separate `GET /snapshot` followed by `GET /events` is not this boundary: a
+change can land between the two requests and disappear unless the application
+supplies a watermark/replay protocol. The controller intentionally cannot make
+that uncoordinated recipe safe.
+
+### Rendering, cache and process lifecycle
+
+For replaceable progress, let the reducer replace the absolute view at each
+accepted revision. For ordered records, append only the exact next revision and
+return `gap` otherwise. Both use the same controller; their ordering policy stays
+in their reducers. `getSnapshot()` + `subscribe()` works headlessly and with
+`useSyncExternalStore`. A React Query application can update its existing query
+cache from a subscriber after `phase === 'live'`; no second hook or store adapter
+is required. Cache `markFresh` windows suppress local echoes, while revision/cursor
+classification detects duplicates—those are different policies.
+
+A server process that owns such a receiver can place `start()` and `close()` in
+an existing `defineManagedResource` and include it in `createApplication`.
+Readiness follows a successful `live` snapshot; shutdown calls `close()`. Stitchkit
+does not add another supervisor, reconnect loop or durable event database.
+
+When migrating a hand-written receiver, remove only the superseded attach/snapshot
+race loop, retry timer and listener bookkeeping. Keep the application's schemas,
+authorization, reducer, cursor/replay policy and durable storage. Development
+proxying and Vite HMR remain frontend tooling; they are described in
+[frontend integrations](./frontend-integrations.md) and never travel through live
+application event envelopes.
+
+The Agent harness control server follows the same ordering: it installs the
+conversation attachment before awaiting the authoritative snapshot and rolls the
+attachment back if that read fails. A host adapter installs its delivery callback,
+issues `attach`, and supplies the returned snapshot through its live-state source;
+the existing Agent cursor and view reducers still own runtime epochs, durable
+versions and transcript projection.
+
 ### Request-response over realtime
 
 For an event with an `ack` schema, `request()` is the Promise form of the same
@@ -11271,7 +11458,7 @@ description: One machine-readable statement a repository makes about itself —
 type: architecture
 status: active
 created: 2026-08-25
-updated: 2026-08-25
+updated: 2026-08-30
 ---
 
 # Project declaration
@@ -11306,6 +11493,32 @@ mode that produces a running, wrong deployment rather than an error.
 
 ## Why declare yourself
 
+### Identity is not product membership
+
+The exported names `ProjectDeclaration` and `ProjectIdentity` describe the buildable source/artifact
+declared by a repository. A singular `identity` does **not** make a product project and a repository
+the same entity, nor does it identify a local checkout or a harness session.
+
+| Entity | Meaning and owner |
+| --- | --- |
+| Product project | A product boundary whose repository membership is explicitly maintained outside this declaration |
+| Repository | Versioned source; its declaration describes roles, build outputs and release requirements |
+| Checkout | A local working copy of a repository revision; local paths and credentials belong to its host |
+| Harness workspace | The host-selected working scope for a session, not an implied product or membership registry |
+
+Membership is many-to-many. For example, an external registry may declare product A includes
+repositories `service-a` and `shared-library`, while product B includes `service-b` and the same
+`shared-library`. Both products can read the library's unchanged declaration. Installing that library
+as a dependency, placing a checkout beside another, or naming a harness workspace does not create
+membership. The embedding product/registry owns these explicit relationships and their access policy.
+
+A private companion repository can be part of a product without becoming a separate product. Its
+relationship and working context stay in an authorized private registry, never in a potentially public
+library declaration. No registry or membership fields are required here; the declaration remains
+optional. Existing exports and schema version 1 are unchanged.
+
+### One statement, several readers
+
 Because the statements exist either way, and without a schema they exist three
 times. A repository already says how many roles it runs (in a process file),
 which variables it needs (in a Zod schema), what it builds (in a script) and
@@ -11501,6 +11714,16 @@ The browser-and-server entrypoint. Re-exports everything from
 | `defineRealtimeContract` | function | Zod-first shared Socket.IO event contract — [guide](../guide/realtime.md#zod-first-event-contract) |
 | `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
 | `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
+| `createLiveStateController` | function | keep typed application state current across one source-owned snapshot/event generation with finite pre-snapshot buffering, generation fencing and explicit resync — [guide](../guide/realtime.md#snapshot--event-state-synchronization) |
+| `LiveStateController` | _type_ | renderer-neutral `start` / `resync` / `getSnapshot` / `subscribe` / `close` handle |
+| `LiveStateControllerConfig` | _type_ | typed source, reducer, explicit event/byte bounds, event sizing and isolated error hooks |
+| `LiveStateControllerSnapshot` / `LiveStateControllerStatus` | _types_ | current value plus phase, generation, buffer and application/duplicate/gap/refusal counters |
+| `LiveStateControllerStatusSchema` | schema | strict runtime validation for controller status metadata |
+| `LiveStatePhaseSchema` / `LiveStatePhase` | schema / _type_ | `idle`, `opening`, `live`, `resync-required`, `unavailable` or `closed` |
+| `LiveStateStopReasonSchema` / `LiveStateStopReason` | schema / _type_ | explicit gap, overflow, source loss, controller failure and bounded `controller-capacity` reasons |
+| `LiveStateEventDecision` | _type_ | provider-owned reducer result: applied state, duplicate or gap |
+| `LiveStateSource` / `LiveStateSourceOpenInput` / `LiveStateSourceOpenResult` | _types_ | host binding for one continuous snapshot/event boundary; transport retry and cursor semantics remain host-owned |
+| `LiveStateControllerError` / `LiveStateSubscriberError` | _types_ | isolated observer failure payloads that do not change source or subscriber truth |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
 | `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
@@ -11540,7 +11763,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeEmitArguments` | _type_ | emit arguments including an inferred acknowledgement callback |
 | `RealtimeEventHandler` | _type_ | handler inferred from an event definition |
 | `InferRealtimeEventMap` | _type_ | inferred Socket.IO-compatible event map |
-| `RealtimeRejectDirection` | _type_ | server/client inbound/outbound rejection direction |
+| `RealtimeRejectDirection` / `RealtimeRejectPhase` / `RealtimeRejectReason` / `RealtimeRejectFault` | _types_ | canonical inferred rejection direction, validation phase, reason and fault classification |
 | `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
 | `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
 | `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
@@ -11717,7 +11940,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `LifecycleHooks` | _type_ | `onRequest` / pre-body `authorize` / `beforeHandle` / `afterHandle` / `onError` |
 | `composeLifecycleHooks` | function | compose HTTP lifecycle phases in declaration order with short-circuit/fallthrough semantics |
 | `AuthorizationContext` | _type_ | HTTP pre-body context with validated params, `input: undefined` and no files |
-| `RouteGroup` | _type_ | a prefixed group of services with its own hooks |
+| `RouteGroup` | _type_ | a prefixed group of services with its own hooks; matched errors try group `onError` → global `onError` → standard envelope, keeping the original error on fallback — [precedence](../guide/server.md#lifecycle-hooks) |
 | `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context |
 | `RawRouteContext` | _type_ | the Bun-bound routing context a raw handler receives |
 | `BunServer` | _type_ | the `Bun.serve` instance type |
@@ -12238,7 +12461,7 @@ and introduces no store, queue or model-provider implementation of its own.
 | `AgentHarnessFileResources` | _type_ | loader plus direct `read_resource` definition for lazy exact content |
 | `createAgentHarnessControlServer` | function | transport-neutral correlated requests, observer attachments and exclusive controller leases |
 | `AgentHarnessControlServer` / `AgentHarnessControlConnection` | _type_ | host server and detachable connection lifecycle; `deliver` is serialized, while required out-of-band `onOverflow` closes/aborts a slow transport before reconnect |
-| `AgentHarnessControlServerConfig` | _type_ | explicit per-connection pending-event bound for failure-isolated control delivery |
+| `AgentHarnessControlServerConfig` | _type_ | explicit per-connection pending-event and server-wide concurrent attachment-snapshot bounds for failure-isolated control delivery |
 | `AgentHarnessPendingApproval` / `AgentHarnessApprovalDecision` | _type_ | exact durable pending request and allow/deny successor input |
 
 Resources default to at most 64 entries, 1 MiB of total UTF-8 text and 128 diagnostics. Duplicate
@@ -12733,7 +12956,7 @@ handler pipeline without opening a TCP port.
 | `DefineRealtimeProbeConfig` | _type_ | name, canonical scenario, explicit fixture and expected realtime outcome |
 | `CreateRealtimeProbeDriverConfig` | _type_ | per-scenario foreign-transport binder and optional handler-call counter |
 | `RealtimeProbeAdapter` | _type_ | connected-state observation, scenario invocation and subscription-only cleanup |
-| `RealtimeProbeFixture` / `RealtimeProbeScenario` | _type_ | driver input and supported event/ack/invalid/disconnect/timeout scenario vocabulary |
+| `RealtimeProbeFixture` / `RealtimeProbeScenario` | _type_ | driver input and supported event/ack/local-invalid/peer-refusal/disconnect/timeout scenario vocabulary |
 | `RealtimeRejectionObservation` | _type_ | parsed structured realtime rejection observation |
 | `RealtimeDisconnectObservation` | _type_ | normalized physical timing of a realtime disconnect |
 | `TransportObservation` | _type_ | validated normalized driver result |
@@ -12784,6 +13007,11 @@ by the scaffolder that writes the first copy, and by whatever builds a source an
 binds the artifact into a deployment. It ships from the framework so those
 readers cannot hold different copies of the same schema.
 
+`identity` identifies the repository-local buildable source/artifact, not a product project, checkout
+or harness workspace. Product↔repository membership is explicit and many-to-many, owned by an
+external registry; dependency edges do not establish membership. Private companion context is never
+required in this public schema. See [identity boundaries](../guide/declaration.md#identity-is-not-product-membership).
+
 **Declaring yourself is optional.** A project with no `project.json` is a
 complete project: nothing else in the framework imports this entrypoint, no
 build, test or start path looks for a declaration, and its absence is never an

package/package.json

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

package/dist/index-es0h4w26.js

@@ -1,63 +0,0 @@
-// src/agent-runtime/terminal-status.ts
-function isSpeakableAssistantStatus(status) {
-  return status === "completed" || status === "interrupted" || status === "committed";
-}
-function isAssistantHistoryEvidence(status, policy) {
-  return isSpeakableAssistantStatus(status) || status === "failed" && policy?.failedAssistant === "assistant-marked";
-}
-function isCompleteAgentHistoryTurn(messages, policy) {
-  if (messages[0]?.role !== "user")
-    return false;
-  const calls = new Set;
-  const completed = new Set;
-  const approvals = new Map;
-  let assistantCount = 0;
-  for (const message of messages) {
-    if (message.role === "assistant") {
-      if (!isAssistantHistoryEvidence(message.status, policy))
-        return false;
-      assistantCount += 1;
-    }
-    for (const part of message.parts) {
-      if (part.type === "tool-call") {
-        if (calls.has(part.callId))
-          return false;
-        calls.add(part.callId);
-      } else if (part.type === "tool-approval-request") {
-        if (!calls.has(part.callId) || completed.has(part.callId) || approvals.has(part.approvalId))
-          return false;
-        if ([...approvals.values()].some((approval) => approval.callId === part.callId))
-          return false;
-        approvals.set(part.approvalId, { callId: part.callId, answered: false });
-      } else if (part.type === "tool-approval-response") {
-        const approval = approvals.get(part.approvalId);
-        if (!approval || approval.answered)
-          return false;
-        approval.answered = true;
-      } else if (part.type === "tool-result") {
-        if (!calls.has(part.callId) || completed.has(part.callId))
-          return false;
-        const approval = [...approvals.values()].find((entry) => entry.callId === part.callId);
-        if (approval && !approval.answered)
-          return false;
-        completed.add(part.callId);
-      }
-    }
-  }
-  return assistantCount > 0 && calls.size === completed.size && [...approvals.values()].every((approval) => approval.answered);
-}
-function assistantStatus(reason) {
-  if (reason === "success" || reason === "policy_stop" || reason === "provider_stop") {
-    return "completed";
-  }
-  if (reason === "superseded")
-    return "superseded";
-  if (reason === "absorbed")
-    return "superseded";
-  if (reason === "interrupted" || reason === "cancelled" || reason === "shutdown") {
-    return "interrupted";
-  }
-  return "failed";
-}
-
-export { isAssistantHistoryEvidence, isCompleteAgentHistoryTurn, assistantStatus };