@zlink-systems/framework 0.26.0 → 0.27.0

package/src/runtime/host/route-mesh-runtime.ts

@@ -1,27 +1,46 @@
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
-import type { RoutingId } from '../../contracts';
-import {
+  type RoutingId,
   ZLinkFrameworkException,
   ZLinkFrameworkRuntimeState,
-  ZLinkTopologyState,
-  ZLinkTopologyReason,
+  ZLinkObjectRole,
   ZLinkPeerState,
+  ZLinkTopologyReason,
+  ZLinkTopologyState,
+  type ZLinkMeshNodeDescriptor,
   type ZLinkObservedStatus,
-  type ZLinkRouteMeshStatus,
-  type ZLinkRouteMeshRuntime
+  type ZLinkRouteMeshRuntime,
+  type ZLinkRouteMeshStatus
 } from '../../contracts';
+
+import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../contracts/Configuration/RegistrationBuilderPolicy';
+import { createDeadlineExceededError } from '../abort';
+import type { ZLinkActivationAdmission } from '../activation-admission';
+import type { ZLinkRuntimeAdmissionGate } from '../admission';
+import type { ZLinkBackendMeshNode } from '../backend';
+import type { ZLinkSpotNodeOptions } from '../configuration';
+import { isRelocationDebugEnabled } from '../diagnostics';
 import {
   RuntimeEventQueue,
   ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY
 } from '../diagnostics/runtime-observation-queue';
-import { createDeadlineExceededError } from '../abort';
+import { debugPendingWorkNames, isStructuralGuardEnabled } from '../execution/state-lane';
 import {
   runtimeStateIsReady,
+  topologyObservationIsTerminal,
   topologyRuntimeIsReady
 } from '../foundation/runtime-state-projections';
+import {
+  MeshNodeRuntimeState,
+  MeshPeerRuntimeState
+} from '../foundation/service-runtime-contracts';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+import { ZLinkOwnerCleanupError } from '../locations/runtime';
+const DEFAULT_ROUTE_MESH_DRAIN_TIMEOUT_MS = 30_000;
+const MAX_ROUTE_MESH_OBSERVATION_WAIT_MS = 1000;
+const PLACEMENT_OBSERVATION_INTERVAL_MS = 100;
 
 type ZLinkDrainForceReason =
   'deadline_exceeded' | 'drain_state_publish_failed' | 'owner_cleanup_failed' | 'teardown_failed';
@@ -33,11 +52,6 @@ type ZLinkMeshDrainResult =
       readonly reason: ZLinkDrainForceReason;
       readonly error?: unknown;
     };
-import type { ZLinkBackendMeshNode } from '../backend';
-import type { ZLinkRuntimeAdmissionGate } from '../admission';
-import type { ZLinkActivationAdmission } from '../activation-admission';
-import type { ZLinkSpotNodeOptions } from '../configuration';
-import { ZLinkObjectRole, type ZLinkMeshNodeDescriptor } from '../../contracts';
 
 export interface ZLinkRouteMeshRuntimeCoordinatorOptions {
   readonly meshNames: readonly string[];
@@ -70,7 +84,6 @@ export interface ZLinkLocalPlacementCounts {
 
 interface ZLinkMeshDrainState {
   state: ZLinkTopologyState;
-  sequence: bigint;
   deadline?: Date;
   operation?: Promise<ZLinkMeshDrainResult>;
   result?: ZLinkMeshDrainResult;
@@ -81,9 +94,6 @@ interface ZLinkMeshDrainState {
 
 export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
   private readonly states = new Map<string, ZLinkMeshDrainState>();
-  private readonly placementFingerprints = new Map<string, string>();
-  private readonly peerFingerprints = new Map<string, Map<string, string>>();
-  private readonly locationStoreHealthFingerprints = new Map<string, boolean>();
   private placementObserver?: ReturnType<typeof setInterval>;
   private hostOperation?: Promise<ZLinkMeshDrainResult>;
   private shutdownOperation?: Promise<ZLinkMeshDrainResult>;
@@ -94,7 +104,6 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
       options.admission.register(meshName);
       this.states.set(meshName, {
         state: ZLinkTopologyState.Starting,
-        sequence: 0n,
         waiters: [],
         observers: new Set()
       });
@@ -109,6 +118,12 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
   }
 
   snapshot(meshName: string): ZLinkRouteMeshStatus {
+    const published = this.publishCurrentStatus(meshName, this.requireState(meshName));
+    if (published === undefined) throw routeNotFound(meshName);
+    return published;
+  }
+
+  private buildSnapshot(meshName: string, sequence: bigint): ZLinkRouteMeshStatus {
     const drain = this.requireState(meshName);
     const node = this.options.meshNode(meshName);
     if (node === undefined) throw routeNotFound(meshName);
@@ -157,7 +172,8 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
               )
           ).length
         );
-        const localWeight = descriptor?.channelWeights[channelName] ?? channel.weight ?? 100;
+        const localWeight =
+          descriptor?.channelWeights[channelName] ?? channel.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT;
         const readyTargetCount =
           Number(readyMemberCount) + (channel.server === true && localWeight > 0 ? 1 : 0);
         return { channelName, isReady: readyTargetCount > 0, readyTargetCount };
@@ -205,20 +221,15 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
         isAvailable: placementAvailable,
         activeActorCount: populationCapacity?.actors.active ?? 0,
         activeSpotCount: populationCapacity?.spots.active ?? 0,
-        unavailableReason: placementAvailable
-          ? undefined
-          : localTopologyState !== ZLinkTopologyState.Ready
-            ? ZLinkTopologyReason.RuntimeNotReady
-            : !locationStoreHealthy
-              ? ZLinkTopologyReason.LocationUnavailable
-              : placementWeight <= 0
-                ? ZLinkTopologyReason.NoReadyTarget
-                : ZLinkTopologyReason.CapacityExceeded
+        unavailableReason: placementUnavailableReason(
+          placementAvailable,
+          hostState,
+          locationStoreHealthy
+        )
       },
-      sequence: drain.sequence > status.lastChangedMs ? drain.sequence : status.lastChangedMs,
+      sequence,
       observedAt: new Date()
     };
-    drain.lastSnapshot = snapshot;
     return snapshot;
   }
 
@@ -230,15 +241,15 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
     const state = this.requireState(meshName);
     if (!Number.isInteger(capacity) || capacity <= 0)
       throw new RangeError('Observer capacity must be positive.');
-    if (state.observers.size === 0) this.seedPlacementFingerprint(meshName);
+    const snapshot = this.snapshot(meshName);
     const queue = new RuntimeEventQueue<ZLinkRouteMeshStatus>(capacity, signal);
+    state.observers.add(queue);
+    this.startPlacementObserver();
     queue.onClose(() => {
       state.observers.delete(queue);
       this.stopPlacementObserverIfIdle();
     });
-    this.snapshot(meshName);
-    state.observers.add(queue);
-    this.startPlacementObserver();
+    this.publishStatus(meshName, queue, snapshot);
     return queue;
   }
 
@@ -247,78 +258,29 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
   }
 
   hostStateChanged(): void {
-    for (const [meshName, state] of this.states) {
-      state.sequence += 1n;
-      let snapshot: ZLinkRouteMeshStatus;
-      try {
-        snapshot = this.snapshot(meshName);
-      } catch {
-        continue;
-      }
-      for (const observer of state.observers) observer.push(snapshot, meshName);
-    }
+    for (const [meshName, state] of this.states) this.publishCurrentStatus(meshName, state);
   }
 
   stopObservers(): void {
     for (const [meshName, state] of this.states) {
-      state.sequence += 1n;
-      let terminal: ZLinkRouteMeshStatus | undefined;
-      try {
-        const current = this.snapshot(meshName);
-        const terminalSequence =
-          current.sequence >= state.sequence ? current.sequence + 1n : state.sequence;
-        state.sequence = terminalSequence;
-        terminal = {
-          ...current,
-          state: ZLinkTopologyState.Stopped,
-          isReady: false,
-          channels: current.channels.map((channel) => ({
-            ...channel,
-            isReady: false
-          })),
-          placement: {
-            ...current.placement,
-            isAvailable: false,
-            unavailableReason: ZLinkTopologyReason.RuntimeNotReady
-          },
-          sequence: terminalSequence,
-          observedAt: new Date()
-        };
-      } catch {
-        const current = state.lastSnapshot;
-        if (current !== undefined) {
-          const terminalSequence =
-            current.sequence >= state.sequence ? current.sequence + 1n : state.sequence;
-          state.sequence = terminalSequence;
-          terminal = {
-            ...current,
-            state: ZLinkTopologyState.Stopped,
-            isReady: false,
-            channels: current.channels.map((channel) => ({
-              ...channel,
-              isReady: false
-            })),
-            placement: {
-              ...current.placement,
-              isAvailable: false,
-              unavailableReason: ZLinkTopologyReason.RuntimeNotReady
-            },
-            sequence: terminalSequence,
-            observedAt: new Date()
-          };
-        }
-      }
-      for (const observer of [...state.observers]) {
-        if (terminal === undefined) observer.close();
-        else observer.seal(terminal, meshName);
+      const published = state.lastSnapshot;
+      if (published !== undefined && topologyObservationIsTerminal(published.state)) continue;
+      const current = published ?? this.publishCurrentStatus(meshName, state);
+      if (current === undefined) {
+        for (const observer of [...state.observers]) observer.close();
+      } else {
+        this.publishSnapshot(
+          meshName,
+          state,
+          terminalSnapshot(current, ZLinkTopologyState.Stopped)
+        );
       }
-      state.observers.clear();
     }
   }
 
   drain(
     meshName: string,
-    deadlineMs = 30_000,
+    deadlineMs: number = DEFAULT_ROUTE_MESH_DRAIN_TIMEOUT_MS,
     signal?: AbortSignal
   ): Promise<ZLinkMeshDrainResult> {
     const state = this.requireState(meshName);
@@ -339,7 +301,10 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
     return waitForOperation(operation, signal);
   }
 
-  drainHost(deadlineMs = 30_000, signal?: AbortSignal): Promise<ZLinkMeshDrainResult> {
+  drainHost(
+    deadlineMs: number = DEFAULT_ROUTE_MESH_DRAIN_TIMEOUT_MS,
+    signal?: AbortSignal
+  ): Promise<ZLinkMeshDrainResult> {
     if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
       return Promise.reject(new TypeError('Drain deadlineMs must be greater than zero.'));
     }
@@ -352,16 +317,12 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
     return waitForOperation(this.hostOperation, signal);
   }
 
-  shutdownHost(
-    deadline: number | Date = 30_000,
-    signal?: AbortSignal,
-    remainingTimeoutMs?: number
-  ): Promise<ZLinkMeshDrainResult> {
+  shutdownHost(deadline: number | Date, signal: AbortSignal): Promise<ZLinkMeshDrainResult> {
     if (typeof deadline === 'number' && (!Number.isFinite(deadline) || deadline <= 0)) {
       return Promise.reject(new TypeError('Shutdown deadlineMs must be greater than zero.'));
     }
     if (this.shutdownOperation === undefined) {
-      const operation = this.performHostShutdown(deadline, remainingTimeoutMs);
+      const operation = this.performHostShutdown(deadline, signal);
       this.shutdownOperation = operation;
       for (const state of this.states.values()) state.operation ??= operation;
     }
@@ -397,7 +358,7 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
           rollback.abort(
             createDeadlineExceededError('Retire descriptor rollback deadline exceeded.')
           ),
-        Math.min(deadlineMs, 1000)
+        Math.min(deadlineMs, MAX_ROUTE_MESH_OBSERVATION_WAIT_MS)
       );
       let rollbackFailed = false;
       for (const meshName of attempted.reverse()) {
@@ -444,7 +405,7 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
       return { kind: 'drained' };
     } catch (error) {
       const classified = drainFailureReason(error);
-      if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION === '1') {
+      if (isRelocationDebugEnabled()) {
         console.error('[zlink.runtime.relocation.drain_failed]', classified, error);
       }
       const reason: ZLinkDrainForceReason = deadline.signal.aborted
@@ -456,7 +417,7 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
           rollback.abort(
             createDeadlineExceededError('Relocation descriptor rollback deadline exceeded.')
           ),
-        Math.min(Math.max(1, deadlineMs), 1000)
+        Math.min(Math.max(1, deadlineMs), MAX_ROUTE_MESH_OBSERVATION_WAIT_MS)
       );
       try {
         await Promise.all(
@@ -585,25 +546,14 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
 
   private async performHostShutdown(
     cleanupDeadline: Date | number,
-    remainingTimeoutMs?: number
+    signal: AbortSignal
   ): Promise<ZLinkMeshDrainResult> {
-    const timeoutMs = Math.max(
-      0,
-      remainingTimeoutMs ??
-        (cleanupDeadline instanceof Date ? cleanupDeadline.getTime() - Date.now() : cleanupDeadline)
-    );
     const deadlineAt =
       cleanupDeadline instanceof Date ? cleanupDeadline : new Date(Date.now() + cleanupDeadline);
     const entries = [...this.states.entries()];
-    if (entries.length === 0) return { kind: 'drained' };
     for (const [, state] of entries) {
       state.deadline = deadlineAt;
     }
-    const deadline = new AbortController();
-    const timer = setTimeout(
-      () => deadline.abort(createDeadlineExceededError('Shutdown deadline exceeded.')),
-      timeoutMs
-    );
     let result: ZLinkMeshDrainResult;
     try {
       for (const [meshName, state] of entries) {
@@ -611,16 +561,16 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
         this.transition(meshName, state, ZLinkTopologyState.Stopping);
       }
       await Promise.all(
-        entries.map(([meshName]) => this.options.publishDraining(meshName, deadline.signal))
+        entries.map(([meshName]) => this.options.publishDraining(meshName, signal))
       );
-      await this.options.publishHostDraining(deadline.signal);
+      await this.options.publishHostDraining(signal);
       await Promise.all(
-        entries.map(([meshName]) => this.options.admission.awaitZero(meshName, deadline.signal))
+        entries.map(([meshName]) => this.options.admission.awaitZero(meshName, signal))
       );
       await Promise.all(
-        entries.map(([meshName]) => this.options.shutdownResources?.(meshName, deadline.signal))
+        entries.map(([meshName]) => this.options.shutdownResources?.(meshName, signal))
       );
-      await this.options.cleanupHostResources(deadline.signal);
+      await this.options.cleanupHostResources(signal);
       result = { kind: 'drained' };
       for (const [meshName, state] of entries) {
         this.transition(meshName, state, ZLinkTopologyState.Stopped);
@@ -630,7 +580,7 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
       const reason: ZLinkDrainForceReason =
         classified !== 'teardown_failed'
           ? classified
-          : deadline.signal.aborted
+          : signal.aborted
             ? 'deadline_exceeded'
             : classified;
       await Promise.all(
@@ -642,8 +592,6 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
       for (const [meshName, state] of entries) {
         this.transition(meshName, state, ZLinkTopologyState.Failed);
       }
-    } finally {
-      clearTimeout(timer);
     }
     for (const [, state] of entries) {
       state.result = result;
@@ -656,113 +604,83 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
   private transition(meshName: string, state: ZLinkMeshDrainState, next: ZLinkTopologyState): void {
     if (state.state === next) return;
     state.state = next;
-    state.sequence += 1n;
-    let current: ZLinkRouteMeshStatus | undefined;
-    let snapshotAvailable = false;
-    try {
-      current = this.snapshot(meshName);
-      snapshotAvailable = true;
-    } catch {
-      current = state.lastSnapshot;
-    }
-    const terminal = next === ZLinkTopologyState.Stopped || next === ZLinkTopologyState.Failed;
-    if (current !== undefined) {
-      if (terminal) {
-        const terminalSequence =
-          current.sequence >= state.sequence ? current.sequence + 1n : state.sequence;
-        state.sequence = terminalSequence;
-        const terminalStatus = {
-          ...current,
-          state: next,
-          isReady: false,
-          channels: current.channels.map((channel) => ({
-            ...channel,
-            isReady: false
-          })),
-          placement: {
-            ...current.placement,
-            isAvailable: false,
-            unavailableReason: ZLinkTopologyReason.RuntimeNotReady
-          },
-          sequence: terminalSequence,
-          observedAt: new Date()
-        };
-        for (const observer of state.observers) observer.seal(terminalStatus, meshName);
-      } else if (snapshotAvailable) {
-        for (const observer of state.observers) observer.push(current, meshName);
-      }
-    }
-    if (terminal) {
-      if (current === undefined) {
-        for (const observer of state.observers) observer.close();
-      }
-      state.observers.clear();
-      this.stopPlacementObserverIfIdle();
+    const published = this.publishCurrentStatus(meshName, state);
+    if (topologyObservationIsTerminal(next) && published === undefined) {
+      for (const observer of [...state.observers]) observer.close();
     }
   }
 
-  private seedPlacementFingerprint(meshName: string): void {
-    this.locationStoreHealthFingerprints.set(
-      meshName,
-      this.options.isLocationStoreHealthy?.() ?? true
-    );
-    const descriptor = this.options.meshNodeDescriptor?.(meshName);
-    if (descriptor !== undefined) {
-      this.placementFingerprints.set(meshName, placementFingerprint(descriptor));
+  private publishCurrentStatus(
+    meshName: string,
+    state: ZLinkMeshDrainState
+  ): ZLinkRouteMeshStatus | undefined {
+    const published = state.lastSnapshot;
+    if (published !== undefined && topologyObservationIsTerminal(published.state)) return published;
+    const desired = topologyObservationIsTerminal(state.state)
+      ? state.state
+      : topologyStateForHost(
+          this.options.hostState?.() ?? ZLinkFrameworkRuntimeState.Serving,
+          state.state
+        );
+    if (published !== undefined && topologyObservationIsTerminal(desired)) {
+      return this.publishSnapshot(meshName, state, terminalSnapshot(published, desired));
     }
-    this.peerFingerprints.set(
+    if (this.options.meshNode(meshName) === undefined) return undefined;
+    const current = this.buildSnapshot(meshName, published?.sequence ?? 0n);
+    return this.publishSnapshot(
       meshName,
-      peerFingerprintMap(this.options.meshNode(meshName)?.peers() ?? [])
+      state,
+      topologyObservationIsTerminal(current.state)
+        ? terminalSnapshot(current, current.state)
+        : current
     );
   }
 
+  private publishSnapshot(
+    meshName: string,
+    state: ZLinkMeshDrainState,
+    current: ZLinkRouteMeshStatus
+  ): ZLinkRouteMeshStatus {
+    const published = state.lastSnapshot;
+    if (published !== undefined && samePublicRouteMeshStatus(published, current)) return published;
+    const next = { ...current, sequence: (published?.sequence ?? 0n) + 1n, observedAt: new Date() };
+    state.lastSnapshot = next;
+    for (const observer of [...state.observers]) this.publishStatus(meshName, observer, next);
+    return next;
+  }
+
+  private publishStatus(
+    meshName: string,
+    observer: RuntimeEventQueue<ZLinkRouteMeshStatus>,
+    status: ZLinkRouteMeshStatus
+  ): void {
+    if (topologyObservationIsTerminal(status.state)) {
+      observer.seal(status, meshName);
+    } else {
+      observer.push(status, meshName);
+    }
+  }
+
   private startPlacementObserver(): void {
     if (this.placementObserver !== undefined) return;
-    this.placementObserver = setInterval(() => this.observePlacementChanges(), 100);
+    this.placementObserver = setInterval(
+      () => this.observePlacementChanges(),
+      PLACEMENT_OBSERVATION_INTERVAL_MS
+    );
     this.placementObserver.unref();
   }
 
   private stopPlacementObserverIfIdle(): void {
-    if ([...this.states.values()].some((state) => state.observers.size > 0)) return;
+    for (const state of this.states.values()) {
+      if (state.observers.size > 0) return;
+    }
     if (this.placementObserver !== undefined) clearInterval(this.placementObserver);
     this.placementObserver = undefined;
   }
 
   private observePlacementChanges(): void {
     for (const [meshName, state] of this.states) {
-      if (state.observers.size === 0) continue;
-      const locationStoreHealthy = this.options.isLocationStoreHealthy?.() ?? true;
-      if (locationStoreHealthy !== this.locationStoreHealthFingerprints.get(meshName)) {
-        this.locationStoreHealthFingerprints.set(meshName, locationStoreHealthy);
-        state.sequence += 1n;
-        for (const observer of state.observers) {
-          observer.push(this.snapshot(meshName), meshName);
-        }
-      }
-      const descriptor = this.options.meshNodeDescriptor?.(meshName);
-      if (descriptor === undefined) continue;
-      const fingerprint = placementFingerprint(descriptor);
-      const previous = this.placementFingerprints.get(meshName);
-      this.placementFingerprints.set(meshName, fingerprint);
-      const node = this.options.meshNode(meshName);
-      if (previous !== undefined && previous !== fingerprint) {
-        state.sequence += 1n;
-        for (const observer of state.observers) {
-          observer.push(this.snapshot(meshName), meshName);
-        }
-      }
-
-      const previousPeers = this.peerFingerprints.get(meshName) ?? new Map();
-      const peers = node?.peers() ?? [];
-      const nextPeers = peerFingerprintMap(peers);
-      this.peerFingerprints.set(meshName, nextPeers);
-      for (const peerRid of new Set([...previousPeers.keys(), ...nextPeers.keys()])) {
-        if (previousPeers.get(peerRid) === nextPeers.get(peerRid)) continue;
-        state.sequence += 1n;
-        for (const observer of state.observers) {
-          observer.push(this.snapshot(meshName), meshName);
-        }
-      }
+      this.publishCurrentStatus(meshName, state);
     }
   }
 
@@ -773,6 +691,77 @@ export class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
   }
 }
 
+function terminalSnapshot(
+  current: ZLinkRouteMeshStatus,
+  state: ZLinkTopologyState
+): ZLinkRouteMeshStatus {
+  return {
+    ...current,
+    state,
+    isReady: false,
+    channels: current.channels.map((channel) => ({ ...channel, isReady: false })),
+    placement: {
+      ...current.placement,
+      isAvailable: false,
+      unavailableReason: ZLinkTopologyReason.RuntimeNotReady
+    }
+  };
+}
+
+function samePublicRouteMeshStatus(
+  left: ZLinkRouteMeshStatus,
+  right: ZLinkRouteMeshStatus
+): boolean {
+  return (
+    left.meshName === right.meshName &&
+    left.state === right.state &&
+    left.isReady === right.isReady &&
+    left.readyPeerCount === right.readyPeerCount &&
+    left.placement.isAvailable === right.placement.isAvailable &&
+    left.placement.activeActorCount === right.placement.activeActorCount &&
+    left.placement.activeSpotCount === right.placement.activeSpotCount &&
+    left.placement.unavailableReason === right.placement.unavailableReason &&
+    left.channels.length === right.channels.length &&
+    left.channels.every((channel, index) => {
+      const other = right.channels[index]!;
+      return (
+        channel.channelName === other.channelName &&
+        channel.isReady === other.isReady &&
+        channel.readyTargetCount === other.readyTargetCount
+      );
+    }) &&
+    left.peers.length === right.peers.length &&
+    left.peers.every((peer, index) => {
+      const other = right.peers[index]!;
+      return (
+        peer.nodeRid === other.nodeRid &&
+        peer.state === other.state &&
+        peer.unavailableReason === other.unavailableReason
+      );
+    })
+  );
+}
+
+function placementUnavailableReason(
+  available: boolean,
+  hostState: ZLinkFrameworkRuntimeState,
+  locationStoreHealthy: boolean
+): ZLinkTopologyReason | undefined {
+  if (available) return undefined;
+  switch (hostState) {
+    case ZLinkFrameworkRuntimeState.Relocating:
+    case ZLinkFrameworkRuntimeState.Relocated:
+    case ZLinkFrameworkRuntimeState.Draining:
+      return ZLinkTopologyReason.Draining;
+    case ZLinkFrameworkRuntimeState.Serving:
+      return !locationStoreHealthy
+        ? ZLinkTopologyReason.LocationUnavailable
+        : ZLinkTopologyReason.CapacityExceeded;
+    default:
+      return ZLinkTopologyReason.RuntimeNotReady;
+  }
+}
+
 function topologyStateForHost(
   state: ZLinkFrameworkRuntimeState,
   fallback: ZLinkTopologyState
@@ -793,30 +782,6 @@ function topologyStateForHost(
   }
 }
 
-function placementFingerprint(descriptor: ZLinkMeshNodeDescriptor): string {
-  const spotTypes = [...descriptor.populationCapacity.spotTypes]
-    .sort((left, right) => {
-      const kind = left.objectKind.localeCompare(right.objectKind);
-      return kind !== 0 ? kind : left.stableType.localeCompare(right.stableType);
-    })
-    .map((entry) => [
-      entry.objectKind,
-      entry.stableType,
-      entry.active,
-      entry.reserved,
-      entry.limit
-    ]);
-  return JSON.stringify([
-    descriptor.objectRole,
-    descriptor.placementWeight,
-    descriptor.populationCapacity.actors,
-    descriptor.populationCapacity.spots,
-    spotTypes,
-    descriptor.activationConcurrency,
-    Object.entries(descriptor.channelWeights).sort(([left], [right]) => left.localeCompare(right))
-  ]);
-}
-
 function hasRemainingCapacity(capacity: {
   readonly active: number;
   readonly limit: number;
@@ -825,19 +790,11 @@ function hasRemainingCapacity(capacity: {
   return capacity.limit === 0 || capacity.active + (capacity.reserved ?? 0) < capacity.limit;
 }
 
-function peerFingerprintMap(peers: ReturnType<ZLinkBackendMeshNode['peers']>): Map<string, string> {
-  return new Map(
-    peers.map((peer) => [
-      String(peer.routingId),
-      JSON.stringify([
-        peer.lifecycleGeneration.toString(),
-        peer.descriptorRevision.toString(),
-        peer.endpoint,
-        peer.state,
-        peer.lastError
-      ])
-    ])
-  );
+export class ZLinkDrainingStatePublishError extends Error {
+  constructor(cause: unknown) {
+    super('Failed to publish draining peer rows.', { cause });
+    this.name = 'ZLinkDrainingStatePublishError';
+  }
 }
 
 export class ZLinkRetiringRollbackError extends Error {
@@ -861,33 +818,32 @@ function multiMeshDrainError(): ZLinkFrameworkException {
   );
 }
 
-function backendState(state: number): ZLinkTopologyState {
+function backendState(state: MeshNodeRuntimeState): ZLinkTopologyState {
   switch (state) {
-    case 1:
+    case MeshNodeRuntimeState.Preparing:
       return ZLinkTopologyState.Starting;
-    case 2:
-    case 3:
-    case 4:
+    case MeshNodeRuntimeState.Serving:
       return ZLinkTopologyState.Ready;
-    case 5:
+    case MeshNodeRuntimeState.Retiring:
+    case MeshNodeRuntimeState.Draining:
       return ZLinkTopologyState.Stopping;
-    case 6:
+    case MeshNodeRuntimeState.Stopped:
       return ZLinkTopologyState.Stopped;
     default:
       return ZLinkTopologyState.Failed;
   }
 }
 
-function peerState(state: number): ZLinkPeerState {
+function peerState(state: MeshPeerRuntimeState): ZLinkPeerState {
   switch (state) {
-    case 3:
+    case MeshPeerRuntimeState.Serving:
       return ZLinkPeerState.Ready;
-    case 4:
+    case MeshPeerRuntimeState.Draining:
       return ZLinkPeerState.Draining;
-    case 6:
+    case MeshPeerRuntimeState.NotRequired:
       return ZLinkPeerState.NotRequired;
-    case 1:
-    case 2:
+    case MeshPeerRuntimeState.Connecting:
+    case MeshPeerRuntimeState.Preparing:
       return ZLinkPeerState.Connecting;
     default:
       return ZLinkPeerState.NotConnected;
@@ -907,14 +863,15 @@ function peerUnavailableReason(state: ZLinkPeerState): ZLinkTopologyReason | und
 }
 
 function drainFailureReason(error: unknown): ZLinkDrainForceReason {
-  const name = error instanceof Error ? error.name : '';
-  if (name === 'ZLinkDrainingStatePublishError') return 'drain_state_publish_failed';
+  if (isStructuralGuardEnabled()) {
+    const pending = debugPendingWorkNames();
+    if (pending.length > 0) console.error('[zlink.runtime.drain.pending]', pending);
+  }
+  if (error instanceof ZLinkDrainingStatePublishError) return 'drain_state_publish_failed';
   if (
-    name === 'ZLinkOwnerCleanupError' ||
+    error instanceof ZLinkOwnerCleanupError ||
     (error instanceof AggregateError &&
-      error.errors.some(
-        (nested) => nested instanceof Error && nested.name === 'ZLinkOwnerCleanupError'
-      ))
+      error.errors.some((nested) => nested instanceof ZLinkOwnerCleanupError))
   ) {
     return 'owner_cleanup_failed';
   }