@zlink-systems/framework 0.30.1 → 0.30.2

package/dist/runtime/spots/index.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultZLinkSpotManager = exports.ZLinkPublicSpotManager = exports.ZLinkSpotNodeRuntimeManager = exports.createFrameworkEntrySpotId = exports.ZLinkEntrySpotActivation = exports.ZLinkRuntimeSpotPublisherTransport = exports.DefaultZLinkSpotHandlerRegistry = exports.DefaultZLinkSpotOutbound = exports.ZLinkSpotTimerRegistry = exports.ZLinkManagedTimer = exports.ZLinkSpotSerialExecutor = exports.ZLinkSpotSerialTurnExecutor = exports.ZLinkSpotActorAdmissionCoordinator = exports.ZLinkSpotRoutedBoundSessionDispatch = exports.sendToSpotHandle = exports.requestToSpotHandle = exports.resolveSpotHandle = exports.createSpotHandle = void 0;
+exports.DefaultZLinkSpotManager = exports.ZLinkPublicSpotManager = exports.ZLinkSpotNodeRuntimeManager = exports.registrationAcceptsNewActor = exports.createFrameworkEntrySpotId = exports.ZLinkEntrySpotActivation = exports.ZLinkRuntimeSpotPublisherTransport = exports.DefaultZLinkSpotHandlerRegistry = exports.DefaultZLinkSpotOutbound = exports.ZLinkSpotTimerRegistry = exports.ZLinkManagedTimer = exports.ZLinkSpotSerialExecutor = exports.ZLinkSpotSerialTurnExecutor = exports.ZLinkSpotActorAdmissionCoordinator = exports.ZLinkSpotRoutedBoundSessionDispatch = exports.sendToSpotHandle = exports.requestToSpotHandle = exports.resolveSpotHandle = exports.createSpotHandle = void 0;
+const actor_reply_1 = require("../actors/actor-reply");
+const bound_session_response_target_1 = require("../streams/bound-session-response-target");
+const actor_handoff_1 = require("../actors/actor-handoff");
+const routing_id_1 = require("../routing-id");
 const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
 var spot_handle_1 = require("./spot-handle");
 Object.defineProperty(exports, "createSpotHandle", { enumerable: true, get: function () { return spot_handle_1.createSpotHandle; } });
@@ -29,9 +33,9 @@ const payload_codec_1 = require("../messaging/payload-codec");
 const channel_envelope_1 = require("../channels/channel-envelope");
 const protocol_1 = require("../streams/protocol");
 const actor_remote_wire_1 = require("../actors/actor-remote-wire");
-const actor_handoff_1 = require("../actors/actor-handoff");
+const actor_handoff_2 = require("../actors/actor-handoff");
 const spot_remote_codec_1 = require("./spot-remote-codec");
-const routing_id_1 = require("../routing-id");
+const routing_id_2 = require("../routing-id");
 const service_wire_constants_generated_1 = require("../foundation/service-wire-constants.generated");
 var spot_serial_turn_executor_1 = require("./spot-serial-turn-executor");
 Object.defineProperty(exports, "ZLinkSpotSerialTurnExecutor", { enumerable: true, get: function () { return spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor; } });
@@ -57,6 +61,7 @@ var spot_entry_activation_1 = require("./spot-entry-activation");
 Object.defineProperty(exports, "ZLinkEntrySpotActivation", { enumerable: true, get: function () { return spot_entry_activation_1.ZLinkEntrySpotActivation; } });
 var spot_node_runtime_manager_1 = require("./spot-node-runtime-manager");
 Object.defineProperty(exports, "createFrameworkEntrySpotId", { enumerable: true, get: function () { return spot_node_runtime_manager_1.createFrameworkEntrySpotId; } });
+Object.defineProperty(exports, "registrationAcceptsNewActor", { enumerable: true, get: function () { return spot_node_runtime_manager_1.registrationAcceptsNewActor; } });
 Object.defineProperty(exports, "ZLinkSpotNodeRuntimeManager", { enumerable: true, get: function () { return spot_node_runtime_manager_1.ZLinkSpotNodeRuntimeManager; } });
 var spot_manager_public_1 = require("./spot-manager-public");
 Object.defineProperty(exports, "ZLinkPublicSpotManager", { enumerable: true, get: function () { return spot_manager_public_1.ZLinkPublicSpotManager; } });
@@ -158,9 +163,17 @@ class DefaultZLinkSpotManager {
             statefulExecutionAllowed: options.statefulExecution?.admissionOpen,
             leaveActor: (spotId, actor, signal, meshName) => 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
@@ -207,10 +220,10 @@ class DefaultZLinkSpotManager {
     resolveRelocationActivation(meshName, spotId) {
         return this.activations.resolve(meshName, spotId);
     }
-    async prepareRelocationSpot(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, signal) {
+    async prepareRelocationSpot(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, restoredTimers, signal) {
         this.activations.stage(meshName, spotId);
         try {
-            return await this.activationLifecycle.materializeRelocation(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, signal);
+            return await this.activationLifecycle.materializeRelocation(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, restoredTimers, signal);
         }
         catch (error) {
             this.activations.abandonStage(meshName, spotId);
@@ -218,11 +231,16 @@ class DefaultZLinkSpotManager {
         }
     }
     async publishRelocationSpot(activation, beforeAdmission) {
-        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) {
+        await this.activationLifecycle.discardPreparation(activation);
         this.activations.detachRelocated(activation.meshName, activation.spotId);
         await activation.timers.dispose();
         await activation.nativeSpot?.dispose();
@@ -231,7 +249,7 @@ class DefaultZLinkSpotManager {
         this.activations.detachRelocated(activation.meshName, activation.spotId);
         await activation.nativeSpot?.dispose();
     }
-    async materializeInstance(meshName, instanceType, spotId, objectGeneration, signal) {
+    async materializeInstance(meshName, instanceType, spotId, objectGeneration, signal, completion = 'publication') {
         const readyTarget = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
         const existing = this.pendingInstanceMaterializations.get(instanceMaterializationKey(meshName, spotId, objectGeneration));
         if (existing !== undefined) {
@@ -240,13 +258,13 @@ class DefaultZLinkSpotManager {
         }
         const release = await this.options.activationAdmission?.acquire(meshName, signal);
         try {
-            await this.materializeInstanceCore(meshName, instanceType, spotId, objectGeneration, readyTarget?.objectGeneration === objectGeneration, signal);
+            await this.materializeInstanceCore(meshName, instanceType, spotId, objectGeneration, readyTarget?.objectGeneration === objectGeneration, signal, completion);
         }
         finally {
             release?.();
         }
     }
-    async materializeInstanceCore(meshName, instanceType, spotId, objectGeneration, requiresReadyTarget, signal) {
+    async materializeInstanceCore(meshName, instanceType, spotId, objectGeneration, requiresReadyTarget, signal, completion) {
         const factory = this.requireInstanceFactory(meshName, instanceType);
         const key = `${meshName}\0${String(spotId)}`;
         const materializationKey = instanceMaterializationKey(meshName, spotId, objectGeneration);
@@ -272,7 +290,7 @@ class DefaultZLinkSpotManager {
                 await (0, abort_1.awaitWithAbort)(closing.ready, signal);
                 continue;
             }
-            const current = this.activations.resolve(meshName, spotId);
+            const current = this.activations.activationForClose(meshName, spotId);
             if (current !== undefined) {
                 if (current.spotType !== factory) {
                     throw new configuration_1.ZLinkConfigurationException(`Instance Spot '${String(spotId)}' is assigned to another type.`);
@@ -306,14 +324,16 @@ 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');
+                    .then(async (activation) => {
+                    if (completion === 'publication')
+                        await activation.serialExecutor.finishPreparation();
                     return activation;
                 }, (error) => {
-                    metric?.complete(instanceActivationOutcome(error));
+                    this.activations.abandonStage(meshName, spotId);
                     throw error;
                 });
                 this.pendingInstanceMaterializations.set(materializationKey, pending);
@@ -353,10 +373,13 @@ class DefaultZLinkSpotManager {
             : 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))
+            if (operation.authority !== undefined &&
+                String(operation.activation.spotId) === String(spotId))
                 return operation.activation;
         }
         return undefined;
@@ -364,6 +387,7 @@ class DefaultZLinkSpotManager {
     isInstanceMaterializing(meshName, spotId) {
         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);
     }
     isSpotClosing(meshName, spotId) {
@@ -374,7 +398,7 @@ class DefaultZLinkSpotManager {
         return this.closeOperations.get(`${meshName}\0${String(spotId)}`)?.authorityDecision;
     }
     async discardInstance(meshName, spotId) {
-        const activation = this.activations.resolve(meshName, spotId);
+        const activation = this.activations.activationForClose(meshName, spotId);
         if (activation === undefined)
             return;
         activation.requestClose();
@@ -400,6 +424,9 @@ class DefaultZLinkSpotManager {
     }
     async completeInstanceTerminal(meshName, spotId, objectGeneration) {
         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;
@@ -438,6 +465,13 @@ class DefaultZLinkSpotManager {
         generations.set(generationKey, (generations.get(generationKey) ?? 0) + 1);
         this.pendingInstanceTerminalGenerations.set(key, generations);
     }
+    publishInstance(target, meshName) {
+        const activation = this.activations.activationForClose(meshName, target.targetSpotId);
+        if (activation?.objectGeneration === target.objectGeneration) {
+            const published = this.activations.publish(meshName, target.targetSpotId);
+            published?.serialExecutor.openPreparationAdmission();
+        }
+    }
     deferInstanceAuthorityRelease(key, objectGeneration) {
         const generations = this.deferredInstanceAuthorityReleases.get(key) ?? new Set();
         generations.add(objectGeneration);
@@ -578,10 +612,12 @@ class DefaultZLinkSpotManager {
             .filter(({ spotId }) => !this.isSpotClosing(meshName, spotId));
     }
     async drainForShutdown(meshName, signal, deadline) {
-        const results = await Promise.allSettled(this.activations
+        // 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 (0, abort_1.awaitWithAbort)(Promise.allSettled(this.activations
             .activeActivations()
             .filter((activation) => activation.meshName === meshName)
-            .map((activation) => this.closeWithReason(meshName, activation.spotId, signal, contracts_1.ZLinkSpotCloseReason.HostShutdown, deadline)));
+            .map((activation) => this.closeWithReason(meshName, activation.spotId, undefined, contracts_1.ZLinkSpotCloseReason.HostShutdown, deadline))), signal);
         const errors = results
             .filter((result) => result.status === 'rejected')
             .map((result) => result.reason);
@@ -599,7 +635,9 @@ class DefaultZLinkSpotManager {
     closeFromContext(activation, objectGeneration, signal) {
         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);
         }
@@ -609,14 +647,14 @@ class DefaultZLinkSpotManager {
         const beginUserAuthority = activation.domain.kind === 'user' && this.options.beginUserClosingAuthority !== undefined
             ? (onCommitted) => this.options.beginUserClosingAuthority(meshName, spotId, objectGeneration, onCommitted)
             : undefined;
-        return this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose, undefined, beginUserAuthority);
+        return this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose, undefined, beginUserAuthority, activation);
     }
-    async closeWithReason(meshName, spotId, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline, beginUserAuthority) {
+    async closeWithReason(meshName, spotId, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline, beginUserAuthority, contextActivation) {
         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' &&
@@ -666,11 +704,13 @@ class DefaultZLinkSpotManager {
         return await operation.ready;
     }
     async runCloseOperation(meshName, spotId, operation, signal, deadline) {
+        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);
@@ -800,11 +840,18 @@ class DefaultZLinkSpotManager {
     beginUserSpotPublication(meshName, spotId) {
         this.activations.stage(meshName, spotId);
     }
-    publishUserSpot(meshName, spotId) {
-        this.activations.publish(meshName, spotId);
+    async publishUserSpot(meshName, spotId) {
+        const published = this.activations.publish(meshName, spotId);
+        await published?.serialExecutor.finishPreparation();
     }
-    abortUserSpotPublication(meshName, spotId) {
+    async abortUserSpotPublication(meshName, spotId) {
         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) {
         const activation = this.activations.resolveUnique(spotId);
@@ -849,9 +896,6 @@ class DefaultZLinkSpotManager {
     async commitActorLeaveAfterTransfer(spotId, actorId) {
         await this.actorMembership.commitActorLeaveAfterTransfer(spotId, actorId);
     }
-    async restoreActorAfterFailedTransfer(spotId, actor, signal) {
-        await this.actorMembership.restoreActorAfterFailedTransfer(spotId, actor, signal);
-    }
     async beginActorTransfer(spotId, actorId) {
         await this.actorMembership.beginActorTransfer(spotId, actorId);
     }
@@ -884,26 +928,41 @@ class DefaultZLinkSpotManager {
         }
         return this.activationLifecycle.admitActorPacketPrefix(activation, actorId, records);
     }
+    /** Resolves the current Actor FIFO owner for both Entry and User membership. */
+    admitSourceActorPacketPrefix(actorId, records) {
+        const owner = this.options.actorDispatchOwnerResolver?.(actorId);
+        if (owner?.actorRef === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' has no local FIFO owner.`);
+        }
+        if (owner.spotId === undefined) {
+            if (this.options.admitEntryActorPacketPrefix === undefined) {
+                throw new configuration_1.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, packetName, message, context) {
         await this.routedSpotPackets.send(spotId, packetName, message, context);
     }
     async dispatchRoutedSpotRequest(spotId, packetName, request, context) {
         return await this.routedSpotPackets.request(spotId, packetName, request, context);
     }
-    async dispatchMeshSpot(meshName, owner, record) {
+    async dispatchMeshSpot(meshName, owner, record, admit) {
         const spotId = owner.spotId;
         if (spotId === null) {
             throw new configuration_1.ZLinkConfigurationException('MeshNode Spot record is missing the owner Spot RID.');
         }
         if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotMulticast) {
-            const activation = this.activations.resolve(meshName, spotId);
+            const activation = this.activations.activationForClose(meshName, spotId);
             if (activation?.actorDispatch === undefined) {
                 throw new configuration_1.ZLinkConfigurationException(`MeshNode Spot multicast target '${String(spotId)}' is not active.`);
             }
             if (record.topic === null || record.topic.length === 0) {
                 throw new configuration_1.ZLinkConfigurationException('MeshNode Spot multicast record is missing its topic.');
             }
-            await activation.actorDispatch.dispatchSubscriptionRecord(record.topic, record.parts, record.sourceNodeRid);
+            const dispatch = () => activation.actorDispatch.dispatchSubscriptionRecord(record.topic, record.parts, record.sourceNodeRid);
+            await (admit === undefined ? dispatch() : admit(dispatch));
             return;
         }
         const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(record.parts, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
@@ -917,20 +976,25 @@ class DefaultZLinkSpotManager {
             contentType: envelope.header.contentType,
             workOptions: (0, serial_work_size_1.zlinkSerialWorkOptions)(envelope.payload.byteLength, record.applicationMetadata?.byteLength ?? (0, serial_work_size_1.zlinkMetadataByteLength)(envelope.header.metadata))
         };
-        if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend) {
-            await this.ensureInstanceApplicationActivation(meshName, spotId);
-            await this.routedSpotPackets.sendEncoded(spotId, packetName, decodePayload, context);
-            return;
-        }
-        if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest) {
-            throw new configuration_1.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((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+            const dispatch = async () => {
+                if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend) {
+                    await this.ensureInstanceApplicationActivation(meshName, spotId);
+                    await this.routedSpotPackets.sendEncoded(spotId, packetName, decodePayload, context);
+                    return;
+                }
+                if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest) {
+                    throw new configuration_1.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((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+            };
+            await (admit === undefined ? dispatch() : admit(dispatch));
         }
         catch (error) {
+            if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest)
+                throw error;
             requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error)));
         }
     }
@@ -954,7 +1018,7 @@ class DefaultZLinkSpotManager {
             target = latest;
         }
     }
-    async dispatchMeshInstance(meshName, owner, record) {
+    async dispatchMeshInstance(meshName, owner, record, admit) {
         const spotId = owner.spotId;
         if (spotId === null) {
             throw new configuration_1.ZLinkConfigurationException('MeshNode Instance Spot record is missing the owner Spot RID.');
@@ -965,55 +1029,58 @@ class DefaultZLinkSpotManager {
             const request = record.operationKind === service_runtime_contracts_1.OperationKind.InstanceSpotRequest;
             this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received, meshName, spotId, record, envelope, 'activating');
             try {
-                await this.ensureInstanceApplicationActivation(meshName, spotId);
-                const activation = this.resolveApplicationActivation(spotId, meshName);
-                if (activation === undefined || activation.domain.kind !== 'instance') {
-                    throw new configuration_1.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 (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale, `Instance Spot target '${String(spotId)}' application generation is stale.`);
-                }
-                const codecs = this.options.messageSerializers === undefined
-                    ? undefined
-                    : { serializers: this.options.messageSerializers };
-                const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
-                const context = {
-                    channelName: envelope.header.channelName,
-                    contentType: envelope.header.contentType,
-                    awaitFirstHandlerTurn: record.kind === service_runtime_contracts_1.ReceiveKind.InstanceSpotActivation,
-                    activationRecord: record,
-                    onOneWayError: this.options.dispatchErrors?.captureEnabled() === true
-                        ? (error) => this.reportInstanceDispatchFailure(meshName, spotId, record, envelope, false, error)
-                        : undefined,
-                    workOptions: (0, serial_work_size_1.zlinkSerialWorkOptions)(envelope.payload.byteLength, record.applicationMetadata?.byteLength ??
-                        (0, serial_work_size_1.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 = (0, framework_errors_internal_1.internalFrameworkWireReply)(refusal);
-                    requireMeshSpotReply(record.replyFailure(terminal.terminalResult, terminal.failureCode));
-                    return;
-                }
-                this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, meshName, spotId, record, envelope, 'ready', target?.stableType);
-                if (!request) {
+                const dispatch = async () => {
+                    await this.ensureInstanceApplicationActivation(meshName, spotId);
+                    const activation = this.resolveApplicationActivation(spotId, meshName);
+                    if (activation === undefined || activation.domain.kind !== 'instance') {
+                        throw new configuration_1.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 (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale, `Instance Spot target '${String(spotId)}' application generation is stale.`);
+                    }
+                    const codecs = this.options.messageSerializers === undefined
+                        ? undefined
+                        : { serializers: this.options.messageSerializers };
+                    const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+                    const context = {
+                        channelName: envelope.header.channelName,
+                        contentType: envelope.header.contentType,
+                        awaitFirstHandlerTurn: record.kind === service_runtime_contracts_1.ReceiveKind.InstanceSpotActivation,
+                        activationRecord: record,
+                        onOneWayError: this.options.dispatchErrors?.captureEnabled() === true
+                            ? (error) => this.reportInstanceDispatchFailure(meshName, spotId, record, envelope, false, error)
+                            : undefined,
+                        workOptions: (0, serial_work_size_1.zlinkSerialWorkOptions)(envelope.payload.byteLength, record.applicationMetadata?.byteLength ??
+                            (0, serial_work_size_1.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 = (0, framework_errors_internal_1.internalFrameworkWireReply)(refusal);
+                        requireMeshSpotReply(record.replyFailure(terminal.terminalResult, terminal.failureCode));
+                        return;
+                    }
+                    this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                    if (!request) {
+                        this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                        await this.routedSpotPackets.sendEncoded(spotId, envelope.packetName, decodePayload, context);
+                        this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                        return;
+                    }
                     this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, meshName, spotId, record, envelope, 'ready', target?.stableType);
-                    await this.routedSpotPackets.sendEncoded(spotId, envelope.packetName, decodePayload, context);
-                    this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, meshName, spotId, record, envelope, 'ready', target?.stableType);
-                    return;
-                }
-                this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, meshName, spotId, record, envelope, 'ready', target?.stableType);
-                const response = await this.routedSpotPackets.requestEncoded(spotId, envelope.packetName, decodePayload, context);
-                requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
-                this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                    const response = await this.routedSpotPackets.requestEncoded(spotId, envelope.packetName, decodePayload, context);
+                    requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+                    this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                };
+                await (admit === undefined ? dispatch() : admit(dispatch));
             }
             catch (error) {
                 this.reportInstanceDispatchFailure(meshName, spotId, record, envelope, request, error);
@@ -1072,7 +1139,7 @@ class DefaultZLinkSpotManager {
             errorReason
         });
     }
-    async dispatchMeshActor(origin, meshName, owner, record) {
+    async dispatchMeshActor(origin, meshName, owner, record, admit) {
         const spotId = owner.spotId;
         const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
         const targetsEntrySpot = spotId === null || (entrySpotId !== undefined && spotId === entrySpotId);
@@ -1081,12 +1148,15 @@ class DefaultZLinkSpotManager {
             throw new configuration_1.ZLinkConfigurationException('MeshNode Actor record is missing its Actor owner.');
         }
         const request = record.kind === service_runtime_contracts_1.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
             ? {
@@ -1112,18 +1182,23 @@ 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);
-            if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
-                throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot Actor dispatch is not configured.');
-            }
-            if (request && !requestTerminalState.submitted) {
-                requireMeshSpotReply(record.reply(this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Response, response)));
-            }
+            const dispatch = async () => {
+                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);
+                if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot Actor dispatch is not configured.');
+                }
+                if (response === actor_handoff_1.RELOCATED_REQUEST_OWNED_BY_REQUESTER)
+                    return;
+                if (request && !requestTerminalState.submitted) {
+                    requireMeshSpotReply(record.reply(this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Response, response)));
+                }
+            };
+            await (admit === undefined ? dispatch() : admit(dispatch));
         }
         catch (error) {
             if (!request) {
@@ -1132,10 +1207,7 @@ class DefaultZLinkSpotManager {
             if (requestTerminalState.prepared || requestTerminalState.submitted) {
                 throw error;
             }
-            requireMeshSpotReply(record.reply(this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Error, {
-                message: error instanceof Error ? error.message : String(error),
-                kind: spotActorFailureKind(error)
-            })));
+            requireMeshSpotReply(record.reply(this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Error, (0, bound_session_response_target_1.boundSessionErrorPayload)(error))));
         }
     }
     async dispatchMeshActorJoin(meshName, owner, record) {
@@ -1628,7 +1700,7 @@ class DefaultZLinkSpotManager {
                             if (!sourceLeaveSubmitted) {
                                 throw new Error(`Actor '${entryActor.context.actorId}' source authority commit failed before leave submission.`);
                             }
-                            const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, async (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => {
+                            const handoffResults = await (0, actor_handoff_2.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, async (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => {
                                 if (this.options.dispatchEntryActorPacket === undefined) {
                                     throw new Error('Entry Spot saved handoff replay requires its Actor packet runtime.');
                                 }
@@ -1745,12 +1817,7 @@ class DefaultZLinkSpotManager {
             const callback = async () => {
                 await this.options.entrySpotCallbacks?.onLeaveActor(actor, undefined, actorRef, control.previousMembershipEpoch);
             };
-            if (this.options.actorTransferRuntime === undefined) {
-                await callback();
-            }
-            else {
-                await this.options.actorTransferRuntime.notifyCoreSourceLeave(actor, callback);
-            }
+            await callback();
             return;
         }
         if (spotId === null) {
@@ -1791,7 +1858,7 @@ class DefaultZLinkSpotManager {
                 };
                 const completeTargetReady = async () => {
                     if (pendingTransfer !== undefined) {
-                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket('remote', activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
+                        const handoffResults = await (0, actor_handoff_2.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket('remote', activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
                             sourceName: 'zlink.framework.actor-handoff',
                             timestamp: new Date(),
                             marker: 'backlog_enqueued',
@@ -1808,7 +1875,7 @@ 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.
@@ -1871,7 +1938,7 @@ 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;
@@ -1917,6 +1984,19 @@ class DefaultZLinkSpotManager {
         }
         catch (error) {
             lifecycleFailure = { error };
+            const reporter = this.options.dispatchErrors;
+            if (reporter?.captureEnabled() === true) {
+                reporter.report({
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.ActorRelocation,
+                    messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Control,
+                    reason: (0, dispatch_error_details_1.dispatchReasonFromError)(error),
+                    action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.FailCaller,
+                    packetName: 'OnJoinedActor',
+                    meshName,
+                    actorId: actor.context.actorId,
+                    error
+                });
+            }
         }
         if (lifecycleFailure === undefined) {
             const sourceLeave = submitSourceLeave(admission.admission.actorRef.nodeRid);
@@ -1930,7 +2010,7 @@ 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
                 ? outcome.deferredJoinCompletion
@@ -1949,6 +2029,16 @@ class DefaultZLinkSpotManager {
         this.formalRemoteActorAdmissions.beginRestore(relocationId);
         return () => this.formalRemoteActorAdmissions.finishRestore(relocationId);
     }
+    /** @internal Transfers accepted ingress after the target Actor becomes visible. */
+    openActorJoinRelocation(meshName, relocationId, actor) {
+        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, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const admission = this.formalRemoteActorAdmissions.get(recovery.request.handoffId);
@@ -1965,7 +2055,7 @@ class DefaultZLinkSpotManager {
         if (admitted.sourceActorNodeRid === undefined) {
             throw new Error(`Actor Join recovery '${recovery.request.handoffId}' lost its command-28 source route.`);
         }
-        const admittedNodeBytes = Buffer.from((0, routing_id_1.encodeRoutingIdStorageHex)(admitted.sourceActorNodeRid), 'hex');
+        const admittedNodeBytes = Buffer.from((0, routing_id_2.encodeRoutingIdStorageHex)(admitted.sourceActorNodeRid), 'hex');
         if (admitted.actorId !== recovery.request.actorId ||
             admitted.actorType !== recovery.request.actorType ||
             admitted.requestFingerprint !== recovery.request.request.toString('base64') ||
@@ -2003,33 +2093,7 @@ class DefaultZLinkSpotManager {
         this.formalRemoteActorAdmissions.attachDeferredJoinCompletion(recovery.request.handoffId, deferred);
     }
     encodeMeshActorReply(requestHeaderPart, kind, payload) {
-        // 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 = (0, protocol_1.decodeStreamHeader)(requestHeaderPart.data(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
-        const encoded = (0, payload_codec_1.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 = (0, protocol_1.encodeStreamHeader)({
-                kind,
-                codec: (0, protocol_1.streamCodecForContentType)(encoded.contentType),
-                flags: protocol_1.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();
-        }
+        return (0, actor_reply_1.encodeActorReply)(requestHeaderPart.data(), kind, payload, this.options.messageSerializers, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
     }
     async createActivation(meshName, spotType, spotId, request, signal, authority) {
         this.requireRegisteredFactory(spotType);
@@ -2053,9 +2117,11 @@ class DefaultZLinkSpotManager {
      * either lands in the snapshot or resolves the Actor directly through
      * ordinary ingress — never both, never neither.
      */
-    async migrateActorJoinPrewarm(activation, actor, transferId) {
+    migrateActorJoinPrewarm(activation, actor, transferId) {
         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, activation, actor.context.actorId, [runtime_message_1.ZLinkBufferMessage.from(arrival.header), runtime_message_1.ZLinkBufferMessage.from(arrival.payload)], arrival.returnResponse, arrival.remoteBoundSessionTarget, arrival.fallbackActorRef, arrival.requestTerminal);
                 arrival.resolve(response);
@@ -2063,7 +2129,13 @@ 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);
+        });
     }
     async dispatchMeshActorPacket(origin, meshName, spotId, actorId, parts, returnResponse, fallbackActorRef, requestTerminal, messageFollowOrigin) {
         const activation = this.activations.resolve(meshName, spotId);
@@ -2119,7 +2191,7 @@ function decodeFormalRemoteTransferRequestBytes(bytes) {
             ? payload.requestContentType
             : 'application/json',
         actorEntryNodeRid: typeof payload.actorEntryNodeRid === 'string'
-            ? (0, routing_id_1.decodeRoutingId)(payload.actorEntryNodeRid, payload.actorEntryNodeRidHex)
+            ? (0, routing_id_2.decodeRoutingId)(payload.actorEntryNodeRid, payload.actorEntryNodeRidHex)
             : undefined,
         sourceSpotId: typeof payload.sourceSpotId === 'string' ? payload.sourceSpotId : undefined,
         actorRef: decodeFormalRemoteActorRef(payload),
@@ -2176,7 +2248,7 @@ function validateRemoteAdmissionCommit(admission, request, actorId, control) {
         expected.targetSpotGeneration !== (control.currentSpotGeneration ?? 0n) ||
         actorRef === undefined ||
         actorRef.actorId !== expected.actorRef.actorId ||
-        String(actorRef.nodeRid) !== String(expected.actorRef.nodeRid) ||
+        !(0, routing_id_1.routingIdsEqual)(actorRef.nodeRid, expected.actorRef.nodeRid) ||
         actorRef.objectGeneration !== expected.actorRef.objectGeneration) {
         throw new configuration_1.ZLinkConfigurationException(`Remote Actor '${actorId}' commit does not match its target admission.`);
     }
@@ -2204,17 +2276,3 @@ function isAbortSignal(value) {
         typeof value.aborted === 'boolean' &&
         typeof value.addEventListener === 'function');
 }
-function instanceActivationOutcome(error) {
-    if ((0, abort_1.isAbortError)(error))
-        return 'shutdown';
-    if (error instanceof contracts_1.ZLinkFrameworkException) {
-        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.DeadlineExceeded)
-            return 'timed_out';
-        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.AlreadyExists)
-            return 'conflict';
-        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.InvalidOperation ||
-            error.kind === contracts_1.ZLinkFrameworkErrorKind.Unavailable)
-            return 'fenced';
-    }
-    return 'failed';
-}