@fuzdev/fuz_app 0.48.0 → 0.50.0

package/dist/actions/action_registry.js

@@ -1,13 +1,37 @@
 /**
  * `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
  */
-// TODO @action-system-review Many getters below are stub API surface — only `spec_by_method`,
-// `request_response_specs`, `remote_notification_specs`, `local_call_specs`,
-// `frontend_methods`, `backend_methods`, and `methods` are used by consumers (codegen).
-// The rest are pre-built for future use. Revisit which getters to keep when the action
-// system matures. Also consider lazy memoization (`??=` or derived).
+// TODO @action-system-review Many getters below are stub API surface — only
+// `spec_by_method`, `methods`, the kind-narrow `*_specs` (`request_response_specs`,
+// `remote_notification_specs`, `local_call_specs`), the `*_handled_*` pair,
+// the `*_relevant_to_*` pair, and `broadcast_*` / `backend_initiated_*` are
+// used by codegen. The auth + initiator-direction getters are pre-built for
+// future use. Revisit which getters to keep when the action system matures.
 /**
  * Utility class to manage and query action specifications.
  * Provides helper methods to get actions by various criteria.
@@ -17,9 +41,14 @@ export class ActionRegistry {
     constructor(specs) {
         this.specs = specs;
     }
+    #spec_by_method;
     get spec_by_method() {
-        return new Map(this.specs.map((spec) => [spec.method, spec]));
+        return (this.#spec_by_method ??= new Map(this.specs.map((spec) => [spec.method, spec])));
+    }
+    get methods() {
+        return this.specs.map((spec) => spec.method);
     }
+    // --- Kind-narrow getters ---
     get request_response_specs() {
         return this.specs.filter((spec) => spec.kind === 'request_response');
     }
@@ -29,44 +58,73 @@ export class ActionRegistry {
     get local_call_specs() {
         return this.specs.filter((spec) => spec.kind === 'local_call');
     }
-    // TODO @action-system-review `backend_specs` filters out local_call (can't run on backend);
-    // `frontend_specs` returns all specs (all action kinds are relevant to the frontend).
-    // Revisit whether these filters are correct as the action system matures.
-    get backend_specs() {
+    get request_response_methods() {
+        return this.request_response_specs.map((spec) => spec.method);
+    }
+    get remote_notification_methods() {
+        return this.remote_notification_specs.map((spec) => spec.method);
+    }
+    get local_call_methods() {
+        return this.local_call_specs.map((spec) => spec.method);
+    }
+    // --- Loose "relevant to side" getters ---
+    // Backs the `FrontendActionMethod` / `BackendActionMethod` enums — the
+    // typed-Proxy method enums where every spec the side might encounter
+    // (call, receive, or execute) belongs in the union.
+    get specs_relevant_to_frontend() {
+        return this.specs.slice();
+    }
+    get specs_relevant_to_backend() {
         return this.specs.filter((spec) => spec.kind !== 'local_call');
     }
-    get frontend_specs() {
-        return this.specs;
+    get methods_relevant_to_frontend() {
+        return this.specs_relevant_to_frontend.map((spec) => spec.method);
     }
-    get backend_to_frontend_specs() {
-        return this.specs.filter((spec) => spec.initiator === 'backend' || spec.initiator === 'both');
+    get methods_relevant_to_backend() {
+        return this.specs_relevant_to_backend.map((spec) => spec.method);
     }
-    get frontend_to_backend_specs() {
-        return this.specs.filter((spec) => spec.initiator === 'frontend' || spec.initiator === 'both');
+    // --- Narrow handler-side getters (request_response only) ---
+    // "Handled" = this side **receives** (initiator excludes own side).
+    // Drives `FrontendRequestResponseMethod` / `BackendRequestResponseMethod`
+    // enums and the typed `BackendActionHandlers` mapped type.
+    get frontend_handled_specs() {
+        return this.request_response_specs.filter((spec) => spec.initiator !== 'frontend');
     }
-    get public_specs() {
-        return this.specs.filter((spec) => spec.auth === 'public');
+    get backend_handled_specs() {
+        return this.request_response_specs.filter((spec) => spec.initiator !== 'backend');
     }
-    get authenticated_specs() {
-        return this.specs.filter((spec) => spec.auth === 'authenticated');
+    get frontend_handled_methods() {
+        return this.frontend_handled_specs.map((spec) => spec.method);
     }
-    get methods() {
-        return this.specs.map((spec) => spec.method);
+    get backend_handled_methods() {
+        return this.backend_handled_specs.map((spec) => spec.method);
     }
-    get request_response_methods() {
-        return this.request_response_specs.map((spec) => spec.method);
+    // --- Broadcast / backend-initiated getters ---
+    // Excludes `streams` targets (request-scoped progress notifications
+    // invoked via `ctx.notify` inside the parent handler). Today
+    // `broadcast_*` and `backend_initiated_*` return the same set;
+    // `backend_initiated_*` is the forward-looking name that will widen
+    // when local_calls or backend-initiated `request_response` join.
+    get broadcast_specs() {
+        const streams_targets = this.#get_streams_target_methods();
+        return this.remote_notification_specs.filter((spec) => spec.initiator !== 'frontend' && !streams_targets.has(spec.method));
     }
-    get remote_notification_methods() {
-        return this.remote_notification_specs.map((spec) => spec.method);
+    get broadcast_methods() {
+        return this.broadcast_specs.map((spec) => spec.method);
     }
-    get local_call_methods() {
-        return this.local_call_specs.map((spec) => spec.method);
+    get backend_initiated_specs() {
+        const streams_targets = this.#get_streams_target_methods();
+        return this.specs.filter((spec) => spec.initiator !== 'frontend' && !streams_targets.has(spec.method));
     }
-    get backend_methods() {
-        return this.backend_specs.map((spec) => spec.method);
+    get backend_initiated_methods() {
+        return this.backend_initiated_specs.map((spec) => spec.method);
     }
-    get frontend_methods() {
-        return this.frontend_specs.map((spec) => spec.method);
+    // --- Initiator-direction (pre-built, unused by codegen today) ---
+    get backend_to_frontend_specs() {
+        return this.specs.filter((spec) => spec.initiator === 'backend' || spec.initiator === 'both');
+    }
+    get frontend_to_backend_specs() {
+        return this.specs.filter((spec) => spec.initiator === 'frontend' || spec.initiator === 'both');
     }
     get frontend_to_backend_methods() {
         return this.frontend_to_backend_specs.map((spec) => spec.method);
@@ -74,10 +132,29 @@ export class ActionRegistry {
     get backend_to_frontend_methods() {
         return this.backend_to_frontend_specs.map((spec) => spec.method);
     }
+    // --- Auth (pre-built, unused by codegen today) ---
+    get public_specs() {
+        return this.specs.filter((spec) => spec.auth === 'public');
+    }
+    get authenticated_specs() {
+        return this.specs.filter((spec) => spec.auth === 'authenticated');
+    }
     get public_methods() {
         return this.public_specs.map((spec) => spec.method);
     }
     get authenticated_methods() {
         return this.authenticated_specs.map((spec) => spec.method);
     }
+    // --- Internal ---
+    #streams_target_methods;
+    #get_streams_target_methods() {
+        if (this.#streams_target_methods)
+            return this.#streams_target_methods;
+        const targets = new Set();
+        for (const spec of this.specs) {
+            if (spec.streams)
+                targets.add(spec.streams);
+        }
+        return (this.#streams_target_methods = targets);
+    }
 }

package/dist/actions/action_types.d.ts

@@ -3,8 +3,8 @@
  *
  * 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.
+ * shared protocol actions (e.g. `heartbeat_action`) can name them without
+ * pulling in server-only modules.
  *
  * @module
  */

package/dist/actions/action_types.js

@@ -3,8 +3,8 @@
  *
  * 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.
+ * 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
+ * `./protocol.js`) 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 `./protocol.js`) 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
+ * `./protocol.js`) 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 `./protocol.js`) 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 `./protocol.js`) 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 `./protocol.js`) 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 `./protocol.js`) 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 `./protocol.js`) 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 `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"}

package/dist/actions/protocol.js

@@ -0,0 +1,46 @@
+/**
+ * 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 `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 { cancel_action } from './cancel.js';
+import { heartbeat_action } from './heartbeat.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 const protocol_actions = [heartbeat_action, cancel_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 const protocol_action_specs = protocol_actions.map((a) => a.spec);

package/dist/actions/register_action_ws.d.ts

@@ -2,7 +2,7 @@
  * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
  *
  * Most consumers should mount WS endpoints via `register_ws_endpoint`
- * (`./register_ws_endpoint.js`), which wraps this function with the standard
+ * (`actions/register_ws_endpoint.ts`), which wraps this function with the standard
  * upgrade stack (origin check + auth + optional role). This module stays
  * exported as the lower-level entry point for tests that drive the
  * dispatcher directly via `create_ws_test_harness`.
@@ -97,8 +97,9 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
      * The actions registered on this endpoint — each carries a spec (drives
      * method lookup, per-action auth, input/output validation) and an
      * optional handler (omit for client-only specs like inbound
-     * notifications). Include the shared `heartbeat_action` here to
-     * complete the disconnect-detection pairing with the frontend client.
+     * notifications). Spread `protocol_actions` from `actions/protocol.ts`
+     * here to complete the disconnect-detection + per-request cancel
+     * pairing with the frontend client.
      */
     actions: ReadonlyArray<Action<TCtx>>;
     /**

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

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

package/dist/actions/register_action_ws.js

@@ -2,7 +2,7 @@
  * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
  *
  * Most consumers should mount WS endpoints via `register_ws_endpoint`
- * (`./register_ws_endpoint.js`), which wraps this function with the standard
+ * (`actions/register_ws_endpoint.ts`), which wraps this function with the standard
  * upgrade stack (origin check + auth + optional role). This module stays
  * exported as the lower-level entry point for tests that drive the
  * dispatcher directly via `create_ws_test_harness`.

package/dist/auth/account_action_specs.d.ts

@@ -2,7 +2,7 @@
  * Account RPC action specs — declarative contract for self-service account
  * operations. Import this module for the specs, Input/Output schemas, and
  * the `all_account_action_specs` registry. Handlers live in
- * `./account_actions.js` so consumers doing typed-client codegen or surface
+ * `auth/account_actions.ts` so consumers doing typed-client codegen or surface
  * reporting don't transitively drag in server-only query code.
  *
  * @module

package/dist/auth/account_action_specs.js

@@ -2,7 +2,7 @@
  * Account RPC action specs — declarative contract for self-service account
  * operations. Import this module for the specs, Input/Output schemas, and
  * the `all_account_action_specs` registry. Handlers live in
- * `./account_actions.js` so consumers doing typed-client codegen or surface
+ * `auth/account_actions.ts` so consumers doing typed-client codegen or surface
  * reporting don't transitively drag in server-only query code.
  *
  * @module

package/dist/auth/account_actions.d.ts

@@ -9,14 +9,14 @@
  * - API token management: `account_token_create`, `account_token_list`,
  *   `account_token_revoke`.
  *
- * The action specs themselves live in `./account_action_specs.js`. Every spec
+ * The action specs themselves live in `auth/account_action_specs.ts`. Every spec
  * declares `auth: 'authenticated'` so the dispatcher enforces auth before the
  * handler runs. Revoke operations are account-scoped (via
  * `query_session_revoke_for_account` / `query_revoke_api_token_for_account`)
  * so passing another account's session or token id returns `revoked: false`
  * rather than revealing whether the id exists.
  *
- * Counterpart to `account_routes.ts`, which keeps the cookie-lifecycle flows
+ * Counterpart to `auth/account_routes.ts`, which keeps the cookie-lifecycle flows
  * (`login`, `logout`, `password`, `signup`, `bootstrap`) on REST.
  *
  * @module

package/dist/auth/account_actions.js

@@ -9,14 +9,14 @@
  * - API token management: `account_token_create`, `account_token_list`,
  *   `account_token_revoke`.
  *
- * The action specs themselves live in `./account_action_specs.js`. Every spec
+ * The action specs themselves live in `auth/account_action_specs.ts`. Every spec
  * declares `auth: 'authenticated'` so the dispatcher enforces auth before the
  * handler runs. Revoke operations are account-scoped (via
  * `query_session_revoke_for_account` / `query_revoke_api_token_for_account`)
  * so passing another account's session or token id returns `revoked: false`
  * rather than revealing whether the id exists.
  *
- * Counterpart to `account_routes.ts`, which keeps the cookie-lifecycle flows
+ * Counterpart to `auth/account_routes.ts`, which keeps the cookie-lifecycle flows
  * (`login`, `logout`, `password`, `signup`, `bootstrap`) on REST.
  *
  * @module

package/dist/auth/admin_action_specs.d.ts

@@ -2,7 +2,7 @@
  * Admin RPC action specs — declarative contract for admin-only operations.
  *
  * Import this module for the specs, Input/Output schemas, and the
- * `all_admin_action_specs` registry. Handlers live in `./admin_actions.js`.
+ * `all_admin_action_specs` registry. Handlers live in `auth/admin_actions.ts`.
  *
  * Authorization is declared at the spec level (`auth: {role: ROLE_ADMIN}`)
  * so the RPC dispatcher enforces admin before the handler runs and the

package/dist/auth/admin_action_specs.js

@@ -2,7 +2,7 @@
  * Admin RPC action specs — declarative contract for admin-only operations.
  *
  * Import this module for the specs, Input/Output schemas, and the
- * `all_admin_action_specs` registry. Handlers live in `./admin_actions.js`.
+ * `all_admin_action_specs` registry. Handlers live in `auth/admin_actions.ts`.
  *
  * Authorization is declared at the spec level (`auth: {role: ROLE_ADMIN}`)
  * so the RPC dispatcher enforces admin before the handler runs and the