@fuzdev/fuz_app 0.148.0 → 0.149.0

package/dist/http/error_schemas.js

@@ -131,6 +131,18 @@ export const ERROR_ROLE_NOT_WEB_GRANTABLE = 'role_not_web_grantable';
 export const ERROR_ROLE_GRANT_NOT_FOUND = 'role_grant_not_found';
 /** Query parameter `event_type` is not a valid audit event type. */
 export const ERROR_INVALID_EVENT_TYPE = 'invalid_event_type';
+// --- Declared input reasons (paged reads) ---
+// each is a field's `invalid_reason` (`schema_meta.ts`): every refusal of the
+// field carries it, whatever the fault — a wrong type or an unsafe integer
+// included; each is named `<field>_invalid`
+/** `limit` on a paged read refused — out of `[1, max]`, or not an integer. */
+export const ERROR_LIMIT_INVALID = 'limit_invalid';
+/** `offset` on a paged read refused — negative, or not a safe integer. */
+export const ERROR_OFFSET_INVALID = 'offset_invalid';
+/** `audit_log_list`'s `since_seq` cursor refused — negative, or not a safe integer. */
+export const ERROR_SINCE_SEQ_INVALID = 'since_seq_invalid';
+/** `audit_log_list`'s `outcome` filter refused — not `'success'` or `'failure'`. */
+export const ERROR_OUTCOME_INVALID = 'outcome_invalid';
 // --- DB table browser ---
 /** DELETE blocked by a foreign key constraint. */
 export const ERROR_FOREIGN_KEY_VIOLATION = 'foreign_key_violation';

package/dist/http/jsonrpc_errors.d.ts

@@ -4,7 +4,8 @@
  * Provides error types, named constructors, and HTTP status mapping
  * for the throw/catch error pattern used by `apply_route_specs`.
  * Core error codes (5 standard + 10 general application). Domain-specific
- * codes stay in consumers — add by casting `as JsonrpcErrorCode`.
+ * codes stay in consumers — add by casting `as JsonrpcErrorCode`, and
+ * declare each one's HTTP status with `register_jsonrpc_error_code`.
  *
  * `JsonrpcErrorCode` and `JsonrpcErrorObject` types are Zod-inferred
  * from `http/jsonrpc.ts` — this module re-uses those as the single source
@@ -26,7 +27,8 @@ export type JsonrpcErrorName = 'parse_error' | 'invalid_request' | 'method_not_f
  * Standard JSON-RPC error codes (5) plus general application codes (10).
  *
  * Extensible — consumers add domain-specific codes to their own objects
- * by casting `as JsonrpcErrorCode`. Application codes use the -32000 to
+ * by casting `as JsonrpcErrorCode`, and declare each one's HTTP status with
+ * `register_jsonrpc_error_code`. Application codes use the -32000 to
  * -32099 range reserved by the JSON-RPC spec.
  *
  * Frozen with `Object.freeze` to convert accidental mutation (test
@@ -99,27 +101,49 @@ export declare const jsonrpc_errors: {
     readonly request_cancelled: (...args: any[]) => ThrownJsonrpcError;
 };
 /**
- * Maps JSON-RPC error codes to HTTP status codes.
- *
- * Extensible — consumers with domain-specific error codes assign directly
- * (`JSONRPC_ERROR_CODE_TO_HTTP_STATUS[-32020] = 502`) at module load. The
- * lookup function reads at call time, so mutation is the supported
- * extension mechanism.
+ * Declare a consumer JSON-RPC error code and the HTTP status it answers, so
+ * `jsonrpc_error_code_to_http_status` maps it instead of falling back to 500.
+ *
+ * Call once at module load, beside the code's declaration — the module's
+ * import is then a side effect, so list it in the package's `sideEffects`.
+ * Registering the same code again with the same status is a no-op, so a
+ * module evaluated twice (a duplicated dependency, a test reload) is fine.
+ * A registered code joins neither `HTTP_STATUS_TO_JSONRPC_ERROR_CODE` (a bare
+ * status carries no consumer meaning, e.g. a proxy's envelope-less 502) nor
+ * `JSONRPC_ERROR_CODE_TO_NAME` (its name lives in the consumer's own
+ * taxonomy), matching the Rust spine's `ConsumerErrorCode`, which carries a
+ * code and a status only.
+ *
+ * @param code - a new code in the -32099 to -32000 server-error range
+ * @param http_status - the 4xx or 5xx status the code answers
+ * @throws Error when `code` is not an integer in -32099 to -32000, is a code
+ *   `JSONRPC_ERROR_CODES` defines, or is already registered with another
+ *   status, or when `http_status` is not an integer in 400 to 599
+ * @example
+ * ```ts
+ * export const JSONRPC_ERROR_CODES = {
+ * 	...BASE_JSONRPC_ERROR_CODES,
+ * 	ai_provider_error: -32020 as JsonrpcErrorCode
+ * } as const;
+ * register_jsonrpc_error_code(JSONRPC_ERROR_CODES.ai_provider_error, 502);
+ * ```
  */
-export declare const JSONRPC_ERROR_CODE_TO_HTTP_STATUS: Record<number, number>;
+export declare const register_jsonrpc_error_code: (code: JsonrpcErrorCode, http_status: number) => void;
 /**
- * Maps HTTP status codes to JSON-RPC error codes (reverse mapping).
+ * Maps HTTP status codes to JSON-RPC error codes (reverse mapping), over the
+ * base set only — built once at module load, before any consumer code is
+ * registered, and frozen.
  *
  * When multiple error codes map to the same HTTP status (e.g. parse_error
  * and invalid_request both map to 400), the last one wins. Use for
  * best-effort HTTP → JSON-RPC translation.
  */
-export declare const HTTP_STATUS_TO_JSONRPC_ERROR_CODE: Record<number, JsonrpcErrorCode>;
+export declare const HTTP_STATUS_TO_JSONRPC_ERROR_CODE: Readonly<Record<number, JsonrpcErrorCode>>;
 /**
  * Map a JSON-RPC error code to an HTTP status code.
  *
- * Returns 500 for unrecognized codes (consumer-defined codes
- * without a mapping default to internal server error). The return
+ * Returns 500 for unrecognized codes (a consumer code never passed to
+ * `register_jsonrpc_error_code` answers internal server error). The return
  * is narrowed to Hono's `ContentfulStatusCode` so call sites can
  * pass the result to `c.json(body, status)` without `as any` —
  * 499 (nginx "client closed request") is non-standard and gets
@@ -140,8 +164,9 @@ export declare const http_status_to_jsonrpc_error_code: (status: number) => Json
  * without inventing a separate vocabulary. Built once at module load
  * from the canonical `JSONRPC_ERROR_CODES` map so the two cannot drift.
  *
- * Consumer-defined codes outside the standard taxonomy are not present;
- * `jsonrpc_error_code_to_name` falls back to `'internal_error'` so the
+ * Consumer-defined codes outside the standard taxonomy are not present —
+ * registering one with `register_jsonrpc_error_code` gives it a status, not
+ * a name; `jsonrpc_error_code_to_name` falls back to `'internal_error'` so the
  * REST shape always carries some reason rather than `undefined`.
  */
 export declare const JSONRPC_ERROR_CODE_TO_NAME: Readonly<Record<number, JsonrpcErrorName>>;

package/dist/http/jsonrpc_errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonrpc_errors.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/jsonrpc_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,OAAO,EAMN,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,MAAM,cAAc,CAAC;AAEtB,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GACzB,aAAa,GACb,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,cAAc,GACd,qBAAqB,GACrB,SAAS,GACT,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EA4C1B,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,CAAC,GAAG,SAAsC,CAAC;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAmG7B,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEH,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY;CAK3F;AAWD;;;;GAIG;AACH,eAAO,MAAM,cAAc;8CAXQ,kBAAkB;kDAAlB,kBAAkB;mDAAlB,kBAAkB;iDAAlB,kBAAkB;iDAAlB,kBAAkB;kDAAlB,kBAAkB;4CAAlB,kBAAkB;4CAAlB,kBAAkB;2CAAlB,kBAAkB;mDAAlB,kBAAkB;+CAAlB,kBAAkB;sDAAlB,kBAAkB;0CAAlB,kBAAkB;iDAAlB,kBAAkB;oDAAlB,kBAAkB;CA2BqC,CAAC;AAI3F;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBpE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAM7E,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,GAAI,MAAM,gBAAgB,KAAG,oBACQ,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,GAAI,QAAQ,MAAM,KAAG,gBACa,CAAC;AAEjF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAMjF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,gBAAgB,KAAG,gBACL,CAAC"}
+{"version":3,"file":"jsonrpc_errors.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/jsonrpc_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,OAAO,EAQN,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,MAAM,cAAc,CAAC;AAEtB,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GACzB,aAAa,GACb,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,cAAc,GACd,qBAAqB,GACrB,SAAS,GACT,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EA4C1B,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,CAAC,GAAG,SAAsC,CAAC;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAmG7B,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEH,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY;CAK3F;AAWD;;;;GAIG;AACH,eAAO,MAAM,cAAc;8CAXQ,kBAAkB;kDAAlB,kBAAkB;mDAAlB,kBAAkB;iDAAlB,kBAAkB;iDAAlB,kBAAkB;kDAAlB,kBAAkB;4CAAlB,kBAAkB;4CAAlB,kBAAkB;2CAAlB,kBAAkB;mDAAlB,kBAAkB;+CAAlB,kBAAkB;sDAAlB,kBAAkB;0CAAlB,kBAAkB;iDAAlB,kBAAkB;oDAAlB,kBAAkB;CA2BqC,CAAC;AAqC3F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,gBAAgB,EAAE,aAAa,MAAM,KAAG,IA0BzF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAQvF,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,GAAI,MAAM,gBAAgB,KAAG,oBACC,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,GAAI,QAAQ,MAAM,KAAG,gBACa,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAMjF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,gBAAgB,KAAG,gBACL,CAAC"}

package/dist/http/jsonrpc_errors.js

@@ -4,7 +4,8 @@
  * Provides error types, named constructors, and HTTP status mapping
  * for the throw/catch error pattern used by `apply_route_specs`.
  * Core error codes (5 standard + 10 general application). Domain-specific
- * codes stay in consumers — add by casting `as JsonrpcErrorCode`.
+ * codes stay in consumers — add by casting `as JsonrpcErrorCode`, and
+ * declare each one's HTTP status with `register_jsonrpc_error_code`.
  *
  * `JsonrpcErrorCode` and `JsonrpcErrorObject` types are Zod-inferred
  * from `http/jsonrpc.ts` — this module re-uses those as the single source
@@ -17,14 +18,15 @@
  * @module
  */
 import { DEV } from 'esm-env';
-import { JSONRPC_PARSE_ERROR, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_INVALID_PARAMS, JSONRPC_INTERNAL_ERROR } from './jsonrpc.js';
+import { JSONRPC_PARSE_ERROR, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_INVALID_PARAMS, JSONRPC_INTERNAL_ERROR, JSONRPC_SERVER_ERROR_START, JSONRPC_SERVER_ERROR_END } from './jsonrpc.js';
 /** Default message for unknown errors. */
 export const UNKNOWN_ERROR_MESSAGE = 'unknown error';
 /**
  * Standard JSON-RPC error codes (5) plus general application codes (10).
  *
  * Extensible — consumers add domain-specific codes to their own objects
- * by casting `as JsonrpcErrorCode`. Application codes use the -32000 to
+ * by casting `as JsonrpcErrorCode`, and declare each one's HTTP status with
+ * `register_jsonrpc_error_code`. Application codes use the -32000 to
  * -32099 range reserved by the JSON-RPC spec.
  *
  * Frozen with `Object.freeze` to convert accidental mutation (test
@@ -225,54 +227,106 @@ export const jsonrpc_errors = {
 };
 // --- HTTP status mapping ---
 /**
- * Maps JSON-RPC error codes to HTTP status codes.
+ * The HTTP status each JSON-RPC error code answers — the base set, plus each
+ * consumer code `register_jsonrpc_error_code` adds.
  *
- * Extensible — consumers with domain-specific error codes assign directly
- * (`JSONRPC_ERROR_CODE_TO_HTTP_STATUS[-32020] = 502`) at module load. The
- * lookup function reads at call time, so mutation is the supported
- * extension mechanism.
+ * Module-private so a consumer can't remap a base code or skip the checks
+ * registration makes; read it through `jsonrpc_error_code_to_http_status`.
  */
-export const JSONRPC_ERROR_CODE_TO_HTTP_STATUS = {
-    [-32700]: 400, // parse_error
-    [-32600]: 400, // invalid_request
-    [-32601]: 404, // method_not_found
-    [-32602]: 400, // invalid_params
-    [-32603]: 500, // internal_error
-    [-32001]: 401, // unauthenticated
-    [-32002]: 403, // forbidden
-    [-32003]: 404, // not_found
-    [-32004]: 409, // conflict
-    [-32005]: 422, // validation_error
-    // queue_overflow shares 429 with rate_limited — listed first so reverse
-    // map wins with rate_limited (a policy) rather than a full buffer.
-    [-32009]: 429, // queue_overflow (backpressure)
-    [-32006]: 429, // rate_limited
-    [-32007]: 503, // service_unavailable
-    [-32008]: 504, // timeout
-    [-32010]: 499 // request_cancelled (nginx "client closed request")
+const jsonrpc_error_code_http_statuses = new Map([
+    [JSONRPC_PARSE_ERROR, 400],
+    [JSONRPC_INVALID_REQUEST, 400],
+    [JSONRPC_METHOD_NOT_FOUND, 404],
+    [JSONRPC_INVALID_PARAMS, 400],
+    [JSONRPC_INTERNAL_ERROR, 500],
+    [JSONRPC_ERROR_CODES.unauthenticated, 401],
+    [JSONRPC_ERROR_CODES.forbidden, 403],
+    [JSONRPC_ERROR_CODES.not_found, 404],
+    [JSONRPC_ERROR_CODES.conflict, 409],
+    [JSONRPC_ERROR_CODES.validation_error, 422],
+    // queue_overflow shares 429 with rate_limited — listed first so the
+    // last-wins reverse map resolves 429 to rate_limited (a policy) rather
+    // than a full buffer
+    [JSONRPC_ERROR_CODES.queue_overflow, 429],
+    [JSONRPC_ERROR_CODES.rate_limited, 429],
+    [JSONRPC_ERROR_CODES.service_unavailable, 503],
+    [JSONRPC_ERROR_CODES.timeout, 504],
+    [JSONRPC_ERROR_CODES.request_cancelled, 499] // nginx "client closed request"
+]);
+/** Every code `JSONRPC_ERROR_CODES` defines — the numbers a consumer code may not reuse. */
+const BASE_JSONRPC_ERROR_CODE_SET = new Set(Object.values(JSONRPC_ERROR_CODES));
+/**
+ * Declare a consumer JSON-RPC error code and the HTTP status it answers, so
+ * `jsonrpc_error_code_to_http_status` maps it instead of falling back to 500.
+ *
+ * Call once at module load, beside the code's declaration — the module's
+ * import is then a side effect, so list it in the package's `sideEffects`.
+ * Registering the same code again with the same status is a no-op, so a
+ * module evaluated twice (a duplicated dependency, a test reload) is fine.
+ * A registered code joins neither `HTTP_STATUS_TO_JSONRPC_ERROR_CODE` (a bare
+ * status carries no consumer meaning, e.g. a proxy's envelope-less 502) nor
+ * `JSONRPC_ERROR_CODE_TO_NAME` (its name lives in the consumer's own
+ * taxonomy), matching the Rust spine's `ConsumerErrorCode`, which carries a
+ * code and a status only.
+ *
+ * @param code - a new code in the -32099 to -32000 server-error range
+ * @param http_status - the 4xx or 5xx status the code answers
+ * @throws Error when `code` is not an integer in -32099 to -32000, is a code
+ *   `JSONRPC_ERROR_CODES` defines, or is already registered with another
+ *   status, or when `http_status` is not an integer in 400 to 599
+ * @example
+ * ```ts
+ * export const JSONRPC_ERROR_CODES = {
+ * 	...BASE_JSONRPC_ERROR_CODES,
+ * 	ai_provider_error: -32020 as JsonrpcErrorCode
+ * } as const;
+ * register_jsonrpc_error_code(JSONRPC_ERROR_CODES.ai_provider_error, 502);
+ * ```
+ */
+export const register_jsonrpc_error_code = (code, http_status) => {
+    if (!Number.isInteger(code) ||
+        code < JSONRPC_SERVER_ERROR_END ||
+        code > JSONRPC_SERVER_ERROR_START) {
+        throw new Error(`a consumer JSON-RPC error code must be an integer in ${JSONRPC_SERVER_ERROR_END} to ${JSONRPC_SERVER_ERROR_START}, got ${code}`);
+    }
+    if (BASE_JSONRPC_ERROR_CODE_SET.has(code)) {
+        throw new Error(`a consumer JSON-RPC error code may not reuse a base-set code, got ${code}`);
+    }
+    if (!Number.isInteger(http_status) || http_status < 400 || http_status > 599) {
+        throw new Error(`a consumer JSON-RPC error code must answer a 4xx or 5xx status, got ${http_status} for ${code}`);
+    }
+    const registered = jsonrpc_error_code_http_statuses.get(code);
+    if (registered === undefined) {
+        jsonrpc_error_code_http_statuses.set(code, http_status);
+    }
+    else if (registered !== http_status) {
+        throw new Error(`JSON-RPC error code ${code} is already registered with status ${registered}, not ${http_status}`);
+    }
 };
 /**
- * Maps HTTP status codes to JSON-RPC error codes (reverse mapping).
+ * Maps HTTP status codes to JSON-RPC error codes (reverse mapping), over the
+ * base set only — built once at module load, before any consumer code is
+ * registered, and frozen.
  *
  * When multiple error codes map to the same HTTP status (e.g. parse_error
  * and invalid_request both map to 400), the last one wins. Use for
  * best-effort HTTP → JSON-RPC translation.
  */
-export const HTTP_STATUS_TO_JSONRPC_ERROR_CODE = Object.fromEntries(Object.entries(JSONRPC_ERROR_CODE_TO_HTTP_STATUS).map(([code, status]) => [
+export const HTTP_STATUS_TO_JSONRPC_ERROR_CODE = Object.freeze(Object.fromEntries(Array.from(jsonrpc_error_code_http_statuses, ([code, status]) => [
     status,
-    Number(code)
-]));
+    code
+])));
 /**
  * Map a JSON-RPC error code to an HTTP status code.
  *
- * Returns 500 for unrecognized codes (consumer-defined codes
- * without a mapping default to internal server error). The return
+ * Returns 500 for unrecognized codes (a consumer code never passed to
+ * `register_jsonrpc_error_code` answers internal server error). The return
  * is narrowed to Hono's `ContentfulStatusCode` so call sites can
  * pass the result to `c.json(body, status)` without `as any` —
  * 499 (nginx "client closed request") is non-standard and gets
  * absorbed by the cast here rather than at every dispatcher branch.
  */
-export const jsonrpc_error_code_to_http_status = (code) => (JSONRPC_ERROR_CODE_TO_HTTP_STATUS[code] ?? 500);
+export const jsonrpc_error_code_to_http_status = (code) => (jsonrpc_error_code_http_statuses.get(code) ?? 500);
 /**
  * Map an HTTP status code to a JSON-RPC error code.
  *
@@ -287,8 +341,9 @@ export const http_status_to_jsonrpc_error_code = (status) => HTTP_STATUS_TO_JSON
  * without inventing a separate vocabulary. Built once at module load
  * from the canonical `JSONRPC_ERROR_CODES` map so the two cannot drift.
  *
- * Consumer-defined codes outside the standard taxonomy are not present;
- * `jsonrpc_error_code_to_name` falls back to `'internal_error'` so the
+ * Consumer-defined codes outside the standard taxonomy are not present —
+ * registering one with `register_jsonrpc_error_code` gives it a status, not
+ * a name; `jsonrpc_error_code_to_name` falls back to `'internal_error'` so the
  * REST shape always carries some reason rather than `undefined`.
  */
 export const JSONRPC_ERROR_CODE_TO_NAME = Object.freeze(Object.fromEntries(Object.entries(JSONRPC_ERROR_CODES).map(([name, code]) => [code, name])));

package/dist/schema_meta.d.ts

@@ -25,6 +25,29 @@ export interface SchemaFieldMeta {
      * schema itself, so a wrapper (`.optional()`, `.extend()`) drops it.
      */
     empty_input_handler_guarded?: boolean;
+    /**
+     * The `error.data.reason` an action input refuses this field with. On a
+     * field of an action's **input** schema, every `invalid_params` whose first
+     * Zod issue lands on the field — missing, wrong type, `null`, out of range,
+     * malformed, or a fault anywhere inside it — carries this reason, where an
+     * undeclared field's refusal carries none. The message stays the generic
+     * `invalid params`. A body with faults on several fields answers the first
+     * issue's reason in Zod's order, which a twin checking in another order
+     * need not match, so the reason is defined for a single-fault body only —
+     * except that an issue on the input itself (an unknown key) anywhere among
+     * the issues means no reason, as the Rust twin refuses unknown keys first.
+     * Declared reasons are named `<field>_invalid`.
+     *
+     * The declaration is the one source of the reason: the dispatcher reads it
+     * (`perform_action`), the adversarial suites expect it, and the Rust twin
+     * owes the same reason on every refusal of the field. Read through the
+     * field's optional, nullable, default, prefault, transform and pipe layers
+     * (not `.readonly()`, `.catch()` or `z.lazy()`), so it may sit on any of
+     * them; a declaration on a nested field overrides its parent's for a fault
+     * inside it, and an object-level refine whose issue names the field takes
+     * its reason too. See `resolve_issues_invalid_reason`.
+     */
+    invalid_reason?: string;
 }
 /**
  * Whether `schema` carries `empty_input_handler_guarded: true` in its `.meta()`.
@@ -33,4 +56,41 @@ export interface SchemaFieldMeta {
  * @returns whether its handler refuses the `{}` the schema admits
  */
 export declare const is_empty_input_handler_guarded: (schema: z.ZodType) => boolean;
+/**
+ * The `invalid_reason` a schema declares, read through its wrappers, the
+ * outermost declaration winning.
+ *
+ * @param schema - a field schema, possibly wrapped
+ * @returns the declared reason, or `undefined` when no layer declares one
+ */
+export declare const schema_invalid_reason: (schema: z.ZodType) => string | undefined;
+/**
+ * The `error.data.reason` an input validation failure at `path` carries: the
+ * `invalid_reason` of the deepest field along `path` that declares one.
+ *
+ * Walks object fields only, each through its wrappers: a segment that is not
+ * a key of an object schema (an array index, a union member's key, an unknown
+ * key) ends the walk, so a fault inside a declared field still resolves to
+ * that field's reason. An empty path — a whole-input fault such as an
+ * unrecognized key on the input object — resolves to none, as does a schema
+ * that is not an object.
+ *
+ * @param input_schema - an action's input schema
+ * @param path - the failing issue's path (`ZodError.issues[0].path`)
+ * @returns the declared reason, or `undefined`
+ */
+export declare const resolve_invalid_reason: (input_schema: z.ZodType, path: ReadonlyArray<PropertyKey>) => string | undefined;
+/**
+ * The `error.data.reason` a failed input parse answers: the declared reason
+ * of the first issue's field (`resolve_invalid_reason`), or none when any
+ * issue sits on the input itself. Such an issue is an unknown key on the
+ * input object (or a non-object input), which the Rust twin refuses before
+ * reading any field, so a stale client sending an extra key gets the same
+ * answer from both spines whatever else its body gets wrong.
+ *
+ * @param input_schema - an action's input schema
+ * @param issues - the failed parse's issues, in Zod's order
+ * @returns the declared reason, or `undefined`
+ */
+export declare const resolve_issues_invalid_reason: (input_schema: z.ZodType, issues: ReadonlyArray<z.core.$ZodIssue>) => string | undefined;
 //# sourceMappingURL=schema_meta.d.ts.map

package/dist/schema_meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema_meta.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/schema_meta.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OACkB,CAAC"}
+{"version":3,"file":"schema_meta.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/schema_meta.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OACkB,CAAC;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAAM,GAAG,SAMlE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,GAClC,cAAc,CAAC,CAAC,OAAO,EACvB,MAAM,aAAa,CAAC,WAAW,CAAC,KAC9B,MAAM,GAAG,SAYX,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,GACzC,cAAc,CAAC,CAAC,OAAO,EACvB,QAAQ,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KACrC,MAAM,GAAG,SAIX,CAAC"}

package/dist/schema_meta.js

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import { zod_get_schema_layers, zod_unwrap_to_object } from './zod.js';
 /**
  * Whether `schema` carries `empty_input_handler_guarded: true` in its `.meta()`.
  *
@@ -13,3 +14,66 @@
  * @returns whether its handler refuses the `{}` the schema admits
  */
 export const is_empty_input_handler_guarded = (schema) => schema.meta()?.empty_input_handler_guarded === true;
+/**
+ * The `invalid_reason` a schema declares, read through its wrappers, the
+ * outermost declaration winning.
+ *
+ * @param schema - a field schema, possibly wrapped
+ * @returns the declared reason, or `undefined` when no layer declares one
+ */
+export const schema_invalid_reason = (schema) => {
+    for (const layer of zod_get_schema_layers(schema)) {
+        const reason = layer.meta()?.invalid_reason;
+        if (reason !== undefined)
+            return reason;
+    }
+    return undefined;
+};
+/**
+ * The `error.data.reason` an input validation failure at `path` carries: the
+ * `invalid_reason` of the deepest field along `path` that declares one.
+ *
+ * Walks object fields only, each through its wrappers: a segment that is not
+ * a key of an object schema (an array index, a union member's key, an unknown
+ * key) ends the walk, so a fault inside a declared field still resolves to
+ * that field's reason. An empty path — a whole-input fault such as an
+ * unrecognized key on the input object — resolves to none, as does a schema
+ * that is not an object.
+ *
+ * @param input_schema - an action's input schema
+ * @param path - the failing issue's path (`ZodError.issues[0].path`)
+ * @returns the declared reason, or `undefined`
+ */
+export const resolve_invalid_reason = (input_schema, path) => {
+    let reason;
+    let schema = input_schema;
+    for (const segment of path) {
+        if (typeof segment !== 'string')
+            break;
+        const shape = zod_unwrap_to_object(schema)?.shape;
+        if (!shape || !Object.hasOwn(shape, segment))
+            break;
+        const field = shape[segment];
+        reason = schema_invalid_reason(field) ?? reason;
+        schema = field;
+    }
+    return reason;
+};
+/**
+ * The `error.data.reason` a failed input parse answers: the declared reason
+ * of the first issue's field (`resolve_invalid_reason`), or none when any
+ * issue sits on the input itself. Such an issue is an unknown key on the
+ * input object (or a non-object input), which the Rust twin refuses before
+ * reading any field, so a stale client sending an extra key gets the same
+ * answer from both spines whatever else its body gets wrong.
+ *
+ * @param input_schema - an action's input schema
+ * @param issues - the failed parse's issues, in Zod's order
+ * @returns the declared reason, or `undefined`
+ */
+export const resolve_issues_invalid_reason = (input_schema, issues) => {
+    const first = issues[0];
+    if (!first || issues.some((issue) => issue.path.length === 0))
+        return undefined;
+    return resolve_invalid_reason(input_schema, first.path);
+};