@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/actions/action_spec.js

@@ -12,20 +12,24 @@
  */
 import { z } from 'zod';
 import { RateLimitKey } from '../http/error_schemas.js';
+import { RouteAuth } from '../http/auth_shape.js';
 export const ActionKind = z.enum(['request_response', 'remote_notification', 'local_call']);
 export const ActionInitiator = z.enum(['frontend', 'backend', 'both']);
-export const ActionAuth = z.union([
-    z.literal('public'),
-    z.literal('authenticated'),
-    z.literal('keeper'),
-    z.strictObject({ role: z.string() }),
-]);
 export const ActionSideEffects = z.boolean();
 export const ActionSpec = z.strictObject({
     method: z.string(),
     kind: ActionKind,
     initiator: ActionInitiator,
-    auth: ActionAuth.nullable(),
+    /**
+     * The four-axis auth shape (canonical schema in `http/auth_shape.ts`).
+     * `null` for `remote_notification` and `local_call` — those don't
+     * dispatch through the request/response auth gate.
+     *
+     * See `../http/auth_shape.ts` for the design rationale (orthogonal
+     * authentication / account-resolution / actor-resolution / role-and-
+     * credential authorization axes).
+     */
+    auth: RouteAuth.nullable(),
     side_effects: ActionSideEffects,
     input: z.custom((v) => v instanceof z.ZodType),
     output: z.custom((v) => v instanceof z.ZodType),
@@ -44,7 +48,7 @@ export const ActionSpec = z.strictObject({
      * failure. Declarative metadata mirroring the `streams` precedent —
      * codegen, UI form-state matching, and docs read it off the spec instead
      * of scanning handler implementations. Reuses the same `as const` string
-     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * constants the handler throws (e.g. `ERROR_ROLE_GRANT_OFFER_*`) so call sites can
      * import either side. Optional — actions that surface only standard
      * transport errors leave it unset.
      */
@@ -54,8 +58,9 @@ export const ActionSpec = z.strictObject({
      * actions without it skip the rate-limit hook entirely.
      *
      * - `'ip'` — keyed on the resolved client IP (`get_client_ip(c)`).
-     * - `'account'` — keyed on the post-auth actor id (`request_context.actor.id`).
-     *   Registration-time error if paired with `auth: 'public'` (no actor).
+     * - `'account'` — keyed on the post-auth account id (`request_context.account.id`).
+     *   Registration-time error if paired with `auth.account !== 'required'`
+     *   (no account to key on).
      * - `'both'` — both checks run; either can block.
      *
      * Throttle-requests semantics — every invocation records, regardless of
@@ -72,7 +77,7 @@ export const ActionSpec = z.strictObject({
 });
 export const RequestResponseActionSpec = ActionSpec.extend({
     kind: z.literal('request_response').default('request_response'),
-    auth: ActionAuth,
+    auth: RouteAuth,
     async: z.literal(true).default(true),
 });
 export const RemoteNotificationActionSpec = ActionSpec.extend({

package/dist/actions/action_types.d.ts

@@ -1,72 +1,40 @@
 /**
- * Shared type surface for the action system — context, handler, composable Action tuple.
+ * Shared type surface for the action system — `Action` (the composable
+ * `{spec, handler?}` tuple) and re-exports of the canonical `ActionContext`
+ * + `ActionHandler` shapes.
  *
- * These types sit above `actions/action_spec.ts` (pure Zod schemas) and below the
- * dispatchers (`actions/register_action_ws.ts`, `actions/action_rpc.ts`). Extracted so the
- * shared protocol actions (e.g. `heartbeat_action`) can name them without
- * pulling in server-only modules.
+ * Sits above `actions/action_spec.ts` (pure Zod schemas) and below the
+ * dispatchers (`actions/register_action_ws.ts`, `actions/action_rpc.ts`,
+ * `actions/perform_action.ts`). Extracted so the shared protocol actions
+ * (e.g. `heartbeat_action`) can name them without pulling in server-only
+ * modules.
+ *
+ * HTTP RPC and WebSocket dispatchers both call into `perform_action`,
+ * and both pass the same `ActionContext` to the handler. Consumers
+ * inject domain deps via factory closures the same way HTTP RPC
+ * factories do (see `auth/standard_rpc_actions.ts`).
  *
  * @module
  */
-import type { Uuid } from '@fuzdev/fuz_util/id.js';
-import type { JsonrpcRequestId } from '../http/jsonrpc.js';
 import type { ActionSpecUnion } from './action_spec.js';
-/**
- * Minimum per-request context every server-side WS handler receives.
- *
- * Consumers extend this with domain-specific fields via the dispatcher's
- * `extend_context` option. Mirrors the HTTP-side `ActionContext` and Rust's
- * `Ctx<'a>` shape (`request_id` + `NotifyFn` + `CancellationToken`).
- */
-export interface BaseHandlerContext {
-    /** JSON-RPC envelope request id — echoed back on the response. */
-    request_id: JsonrpcRequestId;
-    /**
-     * Stable per-socket connection id assigned by
-     * `BackendWebsocketTransport.add_connection` — same reference across every
-     * message on this socket, also passed to `on_socket_open` /
-     * `on_socket_close`. Consumers key per-connection domain state on this
-     * directly instead of trying to derive it from signals (which are
-     * per-message composites of `AbortSignal.any([socket, request])`).
-     */
-    connection_id: Uuid;
-    /**
-     * Send a request-scoped JSON-RPC notification to the originating socket.
-     * Not a broadcast — the message only reaches the client whose request
-     * triggered this handler.
-     */
-    notify: (method: string, params: unknown) => void;
-    /**
-     * Fires on socket close OR on a client-initiated `cancel` notification
-     * matching this request's id. Streaming handlers poll for early
-     * termination; per-message composite (`AbortSignal.any([socket, request])`)
-     * — not stable across messages.
-     */
-    signal: AbortSignal;
-}
-/**
- * Handler signature — receives validated input and per-request context.
- *
- * Named to disambiguate from `actions/action_rpc.ts`'s `ActionHandler`
- * (HTTP-side, `ActionContext` + two generic slots). The WS variant is
- * single-slotted on the context and returns `unknown`.
- */
-export type WsActionHandler<TCtx extends BaseHandlerContext = BaseHandlerContext> = (input: unknown, ctx: TCtx) => unknown;
+import type { ActionHandler } from './action_rpc.js';
 /**
  * A spec paired with its optional handler — the composable unit passed to
- * `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.
+ * `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`
+ * arrays without inventing per-repo ping plumbing.
  *
- * Left open for future fields (`rate_limit`, ACL, middleware hooks) so
- * additions attach to the action itself instead of scattering across
- * parallel arrays.
+ * Polymorphic on `kind`: `request_response` specs require a handler for
+ * dispatch; `remote_notification` specs may declare a stub handler for
+ * symmetry but are dispatcher-handled (e.g. `cancel`); `local_call` specs
+ * never reach a network dispatcher. The WS dispatcher only invokes
+ * handlers on `request_response` actions; everything else is registry-only.
  */
-export interface Action<TCtx extends BaseHandlerContext = BaseHandlerContext> {
-    spec: ActionSpecUnion;
-    /** Server-side handler. Ignored by the client. Omit for client-only specs. */
-    handler?: WsActionHandler<TCtx>;
+export interface Action<TSpec extends ActionSpecUnion = ActionSpecUnion> {
+    spec: TSpec;
+    /** Server-side handler — invoked by dispatchers on `request_response` actions. Ignored for client-only specs and dispatcher-handled notifications. */
+    handler?: ActionHandler;
 }
 //# sourceMappingURL=action_types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;;;;OAOG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,IAAI,CACnF,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB;IAC3E,IAAI,EAAE,eAAe,CAAC;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;CAChC"}
+{"version":3,"file":"action_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,MAAM,CAAC,KAAK,SAAS,eAAe,GAAG,eAAe;IACtE,IAAI,EAAE,KAAK,CAAC;IACZ,sJAAsJ;IACtJ,OAAO,CAAC,EAAE,aAAa,CAAC;CACxB"}

package/dist/actions/action_types.js

@@ -1,10 +1,18 @@
 /**
- * Shared type surface for the action system — context, handler, composable Action tuple.
+ * Shared type surface for the action system — `Action` (the composable
+ * `{spec, handler?}` tuple) and re-exports of the canonical `ActionContext`
+ * + `ActionHandler` shapes.
  *
- * These types sit above `actions/action_spec.ts` (pure Zod schemas) and below the
- * dispatchers (`actions/register_action_ws.ts`, `actions/action_rpc.ts`). Extracted so the
- * shared protocol actions (e.g. `heartbeat_action`) can name them without
- * pulling in server-only modules.
+ * Sits above `actions/action_spec.ts` (pure Zod schemas) and below the
+ * dispatchers (`actions/register_action_ws.ts`, `actions/action_rpc.ts`,
+ * `actions/perform_action.ts`). Extracted so the shared protocol actions
+ * (e.g. `heartbeat_action`) can name them without pulling in server-only
+ * modules.
+ *
+ * HTTP RPC and WebSocket dispatchers both call into `perform_action`,
+ * and both pass the same `ActionContext` to the handler. Consumers
+ * inject domain deps via factory closures the same way HTTP RPC
+ * factories do (see `auth/standard_rpc_actions.ts`).
  *
  * @module
  */

package/dist/actions/broadcast_api.d.ts

@@ -9,11 +9,11 @@
  * Counterpart to `register_action_ws`: that handles request-scoped dispatch
  * (frontend-initiated), this handles broadcast (backend-initiated). Together
  * they cover the two primitives fuz_app consumers share. Request-scoped
- * streaming (`completion_progress`, `tx_apply` events) stays on
+ * streaming (`completion_progress`, `zap_apply` events) stays on
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
  * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
- * drifting across zzz, tx, and undying.
+ * drifting across zzz, zap, and undying.
  *
  * @module
  */

package/dist/actions/broadcast_api.js

@@ -9,11 +9,11 @@
  * Counterpart to `register_action_ws`: that handles request-scoped dispatch
  * (frontend-initiated), this handles broadcast (backend-initiated). Together
  * they cover the two primitives fuz_app consumers share. Request-scoped
- * streaming (`completion_progress`, `tx_apply` events) stays on
+ * streaming (`completion_progress`, `zap_apply` events) stays on
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
  * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
- * drifting across zzz, tx, and undying.
+ * drifting across zzz, zap, and undying.
  *
  * @module
  */

package/dist/actions/compile_action_registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared registration loop for action-dispatcher endpoints.
+ *
+ * `create_rpc_endpoint` (HTTP RPC) and `register_action_ws` (WebSocket)
+ * both build a `Map<method, RpcAction>` from a list of action specs and
+ * gate the build on the same registry-time invariants:
+ *
+ * 1. **Auth-shape biconditional** — per `assert_route_auth_acting_biconditional`
+ *    in `http/auth_shape.ts`: `auth.actor !== 'none' ⟺ input declares
+ *    acting?: ActingActor`. Fires for every spec with non-null auth.
+ * 2. **Rate-limit / account axis** — `rate_limit: 'account' | 'both'`
+ *    requires `auth.account === 'required'`; without an account on the
+ *    request there is no key for the per-account bucket.
+ * 3. **JSON-RPC §4.2 wire validity** — `request_response` specs whose
+ *    handler will reach the dispatch map must not use `z.null()` for
+ *    input (the wire format forbids `"params": null`; use `z.void()`
+ *    for parameterless methods).
+ * 4. **Duplicate method names** — JSON-RPC keys on `method`, so every
+ *    spec in the array must declare a unique `method` regardless of
+ *    kind / handler presence.
+ *
+ * Pre-consolidation each dispatcher inlined these checks; the comment
+ * in `register_action_ws.ts` literally said "mirrors the HTTP RPC
+ * registration check" but nothing kept them mirrored. Centralizing the
+ * loop closes the most likely future drift surface.
+ *
+ * @module
+ */
+import type { Action } from './action_types.js';
+import type { RpcAction } from './action_rpc.js';
+/** Result returned by `compile_action_registry`. */
+export interface ActionRegistryCompileResult {
+    /**
+     * Method → `RpcAction` lookup for dispatch. Only `request_response`
+     * specs with a handler land here — kind-polymorphic input arrays
+     * (the WebSocket dispatcher's `actions: ReadonlyArray<Action>`)
+     * pass `remote_notification` / handler-less specs through unchanged.
+     */
+    action_map: Map<string, RpcAction>;
+}
+/**
+ * Validate registry-time invariants and build the dispatcher's
+ * method → action lookup.
+ *
+ * @param actions - polymorphic action array; HTTP RPC passes `RpcAction[]` (narrower), WebSocket passes `Action[]` (kind-polymorphic — handler-less notification specs are accepted)
+ * @param ctx_label - per-spec error-message prefix, e.g. `'RPC action'` or `'WS action'`. Combined with the spec method as `${ctx_label} "${method}"`.
+ * @throws Error on biconditional violation, rate-limit/account-axis mismatch, JSON-RPC null-input, or duplicate method.
+ */
+export declare const compile_action_registry: (actions: ReadonlyArray<Action>, ctx_label: string) => ActionRegistryCompileResult;
+//# sourceMappingURL=compile_action_registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compile_action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/compile_action_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAI/C,oDAAoD;AACpD,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,aAAa,CAAC,MAAM,CAAC,EAC9B,WAAW,MAAM,KACf,2BAoCF,CAAC"}

package/dist/actions/compile_action_registry.js

@@ -0,0 +1,69 @@
+/**
+ * Shared registration loop for action-dispatcher endpoints.
+ *
+ * `create_rpc_endpoint` (HTTP RPC) and `register_action_ws` (WebSocket)
+ * both build a `Map<method, RpcAction>` from a list of action specs and
+ * gate the build on the same registry-time invariants:
+ *
+ * 1. **Auth-shape biconditional** — per `assert_route_auth_acting_biconditional`
+ *    in `http/auth_shape.ts`: `auth.actor !== 'none' ⟺ input declares
+ *    acting?: ActingActor`. Fires for every spec with non-null auth.
+ * 2. **Rate-limit / account axis** — `rate_limit: 'account' | 'both'`
+ *    requires `auth.account === 'required'`; without an account on the
+ *    request there is no key for the per-account bucket.
+ * 3. **JSON-RPC §4.2 wire validity** — `request_response` specs whose
+ *    handler will reach the dispatch map must not use `z.null()` for
+ *    input (the wire format forbids `"params": null`; use `z.void()`
+ *    for parameterless methods).
+ * 4. **Duplicate method names** — JSON-RPC keys on `method`, so every
+ *    spec in the array must declare a unique `method` regardless of
+ *    kind / handler presence.
+ *
+ * Pre-consolidation each dispatcher inlined these checks; the comment
+ * in `register_action_ws.ts` literally said "mirrors the HTTP RPC
+ * registration check" but nothing kept them mirrored. Centralizing the
+ * loop closes the most likely future drift surface.
+ *
+ * @module
+ */
+import { assert_route_auth_acting_biconditional } from '../http/auth_shape.js';
+import { is_null_schema } from '../http/schema_helpers.js';
+/**
+ * Validate registry-time invariants and build the dispatcher's
+ * method → action lookup.
+ *
+ * @param actions - polymorphic action array; HTTP RPC passes `RpcAction[]` (narrower), WebSocket passes `Action[]` (kind-polymorphic — handler-less notification specs are accepted)
+ * @param ctx_label - per-spec error-message prefix, e.g. `'RPC action'` or `'WS action'`. Combined with the spec method as `${ctx_label} "${method}"`.
+ * @throws Error on biconditional violation, rate-limit/account-axis mismatch, JSON-RPC null-input, or duplicate method.
+ */
+export const compile_action_registry = (actions, ctx_label) => {
+    const action_map = new Map();
+    const seen_methods = new Set();
+    for (const action of actions) {
+        const { spec } = action;
+        const ctx = `${ctx_label} "${spec.method}"`;
+        if (seen_methods.has(spec.method)) {
+            throw new Error(`Duplicate ${ctx_label} method: ${spec.method}`);
+        }
+        seen_methods.add(spec.method);
+        // Auth-shape invariants apply to any spec with non-null auth (which
+        // per the spec union means `kind === 'request_response'`).
+        if (spec.auth !== null) {
+            assert_route_auth_acting_biconditional(spec.auth, { input: spec.input }, ctx);
+            if ((spec.rate_limit === 'account' || spec.rate_limit === 'both') &&
+                spec.auth.account !== 'required') {
+                throw new Error(`${ctx} declares rate_limit: '${spec.rate_limit}' but auth.account !== 'required' — no account guaranteed for account-keyed limiting. Use 'ip' or set auth.account: 'required'.`);
+            }
+        }
+        // Only request_response specs with a handler reach the dispatch
+        // map. Notifications (e.g. WS `cancel`) and handler-less specs
+        // stay registry-only and bypass JSON-RPC wire-validity checks.
+        if (spec.kind === 'request_response' && action.handler) {
+            if (is_null_schema(spec.input)) {
+                throw new Error(`${ctx} uses z.null() for input — JSON-RPC 2.0 §4.2 forbids "params": null on the wire. Use z.void() for parameterless methods.`);
+            }
+            action_map.set(spec.method, { spec, handler: action.handler });
+        }
+    }
+    return { action_map };
+};

package/dist/actions/heartbeat.d.ts

@@ -20,15 +20,19 @@
 import { z } from 'zod';
 import type { Action } from './action_types.js';
 /**
- * `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.
+ * `ActionSpec` for the shared heartbeat. Account-required, actor-none —
+ * upgrade-time auth has already admitted the socket; heartbeats don't
+ * need role gating or actor resolution. `side_effects: false` keeps it
+ * orthogonal to state changes.
  */
 export declare const heartbeat_action_spec: {
     method: string;
     kind: "request_response";
     initiator: "frontend";
-    auth: "authenticated";
+    auth: {
+        account: "required";
+        actor: "none";
+    };
     side_effects: false;
     input: z.ZodObject<{}, z.core.$strict>;
     output: z.ZodObject<{}, z.core.$strict>;

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;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;CAUG,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;;;;GAOG;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;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAUG,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAG9B,CAAC"}

package/dist/actions/heartbeat.js

@@ -19,15 +19,16 @@
  */
 import { z } from 'zod';
 /**
- * `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.
+ * `ActionSpec` for the shared heartbeat. Account-required, actor-none —
+ * upgrade-time auth has already admitted the socket; heartbeats don't
+ * need role gating or actor resolution. `side_effects: false` keeps it
+ * orthogonal to state changes.
  */
 export const heartbeat_action_spec = {
     method: 'heartbeat',
     kind: 'request_response',
     initiator: 'frontend',
-    auth: 'authenticated',
+    auth: { account: 'required', actor: 'none' },
     side_effects: false,
     input: z.strictObject({}),
     output: z.strictObject({}),

package/dist/actions/perform_action.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Transport-agnostic dispatch core shared by HTTP RPC and WebSocket
+ * action dispatchers.
+ *
+ * `perform_action` runs the post-parse pipeline that every action-spec
+ * handler must traverse:
+ *
+ * 1. **Pre-validation auth (401)** — short-circuits unauthenticated callers
+ *    on `'required'` axes before input validation runs, so callers never
+ *    see `invalid_params` for methods with required input.
+ * 2. **Validate params (400)** — `spec.input.safeParse(raw_params)` with
+ *    `z.void()` / `?? {}` rules. The validated input lands inside the
+ *    function so the authorization phase reads `acting` as a typed Zod
+ *    field.
+ * 3. **Authorization phase** — when `auth.actor !== 'none'` (or
+ *    `auth.account !== 'none' && actor === 'none'`), resolves the actor
+ *    via `apply_authorization_phase` against the supplied `account_id`
+ *    plus `validated_input.acting`. Failures fold into a JSON-RPC error
+ *    envelope. The test-harness escape hatch lives in the caller — pass
+ *    `preset.request_context` to skip the live phase and use a pre-baked
+ *    context instead.
+ * 4. **Post-authorization auth (403)** — gates `auth.credential_types` and
+ *    `auth.roles` against the resolved context.
+ * 5. **Rate limit (429)** — per-action IP / account throttling, throttle-
+ *    requests semantics (every invocation records, regardless of outcome).
+ * 6. **Dispatch + DEV-only output validation + error normalization** —
+ *    `spec.side_effects` picks transaction (`deps.db.transaction`) vs
+ *    pool. Handler throws roll back the transaction; the catch sits
+ *    outside the transaction boundary. Handler outputs are validated
+ *    against `spec.output` under DEV (logs an error on mismatch, never
+ *    throws, never mutates the result).
+ *
+ * The function is pure data — it never touches a Hono context, so HTTP
+ * RPC, REST bridge (when on the action surface), and WS dispatch all
+ * call into it the same way and bind the discriminated
+ * `PerformActionResult` to their wire shape.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import { type RequestContext } from '../auth/request_context.js';
+import { type CredentialType } from '../hono_context.js';
+import type { Db } from '../db/db.js';
+import { type JsonrpcRequestId, type JsonrpcErrorObject } from '../http/jsonrpc.js';
+import type { RateLimiter } from '../rate_limiter.js';
+import type { RpcAction } from './action_rpc.js';
+/**
+ * Per-call inputs to `perform_action`. Each transport assembles this from
+ * its wire envelope + connection identity.
+ */
+export interface PerformActionInput {
+    /** The resolved spec + handler (transport does method lookup). */
+    action: RpcAction;
+    /** Raw params from the wire envelope (post-`JsonrpcRequest.parse`, pre-`spec.input.safeParse`). */
+    raw_params: unknown;
+    /** JSON-RPC request id — echoed onto the response. */
+    request_id: JsonrpcRequestId;
+    /** Authenticated account id, or `null` for anonymous. */
+    account_id: string | null;
+    /** Credential type the request arrived on, or `null` for anonymous. */
+    credential_type: CredentialType | null;
+    /** Resolved client IP (`'unknown'` if upstream couldn't resolve). */
+    client_ip: string;
+    /** Per-request abort signal. HTTP: `c.req.raw.signal`. WS: `AbortSignal.any([socket, request])`. */
+    signal: AbortSignal;
+    /** Send a request-scoped notification. HTTP: DEV-warn-and-drop. WS: socket-scoped. */
+    notify: (method: string, params: unknown) => void;
+    /** Stable per-socket id on WS; `undefined` on HTTP. */
+    connection_id?: Uuid;
+    /**
+     * Test-harness escape hatch. When set, the live authorization phase is
+     * skipped and `request_context` is used directly for post-authorization
+     * checks + handler dispatch. Production callers leave this `undefined`.
+     */
+    preset?: {
+        request_context: RequestContext | null;
+    };
+}
+/**
+ * Per-deps inputs to `perform_action`. Each transport supplies its own
+ * pool-level `Db` and rate limiters; the dispatcher wraps in a transaction
+ * iff `spec.side_effects` is true.
+ *
+ * Pool-resilient fire-and-forget effects (audit writes) run through
+ * `AppDeps.audit.emit` from the action factory's closure — the dispatcher
+ * never sees the audit emitter. The bound emitter owns the pool.
+ */
+export interface PerformActionDeps {
+    /** Pool-level DB. The dispatcher wraps in `db.transaction` for `side_effects: true` actions. */
+    db: Db;
+    /**
+     * Eager fire-and-forget pool-write queue, flushed by the transport's
+     * `try/finally` via `flush_pending_effects`.
+     */
+    pending_effects: Array<Promise<void>>;
+    /**
+     * Deferred post-commit thunks pushed via `emit_after_commit`, flushed
+     * by the transport's `try/finally` after the handler returns.
+     */
+    post_commit_effects: Array<() => void | Promise<void>>;
+    /** Logger threaded into `ActionContext.log`. */
+    log: Logger;
+    /** Per-IP limiter (shared across transports). `null` disables. */
+    action_ip_rate_limiter: RateLimiter | null;
+    /** Per-account limiter (shared across transports). `null` disables. */
+    action_account_rate_limiter: RateLimiter | null;
+}
+/**
+ * Discriminated result of `perform_action`. Each transport binds this to
+ * its wire shape: HTTP RPC folds the error into a JSON-RPC envelope and
+ * returns via `c.json`; WS sends the response over the socket.
+ */
+export type PerformActionResult = {
+    kind: 'ok';
+    result: unknown;
+} | {
+    kind: 'error';
+    error: JsonrpcErrorObject;
+    status: number;
+};
+/**
+ * The shared dispatch core. Pure data — no Hono context, no socket. Each
+ * transport calls into this with pre-parsed inputs and binds the result
+ * to its wire shape.
+ *
+ * Phase order: 401 → 400 → 403 → handler. On the test-preset path the
+ * dispatcher skips the live authorization phase and uses the supplied
+ * pre-baked context for post-authorization checks; pre-validation 401
+ * still fires when the harness omits `account_id`.
+ */
+export declare const perform_action: (input: PerformActionInput, deps: PerformActionDeps) => Promise<PerformActionResult>;
+/**
+ * Build a JSON-RPC response envelope from a `PerformActionResult` for
+ * transports that wire over the JSON-RPC 2.0 message shape (HTTP RPC + WS).
+ */
+export declare const perform_action_result_to_envelope: (id: JsonrpcRequestId, result: PerformActionResult) => {
+    jsonrpc: string;
+    id: JsonrpcRequestId;
+} & ({
+    result: unknown;
+} | {
+    error: JsonrpcErrorObject;
+});
+//# sourceMappingURL=perform_action.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"perform_action.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/perform_action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAC,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAEN,KAAK,gBAAgB,EAErB,KAAK,kBAAkB,EACvB,MAAM,oBAAoB,CAAC;AAW5B,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAA+B,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,MAAM,EAAE,SAAS,CAAC;IAClB,mGAAmG;IACnG,UAAU,EAAE,OAAO,CAAC;IACpB,sDAAsD;IACtD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,yDAAyD;IACzD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uEAAuE;IACvE,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,MAAM,EAAE,WAAW,CAAC;IACpB,sFAAsF;IACtF,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,uDAAuD;IACvD,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAC,eAAe,EAAE,cAAc,GAAG,IAAI,CAAA;KAAC,CAAC;CAClD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC,gGAAgG;IAChG,EAAE,EAAE,EAAE,CAAC;IACP;;;OAGG;IACH,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;OAGG;IACH,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,sBAAsB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3C,uEAAuE;IACvE,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAC1B,OAAO,kBAAkB,EACzB,MAAM,iBAAiB,KACrB,OAAO,CAAC,mBAAmB,CAuJ7B,CAAC;AA4EF;;;GAGG;AACH,eAAO,MAAM,iCAAiC,GAC7C,IAAI,gBAAgB,EACpB,QAAQ,mBAAmB,KACzB;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,gBAAgB,CAAA;CAAC,GAAG,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,GAAG;IAAC,KAAK,EAAE,kBAAkB,CAAA;CAAC,CAK5F,CAAC"}