@zlink-systems/framework 0.10.0

package/dist/runtime/foundation/raw-service-mesh-runtime.js

@@ -0,0 +1,1349 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RawServiceMeshRuntime = void 0;
+const node_crypto_1 = require("node:crypto");
+const runtime_values_1 = require("../backend/runtime-values");
+const application_ingress_record_owner_1 = require("../application-jobs/application-ingress-record-owner");
+const operation_registry_1 = require("./operation-registry");
+const service_liveness_registry_1 = require("./service-liveness-registry");
+const service_mailbox_1 = require("./service-mailbox");
+const service_topology_registry_1 = require("./service-topology-registry");
+const service_wire_m6a_codec_1 = require("./service-wire-m6a-codec");
+const service_wire_codec_1 = require("./service-wire-codec");
+const service_wire_constants_generated_1 = require("./service-wire-constants.generated");
+const MONITOR_DISCONNECTED = 0x0200;
+const MONITOR_CONNECTION_READY = 0x1000;
+const MONITOR_CONNECTION_READY_EDGE = 1;
+// Framework error code 13 (RequestTargetNotFound) is encoded as 14 on a
+// RequestResult.NotFound reply. Boundary transport results keep failureCode 0.
+const REQUEST_TARGET_NOT_FOUND_FAILURE_CODE = 14;
+const livenessCodec = (0, service_wire_codec_1.createServiceWireCodec)({
+    magic: [0x5a, 0x4d],
+    major: 1,
+    commands: service_wire_m6a_codec_1.M6aServiceWireCommand
+});
+const MAX_PENDING_MONITOR_EVENTS = 8192;
+const MAX_UNRESOLVED_CONNECTION_CANDIDATES = 4096;
+/**
+ * RouteMesh M6A runtime built only on the public raw binding package.
+ * It owns protocol, admission, mailbox, request and liveness state.
+ */
+class RawServiceMeshRuntime {
+    topology;
+    mailbox;
+    liveness;
+    operations = new operation_registry_1.OperationRegistry();
+    expectedPeers = new Map();
+    endpointOnlyPeers = new Set();
+    peerConnectionIntentRemoved = new Set();
+    connectionCandidates = new Map();
+    unresolvedConnectionCandidates = [];
+    connectionIds = new Map();
+    /**
+     * The monitor drain updates this fence before the event reaches the
+     * normal runtime handler. `null` means that the last observed pair is no
+     * longer usable by the application route.
+     */
+    monitorConnectionStates = new Map();
+    monitorEvents = [];
+    monitorDrainBuffer = [];
+    bindingPort;
+    applicationJobQueue;
+    peerAdmissionSealed;
+    applicationJobStop = new AbortController();
+    onPeerNotRequired;
+    onPeerDisconnected;
+    onProtocolError;
+    onReceiveFlowConfigFailure;
+    resolveAdvertisedEndpoint;
+    descriptor;
+    host;
+    router;
+    monitor;
+    nextCorrelation = 1n;
+    serviceIngress;
+    closed = false;
+    constructor(options) {
+        this.descriptor = options.descriptor;
+        this.topology = new service_topology_registry_1.ServiceTopologyRegistry(options.descriptor);
+        this.mailbox = new service_mailbox_1.ServiceMailbox(undefined, options.onMailboxReady);
+        this.liveness = new service_liveness_registry_1.ServiceLivenessRegistry(options.probeIntervalMs, options.peerTimeoutMs);
+        this.bindingPort = options.bindingPort;
+        if (options.applicationJobQueue === undefined) {
+            throw new TypeError('Raw service runtime requires the host Application Job Queue.');
+        }
+        this.applicationJobQueue = options.applicationJobQueue;
+        this.peerAdmissionSealed = options.peerAdmissionSealed;
+        this.onPeerNotRequired = options.onPeerNotRequired;
+        this.onPeerDisconnected = options.onPeerDisconnected;
+        this.onProtocolError = options.onProtocolError;
+        this.onReceiveFlowConfigFailure = options.onReceiveFlowConfigFailure;
+        this.resolveAdvertisedEndpoint = options.resolveAdvertisedEndpoint;
+    }
+    start() {
+        if (this.router !== undefined)
+            return;
+        if (this.closed)
+            throw new Error('Raw service runtime cannot restart after close.');
+        const host = this.bindingPort.createHost();
+        let router;
+        try {
+            router = host.createRouter();
+            const receiveFlowRouter = router;
+            router.setRoutingId(this.descriptor.nodeRoutingId);
+            this.applicationJobQueue.registerReceiveFlowTarget?.(router, state => receiveFlowRouter.setReceiveFlowState(state), this.onReceiveFlowConfigFailure);
+            router.bind(this.descriptor.advertisedEndpoint);
+            const boundEndpoint = router.localEndpoint();
+            const next = {
+                ...this.descriptor,
+                advertisedEndpoint: this.resolveAdvertisedEndpoint?.(boundEndpoint)
+                    ?? boundEndpoint,
+                descriptorRevision: this.descriptor.descriptorRevision + 1n,
+                state: 'serving'
+            };
+            this.topology.publishLocal(next);
+            this.descriptor = next;
+            this.monitor = router.monitor();
+            this.pullMonitorEvents();
+            this.host = host;
+            this.router = router;
+        }
+        catch (error) {
+            if (router !== undefined) {
+                this.applicationJobQueue.unregisterReceiveFlowTarget?.(router);
+            }
+            host.close();
+            throw error;
+        }
+    }
+    connectPeer(endpoint, expected) {
+        this.requireStarted().connectToRoutingId(expected.nodeRoutingId, endpoint);
+        this.expectedPeers.set(expected.nodeRoutingId, {
+            meshName: expected.meshName,
+            nodeRoutingId: expected.nodeRoutingId,
+            endpoint,
+            securityIdentity: expected.securityIdentity,
+            lifecycleGeneration: expected.lifecycleGeneration
+        });
+    }
+    connectPeerByRoutingId(endpoint, nodeRoutingId, securityIdentity, lifecycleGeneration) {
+        this.requireStarted().connectToRoutingId(nodeRoutingId, endpoint);
+        this.expectedPeers.set(nodeRoutingId, {
+            meshName: this.topology.localDescriptor().meshName,
+            nodeRoutingId,
+            endpoint,
+            securityIdentity,
+            lifecycleGeneration
+        });
+    }
+    expectPeerByRoutingId(endpoint, nodeRoutingId, securityIdentity, lifecycleGeneration) {
+        this.expectedPeers.set(nodeRoutingId, {
+            meshName: this.topology.localDescriptor().meshName,
+            nodeRoutingId,
+            endpoint,
+            securityIdentity,
+            lifecycleGeneration
+        });
+    }
+    connectPeerEndpoint(endpoint) {
+        this.requireStarted().connect(endpoint);
+        this.endpointOnlyPeers.add(endpoint);
+    }
+    disconnectPeer(endpoint, nodeRoutingId, lifecycleGeneration) {
+        const current = this.topology.peer(nodeRoutingId);
+        const expected = this.expectedPeers.get(nodeRoutingId);
+        if (lifecycleGeneration !== undefined
+            && (
+            // Discovery has already fenced this RID to a replacement process.
+            // The old auto-connect intent must not use disconnectRid here: that
+            // is RID-wide and can close the provisional replacement before its
+            // Hello/admission promotes it. admitPeer owns exact old-pair teardown
+            // after the replacement descriptor is accepted.
+            (expected?.lifecycleGeneration !== undefined
+                && expected.lifecycleGeneration !== lifecycleGeneration)
+                ||
+                    (current !== undefined
+                        && current.descriptor.lifecycleGeneration !== lifecycleGeneration)
+                || (current === undefined
+                    && expected?.lifecycleGeneration !== lifecycleGeneration))) {
+            return;
+        }
+        try {
+            const router = this.requireStarted();
+            if (router.disconnectRid !== undefined) {
+                router.disconnectRid(nodeRoutingId);
+            }
+            else {
+                router.disconnect(endpoint);
+            }
+        }
+        catch (error) {
+            if (!isAlreadyDisconnectedError(error))
+                throw error;
+        }
+        finally {
+            if (current !== undefined)
+                this.removePeer(current);
+            this.topology.forgetNotRequired(nodeRoutingId);
+            if (lifecycleGeneration === undefined
+                || expected?.lifecycleGeneration === undefined
+                || expected.lifecycleGeneration === lifecycleGeneration) {
+                this.expectedPeers.delete(nodeRoutingId);
+            }
+            this.notifyPeerConnectionIntentRemoved(nodeRoutingId);
+        }
+    }
+    disconnectPeerEndpoint(endpoint) {
+        try {
+            this.requireStarted().disconnect(endpoint);
+        }
+        catch (error) {
+            if (!isAlreadyDisconnectedError(error))
+                throw error;
+        }
+        finally {
+            this.endpointOnlyPeers.delete(endpoint);
+            const removed = new Set();
+            for (const [nodeRoutingId, expected] of this.expectedPeers) {
+                if (expected.endpoint === endpoint) {
+                    this.expectedPeers.delete(nodeRoutingId);
+                    removed.add(nodeRoutingId);
+                }
+            }
+            for (const peer of this.topology.peers()) {
+                if (peer.descriptor.advertisedEndpoint === endpoint) {
+                    this.removePeer(peer);
+                    removed.add(peer.descriptor.nodeRoutingId);
+                }
+            }
+            for (const nodeRoutingId of removed)
+                this.notifyPeerConnectionIntentRemoved(nodeRoutingId);
+        }
+    }
+    observePeerConnectionIntentRemoved(listener) {
+        this.peerConnectionIntentRemoved.add(listener);
+        return () => { this.peerConnectionIntentRemoved.delete(listener); };
+    }
+    notifyPeerConnectionIntentRemoved(nodeRoutingId) {
+        // Only the logical owner's removal publishes lifecycle termination.
+        // A physical disconnect alone retains the connection expectation.
+        if (this.expectedPeers.has(nodeRoutingId) || this.topology.peer(nodeRoutingId) !== undefined)
+            return;
+        for (const listener of this.peerConnectionIntentRemoved)
+            listener(nodeRoutingId);
+    }
+    async announcePeer(nodeRoutingId) {
+        if (!this.expectedPeers.has(nodeRoutingId) || this.peerAdmissionSealed?.() === true)
+            return false;
+        return this.send(nodeRoutingId, [(0, service_wire_m6a_codec_1.encodeRouteMeshAdmission)(service_wire_m6a_codec_1.M6aServiceWireCommand.hello, this.topology.localDescriptor())]);
+    }
+    isPeerRouteReady(nodeRoutingId, lifecycleGeneration) {
+        const peer = this.topology.peer(nodeRoutingId);
+        const monitorConnection = this.monitorConnectionStates.get(nodeRoutingId);
+        const applicationRouteReady = monitorConnection === undefined
+            || monitorConnection === peer?.connectionId;
+        const ready = peer !== undefined
+            && (lifecycleGeneration === undefined
+                || peer.descriptor.lifecycleGeneration === lifecycleGeneration)
+            && applicationRouteReady
+            && this.liveness.isReady(nodeRoutingId, peer.connectionId);
+        return ready;
+    }
+    async announceExpectedPeers() {
+        let accepted = 0;
+        for (const nodeRoutingId of this.expectedPeers.keys()) {
+            // Admission is a one-time fence for the current physical connection.
+            // Re-sending Hello after the peer is admitted would re-run admission on
+            // every poll and reset the liveness record before application traffic
+            // can use the route. A disconnected peer is removed by monitor handling
+            // and remains eligible for the next admission attempt.
+            if (this.topology.peer(nodeRoutingId) !== undefined)
+                continue;
+            if (await this.announcePeer(nodeRoutingId))
+                accepted++;
+        }
+        return accepted;
+    }
+    async updateLocalDescriptor(options) {
+        const current = this.topology.localDescriptor();
+        const channels = options.state === 'draining'
+            ? current.channels.map(channel => ({ ...channel, weight: 0 }))
+            : options.channelName === undefined
+                ? current.channels
+                : current.channels.map(channel => channel.name === options.channelName
+                    ? { ...channel, weight: options.channelWeight }
+                    : channel);
+        const next = {
+            ...current,
+            descriptorRevision: current.descriptorRevision + 1n,
+            state: options.state ?? current.state,
+            placementWeight: options.placementWeight ?? current.placementWeight,
+            channels
+        };
+        this.topology.publishLocal(next);
+        this.descriptor = next;
+        // An admitted peer keeps the descriptor it received at admission.  The
+        // placement and channel selectors therefore need the new mutable fields
+        // on that same connection before the next request is selected; waiting for
+        // a reconnect would leave a race where a drained node is selected again.
+        const update = (0, service_wire_m6a_codec_1.encodeRouteMeshAdmission)(service_wire_m6a_codec_1.M6aServiceWireCommand.update, this.topology.localDescriptor());
+        for (const peer of this.topology.peers()) {
+            await this.send(peer.descriptor.nodeRoutingId, [update]);
+        }
+        await this.announceExpectedPeers();
+    }
+    replaceDiscoveredNotRequired(descriptors) {
+        this.topology.replaceDiscoveredNotRequired(descriptors);
+    }
+    isObjectClientNodeDirectTarget(nodeRoutingId) {
+        const descriptor = nodeRoutingId === this.descriptor.nodeRoutingId
+            ? this.topology.localDescriptor()
+            : this.topology.knownDescriptor(nodeRoutingId);
+        return descriptor?.objectRole === 'client';
+    }
+    async sendToNode(targetNodeRoutingId, payload) {
+        return this.send(targetNodeRoutingId, [(0, service_wire_m6a_codec_1.encodeNodeSendHeader)(), (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)]);
+    }
+    async sendToChannel(channelName, payload) {
+        const selected = this.topology.selectChannel(channelName, peer => this.isLocalOrReadyPeer(peer.descriptor.nodeRoutingId));
+        if (selected === undefined)
+            return false;
+        if (selected.descriptor.nodeRoutingId === this.descriptor.nodeRoutingId) {
+            const applicationJobOwner = await this.reserveLocalIngress();
+            try {
+                const applicationJob = await applicationJobOwner.acquire('application');
+                const accepted = this.mailbox.tryEnqueue({
+                    owner: `channel:${channelName}`,
+                    domain: 'application',
+                    parts: [(0, service_wire_m6a_codec_1.encodeChannelSendHeader)(channelName), (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)],
+                    sourceRoutingId: this.descriptor.nodeRoutingId,
+                    applicationJob
+                });
+                if (!accepted)
+                    applicationJob.close();
+                return accepted;
+            }
+            finally {
+                applicationJobOwner.close();
+            }
+        }
+        return this.send(selected.descriptor.nodeRoutingId, [
+            (0, service_wire_m6a_codec_1.encodeChannelSendHeader)(channelName),
+            (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)
+        ]);
+    }
+    requestToNode(targetNodeRoutingId, payload, timeoutMs) {
+        return this.requestToTarget(targetNodeRoutingId, payload, timeoutMs);
+    }
+    requestToChannel(channelName, payload, timeoutMs) {
+        const selected = this.topology.selectChannel(channelName, peer => this.isLocalOrReadyPeer(peer.descriptor.nodeRoutingId));
+        return selected === undefined
+            ? undefined
+            : this.requestToTarget(selected.descriptor.nodeRoutingId, payload, timeoutMs, channelName);
+    }
+    isLocalOrReadyPeer(nodeRoutingId) {
+        return nodeRoutingId === this.descriptor.nodeRoutingId
+            || this.isPeerRouteReady(nodeRoutingId);
+    }
+    setServiceIngress(handler) {
+        if (this.serviceIngress !== undefined && this.serviceIngress !== handler) {
+            throw new Error('Raw service ingress is already registered.');
+        }
+        this.serviceIngress = handler;
+    }
+    async reserveLocalIngress(signal) {
+        const waitSignal = signal === undefined
+            ? this.applicationJobStop.signal
+            : AbortSignal.any([this.applicationJobStop.signal, signal]);
+        const permit = await this.applicationJobQueue.acquire(waitSignal);
+        return application_ingress_record_owner_1.ApplicationIngressRecordOwner.create(this.applicationJobQueue, permit, { close() { } });
+    }
+    async sendService(targetNodeRoutingId, parts) {
+        return this.send(targetNodeRoutingId, parts);
+    }
+    requestService(targetNodeRoutingId, parts, timeoutMs) {
+        return this.requireStarted().request(targetNodeRoutingId, parts, timeoutMs);
+    }
+    replyService(record, parts) {
+        if (record.requestSequence === undefined) {
+            throw new TypeError('Service reply requires a request sequence.');
+        }
+        if (record.reply === undefined) {
+            throw new TypeError('Service reply requires an opaque reply capability.');
+        }
+        record.reply(parts);
+    }
+    reply(request, payload, terminalResult = 0, failureCode = 0) {
+        if (request.localReply !== undefined) {
+            request.localReply(terminalResult, failureCode, terminalResult === 0 ? payload : undefined);
+            return;
+        }
+        if (request.reply === undefined || request.correlation === undefined) {
+            throw new TypeError('Reply requires a request mailbox record.');
+        }
+        request.reply([
+            (0, service_wire_m6a_codec_1.encodeReplyHeader)(request.correlation, terminalResult, failureCode),
+            ...(terminalResult === 0 ? [(0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload)] : [])
+        ]);
+    }
+    async pumpOne(nowMs = performance.now(), observe) {
+        const router = this.requireStarted();
+        this.pullMonitorEvents();
+        let permit;
+        try {
+            permit = await this.applicationJobQueue.acquire(this.applicationJobStop.signal);
+        }
+        catch (error) {
+            if (this.closed || this.applicationJobStop.signal.aborted)
+                return 'noData';
+            throw error;
+        }
+        let received;
+        try {
+            received = router.receive(true);
+        }
+        catch (error) {
+            permit.releaseAfterInternalProcessing();
+            throw error;
+        }
+        if (received === undefined) {
+            permit.releaseAfterInternalProcessing();
+            return 'noData';
+        }
+        const applicationJobOwner = application_ingress_record_owner_1.ApplicationIngressRecordOwner.create(this.applicationJobQueue, permit, received);
+        try {
+            const result = await this.processReceived(received, nowMs, applicationJobOwner);
+            if (result === 'protocolError') {
+                this.reportProtocolError(received);
+            }
+            observe?.(received.sourceRid, received.parts.reduce((sum, part) => sum + part.byteLength, 0));
+            return result;
+        }
+        finally {
+            applicationJobOwner.close();
+        }
+    }
+    pullMonitorEvents() {
+        this.monitor?.drain(event => {
+            this.observeMonitorEvent(event);
+            if (this.monitorEvents.length < MAX_PENDING_MONITOR_EVENTS) {
+                this.monitorEvents.push(event);
+                return;
+            }
+            const existingIndex = this.monitorEvents.findIndex(candidate => sameMonitorConnection(candidate, event));
+            if (existingIndex >= 0)
+                this.monitorEvents[existingIndex] = event;
+            else {
+                this.monitorEvents.shift();
+                this.monitorEvents.push(event);
+            }
+        });
+    }
+    reportProtocolError(received) {
+        const request = received.requestSeq !== undefined;
+        const replied = request && this.replyGenericProtocolError(received);
+        this.onProtocolError?.({
+            sourceRoutingId: received.sourceRid,
+            request,
+            replied,
+            ...protocolCommand(received.parts)
+        });
+    }
+    replyGenericProtocolError(received) {
+        if (received.requestSeq === undefined || received.parts.length === 0)
+            return false;
+        try {
+            const header = (0, service_wire_m6a_codec_1.decodeHeader)(received.parts[0]);
+            const correlation = header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.nodeRequest
+                ? (0, service_wire_m6a_codec_1.decodeNodeRequestHeader)(received.parts[0])
+                : header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.channelRequest
+                    ? (0, service_wire_m6a_codec_1.decodeChannelRequestHeader)(received.parts[0]).correlation
+                    : undefined;
+            if (correlation === undefined)
+                return false;
+            const reply = [(0, service_wire_m6a_codec_1.encodeReplyHeader)(correlation, runtime_values_1.RequestResult.ProtocolError, service_wire_constants_generated_1.ServiceWireFrameworkErrorCode.requestProtocolError)];
+            if (received.reply === undefined)
+                return false;
+            received.reply(reply);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof service_wire_m6a_codec_1.ServiceWireProtocolError)
+                return false;
+            throw error;
+        }
+    }
+    async processReceived(received, nowMs, applicationJobOwner) {
+        if (received.parts.length === 0
+            || (received.parts.length === 1
+                && received.parts[0].byteLength === 0)) {
+            if (this.peerAdmissionSealed?.() === true)
+                return 'dropped';
+            return await this.send(received.sourceRid, [(0, service_wire_m6a_codec_1.encodeRouteMeshAdmission)(service_wire_m6a_codec_1.M6aServiceWireCommand.hello, this.topology.localDescriptor())])
+                ? 'infrastructure'
+                : 'dropped';
+        }
+        try {
+            const header = (0, service_wire_m6a_codec_1.decodeHeader)(received.parts[0]);
+            if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.hello && this.peerAdmissionSealed?.() === true) {
+                return 'dropped';
+            }
+            if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.hello
+                || header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.admit
+                || header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.update) {
+                if (received.parts.length !== 1)
+                    return 'protocolError';
+                const descriptor = (0, service_wire_m6a_codec_1.decodeRouteMeshAdmission)(received.parts[0], header.command, received.sourceRid);
+                const expected = this.expectedPeers.get(received.sourceRid);
+                if (expected !== undefined
+                    && (expected.meshName !== descriptor.meshName
+                        || expected.nodeRoutingId !== descriptor.nodeRoutingId)) {
+                    await this.send(received.sourceRid, [(0, service_wire_m6a_codec_1.encodeReject)(3)]);
+                    return 'infrastructure';
+                }
+                const connection = this.currentConnectionCandidate(received.sourceRid, descriptor.advertisedEndpoint);
+                const result = this.admitPeer(descriptor, connection, nowMs, expected);
+                if (result !== 'admitted' && result !== 'notRequired') {
+                    const detail = result === 'invalidDescriptor'
+                        ? describeInvalidAdmissionDescriptor(descriptor, expected, this.topology.peer(descriptor.nodeRoutingId)?.descriptor)
+                        : undefined;
+                    console.warn(`RouteMesh admission rejected peer '${received.sourceRid}' as ${result}`
+                        + (detail === undefined ? '.' : ` (${detail}).`));
+                    await this.send(received.sourceRid, [(0, service_wire_m6a_codec_1.encodeReject)(admissionReason(result))]);
+                    return 'infrastructure';
+                }
+                if (result === 'admitted')
+                    this.selectBilateralConnection(descriptor);
+                if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.hello) {
+                    // Hello supplies only the sender's descriptor. Even NotRequired
+                    // peers must receive ours before the intent owner closes transport;
+                    // submitting a response does not guarantee delivery before close.
+                    await this.send(received.sourceRid, [(0, service_wire_m6a_codec_1.encodeRouteMeshAdmission)(service_wire_m6a_codec_1.M6aServiceWireCommand.admit, this.topology.localDescriptor())]);
+                }
+                else if (result === 'notRequired') {
+                    this.retireNotRequiredExpectedPeer(received.sourceRid, descriptor.advertisedEndpoint);
+                }
+                return 'infrastructure';
+            }
+            if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.reject) {
+                if (received.parts.length !== 1)
+                    return 'protocolError';
+                const reason = (0, service_wire_m6a_codec_1.decodeReject)(received.parts[0]);
+                // A reject belongs to one physical candidate, but the wire record does
+                // not carry that candidate's connection id. Keep an already admitted
+                // peer: bilateral manual connect can reject the duplicate after the
+                // other candidate has become Ready.
+                if (reason === 4 && this.topology.peer(received.sourceRid) === undefined) {
+                    const expected = this.expectedPeers.get(received.sourceRid);
+                    const local = this.topology.localDescriptor();
+                    this.topology.markNotRequired({
+                        ...local,
+                        nodeRoutingId: received.sourceRid,
+                        lifecycleGeneration: 1n,
+                        descriptorRevision: 1n,
+                        advertisedEndpoint: expected?.endpoint ?? local.advertisedEndpoint,
+                        channels: [],
+                        objectRole: 'client'
+                    });
+                    this.retireNotRequiredExpectedPeer(received.sourceRid);
+                }
+                return 'infrastructure';
+            }
+            const peer = this.topology.peer(received.sourceRid);
+            if (peer === undefined)
+                return 'protocolError';
+            if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.livenessProbe
+                || header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.livenessAck) {
+                if (received.parts.length !== 1)
+                    return 'protocolError';
+                const record = livenessCodec.decodeLivenessRecord(received.parts[0]);
+                if (record.command === service_wire_m6a_codec_1.M6aServiceWireCommand.livenessProbe) {
+                    const ack = this.liveness.acknowledgeProbe(received.sourceRid, peer.connectionId, record.probeId);
+                    const sent = ack !== undefined && await this.send(received.sourceRid, [livenessCodec.encodeLivenessRecord({
+                            command: service_wire_m6a_codec_1.M6aServiceWireCommand.livenessAck,
+                            probeId: record.probeId
+                        })]);
+                    if (!sent) {
+                        return 'protocolError';
+                    }
+                }
+                else {
+                    this.liveness.acknowledge(received.sourceRid, peer.connectionId, record.probeId, nowMs);
+                }
+                return 'infrastructure';
+            }
+            const stateful = await this.serviceIngress?.({
+                command: header.command,
+                flags: header.flags,
+                sourceRoutingId: received.sourceRid,
+                sourceNodeGeneration: peer.descriptor.lifecycleGeneration,
+                sourceRoute: received.sourceRoute,
+                ...(received.reply === undefined ? {} : { reply: received.reply }),
+                ...(received.requestSeq === undefined ? {} : { requestSequence: received.requestSeq }),
+                parts: received.parts,
+                applicationJobOwner
+            });
+            if (stateful !== undefined)
+                return stateful;
+            if (header.flags === 0
+                // A bare infrastructure control is normally exactly one frame, but a
+                // relocation Prepare now rides its bound-session journal as
+                // node-internal ZLNI frames trailing the canonical command frame
+                // (spec 28 §4.4). Gating on the command vocabulary alone — instead
+                // of also requiring exactly one part — keeps that multi-frame
+                // Prepare from missing this infrastructure-mailbox acceptance and
+                // falling through to the two-frame application-envelope check below,
+                // which does not recognize command 40 and rejected it as a
+                // protocolError (surfaced downstream as `invalid_frame`, stalling
+                // the source's Prepare resend loop past the relocation admission
+                // budget).
+                && received.parts.length >= 1
+                && isBareInfrastructureControl(header.command)) {
+                const accepted = this.mailbox.tryEnqueue({
+                    owner: `node:${this.descriptor.nodeRoutingId}`,
+                    domain: 'infrastructure',
+                    parts: received.parts,
+                    sourceRoutingId: received.sourceRid,
+                    sourceRoute: received.sourceRoute,
+                    ...(received.reply === undefined ? {} : { reply: received.reply }),
+                    ...(received.requestSeq === undefined ? {} : { requestSequence: received.requestSeq })
+                });
+                return accepted ? 'infrastructure' : 'dropped';
+            }
+            if (header.flags !== 0
+                || received.parts.length !== 2
+                || ![
+                    service_wire_m6a_codec_1.M6aServiceWireCommand.nodeSend,
+                    service_wire_m6a_codec_1.M6aServiceWireCommand.nodeRequest,
+                    service_wire_m6a_codec_1.M6aServiceWireCommand.channelSend,
+                    service_wire_m6a_codec_1.M6aServiceWireCommand.channelRequest
+                ].includes(header.command)) {
+                return 'protocolError';
+            }
+            let owner;
+            let correlation;
+            if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.nodeSend) {
+                owner = `node:${this.descriptor.nodeRoutingId}`;
+            }
+            else if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.nodeRequest) {
+                owner = `node:${this.descriptor.nodeRoutingId}`;
+                correlation = (0, service_wire_m6a_codec_1.decodeNodeRequestHeader)(received.parts[0]);
+            }
+            else if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.channelSend) {
+                owner = `channel:${(0, service_wire_m6a_codec_1.decodeChannelSendHeader)(received.parts[0])}`;
+            }
+            else {
+                const channel = (0, service_wire_m6a_codec_1.decodeChannelRequestHeader)(received.parts[0]);
+                owner = `channel:${channel.channelName}`;
+                correlation = channel.correlation;
+            }
+            const applicationJob = await applicationJobOwner.acquire('application');
+            const accepted = this.mailbox.tryEnqueue({
+                owner,
+                domain: 'application',
+                parts: received.parts,
+                sourceRoutingId: received.sourceRid,
+                sourceRoute: received.sourceRoute,
+                ...(received.reply === undefined ? {} : { reply: received.reply }),
+                requestSequence: received.requestSeq,
+                ...(correlation === undefined ? {} : { correlation }),
+                applicationJob
+            });
+            if (accepted)
+                return 'application';
+            applicationJob.close();
+            if (correlation !== undefined && received.requestSeq !== undefined) {
+                this.replyService({
+                    sourceRoutingId: received.sourceRid,
+                    sourceRoute: received.sourceRoute,
+                    requestSequence: received.requestSeq,
+                    ...(received.reply === undefined ? {} : { reply: received.reply })
+                }, [
+                    (0, service_wire_m6a_codec_1.encodeReplyHeader)(correlation, runtime_values_1.RequestResult.NotConnected, 0)
+                ]);
+                return 'infrastructure';
+            }
+            return 'dropped';
+        }
+        catch (error) {
+            if (error instanceof service_wire_m6a_codec_1.ServiceWireProtocolError)
+                return 'protocolError';
+            throw error;
+        }
+    }
+    async tickLiveness(nowMs = performance.now()) {
+        const result = this.liveness.tick(nowMs);
+        this.requireStarted();
+        for (const probe of result.probes) {
+            await this.send(probe.nodeRoutingId, [livenessCodec.encodeLivenessRecord({
+                    command: service_wire_m6a_codec_1.M6aServiceWireCommand.livenessProbe,
+                    probeId: probe.probeId
+                })]);
+        }
+        for (const nodeRoutingId of result.timedOutNodes) {
+            const peer = this.topology.peer(nodeRoutingId);
+            if (peer === undefined)
+                continue;
+            // Liveness timeout is a semantic peer removal.  Route topology,
+            // physical candidate state, and auto-connect intent must be retired by
+            // the same owner so a failed endpoint cannot be selected again.
+            this.removeConnectionCandidate(nodeRoutingId, peer.connectionId);
+            this.removePeer(peer);
+        }
+        return result;
+    }
+    async drainMonitorEvents(nowMs = performance.now()) {
+        this.pullMonitorEvents();
+        let handled = 0;
+        // Detach the current batch so monitor pulls that run while an event is
+        // being handled append to the next batch without copying or reindexing it.
+        const events = this.monitorEvents;
+        this.monitorEvents = this.monitorDrainBuffer;
+        this.monitorDrainBuffer = events;
+        this.monitorEvents.length = 0;
+        for (const event of events) {
+            handled++;
+            const nodeRoutingId = event.routingId
+                ?? this.expectedPeerRoutingId(event.remoteAddress);
+            if (event.event === MONITOR_CONNECTION_READY && isConnectionReadyEdge(event)) {
+                if (nodeRoutingId === undefined) {
+                    const candidate = this.createUnresolvedConnectionCandidate(event);
+                    const alreadyQueued = this.unresolvedConnectionCandidates.some(value => value.connectionId === candidate.connectionId);
+                    if (!alreadyQueued && this.unresolvedConnectionCandidates.length < MAX_UNRESOLVED_CONNECTION_CANDIDATES) {
+                        this.unresolvedConnectionCandidates.push(candidate);
+                    }
+                    continue;
+                }
+                if (!this.acceptsExpectedMonitorEndpoint(nodeRoutingId, event)) {
+                    continue;
+                }
+                const candidate = this.createConnectionCandidate(nodeRoutingId, event);
+                const existingPeer = this.topology.peer(nodeRoutingId);
+                if (existingPeer !== undefined && existingPeer.connectionId === candidate.connectionId) {
+                    this.monitorConnectionStates.set(nodeRoutingId, candidate.connectionId);
+                    continue;
+                }
+                if (existingPeer !== undefined) {
+                    if (this.liveness.isReady(nodeRoutingId, existingPeer.connectionId)) {
+                        const existingCandidate = this.connectionCandidates
+                            .get(nodeRoutingId)?.get(existingPeer.connectionId);
+                        if (this.isDiscoveredLifecycleReplacement(existingPeer, nodeRoutingId)) {
+                            // A current discovery descriptor with the same RID but a
+                            // different lifecycle token denotes a replacement process.
+                            // Keep its physical pair provisional until its Hello passes
+                            // the descriptor fence; the old ready peer remains semantic
+                            // current until then.
+                            let provisionalCandidates = this.connectionCandidates.get(nodeRoutingId);
+                            if (provisionalCandidates === undefined) {
+                                provisionalCandidates = new Map();
+                                this.connectionCandidates.set(nodeRoutingId, provisionalCandidates);
+                            }
+                            provisionalCandidates.set(candidate.connectionId, candidate);
+                            await this.announcePeer(nodeRoutingId);
+                            continue;
+                        }
+                        if (existingCandidate?.connectionId === candidate.connectionId) {
+                            this.removeConnectionCandidate(nodeRoutingId, candidate.connectionId);
+                            this.monitorConnectionStates.set(nodeRoutingId, existingPeer.connectionId);
+                            continue;
+                        }
+                        // A non-replacement ready route is the current semantic owner.
+                        // A second physical candidate may be admitted only after the
+                        // current lease expires; this also prevents a late old-process
+                        // reconnect from replacing the ready replacement by arrival order.
+                        this.removeConnectionCandidate(nodeRoutingId, candidate.connectionId);
+                        continue;
+                    }
+                    // Keep the physical candidate until the wire descriptor decides
+                    // whether it is the current logical peer. READY events can race
+                    // with DISCONNECTED events during reconnect; rejecting the READY
+                    // here can terminate the replacement before admission evaluates its
+                    // lifecycle generation.
+                    let provisionalCandidates = this.connectionCandidates.get(nodeRoutingId);
+                    if (provisionalCandidates === undefined) {
+                        provisionalCandidates = new Map();
+                        this.connectionCandidates.set(nodeRoutingId, provisionalCandidates);
+                    }
+                    provisionalCandidates.set(candidate.connectionId, candidate);
+                    this.connectionIds.set(nodeRoutingId, candidate.connectionId);
+                    await this.announcePeer(nodeRoutingId);
+                    continue;
+                }
+                let candidates = this.connectionCandidates.get(nodeRoutingId);
+                if (candidates === undefined) {
+                    candidates = new Map();
+                    this.connectionCandidates.set(nodeRoutingId, candidates);
+                }
+                candidates.set(candidate.connectionId, candidate);
+                // Before wire admission the monitor candidate is the only physical
+                // route evidence available to the admission message.
+                this.connectionIds.set(nodeRoutingId, candidate.connectionId);
+                await this.announcePeer(nodeRoutingId);
+            }
+            else if (event.event === MONITOR_DISCONNECTED
+                && nodeRoutingId !== undefined) {
+                const peer = this.topology.peer(nodeRoutingId);
+                const disconnectedId = monitorConnectionId(event, nodeRoutingId);
+                this.removeConnectionCandidate(nodeRoutingId, disconnectedId);
+                if (peer !== undefined && peer.connectionId === disconnectedId) {
+                    this.removePeer(peer);
+                }
+            }
+            else if (event.event === MONITOR_DISCONNECTED) {
+                const disconnectedId = monitorConnectionId(event);
+                const index = this.unresolvedConnectionCandidates.findIndex(candidate => candidate.connectionId === disconnectedId);
+                if (index >= 0)
+                    this.unresolvedConnectionCandidates.splice(index, 1);
+            }
+        }
+        this.monitorDrainBuffer.length = 0;
+        void nowMs;
+        return handled;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.applicationJobStop.abort(new Error('Raw service runtime application job admission stopped.'));
+        this.mailbox.close();
+        this.operations.close('Raw service runtime closed.');
+        this.serviceIngress = undefined;
+        const router = this.router;
+        if (router !== undefined) {
+            this.applicationJobQueue.unregisterReceiveFlowTarget?.(router);
+        }
+        this.monitor?.close();
+        this.monitor = undefined;
+        const host = this.host;
+        this.router = undefined;
+        this.host = undefined;
+        if (host !== undefined)
+            host.close();
+    }
+    requestToTarget(targetNodeRoutingId, payload, timeoutMs, channelName) {
+        const correlation = this.nextCorrelation++;
+        const header = channelName === undefined
+            ? (0, service_wire_m6a_codec_1.encodeNodeRequestHeader)(correlation)
+            : (0, service_wire_m6a_codec_1.encodeChannelRequestHeader)(correlation, channelName);
+        const encodedPayload = (0, service_wire_m6a_codec_1.encodeApplicationPayload)(payload);
+        const pending = this.operations.reserve(timeoutMs);
+        let selectedTargetNodeRoutingId = targetNodeRoutingId;
+        if (selectedTargetNodeRoutingId !== this.descriptor.nodeRoutingId
+            && !this.isPeerRouteReady(selectedTargetNodeRoutingId)) {
+            // Channel selection happens before native admission. If that selection
+            // becomes stale during a peer drain, choose another ready channel peer
+            // while no request has been submitted yet. Reusing the same pending
+            // operation and correlation keeps this recovery pre-admission and
+            // cannot duplicate an application request.
+            if (channelName !== undefined) {
+                const excludedTargets = new Set([selectedTargetNodeRoutingId]);
+                for (;;) {
+                    const alternate = this.topology.selectChannel(channelName, peer => {
+                        const candidate = peer.descriptor.nodeRoutingId;
+                        return !excludedTargets.has(candidate)
+                            && this.isLocalOrReadyPeer(candidate);
+                    });
+                    if (alternate === undefined)
+                        break;
+                    selectedTargetNodeRoutingId = alternate.descriptor.nodeRoutingId;
+                    if (selectedTargetNodeRoutingId === this.descriptor.nodeRoutingId
+                        || this.isPeerRouteReady(selectedTargetNodeRoutingId)) {
+                        break;
+                    }
+                    excludedTargets.add(selectedTargetNodeRoutingId);
+                }
+            }
+        }
+        if (selectedTargetNodeRoutingId === this.descriptor.nodeRoutingId) {
+            const parts = [header, encodedPayload];
+            const capacityStop = new AbortController();
+            void pending.promise.finally(() => capacityStop.abort()).catch(() => undefined);
+            void (async () => {
+                const applicationJobOwner = await this.reserveLocalIngress(capacityStop.signal);
+                try {
+                    if (!this.operations.isPending(pending.id))
+                        return;
+                    const applicationJob = await applicationJobOwner.acquire('application', capacityStop.signal);
+                    if (!this.operations.isPending(pending.id)) {
+                        applicationJob.close();
+                        return;
+                    }
+                    const accepted = this.mailbox.tryEnqueue({
+                        owner: channelName === undefined
+                            ? `node:${this.descriptor.nodeRoutingId}`
+                            : `channel:${channelName}`,
+                        domain: 'application',
+                        parts,
+                        sourceRoutingId: this.descriptor.nodeRoutingId,
+                        correlation,
+                        localReply: (terminalResult, failureCode, reply) => this.operations.complete(pending.id, {
+                            terminalResult,
+                            failureCode,
+                            ...(reply === undefined ? {} : { payload: reply })
+                        }),
+                        applicationJob
+                    });
+                    if (!accepted) {
+                        applicationJob.close();
+                        this.operations.complete(pending.id, {
+                            terminalResult: runtime_values_1.RequestResult.NotConnected,
+                            failureCode: 0
+                        });
+                    }
+                }
+                finally {
+                    applicationJobOwner.close();
+                }
+            })().catch(error => this.operations.fail(pending.id, error));
+            return pending;
+        }
+        if (!this.isPeerRouteReady(selectedTargetNodeRoutingId)) {
+            // Preserve Core's distinct target-not-found result for an RID the
+            // topology has never observed. A known peer without a usable route is
+            // a Framework NotConnected result; an unknown RID is completed locally
+            // as RequestTargetNotFound without submitting an application frame.
+            const knownTarget = this.topology.peer(selectedTargetNodeRoutingId) !== undefined
+                || this.topology.knownDescriptor(selectedTargetNodeRoutingId) !== undefined;
+            this.operations.complete(pending.id, {
+                terminalResult: knownTarget
+                    ? runtime_values_1.RequestResult.NotConnected
+                    : runtime_values_1.RequestResult.NotFound,
+                failureCode: knownTarget ? 0 : REQUEST_TARGET_NOT_FOUND_FAILURE_CODE
+            });
+            return pending;
+        }
+        const parts = [header, encodedPayload];
+        let router;
+        let request;
+        try {
+            router = this.requireStarted();
+            request = router.request(selectedTargetNodeRoutingId, parts, timeoutMs);
+        }
+        catch (error) {
+            this.operations.fail(pending.id, error);
+            return pending;
+        }
+        void request.then(replyParts => {
+            try {
+                if (replyParts.length < 1 || replyParts.length > 2) {
+                    throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid reply parts.');
+                }
+                const reply = (0, service_wire_m6a_codec_1.decodeReplyHeader)(replyParts[0]);
+                if (reply.correlation !== correlation)
+                    throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Reply correlation mismatch.');
+                if (reply.tail.byteLength !== 0) {
+                    throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Generic node/channel reply carries an operation-specific tail.');
+                }
+                if (reply.terminalResult === 0 && replyParts.length !== 2) {
+                    throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Successful reply omits its payload.');
+                }
+                if (reply.terminalResult !== 0 && replyParts.length !== 1) {
+                    throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Failed reply carries a payload.');
+                }
+                const result = {
+                    terminalResult: reply.terminalResult,
+                    failureCode: reply.failureCode
+                };
+                this.operations.complete(pending.id, reply.terminalResult === 0
+                    ? { ...result, payload: (0, service_wire_m6a_codec_1.decodeApplicationPayload)(replyParts[1]) }
+                    : result);
+            }
+            catch (error) {
+                this.operations.fail(pending.id, error);
+            }
+        }, error => {
+            this.operations.fail(pending.id, error);
+        });
+        return pending;
+    }
+    admitPeer(descriptor, connection, nowMs, expected) {
+        const previous = this.topology.peer(descriptor.nodeRoutingId);
+        if (previous !== undefined
+            && previous.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+            && (descriptor.descriptorRevision < previous.descriptor.descriptorRevision
+                || (descriptor.descriptorRevision === previous.descriptor.descriptorRevision
+                    && !(0, service_topology_registry_1.sameServiceNodeDescriptor)(previous.descriptor, descriptor)))) {
+            throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`RouteMesh peer '${descriptor.nodeRoutingId}' descriptor revision is stale or conflicting.`);
+        }
+        const result = this.topology.admit(descriptor, connection.connectionId, expected, connection.discriminator);
+        if (result === 'admitted') {
+            this.connectionIds.set(descriptor.nodeRoutingId, connection.connectionId);
+            this.liveness.admit(descriptor.nodeRoutingId, connection.connectionId, nowMs);
+            this.liveness.requestProbe(descriptor.nodeRoutingId, connection.connectionId, nowMs);
+            this.monitorConnectionStates.set(descriptor.nodeRoutingId, connection.connectionId);
+            if (previous !== undefined && previous.connectionId !== connection.connectionId) {
+                const previousCandidate = this.connectionCandidates
+                    .get(descriptor.nodeRoutingId)?.get(previous.connectionId);
+                if (previousCandidate !== undefined) {
+                    this.removeConnectionCandidate(descriptor.nodeRoutingId, previousCandidate.connectionId);
+                }
+            }
+        }
+        else if (result === 'notRequired' && previous !== undefined) {
+            this.liveness.disconnect(descriptor.nodeRoutingId, previous.connectionId);
+        }
+        else if (previous !== undefined) {
+            this.connectionIds.set(descriptor.nodeRoutingId, previous.connectionId);
+            if (connection.connectionId !== previous.connectionId) {
+                this.removeConnectionCandidate(descriptor.nodeRoutingId, connection.connectionId);
+            }
+        }
+        return result;
+    }
+    currentConnectionCandidate(nodeRoutingId, advertisedEndpoint) {
+        let connectionId = this.connectionIds.get(nodeRoutingId);
+        let candidate = connectionId === undefined
+            ? undefined
+            : this.connectionCandidates.get(nodeRoutingId)?.get(connectionId);
+        if (candidate === undefined) {
+            candidate = this.promoteUnresolvedConnectionCandidate(nodeRoutingId, advertisedEndpoint);
+            connectionId = candidate?.connectionId;
+        }
+        if (candidate === undefined) {
+            const localRid = this.topology.localDescriptor().nodeRoutingId;
+            const endpointOnly = this.endpointOnlyPeers.has(advertisedEndpoint);
+            const direction = this.expectedPeers.has(nodeRoutingId)
+                ? 'outbound'
+                : endpointOnly
+                    ? localRid.localeCompare(nodeRoutingId) <= 0
+                        ? 'outbound'
+                        : 'inbound'
+                    : 'inbound';
+            const initiator = endpointOnly && localRid.localeCompare(nodeRoutingId) > 0
+                ? nodeRoutingId
+                : direction === 'outbound'
+                    ? localRid
+                    : nodeRoutingId;
+            connectionId = `unmonitored:${direction}:${(0, node_crypto_1.randomUUID)()}`;
+            candidate = {
+                connectionId,
+                direction,
+                discriminator: `initiator:${initiator}`,
+                localAddress: '',
+                remoteAddress: advertisedEndpoint
+            };
+            let candidates = this.connectionCandidates.get(nodeRoutingId);
+            if (candidates === undefined) {
+                candidates = new Map();
+                this.connectionCandidates.set(nodeRoutingId, candidates);
+            }
+            candidates.set(connectionId, candidate);
+            this.connectionIds.set(nodeRoutingId, connectionId);
+        }
+        return candidate;
+    }
+    createConnectionCandidate(nodeRoutingId, event) {
+        const local = this.topology.localDescriptor();
+        const expected = this.expectedPeers.get(nodeRoutingId);
+        const direction = event.localAddress === local.advertisedEndpoint
+            ? 'inbound'
+            : expected?.endpoint === event.remoteAddress
+                ? 'outbound'
+                : this.endpointOnlyPeers.has(event.remoteAddress)
+                    ? 'outbound'
+                    : 'unknown';
+        const initiator = direction === 'outbound'
+            ? local.nodeRoutingId
+            : direction === 'inbound'
+                ? nodeRoutingId
+                : undefined;
+        return {
+            connectionId: monitorConnectionId(event, nodeRoutingId),
+            direction,
+            discriminator: initiator === undefined
+                ? `unknown:${monitorConnectionId(event, nodeRoutingId)}`
+                : `initiator:${initiator}`,
+            localAddress: event.localAddress,
+            remoteAddress: event.remoteAddress
+        };
+    }
+    createUnresolvedConnectionCandidate(event) {
+        const connectionId = monitorConnectionId(event);
+        const local = this.topology.localDescriptor();
+        const direction = this.endpointOnlyPeers.has(event.remoteAddress)
+            || this.expectedPeerRoutingId(event.remoteAddress) !== undefined
+            ? 'outbound'
+            : event.localAddress === local.advertisedEndpoint
+                ? 'inbound'
+                : 'unknown';
+        return {
+            connectionId,
+            direction,
+            discriminator: `unresolved:${connectionId}`,
+            localAddress: event.localAddress,
+            remoteAddress: event.remoteAddress
+        };
+    }
+    promoteUnresolvedConnectionCandidate(nodeRoutingId, advertisedEndpoint) {
+        const relevant = this.unresolvedConnectionCandidates
+            .map((candidate, index) => ({ candidate, index }))
+            .filter(({ candidate }) => candidate.remoteAddress === advertisedEndpoint
+            || candidate.direction === 'inbound');
+        if (relevant.length === 0)
+            return undefined;
+        const directions = new Set(relevant.map(value => value.candidate.direction));
+        const localRid = this.topology.localDescriptor().nodeRoutingId;
+        const preferredDirection = directions.has('inbound') && directions.has('outbound')
+            ? localRid.localeCompare(nodeRoutingId) <= 0
+                ? 'outbound'
+                : 'inbound'
+            : relevant.at(-1).candidate.direction;
+        const selected = [...relevant]
+            .reverse()
+            .find(value => value.candidate.direction === preferredDirection)
+            ?? relevant.at(-1);
+        this.unresolvedConnectionCandidates.splice(selected.index, 1);
+        const initiator = selected.candidate.direction === 'outbound'
+            ? localRid
+            : selected.candidate.direction === 'inbound'
+                ? nodeRoutingId
+                : undefined;
+        const candidate = {
+            ...selected.candidate,
+            discriminator: initiator === undefined
+                ? `unknown:${selected.candidate.connectionId}`
+                : `initiator:${initiator}`
+        };
+        let candidates = this.connectionCandidates.get(nodeRoutingId);
+        if (candidates === undefined) {
+            candidates = new Map();
+            this.connectionCandidates.set(nodeRoutingId, candidates);
+        }
+        candidates.set(candidate.connectionId, candidate);
+        this.connectionIds.set(nodeRoutingId, candidate.connectionId);
+        return candidate;
+    }
+    removeConnectionCandidate(nodeRoutingId, connectionId) {
+        const candidates = this.connectionCandidates.get(nodeRoutingId);
+        candidates?.delete(connectionId);
+        if (candidates?.size === 0)
+            this.connectionCandidates.delete(nodeRoutingId);
+        if (this.connectionIds.get(nodeRoutingId) === connectionId) {
+            this.connectionIds.delete(nodeRoutingId);
+        }
+    }
+    isDiscoveredLifecycleReplacement(admitted, nodeRoutingId) {
+        const expected = this.expectedPeers.get(nodeRoutingId);
+        // A same-RID replacement is permitted only from a complete discovery
+        // fence. Manual/endpoint-only intent has no authority to replace a ready
+        // peer, and lifecycle generations are opaque equality tokens.
+        return expected?.endpoint !== undefined
+            && expected.securityIdentity !== undefined
+            && expected.lifecycleGeneration !== undefined
+            && admitted.descriptor.lifecycleGeneration !== expected.lifecycleGeneration;
+    }
+    expectedPeerRoutingId(endpoint) {
+        for (const [nodeRoutingId, expected] of this.expectedPeers) {
+            if (expected.endpoint === endpoint)
+                return nodeRoutingId;
+        }
+        return undefined;
+    }
+    acceptsExpectedMonitorEndpoint(nodeRoutingId, event) {
+        // A monitor address is the physical socket address, which may be an
+        // ephemeral port. Once Core has resolved the peer routing ID, that ID is
+        // the semantic identity; comparing the physical address with the
+        // discovery advertised endpoint would reject valid READY events.
+        if (event.routingId === nodeRoutingId)
+            return true;
+        const expected = this.expectedPeers.get(nodeRoutingId);
+        return expected === undefined || expected.endpoint === undefined
+            || expected.endpoint === event.remoteAddress;
+    }
+    retireNotRequiredExpectedPeer(nodeRoutingId, advertisedEndpoint) {
+        const expected = this.expectedPeers.get(nodeRoutingId);
+        const endpoint = expected?.endpoint
+            ?? (advertisedEndpoint !== undefined
+                && this.endpointOnlyPeers.has(advertisedEndpoint)
+                ? advertisedEndpoint
+                : undefined);
+        if (endpoint !== undefined) {
+            this.requireStarted().disconnect(endpoint);
+            this.endpointOnlyPeers.delete(endpoint);
+            this.onPeerNotRequired?.(nodeRoutingId, endpoint);
+        }
+        this.expectedPeers.delete(nodeRoutingId);
+        this.notifyPeerConnectionIntentRemoved(nodeRoutingId);
+    }
+    selectBilateralConnection(descriptor) {
+        const endpoint = descriptor.advertisedEndpoint;
+        if (!this.endpointOnlyPeers.has(endpoint))
+            return;
+        if (this.expectedPeers.has(descriptor.nodeRoutingId))
+            return;
+        this.expectedPeers.set(descriptor.nodeRoutingId, {
+            meshName: descriptor.meshName,
+            nodeRoutingId: descriptor.nodeRoutingId,
+            endpoint,
+            securityIdentity: descriptor.securityIdentity,
+            lifecycleGeneration: descriptor.lifecycleGeneration
+        });
+        this.endpointOnlyPeers.delete(endpoint);
+    }
+    removePeer(peer) {
+        if (this.monitorConnectionStates.get(peer.descriptor.nodeRoutingId) === peer.connectionId) {
+            this.monitorConnectionStates.set(peer.descriptor.nodeRoutingId, null);
+        }
+        this.topology.disconnect(peer.descriptor.nodeRoutingId, peer.connectionId);
+        this.liveness.disconnect(peer.descriptor.nodeRoutingId, peer.connectionId);
+        this.onPeerDisconnected?.(peer.descriptor.nodeRoutingId, peer.descriptor.advertisedEndpoint, peer.descriptor.lifecycleGeneration);
+    }
+    observeMonitorEvent(event) {
+        const nodeRoutingId = event.routingId
+            ?? this.expectedPeerRoutingId(event.remoteAddress);
+        if (nodeRoutingId === undefined)
+            return;
+        const connectionId = monitorConnectionId(event, nodeRoutingId);
+        if (event.event === MONITOR_CONNECTION_READY && isConnectionReadyEdge(event)) {
+            if (!this.acceptsExpectedMonitorEndpoint(nodeRoutingId, event))
+                return;
+            // The event is queued for admission. Updating monitor state here would
+            // allow a late stale READY to overwrite the admitted replacement.
+            return;
+        }
+        if (event.event === MONITOR_DISCONNECTED
+            && this.monitorConnectionStates.get(nodeRoutingId) === connectionId
+            && this.topology.peer(nodeRoutingId)?.connectionId === connectionId) {
+            this.monitorConnectionStates.set(nodeRoutingId, null);
+        }
+    }
+    requireStarted() {
+        if (this.router === undefined)
+            throw new Error('Raw service runtime is not started.');
+        return this.router;
+    }
+    async send(targetNodeRoutingId, parts) {
+        try {
+            await this.requireStarted().send(targetNodeRoutingId, parts);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.RawServiceMeshRuntime = RawServiceMeshRuntime;
+/**
+ * Relocation and bound-Session controls are service-wire records themselves,
+ * not application NodeSend(16) envelopes. Keep this list closed: a bare
+ * record outside the frozen control vocabulary remains a protocol error.
+ */
+function isBareInfrastructureControl(command) {
+    return [
+        service_wire_constants_generated_1.ServiceWireCommand.relocationReady,
+        service_wire_constants_generated_1.ServiceWireCommand.relocationData,
+        service_wire_constants_generated_1.ServiceWireCommand.replyRelay,
+        service_wire_constants_generated_1.ServiceWireCommand.relocationCutover,
+        service_wire_constants_generated_1.ServiceWireCommand.relocationPrepare,
+        service_wire_constants_generated_1.ServiceWireCommand.sessionRelocationSeal,
+        service_wire_constants_generated_1.ServiceWireCommand.sessionRelocationSealed,
+        service_wire_constants_generated_1.ServiceWireCommand.sessionRelocationRoute,
+        service_wire_constants_generated_1.ServiceWireCommand.replyRelayAck,
+        service_wire_constants_generated_1.ServiceWireCommand.relocationState,
+        service_wire_constants_generated_1.ServiceWireCommand.relocationFailed
+    ].includes(command);
+}
+function protocolCommand(parts) {
+    if (parts.length === 0)
+        return {};
+    try {
+        return { command: (0, service_wire_m6a_codec_1.decodeHeader)(parts[0]).command };
+    }
+    catch {
+        return {};
+    }
+}
+function isAlreadyDisconnectedError(error) {
+    if (typeof error !== 'object' || error === null || !('nativeErrno' in error)) {
+        return false;
+    }
+    return error.nativeErrno === 2;
+}
+function monitorConnectionId(event, resolvedNodeRoutingId = event.routingId ?? '') {
+    if (event.connectionId !== undefined && event.connectionId !== 0n) {
+        return JSON.stringify([
+            resolvedNodeRoutingId,
+            'connection',
+            event.connectionId.toString()
+        ]);
+    }
+    return JSON.stringify([
+        // Monitor `value` is event-specific: CONNECTION_READY reports the
+        // socket's ready count and DISCONNECTED reports its reason. It is not a
+        // connection identity. The public monitor record has no native
+        // connection id, so use the stable routing and endpoint tuple instead.
+        resolvedNodeRoutingId,
+        event.localAddress,
+        event.remoteAddress
+    ]);
+}
+function sameMonitorConnection(left, right) {
+    return monitorConnectionId(left) === monitorConnectionId(right)
+        && left.remoteAddress === right.remoteAddress;
+}
+function isConnectionReadyEdge(event) {
+    return event.flags === undefined
+        ? event.value > 0n
+        : (event.flags & MONITOR_CONNECTION_READY_EDGE) !== 0;
+}
+function describeInvalidAdmissionDescriptor(descriptor, expected, current) {
+    try {
+        (0, service_topology_registry_1.validateDescriptor)(descriptor);
+    }
+    catch (error) {
+        return `descriptor validation: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (expected?.endpoint !== undefined
+        && descriptor.advertisedEndpoint !== expected.endpoint) {
+        return `advertisedEndpoint expected='${expected.endpoint}' actual='${descriptor.advertisedEndpoint}'`;
+    }
+    if (expected?.securityIdentity !== undefined
+        && descriptor.securityIdentity !== expected.securityIdentity) {
+        return `securityIdentity expected='${expected.securityIdentity}' actual='${descriptor.securityIdentity}'`;
+    }
+    if (expected?.lifecycleGeneration !== undefined
+        && descriptor.lifecycleGeneration !== expected.lifecycleGeneration) {
+        return `lifecycleGeneration expected=${expected.lifecycleGeneration} actual=${descriptor.lifecycleGeneration}`;
+    }
+    if (current !== undefined
+        && current.lifecycleGeneration === descriptor.lifecycleGeneration
+        && descriptor.descriptorRevision > current.descriptorRevision) {
+        const immutableField = immutableDescriptorMismatch(current, descriptor);
+        if (immutableField !== undefined)
+            return immutableField;
+    }
+    return 'self routing id or immutable descriptor field';
+}
+function immutableDescriptorMismatch(current, descriptor) {
+    const fields = [
+        'advertisedEndpoint', 'securityIdentity', 'applicationVersion', 'objectRole',
+        'activeCapacityLimit', 'pendingCapacityLimit'
+    ];
+    for (const field of fields) {
+        if (current[field] !== descriptor[field]) {
+            return `${field} changed within lifecycle expected=${String(current[field])} actual=${String(descriptor[field])}`;
+        }
+    }
+    if (JSON.stringify(current.protocolCapabilities) !== JSON.stringify(descriptor.protocolCapabilities)) {
+        return `protocolCapabilities changed within lifecycle expected=${JSON.stringify(current.protocolCapabilities)} actual=${JSON.stringify(descriptor.protocolCapabilities)}`;
+    }
+    if (JSON.stringify(current.channels.map(channel => channel.name))
+        !== JSON.stringify(descriptor.channels.map(channel => channel.name))) {
+        return 'channels changed within lifecycle';
+    }
+    return undefined;
+}
+function admissionReason(result) {
+    switch (result) {
+        case 'meshMismatch':
+            return 2;
+        case 'staleDescriptor':
+            return 7;
+        case 'invalidDescriptor':
+            return 11;
+        case 'notRequired':
+            return 4;
+        case 'admitted':
+            return 1;
+    }
+}