@cadenza.io/service 2.7.0 → 2.9.0

package/dist/index.mjs

@@ -1,5 +1,7 @@
 // src/Cadenza.ts
-import Cadenza from "@cadenza.io/core";
+import Cadenza, {
+  Actor
+} from "@cadenza.io/core";
 
 // src/graph/definition/DeputyTask.ts
 import { v4 as uuid } from "uuid";
@@ -251,6 +253,7 @@ var isBrowser = typeof window !== "undefined" && typeof window.document !== "und
 var META_INTENT_PREFIX = "meta-";
 var META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT = "meta-runtime-transport-diagnostics";
 var META_RUNTIME_STATUS_INTENT = "meta-runtime-status";
+var META_READINESS_INTENT = "meta-readiness";
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 }
@@ -314,6 +317,100 @@ function summarizeResponderStatuses(statuses) {
   return { responded, failed, timedOut, pending };
 }
 
+// src/utils/readiness.ts
+function evaluateDependencyReadiness(input) {
+  const missedHeartbeats = Math.max(
+    0,
+    Math.trunc(Number(input.missedHeartbeats) || 0)
+  );
+  const stale = missedHeartbeats > 0;
+  const timeoutReached = missedHeartbeats >= Math.max(1, input.missThreshold);
+  if (!input.exists) {
+    return {
+      state: "unavailable",
+      stale: true,
+      blocked: true,
+      reason: "missing"
+    };
+  }
+  if (timeoutReached) {
+    return {
+      state: "unavailable",
+      stale: true,
+      blocked: true,
+      reason: "heartbeat-timeout"
+    };
+  }
+  if (input.runtimeState === "unavailable" || !input.acceptingWork) {
+    return {
+      state: "unavailable",
+      stale,
+      blocked: true,
+      reason: "runtime-unavailable"
+    };
+  }
+  if (stale) {
+    return {
+      state: "degraded",
+      stale: true,
+      blocked: false,
+      reason: "heartbeat-stale"
+    };
+  }
+  if (input.runtimeState === "overloaded") {
+    return {
+      state: "overloaded",
+      stale: false,
+      blocked: false,
+      reason: "runtime-overloaded"
+    };
+  }
+  if (input.runtimeState === "degraded") {
+    return {
+      state: "degraded",
+      stale: false,
+      blocked: false,
+      reason: "runtime-degraded"
+    };
+  }
+  return {
+    state: "ready",
+    stale: false,
+    blocked: false,
+    reason: "runtime-healthy"
+  };
+}
+function summarizeDependencyReadiness(evaluations) {
+  const summary = {
+    total: evaluations.length,
+    ready: 0,
+    degraded: 0,
+    overloaded: 0,
+    unavailable: 0,
+    stale: 0
+  };
+  for (const evaluation of evaluations) {
+    if (evaluation.state === "ready") summary.ready++;
+    if (evaluation.state === "degraded") summary.degraded++;
+    if (evaluation.state === "overloaded") summary.overloaded++;
+    if (evaluation.state === "unavailable") summary.unavailable++;
+    if (evaluation.stale) summary.stale++;
+  }
+  return summary;
+}
+function resolveServiceReadinessState(localRuntimeState, localAcceptingWork, dependencySummary) {
+  if (localRuntimeState === "unavailable" || !localAcceptingWork) {
+    return "blocked";
+  }
+  if (dependencySummary.unavailable > 0) {
+    return "blocked";
+  }
+  if (dependencySummary.degraded > 0 || dependencySummary.overloaded > 0 || dependencySummary.stale > 0) {
+    return "degraded";
+  }
+  return "ready";
+}
+
 // src/utils/runtimeStatus.ts
 function resolveRuntimeStatus(input) {
   const numberOfRunningGraphs = Math.max(
@@ -395,6 +492,8 @@ var INTERNAL_RUNTIME_STATUS_TASK_NAMES = /* @__PURE__ */ new Set([
   "Monitor dependee heartbeat freshness",
   "Resolve runtime status fallback inquiry",
   "Respond runtime status inquiry",
+  "Respond readiness inquiry",
+  "Collect distributed readiness",
   "Get status"
 ]);
 function readPositiveIntegerEnv(name, fallback) {
@@ -431,6 +530,8 @@ var ServiceRegistry = class _ServiceRegistry {
     this.remoteIntentDeputiesByTask = /* @__PURE__ */ new Map();
     this.dependeesByService = /* @__PURE__ */ new Map();
     this.dependeeByInstance = /* @__PURE__ */ new Map();
+    this.readinessDependeesByService = /* @__PURE__ */ new Map();
+    this.readinessDependeeByInstance = /* @__PURE__ */ new Map();
     this.lastHeartbeatAtByInstance = /* @__PURE__ */ new Map();
     this.missedHeartbeatsByInstance = /* @__PURE__ */ new Map();
     this.runtimeStatusFallbackInFlightByInstance = /* @__PURE__ */ new Set();
@@ -546,6 +647,66 @@ var ServiceRegistry = class _ServiceRegistry {
       },
       "Responds to runtime-status inquiries with local service instance status."
     ).respondsTo(META_RUNTIME_STATUS_INTENT);
+    CadenzaService.defineIntent({
+      name: META_READINESS_INTENT,
+      description: "Gather service readiness reports derived from local runtime status and required dependees.",
+      input: {
+        type: "object",
+        properties: {
+          detailLevel: {
+            type: "string",
+            constraints: {
+              oneOf: ["minimal", "full"]
+            }
+          },
+          includeDependencies: {
+            type: "boolean"
+          },
+          refreshStaleDependencies: {
+            type: "boolean"
+          },
+          targetServiceName: {
+            type: "string"
+          },
+          targetServiceInstanceId: {
+            type: "string"
+          }
+        }
+      },
+      output: {
+        type: "object",
+        properties: {
+          readinessReports: {
+            type: "array"
+          }
+        }
+      }
+    });
+    CadenzaService.createMetaTask(
+      "Respond readiness inquiry",
+      async (ctx) => {
+        const targetServiceName = ctx.targetServiceName;
+        const targetServiceInstanceId = ctx.targetServiceInstanceId;
+        const report = await this.buildLocalReadinessReport({
+          detailLevel: ctx.detailLevel === "full" ? "full" : "minimal",
+          includeDependencies: ctx.includeDependencies,
+          refreshStaleDependencies: ctx.refreshStaleDependencies
+        });
+        if (!report) {
+          return {};
+        }
+        if (targetServiceName && targetServiceName !== report.serviceName) {
+          return {};
+        }
+        if (targetServiceInstanceId && targetServiceInstanceId !== report.serviceInstanceId) {
+          return {};
+        }
+        return {
+          readinessReports: [report]
+        };
+      },
+      "Responds to distributed readiness inquiries using required dependee health."
+    ).respondsTo(META_READINESS_INTENT);
     this.handleInstanceUpdateTask = CadenzaService.createMetaTask(
       "Handle Instance Update",
       (ctx, emit) => {
@@ -662,7 +823,11 @@ var ServiceRegistry = class _ServiceRegistry {
         if (!ctx.serviceName || !ctx.serviceInstanceId) {
           return false;
         }
-        this.registerDependee(ctx.serviceName, ctx.serviceInstanceId);
+        this.registerDependee(ctx.serviceName, ctx.serviceInstanceId, {
+          requiredForReadiness: this.shouldRequireReadinessFromCommunicationTypes(
+            ctx.communicationTypes
+          )
+        });
         return true;
       },
       "Tracks remote dependency instances for runtime heartbeat monitoring."
@@ -1347,36 +1512,20 @@ var ServiceRegistry = class _ServiceRegistry {
           return false;
         }
         try {
-          const inquiryResult = await CadenzaService.inquire(
-            META_RUNTIME_STATUS_INTENT,
-            {
-              targetServiceName: serviceName,
-              targetServiceInstanceId: serviceInstanceId,
-              detailLevel: ctx.detailLevel === "full" ? "full" : "minimal"
-            },
+          const { report, inquiryMeta } = await this.resolveRuntimeStatusFallbackInquiry(
+            serviceName,
+            serviceInstanceId,
             {
-              overallTimeoutMs: ctx.overallTimeoutMs ?? this.runtimeStatusFallbackTimeoutMs,
-              perResponderTimeoutMs: ctx.perResponderTimeoutMs ?? Math.max(250, Math.floor(this.runtimeStatusFallbackTimeoutMs * 0.75)),
-              requireComplete: ctx.requireComplete ?? false
+              detailLevel: ctx.detailLevel === "full" ? "full" : "minimal",
+              overallTimeoutMs: ctx.overallTimeoutMs,
+              perResponderTimeoutMs: ctx.perResponderTimeoutMs,
+              requireComplete: ctx.requireComplete
             }
           );
-          const report = this.selectRuntimeStatusReportForTarget(
-            inquiryResult,
-            serviceName,
-            serviceInstanceId
-          );
-          if (!report) {
-            throw new Error(
-              `No runtime status report for ${serviceName}/${serviceInstanceId}`
-            );
-          }
-          this.applyRuntimeStatusReport(report);
-          this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
-          this.missedHeartbeatsByInstance.set(serviceInstanceId, 0);
           return {
             ...ctx,
             runtimeStatusReport: report,
-            __inquiryMeta: inquiryResult.__inquiryMeta
+            __inquiryMeta: inquiryMeta
           };
         } catch (error) {
           const instance = this.getInstance(serviceName, serviceInstanceId);
@@ -1410,6 +1559,27 @@ var ServiceRegistry = class _ServiceRegistry {
       },
       "Runs runtime-status inquiry fallback for a dependee instance after missed heartbeats."
     ).doOn("meta.service_registry.runtime_status_fallback_requested").emits("meta.service_registry.runtime_status_fallback_resolved").emitsOnFail("meta.service_registry.runtime_status_fallback_failed");
+    this.collectReadinessTask = CadenzaService.createMetaTask(
+      "Collect distributed readiness",
+      async (ctx) => {
+        const inquiryResult = await CadenzaService.inquire(
+          META_READINESS_INTENT,
+          {
+            detailLevel: ctx.detailLevel === "full" ? "full" : "minimal",
+            includeDependencies: ctx.includeDependencies,
+            refreshStaleDependencies: ctx.refreshStaleDependencies,
+            targetServiceName: ctx.targetServiceName,
+            targetServiceInstanceId: ctx.targetServiceInstanceId
+          },
+          ctx.inquiryOptions ?? ctx.__inquiryOptions ?? {}
+        );
+        return {
+          ...ctx,
+          ...inquiryResult
+        };
+      },
+      "Collects distributed readiness reports from services."
+    ).doOn("meta.service_registry.readiness_requested").emits("meta.service_registry.readiness_collected").emitsOnFail("meta.service_registry.readiness_failed");
     this.collectTransportDiagnosticsTask = CadenzaService.createMetaTask(
       "Collect transport diagnostics",
       async (ctx) => {
@@ -1758,7 +1928,7 @@ var ServiceRegistry = class _ServiceRegistry {
     }
     return this.getInstance(this.serviceName, this.serviceInstanceId);
   }
-  registerDependee(serviceName, serviceInstanceId) {
+  registerDependee(serviceName, serviceInstanceId, options = {}) {
     if (!serviceName || !serviceInstanceId) {
       return;
     }
@@ -1767,6 +1937,13 @@ var ServiceRegistry = class _ServiceRegistry {
     }
     this.dependeesByService.get(serviceName).add(serviceInstanceId);
     this.dependeeByInstance.set(serviceInstanceId, serviceName);
+    if (options.requiredForReadiness) {
+      if (!this.readinessDependeesByService.has(serviceName)) {
+        this.readinessDependeesByService.set(serviceName, /* @__PURE__ */ new Set());
+      }
+      this.readinessDependeesByService.get(serviceName).add(serviceInstanceId);
+      this.readinessDependeeByInstance.set(serviceInstanceId, serviceName);
+    }
     this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
     this.missedHeartbeatsByInstance.set(serviceInstanceId, 0);
   }
@@ -1779,10 +1956,39 @@ var ServiceRegistry = class _ServiceRegistry {
       }
     }
     this.dependeeByInstance.delete(serviceInstanceId);
+    const readinessDependeeServiceName = serviceName ?? this.readinessDependeeByInstance.get(serviceInstanceId);
+    if (readinessDependeeServiceName) {
+      this.readinessDependeesByService.get(readinessDependeeServiceName)?.delete(serviceInstanceId);
+      if (!this.readinessDependeesByService.get(readinessDependeeServiceName)?.size) {
+        this.readinessDependeesByService.delete(readinessDependeeServiceName);
+      }
+    }
+    this.readinessDependeeByInstance.delete(serviceInstanceId);
     this.lastHeartbeatAtByInstance.delete(serviceInstanceId);
     this.missedHeartbeatsByInstance.delete(serviceInstanceId);
     this.runtimeStatusFallbackInFlightByInstance.delete(serviceInstanceId);
   }
+  getHeartbeatMisses(serviceInstanceId, now = Date.now()) {
+    const observedMisses = this.missedHeartbeatsByInstance.get(serviceInstanceId) ?? 0;
+    const lastHeartbeatAt = this.lastHeartbeatAtByInstance.get(serviceInstanceId) ?? 0;
+    if (lastHeartbeatAt <= 0) {
+      return Math.max(observedMisses, this.runtimeStatusMissThreshold);
+    }
+    const estimatedMisses = Math.max(
+      0,
+      Math.floor((now - lastHeartbeatAt) / this.runtimeStatusHeartbeatIntervalMs)
+    );
+    return Math.max(observedMisses, estimatedMisses);
+  }
+  shouldRequireReadinessFromCommunicationTypes(communicationTypes) {
+    if (!Array.isArray(communicationTypes)) {
+      return false;
+    }
+    return communicationTypes.some((type) => {
+      const normalized = String(type).toLowerCase();
+      return normalized === "delegation" || normalized === "inquiry";
+    });
+  }
   resolveRuntimeStatusSnapshot(numberOfRunningGraphs, isActive, isNonResponsive, isBlocked) {
     return resolveRuntimeStatus({
       numberOfRunningGraphs,
@@ -1926,6 +2132,166 @@ var ServiceRegistry = class _ServiceRegistry {
     }
     return null;
   }
+  async resolveRuntimeStatusFallbackInquiry(serviceName, serviceInstanceId, options = {}) {
+    const inquiryResult = await CadenzaService.inquire(
+      META_RUNTIME_STATUS_INTENT,
+      {
+        targetServiceName: serviceName,
+        targetServiceInstanceId: serviceInstanceId,
+        detailLevel: options.detailLevel ?? "minimal"
+      },
+      {
+        overallTimeoutMs: options.overallTimeoutMs ?? this.runtimeStatusFallbackTimeoutMs,
+        perResponderTimeoutMs: options.perResponderTimeoutMs ?? Math.max(250, Math.floor(this.runtimeStatusFallbackTimeoutMs * 0.75)),
+        requireComplete: options.requireComplete ?? false
+      }
+    );
+    const report = this.selectRuntimeStatusReportForTarget(
+      inquiryResult,
+      serviceName,
+      serviceInstanceId
+    );
+    if (!report) {
+      throw new Error(
+        `No runtime status report for ${serviceName}/${serviceInstanceId}`
+      );
+    }
+    if (!this.applyRuntimeStatusReport(report)) {
+      throw new Error(
+        `No tracked instance for runtime fallback ${serviceName}/${serviceInstanceId}`
+      );
+    }
+    this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
+    this.missedHeartbeatsByInstance.set(serviceInstanceId, 0);
+    return {
+      report,
+      inquiryMeta: inquiryResult.__inquiryMeta ?? {}
+    };
+  }
+  evaluateDependencyReadinessDetail(serviceName, serviceInstanceId, now = Date.now()) {
+    const instance = this.getInstance(serviceName, serviceInstanceId);
+    const missedHeartbeats = this.getHeartbeatMisses(serviceInstanceId, now);
+    const runtimeState = instance ? instance.runtimeState ?? this.resolveRuntimeStatusSnapshot(
+      instance.numberOfRunningGraphs ?? 0,
+      instance.isActive,
+      instance.isNonResponsive,
+      instance.isBlocked
+    ).state : "unavailable";
+    const acceptingWork = instance ? typeof instance.acceptingWork === "boolean" ? instance.acceptingWork : this.resolveRuntimeStatusSnapshot(
+      instance.numberOfRunningGraphs ?? 0,
+      instance.isActive,
+      instance.isNonResponsive,
+      instance.isBlocked
+    ).acceptingWork : false;
+    const evaluation = evaluateDependencyReadiness({
+      exists: Boolean(instance),
+      runtimeState,
+      acceptingWork,
+      missedHeartbeats,
+      missThreshold: this.runtimeStatusMissThreshold
+    });
+    const lastHeartbeat = this.lastHeartbeatAtByInstance.get(serviceInstanceId);
+    return {
+      serviceName,
+      serviceInstanceId,
+      dependencyState: evaluation.state,
+      runtimeState,
+      acceptingWork,
+      missedHeartbeats,
+      stale: evaluation.stale,
+      blocked: evaluation.blocked,
+      reason: evaluation.reason,
+      lastHeartbeatAt: lastHeartbeat ? new Date(lastHeartbeat).toISOString() : null,
+      reportedAt: instance?.reportedAt ?? null
+    };
+  }
+  async buildLocalReadinessReport(options = {}) {
+    const localRuntime = this.buildLocalRuntimeStatusReport("minimal");
+    if (!localRuntime) {
+      return null;
+    }
+    const detailLevel = options.detailLevel ?? "minimal";
+    const includeDependencies = options.includeDependencies ?? detailLevel === "full";
+    const refreshStaleDependencies = options.refreshStaleDependencies ?? true;
+    const dependencyPairs = Array.from(this.readinessDependeesByService.entries()).flatMap(
+      ([serviceName, instanceIds]) => Array.from(instanceIds).map((serviceInstanceId) => ({
+        serviceName,
+        serviceInstanceId
+      }))
+    ).sort((left, right) => {
+      if (left.serviceName !== right.serviceName) {
+        return left.serviceName.localeCompare(right.serviceName);
+      }
+      return left.serviceInstanceId.localeCompare(right.serviceInstanceId);
+    });
+    if (refreshStaleDependencies) {
+      for (const dependency of dependencyPairs) {
+        const misses = this.getHeartbeatMisses(dependency.serviceInstanceId);
+        if (misses < this.runtimeStatusMissThreshold) {
+          continue;
+        }
+        if (this.runtimeStatusFallbackInFlightByInstance.has(
+          dependency.serviceInstanceId
+        )) {
+          continue;
+        }
+        this.runtimeStatusFallbackInFlightByInstance.add(
+          dependency.serviceInstanceId
+        );
+        try {
+          await this.resolveRuntimeStatusFallbackInquiry(
+            dependency.serviceName,
+            dependency.serviceInstanceId
+          );
+        } catch (error) {
+          CadenzaService.log(
+            "Readiness dependency fallback failed.",
+            {
+              serviceName: dependency.serviceName,
+              serviceInstanceId: dependency.serviceInstanceId,
+              error: error instanceof Error ? error.message : String(error)
+            },
+            "warning"
+          );
+        } finally {
+          this.runtimeStatusFallbackInFlightByInstance.delete(
+            dependency.serviceInstanceId
+          );
+        }
+      }
+    }
+    const now = Date.now();
+    const dependencyDetails = dependencyPairs.map(
+      (dependency) => this.evaluateDependencyReadinessDetail(
+        dependency.serviceName,
+        dependency.serviceInstanceId,
+        now
+      )
+    );
+    const dependencySummary = summarizeDependencyReadiness(
+      dependencyDetails.map((detail) => ({
+        state: detail.dependencyState,
+        stale: detail.stale,
+        blocked: detail.blocked,
+        reason: detail.reason
+      }))
+    );
+    const readinessState = resolveServiceReadinessState(
+      localRuntime.state,
+      localRuntime.acceptingWork,
+      dependencySummary
+    );
+    return {
+      serviceName: localRuntime.serviceName,
+      serviceInstanceId: localRuntime.serviceInstanceId,
+      reportedAt: new Date(now).toISOString(),
+      readinessState,
+      runtimeState: localRuntime.state,
+      acceptingWork: localRuntime.acceptingWork,
+      dependencySummary,
+      ...includeDependencies ? { dependencies: dependencyDetails } : {}
+    };
+  }
   reset() {
     this.instances.clear();
     this.deputies.clear();
@@ -1935,6 +2301,8 @@ var ServiceRegistry = class _ServiceRegistry {
     this.remoteIntentDeputiesByTask.clear();
     this.dependeesByService.clear();
     this.dependeeByInstance.clear();
+    this.readinessDependeesByService.clear();
+    this.readinessDependeeByInstance.clear();
     this.lastHeartbeatAtByInstance.clear();
     this.missedHeartbeatsByInstance.clear();
     this.runtimeStatusFallbackInFlightByInstance.clear();
@@ -2060,6 +2428,8 @@ var RestController = class _RestController {
   constructor() {
     this.fetchClientDiagnostics = /* @__PURE__ */ new Map();
     this.diagnosticsErrorHistoryLimit = 100;
+    this.diagnosticsMaxClientEntries = 500;
+    this.destroyedDiagnosticsTtlMs = 15 * 6e4;
     /**
      * Fetches data from the given URL with a specified timeout. This function performs
      * a fetch request with the ability to cancel the request if it exceeds the provided timeout duration.
@@ -2713,6 +3083,28 @@ var RestController = class _RestController {
     if (!this._instance) this._instance = new _RestController();
     return this._instance;
   }
+  pruneFetchClientDiagnostics(now = Date.now()) {
+    for (const [fetchId, state] of this.fetchClientDiagnostics.entries()) {
+      if (state.destroyed && now - state.updatedAt > this.destroyedDiagnosticsTtlMs) {
+        this.fetchClientDiagnostics.delete(fetchId);
+      }
+    }
+    if (this.fetchClientDiagnostics.size <= this.diagnosticsMaxClientEntries) {
+      return;
+    }
+    const entriesByEvictionPriority = Array.from(
+      this.fetchClientDiagnostics.entries()
+    ).sort((left, right) => {
+      if (left[1].destroyed !== right[1].destroyed) {
+        return left[1].destroyed ? -1 : 1;
+      }
+      return left[1].updatedAt - right[1].updatedAt;
+    });
+    while (this.fetchClientDiagnostics.size > this.diagnosticsMaxClientEntries && entriesByEvictionPriority.length > 0) {
+      const [fetchId] = entriesByEvictionPriority.shift();
+      this.fetchClientDiagnostics.delete(fetchId);
+    }
+  }
   resolveTransportDiagnosticsOptions(ctx) {
     const detailLevel = ctx.detailLevel === "full" ? "full" : "summary";
     const includeErrorHistory = Boolean(ctx.includeErrorHistory);
@@ -2725,6 +3117,8 @@ var RestController = class _RestController {
     };
   }
   ensureFetchClientDiagnostics(fetchId, serviceName, url) {
+    const now = Date.now();
+    this.pruneFetchClientDiagnostics(now);
     let state = this.fetchClientDiagnostics.get(fetchId);
     if (!state) {
       state = {
@@ -2744,13 +3138,14 @@ var RestController = class _RestController {
         signalFailures: 0,
         statusChecks: 0,
         statusFailures: 0,
-        updatedAt: Date.now()
+        updatedAt: now
       };
       this.fetchClientDiagnostics.set(fetchId, state);
     } else {
       state.serviceName = serviceName;
       state.url = url;
     }
+    this.pruneFetchClientDiagnostics(now);
     return state;
   }
   getErrorMessage(error) {
@@ -2782,6 +3177,7 @@ var RestController = class _RestController {
     }
   }
   collectFetchTransportDiagnostics(ctx) {
+    this.pruneFetchClientDiagnostics();
     const { detailLevel, includeErrorHistory, errorHistoryLimit } = this.resolveTransportDiagnosticsOptions(ctx);
     const serviceName = CadenzaService.serviceRegistry.serviceName ?? "UnknownService";
     const states = Array.from(this.fetchClientDiagnostics.values()).sort(
@@ -2898,55 +3294,225 @@ var waitForSocketConnection = async (socket, timeoutMs, createError) => {
 
 // src/network/SocketController.ts
 var SocketController = class _SocketController {
-  /**
-   * 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() {
-    this.socketClientDiagnostics = /* @__PURE__ */ new Map();
     this.diagnosticsErrorHistoryLimit = 100;
+    this.diagnosticsMaxClientEntries = 500;
+    this.destroyedDiagnosticsTtlMs = 15 * 6e4;
+    this.socketServerDefaultKey = "socket-server-default";
+    this.socketServerActor = CadenzaService.createActor(
+      {
+        name: "SocketServerActor",
+        description: "Holds durable socket server session state and runtime socket server handle",
+        defaultKey: this.socketServerDefaultKey,
+        keyResolver: (input) => this.resolveSocketServerKey(input),
+        loadPolicy: "lazy",
+        writeContract: "overwrite",
+        initState: this.createInitialSocketServerSessionState(
+          this.socketServerDefaultKey
+        )
+      },
+      { isMeta: true }
+    );
+    this.socketClientActor = CadenzaService.createActor(
+      {
+        name: "SocketClientActor",
+        description: "Holds durable socket client session state and runtime socket connection handles",
+        defaultKey: "socket-client-default",
+        keyResolver: (input) => this.resolveSocketClientFetchId(input),
+        loadPolicy: "lazy",
+        writeContract: "overwrite",
+        initState: this.createInitialSocketClientSessionState()
+      },
+      { isMeta: true }
+    );
+    this.socketClientDiagnosticsActor = CadenzaService.createActor(
+      {
+        name: "SocketClientDiagnosticsActor",
+        description: "Tracks socket client diagnostics snapshots per fetchId for transport observability",
+        defaultKey: "socket-client-diagnostics",
+        loadPolicy: "eager",
+        writeContract: "overwrite",
+        initState: {
+          entries: {}
+        }
+      },
+      { isMeta: true }
+    );
+    this.registerDiagnosticsTasks();
+    this.registerSocketServerTasks();
+    this.registerSocketClientTasks();
     CadenzaService.createMetaTask(
       "Collect socket transport diagnostics",
-      (ctx) => this.collectSocketTransportDiagnostics(ctx),
+      this.socketClientDiagnosticsActor.task(
+        ({ state, input }) => this.collectSocketTransportDiagnostics(input, state.entries),
+        { mode: "read" }
+      ),
       "Responds to distributed transport diagnostics inquiries with socket client data."
     ).respondsTo(META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT);
-    CadenzaService.createMetaRoutine(
-      "SocketServer",
-      [
-        CadenzaService.createMetaTask("Setup SocketServer", (ctx) => {
-          if (!ctx.__useSocket) {
+  }
+  static get instance() {
+    if (!this._instance) this._instance = new _SocketController();
+    return this._instance;
+  }
+  registerDiagnosticsTasks() {
+    CadenzaService.createThrottledMetaTask(
+      "SocketClientDiagnosticsActor.Upsert",
+      this.socketClientDiagnosticsActor.task(
+        ({ state, input, setState }) => {
+          const fetchId = String(input.fetchId ?? "").trim();
+          if (!fetchId) {
             return;
           }
-          const server = new Server(ctx.httpsServer ?? ctx.httpServer, {
-            pingInterval: 3e4,
-            pingTimeout: 2e4,
-            maxHttpBufferSize: 1e7,
-            // 10MB large payloads
-            connectionStateRecovery: {
-              maxDisconnectionDuration: 2 * 60 * 1e3,
-              // 2min
-              skipMiddlewares: true
-              // Optional: bypass rate limiter on recover
+          const now = Date.now();
+          const entries = { ...state.entries };
+          const existing = entries[fetchId];
+          const base = existing ? {
+            ...existing,
+            errorHistory: [...existing.errorHistory]
+          } : {
+            fetchId,
+            serviceName: String(input.serviceName ?? ""),
+            url: String(input.url ?? ""),
+            socketId: null,
+            connected: false,
+            handshake: false,
+            reconnectAttempts: 0,
+            connectErrors: 0,
+            reconnectErrors: 0,
+            socketErrors: 0,
+            pendingDelegations: 0,
+            pendingTimers: 0,
+            destroyed: false,
+            lastHandshakeAt: null,
+            lastHandshakeError: null,
+            lastDisconnectAt: null,
+            lastError: null,
+            lastErrorAt: 0,
+            errorHistory: [],
+            updatedAt: now
+          };
+          if (input.serviceName !== void 0) {
+            base.serviceName = String(input.serviceName);
+          }
+          if (input.url !== void 0) {
+            base.url = String(input.url);
+          }
+          const patch = input.patch && typeof input.patch === "object" ? input.patch : {};
+          Object.assign(base, patch);
+          base.fetchId = fetchId;
+          base.updatedAt = now;
+          const errorMessage = input.error !== void 0 ? this.getErrorMessage(input.error) : void 0;
+          if (errorMessage) {
+            base.lastError = errorMessage;
+            base.lastErrorAt = now;
+            base.errorHistory.push({
+              at: new Date(now).toISOString(),
+              message: errorMessage
+            });
+            if (base.errorHistory.length > this.diagnosticsErrorHistoryLimit) {
+              base.errorHistory.splice(
+                0,
+                base.errorHistory.length - this.diagnosticsErrorHistoryLimit
+              );
             }
+          }
+          entries[fetchId] = base;
+          this.pruneDiagnosticsEntries(entries, now);
+          setState({ entries });
+        },
+        { mode: "write" }
+      ),
+      (context) => String(context?.fetchId ?? "default"),
+      "Upserts socket client diagnostics in actor state."
+    ).doOn("meta.socket_client.diagnostics_upsert_requested");
+  }
+  registerSocketServerTasks() {
+    CadenzaService.createThrottledMetaTask(
+      "SocketServerActor.PatchSession",
+      this.socketServerActor.task(
+        ({ state, input, setState }) => {
+          const patch = input.patch && typeof input.patch === "object" ? input.patch : {};
+          setState({
+            ...state,
+            ...patch,
+            updatedAt: Date.now()
+          });
+        },
+        { mode: "write" }
+      ),
+      (context) => String(context?.serverKey ?? this.socketServerDefaultKey),
+      "Applies partial durable session updates for socket server actor."
+    ).doOn("meta.socket_server.session_patch_requested");
+    CadenzaService.createMetaTask(
+      "SocketServerActor.ClearRuntime",
+      this.socketServerActor.task(
+        ({ setRuntimeState }) => {
+          setRuntimeState(null);
+        },
+        { mode: "write" }
+      ),
+      "Clears socket server runtime handle after shutdown."
+    ).doOn("meta.socket_server.runtime_clear_requested");
+    const setupSocketServerTask = CadenzaService.createMetaTask(
+      "Setup SocketServer",
+      this.socketServerActor.task(
+        ({ state, runtimeState, input, actor, setState, setRuntimeState, emit }) => {
+          const serverKey = this.resolveSocketServerKey(input) ?? actor.key ?? this.socketServerDefaultKey;
+          const shouldUseSocket = Boolean(input.__useSocket);
+          if (!shouldUseSocket) {
+            this.destroySocketServerRuntimeHandle(runtimeState);
+            setRuntimeState(null);
+            setState({
+              ...state,
+              serverKey,
+              useSocket: false,
+              status: "inactive",
+              connectionCount: 0,
+              lastShutdownAt: (/* @__PURE__ */ new Date()).toISOString(),
+              updatedAt: Date.now()
+            });
+            return;
+          }
+          let runtimeHandle = runtimeState;
+          if (!runtimeHandle) {
+            runtimeHandle = this.createSocketServerRuntimeHandleFromContext(input);
+            setRuntimeState(runtimeHandle);
+          }
+          const profile = String(input.__securityProfile ?? state.securityProfile ?? "medium");
+          const networkType = String(input.__networkType ?? state.networkType ?? "internal");
+          const schedulePatch = (patch) => {
+            CadenzaService.emit("meta.socket_server.session_patch_requested", {
+              serverKey,
+              patch
+            });
+          };
+          if (runtimeHandle.initialized) {
+            schedulePatch({
+              status: "active",
+              useSocket: true,
+              securityProfile: profile,
+              networkType,
+              connectionCount: runtimeHandle.connectedSocketIds.size,
+              lastStartedAt: state.lastStartedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+            });
+            return;
+          }
+          const server = runtimeHandle.server;
+          runtimeHandle.initialized = true;
+          setState({
+            ...state,
+            serverKey,
+            useSocket: true,
+            status: "active",
+            securityProfile: profile,
+            networkType,
+            connectionCount: runtimeHandle.connectedSocketIds.size,
+            lastStartedAt: state.lastStartedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+            updatedAt: Date.now()
           });
-          const profile = ctx.__securityProfile ?? "medium";
           server.use((socket, next) => {
             const origin = socket?.handshake?.headers?.origin;
             const allowedOrigins = ["*"];
-            const networkType = ctx.__networkType ?? "internal";
             let effectiveOrigin = origin || "unknown";
             if (networkType === "internal") effectiveOrigin = "internal";
             if (profile !== "low" && !allowedOrigins.includes(effectiveOrigin) && !allowedOrigins.includes("*")) {
@@ -2957,7 +3523,9 @@ var SocketController = class _SocketController {
               medium: { points: 1e4, duration: 10 },
               high: { points: 1e3, duration: 60, blockDuration: 300 }
             };
-            const limiter = new RateLimiterMemory2(limiterOptions[profile]);
+            const limiter = new RateLimiterMemory2(
+              limiterOptions[profile] ?? limiterOptions.medium
+            );
             const clientKey = socket?.handshake?.address || "unknown";
             socket.use((packet, packetNext) => {
               limiter.consume(clientKey).then(() => packetNext()).catch((rej) => {
@@ -2992,116 +3560,111 @@ var SocketController = class _SocketController {
             });
             next();
           });
-          if (!server) {
-            CadenzaService.log("Socket setup error: No server", {}, "error");
-            return { ...ctx, __error: "No server", errored: true };
-          }
           server.on("connection", (ws) => {
+            runtimeHandle.connectedSocketIds.add(ws.id);
+            schedulePatch({
+              connectionCount: runtimeHandle.connectedSocketIds.size,
+              lastConnectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              status: "active"
+            });
             try {
-              ws.on(
-                "handshake",
-                (ctx2, callback) => {
-                  CadenzaService.log("SocketServer: New connection", {
-                    ...ctx2,
-                    socketId: ws.id
-                  });
-                  callback({
-                    status: "success",
-                    serviceName: CadenzaService.serviceRegistry.serviceName
-                  });
-                  if (ctx2.isFrontend) {
-                    const fetchId = `browser:${ctx2.serviceInstanceId}`;
-                    CadenzaService.createMetaTask(
-                      `Transmit signal to ${fetchId}`,
-                      (ctx3, emit) => {
-                        if (ctx3.__signalName === void 0) {
-                          return;
-                        }
-                        ws.emit("signal", ctx3);
-                        if (ctx3.__routineExecId) {
-                          emit(
-                            `meta.socket_client.transmitted:${ctx3.__routineExecId}`,
-                            {}
-                          );
-                        }
+              ws.on("handshake", (ctx, callback) => {
+                CadenzaService.log("SocketServer: New connection", {
+                  ...ctx,
+                  socketId: ws.id
+                });
+                callback({
+                  status: "success",
+                  serviceName: CadenzaService.serviceRegistry.serviceName
+                });
+                if (ctx.isFrontend) {
+                  const fetchId = `browser:${ctx.serviceInstanceId}`;
+                  CadenzaService.createMetaTask(
+                    `Transmit signal to ${fetchId}`,
+                    (c, emitter) => {
+                      if (c.__signalName === void 0) {
+                        return;
+                      }
+                      ws.emit("signal", c);
+                      if (c.__routineExecId) {
+                        emitter(`meta.socket_client.transmitted:${c.__routineExecId}`, {});
                       }
-                    ).doOn(
-                      `meta.service_registry.selected_instance_for_socket:${fetchId}`
-                    ).attachSignal("meta.socket_client.transmitted");
-                  }
-                  CadenzaService.emit("meta.socket.handshake", ctx2);
-                }
-              );
-              ws.on(
-                "delegation",
-                (ctx2, callback) => {
-                  const deputyExecId = ctx2.__metadata.__deputyExecId;
-                  CadenzaService.createEphemeralMetaTask(
-                    "Resolve delegation",
-                    (ctx3) => {
-                      callback(ctx3);
-                    },
-                    "Resolves a delegation request using the provided callback from the client (.emitWithAck())",
-                    { register: false }
-                  ).doOn(`meta.node.graph_completed:${deputyExecId}`).emits(`meta.socket.delegation_resolved:${deputyExecId}`);
-                  CadenzaService.createEphemeralMetaTask(
-                    "Delegation progress update",
-                    (ctx3) => {
-                      if (ctx3.__progress !== void 0)
-                        ws.emit("delegation_progress", ctx3);
                     },
-                    "Updates delegation progress",
-                    {
-                      once: false,
-                      destroyCondition: (ctx3) => ctx3.data.progress === 1 || ctx3.data?.progress === void 0,
-                      register: false
-                    }
-                  ).doOn(
-                    `meta.node.routine_execution_progress:${deputyExecId}`,
-                    `meta.node.graph_completed:${deputyExecId}`
-                  ).emitsOnFail(`meta.socket.progress_failed:${deputyExecId}`);
-                  CadenzaService.emit("meta.socket.delegation_requested", {
-                    ...ctx2,
-                    __name: ctx2.__remoteRoutineName
-                  });
+                    "Transmit frontend bound signal through active websocket."
+                  ).doOn(`meta.service_registry.selected_instance_for_socket:${fetchId}`).attachSignal("meta.socket_client.transmitted");
                 }
-              );
-              ws.on(
-                "signal",
-                (ctx2, callback) => {
-                  if (CadenzaService.signalBroker.listObservedSignals().includes(ctx2.__signalName)) {
-                    callback({
-                      __status: "success",
-                      __signalName: ctx2.__signalName
-                    });
-                    CadenzaService.emit(ctx2.__signalName, ctx2);
-                  } else {
-                    CadenzaService.log(
-                      `No such signal ${ctx2.__signalName} on ${ctx2.__serviceName}`,
-                      "warning"
-                    );
-                    callback({
-                      ...ctx2,
-                      __status: "error",
-                      __error: `No such signal: ${ctx2.__signalName}`,
-                      errored: true
-                    });
+                CadenzaService.emit("meta.socket.handshake", ctx);
+              });
+              ws.on("delegation", (ctx, callback) => {
+                const deputyExecId = ctx.__metadata.__deputyExecId;
+                CadenzaService.createEphemeralMetaTask(
+                  "Resolve delegation",
+                  (delegationCtx) => {
+                    callback(delegationCtx);
+                  },
+                  "Resolves a delegation request using client callback.",
+                  { register: false }
+                ).doOn(`meta.node.graph_completed:${deputyExecId}`).emits(`meta.socket.delegation_resolved:${deputyExecId}`);
+                CadenzaService.createEphemeralMetaTask(
+                  "Delegation progress update",
+                  (progressCtx) => {
+                    if (progressCtx.__progress !== void 0) {
+                      ws.emit("delegation_progress", progressCtx);
+                    }
+                  },
+                  "Updates delegation progress to client.",
+                  {
+                    once: false,
+                    destroyCondition: (progressCtx) => progressCtx.data.progress === 1 || progressCtx.data?.progress === void 0,
+                    register: false
                   }
+                ).doOn(
+                  `meta.node.routine_execution_progress:${deputyExecId}`,
+                  `meta.node.graph_completed:${deputyExecId}`
+                ).emitsOnFail(`meta.socket.progress_failed:${deputyExecId}`);
+                CadenzaService.emit("meta.socket.delegation_requested", {
+                  ...ctx,
+                  __name: ctx.__remoteRoutineName
+                });
+              });
+              ws.on("signal", (ctx, callback) => {
+                if (CadenzaService.signalBroker.listObservedSignals().includes(ctx.__signalName)) {
+                  callback({
+                    __status: "success",
+                    __signalName: ctx.__signalName
+                  });
+                  CadenzaService.emit(ctx.__signalName, ctx);
+                } else {
+                  CadenzaService.log(
+                    `No such signal ${ctx.__signalName} on ${ctx.__serviceName}`,
+                    "warning"
+                  );
+                  callback({
+                    ...ctx,
+                    __status: "error",
+                    __error: `No such signal: ${ctx.__signalName}`,
+                    errored: true
+                  });
                 }
-              );
+              });
               ws.on(
                 "status_check",
-                (ctx2, callback) => {
+                (ctx, callback) => {
                   CadenzaService.createEphemeralMetaTask(
                     "Resolve status check",
                     callback,
                     "Resolves a status check request",
                     { register: false }
                   ).doAfter(CadenzaService.serviceRegistry.getStatusTask);
-                  CadenzaService.emit("meta.socket.status_check_requested", ctx2);
+                  CadenzaService.emit("meta.socket.status_check_requested", ctx);
                 }
               );
               ws.on("disconnect", () => {
+                runtimeHandle.connectedSocketIds.delete(ws.id);
+                schedulePatch({
+                  connectionCount: runtimeHandle.connectedSocketIds.size,
+                  lastDisconnectedAt: (/* @__PURE__ */ new Date()).toISOString()
+                });
                 CadenzaService.log(
                   "Socket client disconnected",
                   { socketId: ws.id },
@@ -3111,514 +3674,888 @@ var SocketController = class _SocketController {
                   __wsId: ws.id
                 });
               });
-            } catch (e) {
+            } catch (error) {
               CadenzaService.log(
                 "SocketServer: Error in socket event",
-                { error: e },
+                { error },
                 "error"
               );
             }
             CadenzaService.emit("meta.socket.connected", { __wsId: ws.id });
           });
-          CadenzaService.createMetaTask(
-            "Broadcast status",
-            (ctx2) => server.emit("status_update", ctx2),
+          runtimeHandle.broadcastStatusTask = CadenzaService.createMetaTask(
+            `Broadcast status ${serverKey}`,
+            (ctx) => server.emit("status_update", ctx),
             "Broadcasts the status of the server to all clients"
           ).doOn("meta.service.updated");
-          CadenzaService.createMetaTask(
-            "Shutdown SocketServer",
-            () => server.close(),
+          runtimeHandle.shutdownTask = CadenzaService.createMetaTask(
+            `Shutdown SocketServer ${serverKey}`,
+            async () => {
+              this.destroySocketServerRuntimeHandle(runtimeHandle);
+              CadenzaService.emit("meta.socket_server.runtime_clear_requested", {
+                serverKey
+              });
+              CadenzaService.emit("meta.socket_server.session_patch_requested", {
+                serverKey,
+                patch: {
+                  useSocket: false,
+                  status: "shutdown",
+                  connectionCount: 0,
+                  lastShutdownAt: (/* @__PURE__ */ new Date()).toISOString()
+                }
+              });
+            },
             "Shuts down the socket server"
           ).doOn("meta.socket_server_shutdown_requested").emits("meta.socket.shutdown");
-          return ctx;
-        })
-      ],
-      "Bootstraps the socket server"
-    ).doOn("global.meta.rest.network_configured");
+          return true;
+        },
+        { mode: "write" }
+      ),
+      "Initializes socket server runtime through actor state."
+    );
+    setupSocketServerTask.doOn("global.meta.rest.network_configured");
+  }
+  registerSocketClientTasks() {
+    CadenzaService.createThrottledMetaTask(
+      "SocketClientActor.ApplySessionOperation",
+      this.socketClientActor.task(
+        ({ state, input, setState }) => {
+          const operation = String(
+            input.operation ?? "transmit"
+          );
+          const patch = input.patch && typeof input.patch === "object" ? input.patch : {};
+          let next = {
+            ...state,
+            ...patch,
+            communicationTypes: patch.communicationTypes !== void 0 ? this.normalizeCommunicationTypes(patch.communicationTypes) : state.communicationTypes,
+            updatedAt: Date.now()
+          };
+          if (input.serviceName !== void 0) {
+            next.serviceName = String(input.serviceName);
+          }
+          if (input.serviceAddress !== void 0) {
+            next.serviceAddress = String(input.serviceAddress);
+          }
+          if (input.serviceInstanceId !== void 0) {
+            next.serviceInstanceId = String(input.serviceInstanceId);
+          }
+          if (input.protocol !== void 0) {
+            next.protocol = String(input.protocol);
+          }
+          if (input.url !== void 0) {
+            next.url = String(input.url);
+          }
+          if (input.servicePort !== void 0) {
+            next.servicePort = Number(input.servicePort);
+          }
+          if (input.fetchId !== void 0) {
+            next.fetchId = String(input.fetchId);
+          }
+          if (operation === "connect") {
+            next.destroyed = false;
+          } else if (operation === "handshake") {
+            next.destroyed = false;
+            next.connected = patch.connected ?? true;
+            next.handshake = patch.handshake ?? true;
+          } else if (operation === "shutdown") {
+            next.connected = false;
+            next.handshake = false;
+            next.destroyed = true;
+            next.pendingDelegations = 0;
+            next.pendingTimers = 0;
+          }
+          setState(next);
+          return next;
+        },
+        { mode: "write" }
+      ),
+      (context) => String(this.resolveSocketClientFetchId(context ?? {}) ?? "default"),
+      "Applies socket client session operation patch in actor durable state."
+    ).doOn("meta.socket_client.session_operation_requested");
+    CadenzaService.createMetaTask(
+      "SocketClientActor.ClearRuntime",
+      this.socketClientActor.task(
+        ({ setRuntimeState }) => {
+          setRuntimeState(null);
+        },
+        { mode: "write" }
+      ),
+      "Clears socket client runtime handle."
+    ).doOn("meta.socket_client.runtime_clear_requested");
     CadenzaService.createMetaTask(
       "Connect to socket server",
-      (ctx) => {
-        const {
-          serviceInstanceId,
-          communicationTypes,
-          serviceName,
-          serviceAddress,
-          servicePort,
-          protocol
-        } = ctx;
-        const socketProtocol = protocol === "https" ? "wss" : "ws";
-        const port = protocol === "https" ? 443 : servicePort;
-        const URL = `${socketProtocol}://${serviceAddress}:${port}`;
-        const fetchId = `${serviceAddress}_${port}`;
-        const socketDiagnostics = this.ensureSocketClientDiagnostics(
-          fetchId,
-          serviceName,
-          URL
-        );
-        socketDiagnostics.destroyed = false;
-        socketDiagnostics.updatedAt = Date.now();
-        let handshake = false;
-        let errorCount = 0;
-        const ERROR_LIMIT = 5;
-        if (CadenzaService.get(`Socket handshake with ${URL}`)) {
-          console.error("Socket client already exists", URL);
-          return;
-        }
-        const pendingDelegationIds = /* @__PURE__ */ new Set();
-        const pendingTimers = /* @__PURE__ */ new Set();
-        const syncPendingCounts = () => {
-          socketDiagnostics.pendingDelegations = pendingDelegationIds.size;
-          socketDiagnostics.pendingTimers = pendingTimers.size;
-          socketDiagnostics.updatedAt = Date.now();
-        };
-        let handshakeTask = null;
-        let emitWhenReady = null;
-        let transmitTask = null;
-        let delegateTask = null;
-        let socket = null;
-        socket = io(URL, {
-          reconnection: true,
-          reconnectionAttempts: 5,
-          reconnectionDelay: 2e3,
-          reconnectionDelayMax: 1e4,
-          randomizationFactor: 0.5,
-          transports: ["websocket"],
-          autoConnect: false
-        });
-        emitWhenReady = (event, data, timeoutMs = 6e4, ack) => {
-          return new Promise((resolve) => {
-            const resolveWithError = (errorMessage, fallbackError) => {
-              resolve({
-                ...data,
-                errored: true,
-                __error: errorMessage,
-                error: fallbackError instanceof Error ? fallbackError.message : errorMessage,
-                socketId: socket?.id,
+      this.socketClientActor.task(
+        ({ state, runtimeState, input, setState, setRuntimeState, emit }) => {
+          const serviceInstanceId = String(input.serviceInstanceId ?? "");
+          const communicationTypes = this.normalizeCommunicationTypes(
+            input.communicationTypes
+          );
+          const serviceName = String(input.serviceName ?? "");
+          const serviceAddress = String(input.serviceAddress ?? "");
+          const protocol = String(input.protocol ?? "http");
+          const normalizedPort = this.resolveServicePort(protocol, input.servicePort);
+          if (!serviceAddress || !normalizedPort) {
+            CadenzaService.log(
+              "Socket client setup skipped due to missing address/port",
+              {
                 serviceName,
-                URL
+                serviceAddress,
+                servicePort: input.servicePort,
+                protocol
+              },
+              "warning"
+            );
+            return false;
+          }
+          const socketProtocol = protocol === "https" ? "wss" : "ws";
+          const url = `${socketProtocol}://${serviceAddress}:${normalizedPort}`;
+          const fetchId = `${serviceAddress}_${normalizedPort}`;
+          const applySessionOperation = (operation, patch = {}) => {
+            CadenzaService.emit("meta.socket_client.session_operation_requested", {
+              fetchId,
+              operation,
+              patch,
+              serviceInstanceId,
+              communicationTypes,
+              serviceName,
+              serviceAddress,
+              servicePort: normalizedPort,
+              protocol,
+              url
+            });
+          };
+          const upsertDiagnostics = (patch, error) => {
+            CadenzaService.emit("meta.socket_client.diagnostics_upsert_requested", {
+              fetchId,
+              serviceName,
+              url,
+              patch,
+              error
+            });
+          };
+          setState({
+            ...state,
+            fetchId,
+            serviceInstanceId,
+            communicationTypes,
+            serviceName,
+            serviceAddress,
+            servicePort: normalizedPort,
+            protocol,
+            url,
+            destroyed: false,
+            updatedAt: Date.now()
+          });
+          let runtimeHandle = runtimeState;
+          if (!runtimeHandle || runtimeHandle.url !== url) {
+            this.destroySocketClientRuntimeHandle(runtimeHandle);
+            runtimeHandle = this.createSocketClientRuntimeHandle(url);
+            setRuntimeState(runtimeHandle);
+          }
+          upsertDiagnostics({
+            destroyed: false,
+            connected: false,
+            handshake: false,
+            socketId: runtimeHandle.socket.id ?? null
+          });
+          applySessionOperation("connect", {
+            destroyed: false,
+            connected: false,
+            handshake: false,
+            socketId: runtimeHandle.socket.id ?? null,
+            pendingDelegations: runtimeHandle.pendingDelegationIds.size,
+            pendingTimers: runtimeHandle.pendingTimers.size,
+            errorCount: runtimeHandle.errorCount
+          });
+          if (runtimeHandle.initialized) {
+            return true;
+          }
+          runtimeHandle.initialized = true;
+          runtimeHandle.handshake = false;
+          runtimeHandle.errorCount = 0;
+          const syncPendingCounts = () => {
+            const pendingDelegations = runtimeHandle.pendingDelegationIds.size;
+            const pendingTimers = runtimeHandle.pendingTimers.size;
+            upsertDiagnostics({
+              pendingDelegations,
+              pendingTimers
+            });
+            applySessionOperation("delegate", {
+              pendingDelegations,
+              pendingTimers
+            });
+          };
+          runtimeHandle.emitWhenReady = (event, data, timeoutMs = 6e4, ack) => {
+            return new Promise((resolve) => {
+              const parsedTimeout = Number(timeoutMs);
+              const normalizedTimeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? Math.trunc(parsedTimeout) : 6e4;
+              let timer = null;
+              let settled = false;
+              const clearPendingTimer = () => {
+                if (!timer) {
+                  return;
+                }
+                clearTimeout(timer);
+                runtimeHandle.pendingTimers.delete(timer);
+                syncPendingCounts();
+                timer = null;
+              };
+              const settle = (response) => {
+                if (settled) {
+                  return;
+                }
+                settled = true;
+                clearPendingTimer();
+                if (ack) ack(response);
+                resolve(response);
+              };
+              const resolveWithError = (errorMessage, fallbackError) => {
+                settle({
+                  ...data,
+                  errored: true,
+                  __error: errorMessage,
+                  error: fallbackError instanceof Error ? fallbackError.message : errorMessage,
+                  socketId: runtimeHandle.socket.id,
+                  serviceName,
+                  url
+                });
+              };
+              const tryEmit = async () => {
+                const waitResult = await waitForSocketConnection(
+                  runtimeHandle.socket,
+                  normalizedTimeoutMs + 10,
+                  (reason, error) => {
+                    if (reason === "connect_timeout") {
+                      return `Socket connect timed out before '${event}'`;
+                    }
+                    if (reason === "connect_error") {
+                      const errMessage = error instanceof Error ? error.message : String(error);
+                      return `Socket connect error before '${event}': ${errMessage}`;
+                    }
+                    return `Socket disconnected before '${event}'`;
+                  }
+                );
+                if (!waitResult.ok) {
+                  CadenzaService.log(
+                    waitResult.error,
+                    {
+                      socketId: runtimeHandle.socket.id,
+                      serviceName,
+                      url,
+                      event
+                    },
+                    "error"
+                  );
+                  upsertDiagnostics({}, waitResult.error);
+                  resolveWithError(waitResult.error);
+                  return;
+                }
+                timer = setTimeout(() => {
+                  if (settled) {
+                    return;
+                  }
+                  clearPendingTimer();
+                  const message = `Socket event '${event}' timed out`;
+                  CadenzaService.log(
+                    message,
+                    { socketId: runtimeHandle.socket.id, serviceName, url },
+                    "error"
+                  );
+                  upsertDiagnostics(
+                    {
+                      lastHandshakeError: message
+                    },
+                    message
+                  );
+                  applySessionOperation("transmit", {
+                    lastHandshakeError: message
+                  });
+                  resolveWithError(message);
+                }, normalizedTimeoutMs + 10);
+                runtimeHandle.pendingTimers.add(timer);
+                syncPendingCounts();
+                runtimeHandle.socket.timeout(normalizedTimeoutMs).emit(event, data, (err, response) => {
+                  if (err) {
+                    CadenzaService.log(
+                      "Socket timeout.",
+                      {
+                        event,
+                        error: err.message,
+                        socketId: runtimeHandle.socket.id,
+                        serviceName
+                      },
+                      "warning"
+                    );
+                    upsertDiagnostics(
+                      {
+                        lastHandshakeError: err.message
+                      },
+                      err
+                    );
+                    applySessionOperation("transmit", {
+                      lastHandshakeError: err.message
+                    });
+                    response = {
+                      __error: `Timeout error: ${err}`,
+                      errored: true,
+                      ...data
+                    };
+                  }
+                  settle(response);
+                });
+              };
+              void tryEmit().catch((error) => {
+                CadenzaService.log(
+                  "Socket emit failed unexpectedly",
+                  {
+                    event,
+                    error: error instanceof Error ? error.message : String(error),
+                    socketId: runtimeHandle.socket.id,
+                    serviceName,
+                    url
+                  },
+                  "error"
+                );
+                const message = `Socket event '${event}' failed`;
+                upsertDiagnostics(
+                  {
+                    lastHandshakeError: error instanceof Error ? error.message : String(error)
+                  },
+                  error
+                );
+                applySessionOperation("transmit", {
+                  lastHandshakeError: error instanceof Error ? error.message : String(error)
+                });
+                resolveWithError(message, error);
+              });
+            });
+          };
+          const socket = runtimeHandle.socket;
+          socket.on("connect", () => {
+            if (runtimeHandle.handshake) return;
+            upsertDiagnostics({
+              connected: true,
+              destroyed: false,
+              socketId: socket.id ?? null
+            });
+            applySessionOperation("connect", {
+              connected: true,
+              destroyed: false,
+              socketId: socket.id ?? null
+            });
+            CadenzaService.emit(`meta.socket_client.connected:${fetchId}`, input);
+          });
+          socket.on("delegation_progress", (delegationCtx) => {
+            CadenzaService.emit(
+              `meta.socket_client.delegation_progress:${delegationCtx.__metadata.__deputyExecId}`,
+              delegationCtx
+            );
+          });
+          socket.on("signal", (signalCtx) => {
+            if (CadenzaService.signalBroker.listObservedSignals().includes(signalCtx.__signalName)) {
+              CadenzaService.emit(signalCtx.__signalName, signalCtx);
+            }
+          });
+          socket.on("status_update", (status) => {
+            CadenzaService.emit("meta.socket_client.status_received", status);
+          });
+          socket.on("connect_error", (err) => {
+            runtimeHandle.handshake = false;
+            upsertDiagnostics(
+              {
+                connected: false,
+                handshake: false,
+                connectErrors: state.connectErrors + 1,
+                lastHandshakeError: err.message
+              },
+              err
+            );
+            applySessionOperation("connect", {
+              connected: false,
+              handshake: false,
+              connectErrors: state.connectErrors + 1,
+              lastHandshakeError: err.message
+            });
+            CadenzaService.log(
+              "Socket connect error",
+              {
+                error: err.message,
+                serviceName,
+                socketId: socket.id,
+                url
+              },
+              "error"
+            );
+            CadenzaService.emit(`meta.socket_client.connect_error:${fetchId}`, err);
+          });
+          socket.on("reconnect_attempt", (attempt) => {
+            upsertDiagnostics({ reconnectAttempts: attempt });
+            applySessionOperation("connect", {
+              reconnectAttempts: attempt
+            });
+            CadenzaService.log(`Reconnect attempt: ${attempt}`);
+          });
+          socket.on("reconnect", (attempt) => {
+            upsertDiagnostics({ connected: true });
+            applySessionOperation("connect", {
+              connected: true
+            });
+            CadenzaService.log(`Socket reconnected after ${attempt} tries`, {
+              socketId: socket.id,
+              url,
+              serviceName
+            });
+          });
+          socket.on("reconnect_error", (err) => {
+            runtimeHandle.handshake = false;
+            upsertDiagnostics(
+              {
+                connected: false,
+                handshake: false,
+                reconnectErrors: state.reconnectErrors + 1,
+                lastHandshakeError: err.message
+              },
+              err
+            );
+            applySessionOperation("connect", {
+              connected: false,
+              handshake: false,
+              reconnectErrors: state.reconnectErrors + 1,
+              lastHandshakeError: err.message
+            });
+            CadenzaService.log(
+              "Socket reconnect failed.",
+              { error: err.message, serviceName, url, socketId: socket.id },
+              "warning"
+            );
+          });
+          socket.on("error", (err) => {
+            runtimeHandle.errorCount += 1;
+            upsertDiagnostics(
+              {
+                socketErrors: state.socketErrors + 1,
+                lastHandshakeError: this.getErrorMessage(err)
+              },
+              err
+            );
+            applySessionOperation("transmit", {
+              socketErrors: state.socketErrors + 1,
+              errorCount: runtimeHandle.errorCount,
+              lastHandshakeError: this.getErrorMessage(err)
+            });
+            CadenzaService.log(
+              "Socket error",
+              { error: err, socketId: socket.id, url, serviceName },
+              "error"
+            );
+            CadenzaService.emit("meta.socket_client.error", err);
+          });
+          socket.on("disconnect", () => {
+            const disconnectedAt = (/* @__PURE__ */ new Date()).toISOString();
+            upsertDiagnostics({
+              connected: false,
+              handshake: false,
+              lastDisconnectAt: disconnectedAt
+            });
+            applySessionOperation("connect", {
+              connected: false,
+              handshake: false,
+              lastDisconnectAt: disconnectedAt
+            });
+            CadenzaService.log(
+              "Socket disconnected.",
+              { url, serviceName, socketId: socket.id },
+              "warning"
+            );
+            CadenzaService.emit(`meta.socket_client.disconnected:${fetchId}`, {
+              serviceName,
+              serviceAddress,
+              servicePort: normalizedPort
+            });
+            runtimeHandle.handshake = false;
+          });
+          socket.connect();
+          runtimeHandle.handshakeTask = CadenzaService.createMetaTask(
+            `Socket handshake with ${url}`,
+            async (_ctx, emitter) => {
+              if (runtimeHandle.handshake) return;
+              runtimeHandle.handshake = true;
+              upsertDiagnostics({
+                handshake: true
               });
-            };
-            const tryEmit = async () => {
-              const waitTimeoutMs = timeoutMs > 0 ? timeoutMs + 10 : 1e4;
-              const waitResult = await waitForSocketConnection(
-                socket,
-                waitTimeoutMs,
-                (reason, error) => {
-                  if (reason === "connect_timeout") {
-                    return `Socket connect timed out before '${event}'`;
-                  }
-                  if (reason === "connect_error") {
-                    const errMessage = error instanceof Error ? error.message : String(error);
-                    return `Socket connect error before '${event}': ${errMessage}`;
+              applySessionOperation("handshake", {
+                handshake: true
+              });
+              await runtimeHandle.emitWhenReady?.(
+                "handshake",
+                {
+                  serviceInstanceId: CadenzaService.serviceRegistry.serviceInstanceId,
+                  serviceName: CadenzaService.serviceRegistry.serviceName,
+                  isFrontend: isBrowser,
+                  __status: "success"
+                },
+                1e4,
+                (result) => {
+                  if (result.status === "success") {
+                    const handshakeAt = (/* @__PURE__ */ new Date()).toISOString();
+                    upsertDiagnostics({
+                      connected: true,
+                      handshake: true,
+                      lastHandshakeAt: handshakeAt,
+                      lastHandshakeError: null,
+                      socketId: socket.id ?? null
+                    });
+                    applySessionOperation("handshake", {
+                      connected: true,
+                      handshake: true,
+                      lastHandshakeAt: handshakeAt,
+                      lastHandshakeError: null,
+                      socketId: socket.id ?? null
+                    });
+                    CadenzaService.log("Socket client connected", {
+                      result,
+                      serviceName,
+                      socketId: socket.id,
+                      url
+                    });
+                  } else {
+                    const errorMessage = result?.__error ?? result?.error ?? "Socket handshake failed";
+                    upsertDiagnostics(
+                      {
+                        connected: false,
+                        handshake: false,
+                        lastHandshakeError: errorMessage
+                      },
+                      errorMessage
+                    );
+                    applySessionOperation("handshake", {
+                      connected: false,
+                      handshake: false,
+                      lastHandshakeError: errorMessage
+                    });
+                    CadenzaService.log(
+                      "Socket handshake failed",
+                      { result, serviceName, socketId: socket.id, url },
+                      "warning"
+                    );
                   }
-                  return `Socket disconnected before '${event}'`;
+                  void emitter;
                 }
               );
-              if (!waitResult.ok) {
-                CadenzaService.log(
-                  waitResult.error,
-                  { socketId: socket?.id, serviceName, URL, event },
-                  "error"
-                );
-                this.recordSocketClientError(
-                  fetchId,
-                  serviceName,
-                  URL,
-                  waitResult.error
-                );
-                resolveWithError(waitResult.error);
+            },
+            "Handshakes with socket server"
+          ).doOn(`meta.socket_client.connected:${fetchId}`);
+          runtimeHandle.delegateTask = CadenzaService.createMetaTask(
+            `Delegate flow to Socket service ${url}`,
+            async (delegateCtx, emitter) => {
+              if (delegateCtx.__remoteRoutineName === void 0) {
                 return;
               }
-              let timer = null;
-              if (timeoutMs !== 0) {
-                timer = setTimeout(() => {
-                  if (timer) {
-                    pendingTimers.delete(timer);
-                    syncPendingCounts();
-                    timer = null;
-                  }
-                  CadenzaService.log(
-                    `Socket event '${event}' timed out`,
-                    { socketId: socket?.id, serviceName, URL },
-                    "error"
-                  );
-                  this.recordSocketClientError(
-                    fetchId,
-                    serviceName,
-                    URL,
-                    `Socket event '${event}' timed out`
-                  );
-                  resolveWithError(`Socket event '${event}' timed out`);
-                }, timeoutMs + 10);
-                pendingTimers.add(timer);
+              delete delegateCtx.__isSubMeta;
+              delete delegateCtx.__broadcast;
+              const deputyExecId = delegateCtx.__metadata?.__deputyExecId;
+              const requestSentAt = Date.now();
+              if (deputyExecId) {
+                runtimeHandle.pendingDelegationIds.add(deputyExecId);
                 syncPendingCounts();
               }
-              const connectedSocket = socket;
-              if (!connectedSocket) {
-                resolveWithError(
-                  `Socket unavailable before emitting '${event}'`
-                );
-                return;
-              }
-              connectedSocket.timeout(timeoutMs).emit(event, data, (err, response) => {
-                if (timer) {
-                  clearTimeout(timer);
-                  pendingTimers.delete(timer);
-                  syncPendingCounts();
-                  timer = null;
+              try {
+                const resultContext = await runtimeHandle.emitWhenReady?.(
+                  "delegation",
+                  delegateCtx,
+                  delegateCtx.__timeout ?? 6e4
+                ) ?? {
+                  errored: true,
+                  __error: "Socket delegation returned no response"
+                };
+                const requestDuration = Date.now() - requestSentAt;
+                const metadata = resultContext.__metadata;
+                delete resultContext.__metadata;
+                if (deputyExecId) {
+                  emitter(`meta.socket_client.delegated:${deputyExecId}`, {
+                    ...resultContext,
+                    ...metadata,
+                    __requestDuration: requestDuration
+                  });
                 }
-                if (err) {
-                  CadenzaService.log(
-                    "Socket timeout.",
+                if (resultContext?.errored || resultContext?.failed) {
+                  const errorMessage = resultContext?.__error ?? resultContext?.error ?? "Socket delegation failed";
+                  upsertDiagnostics(
                     {
-                      event,
-                      error: err.message,
-                      socketId: socket?.id,
-                      serviceName
+                      lastHandshakeError: String(errorMessage)
                     },
-                    "warning"
-                  );
-                  this.recordSocketClientError(
-                    fetchId,
-                    serviceName,
-                    URL,
-                    err
+                    errorMessage
                   );
-                  response = {
-                    __error: `Timeout error: ${err}`,
-                    errored: true,
-                    ...ctx,
-                    ...ctx.__metadata
-                  };
+                  applySessionOperation("delegate", {
+                    lastHandshakeError: String(errorMessage)
+                  });
                 }
-                if (ack) ack(response);
-                resolve(response);
-              });
-            };
-            void tryEmit();
-          });
-        };
-        socket.on("connect", () => {
-          if (handshake) return;
-          socketDiagnostics.connected = true;
-          socketDiagnostics.destroyed = false;
-          socketDiagnostics.socketId = socket?.id ?? null;
-          socketDiagnostics.updatedAt = Date.now();
-          CadenzaService.emit(`meta.socket_client.connected:${fetchId}`, ctx);
-        });
-        socket.on("delegation_progress", (ctx2) => {
-          CadenzaService.emit(
-            `meta.socket_client.delegation_progress:${ctx2.__metadata.__deputyExecId}`,
-            ctx2
-          );
-        });
-        socket.on("signal", (ctx2) => {
-          if (CadenzaService.signalBroker.listObservedSignals().includes(ctx2.__signalName)) {
-            CadenzaService.emit(ctx2.__signalName, ctx2);
-          }
-        });
-        socket.on("status_update", (status) => {
-          CadenzaService.emit("meta.socket_client.status_received", status);
-        });
-        socket.on("connect_error", (err) => {
-          handshake = false;
-          socketDiagnostics.connected = false;
-          socketDiagnostics.handshake = false;
-          socketDiagnostics.connectErrors++;
-          socketDiagnostics.lastHandshakeError = err.message;
-          socketDiagnostics.updatedAt = Date.now();
-          this.recordSocketClientError(fetchId, serviceName, URL, err);
-          CadenzaService.log(
-            "Socket connect error",
-            { error: err.message, serviceName, socketId: socket?.id, URL },
-            "error"
-          );
-          CadenzaService.emit(`meta.socket_client.connect_error:${fetchId}`, err);
-        });
-        socket.on("reconnect_attempt", (attempt) => {
-          socketDiagnostics.reconnectAttempts = Math.max(
-            socketDiagnostics.reconnectAttempts,
-            attempt
-          );
-          socketDiagnostics.updatedAt = Date.now();
-          CadenzaService.log(`Reconnect attempt: ${attempt}`);
-        });
-        socket.on("reconnect", (attempt) => {
-          socketDiagnostics.connected = true;
-          socketDiagnostics.updatedAt = Date.now();
-          CadenzaService.log(`Socket reconnected after ${attempt} tries`, {
-            socketId: socket?.id,
-            URL,
-            serviceName
-          });
-        });
-        socket.on("reconnect_error", (err) => {
-          handshake = false;
-          socketDiagnostics.connected = false;
-          socketDiagnostics.handshake = false;
-          socketDiagnostics.reconnectErrors++;
-          socketDiagnostics.lastHandshakeError = err.message;
-          socketDiagnostics.updatedAt = Date.now();
-          this.recordSocketClientError(fetchId, serviceName, URL, err);
-          CadenzaService.log(
-            "Socket reconnect failed.",
-            { error: err.message, serviceName, URL, socketId: socket?.id },
-            "warning"
-          );
-        });
-        socket.on("error", (err) => {
-          errorCount++;
-          socketDiagnostics.socketErrors++;
-          socketDiagnostics.updatedAt = Date.now();
-          this.recordSocketClientError(fetchId, serviceName, URL, err);
-          CadenzaService.log(
-            "Socket error",
-            { error: err, socketId: socket?.id, URL, serviceName },
-            "error"
-          );
-          CadenzaService.emit("meta.socket_client.error", err);
-        });
-        socket.on("disconnect", () => {
-          const disconnectedAt = (/* @__PURE__ */ new Date()).toISOString();
-          socketDiagnostics.connected = false;
-          socketDiagnostics.handshake = false;
-          socketDiagnostics.lastDisconnectAt = disconnectedAt;
-          socketDiagnostics.updatedAt = Date.now();
-          CadenzaService.log(
-            "Socket disconnected.",
-            { URL, serviceName, socketId: socket?.id },
-            "warning"
-          );
-          CadenzaService.emit(`meta.socket_client.disconnected:${fetchId}`, {
-            serviceName,
-            serviceAddress,
-            servicePort
-          });
-          handshake = false;
-        });
-        socket.connect();
-        handshakeTask = CadenzaService.createMetaTask(
-          `Socket handshake with ${URL}`,
-          async (ctx2, emit) => {
-            if (handshake) return;
-            handshake = true;
-            socketDiagnostics.handshake = true;
-            socketDiagnostics.updatedAt = Date.now();
-            await emitWhenReady?.(
-              "handshake",
-              {
-                serviceInstanceId: CadenzaService.serviceRegistry.serviceInstanceId,
-                serviceName: CadenzaService.serviceRegistry.serviceName,
-                isFrontend: isBrowser,
-                __status: "success"
-              },
-              1e4,
-              (result) => {
-                if (result.status === "success") {
-                  socketDiagnostics.connected = true;
-                  socketDiagnostics.handshake = true;
-                  socketDiagnostics.lastHandshakeAt = (/* @__PURE__ */ new Date()).toISOString();
-                  socketDiagnostics.lastHandshakeError = null;
-                  socketDiagnostics.updatedAt = Date.now();
-                  CadenzaService.log("Socket client connected", {
-                    result,
-                    serviceName,
-                    socketId: socket?.id,
-                    URL
+                return resultContext;
+              } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const failedContext = {
+                  errored: true,
+                  __error: message
+                };
+                if (deputyExecId) {
+                  emitter(`meta.socket_client.delegated:${deputyExecId}`, {
+                    ...failedContext,
+                    __requestDuration: Date.now() - requestSentAt
                   });
-                } else {
-                  socketDiagnostics.connected = false;
-                  socketDiagnostics.handshake = false;
-                  socketDiagnostics.lastHandshakeError = result?.__error ?? result?.error ?? "Socket handshake failed";
-                  socketDiagnostics.updatedAt = Date.now();
-                  this.recordSocketClientError(
-                    fetchId,
-                    serviceName,
-                    URL,
-                    socketDiagnostics.lastHandshakeError
-                  );
-                  CadenzaService.log(
-                    "Socket handshake failed",
-                    { result, serviceName, socketId: socket?.id, URL },
-                    "warning"
-                  );
                 }
-              }
-            );
-          },
-          "Handshakes with socket server"
-        ).doOn(`meta.socket_client.connected:${fetchId}`);
-        delegateTask = CadenzaService.createMetaTask(
-          `Delegate flow to Socket service ${URL}`,
-          async (ctx2, emit) => {
-            if (ctx2.__remoteRoutineName === void 0) {
-              return;
-            }
-            return new Promise((resolve) => {
-              delete ctx2.__isSubMeta;
-              delete ctx2.__broadcast;
-              const requestSentAt = Date.now();
-              pendingDelegationIds.add(ctx2.__metadata.__deputyExecId);
-              syncPendingCounts();
-              emitWhenReady?.(
-                "delegation",
-                ctx2,
-                ctx2.__timeout ?? 6e4,
-                (resultContext) => {
-                  const requestDuration = Date.now() - requestSentAt;
-                  const metadata = resultContext.__metadata;
-                  delete resultContext.__metadata;
-                  emit(
-                    `meta.socket_client.delegated:${ctx2.__metadata.__deputyExecId}`,
-                    {
-                      ...resultContext,
-                      ...metadata,
-                      __requestDuration: requestDuration
-                    }
-                  );
-                  pendingDelegationIds.delete(ctx2.__metadata.__deputyExecId);
+                upsertDiagnostics(
+                  {
+                    lastHandshakeError: message
+                  },
+                  error
+                );
+                applySessionOperation("delegate", {
+                  lastHandshakeError: message
+                });
+                return failedContext;
+              } finally {
+                if (deputyExecId) {
+                  runtimeHandle.pendingDelegationIds.delete(deputyExecId);
                   syncPendingCounts();
-                  if (resultContext?.errored || resultContext?.failed) {
-                    this.recordSocketClientError(
-                      fetchId,
-                      serviceName,
-                      URL,
-                      resultContext?.__error ?? resultContext?.error ?? "Socket delegation failed"
-                    );
-                  }
-                  resolve(resultContext);
                 }
-              );
-            });
-          },
-          `Delegate flow to service ${serviceName} with address ${URL}`
-        ).doOn(`meta.service_registry.selected_instance_for_socket:${fetchId}`).attachSignal(
-          "meta.socket_client.delegated",
-          "meta.socket_shutdown_requested"
-        );
-        transmitTask = CadenzaService.createMetaTask(
-          `Transmit signal to socket server ${URL}`,
-          async (ctx2, emit) => {
-            if (ctx2.__signalName === void 0) {
-              return;
-            }
-            return new Promise((resolve) => {
-              delete ctx2.__broadcast;
-              emitWhenReady?.("signal", ctx2, 5e3, (response) => {
-                if (ctx2.__routineExecId) {
-                  emit(
-                    `meta.socket_client.transmitted:${ctx2.__routineExecId}`,
-                    response
-                  );
+              }
+            },
+            `Delegate flow to service ${serviceName} with address ${url}`
+          ).doOn(`meta.service_registry.selected_instance_for_socket:${fetchId}`).attachSignal(
+            "meta.socket_client.delegated",
+            "meta.socket_shutdown_requested"
+          );
+          runtimeHandle.transmitTask = CadenzaService.createMetaTask(
+            `Transmit signal to socket server ${url}`,
+            async (signalCtx, emitter) => {
+              if (signalCtx.__signalName === void 0) {
+                return;
+              }
+              delete signalCtx.__broadcast;
+              const response = await runtimeHandle.emitWhenReady?.("signal", signalCtx, 5e3) ?? {
+                errored: true,
+                __error: "Socket signal transmission returned no response"
+              };
+              applySessionOperation("transmit", {});
+              if (signalCtx.__routineExecId) {
+                emitter(`meta.socket_client.transmitted:${signalCtx.__routineExecId}`, {
+                  ...response
+                });
+              }
+              return response;
+            },
+            `Transmits signal to service ${serviceName} with address ${url}`
+          ).doOn(`meta.service_registry.selected_instance_for_socket:${fetchId}`).attachSignal("meta.socket_client.transmitted");
+          CadenzaService.createEphemeralMetaTask(
+            `Shutdown SocketClient ${url}`,
+            (_ctx, emitter) => {
+              runtimeHandle.handshake = false;
+              upsertDiagnostics({
+                connected: false,
+                handshake: false,
+                destroyed: true,
+                pendingDelegations: 0,
+                pendingTimers: 0
+              });
+              applySessionOperation("shutdown", {
+                connected: false,
+                handshake: false,
+                destroyed: true,
+                pendingDelegations: 0,
+                pendingTimers: 0
+              });
+              CadenzaService.log("Shutting down socket client", { url, serviceName });
+              emitter(`meta.fetch.handshake_requested:${fetchId}`, {
+                serviceInstanceId,
+                serviceName,
+                communicationTypes,
+                serviceAddress,
+                servicePort: normalizedPort,
+                protocol,
+                handshakeData: {
+                  instanceId: CadenzaService.serviceRegistry.serviceInstanceId,
+                  serviceName: CadenzaService.serviceRegistry.serviceName
                 }
-                resolve(response);
               });
-            });
-          },
-          `Transmits signal to service ${serviceName} with address ${URL}`
-        ).doOn(`meta.service_registry.selected_instance_for_socket:${fetchId}`).attachSignal("meta.socket_client.transmitted");
-        CadenzaService.createEphemeralMetaTask(
-          `Shutdown SocketClient ${URL}`,
-          (ctx2, emit) => {
-            handshake = false;
-            socketDiagnostics.connected = false;
-            socketDiagnostics.handshake = false;
-            socketDiagnostics.destroyed = true;
-            socketDiagnostics.updatedAt = Date.now();
-            CadenzaService.log("Shutting down socket client", { URL, serviceName });
-            socket?.close();
-            handshakeTask?.destroy();
-            delegateTask?.destroy();
-            transmitTask?.destroy();
-            handshakeTask = null;
-            delegateTask = null;
-            transmitTask = null;
-            emitWhenReady = null;
-            socket = null;
-            emit(`meta.fetch.handshake_requested:${fetchId}`, {
-              serviceInstanceId,
-              serviceName,
-              communicationTypes,
-              serviceAddress,
-              servicePort,
-              protocol,
-              handshakeData: {
-                instanceId: CadenzaService.serviceRegistry.serviceInstanceId,
-                serviceName: CadenzaService.serviceRegistry.serviceName
+              for (const id of runtimeHandle.pendingDelegationIds) {
+                emitter(`meta.socket_client.delegated:${id}`, {
+                  errored: true,
+                  __error: "Shutting down socket client"
+                });
               }
-            });
-            for (const id of pendingDelegationIds) {
-              emit(`meta.socket_client.delegated:${id}`, {
-                errored: true,
-                __error: "Shutting down socket client"
+              this.destroySocketClientRuntimeHandle(runtimeHandle);
+              emitter("meta.socket_client.runtime_clear_requested", {
+                fetchId
               });
-            }
-            pendingDelegationIds.clear();
-            syncPendingCounts();
-            for (const timer of pendingTimers) {
-              clearTimeout(timer);
-            }
-            pendingTimers.clear();
-            syncPendingCounts();
-          },
-          "Shuts down the socket client"
-        ).doOn(
-          `meta.socket_shutdown_requested:${fetchId}`,
-          `meta.socket_client.disconnected:${fetchId}`,
-          `meta.fetch.handshake_failed:${fetchId}`,
-          `meta.socket_client.connect_error:${fetchId}`
-        ).attachSignal("meta.fetch.handshake_requested").emits("meta.socket_client_shutdown_complete");
-        return true;
-      },
-      "Connects to a specified socket server"
+            },
+            "Shuts down the socket client"
+          ).doOn(
+            `meta.socket_shutdown_requested:${fetchId}`,
+            `meta.socket_client.disconnected:${fetchId}`,
+            `meta.fetch.handshake_failed:${fetchId}`,
+            `meta.socket_client.connect_error:${fetchId}`
+          ).attachSignal("meta.fetch.handshake_requested").emits("meta.socket_client_shutdown_complete");
+          return true;
+        },
+        { mode: "write" }
+      ),
+      "Connects to a specified socket server and wires runtime tasks."
     ).doOn("meta.fetch.handshake_complete").emitsOnFail("meta.socket_client.connect_failed");
   }
-  static get instance() {
-    if (!this._instance) this._instance = new _SocketController();
-    return this._instance;
+  createInitialSocketServerSessionState(serverKey) {
+    return {
+      serverKey,
+      useSocket: false,
+      status: "inactive",
+      securityProfile: "medium",
+      networkType: "internal",
+      connectionCount: 0,
+      lastStartedAt: null,
+      lastConnectedAt: null,
+      lastDisconnectedAt: null,
+      lastShutdownAt: null,
+      updatedAt: 0
+    };
   }
-  resolveTransportDiagnosticsOptions(ctx) {
-    const detailLevel = ctx.detailLevel === "full" ? "full" : "summary";
-    const includeErrorHistory = Boolean(ctx.includeErrorHistory);
-    const requestedLimit = Number(ctx.errorHistoryLimit);
-    const errorHistoryLimit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(200, Math.trunc(requestedLimit))) : 10;
+  createInitialSocketClientSessionState() {
     return {
-      detailLevel,
-      includeErrorHistory,
-      errorHistoryLimit
+      fetchId: "",
+      serviceInstanceId: "",
+      communicationTypes: [],
+      serviceName: "",
+      serviceAddress: "",
+      servicePort: 0,
+      protocol: "http",
+      url: "",
+      socketId: null,
+      connected: false,
+      handshake: false,
+      pendingDelegations: 0,
+      pendingTimers: 0,
+      reconnectAttempts: 0,
+      connectErrors: 0,
+      reconnectErrors: 0,
+      socketErrors: 0,
+      errorCount: 0,
+      destroyed: false,
+      lastHandshakeAt: null,
+      lastHandshakeError: null,
+      lastDisconnectAt: null,
+      updatedAt: 0
     };
   }
-  ensureSocketClientDiagnostics(fetchId, serviceName, url) {
-    let state = this.socketClientDiagnostics.get(fetchId);
-    if (!state) {
-      state = {
-        fetchId,
-        serviceName,
-        url,
-        socketId: null,
-        connected: false,
-        handshake: false,
-        reconnectAttempts: 0,
-        connectErrors: 0,
-        reconnectErrors: 0,
-        socketErrors: 0,
-        pendingDelegations: 0,
-        pendingTimers: 0,
-        destroyed: false,
-        lastHandshakeAt: null,
-        lastHandshakeError: null,
-        lastDisconnectAt: null,
-        lastError: null,
-        lastErrorAt: 0,
-        errorHistory: [],
-        updatedAt: Date.now()
-      };
-      this.socketClientDiagnostics.set(fetchId, state);
-    } else {
-      state.serviceName = serviceName;
-      state.url = url;
+  resolveSocketServerKey(input) {
+    return String(input.serverKey ?? input.__socketServerKey ?? this.socketServerDefaultKey).trim() || this.socketServerDefaultKey;
+  }
+  resolveSocketClientFetchId(input) {
+    const explicitFetchId = String(input.fetchId ?? "").trim();
+    if (explicitFetchId) {
+      return explicitFetchId;
     }
-    return state;
+    const serviceAddress = String(input.serviceAddress ?? "").trim();
+    const protocol = String(input.protocol ?? "http").trim();
+    const port = this.resolveServicePort(protocol, input.servicePort);
+    if (!serviceAddress || !port) {
+      return void 0;
+    }
+    return `${serviceAddress}_${port}`;
+  }
+  resolveServicePort(protocol, rawPort) {
+    if (protocol === "https") {
+      return 443;
+    }
+    const parsed = Number(rawPort);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      return void 0;
+    }
+    return Math.trunc(parsed);
+  }
+  createSocketServerRuntimeHandleFromContext(context) {
+    const baseServer = context.httpsServer ?? context.httpServer;
+    if (!baseServer) {
+      throw new Error(
+        "Socket server runtime setup requires either httpsServer or httpServer"
+      );
+    }
+    const server = new Server(baseServer, {
+      pingInterval: 3e4,
+      pingTimeout: 2e4,
+      maxHttpBufferSize: 1e7,
+      connectionStateRecovery: {
+        maxDisconnectionDuration: 2 * 60 * 1e3,
+        skipMiddlewares: true
+      }
+    });
+    return {
+      server,
+      initialized: false,
+      connectedSocketIds: /* @__PURE__ */ new Set(),
+      broadcastStatusTask: null,
+      shutdownTask: null
+    };
+  }
+  destroySocketServerRuntimeHandle(runtimeHandle) {
+    if (!runtimeHandle) {
+      return;
+    }
+    runtimeHandle.broadcastStatusTask?.destroy();
+    runtimeHandle.shutdownTask?.destroy();
+    runtimeHandle.broadcastStatusTask = null;
+    runtimeHandle.shutdownTask = null;
+    runtimeHandle.connectedSocketIds.clear();
+    runtimeHandle.initialized = false;
+    runtimeHandle.server.close();
+    runtimeHandle.server.removeAllListeners();
+  }
+  createSocketClientRuntimeHandle(url) {
+    return {
+      url,
+      socket: io(url, {
+        reconnection: true,
+        reconnectionAttempts: 5,
+        reconnectionDelay: 2e3,
+        reconnectionDelayMax: 1e4,
+        randomizationFactor: 0.5,
+        transports: ["websocket"],
+        autoConnect: false
+      }),
+      initialized: false,
+      handshake: false,
+      errorCount: 0,
+      pendingDelegationIds: /* @__PURE__ */ new Set(),
+      pendingTimers: /* @__PURE__ */ new Set(),
+      emitWhenReady: null,
+      handshakeTask: null,
+      delegateTask: null,
+      transmitTask: null
+    };
+  }
+  destroySocketClientRuntimeHandle(runtimeHandle) {
+    if (!runtimeHandle) {
+      return;
+    }
+    runtimeHandle.initialized = false;
+    runtimeHandle.handshake = false;
+    runtimeHandle.emitWhenReady = null;
+    runtimeHandle.handshakeTask?.destroy();
+    runtimeHandle.delegateTask?.destroy();
+    runtimeHandle.transmitTask?.destroy();
+    runtimeHandle.handshakeTask = null;
+    runtimeHandle.delegateTask = null;
+    runtimeHandle.transmitTask = null;
+    for (const timer of runtimeHandle.pendingTimers) {
+      clearTimeout(timer);
+    }
+    runtimeHandle.pendingTimers.clear();
+    runtimeHandle.pendingDelegationIds.clear();
+    runtimeHandle.socket.close();
+    runtimeHandle.socket.removeAllListeners();
+  }
+  normalizeCommunicationTypes(value) {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+    return value.map((item) => String(item)).filter((item) => item.trim().length > 0);
   }
   getErrorMessage(error) {
     if (error instanceof Error) {
@@ -3633,28 +4570,53 @@ var SocketController = class _SocketController {
       return String(error);
     }
   }
-  recordSocketClientError(fetchId, serviceName, url, error) {
-    const state = this.ensureSocketClientDiagnostics(fetchId, serviceName, url);
-    const message = this.getErrorMessage(error);
-    const now = Date.now();
-    state.lastError = message;
-    state.lastErrorAt = now;
-    state.updatedAt = now;
-    state.errorHistory.push({
-      at: new Date(now).toISOString(),
-      message
+  pruneDiagnosticsEntries(entries, now = Date.now()) {
+    for (const [fetchId, state] of Object.entries(entries)) {
+      if (state.destroyed && now - state.updatedAt > this.destroyedDiagnosticsTtlMs) {
+        delete entries[fetchId];
+      }
+    }
+    if (Object.keys(entries).length <= this.diagnosticsMaxClientEntries) {
+      return;
+    }
+    const entriesByEvictionPriority = Object.entries(entries).sort((left, right) => {
+      if (left[1].destroyed !== right[1].destroyed) {
+        return left[1].destroyed ? -1 : 1;
+      }
+      return left[1].updatedAt - right[1].updatedAt;
     });
-    if (state.errorHistory.length > this.diagnosticsErrorHistoryLimit) {
-      state.errorHistory.splice(
-        0,
-        state.errorHistory.length - this.diagnosticsErrorHistoryLimit
-      );
+    while (Object.keys(entries).length > this.diagnosticsMaxClientEntries && entriesByEvictionPriority.length > 0) {
+      const [fetchId] = entriesByEvictionPriority.shift();
+      delete entries[fetchId];
     }
   }
-  collectSocketTransportDiagnostics(ctx) {
+  async getSocketClientDiagnosticsEntry(fetchId) {
+    const normalized = String(fetchId ?? "").trim();
+    if (!normalized) {
+      return void 0;
+    }
+    const snapshot = this.socketClientDiagnosticsActor.getState();
+    const entries = { ...snapshot.entries };
+    this.pruneDiagnosticsEntries(entries);
+    return entries[normalized];
+  }
+  resolveTransportDiagnosticsOptions(ctx) {
+    const detailLevel = ctx.detailLevel === "full" ? "full" : "summary";
+    const includeErrorHistory = Boolean(ctx.includeErrorHistory);
+    const requestedLimit = Number(ctx.errorHistoryLimit);
+    const errorHistoryLimit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(200, Math.trunc(requestedLimit))) : 10;
+    return {
+      detailLevel,
+      includeErrorHistory,
+      errorHistoryLimit
+    };
+  }
+  collectSocketTransportDiagnostics(ctx, diagnosticsEntries) {
     const { detailLevel, includeErrorHistory, errorHistoryLimit } = this.resolveTransportDiagnosticsOptions(ctx);
     const serviceName = CadenzaService.serviceRegistry.serviceName ?? "UnknownService";
-    const states = Array.from(this.socketClientDiagnostics.values()).sort(
+    const entries = { ...diagnosticsEntries };
+    this.pruneDiagnosticsEntries(entries);
+    const states = Object.values(entries).sort(
       (a, b) => a.fetchId.localeCompare(b.fetchId)
     );
     const summary = {
@@ -3672,10 +4634,7 @@ var SocketController = class _SocketController {
         0
       ),
       connectErrors: states.reduce((acc, state) => acc + state.connectErrors, 0),
-      reconnectErrors: states.reduce(
-        (acc, state) => acc + state.reconnectErrors,
-        0
-      ),
+      reconnectErrors: states.reduce((acc, state) => acc + state.reconnectErrors, 0),
       socketErrors: states.reduce((acc, state) => acc + state.socketErrors, 0),
       latestError: states.slice().sort((a, b) => b.lastErrorAt - a.lastErrorAt).find((state) => state.lastError)?.lastError ?? null
     };
@@ -7162,6 +8121,14 @@ var CadenzaService = class {
     options.isMeta = true;
     this.createDatabaseService(name, schema, description, options);
   }
+  static createActor(spec, options = {}) {
+    this.bootstrap();
+    return new Actor(spec, options);
+  }
+  static createActorFromDefinition(definition, options = {}) {
+    this.bootstrap();
+    return Cadenza.createActorFromDefinition(definition, options);
+  }
   /**
    * Creates and registers a new task with the provided name, function, and optional details.
    *
@@ -7576,6 +8543,7 @@ CadenzaService.warnedInvalidMetaIntentResponderKeys = /* @__PURE__ */ new Set();
 
 // src/index.ts
 import {
+  Actor as Actor2,
   DebounceTask as DebounceTask2,
   EphemeralTask as EphemeralTask2,
   GraphRoutine as GraphRoutine2,
@@ -7583,6 +8551,7 @@ import {
 } from "@cadenza.io/core";
 var index_default = CadenzaService;
 export {
+  Actor2 as Actor,
   DatabaseTask,
   DebounceTask2 as DebounceTask,
   DeputyTask,