@zlink-systems/framework 0.10.0

package/dist/runtime/host/remote-bound-session-relay.js

@@ -0,0 +1,540 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRemoteBoundSessionRelay = void 0;
+const actor_session_binding_runtime_owner_1 = require("../streams/actor-session-binding-runtime-owner");
+const submission_result_1 = require("../messaging/submission-result");
+const bound_session_wire_1 = require("../actors/bound-session-wire");
+const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
+const routing_id_1 = require("../routing-id");
+const service_stateful_wire_codec_1 = require("../foundation/service-stateful-wire-codec");
+const service_wire_m6a_codec_1 = require("../foundation/service-wire-m6a-codec");
+const bounded_replay_map_1 = require("./bounded-replay-map");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const SERVICE_CONTROL_TERMINAL_CAPACITY = 4096;
+class ZLinkRemoteBoundSessionRelay {
+    options;
+    actorOwnershipGenerations = new Map();
+    activeServiceWireRelocations = new Map();
+    terminalServiceWireRelocations = new bounded_replay_map_1.BoundedReplayMap(SERVICE_CONTROL_TERMINAL_CAPACITY);
+    constructor(options) {
+        this.options = options;
+    }
+    async receiveRoutedBoundSession(actorId, message, packetName, metadata, actorRef, actorPacketTarget) {
+        const ownershipGeneration = actorRef
+            ?.ownershipGeneration;
+        const currentGeneration = this.actorOwnershipGenerations.get(actorId);
+        if (currentGeneration !== undefined &&
+            (ownershipGeneration === undefined || ownershipGeneration < currentGeneration))
+            return;
+        if (ownershipGeneration !== undefined) {
+            this.actorOwnershipGenerations.set(actorId, ownershipGeneration);
+        }
+        await this.options.updateRemoteActorPacketTarget(actorId, actorPacketTarget);
+        if (ownershipGeneration !== undefined
+            && this.actorOwnershipGenerations.get(actorId) !== ownershipGeneration)
+            return;
+        if (actorRef !== undefined) {
+            await this.options.streamBindingRuntime().rebindActor(actorRef);
+        }
+        if (ownershipGeneration !== undefined
+            && this.actorOwnershipGenerations.get(actorId) !== ownershipGeneration)
+            return;
+        const sent = await this.options.streamBindingRuntime().sendLocalBoundSession(actorId, message, packetName, metadata);
+        if (sent) {
+            return;
+        }
+        if (ownershipGeneration !== undefined
+            && this.actorOwnershipGenerations.get(actorId) !== ownershipGeneration)
+            return;
+        if (this.options.actorManager()?.getState(actorId)?.remoteBoundSessionTarget === undefined) {
+            return;
+        }
+        const call = this.options.boundSessionFactory(actorId).send(message);
+        if (packetName !== undefined) {
+            call.packetName(packetName);
+        }
+        for (const [key, value] of metadata) {
+            call.metadata(key, value);
+        }
+        await call.submit();
+    }
+    async receiveRoutedBoundSessionResponse(actorId, packetName, requestSeq, message, replyOptions, actorPacketTarget) {
+        await this.options.updateRemoteActorPacketTarget(actorId, actorPacketTarget);
+        await this.options.streamBindingRuntime().sendLocalBoundSessionResponse(actorId, packetName, requestSeq, message, replyOptions.metadata, replyOptions.compressPayload);
+    }
+    async receiveRoutedBoundSessionError(actorId, packetName, requestSeq, error, metadata, actorPacketTarget) {
+        await this.options.updateRemoteActorPacketTarget(actorId, actorPacketTarget);
+        await this.options.streamBindingRuntime().sendLocalBoundSessionError(actorId, packetName, requestSeq, error, metadata);
+    }
+    async receiveRemoteBoundSessionSend(payload) {
+        const send = (0, bound_session_wire_1.decodeRemoteBoundSessionSendPayload)(payload);
+        await this.options.updateRemoteActorPacketTarget(send.actorId, send.actorPacketTarget);
+        const owner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwnerIfRegistered)(this.options.streamBindingRuntime());
+        const retained = await owner?.retainRelocationOutbound(send.actorId, {
+            deliver: () => this.deliverRemoteBoundSessionSend(send),
+            fail: error => this.options.reportOwnershipRefreshError?.(send.actorId, error)
+        }, send.relocationSealId);
+        if (retained === 'retained')
+            return { ok: true };
+        if (retained === 'rejected')
+            return { ok: false };
+        return { ok: await this.deliverRemoteBoundSessionSend(send) };
+    }
+    async deliverRemoteBoundSessionSend(send) {
+        const metadata = new Map(Object.entries(send.metadata ?? {}));
+        if (await this.options.streamBindingRuntime().sendLocalBoundSession(send.actorId, send.message, send.boundPacketName, metadata)) {
+            return true;
+        }
+        if (this.options.actorManager()?.getState(send.actorId)?.remoteBoundSessionTarget === undefined) {
+            return false;
+        }
+        const call = this.options.boundSessionFactory(send.actorId).send(send.message);
+        if (send.boundPacketName !== undefined) {
+            call.packetName(send.boundPacketName);
+        }
+        for (const [key, value] of metadata) {
+            call.metadata(key, value);
+        }
+        await call.submit();
+        return true;
+    }
+    async receiveRemoteBoundSessionResponse(payload) {
+        const response = (0, bound_session_wire_1.decodeRemoteBoundSessionResponsePayload)(payload);
+        await this.options.updateRemoteActorPacketTarget(response.actorId, response.actorPacketTarget);
+        const sent = await this.options.streamBindingRuntime().sendLocalBoundSessionResponse(response.actorId, response.boundPacketName, response.requestSeq, response.message, new Map(Object.entries(response.metadata ?? {})), response.compressPayload);
+        return { ok: sent };
+    }
+    async receiveRemoteBoundSessionError(payload) {
+        const response = (0, bound_session_wire_1.decodeRemoteBoundSessionErrorPayload)(payload);
+        await this.options.updateRemoteActorPacketTarget(response.actorId, response.actorPacketTarget);
+        const sent = await this.options.streamBindingRuntime().sendLocalBoundSessionError(response.actorId, response.boundPacketName, response.requestSeq, response.error, new Map(Object.entries(response.metadata ?? {})));
+        return { ok: sent };
+    }
+    async receiveServiceWireSessionRelocationSeal(value, signal) {
+        const key = serviceWireBarrierKey(value);
+        const fingerprint = (0, service_stateful_wire_codec_1.encodeSessionRelocationSeal)(value).toString('base64');
+        const terminal = this.terminalServiceWireRelocations.get(key);
+        if (terminal !== undefined) {
+            if (terminal.sealFingerprint !== fingerprint) {
+                throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${key}' repeated command 42 with different bytes.`);
+            }
+            this.terminalServiceWireRelocations.touch(key);
+            return terminal.sealed;
+        }
+        const active = this.activeServiceWireRelocations.get(key);
+        if (active !== undefined) {
+            if (active.sealFingerprint !== fingerprint) {
+                throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${key}' repeated command 42 with different bytes.`);
+            }
+            return await active.sealPromise;
+        }
+        const actorId = value.actor.actor.actorId;
+        // Register the identity before the first asynchronous owner operation.
+        // Concurrent identical commands join this promise; different bytes for
+        // the same identity fail before they can install another seal.
+        let state;
+        const sealController = new AbortController();
+        const sealPromise = Promise.resolve().then(async () => {
+            await this.validateServiceWireSessionRoute(value);
+            await (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.streamBindingRuntime()).sealRelocation({
+                actorId,
+                actorGeneration: value.actor.actor.generation,
+                bindingGeneration: value.session.bindingGeneration,
+                sessionIdentity: value.session.sessionRid,
+                actorNodeRid: value.actor.actor.nodeRid,
+                actorNodeGeneration: value.actor.targetNodeGeneration,
+                sealId: key
+            }, {
+                objectGeneration: value.actor.actor.generation,
+                bindingGeneration: value.session.bindingGeneration
+            }, sealController.signal);
+            return {
+                relocation: value.relocation,
+                coordinator: value.coordinator,
+                actor: value.actor,
+                session: value.session
+            };
+        });
+        state = {
+            actorId,
+            sealFingerprint: fingerprint,
+            sealPromise,
+            sealController
+        };
+        this.activeServiceWireRelocations.set(key, state);
+        const expire = async (error) => {
+            if (state.terminal === true || state.routePromise !== undefined)
+                return;
+            state.terminal = true;
+            sealController.abort(error);
+            if (this.activeServiceWireRelocations.get(key) === state) {
+                this.activeServiceWireRelocations.delete(key);
+            }
+            if (state.sealed !== undefined) {
+                this.terminalServiceWireRelocations.remember(key, {
+                    actorId,
+                    sealFingerprint: state.sealFingerprint,
+                    sealed: state.sealed
+                });
+            }
+            const owner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.streamBindingRuntime());
+            await owner.clearRelocation(actorId, error);
+            void this.options.streamBindingRuntime().disconnectBoundSession(actorId)
+                .catch(disconnectError => this.options.reportOwnershipRefreshError?.(actorId, disconnectError));
+            state.sealAbortCleanup?.();
+        };
+        const timeoutError = () => (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor '${actorId}' Session relocation seal exceeded its absolute deadline.`, true);
+        state.sealTimer = setTimeout(() => { void expire(timeoutError()); }, this.options.sessionRelocationSealTimeoutMs);
+        state.sealTimer.unref();
+        if (signal !== undefined) {
+            const onAbort = () => { void expire(signal.reason ?? timeoutError()); };
+            state.sealAbortCleanup = () => signal.removeEventListener('abort', onAbort);
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+        try {
+            const sealed = await sealPromise;
+            state.sealed = sealed;
+            return sealed;
+        }
+        catch (error) {
+            clearTimeout(state.sealTimer);
+            state.sealAbortCleanup?.();
+            if (this.activeServiceWireRelocations.get(key) === state) {
+                this.activeServiceWireRelocations.delete(key);
+            }
+            if (state.terminal !== true) {
+                const owner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.streamBindingRuntime());
+                if (await owner.relocationSnapshot(actorId, key) !== undefined) {
+                    await owner.clearRelocation(actorId, error);
+                    void this.options.streamBindingRuntime().disconnectBoundSession(actorId)
+                        .catch(disconnectError => this.options.reportOwnershipRefreshError?.(actorId, disconnectError));
+                }
+            }
+            throw sealController.signal.aborted ? sealController.signal.reason : error;
+        }
+    }
+    async receiveServiceWireSessionRelocationRoute(value) {
+        const key = serviceWireBarrierKey(value);
+        const routeRequestFingerprint = (0, service_stateful_wire_codec_1.encodeSessionRelocationRoute)(value).toString('base64');
+        const fingerprint = routeRequestFingerprint;
+        const terminal = this.terminalServiceWireRelocations.get(key);
+        if (terminal !== undefined) {
+            if (terminal.routeFingerprint === undefined) {
+                // The Session owner already closed this binding at the seal deadline.
+                // A late command 44 is terminal and cannot reactivate the route.
+                this.terminalServiceWireRelocations.touch(key);
+                this.warnLateSessionRouteUpdate(value);
+                return;
+            }
+            if (terminal.routeFingerprint !== fingerprint) {
+                throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${key}' repeated command 44 with different bytes.`);
+            }
+            this.terminalServiceWireRelocations.touch(key);
+            this.warnLateSessionRouteUpdate(value);
+            return;
+        }
+        const state = this.activeServiceWireRelocations.get(key);
+        if (state === undefined) {
+            await (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.streamBindingRuntime()).discardRelocationOutbound(value.actor.actorId, key, new bound_session_wire_1.ZLinkRemoteBoundSessionFenceError(`Actor '${value.actor.actorId}' command 44 did not match an active command 42.`));
+            this.warnLateSessionRouteUpdate(value);
+            return;
+        }
+        if (state.routeRequestFingerprint !== undefined
+            && state.routeRequestFingerprint !== routeRequestFingerprint) {
+            throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${key}' repeated command 44 with different bytes.`);
+        }
+        if (state.routeFingerprint !== undefined) {
+            if (state.routeFingerprint !== fingerprint || state.routePromise === undefined) {
+                throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${key}' repeated command 44 with different bytes.`);
+            }
+            this.warnLateSessionRouteUpdate(value);
+            await state.routePromise;
+            return;
+        }
+        state.routeRequestFingerprint = routeRequestFingerprint;
+        state.routeFingerprint = fingerprint;
+        if (state.sealTimer !== undefined)
+            clearTimeout(state.sealTimer);
+        state.sealAbortCleanup?.();
+        const routePromise = state.sealPromise.then(async (sealed) => {
+            validateSessionRelocationRouteAgainstSeal(value, sealed);
+            await this.applyServiceWireSessionRelocationRoute(key, value);
+        });
+        state.routePromise = routePromise;
+        try {
+            await routePromise;
+            this.terminalServiceWireRelocations.remember(key, {
+                actorId: state.actorId,
+                sealFingerprint: state.sealFingerprint,
+                sealed: state.sealed ?? await state.sealPromise,
+                routeRequestFingerprint,
+                routeFingerprint: fingerprint
+            });
+            if (this.activeServiceWireRelocations.get(key) === state) {
+                this.activeServiceWireRelocations.delete(key);
+            }
+            state.terminal = true;
+        }
+        catch (error) {
+            // Command 44 is one-way. Once an exact update wins the timeout race,
+            // an apply failure cannot be repaired by waiting for an ACK-driven
+            // retry. Close the physical Session and terminalize this identity so a
+            // late duplicate cannot reactivate the binding or its held messages.
+            state.terminal = true;
+            if (this.activeServiceWireRelocations.get(key) === state) {
+                this.activeServiceWireRelocations.delete(key);
+            }
+            const sealed = state.sealed ?? await state.sealPromise;
+            this.terminalServiceWireRelocations.remember(key, {
+                actorId: state.actorId,
+                sealFingerprint: state.sealFingerprint,
+                sealed,
+                routeRequestFingerprint,
+                routeFingerprint: fingerprint
+            });
+            (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.streamBindingRuntime())
+                .clearRelocation(state.actorId, error);
+            await this.options.streamBindingRuntime().disconnectBoundSession(state.actorId)
+                .catch(disconnectError => this.options.reportOwnershipRefreshError?.(state.actorId, disconnectError));
+            throw error;
+        }
+    }
+    clearServiceWireSessionRelocations() {
+        for (const state of this.activeServiceWireRelocations.values()) {
+            if (state.sealTimer !== undefined)
+                clearTimeout(state.sealTimer);
+        }
+        this.activeServiceWireRelocations.clear();
+        this.terminalServiceWireRelocations.clear();
+    }
+    warnLateSessionRouteUpdate(value) {
+        console.warn(`late_session_route_update session=${value.session.sessionRid}`);
+    }
+    async applyServiceWireSessionRelocationRoute(key, value) {
+        const runtime = this.options.streamBindingRuntime();
+        const owner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(runtime);
+        const fingerprint = (0, service_stateful_wire_codec_1.encodeSessionRelocationRoute)(value).toString('base64');
+        if (value.route.action === 'abort') {
+            await owner.applyRelocation(value.actor.actorId, key, fingerprint, 'abort', async () => {
+                if (!(await runtime.abortActorRouteSeal(value.actor.actorId, key))) {
+                    throw new bound_session_wire_1.ZLinkRemoteBoundSessionFenceError(`Actor '${value.actor.actorId}' command 44 abort lost its Session seal.`);
+                }
+            });
+        }
+        else {
+            const committedRoute = value.route;
+            const current = (await runtime.find(value.actor.actorId))?.ref;
+            if (current === undefined || current.objectGeneration !== value.actor.generation) {
+                throw new bound_session_wire_1.ZLinkRemoteBoundSessionFenceError(`Actor '${value.actor.actorId}' command 44 has no exact Session binding.`);
+            }
+            const targetActorRef = {
+                actorId: value.actor.actorId,
+                objectGeneration: value.actor.generation,
+                meshName: current.meshName,
+                nodeRid: (0, routing_id_1.decodeRoutingId)(committedRoute.targetNodeRid, undefined),
+                bindingGeneration: value.session.bindingGeneration,
+                ownershipGeneration: committedRoute.targetAuthorityOwnerGeneration,
+                ownerNodeGeneration: committedRoute.targetNodeGeneration
+            };
+            await owner.applyRelocation(value.actor.actorId, key, fingerprint, 'commit', async () => {
+                await runtime.commitActorRoute(targetActorRef, undefined, {
+                    confirmRemoteSessionBinding: 'send',
+                    releaseSeal: { sealId: key }
+                });
+                const currentGeneration = this.actorOwnershipGenerations.get(value.actor.actorId);
+                if (currentGeneration === undefined
+                    || currentGeneration < committedRoute.targetAuthorityOwnerGeneration) {
+                    this.actorOwnershipGenerations.set(value.actor.actorId, committedRoute.targetAuthorityOwnerGeneration);
+                }
+            });
+        }
+        await owner.observeRelocationTerminal(value.actor.actorId, key, fingerprint);
+    }
+    async validateServiceWireSessionRoute(value) {
+        const current = await this.options.streamBindingRuntime().sessionRouteFence(value.actor.actor.actorId);
+        if (current === undefined
+            || current.actor.objectGeneration !== value.actor.actor.generation
+            || !(0, routing_id_1.routingIdsEqual)(current.actor.nodeRid, value.actor.actor.nodeRid)
+            || current.sessionRid.toString() !== value.session.sessionRid
+            || current.bindingGeneration !== value.session.bindingGeneration) {
+            throw new bound_session_wire_1.ZLinkRemoteBoundSessionFenceError(`Actor '${value.actor.actor.actorId}' command 42 was fenced by its exact Session route.`);
+        }
+    }
+    rememberRemoteBoundSessionTarget(actorId, target) {
+        this.options.actorManager()?.getState(actorId)?.setRemoteBoundSessionTarget(target);
+    }
+    resolveRemoteBoundSessionTarget(sourceNodeRid, sourceSessionRid) {
+        const target = this.options.meshRouters.remoteBoundSessionTargetForSource(sourceNodeRid);
+        if (target === undefined)
+            return undefined;
+        // Spec 48 §116/§153/§324-332: the source Session's identity travels with
+        // the bind refresh so a later refresh can tell a same-Session
+        // coordinate-only update apart from a successor binding (a new Session
+        // never inherits the previous Session's staged relocation fence). The
+        // topology resolver stays identity-agnostic; identity is attached here,
+        // at the bind-refresh producer.
+        return {
+            ...target,
+            sessionNodeRid: sourceNodeRid,
+            sessionRid: sourceSessionRid
+        };
+    }
+    actorPacketTargetForState(actorId, routerChannelIdHint) {
+        return this.options.actorPacketTargetForState(actorId, routerChannelIdHint);
+    }
+    clearOwnership(actorId) {
+        this.actorOwnershipGenerations.delete(actorId);
+        (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwnerIfRegistered)(this.options.streamBindingRuntime())?.clearRelocation(actorId, new Error(`Actor '${actorId}' ownership state was cleared.`));
+        for (const [key, value] of this.activeServiceWireRelocations) {
+            if (value.actorId === actorId) {
+                if (value.sealTimer !== undefined)
+                    clearTimeout(value.sealTimer);
+                this.activeServiceWireRelocations.delete(key);
+            }
+        }
+        for (const [key, value] of this.terminalServiceWireRelocations) {
+            if (value.actorId === actorId)
+                this.terminalServiceWireRelocations.delete(key);
+        }
+    }
+    async sendActorResponse(actor, packetName, requestSeq, response, replyOptions, fallbackBoundSessionTarget, fallbackActorRef, signal) {
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        if (await this.options.streamBindingRuntime().sendLocalBoundSessionResponse(actor.context.actorId, packetName, requestSeq, response, replyOptions.metadata, replyOptions.compressPayload)) {
+            return;
+        }
+        const actorRef = currentActorRef(state, fallbackActorRef);
+        const remoteTarget = fallbackBoundSessionTarget ?? state?.remoteBoundSessionTarget;
+        if (remoteTarget !== undefined) {
+            await this.sendRemoteBoundSessionResponse(remoteTarget, actor.context.actorId, packetName, requestSeq, response, replyOptions, signal);
+            return;
+        }
+        if (actorRef === undefined) {
+            throw new Error(`Actor '${actor.context.actorId}' does not have a native actor ref.`);
+        }
+        const actorSessionNode = this.options.actorSessionNode?.(actor.context.actorId);
+        if (actorSessionNode === undefined) {
+            throw new Error('Native bound-session response requires the RouteMesh stream-session service.');
+        }
+        await this.options.streamBindingRuntime().sendNativeBoundSessionResponse(actorSessionNode, actorRef, packetName, requestSeq, response, replyOptions.metadata, replyOptions.compressPayload, signal);
+    }
+    async sendActorError(actorId, packetName, requestSeq, error, metadata, fallbackBoundSessionTarget, fallbackActorRef, signal) {
+        if (await this.options.streamBindingRuntime().sendLocalBoundSessionError(actorId, packetName, requestSeq, error, metadata)) {
+            return;
+        }
+        const state = this.options.actorManager()?.getState(actorId);
+        const actorRef = currentActorRef(state, fallbackActorRef)
+            ?? this.options.destroyedActorRefs.get(actorId);
+        const remoteTarget = fallbackBoundSessionTarget ?? state?.remoteBoundSessionTarget;
+        if (remoteTarget !== undefined) {
+            await this.sendRemoteBoundSessionError(remoteTarget, actorId, packetName, requestSeq, error, metadata, signal);
+            return;
+        }
+        if (actorRef === undefined) {
+            throw new Error(`Actor '${actorId}' does not have a native actor ref.`);
+        }
+        const actorSessionNode = this.options.actorSessionNode?.(actorId);
+        if (actorSessionNode === undefined) {
+            throw new Error('Native bound-session error response requires the RouteMesh stream-session service.');
+        }
+        await this.options.streamBindingRuntime().sendNativeBoundSessionError(actorSessionNode, actorRef, packetName, requestSeq, error, metadata, signal);
+    }
+    async sendRemoteBoundSessionResponse(target, actorId, packetName, requestSeq, message, replyOptions, signal) {
+        const actorPacketTarget = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.options.actorPacketTargetForState(actorId, target.routerChannelId));
+        await this.sendRemoteBoundSessionControl(target, (0, bound_session_wire_1.encodeRemoteBoundSessionResponsePayload)({
+            actorId,
+            boundPacketName: packetName,
+            requestSeq,
+            message,
+            metadata: replyOptions.metadata,
+            compressPayload: replyOptions.compressPayload,
+            actorPacketTarget
+        }), signal);
+    }
+    async sendRemoteBoundSessionError(target, actorId, packetName, requestSeq, error, metadata, signal) {
+        await this.sendRemoteBoundSessionControl(target, (0, bound_session_wire_1.encodeRemoteBoundSessionErrorPayload)({
+            actorId,
+            boundPacketName: packetName,
+            requestSeq,
+            error,
+            metadata,
+            actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.options.actorPacketTargetForState(actorId, target.routerChannelId))
+        }), signal);
+    }
+    async sendRemoteBoundSessionControl(target, payload, signal) {
+        const packetName = payload.packetName;
+        if (typeof packetName !== 'string') {
+            throw new Error('Remote bound session control payload does not declare a packet name.');
+        }
+        const submit = this.options.routeTransport.submitInfrastructure
+            ?? this.options.routeTransport.submit;
+        if (submit === undefined) {
+            throw new Error('Remote bound session node-direct transport is not available.');
+        }
+        const result = await submit.call(this.options.routeTransport, target.routerChannelId, String(target.targetNodeRid), packetName, payload, signal);
+        if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
+            throw new Error(`Remote bound session control '${packetName}' was not admitted`
+                + ` on '${target.routerChannelId}' for '${String(target.targetNodeRid)}'`
+                + ` (status ${result.status}).`);
+        }
+    }
+}
+exports.ZLinkRemoteBoundSessionRelay = ZLinkRemoteBoundSessionRelay;
+function currentActorRef(state, fallback) {
+    const native = state?.nativeActorRef;
+    if (native === undefined)
+        return fallback;
+    const objectGeneration = native.generation
+        ?? native.objectGeneration
+        ?? fallback?.objectGeneration;
+    const meshName = state?.meshName ?? fallback?.meshName;
+    if (objectGeneration === undefined || meshName === undefined)
+        return fallback;
+    return {
+        actorId: native.actorId,
+        objectGeneration,
+        meshName,
+        nodeRid: native.nodeRid,
+        ownershipGeneration: state?.locationGeneration,
+        ownerLeaseGeneration: state?.ownerLeaseGeneration,
+        bindingGeneration: state?.boundSessionBindingGeneration
+    };
+}
+function serviceWireBarrierKey(value) {
+    return (0, service_stateful_wire_codec_1.serviceSessionRelocationIdentityKey)(value);
+}
+function validateSessionRelocationRouteAgainstSeal(route, sealed) {
+    const sameCoordinator = route.coordinator.ownerId === sealed.coordinator.ownerId
+        && route.coordinator.leaseGeneration === sealed.coordinator.leaseGeneration
+        && route.coordinator.nodeRid === sealed.coordinator.nodeRid
+        && route.coordinator.nodeGeneration === sealed.coordinator.nodeGeneration
+        && route.coordinator.expectedAuthorityStoreVersion
+            === sealed.coordinator.expectedAuthorityStoreVersion;
+    const sameSession = route.session.sessionOwnerNodeRid === sealed.session.sessionOwnerNodeRid
+        && route.session.sessionOwnerNodeGeneration === sealed.session.sessionOwnerNodeGeneration
+        && route.session.sessionOwnerId === sealed.session.sessionOwnerId
+        && route.session.sessionOwnerLeaseGeneration
+            === sealed.session.sessionOwnerLeaseGeneration
+        && route.session.sessionRid === sealed.session.sessionRid
+        && route.session.bindingGeneration === sealed.session.bindingGeneration;
+    if (route.relocation.high !== sealed.relocation.high
+        || route.relocation.low !== sealed.relocation.low
+        || !sameCoordinator
+        || !sameSession
+        || route.actor.actorId !== sealed.actor.actor.actorId
+        || route.actor.generation !== sealed.actor.actor.generation) {
+        throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${serviceWireBarrierKey(route)}' changed its command 42 fence.`);
+    }
+    if (route.route.action === 'commit') {
+        if (route.route.previousAuthorityOwnerGeneration
+            !== sealed.actor.authorityOwnerGeneration) {
+            throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${serviceWireBarrierKey(route)}' changed its source authority fence.`);
+        }
+        return;
+    }
+    if (route.route.currentAuthorityOwnerGeneration !== sealed.actor.authorityOwnerGeneration) {
+        throw new service_wire_m6a_codec_1.ServiceWireProtocolError(`Session relocation '${serviceWireBarrierKey(route)}' abort changed its authority fence.`);
+    }
+}

package/dist/runtime/host/route-mesh-runtime-options.d.ts

@@ -0,0 +1,9 @@
+import type { ZLinkMeshChannelRuntimeOptions, ZLinkMeshPlacementRuntimeOptions, ZLinkRouteMeshRuntimeOptions } from '../../contracts';
+import type { ZLinkSpotNodeRuntimeManager } from '../spots';
+export declare class DefaultZLinkRouteMeshRuntimeOptions implements ZLinkRouteMeshRuntimeOptions {
+    private readonly manager;
+    constructor(manager: () => ZLinkSpotNodeRuntimeManager | undefined);
+    mesh(meshName: string): ZLinkMeshPlacementRuntimeOptions;
+    channel(channelName: string): ZLinkMeshChannelRuntimeOptions;
+    private requireManager;
+}

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

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkRouteMeshRuntimeOptions = void 0;
+class DefaultZLinkRouteMeshRuntimeOptions {
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    mesh(meshName) {
+        const manager = this.requireManager();
+        manager.placementWeight(meshName);
+        return {
+            get placementWeight() {
+                return manager.placementWeight(meshName);
+            },
+            set placementWeight(weight) {
+                manager.setRuntimePlacementWeight(meshName, weight);
+            }
+        };
+    }
+    channel(channelName) {
+        const manager = this.requireManager();
+        manager.channelWeight(channelName);
+        return {
+            get weight() {
+                return manager.channelWeight(channelName);
+            },
+            set weight(weight) {
+                manager.setRuntimeChannelWeight(channelName, weight);
+            }
+        };
+    }
+    requireManager() {
+        const manager = this.manager();
+        if (manager === undefined) {
+            throw new Error('RouteMesh runtime options require a started Framework runtime.');
+        }
+        return manager;
+    }
+}
+exports.DefaultZLinkRouteMeshRuntimeOptions = DefaultZLinkRouteMeshRuntimeOptions;

package/dist/runtime/host/route-mesh-runtime.d.ts

@@ -0,0 +1,76 @@
+import { ZLinkFrameworkRuntimeState, type ZLinkObservedStatus, type ZLinkRouteMeshStatus, type ZLinkRouteMeshRuntime } from '../../contracts';
+type ZLinkDrainForceReason = 'deadline_exceeded' | 'drain_state_publish_failed' | 'owner_cleanup_failed' | 'teardown_failed';
+type ZLinkMeshDrainResult = {
+    readonly kind: 'drained';
+} | {
+    readonly kind: 'forceStopped';
+    readonly reason: ZLinkDrainForceReason;
+    readonly error?: unknown;
+};
+import type { ZLinkBackendMeshNode } from '../backend';
+import type { ZLinkRuntimeAdmissionGate } from '../admission';
+import type { ZLinkSpotNodeOptions } from '../configuration';
+import { type ZLinkMeshNodeDescriptor } from '../../contracts';
+export interface ZLinkRouteMeshRuntimeCoordinatorOptions {
+    readonly meshNames: readonly string[];
+    readonly meshOptions: ReadonlyMap<string, ZLinkSpotNodeOptions>;
+    readonly meshNode: (meshName: string) => ZLinkBackendMeshNode | undefined;
+    readonly meshNodeDescriptor?: (meshName: string) => ZLinkMeshNodeDescriptor | undefined;
+    readonly localPlacementCounts?: (meshName: string) => ZLinkLocalPlacementCounts | undefined;
+    readonly isLocationStoreHealthy?: () => boolean;
+    readonly hostState?: () => ZLinkFrameworkRuntimeState;
+    readonly admission: ZLinkRuntimeAdmissionGate;
+    readonly publishRetiring: (meshName: string, signal: AbortSignal) => Promise<void>;
+    readonly rollbackRetiring: (meshName: string, signal: AbortSignal) => Promise<void>;
+    readonly publishDraining: (meshName: string, signal: AbortSignal) => Promise<void>;
+    readonly publishHostDraining: (signal: AbortSignal) => Promise<void>;
+    readonly drainResources: (meshName: string, signal: AbortSignal, stopStartingSignal?: AbortSignal) => Promise<void>;
+    readonly shutdownResources?: (meshName: string, signal: AbortSignal) => Promise<void>;
+    readonly cleanupHostResources: (signal: AbortSignal) => Promise<void>;
+    readonly forceStopResources: (meshName: string) => Promise<void>;
+}
+export interface ZLinkLocalPlacementCounts {
+    readonly activeActorCount: number;
+    readonly activeSpotCount: number;
+}
+export declare class ZLinkRouteMeshRuntimeCoordinator implements ZLinkRouteMeshRuntime {
+    private readonly options;
+    private readonly states;
+    private readonly placementFingerprints;
+    private readonly peerFingerprints;
+    private readonly locationStoreHealthFingerprints;
+    private placementObserver?;
+    private hostOperation?;
+    private shutdownOperation?;
+    private hostRetiringPrepared;
+    constructor(options: ZLinkRouteMeshRuntimeCoordinatorOptions);
+    markServing(): void;
+    snapshot(meshName: string): ZLinkRouteMeshStatus;
+    observe(meshName: string, capacity?: number, signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkRouteMeshStatus>>;
+    isReady(meshName: string): boolean;
+    hostStateChanged(): void;
+    stopObservers(): void;
+    drain(meshName: string, deadlineMs?: number, signal?: AbortSignal): Promise<ZLinkMeshDrainResult>;
+    awaitDrained(meshName: string, signal?: AbortSignal): Promise<ZLinkMeshDrainResult>;
+    drainHost(deadlineMs?: number, signal?: AbortSignal): Promise<ZLinkMeshDrainResult>;
+    shutdownHost(deadline?: number | Date, signal?: AbortSignal, remainingTimeoutMs?: number): Promise<ZLinkMeshDrainResult>;
+    prepareHostRetire(deadlineMs: number): Promise<'prepared' | 'store_unavailable' | 'deadline_exceeded'>;
+    /**
+     * Relocates stateful resources without closing application transport.
+     * Shutdown owns admission sealing, peer/listener teardown and owner cleanup.
+     */
+    relocateHost(deadlineMs: number, stopStartingSignal?: AbortSignal): Promise<ZLinkMeshDrainResult>;
+    private performDrain;
+    private performHostDrain;
+    private performHostShutdown;
+    private transition;
+    private seedPlacementFingerprint;
+    private startPlacementObserver;
+    private stopPlacementObserverIfIdle;
+    private observePlacementChanges;
+    private requireState;
+}
+export declare class ZLinkRetiringRollbackError extends Error {
+    constructor();
+}
+export {};