@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/actors/actor-handoff.js

@@ -1,21 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkActorHandoffCoordinator = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = void 0;
+exports.ZLinkActorHandoffCoordinator = exports.RELOCATED_REQUEST_OWNED_BY_REQUESTER = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = void 0;
 exports.decodeHandoffPacket = decodeHandoffPacket;
 exports.replayActorHandoffBacklog = replayActorHandoffBacklog;
 const contracts_1 = require("../../contracts");
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const Options_1 = require("../../contracts/Locations/Options");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const runtime_message_1 = require("../backend/runtime-message");
 const message_follow_suppression_registry_1 = require("../foundation/message-follow-suppression-registry");
+const service_stateful_registry_1 = require("../foundation/service-stateful-registry");
+const operation_identity_1 = require("../foundation/operation-identity");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const framework_errors_internal_1 = require("../framework-errors-internal");
+const request_deadline_1 = require("../messaging/request-deadline");
 const routing_id_1 = require("../routing-id");
 const protocol_1 = require("../streams/protocol");
 const actor_message_follow_context_1 = require("./actor-message-follow-context");
 const actor_packet_relay_wire_1 = require("./actor-packet-relay-wire");
 const actor_routed_json_request_1 = require("./actor-routed-json-request");
 exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = Options_1.zlinkDefaultLocationOptions.messageFollowDurationMs;
-const RELOCATION_REPLY_RETENTION_MS = 24 * 60 * 60 * 1_000;
+exports.RELOCATED_REQUEST_OWNED_BY_REQUESTER = Symbol('relocated request owned by requester');
 function requireExactTargetOwnerFence(actorId, fence) {
     if (fence === undefined) {
         throw new Error(`Actor '${actorId}' handoff requires a committed target owner fence.`);
@@ -31,6 +36,8 @@ function requireExactTargetOwnerFence(actorId, fence) {
 class ZLinkActorHandoffCoordinator {
     options;
     active = new Map();
+    // Each route is stored once: Actor -> native fence -> location owner id.
+    // Native ingress has the complete fence except the location owner's text id.
     messageFollowRoutes = new Map();
     messageFollowSuppression = new message_follow_suppression_registry_1.MessageFollowSuppressionRegistry();
     // Relocation preserves ObjectGeneration, so (nodeRid, objectGeneration) alone
@@ -56,7 +63,10 @@ class ZLinkActorHandoffCoordinator {
         this.startHandoff(actorId, oldGeneration, 'provisional');
     }
     startHandoff(actorId, oldGeneration, phase) {
-        if (this.active.has(actorId)) {
+        // A releasing handoff has returned its hold to the Actor FIFO; only its
+        // durable prefix drain remains, and the next hold takes over its ingress.
+        const previous = this.active.get(actorId);
+        if (this.isActive(actorId)) {
             throw new Error(`Actor '${actorId}' already has an active packet handoff.`);
         }
         if (oldGeneration <= 0n) {
@@ -92,6 +102,25 @@ class ZLinkActorHandoffCoordinator {
             nodeGeneration: source.nodeGeneration,
             authorityOwnerGeneration: source.authorityOwnerGeneration
         });
+        const pending = [];
+        if (previous?.prefixRelease !== undefined) {
+            // Only records still in the FIFO belong to the new barrier. Running
+            // records keep their existing terminal; withdrawn records surrender
+            // readiness and move their payload before later ingress can arrive.
+            for (let index = 0; index < previous.pending.length;) {
+                const record = previous.pending[index];
+                if (record.withdraw?.() === true) {
+                    record.withdraw = undefined;
+                    pending.push(record);
+                    previous.pending.splice(index, 1);
+                    previous.prefixRelease.cursor -= 1;
+                    previous.pendingBytes -= packetBytes(record.packet);
+                }
+                else {
+                    index += 1;
+                }
+            }
+        }
         this.active.set(actorId, {
             oldGeneration,
             oldNodeRid: sourceOwner.nodeRid,
@@ -101,25 +130,20 @@ class ZLinkActorHandoffCoordinator {
             phase,
             deferredJoin: phase === 'provisional',
             connectionBoundSealed: false,
-            pending: [],
-            nextIndex: 0,
+            pending,
+            nextIndex: pending.reduce((next, record) => Math.max(next, record.packet.index + 1), 0),
             snapshotIndex: -1,
-            pendingBytes: 0
+            pendingBytes: pending.reduce((bytes, record) => bytes + packetBytes(record.packet), 0)
         });
     }
+    /** True while a hold owns this Actor's ingress, before its release to the Actor FIFO. */
     isActive(actorId) {
-        return this.active.has(actorId);
+        const handoff = this.active.get(actorId);
+        return handoff !== undefined && handoff.phase !== 'releasing';
     }
     isProvisional(actorId) {
         return this.active.get(actorId)?.phase === 'provisional';
     }
-    promoteProvisional(actorId) {
-        const handoff = this.active.get(actorId);
-        if (handoff?.phase !== 'provisional') {
-            throw new Error(`Actor '${actorId}' does not have a provisional packet handoff.`);
-        }
-        handoff.phase = 'relocating';
-    }
     sealConnectionBoundIngress(actorId) {
         const handoff = this.active.get(actorId);
         if (handoff !== undefined)
@@ -166,6 +190,33 @@ class ZLinkActorHandoffCoordinator {
             return { terminal: Promise.resolve() };
         return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
     }
+    /** Installs a restored target's payload in the same owner used by local handoffs. */
+    admitTransferredPrefix(actorId, objectGeneration, packets, queue, preparation, start, onResult) {
+        this.beginProvisional(actorId, objectGeneration);
+        const handoff = this.requireActive(actorId);
+        for (const packet of packets) {
+            handoff.pending.push({
+                packet,
+                origin: 'remote',
+                resolve: (response) => {
+                    if (response !== exports.RELOCATED_REQUEST_OWNED_BY_REQUESTER) {
+                        onResult(packet, { index: packet.index, ok: true, response });
+                    }
+                },
+                reject: (error) => onResult(packet, {
+                    index: packet.index,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    errorKind: error instanceof contracts_1.ZLinkFrameworkException
+                        ? (0, framework_errors_internal_1.internalFrameworkErrorKind)(error)
+                        : undefined
+                })
+            });
+            handoff.nextIndex = Math.max(handoff.nextIndex, packet.index + 1);
+            handoff.pendingBytes += packetBytes(packet);
+        }
+        return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
+    }
     admitHandoffPrefix(actorId, handoff, queue, preparation, start) {
         if (handoff.releaseTask !== undefined) {
             return { terminal: handoff.releaseTask };
@@ -241,6 +292,9 @@ class ZLinkActorHandoffCoordinator {
             prepared = undefined;
         };
         return {
+            onWithdrawable: (withdraw) => {
+                pending.withdraw = withdraw;
+            },
             payloadBytes: packetBytes(pending.packet),
             preparation: {
                 prepare: async (signal) => {
@@ -264,6 +318,9 @@ class ZLinkActorHandoffCoordinator {
                 cancel
             },
             drain: async (replay) => {
+                // The FIFO claim, rather than this prefix's eventual terminal,
+                // ends the record's durable ownership and transfer capability.
+                pending.withdraw = undefined;
                 const admission = prepared === undefined
                     ? undefined
                     : (operation) => prepared.run(operation);
@@ -422,11 +479,23 @@ class ZLinkActorHandoffCoordinator {
             pending.reject?.(error);
         }
     }
-    capture(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, deadlineUnixMs, messageFollowOrigin, provisionalReplay) {
-        const incomingContext = (0, actor_message_follow_context_1.actorMessageFollowContext)(fallbackActorRef);
+    capture(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, deadlineUnixMs, messageFollowOrigin, provisionalReplay, onAdmitted) {
+        let incomingContext = (0, actor_message_follow_context_1.actorMessageFollowContext)(fallbackActorRef);
         const originalDeadlineUnixMs = deadlineUnixMs ?? incomingContext?.deadlineUnixMs ?? packetDeadlineUnixMs(parts);
-        const handoff = this.active.get(actorId);
+        const followRoute = this.findMessageFollowRoute(actorId, incomingContext, messageFollowOrigin?.target);
+        // An exact departed tenure belongs to its committed route, even while the
+        // same Actor incarnation is performing a later Join on this node.
+        const handoff = followRoute === undefined ? this.active.get(actorId) : undefined;
+        if (incomingContext === undefined &&
+            followRoute !== undefined &&
+            messageFollowOrigin?.target !== undefined) {
+            incomingContext = this.createInitialIngressContext(followRoute.sourceOwner, messageFollowOrigin.target.actor.generation, parts, returnResponse, originalDeadlineUnixMs, messageFollowOrigin);
+        }
         if (handoff !== undefined) {
+            if (handoff.phase === 'releasing' &&
+                handoff.prefixRelease !== undefined &&
+                handoff.pending.at(-1)?.withdraw === undefined)
+                return undefined;
             if (parts.length < 2)
                 return Promise.resolve(undefined);
             if (handoff.connectionBoundSealed &&
@@ -442,9 +511,13 @@ class ZLinkActorHandoffCoordinator {
                 handoff.replay = provisionalReplay;
             }
             const context = incomingContext ??
-                this.createInitialIngressContext(handoff.sourceOwner, handoff.oldGeneration, parts, returnResponse, originalDeadlineUnixMs);
+                this.createInitialIngressContext(handoff.sourceOwner, handoff.oldGeneration, parts, returnResponse, originalDeadlineUnixMs, messageFollowOrigin);
             try {
                 this.validateContext(actorId, context, parts, returnResponse, fallbackActorRef);
+                // Accepted handoff retains its original deadline; Message Follow uses a local relay window.
+                if (context.deadlineUnixMs !== undefined && Date.now() >= context.deadlineUnixMs) {
+                    throw actorDeadlineExceeded(actorId);
+                }
             }
             catch (error) {
                 return Promise.reject(error);
@@ -473,8 +546,23 @@ class ZLinkActorHandoffCoordinator {
                 return Promise.resolve(undefined);
             }
             const result = new Promise((resolve, reject) => {
-                const source = this.captureRequestSource(handoff.sourceEvidence, context.replyRouteId);
+                const original = messageFollowOrigin?.requestSource;
+                const originalRidHex = original === undefined ? undefined : (0, routing_id_1.routingIdWireHex)(original.nodeRid);
+                const source = original === undefined
+                    ? this.captureRequestSource(handoff.sourceEvidence, context.replyRouteId)
+                    : {
+                        ownerId: original.ownerId,
+                        ownerLeaseGeneration: original.leaseGeneration.toString(),
+                        nodeRid: String(original.nodeRid),
+                        ...(originalRidHex === undefined ? {} : { nodeRidHex: originalRidHex }),
+                        nodeGeneration: original.nodeGeneration.toString(),
+                        replyRouteId: messageFollowOrigin.originalReplyRouteId.toString()
+                    };
                 const requestPacket = { ...packet, source };
+                if (original !== undefined) {
+                    handoff.pending.push({ packet: requestPacket, origin, resolve, reject });
+                    return;
+                }
                 const route = {
                     actorId,
                     operationId: requestPacket.messageFollowContext.operationId,
@@ -491,7 +579,7 @@ class ZLinkActorHandoffCoordinator {
                     this.replyRoutes.delete(source.replyRouteId);
                     if (!route.delivered)
                         route.reject(new Error('Relocation reply route retention expired.'));
-                }, RELOCATION_REPLY_RETENTION_MS);
+                }, service_stateful_registry_1.RELOCATION_REPLY_RETENTION_MS);
                 route.deadline.unref();
                 this.replyRoutes.set(source.replyRouteId, route);
                 handoff.pending.push({
@@ -502,6 +590,7 @@ class ZLinkActorHandoffCoordinator {
                 });
             });
             (0, application_job_queue_scope_1.releaseApplicationJobPermitForDurableHandoff)();
+            onAdmitted?.();
             if (handoff.prefixRelease !== undefined) {
                 try {
                     this.admitPendingPrefix(actorId, handoff, handoff.prefixRelease);
@@ -514,7 +603,6 @@ class ZLinkActorHandoffCoordinator {
             }
             return result;
         }
-        const followRoute = this.findMessageFollowRoute(actorId, incomingContext);
         const staleGeneration = fallbackActorRef?.objectGeneration;
         if (fallbackActorRef !== undefined &&
             this.options.isCurrentActorRef?.(actorId, fallbackActorRef) === true) {
@@ -535,7 +623,7 @@ class ZLinkActorHandoffCoordinator {
                             return Promise.reject(actorLocationStale(actorId));
                         }
                         const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, incomingContext, messageFollowOrigin);
-                        return this.enqueueMessageFollow(followRoute, actorId, packet);
+                        return this.enqueueMessageFollow(followRoute, actorId, packet, onAdmitted);
                     }
                     this.options.onMarker?.('message_follow_rejected', actorId);
                     return Promise.reject(actorLocationStale(actorId));
@@ -581,23 +669,13 @@ class ZLinkActorHandoffCoordinator {
             return Promise.reject(error);
         }
         const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin);
-        return this.enqueueMessageFollow(followRoute, actorId, packet);
+        return this.enqueueMessageFollow(followRoute, actorId, packet, onAdmitted);
     }
     snapshot(actorId) {
         const handoff = this.requireActive(actorId);
         handoff.snapshotIndex = handoff.pending.length - 1;
         return handoff.pending.map((entry) => entry.packet);
     }
-    snapshotCoreBacklog(actorId) {
-        const handoff = this.requireActive(actorId);
-        let snapshotIndex = -1;
-        while (snapshotIndex + 1 < handoff.pending.length &&
-            handoff.pending[snapshotIndex + 1].packet.returnResponse === false) {
-            snapshotIndex++;
-        }
-        handoff.snapshotIndex = snapshotIndex;
-        return handoff.pending.slice(0, snapshotIndex + 1).map((entry) => entry.packet);
-    }
     /**
      * Freezes the post-capture ingress segment immediately before the caller
      * appends the one-way cutover on the same relocation lane. Records returned
@@ -612,11 +690,22 @@ class ZLinkActorHandoffCoordinator {
     }
     complete(actorId, target, targetActorRef, results, targetOwnerFence) {
         const handoff = this.requireActive(actorId);
-        const committedTargetOwner = requireExactTargetOwnerFence(actorId, targetOwnerFence);
+        const committedTargetOwner = targetOwnerFence === null ? null : requireExactTargetOwnerFence(actorId, targetOwnerFence);
         this.active.delete(actorId);
+        // Location runtime §10: a later owner has no source-local Follow route.
+        if (committedTargetOwner === null) {
+            const unavailable = actorLocationStale(actorId);
+            for (const pending of handoff.pending)
+                this.failReleasedPending(pending, unavailable);
+            return;
+        }
         const byIndex = new Map(results.map((result) => [result.index, result]));
         for (let i = 0; i <= handoff.snapshotIndex; i++) {
             const pending = handoff.pending[i];
+            if (pending.packet.messageFollowOrigin?.requestSource !== undefined) {
+                pending.resolve?.(exports.RELOCATED_REQUEST_OWNED_BY_REQUESTER);
+                continue;
+            }
             if (pending.packet.source !== undefined)
                 continue;
             const result = byIndex.get(pending.packet.index);
@@ -654,15 +743,25 @@ class ZLinkActorHandoffCoordinator {
         }
     }
     messageFollowCount(actorId) {
-        return actorId === undefined
-            ? this.messageFollowRoutes.size
-            : [...this.messageFollowRoutes.values()].filter((route) => route.targetActorRef.actorId === actorId).length;
+        let count = 0;
+        if (actorId === undefined) {
+            for (const id of this.messageFollowRoutes.keys())
+                count += this.messageFollowCount(id);
+        }
+        else {
+            const routes = this.messageFollowRoutes.get(actorId);
+            if (routes !== undefined) {
+                for (const owners of routes.values())
+                    count += owners.size;
+            }
+        }
+        return count;
     }
     pendingCount(actorId) {
         return this.active.get(actorId)?.pending.length ?? 0;
     }
     isKnownStale(actor) {
-        return (this.messageFollowCount(actor.actorId) === 0 &&
+        return (!this.messageFollowRoutes.has(actor.actorId) &&
             this.options.isCurrentActorRef?.(actor.actorId, actor) !== true &&
             this.isKnownStaleRef(actor.actorId, actor));
     }
@@ -781,8 +880,18 @@ class ZLinkActorHandoffCoordinator {
                 refs.set(exactRefKey, departedAuthorityOwnerGeneration);
             }
         }
-        const key = messageFollowRouteKey(actorId, oldGeneration, sourceOwner);
-        const previous = this.messageFollowRoutes.get(key);
+        const key = messageFollowRouteKey(oldGeneration, sourceOwner.nodeRidHex ?? (0, routing_id_1.encodeRoutingIdStorageHex)(sourceOwner.nodeRid), sourceOwner.nodeGeneration, sourceOwner.authorityOwnerGeneration, sourceOwner.ownerLeaseGeneration);
+        let routes = this.messageFollowRoutes.get(actorId);
+        if (routes === undefined) {
+            routes = new Map();
+            this.messageFollowRoutes.set(actorId, routes);
+        }
+        let owners = routes.get(key);
+        if (owners === undefined) {
+            owners = new Map();
+            routes.set(key, owners);
+        }
+        const previous = owners.get(sourceOwner.ownerId);
         if (previous !== undefined)
             clearTimeout(previous.deadline);
         const suppressionFence = actorMessageFollowSuppressionFence(actorId, oldGeneration, sourceOwner, targetOwner);
@@ -812,15 +921,24 @@ class ZLinkActorHandoffCoordinator {
         else {
             this.messageFollowSuppression.replaceRoute(previous.suppressionFence, suppressionFence);
         }
-        this.messageFollowRoutes.set(key, entry);
+        owners.set(sourceOwner.ownerId, entry);
         this.options.onMarker?.('message_follow_registered', actorId, this.messageFollowDurationMs);
         return entry;
     }
     removeMessageFollowRoute(entry) {
-        if (this.messageFollowRoutes.get(entry.key) !== entry)
+        const actorId = entry.targetActorRef.actorId;
+        const routes = this.messageFollowRoutes.get(actorId);
+        if (routes === undefined)
+            return;
+        const owners = routes.get(entry.key);
+        if (owners?.get(entry.sourceOwner.ownerId) !== entry)
             return;
         clearTimeout(entry.deadline);
-        this.messageFollowRoutes.delete(entry.key);
+        owners.delete(entry.sourceOwner.ownerId);
+        if (owners.size === 0)
+            routes.delete(entry.key);
+        if (routes.size === 0)
+            this.messageFollowRoutes.delete(actorId);
         this.messageFollowSuppression.expireRoute(entry.suppressionFence);
         this.pruneStaleTenureRecords(entry);
         this.options.onMarker?.('message_follow_route_removed', entry.targetActorRef.actorId);
@@ -857,19 +975,48 @@ class ZLinkActorHandoffCoordinator {
         if (refs.size === 0)
             this.staleActorRefs.delete(actorId);
     }
-    findMessageFollowRoute(actorId, context) {
-        if (context === undefined)
+    findMessageFollowRoute(actorId, context, nativeTarget) {
+        const routes = this.messageFollowRoutes.get(actorId);
+        if (routes === undefined)
             return undefined;
-        return this.messageFollowRoutes.get(messageFollowRouteKey(actorId, BigInt(context.objectGeneration), context.targetOwner));
+        if (context === undefined) {
+            if (nativeTarget === undefined || nativeTarget.actor.actorId !== actorId)
+                return undefined;
+            return routes
+                .get(messageFollowRouteKey(nativeTarget.actor.generation, (0, routing_id_1.encodeRoutingIdStorageHex)(nativeTarget.actor.nodeRid), nativeTarget.targetNodeGeneration, nativeTarget.authorityOwnerGeneration, nativeTarget.ownerLeaseGeneration))
+                ?.values()
+                .next().value;
+        }
+        const owner = context.targetOwner;
+        return routes
+            .get(messageFollowRouteKey(BigInt(context.objectGeneration), owner.nodeRidHex ?? (0, routing_id_1.encodeRoutingIdStorageHex)(owner.nodeRid), owner.nodeGeneration, owner.authorityOwnerGeneration, owner.ownerLeaseGeneration))
+            ?.get(owner.ownerId);
     }
     hasMessageFollowRouteForStaleRef(actorId, actorRef) {
-        return [...this.messageFollowRoutes.values()].some((route) => route.targetActorRef.actorId === actorId &&
-            actorRef.objectGeneration === route.oldGeneration &&
-            (route.oldNodeRid === undefined ||
-                (0, routing_id_1.routingIdsEqual)(actorRef.nodeRid, (0, actor_message_follow_context_1.messageFollowOwnerNodeRid)(route.sourceOwner))));
+        const routes = this.messageFollowRoutes.get(actorId);
+        if (routes === undefined)
+            return false;
+        for (const owners of routes.values()) {
+            for (const route of owners.values()) {
+                if (actorRef.objectGeneration === route.oldGeneration &&
+                    (route.oldNodeRid === undefined ||
+                        (0, routing_id_1.routingIdsEqual)(actorRef.nodeRid, (0, actor_message_follow_context_1.messageFollowOwnerNodeRid)(route.sourceOwner))))
+                    return true;
+            }
+        }
+        return false;
     }
-    createInitialIngressContext(sourceOwner, generation, parts, request, deadlineUnixMs) {
-        const operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+    createInitialIngressContext(sourceOwner, generation, parts, request, deadlineUnixMs, origin) {
+        let operationId;
+        if (origin === undefined) {
+            operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+        }
+        else {
+            const bytes = Buffer.allocUnsafe(operation_identity_1.OPERATION_IDENTITY_BYTES);
+            bytes.writeBigUInt64BE(BigInt.asUintN(stream_wire_1.UINT64_BYTES * 8, origin.originalOperation.high));
+            bytes.writeBigUInt64BE(BigInt.asUintN(stream_wire_1.UINT64_BYTES * 8, origin.originalOperation.low), stream_wire_1.UINT64_BYTES);
+            operationId = bytes.toString('hex');
+        }
         return Object.freeze({
             operationId,
             objectGeneration: generation.toString(),
@@ -877,7 +1024,11 @@ class ZLinkActorHandoffCoordinator {
             targetOwner: sourceOwner,
             deadlineUnixMs,
             correlationId: request ? (0, actor_message_follow_context_1.createMessageFollowId)() : undefined,
-            replyRouteId: request ? (0, actor_message_follow_context_1.createMessageFollowId)() : undefined,
+            replyRouteId: request
+                ? origin === undefined
+                    ? (0, actor_message_follow_context_1.createMessageFollowId)()
+                    : operationId
+                : undefined,
             request,
             hopCount: 0,
             visitedOwners: Object.freeze([(0, actor_message_follow_context_1.messageFollowOwnerFenceKey)(sourceOwner)]),
@@ -892,9 +1043,6 @@ class ZLinkActorHandoffCoordinator {
         if (context.objectGeneration === '0' || context.request !== request) {
             throw actorLocationStale(actorId);
         }
-        if (context.deadlineUnixMs !== undefined && Date.now() >= context.deadlineUnixMs) {
-            throw actorDeadlineExceeded(actorId);
-        }
         (0, actor_message_follow_context_1.verifyActorMessageFollowPayload)(context, parts);
     }
     isKnownStaleRef(actorId, actor) {
@@ -927,12 +1075,13 @@ class ZLinkActorHandoffCoordinator {
             return BigInt(context.targetOwner.authorityOwnerGeneration);
         }
         const current = this.options.currentOwnerFence?.(actorId);
-        if (current !== undefined && current.nodeRid === String(actor.nodeRid)) {
+        if (current !== undefined &&
+            (0, routing_id_1.routingIdsEqual)((0, actor_message_follow_context_1.messageFollowOwnerNodeRid)(current), actor.nodeRid)) {
             return BigInt(current.authorityOwnerGeneration);
         }
         return undefined;
     }
-    enqueueMessageFollow(entry, actorId, packet) {
+    enqueueMessageFollow(entry, actorId, packet, onAdmitted) {
         const context = packet.messageFollowContext;
         const duplicate = entry.operations.get(context.operationId);
         if (duplicate !== undefined) {
@@ -942,6 +1091,7 @@ class ZLinkActorHandoffCoordinator {
                 this.options.onMarker?.('message_follow_rejected', actorId);
                 return Promise.reject(actorLocationStale(actorId));
             }
+            onAdmitted?.();
             return duplicate.result;
         }
         const bytes = packetBytes(packet);
@@ -963,6 +1113,7 @@ class ZLinkActorHandoffCoordinator {
             replyRouteId: context.replyRouteId,
             result
         });
+        onAdmitted?.();
         entry.tail = entry.tail.then(async () => {
             try {
                 resolve(await this.relayMessageFollow(actorId, entry, packet));
@@ -1008,19 +1159,20 @@ class ZLinkActorHandoffCoordinator {
             await this.messageFollowRelayed(actorId, entry, packet, advanced);
             return undefined;
         }
-        const remainingMs = remainingRequestTime(actorId, packet.messageFollowContext.deadlineUnixMs);
+        const timeoutMs = this.options.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS;
+        const relayDeadlineMs = performance.now() + timeoutMs;
         if (this.options.routedTransport.requestRawToSpot === undefined) {
-            const reply = await awaitBeforeDeadline(this.options.routedTransport.requestToSpot(target, payload, {
+            const reply = await (0, request_deadline_1.waitRequestReply)(this.options.routedTransport.requestToSpot(target, payload, {
                 packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
-                timeoutMs: remainingMs ?? this.options.requestTimeoutMs
-            }), actorId, remainingMs);
+                timeoutMs
+            }), actorId, relayDeadlineMs);
             if (reply.ok === false) {
                 throw actorRelayError(actorId, reply.errorKind, reply.error);
             }
             await this.messageFollowRelayed(actorId, entry, packet, advanced);
             return reply.response;
         }
-        const response = await awaitBeforeDeadline((0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routedTransport, target, payload, { timeoutMs: remainingMs ?? this.options.requestTimeoutMs }, `Actor Message Follow raw request is not available for '${actorId}'.`, (parts) => {
+        const response = await (0, request_deadline_1.waitRequestReply)((0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routedTransport, target, payload, { timeoutMs }, `Actor Message Follow raw request is not available for '${actorId}'.`, (parts) => {
             if (parts.length === 0) {
                 throw new Error(`Actor Message Follow reply was empty for '${actorId}'.`);
             }
@@ -1029,7 +1181,7 @@ class ZLinkActorHandoffCoordinator {
                 throw actorRelayError(actorId, reply.errorKind, reply.error);
             }
             return reply.response;
-        }), actorId, remainingMs);
+        }), actorId, relayDeadlineMs);
         await this.messageFollowRelayed(actorId, entry, packet, advanced);
         return response;
     }
@@ -1177,31 +1329,6 @@ function packetDeadlineUnixMs(parts) {
         return undefined;
     }
 }
-function remainingRequestTime(actorId, deadlineUnixMs) {
-    if (deadlineUnixMs === undefined)
-        return undefined;
-    const remaining = deadlineUnixMs - Date.now();
-    if (remaining <= 0)
-        throw actorDeadlineExceeded(actorId);
-    return Math.max(1, Math.ceil(remaining));
-}
-async function awaitBeforeDeadline(operation, actorId, remainingMs) {
-    if (remainingMs === undefined)
-        return await operation;
-    let timer;
-    try {
-        return await Promise.race([
-            operation,
-            new Promise((_resolve, reject) => {
-                timer = setTimeout(() => reject(actorDeadlineExceeded(actorId)), remainingMs);
-            })
-        ]);
-    }
-    finally {
-        if (timer !== undefined)
-            clearTimeout(timer);
-    }
-}
 async function waitForHandoffReplayStart(start, signal) {
     if (signal.aborted)
         throw signal.reason;
@@ -1217,8 +1344,8 @@ async function waitForHandoffReplayStart(start, signal) {
         signal.removeEventListener('abort', abort);
     }
 }
-function messageFollowRouteKey(actorId, objectGeneration, sourceOwner) {
-    return `${actorId}\u0000${objectGeneration}\u0000${(0, actor_message_follow_context_1.messageFollowOwnerFenceKey)(sourceOwner)}`;
+function messageFollowRouteKey(objectGeneration, nodeRidHex, nodeGeneration, authorityOwnerGeneration, ownerLeaseGeneration) {
+    return `${objectGeneration}\u0000${nodeRidHex}\u0000${nodeGeneration}\u0000${authorityOwnerGeneration}\u0000${ownerLeaseGeneration}`;
 }
 function actorRefKey(nodeRid, generation) {
     return `${(0, routing_id_1.encodeRoutingIdStorageHex)(nodeRid)}\u0000${generation}`;
@@ -1230,7 +1357,7 @@ function requestSourcesEqual(expected, actual) {
     return (expected.replyRouteId === actual.replyRouteId &&
         expected.ownerId === actual.ownerId &&
         expected.ownerLeaseGeneration === actual.ownerLeaseGeneration &&
-        expected.nodeRid === actual.nodeRid &&
+        (0, routing_id_1.routingIdsEqual)((0, routing_id_1.decodeRoutingId)(expected.nodeRid, expected.nodeRidHex), (0, routing_id_1.decodeRoutingId)(actual.nodeRid, actual.nodeRidHex)) &&
         expected.nodeGeneration === actual.nodeGeneration &&
         /^[1-9][0-9]*$/.test(actual.ownerLeaseGeneration) &&
         /^[1-9][0-9]*$/.test(actual.nodeGeneration));

package/dist/runtime/actors/actor-join-relocation.d.ts

@@ -29,8 +29,11 @@ export interface ZLinkActorJoinRelocation {
         };
         /** Target's advertised relocation state chunk cap from the accepted admission reply. */
         readonly advertisedReceiveChunkLimitBytes?: number;
+        readonly deadlineAtMs?: number;
         readonly signal?: AbortSignal;
     }): Promise<{
+        /** Source-only terminal after relay readiness transferred public completion. */
+        readonly sourceCleanup?: () => Promise<void>;
         readonly actorRef: ZLinkBackendActorRef;
         readonly membershipEpoch: bigint;
         readonly spotGeneration: bigint;