@cyanheads/mcp-ts-core 0.12.8 → 0.12.9

package/dist/services/mirror/types.d.ts.map

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

package/dist/utils/internal/performance.d.ts

@@ -12,7 +12,7 @@ export declare function initHandlerMetrics(): void;
  * Returns the current time in milliseconds using `globalThis.performance.now()`.
  *
  * Sub-millisecond resolution is guaranteed on all supported engine floors
- * (Node ≥24, Bun ≥1.3, Cloudflare Workers). The returned value is suitable for
+ * (Node ≥24, Bun ≥1.4, Cloudflare Workers). The returned value is suitable for
  * computing durations but its epoch origin is implementation-defined — do not
  * treat it as a wall-clock timestamp.
  *

package/dist/utils/internal/performance.js

@@ -54,14 +54,14 @@ function getActiveRequestsGauge() {
  * Returns the current time in milliseconds using `globalThis.performance.now()`.
  *
  * Sub-millisecond resolution is guaranteed on all supported engine floors
- * (Node ≥24, Bun ≥1.3, Cloudflare Workers). The returned value is suitable for
+ * (Node ≥24, Bun ≥1.4, Cloudflare Workers). The returned value is suitable for
  * computing durations but its epoch origin is implementation-defined — do not
  * treat it as a wall-clock timestamp.
  *
  * @returns Current time in milliseconds.
  */
 // performance is an ambient global declared by @types/node (perf_hooks.d.ts)
-// and available in all supported environments (Node ≥24, Bun ≥1.3, workerd).
+// and available in all supported environments (Node ≥24, Bun ≥1.4, workerd).
 export const nowMs = () => performance.now();
 // Module-level TextEncoder singleton (stateless, safe to reuse)
 let cachedEncoder;

package/dist/utils/network/fetchWithTimeout.js

@@ -479,7 +479,7 @@ export async function fetchWithTimeout(url, timeoutMs, context, options) {
     const timeoutReason = new DOMException(`${operationDescription} timed out after ${timeoutMs}ms.`, 'TimeoutError');
     const timeoutId = setTimeout(() => controller.abort(timeoutReason), timeoutMs);
     // Compose the timeout signal with any caller-supplied signal. AbortSignal.any
-    // is available on all supported floors (Node ≥24, Bun ≥1.3, workerd).
+    // is available on all supported floors (Node ≥24, Bun ≥1.4, workerd).
     const fetchSignal = externalSignal
         ? AbortSignal.any([controller.signal, externalSignal])
         : controller.signal;

package/dist/utils/network/retry.js

@@ -209,7 +209,7 @@ function sleep(ms, signal) {
             return;
         }
         const controller = new AbortController();
-        // AbortSignal.any is available on all supported floors (Node ≥24, Bun ≥1.3, workerd).
+        // AbortSignal.any is available on all supported floors (Node ≥24, Bun ≥1.4, workerd).
         const combined = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
         const timer = setTimeout(() => {
             controller.abort();

package/dist/utils/security/idGenerator.d.ts

@@ -64,8 +64,10 @@ export declare class IdGenerator {
     /**
      * Generates a cryptographically secure random string.
      * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
-     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @param charset - The character set to use, 1 to 256 characters. Defaults to `IdGenerator.DEFAULT_CHARSET`.
      * @returns The generated random string.
+     * @throws {McpError} With {@link JsonRpcErrorCode.ValidationError} when `charset` is empty
+     *   or longer than 256 characters — the sampler cannot terminate on either.
      */
     generateRandomString(length?: number, charset?: string): string;
     /**

package/dist/utils/security/idGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AA8CA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IACxE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IACvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAA0B;IAChD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;IACH,YAAY,cAAc,GAAE,kBAAuB,EAGlD;IAED;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAWjE;IAED;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB,CAE7C;IAED;;;;;OAKG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM,CAER;IAED;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAW1E;IAED;;;;;;OAMG;IACI,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAMtF;IAED;;;;;;;OAOG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAqBzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAGxF;IAED;;;;;;OAMG;IACI,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAe1F;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAStF;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAG3C,CAAC"}
+{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AAqDA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IACxE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IACvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAA0B;IAChD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;IACH,YAAY,cAAc,GAAE,kBAAuB,EAGlD;IAED;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAWjE;IAED;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB,CAE7C;IAED;;;;;;;OAOG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM,CAQR;IAED;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAW1E;IAED;;;;;;OAMG;IACI,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAMtF;IAED;;;;;;;OAOG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAqBzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAGxF;IAED;;;;;;OAMG;IACI,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAe1F;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAStF;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAG3C,CAAC"}

package/dist/utils/security/idGenerator.js

@@ -21,6 +21,8 @@ function getRandomBytes(count) {
     crypto.getRandomValues(bytes);
     return bytes;
 }
+/** Largest charset the byte-wise rejection sampler below can draw from. */
+const MAX_CHARSET_LENGTH = 256;
 /**
  * Builds a random string of `length` characters drawn uniformly from `charset`.
  *
@@ -28,6 +30,10 @@ function getRandomBytes(count) {
  * multiple of `charset.length` that fits in 256, so `byte % charset.length`
  * never biases toward the low characters. Bytes are drawn in over-sized chunks
  * rather than one at a time, so a typical ID costs one `getRandomValues` call.
+ *
+ * `charset` must hold 1 to {@link MAX_CHARSET_LENGTH} characters: an empty
+ * charset never grows `result`, and a longer one rejects every byte, so either
+ * would spin here forever. Public callers validate before reaching this.
  */
 function randomStringFromCharset(length, charset) {
     const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
@@ -103,10 +109,15 @@ export class IdGenerator {
     /**
      * Generates a cryptographically secure random string.
      * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
-     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @param charset - The character set to use, 1 to 256 characters. Defaults to `IdGenerator.DEFAULT_CHARSET`.
      * @returns The generated random string.
+     * @throws {McpError} With {@link JsonRpcErrorCode.ValidationError} when `charset` is empty
+     *   or longer than 256 characters — the sampler cannot terminate on either.
      */
     generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        if (charset.length === 0 || charset.length > MAX_CHARSET_LENGTH) {
+            throw validationError(`Charset must contain between 1 and ${MAX_CHARSET_LENGTH} characters; received ${charset.length}.`, { charsetLength: charset.length, max: MAX_CHARSET_LENGTH });
+        }
         return randomStringFromCharset(length, charset);
     }
     /**

package/dist/utils/security/idGenerator.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -212,8 +212,8 @@
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
     "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@supabase/supabase-js": "^2.115.0",
-    "@types/bun": "^1.4.1",
+    "@supabase/supabase-js": "^2.116.0",
+    "@types/bun": "^1.4.2",
     "@types/node": "26.4.0",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
@@ -230,7 +230,7 @@
     "execa": "^10.0.1",
     "fast-check": "^4.9.0",
     "fast-xml-parser": "^5.11.1",
-    "ignore": "^7.0.8",
+    "ignore": "^7.0.9",
     "js-yaml": "^5.4.1",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
@@ -282,7 +282,7 @@
   ],
   "packageManager": "bun@1.4.0",
   "engines": {
-    "bun": ">=1.3.0",
+    "bun": ">=1.4.0",
     "node": ">=24.0.0"
   },
   "depcheck": {
@@ -302,14 +302,14 @@
   "dependencies": {
     "@hono/node-server": "^2.1.1",
     "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/ext-apps": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.1",
     "dotenv": "^17.4.2",
     "hono": "^4.13.7",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
-    "zod": "^4.5.4"
+    "zod": "^4.6.0"
   },
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",

package/scripts/devcheck.ts

@@ -437,7 +437,8 @@ interface OutdatedRow {
   current: string;
   /** The declared key when attribution is unambiguous, else null. */
   declaredKey: string | null;
-  group: DependencyGroup | null;
+  /** The block the row belongs to; `bun outdated` leaves `prod` rows unmarked. */
+  group: DependencyGroup;
   /** The row verbatim, used to key the rendered rewrite back to its line. */
   line: string;
   /** First cell as printed, marker included. */
@@ -457,11 +458,11 @@ interface OutdatedRow {
  */
 function attributeOutdatedRow(
   target: string,
-  group: DependencyGroup | null,
+  group: DependencyGroup,
   current: string,
 ): Pick<OutdatedRow, 'candidates' | 'declaredKey'> {
   const matches = DECLARED_DEPENDENCIES.filter(
-    (declared) => declared.target === target && (group === null || declared.group === group),
+    (declared) => declared.target === target && declared.group === group,
   );
   const candidates = matches.map((declared) => declared.key);
   if (candidates.length <= 1) return { candidates, declaredKey: candidates[0] ?? null };
@@ -481,7 +482,7 @@ function parseOutdatedRows(output: string): OutdatedRow[] {
     const rawName = cells[1] ?? '';
     // Skip table chrome: header row and separator (e.g., "---")
     if (!rawName || rawName === 'Package' || /^-+$/.test(rawName)) continue;
-    const group = (OUTDATED_GROUP_MARKER.exec(rawName)?.[1] ?? null) as DependencyGroup | null;
+    const group = (OUTDATED_GROUP_MARKER.exec(rawName)?.[1] ?? 'prod') as DependencyGroup;
     const target = rawName.replace(OUTDATED_GROUP_MARKER, '');
     const current = cells[2] ?? '';
     const update = (cells[3] ?? '').replace(/\*/g, '').trim();
@@ -514,7 +515,7 @@ function renderOutdatedTable(output: string): string {
     const row = attributed.get(line);
     let display = cell.trim();
     if (row?.declaredKey && row.declaredKey !== row.target) {
-      display = row.group ? `${row.declaredKey} (${row.group})` : row.declaredKey;
+      display = row.group === 'prod' ? row.declaredKey : `${row.declaredKey} (${row.group})`;
     }
     return { line, display };
   });
@@ -552,9 +553,12 @@ function renderOutdatedTable(output: string): string {
  * Parses `bun audit` output and classifies high/critical vulnerabilities as
  * direct (in our package.json) or upstream (transitive dependency we can't fix).
  *
- * Bun audit format per vulnerability block:
- *   <package>  <version-range>        ← header (no indent, 2+ spaces before range)
- *     <parent> › <child> [› ...]      ← dependency path (indented, › = transitive)
+ * Bun audit format per vulnerability block — Bun 1.4 changed the header token
+ * and the path separator, so both shapes are accepted:
+ *   <package>  <version-range>        ← header, Bun <1.4 (no indent, 2+ spaces before range)
+ *   <package>@<version>               ← header, Bun ≥1.4
+ *     <parent> › <child> [› ...]      ← dependency path (indented; › or, Bun ≥1.4, > = transitive)
+ *     (direct dependency)             ← dependency path of a direct dependency, Bun ≥1.4
  *     <severity>: <description>       ← advisory (indented)
  *
  * Returns null if parsing yields no results (caller should fall back to default behavior).
@@ -567,8 +571,10 @@ function classifyAuditVulns(output: string): { direct: string[]; upstream: strin
     let i = 0;
 
     while (i < lines.length) {
-      // Package header: non-indented, name followed by 2+ spaces then version constraint
-      const pkgMatch = lines[i]?.match(/^([@\w][\w./-]*)\s{2,}(.+)$/);
+      // Package header: non-indented `name  range` (2+ spaces, Bun <1.4) or
+      // `name@version` (Bun ≥1.4). A scoped name leads with `@`, so only a
+      // later `@` splits the Bun 1.4 form.
+      const pkgMatch = lines[i]?.match(/^(@?\w[\w./-]*)(?:\s{2,}|@)(\S.*)$/);
       if (!pkgMatch) {
         i++;
         continue;
@@ -593,14 +599,15 @@ function classifyAuditVulns(output: string): { direct: string[]; upstream: strin
 
       if (!hasHighCritical) continue;
 
-      // Direct if: the vulnerable package is in our package.json,
-      // or any dependency path lacks › (meaning it's not pulled in transitively)
+      // Direct if: the vulnerable package is in our package.json, or any
+      // dependency path lacks a transitive separator — U+203A `›` (Bun <1.4)
+      // or `>` (Bun ≥1.4). Bun 1.4's literal `(direct dependency)` path has neither.
       const pkgName = pkg ?? '';
-      const isDirect = DIRECT_DEPS.has(pkgName) || paths.some((p) => !p.includes('\u203a'));
+      const isDirect = DIRECT_DEPS.has(pkgName) || paths.some((p) => !/[\u203a>]/.test(p));
       if (isDirect) {
         direct.push(`${pkgName} ${versionRange}`);
       } else {
-        const via = paths[0]?.split(/\s*\u203a\s*/)[0] ?? 'unknown';
+        const via = paths[0]?.split(/\s*[\u203a>]\s*/)[0] ?? 'unknown';
         upstream.push(`${pkgName} ${versionRange} (via ${via})`);
       }
     }

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.22"
+  version: "2.23"
   audience: external
   type: reference
 ---
@@ -26,9 +26,9 @@ Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in
 
 Tools use lowercase snake_case with a canonical server/domain prefix: `{server}_{verb}_{noun}` — 3 words.
 
-Examples: `pubmed_search_articles`, `pubmed_fetch_fulltext`, `clinicaltrials_find_studies`.
+Examples: `pubmed_search_articles`, `pubmed_fetch_fulltext`, `clinicaltrials_find_eligible`.
 
-The server prefix uses the canonical platform/brand name, not an abbreviation (`patentsview_` not `patents_`, `clinicaltrials_` not `ct_`). When a name resists the schema — can't pick a verb, noun feels generic, wants 4+ segments — that's usually a signal the scope is fuzzy; split the tool, rename, or reconsider.
+The server prefix is judged on clarity, not length: the brand name or the plain well-known word for the domain both pass (`pubmed_`, `patents_`); an abbreviation fails only when it reads as something else out of context (`loc_`, `ct_`). A fourth segment is fine when the noun is inherently two words (`openfda_search_device_clearances`). When a name resists the schema — can't pick a verb, noun feels generic, the *verb* wants a second word — that's usually a signal the scope is fuzzy; split the tool, rename, or reconsider.
 
 For shape selection (Workflow or Instruction variants — standard single-action tools are the default), see the `design-mcp-server` skill's Tool shapes section.
 
@@ -774,7 +774,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - **Lists**: Return top N with a total count and pagination cursor, not unbounded arrays
 - **Large objects**: Return key fields by default; accept a `fields` or `verbose` parameter for full data
 - **Binary/blob content**: Return metadata and a reference, not the raw content
-- **Analytical working sets**: When upstream returns more *analytical* rows (data an agent would SQL — aggregate, group, join) than fit in context, `DataCanvas` (`ctx.core.canvas?`, Tier 3 — opt-in via `CANVAS_PROVIDER_TYPE=duckdb`) lets you register the rows and return the `canvas_id` plus a preview so the agent can run SQL to slice down without a re-fetch. The `spillover()` helper (`@cyanheads/mcp-ts-core/canvas`) automates the overflow case: drain rows up to a character budget for the inline preview, auto-register the full source on overflow, return both as a discriminated union. **Two gates:** it must be analytical, not a discovery/search surface of categorical metadata (those don't earn a canvas regardless of row count — use MCP-side list filtering or pagination); and a tool emitting a `canvas_id` MUST be paired with a registered `dataframe_query` tool, or the handle is unreachable. Compute distributions or refinement hints across the full result — not the preview — so the agent gets honest aggregate signal on the rows it didn't read. See `api-canvas` for the register / query / export pattern and the spillover flow.
+- **Analytical working sets**: When upstream returns more *analytical* rows (data an agent would SQL — aggregate, group, join) than fit in context, `DataCanvas` (`core.canvas`, wired in `setup()` via `setCanvas`; Tier 3 — opt-in via `CANVAS_PROVIDER_TYPE=duckdb`) lets you register the rows and return the `canvas_id` plus a preview so the agent can run SQL to slice down without a re-fetch. The `spillover()` helper (`@cyanheads/mcp-ts-core/canvas`) automates the overflow case: drain rows up to a character budget for the inline preview, auto-register the full source on overflow, return both as a discriminated union. **Two gates:** it must be analytical, not a discovery/search surface of categorical metadata (those don't earn a canvas regardless of row count — use MCP-side list filtering or pagination); and a tool emitting a `canvas_id` MUST be paired with a registered `dataframe_query` tool, or the handle is unreachable. Compute distributions or refinement hints across the full result — not the preview — so the agent gets honest aggregate signal on the rows it didn't read. See `api-canvas` for the register / query / export pattern and the spillover flow.
 - **One large document**: When a single call returns one document-shaped record (not a row set) that can overflow context, return a section *outline* — top-level keys + per-section byte size — and let the agent re-call with `sections: [...]` for only what it needs, instead of truncating one surface. `outlineOnOverflow()` with `OUTLINE_VARIANT` / `selectSections()` / `formatOutline()` (`@cyanheads/mcp-ts-core/utils`) measures the payload and returns a `full | outline` result. Declare the tool's `output` as a flat `z.object` with a `kind` discriminator and presence-based optional arms (fold in `OUTLINE_VARIANT.shape.sections` / `.notice`) — `tool()` rejects a `z.discriminatedUnion` output — and render each arm on field presence in `format()` so parity holds. Pure measure + key-slice — Workers-portable, unlike canvas `spillover()`. Use for one fat record; use `spillover()` for a row collection. See the `techniques` skill's `outline-on-overflow` reference.
 
 ## MCP-side list filtering

package/skills/api-errors/SKILL.md

@@ -4,7 +4,7 @@ description: >
   McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.10"
   audience: external
   type: reference
 ---
@@ -363,6 +363,7 @@ Important properties:
 - **`data` propagation is restricted** to explicitly-thrown `McpError.data` and `ZodError.issues`. Auto-classified plain errors (`TypeError`, network errors, etc.) emit `code` + `message` only — no `data` — so internal classification context never leaks to clients.
 - **Recovery hint mirroring is automatic.** When the thrown `McpError` carries `data.recovery.hint`, the handler factory appends it to the `content[]` text so the markdown surface matches the JSON surface. Authors don't need to format the hint manually.
 - **Argument-schema rejection is a tool error with the same envelope.** An unknown root key, a wrong type, a missing required field, or a failed constraint returns `isError: true` with `structuredContent.error.code = -32602` (`InvalidParams`) and the readable `Invalid arguments for tool <name>: …` diagnostic in `content[]`. The handler never runs. Two neighbouring failures keep the protocol error path instead, arriving as a JSON-RPC error rather than a tool result: an unknown or disabled tool name, and a malformed request envelope.
+- **A schema constraint cannot carry a declared reason.** Because the handler never runs, a rejection by `.max()`, `.regex()`, `.min()`, or any other Zod refinement bypasses `errors[]` entirely: it arrives as `InvalidParams` with `data.issues` and no `data.reason`, so a caller has nothing to branch on and gets no recovery hint. Decide per constraint which surface it belongs on. A bound that is purely structural — the input is the wrong shape and no guidance beyond the diagnostic would help — belongs on the schema, where it also advertises itself in `inputSchema`. A bound a caller is expected to recover from belongs in the handler as `ctx.fail('reason', message, ctx.recoveryFor('reason'))` against a declared `errors[]` entry, with the limit restated in the field's `.describe()` so it is still visible before the call. Enforcing the same bound in both places is the trap: the schema wins, and the contract entry becomes unreachable while still reading as covered.
 
 **Handler — throw freely, no try/catch:**
 

package/skills/api-mirror/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Stand up a persistent, self-refreshing local mirror of a bulk upstream dataset with the MirrorService (@cyanheads/mcp-ts-core/mirror). Use when a server wraps a large or slow API and should query a synced local index (embedded SQLite + FTS5) instead of paginating the live API per request.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -81,6 +81,8 @@ Why they can't merge: during a from-scratch init the records aren't ordered by t
 
 For access paths the generic query can't express — junction tables for index-backed multi-value filtering, denormalized counters, bespoke `bm25` weighting — use the **raw handle**: `const db = await mirror.raw();` then run prepared statements against your own auxiliary tables (declare them via a migration). Add the auxiliary DDL in a `migrations` step; maintain it from your `sync` mapping or SQL triggers.
 
+A migration runs identically on first creation and on upgrade: a fresh database runs every migration up to `version` right after the declarative DDL, an existing one runs only those above its stored version. So `up()` must tolerate a database that already has the current declarative shape — `CREATE TABLE IF NOT EXISTS` for auxiliary objects, never an `ALTER` that assumes an older layout of a declared column.
+
 ## Readiness — key off the completion marker, not live status
 
 `status().ready` is `true` once a full sync has **ever completed** (`completedAt != null`), not when `status === 'complete'`. The dataset stays transactionally queryable during a refresh, so a mirror mid-refresh — or one whose last refresh failed — is still ready and should keep serving. Gate the mirror read path on `await mirror.ready()`; fall back to the live API only when it is `false` (cold, never-completed init).