@fuzdev/fuz_app 0.147.0 → 0.149.0

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/primitive_schemas.d.ts

@@ -53,7 +53,7 @@ export interface BoundedStringOptions {
  * @param options - the bounds, in UTF-16 code units
  * @returns the bounded string schema
  */
-export declare const bounded_string: ({ min, max, max_message }: BoundedStringOptions) => z.ZodString;
+export declare const bounded_string: (options: BoundedStringOptions) => z.ZodString;
 /** Minimum username length (must have start + middle + end characters). */
 export declare const USERNAME_LENGTH_MIN = 3;
 /** Maximum username length (matches GitHub's limit). The grammar is ASCII, so units and characters agree. */

package/dist/primitive_schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAIlF,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,GAAI,2BAA2B,oBAAoB,KAAG,CAAC,CAAC,SA8ClF,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,6GAA6G;AAC7G,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gNAAgN;AAChN,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,wDAEc,CAAC;AACpC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,wDAEqE,CAAC;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAqBpC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,aAYhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C,wCAAwC;AACxC,eAAO,MAAM,WAAW,QAAO,IAAmC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,8CAAuC,CAAC;AACzD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC,qFAAqF;AACrF,eAAO,MAAM,eAAe,4DAA4B,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,wCAAwC;AACxC,eAAO,MAAM,QAAQ,yDAAqC,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,QAAO,QAAgD,CAAC;AAErF,sFAAsF;AACtF,eAAO,MAAM,WAAW,uEAAqC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,uFAAuF;AACvF,eAAO,MAAM,UAAU,aAEuD,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAEA,CAAC"}
+{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAIlF,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,oBAAoB,KAAG,CAAC,CAAC,SA+ChE,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,6GAA6G;AAC7G,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gNAAgN;AAChN,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,wDAEc,CAAC;AACpC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,wDAEqE,CAAC;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAqBpC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,aAYhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C,wCAAwC;AACxC,eAAO,MAAM,WAAW,QAAO,IAAmC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,8CAAuC,CAAC;AACzD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC,qFAAqF;AACrF,eAAO,MAAM,eAAe,4DAA4B,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,wCAAwC;AACxC,eAAO,MAAM,QAAQ,yDAAqC,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,QAAO,QAAgD,CAAC;AAErF,sFAAsF;AACtF,eAAO,MAAM,WAAW,uEAAqC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,uFAAuF;AACvF,eAAO,MAAM,UAAU,aAEuD,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAEA,CAAC"}

package/dist/primitive_schemas.js

@@ -44,7 +44,8 @@ import { FACT_HASH_EXACT } from '@fuzdev/fuz_util/hash_schemas.ts';
  * @param options - the bounds, in UTF-16 code units
  * @returns the bounded string schema
  */
-export const bounded_string = ({ min, max, max_message }) => {
+export const bounded_string = (options) => {
+    const { min, max, max_message } = options;
     let schema = z.string();
     if (min !== undefined)
         schema = schema.min(min);

package/dist/schema_meta.d.ts

@@ -6,11 +6,91 @@
  *
  * @module
  */
+import type { z } from 'zod';
 import type { Sensitivity } from './sensitivity.js';
 /** Zod `.meta()` shape for fuz_app schema metadata conventions. */
 export interface SchemaFieldMeta {
     description?: string;
     /** Sensitivity level for masking/redaction. `'secret'` masks the value. */
     sensitivity?: Sensitivity;
+    /**
+     * Set on an action's **input** schema that accepts `{}` by design while
+     * its handler refuses `{}` with a declared reason — an input taking one of
+     * several optional selectors, where the handler names the missing or
+     * conflicting one (a schema-level refine would answer a reason-less
+     * `invalid_params` first). A call with no input is never valid for such an
+     * action, so the typed surface keeps its input required
+     * (`action_input_is_optional`), and the input-shape invariant ("an input
+     * accepting `{}` accepts `undefined` too") exempts it. Read from the input
+     * 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()`.
+ *
+ * @param schema - an action's input schema
+ * @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,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;CAC1B"}
+{"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,4 +6,74 @@
  *
  * @module
  */
-export {};
+import { zod_get_schema_layers, zod_unwrap_to_object } from './zod.js';
+/**
+ * Whether `schema` carries `empty_input_handler_guarded: true` in its `.meta()`.
+ *
+ * @param schema - an action's input schema
+ * @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);
+};