@zlink-systems/framework 0.10.0

package/dist/runtime/host/actor-packet-relay.js

@@ -0,0 +1,664 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorPacketRelay = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const runtime_message_1 = require("../backend/runtime-message");
+const contracts_1 = require("../../contracts");
+const ConfigurationException_1 = require("../../contracts/Configuration/ConfigurationException");
+const actors_1 = require("../actors");
+const actor_runtime_state_1 = require("../actors/actor-runtime-state");
+const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
+const actor_routed_json_request_1 = require("../actors/actor-routed-json-request");
+const actor_message_follow_context_1 = require("../actors/actor-message-follow-context");
+const bound_session_wire_1 = require("../actors/bound-session-wire");
+const routing_id_1 = require("../routing-id");
+const submission_result_1 = require("../messaging/submission-result");
+const actor_session_binding_runtime_owner_1 = require("../streams/actor-session-binding-runtime-owner");
+const protocol_1 = require("../streams/protocol");
+const remote_actor_packet_target_store_1 = require("./remote-actor-packet-target-store");
+const REMOTE_SESSION_BIND_RETRY_DEADLINE_MS = 30_000;
+const REMOTE_SESSION_BIND_RETRY_INITIAL_DELAY_MS = 25;
+const REMOTE_SESSION_BIND_RETRY_MAX_DELAY_MS = 1_000;
+class ZLinkActorPacketRelay {
+    options;
+    targets;
+    constructor(options) {
+        this.options = options;
+        const spotRouterChannelIdByMesh = options.meshRouters.spotRouterChannelIdByMesh;
+        this.targets = new remote_actor_packet_target_store_1.ZLinkRemoteActorPacketTargetStore({
+            actorManager: options.actorManager,
+            streamBindingRuntime: options.streamBindingRuntime,
+            meshRouters: options.meshRouters,
+            primaryNodeRid: () => {
+                const node = options.spotNodeRuntime()?.primaryMeshNode;
+                return node === undefined ? undefined : String(node.status().routingId);
+            },
+            spotRouterChannelIdForMesh: spotRouterChannelIdByMesh?.call(options.meshRouters)
+                ?? ((meshName) => meshName)
+        });
+    }
+    async notifyBoundActorDisconnected(actor, signal) {
+        const state = this.options.actorManager()?.getState(actor.actorId);
+        const currentRemoteBoundSessionTarget = state?.spotId === undefined
+            ? undefined
+            : (0, actor_runtime_state_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget);
+        const currentRemoteActorPacketTarget = state?.spotId === undefined ? undefined : state.remoteActorPacketTarget;
+        const remoteTarget = currentRemoteBoundSessionTarget
+            ?? currentRemoteActorPacketTarget
+            ?? (state?.spotId === undefined ? undefined : this.targets.cachedTargetForActor(actor));
+        if (remoteTarget !== undefined) {
+            await this.notifyRemoteActorDisconnected(actor.actorId, remoteTarget, signal, actor.ref);
+            return;
+        }
+        const actorRefTarget = this.targets.targetForActorRef(actor.ref);
+        if (actorRefTarget !== undefined) {
+            await this.notifyRemoteActorDisconnected(actor.actorId, actorRefTarget, signal, actor.ref);
+            return;
+        }
+        if (state?.spotId !== undefined && state.actor !== undefined) {
+            const handled = await this.requireSpotManager().notifyJoinedSpotActorDisconnected(state.spotId, state.actor, signal);
+            if (handled) {
+                return;
+            }
+        }
+        await this.notifyActorDisconnectedById(actor.actorId, signal);
+    }
+    clearRemoteActorPacketTarget(actorId) {
+        this.targets.clear(actorId);
+    }
+    async updateRemoteActorPacketTarget(actorId, value) {
+        await this.targets.updateFromWire(actorId, value);
+    }
+    actorPacketTargetForState(actorId, routerChannelIdHint) {
+        return this.targets.targetForState(actorId, routerChannelIdHint);
+    }
+    async notifyActorDisconnectedById(actorId, signal) {
+        const state = this.options.actorManager()?.getState(actorId);
+        const remoteTarget = state === undefined
+            ? undefined
+            : (0, actor_runtime_state_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget) ?? state.remoteActorPacketTarget;
+        if (remoteTarget !== undefined) {
+            await this.notifyRemoteActorDisconnected(actorId, remoteTarget, signal);
+            return;
+        }
+        await this.notifyLocalActorDisconnectedById(actorId, signal);
+    }
+    async notifyLocalActorDisconnectedById(actorId, signal) {
+        const state = this.options.actorManager()?.getState(actorId);
+        if (state?.spotId !== undefined && state.actor !== undefined) {
+            const handled = await this.requireSpotManager().notifyJoinedSpotActorDisconnected(state.spotId, state.actor, signal);
+            if (handled) {
+                return;
+            }
+        }
+        const localActor = state?.actor;
+        if (localActor === undefined) {
+            throw new Error(`Actor '${actorId}' does not have a local actor instance.`);
+        }
+        const meshName = state?.meshName;
+        if (meshName === undefined) {
+            throw new Error(`Actor '${actorId}' does not have a RouteMesh identity.`);
+        }
+        await this.requireSpotNodeRuntime().notifyEntrySpotActorDisconnected(meshName, localActor, signal);
+    }
+    async receiveRemoteActorPacketRelay(payload, _routeContext) {
+        const relay = (0, actor_packet_relay_wire_1.decodeRemoteActorPacketRelayPayload)(payload);
+        const remoteBoundSessionTarget = relay.routerChannelId === undefined ||
+            relay.boundSessionTargetNodeRid === undefined ||
+            relay.boundSessionSpotId === undefined
+            ? undefined
+            : {
+                routerChannelId: relay.routerChannelId,
+                targetNodeRid: (0, routing_id_1.normalizeRoutingId)(relay.boundSessionTargetNodeRid),
+                spotId: (0, routing_id_1.normalizeRoutingId)(relay.boundSessionSpotId)
+            };
+        const header = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(relay.header, 'base64'));
+        const body = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(relay.payload, 'base64'));
+        let closeFrameMessages = true;
+        try {
+            const frameHeader = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(header), this.options.flowCreationEnabled?.() ?? true);
+            const messageFollowContext = relay.messageFollowContext;
+            if (messageFollowContext !== undefined) {
+                if (messageFollowContext.deadlineUnixMs !== undefined
+                    && Date.now() >= messageFollowContext.deadlineUnixMs) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${relay.actorId}' exceeded its Message Follow deadline.`);
+                }
+                (0, actor_message_follow_context_1.verifyActorMessageFollowPayload)(messageFollowContext, [header, body]);
+            }
+            const relayNodeRid = relay.actorNodeRid ?? relay.bindingActorNodeRid;
+            const relayNodeRidHex = relay.actorNodeRid === undefined
+                ? relay.bindingActorNodeRidHex
+                : relay.actorNodeRidHex;
+            const relayGeneration = relay.actorGeneration ?? relay.bindingActorGeneration;
+            const fallbackActorRef = relayNodeRid === undefined
+                || relayGeneration === undefined
+                ? undefined
+                : messageFollowContext === undefined
+                    ? {
+                        actorId: relay.actorId,
+                        objectGeneration: BigInt(relayGeneration),
+                        meshName: _routeContext.meshName,
+                        nodeRid: (0, routing_id_1.decodeRoutingId)(relayNodeRid, relayNodeRidHex),
+                        ...(relay.bindingGeneration === undefined
+                            ? {}
+                            : { bindingGeneration: BigInt(relay.bindingGeneration) })
+                    }
+                    : (0, actor_message_follow_context_1.attachActorMessageFollowContext)({
+                        actorId: relay.actorId,
+                        objectGeneration: BigInt(relayGeneration),
+                        meshName: _routeContext.meshName,
+                        nodeRid: (0, routing_id_1.decodeRoutingId)(relayNodeRid, relayNodeRidHex),
+                        ...(relay.bindingGeneration === undefined
+                            ? {}
+                            : { bindingGeneration: BigInt(relay.bindingGeneration) })
+                    }, messageFollowContext);
+            if (frameHeader.name === actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_SESSION_BIND_PACKET) {
+                if (frameHeader.kind !== protocol_1.ZLinkStreamMessageKind.Send) {
+                    throw new Error('Remote actor session binding requires a send frame.');
+                }
+                const { sessionNodeRid, sessionRid } = (0, actor_packet_relay_wire_1.decodeRemoteActorSessionBinding)((0, protocol_1.messageToBytes)(body));
+                if (!(0, routing_id_1.routingIdsEqual)(sessionNodeRid, _routeContext.sourceNodeRid)) {
+                    throw new Error('Remote actor session binding source did not match the declared session node.');
+                }
+                const state = this.options.actorManager()?.getState(relay.actorId);
+                const actorRef = state?.nativeActorRef;
+                if (state === undefined || actorRef === undefined) {
+                    throw new Error(`Actor '${relay.actorId}' does not have a concrete actor ref.`);
+                }
+                if (this.requireSpotNodeRuntime().primaryMeshNode === undefined) {
+                    throw new Error('MeshNode actor runtime is not started.');
+                }
+                const target = relay.routerChannelId === undefined
+                    ? this.options.meshRouters.remoteBoundSessionTargetForSource(sessionNodeRid)
+                    : {
+                        routerChannelId: relay.routerChannelId,
+                        targetNodeRid: sessionNodeRid,
+                        spotId: sessionNodeRid
+                    };
+                if (target === undefined) {
+                    throw new Error('Remote actor session binding did not declare a return router.');
+                }
+                const bindingGeneration = fallbackActorRef?.bindingGeneration;
+                const refreshedTarget = (0, actor_runtime_state_1.mergeRemoteBoundSessionTarget)({
+                    ...target,
+                    sessionNodeRid,
+                    sessionRid,
+                    ...(bindingGeneration === undefined ? {} : { bindingGeneration })
+                }, (0, actor_runtime_state_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget));
+                state.setRemoteBoundSessionTarget(refreshedTarget);
+                return { ok: true, response: { acknowledged: true } };
+            }
+            if (frameHeader.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+                this.requireCurrentRemoteBinding(relay, _routeContext);
+                this.options.actorManager()?.getState(relay.actorId)?.setRemoteBoundSessionTarget(undefined);
+                await this.notifyLocalActorDisconnectedById(relay.actorId);
+                return {
+                    ok: true,
+                    actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.actorPacketTargetForState(relay.actorId, relay.routerChannelId))
+                };
+            }
+            if (remoteBoundSessionTarget !== undefined) {
+                this.requireCurrentRemoteBinding(relay, _routeContext);
+            }
+            const state = this.options.actorManager()?.getState(relay.actorId);
+            if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send) {
+                const dispatch = state?.spotId === undefined
+                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
+                    : this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                // Spec 05 §1.3: a one-way Session Actor relay completes at relay
+                // queue admission, not after the remote application turn. In
+                // particular, a handler may register a deferred Join whose relocation
+                // seal must drain the ingress frame that triggered this relay. Keeping
+                // the route send open until that Join finalizes makes command 42 wait
+                // on the very Actor turn that is waiting for relocation. The Actor
+                // queue already owns the accepted frame here, so retain its messages
+                // and observe the ordered handler terminal on a detached runtime task.
+                closeFrameMessages = false;
+                this.options.detachedTaskRunner.runDetached('remote actor one-way packet relay', async () => {
+                    try {
+                        await dispatch;
+                    }
+                    catch (error) {
+                        this.options.errorSink().reportRuntimeTaskException('remote actor packet relay', error);
+                    }
+                    finally {
+                        header.close();
+                        body.close();
+                    }
+                });
+                return {
+                    ok: true,
+                    actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.actorPacketTargetForState(relay.actorId, relay.routerChannelId))
+                };
+            }
+            if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Request
+                && frameHeader.requestSeq !== undefined
+                && relay.returnResponse !== true) {
+                const dispatch = state?.spotId === undefined
+                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
+                    : this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                closeFrameMessages = false;
+                const deferredPacketName = frameHeader.name;
+                const deferredRequestSeq = frameHeader.requestSeq;
+                const deferredMetadata = frameHeader.metadata;
+                void dispatch.catch(async (error) => {
+                    //  Spec 32 §5 — an accepted Request must end in exactly one
+                    //  terminal completion. deferredResponse already told the source
+                    //  the reply will arrive on the bound-session route, so a routed
+                    //  dispatch REJECTED BEFORE DISPATCH (a closing/missing Spot
+                    //  throws ZLinkConfigurationException from activation resolution)
+                    //  must send its error there instead of only sinking it. Failures
+                    //  past that boundary already produce their own terminal through
+                    //  the inner actorErrorSender path — also sending here would emit
+                    //  a duplicate terminal for the same requestSeq.
+                    if (error instanceof ConfigurationException_1.ZLinkConfigurationException
+                        && this.options.actorErrorSender !== undefined) {
+                        try {
+                            await this.options.actorErrorSender(relay.actorId, deferredPacketName, deferredRequestSeq, error, deferredMetadata, remoteBoundSessionTarget, fallbackActorRef);
+                            return;
+                        }
+                        catch (sendFailure) {
+                            this.options.errorSink().reportRuntimeTaskException('remote actor packet relay error reply', sendFailure);
+                        }
+                    }
+                    this.options.errorSink().reportRuntimeTaskException('remote actor packet relay', error);
+                }).finally(() => {
+                    header.close();
+                    body.close();
+                });
+                return {
+                    ok: true,
+                    deferredResponse: true,
+                    actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.actorPacketTargetForState(relay.actorId, relay.routerChannelId))
+                };
+            }
+            const response = state?.spotId === undefined
+                ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef)
+                : await this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef);
+            return {
+                ok: true,
+                response,
+                actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.actorPacketTargetForState(relay.actorId, relay.routerChannelId))
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+                errorKind: error instanceof contracts_1.ZLinkFrameworkException
+                    ? (0, framework_errors_internal_1.internalFrameworkErrorKind)(error)
+                    : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed
+            };
+        }
+        finally {
+            if (closeFrameMessages) {
+                header.close();
+                body.close();
+            }
+        }
+    }
+    async relayActorPacket(actor, frameHeader, payload, signal) {
+        //  Spec 32:87 — a route/owner that is not currently usable is
+        //  Unavailable and retryable within the request deadline. Right after a
+        //  relocation the cached packet target can carry a transiently
+        //  incomplete Ready authority fence (route publication still
+        //  converging); failing the request on the fence check would surface a
+        //  NotFound for a Spot that exists and is Ready on its owner. Clear the
+        //  stale hint and re-resolve with a short bound instead.
+        const fenceRetryDeadlineMs = performance.now() + 1_000;
+        for (;;) {
+            try {
+                if (await this.relayRemoteActorPacket(actor, frameHeader, payload, signal)) {
+                    return true;
+                }
+                return await this.relayLocalActorPacket(actor, frameHeader, payload, signal);
+            }
+            catch (error) {
+                if (!(error instanceof Error
+                    && error.message.includes('no complete Ready authority fence'))
+                    || performance.now() >= fenceRetryDeadlineMs) {
+                    throw error;
+                }
+                this.targets.clear(actor.actorId);
+                this.options.actorManager()?.getState(actor.actorId)
+                    ?.setRemoteActorPacketTarget(undefined);
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+        }
+    }
+    async confirmRemoteSessionBinding(actor, sessionNodeRid, sessionRid, signal, options) {
+        const target = this.targets.targetForActorRef(actor);
+        if (target === undefined)
+            return;
+        const header = (0, protocol_1.encodeStreamHeader)({
+            kind: protocol_1.ZLinkStreamMessageKind.Send,
+            codec: protocol_1.ZLinkStreamCodec.Json,
+            flags: protocol_1.ZLinkStreamHeaderFlags.None,
+            name: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_SESSION_BIND_PACKET,
+            metadata: new Map()
+        });
+        const request = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
+            actorId: actor.actorId,
+            routerChannelId: target.routerChannelId,
+            boundSessionTargetNodeRid: String(sessionNodeRid),
+            boundSessionSpotId: String(sessionNodeRid),
+            bindingActorRef: actor,
+            header,
+            payload: (0, actor_packet_relay_wire_1.encodeRemoteActorSessionBinding)({ sessionNodeRid, sessionRid })
+        });
+        if (options?.waitForAcknowledgement === false) {
+            await this.retryRemoteSessionBindingSend(withDefaultSpotKind(target), request, performance.now() + REMOTE_SESSION_BIND_RETRY_DEADLINE_MS, REMOTE_SESSION_BIND_RETRY_INITIAL_DELAY_MS);
+            return;
+        }
+        const reply = await this.requestRemoteTarget(withDefaultSpotKind(target), request, `Remote actor session binding is not available for '${actor.actorId}'.`, (parts) => JSON.parse(parts[0]?.getString('utf8') ?? '{}'), signal);
+        if (reply.ok === false || (reply.response?.acknowledged !== true && reply.acknowledged !== true)) {
+            //  An {ok:false} (or unacknowledged) reply here is an immediate remote
+            //  rejection — the transport wait itself throws on timeout — so spec 32
+            //  reserves DeadlineExceeded for the deadline path and this reply
+            //  surfaces the remote failure's own classification instead: decode the
+            //  reply's errorKind when it carries a valid framework kind, else
+            //  RequestFailed, matching how other acknowledged relay replies map
+            //  {ok:false} (actorRelayError / remoteRelayErrorKind).
+            const remoteKind = Object.values(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind)
+                .includes(reply.errorKind)
+                ? reply.errorKind
+                : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(remoteKind, `Actor '${actor.actorId}' did not acknowledge its remote session binding: ${JSON.stringify(reply)}`, reply.error);
+        }
+    }
+    async retryRemoteSessionBindingSend(target, request, deadline, delayMs) {
+        try {
+            await this.options.routeTransport.sendToSpot(target, request, { packetName: actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET });
+        }
+        catch (error) {
+            if (performance.now() >= deadline) {
+                //  Spec 32-framework-error-model: DeadlineExceeded(7). Retry
+                //  exhaustion on the one-way bind send remains diagnostics-only but
+                //  the caller waits for its bounded submission terminal so later
+                //  application relay cannot overtake it.
+                this.options.errorSink().reportRuntimeTaskException('remote session binding send', (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, 'Remote actor session binding send retries exceeded their deadline.', error));
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+            await this.retryRemoteSessionBindingSend(target, request, deadline, Math.min(delayMs * 2, REMOTE_SESSION_BIND_RETRY_MAX_DELAY_MS));
+        }
+    }
+    async relayRemoteActorPacket(actor, frameHeader, payload, signal) {
+        const streamRuntime = this.options.streamBindingRuntime();
+        const responseTarget = await streamRuntime.captureBoundSessionResponseTarget(actor);
+        const localNode = this.options.spotNodeRuntime()?.primaryMeshNode;
+        const localNodeRid = localNode === undefined ? undefined : String(localNode.status().routingId);
+        const storedRoute = await streamRuntime.sessionRouteFence(actor.actorId);
+        const aggregateOwner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwnerIfRegistered)(streamRuntime);
+        const aggregateRoute = aggregateOwner === undefined
+            ? undefined
+            : await aggregateOwner.committedRoute(actor.actorId);
+        const storedActorRef = aggregateRoute?.actor ?? storedRoute?.actor ?? actor.ref;
+        const capturedTenureKey = this.targets.tenureKeyForActorRef(actor.actorId, storedActorRef);
+        if (localNodeRid !== undefined
+            && (0, routing_id_1.routingIdsEqual)(storedActorRef.nodeRid, localNodeRid)
+            && this.options.actorManager()?.getState(actor.actorId)?.actor !== undefined) {
+            return false;
+        }
+        const remoteTarget = this.options.actorManager()?.getState(actor.actorId)?.remoteActorPacketTarget
+            ?? this.targets.cachedTargetForActor(actor);
+        if (remoteTarget === undefined) {
+            return false;
+        }
+        // Session Actor relay is a one-way submit. The target sends a response or
+        // error through the bound-session route after its handler reaches a
+        // terminal state; the source stream must not wait for that handler.
+        const returnResponse = false;
+        const encodedHeader = (0, protocol_1.encodeStreamHeader)(frameHeader);
+        //  encodeStreamHeader returns a fresh, unaliased array; view it without re-copying.
+        const header = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(encodedHeader.buffer, encodedHeader.byteOffset, encodedHeader.byteLength));
+        let request;
+        try {
+            const authority = aggregateRoute?.authorityFence;
+            const messageFollowContext = authority?.ownerId === undefined
+                || authority.ownerNodeGeneration === undefined
+                ? undefined
+                : (0, actor_message_follow_context_1.createInitialActorMessageFollowContext)({
+                    meshName: storedActorRef.meshName,
+                    actorRef: storedActorRef,
+                    actorType: authority.actorType ?? '',
+                    ownerNodeGeneration: authority.ownerNodeGeneration,
+                    ownerId: authority.ownerId,
+                    ownerLeaseGeneration: authority.ownerLeaseGeneration,
+                    authorityOwnerGeneration: authority.authorityOwnerGeneration,
+                    authorityStoreVersion: authority.authorityStoreVersion ?? ''
+                }, [header, payload], returnResponse, undefined, isValidMessageFollowId(frameHeader.correlationId)
+                    ? frameHeader.correlationId
+                    : (0, actor_message_follow_context_1.createMessageFollowId)());
+            request = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
+                actorId: actor.actorId,
+                routerChannelId: remoteTarget.routerChannelId,
+                boundSessionTargetNodeRid: localNodeRid === undefined ? undefined : String(localNodeRid),
+                boundSessionSpotId: localNodeRid === undefined ? undefined : String(localNodeRid),
+                bindingActorRef: storedActorRef,
+                header: (0, protocol_1.messageToBytes)(header),
+                payload: (0, protocol_1.messageToBytes)(payload),
+                returnResponse,
+                actorRef: storedActorRef,
+                messageFollowContext
+            });
+        }
+        finally {
+            header.close();
+        }
+        const remoteAddress = {
+            ...remoteTarget,
+            routerChannelId: remoteTarget.routerChannelId,
+            targetNodeRid: remoteTarget.targetNodeRid,
+            spotId: remoteTarget.spotId,
+            spotKind: remoteTarget.spotKind ?? contracts_1.ZLinkSpotKind.User
+        };
+        if ((frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send || frameHeader.requestSeq === undefined)
+            && remoteAddress.spotKind === contracts_1.ZLinkSpotKind.Entry
+            && this.options.routeTransport.submit !== undefined) {
+            const result = await this.options.routeTransport.submit(remoteAddress.routerChannelId, String(remoteAddress.targetNodeRid), actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, request, signal);
+            if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
+                throw new Error(`Actor '${actor.actorId}' remote node relay was not admitted.`);
+            }
+            return true;
+        }
+        if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send || frameHeader.requestSeq === undefined) {
+            await this.options.routeTransport.sendToSpot(remoteAddress, request, {
+                packetName: actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+                signal
+            });
+            return true;
+        }
+        let reply;
+        reply = await this.requestRemoteTarget(remoteAddress, request, `Remote actor packet relay raw request is not available for '${actor.actorId}'.`, (parts) => {
+            if (parts.length === 0) {
+                throw new Error(`Remote actor packet relay reply was empty for '${actor.actorId}'.`);
+            }
+            return JSON.parse(parts[0].getString('utf8'));
+        }, signal);
+        const actorPacketTarget = this.targets.decodeFromWire(reply.actorPacketTarget);
+        const currentStoredRoute = await streamRuntime.sessionRouteFence(actor.actorId);
+        const currentAggregateRoute = aggregateOwner === undefined
+            ? undefined
+            : await aggregateOwner.committedRoute(actor.actorId);
+        const currentActorRef = currentAggregateRoute?.actor ?? currentStoredRoute?.actor ?? actor.ref;
+        const currentTenure = this.targets.tenureKeyForActorRef(actor.actorId, currentActorRef)
+            === capturedTenureKey;
+        if (currentTenure
+            && this.targets.tenureKeyForActor(actor) === capturedTenureKey
+            &&
+                actorPacketTarget !== undefined &&
+            (localNodeRid === undefined || !(0, routing_id_1.routingIdsEqual)(actorPacketTarget.targetNodeRid, localNodeRid))) {
+            this.targets.rememberActorTarget(actor, actorPacketTarget, capturedTenureKey);
+        }
+        else if (currentTenure && reply.ok !== false) {
+            this.targets.clear(actor.actorId, capturedTenureKey, actor);
+        }
+        if (reply.deferredResponse === true && reply.ok !== false) {
+            return true;
+        }
+        if (reply.ok === false) {
+            const sent = await this.sendCapturedOrCurrentBoundSessionError(responseTarget, actor.actorId, frameHeader.name, frameHeader.requestSeq, reply.error ?? 'Remote actor request failed.', (0, bound_session_wire_1.streamMetadataMap)(frameHeader.metadata));
+            if (!sent) {
+                throw new Error(`Actor '${actor.actorId}' local bound session error response route is not ready.`);
+            }
+            return true;
+        }
+        const sent = await this.sendCapturedOrCurrentBoundSessionResponse(responseTarget, actor.actorId, frameHeader.name, frameHeader.requestSeq, reply.response, (0, bound_session_wire_1.streamMetadataMap)(frameHeader.metadata));
+        if (!sent) {
+            throw new Error(`Actor '${actor.actorId}' local bound session response route is not ready.`);
+        }
+        return true;
+    }
+    async notifyRemoteActorDisconnected(actorId, remoteTarget, signal, bindingActorRef) {
+        const spotKind = 'spotKind' in remoteTarget ? remoteTarget.spotKind : undefined;
+        const header = {
+            kind: protocol_1.ZLinkStreamMessageKind.Send,
+            codec: protocol_1.ZLinkStreamCodec.Raw,
+            flags: protocol_1.ZLinkStreamHeaderFlags.None,
+            name: actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
+            metadata: new Map()
+        };
+        const payload = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
+            actorId,
+            routerChannelId: remoteTarget.routerChannelId,
+            bindingActorRef,
+            header: (0, protocol_1.encodeStreamHeader)(header),
+            payload: Buffer.alloc(0)
+        });
+        if ((spotKind ?? contracts_1.ZLinkSpotKind.Entry) === contracts_1.ZLinkSpotKind.Entry) {
+            await this.options.routeTransport.request(remoteTarget.routerChannelId, String(remoteTarget.targetNodeRid), actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, payload, this.options.requestTimeoutMs, signal);
+            return;
+        }
+        await this.options.routeTransport.requestToSpot({
+            routerChannelId: remoteTarget.routerChannelId,
+            targetNodeRid: remoteTarget.targetNodeRid,
+            spotId: remoteTarget.spotId,
+            spotKind: spotKind ?? contracts_1.ZLinkSpotKind.Entry
+        }, payload, {
+            packetName: actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+            timeoutMs: this.options.requestTimeoutMs,
+            signal
+        });
+    }
+    requireCurrentRemoteBinding(relay, routeContext) {
+        const state = this.options.actorManager()?.getState(relay.actorId);
+        const current = state === undefined
+            ? undefined
+            : (0, actor_runtime_state_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget);
+        if (current === undefined
+            || current.sessionNodeRid === undefined
+            || !(0, routing_id_1.routingIdsEqual)(current.sessionNodeRid, routeContext.sourceNodeRid)
+            || current.bindingGeneration === undefined
+            || relay.bindingGeneration === undefined
+            || current.bindingGeneration !== BigInt(relay.bindingGeneration)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${relay.actorId}' bound session identity is stale.`, true);
+        }
+    }
+    async requestRemoteTarget(target, request, unavailableMessage, decodeReply, signal) {
+        if (target.spotKind === contracts_1.ZLinkSpotKind.Entry) {
+            try {
+                return await this.options.routeTransport.request(target.routerChannelId, String(target.targetNodeRid), actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, request, this.options.requestTimeoutMs, signal);
+            }
+            catch (error) {
+                if (!(error instanceof ConfigurationException_1.ZLinkConfigurationException)) {
+                    throw error;
+                }
+            }
+        }
+        return (0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routeTransport, withDefaultSpotKind(target), request, { timeoutMs: this.options.requestTimeoutMs, signal }, unavailableMessage, decodeReply);
+    }
+    async relayLocalActorPacket(actor, frameHeader, payload, signal) {
+        void signal;
+        const state = this.options.actorManager()?.getState(actor.actorId);
+        const spotId = state?.spotId;
+        const hasActiveSpot = spotId !== undefined && this.options.spotManager()?.hasActiveSpot(spotId) === true;
+        if (!hasActiveSpot) {
+            return false;
+        }
+        const actorRef = state?.nativeActorRef;
+        const localNode = this.options.spotNodeRuntime()?.primaryMeshNode;
+        const localNodeRid = localNode === undefined ? undefined : String(localNode.status().routingId);
+        if (actorRef?.nodeRid !== undefined &&
+            localNodeRid !== undefined &&
+            !(0, routing_id_1.routingIdsEqual)(actorRef.nodeRid, localNodeRid)) {
+            return false;
+        }
+        const responseTarget = await this.options.streamBindingRuntime().captureBoundSessionResponseTarget(actor);
+        const encodedHeader = (0, protocol_1.encodeStreamHeader)(frameHeader);
+        //  encodeStreamHeader returns a fresh, unaliased array; view it without re-copying.
+        const header = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(encodedHeader.buffer, encodedHeader.byteOffset, encodedHeader.byteLength));
+        const body = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from((0, protocol_1.messageToBytes)(payload)));
+        const returnResponse = frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Request
+            && frameHeader.requestSeq !== undefined;
+        try {
+            this.options.detachedTaskRunner.runDetached('local actor packet relay', async () => {
+                try {
+                    const response = await this.requireSpotManager().dispatchRoutedActorPacket(spotId, actor.actorId, [header, body], returnResponse);
+                    if (!returnResponse) {
+                        return;
+                    }
+                    const sent = await this.sendCapturedOrCurrentBoundSessionResponse(responseTarget, actor.actorId, frameHeader.name, frameHeader.requestSeq, response, (0, bound_session_wire_1.streamMetadataMap)(frameHeader.metadata));
+                    if (!sent) {
+                        throw new Error(`Actor '${actor.actorId}' local bound session response route is not ready.`);
+                    }
+                }
+                catch (error) {
+                    if (!returnResponse) {
+                        throw error;
+                    }
+                    const sent = await this.sendCapturedOrCurrentBoundSessionError(responseTarget, actor.actorId, frameHeader.name, frameHeader.requestSeq, error, (0, bound_session_wire_1.streamMetadataMap)(frameHeader.metadata));
+                    if (!sent) {
+                        throw error;
+                    }
+                }
+                finally {
+                    header.close();
+                    body.close();
+                }
+            });
+            return true;
+        }
+        catch (error) {
+            header.close();
+            body.close();
+            throw error;
+        }
+    }
+    async sendCapturedOrCurrentBoundSessionResponse(target, actorId, packetName, requestSeq, response, metadata) {
+        return target === undefined
+            ? await this.options.streamBindingRuntime().sendLocalBoundSessionResponse(actorId, packetName, requestSeq, response, metadata, false)
+            : await target.sendResponse(packetName, requestSeq, response, metadata);
+    }
+    async sendCapturedOrCurrentBoundSessionError(target, actorId, packetName, requestSeq, error, metadata) {
+        return target === undefined
+            ? await this.options.streamBindingRuntime().sendLocalBoundSessionError(actorId, packetName, requestSeq, error, metadata)
+            : await target.sendError(packetName, requestSeq, error, metadata);
+    }
+    requireSpotNodeRuntime() {
+        const runtime = this.options.spotNodeRuntime();
+        if (runtime === undefined) {
+            throw new Error('SPOT node runtime is not started.');
+        }
+        return runtime;
+    }
+    requireSpotManager() {
+        const manager = this.options.spotManager();
+        if (manager === undefined) {
+            throw new Error('SPOT manager runtime is not started.');
+        }
+        return manager;
+    }
+}
+exports.ZLinkActorPacketRelay = ZLinkActorPacketRelay;
+function isValidMessageFollowId(value) {
+    return value !== undefined
+        && /^[0-9a-f]{32}$/.test(value)
+        && !/^0+$/.test(value);
+}
+/** Reuses the target when it already carries a spot kind instead of spreading a copy per call. */
+function withDefaultSpotKind(target) {
+    return target.spotKind === undefined
+        ? { ...target, spotKind: contracts_1.ZLinkSpotKind.Entry }
+        : target;
+}