@fuzdev/fuz_app 0.30.0 → 0.32.0

package/dist/actions/action_rpc.d.ts

@@ -11,6 +11,7 @@
  *
  * @module
  */
+import { z } from 'zod';
 import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { RequestResponseActionSpec } from './action_spec.js';
 import { type RouteSpec } from '../http/route_spec.js';
@@ -35,6 +36,15 @@ export interface ActionContext {
     background_db: Db;
     /** Fire-and-forget side effects — push here for post-response flushing. */
     pending_effects: Array<Promise<void>>;
+    /**
+     * Resolved client IP from the trusted-proxy middleware — `'unknown'` if the
+     * middleware wasn't in the stack (e.g. WS dispatch) or couldn't resolve.
+     * Thread into `audit_log_fire_and_forget` as `ip: ctx.client_ip` for every
+     * user-initiated action so RPC audit rows match the REST convention. Pass
+     * `null` only for rows written outside a request (e.g. the
+     * `permit_offer_expire` cleanup sweep in `auth/cleanup.ts`).
+     */
+    client_ip: string;
     /** Logger instance. */
     log: Logger;
     /**
@@ -71,6 +81,25 @@ export interface RpcAction {
     spec: RequestResponseActionSpec;
     handler: ActionHandler;
 }
+/**
+ * Pair a spec with a handler while preserving per-method input/output types.
+ *
+ * Constructing `{spec, handler}` literals widens `handler` to
+ * `ActionHandler<any, any>`, so spec/handler drift (renamed Zod schema,
+ * output field removal, input shape change) slips past the typechecker.
+ * `rpc_action(spec, handler)` binds the handler signature to
+ * `(input: z.infer<spec.input>, ctx) => z.infer<spec.output>` via the
+ * generic spec parameter — drift surfaces at the call site.
+ *
+ * Fits fuz_app's factory-closure pattern (handlers close over
+ * `grantable_roles`, `app_settings` ref, `notification_sender`, etc.).
+ * zzz uses a different shape — a codegen-keyed `Record<Method, Handler>`
+ * map typed via generated `ActionInputs`/`ActionOutputs` — which works when
+ * handlers are pure (no closure state) and specs are codegen-enumerated.
+ * fuz_app's admin + permit-offer actions have neither, so per-pair typing
+ * at the registration site is the right fit.
+ */
+export declare const rpc_action: <TSpec extends RequestResponseActionSpec>(spec: TSpec, handler: ActionHandler<z.infer<TSpec["input"]>, z.infer<TSpec["output"]>>) => RpcAction;
 /** Options for `create_rpc_endpoint`. */
 export interface CreateRpcEndpointOptions {
     /** Mount path for the endpoint (e.g., `/api/rpc`). */

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

@@ -1 +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;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAO5B;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,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;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;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;AAkDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAqPtF,CAAC"}
+{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,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;AAExE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAW5B;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,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;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;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;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvE,SAGD,CAAC;AAEH,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;AA4DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAwPtF,CAAC"}

package/dist/actions/action_rpc.js

@@ -14,11 +14,35 @@
 import { z } from 'zod';
 import { DEV } from 'esm-env';
 import {} from '../http/route_spec.js';
+import { get_client_ip } from '../http/proxy.js';
 import { get_request_context, has_role } from '../auth/request_context.js';
 import { CREDENTIAL_TYPE_KEY } from '../hono_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, } from '../http/jsonrpc_errors.js';
+import { ERROR_INSUFFICIENT_PERMISSIONS, ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, } from '../http/error_schemas.js';
+/**
+ * Pair a spec with a handler while preserving per-method input/output types.
+ *
+ * Constructing `{spec, handler}` literals widens `handler` to
+ * `ActionHandler<any, any>`, so spec/handler drift (renamed Zod schema,
+ * output field removal, input shape change) slips past the typechecker.
+ * `rpc_action(spec, handler)` binds the handler signature to
+ * `(input: z.infer<spec.input>, ctx) => z.infer<spec.output>` via the
+ * generic spec parameter — drift surfaces at the call site.
+ *
+ * Fits fuz_app's factory-closure pattern (handlers close over
+ * `grantable_roles`, `app_settings` ref, `notification_sender`, etc.).
+ * zzz uses a different shape — a codegen-keyed `Record<Method, Handler>`
+ * map typed via generated `ActionInputs`/`ActionOutputs` — which works when
+ * handlers are pure (no closure state) and specs are codegen-enumerated.
+ * fuz_app's admin + permit-offer actions have neither, so per-pair typing
+ * at the registration site is the right fit.
+ */
+export const rpc_action = (spec, handler) => ({
+    spec,
+    handler: handler,
+});
 /**
  * Format a JSON-RPC error response.
  *
@@ -49,15 +73,25 @@ const check_action_auth = (auth, request_context, credential_type) => {
     if (auth === 'keeper') {
         // keeper requires daemon_token credential type AND the keeper role.
         // API tokens and session cookies cannot access keeper actions even
-        // if the account has the keeper permit.
+        // if the account has the keeper permit. Attach the credential type
+        // under `data` so clients can distinguish "wrong credential shape"
+        // from "missing keeper role" — mirrors REST 403 semantics.
         if (credential_type !== 'daemon_token' || !has_role(request_context, 'keeper')) {
-            return jsonrpc_error_messages.forbidden();
+            return jsonrpc_error_messages.forbidden('forbidden', {
+                reason: ERROR_KEEPER_REQUIRES_DAEMON_TOKEN,
+                credential_type,
+            });
         }
         return null;
     }
-    // role check
+    // role check — attach `required_role` under `data.required_role` so
+    // clients can render targeted copy (matches the former REST `PermissionError`
+    // shape that exposed `required_role` as a top-level field).
     if (!has_role(request_context, auth.role)) {
-        return jsonrpc_error_messages.forbidden(`requires role: ${auth.role}`);
+        return jsonrpc_error_messages.forbidden(`requires role: ${auth.role}`, {
+            reason: ERROR_INSUFFICIENT_PERMISSIONS,
+            required_role: auth.role,
+        });
     }
     return null;
 };
@@ -145,6 +179,7 @@ export const create_rpc_endpoint = (options) => {
             }
         };
         const signal = c.req.raw.signal;
+        const client_ip = get_client_ip(c);
         const execute = async (db) => {
             const action_context = {
                 auth: request_context,
@@ -152,16 +187,17 @@ export const create_rpc_endpoint = (options) => {
                 db,
                 background_db: route.background_db,
                 pending_effects: route.pending_effects,
+                client_ip,
                 log,
                 notify,
                 signal,
             };
             const output = await action.handler(parse_result.data, action_context);
-            // DEV-only output validation
+            // DEV-only output validation — logs an error on mismatch, does not throw.
             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);
+                    log.error(`RPC output schema mismatch: ${method_name}`, output_result.error.issues);
                 }
             }
             return c.json({ jsonrpc: JSONRPC_VERSION, id, result: output });

package/dist/actions/action_types.d.ts

@@ -54,8 +54,8 @@ export interface BaseHandlerContext {
 export type WsActionHandler<TCtx extends BaseHandlerContext = BaseHandlerContext> = (input: unknown, ctx: TCtx) => unknown;
 /**
  * A spec paired with its optional handler — the composable unit passed to
- * {@link register_action_ws} and {@link create_rpc_client}. The server uses
- * both fields; the client reads only {@link spec} (the {@link handler} is
+ * `register_action_ws` and `create_rpc_client`. The server uses
+ * both fields; the client reads only `spec` (the `handler` is
  * ignored, harmless). Shared fuz_app primitives (e.g. `heartbeat_action`)
  * export a complete tuple so consumers spread them into both sides'
  * `actions` array without inventing per-repo ping plumbing.

package/dist/actions/cancel.d.ts

@@ -4,7 +4,7 @@
  *
  * Semantics: the client sends `{jsonrpc, method: 'cancel', params:
  * {request_id}}` to abort an in-flight request on the same socket.
- * {@link register_action_ws} intercepts this notification and aborts the
+ * `register_action_ws` intercepts this notification and aborts the
  * matching pending request's `ctx.signal`. Unknown ids are no-ops by design —
  * races between response arrival and cancel delivery are safe without extra
  * coordination.
@@ -12,8 +12,8 @@
  * The handler field is an empty stub: cancel semantics are dispatcher-owned
  * (the dispatcher has the `{request_id → AbortController}` map, not the
  * handler). The handler exists for symmetry with other composable primitives
- * like {@link heartbeat_action}; the dispatcher never calls it. Consumers
- * spread {@link cancel_action} into their server's `actions` array so
+ * like `heartbeat_action`; the dispatcher never calls it. Consumers
+ * spread `cancel_action` into their server's `actions` array so
  * `spec_by_method` knows about it (enabling input validation on incoming
  * cancels) and so `create_rpc_client` codegen produces `app.api.cancel()`
  * when desired — though `FrontendWebsocketClient.request({signal})` sends
@@ -29,11 +29,9 @@
  */
 import { z } from 'zod';
 import type { Action } from './action_types.js';
-/** Method name on the wire — shared across every fuz_app consumer. */
-export declare const CANCEL_METHOD = "cancel";
 /**
- * Params for a {@link CANCEL_METHOD} notification. `request_id` is the id of
- * the pending request to abort. Must match the id of a request sent on the
+ * Params for the `cancel` notification. `request_id` is the id of the
+ * pending request to abort. Must match the id of a request sent on the
  * same socket; cancels from other sockets (or for unknown ids) are ignored.
  */
 export declare const CancelNotificationParams: z.ZodObject<{
@@ -50,19 +48,20 @@ export type CancelNotificationParams = z.infer<typeof CancelNotificationParams>;
  */
 export declare const cancel_action_spec: {
     method: string;
-    initiator: "both" | "frontend" | "backend";
-    input: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    description: string;
     kind: "remote_notification";
+    initiator: "frontend";
     auth: null;
     side_effects: true;
+    input: z.ZodObject<{
+        request_id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strict>;
     output: z.ZodVoid;
     async: true;
-    streams?: string | undefined;
+    description: string;
 };
 /**
- * Placeholder handler — cancel semantics are owned by {@link register_action_ws},
- * not invoked per-handler. Exported for symmetry with the {@link Action}
+ * Placeholder handler — cancel semantics are owned by `register_action_ws`,
+ * not invoked per-handler. Exported for symmetry with the `Action`
  * tuple shape; the dispatcher short-circuits cancel notifications before any
  * handler lookup happens.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"cancel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;kBAEnC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;CAW7B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAAU,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAG3B,CAAC"}
+{"version":3,"file":"cancel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;kBAEnC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CAWS,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAAU,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAG3B,CAAC"}

package/dist/actions/cancel.js

@@ -4,7 +4,7 @@
  *
  * Semantics: the client sends `{jsonrpc, method: 'cancel', params:
  * {request_id}}` to abort an in-flight request on the same socket.
- * {@link register_action_ws} intercepts this notification and aborts the
+ * `register_action_ws` intercepts this notification and aborts the
  * matching pending request's `ctx.signal`. Unknown ids are no-ops by design —
  * races between response arrival and cancel delivery are safe without extra
  * coordination.
@@ -12,8 +12,8 @@
  * The handler field is an empty stub: cancel semantics are dispatcher-owned
  * (the dispatcher has the `{request_id → AbortController}` map, not the
  * handler). The handler exists for symmetry with other composable primitives
- * like {@link heartbeat_action}; the dispatcher never calls it. Consumers
- * spread {@link cancel_action} into their server's `actions` array so
+ * like `heartbeat_action`; the dispatcher never calls it. Consumers
+ * spread `cancel_action` into their server's `actions` array so
  * `spec_by_method` knows about it (enabling input validation on incoming
  * cancels) and so `create_rpc_client` codegen produces `app.api.cancel()`
  * when desired — though `FrontendWebsocketClient.request({signal})` sends
@@ -29,12 +29,9 @@
  */
 import { z } from 'zod';
 import { JsonrpcRequestId } from '../http/jsonrpc.js';
-import { RemoteNotificationActionSpec } from './action_spec.js';
-/** Method name on the wire — shared across every fuz_app consumer. */
-export const CANCEL_METHOD = 'cancel';
 /**
- * Params for a {@link CANCEL_METHOD} notification. `request_id` is the id of
- * the pending request to abort. Must match the id of a request sent on the
+ * Params for the `cancel` notification. `request_id` is the id of the
+ * pending request to abort. Must match the id of a request sent on the
  * same socket; cancels from other sockets (or for unknown ids) are ignored.
  */
 export const CancelNotificationParams = z.strictObject({
@@ -48,8 +45,8 @@ export const CancelNotificationParams = z.strictObject({
  * ownership naturally: a different socket's cancel for the same id misses
  * in its own map.
  */
-export const cancel_action_spec = RemoteNotificationActionSpec.parse({
-    method: CANCEL_METHOD,
+export const cancel_action_spec = {
+    method: 'cancel',
     kind: 'remote_notification',
     initiator: 'frontend',
     auth: null,
@@ -58,10 +55,10 @@ export const cancel_action_spec = RemoteNotificationActionSpec.parse({
     output: z.void(),
     async: true,
     description: 'Client-initiated cancellation of an in-flight request by id. Dispatcher-handled: aborts the ctx.signal of the matching pending request on the same socket. Unknown or completed ids no-op.',
-});
+};
 /**
- * Placeholder handler — cancel semantics are owned by {@link register_action_ws},
- * not invoked per-handler. Exported for symmetry with the {@link Action}
+ * Placeholder handler — cancel semantics are owned by `register_action_ws`,
+ * not invoked per-handler. Exported for symmetry with the `Action`
  * tuple shape; the dispatcher short-circuits cancel notifications before any
  * handler lookup happens.
  */

package/dist/actions/heartbeat.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared heartbeat action — the first composable fuz_app primitive carrying
  * both a spec and a handler in one tuple. Consumers spread
- * {@link heartbeat_action} into both the server's and the client's `actions`
+ * `heartbeat_action` into both the server's and the client's `actions`
  * array so disconnect detection works identically across every repo without
  * per-consumer ping plumbing.
  *
@@ -12,15 +12,13 @@
  * alive without any handler-level state.
  *
  * Nullary input/output today. `{client_ts, server_ts}` fields can be added
- * later if clock-skew telemetry ever matters — the {@link Action} container
+ * later if clock-skew telemetry ever matters — the `Action` container
  * is open for additions without churning consumer call sites.
  *
  * @module
  */
 import { z } from 'zod';
 import type { Action } from './action_types.js';
-/** Method name on the wire — shared across every fuz_app consumer. */
-export declare const HEARTBEAT_METHOD = "heartbeat";
 /**
  * `ActionSpec` for the shared heartbeat. `authenticated` auth — upgrade-time
  * auth has already admitted the socket; heartbeats don't need role gating.
@@ -28,17 +26,14 @@ export declare const HEARTBEAT_METHOD = "heartbeat";
  */
 export declare const heartbeat_action_spec: {
     method: string;
-    initiator: "both" | "frontend" | "backend";
-    side_effects: boolean;
-    input: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    output: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    description: string;
     kind: "request_response";
-    auth: "authenticated" | "keeper" | "public" | {
-        role: string;
-    };
+    initiator: "frontend";
+    auth: "authenticated";
+    side_effects: false;
+    input: z.ZodObject<{}, z.core.$strict>;
+    output: z.ZodObject<{}, z.core.$strict>;
     async: true;
-    streams?: string | undefined;
+    description: string;
 };
 /** Handler — nullary echo. Stateless, suitable for high-frequency pings. */
 export declare const heartbeat_handler: () => Record<string, never>;

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

@@ -1 +1 @@
-{"version":3,"file":"heartbeat.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAUhC,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAG9B,CAAC"}
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;CAUG,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAG9B,CAAC"}

package/dist/actions/heartbeat.js

@@ -1,7 +1,7 @@
 /**
  * Shared heartbeat action — the first composable fuz_app primitive carrying
  * both a spec and a handler in one tuple. Consumers spread
- * {@link heartbeat_action} into both the server's and the client's `actions`
+ * `heartbeat_action` into both the server's and the client's `actions`
  * array so disconnect detection works identically across every repo without
  * per-consumer ping plumbing.
  *
@@ -12,22 +12,19 @@
  * alive without any handler-level state.
  *
  * Nullary input/output today. `{client_ts, server_ts}` fields can be added
- * later if clock-skew telemetry ever matters — the {@link Action} container
+ * later if clock-skew telemetry ever matters — the `Action` container
  * is open for additions without churning consumer call sites.
  *
  * @module
  */
 import { z } from 'zod';
-import { RequestResponseActionSpec } from './action_spec.js';
-/** Method name on the wire — shared across every fuz_app consumer. */
-export const HEARTBEAT_METHOD = 'heartbeat';
 /**
  * `ActionSpec` for the shared heartbeat. `authenticated` auth — upgrade-time
  * auth has already admitted the socket; heartbeats don't need role gating.
  * `side_effects: false` keeps it orthogonal to state changes.
  */
-export const heartbeat_action_spec = RequestResponseActionSpec.parse({
-    method: HEARTBEAT_METHOD,
+export const heartbeat_action_spec = {
+    method: 'heartbeat',
     kind: 'request_response',
     initiator: 'frontend',
     auth: 'authenticated',
@@ -36,7 +33,7 @@ export const heartbeat_action_spec = RequestResponseActionSpec.parse({
     output: z.strictObject({}),
     async: true,
     description: 'Shared activity ping — keeps the socket alive and exercises the dispatch path.',
-});
+};
 /** Handler — nullary echo. Stateless, suitable for high-frequency pings. */
 export const heartbeat_handler = () => ({});
 /**

package/dist/actions/register_action_ws.d.ts

@@ -79,8 +79,8 @@ export interface SocketCloseContext {
 export interface ServerHeartbeatOptions {
     /**
      * Receive-silence (ms) past which the server closes the socket with
-     * {@link WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT}. Any incoming message resets
-     * the counter — chatty clients never trip it. First {@link timeout}
+     * `WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT`. Any incoming message resets
+     * the counter — chatty clients never trip it. First `timeout`
      * window after socket open is exempt (cold-start grace).
      */
     timeout?: number;
@@ -97,7 +97,7 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
      * The actions registered on this endpoint — each carries a spec (drives
      * method lookup, per-action auth, input/output validation) and an
      * optional handler (omit for client-only specs like inbound
-     * notifications). Include the shared {@link heartbeat_action} here to
+     * notifications). Include the shared `heartbeat_action` here to
      * complete the disconnect-detection pairing with the frontend client.
      */
     actions: ReadonlyArray<Action<TCtx>>;

package/dist/actions/register_action_ws.js

@@ -39,7 +39,7 @@ import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_erro
 import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_KEY } from '../hono_context.js';
 import {} from './action_types.js';
-import { CANCEL_METHOD, CancelNotificationParams } from './cancel.js';
+import { cancel_action_spec, CancelNotificationParams } from './cancel.js';
 import { WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT } from './transports.js';
 import { BackendWebsocketTransport } from './transports_ws_backend.js';
 /** Default inactivity window before the server closes a silent socket. */
@@ -206,7 +206,7 @@ export const register_action_ws = (options) => {
                 // are not a feature yet).
                 if (!is_jsonrpc_request(json)) {
                     if (typeof json === 'object' && json !== null && 'method' in json && !('id' in json)) {
-                        if (json.method === CANCEL_METHOD) {
+                        if (json.method === cancel_action_spec.method) {
                             const parsed = CancelNotificationParams.safeParse(json.params);
                             if (!parsed.success) {
                                 log.debug('cancel: invalid params, ignoring', parsed.error.issues);

package/dist/actions/register_ws_endpoint.d.ts

@@ -10,7 +10,7 @@
  * 3. Optional `require_role(required_role)` — for endpoints gated to a
  *    specific role.
  *
- * Then delegates to {@link register_action_ws} for per-message JSON-RPC
+ * Then delegates to `register_action_ws` for per-message JSON-RPC
  * dispatch.
  *
  * @module
@@ -18,7 +18,7 @@
 import type { RoleName } from '../auth/role_schema.js';
 import { type RegisterActionWsOptions, type RegisterActionWsResult } from './register_action_ws.js';
 import type { BaseHandlerContext } from './action_types.js';
-/** Options for {@link register_ws_endpoint}. */
+/** Options for `register_ws_endpoint`. */
 export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> extends RegisterActionWsOptions<TCtx> {
     /**
      * Origin allowlist regexes — typically parsed from the `ALLOWED_ORIGINS`
@@ -38,8 +38,8 @@ export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> exte
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check
  * + auth + optional role) and JSON-RPC dispatch.
  *
- * Returns the {@link BackendWebsocketTransport} (supplied or freshly
- * created), same as {@link register_action_ws} — retain it to wire
+ * Returns the `BackendWebsocketTransport` (supplied or freshly
+ * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
  */
 export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;

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

@@ -1 +1 @@
-{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,gDAAgD;AAChD,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -10,7 +10,7 @@
  * 3. Optional `require_role(required_role)` — for endpoints gated to a
  *    specific role.
  *
- * Then delegates to {@link register_action_ws} for per-message JSON-RPC
+ * Then delegates to `register_action_ws` for per-message JSON-RPC
  * dispatch.
  *
  * @module
@@ -23,8 +23,8 @@ import { register_action_ws, } from './register_action_ws.js';
  * Mount a WebSocket endpoint with the standard upgrade stack (origin check
  * + auth + optional role) and JSON-RPC dispatch.
  *
- * Returns the {@link BackendWebsocketTransport} (supplied or freshly
- * created), same as {@link register_action_ws} — retain it to wire
+ * Returns the `BackendWebsocketTransport` (supplied or freshly
+ * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
  */
 export const register_ws_endpoint = (options) => {

package/dist/actions/rpc_client.d.ts

@@ -65,4 +65,33 @@ export declare const create_rpc_client: (options: CreateRpcClientOptions) => Rec
  */
 export interface RpcClientCallOptions extends ActionPeerSendOptions {
 }
+/**
+ * `method, input -> unwrapped output` signature for adapter wiring.
+ *
+ * The typed `create_rpc_client` Proxy returns `Result<T, JsonrpcErrorObject>`
+ * on every call. UI adapters (e.g. `admin_rpc_adapters.ts`) want a
+ * throw-on-error shape so form components can match on `error.data.reason`
+ * via catch blocks. `create_throwing_rpc_call` bridges the two.
+ */
+export type ThrowingRpcCall = <TOutput = unknown>(method: string, input?: unknown) => Promise<TOutput>;
+/**
+ * Wrap a typed RPC client so every call returns its unwrapped value or throws.
+ *
+ * On `{ok: false}`, throws an `Error` with the JSON-RPC error object's
+ * `{code, message, data}` spread onto it — so catch blocks that inspect
+ * `err.data?.reason` continue to work. On unknown method, throws a clear
+ * "rpc method not found" error instead of the cryptic `undefined is not a
+ * function` that would otherwise surface.
+ *
+ * Invariant upheld by `create_rpc_client`: every `{ok: false}` return
+ * carries a well-formed `JsonrpcErrorObject` with `code` + `message`.
+ * Callers must still use optional chaining on `err.data` because the
+ * JSON-RPC `data` field is spec-level optional — a handler that throws
+ * `jsonrpc_errors.forbidden()` without a `data` argument produces
+ * `err.data === undefined`.
+ *
+ * @param api - typed RPC client from `create_rpc_client` (or any Proxy-like
+ *   object mapping method names to `(input) => Promise<Result<T, error>>`)
+ */
+export declare const create_throwing_rpc_call: (api: Record<string, ((input?: any) => Promise<any>) | undefined>) => ThrowingRpcCall;
 //# sourceMappingURL=rpc_client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC;AA2DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG"}
+{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC;AA2DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG;AAgItE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,GAAG,OAAO,EAC/C,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GACpC,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,KAC9D,eAUF,CAAC"}

package/dist/actions/rpc_client.js

@@ -168,3 +168,34 @@ const create_remote_notification_method = (peer, environment, spec, actions, tra
         return extract_action_result(event);
     };
 };
+/**
+ * Wrap a typed RPC client so every call returns its unwrapped value or throws.
+ *
+ * On `{ok: false}`, throws an `Error` with the JSON-RPC error object's
+ * `{code, message, data}` spread onto it — so catch blocks that inspect
+ * `err.data?.reason` continue to work. On unknown method, throws a clear
+ * "rpc method not found" error instead of the cryptic `undefined is not a
+ * function` that would otherwise surface.
+ *
+ * Invariant upheld by `create_rpc_client`: every `{ok: false}` return
+ * carries a well-formed `JsonrpcErrorObject` with `code` + `message`.
+ * Callers must still use optional chaining on `err.data` because the
+ * JSON-RPC `data` field is spec-level optional — a handler that throws
+ * `jsonrpc_errors.forbidden()` without a `data` argument produces
+ * `err.data === undefined`.
+ *
+ * @param api - typed RPC client from `create_rpc_client` (or any Proxy-like
+ *   object mapping method names to `(input) => Promise<Result<T, error>>`)
+ */
+export const create_throwing_rpc_call = (api) => {
+    return async (method, input) => {
+        const fn = api[method];
+        if (!fn)
+            throw new Error(`rpc method not found: ${method}`);
+        const result = await fn(input);
+        if (!result.ok) {
+            throw Object.assign(new Error(result.error?.message ?? 'rpc error'), result.error);
+        }
+        return result.value;
+    };
+};