stitchkit 0.90.6 → 0.90.8

package/CHANGELOG.md

@@ -15,6 +15,58 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.90.8] — 2026-09-21
+
+### Added
+
+- **Every advertised MCP tool and every tool result now carries a catalog
+  stamp** — `_meta["stitchkit/catalog"] = { digest, tools }`, the fingerprint of
+  the exact advertised surface. A long-lived consumer stores it when it lists the
+  tools and compares it on responses it was already receiving, so it learns its
+  own copy of the contract is stale **without making a request to find out** —
+  including on the refusal that a stale copy causes, which is when the question
+  actually gets asked. `mcpCatalogStamp`, `readMcpCatalogStamp`,
+  `mcpCatalogMeta`, `MCP_CATALOG_META_KEY` and `McpCatalogStamp` are exported
+  from `stitchkit/tools`. `notifications/tools/list_changed` is the push-shaped
+  answer to the same problem and `createMcpHandler` cannot send it — it is
+  stateless by construction, so there is no retained session to notify; that
+  boundary is stated in `docs/architecture/mcp-semantics.md` rather than papered
+  over.
+
+### Fixed
+
+- **A refused union now names the branch and the field instead of only
+  `(root)`.** Zod reports a failed `z.union` as one issue — code
+  `invalid_union`, path `(root)`, message `Invalid input` — and every per-branch
+  reason it computed was discarded on the way to the wire. The refusal therefore
+  said that a request was wrong and nothing about what would have been right, so
+  whoever hit it blamed the source. `zodIssues` now descends into the branches:
+  the union's own issue carries a message naming each branch and where it
+  failed, and each branch failure arrives as its own issue with a full path and
+  a `branch` number. `formatZodError` and realtime rejection reports carry the
+  same detail. Additive — the issue shape gained an optional field and lost
+  nothing.
+
+## [0.90.7] — 2026-09-21
+
+### Fixed
+
+- Release workflows now remain safely rerunnable after another package in the
+  same train reaches npm, candidate registration stays repeatable after
+  publication, and registry polling tolerates normal multi-minute processing.
+- **A release train may no longer publish the framework together with the
+  starter that has to pin it.** The starter's lockfile is written by an install,
+  so it can only resolve a version npm already serves; a train doing both at
+  once states two things that cannot both hold, and the starter it publishes is
+  a version behind from its first minute. `create-stitchkit@0.6.1` shipped that
+  way. The refusal is narrow — a starter deliberately targeting an older minor
+  still rides along with a new one — and it reads the train file rather than the
+  registry, so every attempt at the same commit gets the same answer.
+- **The starter lockfile gate now also refuses a pin npm does not serve.** Its
+  staleness comparison only ever looked downward, so a lockfile naming a version
+  above the newest published one passed every check and left the scaffold to die
+  at `bun install` on the consumer's machine.
+
 ## [0.90.6] — 2026-09-20
 
 ### Added

package/dist/agent-runtime-harness.js

@@ -6,7 +6,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "./index-s208wab5.js";
+} from "./index-4yktadec.js";
 import"./index-p13mwz16.js";
 import"./index-y64k3s0h.js";
 import {
@@ -19,10 +19,10 @@ import {
   walkContainedFiles
 } from "./index-bn2cjajt.js";
 import"./index-7rkhw9ec.js";
-import"./index-8pjqv3zh.js";
+import"./index-1ft2wrv0.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-2hryh65w.js";
+import"./index-42f33bzd.js";
 import"./index-nrqg8tks.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";

package/dist/agent-runtime.js

@@ -31,7 +31,7 @@ import {
   renderAgentStateSlots,
   repairedSearchCall,
   selectAgentHistory
-} from "./index-s208wab5.js";
+} from "./index-4yktadec.js";
 import"./index-p13mwz16.js";
 import {
   AgentAdmissionEventSchema,
@@ -169,14 +169,14 @@ import {
 import {
   buildToolManifest,
   mountAgent
-} from "./index-83fafqw8.js";
+} from "./index-p48nc8g9.js";
 import"./index-7rkhw9ec.js";
-import"./index-zsdgd1tz.js";
-import"./index-1bnkzq95.js";
-import"./index-8pjqv3zh.js";
+import"./index-w58rfj2d.js";
+import"./index-dggfq62w.js";
+import"./index-1ft2wrv0.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-2hryh65w.js";
+import"./index-42f33bzd.js";
 import"./index-nrqg8tks.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";

package/dist/cli.js

@@ -11,14 +11,14 @@ import {
   readCapped,
   renderCliView,
   routeCliArgv
-} from "./index-fqg5mfk7.js";
+} from "./index-mthq65vn.js";
 import"./index-sbdmyz75.js";
-import"./index-zsdgd1tz.js";
-import"./index-1bnkzq95.js";
-import"./index-8pjqv3zh.js";
+import"./index-w58rfj2d.js";
+import"./index-dggfq62w.js";
+import"./index-1ft2wrv0.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-2hryh65w.js";
+import"./index-42f33bzd.js";
 import"./index-nrqg8tks.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";

package/dist/{index-tgh3ksfh.js → index-03bvcv7r.js}

@@ -1,10 +1,10 @@
 import {
   collectTools,
   createToolRunner
-} from "./index-1bnkzq95.js";
+} from "./index-dggfq62w.js";
 import {
   toolErrorFromResult
-} from "./index-8pjqv3zh.js";
+} from "./index-1ft2wrv0.js";
 import {
   assertUniqueToolName
 } from "./index-fenaekmk.js";

package/dist/index-0j3vcp5m.js

@@ -0,0 +1,28 @@
+import {
+  isRecord
+} from "./index-77fekveh.js";
+
+// src/internal/canonical-json.ts
+function compareCodepoints(left, right) {
+  if (left < right)
+    return -1;
+  if (left > right)
+    return 1;
+  return 0;
+}
+function canonicalValue(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalValue);
+  if (!isRecord(value))
+    return value;
+  const result = {};
+  for (const key of Object.keys(value).sort(compareCodepoints)) {
+    result[key] = canonicalValue(value[key]);
+  }
+  return result;
+}
+function serializeCanonicalJson(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+
+export { compareCodepoints, serializeCanonicalJson };

package/dist/{index-8pjqv3zh.js → index-1ft2wrv0.js}

@@ -6,7 +6,7 @@ import {
   formatZodError,
   normalizeError,
   validateDeclaredOutput
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 import {
   coerceJsonArgs
 } from "./index-7zbps32p.js";

package/dist/{index-2hryh65w.js → index-42f33bzd.js}

@@ -10,21 +10,62 @@ import { z } from "zod";
 function issuePath(path) {
   return path.length > 0 ? path.map(String).join(".") : "(root)";
 }
+var MAX_UNION_DEPTH = 3;
+var MAX_DESCRIBED_BRANCHES = 5;
+function unionBranches(issue) {
+  const errors = Reflect.get(issue, "errors");
+  if (!Array.isArray(errors) || errors.length === 0)
+    return;
+  if (!errors.every((branch) => Array.isArray(branch)))
+    return;
+  return errors;
+}
+function unionSummary(branches, prefix) {
+  const described = branches.slice(0, MAX_DESCRIBED_BRANCHES).map((issues, index) => {
+    const first = issues[0];
+    if (!first)
+      return `branch ${index + 1} reported no reason`;
+    return `branch ${index + 1} at ${issuePath([...prefix, ...first.path])}: ${first.message}`;
+  });
+  const rest = branches.length - described.length;
+  const suffix = rest > 0 ? `; ...and ${rest} more branches` : "";
+  return `No union branch matched — ${described.join("; ")}${suffix}`;
+}
+function collectIssues(issues, prefix, branch, depth, into) {
+  for (const issue of issues) {
+    const path = [...prefix, ...issue.path];
+    const branches = depth < MAX_UNION_DEPTH ? unionBranches(issue) : undefined;
+    into.push({
+      path: issuePath(path),
+      code: issue.code,
+      message: branches ? unionSummary(branches, path) : issue.message,
+      ...branch !== undefined && { branch }
+    });
+    if (!branches)
+      continue;
+    branches.forEach((branchIssues, index) => {
+      collectIssues(branchIssues, path, index + 1, depth + 1, into);
+    });
+  }
+}
+function zodIssues(error) {
+  const issues = [];
+  collectIssues(error.issues, [], undefined, 0, issues);
+  return issues;
+}
+var MAX_FORMATTED_ISSUES = 5;
 function formatZodError(error) {
-  const issues = error.issues.slice(0, 5);
-  const lines = issues.map((issue) => `${issuePath(issue.path)}: ${issue.message}`);
-  const suffix = error.issues.length > 5 ? `
-...and ${error.issues.length - 5} more issues` : "";
+  const all = zodIssues(error);
+  const shown = all.slice(0, MAX_FORMATTED_ISSUES);
+  const lines = shown.map((issue) => {
+    const where = issue.branch === undefined ? issue.path : `${issue.path} (branch ${issue.branch})`;
+    return `${where}: ${issue.message}`;
+  });
+  const suffix = all.length > shown.length ? `
+...and ${all.length - shown.length} more issues` : "";
   return lines.join(`
 `) + suffix;
 }
-function zodIssues(error) {
-  return error.issues.map((issue) => ({
-    path: issuePath(issue.path),
-    code: issue.code,
-    message: issue.message
-  }));
-}
 var MAX_DETAIL_ISSUES = 20;
 function errorCode(err) {
   if (AppError.is(err))
@@ -109,4 +150,4 @@ function validateDeclaredOutput(schema, data, onStripped) {
   return validateHandlerOutput(schema, data, onStripped);
 }
 
-export { formatZodError, zodIssues, errorCode, recordedErrorMessage, normalizeError, validateDeclaredOutput };
+export { zodIssues, formatZodError, errorCode, recordedErrorMessage, normalizeError, validateDeclaredOutput };

package/dist/{index-s208wab5.js → index-4yktadec.js}

@@ -36,7 +36,7 @@ import {
 import {
   ToolExecutionControlError,
   isToolExecutionControlError
-} from "./index-8pjqv3zh.js";
+} from "./index-1ft2wrv0.js";
 import {
   isRecord,
   transportResult

package/dist/{index-vy2nxwg8.js → index-adj0pc9r.js}

@@ -3,7 +3,7 @@ import {
   inputIsQuery,
   parseSSE,
   readBoundedUtf8Lines
-} from "./index-1txvygak.js";
+} from "./index-zjze12x8.js";
 import {
   ApiError,
   RequestCancellationError,

package/dist/{index-1bnkzq95.js → index-dggfq62w.js}

@@ -1,6 +1,6 @@
 import {
   executeToolMethod
-} from "./index-8pjqv3zh.js";
+} from "./index-1ft2wrv0.js";
 import {
   assertToolExtensionCompatible,
   mergeSchemas,

package/dist/{index-fqg5mfk7.js → index-mthq65vn.js}

@@ -3,19 +3,19 @@ import {
 } from "./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-zsdgd1tz.js";
+} from "./index-w58rfj2d.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-1bnkzq95.js";
+} from "./index-dggfq62w.js";
 import {
   toolErrorFromResult,
   toolResultFromError
-} from "./index-8pjqv3zh.js";
+} from "./index-1ft2wrv0.js";
 import {
   formatZodError,
   validateDeclaredOutput
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 import {
   coerceJsonArgs
 } from "./index-7zbps32p.js";

package/dist/{index-83fafqw8.js → index-p48nc8g9.js}

@@ -4,16 +4,16 @@ import {
 } from "./index-7rkhw9ec.js";
 import {
   collectToolSurface
-} from "./index-zsdgd1tz.js";
+} from "./index-w58rfj2d.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-1bnkzq95.js";
+} from "./index-dggfq62w.js";
 import {
   isToolExecutionControlError,
   toolCauseFromResult,
   toolResultFromError
-} from "./index-8pjqv3zh.js";
+} from "./index-1ft2wrv0.js";
 import {
   isRecord
 } from "./index-77fekveh.js";

package/dist/{index-7gqx71yd.js → index-qd8gs6nf.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-2qzskm8h.js";
 import {
   zodIssues
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 import {
   AppError
 } from "./index-scs3f1eg.js";
@@ -43,7 +43,13 @@ function parseIssues(value) {
     const code = Reflect.get(entry, "code");
     const message = Reflect.get(entry, "message");
     if (typeof path === "string" && typeof code === "string" && typeof message === "string") {
-      issues.push({ path, code, message });
+      const branch = Reflect.get(entry, "branch");
+      issues.push({
+        path,
+        code,
+        message,
+        ...typeof branch === "number" && Number.isInteger(branch) && branch > 0 && { branch }
+      });
     }
   }
   return issues.length > 0 ? issues : undefined;

package/dist/{index-zsdgd1tz.js → index-w58rfj2d.js}

@@ -1,6 +1,6 @@
 import {
   contractToolMountable
-} from "./index-1bnkzq95.js";
+} from "./index-dggfq62w.js";
 import {
   runtimeToolMountable
 } from "./index-8z9we758.js";

package/dist/{index-640tz39q.js → index-xrwgzjw8.js}

@@ -10,7 +10,7 @@ import {
 import {
   createValidatedRealtimeSocket,
   isModuleNotFound
-} from "./index-7gqx71yd.js";
+} from "./index-qd8gs6nf.js";
 import {
   DEFAULT_PROCESS_SIGNALS,
   RUNTIME_CONTEXT_RESERVED_KEYS,
@@ -41,7 +41,7 @@ import {
   normalizeError,
   recordedErrorMessage,
   validateDeclaredOutput
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   joinRoutePath,

package/dist/{index-1txvygak.js → index-zjze12x8.js}

@@ -1,6 +1,6 @@
 import {
   normalizeError
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 
 // src/internal/bounded-lines.ts
 var DEFAULT_STREAM_LINE_BYTES = 1024 * 1024;

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   createUrlBuilder,
   createUrlBuilders,
   parseNDJSON
-} from "./index-vy2nxwg8.js";
+} from "./index-adj0pc9r.js";
 import {
   REALTIME_REJECTION_KEY,
   asRealtimeRejection,
@@ -23,7 +23,7 @@ import {
   isModuleNotFound,
   parseRealtimeRequestAcknowledgement,
   parseRealtimeRequestArguments
-} from "./index-7gqx71yd.js";
+} from "./index-qd8gs6nf.js";
 import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
@@ -34,7 +34,7 @@ import {
 } from "./index-2qzskm8h.js";
 import {
   parseSSE
-} from "./index-1txvygak.js";
+} from "./index-zjze12x8.js";
 import {
   LiveStateControllerStatusSchema,
   LiveStatePhaseSchema,
@@ -49,7 +49,7 @@ import {
 import {
   formatZodError,
   zodIssues
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 import {
   ALL_TRANSPORTS,
   ContractStreamFrameSchema,

package/dist/internal/canonical-json.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Codepoint order, not locale order.
+ *
+ * `Array.prototype.sort` without a comparator is codepoint order already, but
+ * `localeCompare` is what a reader reaches for — and it would make a digest
+ * depend on the machine's locale, which is the one input a fingerprint must
+ * never have.
+ */
+export declare function compareCodepoints(left: string, right: string): number;
+/**
+ * Canonical bytes for a JSON value — object keys sorted, array order kept.
+ *
+ * The single serialisation behind every digest this repository takes of a
+ * declared surface: the committed manifest snapshot and the live MCP catalog
+ * stamp. Two implementations of "the same bytes" would eventually disagree,
+ * and a fingerprint that disagrees with itself reports drift that never
+ * happened.
+ */
+export declare function serializeCanonicalJson(value: unknown): string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/internal/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/internal/canonical-json.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrE;AAYD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7D"}

package/dist/internal/errors.d.ts

@@ -1,6 +1,5 @@
 import { type ZodType, z } from 'zod';
 import { AppError } from '../contract/index.js';
-export declare function formatZodError(error: z.ZodError): string;
 /** One field-level validation issue — the structured sibling of `formatZodError`. */
 export interface ZodIssueSummary {
     /** Dotted path to the offending field (`(root)` for a top-level issue). */
@@ -9,14 +8,24 @@ export interface ZodIssueSummary {
     code: string;
     /** Human-readable message for this field. */
     message: string;
+    /**
+     * 1-based index of the union branch that produced this issue, counted within
+     * the nearest enclosing union. Absent when no union was involved.
+     */
+    branch?: number;
 }
 /**
  * Project a `ZodError` into structured, wire-safe field issues — path / code /
- * message only, nothing server-internal. For a machine client that matches on
- * fields rather than parsing the text `message`. Returns every issue; a caller
- * that bounds response size slices it (see `normalizeError`).
+ * message (and a union branch, where one applies) — nothing server-internal.
+ * For a machine client that matches on fields rather than parsing the text
+ * `message`. Returns every issue; a caller that bounds response size slices it
+ * (see `normalizeError`).
+ *
+ * A failed union contributes its own issue AND one issue per branch failure, so
+ * the refusal names the branch and the path instead of only `(root)`.
  */
 export declare function zodIssues(error: z.ZodError): ZodIssueSummary[];
+export declare function formatZodError(error: z.ZodError): string;
 /**
  * The stable error code for a thrown value — `AppError.code`, `VALIDATION_ERROR`
  * for a `ZodError`, else `undefined`. Side-effect-free (unlike `normalizeError`,

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,MAAM,EAAE,OAAO,GACd,MAAM,GAAG,SAAS,CAYpB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAyBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAI9D;AAKD,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAWxD;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,MAAM,EAAE,OAAO,GACd,MAAM,GAAG,SAAS,CAYpB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAyBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}

package/dist/node.js

@@ -5,7 +5,7 @@ import {
   createHandler,
   createSocketIOServer,
   createUnixClientTransport
-} from "./index-640tz39q.js";
+} from "./index-xrwgzjw8.js";
 import"./index-y91ry9h2.js";
 import {
   ShutdownOptionsSchema,
@@ -14,7 +14,7 @@ import {
   ShutdownStatusSchema,
   createServerLifecycle
 } from "./index-3z73fh2c.js";
-import"./index-7gqx71yd.js";
+import"./index-qd8gs6nf.js";
 import"./index-2qzskm8h.js";
 import {
   createImplement,
@@ -27,7 +27,7 @@ import {
 } from "./index-aj9geeez.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-2hryh65w.js";
+import"./index-42f33bzd.js";
 import"./index-nrqg8tks.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";

package/dist/observability/index.js

@@ -27,7 +27,7 @@ import {
 import"../index-f9mb610r.js";
 import {
   recordedErrorMessage
-} from "../index-2hryh65w.js";
+} from "../index-42f33bzd.js";
 import"../index-nrqg8tks.js";
 import"../index-rxfy4cq7.js";
 import"../index-6k1937bx.js";

package/dist/realtime/rejected-frame.d.ts

@@ -39,6 +39,12 @@ export interface RealtimeRejectionIssue {
     path: string;
     code: string;
     message: string;
+    /**
+     * The union branch the issue came from, when the refused field was a union.
+     * Without it a refused union reports only its own position and the word
+     * `invalid_union`, which names no field at all.
+     */
+    branch?: number;
 }
 /**
  * At most this many issues travel; a refusal is a signal, not a report.

package/dist/realtime/rejected-frame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rejected-frame.d.ts","sourceRoot":"","sources":["../../src/realtime/rejected-frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,iCAAiC,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,yBAAyB;IACxC,CAAC,sBAAsB,CAAC,EAAE,uBAAuB,CAAC;CACnD;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,uBAAuB,GAC9B,yBAAyB,CAE3B;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAgBlF"}
+{"version":3,"file":"rejected-frame.d.ts","sourceRoot":"","sources":["../../src/realtime/rejected-frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,iCAAiC,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,yBAAyB;IACxC,CAAC,sBAAsB,CAAC,EAAE,uBAAuB,CAAC;CACnD;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,uBAAuB,GAC9B,yBAAyB,CAE3B;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAgBlF"}

package/dist/remote.js

@@ -1,11 +1,11 @@
 import {
   createClient
-} from "./index-vy2nxwg8.js";
-import"./index-1txvygak.js";
+} from "./index-adj0pc9r.js";
+import"./index-zjze12x8.js";
 import {
   ApiError
 } from "./index-3xwxfj4z.js";
-import"./index-2hryh65w.js";
+import"./index-42f33bzd.js";
 import {
   mergeMeta,
   resolveRouteParamsSchema

package/dist/server/index.js

@@ -13,7 +13,7 @@ import {
   sseRoute,
   streamingRoute,
   webSocketLane
-} from "../index-640tz39q.js";
+} from "../index-xrwgzjw8.js";
 import"../index-y91ry9h2.js";
 import {
   withDeadline
@@ -25,13 +25,13 @@ import {
   ShutdownStatusSchema,
   createServerLifecycle
 } from "../index-3z73fh2c.js";
-import"../index-7gqx71yd.js";
+import"../index-qd8gs6nf.js";
 import"../index-2qzskm8h.js";
 import {
   inputIsQuery,
   parseSSE,
   streamSSE
-} from "../index-1txvygak.js";
+} from "../index-zjze12x8.js";
 import {
   composeAuthHooks,
   createAuthHook,
@@ -82,7 +82,7 @@ import {
   formatZodError,
   normalizeError,
   zodIssues
-} from "../index-2hryh65w.js";
+} from "../index-42f33bzd.js";
 import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   joinRoutePath,

package/dist/testing/surface-manifest.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { serializeCanonicalJson } from '../internal/canonical-json.js';
 import type { RealtimeContract, RealtimeEventRegistry } from '../realtime/contract.js';
 import type { RouteGroup, ServiceDef } from '../server/types.js';
 import type { CliCommandDefinition } from '../tools/cli-command.js';
@@ -248,7 +249,7 @@ export interface SurfaceManifestConfig {
     extensions?: readonly SurfaceManifestExtension[];
 }
 /** Canonical bytes used by snapshots and schema digests. Arrays retain order. */
-export declare function serializeSurfaceValue(value: unknown): string;
+export declare const serializeSurfaceValue: typeof serializeCanonicalJson;
 /** Build one versioned snapshot of the declared transport-specific surface. */
 export declare function buildSurfaceManifest(config: SurfaceManifestConfig): SurfaceManifest;
 export declare function assertSurfaceManifestSnapshot(manifest: SurfaceManifest, snapshot: SurfaceManifest): void;

package/dist/testing/surface-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface-manifest.d.ts","sourceRoot":"","sources":["../../src/testing/surface-manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surface-manifest.d.ts","sourceRoot":"","sources":["../../src/testing/surface-manifest.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -28,15 +28,19 @@ import {
 import {
   createClient,
   createClients
-} from "./index-vy2nxwg8.js";
+} from "./index-adj0pc9r.js";
 import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
   RealtimeRequestTimeoutError
 } from "./index-2qzskm8h.js";
-import"./index-1txvygak.js";
+import"./index-zjze12x8.js";
 import"./index-3xwxfj4z.js";
-import"./index-2hryh65w.js";
+import {
+  compareCodepoints,
+  serializeCanonicalJson
+} from "./index-0j3vcp5m.js";
+import"./index-42f33bzd.js";
 import {
   joinRoutePath
 } from "./index-nrqg8tks.js";
@@ -1544,27 +1548,7 @@ var SurfaceManifestSchema = z2.object({
   cliOnly: z2.array(SurfaceManifestCliCommandSchema),
   extensions: z2.array(SurfaceManifestExtensionSchema)
 });
-function compareCodepoints(left, right) {
-  if (left < right)
-    return -1;
-  if (left > right)
-    return 1;
-  return 0;
-}
-function canonicalValue(value) {
-  if (Array.isArray(value))
-    return value.map(canonicalValue);
-  if (!isRecord(value))
-    return value;
-  const result = {};
-  for (const key of Object.keys(value).sort(compareCodepoints)) {
-    result[key] = canonicalValue(value[key]);
-  }
-  return result;
-}
-function serializeSurfaceValue(value) {
-  return JSON.stringify(canonicalValue(value));
-}
+var serializeSurfaceValue = serializeCanonicalJson;
 function digestValue(value) {
   return createHash("sha256").update(serializeSurfaceValue(value)).digest("hex").slice(0, 16);
 }

package/dist/tool-invoker.js

@@ -1,11 +1,11 @@
 import {
   createToolInvoker
-} from "./index-tgh3ksfh.js";
-import"./index-1bnkzq95.js";
-import"./index-8pjqv3zh.js";
+} from "./index-03bvcv7r.js";
+import"./index-dggfq62w.js";
+import"./index-1ft2wrv0.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-2hryh65w.js";
+import"./index-42f33bzd.js";
 import"./index-nrqg8tks.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";

package/dist/tools/mcp-catalog.d.ts

@@ -0,0 +1,68 @@
+import type { PreparedMcpServerSurface } from './mcp-prepare.js';
+/**
+ * The `_meta` key carrying the catalog stamp, on every advertised tool and on
+ * every tool result.
+ *
+ * Namespaced, because `_meta` is shared ground: a host, the official SDK and
+ * the application all write into it, and a bare `catalog` would eventually mean
+ * two things at once.
+ */
+export declare const MCP_CATALOG_META_KEY = "stitchkit/catalog";
+/**
+ * What the server says its advertised catalog currently is.
+ *
+ * `digest` changes whenever any advertised tool's name, description, input
+ * schema, output schema or annotations change — and only then. `tools` is the
+ * count, carried because it makes a mismatch legible without a second lookup
+ * ("they advertise 41, I hold 39").
+ */
+export interface McpCatalogStamp {
+    digest: string;
+    tools: number;
+}
+/**
+ * Fingerprint one advertised MCP catalog.
+ *
+ * The problem this answers is not a broken server — it is a **consumer holding
+ * an old idea of the contract and unable to find out**. A long-lived session
+ * lists the tools once; the server is redeployed with a renamed field; every
+ * later call is refused, and the refusal looks to the consumer like a fault in
+ * the source, because a stale catalog is invisible from inside. The fix has to
+ * ride on responses the consumer is already receiving, so it can compare what
+ * it holds against what is live without asking anything extra.
+ *
+ * `notifications/tools/list_changed` is the push-shaped answer, and this
+ * framework's MCP HTTP handler cannot send it: it is stateless by construction
+ * (`createMcpHandler` builds a fresh server per request and keeps no session),
+ * so there is no retained stream to notify. The stamp works precisely because
+ * it needs no session.
+ */
+export declare function mcpCatalogStamp(surface: PreparedMcpServerSurface): McpCatalogStamp;
+/** The `_meta` fragment a stamped tool or result carries. */
+export declare function mcpCatalogMeta(stamp: McpCatalogStamp): Record<string, unknown>;
+/**
+ * Read a catalog stamp out of a peer's `_meta`, or `null` when there is none.
+ *
+ * Parsed, not trusted: this arrives over the wire from another process, and the
+ * fact that it describes a catalog does not exempt it from being validated.
+ */
+export declare function readMcpCatalogStamp(meta: unknown): McpCatalogStamp | null;
+/**
+ * Attach the stamp to a tool registration, so `tools/list` carries the catalog
+ * the listing came from — the value a consumer stores alongside the tools.
+ */
+export declare function stampToolRegistration<TConfig extends {
+    _meta?: Record<string, unknown>;
+}>(config: TConfig, stamp: McpCatalogStamp | undefined): TConfig;
+/**
+ * Attach the stamp to a tool result.
+ *
+ * This is the half that matters. A consumer compares it against the stamp it
+ * stored at listing time, on a response it was going to receive anyway, and so
+ * learns its catalog is stale WITHOUT asking — including on the refusal that a
+ * stale catalog causes, which is exactly when the question gets asked.
+ */
+export declare function stampToolResult<TResult extends {
+    _meta?: Record<string, unknown>;
+}>(result: TResult, stamp: McpCatalogStamp | undefined): TResult;
+//# sourceMappingURL=mcp-catalog.d.ts.map

package/dist/tools/mcp-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-catalog.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-catalog.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAmB,MAAM,eAAe,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,eAAe,CAclF;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAQzE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACvF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACjF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT"}

package/dist/tools/mcp.d.ts

@@ -2,6 +2,7 @@ import { McpServer, type ServerOptions } from '@modelcontextprotocol/server';
 import type { ServiceDef, StitchLogger } from '../server/types.js';
 import { type ErrorHintFn, type ToolCallHooks, type ToolLifecycle } from './execute.js';
 import { type McpResourceDef } from './mcp-app.js';
+import { type McpCatalogStamp } from './mcp-catalog.js';
 import { type McpSchemaValidationConfig, type McpSurfaceRegistry, type PreparedMcpServerSurface, type PreparedMcpSurface, type ValidateMcpSchemasConfig } from './mcp-prepare.js';
 import { type McpRoundRuntime } from './mcp-round.js';
 import { type ToolExtend } from './mount.js';
@@ -33,6 +34,8 @@ export interface McpMountConfig {
 }
 interface PreparedMcpMountConfig extends McpMountConfig {
     multiRoundRuntime?: McpRoundRuntime;
+    /** The catalog this surface advertises, stamped onto listings and results. */
+    catalog?: McpCatalogStamp;
 }
 /**
  * Validate that every contract tool in `services` can be advertised on the MCP

package/dist/tools/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"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"}

package/dist/tools/native-mcp.d.ts

@@ -1,5 +1,6 @@
 import { type CallToolResult, type McpServer } from '@modelcontextprotocol/server';
 import { executeToolMethod, type ToolCallHooks, type ToolLifecycle } from './execute.js';
+import { type McpCatalogStamp } from './mcp-catalog.js';
 import type { PreparedRuntimeMcpTool } from './mcp-prepare.js';
 import type { McpRoundRuntime } from './mcp-round.js';
 interface NativeMcpRuntimeConfig {
@@ -9,6 +10,8 @@ interface NativeMcpRuntimeConfig {
     coerceJsonArgs?: boolean;
     onOutputStrip?: (toolName: string, paths: string[]) => void;
     multiRoundRuntime?: McpRoundRuntime;
+    /** The catalog this surface advertises, stamped onto listings and results. */
+    catalog?: McpCatalogStamp;
     formatResult: (result: Awaited<ReturnType<typeof executeToolMethod>>, mode: PreparedRuntimeMcpTool['descriptor']['outputMode'], toolName: string) => CallToolResult;
 }
 /** Mount immutable runtime-tool descriptors onto one fresh MCP server/runtime. */

package/dist/tools/native-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-mcp.d.ts","sourceRoot":"","sources":["../../src/tools/native-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,UAAU,sBAAsB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,YAAY,EAAE,CACZ,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,EACrD,IAAI,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,EACxD,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;CACrB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAkHN"}
+{"version":3,"file":"native-mcp.d.ts","sourceRoot":"","sources":["../../src/tools/native-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,KAAK,eAAe,EAA0C,MAAM,eAAe,CAAC;AAC7F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,UAAU,sBAAsB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,CACZ,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,EACrD,IAAI,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,EACxD,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;CACrB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAwHN"}

package/dist/tools.d.ts

@@ -21,6 +21,7 @@ export { listContractToolNames, listToolNames, type ToolNameEntry, } from './too
 export { buildToolManifest, describeToolCatalog, type ToolCatalogConfig, type ToolCatalogEntry, type ToolManifestConfig, type ToolManifestEntry, } from './tools/manifest.js';
 export { buildMcpServer, type DirectMcpSurfaceConfig, type FiniteMcpSurfaceConfig, type McpMountConfig, type McpServerBuildConfig, type McpServerSharedConfig, mountMcp, mountMcpResource, validateMcpSchemas, } from './tools/mcp.js';
 export { EXT_APPS_BUNDLE_PLACEHOLDER, inlineMcpAppBundle, type McpAppCsp, type McpAppResourceMeta, type McpResourceDef, RESOURCE_MIME_TYPE, } from './tools/mcp-app.js';
+export { MCP_CATALOG_META_KEY, type McpCatalogStamp, mcpCatalogMeta, readMcpCatalogStamp, } from './tools/mcp-catalog.js';
 export { createMcpHandler, createMcpHttpRoute, type McpHandlerConfig, type McpHttpConfig, type McpHttpHandler, type McpHttpSecurityConfig, type McpLegacyPolicy, } from './tools/mcp-handler.js';
 export type { IncompatibleSchemaPolicy, McpSchemaValidationConfig, McpSurfaceDefinition, McpSurfaceRegistry, ValidateMcpSchemasConfig, } from './tools/mcp-prepare.js';
 export { createStdioMcpServer, type McpStdioHandle, type StdioAuthConfig, type StdioMcpServerConfig, } from './tools/mcp-stdio.js';

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -1,3 +1,7 @@
+import {
+  compareCodepoints,
+  serializeCanonicalJson
+} from "./index-0j3vcp5m.js";
 import {
   ManagedFileError
 } from "./index-actkayzn.js";
@@ -22,7 +26,7 @@ import {
   buildToolManifest,
   describeToolCatalog,
   mountAgent
-} from "./index-83fafqw8.js";
+} from "./index-p48nc8g9.js";
 import"./index-7rkhw9ec.js";
 import {
   argumentsDigest
@@ -38,7 +42,7 @@ import {
 } from "./index-4fpa9dy2.js";
 import {
   createToolInvoker
-} from "./index-tgh3ksfh.js";
+} from "./index-03bvcv7r.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -47,22 +51,22 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-fqg5mfk7.js";
+} from "./index-mthq65vn.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-zsdgd1tz.js";
+} from "./index-w58rfj2d.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-1bnkzq95.js";
+} from "./index-dggfq62w.js";
 import {
   ToolExecutionControlError,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-8pjqv3zh.js";
+} from "./index-1ft2wrv0.js";
 import {
   getRequestContext,
   getTraceId,
@@ -71,7 +75,7 @@ import {
 import"./index-f9mb610r.js";
 import {
   normalizeError
-} from "./index-2hryh65w.js";
+} from "./index-42f33bzd.js";
 import {
   defineContract
 } from "./index-nrqg8tks.js";
@@ -101,7 +105,9 @@ import {
   presentationMetadata,
   validateMcpRoundPolicy
 } from "./index-fenaekmk.js";
-import"./index-cby4ar3v.js";
+import {
+  toJsonSchema
+} from "./index-cby4ar3v.js";
 import {
   AppError,
   STITCH_ERROR_STATUS
@@ -946,6 +952,63 @@ function inlineMcpAppBundle(html) {
   return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
 }
 
+// src/tools/mcp-catalog.ts
+import { createHash } from "node:crypto";
+var MCP_CATALOG_META_KEY = "stitchkit/catalog";
+var stampCache = new WeakMap;
+function toolFingerprint(descriptor) {
+  const { mountable } = descriptor;
+  return {
+    name: mountable.name,
+    description: mountable.method.desc,
+    input: descriptor.inputSchema,
+    output: descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema, "output", "any") : null,
+    annotations: mountable.method.annotations ?? null
+  };
+}
+function mcpCatalogStamp(surface) {
+  const cached = stampCache.get(surface);
+  if (cached)
+    return cached;
+  const descriptors = [
+    ...surface.contractTools,
+    ...surface.runtimeTools.map((entry) => entry.descriptor)
+  ].sort((left, right) => compareCodepoints(left.mountable.name, right.mountable.name));
+  const bytes = serializeCanonicalJson(descriptors.map(toolFingerprint));
+  const stamp = {
+    digest: createHash("sha256").update(bytes).digest("hex").slice(0, 16),
+    tools: descriptors.length
+  };
+  stampCache.set(surface, stamp);
+  return stamp;
+}
+function mcpCatalogMeta(stamp) {
+  return { [MCP_CATALOG_META_KEY]: { ...stamp } };
+}
+function readMcpCatalogStamp(meta) {
+  if (!isRecord(meta))
+    return null;
+  const value = meta[MCP_CATALOG_META_KEY];
+  if (!isRecord(value))
+    return null;
+  const { digest, tools } = value;
+  if (typeof digest !== "string" || digest.length === 0)
+    return null;
+  if (typeof tools !== "number" || !Number.isInteger(tools) || tools < 0)
+    return null;
+  return { digest, tools };
+}
+function stampToolRegistration(config, stamp) {
+  if (!stamp)
+    return config;
+  return { ...config, _meta: { ...config._meta, ...mcpCatalogMeta(stamp) } };
+}
+function stampToolResult(result, stamp) {
+  if (!stamp)
+    return result;
+  return { ...result, _meta: { ...result._meta, ...mcpCatalogMeta(stamp) } };
+}
+
 // src/tools/mcp-prepare.ts
 function textBlock(text) {
   return [{ type: "text", text }];
@@ -1283,7 +1346,7 @@ function mountPreparedRuntimeMcp(server, tools, config) {
         "ui/resourceUri": definition.ui.resourceUri
       };
     }
-    server.registerTool(definition.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, definition.name, async () => {
+    server.registerTool(definition.name, stampToolRegistration(toolConfig, config.catalog), async (rawArgs, mcpContext) => stampToolResult(await runInMcpRequestContext(mcpContext, definition.name, async () => {
       const args = isRecord(rawArgs) ? rawArgs : {};
       const runTool = (tool, toolArgs, roundContext) => executeToolMethod(tool.method, definition.name, toolArgs, { ...config.context, ...roundContext, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
       const round = await resolveMcpRound({
@@ -1323,7 +1386,7 @@ function mountPreparedRuntimeMcp(server, tools, config) {
         throw new Error("[stitchkit] Runtime MCP presenter invariant failed");
       }
       return presentedResult.data;
-    }));
+    }), config.catalog));
   }
 }
 
@@ -1343,7 +1406,10 @@ function mountMcp(mcpServer, services, config = {}) {
     schemaValidation: config.schemaValidation,
     logger: config.logger
   });
-  mountPreparedMcp(mcpServer, prepared, config);
+  mountPreparedMcp(mcpServer, prepared, {
+    ...config,
+    catalog: mcpCatalogStamp({ contractTools: prepared, runtimeTools: [] })
+  });
 }
 function mountPreparedMcp(mcpServer, prepared, config = {}) {
   const runTool = createToolRunner({
@@ -1373,7 +1439,7 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
         "ui/resourceUri": mountable.method.ui.resourceUri
       };
     }
-    mcpServer.registerTool(mountable.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, mountable.name, async () => {
+    mcpServer.registerTool(mountable.name, stampToolRegistration(toolConfig, config.catalog), async (rawArgs, mcpContext) => stampToolResult(await runInMcpRequestContext(mcpContext, mountable.name, async () => {
       const args = isRecord(rawArgs) ? rawArgs : {};
       try {
         const round = await resolveMcpRound({
@@ -1392,7 +1458,7 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
       } catch (err) {
         return formatMcpResult(toolResultFromError(err), "none", mountable.name, config.errorHint);
       }
-    }));
+    }), config.catalog));
   }
 }
 function buildMcpServer(config, auth) {
@@ -1454,7 +1520,9 @@ function buildMcpServerFromPrepared(config, auth, prepared) {
   };
   const server = new McpServer(config.serverInfo, serverOptions);
   const context = config.context?.(auth);
+  const catalog = mcpCatalogStamp(prepared);
   mountPreparedMcp(server, prepared.contractTools, {
+    catalog,
     context,
     hooks: config.hooks,
     lifecycle: config.lifecycle,
@@ -1473,6 +1541,7 @@ function buildMcpServerFromPrepared(config, auth, prepared) {
     }
   });
   mountPreparedRuntimeMcp(server, prepared.runtimeTools, {
+    catalog,
     context,
     hooks: config.hooks,
     lifecycle: config.lifecycle,
@@ -2683,6 +2752,7 @@ export {
   validateMcpSchemas,
   summarizeTransports,
   resolveMedia,
+  readMcpCatalogStamp,
   protectedResourceMetadataUrl,
   oauthProtectedResourceRoute,
   mountWait,
@@ -2693,6 +2763,7 @@ export {
   mountMcp,
   mountDownload,
   mountAgent,
+  mcpCatalogMeta,
   listToolNames,
   listContractToolNames,
   isToolExecutionControlError,
@@ -2737,6 +2808,7 @@ export {
   PORTABLE_JSON_SCHEMA_FORMATS,
   McpMediaContentSchema,
   McpAnnotationsSchema,
+  MCP_CATALOG_META_KEY,
   EXT_APPS_BUNDLE_PLACEHOLDER,
   AsyncOperationCancelResultSchema
 };

package/llms-full.txt

@@ -3446,6 +3446,42 @@ finite `surfaces` registry when identities share a provably immutable surface.
 Stitchkit never advertises list-change or subscription capabilities
 without an implementation.
 
+### Knowing your catalog is stale — the catalog stamp
+
+A client lists the tools once and keeps that list. If the server's contract
+moves afterwards, the client's copy is wrong and *nothing tells it so*: calls
+are refused, and from inside the client a refusal looks like a broken server.
+This is the most expensive shape a contract disagreement takes, because the
+party able to fix it is the one with no evidence.
+
+Every advertised tool and every tool result therefore carries the fingerprint of
+the catalog it came from:
+
+```ts
+import { readMcpCatalogStamp } from 'stitchkit/tools';
+
+const listed = await client.listTools();
+let known = readMcpCatalogStamp(listed.tools[0]?._meta); // { digest, tools }
+
+const result = await client.callTool({ name: 'record_journal', arguments });
+const live = readMcpCatalogStamp(result._meta);
+if (live && known && live.digest !== known.digest) {
+  // The catalog moved under us. Re-list before blaming the result.
+  known = readMcpCatalogStamp((await client.listTools()).tools[0]?._meta);
+}
+```
+
+The comparison costs nothing and runs on a response you were already receiving —
+including a refusal, which is exactly when a stale catalog is the likeliest
+explanation. `notifications/tools/list_changed` is the push-shaped answer to the
+same problem and `createMcpHandler` cannot send it: it is stateless by
+construction, so there is no retained session to push down.
+
+The digest covers each advertised tool's name, description, input schema, output
+schema and annotations, and nothing else — it moves when the contract moves and
+not when a handler does. Raw SDK registrations stay consumer-owned and are
+outside it.
+
 ### Typed MCP call metadata
 
 Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
@@ -17008,6 +17044,25 @@ A native remote-connector auth surface for MCP — [guide](../guide/mcp-and-agen
 | `RefreshData` | _type_ | a stored refresh-token record |
 | `RegisteredClient` | _type_ | a registered OAuth client |
 
+### Catalog stamp
+
+Every advertised tool and every tool result carries the fingerprint of the catalog it came
+from, so a long-lived consumer can see that its own copy is stale **without making a
+request for it**. `createMcpHandler` is stateless by construction and therefore has no
+retained session to push `notifications/tools/list_changed` down; the stamp needs none.
+
+Store the stamp beside the tools when you list them, compare it against the one on every
+result, and re-list when they differ — including on a refusal, which is exactly when a
+stale catalog is the likeliest explanation and the least visible one. The server side
+needs no wiring: every mount stamps what it advertises.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `readMcpCatalogStamp` | function | read a peer's stamp out of `_meta`, or `null` when there is none |
+| `mcpCatalogMeta` | function | the `_meta` fragment a stamped tool or result carries |
+| `MCP_CATALOG_META_KEY` | const | the namespaced `_meta` key (`stitchkit/catalog`) |
+| `McpCatalogStamp` | _type_ | `{ digest, tools }` — the catalog fingerprint and its tool count |
+
 ### MCP Apps (widgets)
 
 Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.90.6",
+  "version": "0.90.8",
   "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",