@fuzdev/fuz_app 0.113.0 → 0.114.0

package/dist/actions/CLAUDE.md

@@ -82,7 +82,7 @@ order and returns the `Map<method, RpcAction>` the dispatchers use:
 - **Auth-shape biconditional** — `actor !== 'none' ⟺ input declares acting?: ActingActor` (via `assert_route_auth_acting_biconditional`).
 - **No `auth.required_scope`** — the slot is route-spec-only; nothing mounts a guard from it on an action, so declaring it would be a control that silently does nothing. Narrowed tokens are gated per method by the scope check in `perform_action`, which derives the `rpc:<method>` capability from `spec.method` rather than trusting a hand-written one.
 - **Rate-limit account axis** — `rate_limit: 'account' | 'both'` requires `auth.account === 'required'`.
-- **JSON-RPC §4.2 wire validity** — `request_response` specs with a handler may not use `z.null()` for input (use `z.void()` for nullary).
+- **JSON-RPC §4.2 wire validity** — `request_response` specs with a handler may not use `z.null()` for input (use `z.void()` for nullary), nor `z.void()` for output (a response always carries a `result`, which clients validate against `spec.output`; use `z.null()` when there's nothing to return).
 - **Unique method names** across the array.
 
 Only `request_response` specs with a handler reach the dispatch map;
@@ -296,7 +296,7 @@ Pipeline (401 → authz → 403 → 429 → 400 → handler):
 2. Authorization phase — `apply_authorization_phase` against `account_id` + `read_acting(auth, raw_params)`, which takes the selector off the raw params (malformed reads as omitted) since validation runs later. Test escape hatch via `preset.request_context`
 3. Post-authorization auth (403) — credential-type gate, then token scope, then role
 4. Rate limit (429) — throttle-requests semantics, ahead of validation so malformed params charge the budget and a throttled caller pays no schema work
-5. Validate params (400) — `spec.input.safeParse` with `z.void()` / `?? {}` rules
+5. Validate params (400) — `spec.input.safeParse` with `z.void()` / `?? {}` rules; a `z.void()` input reads absent, `null` (GET `?params=null`), and `{}` alike as the no-arg call (`to_input_params` in `http/schema_helpers.ts`, via `to_void_params`, the twin of the Rust `require_void_params`; the peer receive path in `ActionDispatcher` runs the same normalizer) and refuses any other shape
 6. Dispatch + DEV output validation + error normalization — `spec.side_effects` picks transaction vs pool. `ThrownJsonrpcError` preserves code + data; generic throws become `internal_error`
 
 `PerformActionInput` carries `account_id`, `credential_type`, `client_ip`,
@@ -349,8 +349,9 @@ and `allow_fallback: boolean` (default `true`). Explicit
 ### WS close codes (`actions/transports.ts`)
 
 - `WS_CLOSE_SESSION_REVOKED = 4001` — server revoked auth; client enters permanent `revoked` state, no reconnect.
-- `WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002` — client observed receive-silence past `DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT`.
+- `WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002` — client observed receive-silence past its receive timeout (`resolve_heartbeat_receive_timeout`).
 - `WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003` — server observed receive-silence past `DEFAULT_SERVER_HEARTBEAT_TIMEOUT` (60s).
+- `WS_CLOSE_MESSAGE_TOO_BIG = 1009` — server received a message over its `max_message_bytes` cap (RFC 6455 "Message Too Big").
 
 ### Transport modules
 
@@ -358,15 +359,35 @@ and `allow_fallback: boolean` (default `true`). Explicit
 - `actions/transports_ws.ts` — `frontend_websocket_rpc`; thin adapter over `WebsocketRpcConnection` (default impl: `FrontendWebsocketClient`). Answers inbound server→client requests: a built-in `peer_ping_responder` for `peer/ping` (zero-wiring liveness), any other request routed through `peer.receive` with the response sent back over the socket (the frontend half of the ActionPeer receive loop).
 - `actions/transports_ws_backend.ts` — `backend_websocket_rpc`; server-side WS with session tracking; satisfies `FilterableBroadcastTransport`. Server→client requests via `request_connection` (correlation registry in `actions/peer_request.ts`).
 
-`FrontendHttpTransport` synthesizes a JSON-RPC error envelope via
-`http_status_to_jsonrpc_error_code` on non-OK HTTP; DEV warns on drift
-between JSON-RPC error code and declared HTTP status.
+`FrontendHttpTransport` on non-OK HTTP returns the body as-is when it's a
+JSON-RPC error response for the request (same `id` compared as strings since GET sends it as a query param, or `null`) — the
+status → code map is lossy (`queue_overflow` and `rate_limited` share 429), so
+the server's code, message, and data must survive. Any other body gets an
+envelope synthesized via `http_status_to_jsonrpc_error_code`. DEV warns when
+`jsonrpc_error_code_to_http_status(code)` disagrees with the status, or when an
+error envelope arrives with a 2xx.
 
 `FrontendWebsocketTransport` notification sends fail-fast when disconnected
 regardless of `queue` — `connection.send()` has no queue semantic, so
 buffering would masquerade as success at the rpc_client layer. Requests
 route via `queue`.
 
+**WS message cap.** `DEFAULT_WS_MAX_MESSAGE_BYTES` (1 MiB, in
+`actions/transports.ts`, equal to `DEFAULT_MAX_BODY_SIZE` and the twin of the
+Rust spine's constant) bounds one message both ways. `register_action_ws`
+(`max_message_bytes`, also on `WsEndpointSpec`) closes the socket with
+`WS_CLOSE_MESSAGE_TOO_BIG` on a larger inbound message, before parsing — no
+per-message reply, like the Rust spine. The check runs after the runtime
+adapter has buffered the message, so it bounds dispatch work, not memory.
+`FrontendWebsocketTransport`'s optional third argument
+(`FrontendWebsocketTransportOptions.max_message_bytes`, same default) answers
+an outbound request or notification whose JSON encoding exceeds it (in UTF-8
+bytes) locally with an `invalid_request` error carrying
+`data.reason: 'payload_too_large'` (`create_message_too_large_error`) and never
+sends it — otherwise the close would fail every request in flight on the
+socket. A consumer that raises the server cap passes the same value to the
+client; `null` skips the client-side measurement.
+
 ### `BackendWebsocketTransport` — server-side WS state
 
 Three aligned maps keyed by `connection_id` (branded `Uuid`):
@@ -487,7 +508,7 @@ but `upgradeWebSocket` is missing. A factory returning `[]` does NOT trip
 the check, so feature-flag gated WS surfaces stay safe.
 
 `WsEndpointSpec` fields: `path`, `allowed_origins`, `actions`,
-`required_roles?`, `transport?`, `heartbeat?`, `artificial_delay?`,
+`required_roles?`, `transport?`, `heartbeat?`, `artificial_delay?`, `max_message_bytes?`,
 `on_socket_open?`, `on_socket_close?`, `auth_guard?` (default `true`,
 deduped by reference identity via `WeakSet<BackendWebsocketTransport>`),
 `extra_audit_handlers?`.
@@ -604,7 +625,7 @@ individual protocol actions without an opt-out flag.
 
 ### Individual actions
 
-- **`heartbeat_action`** — `request_response`, `initiator: 'frontend'`, `auth: 'authenticated'`, `side_effects: false`, nullary input/output (`z.strictObject({})`). Handler is a stateless no-op echo. Client's activity-aware heartbeat timer fires this whenever idle past `DEFAULT_HEARTBEAT_INTERVAL`; server's `register_action_ws` heartbeat tracker counts the incoming message as activity.
+- **`heartbeat_action`** — `request_response`, `initiator: 'frontend'`, `auth: 'authenticated'`, `side_effects: false`, parameterless `z.void()` input (absent / `null` / `{}` params — the Rust `require_void_params` shapes), empty-object output. Handler is a stateless no-op echo. Client's activity-aware heartbeat timer fires this whenever idle past `DEFAULT_HEARTBEAT_INTERVAL`; server's `register_action_ws` heartbeat tracker counts the incoming message as activity.
 - **`cancel_action`** — `remote_notification`, `initiator: 'frontend'`, `auth: null`, `side_effects: true`. Params: `CancelNotificationParams = z.strictObject({request_id: JsonrpcRequestId})`. **Handler is an empty stub** — cancel semantics are dispatcher-owned (`register_action_ws` has the `{request_id → AbortController}` map). Wire format is snake_case `cancel` + `{request_id}`, not MCP's `$/cancelRequest` + `{requestId}` — MCP adoption would happen at an MCP adapter's translation layer, not in the base transport.
 - **`peer_ping_action`** — `request_response`, `initiator: 'both'`, `auth: public`, `side_effects: false`. Input `PingActionInput = {nonce?, timeout_ms?}` (`.default({})`); output `PingResponse = {nonce, protocol_version}`. The client→server invocation drives the **server→client** direction: the handler calls `ctx.request_client('peer/ping', {nonce})`, awaits the echo, validates it against `PingResponse` + checks the nonce, and returns it. Over HTTP RPC (`ctx.request_client` absent) it refuses with `peer_no_transport`, so it's mounted on both the WS endpoint (via this bundle) and the HTTP RPC endpoint (the spine full mount). `timeout_ms` is clamped shorten-only. `data.reason` codes (`peer_timeout` / `peer_connection_gone` / `peer_no_transport` / `peer_too_many_in_flight` / `peer_ping_invalid_reply` / `peer_ping_nonce_mismatch`) + the `PingResponse` shape (whose `protocol_version` is `PEER_PROTOCOL_VERSION`) are the cross-impl wire contract (twins of the Rust `REASON_PEER_*`). The frontend half — `peer_ping_responder` (the echo a client sends back, wired into `FrontendWebsocketTransport`) — lives here too. `peer_ping_action` is a plain `RpcAction` literal (not `rpc_action(...)`), so the module stays free of the runtime `action_rpc.ts` import and `protocol_action_specs` doesn't drag the dispatch core into frontend bundles — same discipline as `heartbeat`/`cancel`. See `actions/peer_ping.ts`.
 
@@ -619,14 +640,23 @@ high-level shapes that span modules:
 - **39-variant discriminated union** — `ActionEventDataUnion<TMethod, TInput, TOutput>` across `kind` + `phase` + `step` (28 for `request_response`, 6 for `remote_notification`, 5 for `local_call`). Narrows `input` / `output` / `error` / `request` / `response` / `notification` / `progress` at each lifecycle point.
 - **Step transitions** — `initial → parsed | failed`, `parsed → handling | failed`, `handling → handled | failed`, `handled`/`failed` terminal. `validate_step_transition(from, to)` throws on illegal moves.
 - **Phase transitions** — chained: `send_request → receive_response`, `receive_request → send_response`; everything else terminal. `validate_phase_for_kind` + `validate_phase_transition` enforce.
-- **`ActionEvent.parse()`** — `initial → parsed` via `spec.input.safeParse`. Input validation failures **fail immediately** without routing through an error phase (client-side programming errors, not runtime conditions with handlers). Handler errors DO route through `send_error` / `receive_error`. On `receive_response` with error response, transitions to `receive_error` instead of failing.
+- **`ActionEvent.parse()`** — `initial → parsed` via `spec.input.safeParse`. Input validation failures **fail immediately** without routing through an error phase (client-side programming errors, not runtime conditions with handlers). Handler errors DO route through `send_error` / `receive_error`. On `receive_response` with error response, transitions to `receive_error` instead of failing; a success response's `result` is validated against `spec.output` (always, not DEV-only — it's inbound data; undeclared keys are dropped rather than refused, so an older client survives an added response field) and `output` becomes the parsed value, or the event moves to `receive_error` with an `internal_error` carrying `data: {reason: ERROR_RESPONSE_OUTPUT_INVALID, validation_errors}` — a remote contract break, deliberately distinct from the `invalid_params` / `validation_error` of bad caller input.
+- **Handler throws** — `ThrownJsonrpcError` keeps code/message/data; any other throw becomes `internal_error` carrying the thrown message. When the error answers a remote caller (`receive_request` / `send_response`), the raw message goes through `dev_only` like the server dispatch core.
 - **Protocol message creation is automatic** — transitioning `parsed → handling` on `send_request` materializes the outgoing `JsonrpcRequest` with a fresh `create_uuid()` id; on `send` (notification) it materializes the `JsonrpcNotification`.
 
 `ActionDispatcher` (`actions/action_dispatcher.ts`) is symmetric send + receive
 over a `Transports` registry and `ActionEventEnvironment`. `default_send_options`
 excludes `signal` deliberately — a shared signal would abort every subsequent
 call after the first trip. `transport_name` and `queue` can be defaulted here
-once to flip the dispatcher into client-authoritative mode.
+once to flip the dispatcher into client-authoritative mode. Diagnostics (failed
+sends, inbound notifications that fail to parse or whose handler throws, unknown
+methods) go to `environment.log`; unset falls back to `console_action_log`
+(warn/error to `console`, debug dropped) so failures are never silent, and
+`log: null` opts out (`resolve_action_log`). An inbound request or notification
+reads its params through the server dispatch core's normalizer
+(`to_input_params`): for a `z.void()` input, absent, `null`, and `{}` alike are
+the no-arg call; for any other input, absent or `null` params are `{}` (so an
+all-optional object input accepts a call that omits them).
 
 **Naming.** `ActionDispatcher` is the (frontend) send/receive coordinator class.
 "ActionPeer" — unbackticked throughout the peer/ping + `request_client` docs — is
@@ -647,7 +677,11 @@ Ships three correctness primitives default-on:
 
 1. **Promise-based `request`** — auto-assigned monotonic id; pending map keyed by id; resolved via intercept on the message path. Rejects `ThrownJsonrpcError` with specific codes (`unauthenticated`, `request_cancelled`, `queue_overflow`, `service_unavailable`, `internal_error`, or the server's wire code verbatim). The transport catch block preserves `.code` exactly so `FrontendWebsocketTransport` never collapses to `internal_error`.
 2. **Durable queue** — `request()` calls while disconnected buffer up to `DEFAULT_QUEUE_MAX_SIZE = 100` and flush on reopen. Overflow rejects `queue_overflow`. Pass `{queue: false}` to reject immediately (used internally by the heartbeat — it must not fight the queue for the disconnect-detection slot). Raw `send(data)` is **drop-on-disconnect** by design (fire-and-forget notifications want that).
-3. **Activity-aware heartbeat** — idles past `DEFAULT_HEARTBEAT_INTERVAL = 30_000` fire the shared `heartbeat` request. Receive-silence past `DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT = 60_000` closes with `WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT`. Tick runs at `interval / 2` so event-loop blockage pauses the timer itself.
+3. **Activity-aware heartbeat** — the shared `heartbeat` request fires when either direction has been idle past `DEFAULT_HEARTBEAT_INTERVAL = 30_000` (send-only silence would trip the server's detector, receive-only silence this client's). Receive-silence past the receive timeout closes with `WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT`. Tick runs at `interval / 2` so event-loop blockage pauses the timer itself — so a heartbeat can leave up to 1.5 × `interval` after the last receive, and `resolve_heartbeat_receive_timeout` raises the receive timeout (`DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT = 60_000` unless given) to at least `HEARTBEAT_RECEIVE_TIMEOUT_MIN_FACTOR` (2) × `interval`. A long `interval` alone is therefore safe. At most one heartbeat is outstanding — an unanswered one is left to the receive timeout rather than repeated.
+
+`last_send_time` / `last_receive_time` are reactive epoch-ms stamps of the most
+recent frame each way — every frame, including heartbeats and the responses
+`request` consumes — for diagnostics UI.
 
 Reconnect policy (exponential backoff): `delay = DEFAULT_RECONNECT_DELAY * DEFAULT_BACKOFF_FACTOR ** (attempts-1)`,
 capped at `DEFAULT_RECONNECT_DELAY_MAX`. `WS_CLOSE_SESSION_REVOKED` is
@@ -661,14 +695,6 @@ fields fall back to defaults, not "keep current"): `set_reconnect`,
 `socket_status_to_async_status(status, revoked)` collapses to fuz_util's
 4-way `AsyncStatus`.
 
-### `RequestTracker` (`actions/request_tracker.svelte.ts`)
-
-Public utility — reactive pending-request state with timeouts.
-`SvelteMap` keyed by `JsonrpcRequestId`, default `request_timeout_ms = 120_000`.
-Used by transports that don't delegate pending correlation to a
-`WebsocketRpcConnection` (`FrontendWebsocketTransport` delegates to
-`FrontendWebsocketClient`'s own `#pending` map).
-
 ## RPC client (`actions/rpc_client.ts`)
 
 `create_rpc_client({peer, environment, actions?, transport_for_method?})` —
@@ -715,7 +741,7 @@ doesn't get probed as a thenable by `await`.
 
 ### Frontend factory (`actions/frontend_rpc_client.ts`)
 
-`create_frontend_rpc_client<TApi>({specs, path?, transports?, transport_for_method?, on_action_event?})`
+`create_frontend_rpc_client<TApi>({specs, path?, transports?, transport_for_method?, on_action_event?, lookup_action_handler?, log?})`
 bundles `ActionRegistry + ActionEventEnvironment + Transports + ActionDispatcher +
 create_rpc_client + create_throwing_api` boilerplate every consumer
 repeats — plus the `lookup_action_handler: () => undefined` stub (frontend

package/dist/actions/action_dispatcher.d.ts

@@ -8,7 +8,7 @@
  */
 import { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import { Transports, type TransportName, type TransportSendOptions } from './transports.js';
-import type { ActionEventEnvironment } from './action_event_types.js';
+import { type ActionEventEnvironment } from './action_event_types.js';
 /**
  * Per-call options for `ActionDispatcher.send`. Extends `TransportSendOptions`
  * with `transport_name` for per-call transport selection. The peer-wide

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

@@ -1 +1 @@
-{"version":3,"file":"action_dispatcher.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAOtE;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACxE,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACvC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAKxB,oBAAoB,CAAC,EAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAC,CAAC;CACnE;AAED,qBAAa,gBAAgB;;IAC5B,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAC,CAAC;gBAEtD,OAAO,EAAE,uBAAuB;IAM5C;;;;;;;;OAQG;IAEG,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACnC,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CvC;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAgIjF"}
+{"version":3,"file":"action_dispatcher.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAW5B,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAEN,KAAK,sBAAsB,EAE3B,MAAM,yBAAyB,CAAC;AAOjC;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACxE,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACvC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAKxB,oBAAoB,CAAC,EAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAC,CAAC;CACnE;AAED,qBAAa,gBAAgB;;IAC5B,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAC,CAAC;gBAEtD,OAAO,EAAE,uBAAuB;IAW5C;;;;;;;;OAQG;IAEG,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACnC,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CvC;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CA2HjF"}

package/dist/actions/action_dispatcher.js

@@ -9,8 +9,10 @@
 import { JsonrpcMessageFromClientToServer, JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, to_jsonrpc_message_id, is_jsonrpc_request, is_jsonrpc_notification } from '../http/jsonrpc_helpers.js';
 import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
+import { to_input_params } from '../http/schema_helpers.js';
 import { create_action_event } from './action_event.js';
 import { Transports } from './transports.js';
+import { resolve_action_log } from './action_event_types.js';
 export class ActionDispatcher {
     environment;
     transports;
@@ -24,27 +26,31 @@ export class ActionDispatcher {
         this.transports = options.transports ?? new Transports();
         this.default_send_options = options.default_send_options ?? {};
     }
+    /** Diagnostics sink — see `resolve_action_log`. */
+    get #log() {
+        return resolve_action_log(this.environment);
+    }
     async send(message, options) {
         try {
             const transport = this.transports.get_transport(options?.transport_name ?? this.default_send_options.transport_name);
             if (!transport) {
-                this.environment.log?.error('[peer] send failed: no transport available');
+                this.#log?.error('[peer] send failed: no transport available');
                 return create_jsonrpc_error_response(to_jsonrpc_message_id(message), jsonrpc_error_messages.service_unavailable('no transport available'));
             }
             const message_type = is_jsonrpc_request(message) ? 'request' : 'notification';
-            this.environment.log?.debug(`[peer] send ${message_type}:`, message.method, `via ${transport.transport_name}`);
+            this.#log?.debug(`[peer] send ${message_type}:`, message.method, `via ${transport.transport_name}`);
             const result = await transport.send(message, {
                 signal: options?.signal,
                 queue: options?.queue ?? this.default_send_options.queue
             });
             if (result && 'error' in result) {
-                this.environment.log?.error(`[peer] send ${message_type} failed:`, message.method, result.error.message);
+                this.#log?.error(`[peer] send ${message_type} failed:`, message.method, result.error.message);
             }
             return result;
         }
         catch (error) {
             // TODO add retry handling here?
-            this.environment.log?.error('[peer] send unexpected error:', error);
+            this.#log?.error('[peer] send unexpected error:', error);
             return create_jsonrpc_error_response_from_thrown(to_jsonrpc_message_id(message), error);
         } // TODO finally?
     }
@@ -62,7 +68,7 @@ export class ActionDispatcher {
             return result;
         }
         catch (error) {
-            this.environment.log?.error('[peer] receive unexpected error:', error);
+            this.#log?.error('[peer] receive unexpected error:', error);
             // Return appropriate error response based on the message
             return create_jsonrpc_error_response_from_thrown(to_jsonrpc_message_id(message), error);
         } // TODO finally?
@@ -82,13 +88,13 @@ export class ActionDispatcher {
     async #receive_request(request) {
         const spec = this.environment.lookup_action_spec(request.method);
         if (!spec) {
-            this.environment.log?.warn(`[peer] receive request: method not found:`, request.method);
+            this.#log?.warn(`[peer] receive request: method not found:`, request.method);
             return create_jsonrpc_error_response(request.id, jsonrpc_error_messages.method_not_found(request.method));
         }
-        this.environment.log?.debug(`[peer] receive request:`, request.method);
+        this.#log?.debug(`[peer] receive request:`, request.method);
         try {
             // Create action event in receive_request phase
-            const event = create_action_event(this.environment, spec, request.params, 'receive_request');
+            const event = create_action_event(this.environment, spec, to_input_params(spec.input, request.params), 'receive_request');
             event.set_request(request);
             // Parse and handle
             await event.parse().handle_async();
@@ -105,7 +111,7 @@ export class ActionDispatcher {
             }
             // Check for terminal failure
             if (event.data.step === 'failed') {
-                this.environment.log?.error(`[peer] receive request failed:`, request.method, event.data.error);
+                this.#log?.error(`[peer] receive request failed:`, request.method, event.data.error);
                 return create_jsonrpc_error_response(request.id, event.data.error);
             }
             // Check if transitioned to error phase (send_error)
@@ -116,33 +122,33 @@ export class ActionDispatcher {
                 return create_jsonrpc_error_response(request.id, event.data.error);
             }
             // Fallback for unexpected states
-            this.environment.log?.error(`[peer] receive request: unexpected state:`, request.method, event.data);
+            this.#log?.error(`[peer] receive request: unexpected state:`, request.method, event.data);
             return create_jsonrpc_error_response(request.id, jsonrpc_error_messages.internal_error('unknown error'));
         }
         catch (error) {
-            this.environment.log?.error(`[peer] receive request exception:`, request.method, error);
+            this.#log?.error(`[peer] receive request exception:`, request.method, error);
             return create_jsonrpc_error_response_from_thrown(request.id, error);
         }
     }
     async #receive_notification(notification) {
         const spec = this.environment.lookup_action_spec(notification.method);
         if (!spec) {
-            this.environment.log?.warn(`[peer] receive notification: method not found:`, notification.method);
+            this.#log?.warn(`[peer] receive notification: method not found:`, notification.method);
             return;
         }
-        this.environment.log?.debug(`[peer] receive notification:`, notification.method);
+        this.#log?.debug(`[peer] receive notification:`, notification.method);
         try {
             // Create action event in receive phase
-            const event = create_action_event(this.environment, spec, notification.params, 'receive');
+            const event = create_action_event(this.environment, spec, to_input_params(spec.input, notification.params), 'receive');
             event.set_notification(notification);
             // Parse and handle
             await event.parse().handle_async();
             if (event.data.step === 'failed') {
-                this.environment.log?.error(`[peer] receive notification failed:`, notification.method, event.data.error);
+                this.#log?.error(`[peer] receive notification failed:`, notification.method, event.data.error);
             }
         }
         catch (error) {
-            this.environment.log?.error(`[peer] receive notification exception:`, notification.method, error);
+            this.#log?.error(`[peer] receive notification exception:`, notification.method, error);
         }
     }
 }

package/dist/actions/action_event.d.ts

@@ -10,6 +10,12 @@ import type { ActionEventPhase, ActionSpecUnion } from './action_spec.js';
 import type { JsonrpcRequest, JsonrpcResponseOrError, JsonrpcNotification } from '../http/jsonrpc.js';
 import type { ActionEventEnvironment, ActionEventStep } from './action_event_types.js';
 import { type ActionEventDataUnion } from './action_event_data.js';
+/**
+ * `error.data.reason` on the `internal_error` a client reports when a
+ * response's `result` fails `spec.output` — a remote bug, distinct from the
+ * `invalid_params` / `validation_error` a caller's own bad input produces.
+ */
+export declare const ERROR_RESPONSE_OUTPUT_INVALID: "response_output_invalid";
 export type ActionEventChangeObserver<TMethod extends string = string> = (new_data: ActionEventDataUnion<TMethod>, old_data: ActionEventDataUnion<TMethod>, event: ActionEvent<TMethod>) => void;
 /**
  * Action event that manages the lifecycle of an action through its state machine.
@@ -48,7 +54,17 @@ export declare class ActionEvent<TMethod extends string = string, TPhase extends
      */
     set_data(new_data: ActionEventDataUnion<TMethod>): void;
     /**
-     * Parse input data according to the action's schema.
+     * Parse the event's payload against the action's schemas — `spec.input`
+     * for outgoing and incoming calls, `spec.output` for a received response.
+     *
+     * A received response's `result` is validated like any other inbound data,
+     * except that keys `spec.output` doesn't declare are dropped rather than
+     * refused (`safe_parse_dropping_unknown_keys`). On success `output` becomes
+     * the parsed value (brands, defaults, and transforms applied); on any
+     * other mismatch the event moves to `receive_error` with an
+     * `internal_error` whose `data.reason` is `ERROR_RESPONSE_OUTPUT_INVALID`
+     * (the remote broke its contract — not the caller's input), the same path
+     * an error response takes.
      *
      * @returns `this` for chaining with `handle_async` / `handle_sync`
      * @mutates this - transitions step from `initial` to `parsed` (or to
@@ -65,7 +81,7 @@ export declare class ActionEvent<TMethod extends string = string, TPhase extends
      * @throws Error if called from a step other than `parsed` (or `failed`,
      *   which no-ops). Handler-thrown `ThrownJsonrpcError` is caught and
      *   routed through error phases; other throws are wrapped as
-     *   `internal_error`.
+     *   `internal_error` carrying the thrown message (see `#to_handler_error`).
      */
     handle_async(): Promise<void>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAc,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAWtF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAcpF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAErD,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAE,CAEzE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IA8Cb;;;;;;;;;;OAUG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;;;;;;OAOG;IACH,WAAW,IAAI,IAAI;IAkCnB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAyKzD;AAGD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAmBrB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}
+{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAc,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAgBtF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAapF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAG,yBAAkC,CAAC;AAGhF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAErD,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAE,CAEzE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,IAAI,IAAI;IAiEb;;;;;;;;;;OAUG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCnC;;;;;;;OAOG;IACH,WAAW,IAAI,IAAI;IA8BnB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAgMzD;AAGD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAmBrB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}

package/dist/actions/action_event.js

@@ -8,10 +8,18 @@
  */
 import { z } from 'zod';
 import { create_uuid } from '@fuzdev/fuz_util/id.ts';
-import { create_jsonrpc_request, create_jsonrpc_response, create_jsonrpc_error_response, create_jsonrpc_notification, to_jsonrpc_params, to_jsonrpc_result, is_jsonrpc_error_response } from '../http/jsonrpc_helpers.js';
-import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_errors.js';
+import { to_error_message } from '@fuzdev/fuz_util/error.ts';
+import { create_jsonrpc_request, create_jsonrpc_response, create_jsonrpc_error_response, create_jsonrpc_notification, to_jsonrpc_params, is_jsonrpc_error_response } from '../http/jsonrpc_helpers.js';
+import { dev_only, jsonrpc_error_messages, ThrownJsonrpcError, UNKNOWN_ERROR_MESSAGE } from '../http/jsonrpc_errors.js';
+import { safe_parse_dropping_unknown_keys } from '../http/schema_helpers.js';
 import { ActionEventData } from './action_event_data.js';
 import { validate_step_transition, validate_phase_transition, should_validate_output, is_action_complete, create_initial_data, get_initial_phase, is_request_response, is_send_request_with_parsed_input, is_notification_send_with_parsed_input } from './action_event_helpers.js';
+/**
+ * `error.data.reason` on the `internal_error` a client reports when a
+ * response's `result` fails `spec.output` — a remote bug, distinct from the
+ * `invalid_params` / `validation_error` a caller's own bad input produces.
+ */
+export const ERROR_RESPONSE_OUTPUT_INVALID = 'response_output_invalid';
 /**
  * Action event that manages the lifecycle of an action through its state machine.
  */
@@ -65,7 +73,17 @@ export class ActionEvent {
         }
     }
     /**
-     * Parse input data according to the action's schema.
+     * Parse the event's payload against the action's schemas — `spec.input`
+     * for outgoing and incoming calls, `spec.output` for a received response.
+     *
+     * A received response's `result` is validated like any other inbound data,
+     * except that keys `spec.output` doesn't declare are dropped rather than
+     * refused (`safe_parse_dropping_unknown_keys`). On success `output` becomes
+     * the parsed value (brands, defaults, and transforms applied); on any
+     * other mismatch the event moves to `receive_error` with an
+     * `internal_error` whose `data.reason` is `ERROR_RESPONSE_OUTPUT_INVALID`
+     * (the remote broke its contract — not the caller's input), the same path
+     * an error response takes.
      *
      * @returns `this` for chaining with `handle_async` / `handle_sync`
      * @mutates this - transitions step from `initial` to `parsed` (or to
@@ -87,11 +105,25 @@ export class ActionEvent {
             this.#fail(this.#data.response.error);
             return this;
         }
-        // Input already validated in predecessor phase — skip re-parsing
-        if (this.#data.kind === 'request_response' &&
-            (this.#data.phase === 'receive_response' || this.#data.phase === 'send_response')) {
-            this.#transition_step('parsed');
-            return this;
+        if (this.#data.kind === 'request_response') {
+            // The remote's result is untrusted — validate it like inbound input,
+            // tolerating keys a newer remote added (`safe_parse_dropping_unknown_keys`).
+            // Input was already validated in the predecessor phase.
+            if (this.#data.phase === 'receive_response') {
+                const parsed = safe_parse_dropping_unknown_keys(this.spec.output, this.#data.output);
+                if (parsed.success) {
+                    this.#transition_step('parsed', { output: parsed.data });
+                }
+                else {
+                    this.#transition_to_error_phase('receive_error', jsonrpc_error_messages.internal_error(`response failed output validation for ${this.spec.method}: ${z.prettifyError(parsed.error)}`, { reason: ERROR_RESPONSE_OUTPUT_INVALID, validation_errors: parsed.error.issues }));
+                }
+                return this;
+            }
+            // Output was validated when the handler completed in `receive_request`.
+            if (this.#data.phase === 'send_response') {
+                this.#transition_step('parsed');
+                return this;
+            }
         }
         const parsed = this.spec.input.safeParse(this.#data.input);
         if (parsed.success) {
@@ -117,7 +149,7 @@ export class ActionEvent {
      * @throws Error if called from a step other than `parsed` (or `failed`,
      *   which no-ops). Handler-thrown `ThrownJsonrpcError` is caught and
      *   routed through error phases; other throws are wrapped as
-     *   `internal_error`.
+     *   `internal_error` carrying the thrown message (see `#to_handler_error`).
      */
     // TODO add timeout support
     // TODO add cancellation support
@@ -139,10 +171,7 @@ export class ActionEvent {
             this.#complete_handling(result);
         }
         catch (error) {
-            // Preserve ThrownJsonrpcError structure, wrap others as internal_error
-            const error_json = error instanceof ThrownJsonrpcError
-                ? { code: error.code, message: error.message, data: error.data }
-                : jsonrpc_error_messages.internal_error('unknown error');
+            const error_json = this.#to_handler_error(error);
             // If we're already in an error phase, transition to failed
             // Otherwise, transition to appropriate error phase
             if (this.#data.phase === 'send_error' || this.#data.phase === 'receive_error') {
@@ -189,10 +218,7 @@ export class ActionEvent {
             this.#complete_handling(result);
         }
         catch (error) {
-            // Preserve ThrownJsonrpcError structure, wrap others as internal_error
-            const error_json = error instanceof ThrownJsonrpcError
-                ? { code: error.code, message: error.message, data: error.data }
-                : jsonrpc_error_messages.internal_error('unknown error');
+            const error_json = this.#to_handler_error(error);
             this.#fail(error_json);
         }
     }
@@ -260,6 +286,23 @@ export class ActionEvent {
     #fail(error) {
         this.#transition_step('failed', { error });
     }
+    /**
+     * Normalize a handler throw. `ThrownJsonrpcError` keeps its code, message,
+     * and data; anything else becomes `internal_error` with the thrown message.
+     * When the error answers a remote caller (`receive_request` /
+     * `send_response`) the raw message is kept only in development — the same
+     * `dev_only` gate the server dispatch uses, so paths or secrets in an
+     * exception message never cross the wire in production.
+     */
+    #to_handler_error(error) {
+        if (error instanceof ThrownJsonrpcError) {
+            return { code: error.code, message: error.message, data: error.data };
+        }
+        const message = to_error_message(error) || UNKNOWN_ERROR_MESSAGE;
+        const answers_remote = this.#data.kind === 'request_response' &&
+            (this.#data.phase === 'receive_request' || this.#data.phase === 'send_response');
+        return jsonrpc_error_messages.internal_error(answers_remote ? dev_only(message) : message);
+    }
     /**
      * Determine which error phase to transition to based on current phase.
      */
@@ -371,8 +414,9 @@ export class ActionEvent {
         if (this.#data.error) {
             return create_jsonrpc_error_response(this.#data.request.id, this.#data.error);
         }
-        const result = to_jsonrpc_result(this.#data.output);
-        return create_jsonrpc_response(this.#data.request.id, result);
+        // any JSON value is a valid result; `undefined` (a handler that returned
+        // nothing) has no JSON form, so it goes out as `null`
+        return create_jsonrpc_response(this.#data.request.id, (this.#data.output ?? null));
     }
 }
 // TODO not sure about this helper's design/location (should it be internal to the class constructor? a static method?)

package/dist/actions/action_event_types.d.ts

@@ -26,6 +26,28 @@ export interface ActionEventEnvironment {
     readonly executor: ActionExecutor;
     lookup_action_handler: (method: string, phase: ActionEventPhase) => ((event: any) => any) | undefined;
     lookup_action_spec: (method: string) => ActionSpecUnion | undefined;
+    /**
+     * Where dispatch diagnostics go — failed sends, rejected or failing inbound
+     * notifications and requests. Unset falls back to `console_action_log`;
+     * `null` silences them.
+     */
     readonly log?: Logger | null;
 }
+/** The logging surface the action dispatch path uses. */
+export type ActionLog = Pick<Logger, 'error' | 'warn' | 'debug'>;
+/**
+ * Fallback log for environments that leave `log` unset: warnings and errors
+ * go to `console`, so a notification that fails to parse or a handler that
+ * throws is visible rather than silently dropped; per-message debug chatter
+ * is discarded. A plain `console` adapter rather than a `Logger` so it's safe
+ * in any runtime, the browser included.
+ */
+export declare const console_action_log: ActionLog;
+/**
+ * Resolve the log an environment's dispatch diagnostics go to.
+ *
+ * @returns the environment's `log`, `console_action_log` when it's unset, or
+ *   `null` when it's explicitly `null`
+ */
+export declare const resolve_action_log: (environment: ActionEventEnvironment) => ActionLog | null;
 //# sourceMappingURL=action_event_types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action_event_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEtF,eAAO,MAAM,cAAc;;;EAAkC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;;;;;EAAiE,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAS9D,eAAO,MAAM,6BAA6B,EAAE,MAAM,CACjD,eAAe,EACf,aAAa,CAAC,eAAe,CAAC,CAO9B,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAW1F,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAU5F,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,qBAAqB,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,KACnB,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC;IACvC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B"}
+{"version":3,"file":"action_event_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEtF,eAAO,MAAM,cAAc;;;EAAkC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;;;;;EAAiE,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAS9D,eAAO,MAAM,6BAA6B,EAAE,MAAM,CACjD,eAAe,EACf,aAAa,CAAC,eAAe,CAAC,CAO9B,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAW1F,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAU5F,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,qBAAqB,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,KACnB,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC;IACvC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAIhC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,sBAAsB,KAAG,SAAS,GAAG,IAChB,CAAC"}

package/dist/actions/action_event_types.js

@@ -42,3 +42,22 @@ export const action_event_phase_transitions = {
     receive: null,
     execute: null
 };
+/**
+ * Fallback log for environments that leave `log` unset: warnings and errors
+ * go to `console`, so a notification that fails to parse or a handler that
+ * throws is visible rather than silently dropped; per-message debug chatter
+ * is discarded. A plain `console` adapter rather than a `Logger` so it's safe
+ * in any runtime, the browser included.
+ */
+export const console_action_log = {
+    error: (...args) => console.error(...args),
+    warn: (...args) => console.warn(...args),
+    debug: () => { }
+};
+/**
+ * Resolve the log an environment's dispatch diagnostics go to.
+ *
+ * @returns the environment's `log`, `console_action_log` when it's unset, or
+ *   `null` when it's explicitly `null`
+ */
+export const resolve_action_log = (environment) => environment.log === undefined ? console_action_log : environment.log;

package/dist/actions/compile_action_registry.d.ts

@@ -26,7 +26,9 @@
  * - **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).
+ *   for parameterless methods), nor `z.void()` for output (a response
+ *   always carries a `result`, which clients validate against
+ *   `spec.output`; use `z.null()` for methods with nothing to return).
  * - **Duplicate method names** — JSON-RPC keys on `method`, so every
  *   spec in the array must declare a unique `method` regardless of
  *   kind / handler presence.
@@ -56,7 +58,7 @@ export interface ActionRegistryCompileResult {
  *
  * @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.
+ * @throws Error on biconditional violation, rate-limit/account-axis mismatch, JSON-RPC null-input or void-output, 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

@@ -1 +1 @@
-{"version":3,"file":"compile_action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/compile_action_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,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,2BA6CF,CAAC"}
+{"version":3,"file":"compile_action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/compile_action_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,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,2BAoDF,CAAC"}

package/dist/actions/compile_action_registry.js

@@ -26,7 +26,9 @@
  * - **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).
+ *   for parameterless methods), nor `z.void()` for output (a response
+ *   always carries a `result`, which clients validate against
+ *   `spec.output`; use `z.null()` for methods with nothing to return).
  * - **Duplicate method names** — JSON-RPC keys on `method`, so every
  *   spec in the array must declare a unique `method` regardless of
  *   kind / handler presence.
@@ -39,14 +41,14 @@
  * @module
  */
 import { assert_route_auth_acting_biconditional } from '../http/auth_shape.js';
-import { is_null_schema } from '../http/schema_helpers.js';
+import { is_null_schema, is_void_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.
+ * @throws Error on biconditional violation, rate-limit/account-axis mismatch, JSON-RPC null-input or void-output, or duplicate method.
  */
 export const compile_action_registry = (actions, ctx_label) => {
     const action_map = new Map();
@@ -77,6 +79,9 @@ export const compile_action_registry = (actions, ctx_label) => {
             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.`);
             }
+            if (is_void_schema(spec.output)) {
+                throw new Error(`${ctx} uses z.void() for output — a JSON-RPC response always carries a result, and clients validate it against spec.output, so no response could match. Use z.null() for methods with nothing to return.`);
+            }
             action_map.set(spec.method, { spec, handler: action.handler });
         }
     }