stitchkit 0.81.0 → 0.83.0

package/llms-full.txt

@@ -63,11 +63,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 | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 28 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 11 of the 26 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 12 of the 28 minors since 0.56.2, most recently 0.83.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +75,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 6 of the 26 minors since 0.56.2, most recently 0.79.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 28 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 |
@@ -350,13 +350,42 @@ records the verdict and reloads nothing.
 
 ## Adopting it
 
-1. Bake the build id into the bundle: `NEXT_PUBLIC_BUILD_ID=$(git rev-parse
-   --short HEAD)` at build time, or Next's `generateBuildId`. Without it the
-   watcher has no `own` and never reloads.
+1. Bake the build id into the bundle, from **one** source. Without it the
+   watcher has no `own` and never reloads — and it never says so, which is the
+   part worth spending a paragraph on.
+
+   `NEXT_PUBLIC_BUILD_ID=$(git rev-parse --short HEAD)` in the build command is
+   the short version and it has a failure mode: on an immutable-release layout
+   that variable usually lives in a static environment file, so it is easy for
+   two releases to ship the same id. Then `own` equals what the server reports
+   on every response, the watcher is correct to stay quiet, and nothing
+   anywhere is red. A reload that never happens looks exactly like a reload
+   that was not needed.
+
+   So mint it once and let one value reach all three readers. In Next, that is
+   `next.config`:
+
+   ```ts
+   const buildId = process.env.BUILD_ID ?? execSync('git rev-parse --short HEAD').toString().trim()
+
+   export default {
+     generateBuildId: () => buildId,          // → .next/BUILD_ID, which the server marker reads
+     env: { NEXT_PUBLIC_BUILD_ID: buildId },  // → the bundle, which becomes `own`
+   }
+   ```
+
+   The bundle's id and the file the server reports now come from the same
+   expression evaluated once, so they cannot drift apart per release. Any
+   arrangement with that property will do; the one to avoid is two places that
+   each decide the id and are expected to agree.
 2. Point `read` at the id of the **active** release, not the process's cwd.
 3. Add `release: (data: { buildId: string | null }) => void` to your
    `ServerToClientEvents` map where you type your socket, so your own `on`
-   knows the event the binding emits.
+   knows the event the binding emits. This is also what makes a **typed**
+   `Server<…>` fit `bindReleaseToSocketServer`: its `emit` is narrowed to the
+   names in your map, so until `release` is one of them the call fails to
+   typecheck — as a long structural mismatch, which reads like a bug in the
+   binding and is this line instead.
 4. Send `SIGUSR2` from the deploy step that activates a frontend without
    restarting the backend, and name that step in the project's release steps.
 
@@ -9457,7 +9486,7 @@ export const observability = createObservability({
 })
 
 const status = observability.getStatus()
-const drained = await observability.close()
+const report = await observability.close({ timeoutMs: 5_000 })
 ```
 
 `maxPending` defaults to `1000` per sink and must be a positive safe integer.
@@ -9475,14 +9504,71 @@ without parsing callback logs.
 
 `flush()` snapshots the current generation and waits only for events admitted
 up to that call. `close()` atomically stops admission, drains every accepted
-generation and returns the final counters plus `durationMs`; repeated calls
-return the same report. Graceful shutdown order is therefore:
+generation and returns the final counters plus `durationMs`; repeated unbounded
+calls return the same report. Graceful shutdown order is therefore:
 
 1. stop HTTP/MCP admission;
 2. wait for active requests and tool calls;
-3. `await observability.close()`;
+3. `await observability.close({ timeoutMs })`;
 4. close the database/storage connection used by the sinks.
 
+### Give the drain a bound in a shutdown budget
+
+Unbounded, `close()` waits for every accepted event however long the sink takes.
+That is right when the sink is healthy and fatal when it is not: one write that
+never settles — a database that has stopped answering — holds the drain forever,
+and a shutdown that gives every other step a deadline then spends its entire
+budget here and exits by force. A drain that cannot be bounded cannot take part
+in a shutdown budget: it either fits, or it cancels the budget.
+
+Both `flush` and `close` take `{ timeoutMs?, signal? }`:
+
+```ts
+const report = await observability.close({ timeoutMs: 5_000 })
+if (!report.drained) {
+  const t = report.total
+  logger.warn('audit drain incomplete', {
+    stillWriting: t.pending + t.preparing,
+    neverWritten: t.received - t.filtered - t.completed,
+  })
+}
+```
+
+Those are two different numbers and the difference matters. `pending +
+preparing` is what the drain was still waiting for when the bound expired —
+events handed to `write` that may yet succeed. `received - filtered -
+completed` is every event the sink has not written **for any reason**: those,
+plus the ones already lost to `failed`, `dropped` and `preparationFailed`. A
+shutdown log that wants to state how much audit was lost wants the second; one
+that wants to explain why the drain did not finish wants the first.
+
+`drained` is read from the counters, not from which side of the race won, so a
+bound that expires on a sink that has in fact finished — a shutdown signal
+already aborted by an earlier step — reports `true` rather than a false alarm.
+
+The bound ends the **waiting**, not the writes: a sink's `write` is handed no
+cancellation, so an outstanding one keeps running against whatever the consumer
+closes next. It is a bound on waiting for I/O, not on wall time — no bound can
+preempt a `write` that occupies the event loop. Racing `close()` against your
+own timer looks equivalent and is not: it discards the report along with the
+wait.
+
+`flush(bound?)` takes the same bound and returns whether the generation it
+waited on settled. That outcome is returned rather than left to `getStatus()`,
+which cannot answer it: flush waits on the events admitted before the call while
+the status counts everything alive right now, so a complete flush and an expired
+one look identical there.
+
+Every other sink in the framework takes the same bound —
+`createApplicationEventSink`, `createApplicationSnapshotSink`,
+`createAgentRuntimeEventSink`, `createAgentObservability`. The hazard was never
+specific to the audit sink; it was specific to waiting without a limit.
+
+The drain itself is started once and shared, so a second `close` with a shorter
+bound observes the same drain under its own limit rather than starting another.
+Passing no bound keeps the previous behaviour exactly, including the identical
+returned promise.
+
 Stitchkit manages only in-process delivery. If process-crash durability matters,
 make `write` enqueue into a consumer-owned durable outbox and let that adapter
 own retry, replay and storage policy:
@@ -10900,10 +10986,19 @@ A release that breaks a public API leads its `CHANGELOG.md` entry with a
 **`### ⚠️ Breaking changes`** section (exact heading), each item carrying a
 **before → after** snippet. A version with **no** such section is **purely
 additive** — adopting it changes nothing in your code. (See
-[`AGENTS.md` → Breaking changes](../../AGENTS.md).) `bun scripts/upgrade-plan.ts
-<installed> <target>` prints every breaking section your range crosses, oldest
-first, each with its **Who must act** line — the list this guide's migrations
-expand on.
+[`AGENTS.md` → Breaking changes](../../AGENTS.md).) So the list is recoverable
+mechanically, and the package recovers it for you:
+
+```bash
+bunx stitchkit@latest upgrade    # or: npx stitchkit@latest upgrade
+```
+
+Run it inside the project that depends on stitchkit. It reads your installed
+version out of `node_modules`, reads the changelog **shipped inside the
+package**, and prints every breaking section your range crosses, oldest first,
+each with its **Who must act** line — the list this guide's migrations expand
+on. Nothing to clone, nothing to be told: `--from` / `--to` override either end
+of the range if you want a different one.
 
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
@@ -10932,6 +11027,78 @@ makes one thing your job rather than the resolver's:
 The mechanical part is identical either way. Only the *noticing* differs, and an
 exact pin moves it onto you.
 
+## Released migration: 0.83.0
+
+Two things, both mechanical, and only if you touch an observability sink.
+
+```bash
+rg -n "createObservability|createApplicationEventSink|createApplicationSnapshotSink|createAgentRuntimeEventSink|createAgentObservability"
+```
+
+**1. `flush()` returns `Promise<boolean>`.** `await sink.flush()` needs no
+change. Only a declared type does:
+
+```ts
+// before
+const flushAudit: () => Promise<void> = observability.flush
+// after
+const flushAudit: () => Promise<boolean> = observability.flush
+```
+
+**2. `ObservabilityDrainReport` carries `drained`.** The framework builds it, so
+reading code is unchanged. A hand-built report — a test double, or one persisted
+and re-parsed through `ObservabilityDrainReportSchema` — needs the field:
+
+```ts
+// before
+{ request, tools, total, durationMs }
+// after
+{ request, tools, total, durationMs, drained: true }
+```
+
+Then take the thing this release exists for. Every drain now accepts
+`{ timeoutMs?, signal? }`, so a shutdown can give the audit drain the same
+deadline it gives every other step:
+
+```ts
+const report = await observability.close({ timeoutMs: 5_000 })
+if (!report.drained) {
+  logger.warn('audit drain incomplete', {
+    unwritten: report.total.received - report.total.filtered - report.total.completed,
+  })
+}
+```
+
+The bound ends the **waiting**, not the writes: a sink's `write` is handed no
+cancellation, so an outstanding one keeps running against whatever you close
+next. Racing `close()` against your own timer looks equivalent and is not — it
+discards the report along with the wait.
+
+## Released migration: 0.82.0
+
+One thing, and only if you mount MCP or agent tools from a `createTrackingContract` contract.
+
+```bash
+rg -n "createTrackingContract"
+```
+
+The event ingest (`track`, `POST /events`) is now `expose: ['HTTP']`, which is
+what its sibling `bootstrap` always declared. Before, it declared nothing — and
+an endpoint with no `expose` is a tool on MCP and AGENT by default, so the
+mounted surface carried a `track_<prefix>` tool. Since this contract is built
+inside the framework, an application that had made every tool opt-in for the
+endpoints *it* authors could not have opted this one out.
+
+**If you pin a tool-surface digest or count**, it moves by one; re-record it.
+**If you assert on tool names**, `track_<prefix>` is gone. **If nothing in your
+project mounts tools from this contract**, there is nothing to do — the HTTP
+routes, the client and the schemas are unchanged.
+
+Un-declaring the tool was never the intent, so there is no option to keep it. If
+an agent in your system genuinely needs to record something, give it your own
+endpoint with your own schema: the browser ingest trusts a client-minted event
+id and a visit lease, and an agent holds neither.
+
 ## Released migration: 0.81.0
 
 **Path literals own string params.**
@@ -15216,10 +15383,11 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
-| `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(), close() }` with bounded sink lifecycle |
+| `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(bound?): Promise<boolean>, close(bound?) }` with bounded sink lifecycle |
+| `ObservabilityDrainBound` | _type_ | `timeoutMs` and/or `signal` limiting how long `flush`/`close` wait; the wait ends, outstanding writes do not |
 | `ObservabilitySinkStatus` | _type_ | immutable counters for one bounded request/tool sink |
 | `ObservabilityStatus` | _type_ | per-surface plus aggregate operational snapshot |
-| `ObservabilityDrainReport` | _type_ | final closed/drained snapshot plus duration |
+| `ObservabilityDrainReport` | _type_ | final closed/drained snapshot, `durationMs` (the shared drain's age, not this call's wait), and `drained` — read from the counters, `false` only when `total.pending + total.preparing` is nonzero |
 | `ObservabilitySinkStatusSchema` / `ObservabilityStatusSchema` / `ObservabilityDrainReportSchema` | schema | runtime schemas for status/report integration boundaries |
 | `RequestEventSinkConfig` | _type_ | `write`, filter/sanitisation, `maxPending`, `onSinkError` and `onDrop` |
 | `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture and default-off `includeCancelled` rows |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.81.0",
+  "version": "0.83.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",
@@ -34,6 +34,9 @@
     "bun": ">=1.2.0",
     "node": ">=22"
   },
+  "bin": {
+    "stitchkit": "./dist/upgrade-cli.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -42,6 +45,7 @@
     "llms.txt",
     "llms-full.txt",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "exports": {
@@ -186,7 +190,7 @@
     "check": "bun x tsc --noEmit",
     "build:js": "bun run build:entrypoints && bun scripts/preserve-webpack-ignore.mjs",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",
-    "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-declarations-strict.mjs",
+    "build": "rm -rf dist && cp ../../CHANGELOG.md ./CHANGELOG.md && bun run build:js && chmod +x dist/upgrade-cli.js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-declarations-strict.mjs",
     "dev": "bun run build:entrypoints -- --watch",
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",