@zlink-systems/framework 0.26.0 → 0.27.0

package/dist/runtime/host/actor-transfer-runtime.d.ts

@@ -1,18 +1,16 @@
-import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
-import { ZLinkMessage } from '../../contracts';
-import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
-import type { ZLinkAuthorityStore, ZLinkObjectCreationStore, ZLinkOwnerLeaseStore } from '../locations/internal-store-contracts';
+import { type ActorRef, type RoutingId, type ZLinkActor, type ZLinkActorJoinOperationId, type ZLinkMessageSerializer, type ZLinkSpot, ZLinkMessage } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend';
 import { type ZLinkActorHandoffCoordinator, type ZLinkActorHandoffReplayPreparation, type ZLinkActorRoutedJoinTransport, type ZLinkActorTransferRegistry, type ZLinkDeferredJoinCompletion, type ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult, ZLinkActorHandoffTerminalAcceptance, ZLinkActorHandoffTerminalAck } from '../actors/actor-handoff';
+import { type ZLinkActorMessageFollowOwnerFence } from '../actors/actor-message-follow-context';
 import type { ZLinkActorRuntimeState } from '../actors/actor-runtime-state';
+import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend';
+import { type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed, type ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
 import type { ZLinkLocationLifecycle } from '../locations';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthorityStore, ZLinkObjectCreationStore, ZLinkOwnerLeaseStore } from '../locations/internal-store-contracts';
 import type { DefaultZLinkSpotManager } from '../spots';
 import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult, ZLinkActorHandoffTerminalAcceptance, ZLinkActorHandoffTerminalAck } from '../actors/actor-handoff';
-import type { ZLinkNativeActorJoinSnapshot } from '../spots/spot-runtime-ports';
-import { type ZLinkActorMessageFollowOwnerFence } from '../actors/actor-message-follow-context';
-import type { ServiceSessionRelocationRoute, ServiceSessionRelocationSeal, ServiceSessionRelocationSealed, ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
 interface ZLinkSessionRelocationWirePort {
     requestSessionRelocationSeal(meshName: string, targetNodeRid: RoutingId, request: ServiceSessionRelocationSeal, signal?: AbortSignal): Promise<ServiceSessionRelocationSealed>;
     sendSessionRelocationRoute(meshName: string, targetNodeRid: RoutingId, request: ServiceSessionRelocationRoute, signal?: AbortSignal): Promise<void>;
@@ -28,7 +26,7 @@ export interface ZLinkActorTransferRuntimeActorManager {
         readonly actor: ZLinkActor;
         readonly actorRef: ActorRef;
     }>;
-    prepareRelocationActor(actorId: string, actorType: string, objectGeneration: bigint, authorityOwnerGeneration: bigint, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, signal?: AbortSignal, transfer?: {
+    prepareRelocationActor(actorId: string, actorType: string, objectGeneration: bigint, authorityOwnerGeneration: bigint, spotId: RoutingId | undefined, spotGeneration: bigint, membershipEpoch: bigint, signal?: AbortSignal, transfer?: {
         readonly adapterKey: string;
         readonly state: ZLinkMessage;
     }): Promise<ZLinkActor>;
@@ -65,7 +63,6 @@ export interface ZLinkActorTransferRuntimeOptions {
 }
 export declare class ZLinkActorTransferRuntime {
     private readonly options;
-    private readonly sourceDepartureTasks;
     private readonly coreSourceLeaves;
     private readonly activeDeferredJoinTerminals;
     private readonly deferredJoinTerminals;
@@ -76,12 +73,12 @@ export declare class ZLinkActorTransferRuntime {
     cancelDeferredActorHandoff(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
     prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string): ZLinkDeferredJoinCompletion;
     /**
-     * Runs the Accepted completion callback once in the target Actor mailbox.
+     * 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).
      */
-    deliverDeferredJoinAccepted(completion: ZLinkDeferredJoinCompletion, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<void>;
-    private deliverDeferredJoinAcceptedCore;
+    deliverDeferredJoinCompletion(completion: ZLinkDeferredJoinCompletion, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<void>;
+    private deliverDeferredJoinCompletionCore;
     private prepareSourceActorLeave;
     private restoreSourceActor;
     private beginSourceActorMove;
@@ -130,7 +127,6 @@ export declare class ZLinkActorTransferRuntime {
     }>;
     commitRoutedActorAuthority(actor: ZLinkActor, sourceActorRef: ActorRef, transferId: string, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, deadlineUnixMs: number, signal?: AbortSignal): Promise<ZLinkAuthoritySnapshot>;
     private readActorAuthorityForRelocation;
-    rememberRoutedActorTransferTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
     commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
     bindRoutedActorRef(actor: ZLinkActor, actorRef: ActorRef): void;
     claimRoutedActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string, joinedLocation?: {
@@ -138,11 +134,13 @@ export declare class ZLinkActorTransferRuntime {
         readonly membershipEpoch: bigint;
     }): Promise<void>;
     private installNativeActorPacketTarget;
-    claimNativeActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string): Promise<ZLinkNativeActorJoinSnapshot>;
-    publishRoutedActorOwnership(actor: ZLinkActor): Promise<void>;
+    /**
+     * Publishes the committed route of the Session seal that the relocation
+     * operation carried to this target (command 44, Session–Actor binding §8.2).
+     */
+    publishRoutedActorOwnership(actor: ZLinkActor, sealedSession: ZLinkRemoteBoundSessionTarget | undefined): Promise<void>;
     openRoutedActorSession(_actor: ZLinkActor): Promise<void>;
     clearRoutedActor(actor: ZLinkActor): void;
-    rollbackNativeActorJoin(actor: ZLinkActor, snapshot: ZLinkNativeActorJoinSnapshot): Promise<void>;
     rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
     private requireActorManager;

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

@@ -4,16 +4,18 @@ exports.ZLinkActorTransferRuntime = void 0;
 exports.committedActorOwnerFence = committedActorOwnerFence;
 const node_crypto_1 = require("node:crypto");
 const contracts_1 = require("../../contracts");
-const runtime_message_1 = require("../backend/runtime-message");
-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) {
@@ -55,7 +57,6 @@ 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.
@@ -90,11 +91,11 @@ class ZLinkActorTransferRuntime {
         return (0, actors_1.createDeferredJoinCompletion)(actorId, operationId, actorRef, rawReply, replyContentType);
     }
     /**
-     * Runs the Accepted completion callback once in the target Actor mailbox.
+     * 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 deliverDeferredJoinAccepted(completion, actor, actorRef, submitMailbox, signal) {
+    async deliverDeferredJoinCompletion(completion, actor, actorRef, submitMailbox, signal) {
         const terminalKey = deferredJoinTerminalKey(completion);
         if (this.deferredJoinTerminals.get(terminalKey) !== undefined) {
             this.deferredJoinTerminals.touch(terminalKey);
@@ -103,7 +104,7 @@ class ZLinkActorTransferRuntime {
         const active = this.activeDeferredJoinTerminals.get(terminalKey);
         if (active !== undefined)
             return await waitForOperation(active, signal);
-        const delivery = this.deliverDeferredJoinAcceptedCore(completion, actor, actorRef, submitMailbox);
+        const delivery = this.deliverDeferredJoinCompletionCore(completion, actor, actorRef, submitMailbox);
         this.activeDeferredJoinTerminals.set(terminalKey, delivery);
         void delivery.then(() => {
             this.deferredJoinTerminals.remember(terminalKey, true);
@@ -117,7 +118,7 @@ class ZLinkActorTransferRuntime {
         });
         return await waitForOperation(delivery, signal);
     }
-    async deliverDeferredJoinAcceptedCore(completion, actor, actorRef, submitMailbox) {
+    async deliverDeferredJoinCompletionCore(completion, actor, actorRef, submitMailbox) {
         const targetActorRef = this.options
             .actorManager()
             ?.getState(actor.context.actorId)?.nativeActorRef;
@@ -131,6 +132,14 @@ class ZLinkActorTransferRuntime {
                 `actor ${currentActorRef.actorId}/${currentActorRef.objectGeneration}).`);
         }
         await submitMailbox(async () => {
+            if (completion.status === 'failed') {
+                await actor.onJoinCompleted?.({
+                    status: 'failed',
+                    operationId: completion.operationId,
+                    kind: completion.kind
+                });
+                return;
+            }
             await actor.onJoinCompleted?.({
                 status: 'accepted',
                 operationId: completion.operationId,
@@ -173,15 +182,19 @@ 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) {
@@ -268,12 +281,12 @@ class ZLinkActorTransferRuntime {
             : 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);
@@ -349,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 {
@@ -368,8 +380,8 @@ class ZLinkActorTransferRuntime {
                     try {
                         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 {
@@ -385,8 +397,8 @@ class ZLinkActorTransferRuntime {
                 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) {
@@ -399,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);
         }
@@ -410,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) => {
@@ -432,17 +447,36 @@ 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) => {
@@ -469,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 {
@@ -504,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 {
@@ -557,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 ||
@@ -637,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) {
@@ -673,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 {
@@ -711,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 {
-                if (sourceSpotId !== undefined) {
+                await this.options
+                    .spotManager()
+                    ?.commitActorLeaveAfterTransfer(sourceSpotId, actor.context.actorId);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (releaseLocation) {
+            try {
+                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.');
@@ -763,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()) };
@@ -777,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,
@@ -921,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 &&
@@ -982,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.`);
@@ -1006,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.`);
@@ -1032,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);
@@ -1117,7 +1090,6 @@ class ZLinkActorTransferRuntime {
             }
             catch (error) {
                 locationError = error;
-                void lifecycle.releaseActorEventually(actorType, actor.context.actorId);
             }
         }
         try {
@@ -1196,11 +1168,6 @@ 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(completion) {
     return (`${completion.actor.actorId}:${completion.actor.objectGeneration.toString()}:` +
         (0, operation_identity_1.operationIdentityKey)(completion.operationId));
@@ -1243,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);