stitchkit 0.76.2 → 0.77.0

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 21 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 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/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,9 +70,10 @@ 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 21 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `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/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 |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
 code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
@@ -5478,6 +5479,105 @@ Every instrument uses unit `1` and reports an absolute current/lifetime value:
 | `stitchkit.application.schedule.accepting`, `.active`, `.queued`, `.runs_started`, `.runs_completed`, `.runs_failed`, `.ticks_skipped` | current schedule state and absolute run/tick counts |
 | `stitchkit.application.activity.active`, `.queued`, `.completed`, `.failed` | absolute stage projections for declared activity sources |
 
+## Replacing part of the graph without stopping the process
+
+`restart` takes down one resource **and everything that depends on it**, then
+brings that subtree back. Everything else keeps running, and the process epoch
+does not move.
+
+```ts
+const result = await app.restart({ resourceId: 'database' })
+
+result.outcome  // 'restarted' | 'failed' | 'refused'
+result.affected // ['database', 'repository', 'api'] — in start order
+```
+
+The dependants come down with it because they are holding what the resource
+published. A repository that kept running across a database replacement holds a
+pool that has been closed: it still typechecks, still has methods, and fails at
+whatever moment the first call happens. There is no version of this where a
+dependant keeps a live handle, so the subtree — not the resource — is the unit.
+
+A leaf restart affects one resource, and an independent neighbour is never
+touched:
+
+```ts
+await app.restart({ resourceId: 'cache' })
+// mailer and database were not stopped, not started, not activated
+```
+
+**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.
+
+Restarts of overlapping subtrees queue behind each other rather than being
+refused. Two callers asking at once is ordinary; two generations of one resource
+alive at once is the thing this must make impossible.
+
+```ts
+// Both succeed, one complete pass after the other.
+await Promise.all([
+  app.restart({ resourceId: 'database' }),
+  app.restart({ resourceId: 'database' }),
+])
+```
+
+What a restart is **not** is a process restart: it replaces resources, and does
+not re-read configuration the kernel captured when it was constructed.
+
+→ [ADR 0154](../decisions/0154-the-unit-of-a-restart-is-the-subtree.md).
+
+## Decisions a policy set makes together
+
+`createDecisionPipeline` runs an ordered list of policies that each vote
+`allow`, `deny` (with a reason) or `defer`. The first terminal verdict wins and
+the rest do not run.
+
+```ts
+import { createDecisionPipeline } from 'stitchkit/application'
+
+const pipeline = createDecisionPipeline<{ userId: string; scope: string }>([
+  { id: 'banned', decide: (r) => (isBanned(r.userId)
+      ? { outcome: 'deny', reason: 'account suspended' }
+      : { outcome: 'defer' }) },
+  { id: 'scope', decide: (r) => (r.scope === 'admin'
+      ? { outcome: 'allow' }
+      : { outcome: 'defer' }) },
+  { id: 'default', decide: () => ({ outcome: 'deny', reason: 'no policy allowed this' }) },
+])
+
+const result = await pipeline.decide(request)
+result.outcome // 'allow' | 'deny' — never 'defer'
+result.trace   // the policies that actually ran, in order
+```
+
+Three things are deliberate.
+
+**A deny carries a reason, by schema.** `{ outcome: 'deny' }` alone does not
+typecheck. A refusal whose cause exists only in the log of whoever refused is a
+support ticket.
+
+**The trace is what ran, not what was declared.** It stops at the terminal
+verdict. When something was denied the question is which policy denied it and
+what the ones before it said, and a trace listing policies that never ran would
+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.
+
+The same `allow`/`deny`/`defer` type is what an event topic declared
+`mode: 'decision'` uses in `stitchkit/live` — one vocabulary, because a listener
+voting on an event and a policy voting on a request are answering the same
+question.
+
+→ [ADR 0155](../decisions/0155-one-decision-vocabulary-and-an-unanswered-question-is-an-error.md).
+
 ## Admission and graceful shutdown
 
 Use the application operation lease for work that is not already counted by a
@@ -10001,6 +10101,29 @@ 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.77.0
+
+Two type renames, and only if you named them. Nothing runtime moved.
+
+```bash
+rg -n "EventDecision|EventUndecided" --glob '*.ts' --glob '*.tsx'
+```
+
+```ts
+// before
+import type { EventDecision, EventUndecided } from 'stitchkit/live'
+// after
+import type { PolicyDecision, UndecidedOutcome } from 'stitchkit/live'
+```
+
+The shapes are identical — `{ outcome: 'allow' } | { outcome: 'deny', reason } | { outcome: 'defer' }`
+and `'allow' | 'deny'`. If you only ever *return* decisions from listeners and never named the
+type, the search above finds nothing and there is nothing to do.
+
+They were renamed because `createDecisionPipeline` (new in this release) votes with exactly the
+same three outcomes, and two identical types under two names is the thing that makes a search for
+either one return half the truth.
+
 ## Released migration: 0.76.0
 
 One change, and only if you hand `createWatchClient` a transport you wrote yourself.
@@ -13150,7 +13273,8 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
 |--------|------|---------|
 | `defineEvents` | function | declare topics: a wire name, one payload schema and how the topic is delivered to in-process listeners |
 | `toRealtimeContract` | function | project a declaration onto `RealtimeContract`, so the existing validated socket carries it |
-| `EventDeliveryMode` / `EventDecision` / `EventUndecided` | _types_ | `emit` / `serial` / `decision`, one listener's vote, and the outcome when every listener defers |
+| `EventDeliveryMode` | _type_ | `emit` / `serial` / `decision` — how a topic reaches its in-process listeners |
+| `PolicyDecision` / `UndecidedOutcome` | _types_ | one voter's `allow` / `deny` / `defer`, and what a run settles on when every voter defers — the same two types the decision pipeline in `stitchkit/application` uses, because a listener voting on an event and a policy voting on a request are answering the same question |
 | `EventTopicDeclaration` / `EventTopicRegistry` / `EventsConfig` / `EventsDeclaration` | _types_ | one topic's schema, mode, `whenAllDefer` and `listenerTimeoutMs`, and the declaration they compose into |
 | `EventPayloads` / `EventTopicsOfMode` / `WireTopic` | _types_ | payload map keyed by wire topic, the topics of one mode, and the `prefix.name` a topic is addressed by |
 | `createWatchClient` | function | contract-shaped watch client: `watch.action(args)` returns a ref-counted handle sharing one subscription |
@@ -13444,7 +13568,11 @@ cutovers are covered by the executable
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createApplication` | function | compose a validated resource DAG into one non-restartable startup, readiness, admission and shutdown state machine |
+| `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 |
+| `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` |
 | `ApplicationResourcePhase` | _type_ | the phase a managed resource failed in — the vocabulary of `ApplicationResourceShutdown.failures` |
 | `ApplicationShutdownOptionsSchema` / `ApplicationShutdownOptions` | schema / _type_ | the two shutdown budgets and an abort signal — without the HTTP-only `retryAfterSeconds` |
@@ -13568,6 +13696,10 @@ and `ApplicationEventSinkConfig`.
 
 ### Canonical application records
 
+These are also published on their own as
+[`stitchkit/application/schemas`](#stitchkitapplicationschemas), which carries
+no server runtime and can therefore be imported from a browser bundle.
+
 The entrypoint exports each Zod schema beside its inferred type:
 `ApplicationIdSchema` / `ApplicationId`, `ApplicationLifecycleSchema` /
 `ApplicationLifecycle`, `ApplicationHealthSchema` / `ApplicationHealth`,
@@ -13581,6 +13713,20 @@ the function that derives it from a snapshot,
 `ApplicationResourceShutdownSchema` / `ApplicationResourceShutdown`, and
 `ApplicationShutdownResultSchema` / `ApplicationShutdownResult`.
 
+### Decisions
+
+A pipeline of policies that each vote `allow`, `deny` or `defer`, sharing its
+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 |
+| `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 |
+
 ### Keyspace and watched reads
 
 | Export | Kind | Summary |
@@ -13624,6 +13770,33 @@ 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/schemas`
+
+The canonical application records — and nothing else. Every export here is also
+reachable from `stitchkit/application`; the difference is what comes with it.
+
+`stitchkit/application` is the server runtime: it reaches `node:child_process`,
+`node:fs` and `node:crypto`. A browser bundler does not omit those, it
+substitutes stubs — so a module that merely *names* an application schema fails
+while it is initialising, and the page never mounts, on every route rather than
+the one that wanted the schema. A contract whose `output` is an application
+snapshot could be declared and never consumed, which is the one thing a contract
+is for.
+
+So the same schemas ship a second way, from a module with nothing behind them:
+
+```ts
+// browser and server alike
+import { ApplicationSnapshotSchema } from 'stitchkit/application/schemas';
+```
+
+The exports are exactly those listed under
+[canonical application records](#canonical-application-records) above.
+`packages/core/scripts/check-browser-clean.mjs` holds the promise against the
+built artifact: it walks the browser lane's real `dist` output and refuses a
+`node:` import reachable from any of it, and refuses an entry built for the
+browser that no `exports` path leads to — which is how this one was missing.
+
 ---
 
 ## `stitchkit/agent-runtime`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.76.2",
+  "version": "0.77.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/schemas": {
+      "types": "./dist/application-schemas.d.ts",
+      "import": "./dist/application-schemas.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
@@ -156,7 +160,7 @@
   "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/agent-runtime-browser.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/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: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",