@zlink-systems/framework 0.10.0

package/dist/runtime/host/actor-transfer-runtime.js

@@ -0,0 +1,1245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorTransferRuntime = void 0;
+exports.committedActorOwnerFence = committedActorOwnerFence;
+const node_crypto_1 = require("node:crypto");
+const contracts_1 = require("../../contracts");
+const authority_key_codec_1 = require("../locations/authority-key-codec");
+const actors_1 = require("../actors");
+const actor_retry_delay_1 = require("../actors/actor-retry-delay");
+const routing_id_1 = require("../routing-id");
+const payload_codec_1 = require("../messaging/payload-codec");
+const actor_message_follow_context_1 = require("../actors/actor-message-follow-context");
+const service_stateful_wire_codec_1 = require("../foundation/service-stateful-wire-codec");
+const operation_identity_1 = require("../foundation/operation-identity");
+const bounded_replay_map_1 = require("./bounded-replay-map");
+const DEFERRED_JOIN_TERMINAL_CAPACITY = 4096;
+/** Converts only committed actor authority evidence into a Message Follow fence. */
+function committedActorOwnerFence(actorId, targetActorRef, authority) {
+    if (targetActorRef.actorId !== actorId
+        || targetActorRef.objectGeneration <= 0n
+        || authority.objectGeneration !== targetActorRef.objectGeneration
+        || authority.allocation.state !== 'active'
+        || authority.allocation.objectKind !== 'actor'
+        || authority.allocation.descriptor.meshName !== targetActorRef.meshName
+        || !(0, routing_id_1.routingIdsEqual)(authority.allocation.descriptor.rid, targetActorRef.nodeRid)
+        || authority.ownerId.length === 0
+        || authority.ownerLeaseGeneration <= 0n
+        || authority.allocation.descriptorLifecycleGeneration <= 0n
+        || authority.authorityOwnerGeneration <= 0n) {
+        throw new Error(`Actor '${actorId}' handoff target does not match the committed authority snapshot.`);
+    }
+    return (0, actor_message_follow_context_1.ownerFence)({
+        ownerId: authority.ownerId,
+        ownerLeaseGeneration: authority.ownerLeaseGeneration,
+        nodeRid: String(authority.allocation.descriptor.rid),
+        nodeRidHex: (0, routing_id_1.encodeRoutingIdStorageHex)(authority.allocation.descriptor.rid),
+        nodeGeneration: authority.allocation.descriptorLifecycleGeneration,
+        authorityOwnerGeneration: authority.authorityOwnerGeneration
+    });
+}
+function requireSourceObjectGeneration(actorId, state) {
+    const generation = state.nativeActorRef?.generation;
+    if (generation === undefined || generation <= 0n) {
+        throw new Error(`Actor '${actorId}' handoff requires a positive source ObjectGeneration.`);
+    }
+    return generation;
+}
+function createHandoffReplayGate() {
+    let open;
+    const start = new Promise(resolve => {
+        open = resolve;
+    });
+    return { start, open };
+}
+class ZLinkActorTransferRuntime {
+    options;
+    sourceDepartureTasks = new Map();
+    coreSourceLeaves = new Map();
+    activeDeferredJoinTerminals = new Map();
+    deferredJoinTerminals = new bounded_replay_map_1.BoundedReplayMap(DEFERRED_JOIN_TERMINAL_CAPACITY);
+    constructor(options) {
+        this.options = options;
+    }
+    beginDeferredActorHandoff(actor, state, operationId) {
+        const actorId = actor.context.actorId;
+        this.options.actorHandoff.beginProvisional(actorId, operationId, requireSourceObjectGeneration(actorId, state));
+    }
+    promoteDeferredActorHandoff(actor, _state, operationId) {
+        this.options.actorHandoff.promoteProvisional(actor.context.actorId, operationId);
+    }
+    async completeDeferredActorHandoff(actor, target, _targetActorRef, operationId) {
+        const actorId = actor.context.actorId;
+        if (!this.options.actorHandoff.isProvisional(actorId))
+            return;
+        const manager = this.options.spotManager();
+        if (manager === undefined) {
+            throw new Error(`Actor '${actorId}' same-node Join has no local Spot manager.`);
+        }
+        const admitted = this.options.actorHandoff.admitDeferredPrefix(actorId, operationId, drain => manager.admitRoutedActorPacketPrefix(target.spotId, actorId, drain), this.options.prepareApplicationJob);
+        void this.observeHandoffReplay(admitted.terminal);
+    }
+    async cancelDeferredActorHandoff(actor, _state, operationId) {
+        const admitted = this.admitDeferredSourcePrefix(actor, _state, operationId);
+        void this.observeHandoffReplay(admitted.terminal);
+    }
+    async prepareDeferredJoinAccepted(actorId, operationId, actorRef, rawReply, replyContentType, signal, canonicalInventoryDigest) {
+        return await this.requireDeferredJoinJournal().prepare(actorId, operationId, actorRef, rawReply, replyContentType, signal, canonicalInventoryDigest);
+    }
+    async isDeferredJoinAcceptedRootPublication(reference, checksumCrc32c, expected, signal) {
+        const relocation = this.options.relocationStore();
+        return relocation === undefined
+            ? false
+            : await (0, actors_1.isDeferredJoinAcceptedRootPublication)(relocation, reference, checksumCrc32c, expected, signal);
+    }
+    async discardDeferredJoinAccepted(root, signal) {
+        await this.requireDeferredJoinJournal().discardPrepared(root, signal);
+    }
+    markDeferredJoinAcceptedCommitted(root, actorRef, signal) {
+        return this.requireDeferredJoinJournal().markCommitted(root, actorRef, signal);
+    }
+    async commitAndDeliverDeferredJoinAccepted(root, actor, actorRef, submitMailbox, signal) {
+        const terminalKey = deferredJoinTerminalKey(root);
+        const terminal = this.deferredJoinTerminals.get(terminalKey);
+        if (terminal !== undefined) {
+            this.deferredJoinTerminals.touch(terminalKey);
+            return terminal;
+        }
+        const active = this.activeDeferredJoinTerminals.get(terminalKey);
+        if (active !== undefined)
+            return await waitForOperation(active, signal);
+        const completion = this.commitAndDeliverDeferredJoinAcceptedCore(root, actor, actorRef, submitMailbox);
+        this.activeDeferredJoinTerminals.set(terminalKey, completion);
+        void completion.then(completed => {
+            this.deferredJoinTerminals.remember(terminalKey, completed);
+            if (this.activeDeferredJoinTerminals.get(terminalKey) === completion) {
+                this.activeDeferredJoinTerminals.delete(terminalKey);
+            }
+        }, () => {
+            if (this.activeDeferredJoinTerminals.get(terminalKey) === completion) {
+                this.activeDeferredJoinTerminals.delete(terminalKey);
+            }
+        });
+        return await waitForOperation(completion, signal);
+    }
+    async commitAndDeliverDeferredJoinAcceptedCore(root, actor, actorRef, submitMailbox) {
+        const targetActorRef = this.options.actorManager()
+            ?.getState(actor.context.actorId)
+            ?.nativeActorRef;
+        const currentActorRef = targetActorRef === undefined
+            ? actorRef
+            : (0, actors_1.toFrameworkActorRef)(targetActorRef, actor.context.meshName);
+        let current = root.cursor === 'prepared'
+            ? await this.requireDeferredJoinJournal().markCommitted(root, currentActorRef)
+            : root;
+        if (current.cursor === 'delivered')
+            return current;
+        let lastError;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                current = await this.requireDeferredJoinJournal().deliver(current, actor, currentActorRef, submitMailbox);
+                return current;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < 2) {
+                    await new Promise(resolve => {
+                        const timer = setTimeout(resolve, 10 << attempt);
+                        timer.unref();
+                    });
+                    current = await this.requireDeferredJoinJournal().recover(currentActorRef.actorId) ?? current;
+                }
+            }
+        }
+        throw lastError;
+    }
+    requireDeferredJoinJournal() {
+        const authority = this.options.authorityStore();
+        const relocation = this.options.relocationStore();
+        if (authority === undefined || relocation === undefined) {
+            throw new Error('Cross-node deferred Actor Join requires Location and Relocation Stores.');
+        }
+        return new actors_1.ZLinkDeferredJoinAcceptedJournal(authority, relocation, this.options.messageSerializers);
+    }
+    async prepareSourceActorLeave(actor, sourceSpotId, signal) {
+        if (sourceSpotId !== undefined) {
+            const manager = this.options.spotManager();
+            if (manager !== undefined) {
+                await manager.prepareActorLeaveForTransfer(sourceSpotId, actor, signal);
+                return;
+            }
+        }
+        await this.options.notifyEntrySpotActorLeft(actor, signal);
+    }
+    async restoreSourceActor(actor, sourceSpotId, signal) {
+        if (sourceSpotId !== undefined) {
+            const manager = this.options.spotManager();
+            if (manager !== undefined) {
+                await manager.restoreActorAfterFailedTransfer(sourceSpotId, actor, signal);
+                return;
+            }
+        }
+        await this.options.restoreEntrySpotActorJoined(actor, signal);
+    }
+    async beginSourceActorMove(actor, state, deferredOperationId) {
+        if (deferredOperationId !== undefined && this.options.actorHandoff.isProvisional(actor.context.actorId)) {
+            this.promoteDeferredActorHandoff(actor, state, deferredOperationId);
+        }
+        state.beginMove();
+        if (!this.options.actorHandoff.isActive(actor.context.actorId)) {
+            this.options.actorHandoff.begin(actor.context.actorId, requireSourceObjectGeneration(actor.context.actorId, state));
+        }
+        try {
+            if (state.spotId !== undefined) {
+                relocationDebug('source_actor_move.await_spot_transfer', {
+                    actorId: actor.context.actorId,
+                    spotId: String(state.spotId)
+                });
+                await this.options.spotManager()?.beginActorTransfer(state.spotId, actor.context.actorId);
+                relocationDebug('source_actor_move.spot_transfer_complete', {
+                    actorId: actor.context.actorId,
+                    spotId: String(state.spotId)
+                });
+            }
+        }
+        catch (error) {
+            if (deferredOperationId === undefined) {
+                this.options.actorHandoff.cancel(actor.context.actorId);
+            }
+            else {
+                const admitted = this.admitDeferredSourcePrefix(actor, state, deferredOperationId);
+                void this.observeHandoffReplay(admitted.terminal);
+            }
+            state.endMove();
+            throw error;
+        }
+    }
+    async cancelSourceActorMove(actor, state, deferredOperationId, replayStart = Promise.resolve()) {
+        try {
+            if (state.spotId !== undefined) {
+                await this.options.spotManager()?.cancelActorTransfer(state.spotId, actor.context.actorId);
+            }
+        }
+        finally {
+            try {
+                if (deferredOperationId === undefined) {
+                    const admitted = this.admitCanceledSourcePrefix(actor, state, replayStart);
+                    void this.observeHandoffReplay(admitted.terminal);
+                }
+                else {
+                    const admitted = this.admitDeferredSourcePrefix(actor, state, deferredOperationId, replayStart);
+                    void this.observeHandoffReplay(admitted.terminal);
+                }
+            }
+            finally {
+                state.endMove();
+            }
+        }
+    }
+    admitCanceledSourcePrefix(actor, state, replayStart = Promise.resolve()) {
+        // The seal-era ingress hold returns to the source queue on a precommit
+        // abort. Rejection stays reserved for a source Actor whose dispatch is
+        // gone, because held packets then have no queue left to return to.
+        const queue = this.sourceHandoffPrefixQueue(actor, state);
+        if (queue === undefined) {
+            this.options.actorHandoff.cancel(actor.context.actorId);
+            return { terminal: Promise.resolve() };
+        }
+        return this.options.actorHandoff.admitCanceledPrefix(actor.context.actorId, queue, this.options.prepareApplicationJob, replayStart);
+    }
+    admitDeferredSourcePrefix(actor, state, operationId, replayStart = Promise.resolve()) {
+        const queue = this.sourceHandoffPrefixQueue(actor, state);
+        if (queue === undefined) {
+            this.options.actorHandoff.cancel(actor.context.actorId);
+            return { terminal: Promise.resolve() };
+        }
+        return this.options.actorHandoff.admitDeferredPrefix(actor.context.actorId, operationId, queue, this.options.prepareApplicationJob, replayStart);
+    }
+    async observeHandoffReplay(release) {
+        try {
+            await release;
+        }
+        catch (error) {
+            // Release drains every held record before rejecting. Lifecycle cleanup
+            // must continue, while the existing runtime task boundary retains the
+            // one-way/invariant failure for diagnostics.
+            try {
+                this.options.reportPostCommitError?.(error);
+            }
+            catch {
+                // Diagnostics cannot interrupt the relocation terminal lifecycle.
+            }
+        }
+    }
+    sourceHandoffPrefixQueue(actor, state) {
+        const sourceSpotId = state.spotId;
+        const manager = this.options.spotManager();
+        if (sourceSpotId === undefined || manager === undefined) {
+            return undefined;
+        }
+        return drain => manager.admitRoutedActorPacketPrefix(sourceSpotId, actor.context.actorId, drain);
+    }
+    async prepareSource(actor, state, signal, lifecycleAuthority = 'framework', deferredOperationId, relocation) {
+        await this.beginSourceActorMove(actor, state, deferredOperationId);
+        const relocationMetric = state.meshName === undefined
+            ? undefined
+            : this.options.metrics?.startRelocation(state.meshName, 'actor', this.options.actorTransferRegistry.policy(state.actorType));
+        const sourceSpotId = state.spotId;
+        let sourceLeaveStarted = false;
+        let sealId;
+        try {
+            if (state.remoteBoundSessionTarget !== undefined) {
+                sealId = (0, node_crypto_1.randomUUID)();
+                const sealedTarget = await this.sealBoundSessionRoute(actor, state, signal, relocation);
+                state.setRemoteBoundSessionTarget(sealedTarget);
+                this.options.actorHandoff.sealConnectionBoundIngress(actor.context.actorId);
+            }
+            const transfer = await this.options.actorTransferRegistry.transferOut(actor, state.actorType, signal);
+            // The captured state is handed off inline with the join request; the
+            // Relocation Store no longer carries relocation state payloads
+            // (spec 28 §2 — direct transfer is the only handoff original).
+            relocationMetric?.recordBytes(transfer.state.toEncodedPayload().toBytes().byteLength);
+            if (lifecycleAuthority === 'framework') {
+                sourceLeaveStarted = true;
+                await this.prepareSourceActorLeave(actor, sourceSpotId, signal);
+            }
+            const coreSourceLeave = lifecycleAuthority === 'core'
+                ? this.beginCoreSourceLeave(actor.context.actorId)
+                : undefined;
+            const sourceLeaveCompletion = coreSourceLeave?.completion;
+            const handoffBacklog = lifecycleAuthority === 'core'
+                ? this.options.actorHandoff.snapshotCoreBacklog(actor.context.actorId)
+                : this.options.actorHandoff.snapshot(actor.context.actorId);
+            let phase = 'prepared';
+            let committedTargetOwnerFence;
+            return {
+                ...transfer,
+                handoffBacklog,
+                sourceLeaveCompletion,
+                sourceLeaveSubmitted: coreSourceLeave?.submitted,
+                onSourceLeaveSubmitted: (notify) => {
+                    const pending = this.coreSourceLeaves.get(actor.context.actorId);
+                    if (pending === undefined) {
+                        throw new Error(`Actor '${actor.context.actorId}' has no pending Core source leave.`);
+                    }
+                    pending.notifySubmitted = notify;
+                },
+                observeTargetAuthority: async (target, targetActorRef, observeSignal) => {
+                    const authority = this.options.authorityStore();
+                    if (authority === undefined
+                        || target.targetOwnerId === undefined
+                        || target.ownerLeaseGeneration === undefined
+                        || target.targetNodeGeneration === undefined) {
+                        throw new Error(`Actor '${actor.context.actorId}' relocation target has no complete authority fence.`);
+                    }
+                    const committed = await authority.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actor.context.actorId), observeSignal);
+                    if (committed.kind !== 'snapshot'
+                        || committed.ownerId !== target.targetOwnerId
+                        || committed.ownerLeaseGeneration !== target.ownerLeaseGeneration
+                        || committed.allocation.descriptorLifecycleGeneration !== target.targetNodeGeneration
+                        || !(0, routing_id_1.routingIdsEqual)(committed.allocation.descriptor.rid, target.targetNodeRid)
+                        || committed.objectGeneration !== targetActorRef.objectGeneration) {
+                        throw new Error(`Actor '${actor.context.actorId}' relocation target authority was not committed exactly.`);
+                    }
+                    committedTargetOwnerFence = committedActorOwnerFence(actor.context.actorId, targetActorRef, committed);
+                },
+                commit: (target, targetActorRef, results, releaseLocation = true) => {
+                    if (phase !== 'prepared')
+                        return;
+                    if (committedTargetOwnerFence === undefined) {
+                        throw new Error(`Actor '${actor.context.actorId}' handoff has no committed target authority fence.`);
+                    }
+                    phase = 'committed';
+                    relocationMetric?.complete('completed');
+                    try {
+                        this.options.actorHandoff.complete(actor.context.actorId, target, targetActorRef, results, committedTargetOwnerFence);
+                    }
+                    catch (error) {
+                        // The target has already committed. Local Message Follow setup is now
+                        // post-commit work and must not turn the accepted transfer into a
+                        // source rollback that can no longer undo the target.
+                        this.options.reportPostCommitError?.(error);
+                    }
+                    finally {
+                        const releaseSourceLocation = lifecycleAuthority === 'core' && releaseLocation;
+                        if (releaseSourceLocation && sourceLeaveCompletion !== undefined) {
+                            // Core sends the source leave control after the authority
+                            // transition. Keep the source shell available for that
+                            // callback, then release the old location and registry entry.
+                            void sourceLeaveCompletion.then(() => this.scheduleSourceDeparture(actor, sourceSpotId, true), error => {
+                                this.options.reportPostCommitError?.(error);
+                                this.scheduleSourceDeparture(actor, sourceSpotId, true);
+                            });
+                        }
+                        else {
+                            this.scheduleSourceDeparture(actor, sourceSpotId, releaseSourceLocation);
+                        }
+                    }
+                },
+                rollback: async () => {
+                    if (phase !== 'prepared')
+                        return;
+                    phase = 'rolledBack';
+                    relocationMetric?.complete('aborted');
+                    this.coreSourceLeaves.delete(actor.context.actorId);
+                    const replayGate = createHandoffReplayGate();
+                    try {
+                        await this.cancelSourceActorMove(actor, state, deferredOperationId, replayGate.start);
+                        await this.restoreSourceActor(actor, sourceSpotId);
+                        if (sealId !== undefined) {
+                            await this.observeBoundSessionSealAbort(actor, state);
+                        }
+                    }
+                    finally {
+                        replayGate.open();
+                    }
+                }
+            };
+        }
+        catch (error) {
+            relocationMetric?.complete('failed');
+            const replayGate = createHandoffReplayGate();
+            try {
+                await this.cancelSourceActorMove(actor, state, deferredOperationId, replayGate.start);
+                if (sourceLeaveStarted)
+                    await this.restoreSourceActor(actor, sourceSpotId);
+                if (sealId !== undefined) {
+                    await this.observeBoundSessionSealAbort(actor, state);
+                }
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], 'Actor source leave and rollback both failed.');
+            }
+            finally {
+                replayGate.open();
+            }
+            throw error;
+        }
+    }
+    async prepareMaintenanceSession(actor, state, signal, manageMembership = true, relocation) {
+        relocationDebug('maintenance_session.begin', {
+            actorId: actor.context.actorId,
+            spotId: state.spotId === undefined ? undefined : String(state.spotId)
+        });
+        if (manageMembership) {
+            await this.beginSourceActorMove(actor, state);
+        }
+        else {
+            state.beginMove();
+            this.options.actorHandoff.begin(actor.context.actorId, requireSourceObjectGeneration(actor.context.actorId, state));
+        }
+        relocationDebug('maintenance_session.source_move_complete', {
+            actorId: actor.context.actorId
+        });
+        let sealId;
+        try {
+            if (state.remoteBoundSessionTarget !== undefined) {
+                sealId = (0, node_crypto_1.randomUUID)();
+                state.setRemoteBoundSessionTarget(await this.sealBoundSessionRoute(actor, state, signal, relocation));
+                this.options.actorHandoff.sealConnectionBoundIngress(actor.context.actorId);
+            }
+            const handoffBacklog = this.options.actorHandoff.snapshot(actor.context.actorId);
+            let terminal = 'prepared';
+            let replayResults = [];
+            return {
+                target: state.remoteBoundSessionTarget,
+                handoffBacklog,
+                takeRelocationRelay: () => this.options.actorHandoff.takeRelocationRelay(actor.context.actorId),
+                setReplayResults: results => {
+                    if (terminal === 'prepared')
+                        replayResults = [...results];
+                },
+                commit: async (target, targetActorRef, targetOwnerFence) => {
+                    if (terminal === 'rolledBack')
+                        return;
+                    if (terminal === 'prepared') {
+                        this.options.actorHandoff.complete(actor.context.actorId, target, targetActorRef, replayResults, targetOwnerFence);
+                        if (manageMembership && state.spotId !== undefined) {
+                            await this.options.spotManager()
+                                ?.commitActorLeaveAfterTransfer(state.spotId, actor.context.actorId);
+                        }
+                        state.endMove();
+                        terminal = 'committed';
+                    }
+                },
+                rollback: async () => {
+                    if (terminal !== 'prepared')
+                        return;
+                    terminal = 'rolledBack';
+                    const replayGate = createHandoffReplayGate();
+                    try {
+                        if (manageMembership) {
+                            await this.cancelSourceActorMove(actor, state, undefined, replayGate.start);
+                        }
+                        else {
+                            try {
+                                const admitted = this.admitCanceledSourcePrefix(actor, state, replayGate.start);
+                                void this.observeHandoffReplay(admitted.terminal);
+                            }
+                            finally {
+                                state.endMove();
+                            }
+                        }
+                        if (sealId !== undefined) {
+                            await this.observeBoundSessionSealAbort(actor, state);
+                        }
+                    }
+                    finally {
+                        replayGate.open();
+                    }
+                }
+            };
+        }
+        catch (error) {
+            let sourceRestored = false;
+            const replayGate = createHandoffReplayGate();
+            try {
+                if (manageMembership) {
+                    try {
+                        await this.cancelSourceActorMove(actor, state, undefined, replayGate.start);
+                        sourceRestored = true;
+                    }
+                    catch { }
+                }
+                else {
+                    try {
+                        const admitted = this.admitCanceledSourcePrefix(actor, state, replayGate.start);
+                        void this.observeHandoffReplay(admitted.terminal);
+                        sourceRestored = true;
+                    }
+                    catch {
+                        // The Session owner keeps the seal until timeout when the source
+                        // queue could not be restored.
+                    }
+                    finally {
+                        state.endMove();
+                    }
+                }
+                if (sourceRestored && sealId !== undefined) {
+                    await this.observeBoundSessionSealAbort(actor, state);
+                }
+            }
+            finally {
+                replayGate.open();
+            }
+            throw error;
+        }
+    }
+    async notifyCoreSourceLeave(actor, callback) {
+        const pending = this.coreSourceLeaves.get(actor.context.actorId);
+        let callbackResult;
+        try {
+            callbackResult = Promise.resolve(callback());
+        }
+        catch (error) {
+            callbackResult = Promise.reject(error);
+        }
+        // Submission, not the callback result, releases the target Join. Observe
+        // a fast rejection while the submission ACK is in flight without making
+        // that rejection an unhandled promise.
+        void callbackResult.catch(() => { });
+        try {
+            if (pending !== undefined) {
+                if (pending.notifySubmitted === undefined) {
+                    throw new Error(`Actor '${actor.context.actorId}' has no Core source leave submission notifier.`);
+                }
+                await pending.notifySubmitted();
+                pending.resolveSubmitted();
+            }
+            await callbackResult;
+            pending?.resolve();
+        }
+        catch (error) {
+            pending?.rejectSubmitted(error);
+            pending?.reject(error);
+            throw error;
+        }
+        finally {
+            this.coreSourceLeaves.delete(actor.context.actorId);
+        }
+    }
+    async completeRelocationSourceLeave(actor, sourceSpotId, signal) {
+        await this.prepareSourceActorLeave(actor, sourceSpotId, signal);
+    }
+    relayMaintenanceTerminal(actorId, packet, result, sourceNodeRid, targetAuthorityOwnerGeneration) {
+        return this.options.actorHandoff.acceptRelocatedTerminal(actorId, packet, result, sourceNodeRid, targetAuthorityOwnerGeneration);
+    }
+    relayCanonicalMaintenanceTerminal(operationId, replyRouteId, result, sourceNodeRid, targetAuthorityOwnerGeneration) {
+        return this.options.actorHandoff.acceptRelocatedTerminalRelay(operationId, replyRouteId, undefined, result, sourceNodeRid, targetAuthorityOwnerGeneration);
+    }
+    async sealBoundSessionRoute(actor, state, signal, relocation) {
+        const target = state.remoteBoundSessionTarget;
+        const actorRef = state.nativeActorRef;
+        if (target === undefined || actorRef === undefined ||
+            target.bindingGeneration === undefined || target.bindingGeneration <= 0n ||
+            state.locationGeneration === undefined || state.locationGeneration < 0n ||
+            state.ownerLeaseGeneration === undefined || state.ownerLeaseGeneration <= 0n) {
+            throw new Error(`Actor '${actor.context.actorId}' Session route cannot be sealed without its exact source fence.`);
+        }
+        const serviceWire = this.options.sessionRelocationWire?.();
+        const authorityStore = this.options.authorityStore();
+        const descriptors = this.options.liveDescriptors;
+        if (relocation === undefined
+            || serviceWire === undefined
+            || authorityStore === undefined
+            || descriptors === undefined
+            || target.sessionRid === undefined) {
+            throw new Error(`Actor '${actor.context.actorId}' Session relocation requires the command 42/43 service-wire path.`);
+        }
+        const [authority, live] = await Promise.all([
+            authorityStore.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actor.context.actorId), signal),
+            descriptors(target.routerChannelId, signal)
+        ]);
+        const local = this.options.primaryMeshNode().status();
+        const sessionOwner = live.find(value => String(value.rid) === String(target.targetNodeRid));
+        if (authority.kind !== 'snapshot'
+            || sessionOwner === undefined
+            || String(local.routingId) !== String(actorRef.nodeRid)
+            || authority.objectGeneration !== actorRef.generation
+            || authority.authorityOwnerGeneration !== state.locationGeneration
+            || authority.ownerLeaseGeneration !== state.ownerLeaseGeneration
+            || String(authority.allocation.descriptor.rid) !== String(actorRef.nodeRid)
+            || authority.allocation.descriptorLifecycleGeneration !== local.lifecycleGeneration
+            || (target.sessionNodeRid !== undefined
+                && String(target.sessionNodeRid) !== String(target.targetNodeRid))) {
+            throw new Error(`Actor '${actor.context.actorId}' Session route service-wire source fence is stale.`);
+        }
+        const coordinator = {
+            ownerId: authority.ownerId,
+            leaseGeneration: authority.ownerLeaseGeneration,
+            nodeRid: String(local.routingId),
+            nodeGeneration: local.lifecycleGeneration,
+            expectedAuthorityStoreVersion: authority.storeVersion.value
+        };
+        const session = {
+            sessionOwnerNodeRid: String(target.targetNodeRid),
+            sessionOwnerNodeGeneration: sessionOwner.lifecycleGeneration,
+            sessionOwnerId: sessionOwner.ownerId,
+            sessionOwnerLeaseGeneration: sessionOwner.leaseGeneration,
+            sessionRid: String(target.sessionRid),
+            bindingGeneration: target.bindingGeneration
+        };
+        const request = {
+            relocation,
+            coordinator,
+            senderRole: 'source',
+            actor: {
+                actor: {
+                    actorId: actor.context.actorId,
+                    generation: actorRef.generation,
+                    nodeRid: String(actorRef.nodeRid)
+                },
+                targetNodeGeneration: local.lifecycleGeneration,
+                authorityOwnerGeneration: authority.authorityOwnerGeneration,
+                ownerLeaseGeneration: authority.ownerLeaseGeneration
+            },
+            session
+        };
+        await serviceWire.requestSessionRelocationSeal(target.routerChannelId, target.targetNodeRid, request, signal);
+        return {
+            ...target,
+            previousAuthorityOwnerGeneration: authority.authorityOwnerGeneration,
+            previousOwnerLeaseGeneration: authority.ownerLeaseGeneration,
+            relocationSealId: (0, service_stateful_wire_codec_1.serviceSessionRelocationIdentityKey)(request),
+            serviceWireRelocation: { relocation, coordinator, session }
+        };
+    }
+    async abortBoundSessionRouteSeal(actor, state, targetOverride) {
+        const target = targetOverride ?? (0, actors_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget);
+        const actorRef = state.nativeActorRef;
+        if (target === undefined || actorRef === undefined || target.bindingGeneration === undefined ||
+            target.previousAuthorityOwnerGeneration === undefined || target.previousOwnerLeaseGeneration === undefined) {
+            throw new Error(`Actor '${actor.context.actorId}' Session route seal cannot be released without its exact fence.`);
+        }
+        const serviceFence = target.serviceWireRelocation;
+        const serviceWire = this.options.sessionRelocationWire?.();
+        if (serviceFence === undefined || serviceWire === undefined) {
+            throw new Error(`Actor '${actor.context.actorId}' Session route service-wire release is unavailable.`);
+        }
+        const route = {
+            relocation: serviceFence.relocation,
+            coordinator: serviceFence.coordinator,
+            senderRole: 'source',
+            actor: {
+                actorId: actor.context.actorId,
+                generation: actorRef.generation,
+                nodeRid: String(actorRef.nodeRid)
+            },
+            session: serviceFence.session,
+            route: {
+                action: 'abort',
+                currentAuthorityOwnerGeneration: target.previousAuthorityOwnerGeneration
+            }
+        };
+        if (target.relocationSealId !== (0, service_stateful_wire_codec_1.serviceSessionRelocationIdentityKey)(route)) {
+            throw new Error(`Actor '${actor.context.actorId}' Session route seal release changed its seal identity.`);
+        }
+        await serviceWire.sendSessionRelocationRoute(target.routerChannelId, target.targetNodeRid, route, this.options.shutdownSignal?.());
+    }
+    async observeBoundSessionSealAbort(actor, state) {
+        try {
+            await this.abortBoundSessionRouteSeal(actor, state);
+        }
+        catch (error) {
+            try {
+                this.options.reportPostCommitError?.(error);
+            }
+            catch {
+                // Diagnostics cannot replace the relocation failure terminal.
+            }
+        }
+    }
+    beginCoreSourceLeave(actorId) {
+        let resolve;
+        let reject;
+        const promise = new Promise((accept, fail) => {
+            resolve = accept;
+            reject = fail;
+        });
+        let resolveSubmitted;
+        let rejectSubmitted;
+        const submitted = new Promise((accept, fail) => {
+            resolveSubmitted = accept;
+            rejectSubmitted = fail;
+        });
+        void promise.catch(() => { });
+        void submitted.catch(() => { });
+        this.coreSourceLeaves.set(actorId, {
+            promise,
+            resolve,
+            reject,
+            submitted,
+            resolveSubmitted,
+            rejectSubmitted
+        });
+        return { completion: promise, submitted };
+    }
+    scheduleSourceDeparture(actor, sourceSpotId, releaseLocation) {
+        if (this.sourceDepartureTasks.has(actor.context.actorId))
+            return;
+        const task = this.finishSourceDeparture(actor, sourceSpotId, releaseLocation)
+            .finally(() => this.sourceDepartureTasks.delete(actor.context.actorId));
+        this.sourceDepartureTasks.set(actor.context.actorId, task);
+    }
+    async finishSourceDeparture(actor, sourceSpotId, releaseLocation) {
+        const retry = new actor_retry_delay_1.ZLinkActorRetryDelay();
+        while (this.options.shutdownSignal?.()?.aborted !== true) {
+            try {
+                if (sourceSpotId !== undefined) {
+                    await this.options.spotManager()?.commitActorLeaveAfterTransfer(sourceSpotId, actor.context.actorId);
+                }
+                if (releaseLocation) {
+                    const state = this.options.actorManager()?.getState(actor.context.actorId);
+                    if (state?.actorType !== undefined && state.ownsLocation) {
+                        await this.options.locationLifecycle()?.releaseActor(state.actorType, actor.context.actorId);
+                        state.markLocationReleased();
+                    }
+                    // Message Follow owns the bounded stale route after the native leave.
+                    // The source Actor shell must therefore be removed from the process
+                    // registry so a later relocation can materialize the same Actor ID on
+                    // this node without colliding with its previous incarnation.
+                    await this.options.actorManager()?.completeCoreRelocationSource(actor.context.actorId);
+                }
+                this.options.onSourceDepartureCompleted?.(actor.context.actorId);
+                return;
+            }
+            catch (error) {
+                this.options.reportPostCommitError?.(error);
+                if (!await retry.wait(this.options.shutdownSignal?.()))
+                    return;
+            }
+        }
+    }
+    async getOrCreateRoutedActor(actorId, actorType, actorRef, remoteBoundSessionTarget, actorCreateRequest, signal) {
+        const actorManager = this.requireActorManager('Routed actor join requires ZLINK_ACTOR_MANAGER.');
+        const actor = actorRef === undefined
+            ? await actorManager.getOrCreateActor(actorId, actorType, signal)
+            : await actorManager.getOrCreateWithNativeRef(actorId, actorType, actorRef, actorCreateRequest === undefined
+                ? undefined
+                : (0, payload_codec_1.wrapFrameworkPayloadMessage)(actorCreateRequest, this.options.messageSerializers), signal);
+        const state = actorManager.getState(actorId);
+        if (state === undefined) {
+            throw new Error(`Actor '${actorId}' state was not created.`);
+        }
+        if (actorRef !== undefined) {
+            state.setNativeActorRef(actorRef);
+            state.setRemoteBoundSessionTarget(remoteBoundSessionTarget);
+            return { actor, actorRef: actorRef };
+        }
+        return { actor, actorRef: state.ensureNativeActorRef(this.options.primaryMeshNode()) };
+    }
+    async materializeRoutedActor(actorId, actorType, adapterKey, transferState, actorEntryNodeRid, remoteBoundSessionTarget, signal) {
+        const actorManager = this.requireActorManager('Routed actor transfer requires ZLINK_ACTOR_MANAGER.');
+        const materialized = await actorManager.materializeTransferredActor(actorId, actorType, adapterKey, (0, payload_codec_1.wrapFrameworkPayloadMessage)(transferState, this.options.messageSerializers), signal);
+        const state = actorManager.getState(actorId);
+        if (state === undefined) {
+            throw new Error(`Actor '${actorId}' transfer state was not created.`);
+        }
+        if (actorEntryNodeRid !== undefined)
+            state.setEntryNodeRid(actorEntryNodeRid);
+        state.setBoundSessionTransferTarget(remoteBoundSessionTarget);
+        if (remoteBoundSessionTarget !== undefined) {
+            state.setRemoteBoundSessionTarget((0, actors_1.mergeRemoteBoundSessionTarget)(remoteBoundSessionTarget, state.remoteBoundSessionTarget));
+        }
+        if (remoteBoundSessionTarget?.bindingGeneration !== undefined) {
+            state.setBoundSessionBindingGeneration(remoteBoundSessionTarget.bindingGeneration);
+        }
+        return {
+            actor: materialized.actor,
+            actorRef: materialized.actorRef
+        };
+    }
+    async commitRoutedActorAuthority(actor, sourceActorRef, transferId, spotId, spotGeneration, membershipEpoch, deadlineUnixMs, signal) {
+        const deadlineAtMs = performance.now() + (deadlineUnixMs - Date.now());
+        const store = this.options.authorityStore();
+        const owner = this.options.currentOwner();
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        const actorType = state?.actorType;
+        const local = this.options.primaryMeshNode().status();
+        const targetActorRef = state?.nativeActorRef === undefined
+            ? undefined
+            : (0, actors_1.toFrameworkActorRef)(state.nativeActorRef, actor.context.meshName);
+        if (store === undefined
+            || owner === undefined
+            || state === undefined
+            || actorType === undefined
+            || targetActorRef === undefined
+            || local.lifecycleGeneration <= 0n
+            || spotGeneration <= 0n
+            || membershipEpoch <= 0n
+            || !Number.isSafeInteger(deadlineUnixMs)) {
+            throw new Error(`Actor '${actor.context.actorId}' target authority commit has an incomplete materialization fence.`);
+        }
+        const key = (0, authority_key_codec_1.encodeAuthorityKey)('actor', actor.context.actorId);
+        const expected = await store.readAuthority(key, signal);
+        if (expected.kind !== 'snapshot') {
+            throw new Error(`Actor '${actor.context.actorId}' source authority is missing at the target.`);
+        }
+        const exactTarget = (value) => value.allocation.state === 'active'
+            && value.allocation.objectKind === 'actor'
+            && value.allocation.stableType === actorType
+            && value.objectGeneration === targetActorRef.objectGeneration
+            && value.ownerId === owner.ownerId
+            && value.ownerLeaseGeneration === owner.leaseGeneration
+            && value.allocation.descriptor.meshName === actor.context.meshName
+            && (0, routing_id_1.routingIdsEqual)(value.allocation.descriptor.rid, local.routingId)
+            && value.allocation.descriptorLifecycleGeneration === local.lifecycleGeneration;
+        const adopt = (value) => {
+            state.setLocationGeneration(value.authorityOwnerGeneration);
+            state.setOwnerLeaseGeneration(value.ownerLeaseGeneration);
+            state.setJoinedSpot(spotId, state.spot, membershipEpoch, spotGeneration);
+            state.markLocationOwned();
+            return value;
+        };
+        if (exactTarget(expected))
+            return adopt(expected);
+        if (expected.allocation.state !== 'active'
+            || expected.allocation.objectKind !== 'actor'
+            || expected.allocation.stableType !== actorType
+            || expected.objectGeneration !== sourceActorRef.objectGeneration
+            || expected.allocation.descriptor.meshName !== sourceActorRef.meshName
+            || !(0, routing_id_1.routingIdsEqual)(expected.allocation.descriptor.rid, sourceActorRef.nodeRid)) {
+            throw new Error(`Actor '${actor.context.actorId}' relocation source authority is stale at the target.`);
+        }
+        const membershipMutation = Buffer.from(JSON.stringify({
+            actorId: actor.context.actorId,
+            actorGeneration: targetActorRef.objectGeneration.toString(),
+            spotId: String(spotId),
+            spotGeneration: spotGeneration.toString(),
+            membershipEpoch: membershipEpoch.toString()
+        }), 'utf8');
+        const request = {
+            aggregateId: { value: transferId },
+            aggregateGeneration: local.lifecycleGeneration,
+            participants: [{
+                    authorityKey: key,
+                    expectedStoreVersion: expected.storeVersion,
+                    ownerTransition: 'newOwner',
+                    authorityPayload: (0, actors_1.rewriteActorAuthorityRoute)(expected.payload, targetActorRef, String(spotId), spotGeneration, contracts_1.ZLinkSpotKind.User, local.lifecycleGeneration, owner),
+                    membershipMutation
+                }],
+            inventoryDigest: (0, node_crypto_1.createHash)('sha256').update(membershipMutation).digest(),
+            targetDescriptor: {
+                meshName: actor.context.meshName,
+                rid: local.routingId
+            },
+            targetDescriptorLifecycleGeneration: local.lifecycleGeneration,
+            capacity: expected.allocation.capacity,
+            targetOwner: owner
+        };
+        let prepared;
+        let firstError;
+        for (;;) {
+            signal?.throwIfAborted();
+            try {
+                prepared = await store.prepareAggregate(request, signal);
+            }
+            catch (error) {
+                firstError ??= error;
+            }
+            if (prepared?.kind === 'prepared' || prepared?.kind === 'alreadyPrepared')
+                break;
+            const observed = await this.readActorAuthorityForRelocation(store, key, signal);
+            if (observed !== undefined && exactTarget(observed))
+                return adopt(observed);
+            if (prepared !== undefined || observed !== undefined && !sameSourceActorAuthority(observed, expected)) {
+                throw new Error(`Actor '${actor.context.actorId}' target authority prepare was rejected.`, { cause: firstError });
+            }
+            await waitForActorAuthorityRetry(deadlineAtMs, signal, firstError);
+        }
+        for (;;) {
+            signal?.throwIfAborted();
+            let committed;
+            try {
+                committed = await store.commitAggregate(prepared.fence, signal);
+            }
+            catch (error) {
+                firstError ??= error;
+            }
+            const observed = await this.readActorAuthorityForRelocation(store, key, signal);
+            if (observed !== undefined && exactTarget(observed))
+                return adopt(observed);
+            if (committed?.kind === 'stale'
+                || committed?.kind === 'generationExhausted'
+                || observed !== undefined && !sameSourceActorAuthority(observed, expected)) {
+                throw new Error(`Actor '${actor.context.actorId}' target authority commit did not converge.`, { cause: firstError });
+            }
+            await waitForActorAuthorityRetry(deadlineAtMs, signal, firstError);
+        }
+    }
+    async readActorAuthorityForRelocation(store, key, signal) {
+        try {
+            const current = await store.readAuthority(key, signal);
+            return current.kind === 'snapshot' ? current : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    rememberRoutedActorTransferTarget(actorId, target) {
+        if (target === undefined)
+            return;
+        const state = this.options.actorManager()?.getState(actorId);
+        if (state === undefined) {
+            return;
+        }
+        state.setBoundSessionTransferTarget(target);
+        state.setRemoteBoundSessionTarget((0, actors_1.mergeRemoteBoundSessionTarget)(target, state.remoteBoundSessionTarget));
+        if (target.bindingGeneration !== undefined) {
+            state.setBoundSessionBindingGeneration(target.bindingGeneration);
+        }
+    }
+    commitRoutedActor(actor, spotId, spot) {
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        state?.setJoinedSpot(spotId, spot);
+        const actorRef = state?.nativeActorRef;
+        const binding = state?.boundSessionTransferTarget;
+        if (actorRef !== undefined
+            && binding?.sessionNodeRid !== undefined
+            && binding.sessionRid !== undefined
+            && binding.bindingGeneration !== undefined) {
+            this.options.primaryMeshNode().restoreActorSessionBinding?.(actorRef, binding.sessionNodeRid, binding.sessionRid, binding.bindingGeneration);
+        }
+    }
+    bindRoutedActorRef(actor, actorRef) {
+        const node = this.options.primaryMeshNode();
+        const localActorRef = node.actorLookup(actor.context.actorId).actor;
+        const targetActorRef = {
+            actorId: actorRef.actorId,
+            nodeRid: node.status().routingId,
+            generation: localActorRef.generation > 0n
+                ? localActorRef.generation
+                : actorRef.objectGeneration
+        };
+        this.options.actorManager()?.getState(actor.context.actorId)?.setNativeActorRef(targetActorRef);
+    }
+    async claimRoutedActorLocation(actor, spotId, spotMeshName, joinedLocation) {
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        const actorType = state?.actorType;
+        const lifecycle = this.options.locationLifecycle();
+        if (state === undefined || actorType === undefined || lifecycle === undefined) {
+            return;
+        }
+        const node = this.options.primaryMeshNode();
+        const location = node.actorLookup(actor.context.actorId);
+        const spotGeneration = joinedLocation?.spotGeneration ?? location.spotGeneration;
+        const membershipEpoch = joinedLocation?.membershipEpoch ?? location.membershipEpoch;
+        if (spotGeneration <= 0n || membershipEpoch <= 0n) {
+            throw new Error(`Actor '${actor.context.actorId}' committed target location has invalid lifecycle generations.`);
+        }
+        // RoutingId is an opaque byte value, so the committed target is compared by
+        // value. Reference equality would reject a matching SPOT read back from the
+        // Core lookup.
+        if (joinedLocation === undefined
+            && (location.spotId === null
+                || location.spotId === undefined
+                || (0, routing_id_1.encodeRoutingIdStorageHex)(location.spotId)
+                    !== (0, routing_id_1.encodeRoutingIdStorageHex)(spotId))) {
+            throw new Error(`Actor '${actor.context.actorId}' Core location does not match the committed target SPOT.`);
+        }
+        const deadline = performance.now() + 5_000;
+        const ownerNodeGeneration = node.status().lifecycleGeneration;
+        if (ownerNodeGeneration <= 0n) {
+            throw new Error(`Actor '${actor.context.actorId}' owner MeshNode has no valid lifecycle generation.`);
+        }
+        const authority = await this.options.authorityStore()?.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actor.context.actorId));
+        if (authority?.kind === 'snapshot'
+            && authority.allocation.state === 'active'
+            && String(authority.allocation.descriptor.rid) === String(node.status().routingId)
+            && authority.allocation.descriptorLifecycleGeneration === ownerNodeGeneration) {
+            state.setLocationGeneration(authority.authorityOwnerGeneration);
+            state.setOwnerLeaseGeneration(authority.ownerLeaseGeneration);
+            state.setJoinedSpot(spotId, state.spot, membershipEpoch, spotGeneration);
+            await this.installNativeActorPacketTarget(state, spotId, spotGeneration, node);
+            return;
+        }
+        let claim;
+        for (;;) {
+            claim = await lifecycle.takeoverActorJoinedSpot(actorType, actor.context.actorId, (0, actors_1.toFrameworkActorRef)(state.nativeActorRef ?? location.actor, spotMeshName), spotMeshName, spotId, spotGeneration, membershipEpoch, ownerNodeGeneration, async () => state.clearAfterDestroy());
+            if (claim.status !== 'conflict' || performance.now() >= deadline) {
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        if (claim.status === 'conflict') {
+            throw new Error(`Actor '${actor.context.actorId}' target location takeover was rejected.`);
+        }
+        if (claim.generation !== undefined) {
+            state.setLocationGeneration(claim.generation);
+        }
+        if (claim.claimed !== undefined) {
+            state.setOwnerLeaseGeneration(claim.claimed.leaseGeneration);
+        }
+        state.setJoinedSpot(spotId, state.spot, membershipEpoch, spotGeneration);
+        state.markLocationOwned();
+        await this.installNativeActorPacketTarget(state, spotId, spotGeneration, node);
+    }
+    async installNativeActorPacketTarget(state, spotId, spotGeneration, node) {
+        const target = await this.options.spotRouteResolver?.()?.resolve(spotId);
+        if (target === undefined || target.spotKind === 'entry')
+            return;
+        if (!(0, routing_id_1.routingIdsEqual)(target.spotId, spotId)
+            || !(0, routing_id_1.routingIdsEqual)(target.targetNodeRid, node.status().routingId)
+            || target.targetSpotGeneration !== spotGeneration) {
+            throw new Error('Committed native Actor target does not match its Ready Spot route.');
+        }
+        state.setRemoteActorPacketTarget(target);
+    }
+    async claimNativeActorLocation(actor, spotId, spotMeshName) {
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        const previousLocation = this.options.locationLifecycle()?.actorLocationSnapshot(actor.context.actorId);
+        const snapshot = {
+            spotId: state?.spotId,
+            spot: state?.spot,
+            locationSpotId: previousLocation?.spotId,
+            spotMeshName: previousLocation?.meshName,
+            actorRef: previousLocation?.actorRef,
+            spotGeneration: previousLocation?.spotGeneration,
+            membershipEpoch: previousLocation?.membershipEpoch,
+            ownerNodeGeneration: previousLocation?.ownerNodeGeneration
+        };
+        await this.claimRoutedActorLocation(actor, spotId, spotMeshName);
+        return snapshot;
+    }
+    async publishRoutedActorOwnership(actor) {
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        const actorRef = state?.nativeActorRef;
+        const generation = state?.locationGeneration;
+        if (state === undefined || actorRef === undefined || generation === undefined)
+            return;
+        const boundSessionTarget = (0, actors_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget);
+        if (boundSessionTarget?.serviceWireRelocation === undefined)
+            return;
+        await this.publishBoundSessionOwnership(actor.context.actorId, actorRef, generation, boundSessionTarget, state.ownerLeaseGeneration);
+    }
+    async openRoutedActorSession(_actor) { }
+    clearRoutedActor(actor) {
+        this.options.actorManager()?.getState(actor.context.actorId)?.clearJoinedSpot();
+        this.options.clearRemoteActorPacketTarget(actor.context.actorId);
+    }
+    async rollbackNativeActorJoin(actor, snapshot) {
+        const state = this.options.actorManager()?.getState(actor.context.actorId);
+        const actorType = state?.actorType;
+        const lifecycle = this.options.locationLifecycle();
+        if (snapshot.spotId === undefined)
+            state?.clearJoinedSpot();
+        else
+            state?.setJoinedSpot(snapshot.spotId, snapshot.spot);
+        if (state?.ownsLocation !== true || actorType === undefined || lifecycle === undefined)
+            return;
+        if (snapshot.spotId === undefined) {
+            if (snapshot.locationSpotId === undefined
+                || snapshot.spotGeneration === undefined
+                || snapshot.membershipEpoch === undefined
+                || snapshot.ownerNodeGeneration === undefined) {
+                throw new Error(`Actor '${actor.context.actorId}' cannot restore its Entry SPOT location without its exact generation fields.`);
+            }
+            await lifecycle.notifyActorLeftSpot(actorType, actor.context.actorId, snapshot.locationSpotId, snapshot.spotGeneration, snapshot.membershipEpoch, snapshot.ownerNodeGeneration);
+            return;
+        }
+        if (snapshot.actorRef === undefined) {
+            throw new Error(`Actor '${actor.context.actorId}' cannot restore its previous SPOT location without a native ref.`);
+        }
+        if (snapshot.spotMeshName === undefined
+            || snapshot.spotGeneration === undefined
+            || snapshot.membershipEpoch === undefined
+            || snapshot.ownerNodeGeneration === undefined) {
+            throw new Error(`Actor '${actor.context.actorId}' cannot restore its previous SPOT location without its exact generation fields.`);
+        }
+        const restored = await lifecycle.takeoverActorJoinedSpot(actorType, actor.context.actorId, snapshot.actorRef, snapshot.spotMeshName, snapshot.spotId, snapshot.spotGeneration, snapshot.membershipEpoch, snapshot.ownerNodeGeneration, async () => state.clearAfterDestroy());
+        if (restored.status === 'conflict') {
+            throw new Error(`Actor '${actor.context.actorId}' previous SPOT location could not be restored.`);
+        }
+        if (restored.generation !== undefined)
+            state.setLocationGeneration(restored.generation);
+        if (restored.claimed !== undefined)
+            state.setOwnerLeaseGeneration(restored.claimed.leaseGeneration);
+    }
+    async rollbackRoutedActor(actor, signal) {
+        const manager = this.options.actorManager();
+        const state = manager?.getState(actor.context.actorId);
+        const actorType = state?.actorType;
+        const lifecycle = this.options.locationLifecycle();
+        let locationError;
+        if (state?.ownsLocation === true && actorType !== undefined && lifecycle !== undefined) {
+            try {
+                await lifecycle.releaseActor(actorType, actor.context.actorId);
+                state.markLocationReleased();
+            }
+            catch (error) {
+                locationError = error;
+                void lifecycle.releaseActorEventually(actorType, actor.context.actorId);
+            }
+        }
+        try {
+            await manager?.rollbackTransferredActor(actor, signal);
+        }
+        catch (rollbackError) {
+            if (locationError !== undefined) {
+                throw new AggregateError([locationError, rollbackError], `Actor '${actor.context.actorId}' target transfer rollback failed.`);
+            }
+            throw rollbackError;
+        }
+        if (locationError !== undefined)
+            throw locationError;
+    }
+    actorEntryNodeRid(actor) {
+        return this.options.actorManager()?.getState(actor.context.actorId)?.entryNodeRid;
+    }
+    requireActorManager(message) {
+        const actorManager = this.options.actorManager();
+        if (actorManager === undefined) {
+            throw new Error(message);
+        }
+        return actorManager;
+    }
+    async publishBoundSessionOwnership(actorId, actorRef, ownershipGeneration, target, targetOwnerLeaseGeneration) {
+        if (target === undefined) {
+            return;
+        }
+        const serviceFence = target.serviceWireRelocation;
+        const serviceWire = serviceFence === undefined
+            ? undefined
+            : this.options.sessionRelocationWire?.();
+        if (serviceFence === undefined) {
+            throw new Error(`Actor '${actorId}' command 44 has no service-wire relocation fence.`);
+        }
+        {
+            if (target.bindingGeneration === undefined
+                || target.previousAuthorityOwnerGeneration === undefined
+                || target.bindingGeneration <= 0n
+                || target.previousAuthorityOwnerGeneration < 0n
+                || ownershipGeneration <= target.previousAuthorityOwnerGeneration) {
+                throw new Error(`Actor '${actorId}' command 44 Session route fence is incomplete.`);
+            }
+            if (serviceWire === undefined) {
+                throw new Error(`Actor '${actorId}' command 44 service-wire bridge is unavailable.`);
+            }
+            const authority = await this.options.authorityStore()?.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId), this.options.shutdownSignal?.());
+            if (authority?.kind !== 'snapshot'
+                || authority.objectGeneration !== actorRef.generation
+                || authority.authorityOwnerGeneration !== ownershipGeneration
+                || authority.ownerLeaseGeneration !== targetOwnerLeaseGeneration
+                || String(authority.allocation.descriptor.rid) !== String(actorRef.nodeRid)) {
+                throw new Error(`Actor '${actorId}' command 44 target authority fence is stale.`);
+            }
+            await serviceWire.sendSessionRelocationRoute(target.routerChannelId, target.targetNodeRid, {
+                relocation: serviceFence.relocation,
+                coordinator: serviceFence.coordinator,
+                senderRole: 'target',
+                actor: {
+                    actorId,
+                    generation: actorRef.generation,
+                    nodeRid: String(actorRef.nodeRid)
+                },
+                session: serviceFence.session,
+                route: {
+                    action: 'commit',
+                    previousAuthorityOwnerGeneration: target.previousAuthorityOwnerGeneration,
+                    targetAuthorityOwnerGeneration: ownershipGeneration,
+                    targetNodeRid: String(actorRef.nodeRid),
+                    targetNodeGeneration: authority.allocation.descriptorLifecycleGeneration
+                }
+            }, this.options.shutdownSignal?.());
+            return;
+        }
+    }
+}
+exports.ZLinkActorTransferRuntime = ZLinkActorTransferRuntime;
+function relocationDebug(marker, detail) {
+    if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION !== '1')
+        return;
+    console.error('[zlink.runtime.relocation]', marker, detail);
+}
+function deferredJoinTerminalKey(root) {
+    return `${root.actor.actorId}:${root.actor.objectGeneration.toString()}:` +
+        (0, operation_identity_1.operationIdentityKey)(root.operationId);
+}
+function waitForOperation(operation, signal) {
+    if (signal === undefined)
+        return operation;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        operation.then(value => {
+            signal.removeEventListener('abort', abort);
+            resolve(value);
+        }, error => {
+            signal.removeEventListener('abort', abort);
+            reject(error);
+        });
+    });
+}
+function sameSourceActorAuthority(current, expected) {
+    return current.storeVersion.value === expected.storeVersion.value
+        && current.objectGeneration === expected.objectGeneration
+        && current.authorityOwnerGeneration === expected.authorityOwnerGeneration
+        && current.ownerId === expected.ownerId
+        && current.ownerLeaseGeneration === expected.ownerLeaseGeneration
+        && current.allocation.state === expected.allocation.state
+        && current.allocation.objectKind === expected.allocation.objectKind
+        && current.allocation.stableType === expected.allocation.stableType
+        && current.allocation.descriptor.meshName === expected.allocation.descriptor.meshName
+        && (0, routing_id_1.routingIdsEqual)(current.allocation.descriptor.rid, expected.allocation.descriptor.rid)
+        && current.allocation.descriptorLifecycleGeneration
+            === expected.allocation.descriptorLifecycleGeneration;
+}
+async function waitForActorAuthorityRetry(deadlineAtMs, signal, cause) {
+    signal?.throwIfAborted();
+    const remaining = deadlineAtMs - performance.now();
+    if (remaining <= 0) {
+        throw new Error('Actor target authority deadline expired.', { cause });
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, Math.min(10, remaining));
+        timer.unref();
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+        timer.refresh();
+    });
+}