@fuzdev/fuz_app 0.51.0 → 0.53.0

package/dist/actions/action_event.js

@@ -40,10 +40,22 @@ export class ActionEvent {
     }
     // TODO rethink the reactivity of this class, maybe just use `$state` or `$state.raw`?
     // does that have any negative implications when used on the backend?
+    /**
+     * Subscribe a listener fired on every `data` transition.
+     *
+     * @param listener - called with `(new_data, old_data, event)` after each mutation
+     * @returns unsubscribe function
+     * @mutates this - adds `listener` to the internal observer set
+     */
     observe(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
+    /**
+     * Replace the event's `data` and notify observers.
+     *
+     * @mutates this - sets `data` and fires every registered observer in insertion order
+     */
     set_data(new_data) {
         const old_data = this.#data;
         this.#data = new_data;
@@ -54,6 +66,11 @@ export class ActionEvent {
     }
     /**
      * Parse input data according to the action's schema.
+     *
+     * @returns `this` for chaining with `handle_async` / `handle_sync`
+     * @mutates this - transitions step from `initial` to `parsed` (or to
+     *   `failed` / `receive_error` on validation or response error)
+     * @throws Error if called from a step other than `initial`
      */
     parse() {
         if (this.#data.step !== 'initial') {
@@ -93,6 +110,14 @@ export class ActionEvent {
     }
     /**
      * Execute the handler for the current phase.
+     *
+     * @mutates this - transitions step `parsed → handling → handled`, or to
+     *   `failed` / `send_error` / `receive_error` on handler throw. No-op
+     *   when already `failed`.
+     * @throws Error if called from a step other than `parsed` (or `failed`,
+     *   which no-ops). Handler-thrown `ThrownJsonrpcError` is caught and
+     *   routed through error phases; other throws are wrapped as
+     *   `internal_error`.
      */
     // TODO add timeout support
     // TODO add cancellation support
@@ -136,7 +161,12 @@ export class ActionEvent {
         }
     }
     /**
-     * Execute handler synchronously (only for sync local_call actions).
+     * Execute handler synchronously (only for sync `local_call` actions).
+     *
+     * @mutates this - transitions step `parsed → handling → handled`, or to
+     *   `failed` on handler throw. No-op when already `failed`.
+     * @throws Error if the spec is not a sync `local_call`, or if called
+     *   from a step other than `parsed` (or `failed`, which no-ops).
      */
     handle_sync() {
         if (this.spec.kind !== 'local_call' || this.spec.async) {
@@ -168,6 +198,14 @@ export class ActionEvent {
     }
     /**
      * Transition to a new phase.
+     *
+     * @param phase - the next phase to transition into
+     * @mutates this - replaces `data` with a fresh phase-initial record,
+     *   carrying forward `request` / `response` / `error` / `output` as
+     *   appropriate for the kind/phase pair
+     * @throws Error if called from a step other than `handled` (or
+     *   `failed`, which no-ops), or if the phase transition is illegal for
+     *   the current phase
      */
     transition(phase) {
         if (this.#data.step === 'failed') {
@@ -340,6 +378,9 @@ export class ActionEvent {
 // TODO not sure about this helper's design/location (should it be internal to the class constructor? a static method?)
 /**
  * Create an action event from a spec and initial input.
+ *
+ * @throws Error if `initial_phase` is omitted and the executor cannot
+ *   initiate the action (per `spec.initiator`)
  */
 export const create_action_event = (environment, spec, input, initial_phase) => {
     const phase = initial_phase || get_initial_phase(spec.kind, spec.initiator, environment.executor);
@@ -351,6 +392,8 @@ export const create_action_event = (environment, spec, input, initial_phase) =>
 };
 /**
  * Reconstruct an action event from serialized JSON data.
+ *
+ * @throws Error if the JSON's `method` field has no spec registered in `environment`
  */
 export const create_action_event_from_json = (json, environment) => {
     const spec = environment.lookup_action_spec(json.method);

package/dist/actions/action_event_helpers.d.ts

@@ -58,13 +58,39 @@ export declare const is_notification_send_with_parsed_input: <TMethod extends st
     step: "parsed" | "handling";
     input: unknown;
 };
+/**
+ * Validate that a step transition is legal per `ACTION_EVENT_STEP_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not a permitted transition
+ */
 export declare const validate_step_transition: (from: ActionEventStep, to: ActionEventStep) => void;
+/**
+ * Validate that `phase` is one of the phases allowed for `kind` per
+ * `ACTION_EVENT_PHASE_BY_KIND`.
+ *
+ * @throws Error if `phase` is not valid for `kind`
+ */
 export declare const validate_phase_for_kind: (kind: ActionKind, phase: ActionEventPhase) => void;
+/**
+ * Validate that a phase chain is legal per `ACTION_EVENT_PHASE_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not the permitted next phase (or `from` is terminal)
+ */
 export declare const validate_phase_transition: (from: ActionEventPhase, to: ActionEventPhase) => void;
 export declare const get_initial_phase: (kind: ActionKind, initiator: ActionInitiator, executor: ActionExecutor) => ActionEventPhase | null;
 export declare const should_validate_output: (kind: ActionKind, phase: ActionEventPhase) => boolean;
 export declare const is_action_complete: (data: ActionEventData) => boolean;
 export declare const create_initial_data: (kind: ActionKind, phase: ActionEventPhase, method: string, executor: ActionExecutor, input: unknown) => ActionEventData;
+/**
+ * Pull the terminal `Result` from an action event.
+ *
+ * `data.error` populated → error path (covers both explicit `failed` and
+ * the unhandled `receive_error` / `send_error` case where no handler was
+ * registered for the error phase). `step === 'handled'` → success path.
+ *
+ * @throws Error if the event is in a non-terminal state (programming error —
+ *   callers should check `is_action_complete` first)
+ */
 export declare const extract_action_result: (event: ActionEvent) => Result<{
     value: ActionEventData["output"];
 }, {

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

@@ -1 +1 @@
-{"version":3,"file":"action_event_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAC;AAEvD,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,cAAc,EAInB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACX,eAAe,EACf,8BAA8B,EAC9B,iCAAiC,EACjC,wBAAwB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAC,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAGnD,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAAkE,CAAC;AAE9E,eAAO,MAAM,sBAAsB,GAClC,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAwE,CAAC;AAEpF,eAAO,MAAM,aAAa,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,wBACnC,CAAC;AAG5B,eAAO,MAAM,eAAe,GAC3B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,cAAc,CAAA;CACA,CAAC;AAEnE,eAAO,MAAM,kBAAkB,GAC9B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,iBAAiB,CAAA;CACA,CAAC;AAEtE,eAAO,MAAM,gBAAgB,GAC5B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,eAAe,CAAA;CACA,CAAC;AAEpE,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,GAAG;IAAC,KAAK,EAAE,kBAAkB,CAAA;CACA,CAAC;AAEvE,eAAO,MAAM,oBAAoB,GAChC,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAiC,GAAG;IAAC,KAAK,EAAE,MAAM,CAAA;CACA,CAAC;AAE9D,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAiC,GAAG;IAAC,KAAK,EAAE,SAAS,CAAA;CACA,CAAC;AAEjE,eAAO,MAAM,UAAU,GACtB,MAAM,eAAe,KACnB,IAAI,IAAI,wBAAwB,GAAG;IAAC,KAAK,EAAE,SAAS,CAAA;CACA,CAAC;AAGxD,eAAO,MAAM,UAAU,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,SAAS,CAAA;CACrE,CAAC;AAEzB,eAAO,MAAM,SAAS,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,QAAQ,CAAA;CACpE,CAAC;AAExB,eAAO,MAAM,WAAW,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,UAAU,CAAA;CACtE,CAAC;AAE1B,eAAO,MAAM,UAAU,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,SAAS,CAAA;CACrE,CAAC;AAEzB,eAAO,MAAM,SAAS,GAAI,MAAM,eAAe,KAAG,IAAI,IAAI,eAAe,GAAG;IAAC,IAAI,EAAE,QAAQ,CAAA;CACpE,CAAC;AAKxB,eAAO,MAAM,iCAAiC,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAChF,MAAM,eAAe,KACnB,IAAI,IAAI,8BAA8B,CAAC,OAAO,CAAC,GAAG;IACpD,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CACkE,CAAC;AAEnF,eAAO,MAAM,sCAAsC,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EACrF,MAAM,eAAe,KACnB,IAAI,IAAI,iCAAiC,CAAC,OAAO,CAAC,GAAG;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;CACuE,CAAC;AAGxF,eAAO,MAAM,wBAAwB,GAAI,MAAM,eAAe,EAAE,IAAI,eAAe,KAAG,IAIrF,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,MAAM,UAAU,EAAE,OAAO,gBAAgB,KAAG,IAInF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,MAAM,gBAAgB,EAAE,IAAI,gBAAgB,KAAG,IAKxF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC7B,MAAM,UAAU,EAChB,WAAW,eAAe,EAC1B,UAAU,cAAc,KACtB,gBAAgB,GAAG,IAWrB,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAM,UAAU,EAAE,OAAO,gBAAgB,KAAG,OAEpC,CAAC;AAEhD,eAAO,MAAM,kBAAkB,GAAI,MAAM,eAAe,KAAG,OAO1D,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC/B,MAAM,UAAU,EAChB,OAAO,gBAAgB,EACvB,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,OAAO,OAAO,KACZ,eAaD,CAAC;AAEH,eAAO,MAAM,qBAAqB,GACjC,OAAO,WAAW,KAChB,MAAM,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;CAAC,EAAE;IAAC,KAAK,EAAE,kBAAkB,CAAA;CAAC,CAuBxE,CAAC"}
+{"version":3,"file":"action_event_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_helpers.ts"],"names":[],"mappings":"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"}

package/dist/actions/action_event_helpers.js

@@ -27,17 +27,32 @@ export const is_failed = (data) => data.step === 'failed';
 // are created when transitioning from 'parsed' to 'handling'
 export const is_send_request_with_parsed_input = (data) => is_send_request(data) && (data.step === 'parsed' || data.step === 'handling');
 export const is_notification_send_with_parsed_input = (data) => is_notification_send(data) && (data.step === 'parsed' || data.step === 'handling');
-// Validation helpers
+/**
+ * Validate that a step transition is legal per `ACTION_EVENT_STEP_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not a permitted transition
+ */
 export const validate_step_transition = (from, to) => {
     if (!ACTION_EVENT_STEP_TRANSITIONS[from].includes(to)) {
         throw new Error(`Invalid step transition from '${from}' to '${to}'`);
     }
 };
+/**
+ * Validate that `phase` is one of the phases allowed for `kind` per
+ * `ACTION_EVENT_PHASE_BY_KIND`.
+ *
+ * @throws Error if `phase` is not valid for `kind`
+ */
 export const validate_phase_for_kind = (kind, phase) => {
     if (!ACTION_EVENT_PHASE_BY_KIND[kind].includes(phase)) {
         throw new Error(`Invalid phase '${phase}' for ${kind} action`);
     }
 };
+/**
+ * Validate that a phase chain is legal per `ACTION_EVENT_PHASE_TRANSITIONS`.
+ *
+ * @throws Error if `from → to` is not the permitted next phase (or `from` is terminal)
+ */
 export const validate_phase_transition = (from, to) => {
     const expected = ACTION_EVENT_PHASE_TRANSITIONS[from];
     if (expected !== to) {
@@ -81,6 +96,16 @@ export const create_initial_data = (kind, phase, method, executor, input) => ({
     response: null,
     notification: null,
 });
+/**
+ * Pull the terminal `Result` from an action event.
+ *
+ * `data.error` populated → error path (covers both explicit `failed` and
+ * the unhandled `receive_error` / `send_error` case where no handler was
+ * registered for the error phase). `step === 'handled'` → success path.
+ *
+ * @throws Error if the event is in a non-terminal state (programming error —
+ *   callers should check `is_action_complete` first)
+ */
 export const extract_action_result = (event) => {
     const { data } = event;
     // `data.error` populated → error path. This covers two cases:

package/dist/actions/action_peer.d.ts

@@ -31,8 +31,25 @@ export declare class ActionPeer {
     readonly transports: Transports;
     default_send_options: Omit<ActionPeerSendOptions, 'signal'>;
     constructor(options: ActionPeerOptions);
+    /**
+     * Resolve a transport (per-call name → default name → registry default)
+     * and forward the message. Catches unexpected throws and converts them
+     * to JSON-RPC error responses — this method never throws.
+     *
+     * @returns the response envelope for requests, or `null` for successful
+     *   notifications (`JsonrpcErrorResponse` if the notification's transport
+     *   send failed)
+     */
     send(message: JsonrpcRequest, options?: ActionPeerSendOptions): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification, options?: ActionPeerSendOptions): Promise<JsonrpcErrorResponse | null>;
+    /**
+     * Dispatch an inbound JSON-RPC message — request, notification, or
+     * malformed envelope. Never throws; unexpected failures become
+     * JSON-RPC error responses.
+     *
+     * @returns response message for requests, `null` for notifications, or
+     *   an `invalid_request` error for malformed input
+     */
     receive(message: unknown): Promise<JsonrpcMessageFromServerToClient | null>;
 }
 //# sourceMappingURL=action_peer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action_peer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAC,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IAClE,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAKxB,oBAAoB,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;CAC7D;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;gBAEhD,OAAO,EAAE,iBAAiB;IAOhC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CjC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAyIjF"}
+{"version":3,"file":"action_peer.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEN,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAC,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IAClE,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAKxB,oBAAoB,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;CAC7D;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;gBAEhD,OAAO,EAAE,iBAAiB;IAMtC;;;;;;;;OAQG;IAEG,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CvC;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAgIjF"}

package/dist/actions/action_peer.js

@@ -48,6 +48,14 @@ export class ActionPeer {
             return create_jsonrpc_error_response_from_thrown(to_jsonrpc_message_id(message), error);
         } // TODO finally?
     }
+    /**
+     * Dispatch an inbound JSON-RPC message — request, notification, or
+     * malformed envelope. Never throws; unexpected failures become
+     * JSON-RPC error responses.
+     *
+     * @returns response message for requests, `null` for notifications, or
+     *   an `invalid_request` error for malformed input
+     */
     async receive(message) {
         try {
             const result = await this.#receive_message(message);
@@ -59,9 +67,6 @@ export class ActionPeer {
             return create_jsonrpc_error_response_from_thrown(to_jsonrpc_message_id(message), error);
         } // TODO finally?
     }
-    /**
-     * Processes a single JSON-RPC message, returning a response message if any.
-     */
     async #receive_message(message) {
         if (is_jsonrpc_request(message)) {
             return this.#receive_request(message);
@@ -74,9 +79,6 @@ export class ActionPeer {
             return create_jsonrpc_error_response(to_jsonrpc_message_id(message), jsonrpc_error_messages.invalid_request());
         }
     }
-    /**
-     * Processes a JSON-RPC request. Returns the response message.
-     */
     async #receive_request(request) {
         const spec = this.environment.lookup_action_spec(request.method);
         if (!spec) {
@@ -122,9 +124,6 @@ export class ActionPeer {
             return create_jsonrpc_error_response_from_thrown(request.id, error);
         }
     }
-    /**
-     * Processes a JSON-RPC notification. Returns nothing, no response exists.
-     */
     async #receive_notification(notification) {
         const spec = this.environment.lookup_action_spec(notification.method);
         if (!spec) {

package/dist/actions/action_registry.d.ts

@@ -1,7 +1,7 @@
 /**
  * `ActionRegistry` — query and filter utility over `ActionSpecUnion[]`.
  *
- * Vocabulary (set in API review III, see the `docs/` directory and the SAES quest):
+ * Vocabulary (see the `docs/` directory):
  * - `*_handled_*` — request_response specs the named side **receives**
  *   (so the named side owns the handler). Used by codegen to emit typed
  *   handler maps.
@@ -27,10 +27,6 @@
  * @module
  */
 import type { ActionSpecUnion, RequestResponseActionSpec, RemoteNotificationActionSpec, LocalCallActionSpec } from './action_spec.js';
-/**
- * Utility class to manage and query action specifications.
- * Provides helper methods to get actions by various criteria.
- */
 export declare class ActionRegistry {
     #private;
     readonly specs: Array<ActionSpecUnion>;

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

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

package/dist/actions/action_registry.js

@@ -1,7 +1,7 @@
 /**
  * `ActionRegistry` — query and filter utility over `ActionSpecUnion[]`.
  *
- * Vocabulary (set in API review III, see the `docs/` directory and the SAES quest):
+ * Vocabulary (see the `docs/` directory):
  * - `*_handled_*` — request_response specs the named side **receives**
  *   (so the named side owns the handler). Used by codegen to emit typed
  *   handler maps.
@@ -26,16 +26,10 @@
  *
  * @module
  */
-// 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.
- */
+// The auth (`public_*`, `authenticated_*`) and initiator-direction
+// (`backend_to_frontend_*`, `frontend_to_backend_*`) getters are pre-built
+// API surface unused by codegen today; kept low-cost for future filtering
+// without a registry change.
 export class ActionRegistry {
     specs;
     constructor(specs) {

package/dist/actions/action_rpc.d.ts

@@ -18,6 +18,7 @@ import { type RouteSpec } from '../http/route_spec.js';
 import { type RequestContext } from '../auth/request_context.js';
 import type { Db } from '../db/db.js';
 import { type JsonrpcRequestId } from '../http/jsonrpc.js';
+import type { RateLimiter } from '../rate_limiter.js';
 /**
  * Per-request context provided to RPC action handlers.
  *
@@ -108,6 +109,21 @@ export interface CreateRpcEndpointOptions {
     actions: Array<RpcAction>;
     /** Logger instance for handler context. */
     log: Logger;
+    /**
+     * Per-IP rate limiter consulted for actions whose spec declares
+     * `rate_limit: 'ip'` or `'both'`. `null` disables the IP check.
+     * Per-action gate via `action.spec.rate_limit`. Same limiter is
+     * shared with the WebSocket action dispatcher — one budget per
+     * action, not per transport.
+     */
+    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` disables the account check.
+     * Same limiter is shared with the WebSocket action dispatcher.
+     */
+    action_account_rate_limiter?: RateLimiter | null;
 }
 /**
  * Single JSON-RPC 2.0 endpoint — the canonical RPC transport binding.
@@ -132,6 +148,10 @@ export interface CreateRpcEndpointOptions {
  *
  * @param options - endpoint path, actions, and logger
  * @returns route specs (GET + POST) ready for `apply_route_specs`
+ * @throws Error if two actions share the same `spec.method` (registration-time
+ *   duplicate detection); also throws if any action's `spec.input` is
+ *   `z.null()` (JSON-RPC 2.0 §4.2 forbids `params: null` on the wire — use
+ *   `z.void()` for parameterless methods).
  */
 export declare const create_rpc_endpoint: (options: CreateRpcEndpointOptions) => Array<RouteSpec>;
 //# sourceMappingURL=action_rpc.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAW5B;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACxD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvE,SAGD,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;CACZ;AA4DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAsQtF,CAAC"}
+{"version":3,"file":"action_rpc.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAgC,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE9F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,OAAO,EAGN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACxD,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,yBAAyB,EACjE,MAAM,KAAK,EACX,SAAS,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvE,SAGD,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACjD;AAkDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,wBAAwB,KAAG,KAAK,CAAC,SAAS,CAkTtF,CAAC"}

package/dist/actions/action_rpc.js

@@ -43,13 +43,6 @@ export const rpc_action = (spec, handler) => ({
     spec,
     handler: handler,
 });
-/**
- * Format a JSON-RPC error response.
- *
- * @param id - the request id (null if unknown)
- * @param error - the error object
- * @returns a JSON-RPC error response object
- */
 const jsonrpc_error_response = (id, error) => ({
     jsonrpc: JSONRPC_VERSION,
     id,
@@ -58,10 +51,7 @@ const jsonrpc_error_response = (id, error) => ({
 /**
  * Check auth for an action spec against the request context.
  *
- * @param auth - the action's auth requirement
- * @param request_context - the resolved identity (null if unauthenticated)
- * @param credential_type - how the request was authenticated (session, api_token, daemon_token)
- * @returns an error json if auth fails, or null if authorized
+ * @returns a JSON-RPC error object if auth fails, or `null` if authorized
  */
 const check_action_auth = (auth, request_context, credential_type) => {
     if (auth === 'public')
@@ -118,9 +108,13 @@ const check_action_auth = (auth, request_context, credential_type) => {
  *
  * @param options - endpoint path, actions, and logger
  * @returns route specs (GET + POST) ready for `apply_route_specs`
+ * @throws Error if two actions share the same `spec.method` (registration-time
+ *   duplicate detection); also throws if any action's `spec.input` is
+ *   `z.null()` (JSON-RPC 2.0 §4.2 forbids `params: null` on the wire — use
+ *   `z.void()` for parameterless methods).
  */
 export const create_rpc_endpoint = (options) => {
-    const { path: endpoint_path, actions, log } = options;
+    const { path: endpoint_path, actions, log, action_ip_rate_limiter = null, action_account_rate_limiter = null, } = options;
     // build action lookup map
     const action_map = new Map();
     for (const action of actions) {
@@ -130,18 +124,18 @@ export const create_rpc_endpoint = (options) => {
         if (is_null_schema(action.spec.input)) {
             throw new Error(`RPC action "${action.spec.method}" uses z.null() for input — JSON-RPC 2.0 §4.2 forbids "params": null on the wire (must be omitted or be a Structured value). Use z.void() for parameterless methods.`);
         }
+        // Reject account-keyed rate limiting on public actions — there's no
+        // actor post-auth, so the account bucket has no key to consume.
+        if ((action.spec.rate_limit === 'account' || action.spec.rate_limit === 'both') &&
+            action.spec.auth === 'public') {
+            throw new Error(`RPC 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.`);
+        }
         action_map.set(action.spec.method, action);
     }
     /**
      * Core dispatcher — shared by GET and POST handlers.
      *
-     * @param c - Hono context
-     * @param route - route context with db and pending_effects
-     * @param method_name - the JSON-RPC method name
-     * @param raw_params - the raw params (parsed from body or query string)
-     * @param id - the request id
-     * @param restrict_to_reads - true for GET requests (reject side_effects actions)
-     * @returns a Response
+     * @param restrict_to_reads - `true` for GET (rejects `side_effects: true` actions)
      */
     const dispatch = async (c, route, method_name, raw_params, id, restrict_to_reads) => {
         // step 2: lookup method
@@ -165,6 +159,38 @@ export const create_rpc_endpoint = (options) => {
             const error = jsonrpc_error_response(id, auth_error);
             return c.json(error, jsonrpc_error_code_to_http_status(auth_error.code));
         }
+        // step 3.5: rate limit — throttle-requests semantics (record on every
+        // invocation, no success-reset). Suits admin mutation oracles where
+        // the *successful* call is the threat. Different from REST login's
+        // throttle-failures pattern that resets on success. Silent partial
+        // enforcement: a key is checked iff its bucket's limiter is wired —
+        // `rate_limit: 'both'` with only one limiter set runs only that side.
+        const rate_limit = action.spec.rate_limit;
+        const client_ip = get_client_ip(c);
+        if (rate_limit) {
+            const ip_check = action_ip_rate_limiter && (rate_limit === 'ip' || rate_limit === 'both');
+            const account_check = action_account_rate_limiter &&
+                request_context &&
+                (rate_limit === 'account' || rate_limit === 'both');
+            const reject = (retry_after) => {
+                const error = jsonrpc_error_response(id, jsonrpc_error_messages.rate_limited('rate limited', { retry_after }));
+                return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.rate_limited));
+            };
+            if (ip_check) {
+                const result = action_ip_rate_limiter.check(client_ip);
+                if (!result.allowed)
+                    return reject(result.retry_after);
+            }
+            if (account_check) {
+                const result = action_account_rate_limiter.check(request_context.actor.id);
+                if (!result.allowed)
+                    return reject(result.retry_after);
+            }
+            if (ip_check)
+                action_ip_rate_limiter.record(client_ip);
+            if (account_check)
+                action_account_rate_limiter.record(request_context.actor.id);
+        }
         // step 4: validate params
         // Missing `params` on the envelope maps to `undefined` for `z.void()`
         // input schemas and `{}` for object inputs (matches HTTP's "empty
@@ -191,7 +217,6 @@ export const create_rpc_endpoint = (options) => {
             }
         };
         const signal = c.req.raw.signal;
-        const client_ip = get_client_ip(c);
         const execute = async (db) => {
             const action_context = {
                 auth: request_context,