@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,1252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorHandoffCoordinator = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = void 0;
+exports.decodeHandoffPacket = decodeHandoffPacket;
+exports.replayActorHandoffBacklog = replayActorHandoffBacklog;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const runtime_message_1 = require("../backend/runtime-message");
+const contracts_1 = require("../../contracts");
+const message_follow_suppression_registry_1 = require("../foundation/message-follow-suppression-registry");
+const routing_id_1 = require("../routing-id");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const protocol_1 = require("../streams/protocol");
+const actor_routed_json_request_1 = require("./actor-routed-json-request");
+const actor_packet_relay_wire_1 = require("./actor-packet-relay-wire");
+const actor_message_follow_context_1 = require("./actor-message-follow-context");
+exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = 30_000;
+const MAX_MESSAGE_FOLLOW_HOPS = 8;
+const RELOCATION_REPLY_RETENTION_MS = 24 * 60 * 60 * 1_000;
+function requireExactTargetOwnerFence(actorId, fence) {
+    if (fence === undefined) {
+        throw new Error(`Actor '${actorId}' handoff requires a committed target owner fence.`);
+    }
+    try {
+        return (0, actor_message_follow_context_1.ownerFence)(fence);
+    }
+    catch {
+        throw new Error(`Actor '${actorId}' handoff requires a committed target owner fence.`);
+    }
+}
+/** Owns packet ordering from relocation start through Message Follow removal. */
+class ZLinkActorHandoffCoordinator {
+    options;
+    active = new Map();
+    messageFollowRoutes = new Map();
+    messageFollowSuppression = new message_follow_suppression_registry_1.MessageFollowSuppressionRegistry();
+    // Relocation preserves ObjectGeneration, so (nodeRid, objectGeneration) alone
+    // also matches a tenure that later RETURNS to a previously-visited node. The
+    // stale-tenure identity therefore keeps the departing tenure's
+    // authorityOwnerGeneration: a ref is stale only while its authority fence is
+    // not strictly newer than the recorded departure. Entries live exactly as
+    // long as their Message Follow route and are pruned with it.
+    staleGenerations = new Map();
+    staleActorRefs = new Map();
+    messageFollowDurationMs;
+    nextReplyRouteId = 0n;
+    replyRoutes = new Map();
+    constructor(options) {
+        this.options = options;
+        this.messageFollowDurationMs = options.messageFollowDurationMs ?? exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS;
+    }
+    begin(actorId, oldGeneration) {
+        this.startHandoff(actorId, oldGeneration, { phase: 'relocating' });
+    }
+    beginProvisional(actorId, operationId, oldGeneration) {
+        this.startHandoff(actorId, oldGeneration, { phase: 'provisional', operationId });
+    }
+    startHandoff(actorId, oldGeneration, transition) {
+        if (this.active.has(actorId)) {
+            throw new Error(`Actor '${actorId}' already has an active packet handoff.`);
+        }
+        if (oldGeneration <= 0n) {
+            throw new Error(`Actor '${actorId}' handoff requires a positive source ObjectGeneration.`);
+        }
+        const source = this.options.requestSource(actorId);
+        if (source.meshName.length === 0 || source.ownerId.length === 0
+            || source.ownerLeaseGeneration <= 0n
+            || source.nodeRid.length === 0 || source.nodeGeneration <= 0n
+            || source.authorityOwnerGeneration <= 0n) {
+            throw new Error(`Actor '${actorId}' handoff requires an exact source owner fence.`);
+        }
+        if (source.objectGeneration !== oldGeneration) {
+            throw new Error(`Actor '${actorId}' handoff source ObjectGeneration changed from ${oldGeneration} to ${source.objectGeneration}.`);
+        }
+        const sourceOwner = (0, actor_message_follow_context_1.ownerFence)({
+            ownerId: source.ownerId,
+            ownerLeaseGeneration: source.ownerLeaseGeneration,
+            nodeRid: source.nodeRid,
+            nodeRidHex: source.nodeRidHex,
+            nodeGeneration: source.nodeGeneration,
+            authorityOwnerGeneration: source.authorityOwnerGeneration
+        });
+        const sourceEvidence = Object.freeze({
+            meshName: source.meshName,
+            objectGeneration: source.objectGeneration,
+            ownerId: source.ownerId,
+            ownerLeaseGeneration: source.ownerLeaseGeneration,
+            nodeRid: sourceOwner.nodeRid,
+            nodeRidHex: sourceOwner.nodeRidHex
+                ?? (0, routing_id_1.encodeRoutingIdStorageHex)(sourceOwner.nodeRid),
+            nodeGeneration: source.nodeGeneration,
+            authorityOwnerGeneration: source.authorityOwnerGeneration
+        });
+        this.active.set(actorId, {
+            oldGeneration,
+            oldNodeRid: sourceOwner.nodeRid,
+            oldNodeRidHex: sourceEvidence.nodeRidHex,
+            sourceEvidence,
+            sourceOwner,
+            phase: transition.phase,
+            ...(transition.phase === 'provisional' ? { operationId: transition.operationId } : {}),
+            connectionBoundSealed: false,
+            pending: [],
+            nextIndex: 0,
+            snapshotIndex: -1,
+            pendingBytes: 0
+        });
+    }
+    isActive(actorId) {
+        return this.active.has(actorId);
+    }
+    isProvisional(actorId) {
+        return this.active.get(actorId)?.phase === 'provisional';
+    }
+    promoteProvisional(actorId, operationId) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined) {
+            throw new Error(`Actor '${actorId}' does not have a provisional packet handoff.`);
+        }
+        if (handoff.phase !== 'provisional' || handoff.operationId !== operationId) {
+            throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+        }
+        handoff.phase = 'relocating';
+    }
+    sealConnectionBoundIngress(actorId) {
+        const handoff = this.active.get(actorId);
+        if (handoff !== undefined)
+            handoff.connectionBoundSealed = true;
+    }
+    activeSourceOwner(actorId) {
+        return this.active.get(actorId)?.sourceOwner;
+    }
+    async releaseDeferred(actorId, operationId, dispatch, admission) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return;
+        if (handoff.operationId !== operationId) {
+            throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+        }
+        await this.releaseHandoff(actorId, handoff, dispatch ?? handoff.replay, admission);
+    }
+    async releaseCanceled(actorId, dispatch, admission) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return;
+        await this.releaseHandoff(actorId, handoff, dispatch, admission);
+    }
+    /**
+     * Restores a deferred hold as one durable FIFO prefix. The returned
+     * admission means every held record is owned by the source/target Actor
+     * queue, not that any handler has run.
+     *
+     * @internal
+     */
+    admitDeferredPrefix(actorId, operationId, queue, preparation, start = Promise.resolve()) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return { terminal: Promise.resolve() };
+        if (handoff.operationId !== operationId) {
+            throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+        }
+        return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
+    }
+    /** @internal Restores a canceled relocation hold as one Actor FIFO prefix. */
+    admitCanceledPrefix(actorId, queue, preparation, start = Promise.resolve()) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return { terminal: Promise.resolve() };
+        return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
+    }
+    admitHandoffPrefix(actorId, handoff, queue, preparation, start) {
+        if (handoff.releaseTask !== undefined) {
+            return { terminal: handoff.releaseTask };
+        }
+        handoff.phase = 'releasing';
+        let resolveTerminal;
+        let rejectTerminal;
+        const terminal = new Promise((resolve, reject) => {
+            resolveTerminal = resolve;
+            rejectTerminal = reject;
+        });
+        const release = {
+            queue,
+            preparation,
+            start,
+            startOpen: false,
+            cursor: 0,
+            inFlight: 0,
+            errors: [],
+            terminal,
+            resolve: resolveTerminal,
+            reject: rejectTerminal
+        };
+        handoff.prefixRelease = release;
+        handoff.releaseTask = terminal;
+        void start.then(() => {
+            release.startOpen = true;
+            this.finishPrefixReleaseIfIdle(actorId, handoff, release);
+        }, error => {
+            release.startOpen = true;
+            if (handoff.pending.length === 0)
+                release.errors.push(error);
+            this.finishPrefixReleaseIfIdle(actorId, handoff, release);
+        });
+        try {
+            this.admitPendingPrefix(actorId, handoff, release);
+        }
+        catch (error) {
+            // The synchronous caller receives the admission error directly. Observe
+            // the shared terminal as well so this path cannot create an unhandled
+            // rejection before the relocation rollback reports the original error.
+            void terminal.catch(() => undefined);
+            this.finishPrefixReleaseIfIdle(actorId, handoff, release);
+            throw error;
+        }
+        return { terminal };
+    }
+    admitPendingPrefix(actorId, handoff, release) {
+        if (release.cursor >= handoff.pending.length)
+            return;
+        const begin = release.cursor;
+        const end = handoff.pending.length;
+        const pending = handoff.pending.slice(begin, end);
+        let admitted;
+        try {
+            admitted = release.queue(pending.map(record => this.createPrefixRecord(record, release)));
+        }
+        catch (error) {
+            this.failUnqueuedPrefix(handoff, release, error);
+            throw error;
+        }
+        release.cursor = end;
+        release.inFlight += 1;
+        void admitted.terminal.then(() => this.completePrefixBatch(actorId, handoff, release), error => {
+            release.errors.push(error);
+            this.completePrefixBatch(actorId, handoff, release);
+        });
+    }
+    createPrefixRecord(pending, release) {
+        let prepared;
+        const cancel = () => {
+            prepared?.cancel();
+            prepared = undefined;
+        };
+        return {
+            payloadBytes: packetBytes(pending.packet),
+            preparation: {
+                prepare: async (signal) => {
+                    try {
+                        await waitForHandoffReplayStart(release.start, signal);
+                        if (release.preparation !== undefined) {
+                            const next = await release.preparation(signal);
+                            if (signal.aborted) {
+                                next.cancel();
+                                throw signal.reason;
+                            }
+                            prepared = next;
+                        }
+                    }
+                    catch (error) {
+                        if (!signal.aborted)
+                            this.failReleasedPending(pending, error);
+                        throw error;
+                    }
+                },
+                cancel
+            },
+            drain: async (replay) => {
+                const admission = prepared === undefined
+                    ? undefined
+                    : (operation) => prepared.run(operation);
+                try {
+                    await this.replayReleasedPending(pending, replay, admission);
+                }
+                finally {
+                    cancel();
+                }
+            }
+        };
+    }
+    completePrefixBatch(actorId, handoff, release) {
+        release.inFlight -= 1;
+        if (release.inFlight === 0 && release.cursor < handoff.pending.length) {
+            try {
+                this.admitPendingPrefix(actorId, handoff, release);
+            }
+            catch {
+                // admitPendingPrefix recorded the exact error and rejected every
+                // request that never reached the Actor FIFO.
+            }
+        }
+        this.finishPrefixReleaseIfIdle(actorId, handoff, release);
+    }
+    finishPrefixReleaseIfIdle(actorId, handoff, release) {
+        if (!release.startOpen
+            || release.inFlight !== 0
+            || release.cursor !== handoff.pending.length)
+            return;
+        if (handoff.prefixRelease === release)
+            handoff.prefixRelease = undefined;
+        if (this.active.get(actorId) === handoff)
+            this.active.delete(actorId);
+        if (release.errors.length === 0) {
+            release.resolve();
+        }
+        else if (release.errors.length === 1) {
+            release.reject(release.errors[0]);
+        }
+        else {
+            release.reject(new AggregateError(release.errors, `Actor '${actorId}' durable prefix replay failed.`));
+        }
+    }
+    failUnqueuedPrefix(handoff, release, error) {
+        release.errors.push(error);
+        for (let index = release.cursor; index < handoff.pending.length; index += 1) {
+            this.failReleasedPending(handoff.pending[index], error);
+        }
+        release.cursor = handoff.pending.length;
+    }
+    async releaseHandoff(actorId, handoff, replay, admission) {
+        if (handoff.releaseTask !== undefined) {
+            await handoff.releaseTask;
+            return;
+        }
+        // Keep the hold installed while each record obtains a fresh application
+        // permit. Arrivals appended during an awaited replay remain behind the
+        // frozen prefix, and the final active-map removal is atomic with observing
+        // the drained tail. A shared task makes duplicate release callbacks join
+        // the same drain instead of replaying a record twice.
+        handoff.phase = 'releasing';
+        const releaseTask = Promise.resolve().then(() => this.replayReleasedBacklog(actorId, handoff, replay, admission));
+        handoff.releaseTask = releaseTask;
+        await releaseTask;
+    }
+    async replayReleasedBacklog(actorId, handoff, replay, admission) {
+        try {
+            if (handoff.pending.length === 0)
+                return;
+            if (replay === undefined) {
+                const error = new Error(`Actor '${actorId}' provisional packet handoff has no replay target.`);
+                for (const pending of handoff.pending) {
+                    if (pending.packet.source !== undefined) {
+                        this.removeReplyRoute(pending.packet.source.replyRouteId);
+                    }
+                    pending.reject?.(error);
+                }
+                throw error;
+            }
+            let cursor = 0;
+            const oneWayErrors = [];
+            while (cursor < handoff.pending.length) {
+                const pending = handoff.pending[cursor++];
+                try {
+                    await this.replayReleasedPending(pending, replay, admission);
+                }
+                catch (error) {
+                    oneWayErrors.push(error);
+                }
+            }
+            if (oneWayErrors.length === 1)
+                throw oneWayErrors[0];
+            if (oneWayErrors.length > 1) {
+                throw new AggregateError(oneWayErrors, `Actor '${actorId}' handoff replay failed.`);
+            }
+        }
+        finally {
+            if (this.active.get(actorId) === handoff) {
+                this.active.delete(actorId);
+            }
+        }
+    }
+    async replayReleasedPending(pending, replay, admission) {
+        const results = await replayActorHandoffBacklog([pending.packet], (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => {
+            const operation = () => replay(parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+            return admission === undefined ? operation() : admission(operation);
+        });
+        if (pending.packet.source !== undefined) {
+            this.removeReplyRoute(pending.packet.source.replyRouteId);
+        }
+        const result = results[0];
+        if (result.ok === true) {
+            pending.resolve?.(result.response);
+            return;
+        }
+        const error = result.errorKind === undefined
+            ? new Error(result.error ?? 'Actor provisional packet replay failed.')
+            : (0, framework_errors_internal_1.createInternalFrameworkException)(result.errorKind, result.error ?? 'Actor provisional packet replay failed.');
+        if (pending.reject !== undefined) {
+            pending.reject(error);
+            return;
+        }
+        throw error;
+    }
+    failReleasedPending(pending, error) {
+        if (pending.packet.source !== undefined) {
+            this.removeReplyRoute(pending.packet.source.replyRouteId);
+        }
+        pending.reject?.(error);
+    }
+    cancel(actorId) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return;
+        if (handoff.phase === 'releasing')
+            return;
+        this.active.delete(actorId);
+        const error = new Error(`Actor '${actorId}' transfer was canceled.`);
+        for (const pending of handoff.pending) {
+            if (pending.packet.source !== undefined) {
+                this.removeReplyRoute(pending.packet.source.replyRouteId);
+            }
+            pending.reject?.(error);
+        }
+    }
+    capture(actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, deadlineUnixMs, messageFollowOrigin, provisionalReplay) {
+        const incomingContext = (0, actor_message_follow_context_1.actorMessageFollowContext)(fallbackActorRef);
+        const originalDeadlineUnixMs = deadlineUnixMs
+            ?? incomingContext?.deadlineUnixMs
+            ?? packetDeadlineUnixMs(parts);
+        const handoff = this.active.get(actorId);
+        if (handoff !== undefined) {
+            if (parts.length < 2)
+                return Promise.resolve(undefined);
+            if (handoff.connectionBoundSealed && !returnResponse && remoteBoundSessionTarget !== undefined) {
+                // The Session route seal already fixed the accepted high water. A
+                // send whose lifetime is only the Session connection can no longer
+                // drain here and must never enter the durable frozen journal, so the
+                // Session owner keeps redelivery ownership of it.
+                return Promise.reject(actorMoving(actorId));
+            }
+            if (handoff.phase === 'provisional' && handoff.replay === undefined) {
+                handoff.replay = provisionalReplay;
+            }
+            const context = incomingContext ?? this.createInitialIngressContext(handoff.sourceOwner, handoff.oldGeneration, parts, returnResponse, originalDeadlineUnixMs);
+            try {
+                this.validateContext(actorId, context, parts, returnResponse, fallbackActorRef);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            const packet = encodePacket(handoff.nextIndex++, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin);
+            handoff.pendingBytes += packetBytes(packet);
+            this.options.onMarker?.('handoff_backlog', actorId, packet.index);
+            if (returnResponse) {
+                this.reportRequestFrame(actorId, packet);
+            }
+            if (!returnResponse) {
+                handoff.pending.push({ packet });
+                // The durable handoff now owns this record. Return the ingress permit
+                // before waiting for a later replay, which must acquire its own fresh
+                // application-job permit.
+                (0, application_job_queue_scope_1.releaseApplicationJobPermitForDurableHandoff)();
+                if (handoff.prefixRelease !== undefined) {
+                    try {
+                        this.admitPendingPrefix(actorId, handoff, handoff.prefixRelease);
+                    }
+                    catch (error) {
+                        this.finishPrefixReleaseIfIdle(actorId, handoff, handoff.prefixRelease);
+                        return Promise.reject(error);
+                    }
+                }
+                return Promise.resolve(undefined);
+            }
+            const result = new Promise((resolve, reject) => {
+                const source = this.captureRequestSource(handoff.sourceEvidence, context.replyRouteId);
+                const requestPacket = { ...packet, source };
+                const route = {
+                    actorId,
+                    operationId: requestPacket.messageFollowContext.operationId,
+                    source,
+                    sourceEvidence: handoff.sourceEvidence,
+                    sourceOwner: handoff.sourceOwner,
+                    resolve,
+                    reject,
+                    delivered: false
+                };
+                route.deadline = setTimeout(() => {
+                    if (this.replyRoutes.get(source.replyRouteId) !== route)
+                        return;
+                    this.replyRoutes.delete(source.replyRouteId);
+                    if (!route.delivered)
+                        route.reject(new Error('Relocation reply route retention expired.'));
+                }, RELOCATION_REPLY_RETENTION_MS);
+                route.deadline.unref();
+                this.replyRoutes.set(source.replyRouteId, route);
+                handoff.pending.push({ packet: requestPacket, resolve, reject });
+            });
+            (0, application_job_queue_scope_1.releaseApplicationJobPermitForDurableHandoff)();
+            if (handoff.prefixRelease !== undefined) {
+                try {
+                    this.admitPendingPrefix(actorId, handoff, handoff.prefixRelease);
+                }
+                catch {
+                    // failUnqueuedPrefix rejected this request with the exact queue
+                    // admission error and finish below closes the shared release.
+                    this.finishPrefixReleaseIfIdle(actorId, handoff, handoff.prefixRelease);
+                }
+            }
+            return result;
+        }
+        const followRoute = this.findMessageFollowRoute(actorId, incomingContext);
+        const staleGeneration = fallbackActorRef?.objectGeneration;
+        if (fallbackActorRef !== undefined
+            && this.options.isCurrentActorRef?.(actorId, fallbackActorRef) === true) {
+            if (incomingContext !== undefined) {
+                this.validateContext(actorId, incomingContext, parts, returnResponse, fallbackActorRef);
+                const currentFence = this.options.currentOwnerFence?.(actorId);
+                if (currentFence !== undefined
+                    && !(0, actor_message_follow_context_1.messageFollowOwnerFencesEqual)(incomingContext.targetOwner, currentFence)) {
+                    // A relocation round trip (A→B→A) keeps the ObjectGeneration, so a
+                    // context resolved against a departed tenure still addresses this
+                    // node while the current tenure holds strictly newer authority
+                    // fences. The departed fence keeps its exact-fence Message Follow
+                    // chain: relay through it instead of a terminal stale verdict.
+                    if (followRoute !== undefined) {
+                        if (performance.now() >= followRoute.expiresAt) {
+                            this.removeMessageFollowRoute(followRoute);
+                            this.options.onMarker?.('message_follow_rejected', actorId);
+                            return Promise.reject(actorLocationStale(actorId));
+                        }
+                        const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, incomingContext, messageFollowOrigin);
+                        return this.enqueueMessageFollow(followRoute, actorId, packet);
+                    }
+                    this.options.onMarker?.('message_follow_rejected', actorId);
+                    return Promise.reject(actorLocationStale(actorId));
+                }
+            }
+            return undefined;
+        }
+        if (incomingContext === undefined
+            && fallbackActorRef !== undefined
+            && this.hasMessageFollowRouteForStaleRef(actorId, fallbackActorRef)) {
+            this.options.onMarker?.('message_follow_rejected', actorId);
+            return Promise.reject(actorLocationStale(actorId));
+        }
+        if (followRoute === undefined
+            &&
+                staleGeneration !== undefined
+            && this.staleGenerations.get(actorId)?.has(staleGeneration) === true
+            && fallbackActorRef !== undefined
+            && this.isKnownStaleRef(actorId, fallbackActorRef)) {
+            this.options.onMarker?.('message_follow_expired', actorId);
+            return Promise.reject(actorLocationStale(actorId));
+        }
+        if (followRoute === undefined) {
+            if (fallbackActorRef !== undefined && this.isKnownStaleRef(actorId, fallbackActorRef)) {
+                this.options.onMarker?.('message_follow_rejected', actorId);
+                return Promise.reject(actorLocationStale(actorId));
+            }
+            return undefined;
+        }
+        if (performance.now() >= followRoute.expiresAt) {
+            this.removeMessageFollowRoute(followRoute);
+            this.options.onMarker?.('message_follow_rejected', actorId);
+            return Promise.reject(actorLocationStale(actorId));
+        }
+        if (incomingContext === undefined) {
+            this.options.onMarker?.('message_follow_rejected', actorId);
+            return Promise.reject(actorLocationStale(actorId));
+        }
+        const context = incomingContext;
+        try {
+            this.validateContext(actorId, context, parts, returnResponse, fallbackActorRef);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin);
+        return this.enqueueMessageFollow(followRoute, actorId, packet);
+    }
+    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
+     * here become part of the transferred prefix and are therefore excluded
+     * from the later Message Follow tail.
+     */
+    takeRelocationRelay(actorId) {
+        const handoff = this.requireActive(actorId);
+        const first = handoff.snapshotIndex + 1;
+        handoff.snapshotIndex = handoff.pending.length - 1;
+        return handoff.pending.slice(first).map(entry => entry.packet);
+    }
+    complete(actorId, target, targetActorRef, results, targetOwnerFence) {
+        const handoff = this.requireActive(actorId);
+        const committedTargetOwner = requireExactTargetOwnerFence(actorId, targetOwnerFence);
+        this.active.delete(actorId);
+        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.source !== undefined)
+                continue;
+            const result = byIndex.get(pending.packet.index);
+            if (result?.ok === false) {
+                pending.reject?.(new Error(result.error ?? 'Actor handoff replay failed.'));
+            }
+            else if (result === undefined && pending.resolve !== undefined) {
+                pending.reject?.(new Error(`Actor handoff reply '${pending.packet.index}' was not returned by the target.`));
+            }
+            else {
+                pending.resolve?.(result?.response);
+            }
+        }
+        const followRoute = this.installMessageFollowRoute(actorId, handoff.oldGeneration, handoff.oldNodeRid, handoff.oldNodeRidHex, handoff.sourceOwner, committedTargetOwner, target, targetActorRef);
+        for (const pending of handoff.pending) {
+            const source = pending.packet.source;
+            if (source === undefined)
+                continue;
+            const route = this.replyRoutes.get(source.replyRouteId);
+            if (route !== undefined) {
+                route.targetNodeRid = target.targetNodeRid;
+                route.targetAuthorityOwnerGeneration = BigInt(committedTargetOwner.authorityOwnerGeneration);
+            }
+        }
+        for (let i = handoff.snapshotIndex + 1; i < handoff.pending.length; i++) {
+            const pending = handoff.pending[i];
+            if (pending.packet.source !== undefined) {
+                this.removeReplyRoute(pending.packet.source.replyRouteId);
+            }
+            void this.enqueueMessageFollow(followRoute, actorId, pending.packet)
+                .then(value => {
+                pending.resolve?.(value);
+            }, error => {
+                pending.reject?.(error);
+            });
+        }
+    }
+    messageFollowCount(actorId) {
+        return actorId === undefined
+            ? this.messageFollowRoutes.size
+            : [...this.messageFollowRoutes.values()]
+                .filter(route => route.targetActorRef.actorId === actorId).length;
+    }
+    pendingCount(actorId) {
+        return this.active.get(actorId)?.pending.length ?? 0;
+    }
+    isKnownStale(actor) {
+        return this.messageFollowCount(actor.actorId) === 0
+            && this.options.isCurrentActorRef?.(actor.actorId, actor) !== true
+            && this.isKnownStaleRef(actor.actorId, actor);
+    }
+    recordStaleFailure(actorId) {
+        this.options.onMarker?.('message_follow_rejected', actorId);
+    }
+    acceptRelocatedTerminal(actorId, packet, result, sourceNodeRid, targetAuthorityOwnerGeneration) {
+        const source = packet.source;
+        if (source === undefined || source.replyRouteId.length === 0)
+            return 'notAcknowledged';
+        const route = this.replyRoutes.get(source.replyRouteId);
+        if (route === undefined
+            || packet.messageFollowContext.objectGeneration
+                !== route.sourceEvidence.objectGeneration.toString()
+            || !(0, actor_message_follow_context_1.messageFollowOwnerFencesEqual)(packet.messageFollowContext.targetOwner, route.sourceOwner)) {
+            return 'notAcknowledged';
+        }
+        return this.acceptRelocatedTerminalRelay(packet.messageFollowContext.operationId, source.replyRouteId, source, result, sourceNodeRid, targetAuthorityOwnerGeneration, actorId).status;
+    }
+    acceptRelocatedTerminalRelay(operationId, replyRouteId, source, result, sourceNodeRid, targetAuthorityOwnerGeneration, actorId) {
+        if (replyRouteId.length === 0)
+            return { status: 'notAcknowledged' };
+        const route = this.replyRoutes.get(replyRouteId);
+        if (route === undefined)
+            return { status: 'notAcknowledged' };
+        const exactSource = source ?? route.source;
+        if (!requestSourcesEqual(route.source, exactSource)
+            || (actorId !== undefined && route.actorId !== actorId)
+            || route.operationId !== operationId
+            || route.targetNodeRid === undefined
+            || !(0, routing_id_1.routingIdsEqual)(route.targetNodeRid, sourceNodeRid)
+            || route.targetAuthorityOwnerGeneration === undefined
+            || (targetAuthorityOwnerGeneration !== undefined
+                && route.targetAuthorityOwnerGeneration !== targetAuthorityOwnerGeneration)) {
+            return { status: 'notAcknowledged' };
+        }
+        try {
+            if (this.options.validateReplySource(route.sourceEvidence) !== true) {
+                return { status: 'notAcknowledged' };
+            }
+        }
+        catch {
+            return { status: 'notAcknowledged' };
+        }
+        if (route.delivered) {
+            return { status: 'alreadyTerminal', source: terminalRequestSource(route) };
+        }
+        route.delivered = true;
+        if (result.ok) {
+            route.resolve(result.response);
+        }
+        else if (result.errorKind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded) {
+            route.reject(actorDeadlineExceeded(route.actorId));
+        }
+        else {
+            route.reject(new Error(result.error ?? 'Actor handoff replay failed.'));
+        }
+        return { status: 'terminalReceived', source: terminalRequestSource(route) };
+    }
+    captureRequestSource(source, replyRouteId) {
+        if (replyRouteId === undefined) {
+            this.nextReplyRouteId += 1n;
+            replyRouteId = this.nextReplyRouteId.toString();
+        }
+        return {
+            ownerId: source.ownerId,
+            ownerLeaseGeneration: source.ownerLeaseGeneration.toString(),
+            nodeRid: source.nodeRid,
+            nodeGeneration: source.nodeGeneration.toString(),
+            replyRouteId
+        };
+    }
+    removeReplyRoute(replyRouteId) {
+        const route = this.replyRoutes.get(replyRouteId);
+        if (route === undefined)
+            return;
+        if (route.deadline !== undefined)
+            clearTimeout(route.deadline);
+        this.replyRoutes.delete(replyRouteId);
+    }
+    reportRequestFrame(actorId, packet) {
+        try {
+            const header = (0, protocol_1.decodeStreamHeader)(Buffer.from(packet.header, 'base64'));
+            this.options.onRequestFrame?.(actorId, packet.index, header.requestSeq, header.flags);
+        }
+        catch {
+            // Evidence collection must not change how a malformed packet is replayed and rejected.
+        }
+    }
+    requireActive(actorId) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            throw new Error(`Actor '${actorId}' does not have an active packet handoff.`);
+        return handoff;
+    }
+    installMessageFollowRoute(actorId, oldGeneration, oldNodeRid, oldNodeRidHex, sourceOwner, targetOwner, target, targetActorRef) {
+        const departedAuthorityOwnerGeneration = BigInt(sourceOwner.authorityOwnerGeneration);
+        let stale = this.staleGenerations.get(actorId);
+        if (stale === undefined) {
+            stale = new Map();
+            this.staleGenerations.set(actorId, stale);
+        }
+        const recordedGeneration = stale.get(oldGeneration);
+        if (recordedGeneration === undefined || recordedGeneration < departedAuthorityOwnerGeneration) {
+            stale.set(oldGeneration, departedAuthorityOwnerGeneration);
+        }
+        if (oldNodeRid !== undefined) {
+            let refs = this.staleActorRefs.get(actorId);
+            if (refs === undefined) {
+                refs = new Map();
+                this.staleActorRefs.set(actorId, refs);
+            }
+            const exactRefKey = actorRefEvidenceKey(oldNodeRid, oldNodeRidHex, oldGeneration);
+            const recordedRef = refs.get(exactRefKey);
+            if (recordedRef === undefined || recordedRef < departedAuthorityOwnerGeneration) {
+                refs.set(exactRefKey, departedAuthorityOwnerGeneration);
+            }
+        }
+        const key = messageFollowRouteKey(actorId, oldGeneration, sourceOwner);
+        const previous = this.messageFollowRoutes.get(key);
+        if (previous !== undefined)
+            clearTimeout(previous.deadline);
+        const suppressionFence = actorMessageFollowSuppressionFence(actorId, oldGeneration, sourceOwner, targetOwner);
+        const expiresAt = performance.now() + this.messageFollowDurationMs;
+        const entry = {
+            key,
+            oldGeneration,
+            oldNodeRid,
+            oldNodeRidHex,
+            sourceOwner,
+            targetOwner,
+            target,
+            targetActorRef,
+            suppressionFence,
+            expiresAt,
+            deadline: undefined,
+            tail: Promise.resolve(),
+            queuedMessages: 0,
+            queuedBytes: 0,
+            operations: new Map()
+        };
+        entry.deadline = setTimeout(() => this.removeMessageFollowRoute(entry), this.messageFollowDurationMs);
+        entry.deadline.unref();
+        if (previous === undefined) {
+            this.messageFollowSuppression.retainRoute(suppressionFence);
+        }
+        else {
+            this.messageFollowSuppression.replaceRoute(previous.suppressionFence, suppressionFence);
+        }
+        this.messageFollowRoutes.set(key, entry);
+        this.options.onMarker?.('message_follow_registered', actorId, this.messageFollowDurationMs);
+        return entry;
+    }
+    removeMessageFollowRoute(entry) {
+        if (this.messageFollowRoutes.get(entry.key) !== entry)
+            return;
+        clearTimeout(entry.deadline);
+        this.messageFollowRoutes.delete(entry.key);
+        this.messageFollowSuppression.expireRoute(entry.suppressionFence);
+        this.pruneStaleTenureRecords(entry);
+        this.options.onMarker?.('message_follow_route_removed', entry.targetActorRef.actorId);
+    }
+    /**
+     * Stale-tenure records must outlive only the Message Follow window of the
+     * departure that wrote them. A later departure of the same
+     * (nodeRid, objectGeneration) re-records a newer authority generation, so a
+     * record is removed only while it still belongs to this route's departure.
+     */
+    pruneStaleTenureRecords(entry) {
+        const actorId = entry.targetActorRef.actorId;
+        const departedAuthorityOwnerGeneration = BigInt(entry.sourceOwner.authorityOwnerGeneration);
+        const stale = this.staleGenerations.get(actorId);
+        if (stale !== undefined) {
+            const recordedGeneration = stale.get(entry.oldGeneration);
+            if (recordedGeneration !== undefined
+                && recordedGeneration <= departedAuthorityOwnerGeneration) {
+                stale.delete(entry.oldGeneration);
+            }
+            if (stale.size === 0)
+                this.staleGenerations.delete(actorId);
+        }
+        if (entry.oldNodeRid === undefined)
+            return;
+        const refs = this.staleActorRefs.get(actorId);
+        if (refs === undefined)
+            return;
+        const refKey = actorRefEvidenceKey(entry.oldNodeRid, entry.oldNodeRidHex, entry.oldGeneration);
+        const recordedRef = refs.get(refKey);
+        if (recordedRef !== undefined && recordedRef <= departedAuthorityOwnerGeneration) {
+            refs.delete(refKey);
+        }
+        if (refs.size === 0)
+            this.staleActorRefs.delete(actorId);
+    }
+    findMessageFollowRoute(actorId, context) {
+        if (context === undefined)
+            return undefined;
+        return this.messageFollowRoutes.get(messageFollowRouteKey(actorId, BigInt(context.objectGeneration), context.targetOwner));
+    }
+    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))));
+    }
+    createInitialIngressContext(sourceOwner, generation, parts, request, deadlineUnixMs) {
+        const operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+        return Object.freeze({
+            operationId,
+            objectGeneration: generation.toString(),
+            sourceOwner,
+            targetOwner: sourceOwner,
+            deadlineUnixMs,
+            correlationId: request ? (0, actor_message_follow_context_1.createMessageFollowId)() : undefined,
+            replyRouteId: request ? (0, actor_message_follow_context_1.createMessageFollowId)() : undefined,
+            request,
+            hopCount: 0,
+            visitedOwners: Object.freeze([(0, actor_message_follow_context_1.messageFollowOwnerFenceKey)(sourceOwner)]),
+            payloadChecksumSha256: (0, actor_message_follow_context_1.actorMessageFollowPayloadChecksum)(parts)
+        });
+    }
+    validateContext(actorId, context, parts, request, actorRef) {
+        if (actorRef !== undefined
+            && context.objectGeneration !== actorRef.objectGeneration.toString()) {
+            throw actorGenerationStale(actorId);
+        }
+        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) {
+        const physicalRefs = this.staleActorRefs.get(actorId);
+        if (physicalRefs !== undefined) {
+            const departedAuthorityOwnerGeneration = physicalRefs.get(actorRefKey(actor.nodeRid, actor.objectGeneration));
+            return departedAuthorityOwnerGeneration !== undefined
+                && !this.isNewerTenureRef(actorId, actor, departedAuthorityOwnerGeneration);
+        }
+        const departedAuthorityOwnerGeneration = this.staleGenerations.get(actorId)?.get(actor.objectGeneration);
+        return departedAuthorityOwnerGeneration !== undefined
+            && !this.isNewerTenureRef(actorId, actor, departedAuthorityOwnerGeneration)
+            && this.options.isStaleActorRef?.(actorId, actor) === true;
+    }
+    /**
+     * The stale record captures the departing tenure's full fence. A ref whose
+     * authority fence is strictly newer than the recorded departure addresses a
+     * returning tenure (A→B→A keeps the ObjectGeneration), never the departed
+     * one, so it must not match the stale record.
+     */
+    isNewerTenureRef(actorId, actor, departedAuthorityOwnerGeneration) {
+        const tenure = this.tenureAuthorityOwnerGeneration(actorId, actor);
+        return tenure !== undefined && tenure > departedAuthorityOwnerGeneration;
+    }
+    tenureAuthorityOwnerGeneration(actorId, actor) {
+        const context = (0, actor_message_follow_context_1.actorMessageFollowContext)(actor);
+        if (context !== undefined) {
+            return BigInt(context.targetOwner.authorityOwnerGeneration);
+        }
+        const current = this.options.currentOwnerFence?.(actorId);
+        if (current !== undefined && current.nodeRid === String(actor.nodeRid)) {
+            return BigInt(current.authorityOwnerGeneration);
+        }
+        return undefined;
+    }
+    enqueueMessageFollow(entry, actorId, packet) {
+        const context = packet.messageFollowContext;
+        const duplicate = entry.operations.get(context.operationId);
+        if (duplicate !== undefined) {
+            if (duplicate.checksum !== context.payloadChecksumSha256
+                || duplicate.request !== context.request
+                || duplicate.replyRouteId !== context.replyRouteId) {
+                this.options.onMarker?.('message_follow_rejected', actorId);
+                return Promise.reject(actorLocationStale(actorId));
+            }
+            return duplicate.result;
+        }
+        const bytes = packetBytes(packet);
+        if (context.hopCount >= MAX_MESSAGE_FOLLOW_HOPS) {
+            this.options.onMarker?.('message_follow_rejected', actorId);
+            return Promise.reject(actorLocationStale(actorId));
+        }
+        entry.queuedMessages++;
+        entry.queuedBytes += bytes;
+        let resolve;
+        let reject;
+        const result = new Promise((done, fail) => {
+            resolve = done;
+            reject = fail;
+        });
+        entry.operations.set(context.operationId, {
+            checksum: context.payloadChecksumSha256,
+            request: context.request,
+            replyRouteId: context.replyRouteId,
+            result
+        });
+        entry.tail = entry.tail.then(async () => {
+            try {
+                resolve(await this.relayMessageFollow(actorId, entry, packet));
+            }
+            catch (error) {
+                this.options.onMarker?.('message_follow_rejected', actorId);
+                reject(error);
+            }
+            finally {
+                entry.queuedMessages--;
+                entry.queuedBytes -= bytes;
+            }
+        });
+        return result;
+    }
+    async relayMessageFollow(actorId, entry, packet) {
+        const { target, targetActorRef } = entry;
+        const context = packet.messageFollowContext;
+        let advanced;
+        try {
+            advanced = (0, actor_message_follow_context_1.advanceActorMessageFollowContext)(context, entry.sourceOwner, entry.targetOwner);
+        }
+        catch {
+            throw actorLocationStale(actorId);
+        }
+        const payload = (0, actor_packet_relay_wire_1.encodeMessageFollowRemoteActorPacketRelayPayload)({
+            actorId,
+            routerChannelId: packet.remoteBoundSessionTarget?.routerChannelId,
+            boundSessionTargetNodeRid: packet.remoteBoundSessionTarget?.targetNodeRid,
+            boundSessionSpotId: packet.remoteBoundSessionTarget?.spotId,
+            header: packet.header,
+            payload: packet.payload,
+            actorNodeRid: String(targetActorRef.nodeRid),
+            actorNodeRidHex: (0, routing_id_1.encodeRoutingIdStorageHex)(targetActorRef.nodeRid),
+            actorGeneration: targetActorRef.objectGeneration.toString(),
+            returnResponse: packet.returnResponse,
+            messageFollowContext: advanced
+        });
+        if (!packet.returnResponse) {
+            await this.options.routedTransport.sendToSpot(target, payload, {
+                packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
+            });
+            await this.messageFollowRelayed(actorId, entry, packet, advanced);
+            return undefined;
+        }
+        const remainingMs = remainingRequestTime(actorId, packet.messageFollowContext.deadlineUnixMs);
+        if (this.options.routedTransport.requestRawToSpot === undefined) {
+            const reply = await awaitBeforeDeadline(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);
+            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) => {
+            if (parts.length === 0) {
+                throw new Error(`Actor Message Follow reply was empty for '${actorId}'.`);
+            }
+            const reply = JSON.parse(parts[0].getString('utf8'));
+            if (reply.ok === false) {
+                throw actorRelayError(actorId, reply.errorKind, reply.error);
+            }
+            return reply.response;
+        }), actorId, remainingMs);
+        await this.messageFollowRelayed(actorId, entry, packet, advanced);
+        return response;
+    }
+    async messageFollowRelayed(actorId, entry, packet, context) {
+        this.options.onMarker?.('message_follow_relay', actorId, undefined, context);
+        if (packet.messageFollowOrigin !== undefined) {
+            const claim = this.messageFollowSuppression.begin(entry.suppressionFence);
+            if (claim === undefined)
+                return;
+            let accepted = false;
+            try {
+                accepted = await this.options.onMessageFollowRelayed?.(actorId, entry.targetActorRef, context, packet.messageFollowOrigin, entry.queuedMessages, entry.queuedBytes) === true;
+            }
+            catch {
+                accepted = false;
+            }
+            if (accepted) {
+                this.messageFollowSuppression.markSent(claim);
+            }
+            else {
+                this.messageFollowSuppression.abort(claim);
+            }
+        }
+    }
+}
+exports.ZLinkActorHandoffCoordinator = ZLinkActorHandoffCoordinator;
+function actorMessageFollowSuppressionFence(actorId, objectGeneration, source, target) {
+    return Object.freeze({
+        objectKind: 'actor',
+        logicalObjectId: actorId,
+        objectGeneration: objectGeneration.toString(),
+        sourceNodeRid: source.nodeRid,
+        ...(source.nodeRidHex === undefined ? {} : { sourceNodeRidHex: source.nodeRidHex }),
+        sourceNodeGeneration: source.nodeGeneration,
+        sourceAuthorityOwnerGeneration: source.authorityOwnerGeneration,
+        sourceOwnerLeaseGeneration: source.ownerLeaseGeneration,
+        targetNodeRid: target.nodeRid,
+        ...(target.nodeRidHex === undefined ? {} : { targetNodeRidHex: target.nodeRidHex }),
+        targetNodeGeneration: target.nodeGeneration,
+        targetAuthorityOwnerGeneration: target.authorityOwnerGeneration,
+        targetOwnerLeaseGeneration: target.ownerLeaseGeneration
+    });
+}
+function decodeHandoffPacket(packet) {
+    return {
+        parts: [
+            runtime_message_1.ZLinkBufferMessage.from(Buffer.from(packet.header, 'base64')),
+            runtime_message_1.ZLinkBufferMessage.from(Buffer.from(packet.payload, 'base64'))
+        ],
+        remoteBoundSessionTarget: packet.remoteBoundSessionTarget === undefined
+            ? undefined
+            : {
+                routerChannelId: packet.remoteBoundSessionTarget.routerChannelId,
+                targetNodeRid: packet.remoteBoundSessionTarget.targetNodeRid,
+                spotId: packet.remoteBoundSessionTarget.spotId,
+                bindingGeneration: optionalBigInt(packet.remoteBoundSessionTarget.bindingGeneration),
+                previousAuthorityOwnerGeneration: optionalBigInt(packet.remoteBoundSessionTarget.previousAuthorityOwnerGeneration),
+                previousOwnerLeaseGeneration: optionalBigInt(packet.remoteBoundSessionTarget.previousOwnerLeaseGeneration),
+                relocationSealId: packet.remoteBoundSessionTarget.relocationSealId
+            },
+        fallbackActorRef: packet.fallbackActorRef === undefined
+            ? undefined
+            : (0, actor_message_follow_context_1.attachActorMessageFollowContext)({
+                actorId: packet.fallbackActorRef.actorId,
+                objectGeneration: BigInt(packet.fallbackActorRef.objectGeneration),
+                meshName: packet.fallbackActorRef.meshName,
+                nodeRid: packet.fallbackActorRef.nodeRid
+            }, packet.messageFollowContext)
+    };
+}
+async function replayActorHandoffBacklog(backlog, dispatch, onEnqueued) {
+    const results = [];
+    for (const packet of backlog) {
+        const decoded = decodeHandoffPacket(packet);
+        try {
+            if (packet.returnResponse
+                && packet.messageFollowContext.deadlineUnixMs !== undefined
+                && Date.now() >= packet.messageFollowContext.deadlineUnixMs) {
+                throw actorDeadlineExceeded(packet.fallbackActorRef?.actorId ?? 'accepted-handoff');
+            }
+            await onEnqueued?.(packet.index);
+            const response = await dispatch(decoded.parts, packet.returnResponse, decoded.remoteBoundSessionTarget, decoded.fallbackActorRef);
+            results.push({ index: packet.index, ok: true, response });
+        }
+        catch (error) {
+            results.push({
+                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
+            });
+        }
+        finally {
+            decoded.parts.forEach((part) => part.close());
+        }
+    }
+    return results;
+}
+function encodePacket(index, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, messageFollowContext, messageFollowOrigin) {
+    if (messageFollowContext === undefined) {
+        throw new Error('Actor handoff packet requires a Message Follow context.');
+    }
+    return {
+        index,
+        header: Buffer.from(parts[0].data()).toString('base64'),
+        payload: Buffer.from(parts[1].data()).toString('base64'),
+        returnResponse,
+        messageFollowContext,
+        ...(messageFollowOrigin === undefined ? {} : { messageFollowOrigin }),
+        remoteBoundSessionTarget: remoteBoundSessionTarget === undefined
+            ? undefined
+            : {
+                routerChannelId: remoteBoundSessionTarget.routerChannelId,
+                targetNodeRid: String(remoteBoundSessionTarget.targetNodeRid),
+                spotId: String(remoteBoundSessionTarget.spotId),
+                bindingGeneration: remoteBoundSessionTarget.bindingGeneration?.toString(),
+                previousAuthorityOwnerGeneration: remoteBoundSessionTarget.previousAuthorityOwnerGeneration?.toString(),
+                previousOwnerLeaseGeneration: remoteBoundSessionTarget.previousOwnerLeaseGeneration?.toString(),
+                relocationSealId: remoteBoundSessionTarget.relocationSealId
+            },
+        fallbackActorRef: fallbackActorRef === undefined
+            ? undefined
+            : {
+                actorId: fallbackActorRef.actorId,
+                objectGeneration: fallbackActorRef.objectGeneration.toString(),
+                meshName: fallbackActorRef.meshName,
+                nodeRid: String(fallbackActorRef.nodeRid)
+            }
+    };
+}
+function optionalBigInt(value) {
+    return value === undefined ? undefined : BigInt(value);
+}
+function packetBytes(packet) {
+    return Buffer.byteLength(packet.header, 'base64') + Buffer.byteLength(packet.payload, 'base64');
+}
+function packetDeadlineUnixMs(parts) {
+    if (parts.length === 0)
+        return undefined;
+    try {
+        return (0, protocol_1.decodeActorRequestDeadlineUnixMs)(parts[0].data());
+    }
+    catch {
+        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;
+    let abort;
+    const aborted = new Promise((_resolve, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+    });
+    try {
+        await Promise.race([start, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+    }
+}
+function messageFollowRouteKey(actorId, objectGeneration, sourceOwner) {
+    return `${actorId}\u0000${objectGeneration}\u0000${(0, actor_message_follow_context_1.messageFollowOwnerFenceKey)(sourceOwner)}`;
+}
+function actorRefKey(nodeRid, generation) {
+    return `${(0, routing_id_1.encodeRoutingIdStorageHex)(nodeRid)}\u0000${generation}`;
+}
+function actorRefEvidenceKey(nodeRid, nodeRidHex, generation) {
+    return `${nodeRidHex ?? (0, routing_id_1.encodeRoutingIdStorageHex)(nodeRid)}\u0000${generation}`;
+}
+function requestSourcesEqual(expected, actual) {
+    return expected.replyRouteId === actual.replyRouteId
+        && expected.ownerId === actual.ownerId
+        && expected.ownerLeaseGeneration === actual.ownerLeaseGeneration
+        && expected.nodeRid === actual.nodeRid
+        && expected.nodeGeneration === actual.nodeGeneration
+        && /^[1-9][0-9]*$/.test(actual.ownerLeaseGeneration)
+        && /^[1-9][0-9]*$/.test(actual.nodeGeneration);
+}
+function terminalRequestSource(route) {
+    return Object.freeze({
+        ...route.source,
+        // The durable packet keeps its legacy text field. The local ACK path can
+        // restore the exact binary RID from the captured owner fence without
+        // changing that packet wire shape.
+        nodeRid: (0, actor_message_follow_context_1.messageFollowOwnerNodeRid)(route.sourceOwner)
+    });
+}
+function actorLocationStale(actorId) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor route '${actorId}' is stale after the Message Follow duration.`);
+}
+function actorGenerationStale(actorId) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorGenerationStale, `Actor route '${actorId}' carries a different object generation.`);
+}
+function actorDeadlineExceeded(actorId) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorId}' exceeded its original deadline during Message Follow.`);
+}
+function actorMoving(actorId) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving, `Actor '${actorId}' bound-session send arrived after its Session route seal.`, true);
+}
+function actorRelayError(actorId, errorKind, error) {
+    const kind = Object.values(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind)
+        .includes(errorKind)
+        ? errorKind
+        : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(kind, String(error ?? `Actor Message Follow relay failed for '${actorId}'.`), kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving
+        || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected);
+}