stitchkit 0.77.0 → 0.78.0

package/dist/tool-invoker.js

@@ -1,15 +1,15 @@
 import {
   createToolInvoker
-} from "./index-jqtsc9mj.js";
-import"./index-7qy2ex0m.js";
-import"./index-s4c8wy8m.js";
-import"./index-nemjkxjp.js";
+} from "./index-j6mfaw26.js";
+import"./index-cwp38wxn.js";
+import"./index-qaajjfp6.js";
 import"./index-22by16v6.js";
 import"./index-cby4ar3v.js";
-import"./index-nt1mp8km.js";
+import"./index-s5tn4kdv.js";
+import"./index-efm026pw.js";
 import"./index-vj3vvpaa.js";
-import"./index-0w9abg87.js";
 import"./index-qyrqwr4c.js";
+import"./index-0w9abg87.js";
 import"./index-6k1937bx.js";
 export {
   createToolInvoker

package/dist/tools.js

@@ -1,18 +1,12 @@
-import {
-  redact
-} from "./index-aczggrty.js";
 import {
   buildToolManifest,
   mountAgent
-} from "./index-ezmn6ac6.js";
+} from "./index-5r0ak8fr.js";
 import"./index-3xnq72rz.js";
-import {
-  argumentsDigest
-} from "./index-a916km3r.js";
 import {
   signJwt,
   verifyPkce
-} from "./index-da1aqnhb.js";
+} from "./index-aewy3x5j.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_PROCESS_SIGNALS,
@@ -23,7 +17,7 @@ import {
 } from "./index-vbf2p6me.js";
 import {
   createToolInvoker
-} from "./index-jqtsc9mj.js";
+} from "./index-j6mfaw26.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -32,10 +26,10 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-s2rchahr.js";
+} from "./index-31k1ns1s.js";
 import {
   collectToolSurface
-} from "./index-k2zczx1g.js";
+} from "./index-93xp5tgg.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
@@ -44,22 +38,17 @@ import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-7qy2ex0m.js";
+} from "./index-cwp38wxn.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-s4c8wy8m.js";
-import {
-  getRequestContext,
-  getTraceId,
-  runWithRequestContext
-} from "./index-nemjkxjp.js";
+} from "./index-qaajjfp6.js";
 import {
   ManagedFileError
-} from "./index-bfcpjw20.js";
+} from "./index-actkayzn.js";
 import"./index-sbdmyz75.js";
 import {
   PORTABLE_JSON_SCHEMA_FORMATS,
@@ -73,20 +62,28 @@ import {
   validateMcpRoundPolicy
 } from "./index-22by16v6.js";
 import"./index-cby4ar3v.js";
+import {
+  redact
+} from "./index-aczggrty.js";
+import {
+  getRequestContext,
+  getTraceId,
+  runWithRequestContext
+} from "./index-s5tn4kdv.js";
 import {
   normalizeError,
   resolvePropagationContext
-} from "./index-nt1mp8km.js";
+} from "./index-efm026pw.js";
 import {
   defineContract
 } from "./index-vj3vvpaa.js";
+import {
+  isRecord
+} from "./index-qyrqwr4c.js";
 import {
   AppError,
   STITCH_ERROR_STATUS
 } from "./index-0w9abg87.js";
-import {
-  isRecord
-} from "./index-qyrqwr4c.js";
 import {
   ManagedFilePathSchema,
   ManagedFileRefSchema
@@ -1070,6 +1067,52 @@ import {
   inputResponse,
   PROTOCOL_VERSION_META_KEY
 } from "@modelcontextprotocol/server";
+
+// src/internal/stable-digest.ts
+function stableValue(value) {
+  if (Array.isArray(value))
+    return value.map(stableValue);
+  if (value === null || typeof value !== "object")
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort()) {
+    result[key] = stableValue(Reflect.get(value, key));
+  }
+  return result;
+}
+function mix128(input) {
+  let a = 2654435769;
+  let b = 2246822507;
+  let c = 3266489909;
+  let d = 668265263;
+  for (let index = 0;index < input.length; index += 1) {
+    const code = input.charCodeAt(index);
+    a = Math.imul(a ^ code, 2246822519);
+    b = Math.imul(b ^ code, 3266489917);
+    c = Math.imul(c ^ code, 668265263);
+    d = Math.imul(d ^ code, 374761393);
+    a = a << 13 | a >>> 19;
+    b = b << 17 | b >>> 15;
+    c = c << 7 | c >>> 25;
+    d = d << 11 | d >>> 21;
+  }
+  a ^= b >>> 15;
+  b ^= c >>> 13;
+  c ^= d >>> 11;
+  d ^= a >>> 9;
+  return [
+    Math.imul(a ^ a >>> 16, 575075507) >>> 0,
+    Math.imul(b ^ b >>> 13, 2654435761) >>> 0,
+    Math.imul(c ^ c >>> 16, 2246822507) >>> 0,
+    Math.imul(d ^ d >>> 15, 3266489909) >>> 0
+  ];
+}
+function argumentsDigest(args) {
+  const lanes = mix128(JSON.stringify(stableValue(args)) ?? "undefined");
+  return lanes.map((lane) => lane.toString(16).padStart(8, "0")).join("");
+}
+
+// src/tools/mcp-round.ts
 function transportContext(context, toolName, outcome, round) {
   const protocolVersionValue = isRecord(context.mcpReq.envelope) ? Reflect.get(context.mcpReq.envelope, PROTOCOL_VERSION_META_KEY) : undefined;
   const protocolVersion = typeof protocolVersionValue === "string" ? protocolVersionValue : undefined;

package/llms-full.txt

@@ -62,7 +62,7 @@ own, recorded as an ADR.
 | `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` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 22 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 11 of the 23 minors since 0.56.2, most recently 0.75.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 |
@@ -70,10 +70,11 @@ 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` | server | evolving<br>_redefined in 4 of the 22 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 5 of the 23 minors since 0.56.2, most recently 0.78.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 with no server runtime behind them |
+| `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
+| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
 code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
@@ -5509,9 +5510,26 @@ await app.restart({ resourceId: 'cache' })
 **Refused is not failed.** An unknown id, a restart during shutdown, and a
 restart before the application is ready all return `refused` with a reason and
 touch nothing. `failed` means the subtree came down and the new generation did
-not come up — the snapshot says so too, with the failing resource marked
-`failed` / `unhealthy`, because the restart records a failure the same way a
-startup does.
+not come up — and the result agrees with the snapshot: if any affected resource
+ends the restart in `failed`, so does the restart, including an optional one
+whose failure the start loop does not re-throw.
+
+**The close phase is bounded**, by the application's shutdown budget or by one
+this call names:
+
+```ts
+await app.restart({ resourceId: 'database', gracePeriodMs: 5_000, forceTimeoutMs: 2_000 })
+```
+
+**A resource has to be able to start twice.** The kernel calls `start` again, so
+a resource holding state across its own lifetime rebuilds it there. The ones this
+framework ships do — a schedule re-arms, a keyspace opens a new generation and
+re-loads, a managed server built from a factory gets a fresh server. A managed
+server given a server *instance* cannot, and says so by name rather than
+republishing something it has shut down. Give a keyspace a
+`backend: () => …` factory when its backend cannot be re-opened after `close()`.
+
+→ [ADR 0157](../decisions/0157-a-restartable-resource-begins-a-generation.md).
 
 Restarts of overlapping subtrees queue behind each other rather than being
 refused. Two callers asking at once is ordinary; two generations of one resource
@@ -5547,7 +5565,7 @@ const pipeline = createDecisionPipeline<{ userId: string; scope: string }>([
       ? { outcome: 'allow' }
       : { outcome: 'defer' }) },
   { id: 'default', decide: () => ({ outcome: 'deny', reason: 'no policy allowed this' }) },
-])
+], { policyTimeoutMs: 2_000 })
 
 const result = await pipeline.decide(request)
 result.outcome // 'allow' | 'deny' — never 'defer'
@@ -5568,8 +5586,19 @@ answer that wrongly while looking complete.
 **Every policy deferring raises.** `DecisionUndecidedError`, not a default —
 defaulting to `allow` turns an incomplete policy set into an open door, and
 defaulting to `deny` turns it into an outage whose cause reads as a legitimate
-refusal. A policy that throws or times out denies with the policy named
-(`DecisionPolicyError`): broken must not mean skipped.
+refusal.
+
+**A policy that does not answer raises too.** A non-decision, a throw, and running
+past `policyTimeoutMs` are one error — `DecisionPolicyError`, naming the policy
+and carrying the trace so far — because they are indistinguishable downstream and
+handling one but not the others is how a broken policy becomes a skipped one. The
+chain stops there rather than falling through to whatever the next policy would
+have said.
+
+`policyTimeoutMs` is required and has no default. Pick a number your slowest
+policy comfortably beats. The framework will not choose it for you: a policy that
+never settles hangs every caller of the operation it guards, and a default here
+is a number nobody chose applied to code the framework has never seen.
 
 The same `allow`/`deny`/`defer` type is what an event topic declared
 `mode: 'decision'` uses in `stitchkit/live` — one vocabulary, because a listener
@@ -5671,8 +5700,14 @@ changing its revision or status contract. → ADR 0119.
 Use `createDiagnosticJournal` when a process needs finite, ordered local metadata evidence and the
 deployment log pipeline is not the right boundary:
 
+It lives at `stitchkit/application/diagnostic-journal`, not in the main barrel:
+it is the one part of the kernel that spawns, locks and writes files, and while it
+was exported from `stitchkit/application` that single line made the whole
+entrypoint unusable in a browser bundle. Its schemas stay in
+`stitchkit/application`.
+
 ```ts
-import { createDiagnosticJournal } from 'stitchkit/application'
+import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
 import { z } from 'zod'
 
 const journal = await createDiagnosticJournal({
@@ -10101,6 +10136,50 @@ 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.78.0
+
+Two mechanical edits. Find them both:
+
+```bash
+rg -n "createDecisionPipeline|createDiagnosticJournal" --glob '*.ts' --glob '*.tsx'
+```
+
+**1. `createDecisionPipeline` takes a deadline.**
+
+```ts
+// before
+createDecisionPipeline([policyA, policyB])
+// after
+createDecisionPipeline([policyA, policyB], { policyTimeoutMs: 2_000 })
+```
+
+Pick a number your slowest policy comfortably beats. There is no default on
+purpose: a policy that never settles hangs every caller of the operation it
+guards, and the framework has no basis for choosing that number for you.
+
+Past the deadline — and on a throw, and on a non-decision — the pipeline raises
+`DecisionPolicyError` naming the policy, with the trace so far. If you already
+catch that for a bad return value, you now catch two more cases with it.
+
+**2. `createDiagnosticJournal` moved.**
+
+```ts
+// before
+import { createDiagnosticJournal } from 'stitchkit/application'
+// after
+import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+```
+
+Only the factory moved. `DiagnosticJournalConfig`, every
+`DiagnosticJournal*Schema` and `readDiagnosticJournalLockDiagnosis` stay where
+they were.
+
+**If you restart resources**, nothing to change — but three things that did not
+work now do: a managed schedule can be restarted, a restarted keyspace accepts
+writes again, and a restarted managed server is actually shut down at exit. If
+you pass `managedServerResource` a server *instance*, a restart is now refused
+by name; pass a factory (`server: (context) => …`) to restart it.
+
 ## Released migration: 0.77.0
 
 Two type renames, and only if you named them. Nothing runtime moved.
@@ -13570,7 +13649,7 @@ cutovers are covered by the executable
 |--------|------|---------|
 | `createApplication` | function | compose a validated resource DAG into one startup, readiness, admission and shutdown state machine |
 | `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
-| `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id |
+| `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |
 | `ApplicationRestartResultSchema` / `ApplicationRestartResult` | schema / _type_ | the subtree that was actually taken down and brought back, in start order, with the outcome, the reason on anything but success, and how long it took |
 | `ApplicationRestartOutcomeSchema` / `ApplicationRestartOutcome` | schema / _type_ | `restarted`, `failed` or `refused` — a refusal (unknown id, shutting down, not yet ready) is not a failure and touches nothing |
 | `ApplicationResourceFailure` | _type_ | one resource failure with the cause its phase label cannot carry — delivered to `onResourceFailure` |
@@ -13721,11 +13800,12 @@ vocabulary with an event topic declared `mode: 'decision'`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createDecisionPipeline` | function | run policies in declaration order; the first terminal verdict wins and the rest do not run |
+| `DecisionPipelineConfig` | _type_ | `policyTimeoutMs` — how long one policy has to answer. Required, no default: a policy that never settles hangs every caller of the operation it guards |
 | `PolicyDecisionSchema` / `PolicyDecision` | schema / _type_ | `allow`, `deny` with a reason, or `defer` — a deny cannot be silent |
 | `DecisionPolicy` / `DecisionPipeline` | _types_ | one named voter over the caller's subject, and the pipeline it composes into |
 | `DecisionResult` / `DecisionTraceEntry` | _types_ | the verdict, and the trace of what actually ran — not what was declared |
 | `DecisionUndecidedError` | class | every policy deferred and no undecided outcome was declared: an unanswered question, raised rather than guessed |
-| `DecisionPolicyError` | class | a policy threw or timed out; the pipeline denies with the policy named |
+| `DecisionPolicyError` | class | a policy returned a non-decision, threw, or ran past `policyTimeoutMs` — one error for all three, carrying the policy id and the trace so far |
 
 ### Keyspace and watched reads
 
@@ -13733,7 +13813,7 @@ vocabulary with an event topic declared `mode: 'decision'`.
 |--------|------|---------|
 | `defineKeyspace` / `keyspaceResource` | function | a named record set read synchronously from memory and written through one serialised chain; backend first, then memory, then the change event |
 | `openKeyspace` / `OpenedKeyspace` | function / type | the same keyspace opened directly, for an application that owns its own lifecycle rather than declaring resources to a kernel |
-| `KeyspaceBackend` / `KeyspaceDeclaration` / `KeyspaceChange` / `KeyspaceResourceConfig` / `OpenKeyspace` | _types_ | the four-method durability port, the declaration, the announced change, the resource's options and the published handle |
+| `KeyspaceBackend` / `KeyspaceDeclaration` / `KeyspaceChange` / `KeyspaceResourceConfig` / `OpenKeyspace` | _types_ | the four-method durability port, the declaration, the announced change, the resource's options and the published handle. `backend` takes a value or a **factory** — a factory is called once per generation, so a restarted keyspace gets a backend that was never closed |
 | `memoryKeyspaceBackend` / `sqliteKeyspaceBackend` / `SqliteKeyspaceBackendConfig` | function / type | a disposable in-process backend, and one table with a key and a JSON payload over a caller-owned database |
 | `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _types_ | the minimal synchronous SQLite boundary the framework types against |
 | `createWatchHub` / `watchKey` | function | one read per question however many are asking: single-flight per key, re-read on a declared topic, publish only what changed |
@@ -13770,6 +13850,23 @@ snapshots; the adapter owns no SDK lifecycle, polling or delta state.
 | `ApplicationTelemetryMeter` | _type_ | minimal structural `Meter.createObservableGauge` boundary compatible with `@opentelemetry/api` |
 | `ApplicationOpenTelemetryCollectionError` | _type_ | isolated instrument-name/error diagnostic without product/provider attributes |
 
+## `stitchkit/application/diagnostic-journal`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createDiagnosticJournal` | function | the bounded local journal: a file lock, a spawn to diagnose a stale one, and framed writes |
+
+Its own entrypoint because of what it reaches — `node:child_process`,
+`node:fs`, `node:os`, `node:util` — with `promisify(execFile)` evaluated while
+the module initialises. Exported from `stitchkit/application`, that one line made
+the entire barrel unusable in a browser bundle: not by failing at the call, but
+by throwing during module initialisation, on every route.
+
+Its **contract** stays in `stitchkit/application` — every
+`DiagnosticJournal*Schema`, the states and the refusal reasons touch nothing but
+Zod, and a client reading a journal's status has as much right to them as the
+server writing it.
+
 ## `stitchkit/application/schemas`
 
 The canonical application records — and nothing else. Every export here is also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.77.0",
+  "version": "0.78.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",
@@ -129,6 +129,10 @@
       "types": "./dist/application-opentelemetry.d.ts",
       "import": "./dist/application-opentelemetry.js"
     },
+    "./application/diagnostic-journal": {
+      "types": "./dist/application-diagnostic-journal.d.ts",
+      "import": "./dist/application-diagnostic-journal.js"
+    },
     "./application/schemas": {
       "types": "./dist/application-schemas.d.ts",
       "import": "./dist/application-schemas.js"
@@ -160,11 +164,11 @@
   "scripts": {
     "build:native-contained-files": "node scripts/build-contained-files-native.mjs",
     "check": "bun x tsc --noEmit",
-    "build:browser": "bun build src/index.ts src/live.ts src/react.ts src/contract/index.ts src/primitives.ts src/declaration.ts src/application-schemas.ts src/agent-runtime-browser.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-harness.ts src/agent-runtime-coding-tools.ts src/agent-runtime-openrouter.ts src/agent-runtime-sqlite-bun.ts src/agent-runtime-sqlite-node.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts src/telegram.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:browser": "bun build src/index.ts src/live.ts src/react.ts src/contract/index.ts src/primitives.ts src/declaration.ts src/application-schemas.ts src/application.ts src/remote.ts src/agent-runtime-browser.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-harness.ts src/agent-runtime-coding-tools.ts src/agent-runtime-openrouter.ts src/agent-runtime-sqlite-bun.ts src/agent-runtime-sqlite-node.ts src/application-diagnostic-journal.ts src/application-grammy.ts src/application-opentelemetry.ts src/telegram.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server && 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-env-live.mjs && bun scripts/check-public-types.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",
     "dev": "bun run build:js -- --watch",
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",