@fuzdev/fuz_app 0.50.0 → 0.52.0

package/dist/actions/CLAUDE.md

@@ -1,6 +1,6 @@
 # actions/ — SAES (Symmetric Action Event System)
 
-One declarative `ActionSpec` shape — `{method, kind, initiator, auth, side_effects, input, output, async, description}` — binds to three
+One declarative `ActionSpec` shape — `{method, kind, initiator, auth, side_effects, input, output, async, description, streams?, error_reasons?}` — binds to three
 transport surfaces (REST, JSON-RPC, WebSocket) with uniform DEV-only output
 validation and symmetric send/receive. This directory holds the spec types,
 registry, codegen helpers, both transport bridges, the single-endpoint RPC
@@ -47,6 +47,19 @@ Optional `streams?: string` names a companion `remote_notification` method
 emitted as request-scoped progress. Transport-agnostic handshake —
 registry-time validation that the named method exists is a consumer concern.
 
+Optional `error_reasons?: ReadonlyArray<string>` declares the reason codes a
+handler may surface via `error.data.reason`. Same precedent as `streams`:
+declarative metadata for consumers (codegen, UI form-state matching, docs)
+to read off the spec instead of scanning handler code. No runtime
+enforcement — drift between declared reasons and what handlers actually
+throw is caught per-module by source-scanning unit tests (see
+`../../test/auth/permit_offer_actions.error_reasons.test.ts`). Reuses
+the same `as const` string constants the handler throws (e.g.
+`ERROR_OFFER_*` from `../auth/permit_offer_action_specs.ts`,
+`ERROR_PERMIT_NOT_FOUND` from `../http/error_schemas.ts`) so call
+sites can import either side. Standard transport errors (validation,
+auth, rate-limit) stay implicit.
+
 Canonical spec shape: module-scope declaration with `satisfies` +
 `{method}_action_spec` naming, preserving the literal `method` type and
 dropping per-spec `*_METHOD` constants (readers dereference `.method` at
@@ -116,8 +129,8 @@ not the runtime):
 - `ImportBuilder` — tracks value / type / namespace imports; emits `import type` when every entry on a module is a type (tree-shaking). Namespace (`* as specs`) entries are emitted verbatim. Public surface: `add`, `add_type`, `add_many`, `add_types`, `build`, `preview`, `has_imports`, `import_count`, `clear`.
 - `get_executor_phases(spec, executor)` — phases a given executor (`'frontend' | 'backend'`) participates in for the spec. Deduplicates via `Set` (handles `initiator: 'both'` overlap).
 - `get_handler_return_type(spec, phase, imports, collections_path?)` — the TS type a phase handler must return; triggers the `ActionOutputs` import (sourced from `collections_path`, default `'./action_collections.js'`) as a side effect.
-- `generate_phase_handlers(spec, executor, imports, {action_event_type?, collections_path?})` — emits the typed handler-map fragment for one action; consumers compose these into `ActionHandlers` types.
-- `generate_actions_api_method_signature(spec, {sync_returns_value?})` — single source of truth for the typed `FrontendActionsApi` method shape. Threads `options?: RpcClientCallOptions` (`{signal?, transport_name?, queue?}`) onto every async method — `request_response`, `remote_notification`, and async `local_call` — and wraps the return in `Promise<Result<...>>`. Notifications were previously emitted as `=> void`, mismatching the runtime (`create_remote_notification_method` returns a Promise that resolves to `Result<{value: void}>`); regenerate consumer typed clients to pick up the corrected shape.
+- `generate_phase_handlers(spec, executor, imports, {action_event_type?, collections_path?})` — emits the typed handler-map fragment for one action; consumers compose these into `ActionHandlers` types. Returns `''` when the spec contributes no phases on the given executor (e.g. a backend-only `local_call` asked for `'frontend'`) so wrappers' `.filter(Boolean)` drops the row entirely instead of emitting a useless `${method}?: never` for a method that doesn't belong on this side.
+- `generate_actions_api_method_signature(spec, imports, {sync_returns_value?, collections_path?})` — single source of truth for the typed `FrontendActionsApi` method shape. Threads `options?: RpcClientCallOptions` (`{signal?, transport_name?, queue?}`) onto every async method — `request_response`, `remote_notification`, and async `local_call` — and wraps the return in `Promise<Result<...>>`. Registers exactly the imports the emitted line references on `imports` — `ActionInputs` only when the spec has input, `RpcClientCallOptions` only when async, `Result` / `JsonrpcErrorObject` only when the return wraps in `Result`. Mirrors the leaf-level pattern `get_handler_return_type` already follows so wrappers no longer pre-register imports a per-spec emit might not actually use.
 - `create_banner(origin_path)` — gen banner comment.
 - `to_action_spec_identifier(method)` / `to_action_spec_input_identifier` / `to_action_spec_output_identifier` — naming convention helpers (emit `foo_action_spec` / `foo_action_spec.input` / `foo_action_spec.output`).
 - `PROTOCOL_ACTION_METHODS` (+ `ProtocolActionMethod` type) — readonly tuple `['heartbeat', 'cancel']`. Pairs with `protocol_actions` / `protocol_action_specs` in `actions/protocol.ts` (the runtime bundles). Consumers spread when filtering backend `request_response` methods so dispatcher-owned protocol actions don't leak into `BackendRequestResponseMethod` / handler maps.

package/dist/actions/action_bridge.d.ts

@@ -49,7 +49,8 @@ export declare const derive_http_method: (side_effects: ActionSideEffects) => Ro
  * @param spec - the action spec (must have non-null `auth`)
  * @param options - HTTP-specific options (path, handler, optional overrides)
  * @returns a `RouteSpec` ready for `apply_route_specs`
- * @throws if `spec.auth` is null
+ * @throws Error if `spec.auth` is null (only `request_response` actions can
+ *   become routes; notifications and local calls cannot)
  */
 export declare const create_action_route_spec: (spec: ActionSpec, options: ActionRouteOptions) => RouteSpec;
 /**
@@ -60,6 +61,7 @@ export declare const create_action_route_spec: (spec: ActionSpec, options: Actio
  * @param spec - the action spec (must have `kind: 'remote_notification'`)
  * @param options - optional event-specific options (channel)
  * @returns an `EventSpec` ready for `create_validated_broadcaster`
+ * @throws Error if `spec.kind` is not `'remote_notification'`
  */
 export declare const create_action_event_spec: (spec: ActionSpec, options?: ActionEventOptions) => EventSpec;
 //# sourceMappingURL=action_bridge.d.ts.map

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

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

package/dist/actions/action_bridge.js

@@ -35,7 +35,8 @@ export const derive_http_method = (side_effects) => {
  * @param spec - the action spec (must have non-null `auth`)
  * @param options - HTTP-specific options (path, handler, optional overrides)
  * @returns a `RouteSpec` ready for `apply_route_specs`
- * @throws if `spec.auth` is null
+ * @throws Error if `spec.auth` is null (only `request_response` actions can
+ *   become routes; notifications and local calls cannot)
  */
 export const create_action_route_spec = (spec, options) => {
     if (spec.auth === null) {
@@ -63,6 +64,7 @@ export const create_action_route_spec = (spec, options) => {
  * @param spec - the action spec (must have `kind: 'remote_notification'`)
  * @param options - optional event-specific options (channel)
  * @returns an `EventSpec` ready for `create_validated_broadcaster`
+ * @throws Error if `spec.kind` is not `'remote_notification'`
  */
 export const create_action_event_spec = (spec, options) => {
     if (spec.kind !== 'remote_notification') {

package/dist/actions/action_codegen.d.ts

@@ -59,12 +59,17 @@ export declare class ImportBuilder {
      * Add a value import to be included in the generated code.
      * @param from - the module to import from
      * @param what - what to import (value)
+     * @returns `this` for chaining
+     * @mutates this - inserts into the internal `imports` map
      */
     add(from: string, what: string): this;
     /**
      * Add a type import to be included in the generated code.
      * @param from - the module to import from
      * @param what - what to import (type)
+     * @returns `this` for chaining
+     * @mutates this - inserts into the internal `imports` map (downgrade to
+     *   type is suppressed if already registered as a value)
      */
     add_type(from: string, what: string): this;
     /**
@@ -95,6 +100,9 @@ export declare class ImportBuilder {
     preview(): Array<string>;
     /**
      * Clear all imports.
+     *
+     * @returns `this` for chaining
+     * @mutates this - empties the internal `imports` map
      */
     clear(): this;
 }
@@ -118,9 +126,18 @@ export declare const get_handler_return_type: (spec: ActionSpecUnion, phase: Act
  * Generates the phase handlers for an action spec using the unified ActionEvent type
  * with the new phase/step type parameters.
  *
+ * Returns `''` when the spec contributes no phases on the given executor side
+ * (e.g. a backend-only `local_call` asked for `'frontend'`). Upstream wrappers
+ * compose blocks with `.filter(Boolean)` so empty entries are dropped from the
+ * generated handler map. The earlier shape was `${method}?: never`, which read
+ * as "calling this here is a type error" but in practice produced useless rows
+ * on `FrontendActionHandlers` for methods that don't belong on this side at
+ * all — drop the row instead so the typed surface only carries methods the
+ * executor actually handles.
+ *
  * @param options.action_event_type - custom type name to use instead of `ActionEvent`
  *   (consumers can define a narrowed type that carries typed input/output via their codegen maps)
- * @param options.collections_path - import path the side-effect `ActionOutputs` import
+ * @param options.collections_path - Import path the side-effect `ActionOutputs` import
  *   resolves to. Defaults to `'./action_collections.js'`.
  */
 export declare const generate_phase_handlers: (spec: ActionSpecUnion, executor: "frontend" | "backend", imports: ImportBuilder, options?: {
@@ -151,19 +168,28 @@ export declare const to_action_spec_output_identifier: (method: string) => strin
  * failure). Earlier emit shapes declared notifications as `=> void` —
  * regenerate consumer typed clients to pick up the corrected return.
  *
- * Consumers must import `ActionInputs`, `ActionOutputs`, `Result`,
- * `JsonrpcErrorObject`, and (for async) `RpcClientCallOptions` into the
- * generated module — the helper only emits the type references.
+ * Registers exactly the imports the emitted line references on `imports`:
+ * `ActionInputs` (when the spec has input), `ActionOutputs` (always),
+ * `RpcClientCallOptions` (async only), and `Result` + `JsonrpcErrorObject`
+ * (any return shape that wraps the value in `Result<{value}, {error}>` —
+ * every async method, plus sync `local_call` when `sync_returns_value:
+ * false`). Mirrors the leaf-level pattern `get_handler_return_type` already
+ * follows so wrappers no longer pre-register imports a per-spec emit might
+ * not actually use.
  *
  * @param spec - the action spec to emit
- * @param options.sync_returns_value - when true (default), sync local_call
+ * @param imports - import builder to register references on
+ * @param options.sync_returns_value - When true (default), sync `local_call`
  *   methods return the output value directly; when false they're wrapped in
  *   `Result<{value, error}>` like async methods. Set to `false` if your
- *   FrontendActionsApi treats every method uniformly.
+ *   `FrontendActionsApi` treats every method uniformly.
+ * @param options.collections_path - Import path that `ActionInputs` /
+ *   `ActionOutputs` resolve to. Defaults to `'./action_collections.js'`.
  * @returns one line like `foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;`
  */
-export declare const generate_actions_api_method_signature: (spec: ActionSpecUnion, options?: {
+export declare const generate_actions_api_method_signature: (spec: ActionSpecUnion, imports: ImportBuilder, options?: {
     sync_returns_value?: boolean;
+    collections_path?: string;
 }) => string;
 /** Discriminator for `generate_action_method_enums` — which method-set enums to emit. */
 export type ActionMethodEnumKind = 'all' | 'request_response' | 'remote_notification' | 'local_call' | 'frontend' | 'backend' | 'frontend_handled' | 'backend_handled' | 'broadcast';
@@ -300,8 +326,11 @@ export declare const generate_action_event_datas: (specs: ReadonlyArray<ActionSp
  * (e.g. omit additional methods alongside the default protocol-action
  * filter) via `method_filter`.
  *
- * Adds the `Result`, `JsonrpcErrorObject`, and `RpcClientCallOptions` type
- * imports plus `ActionInputs` / `ActionOutputs` (sourced from `collections_path`).
+ * Imports are registered by the leaf `generate_actions_api_method_signature`
+ * per emitted line — only what the spec set actually references shows up on
+ * `imports`. A spec set with no async methods skips `RpcClientCallOptions`;
+ * one with no inputs skips `ActionInputs`; sync `local_call` methods with
+ * `sync_returns_value: true` (the default) skip `Result` / `JsonrpcErrorObject`.
  *
  * The interface name is fixed at `FrontendActionsApi` — the symmetric counterpart
  * of `BackendActionsApi`. Earlier consumer-named variants (`MyActionsApi`,
@@ -347,7 +376,7 @@ export declare const generate_frontend_action_handlers: (specs: ReadonlyArray<Ac
  * Method signature shape today is `(input) => Promise<void>` — matches the
  * fire-and-forget runtime of `create_broadcast_api`. Generalizing per-kind
  * via `generate_actions_api_method_signature` is deferred until a second
- * backend runtime constructor lands (see SAES quest § API review III).
+ * backend runtime constructor lands.
  *
  * @param options.qualify_spec - per-spec qualified identifier callback for
  *   multi-source consumers. When set, the helper emits the callback's return
@@ -413,6 +442,11 @@ export interface SpecSource {
  * per-call callback wasn't enough; the import dance + dup-check was the
  * real boilerplate.
  *
+ * @throws Error if two sources contain the same method name (same-method
+ *   detection is the consumer's primary debugging signal). Also throws if
+ *   the returned `qualify_spec` is later called with a method not registered
+ *   in any source.
+ *
  * @example
  * ```ts
  * const sources = [
@@ -433,9 +467,6 @@ export interface SpecSource {
  *   });
  * };
  * ```
- *
- * @throws if two sources contain the same method name (same-method detection
- *   is the consumer's primary debugging signal).
  */
 export declare const create_namespace_qualifier: (sources: ReadonlyArray<SpecSource>, imports: ImportBuilder) => {
     qualify_spec: (spec: ActionSpecUnion) => string;

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

@@ -1 +1 @@
-{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"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"}

package/dist/actions/action_codegen.js

@@ -52,6 +52,8 @@ export class ImportBuilder {
      * Add a value import to be included in the generated code.
      * @param from - the module to import from
      * @param what - what to import (value)
+     * @returns `this` for chaining
+     * @mutates this - inserts into the internal `imports` map
      */
     add(from, what) {
         // Handle namespace imports specially
@@ -64,6 +66,9 @@ export class ImportBuilder {
      * Add a type import to be included in the generated code.
      * @param from - the module to import from
      * @param what - what to import (type)
+     * @returns `this` for chaining
+     * @mutates this - inserts into the internal `imports` map (downgrade to
+     *   type is suppressed if already registered as a value)
      */
     add_type(from, what) {
         return this.#add_import(from, what, 'type');
@@ -134,6 +139,9 @@ export class ImportBuilder {
     }
     /**
      * Clear all imports.
+     *
+     * @returns `this` for chaining
+     * @mutates this - empties the internal `imports` map
      */
     clear() {
         this.imports.clear();
@@ -278,16 +286,25 @@ export const get_handler_return_type = (spec, phase, imports, collections_path =
  * Generates the phase handlers for an action spec using the unified ActionEvent type
  * with the new phase/step type parameters.
  *
+ * Returns `''` when the spec contributes no phases on the given executor side
+ * (e.g. a backend-only `local_call` asked for `'frontend'`). Upstream wrappers
+ * compose blocks with `.filter(Boolean)` so empty entries are dropped from the
+ * generated handler map. The earlier shape was `${method}?: never`, which read
+ * as "calling this here is a type error" but in practice produced useless rows
+ * on `FrontendActionHandlers` for methods that don't belong on this side at
+ * all — drop the row instead so the typed surface only carries methods the
+ * executor actually handles.
+ *
  * @param options.action_event_type - custom type name to use instead of `ActionEvent`
  *   (consumers can define a narrowed type that carries typed input/output via their codegen maps)
- * @param options.collections_path - import path the side-effect `ActionOutputs` import
+ * @param options.collections_path - Import path the side-effect `ActionOutputs` import
  *   resolves to. Defaults to `'./action_collections.js'`.
  */
 export const generate_phase_handlers = (spec, executor, imports, options) => {
     const { method } = spec;
     const phases = get_executor_phases(spec, executor);
     if (phases.length === 0) {
-        return `${method}?: never`;
+        return '';
     }
     const action_event_type = options?.action_event_type ?? 'ActionEvent';
     const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
@@ -331,32 +348,52 @@ export const to_action_spec_output_identifier = (method) => `${to_action_spec_id
  * failure). Earlier emit shapes declared notifications as `=> void` —
  * regenerate consumer typed clients to pick up the corrected return.
  *
- * Consumers must import `ActionInputs`, `ActionOutputs`, `Result`,
- * `JsonrpcErrorObject`, and (for async) `RpcClientCallOptions` into the
- * generated module — the helper only emits the type references.
+ * Registers exactly the imports the emitted line references on `imports`:
+ * `ActionInputs` (when the spec has input), `ActionOutputs` (always),
+ * `RpcClientCallOptions` (async only), and `Result` + `JsonrpcErrorObject`
+ * (any return shape that wraps the value in `Result<{value}, {error}>` —
+ * every async method, plus sync `local_call` when `sync_returns_value:
+ * false`). Mirrors the leaf-level pattern `get_handler_return_type` already
+ * follows so wrappers no longer pre-register imports a per-spec emit might
+ * not actually use.
  *
  * @param spec - the action spec to emit
- * @param options.sync_returns_value - when true (default), sync local_call
+ * @param imports - import builder to register references on
+ * @param options.sync_returns_value - When true (default), sync `local_call`
  *   methods return the output value directly; when false they're wrapped in
  *   `Result<{value, error}>` like async methods. Set to `false` if your
- *   FrontendActionsApi treats every method uniformly.
+ *   `FrontendActionsApi` treats every method uniformly.
+ * @param options.collections_path - Import path that `ActionInputs` /
+ *   `ActionOutputs` resolve to. Defaults to `'./action_collections.js'`.
  * @returns one line like `foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;`
  */
-export const generate_actions_api_method_signature = (spec, options) => {
+export const generate_actions_api_method_signature = (spec, imports, options) => {
     const sync_returns_value = options?.sync_returns_value ?? true;
+    const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
     const innermost_type_name = zod_get_base_type(spec.input);
     const has_input = innermost_type_name !== 'null' && innermost_type_name !== 'void';
     const input_param = has_input
         ? `input${spec.input.safeParse(undefined).success ? '?' : ''}: ActionInputs['${spec.method}']`
         : 'input?: void';
+    if (has_input)
+        imports.add_type(collections_path, 'ActionInputs');
+    imports.add_type(collections_path, 'ActionOutputs');
     const is_async = spec.kind === 'request_response' || spec.kind === 'remote_notification' || spec.async;
     const options_param = is_async ? ', options?: RpcClientCallOptions' : '';
+    if (is_async) {
+        imports.add_type('@fuzdev/fuz_app/actions/rpc_client.js', 'RpcClientCallOptions');
+    }
     const result_return = `Result<{value: ActionOutputs['${spec.method}']}, {error: JsonrpcErrorObject}>`;
     const return_type = is_async
         ? `Promise<${result_return}>`
         : sync_returns_value
             ? `ActionOutputs['${spec.method}']`
             : result_return;
+    const wraps_in_result = is_async || !sync_returns_value;
+    if (wraps_in_result) {
+        imports.add_type('@fuzdev/fuz_util/result.js', 'Result');
+        imports.add_type('@fuzdev/fuz_app/http/jsonrpc.js', 'JsonrpcErrorObject');
+    }
     return `${spec.method}: (${input_param}${options_param}) => ${return_type};`;
 };
 // --------------------------------------------------------------------------
@@ -711,8 +748,11 @@ ${lines.join('\n')}
  * (e.g. omit additional methods alongside the default protocol-action
  * filter) via `method_filter`.
  *
- * Adds the `Result`, `JsonrpcErrorObject`, and `RpcClientCallOptions` type
- * imports plus `ActionInputs` / `ActionOutputs` (sourced from `collections_path`).
+ * Imports are registered by the leaf `generate_actions_api_method_signature`
+ * per emitted line — only what the spec set actually references shows up on
+ * `imports`. A spec set with no async methods skips `RpcClientCallOptions`;
+ * one with no inputs skips `ActionInputs`; sync `local_call` methods with
+ * `sync_returns_value: true` (the default) skip `Result` / `JsonrpcErrorObject`.
  *
  * The interface name is fixed at `FrontendActionsApi` — the symmetric counterpart
  * of `BackendActionsApi`. Earlier consumer-named variants (`MyActionsApi`,
@@ -738,14 +778,10 @@ export const generate_frontend_actions_api = (specs, imports, options) => {
         return `${interface_doc}
 export interface FrontendActionsApi {}`;
     }
-    const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
-    imports.add_type('@fuzdev/fuz_util/result.js', 'Result');
-    imports.add_type('@fuzdev/fuz_app/http/jsonrpc.js', 'JsonrpcErrorObject');
-    imports.add_type('@fuzdev/fuz_app/actions/rpc_client.js', 'RpcClientCallOptions');
-    imports.add_types(collections_path, 'ActionInputs', 'ActionOutputs');
     const lines = filtered
-        .map((spec) => generate_actions_api_method_signature(spec, {
+        .map((spec) => generate_actions_api_method_signature(spec, imports, {
         sync_returns_value: options?.sync_returns_value,
+        collections_path: options?.collections_path,
     }))
         .map((line) => `\t${line}`)
         .join('\n');
@@ -811,7 +847,7 @@ ${lines};
  * Method signature shape today is `(input) => Promise<void>` — matches the
  * fire-and-forget runtime of `create_broadcast_api`. Generalizing per-kind
  * via `generate_actions_api_method_signature` is deferred until a second
- * backend runtime constructor lands (see SAES quest § API review III).
+ * backend runtime constructor lands.
  *
  * @param options.qualify_spec - per-spec qualified identifier callback for
  *   multi-source consumers. When set, the helper emits the callback's return
@@ -908,6 +944,11 @@ export type ${type_name} = {
  * per-call callback wasn't enough; the import dance + dup-check was the
  * real boilerplate.
  *
+ * @throws Error if two sources contain the same method name (same-method
+ *   detection is the consumer's primary debugging signal). Also throws if
+ *   the returned `qualify_spec` is later called with a method not registered
+ *   in any source.
+ *
  * @example
  * ```ts
  * const sources = [
@@ -928,9 +969,6 @@ export type ${type_name} = {
  *   });
  * };
  * ```
- *
- * @throws if two sources contain the same method name (same-method detection
- *   is the consumer's primary debugging signal).
  */
 export const create_namespace_qualifier = (sources, imports) => {
     const method_to_ns = new Map();

package/dist/actions/action_event.d.ts

@@ -33,22 +33,60 @@ export declare class ActionEvent<TMethod extends string = string, TPhase extends
     };
     constructor(environment: ActionEventEnvironment, spec: ActionSpecUnion, data: ActionEventDataUnion<TMethod>);
     toJSON(): ActionEventDataUnion<TMethod>;
+    /**
+     * Subscribe a listener fired on every `data` transition.
+     *
+     * @param listener - called with `(new_data, old_data, event)` after each mutation
+     * @returns unsubscribe function
+     * @mutates this - adds `listener` to the internal observer set
+     */
     observe(listener: ActionEventChangeObserver<TMethod>): () => void;
+    /**
+     * Replace the event's `data` and notify observers.
+     *
+     * @mutates this - sets `data` and fires every registered observer in insertion order
+     */
     set_data(new_data: ActionEventDataUnion<TMethod>): void;
     /**
      * Parse input data according to the action's schema.
+     *
+     * @returns `this` for chaining with `handle_async` / `handle_sync`
+     * @mutates this - transitions step from `initial` to `parsed` (or to
+     *   `failed` / `receive_error` on validation or response error)
+     * @throws Error if called from a step other than `initial`
      */
     parse(): this;
     /**
      * Execute the handler for the current phase.
+     *
+     * @mutates this - transitions step `parsed → handling → handled`, or to
+     *   `failed` / `send_error` / `receive_error` on handler throw. No-op
+     *   when already `failed`.
+     * @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`.
      */
     handle_async(): Promise<void>;
     /**
-     * Execute handler synchronously (only for sync local_call actions).
+     * Execute handler synchronously (only for sync `local_call` actions).
+     *
+     * @mutates this - transitions step `parsed → handling → handled`, or to
+     *   `failed` on handler throw. No-op when already `failed`.
+     * @throws Error if the spec is not a sync `local_call`, or if called
+     *   from a step other than `parsed` (or `failed`, which no-ops).
      */
     handle_sync(): void;
     /**
      * Transition to a new phase.
+     *
+     * @param phase - the next phase to transition into
+     * @mutates this - replaces `data` with a fresh phase-initial record,
+     *   carrying forward `request` / `response` / `error` / `output` as
+     *   appropriate for the kind/phase pair
+     * @throws Error if called from a step other than `handled` (or
+     *   `failed`, which no-ops), or if the phase transition is illegal for
+     *   the current phase
      */
     transition(phase: ActionEventPhase): void;
     is_complete(): boolean;
@@ -59,10 +97,15 @@ export declare class ActionEvent<TMethod extends string = string, TPhase extends
 }
 /**
  * Create an action event from a spec and initial input.
+ *
+ * @throws Error if `initial_phase` is omitted and the executor cannot
+ *   initiate the action (per `spec.initiator`)
  */
 export declare const create_action_event: <TMethod extends string = string>(environment: ActionEventEnvironment, spec: ActionSpecUnion, input: unknown, initial_phase?: ActionEventPhase) => ActionEvent<TMethod>;
 /**
  * Reconstruct an action event from serialized JSON data.
+ *
+ * @throws Error if the JSON's `method` field has no spec registered in `environment`
  */
 export declare const create_action_event_from_json: <TMethod extends string = string>(json: ActionEventDataUnion<TMethod>, environment: ActionEventEnvironment) => ActionEvent<TMethod>;
 export declare const parse_action_event: (raw_json: unknown, environment: ActionEventEnvironment) => ActionEvent;

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,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAclF,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;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC;IAEnD,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,KAAK,IAAI,IAAI;IA8Cb;;OAEG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;OAEG;IACH,WAAW,IAAI,IAAI;IAkCnB;;OAEG;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;;GAEG;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,CAiBrB,CAAC;AAEF;;GAEG;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;AAKH,OAAO,KAAK,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAclF,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;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC;IAEnD,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;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,CAiBrB,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

@@ -40,10 +40,22 @@ export class ActionEvent {
     }
     // TODO rethink the reactivity of this class, maybe just use `$state` or `$state.raw`?
     // does that have any negative implications when used on the backend?
+    /**
+     * Subscribe a listener fired on every `data` transition.
+     *
+     * @param listener - called with `(new_data, old_data, event)` after each mutation
+     * @returns unsubscribe function
+     * @mutates this - adds `listener` to the internal observer set
+     */
     observe(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
+    /**
+     * Replace the event's `data` and notify observers.
+     *
+     * @mutates this - sets `data` and fires every registered observer in insertion order
+     */
     set_data(new_data) {
         const old_data = this.#data;
         this.#data = new_data;
@@ -54,6 +66,11 @@ export class ActionEvent {
     }
     /**
      * Parse input data according to the action's schema.
+     *
+     * @returns `this` for chaining with `handle_async` / `handle_sync`
+     * @mutates this - transitions step from `initial` to `parsed` (or to
+     *   `failed` / `receive_error` on validation or response error)
+     * @throws Error if called from a step other than `initial`
      */
     parse() {
         if (this.#data.step !== 'initial') {
@@ -93,6 +110,14 @@ export class ActionEvent {
     }
     /**
      * Execute the handler for the current phase.
+     *
+     * @mutates this - transitions step `parsed → handling → handled`, or to
+     *   `failed` / `send_error` / `receive_error` on handler throw. No-op
+     *   when already `failed`.
+     * @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`.
      */
     // TODO add timeout support
     // TODO add cancellation support
@@ -136,7 +161,12 @@ export class ActionEvent {
         }
     }
     /**
-     * Execute handler synchronously (only for sync local_call actions).
+     * Execute handler synchronously (only for sync `local_call` actions).
+     *
+     * @mutates this - transitions step `parsed → handling → handled`, or to
+     *   `failed` on handler throw. No-op when already `failed`.
+     * @throws Error if the spec is not a sync `local_call`, or if called
+     *   from a step other than `parsed` (or `failed`, which no-ops).
      */
     handle_sync() {
         if (this.spec.kind !== 'local_call' || this.spec.async) {
@@ -168,6 +198,14 @@ export class ActionEvent {
     }
     /**
      * Transition to a new phase.
+     *
+     * @param phase - the next phase to transition into
+     * @mutates this - replaces `data` with a fresh phase-initial record,
+     *   carrying forward `request` / `response` / `error` / `output` as
+     *   appropriate for the kind/phase pair
+     * @throws Error if called from a step other than `handled` (or
+     *   `failed`, which no-ops), or if the phase transition is illegal for
+     *   the current phase
      */
     transition(phase) {
         if (this.#data.step === 'failed') {
@@ -340,6 +378,9 @@ export class ActionEvent {
 // TODO not sure about this helper's design/location (should it be internal to the class constructor? a static method?)
 /**
  * Create an action event from a spec and initial input.
+ *
+ * @throws Error if `initial_phase` is omitted and the executor cannot
+ *   initiate the action (per `spec.initiator`)
  */
 export const create_action_event = (environment, spec, input, initial_phase) => {
     const phase = initial_phase || get_initial_phase(spec.kind, spec.initiator, environment.executor);
@@ -351,6 +392,8 @@ export const create_action_event = (environment, spec, input, initial_phase) =>
 };
 /**
  * Reconstruct an action event from serialized JSON data.
+ *
+ * @throws Error if the JSON's `method` field has no spec registered in `environment`
  */
 export const create_action_event_from_json = (json, environment) => {
     const spec = environment.lookup_action_spec(json.method);