theokit 0.6.1 → 0.8.0

package/dist/{server-error-to-envelope-UJK6OWDJ.js → chunk-UVXB2ER7.js}

@@ -1,7 +1,3 @@
-#!/usr/bin/env node
-import "tsx/esm";
-import "./chunk-KT3MWNZG.js";
-
 // src/core/contracts/theo-error.ts
 var TheoError = class extends Error {
   name = "TheoError";
@@ -55,6 +51,43 @@ function sanitizeMeta(meta) {
   }
   return out;
 }
+var NotFoundError = class extends TheoError {
+  constructor(message = "Not Found", meta) {
+    super({ code: "NOT_FOUND", message, ...meta !== void 0 ? { meta } : {} });
+  }
+};
+function fromUnknown(value) {
+  if (value instanceof TheoError) return value;
+  if (value instanceof Error) {
+    return new TheoError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: value.message,
+      cause: value
+    });
+  }
+  if (typeof value === "string") {
+    return new TheoError({ code: "INTERNAL_SERVER_ERROR", message: value });
+  }
+  if (value === void 0 || value === null) {
+    return new TheoError({ code: "INTERNAL_SERVER_ERROR", message: "Unknown error" });
+  }
+  return new TheoError({
+    code: "INTERNAL_SERVER_ERROR",
+    message: `Non-Error value thrown: ${safeStringify(value)}`,
+    cause: value
+  });
+}
+function safeStringify(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  if (typeof value === "symbol") return value.toString();
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "[unstringifiable value]";
+  }
+}
 
 // src/core/contracts/server-error-to-envelope.ts
 var ERROR_NAME_TO_CODE = /* @__PURE__ */ new Map([
@@ -128,7 +161,11 @@ function serverErrorToEnvelope(value) {
     ext
   };
 }
+
 export {
+  TheoError,
+  NotFoundError,
+  fromUnknown,
   serverErrorToEnvelope
 };
-//# sourceMappingURL=server-error-to-envelope-UJK6OWDJ.js.map
+//# sourceMappingURL=chunk-UVXB2ER7.js.map

package/dist/chunk-UVXB2ER7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/contracts/theo-error.ts","../src/core/contracts/server-error-to-envelope.ts"],"sourcesContent":["/**\n * `TheoError` — envelope-emitting `Error` subclass per plan\n * g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.2.\n *\n * Mirrors trpc's TRPCError ergonomic pattern (referencia:\n * trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87)\n * adapted for theokit's hybrid envelope model (blueprint Form 4).\n *\n * Per ADR D5: `meta.stack` is auto-stripped in non-dev builds when serialized\n * via `toJSON()` — defense against accidental stack leak to clients (encore\n * `json:\"-\"` analog).\n *\n * Lives in `core/contracts/` per architecture.md v3 invariant #3.\n */\n\nimport type { TheoErrorCode, TheoErrorEnvelope } from './error-envelope.js'\n\n/**\n * Constructor options. `code` and `message` are required; `cause` follows TC39\n * proposal-error-cause; `meta` and `ext` are opt-in per blueprint ADR D2.\n */\nexport interface TheoErrorOptions<TExt = unknown> {\n  readonly code: TheoErrorCode\n  readonly message: string\n  readonly cause?: unknown\n  readonly meta?: Record<string, unknown>\n  readonly ext?: TExt\n}\n\n/**\n * `TheoError` — envelope-emitting Error subclass. Use this anywhere in\n * `theokit/server`, route handlers, or middleware to emit a typed,\n * cross-layer-compatible error.\n *\n * Mirrors TRPCError pattern: `code` is required, `message` defaults to\n * code if omitted, `cause` chain is preserved via TC39 proposal-error-cause.\n */\nexport class TheoError<TExt = unknown> extends Error {\n  override readonly name = 'TheoError'\n  readonly code: TheoErrorCode\n  readonly meta?: Record<string, unknown>\n  readonly ext?: TExt\n\n  constructor(opts: TheoErrorOptions<TExt>) {\n    super(opts.message, opts.cause !== undefined ? { cause: opts.cause } : undefined)\n    this.code = opts.code\n    this.meta = opts.meta\n    this.ext = opts.ext\n  }\n\n  /**\n   * The canonical envelope view of this error. Use when crossing the wire\n   * boundary or feeding telemetry — exposes the shape consumers can rely on\n   * without depending on the class identity.\n   */\n  get envelope(): TheoErrorEnvelope<TExt> {\n    return {\n      code: this.code,\n      message: this.message,\n      cause: (this as Error & { cause?: unknown }).cause,\n      meta: this.meta,\n      ext: this.ext,\n    }\n  }\n\n  /**\n   * JSON serialization — emits envelope shape only (no name/stack class\n   * internals). Per ADR D5, `meta.stack` is auto-stripped in non-dev to\n   * prevent accidental leak; other meta keys are preserved.\n   */\n  toJSON(): TheoErrorEnvelope<TExt> {\n    const meta = this.meta ? sanitizeMeta(this.meta) : undefined\n    return {\n      code: this.code,\n      message: this.message,\n      cause: (this as Error & { cause?: unknown }).cause,\n      meta,\n      ext: this.ext,\n    }\n  }\n}\n\n/**\n * Strip server-only sensitive meta keys in non-dev builds. Per ADR D5,\n * `stack` is the canonical leak vector (trpc accidentally exposes it via\n * `config.isDev` even today — references/trpc getErrorShape.ts:29-31).\n * Default to safe-by-default; preserve in dev only.\n */\nfunction sanitizeMeta(meta: Record<string, unknown>): Record<string, unknown> | undefined {\n  // Treat anything other than NODE_ENV === 'development' as production-safe\n  // (CI, staging, production all strip). Matches the security posture in\n  // blueprint EC-5 (default STRICT).\n  if (process.env.NODE_ENV === 'development') {\n    return meta\n  }\n  const out: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(meta)) {\n    if (k === 'stack') continue\n    out[k] = v\n  }\n  return out\n}\n\n/**\n * Coerce any unknown value into a TheoError envelope.\n *\n * - If value is already a TheoError, returns it unchanged (no double-wrap).\n * - If value is a plain Error, wraps it as `INTERNAL_SERVER_ERROR` with\n *   `cause` chain preserving the original.\n * - Other values (string, undefined, object) are coerced safely with a\n *   meaningful message.\n *\n * Use at framework boundaries (route handler catch-all, middleware catch,\n * SDK egress) to ensure every error crossing the wire carries an envelope.\n */\n/**\n * `NotFoundError` — typed 404. A `TheoError` with code `NOT_FOUND`, so it\n * carries a stable `code` (not a bare status literal) and maps to HTTP 404 via\n * `envelopeCodeToStatus`. Throw it from a `defineRoute` handler for ergonomic\n * 404s (M7-1).\n */\nexport class NotFoundError extends TheoError {\n  constructor(message = 'Not Found', meta?: Record<string, unknown>) {\n    super({ code: 'NOT_FOUND', message, ...(meta !== undefined ? { meta } : {}) })\n  }\n}\n\nexport function fromUnknown(value: unknown): TheoError {\n  if (value instanceof TheoError) return value\n  if (value instanceof Error) {\n    return new TheoError({\n      code: 'INTERNAL_SERVER_ERROR',\n      message: value.message,\n      cause: value,\n    })\n  }\n  if (typeof value === 'string') {\n    return new TheoError({ code: 'INTERNAL_SERVER_ERROR', message: value })\n  }\n  if (value === undefined || value === null) {\n    return new TheoError({ code: 'INTERNAL_SERVER_ERROR', message: 'Unknown error' })\n  }\n  // Object / number / boolean / etc. — best-effort stringify\n  return new TheoError({\n    code: 'INTERNAL_SERVER_ERROR',\n    message: `Non-Error value thrown: ${safeStringify(value)}`,\n    cause: value,\n  })\n}\n\n/**\n * Best-effort stringify of an unknown value for error message context.\n * JSON.stringify first (preserves shape for diagnostics); on cycle/BigInt/symbol\n * failure, signal explicitly instead of falling back to `[object Object]`.\n */\nfunction safeStringify(value: unknown): string {\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'boolean') return String(value)\n  if (typeof value === 'bigint') return `${value.toString()}n`\n  if (typeof value === 'symbol') return value.toString()\n  try {\n    return JSON.stringify(value)\n  } catch {\n    return '[unstringifiable value]'\n  }\n}\n","/**\n * G5 T2.5 — server-side boundary translation per blueprint ADR D3.\n *\n * Translates ad-hoc Error class instances (FileTooLargeError,\n * AuthRequiredError, RouterConventionError, etc.) into the canonical\n * `TheoErrorEnvelope` shape at the wire boundary. This is the SINGLE\n * boundary translation point — class identities stay in place inside the\n * codebase (no invasive call-site rewrites), but the envelope is what\n * crosses to clients.\n *\n * Pure; no I/O. Lives in `core/contracts/` per architecture.md v3\n * invariant #3 (canonical home for shared client↔server types). This file\n * is the EXCEPTION-of-an-exception: it intentionally inspects Error names\n * by string instead of `instanceof` to avoid `core/contracts/` taking a\n * dependency on `server/`. The mapping table is small and grep-discoverable.\n */\n\nimport type { TheoErrorCode, TheoErrorEnvelope } from './error-envelope.js'\nimport { TheoError } from './theo-error.js'\n\n/**\n * Mapping from ad-hoc Error class name to envelope code. Add entries here\n * when a new ad-hoc Error is introduced anywhere in `theokit/server/`.\n * Build-time errors (Duplicate*, ActionScanError, InvalidPluginShapeError)\n * are NOT in this table by design — they never cross the wire boundary,\n * so their canonical shape is `INTERNAL_SERVER_ERROR` via the default branch.\n */\nconst ERROR_NAME_TO_CODE: ReadonlyMap<string, TheoErrorCode> = new Map<string, TheoErrorCode>([\n  ['AuthRequiredError', 'UNAUTHORIZED'],\n  ['FileTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  ['RequestBodyTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  ['BodyTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  // RouterConventionError reaches the wire only during dev-error overlay;\n  // INTERNAL_SERVER_ERROR is appropriate, but we add a HintExt-shaped ext\n  // with the migration guidance for the devtools display.\n  ['RouterConventionError', 'INTERNAL_SERVER_ERROR'],\n])\n\ntype MetaExtractor = (err: Error) => Record<string, unknown> | null\n\n/**\n * Class-specific metadata extractors. Each function receives the raw Error\n * and returns an object merged into envelope.meta (excluding name/message\n * which are reserved).\n */\nconst META_EXTRACTORS: ReadonlyMap<string, MetaExtractor> = new Map<string, MetaExtractor>([\n  [\n    'FileTooLargeError',\n    (err) => {\n      const e = err as Error & { truncatedFilenames?: string[]; maxFileSize?: number }\n      return {\n        truncatedFilenames: e.truncatedFilenames ?? [],\n        maxFileSize: e.maxFileSize,\n      }\n    },\n  ],\n  [\n    'RouterConventionError',\n    (err) => {\n      const e = err as Error & { file?: string; suggestion?: string; migrationUrl?: string }\n      return {\n        file: e.file,\n        suggestion: e.suggestion,\n        migrationUrl: e.migrationUrl,\n      }\n    },\n  ],\n])\n\ntype ExtBuilder = (err: Error) => unknown\n\n/**\n * Class-specific ext (extension slot) builders. RouterConventionError ships a\n * HintExt-shaped `{ hint }` so devtools / dev overlay can render the actionable\n * migration tip directly.\n */\nconst EXT_BUILDERS: ReadonlyMap<string, ExtBuilder> = new Map<string, ExtBuilder>([\n  [\n    'RouterConventionError',\n    () => ({\n      hint: 'Run `theokit migrate router` to convert dotted-basename routes to directory-nested form.',\n    }),\n  ],\n])\n\n/**\n * Translate any server-side Error instance into a canonical envelope.\n *\n * Pass-through behavior:\n * - `TheoError` instances return their `.envelope` unchanged.\n * - Plain `Error` with unknown name → `INTERNAL_SERVER_ERROR`.\n * - Non-Error values → wrapped via `TheoError.fromUnknown` semantics.\n *\n * Meta carries the source class `name` plus class-specific fields when an\n * extractor is registered. This keeps wire-side telemetry useful without\n * leaking implementation details.\n */\nexport function serverErrorToEnvelope(value: unknown): TheoErrorEnvelope {\n  if (value instanceof TheoError) {\n    return value.envelope\n  }\n  if (!(value instanceof Error)) {\n    return {\n      code: 'INTERNAL_SERVER_ERROR',\n      message: typeof value === 'string' ? value : 'Unknown error',\n    }\n  }\n  const name = value.name\n  const code = ERROR_NAME_TO_CODE.get(name) ?? 'INTERNAL_SERVER_ERROR'\n  const extractor = META_EXTRACTORS.get(name)\n  const extra = extractor ? extractor(value) : null\n  const meta: Record<string, unknown> = { name }\n  if (extra) {\n    for (const [k, v] of Object.entries(extra)) {\n      if (v !== undefined) meta[k] = v\n    }\n  }\n  const extBuilder = EXT_BUILDERS.get(name)\n  const ext = extBuilder ? extBuilder(value) : undefined\n  return {\n    code,\n    message: value.message,\n    cause: (value as Error & { cause?: unknown }).cause,\n    meta,\n    ext,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-V3LJN2GS.js

@@ -0,0 +1,38 @@
+// src/server/define/health-route.ts
+var HEALTH_PATH = "/__theo/health";
+var READY_PATH = "/__theo/ready";
+function defineHealthRoute(handler = () => ({ status: "ok" })) {
+  return { kind: "health", handler };
+}
+function defineReadyRoute(probe) {
+  return { kind: "ready", probe };
+}
+async function serveReservedRoute(pathname, routes = {}) {
+  if (pathname === HEALTH_PATH) {
+    const handler = routes.health?.handler ?? (() => ({ status: "ok" }));
+    return { status: 200, body: handler() };
+  }
+  if (pathname === READY_PATH) {
+    const probe = routes.ready?.probe;
+    if (probe === void 0) {
+      return { status: 200, body: { status: "ready" } };
+    }
+    try {
+      const ready = await probe();
+      return ready ? { status: 200, body: { status: "ready" } } : { status: 503, body: { status: "not-ready" } };
+    } catch (err) {
+      console.error("[theo] readiness probe threw \u2014 treating as not-ready", err);
+      return { status: 503, body: { status: "not-ready" } };
+    }
+  }
+  return null;
+}
+
+export {
+  HEALTH_PATH,
+  READY_PATH,
+  defineHealthRoute,
+  defineReadyRoute,
+  serveReservedRoute
+};
+//# sourceMappingURL=chunk-V3LJN2GS.js.map

package/dist/chunk-V3LJN2GS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/define/health-route.ts"],"sourcesContent":["/**\n * M7-2 — health/ready reserved routes for the convention/filesystem-route\n * server. Liveness (`/__theo/health`, always 200) and readiness\n * (`/__theo/ready`, 200/503 from a probe) are registered on a reserved\n * namespace BEFORE the user-route catch-all + 404 branch — mirroring nitro's\n * `/_nitro/*` reserved-namespace pattern (knowledge-base/references/nitro/src/\n * runtime/internal/routes/dev-tasks.ts). Liveness and readiness are kept\n * separate by design: liveness says \"the process is up\", readiness says\n * \"dependencies are up\".\n *\n * @public\n */\n\n/** Reserved path for the liveness endpoint. */\nexport const HEALTH_PATH = '/__theo/health'\n/** Reserved path for the readiness endpoint. */\nexport const READY_PATH = '/__theo/ready'\n\n/** Config produced by {@link defineHealthRoute}. */\nexport interface HealthRouteConfig {\n  readonly kind: 'health'\n  /** Returns the liveness body (auto-serialized to JSON). Default: `{ status: 'ok' }`. */\n  readonly handler: () => unknown\n}\n\n/** Config produced by {@link defineReadyRoute}. */\nexport interface ReadyRouteConfig {\n  readonly kind: 'ready'\n  /** Resolves `true` when dependencies are ready. A throw/reject is treated as not-ready (503). */\n  readonly probe: () => boolean | Promise<boolean>\n}\n\n/** The reserved-route registry consulted by {@link serveReservedRoute}. */\nexport interface ReservedRoutes {\n  readonly health?: HealthRouteConfig\n  readonly ready?: ReadyRouteConfig\n}\n\n/** A reserved-route response: an HTTP status + a JSON-serializable body. */\nexport interface ReservedResponse {\n  readonly status: number\n  readonly body: unknown\n}\n\n/**\n * Define the liveness route. The default handler returns `{ status: 'ok' }`.\n * Liveness is always 200 — it asserts the process is up, not that dependencies are.\n */\nexport function defineHealthRoute(\n  handler: () => unknown = () => ({ status: 'ok' }),\n): HealthRouteConfig {\n  return { kind: 'health', handler }\n}\n\n/**\n * Define the readiness route. The `probe` decides 200 (ready) vs 503 (not-ready).\n * A probe that throws/rejects is treated as not-ready (503) — never a 500 crash.\n */\nexport function defineReadyRoute(probe: () => boolean | Promise<boolean>): ReadyRouteConfig {\n  return { kind: 'ready', probe }\n}\n\n/**\n * Pure dispatcher: map a request pathname to a reserved-route response, or\n * `null` when the path is not reserved (so the user catch-all + 404 take over).\n * Liveness defaults to 200 `{status:'ok'}`; readiness without a probe is\n * trivially ready (200). Registered BEFORE the user catch-all by the caller.\n */\nexport async function serveReservedRoute(\n  pathname: string,\n  routes: ReservedRoutes = {},\n): Promise<ReservedResponse | null> {\n  if (pathname === HEALTH_PATH) {\n    const handler = routes.health?.handler ?? (() => ({ status: 'ok' }))\n    return { status: 200, body: handler() }\n  }\n  if (pathname === READY_PATH) {\n    const probe = routes.ready?.probe\n    if (probe === undefined) {\n      return { status: 200, body: { status: 'ready' } }\n    }\n    try {\n      const ready = await probe()\n      return ready\n        ? { status: 200, body: { status: 'ready' } }\n        : { status: 503, body: { status: 'not-ready' } }\n    } catch (err) {\n      // 503 (the dependency is not ready) but NEVER swallow the cause — a\n      // readiness probe failing silently is invisible to ops (project rule:\n      // \"NUNCA engula exceções\"). Log the cause, keep the 503 contract.\n      console.error('[theo] readiness probe threw — treating as not-ready', err)\n      return { status: 503, body: { status: 'not-ready' } }\n    }\n  }\n  return null\n}\n"],"mappings":";AAcO,IAAM,cAAc;AAEpB,IAAM,aAAa;AAgCnB,SAAS,kBACd,UAAyB,OAAO,EAAE,QAAQ,KAAK,IAC5B;AACnB,SAAO,EAAE,MAAM,UAAU,QAAQ;AACnC;AAMO,SAAS,iBAAiB,OAA2D;AAC1F,SAAO,EAAE,MAAM,SAAS,MAAM;AAChC;AAQA,eAAsB,mBACpB,UACA,SAAyB,CAAC,GACQ;AAClC,MAAI,aAAa,aAAa;AAC5B,UAAM,UAAU,OAAO,QAAQ,YAAY,OAAO,EAAE,QAAQ,KAAK;AACjE,WAAO,EAAE,QAAQ,KAAK,MAAM,QAAQ,EAAE;AAAA,EACxC;AACA,MAAI,aAAa,YAAY;AAC3B,UAAM,QAAQ,OAAO,OAAO;AAC5B,QAAI,UAAU,QAAW;AACvB,aAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,QAAQ,QAAQ,EAAE;AAAA,IAClD;AACA,QAAI;AACF,YAAM,QAAQ,MAAM,MAAM;AAC1B,aAAO,QACH,EAAE,QAAQ,KAAK,MAAM,EAAE,QAAQ,QAAQ,EAAE,IACzC,EAAE,QAAQ,KAAK,MAAM,EAAE,QAAQ,YAAY,EAAE;AAAA,IACnD,SAAS,KAAK;AAIZ,cAAQ,MAAM,6DAAwD,GAAG;AACzE,aAAO,EAAE,QAAQ,KAAK,MAAM,EAAE,QAAQ,YAAY,EAAE;AAAA,IACtD;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/{chunk-Z5IGLBWE.js → chunk-WFNLNIJX.js}

@@ -326,4 +326,4 @@ export {
   _resetWarnOnceForTests,
   warnOnce
 };
-//# sourceMappingURL=chunk-Z5IGLBWE.js.map
+//# sourceMappingURL=chunk-WFNLNIJX.js.map

package/dist/{chunk-TQYSPYKU.js → chunk-WS67ONGI.js}

@@ -1,3 +1,6 @@
+#!/usr/bin/env node
+import "tsx/esm";
+
 // src/core/contracts/theo-error.ts
 var TheoError = class extends Error {
   name = "TheoError";
@@ -128,4 +131,4 @@ function serverErrorToEnvelope(value) {
 export {
   serverErrorToEnvelope
 };
-//# sourceMappingURL=chunk-TQYSPYKU.js.map
+//# sourceMappingURL=chunk-WS67ONGI.js.map

package/dist/chunk-WS67ONGI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/contracts/theo-error.ts","../src/core/contracts/server-error-to-envelope.ts"],"sourcesContent":["/**\n * `TheoError` — envelope-emitting `Error` subclass per plan\n * g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.2.\n *\n * Mirrors trpc's TRPCError ergonomic pattern (referencia:\n * trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87)\n * adapted for theokit's hybrid envelope model (blueprint Form 4).\n *\n * Per ADR D5: `meta.stack` is auto-stripped in non-dev builds when serialized\n * via `toJSON()` — defense against accidental stack leak to clients (encore\n * `json:\"-\"` analog).\n *\n * Lives in `core/contracts/` per architecture.md v3 invariant #3.\n */\n\nimport type { TheoErrorCode, TheoErrorEnvelope } from './error-envelope.js'\n\n/**\n * Constructor options. `code` and `message` are required; `cause` follows TC39\n * proposal-error-cause; `meta` and `ext` are opt-in per blueprint ADR D2.\n */\nexport interface TheoErrorOptions<TExt = unknown> {\n  readonly code: TheoErrorCode\n  readonly message: string\n  readonly cause?: unknown\n  readonly meta?: Record<string, unknown>\n  readonly ext?: TExt\n}\n\n/**\n * `TheoError` — envelope-emitting Error subclass. Use this anywhere in\n * `theokit/server`, route handlers, or middleware to emit a typed,\n * cross-layer-compatible error.\n *\n * Mirrors TRPCError pattern: `code` is required, `message` defaults to\n * code if omitted, `cause` chain is preserved via TC39 proposal-error-cause.\n */\nexport class TheoError<TExt = unknown> extends Error {\n  override readonly name = 'TheoError'\n  readonly code: TheoErrorCode\n  readonly meta?: Record<string, unknown>\n  readonly ext?: TExt\n\n  constructor(opts: TheoErrorOptions<TExt>) {\n    super(opts.message, opts.cause !== undefined ? { cause: opts.cause } : undefined)\n    this.code = opts.code\n    this.meta = opts.meta\n    this.ext = opts.ext\n  }\n\n  /**\n   * The canonical envelope view of this error. Use when crossing the wire\n   * boundary or feeding telemetry — exposes the shape consumers can rely on\n   * without depending on the class identity.\n   */\n  get envelope(): TheoErrorEnvelope<TExt> {\n    return {\n      code: this.code,\n      message: this.message,\n      cause: (this as Error & { cause?: unknown }).cause,\n      meta: this.meta,\n      ext: this.ext,\n    }\n  }\n\n  /**\n   * JSON serialization — emits envelope shape only (no name/stack class\n   * internals). Per ADR D5, `meta.stack` is auto-stripped in non-dev to\n   * prevent accidental leak; other meta keys are preserved.\n   */\n  toJSON(): TheoErrorEnvelope<TExt> {\n    const meta = this.meta ? sanitizeMeta(this.meta) : undefined\n    return {\n      code: this.code,\n      message: this.message,\n      cause: (this as Error & { cause?: unknown }).cause,\n      meta,\n      ext: this.ext,\n    }\n  }\n}\n\n/**\n * Strip server-only sensitive meta keys in non-dev builds. Per ADR D5,\n * `stack` is the canonical leak vector (trpc accidentally exposes it via\n * `config.isDev` even today — references/trpc getErrorShape.ts:29-31).\n * Default to safe-by-default; preserve in dev only.\n */\nfunction sanitizeMeta(meta: Record<string, unknown>): Record<string, unknown> | undefined {\n  // Treat anything other than NODE_ENV === 'development' as production-safe\n  // (CI, staging, production all strip). Matches the security posture in\n  // blueprint EC-5 (default STRICT).\n  if (process.env.NODE_ENV === 'development') {\n    return meta\n  }\n  const out: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(meta)) {\n    if (k === 'stack') continue\n    out[k] = v\n  }\n  return out\n}\n\n/**\n * Coerce any unknown value into a TheoError envelope.\n *\n * - If value is already a TheoError, returns it unchanged (no double-wrap).\n * - If value is a plain Error, wraps it as `INTERNAL_SERVER_ERROR` with\n *   `cause` chain preserving the original.\n * - Other values (string, undefined, object) are coerced safely with a\n *   meaningful message.\n *\n * Use at framework boundaries (route handler catch-all, middleware catch,\n * SDK egress) to ensure every error crossing the wire carries an envelope.\n */\n/**\n * `NotFoundError` — typed 404. A `TheoError` with code `NOT_FOUND`, so it\n * carries a stable `code` (not a bare status literal) and maps to HTTP 404 via\n * `envelopeCodeToStatus`. Throw it from a `defineRoute` handler for ergonomic\n * 404s (M7-1).\n */\nexport class NotFoundError extends TheoError {\n  constructor(message = 'Not Found', meta?: Record<string, unknown>) {\n    super({ code: 'NOT_FOUND', message, ...(meta !== undefined ? { meta } : {}) })\n  }\n}\n\nexport function fromUnknown(value: unknown): TheoError {\n  if (value instanceof TheoError) return value\n  if (value instanceof Error) {\n    return new TheoError({\n      code: 'INTERNAL_SERVER_ERROR',\n      message: value.message,\n      cause: value,\n    })\n  }\n  if (typeof value === 'string') {\n    return new TheoError({ code: 'INTERNAL_SERVER_ERROR', message: value })\n  }\n  if (value === undefined || value === null) {\n    return new TheoError({ code: 'INTERNAL_SERVER_ERROR', message: 'Unknown error' })\n  }\n  // Object / number / boolean / etc. — best-effort stringify\n  return new TheoError({\n    code: 'INTERNAL_SERVER_ERROR',\n    message: `Non-Error value thrown: ${safeStringify(value)}`,\n    cause: value,\n  })\n}\n\n/**\n * Best-effort stringify of an unknown value for error message context.\n * JSON.stringify first (preserves shape for diagnostics); on cycle/BigInt/symbol\n * failure, signal explicitly instead of falling back to `[object Object]`.\n */\nfunction safeStringify(value: unknown): string {\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'boolean') return String(value)\n  if (typeof value === 'bigint') return `${value.toString()}n`\n  if (typeof value === 'symbol') return value.toString()\n  try {\n    return JSON.stringify(value)\n  } catch {\n    return '[unstringifiable value]'\n  }\n}\n","/**\n * G5 T2.5 — server-side boundary translation per blueprint ADR D3.\n *\n * Translates ad-hoc Error class instances (FileTooLargeError,\n * AuthRequiredError, RouterConventionError, etc.) into the canonical\n * `TheoErrorEnvelope` shape at the wire boundary. This is the SINGLE\n * boundary translation point — class identities stay in place inside the\n * codebase (no invasive call-site rewrites), but the envelope is what\n * crosses to clients.\n *\n * Pure; no I/O. Lives in `core/contracts/` per architecture.md v3\n * invariant #3 (canonical home for shared client↔server types). This file\n * is the EXCEPTION-of-an-exception: it intentionally inspects Error names\n * by string instead of `instanceof` to avoid `core/contracts/` taking a\n * dependency on `server/`. The mapping table is small and grep-discoverable.\n */\n\nimport type { TheoErrorCode, TheoErrorEnvelope } from './error-envelope.js'\nimport { TheoError } from './theo-error.js'\n\n/**\n * Mapping from ad-hoc Error class name to envelope code. Add entries here\n * when a new ad-hoc Error is introduced anywhere in `theokit/server/`.\n * Build-time errors (Duplicate*, ActionScanError, InvalidPluginShapeError)\n * are NOT in this table by design — they never cross the wire boundary,\n * so their canonical shape is `INTERNAL_SERVER_ERROR` via the default branch.\n */\nconst ERROR_NAME_TO_CODE: ReadonlyMap<string, TheoErrorCode> = new Map<string, TheoErrorCode>([\n  ['AuthRequiredError', 'UNAUTHORIZED'],\n  ['FileTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  ['RequestBodyTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  ['BodyTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  // RouterConventionError reaches the wire only during dev-error overlay;\n  // INTERNAL_SERVER_ERROR is appropriate, but we add a HintExt-shaped ext\n  // with the migration guidance for the devtools display.\n  ['RouterConventionError', 'INTERNAL_SERVER_ERROR'],\n])\n\ntype MetaExtractor = (err: Error) => Record<string, unknown> | null\n\n/**\n * Class-specific metadata extractors. Each function receives the raw Error\n * and returns an object merged into envelope.meta (excluding name/message\n * which are reserved).\n */\nconst META_EXTRACTORS: ReadonlyMap<string, MetaExtractor> = new Map<string, MetaExtractor>([\n  [\n    'FileTooLargeError',\n    (err) => {\n      const e = err as Error & { truncatedFilenames?: string[]; maxFileSize?: number }\n      return {\n        truncatedFilenames: e.truncatedFilenames ?? [],\n        maxFileSize: e.maxFileSize,\n      }\n    },\n  ],\n  [\n    'RouterConventionError',\n    (err) => {\n      const e = err as Error & { file?: string; suggestion?: string; migrationUrl?: string }\n      return {\n        file: e.file,\n        suggestion: e.suggestion,\n        migrationUrl: e.migrationUrl,\n      }\n    },\n  ],\n])\n\ntype ExtBuilder = (err: Error) => unknown\n\n/**\n * Class-specific ext (extension slot) builders. RouterConventionError ships a\n * HintExt-shaped `{ hint }` so devtools / dev overlay can render the actionable\n * migration tip directly.\n */\nconst EXT_BUILDERS: ReadonlyMap<string, ExtBuilder> = new Map<string, ExtBuilder>([\n  [\n    'RouterConventionError',\n    () => ({\n      hint: 'Run `theokit migrate router` to convert dotted-basename routes to directory-nested form.',\n    }),\n  ],\n])\n\n/**\n * Translate any server-side Error instance into a canonical envelope.\n *\n * Pass-through behavior:\n * - `TheoError` instances return their `.envelope` unchanged.\n * - Plain `Error` with unknown name → `INTERNAL_SERVER_ERROR`.\n * - Non-Error values → wrapped via `TheoError.fromUnknown` semantics.\n *\n * Meta carries the source class `name` plus class-specific fields when an\n * extractor is registered. This keeps wire-side telemetry useful without\n * leaking implementation details.\n */\nexport function serverErrorToEnvelope(value: unknown): TheoErrorEnvelope {\n  if (value instanceof TheoError) {\n    return value.envelope\n  }\n  if (!(value instanceof Error)) {\n    return {\n      code: 'INTERNAL_SERVER_ERROR',\n      message: typeof value === 'string' ? value : 'Unknown error',\n    }\n  }\n  const name = value.name\n  const code = ERROR_NAME_TO_CODE.get(name) ?? 'INTERNAL_SERVER_ERROR'\n  const extractor = META_EXTRACTORS.get(name)\n  const extra = extractor ? extractor(value) : null\n  const meta: Record<string, unknown> = { name }\n  if (extra) {\n    for (const [k, v] of Object.entries(extra)) {\n      if (v !== undefined) meta[k] = v\n    }\n  }\n  const extBuilder = EXT_BUILDERS.get(name)\n  const ext = extBuilder ? extBuilder(value) : undefined\n  return {\n    code,\n    message: value.message,\n    cause: (value as Error & { cause?: unknown }).cause,\n    meta,\n    ext,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-X32XEJXR.js

@@ -0,0 +1,35 @@
+// src/core/contracts/envelope-code-to-status.ts
+var CODE_TO_STATUS = {
+  // 4xx — client errors
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  PRECONDITION_FAILED: 412,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  RATE_LIMITED: 429,
+  // 5xx — server errors
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+  // SDK-domain codes — intentionally 500
+  AGENT_RUN_ERROR: 500,
+  PROVIDER_KEY_MISSING: 500,
+  BUDGET_EXCEEDED: 500,
+  CREDENTIAL_POOL_EXHAUSTED: 500
+};
+function envelopeCodeToStatus(code) {
+  return CODE_TO_STATUS[code] ?? 500;
+}
+
+export {
+  envelopeCodeToStatus
+};
+//# sourceMappingURL=chunk-X32XEJXR.js.map

package/dist/chunk-X32XEJXR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/contracts/envelope-code-to-status.ts"],"sourcesContent":["/**\n * Maps a TheoErrorEnvelope `code` to its canonical HTTP status.\n *\n * Single source of truth — previously duplicated in `web-handler.ts` and\n * `handle-request-error.ts` (architecture-remediation plan T1.2, 2026-06-12).\n *\n * Every TheoErrorCode value MUST have an explicit entry here. SDK-domain codes\n * (AGENT_RUN_ERROR, PROVIDER_KEY_MISSING, BUDGET_EXCEEDED, CREDENTIAL_POOL_EXHAUSTED)\n * intentionally map to 500 — they represent internal failures, not client errors.\n */\n\nconst CODE_TO_STATUS: Record<string, number> = {\n  // 4xx — client errors\n  BAD_REQUEST: 400,\n  UNAUTHORIZED: 401,\n  FORBIDDEN: 403,\n  NOT_FOUND: 404,\n  METHOD_NOT_ALLOWED: 405,\n  CONFLICT: 409,\n  PRECONDITION_FAILED: 412,\n  PAYLOAD_TOO_LARGE: 413,\n  UNSUPPORTED_MEDIA_TYPE: 415,\n  UNPROCESSABLE_ENTITY: 422,\n  TOO_MANY_REQUESTS: 429,\n  RATE_LIMITED: 429,\n\n  // 5xx — server errors\n  INTERNAL_SERVER_ERROR: 500,\n  NOT_IMPLEMENTED: 501,\n  BAD_GATEWAY: 502,\n  SERVICE_UNAVAILABLE: 503,\n  GATEWAY_TIMEOUT: 504,\n\n  // SDK-domain codes — intentionally 500\n  AGENT_RUN_ERROR: 500,\n  PROVIDER_KEY_MISSING: 500,\n  BUDGET_EXCEEDED: 500,\n  CREDENTIAL_POOL_EXHAUSTED: 500,\n}\n\nexport function envelopeCodeToStatus(code: string): number {\n  return CODE_TO_STATUS[code] ?? 500\n}\n"],"mappings":";AAWA,IAAM,iBAAyC;AAAA;AAAA,EAE7C,aAAa;AAAA,EACb,cAAc;AAAA,EACd,WAAW;AAAA,EACX,WAAW;AAAA,EACX,oBAAoB;AAAA,EACpB,UAAU;AAAA,EACV,qBAAqB;AAAA,EACrB,mBAAmB;AAAA,EACnB,wBAAwB;AAAA,EACxB,sBAAsB;AAAA,EACtB,mBAAmB;AAAA,EACnB,cAAc;AAAA;AAAA,EAGd,uBAAuB;AAAA,EACvB,iBAAiB;AAAA,EACjB,aAAa;AAAA,EACb,qBAAqB;AAAA,EACrB,iBAAiB;AAAA;AAAA,EAGjB,iBAAiB;AAAA,EACjB,sBAAsB;AAAA,EACtB,iBAAiB;AAAA,EACjB,2BAA2B;AAC7B;AAEO,SAAS,qBAAqB,MAAsB;AACzD,SAAO,eAAe,IAAI,KAAK;AACjC;","names":[]}

package/dist/{chunk-MV4LKTW6.js → chunk-Z374WCMZ.js}

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import "tsx/esm";
+import {
+  serverErrorToEnvelope
+} from "./chunk-WS67ONGI.js";
 
 // src/server/plugins/plugin-runner.ts
 var DuplicatePluginError = class extends Error {
@@ -1535,6 +1538,37 @@ function coerceBoolean(formData, key) {
   return Boolean(val);
 }
 
+// src/core/contracts/envelope-code-to-status.ts
+var CODE_TO_STATUS2 = {
+  // 4xx — client errors
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  PRECONDITION_FAILED: 412,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  RATE_LIMITED: 429,
+  // 5xx — server errors
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+  // SDK-domain codes — intentionally 500
+  AGENT_RUN_ERROR: 500,
+  PROVIDER_KEY_MISSING: 500,
+  BUDGET_EXCEEDED: 500,
+  CREDENTIAL_POOL_EXHAUSTED: 500
+};
+function envelopeCodeToStatus(code) {
+  return CODE_TO_STATUS2[code] ?? 500;
+}
+
 // src/server/http/handle-request-error.ts
 async function handleRequestError(err, c) {
   if (c.pluginRunner) {
@@ -1558,14 +1592,26 @@ async function handleRequestError(err, c) {
     const authErr = err;
     sendError(c.res, authErr.code, authErr.message, authErr.status, void 0, c.requestId);
   } else {
-    sendError(
-      c.res,
-      "INTERNAL_ERROR",
-      err instanceof Error ? err.message : "Internal server error",
-      500,
-      void 0,
-      c.requestId
-    );
+    const envelope = serverErrorToEnvelope(err);
+    if (envelope.code === "INTERNAL_SERVER_ERROR") {
+      sendError(
+        c.res,
+        "INTERNAL_ERROR",
+        err instanceof Error ? err.message : "Internal server error",
+        500,
+        void 0,
+        c.requestId
+      );
+    } else {
+      sendError(
+        c.res,
+        envelope.code,
+        envelope.message,
+        envelopeCodeToStatus(envelope.code),
+        void 0,
+        c.requestId
+      );
+    }
   }
   if (c.pluginRunner) {
     const errCtxObj = {};
@@ -2036,4 +2082,4 @@ export {
   applySecurityHeaders,
   generateNonce
 };
-//# sourceMappingURL=chunk-MV4LKTW6.js.map
+//# sourceMappingURL=chunk-Z374WCMZ.js.map