@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/host/actor-transfer-runtime.ts

@@ -1,72 +1,72 @@
-import { createHash, randomUUID } from 'node:crypto';
-import type {
-  ActorRef,
-  RoutingId,
-  ZLinkActor,
-  ZLinkActorJoinOperationId,
+import { createHash } from 'node:crypto';
+import {
+  type ActorRef,
+  type RoutingId,
+  type ZLinkActor,
+  type ZLinkActorJoinOperationId,
+  type ZLinkMessageSerializer,
+  type ZLinkSpot,
+  ZLinkEncodedPayload,
   ZLinkMessage,
-  ZLinkMessageSerializer,
-  ZLinkRelocationStore,
-  ZLinkSpot
+  ZLinkSpotKind
 } from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
-import type {
-  ZLinkAggregateId,
-  ZLinkAuthoritySnapshot,
-  ZLinkLocationOwnerToken
-} from '../locations/internal-location-contracts';
-import type {
-  ZLinkAuthorityStore,
-  ZLinkObjectCreationStore,
-  ZLinkOwnerLeaseStore
-} from '../locations/internal-store-contracts';
-import { encodeAuthorityKey } from '../locations/authority-key-codec';
+
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend';
 import {
+  createDeferredJoinCompletion,
+  rewriteActorAuthorityRoute,
   toFrameworkActorRef,
-  mergeRemoteBoundSessionTarget,
-  preferredRemoteBoundSessionTarget,
   type ZLinkActorHandoffCoordinator,
   type ZLinkActorHandoffPrefixAdmission,
   type ZLinkActorHandoffPrefixQueue,
   type ZLinkActorHandoffReplayPreparation,
   type ZLinkActorRoutedJoinTransport,
   type ZLinkActorTransferRegistry,
-  isDeferredJoinAcceptedRootPublication,
-  ZLinkDeferredJoinAcceptedJournal,
-  rewriteActorAuthorityRoute,
-  type ZLinkDeferredJoinAcceptedRoot,
-  type ZLinkDeferredJoinRootIdentity,
+  type ZLinkDeferredJoinCompletion,
   type ZLinkRemoteBoundSessionTarget
 } from '../actors';
-import type { ZLinkActorRuntimeState } from '../actors/actor-runtime-state';
-import { ZLinkActorRetryDelay } from '../actors/actor-retry-delay';
-import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
-import type { ZLinkLocationLifecycle } from '../locations';
-import { wrapFrameworkPayloadMessage } from '../messaging/payload-codec';
-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 {
   ownerFence,
   type ZLinkActorMessageFollowOwnerFence
 } from '../actors/actor-message-follow-context';
-import type {
-  ServiceSessionRelocationRoute,
-  ServiceSessionRelocationSeal,
-  ServiceSessionRelocationSealed,
-  ServiceWireOperationId
-} from '../foundation/service-stateful-wire-codec';
-import { serviceSessionRelocationIdentityKey } from '../foundation/service-stateful-wire-codec';
+import type { ZLinkActorRuntimeState } from '../actors/actor-runtime-state';
+import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend';
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
+import { isRelocationDebugEnabled, relocationDebug } from '../diagnostics';
 import { operationIdentityKey } from '../foundation/operation-identity';
+import {
+  type ServiceSessionRelocationRoute,
+  type ServiceSessionRelocationSeal,
+  type ServiceSessionRelocationSealed,
+  type ServiceWireOperationId,
+  serviceSessionRelocationIdentityKey
+} from '../foundation/service-stateful-wire-codec';
+
+import type { ZLinkLocationLifecycle } from '../locations';
+import { encodeAuthorityKey } from '../locations/authority-key-codec';
+import type {
+  ZLinkAggregateId,
+  ZLinkAuthoritySnapshot,
+  ZLinkLocationOwnerToken
+} from '../locations/internal-location-contracts';
+import type {
+  ZLinkAuthorityStore,
+  ZLinkObjectCreationStore,
+  ZLinkOwnerLeaseStore
+} from '../locations/internal-store-contracts';
+import { wrapFrameworkPayloadMessage } from '../messaging/payload-codec';
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
+import type { DefaultZLinkSpotManager } from '../spots';
+import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import { BoundedReplayMap } from './bounded-replay-map';
+const TRANSFER_RESOLUTION_TIMEOUT_MS = 5_000;
+const TRANSFER_POLL_INTERVAL_MS = 10;
 
 const DEFERRED_JOIN_TERMINAL_CAPACITY = 4096;
 
@@ -168,7 +168,7 @@ export interface ZLinkActorTransferRuntimeActorManager {
     actorType: string,
     objectGeneration: bigint,
     authorityOwnerGeneration: bigint,
-    spotId: RoutingId,
+    spotId: RoutingId | undefined,
     spotGeneration: bigint,
     membershipEpoch: bigint,
     signal?: AbortSignal,
@@ -198,7 +198,6 @@ export interface ZLinkActorTransferRuntimeOptions {
   readonly authorityStore: () =>
     (ZLinkAuthorityStore & ZLinkObjectCreationStore & ZLinkOwnerLeaseStore) | undefined;
   readonly currentOwner: () => ZLinkLocationOwnerToken | undefined;
-  readonly relocationStore: () => ZLinkRelocationStore | undefined;
   /** Live admitted peers of a mesh; used to stop retries against a gone session owner. */
   readonly liveDescriptors?: (
     meshName: string,
@@ -216,7 +215,6 @@ export interface ZLinkActorTransferRuntimeOptions {
 }
 
 export class ZLinkActorTransferRuntime {
-  private readonly sourceDepartureTasks = new Map<string, Promise<void>>();
   private readonly coreSourceLeaves = new Map<
     string,
     {
@@ -229,43 +227,31 @@ export class ZLinkActorTransferRuntime {
       notifySubmitted?: () => Promise<void>;
     }
   >();
-  private readonly activeDeferredJoinTerminals = new Map<
-    string,
-    Promise<ZLinkDeferredJoinAcceptedRoot>
-  >();
-  private readonly deferredJoinTerminals = new BoundedReplayMap<
-    string,
-    ZLinkDeferredJoinAcceptedRoot
-  >(DEFERRED_JOIN_TERMINAL_CAPACITY);
+  //  Spot Actor membership sections 4-5: Join completion idempotency is
+  //  process-local. These maps end with the process; nothing is replayed.
+  private readonly activeDeferredJoinTerminals = new Map<string, Promise<void>>();
+  private readonly deferredJoinTerminals = new BoundedReplayMap<string, true>(
+    DEFERRED_JOIN_TERMINAL_CAPACITY
+  );
 
   constructor(private readonly options: ZLinkActorTransferRuntimeOptions) {}
 
-  beginDeferredActorHandoff(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    operationId: string
-  ): void {
+  beginDeferredActorHandoff(actor: ZLinkActor, state: ZLinkActorRuntimeState): void {
     const actorId = actor.context.actorId;
     this.options.actorHandoff.beginProvisional(
       actorId,
-      operationId,
       requireSourceObjectGeneration(actorId, state)
     );
   }
 
-  promoteDeferredActorHandoff(
-    actor: ZLinkActor,
-    _state: ZLinkActorRuntimeState,
-    operationId: string
-  ): void {
-    this.options.actorHandoff.promoteProvisional(actor.context.actorId, operationId);
+  promoteDeferredActorHandoff(actor: ZLinkActor, _state: ZLinkActorRuntimeState): void {
+    this.options.actorHandoff.promoteProvisional(actor.context.actorId);
   }
 
   async completeDeferredActorHandoff(
     actor: ZLinkActor,
     target: ZLinkSpotRouteTarget,
-    _targetActorRef: ActorRef,
-    operationId: string
+    _targetActorRef: ActorRef
   ): Promise<void> {
     const actorId = actor.context.actorId;
     if (!this.options.actorHandoff.isProvisional(actorId)) return;
@@ -275,7 +261,6 @@ export class ZLinkActorTransferRuntime {
     }
     const admitted = this.options.actorHandoff.admitDeferredPrefix(
       actorId,
-      operationId,
       (drain) => manager.admitRoutedActorPacketPrefix(target.spotId, actorId, drain),
       this.options.prepareApplicationJob
     );
@@ -284,110 +269,70 @@ export class ZLinkActorTransferRuntime {
 
   async cancelDeferredActorHandoff(
     actor: ZLinkActor,
-    _state: ZLinkActorRuntimeState,
-    operationId: string
+    state: ZLinkActorRuntimeState
   ): Promise<void> {
-    const admitted = this.admitDeferredSourcePrefix(actor, _state, operationId);
+    const admitted = this.admitDeferredSourcePrefix(actor, state);
     void this.observeHandoffReplay(admitted.terminal);
   }
 
-  async prepareDeferredJoinAccepted(
+  prepareDeferredJoinAccepted(
     actorId: string,
     operationId: ZLinkActorJoinOperationId,
     actorRef: ActorRef,
     rawReply: Uint8Array,
-    replyContentType?: string,
-    signal?: AbortSignal,
-    canonicalInventoryDigest?: string
-  ): Promise<ZLinkDeferredJoinAcceptedRoot> {
-    return await this.requireDeferredJoinJournal().prepare(
-      actorId,
-      operationId,
-      actorRef,
-      rawReply,
-      replyContentType,
-      signal,
-      canonicalInventoryDigest
-    );
-  }
-
-  async isDeferredJoinAcceptedRootPublication(
-    reference: string,
-    checksumCrc32c: number,
-    expected: ZLinkDeferredJoinRootIdentity,
-    signal?: AbortSignal
-  ): Promise<boolean> {
-    const relocation = this.options.relocationStore();
-    return relocation === undefined
-      ? false
-      : await isDeferredJoinAcceptedRootPublication(
-          relocation,
-          reference,
-          checksumCrc32c,
-          expected,
-          signal
-        );
-  }
-
-  async discardDeferredJoinAccepted(
-    root: ZLinkDeferredJoinAcceptedRoot,
-    signal?: AbortSignal
-  ): Promise<void> {
-    await this.requireDeferredJoinJournal().discardPrepared(root, signal);
+    replyContentType?: string
+  ): ZLinkDeferredJoinCompletion {
+    return createDeferredJoinCompletion(actorId, operationId, actorRef, rawReply, replyContentType);
   }
 
-  markDeferredJoinAcceptedCommitted(
-    root: ZLinkDeferredJoinAcceptedRoot,
-    actorRef: ActorRef,
-    signal?: AbortSignal
-  ): Promise<ZLinkDeferredJoinAcceptedRoot> {
-    return this.requireDeferredJoinJournal().markCommitted(root, actorRef, signal);
-  }
-
-  async commitAndDeliverDeferredJoinAccepted(
-    root: ZLinkDeferredJoinAcceptedRoot,
+  /**
+   * 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: ZLinkDeferredJoinCompletion,
     actor: ZLinkActor,
     actorRef: ActorRef,
     submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>,
     signal?: AbortSignal
-  ): Promise<ZLinkDeferredJoinAcceptedRoot> {
-    const terminalKey = deferredJoinTerminalKey(root);
-    const terminal = this.deferredJoinTerminals.get(terminalKey);
-    if (terminal !== undefined) {
+  ): Promise<void> {
+    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,
+    const delivery = this.deliverDeferredJoinCompletionCore(
+      completion,
       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.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);
   }
 
-  private async commitAndDeliverDeferredJoinAcceptedCore(
-    root: ZLinkDeferredJoinAcceptedRoot,
+  private async deliverDeferredJoinCompletionCore(
+    completion: ZLinkDeferredJoinCompletion,
     actor: ZLinkActor,
     actorRef: ActorRef,
     submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>
-  ): Promise<ZLinkDeferredJoinAcceptedRoot> {
+  ): Promise<void> {
     const targetActorRef = this.options
       .actorManager()
       ?.getState(actor.context.actorId)?.nativeActorRef;
@@ -395,47 +340,43 @@ export class ZLinkActorTransferRuntime {
       targetActorRef === undefined
         ? actorRef
         : 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: unknown;
-    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<void>((resolve) => {
-            const timer = setTimeout(resolve, 10 << attempt);
-            timer.unref();
-          });
-          current =
-            (await this.requireDeferredJoinJournal().recover(currentActorRef.actorId)) ?? current;
-        }
-      }
-    }
-    throw lastError;
-  }
-
-  private requireDeferredJoinJournal(): ZLinkDeferredJoinAcceptedJournal {
-    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.');
+    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}).`
+      );
     }
-    return new ZLinkDeferredJoinAcceptedJournal(
-      authority,
-      relocation,
-      this.options.messageSerializers
-    );
+    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,
+        actor: currentActorRef,
+        reply:
+          completion.rawReply.byteLength === 0
+            ? undefined
+            : completion.replyContentType === undefined
+              ? ZLinkMessage.fromEncoded(ZLinkEncodedPayload.from(completion.rawReply))
+              : wrapFrameworkPayloadMessage(
+                  RuntimeMessage.from(completion.rawReply),
+                  this.options.messageSerializers,
+                  completion.replyContentType,
+                  undefined,
+                  'reply'
+                )
+      });
+    });
   }
 
   private async prepareSourceActorLeave(
@@ -471,13 +412,10 @@ export class ZLinkActorTransferRuntime {
   private async beginSourceActorMove(
     actor: ZLinkActor,
     state: ZLinkActorRuntimeState,
-    deferredOperationId?: string
+    deferredJoin = false
   ): Promise<void> {
-    if (
-      deferredOperationId !== undefined &&
-      this.options.actorHandoff.isProvisional(actor.context.actorId)
-    ) {
-      this.promoteDeferredActorHandoff(actor, state, deferredOperationId);
+    if (deferredJoin && this.options.actorHandoff.isProvisional(actor.context.actorId)) {
+      this.promoteDeferredActorHandoff(actor, state);
     }
     state.beginMove();
     if (!this.options.actorHandoff.isActive(actor.context.actorId)) {
@@ -488,21 +426,25 @@ export class ZLinkActorTransferRuntime {
     }
     try {
       if (state.spotId !== undefined) {
-        relocationDebug('source_actor_move.await_spot_transfer', {
-          actorId: actor.context.actorId,
-          spotId: String(state.spotId)
-        });
+        if (isRelocationDebugEnabled()) {
+          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 (isRelocationDebugEnabled()) {
+          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();
@@ -513,7 +455,7 @@ export class ZLinkActorTransferRuntime {
   private async cancelSourceActorMove(
     actor: ZLinkActor,
     state: ZLinkActorRuntimeState,
-    deferredOperationId?: string,
+    deferredJoin = false,
     replayStart: Promise<void> = Promise.resolve()
   ): Promise<void> {
     try {
@@ -522,16 +464,11 @@ export 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);
         }
       } finally {
@@ -564,7 +501,6 @@ export class ZLinkActorTransferRuntime {
   private admitDeferredSourcePrefix(
     actor: ZLinkActor,
     state: ZLinkActorRuntimeState,
-    operationId: string,
     replayStart: Promise<void> = Promise.resolve()
   ): ZLinkActorHandoffPrefixAdmission {
     const queue = this.sourceHandoffPrefixQueue(actor, state);
@@ -574,7 +510,6 @@ export class ZLinkActorTransferRuntime {
     }
     return this.options.actorHandoff.admitDeferredPrefix(
       actor.context.actorId,
-      operationId,
       queue,
       this.options.prepareApplicationJob,
       replayStart
@@ -614,10 +549,10 @@ export class ZLinkActorTransferRuntime {
     state: ZLinkActorRuntimeState,
     signal?: AbortSignal,
     lifecycleAuthority: 'framework' | 'core' = 'framework',
-    deferredOperationId?: string,
+    deferredJoin = false,
     relocation?: ServiceWireOperationId
   ) {
-    await this.beginSourceActorMove(actor, state, deferredOperationId);
+    await this.beginSourceActorMove(actor, state, deferredJoin);
     const relocationMetric =
       state.meshName === undefined
         ? undefined
@@ -628,12 +563,12 @@ export class ZLinkActorTransferRuntime {
           );
     const sourceSpotId = state.spotId;
     let sourceLeaveStarted = false;
-    let sealId: string | undefined;
+    // The relocation operation owns its Session seal; the Actor keeps only
+    // its current binding (Session–Actor binding §8.1).
+    let sealedSession: ZLinkRemoteBoundSessionTarget | undefined;
     try {
-      if (state.remoteBoundSessionTarget !== undefined) {
-        sealId = 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(
@@ -746,8 +681,7 @@ export class ZLinkActorTransferRuntime {
               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 {
@@ -762,10 +696,10 @@ export 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 {
             replayGate.open();
@@ -776,10 +710,10 @@ export 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) {
         throw new AggregateError(
@@ -810,11 +744,14 @@ export class ZLinkActorTransferRuntime {
       targetOwnerFence: ZLinkActorMessageFollowOwnerFence
     ): Promise<void>;
     rollback(): Promise<void>;
+    discard(reason: unknown): void;
   }> {
-    relocationDebug('maintenance_session.begin', {
-      actorId: actor.context.actorId,
-      spotId: state.spotId === undefined ? undefined : String(state.spotId)
-    });
+    if (isRelocationDebugEnabled()) {
+      relocationDebug('maintenance_session.begin', {
+        actorId: actor.context.actorId,
+        spotId: state.spotId === undefined ? undefined : String(state.spotId)
+      });
+    }
     if (manageMembership) {
       await this.beginSourceActorMove(actor, state);
     } else {
@@ -824,23 +761,22 @@ export class ZLinkActorTransferRuntime {
         requireSourceObjectGeneration(actor.context.actorId, state)
       );
     }
-    relocationDebug('maintenance_session.source_move_complete', {
-      actorId: actor.context.actorId
-    });
-    let sealId: string | undefined;
+    if (isRelocationDebugEnabled()) {
+      relocationDebug('maintenance_session.source_move_complete', {
+        actorId: actor.context.actorId
+      });
+    }
+    let sealedSession: ZLinkRemoteBoundSessionTarget | undefined;
     try {
-      if (state.remoteBoundSessionTarget !== undefined) {
-        sealId = 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' | 'committed' | 'rolledBack' = 'prepared';
       let replayResults: readonly import('../actors').ZLinkActorHandoffResult[] = [];
       return {
-        target: state.remoteBoundSessionTarget,
+        target: sealedSession,
         handoffBacklog,
         takeRelocationRelay: () =>
           this.options.actorHandoff.takeRelocationRelay(actor.context.actorId),
@@ -848,8 +784,10 @@ export class ZLinkActorTransferRuntime {
           if (terminal === 'prepared') replayResults = [...results];
         },
         commit: async (target, targetActorRef, targetOwnerFence) => {
-          if (terminal === 'rolledBack') return;
-          if (terminal === 'prepared') {
+          if (terminal !== 'prepared') return;
+          terminal = 'committed';
+          const failures: unknown[] = [];
+          try {
             this.options.actorHandoff.complete(
               actor.context.actorId,
               target,
@@ -857,15 +795,34 @@ export class ZLinkActorTransferRuntime {
               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;
           terminal = 'rolledBack';
@@ -881,8 +838,8 @@ export class ZLinkActorTransferRuntime {
                 state.endMove();
               }
             }
-            if (sealId !== undefined) {
-              await this.observeBoundSessionSealAbort(actor, state);
+            if (sealedSession !== undefined) {
+              await this.observeBoundSessionSealAbort(actor, state, sealedSession);
             }
           } finally {
             replayGate.open();
@@ -910,8 +867,8 @@ export class ZLinkActorTransferRuntime {
             state.endMove();
           }
         }
-        if (sourceRestored && sealId !== undefined) {
-          await this.observeBoundSessionSealAbort(actor, state);
+        if (sourceRestored && sealedSession !== undefined) {
+          await this.observeBoundSessionSealAbort(actor, state, sealedSession);
         }
       } finally {
         replayGate.open();
@@ -1000,7 +957,7 @@ export class ZLinkActorTransferRuntime {
     signal?: AbortSignal,
     relocation?: ServiceWireOperationId
   ): Promise<ZLinkRemoteBoundSessionTarget> {
-    const target = state.remoteBoundSessionTarget;
+    const target = state.boundSession;
     const actorRef = state.nativeActorRef;
     if (
       target === undefined ||
@@ -1101,17 +1058,10 @@ export class ZLinkActorTransferRuntime {
   private async abortBoundSessionRouteSeal(
     actor: ZLinkActor,
     state: ZLinkActorRuntimeState,
-    targetOverride?: ZLinkRemoteBoundSessionTarget
+    target: ZLinkRemoteBoundSessionTarget
   ): Promise<void> {
-    const target =
-      targetOverride ??
-      preferredRemoteBoundSessionTarget(
-        state.remoteBoundSessionTarget,
-        state.boundSessionTransferTarget
-      );
     const actorRef = state.nativeActorRef;
     if (
-      target === undefined ||
       actorRef === undefined ||
       target.bindingGeneration === undefined ||
       target.previousAuthorityOwnerGeneration === undefined ||
@@ -1158,10 +1108,11 @@ export class ZLinkActorTransferRuntime {
 
   private async observeBoundSessionSealAbort(
     actor: ZLinkActor,
-    state: ZLinkActorRuntimeState
+    state: ZLinkActorRuntimeState,
+    sealedSession: ZLinkRemoteBoundSessionTarget
   ): Promise<void> {
     try {
-      await this.abortBoundSessionRouteSeal(actor, state);
+      await this.abortBoundSessionRouteSeal(actor, state, sealedSession);
     } catch (error) {
       try {
         this.options.reportPostCommitError?.(error);
@@ -1203,49 +1154,58 @@ export class ZLinkActorTransferRuntime {
   private scheduleSourceDeparture(
     actor: ZLinkActor,
     sourceSpotId: RoutingId | undefined,
-    releaseLocation: boolean
+    releaseLocation: boolean,
+    failures: unknown[] = []
   ): void {
-    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);
+    void this.finishSourceDeparture(actor, sourceSpotId, releaseLocation, failures);
   }
 
   private async finishSourceDeparture(
     actor: ZLinkActor,
     sourceSpotId: RoutingId | undefined,
-    releaseLocation: boolean
+    releaseLocation: boolean,
+    failures: unknown[]
   ): Promise<void> {
-    const retry = new ZLinkActorRetryDelay();
-    while (this.options.shutdownSignal?.()?.aborted !== true) {
+    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(
@@ -1277,7 +1237,9 @@ export class ZLinkActorTransferRuntime {
     }
     if (actorRef !== undefined) {
       state.setNativeActorRef(actorRef as unknown as ZLinkBackendActorRef);
-      state.setRemoteBoundSessionTarget(remoteBoundSessionTarget);
+      if (remoteBoundSessionTarget !== undefined) {
+        state.installBoundSessionBinding(remoteBoundSessionTarget);
+      }
       return { actor, actorRef: actorRef as unknown as ZLinkBackendActorRef };
     }
     return { actor, actorRef: state.ensureNativeActorRef(this.options.primaryMeshNode()) };
@@ -1307,14 +1269,10 @@ export class ZLinkActorTransferRuntime {
       throw new Error(`Actor '${actorId}' transfer state was not created.`);
     }
     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(
-        mergeRemoteBoundSessionTarget(remoteBoundSessionTarget, state.remoteBoundSessionTarget)
-      );
-    }
-    if (remoteBoundSessionTarget?.bindingGeneration !== undefined) {
-      state.setBoundSessionBindingGeneration(remoteBoundSessionTarget.bindingGeneration);
+      state.installBoundSessionBinding(remoteBoundSessionTarget);
     }
     return {
       actor: materialized.actor,
@@ -1492,29 +1450,11 @@ export class ZLinkActorTransferRuntime {
     }
   }
 
-  rememberRoutedActorTransferTarget(
-    actorId: string,
-    target: ZLinkRemoteBoundSessionTarget | undefined
-  ): void {
-    if (target === undefined) return;
-    const state = this.options.actorManager()?.getState(actorId);
-    if (state === undefined) {
-      return;
-    }
-    state.setBoundSessionTransferTarget(target);
-    state.setRemoteBoundSessionTarget(
-      mergeRemoteBoundSessionTarget(target, state.remoteBoundSessionTarget)
-    );
-    if (target.bindingGeneration !== undefined) {
-      state.setBoundSessionBindingGeneration(target.bindingGeneration);
-    }
-  }
-
   commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void {
     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 &&
@@ -1582,7 +1522,7 @@ export class ZLinkActorTransferRuntime {
         `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(
@@ -1620,7 +1560,7 @@ export class ZLinkActorTransferRuntime {
       if (claim.status !== 'conflict' || performance.now() >= deadline) {
         break;
       }
-      await new Promise<void>((resolve) => setTimeout(resolve, 10));
+      await new Promise<void>((resolve) => setTimeout(resolve, TRANSFER_POLL_INTERVAL_MS));
     }
     if (claim.status === 'conflict') {
       throw new Error(`Actor '${actor.context.actorId}' target location takeover was rejected.`);
@@ -1654,44 +1594,24 @@ export class ZLinkActorTransferRuntime {
     state.setRemoteActorPacketTarget(target);
   }
 
-  async claimNativeActorLocation(
+  /**
+   * 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: ZLinkActor,
-    spotId: RoutingId,
-    spotMeshName: string
-  ): Promise<ZLinkNativeActorJoinSnapshot> {
-    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: ZLinkActor): Promise<void> {
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
+  ): Promise<void> {
     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 = preferredRemoteBoundSessionTarget(
-      state.remoteBoundSessionTarget,
-      state.boundSessionTransferTarget
-    );
-    if (boundSessionTarget?.serviceWireRelocation === undefined) return;
+    if (sealedSession?.serviceWireRelocation === undefined) return;
     await this.publishBoundSessionOwnership(
       actor.context.actorId,
       actorRef,
       generation,
-      boundSessionTarget,
+      sealedSession,
       state.ownerLeaseGeneration
     );
   }
@@ -1703,73 +1623,6 @@ export class ZLinkActorTransferRuntime {
     this.options.clearRemoteActorPacketTarget(actor.context.actorId);
   }
 
-  async rollbackNativeActorJoin(
-    actor: ZLinkActor,
-    snapshot: ZLinkNativeActorJoinSnapshot
-  ): Promise<void> {
-    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: ZLinkActor, signal?: AbortSignal): Promise<void> {
     const manager = this.options.actorManager();
     const state = manager?.getState(actor.context.actorId);
@@ -1782,7 +1635,6 @@ export class ZLinkActorTransferRuntime {
         state.markLocationReleased();
       } catch (error) {
         locationError = error;
-        void lifecycle.releaseActorEventually(actorType, actor.context.actorId);
       }
     }
     try {
@@ -1870,7 +1722,8 @@ export 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?.()
@@ -1880,15 +1733,10 @@ export class ZLinkActorTransferRuntime {
   }
 }
 
-function relocationDebug(marker: string, detail: Record<string, unknown>): void {
-  if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION !== '1') return;
-  console.error('[zlink.runtime.relocation]', marker, detail);
-}
-
-function deferredJoinTerminalKey(root: ZLinkDeferredJoinAcceptedRoot): string {
+function deferredJoinTerminalKey(completion: ZLinkDeferredJoinCompletion): string {
   return (
-    `${root.actor.actorId}:${root.actor.objectGeneration.toString()}:` +
-    operationIdentityKey(root.operationId)
+    `${completion.actor.actorId}:${completion.actor.objectGeneration.toString()}:` +
+    operationIdentityKey(completion.operationId)
   );
 }
 
@@ -1942,7 +1790,7 @@ async function waitForActorAuthorityRetry(
     throw new Error('Actor target authority deadline expired.', { cause });
   }
   await new Promise<void>((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);