@cadenza.io/service 2.6.1 → 2.7.0

package/dist/index.js

@@ -298,6 +298,7 @@ var isBrowser = typeof window !== "undefined" && typeof window.document !== "und
 // src/utils/inquiry.ts
 var META_INTENT_PREFIX = "meta-";
 var META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT = "meta-runtime-transport-diagnostics";
+var META_RUNTIME_STATUS_INTENT = "meta-runtime-status";
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 }
@@ -361,8 +362,104 @@ function summarizeResponderStatuses(statuses) {
   return { responded, failed, timedOut, pending };
 }
 
+// src/utils/runtimeStatus.ts
+function resolveRuntimeStatus(input) {
+  const numberOfRunningGraphs = Math.max(
+    0,
+    Math.trunc(Number(input.numberOfRunningGraphs) || 0)
+  );
+  const isActive = Boolean(input.isActive);
+  const isNonResponsive = Boolean(input.isNonResponsive);
+  const isBlocked = Boolean(input.isBlocked);
+  if (!isActive || isNonResponsive || isBlocked) {
+    return {
+      state: "unavailable",
+      acceptingWork: false,
+      numberOfRunningGraphs,
+      isActive,
+      isNonResponsive,
+      isBlocked
+    };
+  }
+  if (numberOfRunningGraphs >= input.overloadedGraphThreshold) {
+    return {
+      state: "overloaded",
+      acceptingWork: true,
+      numberOfRunningGraphs,
+      isActive,
+      isNonResponsive,
+      isBlocked
+    };
+  }
+  if (numberOfRunningGraphs >= input.degradedGraphThreshold) {
+    return {
+      state: "degraded",
+      acceptingWork: true,
+      numberOfRunningGraphs,
+      isActive,
+      isNonResponsive,
+      isBlocked
+    };
+  }
+  return {
+    state: "healthy",
+    acceptingWork: true,
+    numberOfRunningGraphs,
+    isActive,
+    isNonResponsive,
+    isBlocked
+  };
+}
+function runtimeStatusPriority(state) {
+  switch (state) {
+    case "healthy":
+      return 0;
+    case "degraded":
+      return 1;
+    case "overloaded":
+      return 2;
+    case "unavailable":
+      return 3;
+    default:
+      return 4;
+  }
+}
+function hasSignificantRuntimeStatusChange(previous, next) {
+  if (!previous) {
+    return true;
+  }
+  return previous.state !== next.state || previous.acceptingWork !== next.acceptingWork || previous.isActive !== next.isActive || previous.isNonResponsive !== next.isNonResponsive || previous.isBlocked !== next.isBlocked;
+}
+
 // src/registry/ServiceRegistry.ts
 var META_SERVICE_REGISTRY_FULL_SYNC_INTENT = "meta-service-registry-full-sync";
+var META_RUNTIME_STATUS_HEARTBEAT_TICK_SIGNAL = "meta.service_registry.runtime_status.heartbeat_tick";
+var META_RUNTIME_STATUS_MONITOR_TICK_SIGNAL = "meta.service_registry.runtime_status.monitor_tick";
+var INTERNAL_RUNTIME_STATUS_TASK_NAMES = /* @__PURE__ */ new Set([
+  "Track local routine start",
+  "Track local routine end",
+  "Start runtime status sharing intervals",
+  "Broadcast runtime status",
+  "Monitor dependee heartbeat freshness",
+  "Resolve runtime status fallback inquiry",
+  "Respond runtime status inquiry",
+  "Get status"
+]);
+function readPositiveIntegerEnv(name, fallback) {
+  if (typeof process === "undefined") {
+    return fallback;
+  }
+  const raw = process.env?.[name];
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+  const normalized = Math.trunc(parsed);
+  if (normalized <= 0) {
+    return fallback;
+  }
+  return normalized;
+}
 var ServiceRegistry = class _ServiceRegistry {
   /**
    * Initializes a private constructor for managing service instances, remote signals,
@@ -380,6 +477,34 @@ var ServiceRegistry = class _ServiceRegistry {
     this.remoteIntents = /* @__PURE__ */ new Map();
     this.remoteIntentDeputiesByKey = /* @__PURE__ */ new Map();
     this.remoteIntentDeputiesByTask = /* @__PURE__ */ new Map();
+    this.dependeesByService = /* @__PURE__ */ new Map();
+    this.dependeeByInstance = /* @__PURE__ */ new Map();
+    this.lastHeartbeatAtByInstance = /* @__PURE__ */ new Map();
+    this.missedHeartbeatsByInstance = /* @__PURE__ */ new Map();
+    this.runtimeStatusFallbackInFlightByInstance = /* @__PURE__ */ new Set();
+    this.activeRoutineExecutionIds = /* @__PURE__ */ new Set();
+    this.runtimeStatusHeartbeatStarted = false;
+    this.lastRuntimeStatusSnapshot = null;
+    this.runtimeStatusHeartbeatIntervalMs = readPositiveIntegerEnv(
+      "CADENZA_RUNTIME_STATUS_HEARTBEAT_MS",
+      3e4
+    );
+    this.runtimeStatusMissThreshold = readPositiveIntegerEnv(
+      "CADENZA_RUNTIME_STATUS_MISSED_HEARTBEATS",
+      3
+    );
+    this.runtimeStatusFallbackTimeoutMs = readPositiveIntegerEnv(
+      "CADENZA_RUNTIME_STATUS_FALLBACK_TIMEOUT_MS",
+      1500
+    );
+    this.degradedGraphThreshold = readPositiveIntegerEnv(
+      "CADENZA_RUNTIME_STATUS_DEGRADED_GRAPH_THRESHOLD",
+      10
+    );
+    this.overloadedGraphThreshold = readPositiveIntegerEnv(
+      "CADENZA_RUNTIME_STATUS_OVERLOADED_GRAPH_THRESHOLD",
+      20
+    );
     this.serviceName = null;
     this.serviceInstanceId = null;
     this.numberOfRunningGraphs = 0;
@@ -418,10 +543,77 @@ var ServiceRegistry = class _ServiceRegistry {
         }
       }
     });
+    CadenzaService.defineIntent({
+      name: META_RUNTIME_STATUS_INTENT,
+      description: "Gather lightweight runtime status reports from services in the distributed runtime.",
+      input: {
+        type: "object",
+        properties: {
+          detailLevel: {
+            type: "string",
+            constraints: {
+              oneOf: ["minimal", "full"]
+            }
+          },
+          targetServiceName: {
+            type: "string"
+          },
+          targetServiceInstanceId: {
+            type: "string"
+          }
+        }
+      },
+      output: {
+        type: "object",
+        properties: {
+          runtimeStatusReports: {
+            type: "array"
+          }
+        }
+      }
+    });
+    CadenzaService.createMetaTask(
+      "Respond runtime status inquiry",
+      (ctx) => {
+        const targetServiceName = ctx.targetServiceName;
+        const targetServiceInstanceId = ctx.targetServiceInstanceId;
+        const detailLevel = ctx.detailLevel === "full" ? "full" : "minimal";
+        const report = this.buildLocalRuntimeStatusReport(detailLevel);
+        if (!report) {
+          return {};
+        }
+        if (targetServiceName && targetServiceName !== report.serviceName) {
+          return {};
+        }
+        if (targetServiceInstanceId && targetServiceInstanceId !== report.serviceInstanceId) {
+          return {};
+        }
+        return {
+          runtimeStatusReports: [report]
+        };
+      },
+      "Responds to runtime-status inquiries with local service instance status."
+    ).respondsTo(META_RUNTIME_STATUS_INTENT);
     this.handleInstanceUpdateTask = CadenzaService.createMetaTask(
       "Handle Instance Update",
       (ctx, emit) => {
-        const { serviceInstance } = ctx;
+        const serviceInstance = ctx.serviceInstance ?? (ctx.__serviceInstanceId || ctx.serviceInstanceId ? {
+          uuid: ctx.__serviceInstanceId ?? ctx.serviceInstanceId,
+          serviceName: ctx.__serviceName ?? ctx.serviceName,
+          address: ctx.serviceAddress ?? "",
+          port: ctx.servicePort ?? 0,
+          exposed: !!ctx.exposed,
+          isFrontend: !!ctx.isFrontend,
+          isActive: typeof ctx.isActive === "boolean" ? ctx.isActive : typeof ctx.__active === "boolean" ? ctx.__active : true,
+          isNonResponsive: !!ctx.isNonResponsive,
+          isBlocked: !!ctx.isBlocked,
+          health: ctx.health ?? ctx.__health ?? {},
+          numberOfRunningGraphs: ctx.numberOfRunningGraphs ?? ctx.__numberOfRunningGraphs ?? 0,
+          isPrimary: false
+        } : void 0);
+        if (!serviceInstance?.uuid || !serviceInstance?.serviceName) {
+          return false;
+        }
         const {
           uuid: uuid4,
           serviceName,
@@ -443,6 +635,7 @@ var ServiceRegistry = class _ServiceRegistry {
             emit(`meta.socket_shutdown_requested:${address}_${port}`, {});
             emit(`meta.fetch.destroy_requested:${address}_${port}`, {});
           }
+          this.unregisterDependee(uuid4, serviceName);
           return;
         }
         if (!this.instances.has(serviceName))
@@ -454,6 +647,18 @@ var ServiceRegistry = class _ServiceRegistry {
         } else {
           instances.push(serviceInstance);
         }
+        const trackedInstance = existing ?? instances.find((instance) => instance.uuid === uuid4);
+        if (trackedInstance) {
+          const snapshot = this.resolveRuntimeStatusSnapshot(
+            trackedInstance.numberOfRunningGraphs ?? 0,
+            trackedInstance.isActive,
+            trackedInstance.isNonResponsive,
+            trackedInstance.isBlocked
+          );
+          trackedInstance.runtimeState = snapshot.state;
+          trackedInstance.acceptingWork = snapshot.acceptingWork;
+          trackedInstance.reportedAt = trackedInstance.reportedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+        }
         if (this.serviceName === serviceName) {
           return false;
         }
@@ -493,13 +698,23 @@ var ServiceRegistry = class _ServiceRegistry {
       "global.meta.service_instance.inserted",
       "global.meta.service_instance.updated",
       "meta.service_instance.inserted",
-      "meta.service_instance.updated",
-      "meta.socket_client.status_received"
+      "meta.service_instance.updated"
     ).attachSignal(
       "meta.service_registry.dependee_registered",
       "meta.socket_shutdown_requested",
       "meta.fetch.destroy_requested"
     );
+    CadenzaService.createMetaTask(
+      "Track dependee registration",
+      (ctx) => {
+        if (!ctx.serviceName || !ctx.serviceInstanceId) {
+          return false;
+        }
+        this.registerDependee(ctx.serviceName, ctx.serviceInstanceId);
+        return true;
+      },
+      "Tracks remote dependency instances for runtime heartbeat monitoring."
+    ).doOn("meta.service_registry.dependee_registered");
     CadenzaService.createMetaTask("Split service instances", function* (ctx) {
       if (!ctx.serviceInstances) {
         return;
@@ -599,6 +814,15 @@ var ServiceRegistry = class _ServiceRegistry {
         for (const instance of instances ?? []) {
           instance.isActive = false;
           instance.isNonResponsive = true;
+          const snapshot = this.resolveRuntimeStatusSnapshot(
+            instance.numberOfRunningGraphs ?? 0,
+            instance.isActive,
+            instance.isNonResponsive,
+            instance.isBlocked
+          );
+          instance.runtimeState = snapshot.state;
+          instance.acceptingWork = snapshot.acceptingWork;
+          instance.reportedAt = (/* @__PURE__ */ new Date()).toISOString();
           emit("global.meta.service_registry.service_not_responding", {
             data: {
               isActive: false,
@@ -616,7 +840,8 @@ var ServiceRegistry = class _ServiceRegistry {
       "meta.fetch.handshake_failed",
       "meta.fetch.handshake_failed.*",
       "meta.socket_client.disconnected",
-      "meta.socket_client.disconnected.*"
+      "meta.socket_client.disconnected.*",
+      "meta.service_registry.runtime_status_unreachable"
     ).attachSignal("global.meta.service_registry.service_not_responding");
     this.handleServiceHandshakeTask = CadenzaService.createMetaTask(
       "Handle service handshake",
@@ -631,6 +856,15 @@ var ServiceRegistry = class _ServiceRegistry {
         }
         instance.isActive = true;
         instance.isNonResponsive = false;
+        const snapshot = this.resolveRuntimeStatusSnapshot(
+          instance.numberOfRunningGraphs ?? 0,
+          instance.isActive,
+          instance.isNonResponsive,
+          instance.isBlocked
+        );
+        instance.runtimeState = snapshot.state;
+        instance.acceptingWork = snapshot.acceptingWork;
+        instance.reportedAt = (/* @__PURE__ */ new Date()).toISOString();
         emit("global.meta.service_registry.service_handshake", {
           data: {
             isActive: instance.isActive,
@@ -648,6 +882,7 @@ var ServiceRegistry = class _ServiceRegistry {
           if (indexToDelete >= 0) {
             this.instances.get(serviceName)?.splice(indexToDelete, 1);
           }
+          this.unregisterDependee(i.uuid, serviceName);
           emit("global.meta.service_registry.deleted", {
             data: {
               isActive: false,
@@ -669,14 +904,46 @@ var ServiceRegistry = class _ServiceRegistry {
     this.handleSocketStatusUpdateTask = CadenzaService.createMetaTask(
       "Handle Socket Status Update",
       (ctx) => {
-        const instanceId = ctx.__serviceInstanceId;
-        const serviceName = ctx.__serviceName;
-        const instances = this.instances.get(serviceName);
-        const instance = instances?.find((i) => i.uuid === instanceId);
-        if (instance) {
-          instance.health = ctx.health;
-          instance.numberOfRunningGraphs = ctx.numberOfRunningGraphs;
+        const report = this.normalizeRuntimeStatusReport(ctx);
+        if (!report) {
+          return false;
         }
+        if (report.serviceName === this.serviceName && report.serviceInstanceId === this.serviceInstanceId) {
+          return false;
+        }
+        let applied = this.applyRuntimeStatusReport(report);
+        if (!applied && report.serviceAddress && typeof report.servicePort === "number") {
+          if (!this.instances.has(report.serviceName)) {
+            this.instances.set(report.serviceName, []);
+          }
+          this.instances.get(report.serviceName).push({
+            uuid: report.serviceInstanceId,
+            serviceName: report.serviceName,
+            address: report.serviceAddress,
+            port: report.servicePort,
+            exposed: !!report.exposed,
+            isFrontend: !!report.isFrontend,
+            isActive: report.isActive,
+            isNonResponsive: report.isNonResponsive,
+            isBlocked: report.isBlocked,
+            numberOfRunningGraphs: report.numberOfRunningGraphs,
+            runtimeState: report.state,
+            acceptingWork: report.acceptingWork,
+            reportedAt: report.reportedAt,
+            health: report.health ?? {},
+            isPrimary: false
+          });
+          applied = true;
+        }
+        if (!applied) {
+          return false;
+        }
+        this.registerDependee(report.serviceName, report.serviceInstanceId);
+        this.lastHeartbeatAtByInstance.set(report.serviceInstanceId, Date.now());
+        this.missedHeartbeatsByInstance.set(report.serviceInstanceId, 0);
+        this.runtimeStatusFallbackInFlightByInstance.delete(
+          report.serviceInstanceId
+        );
         return true;
       },
       "Handles status update from socket broadcast"
@@ -806,7 +1073,25 @@ var ServiceRegistry = class _ServiceRegistry {
         const { __serviceName, __triedInstances, __retries, __broadcast } = context;
         let retries = __retries ?? 0;
         let triedInstances = __triedInstances ?? [];
-        const instances = this.instances.get(__serviceName)?.filter((i) => i.isActive && !i.isNonResponsive && !i.isBlocked).sort((a, b) => a.numberOfRunningGraphs - b.numberOfRunningGraphs);
+        const instances = this.instances.get(__serviceName)?.filter((i) => i.isActive && !i.isNonResponsive && !i.isBlocked).sort((a, b) => {
+          const leftStatus = this.resolveRuntimeStatusSnapshot(
+            a.numberOfRunningGraphs ?? 0,
+            a.isActive,
+            a.isNonResponsive,
+            a.isBlocked
+          );
+          const rightStatus = this.resolveRuntimeStatusSnapshot(
+            b.numberOfRunningGraphs ?? 0,
+            b.isActive,
+            b.isNonResponsive,
+            b.isBlocked
+          );
+          const priorityDelta = runtimeStatusPriority(leftStatus.state) - runtimeStatusPriority(rightStatus.state);
+          if (priorityDelta !== 0) {
+            return priorityDelta;
+          }
+          return (a.numberOfRunningGraphs ?? 0) - (b.numberOfRunningGraphs ?? 0);
+        });
         if (!instances || instances.length === 0 || retries > this.retryCount) {
           context.errored = true;
           context.__error = `No active instances for ${__serviceName}. Retries: ${retries}. ${this.instances.get(
@@ -892,15 +1177,287 @@ var ServiceRegistry = class _ServiceRegistry {
           errored: true
         };
       }
-      const self = this.instances.get(this.serviceName)?.find((i) => i.uuid === this.serviceInstanceId);
+      const report = this.buildLocalRuntimeStatusReport("full");
+      if (!report) {
+        return {
+          ...ctx,
+          __status: "error",
+          __error: "No local service instance available for status check",
+          errored: true
+        };
+      }
       return {
         ...ctx,
         __status: "ok",
-        __numberOfRunningGraphs: self?.numberOfRunningGraphs ?? 0,
-        __health: self?.health ?? {},
-        __active: self?.isActive ?? false
+        __serviceName: report.serviceName,
+        __serviceInstanceId: report.serviceInstanceId,
+        __numberOfRunningGraphs: report.numberOfRunningGraphs,
+        __health: report.health ?? {},
+        __active: report.isActive,
+        reportedAt: report.reportedAt,
+        serviceName: report.serviceName,
+        serviceInstanceId: report.serviceInstanceId,
+        numberOfRunningGraphs: report.numberOfRunningGraphs,
+        health: report.health ?? {},
+        isActive: report.isActive,
+        isNonResponsive: report.isNonResponsive,
+        isBlocked: report.isBlocked,
+        state: report.state,
+        acceptingWork: report.acceptingWork
       };
-    }).doOn("meta.socket.status_check_requested");
+    }).doOn(
+      "meta.socket.status_check_requested",
+      "meta.rest.status_check_requested"
+    );
+    CadenzaService.createMetaTask(
+      "Track local routine start",
+      (ctx, emit) => {
+        const sourceTaskName = String(ctx.__signalEmission?.taskName ?? "");
+        if (INTERNAL_RUNTIME_STATUS_TASK_NAMES.has(sourceTaskName)) {
+          return false;
+        }
+        const routineId = String(
+          ctx.filter?.uuid ?? ctx.__routineExecId ?? ""
+        );
+        if (!routineId) {
+          return false;
+        }
+        this.activeRoutineExecutionIds.add(routineId);
+        this.numberOfRunningGraphs = this.activeRoutineExecutionIds.size;
+        const localInstance = this.getLocalInstance();
+        if (!localInstance) {
+          return true;
+        }
+        const snapshot = this.resolveRuntimeStatusSnapshot(
+          this.numberOfRunningGraphs,
+          localInstance.isActive,
+          localInstance.isNonResponsive,
+          localInstance.isBlocked
+        );
+        if (hasSignificantRuntimeStatusChange(this.lastRuntimeStatusSnapshot, snapshot)) {
+          emit("meta.service_registry.runtime_status_broadcast_requested", {
+            reason: "runtime-state-change"
+          });
+        }
+        return true;
+      },
+      "Tracks local routine starts for runtime load status."
+    ).doOn("meta.node.started_routine_execution");
+    CadenzaService.createMetaTask(
+      "Track local routine end",
+      (ctx, emit) => {
+        const sourceTaskName = String(ctx.__signalEmission?.taskName ?? "");
+        if (INTERNAL_RUNTIME_STATUS_TASK_NAMES.has(sourceTaskName)) {
+          return false;
+        }
+        const routineId = String(
+          ctx.filter?.uuid ?? ctx.__routineExecId ?? ""
+        );
+        if (!routineId) {
+          return false;
+        }
+        this.activeRoutineExecutionIds.delete(routineId);
+        this.numberOfRunningGraphs = this.activeRoutineExecutionIds.size;
+        const localInstance = this.getLocalInstance();
+        if (!localInstance) {
+          return true;
+        }
+        const snapshot = this.resolveRuntimeStatusSnapshot(
+          this.numberOfRunningGraphs,
+          localInstance.isActive,
+          localInstance.isNonResponsive,
+          localInstance.isBlocked
+        );
+        if (hasSignificantRuntimeStatusChange(this.lastRuntimeStatusSnapshot, snapshot)) {
+          emit("meta.service_registry.runtime_status_broadcast_requested", {
+            reason: "runtime-state-change"
+          });
+        }
+        return true;
+      },
+      "Tracks local routine completion for runtime load status."
+    ).doOn("meta.node.ended_routine_execution");
+    CadenzaService.createMetaTask(
+      "Start runtime status sharing intervals",
+      () => {
+        if (this.runtimeStatusHeartbeatStarted) {
+          return false;
+        }
+        this.runtimeStatusHeartbeatStarted = true;
+        CadenzaService.interval(
+          META_RUNTIME_STATUS_HEARTBEAT_TICK_SIGNAL,
+          { reason: "heartbeat" },
+          this.runtimeStatusHeartbeatIntervalMs,
+          true
+        );
+        CadenzaService.interval(
+          META_RUNTIME_STATUS_MONITOR_TICK_SIGNAL,
+          {},
+          this.runtimeStatusHeartbeatIntervalMs
+        );
+        return true;
+      },
+      "Starts runtime status heartbeat and heartbeat-monitor loops once per service instance."
+    ).doOn("meta.service_registry.instance_inserted");
+    CadenzaService.createMetaTask(
+      "Broadcast runtime status",
+      (ctx, emit) => {
+        const report = this.buildLocalRuntimeStatusReport(
+          ctx.detailLevel === "full" ? "full" : "minimal"
+        );
+        if (!report) {
+          return false;
+        }
+        const snapshot = this.resolveRuntimeStatusSnapshot(
+          report.numberOfRunningGraphs,
+          report.isActive,
+          report.isNonResponsive,
+          report.isBlocked
+        );
+        const force = ctx.reason === "heartbeat" || ctx.force === true || this.lastRuntimeStatusSnapshot === null;
+        if (!force && !hasSignificantRuntimeStatusChange(this.lastRuntimeStatusSnapshot, snapshot)) {
+          return false;
+        }
+        this.lastRuntimeStatusSnapshot = snapshot;
+        emit("meta.service.updated", {
+          __serviceName: report.serviceName,
+          __serviceInstanceId: report.serviceInstanceId,
+          __reportedAt: report.reportedAt,
+          __numberOfRunningGraphs: report.numberOfRunningGraphs,
+          __health: report.health ?? {},
+          __active: report.isActive,
+          serviceName: report.serviceName,
+          serviceInstanceId: report.serviceInstanceId,
+          serviceAddress: report.serviceAddress,
+          servicePort: report.servicePort,
+          exposed: report.exposed,
+          isFrontend: report.isFrontend,
+          reportedAt: report.reportedAt,
+          numberOfRunningGraphs: report.numberOfRunningGraphs,
+          health: report.health ?? {},
+          isActive: report.isActive,
+          isNonResponsive: report.isNonResponsive,
+          isBlocked: report.isBlocked,
+          state: report.state,
+          acceptingWork: report.acceptingWork
+        });
+        return true;
+      },
+      "Broadcasts local runtime status to connected dependees."
+    ).doOn(
+      META_RUNTIME_STATUS_HEARTBEAT_TICK_SIGNAL,
+      "meta.service_registry.runtime_status_broadcast_requested"
+    );
+    CadenzaService.createMetaTask(
+      "Monitor dependee heartbeat freshness",
+      (ctx, emit) => {
+        if (!this.useSocket) {
+          return false;
+        }
+        const now = Date.now();
+        for (const [serviceName, instanceIds] of this.dependeesByService) {
+          for (const serviceInstanceId of instanceIds) {
+            const instance = this.getInstance(serviceName, serviceInstanceId);
+            if (!instance || !instance.isActive || instance.isBlocked) {
+              continue;
+            }
+            const lastHeartbeat = this.lastHeartbeatAtByInstance.get(serviceInstanceId) ?? 0;
+            const misses = this.missedHeartbeatsByInstance.get(serviceInstanceId) ?? 0;
+            const heartbeatBudget = this.runtimeStatusHeartbeatIntervalMs * (misses + 1);
+            if (lastHeartbeat > 0 && now - lastHeartbeat < heartbeatBudget) {
+              continue;
+            }
+            const nextMisses = misses + 1;
+            this.missedHeartbeatsByInstance.set(serviceInstanceId, nextMisses);
+            if (nextMisses < this.runtimeStatusMissThreshold || this.runtimeStatusFallbackInFlightByInstance.has(serviceInstanceId)) {
+              continue;
+            }
+            this.runtimeStatusFallbackInFlightByInstance.add(serviceInstanceId);
+            emit("meta.service_registry.runtime_status_fallback_requested", {
+              ...ctx,
+              serviceName,
+              serviceInstanceId,
+              serviceAddress: instance.address,
+              servicePort: instance.port
+            });
+          }
+        }
+        return true;
+      },
+      "Monitors dependee heartbeat freshness and requests inquiry fallback after repeated misses."
+    ).doOn(META_RUNTIME_STATUS_MONITOR_TICK_SIGNAL);
+    CadenzaService.createMetaTask(
+      "Resolve runtime status fallback inquiry",
+      async (ctx, emit) => {
+        const serviceName = ctx.serviceName;
+        const serviceInstanceId = ctx.serviceInstanceId;
+        if (!serviceName || !serviceInstanceId) {
+          return false;
+        }
+        try {
+          const inquiryResult = await CadenzaService.inquire(
+            META_RUNTIME_STATUS_INTENT,
+            {
+              targetServiceName: serviceName,
+              targetServiceInstanceId: serviceInstanceId,
+              detailLevel: ctx.detailLevel === "full" ? "full" : "minimal"
+            },
+            {
+              overallTimeoutMs: ctx.overallTimeoutMs ?? this.runtimeStatusFallbackTimeoutMs,
+              perResponderTimeoutMs: ctx.perResponderTimeoutMs ?? Math.max(250, Math.floor(this.runtimeStatusFallbackTimeoutMs * 0.75)),
+              requireComplete: ctx.requireComplete ?? false
+            }
+          );
+          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
+          };
+        } catch (error) {
+          const instance = this.getInstance(serviceName, serviceInstanceId);
+          const message = error instanceof Error ? error.message : String(error);
+          CadenzaService.log(
+            "Runtime status fallback inquiry failed.",
+            {
+              serviceName,
+              serviceInstanceId,
+              error: message
+            },
+            "warning"
+          );
+          emit("meta.service_registry.runtime_status_unreachable", {
+            ...ctx,
+            serviceName,
+            serviceInstanceId,
+            serviceAddress: instance?.address ?? ctx.serviceAddress,
+            servicePort: instance?.port ?? ctx.servicePort,
+            __error: message,
+            errored: true
+          });
+          return {
+            ...ctx,
+            __error: message,
+            errored: true
+          };
+        } finally {
+          this.runtimeStatusFallbackInFlightByInstance.delete(serviceInstanceId);
+        }
+      },
+      "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.collectTransportDiagnosticsTask = CadenzaService.createMetaTask(
       "Collect transport diagnostics",
       async (ctx) => {
@@ -1240,6 +1797,183 @@ var ServiceRegistry = class _ServiceRegistry {
       localTaskName: task.name
     };
   }
+  getInstance(serviceName, instanceId) {
+    return this.instances.get(serviceName)?.find((instance) => instance.uuid === instanceId);
+  }
+  getLocalInstance() {
+    if (!this.serviceName || !this.serviceInstanceId) {
+      return void 0;
+    }
+    return this.getInstance(this.serviceName, this.serviceInstanceId);
+  }
+  registerDependee(serviceName, serviceInstanceId) {
+    if (!serviceName || !serviceInstanceId) {
+      return;
+    }
+    if (!this.dependeesByService.has(serviceName)) {
+      this.dependeesByService.set(serviceName, /* @__PURE__ */ new Set());
+    }
+    this.dependeesByService.get(serviceName).add(serviceInstanceId);
+    this.dependeeByInstance.set(serviceInstanceId, serviceName);
+    this.lastHeartbeatAtByInstance.set(serviceInstanceId, Date.now());
+    this.missedHeartbeatsByInstance.set(serviceInstanceId, 0);
+  }
+  unregisterDependee(serviceInstanceId, serviceName) {
+    const dependeeServiceName = serviceName ?? this.dependeeByInstance.get(serviceInstanceId);
+    if (dependeeServiceName) {
+      this.dependeesByService.get(dependeeServiceName)?.delete(serviceInstanceId);
+      if (!this.dependeesByService.get(dependeeServiceName)?.size) {
+        this.dependeesByService.delete(dependeeServiceName);
+      }
+    }
+    this.dependeeByInstance.delete(serviceInstanceId);
+    this.lastHeartbeatAtByInstance.delete(serviceInstanceId);
+    this.missedHeartbeatsByInstance.delete(serviceInstanceId);
+    this.runtimeStatusFallbackInFlightByInstance.delete(serviceInstanceId);
+  }
+  resolveRuntimeStatusSnapshot(numberOfRunningGraphs, isActive, isNonResponsive, isBlocked) {
+    return resolveRuntimeStatus({
+      numberOfRunningGraphs,
+      isActive,
+      isNonResponsive,
+      isBlocked,
+      degradedGraphThreshold: this.degradedGraphThreshold,
+      overloadedGraphThreshold: this.overloadedGraphThreshold
+    });
+  }
+  normalizeRuntimeStatusReport(ctx) {
+    const serviceName = ctx.serviceName ?? ctx.__serviceName ?? ctx.serviceInstance?.serviceName;
+    const serviceInstanceId = ctx.serviceInstanceId ?? ctx.__serviceInstanceId ?? ctx.serviceInstance?.uuid;
+    if (!serviceName || !serviceInstanceId) {
+      return null;
+    }
+    const servicePort = ctx.servicePort ?? ctx.port ?? ctx.serviceInstance?.port;
+    const numberOfRunningGraphs = Math.max(
+      0,
+      Math.trunc(
+        Number(ctx.numberOfRunningGraphs ?? ctx.__numberOfRunningGraphs ?? 0)
+      )
+    );
+    const isActive = Boolean(ctx.isActive ?? ctx.__active ?? true);
+    const isNonResponsive = Boolean(ctx.isNonResponsive ?? false);
+    const isBlocked = Boolean(ctx.isBlocked ?? false);
+    const resolved = this.resolveRuntimeStatusSnapshot(
+      numberOfRunningGraphs,
+      isActive,
+      isNonResponsive,
+      isBlocked
+    );
+    return {
+      serviceName,
+      serviceInstanceId,
+      serviceAddress: ctx.serviceAddress ?? ctx.address ?? ctx.serviceInstance?.address,
+      servicePort: typeof servicePort === "number" ? servicePort : void 0,
+      exposed: typeof ctx.exposed === "boolean" ? ctx.exposed : typeof ctx.serviceInstance?.exposed === "boolean" ? ctx.serviceInstance.exposed : void 0,
+      isFrontend: typeof ctx.isFrontend === "boolean" ? ctx.isFrontend : typeof ctx.serviceInstance?.isFrontend === "boolean" ? ctx.serviceInstance.isFrontend : void 0,
+      reportedAt: ctx.reportedAt ?? (typeof ctx.__reportedAt === "string" ? ctx.__reportedAt : void 0) ?? (/* @__PURE__ */ new Date()).toISOString(),
+      state: ctx.state === "healthy" || ctx.state === "degraded" || ctx.state === "overloaded" || ctx.state === "unavailable" ? ctx.state : resolved.state,
+      acceptingWork: typeof ctx.acceptingWork === "boolean" ? ctx.acceptingWork : resolved.acceptingWork,
+      numberOfRunningGraphs,
+      isActive,
+      isNonResponsive,
+      isBlocked,
+      health: ctx.health ?? ctx.__health ?? {}
+    };
+  }
+  applyRuntimeStatusReport(report) {
+    const instance = this.getInstance(report.serviceName, report.serviceInstanceId);
+    if (!instance) {
+      return false;
+    }
+    if (report.serviceAddress) {
+      instance.address = report.serviceAddress;
+    }
+    if (typeof report.servicePort === "number") {
+      instance.port = report.servicePort;
+    }
+    if (typeof report.exposed === "boolean") {
+      instance.exposed = report.exposed;
+    }
+    if (typeof report.isFrontend === "boolean") {
+      instance.isFrontend = report.isFrontend;
+    }
+    instance.numberOfRunningGraphs = report.numberOfRunningGraphs;
+    instance.isActive = report.isActive;
+    instance.isNonResponsive = report.isNonResponsive;
+    instance.isBlocked = report.isBlocked;
+    instance.runtimeState = report.state;
+    instance.acceptingWork = report.acceptingWork;
+    instance.reportedAt = report.reportedAt;
+    instance.health = {
+      ...instance.health ?? {},
+      ...report.health ?? {},
+      runtimeStatus: {
+        state: report.state,
+        acceptingWork: report.acceptingWork,
+        reportedAt: report.reportedAt
+      }
+    };
+    return true;
+  }
+  buildLocalRuntimeStatusReport(detailLevel = "minimal") {
+    if (!this.serviceName || !this.serviceInstanceId) {
+      return null;
+    }
+    const localInstance = this.getLocalInstance();
+    if (!localInstance) {
+      return null;
+    }
+    const numberOfRunningGraphs = this.activeRoutineExecutionIds.size || this.numberOfRunningGraphs || 0;
+    this.numberOfRunningGraphs = numberOfRunningGraphs;
+    const snapshot = this.resolveRuntimeStatusSnapshot(
+      numberOfRunningGraphs,
+      localInstance.isActive,
+      localInstance.isNonResponsive,
+      localInstance.isBlocked
+    );
+    const reportedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const report = {
+      serviceName: this.serviceName,
+      serviceInstanceId: this.serviceInstanceId,
+      serviceAddress: localInstance.address,
+      servicePort: localInstance.port,
+      exposed: localInstance.exposed,
+      isFrontend: localInstance.isFrontend,
+      reportedAt,
+      state: snapshot.state,
+      acceptingWork: snapshot.acceptingWork,
+      numberOfRunningGraphs: snapshot.numberOfRunningGraphs,
+      isActive: snapshot.isActive,
+      isNonResponsive: snapshot.isNonResponsive,
+      isBlocked: snapshot.isBlocked,
+      health: {
+        ...localInstance.health ?? {},
+        runtimeStatus: {
+          state: snapshot.state,
+          acceptingWork: snapshot.acceptingWork,
+          reportedAt
+        }
+      }
+    };
+    this.applyRuntimeStatusReport(report);
+    if (detailLevel !== "full") {
+      delete report.health;
+    }
+    return report;
+  }
+  selectRuntimeStatusReportForTarget(inquiryResult, targetServiceName, targetServiceInstanceId) {
+    const reports = Array.isArray(inquiryResult.runtimeStatusReports) ? inquiryResult.runtimeStatusReports : [];
+    for (const candidate of reports) {
+      const report = this.normalizeRuntimeStatusReport(candidate);
+      if (!report) {
+        continue;
+      }
+      if (report.serviceName === targetServiceName && report.serviceInstanceId === targetServiceInstanceId) {
+        return report;
+      }
+    }
+    return null;
+  }
   reset() {
     this.instances.clear();
     this.deputies.clear();
@@ -1247,6 +1981,15 @@ var ServiceRegistry = class _ServiceRegistry {
     this.remoteIntents.clear();
     this.remoteIntentDeputiesByKey.clear();
     this.remoteIntentDeputiesByTask.clear();
+    this.dependeesByService.clear();
+    this.dependeeByInstance.clear();
+    this.lastHeartbeatAtByInstance.clear();
+    this.missedHeartbeatsByInstance.clear();
+    this.runtimeStatusFallbackInFlightByInstance.clear();
+    this.activeRoutineExecutionIds.clear();
+    this.numberOfRunningGraphs = 0;
+    this.runtimeStatusHeartbeatStarted = false;
+    this.lastRuntimeStatusSnapshot = null;
   }
 };