@fuzdev/fuz_app 0.50.0 → 0.52.0

package/dist/actions/action_event_helpers.d.ts

@@ -58,13 +58,39 @@ export declare const is_notification_send_with_parsed_input: <TMethod extends st
     step: "parsed" | "handling";
     input: unknown;
 };
+/**
+ * Validate that a step transition is legal per `ACTION_EVENT_STEP_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not a permitted transition
+ */
 export declare const validate_step_transition: (from: ActionEventStep, to: ActionEventStep) => void;
+/**
+ * Validate that `phase` is one of the phases allowed for `kind` per
+ * `ACTION_EVENT_PHASE_BY_KIND`.
+ *
+ * @throws Error if `phase` is not valid for `kind`
+ */
 export declare const validate_phase_for_kind: (kind: ActionKind, phase: ActionEventPhase) => void;
+/**
+ * Validate that a phase chain is legal per `ACTION_EVENT_PHASE_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not the permitted next phase (or `from` is terminal)
+ */
 export declare const validate_phase_transition: (from: ActionEventPhase, to: ActionEventPhase) => void;
 export declare const get_initial_phase: (kind: ActionKind, initiator: ActionInitiator, executor: ActionExecutor) => ActionEventPhase | null;
 export declare const should_validate_output: (kind: ActionKind, phase: ActionEventPhase) => boolean;
 export declare const is_action_complete: (data: ActionEventData) => boolean;
 export declare const create_initial_data: (kind: ActionKind, phase: ActionEventPhase, method: string, executor: ActionExecutor, input: unknown) => ActionEventData;
+/**
+ * Pull the terminal `Result` from an action event.
+ *
+ * `data.error` populated → error path (covers both explicit `failed` and
+ * the unhandled `receive_error` / `send_error` case where no handler was
+ * registered for the error phase). `step === 'handled'` → success path.
+ *
+ * @throws Error if the event is in a non-terminal state (programming error —
+ *   callers should check `is_action_complete` first)
+ */
 export declare const extract_action_result: (event: ActionEvent) => Result<{
     value: ActionEventData["output"];
 }, {

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

@@ -1 +1 @@
-{"version":3,"file":"action_event_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAC;AAEvD,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,cAAc,EAInB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACX,eAAe,EACf,8BAA8B,EAC9B,iCAAiC,EACjC,wBAAwB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAC,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAGnD,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAAkE,CAAC;AAE9E,eAAO,MAAM,sBAAsB,GAClC,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAwE,CAAC;AAEpF,eAAO,MAAM,aAAa,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,wBACnC,CAAC;AAG5B,eAAO,MAAM,eAAe,GAC3B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,cAAc,CAAA;CACA,CAAC;AAEnE,eAAO,MAAM,kBAAkB,GAC9B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,iBAAiB,CAAA;CACA,CAAC;AAEtE,eAAO,MAAM,gBAAgB,GAC5B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,eAAe,CAAA;CACA,CAAC;AAEpE,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,kBAAkB,CAAA;CACA,CAAC;AAEvE,eAAO,MAAM,oBAAoB,GAChC,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAiC,GAAG;IAAC,KAAK,EAAE,MAAM,CAAA;CACA,CAAC;AAE9D,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAiC,GAAG;IAAC,KAAK,EAAE,SAAS,CAAA;CACA,CAAC;AAEjE,eAAO,MAAM,UAAU,GACtB,MAAM,eAAe,KACnB,IAAI,IAAI,wBAAwB,GAAG;IAAC,KAAK,EAAE,SAAS,CAAA;CACA,CAAC;AAGxD,eAAO,MAAM,UAAU,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,SAAS,CAAA;CACrE,CAAC;AAEzB,eAAO,MAAM,SAAS,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,QAAQ,CAAA;CACpE,CAAC;AAExB,eAAO,MAAM,WAAW,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,UAAU,CAAA;CACtE,CAAC;AAE1B,eAAO,MAAM,UAAU,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,SAAS,CAAA;CACrE,CAAC;AAEzB,eAAO,MAAM,SAAS,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,QAAQ,CAAA;CACpE,CAAC;AAKxB,eAAO,MAAM,iCAAiC,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAChF,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,CAAC,OAAO,CAAC,GAAG;IACpD,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CACkE,CAAC;AAEnF,eAAO,MAAM,sCAAsC,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EACrF,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAiC,CAAC,OAAO,CAAC,GAAG;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CACuE,CAAC;AAGxF,eAAO,MAAM,wBAAwB,GAAI,MAAM,eAAe,EAAE,IAAI,eAAe,KAAG,IAIrF,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,MAAM,UAAU,EAAE,OAAO,gBAAgB,KAAG,IAInF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,MAAM,gBAAgB,EAAE,IAAI,gBAAgB,KAAG,IAKxF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC7B,MAAM,UAAU,EAChB,WAAW,eAAe,EAC1B,UAAU,cAAc,KACtB,gBAAgB,GAAG,IAWrB,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAM,UAAU,EAAE,OAAO,gBAAgB,KAAG,OAEpC,CAAC;AAEhD,eAAO,MAAM,kBAAkB,GAAI,MAAM,eAAe,KAAG,OAO1D,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC/B,MAAM,UAAU,EAChB,OAAO,gBAAgB,EACvB,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,OAAO,OAAO,KACZ,eAaD,CAAC;AAEH,eAAO,MAAM,qBAAqB,GACjC,OAAO,WAAW,KAChB,MAAM,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;CAAC,EAAE;IAAC,KAAK,EAAE,kBAAkB,CAAA;CAAC,CAuBxE,CAAC"}
+{"version":3,"file":"action_event_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_helpers.ts"],"names":[],"mappings":"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"}

package/dist/actions/action_event_helpers.js

@@ -27,17 +27,32 @@ export const is_failed = (data) => data.step === 'failed';
 // are created when transitioning from 'parsed' to 'handling'
 export const is_send_request_with_parsed_input = (data) => is_send_request(data) && (data.step === 'parsed' || data.step === 'handling');
 export const is_notification_send_with_parsed_input = (data) => is_notification_send(data) && (data.step === 'parsed' || data.step === 'handling');
-// Validation helpers
+/**
+ * Validate that a step transition is legal per `ACTION_EVENT_STEP_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not a permitted transition
+ */
 export const validate_step_transition = (from, to) => {
     if (!ACTION_EVENT_STEP_TRANSITIONS[from].includes(to)) {
         throw new Error(`Invalid step transition from '${from}' to '${to}'`);
     }
 };
+/**
+ * Validate that `phase` is one of the phases allowed for `kind` per
+ * `ACTION_EVENT_PHASE_BY_KIND`.
+ *
+ * @throws Error if `phase` is not valid for `kind`
+ */
 export const validate_phase_for_kind = (kind, phase) => {
     if (!ACTION_EVENT_PHASE_BY_KIND[kind].includes(phase)) {
         throw new Error(`Invalid phase '${phase}' for ${kind} action`);
     }
 };
+/**
+ * Validate that a phase chain is legal per `ACTION_EVENT_PHASE_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not the permitted next phase (or `from` is terminal)
+ */
 export const validate_phase_transition = (from, to) => {
     const expected = ACTION_EVENT_PHASE_TRANSITIONS[from];
     if (expected !== to) {
@@ -81,6 +96,16 @@ export const create_initial_data = (kind, phase, method, executor, input) => ({
     response: null,
     notification: null,
 });
+/**
+ * Pull the terminal `Result` from an action event.
+ *
+ * `data.error` populated → error path (covers both explicit `failed` and
+ * the unhandled `receive_error` / `send_error` case where no handler was
+ * registered for the error phase). `step === 'handled'` → success path.
+ *
+ * @throws Error if the event is in a non-terminal state (programming error —
+ *   callers should check `is_action_complete` first)
+ */
 export const extract_action_result = (event) => {
     const { data } = event;
     // `data.error` populated → error path. This covers two cases:

package/dist/actions/action_peer.d.ts

@@ -31,8 +31,25 @@ export declare class ActionPeer {
     readonly transports: Transports;
     default_send_options: Omit<ActionPeerSendOptions, 'signal'>;
     constructor(options: ActionPeerOptions);
+    /**
+     * Resolve a transport (per-call name → default name → registry default)
+     * and forward the message. Catches unexpected throws and converts them
+     * to JSON-RPC error responses — this method never throws.
+     *
+     * @returns the response envelope for requests, or `null` for successful
+     *   notifications (`JsonrpcErrorResponse` if the notification's transport
+     *   send failed)
+     */
     send(message: JsonrpcRequest, options?: ActionPeerSendOptions): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification, options?: ActionPeerSendOptions): Promise<JsonrpcErrorResponse | null>;
+    /**
+     * Dispatch an inbound JSON-RPC message — request, notification, or
+     * malformed envelope. Never throws; unexpected failures become
+     * JSON-RPC error responses.
+     *
+     * @returns response message for requests, `null` for notifications, or
+     *   an `invalid_request` error for malformed input
+     */
     receive(message: unknown): Promise<JsonrpcMessageFromServerToClient | null>;
 }
 //# sourceMappingURL=action_peer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action_peer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAC,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IAClE,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAKxB,oBAAoB,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;CAC7D;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;gBAEhD,OAAO,EAAE,iBAAiB;IAOhC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CjC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAyIjF"}
+{"version":3,"file":"action_peer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAC,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IAClE,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAKxB,oBAAoB,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;CAC7D;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;gBAEhD,OAAO,EAAE,iBAAiB;IAMtC;;;;;;;;OAQG;IAEG,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CvC;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAyIjF"}

package/dist/actions/action_peer.js

@@ -48,6 +48,14 @@ export class ActionPeer {
             return create_jsonrpc_error_response_from_thrown(to_jsonrpc_message_id(message), error);
         } // TODO finally?
     }
+    /**
+     * Dispatch an inbound JSON-RPC message — request, notification, or
+     * malformed envelope. Never throws; unexpected failures become
+     * JSON-RPC error responses.
+     *
+     * @returns response message for requests, `null` for notifications, or
+     *   an `invalid_request` error for malformed input
+     */
     async receive(message) {
         try {
             const result = await this.#receive_message(message);

package/dist/actions/action_registry.d.ts

@@ -1,7 +1,7 @@
 /**
  * `ActionRegistry` — query and filter utility over `ActionSpecUnion[]`.
  *
- * Vocabulary (set in API review III, see the `docs/` directory and the SAES quest):
+ * Vocabulary (see the `docs/` directory):
  * - `*_handled_*` — request_response specs the named side **receives**
  *   (so the named side owns the handler). Used by codegen to emit typed
  *   handler maps.
@@ -17,7 +17,7 @@
  *
  * Cache discipline: `spec_by_method` (Map) and the internal streams-target
  * set lazy-memoize because the Map is consulted per-RPC dispatch
- * (`frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
+ * (`actions/frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
  * streams set is rebuilt by two public getters. Array-returning getters
  * recompute on each call so callers can mutate the result freely
  * (`.sort()`, `.push(injected)` on a copy, etc.) without affecting the

package/dist/actions/action_registry.js

@@ -1,7 +1,7 @@
 /**
  * `ActionRegistry` — query and filter utility over `ActionSpecUnion[]`.
  *
- * Vocabulary (set in API review III, see the `docs/` directory and the SAES quest):
+ * Vocabulary (see the `docs/` directory):
  * - `*_handled_*` — request_response specs the named side **receives**
  *   (so the named side owns the handler). Used by codegen to emit typed
  *   handler maps.
@@ -17,7 +17,7 @@
  *
  * Cache discipline: `spec_by_method` (Map) and the internal streams-target
  * set lazy-memoize because the Map is consulted per-RPC dispatch
- * (`frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
+ * (`actions/frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
  * streams set is rebuilt by two public getters. Array-returning getters
  * recompute on each call so callers can mutate the result freely
  * (`.sort()`, `.push(injected)` on a copy, etc.) without affecting the

package/dist/actions/action_rpc.d.ts

@@ -132,6 +132,10 @@ export interface CreateRpcEndpointOptions {
  *
  * @param options - endpoint path, actions, and logger
  * @returns route specs (GET + POST) ready for `apply_route_specs`
+ * @throws Error if two actions share the same `spec.method` (registration-time
+ *   duplicate detection); also throws if any action's `spec.input` is
+ *   `z.null()` (JSON-RPC 2.0 §4.2 forbids `params: null` on the wire — use
+ *   `z.void()` for parameterless methods).
  */
 export declare const create_rpc_endpoint: (options: CreateRpcEndpointOptions) => Array<RouteSpec>;
 //# sourceMappingURL=action_rpc.d.ts.map

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;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,CAsQtF,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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAsQtF,CAAC"}

package/dist/actions/action_rpc.js

@@ -118,6 +118,10 @@ const check_action_auth = (auth, request_context, credential_type) => {
  *
  * @param options - endpoint path, actions, and logger
  * @returns route specs (GET + POST) ready for `apply_route_specs`
+ * @throws Error if two actions share the same `spec.method` (registration-time
+ *   duplicate detection); also throws if any action's `spec.input` is
+ *   `z.null()` (JSON-RPC 2.0 §4.2 forbids `params: null` on the wire — use
+ *   `z.void()` for parameterless methods).
  */
 export const create_rpc_endpoint = (options) => {
     const { path: endpoint_path, actions, log } = options;

package/dist/actions/action_spec.d.ts

@@ -3,7 +3,10 @@
  *
  * Extracted from zzz's action system. Action specs define method, kind,
  * auth, side effects, and input/output schemas. Bridge functions in
- * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
+ * `actions/action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
+ *
+ * @see `actions/action_rpc.ts` for the JSON-RPC dispatcher
+ * @see `actions/register_action_ws.ts` for the WebSocket dispatcher
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
  * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
@@ -59,6 +62,16 @@ export declare const ActionSpec: z.ZodObject<{
      * consumer-side concern.
      */
     streams: z.ZodOptional<z.ZodString>;
+    /**
+     * Error reason codes this action may surface via `error.data.reason` on
+     * 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
+     * import either side. Optional — actions that surface only standard
+     * transport errors leave it unset.
+     */
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
 }, z.core.$strict>;
 export type ActionSpec = z.infer<typeof ActionSpec>;
 export declare const RequestResponseActionSpec: z.ZodObject<{
@@ -73,6 +86,7 @@ export declare const RequestResponseActionSpec: z.ZodObject<{
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
     auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
         role: z.ZodString;
@@ -90,6 +104,7 @@ export declare const RemoteNotificationActionSpec: z.ZodObject<{
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"remote_notification">>;
     auth: z.ZodDefault<z.ZodNull>;
     side_effects: z.ZodDefault<z.ZodLiteral<true>>;
@@ -98,8 +113,8 @@ export declare const RemoteNotificationActionSpec: z.ZodObject<{
 }, z.core.$strict>;
 export type RemoteNotificationActionSpec = z.infer<typeof RemoteNotificationActionSpec>;
 /**
- * Local calls can wrap synchronous or asynchronous actions,
- * and are the escape hatch for remote APIs that do not support SAES.
+ * Local calls can wrap synchronous or asynchronous actions, and are the
+ * escape hatch for remote APIs that do not support SAES.
  */
 export declare const LocalCallActionSpec: z.ZodObject<{
     method: z.ZodString;
@@ -114,6 +129,7 @@ export declare const LocalCallActionSpec: z.ZodObject<{
     async: z.ZodBoolean;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"local_call">>;
     auth: z.ZodDefault<z.ZodNull>;
 }, z.core.$strict>;
@@ -130,6 +146,7 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
     auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
         role: z.ZodString;
@@ -145,6 +162,7 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"remote_notification">>;
     auth: z.ZodDefault<z.ZodNull>;
     side_effects: z.ZodDefault<z.ZodLiteral<true>>;
@@ -163,10 +181,12 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     async: z.ZodBoolean;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     kind: z.ZodDefault<z.ZodLiteral<"local_call">>;
     auth: z.ZodDefault<z.ZodNull>;
 }, z.core.$strict>]>;
 export type ActionSpecUnion = z.infer<typeof ActionSpecUnion>;
+/** Structural type guard for any `ActionSpecUnion` variant — checks `kind` is one of the three known values. */
 export declare const is_action_spec: (value: unknown) => value is ActionSpecUnion;
 export declare const ActionEventPhase: z.ZodEnum<{
     send_request: "send_request";

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

@@ -1 +1 @@
-{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/actions/action_spec.js

@@ -3,7 +3,10 @@
  *
  * Extracted from zzz's action system. Action specs define method, kind,
  * auth, side effects, and input/output schemas. Bridge functions in
- * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
+ * `actions/action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
+ *
+ * @see `actions/action_rpc.ts` for the JSON-RPC dispatcher
+ * @see `actions/register_action_ws.ts` for the WebSocket dispatcher
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
  * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
@@ -40,6 +43,16 @@ export const ActionSpec = z.strictObject({
      * consumer-side concern.
      */
     streams: z.string().optional(),
+    /**
+     * Error reason codes this action may surface via `error.data.reason` on
+     * 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
+     * import either side. Optional — actions that surface only standard
+     * transport errors leave it unset.
+     */
+    error_reasons: z.array(z.string()).readonly().optional(),
 });
 export const RequestResponseActionSpec = ActionSpec.extend({
     kind: z.literal('request_response').default('request_response'),
@@ -54,8 +67,8 @@ export const RemoteNotificationActionSpec = ActionSpec.extend({
     async: z.literal(true).default(true),
 });
 /**
- * Local calls can wrap synchronous or asynchronous actions,
- * and are the escape hatch for remote APIs that do not support SAES.
+ * Local calls can wrap synchronous or asynchronous actions, and are the
+ * escape hatch for remote APIs that do not support SAES.
  */
 export const LocalCallActionSpec = ActionSpec.extend({
     kind: z.literal('local_call').default('local_call'),
@@ -66,6 +79,7 @@ export const ActionSpecUnion = z.union([
     RemoteNotificationActionSpec,
     LocalCallActionSpec,
 ]);
+/** Structural type guard for any `ActionSpecUnion` variant — checks `kind` is one of the three known values. */
 export const is_action_spec = (value) => value !== null &&
     typeof value === 'object' &&
     'method' in value &&

package/dist/actions/action_types.d.ts

@@ -1,8 +1,8 @@
 /**
  * Shared type surface for the action system — context, handler, composable Action tuple.
  *
- * These types sit above `action_spec.ts` (pure Zod schemas) and below the
- * dispatchers (`register_action_ws.ts`, `action_rpc.ts`). Extracted so the
+ * 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.
  *

package/dist/actions/action_types.js

@@ -1,8 +1,8 @@
 /**
  * Shared type surface for the action system — context, handler, composable Action tuple.
  *
- * These types sit above `action_spec.ts` (pure Zod schemas) and below the
- * dispatchers (`register_action_ws.ts`, `action_rpc.ts`). Extracted so the
+ * 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.
  *

package/dist/actions/cancel.d.ts

@@ -14,7 +14,7 @@
  * handler). The handler exists for symmetry with other protocol actions
  * like `heartbeat_action`; the dispatcher never calls it. Consumers
  * spread `cancel_action` (or the `protocol_actions` bundle from
- * `./protocol.js`) into their server's `actions` array so `spec_by_method`
+ * `actions/protocol.ts`) 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 the cancel on
@@ -69,7 +69,7 @@ export declare const cancel_action_spec: {
 export declare const cancel_handler: () => void;
 /**
  * Protocol-action tuple — spread into the server's `actions` array (or via
- * `protocol_actions` from `./protocol.js`) so the dispatcher registers the
+ * `protocol_actions` from `actions/protocol.ts`) so the dispatcher registers the
  * spec for input validation and so `create_rpc_client` codegen sees the
  * method. The client doesn't need to call it directly;
  * `FrontendWebsocketClient.request({signal})` sends the cancel notification

package/dist/actions/cancel.js

@@ -14,7 +14,7 @@
  * handler). The handler exists for symmetry with other protocol actions
  * like `heartbeat_action`; the dispatcher never calls it. Consumers
  * spread `cancel_action` (or the `protocol_actions` bundle from
- * `./protocol.js`) into their server's `actions` array so `spec_by_method`
+ * `actions/protocol.ts`) 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 the cancel on
@@ -66,7 +66,7 @@ export const cancel_action_spec = {
 export const cancel_handler = () => { }; // eslint-disable-line @typescript-eslint/no-empty-function
 /**
  * Protocol-action tuple — spread into the server's `actions` array (or via
- * `protocol_actions` from `./protocol.js`) so the dispatcher registers the
+ * `protocol_actions` from `actions/protocol.ts`) so the dispatcher registers the
  * spec for input validation and so `create_rpc_client` codegen sees the
  * method. The client doesn't need to call it directly;
  * `FrontendWebsocketClient.request({signal})` sends the cancel notification

package/dist/actions/heartbeat.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared heartbeat action — a fuz_app protocol action carrying both a spec
  * and a handler in one tuple. Consumers spread `heartbeat_action` (or the
- * `protocol_actions` bundle from `./protocol.js`) into the server's
+ * `protocol_actions` bundle from `actions/protocol.ts`) into the server's
  * `actions` array so disconnect detection works identically across every
  * repo without per-consumer ping plumbing.
  *
@@ -39,7 +39,7 @@ export declare const heartbeat_action_spec: {
 export declare const heartbeat_handler: () => Record<string, never>;
 /**
  * Protocol-action tuple — spread into the server's `actions` array for
- * dispatch (or via `protocol_actions` from `./protocol.js`) so the
+ * dispatch (or via `protocol_actions` from `actions/protocol.ts`) so the
  * dispatcher resolves the heartbeat handler. The frontend-side spread
  * happens via `protocol_action_specs` — the client doesn't run the echo
  * handler, but the spec must be in `ActionRegistry` so `create_rpc_client`

package/dist/actions/heartbeat.js

@@ -1,7 +1,7 @@
 /**
  * Shared heartbeat action — a fuz_app protocol action carrying both a spec
  * and a handler in one tuple. Consumers spread `heartbeat_action` (or the
- * `protocol_actions` bundle from `./protocol.js`) into the server's
+ * `protocol_actions` bundle from `actions/protocol.ts`) into the server's
  * `actions` array so disconnect detection works identically across every
  * repo without per-consumer ping plumbing.
  *
@@ -38,7 +38,7 @@ export const heartbeat_action_spec = {
 export const heartbeat_handler = () => ({});
 /**
  * Protocol-action tuple — spread into the server's `actions` array for
- * dispatch (or via `protocol_actions` from `./protocol.js`) so the
+ * dispatch (or via `protocol_actions` from `actions/protocol.ts`) so the
  * dispatcher resolves the heartbeat handler. The frontend-side spread
  * happens via `protocol_action_specs` — the client doesn't run the echo
  * handler, but the spec must be in `ActionRegistry` so `create_rpc_client`

package/dist/actions/protocol.d.ts

@@ -7,7 +7,7 @@
  * fuz_app, not consumer domain logic. The split is intentional: the server
  * needs `{spec, handler}` tuples to drive dispatch; the frontend
  * `ActionRegistry` only stores specs. The codegen
- * `include_protocol_actions: false` default (in `action_codegen.ts`) is the
+ * `include_protocol_actions: false` default (in `actions/action_codegen.ts`) is the
  * third leg of this contract — protocol actions are excluded from
  * generated typed surfaces because consumers spread them in at
  * registration time.

package/dist/actions/protocol.js

@@ -7,7 +7,7 @@
  * fuz_app, not consumer domain logic. The split is intentional: the server
  * needs `{spec, handler}` tuples to drive dispatch; the frontend
  * `ActionRegistry` only stores specs. The codegen
- * `include_protocol_actions: false` default (in `action_codegen.ts`) is the
+ * `include_protocol_actions: false` default (in `actions/action_codegen.ts`) is the
  * third leg of this contract — protocol actions are excluded from
  * generated typed surfaces because consumers spread them in at
  * registration time.

package/dist/actions/register_action_ws.d.ts

@@ -157,12 +157,15 @@ export interface RegisterActionWsResult {
  * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
  *   already verified identity); `keeper` requires `daemon_token` credential
  *   type *and* the keeper role; role-based `{role}` requires the named role
- *   via `has_role`, matching the HTTP path in `action_rpc.ts`.
+ *   via `has_role`, matching the HTTP path in `actions/action_rpc.ts`.
  * - DEV mode validates handler output against the spec's `output` schema and
  *   warns on mismatches.
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
+ * @mutates options.app - registers a `GET path` route via `upgradeWebSocket`
+ * @mutates options.transport - on every message, adds/removes connections
+ *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export declare const register_action_ws: <TCtx extends BaseHandlerContext>(options: RegisterActionWsOptions<TCtx>) => RegisterActionWsResult;
 //# sourceMappingURL=register_action_ws.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAiBjD,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;;OAOG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAiBjD,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;;OAOG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}

package/dist/actions/register_action_ws.js

@@ -55,12 +55,15 @@ export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
  * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
  *   already verified identity); `keeper` requires `daemon_token` credential
  *   type *and* the keeper role; role-based `{role}` requires the named role
- *   via `has_role`, matching the HTTP path in `action_rpc.ts`.
+ *   via `has_role`, matching the HTTP path in `actions/action_rpc.ts`.
  * - DEV mode validates handler output against the spec's `output` schema and
  *   warns on mismatches.
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
+ * @mutates options.app - registers a `GET path` route via `upgradeWebSocket`
+ * @mutates options.transport - on every message, adds/removes connections
+ *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export const register_action_ws = (options) => {
     const { path, app, upgradeWebSocket, actions, extend_context, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;

package/dist/actions/register_ws_endpoint.d.ts

@@ -41,6 +41,9 @@ export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> exte
  * 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.
+ *
+ * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;
 //# sourceMappingURL=register_ws_endpoint.d.ts.map

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,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"}
+{"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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -26,6 +26,9 @@ import { register_action_ws, } from './register_action_ws.js';
  * 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.
+ *
+ * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export const register_ws_endpoint = (options) => {
     const { app, path, allowed_origins, required_role, log = new Logger('[ws]'), ...rest } = options;

package/dist/actions/request_tracker.svelte.d.ts

@@ -35,18 +35,26 @@ export declare class RequestTracker {
      * Track a new request with the given id.
      * @param id - the request id
      * @returns a deferred promise that will be resolved when the response is received
+     * @mutates this - inserts a `RequestTrackerItem` into `pending_requests`
+     *   and arms a timeout that auto-rejects after `request_timeout_ms`;
+     *   clears any prior timeout for the same id
      */
     track_request(id: JsonrpcRequestId): Deferred<JsonrpcResponseOrError>;
     /**
      * Resolve a pending request with the given response data.
      * @param id - the request id
      * @param response - the response data
+     * @mutates this - clears the timeout, marks status `'success'`,
+     *   resolves the deferred, and removes the entry from `pending_requests`
      */
     resolve_request(id: JsonrpcRequestId, response: JsonrpcResponseOrError): void;
     /**
      * Rejects a pending request with the given error.
      * @param id - the request id
      * @param error_message - the complete `JsonrpcErrorResponse` object
+     * @mutates this - clears the timeout, marks status `'failure'`,
+     *   rejects the deferred with a `ThrownJsonrpcError`, and removes the
+     *   entry from `pending_requests`
      */
     reject_request(id: JsonrpcRequestId, error_message: JsonrpcErrorResponse): void;
     /**
@@ -55,13 +63,18 @@ export declare class RequestTracker {
      */
     handle_message(message: any): void;
     /**
-     * Cancel a pending request.
+     * Cancel a pending request without rejecting its deferred — just
+     * cleanup. The caller's promise stays unsettled; pair with an external
+     * resolution if needed.
      * @param id - the request id
+     * @mutates this - clears the timeout and removes the entry from `pending_requests`
      */
     cancel_request(id: JsonrpcRequestId): void;
     /**
      * Cancel all pending requests.
      * @param reason - optional reason to include in rejection
+     * @mutates this - clears every timeout, marks each status `'failure'`,
+     *   rejects each deferred with `internal_error`, and empties `pending_requests`
      */
     cancel_all_requests(reason?: string): void;
 }