@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkActorClient = void 0;
+const request_runtime_1 = require("../foundation/request-runtime");
 const node_buffer_1 = require("node:buffer");
 const channel_envelope_1 = require("../channels/channel-envelope");
 const routing_id_1 = require("../routing-id");
@@ -23,11 +24,12 @@ const protocol_1 = require("../streams/protocol");
 const actor_execution_context_1 = require("./actor-execution-context");
 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");
 class DefaultZLinkActorClient {
     options;
+    requests;
     constructor(options) {
         this.options = options;
+        this.requests = options.requests ?? new request_runtime_1.RequestRuntime();
     }
     sendToActor(actorId, message) {
         requireActorId(actorId);
@@ -40,11 +42,13 @@ class DefaultZLinkActorClient {
     async send(actorId, explicitPacketName, message, metadata) {
         const route = await this.resolveActorRoute(actorId);
         const { meshName, actorRef: actor } = route;
-        this.throwIfKnownStale(meshName, actor);
+        this.throwIfKnownStale(route);
         const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Send, undefined, explicitPacketName, message, metadata);
-        const messageFollow = createActorMessageFollowContext(route, parts, false);
-        const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
+        let routeFence;
         try {
+            const messageFollow = createActorMessageFollowContext(route, parts, false);
+            routeFence = actorRouteInvalidationFence(route);
+            const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
             const submissionCopies = (await this.options.transportDeliveryGate?.()?.waitBeforeSubmit(actorId, 'oneWay')) ?? 1;
             const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, false, routedActor);
             if (handoff !== undefined) {
@@ -74,75 +78,76 @@ class DefaultZLinkActorClient {
             return await this.submitActorSend(meshName, toBackendActorRef(actor), parts, route);
         }
         catch (error) {
-            if (isStaleActorError(error)) {
-                this.invalidateActorRoute(actorId);
-                this.options.staleActorRefReporter?.(meshName, actor.actorId);
-                throw actorLocationStale(actor.actorId, error);
-            }
-            throw error;
+            throw this.mapActorFailure(actorId, error, routeFence, meshName);
         }
         finally {
             closeMessages(parts);
         }
     }
-    async request(actorId, explicitPacketName, request, timeoutMs, metadata, signal, waitPolicy = 'async', onAdmitted) {
+    request(actorId, explicitPacketName, request, timeoutMs, metadata, signal, waitPolicy = 'async', onAdmitted) {
         (0, abort_1.throwIfAborted)(signal);
         const sourceSpotId = (0, actor_execution_context_1.currentZLinkActorExecution)()?.spotId ?? (0, execution_1.currentZLinkSpotSerialSourceId)();
         const effectiveTimeoutMs = timeoutMs ?? this.options.defaultRequestTimeoutMs;
-        const deadlineMs = effectiveTimeoutMs === undefined ? undefined : performance.now() + effectiveTimeoutMs;
-        const deadlineUnixMs = effectiveTimeoutMs === undefined ? undefined : Date.now() + effectiveTimeoutMs;
-        const route = await this.resolveActorRoute(actorId, signal, deadlineMs);
-        if (waitPolicy === 'async' &&
-            sourceSpotId !== undefined &&
-            sameSpotRoute(sourceSpotId, route)) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `An Actor request cannot await Actor '${actorId}' on the current Spot while holding its execution claim.`);
-        }
-        const { meshName, actorRef: actor } = route;
-        this.throwIfKnownStale(meshName, actor);
-        const operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
-        const correlationId = (0, actor_message_follow_context_1.createMessageFollowId)();
-        const requestSequence = BigInt(`0x${operationId.slice(16)}`);
-        const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Request, requestSequence === 0n ? 1n : requestSequence, explicitPacketName, request, mergeActorRequestMetadata(metadata, deadlineUnixMs), correlationId);
-        const messageFollow = createActorMessageFollowContext(route, parts, true, deadlineUnixMs, correlationId, operationId);
-        const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
-        try {
-            const delivery = this.options
-                .transportDeliveryGate?.()
-                ?.waitBeforeSubmit(actorId, 'request', signal);
-            const submissionCopies = delivery === undefined
-                ? 1
-                : ((await (0, actor_request_deadline_1.waitActorReply)(delivery, actorId, deadlineMs, signal)) ?? 1);
-            const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs, onAdmitted);
-            if (handoff !== undefined) {
-                const submissions = [handoff];
-                for (let copy = 1; copy < submissionCopies; copy++) {
-                    const duplicate = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs, onAdmitted);
-                    if (duplicate !== undefined)
-                        submissions.push(duplicate);
+        let meshName;
+        let routeFence;
+        return this.requests.prepare(effectiveTimeoutMs, signal, (requestOperation, receiver) => {
+            void (async () => {
+                const deadlineMs = requestOperation.deadlineMs;
+                const deadlineUnixMs = effectiveTimeoutMs === undefined ? undefined : Date.now() + effectiveTimeoutMs;
+                const route = await this.resolveActorRoute(actorId, signal, deadlineMs, requestOperation);
+                if (!requestOperation.isPending())
+                    return;
+                if (waitPolicy === 'async' &&
+                    sourceSpotId !== undefined &&
+                    sameSpotRoute(sourceSpotId, route)) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `An Actor request cannot await Actor '${actorId}' on the current Spot while holding its execution claim.`);
                 }
-                const replies = await (0, actor_request_deadline_1.waitActorReply)(Promise.all(submissions), actorId, deadlineMs, signal);
-                return replies[0];
-            }
-            return await this.submitActorRequest(meshName, toBackendActorRef(actor), parts, (0, actor_request_deadline_1.remainingActorRequestTimeout)(actorId, deadlineMs), signal, route, messageFollow, onAdmitted);
-        }
-        catch (error) {
-            if (isStaleActorError(error)) {
-                this.invalidateActorRoute(actorId);
-                this.options.staleActorRefReporter?.(meshName, actor.actorId);
-                throw actorLocationStale(actor.actorId, error);
-            }
-            throw error;
-        }
-        finally {
-            closeMessages(parts);
-        }
+                const { actorRef: actor } = route;
+                meshName = route.meshName;
+                if (this.options.staleActorRefPredicate?.(meshName, actor) === true) {
+                    routeFence = actorRouteInvalidationFence(route);
+                    throw actorLocationStale(actor.actorId, undefined);
+                }
+                const operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+                const correlationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+                const requestSequence = BigInt(`0x${operationId.slice(16)}`);
+                const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Request, requestSequence === 0n ? 1n : requestSequence, explicitPacketName, request, mergeActorRequestMetadata(metadata, deadlineUnixMs), correlationId);
+                try {
+                    const messageFollow = createActorMessageFollowContext(route, parts, true, deadlineUnixMs, correlationId, operationId);
+                    routeFence = actorRouteInvalidationFence(route);
+                    const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
+                    const delivery = this.options
+                        .transportDeliveryGate?.()
+                        ?.waitBeforeSubmit(actorId, 'request', signal);
+                    const submissionCopies = delivery === undefined
+                        ? 1
+                        : ((await (0, actor_request_deadline_1.waitActorReply)(delivery, actorId, requestOperation)) ?? 1);
+                    const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs, onAdmitted, requestOperation);
+                    if (handoff !== undefined) {
+                        const submissions = [handoff];
+                        for (let copy = 1; copy < submissionCopies; copy++) {
+                            const duplicate = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs, onAdmitted, requestOperation);
+                            if (duplicate !== undefined)
+                                submissions.push(duplicate);
+                        }
+                        const replies = await Promise.all(submissions);
+                        receiver.operationCompleted(requestOperation.id, replies[0], undefined);
+                        return;
+                    }
+                    this.submitActorRequest(meshName, toBackendActorRef(actor), parts, (0, actor_request_deadline_1.remainingActorRequestTimeout)(actorId, deadlineMs), signal, route, messageFollow, onAdmitted, requestOperation, receiver);
+                }
+                finally {
+                    closeMessages(parts);
+                }
+            })().catch((error) => receiver.operationFailed(requestOperation.id, error, undefined));
+        }, (value) => value, (error) => this.mapActorFailure(actorId, error, routeFence, meshName));
     }
-    async resolveActorRoute(actorId, signal, deadlineMs) {
+    async resolveActorRoute(actorId, signal, deadlineMs, requestOperation) {
         const resolver = this.options.locationResolver();
         if (resolver === undefined) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, 'Actor direct messaging requires a Location Store.');
         }
-        const resolution = await resolver.resolveDirectActorRoute(actorId, signal, deadlineMs);
+        const resolution = await resolver.resolveDirectActorRoute(actorId, signal, deadlineMs, requestOperation);
         if (resolution.kind === 'missing') {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor route '${actorId}' was not found.`);
         }
@@ -151,15 +156,21 @@ class DefaultZLinkActorClient {
         }
         return resolution.route;
     }
-    invalidateActorRoute(actorId) {
-        this.options.locationResolver()?.invalidateActorRoute(actorId);
+    mapActorFailure(actorId, error, routeFence, meshName) {
+        if (!isStaleActorError(error))
+            return error;
+        const resolver = this.options.locationResolver();
+        if (routeFence !== undefined && resolver !== undefined)
+            resolver.invalidateActorRouteIfMatches(routeFence);
+        if (meshName !== undefined)
+            this.options.staleActorRefReporter?.(meshName, actorId);
+        return actorLocationStale(actorId, error);
     }
-    throwIfKnownStale(meshName, actor) {
+    throwIfKnownStale(route) {
+        const { meshName, actorRef: actor } = route;
         if (this.options.staleActorRefPredicate?.(meshName, actor) !== true)
             return;
-        this.invalidateActorRoute(actor.actorId);
-        this.options.staleActorRefReporter?.(meshName, actor.actorId);
-        throw actorLocationStale(actor.actorId, undefined);
+        throw this.mapActorFailure(actor.actorId, actorLocationStale(actor.actorId, undefined), actorRouteInvalidationFence(route), meshName);
     }
     createPacketParts(kind, requestSeq, explicitPacketName, message, metadata, correlationId) {
         const packetName = (0, packet_name_1.resolveFrameworkPacketName)(message, explicitPacketName, 'Actor');
@@ -208,7 +219,7 @@ class DefaultZLinkActorClient {
             throw mapSubmitError(error, 'Actor send');
         }
     }
-    async submitActorRequest(meshName, actor, parts, timeoutMs, signal, route, messageFollowContext, onAdmitted) {
+    submitActorRequest(meshName, actor, parts, timeoutMs, signal, route, messageFollowContext, onAdmitted, requestOperation, destination) {
         const node = this.requireNode(meshName);
         if (this.options.routeTransport !== undefined &&
             !(0, routing_id_1.routingIdsEqual)(node.status().routingId, actor.nodeRid)) {
@@ -231,29 +242,46 @@ class DefaultZLinkActorClient {
                 returnResponse: true,
                 messageFollowContext
             });
-            const reply = await (0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routeTransport, remoteActorRouteTarget(route), relay, { timeoutMs, signal, onAdmitted }, `Remote Actor request is not available for '${actor.actorId}'.`, (replyParts) => JSON.parse(replyParts[0]?.getString('utf8') ?? '{}'));
-            if (reply.ok !== true) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(remoteRelayErrorKind(reply.errorKind), typeof reply.error === 'string'
-                    ? reply.error
-                    : `Remote Actor request failed for '${actor.actorId}'.`);
-            }
-            return reply.response;
+            this.options.routeTransport.requestToSpot(remoteActorRouteTarget(route), relay, {
+                packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+                timeoutMs,
+                signal,
+                onAdmitted,
+                requestOperation
+            }, {
+                operationCompleted: (id, value) => {
+                    const reply = value;
+                    if (reply.ok !== true) {
+                        destination.operationFailed(id, (0, framework_errors_internal_1.createInternalFrameworkException)(remoteRelayErrorKind(reply.errorKind), typeof reply.error === 'string'
+                            ? reply.error
+                            : `Remote Actor request failed for '${actor.actorId}'.`), undefined);
+                        return;
+                    }
+                    destination.operationCompleted(id, reply.response, undefined);
+                },
+                operationFailed: (id, error) => destination.operationFailed(id, error, undefined)
+            });
+            return;
         }
         const completions = this.options.completionTableProvider(meshName);
         if (completions === undefined) {
             throw routeNotConnected('Actor request requires a running MeshNode completion table.');
         }
-        const completion = await completions.submit(() => node.requestToActor(actor, toMessageLikeParts(parts), {
+        const packetName = (0, protocol_1.decodeStreamHeader)(parts[0].data()).name;
+        this.requests.run(requestOperation, (receiver) => completions.submit((completion) => node.requestToActor(actor, toMessageLikeParts(parts), {
             flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
             routeFence: nativeActorRouteFence(route, actor),
             timeoutMs,
-            onAdmitted
-        }), signal);
-        if (completion.terminalResult !== runtime_values_1.RequestResult.Ok) {
-            (0, backend_1.closeMeshCompletion)(completion);
-            throw mapRequestResult(completion.terminalResult, completion.failureErrno, 'Actor request');
-        }
-        return decodeActorReply(completion.parts, this.options.messageSerializers, (0, protocol_1.decodeStreamHeader)(parts[0].data()).name);
+            onAdmitted,
+            requestOperation
+        }, completion), signal, requestOperation, receiver), (raw) => {
+            const completion = raw;
+            if (completion.terminalResult !== runtime_values_1.RequestResult.Ok) {
+                (0, backend_1.closeMeshCompletion)(completion);
+                throw mapRequestResult(completion.terminalResult, completion.failureErrno, 'Actor request');
+            }
+            return decodeActorReply(completion.parts, this.options.messageSerializers, packetName);
+        }, request_result_1.identityRequestReply, destination);
     }
     requireNode(meshName) {
         const node = this.options.nodeProvider(meshName);
@@ -272,6 +300,16 @@ function nativeActorRouteFence(route, actor) {
         ownerLeaseGeneration: route.ownerLeaseGeneration
     };
 }
+function actorRouteInvalidationFence(route) {
+    return {
+        actorId: route.actorRef.actorId,
+        objectGeneration: route.actorRef.objectGeneration,
+        targetNodeRid: route.actorRef.nodeRid,
+        targetNodeGeneration: route.ownerNodeGeneration,
+        authorityOwnerGeneration: route.authorityOwnerGeneration,
+        ownerLeaseGeneration: route.ownerLeaseGeneration
+    };
+}
 function remoteActorRouteTarget(route) {
     if (route.enclosingSpotRoute !== undefined) {
         return route.enclosingSpotRoute;
@@ -403,7 +441,7 @@ class DefaultZLinkActorRequestCall {
     yield(signal) {
         this.rejectSelfActorRequest();
         const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
-        const pending = this.execute('yield', signal);
+        const pending = (0, request_result_1.mapZLinkRequestReply)(this.execute('yield', signal));
         return turn.yieldFrameworkPromise(pending);
     }
     execute(waitPolicy, signal, onAdmitted) {

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

@@ -85,7 +85,18 @@ class DefaultZLinkActorContext {
     async [exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME](nodeRid, request, signal) {
         const requestMessage = encodeJoinRequest(request, this.messageSerializers);
         try {
-            return (await this.requireJoinCoordinator().joinEntrySpot(this.requireActor(), this.state, nodeRid, requestMessage, undefined, signal)).accepted;
+            const result = await this.requireJoinCoordinator().joinEntrySpot(this.requireActor(), this.state, nodeRid, requestMessage, undefined, signal);
+            try {
+                if (result.sourceCleanup !== undefined) {
+                    await result.sourceCleanup();
+                    return result.accepted;
+                }
+            }
+            finally {
+                result.reply?.close();
+            }
+            await result.finalizeDeferredJoin?.();
+            return result.accepted;
         }
         finally {
             requestMessage.close();
@@ -172,7 +183,7 @@ class DefaultZLinkActorJoinSpotCall {
                         // handler terminal. Target admission starts before reply encoding,
                         // while completion and finalization remain in execute().
                         this.coordinator.beginDeferredJoin?.(this.actor, this.state);
-                        pendingJoin = this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                        pendingJoin = this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId, deadline.atMs);
                         if (this.turn === undefined) {
                             await pendingJoin.catch(() => undefined);
                         }
@@ -187,7 +198,7 @@ class DefaultZLinkActorJoinSpotCall {
                     let result;
                     try {
                         const pending = pendingJoin ??
-                            this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                            this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId, deadline.atMs);
                         result =
                             this.turn === undefined
                                 ? await pending
@@ -309,7 +320,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
                     this.state.endDeferredJoin();
                     try {
                         this.coordinator.beginDeferredJoin?.(this.actor, this.state);
-                        pendingJoin = this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                        pendingJoin = this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId, deadline.atMs);
                         if (this.turn === undefined) {
                             await pendingJoin.catch(() => undefined);
                         }
@@ -324,7 +335,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
                     let result;
                     try {
                         const pending = pendingJoin ??
-                            this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                            this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId, deadline.atMs);
                         result =
                             this.turn === undefined
                                 ? await pending

package/dist/runtime/actors/actor-execution-context.js

@@ -5,9 +5,9 @@ exports.currentZLinkActorExecution = currentZLinkActorExecution;
 const node_async_hooks_1 = require("node:async_hooks");
 const actorExecutionStorage = new node_async_hooks_1.AsyncLocalStorage();
 /** Runs one Actor handler while retaining its Actor FIFO claim across Yield. */
-async function runZLinkActorExecution(actorId, spotId, operation) {
+function runZLinkActorExecution(actorId, spotId, operation) {
     const context = { actorId, spotId, active: true };
-    return await actorExecutionStorage.run(context, async () => {
+    return actorExecutionStorage.run(context, async () => {
         try {
             return await operation();
         }

package/dist/runtime/actors/actor-handoff.d.ts

@@ -1,3 +1,6 @@
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation } from '../foundation/operation-registry';
+import { inspectRuntime } from '../internal-observation';
 import { type ActorRef, type RoutingId } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
@@ -10,6 +13,7 @@ import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
 export declare const DEFAULT_MESSAGE_FOLLOW_DURATION_MS: number;
 export declare const RELOCATED_REQUEST_OWNED_BY_REQUESTER: unique symbol;
 export interface ZLinkActorHandoffPacket {
+    requestOperation?: PendingOperation<unknown>;
     readonly index: number;
     readonly header: string;
     readonly payload: string;
@@ -84,6 +88,7 @@ interface ReplySourceEvidence {
     readonly authorityOwnerGeneration: bigint;
 }
 export interface ZLinkActorHandoffCoordinatorOptions {
+    readonly requests?: RequestRuntime;
     readonly routedTransport: ZLinkActorRoutedJoinTransport;
     readonly messageFollowDurationMs?: number;
     readonly requestTimeoutMs?: number;
@@ -109,6 +114,12 @@ export interface ZLinkActorHandoffCoordinatorOptions {
 /** Owns packet ordering from relocation start through Message Follow removal. */
 export declare class ZLinkActorHandoffCoordinator {
     private readonly options;
+    private readonly requests;
+    [inspectRuntime](): Readonly<{
+        replyRouteCount: number;
+        hasMessageFollowRoute: (actorId: string, actorRef: ActorRef) => boolean;
+        tenureAuthorityOwnerGeneration: (actorId: string, actorRef: ActorRef) => bigint | undefined;
+    }>;
     private readonly active;
     private readonly messageFollowRoutes;
     private readonly messageFollowSuppression;
@@ -147,7 +158,7 @@ export declare class ZLinkActorHandoffCoordinator {
      */
     failPending(actorId: string, reason: unknown): void;
     cancel(actorId: string): void;
-    capture(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch, onAdmitted?: () => void): Promise<unknown> | undefined;
+    capture(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch, onAdmitted?: () => void, requestOperation?: PendingOperation<unknown>): Promise<unknown> | undefined;
     snapshot(actorId: string): readonly ZLinkActorHandoffPacket[];
     /**
      * Freezes the post-capture ingress segment immediately before the caller

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

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkActorHandoffCoordinator = exports.RELOCATED_REQUEST_OWNED_BY_REQUESTER = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = void 0;
 exports.decodeHandoffPacket = decodeHandoffPacket;
 exports.replayActorHandoffBacklog = replayActorHandoffBacklog;
+const request_runtime_1 = require("../foundation/request-runtime");
+const internal_observation_1 = require("../internal-observation");
 const contracts_1 = require("../../contracts");
 const Registration_1 = require("../../contracts/Configuration/Registration");
 const Options_1 = require("../../contracts/Locations/Options");
@@ -13,12 +15,10 @@ const service_stateful_registry_1 = require("../foundation/service-stateful-regi
 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;
 exports.RELOCATED_REQUEST_OWNED_BY_REQUESTER = Symbol('relocated request owned by requester');
 function requireExactTargetOwnerFence(actorId, fence) {
@@ -35,6 +35,14 @@ function requireExactTargetOwnerFence(actorId, fence) {
 /** Owns packet ordering from relocation start through Message Follow removal. */
 class ZLinkActorHandoffCoordinator {
     options;
+    requests;
+    [internal_observation_1.inspectRuntime]() {
+        return Object.freeze({
+            replyRouteCount: this.replyRoutes.size,
+            hasMessageFollowRoute: (actorId, actorRef) => this.hasMessageFollowRouteForStaleRef(actorId, actorRef),
+            tenureAuthorityOwnerGeneration: (actorId, actorRef) => this.tenureAuthorityOwnerGeneration(actorId, actorRef)
+        });
+    }
     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.
@@ -53,6 +61,7 @@ class ZLinkActorHandoffCoordinator {
     replyRoutes = new Map();
     constructor(options) {
         this.options = options;
+        this.requests = options.requests ?? new request_runtime_1.RequestRuntime();
         this.messageFollowDurationMs =
             options.messageFollowDurationMs ?? exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS;
     }
@@ -479,7 +488,7 @@ class ZLinkActorHandoffCoordinator {
             pending.reject?.(error);
         }
     }
-    capture(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, deadlineUnixMs, messageFollowOrigin, provisionalReplay, onAdmitted) {
+    capture(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, deadlineUnixMs, messageFollowOrigin, provisionalReplay, onAdmitted, requestOperation) {
         let incomingContext = (0, actor_message_follow_context_1.actorMessageFollowContext)(fallbackActorRef);
         const originalDeadlineUnixMs = deadlineUnixMs ?? incomingContext?.deadlineUnixMs ?? packetDeadlineUnixMs(parts);
         const followRoute = this.findMessageFollowRoute(actorId, incomingContext, messageFollowOrigin?.target);
@@ -522,7 +531,7 @@ class ZLinkActorHandoffCoordinator {
             catch (error) {
                 return Promise.reject(error);
             }
-            const packet = encodePacket(handoff.nextIndex++, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin);
+            const packet = encodePacket(handoff.nextIndex++, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin, requestOperation);
             handoff.pendingBytes += packetBytes(packet);
             this.options.onMarker?.('handoff_backlog', actorId, packet.index);
             if (returnResponse) {
@@ -622,7 +631,7 @@ class ZLinkActorHandoffCoordinator {
                             this.options.onMarker?.('message_follow_rejected', actorId);
                             return Promise.reject(actorLocationStale(actorId));
                         }
-                        const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, incomingContext, messageFollowOrigin);
+                        const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, incomingContext, messageFollowOrigin, requestOperation);
                         return this.enqueueMessageFollow(followRoute, actorId, packet, onAdmitted);
                     }
                     this.options.onMarker?.('message_follow_rejected', actorId);
@@ -668,7 +677,7 @@ class ZLinkActorHandoffCoordinator {
         catch (error) {
             return Promise.reject(error);
         }
-        const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin);
+        const packet = encodePacket(0, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, context, messageFollowOrigin, requestOperation);
         return this.enqueueMessageFollow(followRoute, actorId, packet, onAdmitted);
     }
     snapshot(actorId) {
@@ -1113,23 +1122,32 @@ class ZLinkActorHandoffCoordinator {
             replyRouteId: context.replyRouteId,
             result
         });
+        packet.requestOperation?.setFailureDispatcher(reject);
         onAdmitted?.();
         entry.tail = entry.tail.then(async () => {
             try {
-                resolve(await this.relayMessageFollow(actorId, entry, packet));
+                if (packet.requestOperation !== undefined && !packet.requestOperation.isPending()) {
+                    resolve(await packet.requestOperation.promise);
+                }
+                else {
+                    await this.relayMessageFollow(actorId, entry, packet, resolve, reject);
+                }
+                await result;
             }
             catch (error) {
                 this.options.onMarker?.('message_follow_rejected', actorId);
                 reject(error);
             }
             finally {
+                packet.requestOperation?.clearFailureDispatcher(reject);
+                delete packet.requestOperation;
                 entry.queuedMessages--;
                 entry.queuedBytes -= bytes;
             }
         });
         return result;
     }
-    async relayMessageFollow(actorId, entry, packet) {
+    async relayMessageFollow(actorId, entry, packet, resolve, reject) {
         const { target, targetActorRef } = entry;
         const context = packet.messageFollowContext;
         let advanced;
@@ -1157,33 +1175,54 @@ class ZLinkActorHandoffCoordinator {
                 packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
             });
             await this.messageFollowRelayed(actorId, entry, packet, advanced);
-            return undefined;
+            resolve(undefined);
+            return;
         }
         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 (0, request_deadline_1.waitRequestReply)(this.options.routedTransport.requestToSpot(target, payload, {
-                packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
-                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 requestOperation = packet.requestOperation ?? this.requests.begin(timeoutMs);
+        if (packet.requestOperation === undefined) {
+            // The existing business result delivers failures from this entry alias.
+            void requestOperation.promise.catch(() => { });
+            requestOperation.setFailureDispatcher(reject);
+        }
+        if (!requestOperation.isPending()) {
+            resolve(await requestOperation.promise);
+            return;
+        }
+        try {
+            this.options.routedTransport.requestToSpot(target, payload, { packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, timeoutMs, requestOperation }, {
+                operationCompleted: (_id, value) => {
+                    requestOperation.clearFailureDispatcher(reject);
+                    if (!requestOperation.isPending())
+                        return;
+                    void (async () => {
+                        const reply = value;
+                        if (reply.ok === false)
+                            throw actorRelayError(actorId, reply.errorKind, reply.error);
+                        await this.messageFollowRelayed(actorId, entry, packet, advanced);
+                        if (packet.requestOperation === undefined)
+                            requestOperation.complete(reply.response);
+                        resolve(reply.response);
+                    })().catch((error) => {
+                        if (packet.requestOperation === undefined)
+                            requestOperation.fail(error);
+                        reject(error);
+                    });
+                },
+                operationFailed: (_id, error) => {
+                    requestOperation.clearFailureDispatcher(reject);
+                    if (packet.requestOperation === undefined)
+                        requestOperation.fail(error);
+                    reject(error);
+                }
+            });
+        }
+        catch (error) {
+            requestOperation.clearFailureDispatcher(reject);
+            if (packet.requestOperation === undefined)
+                requestOperation.fail(error);
+            throw error;
         }
-        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}'.`);
-            }
-            const reply = JSON.parse(parts[0].getString('utf8'));
-            if (reply.ok === false) {
-                throw actorRelayError(actorId, reply.errorKind, reply.error);
-            }
-            return reply.response;
-        }), actorId, relayDeadlineMs);
-        await this.messageFollowRelayed(actorId, entry, packet, advanced);
-        return response;
     }
     async messageFollowRelayed(actorId, entry, packet, context) {
         this.options.onMarker?.('message_follow_relay', actorId, undefined, context);
@@ -1281,11 +1320,11 @@ async function replayActorHandoffBacklog(backlog, dispatch, onEnqueued) {
     }
     return results;
 }
-function encodePacket(index, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, messageFollowContext, messageFollowOrigin) {
+function encodePacket(index, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, messageFollowContext, messageFollowOrigin, requestOperation) {
     if (messageFollowContext === undefined) {
         throw new Error('Actor handoff packet requires a Message Follow context.');
     }
-    return {
+    const packet = {
         index,
         header: Buffer.from(parts[0].data()).toString('base64'),
         payload: Buffer.from(parts[1].data()).toString('base64'),
@@ -1312,6 +1351,12 @@ function encodePacket(index, parts, returnResponse, remoteBoundSessionTarget, fa
                 nodeRid: String(fallbackActorRef.nodeRid)
             }
     };
+    if (requestOperation !== undefined)
+        Object.defineProperty(packet, 'requestOperation', {
+            value: requestOperation,
+            configurable: true
+        });
+    return packet;
 }
 function optionalBigInt(value) {
     return value === undefined ? undefined : BigInt(value);