@cadenza.io/service 2.7.0 → 2.8.0

package/dist/index.d.mts

@@ -236,6 +236,8 @@ declare class ServiceRegistry {
     private remoteIntentDeputiesByTask;
     private dependeesByService;
     private dependeeByInstance;
+    private readinessDependeesByService;
+    private readinessDependeeByInstance;
     private lastHeartbeatAtByInstance;
     private missedHeartbeatsByInstance;
     private runtimeStatusFallbackInFlightByInstance;
@@ -270,6 +272,7 @@ declare class ServiceRegistry {
     handleServiceNotRespondingTask: Task;
     handleServiceHandshakeTask: Task;
     collectTransportDiagnosticsTask: Task;
+    collectReadinessTask: Task;
     private buildRemoteIntentDeputyKey;
     private normalizeIntentMaps;
     private registerRemoteIntentDeputy;
@@ -279,11 +282,16 @@ declare class ServiceRegistry {
     private getLocalInstance;
     private registerDependee;
     private unregisterDependee;
+    private getHeartbeatMisses;
+    private shouldRequireReadinessFromCommunicationTypes;
     private resolveRuntimeStatusSnapshot;
     private normalizeRuntimeStatusReport;
     private applyRuntimeStatusReport;
     private buildLocalRuntimeStatusReport;
     private selectRuntimeStatusReportForTarget;
+    private resolveRuntimeStatusFallbackInquiry;
+    private evaluateDependencyReadinessDetail;
+    private buildLocalReadinessReport;
     /**
      * Initializes a private constructor for managing service instances, remote signals,
      * service health, and handling updates or synchronization tasks. The constructor

package/dist/index.d.ts

@@ -236,6 +236,8 @@ declare class ServiceRegistry {
     private remoteIntentDeputiesByTask;
     private dependeesByService;
     private dependeeByInstance;
+    private readinessDependeesByService;
+    private readinessDependeeByInstance;
     private lastHeartbeatAtByInstance;
     private missedHeartbeatsByInstance;
     private runtimeStatusFallbackInFlightByInstance;
@@ -270,6 +272,7 @@ declare class ServiceRegistry {
     handleServiceNotRespondingTask: Task;
     handleServiceHandshakeTask: Task;
     collectTransportDiagnosticsTask: Task;
+    collectReadinessTask: Task;
     private buildRemoteIntentDeputyKey;
     private normalizeIntentMaps;
     private registerRemoteIntentDeputy;
@@ -279,11 +282,16 @@ declare class ServiceRegistry {
     private getLocalInstance;
     private registerDependee;
     private unregisterDependee;
+    private getHeartbeatMisses;
+    private shouldRequireReadinessFromCommunicationTypes;
     private resolveRuntimeStatusSnapshot;
     private normalizeRuntimeStatusReport;
     private applyRuntimeStatusReport;
     private buildLocalRuntimeStatusReport;
     private selectRuntimeStatusReportForTarget;
+    private resolveRuntimeStatusFallbackInquiry;
+    private evaluateDependencyReadinessDetail;
+    private buildLocalReadinessReport;
     /**
      * Initializes a private constructor for managing service instances, remote signals,
      * service health, and handling updates or synchronization tasks. The constructor

package/dist/index.js

@@ -299,6 +299,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;
 }
@@ -362,6 +363,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(
@@ -443,6 +538,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) {
@@ -479,6 +576,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();
@@ -594,6 +693,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) => {
@@ -710,7 +869,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."
@@ -1395,36 +1558,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);
@@ -1458,6 +1605,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) => {
@@ -1806,7 +1974,7 @@ var ServiceRegistry = class _ServiceRegistry {
     }
     return this.getInstance(this.serviceName, this.serviceInstanceId);
   }
-  registerDependee(serviceName, serviceInstanceId) {
+  registerDependee(serviceName, serviceInstanceId, options = {}) {
     if (!serviceName || !serviceInstanceId) {
       return;
     }
@@ -1815,6 +1983,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);
   }
@@ -1827,10 +2002,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,
@@ -1974,6 +2178,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();
@@ -1983,6 +2347,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();