@fuzdev/fuz_app 0.5.0 → 0.6.0

package/dist/actions/action_bridge.d.ts

@@ -39,7 +39,7 @@ export declare const derive_http_method: (side_effects: ActionSideEffects) => Ro
  * Derive a `RouteSpec` from an `ActionSpec` and options.
  *
  * Only `request_response` actions (which require non-null `auth`) can become routes.
- * `remote_notification` actions (auth null) should use `event_spec_from_action`.
+ * `remote_notification` actions (auth null) should use `create_action_event_spec`.
  * `local_call` actions are not for HTTP transport.
  *
  * Error schemas are transport-specific (keyed by HTTP status codes) and belong
@@ -51,7 +51,7 @@ export declare const derive_http_method: (side_effects: ActionSideEffects) => Ro
  * @returns a `RouteSpec` ready for `apply_route_specs`
  * @throws if `spec.auth` is null
  */
-export declare const route_spec_from_action: (spec: ActionSpec, options: ActionRouteOptions) => RouteSpec;
+export declare const create_action_route_spec: (spec: ActionSpec, options: ActionRouteOptions) => RouteSpec;
 /**
  * Derive an `SseEventSpec` from an `ActionSpec`.
  *
@@ -61,5 +61,5 @@ export declare const route_spec_from_action: (spec: ActionSpec, options: ActionR
  * @param options - optional SSE-specific options (channel)
  * @returns an `SseEventSpec` ready for `create_validated_broadcaster`
  */
-export declare const event_spec_from_action: (spec: ActionSpec, options?: ActionEventOptions) => SseEventSpec;
+export declare const create_action_event_spec: (spec: ActionSpec, options?: ActionEventOptions) => SseEventSpec;
 //# sourceMappingURL=action_bridge.d.ts.map

package/dist/actions/action_bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,UAAU,IAAI,cAAc,EAAE,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAClG,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+IAA+I;IAC/I,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,KAAG,SAKtD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SAkBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,YAYF,CAAC"}
+{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,UAAU,IAAI,cAAc,EAAE,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAClG,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+IAA+I;IAC/I,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,KAAG,SAKtD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SAmBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,YAYF,CAAC"}

package/dist/actions/action_bridge.js

@@ -25,7 +25,7 @@ export const derive_http_method = (side_effects) => {
  * Derive a `RouteSpec` from an `ActionSpec` and options.
  *
  * Only `request_response` actions (which require non-null `auth`) can become routes.
- * `remote_notification` actions (auth null) should use `event_spec_from_action`.
+ * `remote_notification` actions (auth null) should use `create_action_event_spec`.
  * `local_call` actions are not for HTTP transport.
  *
  * Error schemas are transport-specific (keyed by HTTP status codes) and belong
@@ -37,7 +37,7 @@ export const derive_http_method = (side_effects) => {
  * @returns a `RouteSpec` ready for `apply_route_specs`
  * @throws if `spec.auth` is null
  */
-export const route_spec_from_action = (spec, options) => {
+export const create_action_route_spec = (spec, options) => {
     if (spec.auth === null) {
         throw new Error(`Cannot derive route spec from action '${spec.method}': auth is null (only request_response actions with non-null auth can become routes)`);
     }
@@ -52,6 +52,7 @@ export const route_spec_from_action = (spec, options) => {
         input: spec.input,
         output: spec.output,
         ...(options.errors ? { errors: options.errors } : {}),
+        transaction: spec.side_effects,
     };
 };
 /**
@@ -63,7 +64,7 @@ export const route_spec_from_action = (spec, options) => {
  * @param options - optional SSE-specific options (channel)
  * @returns an `SseEventSpec` ready for `create_validated_broadcaster`
  */
-export const event_spec_from_action = (spec, options) => {
+export const create_action_event_spec = (spec, options) => {
     if (spec.kind !== 'remote_notification') {
         throw new Error(`Cannot derive event spec from action '${spec.method}': kind is '${spec.kind}' (must be 'remote_notification')`);
     }

package/dist/actions/action_rpc.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Single JSON-RPC 2.0 endpoint from action specs.
+ *
+ * `create_rpc_endpoint` produces `RouteSpec[]` (GET + POST on one path)
+ * with an internal dispatcher. Method name lives in the JSON-RPC envelope
+ * (POST body or GET query string), not the URL. Auth is checked per-action
+ * inside the dispatcher.
+ *
+ * Handler signature: `(input: TInput, ctx: ActionContext) => TOutput`
+ * where `ActionContext` provides auth identity, DB, and framework context.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { RequestResponseActionSpec } from './action_spec.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import { type RequestContext } from '../auth/request_context.js';
+import type { Db } from '../db/db.js';
+/**
+ * Per-request context provided to RPC action handlers.
+ *
+ * Extends `RouteContext` with auth identity and logger.
+ * `auth` is `RequestContext | null` — handlers for authenticated
+ * actions can narrow via the auth middleware guarantee.
+ */
+export interface ActionContext {
+    /** The authenticated identity, or `null` for public routes. */
+    auth: RequestContext | null;
+    /** Transaction-scoped for mutations, pool-level for reads. */
+    db: Db;
+    /** Always pool-level — for fire-and-forget effects that outlive the transaction. */
+    background_db: Db;
+    /** Fire-and-forget side effects — push here for post-response flushing. */
+    pending_effects: Array<Promise<void>>;
+    /** Logger instance. */
+    log: Logger;
+}
+/**
+ * Handler function for an RPC action.
+ *
+ * Receives validated input and an `ActionContext` with per-request deps.
+ * Returns the output value (serialized to JSON by the wrapper).
+ */
+export type ActionHandler<TInput = any, TOutput = any> = (input: TInput, ctx: ActionContext) => TOutput | Promise<TOutput>;
+/**
+ * An RPC action — combines an action spec with its handler.
+ *
+ * The spec defines the contract (method, auth, schemas, side effects).
+ * The handler implements the behavior.
+ */
+export interface RpcAction {
+    spec: RequestResponseActionSpec;
+    handler: ActionHandler;
+}
+/** Options for `create_rpc_endpoint`. */
+export interface CreateRpcEndpointOptions {
+    /** Mount path for the endpoint (e.g., `/api/rpc`). */
+    path: string;
+    /** RPC actions to serve. */
+    actions: Array<RpcAction>;
+    /** Logger instance for handler context. */
+    log: Logger;
+}
+/**
+ * Single JSON-RPC 2.0 endpoint — the canonical RPC transport binding.
+ *
+ * Returns two `RouteSpec` entries (GET + POST on the same path) for
+ * `apply_route_specs`. The internal dispatcher handles:
+ *
+ * 1. **Parse envelope** — POST: JSON body as `JsonrpcRequest`. GET: `method`
+ *    and `params` from query string.
+ * 2. **Lookup method** — find the `RpcAction` by method name.
+ * 3. **Auth check** — verify identity against the action's `auth` requirement.
+ * 4. **Validate params** — parse input against the action's `input` schema.
+ * 5. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
+ *    construct `ActionContext`, call handler, return JSON-RPC response.
+ *
+ * GET is restricted to `side_effects: false` actions (cacheable reads).
+ * All errors use JSON-RPC format: `{jsonrpc, id, error: {code, message, data?}}`.
+ *
+ * The RouteSpecs use `auth: {type: 'none'}` because auth is checked per-action
+ * inside the dispatcher, and `transaction: false` because transaction scope
+ * is per-action (mutations get a transaction, reads get pool).
+ *
+ * @param options - endpoint path, actions, and logger
+ * @returns route specs (GET + POST) ready for `apply_route_specs`
+ */
+export declare const create_rpc_endpoint: (options: CreateRpcEndpointOptions) => Array<RouteSpec>;
+//# sourceMappingURL=action_rpc.d.ts.map

package/dist/actions/action_rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAC9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAWpC;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACxD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;CACZ;AA4CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CA6NtF,CAAC"}

package/dist/actions/action_rpc.js

@@ -0,0 +1,248 @@
+/**
+ * Single JSON-RPC 2.0 endpoint from action specs.
+ *
+ * `create_rpc_endpoint` produces `RouteSpec[]` (GET + POST on one path)
+ * with an internal dispatcher. Method name lives in the JSON-RPC envelope
+ * (POST body or GET query string), not the URL. Auth is checked per-action
+ * inside the dispatcher.
+ *
+ * Handler signature: `(input: TInput, ctx: ActionContext) => TOutput`
+ * where `ActionContext` provides auth identity, DB, and framework context.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { DEV } from 'esm-env';
+import {} from '../http/route_spec.js';
+import { get_request_context, has_role } from '../auth/request_context.js';
+import { is_null_schema } from '../http/schema_helpers.js';
+import { JSONRPC_VERSION, JsonrpcRequest } from '../http/jsonrpc.js';
+import { jsonrpc_error_messages, jsonrpc_error_code_to_http_status, JSONRPC_ERROR_CODES, ThrownJsonrpcError, } from '../http/jsonrpc_errors.js';
+/**
+ * Format a JSON-RPC error response.
+ *
+ * @param id - the request id (null if unknown)
+ * @param error - the error object
+ * @returns a JSON-RPC error response object
+ */
+const jsonrpc_error_response = (id, error) => ({
+    jsonrpc: JSONRPC_VERSION,
+    id,
+    error,
+});
+/**
+ * Check auth for an action spec against the request context.
+ *
+ * @param auth - the action's auth requirement
+ * @param request_context - the resolved identity (null if unauthenticated)
+ * @returns an error json if auth fails, or null if authorized
+ */
+const check_action_auth = (auth, request_context) => {
+    if (auth === 'public')
+        return null;
+    if (!request_context)
+        return jsonrpc_error_messages.unauthenticated();
+    if (auth === 'authenticated')
+        return null;
+    if (auth === 'keeper') {
+        // keeper requires the keeper role
+        if (!has_role(request_context, 'keeper'))
+            return jsonrpc_error_messages.forbidden();
+        return null;
+    }
+    // role check
+    if (!has_role(request_context, auth.role)) {
+        return jsonrpc_error_messages.forbidden(`requires role: ${auth.role}`);
+    }
+    return null;
+};
+/**
+ * Single JSON-RPC 2.0 endpoint — the canonical RPC transport binding.
+ *
+ * Returns two `RouteSpec` entries (GET + POST on the same path) for
+ * `apply_route_specs`. The internal dispatcher handles:
+ *
+ * 1. **Parse envelope** — POST: JSON body as `JsonrpcRequest`. GET: `method`
+ *    and `params` from query string.
+ * 2. **Lookup method** — find the `RpcAction` by method name.
+ * 3. **Auth check** — verify identity against the action's `auth` requirement.
+ * 4. **Validate params** — parse input against the action's `input` schema.
+ * 5. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
+ *    construct `ActionContext`, call handler, return JSON-RPC response.
+ *
+ * GET is restricted to `side_effects: false` actions (cacheable reads).
+ * All errors use JSON-RPC format: `{jsonrpc, id, error: {code, message, data?}}`.
+ *
+ * The RouteSpecs use `auth: {type: 'none'}` because auth is checked per-action
+ * inside the dispatcher, and `transaction: false` because transaction scope
+ * is per-action (mutations get a transaction, reads get pool).
+ *
+ * @param options - endpoint path, actions, and logger
+ * @returns route specs (GET + POST) ready for `apply_route_specs`
+ */
+export const create_rpc_endpoint = (options) => {
+    const { path: endpoint_path, actions, log } = options;
+    // build action lookup map
+    const action_map = new Map();
+    for (const action of actions) {
+        if (action_map.has(action.spec.method)) {
+            throw new Error(`Duplicate RPC action method: ${action.spec.method}`);
+        }
+        action_map.set(action.spec.method, action);
+    }
+    /**
+     * Core dispatcher — shared by GET and POST handlers.
+     *
+     * @param c - Hono context
+     * @param route - route context with db and pending_effects
+     * @param method_name - the JSON-RPC method name
+     * @param raw_params - the raw params (parsed from body or query string)
+     * @param id - the request id
+     * @param restrict_to_reads - true for GET requests (reject side_effects actions)
+     * @returns a Response
+     */
+    const dispatch = async (c, route, method_name, raw_params, id, restrict_to_reads) => {
+        // step 2: lookup method
+        const action = action_map.get(method_name);
+        if (!action) {
+            const error = jsonrpc_error_response(id, jsonrpc_error_messages.method_not_found(method_name));
+            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.method_not_found));
+        }
+        // GET restriction: only side_effects:false actions
+        if (restrict_to_reads && action.spec.side_effects) {
+            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_request({
+                reason: `method '${method_name}' has side effects and must use POST`,
+            }));
+            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_request));
+        }
+        // step 3: auth check
+        const request_context = get_request_context(c);
+        const auth_error = check_action_auth(action.spec.auth, request_context);
+        if (auth_error) {
+            const error = jsonrpc_error_response(id, auth_error);
+            return c.json(error, jsonrpc_error_code_to_http_status(auth_error.code));
+        }
+        // step 4: validate params
+        const params = raw_params ?? (is_null_schema(action.spec.input) ? null : undefined);
+        const parse_result = action.spec.input.safeParse(params);
+        if (!parse_result.success) {
+            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params('invalid params', {
+                issues: parse_result.error.issues,
+            }));
+            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_params));
+        }
+        // step 5: dispatch — transaction for mutations, pool for reads
+        const use_transaction = action.spec.side_effects;
+        const execute = async (db) => {
+            const action_context = {
+                auth: request_context,
+                db,
+                background_db: route.background_db,
+                pending_effects: route.pending_effects,
+                log,
+            };
+            const output = await action.handler(parse_result.data, action_context);
+            // DEV-only output validation
+            if (DEV) {
+                const output_result = action.spec.output.safeParse(output);
+                if (!output_result.success) {
+                    log.warn(`RPC output schema mismatch: ${method_name}`, output_result.error.issues);
+                }
+            }
+            return c.json({ jsonrpc: JSONRPC_VERSION, id, result: output });
+        };
+        // error handling wraps the transaction boundary so handler throws
+        // cause rollback before the error is formatted as a JSON-RPC response
+        try {
+            if (use_transaction) {
+                return await route.db.transaction((tx) => execute(tx));
+            }
+            return await execute(route.db);
+        }
+        catch (err) {
+            if (err instanceof ThrownJsonrpcError) {
+                const status = jsonrpc_error_code_to_http_status(err.code);
+                const error_json = { code: err.code, message: err.message };
+                if (err.data !== undefined)
+                    error_json.data = err.data;
+                return c.json(jsonrpc_error_response(id, error_json), status);
+            }
+            // generic error
+            log.error(`Unhandled RPC handler error: ${method_name}`, err);
+            const message = DEV && err instanceof Error ? err.message : 'internal server error';
+            return c.json(jsonrpc_error_response(id, jsonrpc_error_messages.internal_error(message)), 500);
+        }
+    };
+    // POST handler — parse JSON-RPC envelope from body
+    const post_handler = async (c, route) => {
+        // step 1: parse envelope
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            const error = jsonrpc_error_response(null, jsonrpc_error_messages.parse_error());
+            return c.json(error, 400);
+        }
+        const envelope = JsonrpcRequest.safeParse(body);
+        if (!envelope.success) {
+            // try to extract id even from an invalid envelope
+            const raw_id = typeof body === 'object' && body !== null && 'id' in body
+                ? body.id
+                : null;
+            const id = typeof raw_id === 'string' || typeof raw_id === 'number' ? raw_id : null;
+            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_request({ issues: envelope.error.issues }));
+            return c.json(error, 400);
+        }
+        return dispatch(c, route, envelope.data.method, envelope.data.params, envelope.data.id, false);
+    };
+    // GET handler — extract method and params from query string
+    const get_handler = async (c, route) => {
+        // step 1: parse from query string
+        const method_name = c.req.query('method');
+        if (!method_name) {
+            const error = jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request({ reason: 'missing method query parameter' }));
+            return c.json(error, 400);
+        }
+        const id_raw = c.req.query('id');
+        if (!id_raw) {
+            const error = jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request({ reason: 'missing id query parameter' }));
+            return c.json(error, 400);
+        }
+        // parse params from query string (optional — null input schemas need no params)
+        const params_raw = c.req.query('params');
+        let params;
+        if (params_raw !== undefined) {
+            try {
+                params = JSON.parse(params_raw);
+            }
+            catch {
+                const error = jsonrpc_error_response(id_raw, jsonrpc_error_messages.invalid_params('params query parameter is not valid JSON'));
+                return c.json(error, 400);
+            }
+        }
+        return dispatch(c, route, method_name, params, id_raw, true);
+    };
+    return [
+        {
+            method: 'POST',
+            path: endpoint_path,
+            auth: { type: 'none' }, // per-action auth inside dispatcher
+            handler: post_handler,
+            description: `JSON-RPC 2.0 endpoint — ${actions.length} method${actions.length === 1 ? '' : 's'}`,
+            input: z.null(), // dispatcher owns body parsing; rpc_endpoints surface has the real schemas
+            output: z.any(), // varies by method
+            transaction: false, // per-action inside dispatcher
+        },
+        {
+            method: 'GET',
+            path: endpoint_path,
+            auth: { type: 'none' }, // per-action auth inside dispatcher
+            handler: get_handler,
+            description: `JSON-RPC 2.0 endpoint (cacheable reads) — ${actions.length} method${actions.length === 1 ? '' : 's'}`,
+            input: z.null(), // params from query string, validated by dispatcher
+            output: z.any(), // varies by method
+            transaction: false, // per-action inside dispatcher
+        },
+    ];
+};

package/dist/http/jsonrpc.d.ts

@@ -0,0 +1,62 @@
+/**
+ * JSON-RPC 2.0 envelope schemas for the single RPC endpoint dispatcher.
+ *
+ * Minimal subset extracted from zzz's `jsonrpc.ts` — only what the
+ * `create_rpc_endpoint` dispatcher needs to parse incoming requests
+ * and format outgoing responses. Full JSON-RPC schemas (batching,
+ * MCP extensions, notification types) remain in zzz.
+ *
+ * Following MCP, params and result are object-only (no positional arrays).
+ *
+ * @source https://github.com/modelcontextprotocol/typescript-sdk
+ * @see https://www.jsonrpc.org/specification
+ * @module
+ */
+import { z } from 'zod';
+export declare const JSONRPC_VERSION = "2.0";
+/** A uniquely identifying id for a request in JSON-RPC. Like MCP, excludes null. */
+export declare const JsonrpcRequestId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+export type JsonrpcRequestId = z.infer<typeof JsonrpcRequestId>;
+/** A JSON-RPC method name. */
+export declare const JsonrpcMethod: z.ZodString;
+export type JsonrpcMethod = z.infer<typeof JsonrpcMethod>;
+/** Request params — loose object to allow additional properties. */
+export declare const JsonrpcRequestParams: z.ZodObject<{}, z.core.$loose>;
+export type JsonrpcRequestParams = z.infer<typeof JsonrpcRequestParams>;
+/** Result — loose object to allow additional properties. */
+export declare const JsonrpcResult: z.ZodObject<{}, z.core.$loose>;
+export type JsonrpcResult = z.infer<typeof JsonrpcResult>;
+/** A request that expects a response. */
+export declare const JsonrpcRequest: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$loose>;
+export type JsonrpcRequest = z.infer<typeof JsonrpcRequest>;
+/** A successful (non-error) response to a request. */
+export declare const JsonrpcResponse: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    result: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$loose>;
+export type JsonrpcResponse = z.infer<typeof JsonrpcResponse>;
+/** Error object within a JSON-RPC error response. */
+export declare const JsonrpcErrorObject: z.ZodObject<{
+    code: z.ZodNumber;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export type JsonrpcErrorObject = z.infer<typeof JsonrpcErrorObject>;
+/** A response that indicates an error occurred. */
+export declare const JsonrpcErrorResponse: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    error: z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type JsonrpcErrorResponse = z.infer<typeof JsonrpcErrorResponse>;
+//# sourceMappingURL=jsonrpc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,iDAAoC,CAAC;AAClE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,8BAA8B;AAC9B,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,gCAAoB,CAAC;AACtD,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,4DAA4D;AAC5D,eAAO,MAAM,aAAa,gCAAoB,CAAC;AAC/C,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,yCAAyC;AACzC,eAAO,MAAM,cAAc;;;;;iBAKzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,sDAAsD;AACtD,eAAO,MAAM,eAAe;;;;iBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB;;;;iBAI7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,mDAAmD;AACnD,eAAO,MAAM,oBAAoB;;;;;;;;iBAI/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/http/jsonrpc.js

@@ -0,0 +1,49 @@
+/**
+ * JSON-RPC 2.0 envelope schemas for the single RPC endpoint dispatcher.
+ *
+ * Minimal subset extracted from zzz's `jsonrpc.ts` — only what the
+ * `create_rpc_endpoint` dispatcher needs to parse incoming requests
+ * and format outgoing responses. Full JSON-RPC schemas (batching,
+ * MCP extensions, notification types) remain in zzz.
+ *
+ * Following MCP, params and result are object-only (no positional arrays).
+ *
+ * @source https://github.com/modelcontextprotocol/typescript-sdk
+ * @see https://www.jsonrpc.org/specification
+ * @module
+ */
+import { z } from 'zod';
+export const JSONRPC_VERSION = '2.0';
+/** A uniquely identifying id for a request in JSON-RPC. Like MCP, excludes null. */
+export const JsonrpcRequestId = z.union([z.string(), z.number()]);
+/** A JSON-RPC method name. */
+export const JsonrpcMethod = z.string();
+/** Request params — loose object to allow additional properties. */
+export const JsonrpcRequestParams = z.looseObject({});
+/** Result — loose object to allow additional properties. */
+export const JsonrpcResult = z.looseObject({});
+/** A request that expects a response. */
+export const JsonrpcRequest = z.looseObject({
+    jsonrpc: z.literal(JSONRPC_VERSION),
+    id: JsonrpcRequestId,
+    method: JsonrpcMethod,
+    params: JsonrpcRequestParams.optional(),
+});
+/** A successful (non-error) response to a request. */
+export const JsonrpcResponse = z.looseObject({
+    jsonrpc: z.literal(JSONRPC_VERSION),
+    id: JsonrpcRequestId,
+    result: JsonrpcResult,
+});
+/** Error object within a JSON-RPC error response. */
+export const JsonrpcErrorObject = z.looseObject({
+    code: z.number(),
+    message: z.string(),
+    data: z.unknown().optional(),
+});
+/** A response that indicates an error occurred. */
+export const JsonrpcErrorResponse = z.looseObject({
+    jsonrpc: z.literal(JSONRPC_VERSION),
+    id: JsonrpcRequestId.nullable(),
+    error: JsonrpcErrorObject,
+});

package/dist/http/jsonrpc_errors.d.ts

@@ -0,0 +1,132 @@
+/**
+ * JSON-RPC error infrastructure for fuz_app routes.
+ *
+ * Provides error types, named constructors, and HTTP status mapping
+ * for the throw/catch error pattern used by `apply_route_specs`.
+ * Extracted from zzz's `jsonrpc_errors.ts` — only core error codes
+ * (5 standard + 8 general application). Domain-specific codes stay
+ * in consumers. `JSONRPC_ERROR_CODES` is extensible — consumers
+ * add their own codes by casting `as JsonrpcErrorCode`.
+ *
+ * Complementary to `error_schemas.ts`: that module is declarative
+ * (Zod schemas for surface introspection), this one is runtime
+ * (throw + catch + map).
+ *
+ * @module
+ */
+/** Branded number type for JSON-RPC error codes. */
+export type JsonrpcErrorCode = number & {
+    readonly __brand: 'JsonrpcErrorCode';
+};
+/** JSON-RPC error response object — code, message, and optional data. */
+export interface JsonrpcErrorJson {
+    code: JsonrpcErrorCode;
+    message: string;
+    data?: unknown;
+}
+/** Names of standard and general application JSON-RPC error codes. */
+export type JsonrpcErrorName = 'parse_error' | 'invalid_request' | 'method_not_found' | 'invalid_params' | 'internal_error' | 'unauthenticated' | 'forbidden' | 'not_found' | 'conflict' | 'validation_error' | 'rate_limited' | 'service_unavailable' | 'timeout';
+/**
+ * Standard JSON-RPC error codes (5) plus general application codes (8).
+ *
+ * Extensible — consumers add domain-specific codes to their own objects
+ * by casting `as JsonrpcErrorCode`. Application codes use the -32000 to
+ * -32099 range reserved by the JSON-RPC spec.
+ */
+export declare const JSONRPC_ERROR_CODES: {
+    /** -32700 */
+    readonly parse_error: JsonrpcErrorCode;
+    /** -32600 */
+    readonly invalid_request: JsonrpcErrorCode;
+    /** -32601 */
+    readonly method_not_found: JsonrpcErrorCode;
+    /** -32602 */
+    readonly invalid_params: JsonrpcErrorCode;
+    /** -32603 */
+    readonly internal_error: JsonrpcErrorCode;
+    /**
+     * Same as HTTP 401 "unauthorized", but correctly named.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#client_error_responses
+     */
+    readonly unauthenticated: JsonrpcErrorCode;
+    /**
+     * Named to match HTTP 403 — avoids confusion with 401 which
+     * is incorrectly named "unauthorized" in HTTP.
+     */
+    readonly forbidden: JsonrpcErrorCode;
+    readonly not_found: JsonrpcErrorCode;
+    readonly conflict: JsonrpcErrorCode;
+    /**
+     * Application-level validation failures (business logic).
+     * Use `invalid_params` (-32602) for schema/parsing failures.
+     */
+    readonly validation_error: JsonrpcErrorCode;
+    readonly rate_limited: JsonrpcErrorCode;
+    readonly service_unavailable: JsonrpcErrorCode;
+    readonly timeout: JsonrpcErrorCode;
+};
+/**
+ * Named constructors for `JsonrpcErrorJson` objects.
+ *
+ * Each function creates a JSON-RPC error response object with the correct
+ * code and a sensible default message. Used by the catch layer in
+ * `apply_route_specs` to build response bodies.
+ */
+export declare const jsonrpc_error_messages: {
+    readonly parse_error: (data?: unknown) => JsonrpcErrorJson;
+    readonly invalid_request: (data?: unknown) => JsonrpcErrorJson;
+    readonly method_not_found: (method?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly invalid_params: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly internal_error: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly unauthenticated: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly forbidden: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly not_found: (resource?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly conflict: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly validation_error: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly rate_limited: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly service_unavailable: (message?: string, data?: unknown) => JsonrpcErrorJson;
+    readonly timeout: (message?: string, data?: unknown) => JsonrpcErrorJson;
+};
+/**
+ * Error class carrying a JSON-RPC error code — thrown by handlers,
+ * caught by `apply_route_specs` and mapped to HTTP status + JSON-RPC error response.
+ *
+ * Named for what it is: an error with a JSON-RPC error code that gets thrown.
+ */
+export declare class ThrownJsonrpcError extends Error {
+    code: JsonrpcErrorCode;
+    data?: unknown;
+    constructor(code: JsonrpcErrorCode, message: string, data?: unknown, options?: ErrorOptions);
+}
+/**
+ * Named constructors for `ThrownJsonrpcError`.
+ *
+ * Usage: `throw jsonrpc_errors.not_found('user')` or `throw jsonrpc_errors.forbidden()`.
+ */
+export declare const jsonrpc_errors: {
+    readonly parse_error: (data?: unknown) => ThrownJsonrpcError;
+    readonly invalid_request: (data?: unknown) => ThrownJsonrpcError;
+    readonly method_not_found: (method?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly invalid_params: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly internal_error: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly unauthenticated: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly forbidden: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly not_found: (resource?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly conflict: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly validation_error: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly rate_limited: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly service_unavailable: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly timeout: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+};
+/**
+ * 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).
+ *
+ * @param code - the JSON-RPC error code
+ * @returns the corresponding HTTP status code
+ */
+export declare const jsonrpc_error_code_to_http_status: (code: JsonrpcErrorCode) => number;
+//# sourceMappingURL=jsonrpc_errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc_errors.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/jsonrpc_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAC,CAAC;AAE/E,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,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,CAAC;AAEb;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;IAE/B,aAAa;0BACU,gBAAgB;IACvC,aAAa;8BACc,gBAAgB;IAC3C,aAAa;+BACe,gBAAgB;IAC5C,aAAa;6BACa,gBAAgB;IAC1C,aAAa;6BACa,gBAAgB;IAG1C;;;;OAIG;8BACwB,gBAAgB;IAC3C;;;OAGG;wBACkB,gBAAgB;wBAChB,gBAAgB;uBACjB,gBAAgB;IACpC;;;OAGG;+BACyB,gBAAgB;2BACpB,gBAAgB;kCACT,gBAAgB;sBAC5B,gBAAgB;CAC2B,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;kCACb,OAAO,KAAG,gBAAgB;sCAMtB,OAAO,KAAG,gBAAgB;yCAMvB,MAAM,SAAS,OAAO,KAAG,gBAAgB;wCAM1C,MAAM,SAAS,OAAO,KAAG,gBAAgB;wCAO1D,MAAM,SACR,OAAO,KACZ,gBAAgB;yCAMQ,MAAM,SAA6B,OAAO,KAAG,gBAAgB;mCAMnE,MAAM,SAAuB,OAAO,KAAG,gBAAgB;oCAMrD,MAAM,SAAS,OAAO,KAAG,gBAAgB;kCAM5C,MAAM,SAAsB,OAAO,KAAG,gBAAgB;0CAM9C,MAAM,SAA8B,OAAO,KAAG,gBAAgB;sCAMlE,MAAM,SAA0B,OAAO,KAAG,gBAAgB;6CAOxE,MAAM,SACR,OAAO,KACZ,gBAAgB;iCAMA,MAAM,SAAqB,OAAO,KAAG,gBAAgB;CAKe,CAAC;AAEzF;;;;;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;gFAAlB,kBAAkB;+EAAlB,kBAAkB;+EAAlB,kBAAkB;gFAAlB,kBAAkB;0EAAlB,kBAAkB;2EAAlB,kBAAkB;yEAAlB,kBAAkB;iFAAlB,kBAAkB;6EAAlB,kBAAkB;oFAAlB,kBAAkB;wEAAlB,kBAAkB;CAyBqC,CAAC;AAoB3F;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,GAAI,MAAM,gBAAgB,KAAG,MACjB,CAAC"}