@fuzdev/fuz_app 0.47.0 → 0.49.0

package/dist/actions/action_codegen.js

@@ -10,12 +10,12 @@ import { ActionRegistry } from './action_registry.js';
 export const COMPOSABLE_ACTION_METHODS = ['heartbeat', 'cancel'];
 const COMPOSABLE_METHOD_SET = new Set(COMPOSABLE_ACTION_METHODS);
 /**
- * Type predicate for filtering composable methods out of a typed `ActionsApi`
+ * Type predicate for filtering composable methods out of a typed `FrontendActionsApi`
  * `method_filter`. Avoids the `(... as never)` cast required to call
  * `Array.prototype.includes` on the readonly tuple at narrow string types.
  *
  * @example
- * generate_actions_api(specs, imports, {
+ * generate_frontend_actions_api(specs, imports, {
  *   method_filter: (s) => !is_composable_action_method(s.method),
  * });
  */
@@ -312,10 +312,10 @@ export const to_action_spec_identifier = (method) => `${method}_action_spec`;
 export const to_action_spec_input_identifier = (method) => `${to_action_spec_identifier(method)}.input`;
 export const to_action_spec_output_identifier = (method) => `${to_action_spec_identifier(method)}.output`;
 /**
- * Generates one method line of the typed `ActionsApi` interface for a single
- * spec. Encapsulates the input/options/return-type signature shape so the
- * surface evolves in one place when fields like `signal` or `transport_name`
- * are added to per-call options.
+ * Generates one method line of the typed `FrontendActionsApi` interface for a
+ * single spec. Encapsulates the input/options/return-type signature shape so
+ * the surface evolves in one place when fields like `signal` or
+ * `transport_name` are added to per-call options.
  *
  * Async methods (`request_response`, `remote_notification`, async
  * `local_call`) get an optional second `options?: RpcClientCallOptions` arg
@@ -336,7 +336,7 @@ export const to_action_spec_output_identifier = (method) => `${to_action_spec_id
  * @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
- *   ActionsApi treats every method uniformly.
+ *   FrontendActionsApi treats every method uniformly.
  * @returns one line like `foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;`
  */
 export const generate_actions_api_method_signature = (spec, options) => {
@@ -356,6 +356,40 @@ export const generate_actions_api_method_signature = (spec, options) => {
             : result_return;
     return `${spec.method}: (${input_param}${options_param}) => ${return_type};`;
 };
+// --------------------------------------------------------------------------
+// High-level codegen helpers — compose the lower-level primitives above into
+// the literal blocks consumer `*.gen.ts` producers emit. Tier 1 consumers
+// (HTTP-only, e.g. tx) call the value-side helpers; Tier 2 (`TypedActionEvent`-
+// aware, e.g. zzz) also call the typed-event + frontend-handlers helpers.
+//
+// **Multi-source consumers.** Helpers that reference specs at runtime
+// (`generate_action_specs_record`, `generate_action_inputs_outputs`,
+// `generate_backend_actions_api`) default to a single `* as specs from
+// specs_module` namespace import and emit `specs.{method}_action_spec`. Pass
+// `qualify_spec?: (spec) => string` to emit a per-spec qualified identifier
+// (e.g. `admin_specs.account_list_action_spec`) for consumers stitching local
+// specs together with multiple upstream sources (`all_admin_action_specs` /
+// `all_permit_offer_action_specs` / `all_account_action_specs` /
+// `all_self_service_role_action_specs` from fuz_app). When `qualify_spec` is
+// set, the helper does NOT add a `* as specs` import — the consumer manages
+// the multiple `* as ns` imports itself — and `specs_module` is ignored.
+// `create_namespace_qualifier` automates the source-table → qualifier wiring.
+// --------------------------------------------------------------------------
+/**
+ * Format a `z.enum([...])` runtime const + matching `z.infer` type alias.
+ * Caller is responsible for ensuring `methods` is non-empty (`z.enum([])` is
+ * invalid) and registering the `zod` import on the `ImportBuilder`.
+ */
+const format_method_enum_block = (name, jsdoc, methods) => {
+    const lines = methods.map((m) => `\t'${m}',`).join('\n');
+    return `/**
+ * ${jsdoc}
+ */
+export const ${name} = z.enum([
+${lines}
+]);
+export type ${name} = z.infer<typeof ${name}>;`;
+};
 /** Default emit set — every enum kind. */
 export const ACTION_METHOD_ENUM_KINDS_ALL = new Set([
     'all',
@@ -364,19 +398,41 @@ export const ACTION_METHOD_ENUM_KINDS_ALL = new Set([
     'local_call',
     'frontend',
     'backend',
+    'frontend_handled',
+    'backend_handled',
+    'broadcast',
 ]);
 /**
  * Filter `heartbeat` / `cancel` out of `specs` unless the consumer opts back in.
  * Composables ship from fuz_app and are spread into every consumer's `actions`
  * array at registration time — they should not appear in consumer-owned typed
- * surfaces (`ActionMethod`, `ActionsApi`, `ActionInputs`, etc.) by default.
+ * surfaces (`ActionMethod`, `FrontendActionsApi`, `ActionInputs`, etc.) by
+ * default.
  */
 const filter_composables = (specs, include_composables) => include_composables ? specs : specs.filter((s) => !is_composable_action_method(s.method));
+/**
+ * Resolve the per-spec identifier qualifier used by the multi-source helpers
+ * (`generate_action_specs_record`, `generate_action_inputs_outputs`,
+ * `generate_backend_actions_api`). When `qualify_spec` is set, returns the
+ * caller's callback verbatim — the consumer is managing its own namespace
+ * imports. Otherwise, registers the default `* as specs from specs_module`
+ * import (defaulting to `'./action_specs.js'`) and returns the matching
+ * `specs.${method}_action_spec` qualifier.
+ */
+const resolve_spec_qualifier = (imports, options) => {
+    if (options?.qualify_spec)
+        return options.qualify_spec;
+    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
+    imports.add(specs_module, '* as specs');
+    return (s) => `specs.${s.method}_action_spec`;
+};
 /**
  * Emit one or more `z.enum([...])` declarations for action method names —
  * `ActionMethod`, `RequestResponseActionMethod`, `RemoteNotificationActionMethod`,
- * `LocalCallActionMethod`, `FrontendActionMethod`, `BackendActionMethod`. Pairs
- * each runtime const with a `z.infer` type alias under the same identifier.
+ * `LocalCallActionMethod`, `FrontendActionMethod`, `BackendActionMethod`,
+ * `FrontendRequestResponseMethod`, `BackendRequestResponseMethod`,
+ * `BroadcastActionMethod`. Pairs each runtime const with a `z.infer` type
+ * alias under the same identifier.
  *
  * Composable methods (`heartbeat`, `cancel`) are filtered out by default —
  * pass `include_composables: true` if a consumer genuinely wants them on
@@ -386,7 +442,11 @@ const filter_composables = (specs, include_composables) => include_composables ?
  * Adds `import {z} from 'zod';` to `imports` only when at least one block
  * is emitted (idempotent).
  *
- * @param options.emit - subset of enums to emit; defaults to all six.
+ * For genuinely cross-product enums the discriminator doesn't cover, use
+ * `generate_action_method_enum_block` — caller owns the predicate, name,
+ * and jsdoc.
+ *
+ * @param options.emit - subset of enums to emit; defaults to all nine.
  * @param options.include_composables - when true, retains `heartbeat` /
  *   `cancel` in the emitted enums. Default `false`.
  */
@@ -402,21 +462,48 @@ export const generate_action_method_enums = (specs, imports, options) => {
         // Consumers that need a kind to exist should check their spec set, not the helper.
         if (methods.length === 0)
             return;
-        const lines = methods.map((m) => `\t'${m}',`).join('\n');
-        blocks.push(`/**\n * ${jsdoc}\n */\nexport const ${name} = z.enum([\n${lines}\n]);
-export type ${name} = z.infer<typeof ${name}>;`);
+        blocks.push(format_method_enum_block(name, jsdoc, methods));
     };
     emit_block('all', 'ActionMethod', registry.methods, 'All action method names. Request/response actions have two types per method.');
     emit_block('request_response', 'RequestResponseActionMethod', registry.request_response_methods, 'Names of all request_response actions.');
     emit_block('remote_notification', 'RemoteNotificationActionMethod', registry.remote_notification_methods, 'Names of all remote_notification actions.');
     emit_block('local_call', 'LocalCallActionMethod', registry.local_call_methods, 'Names of all local_call actions.');
-    emit_block('frontend', 'FrontendActionMethod', registry.frontend_methods, 'Names of all actions that may be handled on the client.');
-    emit_block('backend', 'BackendActionMethod', registry.backend_methods, 'Names of all actions that may be handled on the server.');
+    // Loose: every spec the side might encounter (call, receive, or execute).
+    // Drives the typed-Proxy method enum keyed by FrontendActionsApi.
+    emit_block('frontend', 'FrontendActionMethod', registry.methods_relevant_to_frontend, 'Names of all actions in the typed FrontendActionsApi surface — every spec the frontend may encounter (call, receive, or execute locally).');
+    emit_block('backend', 'BackendActionMethod', registry.methods_relevant_to_backend, 'Names of all actions the backend may encounter — request_response and remote_notification (local_call is frontend-only).');
+    // Narrow: request_response actions this side handles (receives).
+    emit_block('frontend_handled', 'FrontendRequestResponseMethod', registry.frontend_handled_methods, 'Names of request_response actions the frontend handles (initiator excludes frontend).');
+    emit_block('backend_handled', 'BackendRequestResponseMethod', registry.backend_handled_methods, 'Names of request_response actions the backend handles (initiator excludes backend).');
+    // Broadcast: backend-initiated remote_notification, excluding `streams` targets.
+    emit_block('broadcast', 'BroadcastActionMethod', registry.broadcast_methods, "Names of remote_notification actions exposed by the broadcast API (backend-initiated, excluding request-scoped progress notifications named by another action's `streams`).");
     if (blocks.length === 0)
         return '';
     imports.add('zod', 'z');
     return blocks.join('\n\n');
 };
+/**
+ * Emit a single named `z.enum([...])` + `z.infer` block for an arbitrary
+ * spec subset. Lower-level escape hatch from `generate_action_method_enums` —
+ * for cross-product or domain-specific enums the built-in discriminator
+ * doesn't cover.
+ *
+ * Mirrors the built-in helper's contract: composables filtered by default,
+ * empty subsets return `''` (skip rather than emit `z.enum([])`), `zod`
+ * import registered idempotently only when at least one method qualifies.
+ *
+ * The cross-product space is open-ended; rather than grow the
+ * `ActionMethodEnumKind` discriminator one cross-product at a time, callers
+ * own the subset shape — name, jsdoc, predicate.
+ */
+export const generate_action_method_enum_block = (specs, imports, options) => {
+    const filtered = filter_composables(specs, options.include_composables);
+    const methods = filtered.filter(options.predicate).map((s) => s.method);
+    if (methods.length === 0)
+        return '';
+    imports.add('zod', 'z');
+    return format_method_enum_block(options.name, options.jsdoc, methods);
+};
 /**
  * Emit the fixed-shape `TypedActionEvent` alias used by `FrontendActionHandlers`
  * to narrow `ActionEvent.data` against the consumer's generated `ActionEventDatas`
@@ -449,11 +536,12 @@ type TypedActionEvent<
  * Array<ActionSpecUnion>` value bundling every spec. Adds the `* as specs`
  * namespace import + the `ActionSpecUnion` type import.
  *
- * **Single-namespace.** Every spec is referenced as `specs.{method}_action_spec`.
- * Multi-source consumers (tx, visiones) need a per-method namespace lookup
- * and currently use lower-level primitives instead — see the `--- High-level
- * codegen helpers ---` banner above for the rationale and the planned
- * `qualify_spec?` extension point.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers (e.g. ``(s) => `admin_specs.${s.method}_action_spec` ``).
+ *   When set, the helper emits the callback's return value instead of
+ *   ``specs.${method}_action_spec`` and skips the default `* as specs`
+ *   import — the consumer manages its own namespace imports. `specs_module`
+ *   is ignored when `qualify_spec` is set. Single-source consumers omit it.
  */
 export const generate_action_specs_record = (specs, imports, options) => {
     const filtered = filter_composables(specs, options?.include_composables);
@@ -470,14 +558,9 @@ export interface ActionSpecs {}
 
 export const action_specs: Array<ActionSpecUnion> = Object.values(ActionSpecs);`;
     }
-    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
-    imports.add(specs_module, '* as specs');
-    const value_lines = filtered
-        .map((s) => `\t${s.method}: specs.${s.method}_action_spec,`)
-        .join('\n');
-    const type_lines = filtered
-        .map((s) => `\t${s.method}: typeof specs.${s.method}_action_spec;`)
-        .join('\n');
+    const qualify = resolve_spec_qualifier(imports, options);
+    const value_lines = filtered.map((s) => `\t${s.method}: ${qualify(s)},`).join('\n');
+    const type_lines = filtered.map((s) => `\t${s.method}: typeof ${qualify(s)};`).join('\n');
     return `/**
  * Action specifications indexed by method name.
  * These represent the complete action spec definitions.
@@ -498,8 +581,11 @@ export const action_specs: Array<ActionSpecUnion> = Object.values(ActionSpecs);`
  *
  * Adds `import {z} from 'zod';` and the `* as specs` namespace import.
  *
- * **Single-namespace.** Same caveat as `generate_action_specs_record` —
- * multi-source consumers use the lower-level primitives.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers. The helper appends `.input` / `.output` to the
+ *   callback's return value. When set, the helper skips the default
+ *   `* as specs` import — the consumer manages its own namespace imports —
+ *   and `specs_module` is ignored. Single-source consumers omit it.
  */
 export const generate_action_inputs_outputs = (specs, imports, options) => {
     const filtered = filter_composables(specs, options?.include_composables);
@@ -523,19 +609,14 @@ export const ActionOutputs = {} as const;
 export interface ActionOutputs {}`;
     }
     imports.add('zod', 'z');
-    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
-    imports.add(specs_module, '* as specs');
-    const inputs_value = filtered
-        .map((s) => `\t${s.method}: specs.${s.method}_action_spec.input,`)
-        .join('\n');
+    const qualify = resolve_spec_qualifier(imports, options);
+    const inputs_value = filtered.map((s) => `\t${s.method}: ${qualify(s)}.input,`).join('\n');
     const inputs_type = filtered
-        .map((s) => `\t${s.method}: z.infer<typeof specs.${s.method}_action_spec.input>;`)
-        .join('\n');
-    const outputs_value = filtered
-        .map((s) => `\t${s.method}: specs.${s.method}_action_spec.output,`)
+        .map((s) => `\t${s.method}: z.infer<typeof ${qualify(s)}.input>;`)
         .join('\n');
+    const outputs_value = filtered.map((s) => `\t${s.method}: ${qualify(s)}.output,`).join('\n');
     const outputs_type = filtered
-        .map((s) => `\t${s.method}: z.infer<typeof specs.${s.method}_action_spec.output>;`)
+        .map((s) => `\t${s.method}: z.infer<typeof ${qualify(s)}.output>;`)
         .join('\n');
     return `/**
  * Action parameter schemas indexed by method name.
@@ -570,12 +651,16 @@ ${outputs_type}
  *
  * Adds the per-kind data type imports (only the kinds that appear in `specs`).
  *
- * @param options.collections_path - when set, adds `ActionInputs` /
- *   `ActionOutputs` type imports from this path. Leave unset (default) when
- *   the producer emits `ActionEventDatas` in the same file as
- *   `ActionInputs` / `ActionOutputs` — same-file scope means no imports
- *   needed (the zzz pattern, where `generate_action_inputs_outputs` and
- *   this helper feed the same `action_collections.ts` output).
+ * @param options.same_file - when `true` (default), assumes `ActionInputs` /
+ *   `ActionOutputs` are in the same module as the emitted `ActionEventDatas`
+ *   and adds no import (the zzz pattern, where `generate_action_inputs_outputs`
+ *   and this helper feed the same `action_collections.ts` output). When
+ *   `false`, adds `ActionInputs` / `ActionOutputs` type imports from
+ *   `collections_path`.
+ * @param options.collections_path - import path used when `same_file: false`.
+ *   Defaults to `'./action_collections.js'`. Ignored when `same_file: true`
+ *   — `same_file` is the file-layout switch; `collections_path` is just the
+ *   path the import resolves to.
  */
 export const generate_action_event_datas = (specs, imports, options) => {
     const filtered = filter_composables(specs, options?.include_composables);
@@ -589,8 +674,10 @@ export const generate_action_event_datas = (specs, imports, options) => {
  */
 export interface ActionEventDatas {}`;
     }
-    if (options?.collections_path) {
-        imports.add_types(options.collections_path, 'ActionInputs', 'ActionOutputs');
+    const same_file = options?.same_file ?? true;
+    if (!same_file) {
+        const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
+        imports.add_types(collections_path, 'ActionInputs', 'ActionOutputs');
     }
     const lines = filtered.map((spec) => {
         const data_type = spec.kind === 'request_response'
@@ -614,29 +701,36 @@ ${lines.join('\n')}
 }`;
 };
 /**
- * Emit the `ActionsApi` interface — one method signature per spec via
+ * Emit the `FrontendActionsApi` interface — one method signature per spec via
  * `generate_actions_api_method_signature`. Optionally filter the spec set
  * (e.g. omit composable methods) via `method_filter`.
  *
  * Adds the `Result`, `JsonrpcErrorObject`, and `RpcClientCallOptions` type
  * imports plus `ActionInputs` / `ActionOutputs` (sourced from `collections_path`).
+ *
+ * The interface name is fixed at `FrontendActionsApi` — the symmetric counterpart
+ * of `BackendActionsApi`. Earlier consumer-named variants (`MyActionsApi`,
+ * `VisionesActionsApi`) were retired in API review III to make the side-of-the-wire
+ * intent visible at every call site. If a consumer needs a different name they
+ * hand-roll the interface (the helper's job is the standard symmetric shape).
  */
-export const generate_actions_api = (specs, imports, options) => {
+export const generate_frontend_actions_api = (specs, imports, options) => {
     const composable_filtered = filter_composables(specs, options?.include_composables);
     const filter = options?.method_filter;
     const filtered = filter ? composable_filtered.filter((s) => filter(s)) : composable_filtered;
     const interface_doc = `/**
- * Interface for action dispatch functions.
- * Async methods (request_response, remote_notification, async local_call)
- * return \`Promise<Result<...>>\` and accept an optional \`RpcClientCallOptions\`
- * second arg that threads \`signal\`, \`transport_name\`, and \`queue\` through to
- * the peer. Sync local_call methods return values directly.
+ * Typed dispatch surface for the frontend's RPC client. Symmetric counterpart
+ * of \`BackendActionsApi\`. Async methods (request_response, remote_notification,
+ * async local_call) return \`Promise<Result<...>>\` and accept an optional
+ * \`RpcClientCallOptions\` second arg that threads \`signal\`, \`transport_name\`,
+ * and \`queue\` through to the peer. Sync local_call methods return values
+ * directly.
  */`;
     if (filtered.length === 0) {
-        // Empty spec list — emit `ActionsApi {}` and skip every import. None
-        // of the symbols would be referenced by the empty body.
+        // Empty spec list — emit `FrontendActionsApi {}` and skip every import.
+        // None of the symbols would be referenced by the empty body.
         return `${interface_doc}
-export interface ActionsApi {}`;
+export interface FrontendActionsApi {}`;
     }
     const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
     imports.add_type('@fuzdev/fuz_util/result.js', 'Result');
@@ -650,7 +744,7 @@ export interface ActionsApi {}`;
         .map((line) => `\t${line}`)
         .join('\n');
     return `${interface_doc}
-export interface ActionsApi {
+export interface FrontendActionsApi {
 ${lines}
 }`;
 };
@@ -696,23 +790,42 @@ ${lines};
  * each `(input) => Promise<void>`. The array bundles the matching specs as a
  * `ReadonlyArray<ActionSpecUnion>`.
  *
- * Filter: `kind === 'remote_notification' && initiator !== 'frontend'`.
+ * Filter: `kind === 'remote_notification' && initiator !== 'frontend'`,
+ * additionally excluding methods that are the target of another spec's
+ * `streams` field. Streams targets (e.g. `completion_progress`,
+ * `ollama_progress`) are request-scoped notifications invoked via
+ * `ctx.notify` inside their parent handler — they're never callable through
+ * the broadcast API. The discriminator is `ActionSpec.streams`, not a manual
+ * exclusion list.
  *
  * Adds the `* as specs` namespace import (from `specs_module`), the
  * `ActionInputs` type import (from `collections_path`), and the
  * `ActionSpecUnion` type import.
  *
- * **Single-namespace.** Same caveat as `generate_action_specs_record` —
- * multi-source consumers use the lower-level primitives.
+ * 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).
+ *
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers. When set, the helper emits the callback's return
+ *   value instead of ``specs.${method}_action_spec`` in the broadcast array
+ *   and skips the default `* as specs` import — the consumer manages its own
+ *   namespace imports. `specs_module` is ignored when `qualify_spec` is set.
+ *   Single-source consumers omit it.
  */
 export const generate_backend_actions_api = (specs, imports, options) => {
     const composable_filtered = filter_composables(specs, options?.include_composables);
-    const broadcast = composable_filtered.filter((s) => s.kind === 'remote_notification' && s.initiator !== 'frontend');
+    const registry = new ActionRegistry([...composable_filtered]);
+    const broadcast = registry.broadcast_specs;
     imports.add_type('@fuzdev/fuz_app/actions/action_spec.js', 'ActionSpecUnion');
     const interface_doc = `/**
- * Broadcast-style notifications from the backend to all connected clients.
- * Request-scoped streaming goes through \`ctx.notify\` instead — it's
- * socket-scoped, not a broadcast.
+ * Typed dispatch surface for backend-initiated calls. Symmetric counterpart
+ * of \`FrontendActionsApi\`. Today exposes broadcast-style \`remote_notification\`
+ * methods (1→N fan-out via \`create_broadcast_api\`); request-scoped streaming
+ * goes through \`ctx.notify\` inside a handler — it's socket-scoped, not a
+ * broadcast. Will widen when a second backend runtime constructor (targeted
+ * send, backend-initiated request_response) lands.
  */`;
     if (broadcast.length === 0) {
         // No backend-initiated remote_notifications — skip `* as specs` and
@@ -722,18 +835,156 @@ export interface BackendActionsApi {}
 
 export const broadcast_action_specs: ReadonlyArray<ActionSpecUnion> = [];`;
     }
-    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
     const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
-    imports.add(specs_module, '* as specs');
     imports.add_type(collections_path, 'ActionInputs');
+    const qualify = resolve_spec_qualifier(imports, options);
     const interface_body = '\n' +
         broadcast
             .map((s) => `\t${s.method}: (input: ActionInputs['${s.method}']) => Promise<void>;`)
             .join('\n') +
         '\n';
-    const array_body = '\n' + broadcast.map((s) => `\tspecs.${s.method}_action_spec,`).join('\n') + '\n';
+    const array_body = '\n' + broadcast.map((s) => `\t${qualify(s)},`).join('\n') + '\n';
     return `${interface_doc}
 export interface BackendActionsApi {${interface_body}}
 
 export const broadcast_action_specs: ReadonlyArray<ActionSpecUnion> = [${array_body}];`;
 };
+/**
+ * Emit the `BackendActionHandlers` mapped type — one entry per
+ * `BackendRequestResponseMethod`, each `(input, ctx) => output | Promise<output>`.
+ * Replaces the hand-maintained `Exclude<>` + parallel mapped-type pattern
+ * (zzz had this at `zzz/src/lib/server/zzz_action_handlers.ts:42-66`).
+ *
+ * The context type is consumer-defined (e.g. zzz's `ZzzHandlerContext`). Pass
+ * `context_type` to name it; the helper assumes it's importable or defined
+ * in the emitted module's scope (consumer's responsibility).
+ *
+ * Adds `ActionInputs` / `ActionOutputs` type imports from `collections_path`
+ * and the `BackendRequestResponseMethod` import from `metatypes_path`.
+ *
+ * @param options.type_name - default `'BackendActionHandlers'`.
+ * @param options.method_enum_name - default `'BackendRequestResponseMethod'`.
+ *   Pair with `generate_action_method_enums` emitting the `'backend_handled'` kind.
+ * @param options.context_type - default `'BackendHandlerContext'`. Caller's
+ *   handler context type — must be in scope at the emit site.
+ * @param options.collections_path - default `'./action_collections.js'`.
+ * @param options.metatypes_path - default `'./action_metatypes.js'`.
+ */
+export const generate_backend_action_handlers_map = (imports, options) => {
+    const type_name = options?.type_name ?? 'BackendActionHandlers';
+    const method_enum_name = options?.method_enum_name ?? 'BackendRequestResponseMethod';
+    const context_type = options?.context_type ?? 'BackendHandlerContext';
+    const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
+    const metatypes_path = options?.metatypes_path ?? DEFAULT_METATYPES_PATH;
+    imports.add_types(collections_path, 'ActionInputs', 'ActionOutputs');
+    imports.add_type(metatypes_path, method_enum_name);
+    return `/**
+ * Typed handler map for request_response actions the backend handles.
+ * One entry per ${method_enum_name}; each handler receives the typed input
+ * and returns the typed output (sync or async).
+ */
+export type ${type_name} = {
+	[K in ${method_enum_name}]: (
+		input: ActionInputs[K],
+		ctx: ${context_type},
+	) => ActionOutputs[K] | Promise<ActionOutputs[K]>;
+};`;
+};
+/**
+ * Multi-source consumer helper. Takes a list of `{ns, module, specs}` rows,
+ * registers `import * as ns from module` for each on `imports`, builds the
+ * `method_to_ns` lookup with duplicate-method detection, and returns
+ * `{qualify_spec, all_specs}` ready to thread through the high-level
+ * helpers.
+ *
+ * Closes the per-file boilerplate gap that kept tx + visiones on hand-rolled
+ * template strings even after `qualify_spec?` landed in API review II — the
+ * per-call callback wasn't enough; the import dance + dup-check was the
+ * real boilerplate.
+ *
+ * @example
+ * ```ts
+ * const sources = [
+ *   {ns: 'tx_specs', module: './action_specs.js', specs: all_tx_action_specs},
+ *   {ns: 'admin_specs', module: '@fuzdev/fuz_app/auth/admin_action_specs.js', specs: all_admin_action_specs},
+ * ];
+ *
+ * export const gen: Gen = ({origin_path}) => {
+ *   const imports = new ImportBuilder();
+ *   const {qualify_spec, all_specs} = create_namespace_qualifier(sources, imports);
+ *   return compose_gen_file({
+ *     origin_path,
+ *     imports,
+ *     blocks: [
+ *       generate_action_specs_record(all_specs, imports, {qualify_spec}),
+ *       generate_action_inputs_outputs(all_specs, imports, {qualify_spec}),
+ *     ],
+ *   });
+ * };
+ * ```
+ *
+ * @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();
+    const all_specs = [];
+    for (const { ns, module, specs } of sources) {
+        imports.add(module, `* as ${ns}`);
+        for (const spec of specs) {
+            if (method_to_ns.has(spec.method)) {
+                throw new Error(`duplicate action method across sources: ${spec.method} (in ${method_to_ns.get(spec.method)} and ${ns})`);
+            }
+            method_to_ns.set(spec.method, ns);
+            all_specs.push(spec);
+        }
+    }
+    const qualify_spec = (spec) => {
+        const ns = method_to_ns.get(spec.method);
+        if (!ns) {
+            throw new Error(`unknown action method passed to qualify_spec: ${spec.method} — not in any registered source`);
+        }
+        return `${ns}.${spec.method}_action_spec`;
+    };
+    return { qualify_spec, all_specs };
+};
+/**
+ * Wrap the per-`*.gen.ts` boilerplate (banner + `imports.build()` +
+ * blocks join + template literal) into one call. Returns the full file body
+ * as a string ready to return from a `Gen` function.
+ *
+ * Each consumer producer collapses to one `compose_gen_file` call wrapping
+ * the helper invocations.
+ *
+ * @example
+ * ```ts
+ * export const gen: Gen = ({origin_path}) => {
+ *   const imports = new ImportBuilder();
+ *   return compose_gen_file({
+ *     origin_path,
+ *     imports,
+ *     blocks: [
+ *       generate_action_specs_record(all_action_specs, imports),
+ *       generate_action_inputs_outputs(all_action_specs, imports),
+ *       generate_action_event_datas(all_action_specs, imports),
+ *     ],
+ *   });
+ * };
+ * ```
+ *
+ * Empty blocks (`''`) are filtered out so helpers that short-circuit on
+ * empty spec sets don't introduce stray double blank lines.
+ */
+export const compose_gen_file = (input) => {
+    const banner = create_banner(input.origin_path);
+    const body = input.blocks.filter(Boolean).join('\n\n');
+    return `
+		// ${banner}
+
+		${input.imports.build()}
+
+		${body}
+
+		// ${banner}
+	`;
+};

package/dist/actions/action_registry.d.ts

@@ -1,6 +1,29 @@
 /**
  * `ActionRegistry` — query and filter utility over `ActionSpecUnion[]`.
  *
+ * Vocabulary (set in API review III, see the `docs/` directory and the SAES quest):
+ * - `*_handled_*` — request_response specs the named side **receives**
+ *   (so the named side owns the handler). Used by codegen to emit typed
+ *   handler maps.
+ * - `*_relevant_to_*` — the loose "everything this side might encounter"
+ *   set, used by the typed-Proxy method enums (`FrontendActionMethod`,
+ *   `BackendActionMethod`).
+ * - `broadcast_*` — kind-narrow `remote_notification` set with the
+ *   `streams`-target exclusion. Today this matches what the broadcast
+ *   API exposes.
+ * - `backend_initiated_*` — forward-looking kind-agnostic version of the
+ *   broadcast set. Same content today; will diverge when local_calls or
+ *   backend `request_response` join the backend's typed surface.
+ *
+ * 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
+ * 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
+ * registry — codegen is a build-time path where the extra `.filter` /
+ * `.map` work is negligible.
+ *
  * @module
  */
 import type { ActionSpecUnion, RequestResponseActionSpec, RemoteNotificationActionSpec, LocalCallActionSpec } from './action_spec.js';
@@ -9,26 +32,35 @@ import type { ActionSpecUnion, RequestResponseActionSpec, RemoteNotificationActi
  * Provides helper methods to get actions by various criteria.
  */
 export declare class ActionRegistry {
+    #private;
     readonly specs: Array<ActionSpecUnion>;
     constructor(specs: Array<ActionSpecUnion>);
     get spec_by_method(): Map<string, ActionSpecUnion>;
+    get methods(): Array<string>;
     get request_response_specs(): Array<RequestResponseActionSpec>;
     get remote_notification_specs(): Array<RemoteNotificationActionSpec>;
     get local_call_specs(): Array<LocalCallActionSpec>;
-    get backend_specs(): Array<ActionSpecUnion>;
-    get frontend_specs(): Array<ActionSpecUnion>;
-    get backend_to_frontend_specs(): Array<ActionSpecUnion>;
-    get frontend_to_backend_specs(): Array<ActionSpecUnion>;
-    get public_specs(): Array<ActionSpecUnion>;
-    get authenticated_specs(): Array<ActionSpecUnion>;
-    get methods(): Array<string>;
     get request_response_methods(): Array<string>;
     get remote_notification_methods(): Array<string>;
     get local_call_methods(): Array<string>;
-    get backend_methods(): Array<string>;
-    get frontend_methods(): Array<string>;
+    get specs_relevant_to_frontend(): Array<ActionSpecUnion>;
+    get specs_relevant_to_backend(): Array<ActionSpecUnion>;
+    get methods_relevant_to_frontend(): Array<string>;
+    get methods_relevant_to_backend(): Array<string>;
+    get frontend_handled_specs(): Array<RequestResponseActionSpec>;
+    get backend_handled_specs(): Array<RequestResponseActionSpec>;
+    get frontend_handled_methods(): Array<string>;
+    get backend_handled_methods(): Array<string>;
+    get broadcast_specs(): Array<RemoteNotificationActionSpec>;
+    get broadcast_methods(): Array<string>;
+    get backend_initiated_specs(): Array<ActionSpecUnion>;
+    get backend_initiated_methods(): Array<string>;
+    get backend_to_frontend_specs(): Array<ActionSpecUnion>;
+    get frontend_to_backend_specs(): Array<ActionSpecUnion>;
     get frontend_to_backend_methods(): Array<string>;
     get backend_to_frontend_methods(): Array<string>;
+    get public_specs(): Array<ActionSpecUnion>;
+    get authenticated_specs(): Array<ActionSpecUnion>;
     get public_methods(): Array<string>;
     get authenticated_methods(): Array<string>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,eAAe,EACf,yBAAyB,EACzB,4BAA4B,EAC5B,mBAAmB,EACnB,MAAM,kBAAkB,CAAC;AAQ1B;;;GAGG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;gBAE3B,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC;IAIzC,IAAI,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAEjD;IAED,IAAI,sBAAsB,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAE7D;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAEnE;IAED,IAAI,gBAAgB,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAEjD;IAKD,IAAI,aAAa,IAAI,KAAK,CAAC,eAAe,CAAC,CAE1C;IAED,IAAI,cAAc,IAAI,KAAK,CAAC,eAAe,CAAC,CAE3C;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,YAAY,IAAI,KAAK,CAAC,eAAe,CAAC,CAEzC;IAED,IAAI,mBAAmB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEhD;IAED,IAAI,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,CAE3B;IAED,IAAI,wBAAwB,IAAI,KAAK,CAAC,MAAM,CAAC,CAE5C;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,kBAAkB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEtC;IAED,IAAI,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC,CAEnC;IAED,IAAI,gBAAgB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEpC;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,cAAc,IAAI,KAAK,CAAC,MAAM,CAAC,CAElC;IAED,IAAI,qBAAqB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEzC;CACD"}
+{"version":3,"file":"action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACX,eAAe,EACf,yBAAyB,EACzB,4BAA4B,EAC5B,mBAAmB,EACnB,MAAM,kBAAkB,CAAC;AAS1B;;;GAGG;AACH,qBAAa,cAAc;;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;gBAE3B,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC;IAKzC,IAAI,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAEjD;IAED,IAAI,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,CAE3B;IAID,IAAI,sBAAsB,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAE7D;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAEnE;IAED,IAAI,gBAAgB,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAEjD;IAED,IAAI,wBAAwB,IAAI,KAAK,CAAC,MAAM,CAAC,CAE5C;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,kBAAkB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEtC;IAOD,IAAI,0BAA0B,IAAI,KAAK,CAAC,eAAe,CAAC,CAEvD;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,4BAA4B,IAAI,KAAK,CAAC,MAAM,CAAC,CAEhD;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAOD,IAAI,sBAAsB,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAE7D;IAED,IAAI,qBAAqB,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAE5D;IAED,IAAI,wBAAwB,IAAI,KAAK,CAAC,MAAM,CAAC,CAE5C;IAED,IAAI,uBAAuB,IAAI,KAAK,CAAC,MAAM,CAAC,CAE3C;IASD,IAAI,eAAe,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAKzD;IAED,IAAI,iBAAiB,IAAI,KAAK,CAAC,MAAM,CAAC,CAErC;IAED,IAAI,uBAAuB,IAAI,KAAK,CAAC,eAAe,CAAC,CAKpD;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,MAAM,CAAC,CAE7C;IAID,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAID,IAAI,YAAY,IAAI,KAAK,CAAC,eAAe,CAAC,CAEzC;IAED,IAAI,mBAAmB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEhD;IAED,IAAI,cAAc,IAAI,KAAK,CAAC,MAAM,CAAC,CAElC;IAED,IAAI,qBAAqB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEzC;CAaD"}