stitchkit 0.20.0 → 0.22.0

package/dist/cli.js

@@ -4,9 +4,9 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-xmncnw8z.js";
+} from "./index-x8m8e7dc.js";
 import"./index-0ed3bx43.js";
-import"./index-ng2v2ts4.js";
+import"./index-4gawbm74.js";
 import"./index-c7nyw0yt.js";
 export {
   pollUntilDone,

package/dist/{index-ng2v2ts4.js → index-4gawbm74.js}

@@ -84,17 +84,25 @@ function base64UrlToBytes(segment) {
 }
 // src/internal/errors.ts
 import { z as z2 } from "zod";
+function issuePath(path) {
+  return path.length > 0 ? path.map(String).join(".") : "(root)";
+}
 function formatZodError(error) {
   const issues = error.issues.slice(0, 5);
-  const lines = issues.map((issue) => {
-    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-    return `${path}: ${issue.message}`;
-  });
+  const lines = issues.map((issue) => `${issuePath(issue.path)}: ${issue.message}`);
   const suffix = error.issues.length > 5 ? `
 ...and ${error.issues.length - 5} 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))
     return err.code;
@@ -106,7 +114,9 @@ function normalizeError(err) {
   if (AppError.is(err))
     return err;
   if (err instanceof z2.ZodError) {
-    return new AppError("VALIDATION_ERROR", formatZodError(err), 400);
+    return new AppError("VALIDATION_ERROR", formatZodError(err), 400, {
+      issues: zodIssues(err).slice(0, MAX_DETAIL_ISSUES)
+    });
   }
   console.error("[stitchkit] unhandled error:", err);
   return new AppError("INTERNAL_SERVER_ERROR", "Internal server error", 500);
@@ -128,4 +138,4 @@ function isWithinDir(root, target) {
   return target === root || target === base || target.startsWith(base + sep);
 }
 
-export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, errorCode, normalizeError, validateHandlerOutput, isWithinDir };
+export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, normalizeError, validateHandlerOutput, isWithinDir };

package/dist/{index-ynnh9x6h.js → index-a9n8m4ec.js}

@@ -3,7 +3,7 @@ import {
   bytesToBase64Url,
   forbidden,
   unauthorized
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/{index-f5e4efj1.js → index-g8kyab85.js}

@@ -10,7 +10,7 @@ import {
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import {
   extractIp,
   getClientInfo,

package/dist/{index-xmncnw8z.js → index-x8m8e7dc.js}

@@ -7,7 +7,7 @@ import {
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/internal/errors.d.ts

@@ -1,6 +1,22 @@
 import { type ZodType, z } from 'zod';
 import { AppError } from '../contract';
 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). */
+    path: string;
+    /** Zod issue code (e.g. `invalid_type`, `too_small`). */
+    code: string;
+    /** Human-readable message for this field. */
+    message: string;
+}
+/**
+ * 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`).
+ */
+export declare function zodIssues(error: z.ZodError): ZodIssueSummary[];
 /**
  * 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;AAEvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CASxD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}
+{"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;AAOvC,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,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}

package/dist/node.js

@@ -3,7 +3,7 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-f5e4efj1.js";
+} from "./index-g8kyab85.js";
 import"./index-tje0q6gp.js";
 import {
   AppError,
@@ -14,7 +14,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import"./index-dzx781tm.js";
 import"./index-khwedj16.js";
 import"./index-c7nyw0yt.js";

package/dist/server/error-hook.d.ts

@@ -9,6 +9,10 @@
  * of leaking stitchkit's code to the wire. The envelope stays app-owned via
  * `render`, so the core prescribes no domain shape (ADR 0002).
  *
+ * The thrown value is classified through the framework's own `normalizeError`
+ * first, so a `ZodError` (invalid input) is an honest `VALIDATION_ERROR` 400 —
+ * not a 500 — exactly as the framework default would render it.
+ *
  * ```ts
  * const onError = createErrorHook({
  *   codeMap: {
@@ -31,7 +35,7 @@ export interface ResolvedError {
     code: string;
     /** HTTP status. */
     status: number;
-    /** Safe message — the `AppError` message, or a generic string for a raw throw. */
+    /** Safe message — the `AppError` / `ZodError` summary, or a generic string for a raw throw. */
     message: string;
     /** Structured details, when the thrown `AppError` carried them. */
     details?: Record<string, unknown>;

package/dist/server/error-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAoBxC"}
+{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAyBxC"}

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export { AppError, appError, badRequest, conflict, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from '../contract';
+export { errorCode, formatZodError, normalizeError, type ZodIssueSummary, zodIssues, } from '../internal/errors';
 export { cacheHeaders, createCache } from './cache';
 export { createHandler, createServer } from './create';
 export { createErrorHook, type ErrorHookConfig, type ResolvedError, } from './error-hook';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-f5e4efj1.js";
+} from "../index-g8kyab85.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -23,7 +23,7 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-ynnh9x6h.js";
+} from "../index-a9n8m4ec.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   corsHeaders,
@@ -39,13 +39,16 @@ import {
   appError,
   badRequest,
   conflict,
+  errorCode,
   forbidden,
+  formatZodError,
   isStitchErrorCode,
   normalizeError,
   notFound,
   rateLimited,
-  unauthorized
-} from "../index-ng2v2ts4.js";
+  unauthorized,
+  zodIssues
+} from "../index-4gawbm74.js";
 import {
   extractIp,
   generateTraceId,
@@ -118,15 +121,14 @@ function cacheHeaders(maxAge, scope = "public") {
 // src/server/error-hook.ts
 function createErrorHook(config) {
   return (_ctx, error) => {
-    const isApp = AppError.is(error);
-    const rawCode = isApp ? error.code : "INTERNAL_SERVER_ERROR";
-    const code = config.codeMap && isStitchErrorCode(rawCode) ? config.codeMap[rawCode] : rawCode;
+    const appErr = normalizeError(error);
+    const code = config.codeMap && isStitchErrorCode(appErr.code) ? config.codeMap[appErr.code] : appErr.code;
     const info = {
       code,
-      status: isApp ? error.status : 500,
-      message: isApp ? error.message : "Internal server error",
-      details: isApp ? error.details : undefined,
-      hint: isApp ? error.hint : undefined
+      status: appErr.status,
+      message: appErr.message,
+      details: appErr.details,
+      hint: appErr.hint
     };
     config.onError?.(error, info);
     return new Response(JSON.stringify(config.render(info)), {
@@ -617,6 +619,7 @@ async function* parseSSE(response, options) {
   }
 }
 export {
+  zodIssues,
   webSocketLane,
   weakETag,
   verifyPkce,
@@ -639,15 +642,18 @@ export {
   parseBody,
   openApiRoute,
   notFound,
+  normalizeError,
   isStitchErrorCode,
   implement,
   getClientInfo,
   generateTraceId,
   generateOpenApiDocument,
+  formatZodError,
   forbidden,
   extractToken,
   extractIp,
   errorResponse2 as errorResponse,
+  errorCode,
   deriveCodeChallenge,
   defineCookie,
   createSocketIOServer,

package/dist/server/multipart.d.ts

@@ -13,8 +13,9 @@ export interface MultipartResult {
  *
  * A multipart text field is always a **string** (per the spec) and is handed to
  * the schema as one — the schema decides its type, exactly as with query params:
- * `z.coerce.number()` for a number, `z.coerce.boolean()` for a boolean, and
- * `z.preprocess((v) => JSON.parse(String(v)), Schema)` to opt a field into JSON.
+ * `z.coerce.number()` for a number, `z.stringbool()` for a boolean (NOT
+ * `z.coerce.boolean()`, which is `Boolean(str)` — `'false'` would become `true`),
+ * and `z.preprocess((v) => JSON.parse(String(v)), Schema)` to opt a field into JSON.
  * Content is never sniffed to guess a type — the contract owns the type, not the
  * value (so an id like `'33111715'` never turns into a number under a `z.string()`).
  */

package/dist/server/multipart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AA0CD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,SAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CAyB1B"}
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AA0CD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,SAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CAyB1B"}

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-ynnh9x6h.js";
+} from "./index-a9n8m4ec.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-tje0q6gp.js";
@@ -18,14 +18,14 @@ import {
   pollUntil,
   readCapped,
   toolResultFromError
-} from "./index-xmncnw8z.js";
+} from "./index-x8m8e7dc.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
   AppError,
   isWithinDir
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import"./index-khwedj16.js";
 import {
   isRecord,

package/llms-full.txt

@@ -289,8 +289,9 @@ await api.search({ q: 'x', filter: { status: 'active' } })
 
 Flatten the field (`status: 'active'`) or move the operation to a body verb
 (`POST`). Remember the server parses query values from **strings** — use
-`z.coerce.number()` / `z.coerce.boolean()` in a query-input schema for
-non-string fields.
+`z.coerce.number()` for numbers and `z.stringbool()` for booleans in a
+query-input schema (not `z.coerce.boolean()`, which is `Boolean(str)`, so
+`'false'` would become `true`).
 
 ## Transports
 
@@ -393,7 +394,7 @@ the schema owns its type, exactly as with [query input](#query-input-get--delete
 input: z.object({
   id: z.string(),               // an id like '33111715' stays a string
   count: z.coerce.number(),     // '5' → 5
-  active: z.coerce.boolean(),   // 'true' → true
+  active: z.stringbool(),       // 'true' → true, 'false' → false
   meta: z.preprocess((v) => JSON.parse(String(v)), MetaSchema),  // opt a field into JSON
 })
 ```
@@ -2292,7 +2293,27 @@ transport (HTTP, MCP, agent). → ADR 0032.
 `details` and `hint` are included when present. On HTTP this is the response
 body with the matching status; for an MCP or agent call the same `code` and
 `details` come back as a tool error. A schema-validation failure on the request
-is turned into a `400 VALIDATION_ERROR` automatically.
+is turned into a `400 VALIDATION_ERROR` automatically — and it carries the
+offending fields as structured `details.issues`, so a machine client matches on
+them instead of parsing the text `message`:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "name: Invalid input\nage: Invalid input",
+    "details": {
+      "issues": [
+        { "path": "name", "code": "invalid_type", "message": "Invalid input" },
+        { "path": "age",  "code": "invalid_type", "message": "Invalid input" }
+      ]
+    }
+  }
+}
+```
+
+Use the exported `zodIssues(error)` to build the same structured list from a
+`ZodError` in your own hook.
 
 ### On the client
 
@@ -2376,6 +2397,25 @@ createServer({ services, hooks: { onError } })
 Codes you threw yourself (not stitchkit's) pass through `codeMap` unchanged; the
 `satisfies Record<StitchErrorCode, …>` keeps the map exhaustive across upgrades.
 
+Invalid input (a `ZodError`) is classified as `VALIDATION_ERROR` 400 before it
+reaches `render` — a client fault is an honest 400, not a 500 — and the
+offending fields arrive as structured `info.details.issues`, so your `render`
+can surface them to a machine client without parsing the message.
+
+If you write a **bespoke** `onError` instead of using `createErrorHook`, run the
+thrown value through the exported `normalizeError` to get the same classification
+(a raw `ZodError` reaches your hook untouched, so the framework can inspect it —
+call `zodIssues(err)` yourself if you want the structured fields):
+
+```ts
+import { normalizeError } from 'stitchkit/server'
+
+onError: (ctx, err) => {
+  const e = normalizeError(err)   // ZodError → VALIDATION_ERROR 400, else generic 500
+  return jsonError(e.code, e.status, e.message)
+}
+```
+
 
 ==============================================================================
 # Guide: Observability  (docs/guide/observability.md)
@@ -3150,6 +3190,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `ByteRange` | _type_ | an inclusive `{ start, end }` byte range |
 | `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
 | `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
+| `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400 with structured `details.issues`, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
+| `errorCode` | function | the stable error code for a thrown value (side-effect-free — for log attribution) |
+| `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
+| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |
+| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) |
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler` (runtime-agnostic) |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.20.0",
+  "version": "0.22.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",