stitchkit 0.77.0 → 0.79.0

package/llms-full.txt

@@ -53,6 +53,7 @@ own, recorded as an ADR.
 | `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` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
@@ -60,9 +61,9 @@ own, recorded as an ADR.
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification and Bot API send-failure classification |
 | `stitchkit/observability` | server | stable | 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` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
+| `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 | 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 24 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 +71,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 6 of the 24 minors since 0.56.2, most recently 0.79.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 +5511,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 +5566,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 +5587,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 +5701,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 +10137,84 @@ 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.79.0
+
+One thing, and only if you assert on the whole snapshot.
+
+```bash
+rg -n "getSnapshot\(\)|projectApplicationStatus|status\(\)" --glob '*.test.ts' --glob '*.spec.ts'
+```
+
+`ApplicationSnapshot` and `ApplicationStatusProjection` each gained a
+`restarting` field — ids in the snapshot, a count in the projection. A reader
+that names the fields it wants is unaffected. A test that compares the whole
+object with `toEqual` fails until it adds the field:
+
+```ts
+// before
+expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 } })
+// after
+expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 }, restarting: 0 })
+```
+
+It is zero except while a restart is running, and then it names the subtree being
+replaced. That is the point: a snapshot taken mid-restart used to be
+indistinguishable from a resource that had failed on its own, so a dashboard read
+a planned replacement as an outage.
+
+**If you watch a hub across a restart**, nothing to change, but the behaviour is
+different and better: closing a hub now tells its subscribers `unavailable` /
+`source-unavailable` instead of dropping them, so a page stops showing a value
+that will never update again.
+
+**If you need a tool contract in a browser**, `stitchkit/tools/contract` now
+carries the async-operation helpers, its schemas and the view-file input/output
+without the runtime. `stitchkit/tools` still exports all of them.
+
+## 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 +13684,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 +13835,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 +13848,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 +13885,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.79.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",
@@ -61,6 +61,10 @@
       "types": "./dist/tools.d.ts",
       "import": "./dist/tools.js"
     },
+    "./tools/contract": {
+      "types": "./dist/tools-contract.d.ts",
+      "import": "./dist/tools-contract.js"
+    },
     "./tools/invoker": {
       "types": "./dist/tool-invoker.d.ts",
       "import": "./dist/tool-invoker.js"
@@ -129,6 +133,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,18 +168,17 @@
   "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:js": "bun run build:browser && bun run build:server && bun scripts/preserve-webpack-ignore.mjs",
+    "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-env-live.mjs && bun scripts/check-public-types.mjs",
-    "dev": "bun run build:js -- --watch",
+    "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:entrypoints -- --watch",
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
     "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",
     "consumer-lane": "bun scripts/consumer-lane/run.mjs",
-    "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts"
+    "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts",
+    "build:entrypoints": "bun scripts/build-entrypoints.mjs"
   },
   "peerDependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2",

package/dist/index-ksp6e2ye.js

@@ -1,24 +0,0 @@
-// src/internal/typed.ts
-function typedEntries(value) {
-  return Object.entries(value);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function transportResult(value) {
-  return value;
-}
-function mapObject(source, mapper) {
-  const result = {};
-  for (const [key, value] of typedEntries(source)) {
-    const mapped = mapper(key, value);
-    if (mapped !== undefined)
-      result[key] = mapped;
-  }
-  return result;
-}
-function mapObjectTypeBoundary(source, mapper) {
-  return mapObject(source, (key, value) => mapper(key, value));
-}
-
-export { typedEntries, isRecord, transportResult, mapObject, mapObjectTypeBoundary };

package/dist/index-vj3vvpaa.js

@@ -1,307 +0,0 @@
-// src/contract/define.ts
-import { z } from "zod";
-
-// src/internal/route-pattern.ts
-var PARAM_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
-function joinRoutePath(...parts) {
-  const joined = parts.filter((part) => Boolean(part)).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
-  return `/${joined}`;
-}
-function parseTrailingWildcard(path) {
-  const segments = path.split("/").filter(Boolean);
-  const paramNames = new Set;
-  let wildcard = null;
-  for (const [segmentIndex, segment] of segments.entries()) {
-    if (segment.startsWith(":")) {
-      const name2 = segment.slice(1);
-      if (!PARAM_IDENTIFIER.test(name2)) {
-        throw new Error(`Invalid route parameter name "${name2}" in path "${path}"`);
-      }
-      if (paramNames.has(name2)) {
-        throw new Error(`Duplicate route parameter name "${name2}" in path "${path}"`);
-      }
-      paramNames.add(name2);
-      continue;
-    }
-    if (!segment.startsWith("*")) {
-      if (segment.includes("*")) {
-        throw new Error(`Wildcard must occupy its own segment in path "${path}"`);
-      }
-      continue;
-    }
-    const name = segment.slice(1);
-    if (!PARAM_IDENTIFIER.test(name)) {
-      throw new Error(`Trailing wildcard in path "${path}" must be named, for example "/*filePath"`);
-    }
-    if (segmentIndex !== segments.length - 1) {
-      throw new Error(`Wildcard "*${name}" must be the final segment in path "${path}"`);
-    }
-    if (wildcard) {
-      throw new Error(`Path "${path}" contains more than one wildcard`);
-    }
-    if (paramNames.has(name)) {
-      throw new Error(`Duplicate route parameter name "${name}" in path "${path}"`);
-    }
-    wildcard = { name, segmentIndex };
-  }
-  return wildcard;
-}
-
-// src/internal/safe-json.ts
-function isUnsafeKey(key) {
-  return key === "__proto__";
-}
-function safeJsonParse(text) {
-  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
-}
-
-// src/contract/define.ts
-function defineContract(meta, endpoints) {
-  const toolTransports = new Map;
-  for (const [key, ep] of Object.entries(endpoints)) {
-    const wildcard = parseTrailingWildcard(ep.path);
-    if (wildcard) {
-      if (!ep.params) {
-        throw new Error(`Contract "${meta.prefix}": endpoint "${key}" wildcard "${wildcard.name}" requires a params schema field`);
-      }
-      const paramsJson = z.toJSONSchema(ep.params, { io: "input" });
-      if (!paramsJson.properties || !(wildcard.name in paramsJson.properties)) {
-        throw new Error(`Contract "${meta.prefix}": endpoint "${key}" params schema is missing wildcard field "${wildcard.name}"`);
-      }
-    }
-    if (ep.desc.trim() === "") {
-      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
-    }
-    if (ep.maxJsonBodyBytes !== undefined && (!Number.isSafeInteger(ep.maxJsonBodyBytes) || ep.maxJsonBodyBytes <= 0)) {
-      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" maxJsonBodyBytes must be a positive safe integer, received ${ep.maxJsonBodyBytes}`);
-    }
-    if (ep.multipart)
-      assertMultipartEndpoint(meta.prefix, key, ep);
-    if (ep.rawResponse)
-      assertRawEndpoint(meta.prefix, key, ep);
-    if ("stream" in ep)
-      assertStreamingResponseEndpoint(meta.prefix, key, ep);
-    if (ep.method === "HEAD")
-      assertHeadEndpoint(meta.prefix, key, ep);
-    if (ep.rawBody)
-      assertRawBodyEndpoint(meta.prefix, key, ep);
-    if ("responseMeta" in ep)
-      assertResponseMetaEndpoint(meta.prefix, key, ep);
-    if (!("toolName" in ep) || !ep.toolName)
-      continue;
-    const transports = new Set(ep.expose ? ep.expose.filter((t) => t !== "HTTP") : ["MCP", "AGENT"]);
-    if (transports.size === 0) {
-      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" sets toolName "${ep.toolName}" but is not exposed on any tool transport (MCP / AGENT)`);
-    }
-    const existing = toolTransports.get(ep.toolName);
-    if (existing) {
-      for (const t of transports) {
-        if (existing.transports.has(t)) {
-          throw new Error(`Contract "${meta.prefix}": duplicate toolName "${ep.toolName}" on transport "${t}" (endpoints: "${existing.key}" and "${key}")`);
-        }
-        existing.transports.add(t);
-      }
-    } else {
-      toolTransports.set(ep.toolName, { key, transports });
-    }
-  }
-  return { meta, endpoints };
-}
-function assertPositiveLimit(where, name, value) {
-  if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
-    throw new Error(`${where} ${name} must be a positive safe integer, received ${value}`);
-  }
-}
-function assertMultipartEndpoint(prefix, key, ep) {
-  const where = `Contract "${prefix}": multipart endpoint "${key}"`;
-  if (ep.method !== "POST" && ep.method !== "PUT" && ep.method !== "PATCH") {
-    throw new Error(`${where} must use POST, PUT or PATCH`);
-  }
-  const multipart = ep.multipart;
-  if (!multipart || typeof multipart !== "object") {
-    throw new Error(`${where} must declare a multipart descriptor`);
-  }
-  assertPositiveLimit(where, "maxRequestBytes", multipart.maxRequestBytes);
-  assertPositiveLimit(where, "maxFieldBytes", multipart.maxFieldBytes);
-  const entries = Object.entries(multipart.files);
-  if (entries.length === 0)
-    throw new Error(`${where} must declare at least one file field`);
-  for (const [field, policy] of entries) {
-    if (!field || isUnsafeKey(field))
-      throw new Error(`${where} has an invalid file field name`);
-    assertPositiveLimit(`${where} field "${field}"`, "maxBytes", policy.maxBytes);
-    assertPositiveLimit(`${where} field "${field}"`, "maxFiles", policy.maxFiles);
-    if (policy.multiple !== true && policy.maxFiles !== undefined) {
-      throw new Error(`${where} field "${field}" may set maxFiles only with multiple: true`);
-    }
-    if (policy.contentTypes) {
-      if (policy.contentTypes.length === 0) {
-        throw new Error(`${where} field "${field}" contentTypes cannot be empty`);
-      }
-      for (const contentType of policy.contentTypes) {
-        if (!/^[a-z0-9!#$&^_.+-]+\/(?:[a-z0-9!#$&^_.+-]+|\*)$/i.test(contentType)) {
-          throw new Error(`${where} field "${field}" has invalid content type policy "${contentType}"`);
-        }
-      }
-    }
-  }
-}
-function assertRawEndpoint(prefix, key, ep) {
-  const where = `Contract "${prefix}": raw endpoint "${key}"`;
-  if (ep.output)
-    throw new Error(`${where} cannot declare an output schema`);
-  if ("toolName" in ep && ep.toolName)
-    throw new Error(`${where} cannot set a toolName`);
-  if ("ui" in ep && ep.ui)
-    throw new Error(`${where} cannot set MCP ui metadata`);
-  if ("annotations" in ep && ep.annotations) {
-    throw new Error(`${where} cannot set MCP annotations`);
-  }
-  const nonHttp = (ep.expose ?? []).filter((t) => t !== "HTTP");
-  if (nonHttp.length > 0) {
-    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
-  }
-}
-function assertStreamingResponseEndpoint(prefix, key, ep) {
-  const where = `Contract "${prefix}": streaming endpoint "${key}"`;
-  if (!("stream" in ep) || !ep.stream || typeof ep.stream !== "object") {
-    throw new Error(`${where} must declare a stream descriptor`);
-  }
-  if (!ep.stream.item || typeof ep.stream.item.parse !== "function") {
-    throw new Error(`${where} must declare an item schema`);
-  }
-  const runtimeFormat = Reflect.get(ep.stream, "format");
-  const runtimeFinalLine = Reflect.get(ep.stream, "finalLine");
-  if (ep.stream.framing === "item" && runtimeFormat === "sse") {
-    throw new Error(`${where} item framing is supported only for ndjson`);
-  }
-  if (ep.stream.framing === "item" && ep.stream.completion !== "terminal") {
-    throw new Error(`${where} item framing requires terminal completion`);
-  }
-  if (ep.stream.completion === "terminal" && !ep.stream.terminal) {
-    throw new Error(`${where} terminal completion requires a terminal schema`);
-  }
-  if (runtimeFinalLine === "require-newline" && runtimeFormat === "sse") {
-    throw new Error(`${where} finalLine applies only to ndjson`);
-  }
-  assertPositiveLimit(where, "maxFrameBytes", ep.stream.maxFrameBytes);
-  assertPositiveLimit(where, "lifetimeMs", ep.stream.lifetimeMs);
-  assertPositiveLimit(where, "heartbeatMs", ep.stream.heartbeatMs);
-  if (ep.stream.idleTimeoutSeconds !== undefined && (!Number.isSafeInteger(ep.stream.idleTimeoutSeconds) || ep.stream.idleTimeoutSeconds < 0)) {
-    throw new Error(`${where} idleTimeoutSeconds must be a non-negative safe integer`);
-  }
-  if (ep.output)
-    throw new Error(`${where} cannot declare an output schema`);
-  if (ep.rawResponse)
-    throw new Error(`${where} cannot also be rawResponse`);
-  if (ep.multipart)
-    throw new Error(`${where} cannot be multipart`);
-  if ("toolName" in ep && ep.toolName)
-    throw new Error(`${where} cannot set a toolName`);
-  const nonHttp = (ep.expose ?? []).filter((transport) => transport !== "HTTP");
-  if (nonHttp.length > 0) {
-    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
-  }
-}
-function assertHeadEndpoint(prefix, key, ep) {
-  const where = `Contract "${prefix}": HEAD endpoint "${key}"`;
-  if (!ep.rawResponse)
-    throw new Error(`${where} must declare rawResponse: true`);
-  if (ep.input)
-    throw new Error(`${where} cannot declare an input schema`);
-  if (ep.multipart)
-    throw new Error(`${where} cannot be multipart`);
-  if (ep.rawBody)
-    throw new Error(`${where} cannot retain a raw body`);
-}
-function assertRawBodyEndpoint(prefix, key, ep) {
-  const where = `Contract "${prefix}": rawBody endpoint "${key}"`;
-  if (!ep.input)
-    throw new Error(`${where} must declare an input schema`);
-  if (ep.multipart)
-    throw new Error(`${where} cannot be multipart`);
-  if (ep.method !== "POST" && ep.method !== "PUT" && ep.method !== "PATCH") {
-    throw new Error(`${where} must use POST, PUT or PATCH`);
-  }
-  if ("toolName" in ep && ep.toolName)
-    throw new Error(`${where} cannot set a toolName`);
-  if ("ui" in ep && ep.ui)
-    throw new Error(`${where} cannot set MCP ui metadata`);
-  if ("annotations" in ep && ep.annotations) {
-    throw new Error(`${where} cannot set MCP annotations`);
-  }
-  const nonHttp = (ep.expose ?? []).filter((transport) => transport !== "HTTP");
-  if (nonHttp.length > 0) {
-    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
-  }
-}
-function assertResponseMetaEndpoint(prefix, key, ep) {
-  const where = `Contract "${prefix}": responseMeta endpoint "${key}"`;
-  if (!ep.responseMeta || typeof ep.responseMeta !== "object") {
-    throw new Error(`${where} must declare responseMeta as an object`);
-  }
-  const status = ep.responseMeta.status;
-  if (status !== undefined && (!Number.isSafeInteger(status) || status < 200 || status > 299)) {
-    throw new Error(`${where} status must be a successful 2xx integer, received ${status}`);
-  }
-  if (ep.output && (status === 204 || status === 205)) {
-    throw new Error(`${where} cannot combine output with bodyless status ${status}`);
-  }
-  if (ep.rawResponse)
-    throw new Error(`${where} cannot also be a rawResponse endpoint`);
-  if ("toolName" in ep && ep.toolName)
-    throw new Error(`${where} cannot set a toolName`);
-  if ("ui" in ep && ep.ui)
-    throw new Error(`${where} cannot set MCP ui metadata`);
-  if ("annotations" in ep && ep.annotations) {
-    throw new Error(`${where} cannot set MCP annotations`);
-  }
-  const nonHttp = (ep.expose ?? []).filter((transport) => transport !== "HTTP");
-  if (nonHttp.length > 0) {
-    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
-  }
-}
-function mergeMeta(contractMeta, endpointMeta) {
-  if (!contractMeta)
-    return endpointMeta;
-  if (!endpointMeta)
-    return { ...contractMeta };
-  return { ...contractMeta, ...endpointMeta };
-}
-// src/contract/errors-factory.ts
-import { z as z2 } from "zod";
-// src/contract/pagination.ts
-import { z as z3 } from "zod";
-
-// src/internal/base64url.ts
-function bytesToBase64Url(bytes) {
-  let binary = "";
-  for (const byte of bytes)
-    binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function base64UrlToBytes(segment) {
-  if (!/^[A-Za-z0-9_-]*$/.test(segment) || segment.length % 4 === 1) {
-    throw new Error("invalid base64url segment");
-  }
-  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
-  return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
-}
-// src/contract/stream.ts
-import { z as z4 } from "zod";
-var DEFAULT_CONTRACT_STREAM_FRAME_BYTES = 256 * 1024;
-var ContractStreamFrameSchema = z4.discriminatedUnion("type", [
-  z4.object({ type: z4.literal("data"), data: z4.unknown() }).strict(),
-  z4.object({
-    type: z4.literal("error"),
-    error: z4.object({
-      code: z4.string(),
-      message: z4.string().optional(),
-      details: z4.unknown().optional(),
-      hint: z4.string().optional()
-    }).strict()
-  }).strict(),
-  z4.object({ type: z4.literal("end") }).strict()
-]);
-export { joinRoutePath, parseTrailingWildcard, isUnsafeKey, safeJsonParse, defineContract, mergeMeta, bytesToBase64Url, base64UrlToBytes, DEFAULT_CONTRACT_STREAM_FRAME_BYTES, ContractStreamFrameSchema };