@fuzdev/fuz_app 0.49.0 → 0.51.0

package/dist/actions/action_codegen.js

@@ -2,24 +2,27 @@ import { UnreachableError } from '@fuzdev/fuz_util/error.js';
 import { zod_get_base_type } from '@fuzdev/fuz_util/zod.js';
 import { ActionRegistry } from './action_registry.js';
 /**
- * Method names of composable actions exported from fuz_app — `heartbeat` (auth-aware
- * client liveness probe) and `cancel` (request-scoped abort signal). Consumers spread
- * this list when filtering backend request_response methods so the dispatcher-owned
- * composables don't show up in `BackendRequestResponseMethod` / handler maps.
+ * Method names of fuz_app's protocol actions — `heartbeat` (auth-aware client
+ * liveness probe) and `cancel` (request-scoped abort signal). Consumers spread
+ * this list when filtering backend request_response methods so the
+ * dispatcher-owned protocol actions don't show up in
+ * `BackendRequestResponseMethod` / handler maps. Pairs with `protocol_actions`
+ * / `protocol_action_specs` from `actions/protocol.ts` (the runtime bundles).
  */
-export const COMPOSABLE_ACTION_METHODS = ['heartbeat', 'cancel'];
-const COMPOSABLE_METHOD_SET = new Set(COMPOSABLE_ACTION_METHODS);
+export const PROTOCOL_ACTION_METHODS = ['heartbeat', 'cancel'];
+const PROTOCOL_METHOD_SET = new Set(PROTOCOL_ACTION_METHODS);
 /**
- * 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.
+ * Type predicate for filtering protocol-action 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_frontend_actions_api(specs, imports, {
- *   method_filter: (s) => !is_composable_action_method(s.method),
+ *   method_filter: (s) => !is_protocol_action_method(s.method),
  * });
  */
-export const is_composable_action_method = (method) => COMPOSABLE_METHOD_SET.has(method);
+export const is_protocol_action_method = (method) => PROTOCOL_METHOD_SET.has(method);
 /**
  * Manages imports for generated code, building them on demand.
  * Automatically optimizes type-only imports to use `import type` syntax.
@@ -275,6 +278,15 @@ 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
@@ -284,7 +296,7 @@ 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;
@@ -328,32 +340,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 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.
+ * @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};`;
 };
 // --------------------------------------------------------------------------
@@ -404,12 +436,13 @@ export const ACTION_METHOD_ENUM_KINDS_ALL = new Set([
 ]);
 /**
  * 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
+ * Protocol actions ship from fuz_app and are spread into every consumer's
+ * `actions` array at registration time (via `protocol_actions` from
+ * `actions/protocol.ts`) — they should not appear in consumer-owned typed
  * 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));
+const filter_protocol_actions = (specs, include_protocol_actions) => include_protocol_actions ? specs : specs.filter((s) => !is_protocol_action_method(s.method));
 /**
  * Resolve the per-spec identifier qualifier used by the multi-source helpers
  * (`generate_action_specs_record`, `generate_action_inputs_outputs`,
@@ -434,10 +467,10 @@ const resolve_spec_qualifier = (imports, options) => {
  * `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
- * their typed surface. Empty kinds are skipped so the helper never emits
- * `z.enum([])` (zod runtime-throws on that).
+ * Protocol-action methods (`heartbeat`, `cancel`) are filtered out by
+ * default — pass `include_protocol_actions: true` if a consumer genuinely
+ * wants them on their typed surface. Empty kinds are skipped so the helper
+ * never emits `z.enum([])` (zod runtime-throws on that).
  *
  * Adds `import {z} from 'zod';` to `imports` only when at least one block
  * is emitted (idempotent).
@@ -447,12 +480,12 @@ const resolve_spec_qualifier = (imports, options) => {
  * and jsdoc.
  *
  * @param options.emit - subset of enums to emit; defaults to all nine.
- * @param options.include_composables - when true, retains `heartbeat` /
+ * @param options.include_protocol_actions - when true, retains `heartbeat` /
  *   `cancel` in the emitted enums. Default `false`.
  */
 export const generate_action_method_enums = (specs, imports, options) => {
     const emit = options?.emit ?? ACTION_METHOD_ENUM_KINDS_ALL;
-    const filtered = filter_composables(specs, options?.include_composables);
+    const filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     const registry = new ActionRegistry([...filtered]);
     const blocks = [];
     const emit_block = (kind, name, methods, jsdoc) => {
@@ -488,16 +521,17 @@ export const generate_action_method_enums = (specs, imports, options) => {
  * 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.
+ * Mirrors the built-in helper's contract: protocol actions 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 filtered = filter_protocol_actions(specs, options.include_protocol_actions);
     const methods = filtered.filter(options.predicate).map((s) => s.method);
     if (methods.length === 0)
         return '';
@@ -544,7 +578,7 @@ type TypedActionEvent<
  *   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);
+    const filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     imports.add_type('@fuzdev/fuz_app/actions/action_spec.js', 'ActionSpecUnion');
     if (filtered.length === 0) {
         // Empty spec list — emit minimal valid output and skip the `* as specs`
@@ -588,7 +622,7 @@ export const action_specs: Array<ActionSpecUnion> = Object.values(ActionSpecs);`
  *   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);
+    const filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     if (filtered.length === 0) {
         // Empty spec list — emit minimal valid output and skip the `zod` /
         // `* as specs` imports that would have nothing to reference.
@@ -663,7 +697,7 @@ ${outputs_type}
  *   path the import resolves to.
  */
 export const generate_action_event_datas = (specs, imports, options) => {
-    const filtered = filter_composables(specs, options?.include_composables);
+    const filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     if (filtered.length === 0) {
         // Empty spec list — emit `interface ActionEventDatas {}` and skip
         // the optional collections-path import that would be unused.
@@ -703,10 +737,14 @@ ${lines.join('\n')}
 /**
  * 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`.
+ * (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`,
@@ -715,9 +753,9 @@ ${lines.join('\n')}
  * hand-roll the interface (the helper's job is the standard symmetric shape).
  */
 export const generate_frontend_actions_api = (specs, imports, options) => {
-    const composable_filtered = filter_composables(specs, options?.include_composables);
+    const protocol_filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     const filter = options?.method_filter;
-    const filtered = filter ? composable_filtered.filter((s) => filter(s)) : composable_filtered;
+    const filtered = filter ? protocol_filtered.filter((s) => filter(s)) : protocol_filtered;
     const interface_doc = `/**
  * Typed dispatch surface for the frontend's RPC client. Symmetric counterpart
  * of \`BackendActionsApi\`. Async methods (request_response, remote_notification,
@@ -732,14 +770,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');
@@ -755,7 +789,7 @@ ${lines}
  * matching `TypedActionEvent` alias) — call both in the same gen producer.
  */
 export const generate_frontend_action_handlers = (specs, imports, options) => {
-    const filtered = filter_composables(specs, options?.include_composables);
+    const filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
     const interface_doc = `/**
  * Frontend action handlers organized by method and phase.
  * Generated using spec.initiator to determine valid phases:
@@ -815,8 +849,8 @@ ${lines};
  *   Single-source consumers omit it.
  */
 export const generate_backend_actions_api = (specs, imports, options) => {
-    const composable_filtered = filter_composables(specs, options?.include_composables);
-    const registry = new ActionRegistry([...composable_filtered]);
+    const protocol_filtered = filter_protocol_actions(specs, options?.include_protocol_actions);
+    const registry = new ActionRegistry([...protocol_filtered]);
     const broadcast = registry.broadcast_specs;
     imports.add_type('@fuzdev/fuz_app/actions/action_spec.js', 'ActionSpecUnion');
     const interface_doc = `/**

package/dist/actions/action_registry.d.ts

@@ -17,7 +17,7 @@
  *
  * Cache discipline: `spec_by_method` (Map) and the internal streams-target
  * set lazy-memoize because the Map is consulted per-RPC dispatch
- * (`frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
+ * (`actions/frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
  * streams set is rebuilt by two public getters. Array-returning getters
  * recompute on each call so callers can mutate the result freely
  * (`.sort()`, `.push(injected)` on a copy, etc.) without affecting the

package/dist/actions/action_registry.js

@@ -17,7 +17,7 @@
  *
  * Cache discipline: `spec_by_method` (Map) and the internal streams-target
  * set lazy-memoize because the Map is consulted per-RPC dispatch
- * (`frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
+ * (`actions/frontend_rpc_client.ts` wires it into `lookup_action_spec`) and the
  * streams set is rebuilt by two public getters. Array-returning getters
  * recompute on each call so callers can mutate the result freely
  * (`.sort()`, `.push(injected)` on a copy, etc.) without affecting the

package/dist/actions/action_spec.d.ts

@@ -3,7 +3,7 @@
  *
  * Extracted from zzz's action system. Action specs define method, kind,
  * auth, side effects, and input/output schemas. Bridge functions in
- * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
+ * `actions/action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
  * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.

package/dist/actions/action_spec.js

@@ -3,7 +3,7 @@
  *
  * Extracted from zzz's action system. Action specs define method, kind,
  * auth, side effects, and input/output schemas. Bridge functions in
- * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
+ * `actions/action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
  * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.

package/dist/actions/action_types.d.ts

@@ -1,10 +1,10 @@
 /**
  * Shared type surface for the action system — context, handler, composable Action tuple.
  *
- * These types sit above `action_spec.ts` (pure Zod schemas) and below the
- * dispatchers (`register_action_ws.ts`, `action_rpc.ts`). Extracted so the
- * shared composable fuz_app actions (e.g. `heartbeat_action`) can name them
- * without pulling in server-only modules.
+ * These types sit above `actions/action_spec.ts` (pure Zod schemas) and below the
+ * dispatchers (`actions/register_action_ws.ts`, `actions/action_rpc.ts`). Extracted so the
+ * shared protocol actions (e.g. `heartbeat_action`) can name them without
+ * pulling in server-only modules.
  *
  * @module
  */

package/dist/actions/action_types.js

@@ -1,10 +1,10 @@
 /**
  * Shared type surface for the action system — context, handler, composable Action tuple.
  *
- * These types sit above `action_spec.ts` (pure Zod schemas) and below the
- * dispatchers (`register_action_ws.ts`, `action_rpc.ts`). Extracted so the
- * shared composable fuz_app actions (e.g. `heartbeat_action`) can name them
- * without pulling in server-only modules.
+ * These types sit above `actions/action_spec.ts` (pure Zod schemas) and below the
+ * dispatchers (`actions/register_action_ws.ts`, `actions/action_rpc.ts`). Extracted so the
+ * shared protocol actions (e.g. `heartbeat_action`) can name them without
+ * pulling in server-only modules.
  *
  * @module
  */

package/dist/actions/cancel.d.ts

@@ -1,6 +1,6 @@
 /**
- * Shared cancel action — the second composable fuz_app primitive, validating
- * the spec+handler tuple pattern on a notification-kind action.
+ * Shared cancel action — a fuz_app protocol action validating the
+ * spec+handler tuple pattern on a notification-kind action.
  *
  * Semantics: the client sends `{jsonrpc, method: 'cancel', params:
  * {request_id}}` to abort an in-flight request on the same socket.
@@ -11,13 +11,14 @@
  *
  * The handler field is an empty stub: cancel semantics are dispatcher-owned
  * (the dispatcher has the `{request_id → AbortController}` map, not the
- * handler). The handler exists for symmetry with other composable primitives
+ * handler). The handler exists for symmetry with other protocol actions
  * like `heartbeat_action`; the dispatcher never calls it. Consumers
- * spread `cancel_action` into their server's `actions` array so
- * `spec_by_method` knows about it (enabling input validation on incoming
- * cancels) and so `create_rpc_client` codegen produces `app.api.cancel()`
- * when desired — though `FrontendWebsocketClient.request({signal})` sends
- * the cancel on abort without needing the typed API.
+ * spread `cancel_action` (or the `protocol_actions` bundle from
+ * `actions/protocol.ts`) into their server's `actions` array so `spec_by_method`
+ * knows about it (enabling input validation on incoming cancels) and so
+ * `create_rpc_client` codegen produces `app.api.cancel()` when desired —
+ * though `FrontendWebsocketClient.request({signal})` sends the cancel on
+ * abort without needing the typed API.
  *
  * Wire format is snake_case `cancel` with `{request_id}`, not MCP's
  * `$/cancelRequest` with `{requestId}` — fuz_app's WS transport isn't MCP,
@@ -67,9 +68,10 @@ export declare const cancel_action_spec: {
  */
 export declare const cancel_handler: () => void;
 /**
- * Composable tuple — spread into the server's `actions` array so the
- * dispatcher registers the spec for input validation and so `create_rpc_client`
- * codegen sees the method. The client doesn't need to call it directly;
+ * Protocol-action tuple — spread into the server's `actions` array (or via
+ * `protocol_actions` from `actions/protocol.ts`) so the dispatcher registers the
+ * spec for input validation and so `create_rpc_client` codegen sees the
+ * method. The client doesn't need to call it directly;
  * `FrontendWebsocketClient.request({signal})` sends the cancel notification
  * automatically when the signal fires.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"cancel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;kBAEnC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CAWS,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAAU,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAG3B,CAAC"}
+{"version":3,"file":"cancel.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/cancel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;kBAEnC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CAWS,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAAU,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAG3B,CAAC"}

package/dist/actions/cancel.js

@@ -1,6 +1,6 @@
 /**
- * Shared cancel action — the second composable fuz_app primitive, validating
- * the spec+handler tuple pattern on a notification-kind action.
+ * Shared cancel action — a fuz_app protocol action validating the
+ * spec+handler tuple pattern on a notification-kind action.
  *
  * Semantics: the client sends `{jsonrpc, method: 'cancel', params:
  * {request_id}}` to abort an in-flight request on the same socket.
@@ -11,13 +11,14 @@
  *
  * The handler field is an empty stub: cancel semantics are dispatcher-owned
  * (the dispatcher has the `{request_id → AbortController}` map, not the
- * handler). The handler exists for symmetry with other composable primitives
+ * handler). The handler exists for symmetry with other protocol actions
  * like `heartbeat_action`; the dispatcher never calls it. Consumers
- * spread `cancel_action` into their server's `actions` array so
- * `spec_by_method` knows about it (enabling input validation on incoming
- * cancels) and so `create_rpc_client` codegen produces `app.api.cancel()`
- * when desired — though `FrontendWebsocketClient.request({signal})` sends
- * the cancel on abort without needing the typed API.
+ * spread `cancel_action` (or the `protocol_actions` bundle from
+ * `actions/protocol.ts`) into their server's `actions` array so `spec_by_method`
+ * knows about it (enabling input validation on incoming cancels) and so
+ * `create_rpc_client` codegen produces `app.api.cancel()` when desired —
+ * though `FrontendWebsocketClient.request({signal})` sends the cancel on
+ * abort without needing the typed API.
  *
  * Wire format is snake_case `cancel` with `{request_id}`, not MCP's
  * `$/cancelRequest` with `{requestId}` — fuz_app's WS transport isn't MCP,
@@ -64,9 +65,10 @@ export const cancel_action_spec = {
  */
 export const cancel_handler = () => { }; // eslint-disable-line @typescript-eslint/no-empty-function
 /**
- * Composable tuple — spread into the server's `actions` array so the
- * dispatcher registers the spec for input validation and so `create_rpc_client`
- * codegen sees the method. The client doesn't need to call it directly;
+ * Protocol-action tuple — spread into the server's `actions` array (or via
+ * `protocol_actions` from `actions/protocol.ts`) so the dispatcher registers the
+ * spec for input validation and so `create_rpc_client` codegen sees the
+ * method. The client doesn't need to call it directly;
  * `FrontendWebsocketClient.request({signal})` sends the cancel notification
  * automatically when the signal fires.
  */

package/dist/actions/frontend_rpc_client.d.ts

@@ -58,6 +58,15 @@ export interface CreateFrontendRpcClientOptions<TApi extends object = object> {
      * list silently return `undefined` from the Proxy — the generic `TApi`
      * cannot constrain runtime membership, so consumers must keep this list
      * in sync with the typed surface (codegen recommended).
+     *
+     * Protocol actions (`heartbeat`, `cancel`) are **not** auto-spread —
+     * they're filtered out of generated `action_specs` by codegen's
+     * `include_protocol_actions: false` default and consumers spread them
+     * in explicitly so the contract stays visible at every registration
+     * site. For WS-using consumers, spread `protocol_action_specs` from
+     * `actions/protocol.ts` here:
+     * `specs: [...protocol_action_specs, ...action_specs]`. HTTP-only
+     * consumers can omit them.
      */
     specs: ReadonlyArray<ActionSpecUnion>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"frontend_rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/frontend_rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,8BAA8B,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAC3E;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;IAC1C;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACpE;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,CAAC;CACxE;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB,CAAC,IAAI;IACtC;;;;OAIG;IACH,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;OAKG;IACH,UAAU,EAAE,IAAI,CAAC;IACjB,0GAA0G;IAC1G,IAAI,EAAE,UAAU,CAAC;IACjB,sHAAsH;IACtH,WAAW,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,IAAI,SAAS,MAAM,EAC7D,SAAS,8BAA8B,CAAC,IAAI,CAAC,KAC3C,iBAAiB,CAAC,IAAI,CAsBxB,CAAC"}
+{"version":3,"file":"frontend_rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/frontend_rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,8BAA8B,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAC3E;;;;;;;;;;;;;;OAcG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;IAC1C;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACpE;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,CAAC;CACxE;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB,CAAC,IAAI;IACtC;;;;OAIG;IACH,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;OAKG;IACH,UAAU,EAAE,IAAI,CAAC;IACjB,0GAA0G;IAC1G,IAAI,EAAE,UAAU,CAAC;IACjB,sHAAsH;IACtH,WAAW,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,IAAI,SAAS,MAAM,EAC7D,SAAS,8BAA8B,CAAC,IAAI,CAAC,KAC3C,iBAAiB,CAAC,IAAI,CAsBxB,CAAC"}

package/dist/actions/heartbeat.d.ts

@@ -1,9 +1,9 @@
 /**
- * Shared heartbeat action — the first composable fuz_app primitive carrying
- * both a spec and a handler in one tuple. Consumers spread
- * `heartbeat_action` into both the server's and the client's `actions`
- * array so disconnect detection works identically across every repo without
- * per-consumer ping plumbing.
+ * Shared heartbeat action — a fuz_app protocol action carrying both a spec
+ * and a handler in one tuple. Consumers spread `heartbeat_action` (or the
+ * `protocol_actions` bundle from `actions/protocol.ts`) into the server's
+ * `actions` array so disconnect detection works identically across every
+ * repo without per-consumer ping plumbing.
  *
  * The client's activity-aware heartbeat timer (in
  * `FrontendWebsocketClient`) issues a `heartbeat` request whenever the
@@ -38,9 +38,12 @@ export declare const heartbeat_action_spec: {
 /** Handler — nullary echo. Stateless, suitable for high-frequency pings. */
 export declare const heartbeat_handler: () => Record<string, never>;
 /**
- * Composable tuple — spread into the server's `actions` array for dispatch
- * and into the client's `actions` array so `create_rpc_client` types
- * `app.api.heartbeat()` against the shared spec.
+ * Protocol-action tuple — spread into the server's `actions` array for
+ * dispatch (or via `protocol_actions` from `actions/protocol.ts`) so the
+ * dispatcher resolves the heartbeat handler. The frontend-side spread
+ * happens via `protocol_action_specs` — the client doesn't run the echo
+ * handler, but the spec must be in `ActionRegistry` so `create_rpc_client`
+ * types `app.api.heartbeat()` against the shared spec.
  */
 export declare const heartbeat_action: Action;
 //# sourceMappingURL=heartbeat.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"heartbeat.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;CAUG,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAG9B,CAAC"}
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;CAUG,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,KAAK,CAAS,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAG9B,CAAC"}

package/dist/actions/heartbeat.js

@@ -1,9 +1,9 @@
 /**
- * Shared heartbeat action — the first composable fuz_app primitive carrying
- * both a spec and a handler in one tuple. Consumers spread
- * `heartbeat_action` into both the server's and the client's `actions`
- * array so disconnect detection works identically across every repo without
- * per-consumer ping plumbing.
+ * Shared heartbeat action — a fuz_app protocol action carrying both a spec
+ * and a handler in one tuple. Consumers spread `heartbeat_action` (or the
+ * `protocol_actions` bundle from `actions/protocol.ts`) into the server's
+ * `actions` array so disconnect detection works identically across every
+ * repo without per-consumer ping plumbing.
  *
  * The client's activity-aware heartbeat timer (in
  * `FrontendWebsocketClient`) issues a `heartbeat` request whenever the
@@ -37,9 +37,12 @@ export const heartbeat_action_spec = {
 /** Handler — nullary echo. Stateless, suitable for high-frequency pings. */
 export const heartbeat_handler = () => ({});
 /**
- * Composable tuple — spread into the server's `actions` array for dispatch
- * and into the client's `actions` array so `create_rpc_client` types
- * `app.api.heartbeat()` against the shared spec.
+ * Protocol-action tuple — spread into the server's `actions` array for
+ * dispatch (or via `protocol_actions` from `actions/protocol.ts`) so the
+ * dispatcher resolves the heartbeat handler. The frontend-side spread
+ * happens via `protocol_action_specs` — the client doesn't run the echo
+ * handler, but the spec must be in `ActionRegistry` so `create_rpc_client`
+ * types `app.api.heartbeat()` against the shared spec.
  */
 export const heartbeat_action = {
     spec: heartbeat_action_spec,

package/dist/actions/protocol.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Canonical bundles of fuz_app's protocol actions — `heartbeat` and
+ * `cancel`. Spread these into consumer registrations on both sides of the
+ * wire so the registries stay symmetric without per-consumer plumbing.
+ *
+ * Protocol actions are wire-protocol concerns (liveness, abort) shipped by
+ * fuz_app, not consumer domain logic. The split is intentional: the server
+ * needs `{spec, handler}` tuples to drive dispatch; the frontend
+ * `ActionRegistry` only stores specs. The codegen
+ * `include_protocol_actions: false` default (in `actions/action_codegen.ts`) is the
+ * third leg of this contract — protocol actions are excluded from
+ * generated typed surfaces because consumers spread them in at
+ * registration time.
+ *
+ * Adding a future protocol action (e.g. clock-skew probe, reconnect-resume
+ * token) means appending to these arrays in one place; no consumer
+ * migration required.
+ *
+ * @module
+ */
+import type { ActionSpecUnion } from './action_spec.js';
+import type { Action } from './action_types.js';
+/**
+ * Canonical protocol `{spec, handler}` tuples for the server's
+ * `register_action_ws` `actions` array. Spread before consumer-owned actions
+ * so disconnect detection and per-request cancel work uniformly:
+ *
+ * ```ts
+ * register_action_ws({actions: [...protocol_actions, ...consumer_actions], ...})
+ * ```
+ */
+export declare const protocol_actions: ReadonlyArray<Action>;
+/**
+ * Canonical protocol specs for `ActionRegistry` construction on the
+ * frontend. Spread before consumer-owned specs so dispatcher-owned methods
+ * are present in the lookup map even though codegen excludes them from the
+ * generated `action_specs` array:
+ *
+ * ```ts
+ * new ActionRegistry([...protocol_action_specs, ...action_specs])
+ * ```
+ *
+ * Derived from `protocol_actions` so a future protocol action lands in one
+ * place — the two arrays cannot drift.
+ */
+export declare const protocol_action_specs: ReadonlyArray<ActionSpecUnion>;
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAqC,CAAC;AAEzF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,eAAe,CAEhE,CAAC"}