@zlink-systems/framework 0.26.0 → 0.27.0

package/dist/runtime/host/route-mesh-runtime.js

@@ -1,18 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkRetiringRollbackError = exports.ZLinkRouteMeshRuntimeCoordinator = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
+exports.ZLinkRetiringRollbackError = exports.ZLinkDrainingStatePublishError = exports.ZLinkRouteMeshRuntimeCoordinator = void 0;
 const contracts_1 = require("../../contracts");
-const runtime_observation_queue_1 = require("../diagnostics/runtime-observation-queue");
+const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
 const abort_1 = require("../abort");
+const diagnostics_1 = require("../diagnostics");
+const runtime_observation_queue_1 = require("../diagnostics/runtime-observation-queue");
+const state_lane_1 = require("../execution/state-lane");
 const runtime_state_projections_1 = require("../foundation/runtime-state-projections");
-const contracts_2 = require("../../contracts");
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const runtime_1 = require("../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;
 class ZLinkRouteMeshRuntimeCoordinator {
     options;
     states = new Map();
-    placementFingerprints = new Map();
-    peerFingerprints = new Map();
-    locationStoreHealthFingerprints = new Map();
     placementObserver;
     hostOperation;
     shutdownOperation;
@@ -23,7 +27,6 @@ class ZLinkRouteMeshRuntimeCoordinator {
             options.admission.register(meshName);
             this.states.set(meshName, {
                 state: contracts_1.ZLinkTopologyState.Starting,
-                sequence: 0n,
                 waiters: [],
                 observers: new Set()
             });
@@ -37,6 +40,12 @@ class ZLinkRouteMeshRuntimeCoordinator {
         }
     }
     snapshot(meshName) {
+        const published = this.publishCurrentStatus(meshName, this.requireState(meshName));
+        if (published === undefined)
+            throw routeNotFound(meshName);
+        return published;
+    }
+    buildSnapshot(meshName, sequence) {
         const drain = this.requireState(meshName);
         const node = this.options.meshNode(meshName);
         if (node === undefined)
@@ -74,7 +83,7 @@ class ZLinkRouteMeshRuntimeCoordinator {
         const channels = Object.entries(this.options.meshOptions.get(meshName)?.meshChannels ?? {}).map(([channelName, channel]) => {
             const readyMemberCount = BigInt(peerChannels.filter((entry, index) => peers[index]?.state === contracts_1.ZLinkPeerState.Ready &&
                 entry.names.some((name, channelIndex) => name === channelName && (entry.weights[channelIndex] ?? 0) > 0)).length);
-            const localWeight = descriptor?.channelWeights[channelName] ?? channel.weight ?? 100;
+            const localWeight = descriptor?.channelWeights[channelName] ?? channel.weight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT;
             const readyTargetCount = Number(readyMemberCount) + (channel.server === true && localWeight > 0 ? 1 : 0);
             return { channelName, isReady: readyTargetCount > 0, readyTargetCount };
         });
@@ -89,14 +98,14 @@ class ZLinkRouteMeshRuntimeCoordinator {
             ? contracts_1.ZLinkTopologyState.Degraded
             : hostTopologyState;
         const hostReady = (0, runtime_state_projections_1.runtimeStateIsReady)(hostState);
-        const objectRole = descriptor?.objectRole ?? contracts_2.ZLinkObjectRole.None;
+        const objectRole = descriptor?.objectRole ?? contracts_1.ZLinkObjectRole.None;
         const placementWeight = descriptor?.placementWeight ?? 0;
         const capacityAvailable = descriptor !== undefined &&
             populationCapacity !== undefined &&
             (this.options.activationAdmission?.hasHeadroom(meshName) ?? true) &&
             (hasRemainingCapacity(populationCapacity.actors) ||
                 hasRemainingCapacity(populationCapacity.spots));
-        const placementAvailable = objectRole === contracts_2.ZLinkObjectRole.Server &&
+        const placementAvailable = objectRole === contracts_1.ZLinkObjectRole.Server &&
             placementWeight > 0 &&
             capacityAvailable &&
             locationStoreHealthy &&
@@ -113,113 +122,51 @@ class ZLinkRouteMeshRuntimeCoordinator {
                 isAvailable: placementAvailable,
                 activeActorCount: populationCapacity?.actors.active ?? 0,
                 activeSpotCount: populationCapacity?.spots.active ?? 0,
-                unavailableReason: placementAvailable
-                    ? undefined
-                    : localTopologyState !== contracts_1.ZLinkTopologyState.Ready
-                        ? contracts_1.ZLinkTopologyReason.RuntimeNotReady
-                        : !locationStoreHealthy
-                            ? contracts_1.ZLinkTopologyReason.LocationUnavailable
-                            : placementWeight <= 0
-                                ? contracts_1.ZLinkTopologyReason.NoReadyTarget
-                                : contracts_1.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;
     }
     observe(meshName, capacity = runtime_observation_queue_1.ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY, signal) {
         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 runtime_observation_queue_1.RuntimeEventQueue(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;
     }
     isReady(meshName) {
         return this.snapshot(meshName).isReady;
     }
     hostStateChanged() {
-        for (const [meshName, state] of this.states) {
-            state.sequence += 1n;
-            let snapshot;
-            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() {
         for (const [meshName, state] of this.states) {
-            state.sequence += 1n;
-            let terminal;
-            try {
-                const current = this.snapshot(meshName);
-                const terminalSequence = current.sequence >= state.sequence ? current.sequence + 1n : state.sequence;
-                state.sequence = terminalSequence;
-                terminal = {
-                    ...current,
-                    state: contracts_1.ZLinkTopologyState.Stopped,
-                    isReady: false,
-                    channels: current.channels.map((channel) => ({
-                        ...channel,
-                        isReady: false
-                    })),
-                    placement: {
-                        ...current.placement,
-                        isAvailable: false,
-                        unavailableReason: contracts_1.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: contracts_1.ZLinkTopologyState.Stopped,
-                        isReady: false,
-                        channels: current.channels.map((channel) => ({
-                            ...channel,
-                            isReady: false
-                        })),
-                        placement: {
-                            ...current.placement,
-                            isAvailable: false,
-                            unavailableReason: contracts_1.ZLinkTopologyReason.RuntimeNotReady
-                        },
-                        sequence: terminalSequence,
-                        observedAt: new Date()
-                    };
-                }
-            }
-            for (const observer of [...state.observers]) {
-                if (terminal === undefined)
+            const published = state.lastSnapshot;
+            if (published !== undefined && (0, runtime_state_projections_1.topologyObservationIsTerminal)(published.state))
+                continue;
+            const current = published ?? this.publishCurrentStatus(meshName, state);
+            if (current === undefined) {
+                for (const observer of [...state.observers])
                     observer.close();
-                else
-                    observer.seal(terminal, meshName);
             }
-            state.observers.clear();
+            else {
+                this.publishSnapshot(meshName, state, terminalSnapshot(current, contracts_1.ZLinkTopologyState.Stopped));
+            }
         }
     }
-    drain(meshName, deadlineMs = 30_000, signal) {
+    drain(meshName, deadlineMs = DEFAULT_ROUTE_MESH_DRAIN_TIMEOUT_MS, signal) {
         const state = this.requireState(meshName);
         if (this.states.size > 1)
             return Promise.reject(multiMeshDrainError());
@@ -237,7 +184,7 @@ class ZLinkRouteMeshRuntimeCoordinator {
             new Promise((resolve) => state.waiters.push(resolve));
         return waitForOperation(operation, signal);
     }
-    drainHost(deadlineMs = 30_000, signal) {
+    drainHost(deadlineMs = DEFAULT_ROUTE_MESH_DRAIN_TIMEOUT_MS, signal) {
         if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
             return Promise.reject(new TypeError('Drain deadlineMs must be greater than zero.'));
         }
@@ -250,12 +197,12 @@ class ZLinkRouteMeshRuntimeCoordinator {
         }
         return waitForOperation(this.hostOperation, signal);
     }
-    shutdownHost(deadline = 30_000, signal, remainingTimeoutMs) {
+    shutdownHost(deadline, signal) {
         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;
@@ -280,7 +227,7 @@ class ZLinkRouteMeshRuntimeCoordinator {
             // A failed response can still follow a committed Store write. Restore
             // every attempted descriptor before the host reports a reversible block.
             const rollback = new AbortController();
-            const rollbackTimer = setTimeout(() => rollback.abort((0, abort_1.createDeadlineExceededError)('Retire descriptor rollback deadline exceeded.')), Math.min(deadlineMs, 1000));
+            const rollbackTimer = setTimeout(() => rollback.abort((0, abort_1.createDeadlineExceededError)('Retire descriptor rollback deadline exceeded.')), Math.min(deadlineMs, MAX_ROUTE_MESH_OBSERVATION_WAIT_MS));
             let rollbackFailed = false;
             for (const meshName of attempted.reverse()) {
                 try {
@@ -318,14 +265,14 @@ class ZLinkRouteMeshRuntimeCoordinator {
         }
         catch (error) {
             const classified = drainFailureReason(error);
-            if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION === '1') {
+            if ((0, diagnostics_1.isRelocationDebugEnabled)()) {
                 console.error('[zlink.runtime.relocation.drain_failed]', classified, error);
             }
             const reason = deadline.signal.aborted
                 ? 'deadline_exceeded'
                 : classified;
             const rollback = new AbortController();
-            const rollbackTimer = setTimeout(() => rollback.abort((0, abort_1.createDeadlineExceededError)('Relocation descriptor rollback deadline exceeded.')), Math.min(Math.max(1, deadlineMs), 1000));
+            const rollbackTimer = setTimeout(() => rollback.abort((0, abort_1.createDeadlineExceededError)('Relocation descriptor rollback deadline exceeded.')), Math.min(Math.max(1, deadlineMs), MAX_ROUTE_MESH_OBSERVATION_WAIT_MS));
             try {
                 await Promise.all(entries.map(([meshName]) => this.options.rollbackRetiring(meshName, rollback.signal)));
             }
@@ -432,29 +379,23 @@ class ZLinkRouteMeshRuntimeCoordinator {
         }
         return result;
     }
-    async performHostShutdown(cleanupDeadline, remainingTimeoutMs) {
-        const timeoutMs = Math.max(0, remainingTimeoutMs ??
-            (cleanupDeadline instanceof Date ? cleanupDeadline.getTime() - Date.now() : cleanupDeadline));
+    async performHostShutdown(cleanupDeadline, signal) {
         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((0, abort_1.createDeadlineExceededError)('Shutdown deadline exceeded.')), timeoutMs);
         let result;
         try {
             for (const [meshName, state] of entries) {
                 this.options.admission.seal(meshName, framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown);
                 this.transition(meshName, state, contracts_1.ZLinkTopologyState.Stopping);
             }
-            await Promise.all(entries.map(([meshName]) => this.options.publishDraining(meshName, deadline.signal)));
-            await this.options.publishHostDraining(deadline.signal);
-            await Promise.all(entries.map(([meshName]) => this.options.admission.awaitZero(meshName, deadline.signal)));
-            await Promise.all(entries.map(([meshName]) => this.options.shutdownResources?.(meshName, deadline.signal)));
-            await this.options.cleanupHostResources(deadline.signal);
+            await Promise.all(entries.map(([meshName]) => this.options.publishDraining(meshName, signal)));
+            await this.options.publishHostDraining(signal);
+            await Promise.all(entries.map(([meshName]) => this.options.admission.awaitZero(meshName, signal)));
+            await Promise.all(entries.map(([meshName]) => this.options.shutdownResources?.(meshName, signal)));
+            await this.options.cleanupHostResources(signal);
             result = { kind: 'drained' };
             for (const [meshName, state] of entries) {
                 this.transition(meshName, state, contracts_1.ZLinkTopologyState.Stopped);
@@ -464,7 +405,7 @@ class ZLinkRouteMeshRuntimeCoordinator {
             const classified = drainFailureReason(error);
             const reason = classified !== 'teardown_failed'
                 ? classified
-                : deadline.signal.aborted
+                : signal.aborted
                     ? 'deadline_exceeded'
                     : classified;
             await Promise.all(entries.map(([meshName]) => this.options.forceStopResources(meshName).catch(() => undefined)));
@@ -473,9 +414,6 @@ class ZLinkRouteMeshRuntimeCoordinator {
                 this.transition(meshName, state, contracts_1.ZLinkTopologyState.Failed);
             }
         }
-        finally {
-            clearTimeout(timer);
-        }
         for (const [, state] of entries) {
             state.result = result;
             for (const resolve of state.waiters)
@@ -488,112 +426,65 @@ class ZLinkRouteMeshRuntimeCoordinator {
         if (state.state === next)
             return;
         state.state = next;
-        state.sequence += 1n;
-        let current;
-        let snapshotAvailable = false;
-        try {
-            current = this.snapshot(meshName);
-            snapshotAvailable = true;
-        }
-        catch {
-            current = state.lastSnapshot;
-        }
-        const terminal = next === contracts_1.ZLinkTopologyState.Stopped || next === contracts_1.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: contracts_1.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 ((0, runtime_state_projections_1.topologyObservationIsTerminal)(next) && published === undefined) {
+            for (const observer of [...state.observers])
+                observer.close();
         }
     }
-    seedPlacementFingerprint(meshName) {
-        this.locationStoreHealthFingerprints.set(meshName, this.options.isLocationStoreHealthy?.() ?? true);
-        const descriptor = this.options.meshNodeDescriptor?.(meshName);
-        if (descriptor !== undefined) {
-            this.placementFingerprints.set(meshName, placementFingerprint(descriptor));
+    publishCurrentStatus(meshName, state) {
+        const published = state.lastSnapshot;
+        if (published !== undefined && (0, runtime_state_projections_1.topologyObservationIsTerminal)(published.state))
+            return published;
+        const desired = (0, runtime_state_projections_1.topologyObservationIsTerminal)(state.state)
+            ? state.state
+            : topologyStateForHost(this.options.hostState?.() ?? contracts_1.ZLinkFrameworkRuntimeState.Serving, state.state);
+        if (published !== undefined && (0, runtime_state_projections_1.topologyObservationIsTerminal)(desired)) {
+            return this.publishSnapshot(meshName, state, terminalSnapshot(published, desired));
+        }
+        if (this.options.meshNode(meshName) === undefined)
+            return undefined;
+        const current = this.buildSnapshot(meshName, published?.sequence ?? 0n);
+        return this.publishSnapshot(meshName, state, (0, runtime_state_projections_1.topologyObservationIsTerminal)(current.state)
+            ? terminalSnapshot(current, current.state)
+            : current);
+    }
+    publishSnapshot(meshName, state, current) {
+        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;
+    }
+    publishStatus(meshName, observer, status) {
+        if ((0, runtime_state_projections_1.topologyObservationIsTerminal)(status.state)) {
+            observer.seal(status, meshName);
+        }
+        else {
+            observer.push(status, meshName);
         }
-        this.peerFingerprints.set(meshName, peerFingerprintMap(this.options.meshNode(meshName)?.peers() ?? []));
     }
     startPlacementObserver() {
         if (this.placementObserver !== undefined)
             return;
-        this.placementObserver = setInterval(() => this.observePlacementChanges(), 100);
+        this.placementObserver = setInterval(() => this.observePlacementChanges(), PLACEMENT_OBSERVATION_INTERVAL_MS);
         this.placementObserver.unref();
     }
     stopPlacementObserverIfIdle() {
-        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;
     }
     observePlacementChanges() {
         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);
         }
     }
     requireState(meshName) {
@@ -604,6 +495,59 @@ class ZLinkRouteMeshRuntimeCoordinator {
     }
 }
 exports.ZLinkRouteMeshRuntimeCoordinator = ZLinkRouteMeshRuntimeCoordinator;
+function terminalSnapshot(current, state) {
+    return {
+        ...current,
+        state,
+        isReady: false,
+        channels: current.channels.map((channel) => ({ ...channel, isReady: false })),
+        placement: {
+            ...current.placement,
+            isAvailable: false,
+            unavailableReason: contracts_1.ZLinkTopologyReason.RuntimeNotReady
+        }
+    };
+}
+function samePublicRouteMeshStatus(left, right) {
+    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, hostState, locationStoreHealthy) {
+    if (available)
+        return undefined;
+    switch (hostState) {
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocating:
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocated:
+        case contracts_1.ZLinkFrameworkRuntimeState.Draining:
+            return contracts_1.ZLinkTopologyReason.Draining;
+        case contracts_1.ZLinkFrameworkRuntimeState.Serving:
+            return !locationStoreHealthy
+                ? contracts_1.ZLinkTopologyReason.LocationUnavailable
+                : contracts_1.ZLinkTopologyReason.CapacityExceeded;
+        default:
+            return contracts_1.ZLinkTopologyReason.RuntimeNotReady;
+    }
+}
 function topologyStateForHost(state, fallback) {
     switch (state) {
         case contracts_1.ZLinkFrameworkRuntimeState.Serving:
@@ -620,44 +564,16 @@ function topologyStateForHost(state, fallback) {
             return contracts_1.ZLinkTopologyState.Failed;
     }
 }
-function placementFingerprint(descriptor) {
-    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) {
     return capacity.limit === 0 || capacity.active + (capacity.reserved ?? 0) < capacity.limit;
 }
-function peerFingerprintMap(peers) {
-    return new Map(peers.map((peer) => [
-        String(peer.routingId),
-        JSON.stringify([
-            peer.lifecycleGeneration.toString(),
-            peer.descriptorRevision.toString(),
-            peer.endpoint,
-            peer.state,
-            peer.lastError
-        ])
-    ]));
+class ZLinkDrainingStatePublishError extends Error {
+    constructor(cause) {
+        super('Failed to publish draining peer rows.', { cause });
+        this.name = 'ZLinkDrainingStatePublishError';
+    }
 }
+exports.ZLinkDrainingStatePublishError = ZLinkDrainingStatePublishError;
 class ZLinkRetiringRollbackError extends Error {
     constructor() {
         super('Retiring descriptor publication could not be rolled back to Serving.');
@@ -673,15 +589,14 @@ function multiMeshDrainError() {
 }
 function backendState(state) {
     switch (state) {
-        case 1:
+        case service_runtime_contracts_1.MeshNodeRuntimeState.Preparing:
             return contracts_1.ZLinkTopologyState.Starting;
-        case 2:
-        case 3:
-        case 4:
+        case service_runtime_contracts_1.MeshNodeRuntimeState.Serving:
             return contracts_1.ZLinkTopologyState.Ready;
-        case 5:
+        case service_runtime_contracts_1.MeshNodeRuntimeState.Retiring:
+        case service_runtime_contracts_1.MeshNodeRuntimeState.Draining:
             return contracts_1.ZLinkTopologyState.Stopping;
-        case 6:
+        case service_runtime_contracts_1.MeshNodeRuntimeState.Stopped:
             return contracts_1.ZLinkTopologyState.Stopped;
         default:
             return contracts_1.ZLinkTopologyState.Failed;
@@ -689,14 +604,14 @@ function backendState(state) {
 }
 function peerState(state) {
     switch (state) {
-        case 3:
+        case service_runtime_contracts_1.MeshPeerRuntimeState.Serving:
             return contracts_1.ZLinkPeerState.Ready;
-        case 4:
+        case service_runtime_contracts_1.MeshPeerRuntimeState.Draining:
             return contracts_1.ZLinkPeerState.Draining;
-        case 6:
+        case service_runtime_contracts_1.MeshPeerRuntimeState.NotRequired:
             return contracts_1.ZLinkPeerState.NotRequired;
-        case 1:
-        case 2:
+        case service_runtime_contracts_1.MeshPeerRuntimeState.Connecting:
+        case service_runtime_contracts_1.MeshPeerRuntimeState.Preparing:
             return contracts_1.ZLinkPeerState.Connecting;
         default:
             return contracts_1.ZLinkPeerState.NotConnected;
@@ -714,12 +629,16 @@ function peerUnavailableReason(state) {
     }
 }
 function drainFailureReason(error) {
-    const name = error instanceof Error ? error.name : '';
-    if (name === 'ZLinkDrainingStatePublishError')
+    if ((0, state_lane_1.isStructuralGuardEnabled)()) {
+        const pending = (0, state_lane_1.debugPendingWorkNames)();
+        if (pending.length > 0)
+            console.error('[zlink.runtime.drain.pending]', pending);
+    }
+    if (error instanceof ZLinkDrainingStatePublishError)
         return 'drain_state_publish_failed';
-    if (name === 'ZLinkOwnerCleanupError' ||
+    if (error instanceof runtime_1.ZLinkOwnerCleanupError ||
         (error instanceof AggregateError &&
-            error.errors.some((nested) => nested instanceof Error && nested.name === 'ZLinkOwnerCleanupError'))) {
+            error.errors.some((nested) => nested instanceof runtime_1.ZLinkOwnerCleanupError))) {
         return 'owner_cleanup_failed';
     }
     return 'teardown_failed';

package/dist/runtime/host/runtime-shutdown.d.ts

@@ -15,10 +15,12 @@ export interface ZLinkRuntimeStartRollbackParts {
     readonly spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;
     readonly channelRuntime?: ZLinkChannelRuntimeManager;
     readonly ownedStores?: readonly ZLinkRuntimeOwnedStore[];
+    readonly shutdownSignal?: AbortSignal;
 }
 export interface ZLinkRuntimeStopParts {
     readonly state: ZLinkFrameworkExecutionState;
     readonly cleanupDeadline?: Date;
+    readonly shutdownSignal?: AbortSignal;
     readonly locationSnapshot: ZLinkLocationRuntimeStopSnapshot;
     readonly streamRuntime?: ZLinkStreamRuntimeManager;
     readonly spotNodeRuntime?: ZLinkSpotNodeRuntimeManager;