stitchkit 0.89.0 → 0.90.0

package/llms-full.txt

@@ -48,7 +48,7 @@ own, recorded as an ADR.
 |--------|--------|----------|-------|
 | `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
 | `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
-| `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract, projected onto the realtime contract |
+| `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract — and watched reads: `createWatchClient`, the value/difference frame and its reassembly |
 | `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
@@ -64,11 +64,11 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 34 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 35 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 20 of the 34 minors since 0.56.2, most recently 0.89.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 20 of the 35 minors since 0.56.2, most recently 0.89.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults and deterministic race controls |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -78,7 +78,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 34 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 35 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -8810,13 +8810,49 @@ Nothing an open can fail with escapes as a rejected promise: a disconnected
 socket, a timeout, a refusal all arrive as `unavailable` carrying the error's own
 code and message, and the next connection retries.
 
+The re-open carries what the client still holds, so a reconnection is usually
+cheap: the hub answers with a difference, or with nothing at all when the answer
+has not moved. That needs the key to still exist on the server — set `holdMs`
+past your reconnect delay, or the last detach releases the source and the page
+pays the whole value once.
+
+### Large answers cross as differences
+
+A frame carries the value, a **difference** to a revision this subscriber already
+holds, or `unchanged`. The hub chooses per subscriber and sends a difference only
+when it is genuinely smaller; your `value` listener sees the rebuilt value either
+way and needs no code for this.
+
+It matters when an answer is large and moves a little: a ~75 KB list in which two
+timestamps change, republished every fifteen seconds, was a megabyte per
+subscriber per minute before and is a frame under a kilobyte now.
+
+```ts
+createWatchHub({
+  // Superseded values kept per key, so a difference has something to be taken
+  // against. Default 262144. Set 0 to send whole values only.
+  deltaMemoryBytes: 256 * 1024,
+  holdMs: 30_000,
+  // …
+});
+```
+
+Reassembly is checked against the server's fingerprint on every frame. If a
+difference will not apply — a client that missed a revision, a hub that restarted
+— that **one key** resynchronises: your `state` listener sees `resync-required`
+and the whole value follows. Other keys on the same socket are untouched.
+
+Both ends must come from the same major release: a client older than 0.90 reads a
+difference frame as a value of `undefined`.
+
 ### `watch` or `createLiveStateController`?
 
 > **If you would have written `applyEvent` as `(_, next) => next`, you want
-> `watch`: the server sends the value whole.** `createLiveStateController` is for
-> a server that sends *deltas* you have to fold. `watch` is that controller with
-> the fold fixed to replacement, plus the key sharing and the retention — so
-> applying both to one value is always a mistake.
+> `watch`: whatever crosses the wire, what your `value` listener receives is the
+> whole answer.** `createLiveStateController` is for a server whose *protocol* is
+> deltas that your code folds. `watch` may send a difference too, but it folds it
+> for you and hands you the value — so applying both to one value is always a
+> mistake.
 
 ### What it cannot promise
 
@@ -9746,9 +9782,10 @@ stitchkit answers this at two levels.
   sanitisation and `createObservability` with independent request/tool sinks.
   [Start here ↓](#the-observability-module)
 
-stitchkit still ships no logger and no audit store — those are the app's choice.
-What it ships is the machinery that turns a completed call into a clean,
-normalised record.
+stitchkit still ships no logger and no audit store, and auditing stays opt-in —
+those are the app's choice (→ ADR 0012, reaffirmed in ADR 0184). What it ships is
+the machinery that turns a completed call into a clean, normalised record, keeps
+the ones worth keeping, and does not lose them when the store is down.
 
 ## The observability module
 
@@ -9985,6 +10022,69 @@ queryable across all three:
 | `resultSize` / `responseBytes` | result item count + serialised size |
 | `userId` / `ipAddress` / `userAgent` | identity |
 
+### Write the calls that changed something
+
+`auditChanges` is the filter most projects end up writing, shipped so they do not
+have to write it six ways:
+
+```ts
+import { auditChanges, createObservability } from 'stitchkit/observability';
+
+createObservability({
+  request: { write: saveAuditRow, filter: auditChanges },
+  tools: { write: saveAuditRow, filter: auditChanges },
+});
+```
+
+It drops `GET`, `HEAD` and `OPTIONS`, keeps everything else, and keeps `401` and
+`403` **whatever the verb was** — a refused read is the row an audit exists to
+hold, and a filter that drops every `GET` drops exactly that. An unrecognised
+verb is kept: an extra row costs bytes, a missing one costs the answer to "who
+changed this", silently and only later.
+
+One filter across HTTP, MCP and agent calls, because a tool call carries its
+contract verb in `httpMethod` while its `method` is the literal `TOOL`.
+
+Narrower policy stays yours — compose it:
+
+```ts
+filter: (event) => auditChanges(event) && event.serviceName !== 'health',
+```
+
+### Keeping the row when the store is down
+
+A sink is fire-and-forget, so an unreachable store means the event is simply
+gone — and a store is most likely to be unreachable during an incident, which is
+the window whose rows someone will later want most.
+
+`createSpooledSink` writes the row to a local append-only file first, offers it
+to the store second, and marks it delivered third. What a previous process left
+unmarked is replayed:
+
+```ts
+import { createSpooledSink } from 'stitchkit/observability';
+
+const audit = createSpooledSink({
+  path: '/var/lib/app/audit.ndjson',
+  write: saveAuditRow,
+});
+
+// Once, at startup, before the sink is wired — and await it.
+const { replayed, failed } = await audit.recover();
+
+createObservability({ request: { write: audit.write, filter: auditChanges } });
+```
+
+The guarantee is **at least once**. A crash between the store accepting a row and
+the file recording that it did replays the row, so **the store must be idempotent
+on the record key** — `event.spanId` by default, unique per call. A unique index
+on it turns the duplicate into a no-op; without one, replay writes the row twice.
+Exactly-once would need the file and the database to share a transaction. They do
+not.
+
+One process, one path. Two processes pointed at the same file replay each other's
+records: harmless against an idempotent store, wasteful always.
+
 ### Request context
 
 When request observability is configured, `createHandler` establishes the
@@ -11382,6 +11482,32 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.90.0
+
+1. `stitchkit.watch.value` is a discriminated union on `kind` — `full`, `delta`,
+   `unchanged` — and every frame carries `fingerprint`. **Both ends must come from
+   the same major.** A client older than this release reads a `delta` frame as a
+   value of `undefined`, silently; upgrade the hub and the pages that talk to it
+   together, or set `deltaMemoryBytes: 0` on the hub until they are.
+
+   Applications using `createWatchClient` need no code change: it rebuilds the
+   value and hands the listener the whole answer as before. Code that reads
+   `WatchValueFrame.value` directly — a hand-written subscriber, a test double —
+   narrows on `kind` first.
+
+   ```ts
+   // before: frame.value
+   // after:
+   if (frame.kind === 'full') hold(frame.value);
+   else if (frame.kind === 'delta') hold(applyWatchDelta(held, frame.delta));
+   // 'unchanged' leaves what you hold standing
+   ```
+
+2. `AttachedWatcher.open` takes an optional third argument, `have`. A custom
+   server binding that forwards `stitchkit.watch.open` should pass the payload's
+   `have` through; omitting it costs a whole value on every reconnection and is
+   otherwise harmless.
+
 ## Released migration: 0.89.0
 
 1. Custom `AgentRuntimeStore` adapters implement `seedConversationInput`; custom
@@ -15121,7 +15247,10 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
 | `watchContract` | const | the four-event realtime contract a watched read travels on |
 | `WATCH_OPEN` / `WATCH_CLOSE` / `WATCH_VALUE` / `WATCH_STATE` | const | the event names of that contract |
 | `WatchKey` / `WatchKeySchema` / `watchKeyString` | type / schema / function | `(service, action, arguments digest)` — the identity both ends compute the same way |
-| `WatchValueFrame` / `WatchValueSchema` / `WatchStateFrame` / `WatchStateSchema` | _types_ | a value with its monotonic revision, and a phase from `LiveStatePhase` with the read's own code and message |
+| `WatchValueFrame` / `WatchValueSchema` / `WatchStateFrame` / `WatchStateSchema` | _types_ | one answer — `full`, `delta` or `unchanged`, with its monotonic revision and fingerprint — and a phase from `LiveStatePhase` with the read's own code and message |
+| `WatchHave` / `WatchHaveSchema` | type / schema | what a reconnecting subscriber already holds, offered on `open`: a revision and the fingerprint that proves it |
+| `WatchDelta` / `WatchDeltaSchema` / `WatchArrayOp` / `WatchArrayOpSchema` | _types_ / schemas | a structural difference over parsed JSON — objects by changed and dropped key, arrays by runs copied from the previous value |
+| `watchDiff` / `applyWatchDelta` / `watchDeltaWins` | functions | build a difference (`undefined` when equal), rebuild the value from one (throws rather than inventing), and whether it is actually smaller than the value |
 
 ---
 
@@ -16142,6 +16271,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
+| `auditChanges` | function | the sink `filter` most projects write themselves — drops `GET`/`HEAD`/`OPTIONS`, keeps `401`/`403` whatever the verb, keeps an unrecognised verb |
+| `createSpooledSink` / `SpooledSink` / `SpooledSinkConfig` / `SpoolRecovery` | function / _types_ | spool the row to an append-only file before the store and replay what a previous process left undelivered — at least once, keyed on `spanId` |
 | `createDimensionsProjector` / `DimensionsProjector` / `DimensionsProjectorConfig` / `ProjectedDimensions` | function / _type_ | typed request/result/error attribution projected into the existing request context |
 | `DimensionCollision` / `SetRequestDimensionsOptions` | _type_ | explicit overwrite, preserve or error policy for dimension keys |
 | `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |

package/package.json

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

package/dist/index-dre2ywck.js

@@ -1,48 +0,0 @@
-import {
-  LiveStatePhaseSchema,
-  LiveStateStopReasonSchema
-} from "./index-ywd0y6m1.js";
-
-// src/live/watch-contract.ts
-import { z } from "zod";
-var WatchKeySchema = z.object({
-  service: z.string().min(1),
-  action: z.string().min(1),
-  digest: z.string().min(1)
-}).strict().readonly();
-var WatchOpenSchema = z.object({ key: WatchKeySchema, args: z.unknown() }).readonly();
-var WatchAcceptedSchema = z.object({
-  accepted: z.boolean(),
-  reason: z.string().optional()
-}).strict().readonly();
-var WatchValueSchema = z.object({
-  key: WatchKeySchema,
-  revision: z.number().int().nonnegative(),
-  value: z.unknown()
-}).readonly();
-var WatchStateSchema = z.object({
-  key: WatchKeySchema,
-  phase: LiveStatePhaseSchema,
-  reason: LiveStateStopReasonSchema.optional(),
-  code: z.string().optional(),
-  message: z.string().optional()
-}).readonly();
-var WATCH_OPEN = "stitchkit.watch.open";
-var WATCH_CLOSE = "stitchkit.watch.close";
-var WATCH_VALUE = "stitchkit.watch.value";
-var WATCH_STATE = "stitchkit.watch.state";
-var watchContract = {
-  serverToClient: {
-    [WATCH_VALUE]: { args: z.tuple([WatchValueSchema]) },
-    [WATCH_STATE]: { args: z.tuple([WatchStateSchema]) }
-  },
-  clientToServer: {
-    [WATCH_OPEN]: { args: z.tuple([WatchOpenSchema]), ack: WatchAcceptedSchema },
-    [WATCH_CLOSE]: { args: z.tuple([z.object({ key: WatchKeySchema }).readonly()]) }
-  }
-};
-function watchKeyString(key) {
-  return `${key.service}/${key.action}/${key.digest}`;
-}
-
-export { WatchKeySchema, WatchValueSchema, WatchStateSchema, WATCH_OPEN, WATCH_CLOSE, WATCH_VALUE, WATCH_STATE, watchContract, watchKeyString };