@cadenza.io/service 2.7.0 → 2.9.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _cadenza_io_core from '@cadenza.io/core';
-import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, TaskOptions, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
-export { AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
+import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, TaskOptions, ActorSpec, ActorFactoryOptions, Actor, ActorDefinition, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
+export { Actor, ActorConsistencyProfileName, ActorDefinition, ActorFactoryOptions, ActorInvocationOptions, ActorKeyDefinition, ActorKind, ActorLoadPolicy, ActorRuntimeReadGuard, ActorSpec, ActorStateDefinition, ActorStateReducer, ActorStateStore, ActorTaskBindingDefinition, ActorTaskBindingOptions, ActorTaskContext, ActorTaskHandler, ActorTaskMode, ActorWriteContract, AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, IdempotencyPolicy, RetryPolicy, SessionPolicy, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
 
 /**
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -236,6 +236,8 @@ declare class ServiceRegistry {
     private remoteIntentDeputiesByTask;
     private dependeesByService;
     private dependeeByInstance;
+    private readinessDependeesByService;
+    private readinessDependeeByInstance;
     private lastHeartbeatAtByInstance;
     private missedHeartbeatsByInstance;
     private runtimeStatusFallbackInFlightByInstance;
@@ -270,6 +272,7 @@ declare class ServiceRegistry {
     handleServiceNotRespondingTask: Task;
     handleServiceHandshakeTask: Task;
     collectTransportDiagnosticsTask: Task;
+    collectReadinessTask: Task;
     private buildRemoteIntentDeputyKey;
     private normalizeIntentMaps;
     private registerRemoteIntentDeputy;
@@ -279,11 +282,16 @@ declare class ServiceRegistry {
     private getLocalInstance;
     private registerDependee;
     private unregisterDependee;
+    private getHeartbeatMisses;
+    private shouldRequireReadinessFromCommunicationTypes;
     private resolveRuntimeStatusSnapshot;
     private normalizeRuntimeStatusReport;
     private applyRuntimeStatusReport;
     private buildLocalRuntimeStatusReport;
     private selectRuntimeStatusReportForTarget;
+    private resolveRuntimeStatusFallbackInquiry;
+    private evaluateDependencyReadinessDetail;
+    private buildLocalReadinessReport;
     /**
      * Initializes a private constructor for managing service instances, remote signals,
      * service health, and handling updates or synchronization tasks. The constructor
@@ -22414,6 +22422,8 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    static createActor<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
+    static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
      * Creates and registers a new task with the provided name, function, and optional details.
      *
@@ -22776,6 +22786,9 @@ declare class RestController {
     static get instance(): RestController;
     private fetchClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private pruneFetchClientDiagnostics;
     private resolveTransportDiagnosticsOptions;
     private ensureFetchClientDiagnostics;
     private getErrorMessage;
@@ -22805,41 +22818,68 @@ declare class RestController {
     constructor();
 }
 
+interface TransportDiagnosticErrorEntry {
+    at: string;
+    message: string;
+}
+interface SocketClientDiagnosticsState {
+    fetchId: string;
+    serviceName: string;
+    url: string;
+    socketId: string | null;
+    connected: boolean;
+    handshake: boolean;
+    reconnectAttempts: number;
+    connectErrors: number;
+    reconnectErrors: number;
+    socketErrors: number;
+    pendingDelegations: number;
+    pendingTimers: number;
+    destroyed: boolean;
+    lastHandshakeAt: string | null;
+    lastHandshakeError: string | null;
+    lastDisconnectAt: string | null;
+    lastError: string | null;
+    lastErrorAt: number;
+    errorHistory: TransportDiagnosticErrorEntry[];
+    updatedAt: number;
+}
 /**
- * The `SocketController` class handles the setup and management of a WebSocket server,
- * ensuring secure connections, message handling, and rate-limiting.
- * This class is designed to function as a singleton, providing a unified interface
- * for WebSocket interactions in the application by standardizing the server setup
- * and integrating task-based processing through the `Cadenza` framework.
+ * Socket transport orchestration in the Cadenza primitive ecosystem.
+ *
+ * - setup is signal-triggered
+ * - state/runtime ownership is actor-backed
+ * - dynamic runtime tasks are still allowed for advanced orchestration (ephemeral resolvers etc.)
  */
 declare class SocketController {
     private static _instance;
     static get instance(): SocketController;
-    private socketClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
-    private resolveTransportDiagnosticsOptions;
-    private ensureSocketClientDiagnostics;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private readonly socketServerDefaultKey;
+    private readonly socketServerActor;
+    private readonly socketClientActor;
+    private readonly socketClientDiagnosticsActor;
+    constructor();
+    private registerDiagnosticsTasks;
+    private registerSocketServerTasks;
+    private registerSocketClientTasks;
+    private createInitialSocketServerSessionState;
+    private createInitialSocketClientSessionState;
+    private resolveSocketServerKey;
+    private resolveSocketClientFetchId;
+    private resolveServicePort;
+    private createSocketServerRuntimeHandleFromContext;
+    private destroySocketServerRuntimeHandle;
+    private createSocketClientRuntimeHandle;
+    private destroySocketClientRuntimeHandle;
+    private normalizeCommunicationTypes;
     private getErrorMessage;
-    private recordSocketClientError;
+    private pruneDiagnosticsEntries;
+    getSocketClientDiagnosticsEntry(fetchId: string): Promise<SocketClientDiagnosticsState | undefined>;
+    private resolveTransportDiagnosticsOptions;
     private collectSocketTransportDiagnostics;
-    /**
-     * Constructs the `SocketServer`, setting up a WebSocket server with specific configurations,
-     * including connection state recovery, rate limiting, CORS handling, and custom event handling.
-     * This class sets up the communication infrastructure for scalable, resilient, and secure WebSocket-based interactions
-     * using metadata-driven task execution with `Cadenza`.
-     *
-     * It provides support for:
-     * - Origin-based access control for connections.
-     * - Optional payload sanitization.
-     * - Configurable rate limiting and behavior on limit breaches (soft/hard disconnects).
-     * - Event handlers for connection, handshake, delegation, signaling, status checks, and disconnection.
-     *
-     * The server can handle both internal and external interactions depending on the provided configurations,
-     * and integrates directly with Cadenza's task workflow engine.
-     *
-     * Initializes the `SocketServer` to be ready for WebSocket communication.
-     */
-    constructor();
 }
 
 /**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _cadenza_io_core from '@cadenza.io/core';
-import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, TaskOptions, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
-export { AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
+import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, TaskOptions, ActorSpec, ActorFactoryOptions, Actor, ActorDefinition, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
+export { Actor, ActorConsistencyProfileName, ActorDefinition, ActorFactoryOptions, ActorInvocationOptions, ActorKeyDefinition, ActorKind, ActorLoadPolicy, ActorRuntimeReadGuard, ActorSpec, ActorStateDefinition, ActorStateReducer, ActorStateStore, ActorTaskBindingDefinition, ActorTaskBindingOptions, ActorTaskContext, ActorTaskHandler, ActorTaskMode, ActorWriteContract, AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, IdempotencyPolicy, RetryPolicy, SessionPolicy, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
 
 /**
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -236,6 +236,8 @@ declare class ServiceRegistry {
     private remoteIntentDeputiesByTask;
     private dependeesByService;
     private dependeeByInstance;
+    private readinessDependeesByService;
+    private readinessDependeeByInstance;
     private lastHeartbeatAtByInstance;
     private missedHeartbeatsByInstance;
     private runtimeStatusFallbackInFlightByInstance;
@@ -270,6 +272,7 @@ declare class ServiceRegistry {
     handleServiceNotRespondingTask: Task;
     handleServiceHandshakeTask: Task;
     collectTransportDiagnosticsTask: Task;
+    collectReadinessTask: Task;
     private buildRemoteIntentDeputyKey;
     private normalizeIntentMaps;
     private registerRemoteIntentDeputy;
@@ -279,11 +282,16 @@ declare class ServiceRegistry {
     private getLocalInstance;
     private registerDependee;
     private unregisterDependee;
+    private getHeartbeatMisses;
+    private shouldRequireReadinessFromCommunicationTypes;
     private resolveRuntimeStatusSnapshot;
     private normalizeRuntimeStatusReport;
     private applyRuntimeStatusReport;
     private buildLocalRuntimeStatusReport;
     private selectRuntimeStatusReportForTarget;
+    private resolveRuntimeStatusFallbackInquiry;
+    private evaluateDependencyReadinessDetail;
+    private buildLocalReadinessReport;
     /**
      * Initializes a private constructor for managing service instances, remote signals,
      * service health, and handling updates or synchronization tasks. The constructor
@@ -22414,6 +22422,8 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    static createActor<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
+    static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
      * Creates and registers a new task with the provided name, function, and optional details.
      *
@@ -22776,6 +22786,9 @@ declare class RestController {
     static get instance(): RestController;
     private fetchClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private pruneFetchClientDiagnostics;
     private resolveTransportDiagnosticsOptions;
     private ensureFetchClientDiagnostics;
     private getErrorMessage;
@@ -22805,41 +22818,68 @@ declare class RestController {
     constructor();
 }
 
+interface TransportDiagnosticErrorEntry {
+    at: string;
+    message: string;
+}
+interface SocketClientDiagnosticsState {
+    fetchId: string;
+    serviceName: string;
+    url: string;
+    socketId: string | null;
+    connected: boolean;
+    handshake: boolean;
+    reconnectAttempts: number;
+    connectErrors: number;
+    reconnectErrors: number;
+    socketErrors: number;
+    pendingDelegations: number;
+    pendingTimers: number;
+    destroyed: boolean;
+    lastHandshakeAt: string | null;
+    lastHandshakeError: string | null;
+    lastDisconnectAt: string | null;
+    lastError: string | null;
+    lastErrorAt: number;
+    errorHistory: TransportDiagnosticErrorEntry[];
+    updatedAt: number;
+}
 /**
- * The `SocketController` class handles the setup and management of a WebSocket server,
- * ensuring secure connections, message handling, and rate-limiting.
- * This class is designed to function as a singleton, providing a unified interface
- * for WebSocket interactions in the application by standardizing the server setup
- * and integrating task-based processing through the `Cadenza` framework.
+ * Socket transport orchestration in the Cadenza primitive ecosystem.
+ *
+ * - setup is signal-triggered
+ * - state/runtime ownership is actor-backed
+ * - dynamic runtime tasks are still allowed for advanced orchestration (ephemeral resolvers etc.)
  */
 declare class SocketController {
     private static _instance;
     static get instance(): SocketController;
-    private socketClientDiagnostics;
     private readonly diagnosticsErrorHistoryLimit;
-    private resolveTransportDiagnosticsOptions;
-    private ensureSocketClientDiagnostics;
+    private readonly diagnosticsMaxClientEntries;
+    private readonly destroyedDiagnosticsTtlMs;
+    private readonly socketServerDefaultKey;
+    private readonly socketServerActor;
+    private readonly socketClientActor;
+    private readonly socketClientDiagnosticsActor;
+    constructor();
+    private registerDiagnosticsTasks;
+    private registerSocketServerTasks;
+    private registerSocketClientTasks;
+    private createInitialSocketServerSessionState;
+    private createInitialSocketClientSessionState;
+    private resolveSocketServerKey;
+    private resolveSocketClientFetchId;
+    private resolveServicePort;
+    private createSocketServerRuntimeHandleFromContext;
+    private destroySocketServerRuntimeHandle;
+    private createSocketClientRuntimeHandle;
+    private destroySocketClientRuntimeHandle;
+    private normalizeCommunicationTypes;
     private getErrorMessage;
-    private recordSocketClientError;
+    private pruneDiagnosticsEntries;
+    getSocketClientDiagnosticsEntry(fetchId: string): Promise<SocketClientDiagnosticsState | undefined>;
+    private resolveTransportDiagnosticsOptions;
     private collectSocketTransportDiagnostics;
-    /**
-     * Constructs the `SocketServer`, setting up a WebSocket server with specific configurations,
-     * including connection state recovery, rate limiting, CORS handling, and custom event handling.
-     * This class sets up the communication infrastructure for scalable, resilient, and secure WebSocket-based interactions
-     * using metadata-driven task execution with `Cadenza`.
-     *
-     * It provides support for:
-     * - Origin-based access control for connections.
-     * - Optional payload sanitization.
-     * - Configurable rate limiting and behavior on limit breaches (soft/hard disconnects).
-     * - Event handlers for connection, handshake, delegation, signaling, status checks, and disconnection.
-     *
-     * The server can handle both internal and external interactions depending on the provided configurations,
-     * and integrates directly with Cadenza's task workflow engine.
-     *
-     * Initializes the `SocketServer` to be ready for WebSocket communication.
-     */
-    constructor();
 }
 
 /**