@fuzdev/fuz_app 0.10.1 → 0.12.0

package/dist/actions/action_event_helpers.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Action event helper functions — type guards, validators, and data creation.
+ *
+ * @module
+ */
+import type { Result } from '@fuzdev/fuz_util/result.js';
+import { type ActionEventStep, type ActionExecutor } from './action_event_types.js';
+import type { ActionEventData, ActionEventRequestResponseData, ActionEventRemoteNotificationData, ActionEventLocalCallData } from './action_event_data.js';
+import type { ActionEventPhase, ActionInitiator, ActionKind } from './action_spec.js';
+import type { JsonrpcErrorObject } from '../http/jsonrpc.js';
+import type { ActionEvent } from './action_event.js';
+export declare const is_request_response: (data: ActionEventData) => data is ActionEventRequestResponseData;
+export declare const is_remote_notification: (data: ActionEventData) => data is ActionEventRemoteNotificationData;
+export declare const is_local_call: (data: ActionEventData) => data is ActionEventLocalCallData;
+export declare const is_send_request: (data: ActionEventData) => data is ActionEventRequestResponseData & {
+    phase: "send_request";
+};
+export declare const is_receive_request: (data: ActionEventData) => data is ActionEventRequestResponseData & {
+    phase: "receive_request";
+};
+export declare const is_send_response: (data: ActionEventData) => data is ActionEventRequestResponseData & {
+    phase: "send_response";
+};
+export declare const is_receive_response: (data: ActionEventData) => data is ActionEventRequestResponseData & {
+    phase: "receive_response";
+};
+export declare const is_notification_send: (data: ActionEventData) => data is ActionEventRemoteNotificationData & {
+    phase: "send";
+};
+export declare const is_notification_receive: (data: ActionEventData) => data is ActionEventRemoteNotificationData & {
+    phase: "receive";
+};
+export declare const is_execute: (data: ActionEventData) => data is ActionEventLocalCallData & {
+    phase: "execute";
+};
+export declare const is_initial: (data: ActionEventData) => data is ActionEventData & {
+    step: "initial";
+};
+export declare const is_parsed: (data: ActionEventData) => data is ActionEventData & {
+    step: "parsed";
+};
+export declare const is_handling: (data: ActionEventData) => data is ActionEventData & {
+    step: "handling";
+};
+export declare const is_handled: (data: ActionEventData) => data is ActionEventData & {
+    step: "handled";
+};
+export declare const is_failed: (data: ActionEventData) => data is ActionEventData & {
+    step: "failed";
+};
+export declare const is_send_request_with_parsed_input: <TMethod extends string = string>(data: ActionEventData) => data is ActionEventRequestResponseData<TMethod> & {
+    phase: "send_request";
+    step: "parsed" | "handling";
+    input: unknown;
+};
+export declare const is_notification_send_with_parsed_input: <TMethod extends string = string>(data: ActionEventData) => data is ActionEventRemoteNotificationData<TMethod> & {
+    phase: "send";
+    step: "parsed" | "handling";
+    input: unknown;
+};
+export declare const validate_step_transition: (from: ActionEventStep, to: ActionEventStep) => void;
+export declare const validate_phase_for_kind: (kind: ActionKind, phase: ActionEventPhase) => void;
+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;
+export declare const extract_action_result: (event: ActionEvent) => Result<{
+    value: ActionEventData["output"];
+}, {
+    error: JsonrpcErrorObject;
+}>;
+//# sourceMappingURL=action_event_helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,96 @@
+/**
+ * Action event helper functions — type guards, validators, and data creation.
+ *
+ * @module
+ */
+import { ACTION_EVENT_STEP_TRANSITIONS, ACTION_EVENT_PHASE_BY_KIND, ACTION_EVENT_PHASE_TRANSITIONS, } from './action_event_types.js';
+// Type guards for action kinds
+export const is_request_response = (data) => data.kind === 'request_response';
+export const is_remote_notification = (data) => data.kind === 'remote_notification';
+export const is_local_call = (data) => data.kind === 'local_call';
+// Type guards for specific states
+export const is_send_request = (data) => data.kind === 'request_response' && data.phase === 'send_request';
+export const is_receive_request = (data) => data.kind === 'request_response' && data.phase === 'receive_request';
+export const is_send_response = (data) => data.kind === 'request_response' && data.phase === 'send_response';
+export const is_receive_response = (data) => data.kind === 'request_response' && data.phase === 'receive_response';
+export const is_notification_send = (data) => data.kind === 'remote_notification' && data.phase === 'send';
+export const is_notification_receive = (data) => data.kind === 'remote_notification' && data.phase === 'receive';
+export const is_execute = (data) => data.kind === 'local_call' && data.phase === 'execute';
+// Step state guards
+export const is_initial = (data) => data.step === 'initial';
+export const is_parsed = (data) => data.step === 'parsed';
+export const is_handling = (data) => data.step === 'handling';
+export const is_handled = (data) => data.step === 'handled';
+export const is_failed = (data) => data.step === 'failed';
+// Combined type guards for specific states with parsed input
+// These check for 'parsed' or 'handling' steps since protocol messages
+// 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
+export const validate_step_transition = (from, to) => {
+    const valid_transitions = ACTION_EVENT_STEP_TRANSITIONS[from];
+    if (!valid_transitions.includes(to)) {
+        throw new Error(`Invalid step transition from '${from}' to '${to}'`);
+    }
+};
+export const validate_phase_for_kind = (kind, phase) => {
+    const valid_phases = ACTION_EVENT_PHASE_BY_KIND[kind];
+    if (!valid_phases.includes(phase)) {
+        throw new Error(`Invalid phase '${phase}' for ${kind} action`);
+    }
+};
+export const validate_phase_transition = (from, to) => {
+    const expected = ACTION_EVENT_PHASE_TRANSITIONS[from];
+    if (expected !== to) {
+        throw new Error(`Invalid phase transition from '${from}' to '${to}'`);
+    }
+};
+export const get_initial_phase = (kind, initiator, executor) => {
+    if (initiator !== 'both' && initiator !== executor)
+        return null;
+    switch (kind) {
+        case 'request_response':
+            return 'send_request';
+        case 'remote_notification':
+            return 'send';
+        case 'local_call':
+            return 'execute';
+    }
+};
+export const should_validate_output = (kind, phase) => (kind === 'request_response' && (phase === 'receive_request' || phase === 'receive_response')) ||
+    (kind === 'local_call' && phase === 'execute');
+export const is_action_complete = (data) => {
+    if (data.step === 'failed')
+        return true;
+    if (data.step !== 'handled')
+        return false;
+    // Check if in terminal phase
+    const next_phase = ACTION_EVENT_PHASE_TRANSITIONS[data.phase];
+    return next_phase === null;
+};
+export const create_initial_data = (kind, phase, method, executor, input) => ({
+    kind,
+    phase,
+    step: 'initial',
+    method,
+    executor,
+    input,
+    output: null,
+    error: null,
+    progress: null,
+    request: null,
+    response: null,
+    notification: null,
+});
+export const extract_action_result = (event) => {
+    const { data } = event;
+    if (data.step === 'handled') {
+        return { ok: true, value: data.output };
+    }
+    if (data.step === 'failed') {
+        return { ok: false, error: data.error };
+    }
+    // Programming error - event not in terminal state
+    throw new Error(`cannot extract result: event in non-terminal state (step: ${data.step})`);
+};

package/dist/actions/action_event_types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Action event type definitions — state machine constants and environment interface.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { ActionEventPhase, ActionKind, ActionSpecUnion } from './action_spec.js';
+export declare const ActionExecutor: z.ZodEnum<{
+    frontend: "frontend";
+    backend: "backend";
+}>;
+export type ActionExecutor = z.infer<typeof ActionExecutor>;
+export declare const ActionEventStep: z.ZodEnum<{
+    initial: "initial";
+    parsed: "parsed";
+    handling: "handling";
+    handled: "handled";
+    failed: "failed";
+}>;
+export type ActionEventStep = z.infer<typeof ActionEventStep>;
+export declare const ACTION_EVENT_STEP_TRANSITIONS: Record<ActionEventStep, ReadonlyArray<ActionEventStep>>;
+export declare const ACTION_EVENT_PHASE_BY_KIND: Record<ActionKind, ReadonlyArray<ActionEventPhase>>;
+export declare const ACTION_EVENT_PHASE_TRANSITIONS: Record<ActionEventPhase, ActionEventPhase | null>;
+export interface ActionEventEnvironment {
+    readonly executor: ActionExecutor;
+    lookup_action_handler: (method: string, phase: ActionEventPhase) => ((event: any) => any) | undefined;
+    lookup_action_spec: (method: string) => ActionSpecUnion | undefined;
+    readonly log?: Logger | null;
+}
+//# sourceMappingURL=action_event_types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action_event_types.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event_types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,gBAAgB,EAAE,UAAU,EAAE,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEpF,eAAO,MAAM,cAAc;;;EAAkC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,eAAe;;;;;;EAAiE,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,6BAA6B,EAMrC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;AAE7D,eAAO,MAAM,0BAA0B,EAWlC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEzD,eAAO,MAAM,8BAA8B,EAUtC,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,qBAAqB,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,KACnB,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC;IACvC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B"}

package/dist/actions/action_event_types.js

@@ -0,0 +1,38 @@
+/**
+ * Action event type definitions — state machine constants and environment interface.
+ *
+ * @module
+ */
+import { z } from 'zod';
+export const ActionExecutor = z.enum(['frontend', 'backend']);
+export const ActionEventStep = z.enum(['initial', 'parsed', 'handling', 'handled', 'failed']);
+export const ACTION_EVENT_STEP_TRANSITIONS = {
+    initial: ['parsed', 'failed'],
+    parsed: ['handling', 'failed'],
+    handling: ['handled', 'failed'],
+    handled: [],
+    failed: [],
+};
+export const ACTION_EVENT_PHASE_BY_KIND = {
+    request_response: [
+        'send_request',
+        'receive_request',
+        'send_response',
+        'receive_response',
+        'send_error',
+        'receive_error',
+    ],
+    remote_notification: ['send', 'receive'],
+    local_call: ['execute'],
+};
+export const ACTION_EVENT_PHASE_TRANSITIONS = {
+    send_request: 'receive_response',
+    receive_request: 'send_response',
+    send_response: null,
+    receive_response: null,
+    send_error: null,
+    receive_error: null,
+    send: null,
+    receive: null,
+    execute: null,
+};

package/dist/actions/action_peer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ActionPeer — symmetric send/receive for JSON-RPC actions.
+ *
+ * Wraps a `Transports` registry and `ActionEventEnvironment` to provide
+ * bidirectional action dispatch via JSON-RPC 2.0.
+ *
+ * @module
+ */
+import { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
+import { Transports, type TransportName } from './transports.js';
+import type { ActionEventEnvironment } from './action_event_types.js';
+export interface ActionPeerSendOptions {
+    transport_name?: TransportName;
+}
+export interface ActionPeerOptions {
+    environment: ActionEventEnvironment;
+    transports?: Transports;
+    default_send_options?: Partial<ActionPeerSendOptions>;
+}
+export declare class ActionPeer {
+    #private;
+    readonly environment: ActionEventEnvironment;
+    readonly transports: Transports;
+    default_send_options: ActionPeerSendOptions;
+    constructor(options: ActionPeerOptions);
+    send(message: JsonrpcRequest, options?: ActionPeerSendOptions): Promise<JsonrpcResponseOrError>;
+    send(message: JsonrpcNotification, options?: ActionPeerSendOptions): Promise<JsonrpcErrorResponse | null>;
+    receive(message: unknown): Promise<JsonrpcMessageFromServerToClient | null>;
+}
+//# sourceMappingURL=action_peer.d.ts.map

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

@@ -0,0 +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,EAAC,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,MAAM,WAAW,qBAAqB;IACrC,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,sBAAsB,CAAC;IAGpC,UAAU,CAAC,EAAE,UAAU,CAAC;IAGxB,oBAAoB,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACtD;AAED,qBAAa,UAAU;;IACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAMhC,oBAAoB,EAAE,qBAAqB,CAAC;gBAEhC,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;IA2CjC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC;CAyIjF"}

package/dist/actions/action_peer.js

@@ -0,0 +1,146 @@
+/**
+ * ActionPeer — symmetric send/receive for JSON-RPC actions.
+ *
+ * Wraps a `Transports` registry and `ActionEventEnvironment` to provide
+ * bidirectional action dispatch via JSON-RPC 2.0.
+ *
+ * @module
+ */
+import { JsonrpcMessageFromClientToServer, JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse, } from '../http/jsonrpc.js';
+import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, to_jsonrpc_message_id, is_jsonrpc_request, is_jsonrpc_notification, } from '../http/jsonrpc_helpers.js';
+import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
+import { create_action_event } from './action_event.js';
+import { Transports } from './transports.js';
+export class ActionPeer {
+    environment;
+    transports;
+    // TODO maybe expand the pattern of using `transports` in send, so what's used in receive?
+    // It seems abstracting that out would make this class much simpler and generic, but too much so?
+    // What deps should it actually know about, and what gains could we have by making it more decoupled?
+    // e.g. don't just decouple for the sake of imagined flexibility!
+    default_send_options;
+    constructor(options) {
+        this.environment = options.environment;
+        this.transports = options.transports ?? new Transports();
+        this.default_send_options = options.default_send_options ?? {};
+    }
+    async send(message, options) {
+        try {
+            const transport = this.transports.get_transport(options?.transport_name ?? this.default_send_options.transport_name);
+            if (!transport) {
+                this.environment.log?.error('[peer] send failed: no transport available');
+                return create_jsonrpc_error_response(to_jsonrpc_message_id(message), jsonrpc_error_messages.service_unavailable('no transport available'));
+            }
+            const message_type = is_jsonrpc_request(message) ? 'request' : 'notification';
+            this.environment.log?.debug(`[peer] send ${message_type}:`, message.method, `via ${transport.transport_name}`);
+            const result = await transport.send(message);
+            if (result && 'error' in result) {
+                this.environment.log?.error(`[peer] send ${message_type} failed:`, message.method, result.error.message);
+            }
+            return result;
+        }
+        catch (error) {
+            // TODO add retry handling here?
+            this.environment.log?.error('[peer] send unexpected error:', error);
+            return create_jsonrpc_error_response_from_thrown(to_jsonrpc_message_id(message), error);
+        } // TODO finally?
+    }
+    async receive(message) {
+        try {
+            const result = await this.#receive_message(message);
+            return result;
+        }
+        catch (error) {
+            this.environment.log?.error('[peer] receive unexpected error:', error);
+            // Return appropriate error response based on the message
+            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);
+        }
+        else if (is_jsonrpc_notification(message)) {
+            await this.#receive_notification(message);
+            return null;
+        }
+        else {
+            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) {
+            this.environment.log?.warn(`[peer] receive request: method not found:`, request.method);
+            return create_jsonrpc_error_response(request.id, jsonrpc_error_messages.method_not_found(request.method));
+        }
+        this.environment.log?.debug(`[peer] receive request:`, request.method);
+        try {
+            // Create action event in receive_request phase
+            const event = create_action_event(this.environment, spec, request.params, 'receive_request');
+            event.set_request(request);
+            // Parse and handle
+            await event.parse().handle_async();
+            // Check if we successfully handled the request
+            if (event.data.step === 'handled') {
+                // Transition to send_response phase
+                event.transition('send_response');
+                await event.parse().handle_async();
+                // TODO doesn't seem exactly right, shouldn't need the guard, or needs some other tweaks
+                // Return the response if any
+                if (event.data.response) {
+                    return event.data.response;
+                }
+            }
+            // Check for terminal failure
+            if (event.data.step === 'failed') {
+                this.environment.log?.error(`[peer] receive request failed:`, request.method, event.data.error);
+                return create_jsonrpc_error_response(request.id, event.data.error);
+            }
+            // Check if transitioned to error phase (send_error)
+            if (event.data.phase === 'send_error') {
+                // Error handler may exist - try to handle it (already parsed)
+                await event.handle_async();
+                // Return error response (handler may have modified/logged it)
+                return create_jsonrpc_error_response(request.id, event.data.error);
+            }
+            // Fallback for unexpected states
+            this.environment.log?.error(`[peer] receive request: unexpected state:`, request.method, event.data);
+            return create_jsonrpc_error_response(request.id, jsonrpc_error_messages.internal_error('unknown error'));
+        }
+        catch (error) {
+            this.environment.log?.error(`[peer] receive request exception:`, request.method, error);
+            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) {
+            this.environment.log?.warn(`[peer] receive notification: method not found:`, notification.method);
+            return;
+        }
+        this.environment.log?.debug(`[peer] receive notification:`, notification.method);
+        try {
+            // Create action event in receive phase
+            const event = create_action_event(this.environment, spec, notification.params, 'receive');
+            event.set_notification(notification);
+            // Parse and handle
+            await event.parse().handle_async();
+            if (event.data.step === 'failed') {
+                this.environment.log?.error(`[peer] receive notification failed:`, notification.method, event.data.error);
+            }
+        }
+        catch (error) {
+            this.environment.log?.error(`[peer] receive notification exception:`, notification.method, error);
+        }
+    }
+}

package/dist/actions/action_spec.d.ts

@@ -3,7 +3,7 @@
  *
  * Extracted from zzz's action system. Action specs define method, kind,
  * auth, side effects, and input/output schemas. Bridge functions in
- * `action_bridge.ts` derive `RouteSpec` and `SseEventSpec` from them.
+ * `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 with the saes-rpc quest.

package/dist/actions/action_spec.js

@@ -3,7 +3,7 @@
  *
  * Extracted from zzz's action system. Action specs define method, kind,
  * auth, side effects, and input/output schemas. Bridge functions in
- * `action_bridge.ts` derive `RouteSpec` and `SseEventSpec` from them.
+ * `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 with the saes-rpc quest.

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

@@ -0,0 +1,69 @@
+/**
+ * Request tracker — manages pending JSON-RPC requests with timeouts.
+ *
+ * Uses SvelteMap for reactive pending request tracking.
+ *
+ * @module
+ */
+import { type Deferred, type AsyncStatus } from '@fuzdev/fuz_util/async.js';
+import { SvelteMap } from 'svelte/reactivity';
+import { type JsonrpcErrorResponse, type JsonrpcRequestId, type JsonrpcResponseOrError } from '../http/jsonrpc.js';
+/** ISO datetime string for request creation timestamps. */
+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>;
+    readonly created: Datetime;
+    status: AsyncStatus;
+    timeout: NodeJS.Timeout | undefined;
+    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.
+ */
+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_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_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_request(id: JsonrpcRequestId, error_message: JsonrpcErrorResponse): void;
+    /**
+     * Handles an incoming JSON-RPC message. Resolves or rejects the associated request.
+     * Ignores notifications and unknown/invalid messages.
+     */
+    handle_message(message: any): void;
+    /**
+     * Cancel a pending request.
+     * @param id - the request id
+     */
+    cancel_request(id: JsonrpcRequestId): void;
+    /**
+     * Cancel all pending requests.
+     * @param reason - optional reason to include in rejection
+     */
+    cancel_all_requests(reason?: string): void;
+}
+export {};
+//# sourceMappingURL=request_tracker.svelte.d.ts.map

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

@@ -0,0 +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"}