@fuzdev/fuz_app 0.51.0 → 0.53.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
@@ -19,10 +19,10 @@ IMPORTANT: Every exported Zod schema is paired with a same-named `z.infer`
 type export. When adding new schemas, keep the pair invariant — it is the
 convention callers rely on for type imports.
 
-NOTE: The system is marked `@action-system-review` — `action_registry`,
-`action_codegen`, and `action_bridge` still hold partial/stub API. Non-obvious
-future-churn sites are flagged in source. Treat the core bridge + RPC endpoint
-as stable; registry getters and codegen shapes may move.
+NOTE: `ActionRegistry` keeps a few pre-built getters (auth filters,
+initiator-direction filters) that codegen doesn't consume today — kept
+low-cost for future filtering. Bridge, RPC endpoint, and per-derivation
+codegen helpers are post-SAES-RPC-closeout stable.
 
 ## Action specs (`action_spec.ts`)
 
@@ -47,6 +47,36 @@ 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.
+
+Optional `rate_limit?: 'ip' | 'account' | 'both'` opts the action into
+the dispatcher's per-action rate-limit hook. Same hook fires on the HTTP
+RPC dispatcher (`create_rpc_endpoint`) and the WebSocket dispatcher
+(`register_action_ws`) — one budget per action, not per transport.
+`'ip'` keys on the resolved client IP; `'account'` keys on
+`request_context.actor.id` (post-auth) and is rejected at registration
+when paired with `auth: 'public'` (no actor to key on); `'both'` runs
+both checks. **Throttle-requests semantics** — every invocation records,
+regardless of outcome (different from REST login's throttle-failures
+that resets on success). The motivating threat is admin mutation oracles
+(`invite_create` account-existence probe) where the _successful_
+invocation is the threat. Limiters are configured at server-assembly
+time via `AppServerOptions.action_ip_rate_limiter` /
+`action_account_rate_limiter` and threaded into both dispatchers
+automatically; consumers wiring `register_action_ws` directly forward
+the same limiters from `AppServerContext`.
+
 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
@@ -80,8 +110,11 @@ The remaining asymmetry today is runtime: there is no
 `create_backend_rpc_client` and `create_broadcast_api` returns
 `Promise<void>` (fire-and-forget broadcast) rather than the
 `Promise<Result<{value}, {error}>>` shape `FrontendActionsApi` methods
-return. Closing those gaps is captured in the SAES quest's API
-review III deferred set — wait for a second backend runtime case.
+return. Closing those gaps is on the deferred follow-up set in the
+[SAES RPC closeout](https://github.com/ryanatkn/grimoire/blob/main/quests/HISTORY.md#saes-rpc-direction-2026-04)
+(grimoire `lore/fuz_app/TODO.md` § Future Directions tracks the symmetric
+backend signature, backend RPC client, and local-call symmetry items) —
+wait for a second backend runtime case.
 
 `ActionRegistry(specs)` is a query/filter wrapper over `ActionSpecUnion[]`.
 Codegen-used getter groups:
@@ -105,8 +138,8 @@ Codegen-used getter groups:
   `request_response` join): `backend_initiated_specs`,
   `backend_initiated_methods`.
 
-Other getters (auth, initiator-direction) are pre-built stubs flagged
-`@action-system-review`.
+Other getters (auth filters, initiator-direction filters) are pre-built
+API surface unused by codegen today.
 
 `action_codegen.ts` provides gen helpers (used by consumer `*.gen.ts` files,
 not the runtime):
@@ -176,7 +209,7 @@ and `FrontendActionHandlers`.
 - `generate_action_event_datas(specs, imports, {same_file?, collections_path?, include_protocol_actions?})` — `ActionEventDatas` interface; per-spec variant by kind (`ActionEventRequestResponseData` / `ActionEventRemoteNotificationData` / `ActionEventLocalCallData`). `same_file` (default `true`) is the file-layout switch: when `true`, assumes `ActionInputs` / `ActionOutputs` are in the same module and adds no import (the zzz pattern); when `false`, adds the type imports from `collections_path` (default `'./action_collections.js'`). `collections_path` alone is a no-op — the surprising omit-vs-default behavior of earlier versions has been replaced.
 - `generate_frontend_actions_api(specs, imports, {interface_name?, method_filter?, collections_path?, sync_returns_value?, include_protocol_actions?})` — emits the typed `FrontendActionsApi` interface (configurable via `interface_name`, default `'FrontendActionsApi'`). One method signature per spec via `generate_actions_api_method_signature`. Protocol actions filtered by default; `method_filter: (spec) => boolean` runs after the protocol-action filter. Renamed from `generate_actions_api` in API review III to make the side-of-the-wire intent visible at every consumer site.
 - `generate_frontend_action_handlers(specs, imports, {collections_path?, include_protocol_actions?})` — `FrontendActionHandlers` interface (Tier 2 only — wraps `generate_phase_handlers` with `action_event_type: 'TypedActionEvent'`). Pair with `generate_typed_action_event_alias`.
-- `generate_backend_actions_api(specs, imports, {interface_name?, spec_array_name?, specs_module?, collections_path?, qualify_spec?, include_protocol_actions?})` — `BackendActionsApi` interface AND `broadcast_action_specs: ReadonlyArray<ActionSpecUnion>` array (both names configurable). Filter: `kind === 'remote_notification' && initiator !== 'frontend'`, with `streams`-target methods (request-scoped progress notifications invoked via `ctx.notify`) excluded — the discriminator is `ActionSpec.streams`, not a manual list. Adds `ActionInputs` (from `collections_path`) + `ActionSpecUnion`, plus `* as specs` from `specs_module` unless `qualify_spec` is set. Method shape today is `(input) => Promise<void>` (matches `create_broadcast_api`'s fire-and-forget runtime); generalizing to per-kind shapes via `generate_actions_api_method_signature` is deferred until a second backend runtime constructor lands (see SAES quest § API review III deferred set).
+- `generate_backend_actions_api(specs, imports, {interface_name?, spec_array_name?, specs_module?, collections_path?, qualify_spec?, include_protocol_actions?})` — `BackendActionsApi` interface AND `broadcast_action_specs: ReadonlyArray<ActionSpecUnion>` array (both names configurable). Filter: `kind === 'remote_notification' && initiator !== 'frontend'`, with `streams`-target methods (request-scoped progress notifications invoked via `ctx.notify`) excluded — the discriminator is `ActionSpec.streams`, not a manual list. Adds `ActionInputs` (from `collections_path`) + `ActionSpecUnion`, plus `* as specs` from `specs_module` unless `qualify_spec` is set. Method shape today is `(input) => Promise<void>` (matches `create_broadcast_api`'s fire-and-forget runtime); generalizing to per-kind shapes via `generate_actions_api_method_signature` is deferred until a second backend runtime constructor lands (tracked in grimoire `lore/fuz_app/TODO.md` § Future Directions, _Symmetric backend signature shape_).
 - `generate_backend_action_handlers_map(imports, options?)` — emits the `BackendActionHandlers` mapped type (`{[K in BackendRequestResponseMethod]: (input: ActionInputs[K], ctx: BackendHandlerContext) => ActionOutputs[K] | Promise<ActionOutputs[K]>}`). Replaces the hand-maintained `Exclude<>` + parallel mapped-type pattern (zzz had this at `zzz/src/lib/server/zzz_action_handlers.ts:42-66`). Configurable type name, method enum name, and context type name; configurable `collections_path` / `metatypes_path` for the type imports.
 
 ### Wrapper + multi-source helper

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

@@ -22,9 +22,6 @@ export type ProtocolActionMethod = (typeof PROTOCOL_ACTION_METHODS)[number];
  * });
  */
 export declare const is_protocol_action_method: (method: string) => method is ProtocolActionMethod;
-/**
- * Represents an import item with its kind (type, value, or namespace).
- */
 interface ImportItem {
     name: string;
     kind: 'type' | 'value' | 'namespace';
@@ -56,51 +53,41 @@ export declare class ImportBuilder {
     #private;
     imports: Map<string, Map<string, ImportItem>>;
     /**
-     * Add a value import to be included in the generated code.
-     * @param from - the module to import from
-     * @param what - what to import (value)
+     * Add a value import. Accepts `* as ns` strings as namespace imports.
+     *
+     * @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)
+     * Add a type-only import.
+     *
+     * @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;
-    /**
-     * Add multiple value imports from the same module.
-     */
     add_many(from: string, ...items: Array<string>): this;
-    /**
-     * Add multiple type imports from the same module.
-     */
     add_types(from: string, ...items: Array<string>): this;
     /**
-     * Generate the import statements.
-     * If all imports from a module are types, uses `import type` syntax.
+     * Generate the import statements. When every import from a module is a
+     * type, emits `import type {…}` so the whole statement disappears at
+     * compile time.
      */
     build(): string;
-    /**
-     * Check if the builder has any imports.
-     */
     has_imports(): boolean;
-    /**
-     * Get the number of import statements that will be generated.
-     */
     get import_count(): number;
-    /**
-     * Preview what imports will be generated (useful for debugging).
-     * @returns array of import statement strings
-     */
+    /** Build the same statement list as `build` without joining — for inspection in tests. */
     preview(): Array<string>;
     /**
      * Clear all imports.
+     *
+     * @returns `this` for chaining
+     * @mutates this - empties the internal `imports` map
      */
     clear(): this;
 }
-/**
- * Determines which phases an executor can handle based on the action spec.
- */
+/** Phases an executor can handle for the given spec — kind + initiator → set of phases. */
 export declare const get_executor_phases: (spec: ActionSpecUnion, executor: "frontend" | "backend") => Array<ActionEventPhase>;
 /** Default `collections_path` — every consumer's gen producers point at the sibling `action_collections.js`. */
 export declare const DEFAULT_COLLECTIONS_PATH = "./action_collections.js";
@@ -129,16 +116,14 @@ export declare const get_handler_return_type: (spec: ActionSpecUnion, phase: Act
  *
  * @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?: {
     action_event_type?: string;
     collections_path?: string;
 }) => string;
-/**
- * Creates a file banner comment.
- */
+/** "DO NOT EDIT" banner naming the gen producer. */
 export declare const create_banner: (origin_path: string) => string;
 export declare const to_action_spec_identifier: (method: string) => string;
 export declare const to_action_spec_input_identifier: (method: string) => string;
@@ -169,13 +154,11 @@ export declare const to_action_spec_output_identifier: (method: string) => strin
  * follows so wrappers no longer pre-register imports a per-spec emit might
  * not actually use.
  *
- * @param spec - the action spec to emit
- * @param imports - import builder to register references on
- * @param options.sync_returns_value - when true (default), sync local_call
+ * @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.
- * @param options.collections_path - import path that `ActionInputs` /
+ *   `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<...>>;`
  */
@@ -368,7 +351,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
@@ -434,6 +417,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 = [
@@ -454,9 +442,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

@@ -49,9 +49,10 @@ export const is_protocol_action_method = (method) => PROTOCOL_METHOD_SET.has(met
 export class ImportBuilder {
     imports = new Map();
     /**
-     * Add a value import to be included in the generated code.
-     * @param from - the module to import from
-     * @param what - what to import (value)
+     * Add a value import. Accepts `* as ns` strings as namespace imports.
+     *
+     * @returns `this` for chaining
+     * @mutates this - inserts into the internal `imports` map
      */
     add(from, what) {
         // Handle namespace imports specially
@@ -61,34 +62,27 @@ export class ImportBuilder {
         return this.#add_import(from, what, 'value');
     }
     /**
-     * Add a type import to be included in the generated code.
-     * @param from - the module to import from
-     * @param what - what to import (type)
+     * Add a type-only import.
+     *
+     * @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');
     }
-    /**
-     * Add multiple value imports from the same module.
-     */
     add_many(from, ...items) {
         for (const item of items) {
             this.add(from, item);
         }
         return this;
     }
-    /**
-     * Add multiple type imports from the same module.
-     */
     add_types(from, ...items) {
         for (const item of items) {
             this.add_type(from, item);
         }
         return this;
     }
-    /**
-     * Internal method to add an import with its kind.
-     */
     #add_import(from, name, kind) {
         // Skip empty imports
         if (!name || (kind !== 'namespace' && name === '')) {
@@ -107,42 +101,33 @@ export class ImportBuilder {
         return this;
     }
     /**
-     * Generate the import statements.
-     * If all imports from a module are types, uses `import type` syntax.
+     * Generate the import statements. When every import from a module is a
+     * type, emits `import type {…}` so the whole statement disappears at
+     * compile time.
      */
     build() {
         return this.#generate_import_statements().join('\n');
     }
-    /**
-     * Check if the builder has any imports.
-     */
     has_imports() {
         return this.imports.size > 0;
     }
-    /**
-     * Get the number of import statements that will be generated.
-     */
     get import_count() {
         return this.imports.size;
     }
-    /**
-     * Preview what imports will be generated (useful for debugging).
-     * @returns array of import statement strings
-     */
+    /** Build the same statement list as `build` without joining — for inspection in tests. */
     preview() {
         return this.#generate_import_statements();
     }
     /**
      * Clear all imports.
+     *
+     * @returns `this` for chaining
+     * @mutates this - empties the internal `imports` map
      */
     clear() {
         this.imports.clear();
         return this;
     }
-    /**
-     * Internal helper to generate import statements from the current state.
-     * Shared by both build() and preview() methods.
-     */
     #generate_import_statements() {
         const statements = [];
         for (const [from, module_imports] of this.imports) {
@@ -185,9 +170,7 @@ export class ImportBuilder {
         return statements;
     }
 }
-/**
- * Determines which phases an executor can handle based on the action spec.
- */
+/** Phases an executor can handle for the given spec — kind + initiator → set of phases. */
 export const get_executor_phases = (spec, executor) => {
     const { kind, initiator } = spec;
     const phases = [];
@@ -214,9 +197,9 @@ export const get_executor_phases = (spec, executor) => {
                     }
                     if (can_receive) {
                         phases.push('receive_request', 'send_response');
-                        // TODO @action-system-review This adds send_error redundantly when initiator:'both'
-                        // (already added above). Deduplication via Set at the end handles it,
-                        // but the logic should be consolidated when the action system is revisited.
+                        // TODO consolidate — `send_error` is added redundantly when
+                        // initiator:'both' (already pushed above); the trailing Set dedup
+                        // handles it.
                         phases.push('send_error');
                     }
                     break;
@@ -289,7 +272,7 @@ export const get_handler_return_type = (spec, phase, imports, collections_path =
  *
  * @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) => {
@@ -315,9 +298,7 @@ export const generate_phase_handlers = (spec, executor, imports, options) => {
         .join(';\n\t\t');
     return `${method}?: {\n\t\t${phase_handlers};\n\t}`;
 };
-/**
- * Creates a file banner comment.
- */
+/** "DO NOT EDIT" banner naming the gen producer. */
 export const create_banner = (origin_path) => `generated by ${origin_path} - DO NOT EDIT OR RISK LOST DATA`;
 // TODO rethink these, see also zzz `codegen.ts`
 export const to_action_spec_identifier = (method) => `${method}_action_spec`;
@@ -349,13 +330,11 @@ export const to_action_spec_output_identifier = (method) => `${to_action_spec_id
  * follows so wrappers no longer pre-register imports a per-spec emit might
  * not actually use.
  *
- * @param spec - the action spec to emit
- * @param imports - import builder to register references on
- * @param options.sync_returns_value - when true (default), sync local_call
+ * @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.
- * @param options.collections_path - import path that `ActionInputs` /
+ *   `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<...>>;`
  */
@@ -839,7 +818,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
@@ -936,6 +915,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 = [
@@ -956,9 +940,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"}