@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/spots/index.ts

@@ -1,3 +1,7 @@
+import { encodeActorReply } from '../actors/actor-reply';
+import { boundSessionErrorPayload } from '../streams/bound-session-response-target';
+import { RELOCATED_REQUEST_OWNED_BY_REQUESTER } from '../actors/actor-handoff';
+import { routingIdsEqual } from '../routing-id';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { dispatchReasonFromError } from '../diagnostics/dispatch-error-details';
 import type {
@@ -29,7 +33,7 @@ export { ZLinkSpotActorAdmissionCoordinator } from './spot-actor-admission-coord
 import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from './spot-routing-internal';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
-import { awaitWithAbort, isAbortError, throwIfAborted } from '../abort';
+import { awaitWithAbort, throwIfAborted } from '../abort';
 import {
   ZLinkMessage,
   ZLinkFrameworkException,
@@ -81,7 +85,6 @@ import {
 } from '../actors';
 import type { ZLinkLocationLifecycle } from '../locations';
 import {
-  encodeFrameworkPayload,
   encodeFrameworkPayloadMessage,
   frameworkPayloadContentType,
   wrapFrameworkPayloadMessage
@@ -92,13 +95,7 @@ import {
   encodeChannelErrorReplyParts,
   encodeChannelReplyParts
 } from '../channels/channel-envelope';
-import {
-  decodeStreamHeader,
-  encodeStreamHeader,
-  streamCodecForContentType,
-  ZLinkStreamHeaderFlags,
-  ZLinkStreamMessageKind
-} from '../streams/protocol';
+import { ZLinkStreamMessageKind } from '../streams/protocol';
 import {
   REMOTE_ACTOR_JOIN_PACKET,
   REMOTE_ACTOR_JOIN_ABORT,
@@ -135,6 +132,7 @@ export {
 export { ZLinkRuntimeSpotPublisherTransport } from './spot-publisher-transport';
 import { ZLinkSpotActivationRegistry } from './spot-activation-registry';
 import type { ZLinkSpotActivation } from './spot-activation-state';
+import type { ZLinkSpotPreparationCompletion } from './spot-serial-executor';
 import { ZLinkSpotActivationLifecycle, type ZLinkNativeSpotAuthority } from './spot-activation';
 import { ZLinkSpotActorMembership } from './spot-actor-membership';
 import { ZLinkFormalRemoteActorTransferRegistry } from './formal-remote-actor-transfer-registry';
@@ -148,7 +146,7 @@ import type {
   ZLinkSpotActorTransferRuntime,
   ZLinkSpotBoundSessionRuntime
 } from './spot-runtime-ports';
-import type { ZLinkRuntimeAdmissionGate } from '../admission';
+import type { ZLinkRuntimeAdmissionGate, ZLinkMeshDispatchAdmission } from '../admission';
 import type { ZLinkActivationAdmission } from '../activation-admission';
 import type { ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
 import type { ZLinkLocalSpotCreateResult } from './spot-manager-internal-contracts';
@@ -159,6 +157,7 @@ import { ZLinkRoutedSpotPacketDispatch } from './spot-routed-spot-packet-dispatc
 export { ZLinkEntrySpotActivation } from './spot-entry-activation';
 export {
   createFrameworkEntrySpotId,
+  registrationAcceptsNewActor,
   ZLinkSpotNodeRuntimeManager,
   type ZLinkSpotNodeRuntimeManagerOptions
 } from './spot-node-runtime-manager';
@@ -209,12 +208,18 @@ export interface ZLinkSpotManagerOptions {
     actor: ZLinkActor,
     handoffBacklog?: readonly ZLinkActorHandoffPacket[]
   ) => Promise<void>;
+  readonly admitEntryActorPacketPrefix?: (
+    meshName: string,
+    actorId: string,
+    records: readonly ZLinkActorHandoffPrefixRecord[]
+  ) => ZLinkActorHandoffPrefixAdmission;
   readonly executeEntryActor?: <T>(
     meshName: string,
     actorId: string,
     operation: () => Promise<T>
   ) => Promise<T>;
   readonly actorCountProvider?: (spotId: RoutingId) => number;
+  readonly releaseActorMembers?: (meshName: string, spotId: RoutingId) => Promise<void>;
   readonly userSpotExecutionMode?: (
     meshName: string,
     spotType: Type<ZLinkSpot>
@@ -408,6 +413,7 @@ export class DefaultZLinkSpotManager {
       nodeRid: options.nodeRid,
       nodeRidProvider: options.nodeRidProvider,
       actorCountProvider: options.actorCountProvider,
+      releaseActorMembers: options.releaseActorMembers,
       userSpotExecutionMode: options.userSpotExecutionMode,
       userSpotRelocationCoordinationMode: options.userSpotRelocationCoordinationMode,
       channelClient: options.channelClient,
@@ -437,9 +443,16 @@ export class DefaultZLinkSpotManager {
         this.actorMembership.leaveActor(spotId, actor, signal, meshName),
       requestContextClose: (activation, objectGeneration, signal) =>
         this.closeFromContext(activation, objectGeneration, signal),
-      registerActivation: (activation) => {
-        this.activations.register(activation);
+      stageActivation: (activation) => {
+        this.activations.registerPreparing(activation);
+      },
+      discardActivation: (activation) => {
+        this.activations.finishClose(activation.meshName, activation.spotId);
+      },
+      registerActivation: async (activation) => {
+        const published = this.activations.register(activation);
         this.scheduleIdleSweep();
+        if (published?.domain.kind === 'user') await published.serialExecutor.finishPreparation();
       },
       //  Spec 15 §4.2 relocation temporary queue: production ingress
       //  consults the same admission attempts registered on Accepted
@@ -511,6 +524,7 @@ export class DefaultZLinkSpotManager {
     spotId: RoutingId,
     objectGeneration: bigint,
     authorityOwnerGeneration: bigint,
+    restoredTimers: readonly import('./spot-timer').ZLinkTimerRelocationState[],
     signal?: AbortSignal
   ): Promise<ZLinkSpotActivation> {
     this.activations.stage(meshName, spotId);
@@ -523,6 +537,7 @@ export class DefaultZLinkSpotManager {
         spotId,
         objectGeneration,
         authorityOwnerGeneration,
+        restoredTimers,
         signal
       );
     } catch (error) {
@@ -535,12 +550,19 @@ export class DefaultZLinkSpotManager {
     activation: ZLinkSpotActivation,
     beforeAdmission?: () => Promise<void>
   ): Promise<void> {
-    await activation.serial.execute(() => activation.spot.onInitialize?.());
+    // Spot timer §1: OnInitialize before Ready reattaches restored keys; the
+    // relocation-ready completion and later callbacks use the ordinary rule.
+    await activation.serial.postBarrierTurn(() =>
+      activation.timers.runRelocationInitialization(() => activation.spot.onInitialize?.())
+    );
     await beforeAdmission?.();
     this.activations.publish(activation.meshName, activation.spotId);
+    await activation.serialExecutor.finishPreparation();
+    await activation.timers.publishRelocation();
   }
 
   async abortRelocationSpot(activation: ZLinkSpotActivation): Promise<void> {
+    await this.activationLifecycle.discardPreparation(activation);
     this.activations.detachRelocated(activation.meshName, activation.spotId);
     await activation.timers.dispose();
     await activation.nativeSpot?.dispose();
@@ -556,7 +578,8 @@ export class DefaultZLinkSpotManager {
     instanceType: string,
     spotId: RoutingId,
     objectGeneration: bigint,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    completion: ZLinkSpotPreparationCompletion = 'publication'
   ): Promise<void> {
     const readyTarget = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
     const existing = this.pendingInstanceMaterializations.get(
@@ -574,7 +597,8 @@ export class DefaultZLinkSpotManager {
         spotId,
         objectGeneration,
         readyTarget?.objectGeneration === objectGeneration,
-        signal
+        signal,
+        completion
       );
     } finally {
       release?.();
@@ -587,7 +611,8 @@ export class DefaultZLinkSpotManager {
     spotId: RoutingId,
     objectGeneration: bigint,
     requiresReadyTarget: boolean,
-    signal?: AbortSignal
+    signal: AbortSignal | undefined,
+    completion: ZLinkSpotPreparationCompletion
   ): Promise<void> {
     const factory = this.requireInstanceFactory(meshName, instanceType);
     const key = `${meshName}\0${String(spotId)}`;
@@ -620,7 +645,7 @@ export class DefaultZLinkSpotManager {
         continue;
       }
 
-      const current = this.activations.resolve(meshName, spotId);
+      const current = this.activations.activationForClose(meshName, spotId);
       if (current !== undefined) {
         if (current.spotType !== factory) {
           throw new ZLinkConfigurationException(
@@ -666,16 +691,16 @@ export class DefaultZLinkSpotManager {
         }
       }
       if (pending === undefined) {
-        const metric = this.options.metrics?.startInstanceSpotActivation(meshName, instanceType);
+        if (completion === 'first-terminal') this.activations.stage(meshName, spotId);
         pending = this.activationLifecycle
           .materializeInstance(meshName, instanceType, factory, spotId, objectGeneration, signal)
           .then(
-            (activation) => {
-              metric?.complete('ready');
+            async (activation) => {
+              if (completion === 'publication') await activation.serialExecutor.finishPreparation();
               return activation;
             },
             (error) => {
-              metric?.complete(instanceActivationOutcome(error));
+              this.activations.abandonStage(meshName, spotId);
               throw error;
             }
           );
@@ -723,10 +748,16 @@ export class DefaultZLinkSpotManager {
         ? this.activations.resolveUnique(spotId)
         : this.activations.resolve(meshName, spotId);
     if (current !== undefined) return current;
-    if (meshName !== undefined)
-      return this.closeOperations.get(`${meshName}\0${String(spotId)}`)?.activation;
+    if (meshName !== undefined) {
+      const closing = this.closeOperations.get(`${meshName}\0${String(spotId)}`);
+      return closing?.authority === undefined ? undefined : closing.activation;
+    }
     for (const operation of this.closeOperations.values()) {
-      if (String(operation.activation.spotId) === String(spotId)) return operation.activation;
+      if (
+        operation.authority !== undefined &&
+        String(operation.activation.spotId) === String(spotId)
+      )
+        return operation.activation;
     }
     return undefined;
   }
@@ -735,6 +766,7 @@ export class DefaultZLinkSpotManager {
     const prefix = instanceMaterializationPrefix(meshName, spotId);
     return (
       (this.pendingInstanceMaterializationsByPrefix.get(prefix)?.size ?? 0) > 0 ||
+      this.activations.activationForClose(meshName, spotId)?.serialExecutor.isPreparing === true ||
       this.closeOperations.get(`${meshName}\0${String(spotId)}`)?.authority !== undefined
     );
   }
@@ -751,7 +783,7 @@ export class DefaultZLinkSpotManager {
   }
 
   async discardInstance(meshName: string, spotId: RoutingId): Promise<void> {
-    const activation = this.activations.resolve(meshName, spotId);
+    const activation = this.activations.activationForClose(meshName, spotId);
     if (activation === undefined) return;
     activation.requestClose();
     const operation = this.activations.startClose(
@@ -801,6 +833,9 @@ export class DefaultZLinkSpotManager {
     objectGeneration: bigint
   ): Promise<boolean> {
     const key = `${meshName}\0${String(spotId)}`;
+    const activation = this.activations.activationForClose(meshName, spotId);
+    if (activation?.objectGeneration === objectGeneration)
+      await activation.serialExecutor.finishPreparation();
     const pending = this.pendingInstanceTerminals.get(key);
     if (pending === undefined) return false;
     this.removePendingInstanceTerminalGeneration(key, objectGeneration);
@@ -847,6 +882,17 @@ export class DefaultZLinkSpotManager {
     this.pendingInstanceTerminalGenerations.set(key, generations);
   }
 
+  publishInstance(
+    target: { readonly targetSpotId: string; readonly objectGeneration: bigint },
+    meshName: string
+  ): void {
+    const activation = this.activations.activationForClose(meshName, target.targetSpotId);
+    if (activation?.objectGeneration === target.objectGeneration) {
+      const published = this.activations.publish(meshName, target.targetSpotId);
+      published?.serialExecutor.openPreparationAdmission();
+    }
+  }
+
   private deferInstanceAuthorityRelease(key: string, objectGeneration: bigint): void {
     const generations = this.deferredInstanceAuthorityReleases.get(key) ?? new Set<bigint>();
     generations.add(objectGeneration);
@@ -1077,19 +1123,24 @@ export class DefaultZLinkSpotManager {
   }
 
   async drainForShutdown(meshName: string, signal?: AbortSignal, deadline?: Date): Promise<void> {
-    const results = await Promise.allSettled(
-      this.activations
-        .activeActivations()
-        .filter((activation) => activation.meshName === meshName)
-        .map((activation) =>
-          this.closeWithReason(
-            meshName,
-            activation.spotId,
-            signal,
-            ZLinkSpotCloseReason.HostShutdown,
-            deadline
+    // The host bounds observation of the whole Close, including lifecycle admission.
+    // The owned operation keeps the gate and scopes until its running turns settle.
+    const results = await awaitWithAbort(
+      Promise.allSettled(
+        this.activations
+          .activeActivations()
+          .filter((activation) => activation.meshName === meshName)
+          .map((activation) =>
+            this.closeWithReason(
+              meshName,
+              activation.spotId,
+              undefined,
+              ZLinkSpotCloseReason.HostShutdown,
+              deadline
+            )
           )
-        )
+      ),
+      signal
     );
     const errors = results
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
@@ -1127,7 +1178,10 @@ export class DefaultZLinkSpotManager {
   ): Promise<boolean> {
     const { meshName, spotId } = activation;
     const operation = this.closeOperations.get(`${meshName}\0${String(spotId)}`);
-    const current = operation?.activation ?? this.activations.resolve(meshName, spotId);
+    const current =
+      operation?.activation ??
+      this.activations.resolve(meshName, spotId) ??
+      (activation.serialExecutor.isPreparing ? activation : undefined);
     if (current === undefined) {
       return Promise.resolve(false);
     }
@@ -1150,7 +1204,8 @@ export class DefaultZLinkSpotManager {
       signal,
       ZLinkSpotCloseReason.ExplicitClose,
       undefined,
-      beginUserAuthority
+      beginUserAuthority,
+      activation
     );
   }
 
@@ -1164,13 +1219,14 @@ export class DefaultZLinkSpotManager {
       onCommitted: () => void
     ) => Promise<
       import('../locations/spot-location-claims').ZLinkInstanceClosingAuthority | undefined
-    >
+    >,
+    contextActivation?: ZLinkSpotActivation
   ): Promise<boolean> {
     requireMeshName(meshName);
     const key = `${meshName}\0${String(spotId)}`;
     let operation = this.closeOperations.get(key);
     if (operation === undefined) {
-      const activation = this.activations.resolve(meshName, spotId);
+      const activation = this.activations.resolve(meshName, spotId) ?? contextActivation;
       if (activation === undefined) return false;
       if (
         activation.domain.kind === 'user' &&
@@ -1243,10 +1299,11 @@ export class DefaultZLinkSpotManager {
     signal?: AbortSignal,
     deadline?: Date
   ): Promise<boolean> {
+    if (this.activations.resolve(meshName, spotId) !== operation.activation) return false;
     const seal = await this.beginCloseAuthority(meshName, spotId, operation, signal);
     if (seal === undefined) return false;
     if (seal !== true) {
-      await this.activationLifecycle.sealForClose(operation.activation, seal);
+      await this.activationLifecycle.sealForClose(operation.activation, seal, signal);
     } else {
       await operation.activation.executionBarrier.waitForStartedTurns(signal);
     }
@@ -1418,12 +1475,19 @@ export class DefaultZLinkSpotManager {
     this.activations.stage(meshName, spotId);
   }
 
-  publishUserSpot(meshName: string, spotId: RoutingId): void {
-    this.activations.publish(meshName, spotId);
+  async publishUserSpot(meshName: string, spotId: RoutingId): Promise<void> {
+    const published = this.activations.publish(meshName, spotId);
+    await published?.serialExecutor.finishPreparation();
   }
 
-  abortUserSpotPublication(meshName: string, spotId: RoutingId): void {
+  async abortUserSpotPublication(meshName: string, spotId: RoutingId): Promise<void> {
     this.activations.abandonStage(meshName, spotId);
+    const activation = this.activations.activationForClose(meshName, spotId);
+    if (activation?.serialExecutor.isPreparing === true) {
+      await this.activationLifecycle.cleanupFailedIncarnation(activation);
+      this.activations.finishClose(meshName, spotId);
+      await activation.serialExecutor.close();
+    }
   }
 
   resolveLocalSpotRoute(spotId: RoutingId): ZLinkSpotRouteTarget | undefined {
@@ -1509,14 +1573,6 @@ export class DefaultZLinkSpotManager {
     await this.actorMembership.commitActorLeaveAfterTransfer(spotId, actorId);
   }
 
-  async restoreActorAfterFailedTransfer(
-    spotId: RoutingId,
-    actor: ZLinkActor,
-    signal?: AbortSignal
-  ): Promise<void> {
-    await this.actorMembership.restoreActorAfterFailedTransfer(spotId, actor, signal);
-  }
-
   async beginActorTransfer(spotId: RoutingId, actorId: string): Promise<void> {
     await this.actorMembership.beginActorTransfer(spotId, actorId);
   }
@@ -1595,6 +1651,24 @@ export class DefaultZLinkSpotManager {
     return this.activationLifecycle.admitActorPacketPrefix(activation, actorId, records);
   }
 
+  /** Resolves the current Actor FIFO owner for both Entry and User membership. */
+  admitSourceActorPacketPrefix(
+    actorId: string,
+    records: readonly ZLinkActorHandoffPrefixRecord[]
+  ): ZLinkActorHandoffPrefixAdmission {
+    const owner = this.options.actorDispatchOwnerResolver?.(actorId);
+    if (owner?.actorRef === undefined) {
+      throw new ZLinkConfigurationException(`Actor '${actorId}' has no local FIFO owner.`);
+    }
+    if (owner.spotId === undefined) {
+      if (this.options.admitEntryActorPacketPrefix === undefined) {
+        throw new ZLinkConfigurationException(`Actor '${actorId}' has no Entry FIFO port.`);
+      }
+      return this.options.admitEntryActorPacketPrefix(owner.actorRef.meshName, actorId, records);
+    }
+    return this.admitRoutedActorPacketPrefix(owner.spotId, actorId, records);
+  }
+
   async dispatchRoutedSpotSend(
     spotId: RoutingId,
     packetName: string | undefined,
@@ -1620,6 +1694,7 @@ export class DefaultZLinkSpotManager {
       readonly workOptions?: import('../execution/serial-execution-queue').ZLinkSerialWorkOptions;
       readonly admissionTimeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply> {
     return await this.routedSpotPackets.request<TReply>(spotId, packetName, request, context);
@@ -1628,14 +1703,15 @@ export class DefaultZLinkSpotManager {
   async dispatchMeshSpot(
     meshName: string,
     owner: ReadyRecord,
-    record: ReceiveRecord
+    record: ReceiveRecord,
+    admit?: ZLinkMeshDispatchAdmission
   ): Promise<void> {
     const spotId = owner.spotId as unknown as RoutingId | null;
     if (spotId === null) {
       throw new ZLinkConfigurationException('MeshNode Spot record is missing the owner Spot RID.');
     }
     if (record.kind === ReceiveKind.SpotMulticast) {
-      const activation = this.activations.resolve(meshName, spotId);
+      const activation = this.activations.activationForClose(meshName, spotId);
       if (activation?.actorDispatch === undefined) {
         throw new ZLinkConfigurationException(
           `MeshNode Spot multicast target '${String(spotId)}' is not active.`
@@ -1646,11 +1722,13 @@ export class DefaultZLinkSpotManager {
           'MeshNode Spot multicast record is missing its topic.'
         );
       }
-      await activation.actorDispatch.dispatchSubscriptionRecord(
-        record.topic,
-        record.parts,
-        record.sourceNodeRid as unknown as RoutingId | null
-      );
+      const dispatch = () =>
+        activation.actorDispatch!.dispatchSubscriptionRecord(
+          record.topic!,
+          record.parts,
+          record.sourceNodeRid as unknown as RoutingId | null
+        );
+      await (admit === undefined ? dispatch() : admit(dispatch));
       return;
     }
     const envelope = decodeChannelEnvelope(
@@ -1672,28 +1750,32 @@ export class DefaultZLinkSpotManager {
         record.applicationMetadata?.byteLength ?? zlinkMetadataByteLength(envelope.header.metadata)
       )
     };
-    if (record.kind === ReceiveKind.SpotSend) {
-      await this.ensureInstanceApplicationActivation(meshName, spotId);
-      await this.routedSpotPackets.sendEncoded(spotId, packetName, decodePayload, context);
-      return;
-    }
-    if (record.kind !== ReceiveKind.SpotRequest) {
-      throw new ZLinkConfigurationException(
-        `Unsupported MeshNode Spot record kind '${record.kind}'.`
-      );
-    }
     try {
-      await this.ensureInstanceApplicationActivation(meshName, spotId);
-      const response = await this.routedSpotPackets.requestEncoded(
-        spotId,
-        packetName,
-        decodePayload,
-        context
-      );
-      requireMeshSpotReply(
-        record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
-      );
+      const dispatch = async () => {
+        if (record.kind === ReceiveKind.SpotSend) {
+          await this.ensureInstanceApplicationActivation(meshName, spotId);
+          await this.routedSpotPackets.sendEncoded(spotId, packetName, decodePayload, context);
+          return;
+        }
+        if (record.kind !== ReceiveKind.SpotRequest) {
+          throw new ZLinkConfigurationException(
+            `Unsupported MeshNode Spot record kind '${record.kind}'.`
+          );
+        }
+        await this.ensureInstanceApplicationActivation(meshName, spotId);
+        const response = await this.routedSpotPackets.requestEncoded(
+          spotId,
+          packetName,
+          decodePayload,
+          context
+        );
+        requireMeshSpotReply(
+          record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
+        );
+      };
+      await (admit === undefined ? dispatch() : admit(dispatch));
     } catch (error) {
+      if (record.kind !== ReceiveKind.SpotRequest) throw error;
       requireMeshSpotReply(record.reply(encodeChannelErrorReplyParts(envelope.header, error)));
     }
   }
@@ -1728,7 +1810,8 @@ export class DefaultZLinkSpotManager {
   async dispatchMeshInstance(
     meshName: string,
     owner: ReadyRecord,
-    record: ReceiveRecord
+    record: ReceiveRecord,
+    admit?: ZLinkMeshDispatchAdmission
   ): Promise<void> {
     const spotId = owner.spotId as unknown as RoutingId | null;
     if (spotId === null) {
@@ -1758,75 +1841,111 @@ export class DefaultZLinkSpotManager {
         'activating'
       );
       try {
-        await this.ensureInstanceApplicationActivation(meshName, spotId);
-        const activation = this.resolveApplicationActivation(spotId, meshName);
-        if (activation === undefined || activation.domain.kind !== 'instance') {
-          throw new ZLinkConfigurationException(
-            `MeshNode Instance Spot target '${String(spotId)}' is not active.`
-          );
-        }
-        const target = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
-        if (
-          target !== undefined &&
-          activation.domain.objectGeneration !== target.objectGeneration
-        ) {
-          throw createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
-            `Instance Spot target '${String(spotId)}' application generation is stale.`
+        const dispatch = async () => {
+          await this.ensureInstanceApplicationActivation(meshName, spotId);
+          const activation = this.resolveApplicationActivation(spotId, meshName);
+          if (activation === undefined || activation.domain.kind !== 'instance') {
+            throw new ZLinkConfigurationException(
+              `MeshNode Instance Spot target '${String(spotId)}' is not active.`
+            );
+          }
+          const target = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
+          if (
+            target !== undefined &&
+            activation.domain.objectGeneration !== target.objectGeneration
+          ) {
+            throw createInternalFrameworkException(
+              ZLinkFrameworkInternalErrorKind.SpotGenerationStale,
+              `Instance Spot target '${String(spotId)}' application generation is stale.`
+            );
+          }
+          const codecs =
+            this.options.messageSerializers === undefined
+              ? undefined
+              : { serializers: this.options.messageSerializers };
+          const decodePayload = () => decodeChannelPayload(envelope, codecs);
+          const context = {
+            channelName: envelope.header.channelName,
+            contentType: envelope.header.contentType,
+            awaitFirstHandlerTurn: record.kind === ReceiveKind.InstanceSpotActivation,
+            activationRecord: record,
+            onOneWayError:
+              this.options.dispatchErrors?.captureEnabled() === true
+                ? (error: unknown) =>
+                    this.reportInstanceDispatchFailure(
+                      meshName,
+                      spotId,
+                      record,
+                      envelope,
+                      false,
+                      error
+                    )
+                : undefined,
+            workOptions: zlinkSerialWorkOptions(
+              envelope.payload.byteLength,
+              record.applicationMetadata?.byteLength ??
+                zlinkMetadataByteLength(envelope.header.metadata)
+            )
+          };
+          // Spot messaging §7 step 3: an Instance intent request that reaches an
+          // incarnation whose Close ended admission is refused before admission
+          // with the owner fence terminal, so its caller re-reads authority.
+          const instanceIntent =
+            record.activationRecord?.activation === 'missing' ||
+            (record.activationRecord?.activation === 'ready' &&
+              record.activationRecord.instanceIntent);
+          const refusal = activation.serial.applicationAdmissionRefusal(instanceIntent === true);
+          if (request && refusal !== undefined && record.replyFailure !== undefined) {
+            this.reportInstanceDispatchFailure(
+              meshName,
+              spotId,
+              record,
+              envelope,
+              request,
+              refusal
+            );
+            const terminal = internalFrameworkWireReply(refusal);
+            requireMeshSpotReply(
+              record.replyFailure(terminal.terminalResult, terminal.failureCode)
+            );
+            return;
+          }
+          this.traceInstanceMessage(
+            ZLinkMessageFlowOutcome.Admitted,
+            meshName,
+            spotId,
+            record,
+            envelope,
+            'ready',
+            target?.stableType
           );
-        }
-        const codecs =
-          this.options.messageSerializers === undefined
-            ? undefined
-            : { serializers: this.options.messageSerializers };
-        const decodePayload = () => decodeChannelPayload(envelope, codecs);
-        const context = {
-          channelName: envelope.header.channelName,
-          contentType: envelope.header.contentType,
-          awaitFirstHandlerTurn: record.kind === ReceiveKind.InstanceSpotActivation,
-          activationRecord: record,
-          onOneWayError:
-            this.options.dispatchErrors?.captureEnabled() === true
-              ? (error: unknown) =>
-                  this.reportInstanceDispatchFailure(
-                    meshName,
-                    spotId,
-                    record,
-                    envelope,
-                    false,
-                    error
-                  )
-              : undefined,
-          workOptions: zlinkSerialWorkOptions(
-            envelope.payload.byteLength,
-            record.applicationMetadata?.byteLength ??
-              zlinkMetadataByteLength(envelope.header.metadata)
-          )
-        };
-        // Spot messaging §7 step 3: an Instance intent request that reaches an
-        // incarnation whose Close ended admission is refused before admission
-        // with the owner fence terminal, so its caller re-reads authority.
-        const instanceIntent =
-          record.activationRecord?.activation === 'missing' ||
-          (record.activationRecord?.activation === 'ready' &&
-            record.activationRecord.instanceIntent);
-        const refusal = activation.serial.applicationAdmissionRefusal(instanceIntent === true);
-        if (request && refusal !== undefined && record.replyFailure !== undefined) {
-          this.reportInstanceDispatchFailure(meshName, spotId, record, envelope, request, refusal);
-          const terminal = internalFrameworkWireReply(refusal);
-          requireMeshSpotReply(record.replyFailure(terminal.terminalResult, terminal.failureCode));
-          return;
-        }
-        this.traceInstanceMessage(
-          ZLinkMessageFlowOutcome.Admitted,
-          meshName,
-          spotId,
-          record,
-          envelope,
-          'ready',
-          target?.stableType
-        );
-        if (!request) {
+          if (!request) {
+            this.traceInstanceMessage(
+              ZLinkMessageFlowOutcome.Dispatched,
+              meshName,
+              spotId,
+              record,
+              envelope,
+              'ready',
+              target?.stableType
+            );
+            await this.routedSpotPackets.sendEncoded(
+              spotId,
+              envelope.packetName,
+              decodePayload,
+              context
+            );
+            this.traceInstanceMessage(
+              ZLinkMessageFlowOutcome.Completed,
+              meshName,
+              spotId,
+              record,
+              envelope,
+              'ready',
+              target?.stableType
+            );
+            return;
+          }
           this.traceInstanceMessage(
             ZLinkMessageFlowOutcome.Dispatched,
             meshName,
@@ -1836,14 +1955,17 @@ export class DefaultZLinkSpotManager {
             'ready',
             target?.stableType
           );
-          await this.routedSpotPackets.sendEncoded(
+          const response = await this.routedSpotPackets.requestEncoded(
             spotId,
             envelope.packetName,
             decodePayload,
             context
           );
+          requireMeshSpotReply(
+            record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
+          );
           this.traceInstanceMessage(
-            ZLinkMessageFlowOutcome.Completed,
+            ZLinkMessageFlowOutcome.Replied,
             meshName,
             spotId,
             record,
@@ -1851,35 +1973,8 @@ export class DefaultZLinkSpotManager {
             'ready',
             target?.stableType
           );
-          return;
-        }
-        this.traceInstanceMessage(
-          ZLinkMessageFlowOutcome.Dispatched,
-          meshName,
-          spotId,
-          record,
-          envelope,
-          'ready',
-          target?.stableType
-        );
-        const response = await this.routedSpotPackets.requestEncoded(
-          spotId,
-          envelope.packetName,
-          decodePayload,
-          context
-        );
-        requireMeshSpotReply(
-          record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
-        );
-        this.traceInstanceMessage(
-          ZLinkMessageFlowOutcome.Replied,
-          meshName,
-          spotId,
-          record,
-          envelope,
-          'ready',
-          target?.stableType
-        );
+        };
+        await (admit === undefined ? dispatch() : admit(dispatch));
       } catch (error) {
         this.reportInstanceDispatchFailure(meshName, spotId, record, envelope, request, error);
         const reason = dispatchReasonFromError(error);
@@ -1974,7 +2069,8 @@ export class DefaultZLinkSpotManager {
     origin: ApplicationJobOrigin,
     meshName: string,
     owner: ReadyRecord,
-    record: ReceiveRecord
+    record: ReceiveRecord,
+    admit?: ZLinkMeshDispatchAdmission
   ): Promise<void> {
     const spotId = owner.spotId as unknown as RoutingId | null;
     const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
@@ -1985,12 +2081,15 @@ export class DefaultZLinkSpotManager {
       throw new ZLinkConfigurationException('MeshNode Actor record is missing its Actor owner.');
     }
     const request = record.kind === ReceiveKind.ActorRequest;
-    const resolvedOwner = this.options.actorDispatchOwnerResolver?.(actor.actorId);
-    const resolvedActorRef = resolvedOwner?.actorRef ?? {
-      actorId: actor.actorId,
-      objectGeneration: actor.generation,
+    const nativeTarget = record.messageFollowOrigin?.target;
+    const ingressActor = nativeTarget?.actor ?? actor;
+    const resolvedActorRef = (nativeTarget === undefined
+      ? this.options.actorDispatchOwnerResolver?.(actor.actorId).actorRef
+      : undefined) ?? {
+      actorId: ingressActor.actorId,
+      objectGeneration: ingressActor.generation,
       meshName,
-      nodeRid: String(actor.nodeRid)
+      nodeRid: ingressActor.nodeRid
     };
     const responseActorRef =
       record.sourceBindingGeneration > 0n
@@ -2029,43 +2128,49 @@ export class DefaultZLinkSpotManager {
         )
       : undefined;
     try {
-      if (this.formalRemoteTransfers.has(actor.actorId)) {
-        throw new Error(`Actor '${actor.actorId}' target transfer reconciliation is not complete.`);
-      }
-      const response = targetsEntrySpot
-        ? await this.options.dispatchEntryActorPacket?.(
-            origin,
-            actor.actorId,
-            record.parts,
-            request,
-            undefined,
-            ownerActorRef,
-            requestTerminal,
-            record.messageFollowOrigin
-          )
-        : await this.dispatchMeshActorPacket(
-            origin,
-            meshName,
-            spotId,
-            actor.actorId,
-            record.parts,
-            request,
-            ownerActorRef,
-            requestTerminal,
-            record.messageFollowOrigin
+      const dispatch = async () => {
+        if (this.formalRemoteTransfers.has(actor.actorId)) {
+          throw new Error(
+            `Actor '${actor.actorId}' target transfer reconciliation is not complete.`
           );
-      if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
-        throw new ZLinkConfigurationException(
-          'MeshNode Entry Spot Actor dispatch is not configured.'
-        );
-      }
-      if (request && !requestTerminalState.submitted) {
-        requireMeshSpotReply(
-          record.reply(
-            this.encodeMeshActorReply(record.parts[0], ZLinkStreamMessageKind.Response, response)
-          )
-        );
-      }
+        }
+        const response = targetsEntrySpot
+          ? await this.options.dispatchEntryActorPacket?.(
+              origin,
+              actor.actorId,
+              record.parts,
+              request,
+              undefined,
+              ownerActorRef,
+              requestTerminal,
+              record.messageFollowOrigin
+            )
+          : await this.dispatchMeshActorPacket(
+              origin,
+              meshName,
+              spotId,
+              actor.actorId,
+              record.parts,
+              request,
+              ownerActorRef,
+              requestTerminal,
+              record.messageFollowOrigin
+            );
+        if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
+          throw new ZLinkConfigurationException(
+            'MeshNode Entry Spot Actor dispatch is not configured.'
+          );
+        }
+        if (response === RELOCATED_REQUEST_OWNED_BY_REQUESTER) return;
+        if (request && !requestTerminalState.submitted) {
+          requireMeshSpotReply(
+            record.reply(
+              this.encodeMeshActorReply(record.parts[0], ZLinkStreamMessageKind.Response, response)
+            )
+          );
+        }
+      };
+      await (admit === undefined ? dispatch() : admit(dispatch));
     } catch (error) {
       if (!request) {
         throw error;
@@ -2075,10 +2180,11 @@ export class DefaultZLinkSpotManager {
       }
       requireMeshSpotReply(
         record.reply(
-          this.encodeMeshActorReply(record.parts[0], ZLinkStreamMessageKind.Error, {
-            message: error instanceof Error ? error.message : String(error),
-            kind: spotActorFailureKind(error)
-          })
+          this.encodeMeshActorReply(
+            record.parts[0],
+            ZLinkStreamMessageKind.Error,
+            boundSessionErrorPayload(error)
+          )
         )
       );
     }
@@ -2866,11 +2972,7 @@ export class DefaultZLinkSpotManager {
           control.previousMembershipEpoch
         );
       };
-      if (this.options.actorTransferRuntime === undefined) {
-        await callback();
-      } else {
-        await this.options.actorTransferRuntime.notifyCoreSourceLeave(actor, callback);
-      }
+      await callback();
       return;
     }
     if (spotId === null) {
@@ -2961,7 +3063,7 @@ export class DefaultZLinkSpotManager {
             // ingress hold) migrate into the real Actor queue next, in the
             // order they parked — after the relayed backlog above, before
             // regular ingress opens.
-            await this.migrateActorJoinPrewarm(activation, actor, pendingTransfer.transferId);
+            this.migrateActorJoinPrewarm(activation, actor, pendingTransfer.transferId);
             // This registry owns target lifecycle and saved backlog
             // reconciliation only. Session route readiness is enforced by
             // the Session binding aggregate after this boundary.
@@ -3034,9 +3136,7 @@ export class DefaultZLinkSpotManager {
           if (sourceJoinedActor === undefined && pendingTransfer === undefined) {
             return;
           }
-          await this.options.actorTransferRuntime.notifyCoreSourceLeave(actor, () =>
-            activation.spot.onLeaveActor(actor)
-          );
+          await activation.spot.onLeaveActor(actor);
         }
         activation.commitActorDeparture(actor.context.actorId);
         return;
@@ -3075,7 +3175,7 @@ export class DefaultZLinkSpotManager {
     }
     const outcome = admission.result ?? (await admission.resultTask);
     if ('error' in outcome) throw outcome.error;
-    if (!outcome.accepted || admission.state !== 'admitted') {
+    if (!outcome.accepted || (admission.state !== 'admitted' && admission.state !== 'restoring')) {
       throw new Error(`Actor Join relocation '${relocationId}' has no accepted admission.`);
     }
     const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
@@ -3096,6 +3196,19 @@ export class DefaultZLinkSpotManager {
       }
     } catch (error) {
       lifecycleFailure = { error };
+      const reporter = this.options.dispatchErrors;
+      if (reporter?.captureEnabled() === true) {
+        reporter.report({
+          surface: ZLinkDispatchErrorSurface.ActorRelocation,
+          messageKind: ZLinkDispatchMessageKind.Control,
+          reason: dispatchReasonFromError(error),
+          action: ZLinkDispatchErrorAction.FailCaller,
+          packetName: 'OnJoinedActor',
+          meshName,
+          actorId: actor.context.actorId,
+          error
+        });
+      }
     }
     if (lifecycleFailure === undefined) {
       const sourceLeave = submitSourceLeave(admission.admission.actorRef.nodeRid);
@@ -3114,7 +3227,7 @@ export class DefaultZLinkSpotManager {
             if (activation === undefined) {
               throw new Error(`Actor Join relocation '${relocationId}' target mailbox is missing.`);
             }
-            return activation.executeActor(actor.context.actorId, operation);
+            return activation.executeActor(actor.context.actorId, operation, { lane: 'lifecycle' });
           };
       await this.options.actorTransferRuntime.deliverDeferredJoinCompletion(
         lifecycleFailure === undefined
@@ -3135,6 +3248,21 @@ export class DefaultZLinkSpotManager {
     return true;
   }
 
+  beginActorJoinRelocation(relocationId: string): () => void {
+    this.formalRemoteActorAdmissions.beginRestore(relocationId);
+    return () => this.formalRemoteActorAdmissions.finishRestore(relocationId);
+  }
+
+  /** @internal Transfers accepted ingress after the target Actor becomes visible. */
+  openActorJoinRelocation(meshName: string, relocationId: string, actor: ZLinkActor): void {
+    const admission = this.formalRemoteActorAdmissions.get(relocationId);
+    if (admission === undefined) return;
+    const activation = this.activations.resolve(meshName, admission.admission.spotId);
+    if (activation !== undefined) {
+      this.migrateActorJoinPrewarm(activation, actor, relocationId);
+    }
+  }
+
   async restoreCanonicalActorJoinRecovery(
     recovery: CanonicalActorJoinRecovery,
     signal?: AbortSignal
@@ -3147,7 +3275,11 @@ export class DefaultZLinkSpotManager {
       );
     }
     const outcome = admission.result ?? (await admission.resultTask);
-    if ('error' in outcome || !outcome.accepted || admission.state !== 'admitted') {
+    if (
+      'error' in outcome ||
+      !outcome.accepted ||
+      (admission.state !== 'admitted' && admission.state !== 'restoring')
+    ) {
       throw new Error(
         `Actor Join recovery '${recovery.request.handoffId}' has no accepted admission.`
       );
@@ -3225,35 +3357,13 @@ export class DefaultZLinkSpotManager {
     kind: ZLinkStreamMessageKind.Response | ZLinkStreamMessageKind.Error,
     payload: unknown
   ): readonly Buffer[] {
-    // Spec 27 §4/§7: the decode gate strips the observation-only flow pair at
-    // Off (and skips its validation); when tracing is on the reply preserves
-    // the request's flow pair alongside its correlation.
-    const requestHeader = decodeStreamHeader(
+    return encodeActorReply(
       requestHeaderPart.data(),
+      kind,
+      payload,
+      this.options.messageSerializers,
       this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true
     );
-    const encoded = encodeFrameworkPayload(payload, this.options.messageSerializers);
-    try {
-      //  encodeStreamHeader returns a fresh, unaliased array; view it without
-      //  re-copying. The payload copy stays: encoded.message closes below.
-      const replyHeader = encodeStreamHeader({
-        kind,
-        codec: streamCodecForContentType(encoded.contentType),
-        flags: ZLinkStreamHeaderFlags.None,
-        requestSeq: requestHeader.requestSeq,
-        name: '',
-        metadata: new Map(),
-        correlationId: requestHeader.correlationId,
-        flowId: requestHeader.flowId,
-        flowOrigin: requestHeader.flowOrigin
-      });
-      return [
-        Buffer.from(replyHeader.buffer, replyHeader.byteOffset, replyHeader.byteLength),
-        Buffer.from(encoded.message.data())
-      ];
-    } finally {
-      encoded.message.close();
-    }
   }
 
   private async createActivation<TSpot extends ZLinkSpot>(
@@ -3315,13 +3425,14 @@ export class DefaultZLinkSpotManager {
    * either lands in the snapshot or resolves the Actor directly through
    * ordinary ingress — never both, never neither.
    */
-  private async migrateActorJoinPrewarm(
+  private migrateActorJoinPrewarm(
     activation: ZLinkSpotActivation,
     actor: ZLinkActor,
     transferId: string
-  ): Promise<void> {
+  ): void {
     const drained = this.formalRemoteActorAdmissions.completeMigration(transferId);
-    for (const arrival of drained) {
+    if (drained.length === 0) return;
+    const terminals = drained.map(async (arrival) => {
       try {
         const response = await this.dispatchActorPacket(
           arrival.origin,
@@ -3337,7 +3448,16 @@ export class DefaultZLinkSpotManager {
       } catch (error) {
         arrival.reject(error);
       }
-    }
+    });
+    // Reserve every retained arrival's FIFO position before ordinary ingress
+    // can resume. Handler terminals must not hold the relocation finalize that
+    // releases an earlier saved-work prefix.
+    this.options.detachedTaskRunner.runDetached(
+      `actor Join ingress migration ${actor.context.actorId}`,
+      async () => {
+        await Promise.all(terminals);
+      }
+    );
   }
 
   private async dispatchMeshActorPacket(
@@ -3555,7 +3675,7 @@ function validateRemoteAdmissionCommit(
     expected.targetSpotGeneration !== (control.currentSpotGeneration ?? 0n) ||
     actorRef === undefined ||
     actorRef.actorId !== expected.actorRef.actorId ||
-    String(actorRef.nodeRid) !== String(expected.actorRef.nodeRid) ||
+    !routingIdsEqual(actorRef.nodeRid, expected.actorRef.nodeRid) ||
     actorRef.objectGeneration !== expected.actorRef.objectGeneration
   ) {
     throw new ZLinkConfigurationException(
@@ -3603,17 +3723,3 @@ function isAbortSignal(value: unknown): value is AbortSignal {
     typeof (value as { addEventListener?: unknown }).addEventListener === 'function'
   );
 }
-
-function instanceActivationOutcome(error: unknown): string {
-  if (isAbortError(error)) return 'shutdown';
-  if (error instanceof ZLinkFrameworkException) {
-    if (error.kind === ZLinkFrameworkErrorKind.DeadlineExceeded) return 'timed_out';
-    if (error.kind === ZLinkFrameworkErrorKind.AlreadyExists) return 'conflict';
-    if (
-      error.kind === ZLinkFrameworkErrorKind.InvalidOperation ||
-      error.kind === ZLinkFrameworkErrorKind.Unavailable
-    )
-      return 'fenced';
-  }
-  return 'failed';
-}