@fuzdev/fuz_app 0.51.0 → 0.53.0

package/dist/actions/action_spec.d.ts

@@ -5,10 +5,8 @@
  * auth, side effects, and input/output schemas. Bridge functions in
  * `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.
- * Current state: bridge is stable, registry and codegen are partially stub API.
- * Search for `@action-system-review` across the actions/ and routes/ modules.
+ * @see `actions/action_rpc.ts` for the JSON-RPC dispatcher
+ * @see `actions/register_action_ws.ts` for the WebSocket dispatcher
  *
  * @module
  */
@@ -59,6 +57,40 @@ export declare const ActionSpec: z.ZodObject<{
      * consumer-side concern.
      */
     streams: z.ZodOptional<z.ZodString>;
+    /**
+     * Error reason codes this action may surface via `error.data.reason` on
+     * failure. Declarative metadata mirroring the `streams` precedent —
+     * codegen, UI form-state matching, and docs read it off the spec instead
+     * of scanning handler implementations. Reuses the same `as const` string
+     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * import either side. Optional — actions that surface only standard
+     * transport errors leave it unset.
+     */
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    /**
+     * Rate limit key the RPC dispatcher consults for this action. Optional —
+     * actions without it skip the rate-limit hook entirely.
+     *
+     * - `'ip'` — keyed on the resolved client IP (`get_client_ip(c)`).
+     * - `'account'` — keyed on the post-auth actor id (`request_context.actor.id`).
+     *   Registration-time error if paired with `auth: 'public'` (no actor).
+     * - `'both'` — both checks run; either can block.
+     *
+     * Throttle-requests semantics — every invocation records, regardless of
+     * outcome (different from REST login's throttle-failures, which resets
+     * on success). Suits admin mutation oracles (`invite_create` account-
+     * existence probe) where the *successful* invocation is the threat.
+     *
+     * Today only `RequestResponseActionSpec` is consulted by the RPC
+     * dispatcher. The field is on the base for shape symmetry with
+     * `streams` and `error_reasons`; remote_notification / local_call
+     * dispatchers don't read it.
+     */
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
 }, z.core.$strict>;
 export type ActionSpec = z.infer<typeof ActionSpec>;
 export declare const RequestResponseActionSpec: z.ZodObject<{
@@ -73,6 +105,12 @@ export declare const RequestResponseActionSpec: z.ZodObject<{
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
     auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
         role: z.ZodString;
@@ -90,6 +128,12 @@ export declare const RemoteNotificationActionSpec: z.ZodObject<{
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
     kind: z.ZodDefault<z.ZodLiteral<"remote_notification">>;
     auth: z.ZodDefault<z.ZodNull>;
     side_effects: z.ZodDefault<z.ZodLiteral<true>>;
@@ -98,8 +142,8 @@ export declare const RemoteNotificationActionSpec: z.ZodObject<{
 }, z.core.$strict>;
 export type RemoteNotificationActionSpec = z.infer<typeof RemoteNotificationActionSpec>;
 /**
- * Local calls can wrap synchronous or asynchronous actions,
- * and are the escape hatch for remote APIs that do not support SAES.
+ * Local calls can wrap synchronous or asynchronous actions, and are the
+ * escape hatch for remote APIs that do not support SAES.
  */
 export declare const LocalCallActionSpec: z.ZodObject<{
     method: z.ZodString;
@@ -114,6 +158,12 @@ export declare const LocalCallActionSpec: z.ZodObject<{
     async: z.ZodBoolean;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
     kind: z.ZodDefault<z.ZodLiteral<"local_call">>;
     auth: z.ZodDefault<z.ZodNull>;
 }, z.core.$strict>;
@@ -130,6 +180,12 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
     auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
         role: z.ZodString;
@@ -145,6 +201,12 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
     kind: z.ZodDefault<z.ZodLiteral<"remote_notification">>;
     auth: z.ZodDefault<z.ZodNull>;
     side_effects: z.ZodDefault<z.ZodLiteral<true>>;
@@ -163,10 +225,17 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
     async: z.ZodBoolean;
     description: z.ZodString;
     streams: z.ZodOptional<z.ZodString>;
+    error_reasons: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    rate_limit: z.ZodOptional<z.ZodEnum<{
+        account: "account";
+        ip: "ip";
+        both: "both";
+    }>>;
     kind: z.ZodDefault<z.ZodLiteral<"local_call">>;
     auth: z.ZodDefault<z.ZodNull>;
 }, z.core.$strict>]>;
 export type ActionSpecUnion = z.infer<typeof ActionSpecUnion>;
+/** Structural type guard for any `ActionSpecUnion` variant — checks `kind` is one of the three known values. */
 export declare const is_action_spec: (value: unknown) => value is ActionSpecUnion;
 export declare const ActionEventPhase: z.ZodEnum<{
     send_request: "send_request";

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

@@ -1 +1 @@
-{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;;;;;;;;;;;;;;OAkBG;;;;;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/actions/action_spec.js

@@ -5,14 +5,13 @@
  * auth, side effects, and input/output schemas. Bridge functions in
  * `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.
- * Current state: bridge is stable, registry and codegen are partially stub API.
- * Search for `@action-system-review` across the actions/ and routes/ modules.
+ * @see `actions/action_rpc.ts` for the JSON-RPC dispatcher
+ * @see `actions/register_action_ws.ts` for the WebSocket dispatcher
  *
  * @module
  */
 import { z } from 'zod';
+import { RateLimitKey } from '../http/error_schemas.js';
 export const ActionKind = z.enum(['request_response', 'remote_notification', 'local_call']);
 export const ActionInitiator = z.enum(['frontend', 'backend', 'both']);
 export const ActionAuth = z.union([
@@ -40,6 +39,36 @@ export const ActionSpec = z.strictObject({
      * consumer-side concern.
      */
     streams: z.string().optional(),
+    /**
+     * Error reason codes this action may surface via `error.data.reason` on
+     * failure. Declarative metadata mirroring the `streams` precedent —
+     * codegen, UI form-state matching, and docs read it off the spec instead
+     * of scanning handler implementations. Reuses the same `as const` string
+     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * import either side. Optional — actions that surface only standard
+     * transport errors leave it unset.
+     */
+    error_reasons: z.array(z.string()).readonly().optional(),
+    /**
+     * Rate limit key the RPC dispatcher consults for this action. Optional —
+     * actions without it skip the rate-limit hook entirely.
+     *
+     * - `'ip'` — keyed on the resolved client IP (`get_client_ip(c)`).
+     * - `'account'` — keyed on the post-auth actor id (`request_context.actor.id`).
+     *   Registration-time error if paired with `auth: 'public'` (no actor).
+     * - `'both'` — both checks run; either can block.
+     *
+     * Throttle-requests semantics — every invocation records, regardless of
+     * outcome (different from REST login's throttle-failures, which resets
+     * on success). Suits admin mutation oracles (`invite_create` account-
+     * existence probe) where the *successful* invocation is the threat.
+     *
+     * Today only `RequestResponseActionSpec` is consulted by the RPC
+     * dispatcher. The field is on the base for shape symmetry with
+     * `streams` and `error_reasons`; remote_notification / local_call
+     * dispatchers don't read it.
+     */
+    rate_limit: RateLimitKey.optional(),
 });
 export const RequestResponseActionSpec = ActionSpec.extend({
     kind: z.literal('request_response').default('request_response'),
@@ -54,8 +83,8 @@ export const RemoteNotificationActionSpec = ActionSpec.extend({
     async: z.literal(true).default(true),
 });
 /**
- * Local calls can wrap synchronous or asynchronous actions,
- * and are the escape hatch for remote APIs that do not support SAES.
+ * Local calls can wrap synchronous or asynchronous actions, and are the
+ * escape hatch for remote APIs that do not support SAES.
  */
 export const LocalCallActionSpec = ActionSpec.extend({
     kind: z.literal('local_call').default('local_call'),
@@ -66,6 +95,7 @@ export const ActionSpecUnion = z.union([
     RemoteNotificationActionSpec,
     LocalCallActionSpec,
 ]);
+/** Structural type guard for any `ActionSpecUnion` variant — checks `kind` is one of the three known values. */
 export const is_action_spec = (value) => value !== null &&
     typeof value === 'object' &&
     'method' in value &&

package/dist/actions/frontend_rpc_client.d.ts

@@ -142,14 +142,6 @@ export interface FrontendRpcClient<TApi> {
     /** Action environment — exposed for consumers that need to share it (e.g. attach a notification handler registry). */
     environment: ActionEventEnvironment;
 }
-/**
- * Build a frontend-only typed RPC client.
- *
- * @param options - `specs` (required), optional `path` / `transports` /
- *   `transport_for_method` / `on_action_event`
- * @returns `{api, api_result, peer, environment}` — both Proxy shapes plus
- *   the underlying primitives. `api` throws on `{ok: false}`; `api_result`
- *   returns the Result.
- */
+/** Build a frontend-only typed RPC client. See module doc for the bundle's design. */
 export declare const create_frontend_rpc_client: <TApi extends object>(options: CreateFrontendRpcClientOptions<TApi>) => FrontendRpcClient<TApi>;
 //# sourceMappingURL=frontend_rpc_client.d.ts.map

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;;;;;;;;;;;;;;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"}
+{"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,sFAAsF;AACtF,eAAO,MAAM,0BAA0B,GAAI,IAAI,SAAS,MAAM,EAC7D,SAAS,8BAA8B,CAAC,IAAI,CAAC,KAC3C,iBAAiB,CAAC,IAAI,CAsBxB,CAAC"}

package/dist/actions/frontend_rpc_client.js

@@ -50,15 +50,7 @@ import { ActionPeer } from './action_peer.js';
 import { Transports } from './transports.js';
 import { FrontendHttpTransport } from './transports_http.js';
 import { create_rpc_client, create_throwing_api, } from './rpc_client.js';
-/**
- * Build a frontend-only typed RPC client.
- *
- * @param options - `specs` (required), optional `path` / `transports` /
- *   `transport_for_method` / `on_action_event`
- * @returns `{api, api_result, peer, environment}` — both Proxy shapes plus
- *   the underlying primitives. `api` throws on `{ok: false}`; `api_result`
- *   returns the Result.
- */
+/** Build a frontend-only typed RPC client. See module doc for the bundle's design. */
 export const create_frontend_rpc_client = (options) => {
     const registry = new ActionRegistry([...options.specs]);
     const environment = {

package/dist/actions/register_action_ws.d.ts

@@ -32,6 +32,7 @@ import type { Context, Hono } from 'hono';
 import type { UpgradeWebSocket, WSContext } from 'hono/ws';
 import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
 import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { RateLimiter } from '../rate_limiter.js';
 import { type Action, type BaseHandlerContext, type WsActionHandler } from './action_types.js';
 import { BackendWebsocketTransport, type ConnectionIdentity } from './transports_ws_backend.js';
 export type { Action, BaseHandlerContext, WsActionHandler };
@@ -140,6 +141,21 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
      * down the transport's internal state. Errors are logged and swallowed.
      */
     on_socket_close?: (ctx: SocketCloseContext) => void | Promise<void>;
+    /**
+     * Per-IP rate limiter consulted for actions whose spec declares
+     * `rate_limit: 'ip'` or `'both'`. `null` (or omitted) disables the
+     * IP check. Same limiter is shared with the HTTP RPC dispatcher so
+     * one budget covers both transports per action. Resolved at upgrade
+     * time and reused for every message on the socket.
+     */
+    action_ip_rate_limiter?: RateLimiter | null;
+    /**
+     * Per-actor rate limiter consulted for actions whose spec declares
+     * `rate_limit: 'account'` or `'both'`. Keyed on
+     * `request_context.actor.id`. `null` (or omitted) disables the
+     * account check. Same limiter is shared with the HTTP RPC dispatcher.
+     */
+    action_account_rate_limiter?: RateLimiter | null;
 }
 /** Result of `register_action_ws`. */
 export interface RegisterActionWsResult {
@@ -163,6 +179,9 @@ export interface RegisterActionWsResult {
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
+ * @mutates options.app - registers a `GET path` route via `upgradeWebSocket`
+ * @mutates options.transport - on every message, adds/removes connections
+ *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export declare const register_action_ws: <TCtx extends BaseHandlerContext>(options: RegisterActionWsOptions<TCtx>) => RegisterActionWsResult;
 //# sourceMappingURL=register_action_ws.d.ts.map

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

package/dist/actions/register_action_ws.js

@@ -34,6 +34,7 @@ import { Logger } from '@fuzdev/fuz_util/log.js';
 import { get_request_context, has_role } from '../auth/request_context.js';
 import { hash_session_token } from '../auth/session_queries.js';
 import { ROLE_KEEPER } from '../auth/role_schema.js';
+import { get_client_ip } from '../http/proxy.js';
 import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
@@ -61,9 +62,12 @@ export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
  *
  * @returns the transport (supplied or freshly created) — retain it to wire
  *   `create_ws_auth_guard` or broadcast on audit events.
+ * @mutates options.app - registers a `GET path` route via `upgradeWebSocket`
+ * @mutates options.transport - on every message, adds/removes connections
+ *   in the transport's internal maps via `add_connection` / `remove_connection`
  */
 export const register_action_ws = (options) => {
-    const { path, app, upgradeWebSocket, actions, extend_context, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;
+    const { path, app, upgradeWebSocket, actions, extend_context, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, action_ip_rate_limiter = null, action_account_rate_limiter = null, } = options;
     // Fan the unified actions array into the two lookups the dispatcher
     // consults at message time. Keeping them internal means the composable
     // `{spec, handler}` tuple remains the only shape consumers name.
@@ -73,6 +77,12 @@ export const register_action_ws = (options) => {
         spec_by_method.set(action.spec.method, action.spec);
         if (action.handler)
             handlers[action.spec.method] = action.handler;
+        // Reject account-keyed rate limiting on public actions — the dispatcher
+        // has no actor to key on. Mirrors the HTTP RPC registration check.
+        if ((action.spec.rate_limit === 'account' || action.spec.rate_limit === 'both') &&
+            action.spec.auth === 'public') {
+            throw new Error(`WS action "${action.spec.method}" declares rate_limit: '${action.spec.rate_limit}' but auth: 'public' — no actor available for account-keyed limiting. Use 'ip' or change auth.`);
+        }
     }
     const heartbeat_enabled = heartbeat !== false;
     const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
@@ -87,6 +97,10 @@ export const register_action_ws = (options) => {
         // non-null by the time we get here.
         const request_context = get_request_context(c);
         const account_id = request_context.account.id;
+        // Resolved at upgrade — every message on this socket shares the
+        // same client IP, so we capture once and reuse for rate-limit
+        // keying. `'unknown'` if the proxy middleware wasn't in the stack.
+        const client_ip = get_client_ip(c);
         const credential_type = c.get(CREDENTIAL_TYPE_KEY);
         // Session-based connections have a token hash for targeted revocation.
         // Bearer/daemon connections pass null — still reachable via
@@ -245,6 +259,35 @@ export const register_action_ws = (options) => {
                         return;
                     }
                 }
+                // Rate limit — throttle-requests semantics, mirrors the HTTP RPC
+                // dispatcher. Same limiters are shared across transports so an
+                // attacker can't bypass the budget by switching from RPC to WS.
+                const rate_limit = spec.rate_limit;
+                if (rate_limit) {
+                    const ip_check = action_ip_rate_limiter && (rate_limit === 'ip' || rate_limit === 'both');
+                    const account_check = action_account_rate_limiter && (rate_limit === 'account' || rate_limit === 'both');
+                    const send_rate_limited = (retry_after) => {
+                        ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.rate_limited('rate limited', { retry_after }))));
+                    };
+                    if (ip_check) {
+                        const result = action_ip_rate_limiter.check(client_ip);
+                        if (!result.allowed) {
+                            send_rate_limited(result.retry_after);
+                            return;
+                        }
+                    }
+                    if (account_check) {
+                        const result = action_account_rate_limiter.check(request_context.actor.id);
+                        if (!result.allowed) {
+                            send_rate_limited(result.retry_after);
+                            return;
+                        }
+                    }
+                    if (ip_check)
+                        action_ip_rate_limiter.record(client_ip);
+                    if (account_check)
+                        action_account_rate_limiter.record(request_context.actor.id);
+                }
                 // Look up handler — method is validated against spec_by_method above.
                 const handler = handlers[method];
                 if (!handler) {

package/dist/actions/register_ws_endpoint.d.ts

@@ -41,6 +41,9 @@ export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> exte
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ *
+ * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;
 //# sourceMappingURL=register_ws_endpoint.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -26,6 +26,9 @@ import { register_action_ws, } from './register_action_ws.js';
  * Returns the `BackendWebsocketTransport` (supplied or freshly
  * created), same as `register_action_ws` — retain it to wire
  * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ *
+ * @mutates options.app - applies origin/auth/role middleware via `app.use`,
+ *   then registers the `GET path` route via the inner `register_action_ws`
  */
 export const register_ws_endpoint = (options) => {
     const { app, path, allowed_origins, required_role, log = new Logger('[ws]'), ...rest } = options;

package/dist/actions/request_tracker.svelte.d.ts

@@ -12,9 +12,6 @@ import { type JsonrpcErrorResponse, type JsonrpcRequestId, type JsonrpcResponseO
 type Datetime = string & {
     readonly __brand: 'Datetime';
 };
-/**
- * Represents a pending request with its associated state.
- */
 export declare class RequestTrackerItem {
     readonly id: JsonrpcRequestId;
     readonly deferred: Deferred<JsonrpcResponseOrError>;
@@ -24,29 +21,35 @@ export declare class RequestTrackerItem {
     constructor(id: JsonrpcRequestId, deferred: Deferred<JsonrpcResponseOrError>, created: Datetime, status: AsyncStatus, timeout: NodeJS.Timeout | undefined);
 }
 /**
- * Tracks JSON-RPC requests and their responses to manage promises and timeouts.
- * Used by transports to handle the request-response lifecycle.
+ * Reactive pending-request store with per-request timeouts. Used by transports
+ * that don't delegate request/response correlation to a `WebsocketRpcConnection`.
  */
 export declare class RequestTracker {
     readonly pending_requests: SvelteMap<JsonrpcRequestId, RequestTrackerItem>;
     readonly request_timeout_ms: number;
     constructor(request_timeout_ms?: number);
     /**
-     * Track a new request with the given id.
-     * @param id - the request id
-     * @returns a deferred promise that will be resolved when the response is received
+     * Track a new request keyed by `id`.
+     *
+     * @returns deferred resolved on response, or rejected via the timeout
+     * @mutates this - inserts a `RequestTrackerItem` into `pending_requests`
+     *   and arms a timeout that auto-rejects after `request_timeout_ms`;
+     *   clears any prior timeout for the same id
      */
     track_request(id: JsonrpcRequestId): Deferred<JsonrpcResponseOrError>;
     /**
-     * Resolve a pending request with the given response data.
-     * @param id - the request id
-     * @param response - the response data
+     * Resolve a pending request with its response.
+     *
+     * @mutates this - clears the timeout, marks status `'success'`,
+     *   resolves the deferred, and removes the entry from `pending_requests`
      */
     resolve_request(id: JsonrpcRequestId, response: JsonrpcResponseOrError): void;
     /**
-     * Rejects a pending request with the given error.
-     * @param id - the request id
-     * @param error_message - the complete `JsonrpcErrorResponse` object
+     * Reject a pending request with `error_message`.
+     *
+     * @mutates this - clears the timeout, marks status `'failure'`,
+     *   rejects the deferred with a `ThrownJsonrpcError`, and removes the
+     *   entry from `pending_requests`
      */
     reject_request(id: JsonrpcRequestId, error_message: JsonrpcErrorResponse): void;
     /**
@@ -55,13 +58,18 @@ export declare class RequestTracker {
      */
     handle_message(message: any): void;
     /**
-     * Cancel a pending request.
-     * @param id - the request id
+     * Cancel a pending request without rejecting its deferred — just
+     * cleanup. The caller's promise stays unsettled; pair with an external
+     * resolution if needed.
+     *
+     * @mutates this - clears the timeout and removes the entry from `pending_requests`
      */
     cancel_request(id: JsonrpcRequestId): void;
     /**
      * Cancel all pending requests.
      * @param reason - optional reason to include in rejection
+     * @mutates this - clears every timeout, marks each status `'failure'`,
+     *   rejects each deferred with `internal_error`, and empties `pending_requests`
      */
     cancel_all_requests(reason?: string): void;
 }

package/dist/actions/request_tracker.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request_tracker.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/request_tracker.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,2BAA2B,CAAC;AAC3F,OAAO,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAG5B,2DAA2D;AAC3D,KAAK,QAAQ,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAMxD;;GAEG;AACH,qBAAa,kBAAkB;IAC9B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAiB;IACpC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAgB;gBAGlD,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,EAC1C,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS;CAQpC;AAED;;;GAGG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAmB;IAC7F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;gBAExB,kBAAkB,SAAU;IAIxC;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CAAC,sBAAsB,CAAC;IA6BrE;;;;OAIG;IACH,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAkB7E;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,GAAG,IAAI;IAuB/E;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAiBlC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAe1C;;;OAGG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CAiB1C"}
+{"version":3,"file":"request_tracker.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/request_tracker.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAC,MAAM,2BAA2B,CAAC;AAC3F,OAAO,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,MAAM,oBAAoB,CAAC;AAG5B,2DAA2D;AAC3D,KAAK,QAAQ,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAMxD,qBAAa,kBAAkB;IAC9B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAiB;IACpC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS,CAAgB;gBAGlD,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,QAAQ,CAAC,sBAAsB,CAAC,EAC1C,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,SAAS;CAQpC;AAED;;;GAGG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAmB;IAC7F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;gBAExB,kBAAkB,SAAU;IAIxC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,EAAE,gBAAgB,GAAG,QAAQ,CAAC,sBAAsB,CAAC;IA6BrE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAkB7E;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,GAAG,IAAI;IAuB/E;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAiBlC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAe1C;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CAiB1C"}

package/dist/actions/request_tracker.svelte.js

@@ -12,9 +12,6 @@ import { ThrownJsonrpcError, JSONRPC_ERROR_CODES } from '../http/jsonrpc_errors.
 const get_datetime_now = () => new Date().toISOString();
 // TODO what if this uses a tracker id param that's an opaque UUID but can be used for action association?
 // TODO name, like `TrackedRequest`? or is this implicit namespacing and generic name preferred
-/**
- * Represents a pending request with its associated state.
- */
 export class RequestTrackerItem {
     id;
     deferred;
@@ -30,8 +27,8 @@ export class RequestTrackerItem {
     }
 }
 /**
- * Tracks JSON-RPC requests and their responses to manage promises and timeouts.
- * Used by transports to handle the request-response lifecycle.
+ * Reactive pending-request store with per-request timeouts. Used by transports
+ * that don't delegate request/response correlation to a `WebsocketRpcConnection`.
  */
 export class RequestTracker {
     pending_requests = new SvelteMap();
@@ -40,9 +37,12 @@ export class RequestTracker {
         this.request_timeout_ms = request_timeout_ms;
     }
     /**
-     * Track a new request with the given id.
-     * @param id - the request id
-     * @returns a deferred promise that will be resolved when the response is received
+     * Track a new request keyed by `id`.
+     *
+     * @returns deferred resolved on response, or rejected via the timeout
+     * @mutates this - inserts a `RequestTrackerItem` into `pending_requests`
+     *   and arms a timeout that auto-rejects after `request_timeout_ms`;
+     *   clears any prior timeout for the same id
      */
     track_request(id) {
         const deferred = create_deferred();
@@ -66,9 +66,10 @@ export class RequestTracker {
         return deferred;
     }
     /**
-     * Resolve a pending request with the given response data.
-     * @param id - the request id
-     * @param response - the response data
+     * Resolve a pending request with its response.
+     *
+     * @mutates this - clears the timeout, marks status `'success'`,
+     *   resolves the deferred, and removes the entry from `pending_requests`
      */
     resolve_request(id, response) {
         const request = this.pending_requests.get(id);
@@ -86,9 +87,11 @@ export class RequestTracker {
         this.pending_requests.delete(id);
     }
     /**
-     * Rejects a pending request with the given error.
-     * @param id - the request id
-     * @param error_message - the complete `JsonrpcErrorResponse` object
+     * Reject a pending request with `error_message`.
+     *
+     * @mutates this - clears the timeout, marks status `'failure'`,
+     *   rejects the deferred with a `ThrownJsonrpcError`, and removes the
+     *   entry from `pending_requests`
      */
     reject_request(id, error_message) {
         const request = this.pending_requests.get(id);
@@ -127,8 +130,11 @@ export class RequestTracker {
         // ignore other messages
     }
     /**
-     * Cancel a pending request.
-     * @param id - the request id
+     * Cancel a pending request without rejecting its deferred — just
+     * cleanup. The caller's promise stays unsettled; pair with an external
+     * resolution if needed.
+     *
+     * @mutates this - clears the timeout and removes the entry from `pending_requests`
      */
     cancel_request(id) {
         const request = this.pending_requests.get(id);
@@ -145,6 +151,8 @@ export class RequestTracker {
     /**
      * Cancel all pending requests.
      * @param reason - optional reason to include in rejection
+     * @mutates this - clears every timeout, marks each status `'failure'`,
+     *   rejects each deferred with `internal_error`, and empties `pending_requests`
      */
     cancel_all_requests(reason) {
         for (const [id, request] of this.pending_requests.entries()) {

package/dist/actions/rpc_client.d.ts

@@ -68,7 +68,6 @@ export interface CreateRpcClientOptions<TApi extends object = object> {
  * const api_result = create_rpc_client<MyActionsApi>({peer, environment});
  * ```
  *
- * @param options - client options (peer, environment, optional callbacks)
  * @returns a Proxy typed as `TApi` that responds to any method name found in the environment's specs
  */
 export declare const create_rpc_client: <TApi extends object>(options: CreateRpcClientOptions<TApi>) => TApi;

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

@@ -1 +1 @@
-{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAC;AAQvD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAsB,KAAK,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAMxE,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,uCAAuC;AACvC,MAAM,WAAW,sBAAsB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACpE;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,SAAS,MAAM,EACpD,SAAS,sBAAsB,CAAC,IAAI,CAAC,KACnC,IA4BF,CAAC;AA6DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG;AAoHtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI;KAC9B,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAClC,GAAG,IAAI,EAAE,MAAM,KAAK,KAChB,OAAO,CAAC,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,MAAM,CAAA;KAAC,EAAE;QAAC,KAAK,EAAE,kBAAkB,CAAA;KAAC,CAAC,CAAC,GACrE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,GACnC,IAAI,CAAC,CAAC,CAAC;CACV,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,mBAAmB,GAAI,IAAI,SAAS,MAAM,EAAE,YAAY,IAAI,KAAG,WAAW,CAAC,IAAI,CA8B3F,CAAC"}
+{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAC;AAQvD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAsB,KAAK,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAMxE,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,uCAAuC;AACvC,MAAM,WAAW,sBAAsB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC;IACpE;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,SAAS,MAAM,EACpD,SAAS,sBAAsB,CAAC,IAAI,CAAC,KACnC,IA4BF,CAAC;AAuDF;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;CAAG;AA6GtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI;KAC9B,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAClC,GAAG,IAAI,EAAE,MAAM,KAAK,KAChB,OAAO,CAAC,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,MAAM,CAAA;KAAC,EAAE;QAAC,KAAK,EAAE,kBAAkB,CAAA;KAAC,CAAC,CAAC,GACrE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,GACnC,IAAI,CAAC,CAAC,CAAC;CACV,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,mBAAmB,GAAI,IAAI,SAAS,MAAM,EAAE,YAAY,IAAI,KAAG,WAAW,CAAC,IAAI,CA8B3F,CAAC"}