@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -4,15 +4,18 @@ 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 runtime_message_1 = require("../backend/runtime-message");
+const diagnostics_1 = require("../diagnostics");
 const operation_identity_1 = require("../foundation/operation-identity");
+const service_stateful_wire_codec_1 = require("../foundation/service-stateful-wire-codec");
+const authority_key_codec_1 = require("../locations/authority-key-codec");
+const payload_codec_1 = require("../messaging/payload-codec");
+const routing_id_1 = require("../routing-id");
 const bounded_replay_map_1 = require("./bounded-replay-map");
+const TRANSFER_RESOLUTION_TIMEOUT_MS = 5_000;
+const TRANSFER_POLL_INTERVAL_MS = 10;
 const DEFERRED_JOIN_TERMINAL_CAPACITY = 4096;
 /** Converts only committed actor authority evidence into a Message Follow fence. */
 function committedActorOwnerFence(actorId, targetActorRef, authority) {
@@ -54,21 +57,22 @@ function createHandoffReplayGate() {
 }
 class ZLinkActorTransferRuntime {
     options;
-    sourceDepartureTasks = new Map();
     coreSourceLeaves = new Map();
+    //  Spot Actor membership sections 4-5: Join completion idempotency is
+    //  process-local. These maps end with the process; nothing is replayed.
     activeDeferredJoinTerminals = new Map();
     deferredJoinTerminals = new bounded_replay_map_1.BoundedReplayMap(DEFERRED_JOIN_TERMINAL_CAPACITY);
     constructor(options) {
         this.options = options;
     }
-    beginDeferredActorHandoff(actor, state, operationId) {
+    beginDeferredActorHandoff(actor, state) {
         const actorId = actor.context.actorId;
-        this.options.actorHandoff.beginProvisional(actorId, operationId, requireSourceObjectGeneration(actorId, state));
+        this.options.actorHandoff.beginProvisional(actorId, requireSourceObjectGeneration(actorId, state));
     }
-    promoteDeferredActorHandoff(actor, _state, operationId) {
-        this.options.actorHandoff.promoteProvisional(actor.context.actorId, operationId);
+    promoteDeferredActorHandoff(actor, _state) {
+        this.options.actorHandoff.promoteProvisional(actor.context.actorId);
     }
-    async completeDeferredActorHandoff(actor, target, _targetActorRef, operationId) {
+    async completeDeferredActorHandoff(actor, target, _targetActorRef) {
         const actorId = actor.context.actorId;
         if (!this.options.actorHandoff.isProvisional(actorId))
             return;
@@ -76,91 +80,77 @@ class ZLinkActorTransferRuntime {
         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);
+        const admitted = this.options.actorHandoff.admitDeferredPrefix(actorId, (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);
+    async cancelDeferredActorHandoff(actor, state) {
+        const admitted = this.admitDeferredSourcePrefix(actor, state);
         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);
+    prepareDeferredJoinAccepted(actorId, operationId, actorRef, rawReply, replyContentType) {
+        return (0, actors_1.createDeferredJoinCompletion)(actorId, operationId, actorRef, rawReply, replyContentType);
     }
-    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) {
+    /**
+     * Runs the completion callback once in the target Actor mailbox.
+     * A repeated delivery of the same OperationId in this process observes the
+     * first terminal (completion idempotency only).
+     */
+    async deliverDeferredJoinCompletion(completion, actor, actorRef, submitMailbox, signal) {
+        const terminalKey = deferredJoinTerminalKey(completion);
+        if (this.deferredJoinTerminals.get(terminalKey) !== undefined) {
             this.deferredJoinTerminals.touch(terminalKey);
-            return terminal;
+            return;
         }
         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) {
+        const delivery = this.deliverDeferredJoinCompletionCore(completion, actor, actorRef, submitMailbox);
+        this.activeDeferredJoinTerminals.set(terminalKey, delivery);
+        void delivery.then(() => {
+            this.deferredJoinTerminals.remember(terminalKey, true);
+            if (this.activeDeferredJoinTerminals.get(terminalKey) === delivery) {
                 this.activeDeferredJoinTerminals.delete(terminalKey);
             }
         }, () => {
-            if (this.activeDeferredJoinTerminals.get(terminalKey) === completion) {
+            if (this.activeDeferredJoinTerminals.get(terminalKey) === delivery) {
                 this.activeDeferredJoinTerminals.delete(terminalKey);
             }
         });
-        return await waitForOperation(completion, signal);
+        return await waitForOperation(delivery, signal);
     }
-    async commitAndDeliverDeferredJoinAcceptedCore(root, actor, actorRef, submitMailbox) {
+    async deliverDeferredJoinCompletionCore(completion, 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;
-                }
+        if (completion.actor.actorId !== currentActorRef.actorId ||
+            completion.actor.objectGeneration !== currentActorRef.objectGeneration) {
+            throw new Error('Deferred Join completion generation fence is stale ' +
+                `(completion ${completion.actor.actorId}/${completion.actor.objectGeneration}, ` +
+                `actor ${currentActorRef.actorId}/${currentActorRef.objectGeneration}).`);
+        }
+        await submitMailbox(async () => {
+            if (completion.status === 'failed') {
+                await actor.onJoinCompleted?.({
+                    status: 'failed',
+                    operationId: completion.operationId,
+                    kind: completion.kind
+                });
+                return;
             }
-        }
-        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);
+            await actor.onJoinCompleted?.({
+                status: 'accepted',
+                operationId: completion.operationId,
+                actor: currentActorRef,
+                reply: completion.rawReply.byteLength === 0
+                    ? undefined
+                    : completion.replyContentType === undefined
+                        ? contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(completion.rawReply))
+                        : (0, payload_codec_1.wrapFrameworkPayloadMessage)(runtime_message_1.ZLinkBufferMessage.from(completion.rawReply), this.options.messageSerializers, completion.replyContentType, undefined, 'reply')
+            });
+        });
     }
     async prepareSourceActorLeave(actor, sourceSpotId, signal) {
         if (sourceSpotId !== undefined) {
@@ -182,10 +172,9 @@ class ZLinkActorTransferRuntime {
         }
         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);
+    async beginSourceActorMove(actor, state, deferredJoin = false) {
+        if (deferredJoin && this.options.actorHandoff.isProvisional(actor.context.actorId)) {
+            this.promoteDeferredActorHandoff(actor, state);
         }
         state.beginMove();
         if (!this.options.actorHandoff.isActive(actor.context.actorId)) {
@@ -193,30 +182,34 @@ class ZLinkActorTransferRuntime {
         }
         try {
             if (state.spotId !== undefined) {
-                relocationDebug('source_actor_move.await_spot_transfer', {
-                    actorId: actor.context.actorId,
-                    spotId: String(state.spotId)
-                });
+                if ((0, diagnostics_1.isRelocationDebugEnabled)()) {
+                    (0, diagnostics_1.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)
-                });
+                if ((0, diagnostics_1.isRelocationDebugEnabled)()) {
+                    (0, diagnostics_1.relocationDebug)('source_actor_move.spot_transfer_complete', {
+                        actorId: actor.context.actorId,
+                        spotId: String(state.spotId)
+                    });
+                }
             }
         }
         catch (error) {
-            if (deferredOperationId === undefined) {
+            if (!deferredJoin) {
                 this.options.actorHandoff.cancel(actor.context.actorId);
             }
             else {
-                const admitted = this.admitDeferredSourcePrefix(actor, state, deferredOperationId);
+                const admitted = this.admitDeferredSourcePrefix(actor, state);
                 void this.observeHandoffReplay(admitted.terminal);
             }
             state.endMove();
             throw error;
         }
     }
-    async cancelSourceActorMove(actor, state, deferredOperationId, replayStart = Promise.resolve()) {
+    async cancelSourceActorMove(actor, state, deferredJoin = false, replayStart = Promise.resolve()) {
         try {
             if (state.spotId !== undefined) {
                 await this.options.spotManager()?.cancelActorTransfer(state.spotId, actor.context.actorId);
@@ -224,12 +217,12 @@ class ZLinkActorTransferRuntime {
         }
         finally {
             try {
-                if (deferredOperationId === undefined) {
+                if (!deferredJoin) {
                     const admitted = this.admitCanceledSourcePrefix(actor, state, replayStart);
                     void this.observeHandoffReplay(admitted.terminal);
                 }
                 else {
-                    const admitted = this.admitDeferredSourcePrefix(actor, state, deferredOperationId, replayStart);
+                    const admitted = this.admitDeferredSourcePrefix(actor, state, replayStart);
                     void this.observeHandoffReplay(admitted.terminal);
                 }
             }
@@ -249,13 +242,13 @@ class ZLinkActorTransferRuntime {
         }
         return this.options.actorHandoff.admitCanceledPrefix(actor.context.actorId, queue, this.options.prepareApplicationJob, replayStart);
     }
-    admitDeferredSourcePrefix(actor, state, operationId, replayStart = Promise.resolve()) {
+    admitDeferredSourcePrefix(actor, state, 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);
+        return this.options.actorHandoff.admitDeferredPrefix(actor.context.actorId, queue, this.options.prepareApplicationJob, replayStart);
     }
     async observeHandoffReplay(release) {
         try {
@@ -281,19 +274,19 @@ class ZLinkActorTransferRuntime {
         }
         return (drain) => manager.admitRoutedActorPacketPrefix(sourceSpotId, actor.context.actorId, drain);
     }
-    async prepareSource(actor, state, signal, lifecycleAuthority = 'framework', deferredOperationId, relocation) {
-        await this.beginSourceActorMove(actor, state, deferredOperationId);
+    async prepareSource(actor, state, signal, lifecycleAuthority = 'framework', deferredJoin = false, relocation) {
+        await this.beginSourceActorMove(actor, state, deferredJoin);
         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;
+        // The relocation operation owns its Session seal; the Actor keeps only
+        // its current binding (Session–Actor binding §8.1).
+        let sealedSession;
         try {
-            if (state.remoteBoundSessionTarget !== undefined) {
-                sealId = (0, node_crypto_1.randomUUID)();
-                const sealedTarget = await this.sealBoundSessionRoute(actor, state, signal, relocation);
-                state.setRemoteBoundSessionTarget(sealedTarget);
+            if (state.boundSession !== undefined) {
+                sealedSession = await this.sealBoundSessionRoute(actor, state, signal, relocation);
                 this.options.actorHandoff.sealConnectionBoundIngress(actor.context.actorId);
             }
             const transfer = await this.options.actorTransferRegistry.transferOut(actor, state.actorType, signal);
@@ -369,8 +362,7 @@ class ZLinkActorTransferRuntime {
                             // 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);
+                                this.scheduleSourceDeparture(actor, sourceSpotId, true, [error]);
                             });
                         }
                         else {
@@ -386,10 +378,10 @@ class ZLinkActorTransferRuntime {
                     this.coreSourceLeaves.delete(actor.context.actorId);
                     const replayGate = createHandoffReplayGate();
                     try {
-                        await this.cancelSourceActorMove(actor, state, deferredOperationId, replayGate.start);
+                        await this.cancelSourceActorMove(actor, state, deferredJoin, replayGate.start);
                         await this.restoreSourceActor(actor, sourceSpotId);
-                        if (sealId !== undefined) {
-                            await this.observeBoundSessionSealAbort(actor, state);
+                        if (sealedSession !== undefined) {
+                            await this.observeBoundSessionSealAbort(actor, state, sealedSession);
                         }
                     }
                     finally {
@@ -402,11 +394,11 @@ class ZLinkActorTransferRuntime {
             relocationMetric?.complete('failed');
             const replayGate = createHandoffReplayGate();
             try {
-                await this.cancelSourceActorMove(actor, state, deferredOperationId, replayGate.start);
+                await this.cancelSourceActorMove(actor, state, deferredJoin, replayGate.start);
                 if (sourceLeaveStarted)
                     await this.restoreSourceActor(actor, sourceSpotId);
-                if (sealId !== undefined) {
-                    await this.observeBoundSessionSealAbort(actor, state);
+                if (sealedSession !== undefined) {
+                    await this.observeBoundSessionSealAbort(actor, state, sealedSession);
                 }
             }
             catch (rollbackError) {
@@ -419,10 +411,12 @@ class ZLinkActorTransferRuntime {
         }
     }
     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 ((0, diagnostics_1.isRelocationDebugEnabled)()) {
+            (0, diagnostics_1.relocationDebug)('maintenance_session.begin', {
+                actorId: actor.context.actorId,
+                spotId: state.spotId === undefined ? undefined : String(state.spotId)
+            });
+        }
         if (manageMembership) {
             await this.beginSourceActorMove(actor, state);
         }
@@ -430,21 +424,22 @@ class ZLinkActorTransferRuntime {
             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;
+        if ((0, diagnostics_1.isRelocationDebugEnabled)()) {
+            (0, diagnostics_1.relocationDebug)('maintenance_session.source_move_complete', {
+                actorId: actor.context.actorId
+            });
+        }
+        let sealedSession;
         try {
-            if (state.remoteBoundSessionTarget !== undefined) {
-                sealId = (0, node_crypto_1.randomUUID)();
-                state.setRemoteBoundSessionTarget(await this.sealBoundSessionRoute(actor, state, signal, relocation));
+            if (state.boundSession !== undefined) {
+                sealedSession = 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,
+                target: sealedSession,
                 handoffBacklog,
                 takeRelocationRelay: () => this.options.actorHandoff.takeRelocationRelay(actor.context.actorId),
                 setReplayResults: (results) => {
@@ -452,19 +447,44 @@ class ZLinkActorTransferRuntime {
                         replayResults = [...results];
                 },
                 commit: async (target, targetActorRef, targetOwnerFence) => {
-                    if (terminal === 'rolledBack')
+                    if (terminal !== 'prepared')
                         return;
-                    if (terminal === 'prepared') {
+                    terminal = 'committed';
+                    const failures = [];
+                    try {
                         this.options.actorHandoff.complete(actor.context.actorId, target, targetActorRef, replayResults, targetOwnerFence);
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    try {
                         if (manageMembership && state.spotId !== undefined) {
                             await this.options
                                 .spotManager()
                                 ?.commitActorLeaveAfterTransfer(state.spotId, actor.context.actorId);
                         }
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    try {
                         state.endMove();
-                        terminal = 'committed';
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                    if (failures.length > 0) {
+                        throw failures.length === 1
+                            ? failures[0]
+                            : new AggregateError(failures, 'Actor source retirement failed.');
                     }
                 },
+                discard: (reason) => {
+                    if (terminal !== 'prepared')
+                        return;
+                    terminal = 'rolledBack';
+                    this.options.actorHandoff.failPending(actor.context.actorId, reason);
+                },
                 rollback: async () => {
                     if (terminal !== 'prepared')
                         return;
@@ -483,8 +503,8 @@ class ZLinkActorTransferRuntime {
                                 state.endMove();
                             }
                         }
-                        if (sealId !== undefined) {
-                            await this.observeBoundSessionSealAbort(actor, state);
+                        if (sealedSession !== undefined) {
+                            await this.observeBoundSessionSealAbort(actor, state, sealedSession);
                         }
                     }
                     finally {
@@ -518,8 +538,8 @@ class ZLinkActorTransferRuntime {
                         state.endMove();
                     }
                 }
-                if (sourceRestored && sealId !== undefined) {
-                    await this.observeBoundSessionSealAbort(actor, state);
+                if (sourceRestored && sealedSession !== undefined) {
+                    await this.observeBoundSessionSealAbort(actor, state, sealedSession);
                 }
             }
             finally {
@@ -571,7 +591,7 @@ class ZLinkActorTransferRuntime {
         return this.options.actorHandoff.acceptRelocatedTerminalRelay(operationId, replyRouteId, undefined, result, sourceNodeRid, targetAuthorityOwnerGeneration);
     }
     async sealBoundSessionRoute(actor, state, signal, relocation) {
-        const target = state.remoteBoundSessionTarget;
+        const target = state.boundSession;
         const actorRef = state.nativeActorRef;
         if (target === undefined ||
             actorRef === undefined ||
@@ -651,12 +671,9 @@ class ZLinkActorTransferRuntime {
             serviceWireRelocation: { relocation, coordinator, session }
         };
     }
-    async abortBoundSessionRouteSeal(actor, state, targetOverride) {
-        const target = targetOverride ??
-            (0, actors_1.preferredRemoteBoundSessionTarget)(state.remoteBoundSessionTarget, state.boundSessionTransferTarget);
+    async abortBoundSessionRouteSeal(actor, state, target) {
         const actorRef = state.nativeActorRef;
-        if (target === undefined ||
-            actorRef === undefined ||
+        if (actorRef === undefined ||
             target.bindingGeneration === undefined ||
             target.previousAuthorityOwnerGeneration === undefined ||
             target.previousOwnerLeaseGeneration === undefined) {
@@ -687,9 +704,9 @@ class ZLinkActorTransferRuntime {
         }
         await serviceWire.sendSessionRelocationRoute(target.routerChannelId, target.targetNodeRid, route, this.options.shutdownSignal?.());
     }
-    async observeBoundSessionSealAbort(actor, state) {
+    async observeBoundSessionSealAbort(actor, state, sealedSession) {
         try {
-            await this.abortBoundSessionRouteSeal(actor, state);
+            await this.abortBoundSessionRouteSeal(actor, state, sealedSession);
         }
         catch (error) {
             try {
@@ -725,44 +742,52 @@ class ZLinkActorTransferRuntime {
         });
         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);
+    scheduleSourceDeparture(actor, sourceSpotId, releaseLocation, failures = []) {
+        void this.finishSourceDeparture(actor, sourceSpotId, releaseLocation, failures);
     }
-    async finishSourceDeparture(actor, sourceSpotId, releaseLocation) {
-        const retry = new actor_retry_delay_1.ZLinkActorRetryDelay();
-        while (this.options.shutdownSignal?.()?.aborted !== true) {
+    async finishSourceDeparture(actor, sourceSpotId, releaseLocation, failures) {
+        if (sourceSpotId !== undefined) {
+            try {
+                await this.options
+                    .spotManager()
+                    ?.commitActorLeaveAfterTransfer(sourceSpotId, actor.context.actorId);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (releaseLocation) {
             try {
-                if (sourceSpotId !== undefined) {
+                const state = this.options.actorManager()?.getState(actor.context.actorId);
+                if (state?.actorType !== undefined && state.ownsLocation) {
                     await this.options
-                        .spotManager()
-                        ?.commitActorLeaveAfterTransfer(sourceSpotId, actor.context.actorId);
+                        .locationLifecycle()
+                        ?.releaseActor(state.actorType, actor.context.actorId);
+                    state.markLocationReleased();
                 }
-                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;
+                failures.push(error);
             }
         }
+        try {
+            // Message Follow keeps its route separately from the retired application instance.
+            await this.options.actorManager()?.completeCoreRelocationSource(actor.context.actorId);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            this.options.onSourceDepartureCompleted?.(actor.context.actorId);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length > 0) {
+            this.options.reportPostCommitError?.(failures.length === 1
+                ? failures[0]
+                : new AggregateError(failures, 'Actor source retirement failed.'));
+        }
     }
     async getOrCreateRoutedActor(actorId, actorType, actorRef, remoteBoundSessionTarget, actorCreateRequest, signal) {
         const actorManager = this.requireActorManager('Routed actor join requires ZLINK_ACTOR_MANAGER.');
@@ -777,7 +802,9 @@ class ZLinkActorTransferRuntime {
         }
         if (actorRef !== undefined) {
             state.setNativeActorRef(actorRef);
-            state.setRemoteBoundSessionTarget(remoteBoundSessionTarget);
+            if (remoteBoundSessionTarget !== undefined) {
+                state.installBoundSessionBinding(remoteBoundSessionTarget);
+            }
             return { actor, actorRef: actorRef };
         }
         return { actor, actorRef: state.ensureNativeActorRef(this.options.primaryMeshNode()) };
@@ -791,12 +818,10 @@ class ZLinkActorTransferRuntime {
         }
         if (actorEntryNodeRid !== undefined)
             state.setEntryNodeRid(actorEntryNodeRid);
-        state.setBoundSessionTransferTarget(remoteBoundSessionTarget);
+        // The relocation delivers the binding it carried; the target installs it
+        // through the one install rule (Session–Actor binding §6, §8).
         if (remoteBoundSessionTarget !== undefined) {
-            state.setRemoteBoundSessionTarget((0, actors_1.mergeRemoteBoundSessionTarget)(remoteBoundSessionTarget, state.remoteBoundSessionTarget));
-        }
-        if (remoteBoundSessionTarget?.bindingGeneration !== undefined) {
-            state.setBoundSessionBindingGeneration(remoteBoundSessionTarget.bindingGeneration);
+            state.installBoundSessionBinding(remoteBoundSessionTarget);
         }
         return {
             actor: materialized.actor,
@@ -935,24 +960,11 @@ class ZLinkActorTransferRuntime {
             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;
+        const binding = state?.boundSession;
         if (actorRef !== undefined &&
             binding?.sessionNodeRid !== undefined &&
             binding.sessionRid !== undefined &&
@@ -996,7 +1008,7 @@ class ZLinkActorTransferRuntime {
                     (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 deadline = performance.now() + TRANSFER_RESOLUTION_TIMEOUT_MS;
         const ownerNodeGeneration = node.status().lifecycleGeneration;
         if (ownerNodeGeneration <= 0n) {
             throw new Error(`Actor '${actor.context.actorId}' owner MeshNode has no valid lifecycle generation.`);
@@ -1020,7 +1032,7 @@ class ZLinkActorTransferRuntime {
             if (claim.status !== 'conflict' || performance.now() >= deadline) {
                 break;
             }
-            await new Promise((resolve) => setTimeout(resolve, 10));
+            await new Promise((resolve) => setTimeout(resolve, TRANSFER_POLL_INTERVAL_MS));
         }
         if (claim.status === 'conflict') {
             throw new Error(`Actor '${actor.context.actorId}' target location takeover was rejected.`);
@@ -1046,78 +1058,25 @@ class ZLinkActorTransferRuntime {
         }
         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) {
+    /**
+     * Publishes the committed route of the Session seal that the relocation
+     * operation carried to this target (command 44, Session–Actor binding §8.2).
+     */
+    async publishRoutedActorOwnership(actor, sealedSession) {
         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)
+        if (sealedSession?.serviceWireRelocation === undefined)
             return;
-        await this.publishBoundSessionOwnership(actor.context.actorId, actorRef, generation, boundSessionTarget, state.ownerLeaseGeneration);
+        await this.publishBoundSessionOwnership(actor.context.actorId, actorRef, generation, sealedSession, 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);
@@ -1131,7 +1090,6 @@ class ZLinkActorTransferRuntime {
             }
             catch (error) {
                 locationError = error;
-                void lifecycle.releaseActorEventually(actorType, actor.context.actorId);
             }
         }
         try {
@@ -1201,7 +1159,8 @@ class ZLinkActorTransferRuntime {
                     previousAuthorityOwnerGeneration: target.previousAuthorityOwnerGeneration,
                     targetAuthorityOwnerGeneration: ownershipGeneration,
                     targetNodeRid: String(actorRef.nodeRid),
-                    targetNodeGeneration: authority.allocation.descriptorLifecycleGeneration
+                    targetNodeGeneration: authority.allocation.descriptorLifecycleGeneration,
+                    targetOwnerLeaseGeneration: authority.ownerLeaseGeneration
                 }
             }, this.options.shutdownSignal?.());
             return;
@@ -1209,14 +1168,9 @@ class ZLinkActorTransferRuntime {
     }
 }
 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 deferredJoinTerminalKey(completion) {
+    return (`${completion.actor.actorId}:${completion.actor.objectGeneration.toString()}:` +
+        (0, operation_identity_1.operationIdentityKey)(completion.operationId));
 }
 function waitForOperation(operation, signal) {
     if (signal === undefined)
@@ -1256,7 +1210,7 @@ async function waitForActorAuthorityRetry(deadlineAtMs, signal, cause) {
         throw new Error('Actor target authority deadline expired.', { cause });
     }
     await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, Math.min(10, remaining));
+        const timer = setTimeout(resolve, Math.min(TRANSFER_POLL_INTERVAL_MS, remaining));
         timer.unref();
         const abort = () => {
             clearTimeout(timer);