@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,746 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRetiringRollbackError = exports.ZLinkRouteMeshRuntimeCoordinator = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const runtime_observation_queue_1 = require("../diagnostics/runtime-observation-queue");
+const abort_1 = require("../abort");
+const runtime_state_projections_1 = require("../foundation/runtime-state-projections");
+const contracts_2 = require("../../contracts");
+class ZLinkRouteMeshRuntimeCoordinator {
+    options;
+    states = new Map();
+    placementFingerprints = new Map();
+    peerFingerprints = new Map();
+    locationStoreHealthFingerprints = new Map();
+    placementObserver;
+    hostOperation;
+    shutdownOperation;
+    hostRetiringPrepared = false;
+    constructor(options) {
+        this.options = options;
+        for (const meshName of options.meshNames) {
+            options.admission.register(meshName);
+            this.states.set(meshName, {
+                state: contracts_1.ZLinkTopologyState.Starting,
+                sequence: 0n,
+                waiters: [],
+                observers: new Set()
+            });
+        }
+    }
+    markServing() {
+        for (const [meshName, state] of this.states) {
+            if (state.state !== contracts_1.ZLinkTopologyState.Starting)
+                continue;
+            this.transition(meshName, state, contracts_1.ZLinkTopologyState.Ready);
+        }
+    }
+    snapshot(meshName) {
+        const drain = this.requireState(meshName);
+        const node = this.options.meshNode(meshName);
+        if (node === undefined)
+            throw routeNotFound(meshName);
+        const status = node.status();
+        const descriptor = this.options.meshNodeDescriptor?.(meshName);
+        const localPlacementCounts = this.options.localPlacementCounts?.(meshName);
+        const populationCapacity = descriptor === undefined || localPlacementCounts === undefined
+            ? descriptor?.populationCapacity
+            : {
+                ...descriptor.populationCapacity,
+                actors: {
+                    ...descriptor.populationCapacity.actors,
+                    active: localPlacementCounts.activeActorCount
+                },
+                spots: {
+                    ...descriptor.populationCapacity.spots,
+                    active: localPlacementCounts.activeSpotCount
+                }
+            };
+        const backendPeers = node.peers();
+        const peerChannels = backendPeers.map((peer) => peer.routingId === null
+            ? { names: [], weights: [] }
+            : node.peerChannels(peer.routingId, peer.lifecycleGeneration));
+        const peers = backendPeers.map((peer) => {
+            const state = peerState(peer.state);
+            return {
+                nodeRid: (peer.routingId === null ? '' : String(peer.routingId)),
+                state,
+                unavailableReason: peerUnavailableReason(state)
+            };
+        });
+        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 readyTargetCount = Number(readyMemberCount)
+                + (channel.server === true && localWeight > 0 ? 1 : 0);
+            return { channelName, isReady: readyTargetCount > 0, readyTargetCount };
+        });
+        const backendTopologyState = backendState(status.state);
+        const hasUnavailableRequiredPeer = peers.some(peer => peer.state === contracts_1.ZLinkPeerState.Connecting
+            || peer.state === contracts_1.ZLinkPeerState.NotConnected);
+        const localTopologyState = drain.state === contracts_1.ZLinkTopologyState.Ready
+            ? backendTopologyState
+            : drain.state;
+        const hostState = this.options.hostState?.()
+            ?? contracts_1.ZLinkFrameworkRuntimeState.Serving;
+        const hostTopologyState = topologyStateForHost(hostState, localTopologyState);
+        const locationStoreHealthy = this.options.isLocationStoreHealthy?.() ?? true;
+        const state = hostTopologyState === contracts_1.ZLinkTopologyState.Ready
+            && (hasUnavailableRequiredPeer || !locationStoreHealthy)
+            ? contracts_1.ZLinkTopologyState.Degraded
+            : hostTopologyState;
+        const hostReady = (0, runtime_state_projections_1.runtimeStateIsReady)(hostState);
+        const objectRole = descriptor?.objectRole ?? contracts_2.ZLinkObjectRole.None;
+        const placementWeight = descriptor?.placementWeight ?? 0;
+        const capacityAvailable = descriptor !== undefined
+            && populationCapacity !== undefined
+            && hasRemainingCapacity(descriptor.activationConcurrency)
+            && (hasRemainingCapacity(populationCapacity.actors)
+                || hasRemainingCapacity(populationCapacity.spots));
+        const placementAvailable = objectRole === contracts_2.ZLinkObjectRole.Server
+            && placementWeight > 0
+            && capacityAvailable
+            && locationStoreHealthy
+            && hostReady
+            && localTopologyState === contracts_1.ZLinkTopologyState.Ready;
+        const snapshot = {
+            meshName,
+            state,
+            isReady: (0, runtime_state_projections_1.topologyRuntimeIsReady)(hostState, state === contracts_1.ZLinkTopologyState.Ready ? 1 : 0),
+            readyPeerCount: peers.filter(peer => peer.state === contracts_1.ZLinkPeerState.Ready).length,
+            channels: hostReady
+                ? channels
+                : channels.map(channel => ({ ...channel, isReady: false })),
+            peers,
+            placement: {
+                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
+            },
+            sequence: drain.sequence > status.lastChangedMs ? drain.sequence : status.lastChangedMs,
+            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 queue = new runtime_observation_queue_1.RuntimeEventQueue(capacity, signal);
+        queue.onClose(() => {
+            state.observers.delete(queue);
+            this.stopPlacementObserverIfIdle();
+        });
+        this.snapshot(meshName);
+        state.observers.add(queue);
+        this.startPlacementObserver();
+        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);
+        }
+    }
+    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)
+                    observer.close();
+                else
+                    observer.seal(terminal, meshName);
+            }
+            state.observers.clear();
+        }
+    }
+    drain(meshName, deadlineMs = 30_000, signal) {
+        const state = this.requireState(meshName);
+        if (this.states.size > 1)
+            return Promise.reject(multiMeshDrainError());
+        if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+            return Promise.reject(new TypeError('Drain deadlineMs must be greater than zero.'));
+        }
+        state.operation ??= this.performDrain(meshName, state, deadlineMs);
+        return waitForOperation(state.operation, signal);
+    }
+    awaitDrained(meshName, signal) {
+        const state = this.requireState(meshName);
+        if (this.states.size > 1)
+            return Promise.reject(multiMeshDrainError());
+        const operation = state.operation ?? new Promise((resolve) => state.waiters.push(resolve));
+        return waitForOperation(operation, signal);
+    }
+    drainHost(deadlineMs = 30_000, signal) {
+        if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+            return Promise.reject(new TypeError('Drain deadlineMs must be greater than zero.'));
+        }
+        if (this.hostOperation === undefined) {
+            const onlyState = this.states.size === 1 ? this.states.values().next().value : undefined;
+            const operation = onlyState?.operation ?? this.performHostDrain(deadlineMs);
+            this.hostOperation = operation;
+            for (const state of this.states.values())
+                state.operation ??= operation;
+        }
+        return waitForOperation(this.hostOperation, signal);
+    }
+    shutdownHost(deadline = 30_000, signal, remainingTimeoutMs) {
+        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);
+            this.shutdownOperation = operation;
+            for (const state of this.states.values())
+                state.operation ??= operation;
+        }
+        return waitForOperation(this.shutdownOperation, signal);
+    }
+    async prepareHostRetire(deadlineMs) {
+        if (this.hostRetiringPrepared)
+            return 'prepared';
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort((0, abort_1.createDeadlineExceededError)('Retire descriptor publication deadline exceeded.')), deadlineMs);
+        const attempted = [];
+        try {
+            for (const meshName of this.states.keys()) {
+                attempted.push(meshName);
+                await this.options.publishRetiring(meshName, deadline.signal);
+            }
+            this.hostRetiringPrepared = true;
+            return 'prepared';
+        }
+        catch {
+            // 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));
+            let rollbackFailed = false;
+            for (const meshName of attempted.reverse()) {
+                try {
+                    await this.options.rollbackRetiring(meshName, rollback.signal);
+                }
+                catch {
+                    rollbackFailed = true;
+                }
+            }
+            clearTimeout(rollbackTimer);
+            if (rollbackFailed) {
+                throw new ZLinkRetiringRollbackError();
+            }
+            return deadline.signal.aborted ? 'deadline_exceeded' : 'store_unavailable';
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Relocates stateful resources without closing application transport.
+     * Shutdown owns admission sealing, peer/listener teardown and owner cleanup.
+     */
+    async relocateHost(deadlineMs, stopStartingSignal) {
+        if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+            throw new TypeError('Relocation deadlineMs must be greater than zero.');
+        }
+        const entries = [...this.states.entries()];
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort((0, abort_1.createDeadlineExceededError)('Relocation deadline exceeded.')), deadlineMs);
+        try {
+            await Promise.all(entries.map(([meshName]) => this.options.drainResources(meshName, deadline.signal, stopStartingSignal)));
+            this.hostRetiringPrepared = false;
+            return { kind: 'drained' };
+        }
+        catch (error) {
+            const classified = drainFailureReason(error);
+            if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION === '1') {
+                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));
+            try {
+                await Promise.all(entries.map(([meshName]) => this.options.rollbackRetiring(meshName, rollback.signal)));
+            }
+            catch {
+                throw new ZLinkRetiringRollbackError();
+            }
+            finally {
+                clearTimeout(rollbackTimer);
+                this.hostRetiringPrepared = false;
+            }
+            return { kind: 'forceStopped', reason, error };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async performDrain(meshName, state, deadlineMs) {
+        state.deadline = new Date(Date.now() + deadlineMs);
+        this.options.admission.seal(meshName);
+        this.transition(meshName, state, contracts_1.ZLinkTopologyState.Stopping);
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort((0, abort_1.createDeadlineExceededError)('Drain deadline exceeded.')), deadlineMs);
+        let result;
+        try {
+            await this.options.publishDraining(meshName, deadline.signal);
+            await this.options.publishHostDraining(deadline.signal);
+            await this.options.admission.awaitZero(meshName, deadline.signal);
+            await this.options.drainResources(meshName, deadline.signal);
+            await this.options.cleanupHostResources(deadline.signal);
+            result = { kind: 'drained' };
+            this.transition(meshName, state, contracts_1.ZLinkTopologyState.Stopped);
+        }
+        catch (error) {
+            const classified = drainFailureReason(error);
+            const reason = classified !== 'teardown_failed'
+                ? classified
+                : deadline.signal.aborted ? 'deadline_exceeded' : classified;
+            await this.options.forceStopResources(meshName).catch(() => undefined);
+            result = { kind: 'forceStopped', reason };
+            this.transition(meshName, state, contracts_1.ZLinkTopologyState.Failed);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        state.result = result;
+        for (const resolve of state.waiters)
+            resolve(result);
+        state.waiters.length = 0;
+        return result;
+    }
+    async performHostDrain(deadlineMs) {
+        const entries = [...this.states.entries()];
+        if (entries.length === 0)
+            return { kind: 'drained' };
+        const deadlineAt = new Date(Date.now() + deadlineMs);
+        for (const [, state] of entries) {
+            state.deadline = deadlineAt;
+        }
+        const deadline = new AbortController();
+        const timer = setTimeout(() => deadline.abort((0, abort_1.createDeadlineExceededError)('Drain deadline exceeded.')), deadlineMs);
+        let result;
+        try {
+            if (!this.hostRetiringPrepared) {
+                await Promise.all(entries.map(([meshName]) => this.options.publishRetiring(meshName, deadline.signal)));
+            }
+            this.hostRetiringPrepared = false;
+            await Promise.all(entries.map(([meshName]) => this.options.drainResources(meshName, deadline.signal)));
+            for (const [meshName, state] of entries) {
+                this.options.admission.seal(meshName);
+                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 this.options.cleanupHostResources(deadline.signal);
+            result = { kind: 'drained' };
+            for (const [meshName, state] of entries) {
+                this.transition(meshName, state, contracts_1.ZLinkTopologyState.Stopped);
+            }
+        }
+        catch (error) {
+            const classified = drainFailureReason(error);
+            const reason = classified !== 'teardown_failed'
+                ? classified
+                : deadline.signal.aborted ? 'deadline_exceeded' : classified;
+            await Promise.all(entries.map(([meshName]) => this.options.forceStopResources(meshName).catch(() => undefined)));
+            result = { kind: 'forceStopped', reason };
+            for (const [meshName, state] of entries) {
+                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)
+                resolve(result);
+            state.waiters.length = 0;
+        }
+        return result;
+    }
+    async performHostShutdown(cleanupDeadline, remainingTimeoutMs) {
+        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((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);
+            result = { kind: 'drained' };
+            for (const [meshName, state] of entries) {
+                this.transition(meshName, state, contracts_1.ZLinkTopologyState.Stopped);
+            }
+        }
+        catch (error) {
+            const classified = drainFailureReason(error);
+            const reason = classified !== 'teardown_failed'
+                ? classified
+                : deadline.signal.aborted ? 'deadline_exceeded' : classified;
+            await Promise.all(entries.map(([meshName]) => this.options.forceStopResources(meshName).catch(() => undefined)));
+            result = { kind: 'forceStopped', reason };
+            for (const [meshName, state] of entries) {
+                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)
+                resolve(result);
+            state.waiters.length = 0;
+        }
+        return result;
+    }
+    transition(meshName, state, next) {
+        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();
+        }
+    }
+    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));
+        }
+        this.peerFingerprints.set(meshName, peerFingerprintMap(this.options.meshNode(meshName)?.peers() ?? []));
+    }
+    startPlacementObserver() {
+        if (this.placementObserver !== undefined)
+            return;
+        this.placementObserver = setInterval(() => this.observePlacementChanges(), 100);
+        this.placementObserver.unref();
+    }
+    stopPlacementObserverIfIdle() {
+        if ([...this.states.values()].some((state) => 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);
+                }
+            }
+        }
+    }
+    requireState(meshName) {
+        const state = this.states.get(meshName);
+        if (state !== undefined)
+            return state;
+        throw routeNotFound(meshName);
+    }
+}
+exports.ZLinkRouteMeshRuntimeCoordinator = ZLinkRouteMeshRuntimeCoordinator;
+function topologyStateForHost(state, fallback) {
+    switch (state) {
+        case contracts_1.ZLinkFrameworkRuntimeState.Serving:
+            return fallback;
+        case contracts_1.ZLinkFrameworkRuntimeState.Preparing:
+            return contracts_1.ZLinkTopologyState.Starting;
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocating:
+        case contracts_1.ZLinkFrameworkRuntimeState.Relocated:
+        case contracts_1.ZLinkFrameworkRuntimeState.Draining:
+            return contracts_1.ZLinkTopologyState.Stopping;
+        case contracts_1.ZLinkFrameworkRuntimeState.Stopped:
+            return contracts_1.ZLinkTopologyState.Stopped;
+        case contracts_1.ZLinkFrameworkRuntimeState.Error:
+            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 ZLinkRetiringRollbackError extends Error {
+    constructor() {
+        super('Retiring descriptor publication could not be rolled back to Serving.');
+        this.name = 'ZLinkRetiringRollbackError';
+    }
+}
+exports.ZLinkRetiringRollbackError = ZLinkRetiringRollbackError;
+function routeNotFound(meshName) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `RouteMesh '${meshName}' is not registered or no longer available.`);
+}
+function multiMeshDrainError() {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, 'RouteMesh drain is unavailable when one framework host owns multiple RouteMesh instances.');
+}
+function backendState(state) {
+    switch (state) {
+        case 1: return contracts_1.ZLinkTopologyState.Starting;
+        case 2:
+        case 3:
+        case 4: return contracts_1.ZLinkTopologyState.Ready;
+        case 5: return contracts_1.ZLinkTopologyState.Stopping;
+        case 6: return contracts_1.ZLinkTopologyState.Stopped;
+        default: return contracts_1.ZLinkTopologyState.Failed;
+    }
+}
+function peerState(state) {
+    switch (state) {
+        case 3: return contracts_1.ZLinkPeerState.Ready;
+        case 4: return contracts_1.ZLinkPeerState.Draining;
+        case 6: return contracts_1.ZLinkPeerState.NotRequired;
+        case 1:
+        case 2:
+            return contracts_1.ZLinkPeerState.Connecting;
+        default:
+            return contracts_1.ZLinkPeerState.NotConnected;
+    }
+}
+function peerUnavailableReason(state) {
+    switch (state) {
+        case contracts_1.ZLinkPeerState.Ready:
+        case contracts_1.ZLinkPeerState.NotRequired:
+            return undefined;
+        case contracts_1.ZLinkPeerState.Draining:
+            return contracts_1.ZLinkTopologyReason.Draining;
+        default:
+            return contracts_1.ZLinkTopologyReason.NoReadyPeer;
+    }
+}
+function drainFailureReason(error) {
+    const name = error instanceof Error ? error.name : '';
+    if (name === 'ZLinkDrainingStatePublishError')
+        return 'drain_state_publish_failed';
+    if (name === 'ZLinkOwnerCleanupError' || error instanceof AggregateError
+        && error.errors.some((nested) => nested instanceof Error && nested.name === 'ZLinkOwnerCleanupError')) {
+        return 'owner_cleanup_failed';
+    }
+    return 'teardown_failed';
+}
+function waitForOperation(operation, signal) {
+    if (signal === undefined)
+        return operation;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        operation.then((result) => {
+            signal.removeEventListener('abort', abort);
+            resolve(result);
+        }, (error) => {
+            signal.removeEventListener('abort', abort);
+            reject(error);
+        });
+    });
+}