@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -2,23 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkActorClient = void 0;
 exports.forwardEncodedActorPacket = forwardEncodedActorPacket;
-const framework_errors_internal_1 = require("../framework-errors-internal");
-const runtime_message_1 = require("../backend/runtime-message");
-const runtime_values_1 = require("../backend/runtime-values");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const contracts_1 = require("../../contracts");
-const contracts_2 = require("../../contracts");
-const submission_result_1 = require("../messaging/submission-result");
-const backend_1 = require("../backend");
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const abort_1 = require("../abort");
-const payload_codec_1 = require("../messaging/payload-codec");
+const backend_1 = require("../backend");
+const runtime_message_1 = require("../backend/runtime-message");
+const runtime_values_1 = require("../backend/runtime-values");
+const configuration_1 = require("../configuration");
+const execution_1 = require("../execution");
+const actor_request_deadline_1 = require("./actor-request-deadline");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const packet_name_1 = require("../messaging/packet-name");
+const payload_codec_1 = require("../messaging/payload-codec");
+const submission_result_1 = require("../messaging/submission-result");
 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");
-const actor_message_follow_context_1 = require("./actor-message-follow-context");
-const execution_1 = require("../execution");
-const configuration_1 = require("../configuration");
-const actor_execution_context_1 = require("./actor-execution-context");
 class DefaultZLinkActorClient {
     options;
     constructor(options) {
@@ -53,7 +55,7 @@ class DefaultZLinkActorClient {
                         submissions.push(duplicate);
                 }
                 await (0, abort_1.awaitWithAbort)(Promise.all(submissions), signal);
-                return submitted();
+                return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
             }
             const node = this.requireNode(meshName);
             if (this.options.routeTransport !== undefined &&
@@ -66,8 +68,8 @@ class DefaultZLinkActorClient {
                     actorRef: actor,
                     returnResponse: false,
                     messageFollowContext: messageFollow
-                }), { packetName: '__zlink.actor.packet.relay' });
-                return submitted();
+                }), { packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET });
+                return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
             }
             return await this.submitActorSend(meshName, toBackendActorRef(actor), parts);
         }
@@ -89,7 +91,7 @@ class DefaultZLinkActorClient {
         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);
+        const route = await this.resolveActorRoute(actorId, signal, deadlineMs);
         if (waitPolicy === 'async' &&
             sourceSpotId !== undefined &&
             sameSpotRoute(sourceSpotId, route)) {
@@ -104,9 +106,12 @@ class DefaultZLinkActorClient {
         const messageFollow = createActorMessageFollowContext(route, parts, true, deadlineUnixMs, correlationId, operationId);
         const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
         try {
-            const submissionCopies = (await this.options
+            const delivery = this.options
                 .transportDeliveryGate?.()
-                ?.waitBeforeSubmit(actorId, 'request', signal)) ?? 1;
+                ?.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);
             if (handoff !== undefined) {
                 const submissions = [handoff];
@@ -115,10 +120,10 @@ class DefaultZLinkActorClient {
                     if (duplicate !== undefined)
                         submissions.push(duplicate);
                 }
-                const replies = await waitHandoffReply(Promise.all(submissions), remainingActorRequestTimeout(actorId, deadlineMs));
+                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, remainingActorRequestTimeout(actorId, deadlineMs), signal, route, messageFollow);
+            return await this.submitActorRequest(meshName, toBackendActorRef(actor), parts, (0, actor_request_deadline_1.remainingActorRequestTimeout)(actorId, deadlineMs), signal, route, messageFollow);
         }
         catch (error) {
             if (isStaleActorError(error)) {
@@ -132,12 +137,12 @@ class DefaultZLinkActorClient {
             closeMessages(parts);
         }
     }
-    async resolveActorRoute(actorId, signal) {
+    async resolveActorRoute(actorId, signal, deadlineMs) {
         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);
+        const resolution = await resolver.resolveDirectActorRoute(actorId, signal, deadlineMs);
         if (resolution.kind === 'missing') {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor route '${actorId}' was not found.`);
         }
@@ -191,17 +196,15 @@ class DefaultZLinkActorClient {
     async submitActorSend(meshName, actor, parts) {
         const node = this.requireNode(meshName);
         try {
-            return mapSubmitResult(await node.sendToActor(actor, toMessageLikeParts(parts), {
+            return (0, submission_result_1.classifySubmitResult)(await node.sendToActor(actor, toMessageLikeParts(parts), {
                 flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE
             }), 'Actor send');
         }
         catch (error) {
             if ((0, runtime_values_1.isZLinkBackendResultError)(error)) {
-                return mapSubmitResult(error.result, 'Actor send');
+                return (0, submission_result_1.classifySubmitResult)(error.result, 'Actor send', error.phase);
             }
-            throw (0, runtime_values_1.isZLinkBackendResultError)(error)
-                ? mapRequestError(error, 'Actor send')
-                : mapSubmitError(error, 'Actor send');
+            throw mapSubmitError(error, 'Actor send');
         }
     }
     async submitActorRequest(meshName, actor, parts, timeoutMs, signal, route, messageFollowContext) {
@@ -296,36 +299,10 @@ function remoteRelayErrorKind(value) {
         ? value
         : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
 }
-function remainingActorRequestTimeout(actorId, deadlineMs) {
-    if (deadlineMs === undefined)
-        return undefined;
-    const remaining = deadlineMs - performance.now();
-    if (remaining <= 0) {
-        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorId}' exceeded its deadline before submission.`);
-    }
-    return Math.max(1, Math.ceil(remaining));
-}
 function requireActorId(actorId) {
     const byteLength = Buffer.byteLength(actorId, 'utf8');
-    if (byteLength < 1 || byteLength > 255) {
-        throw new configuration_1.ZLinkConfigurationException('Actor ID must contain 1..255 UTF-8 bytes.');
-    }
-}
-async function waitHandoffReply(reply, timeoutMs) {
-    if (timeoutMs === undefined)
-        return (await reply);
-    let deadline;
-    try {
-        return await Promise.race([
-            reply,
-            new Promise((_resolve, reject) => {
-                deadline = setTimeout(() => reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Actor handoff request timed out.', true)), timeoutMs);
-            })
-        ]);
-    }
-    finally {
-        if (deadline !== undefined)
-            clearTimeout(deadline);
+    if (byteLength < 1 || byteLength > CoreTypes_1.ZLINK_MAX_ACTOR_ID_BYTES) {
+        throw new configuration_1.ZLinkConfigurationException(`Actor ID must contain 1..${CoreTypes_1.ZLINK_MAX_ACTOR_ID_BYTES} UTF-8 bytes.`);
     }
 }
 async function forwardEncodedActorPacket(node, completions, actor, header, payload, returnResponse, timeoutMs, serializers) {
@@ -493,97 +470,20 @@ function decodeActorReplyPayload(kind, payload, serializers, packetName) {
         const wireKind = error.kind;
         const publicKind = typeof wireKind === 'number' &&
             Number.isInteger(wireKind) &&
-            wireKind >= contracts_2.ZLinkFrameworkErrorKind.NotFound &&
-            wireKind <= contracts_2.ZLinkFrameworkErrorKind.InternalFailure
+            wireKind >= contracts_1.ZLinkFrameworkErrorKind.NotFound &&
+            wireKind <= contracts_1.ZLinkFrameworkErrorKind.InternalFailure
             ? wireKind
-            : contracts_2.ZLinkFrameworkErrorKind.InternalFailure;
-        throw new contracts_2.ZLinkFrameworkException(publicKind, error.message ?? 'Actor request failed.');
+            : contracts_1.ZLinkFrameworkErrorKind.InternalFailure;
+        throw new contracts_1.ZLinkFrameworkException(publicKind, error.message ?? 'Actor request failed.');
     }
-    return (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload, serializers, undefined, 'application/json', packetName, 'reply');
+    return (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload, serializers, undefined, stream_wire_1.ZlinkStreamContentType.Json, packetName, 'reply');
 }
 function mapSubmitError(error, operationName) {
-    if (error instanceof contracts_2.ZLinkFrameworkException) {
+    if (error instanceof contracts_1.ZLinkFrameworkException) {
         return error;
     }
-    if ((0, runtime_values_1.isZLinkBackendResultError)(error)) {
-        switch (error.result) {
-            case runtime_values_1.SubmitResult.NotConnected:
-                return routeNotConnected(`${operationName} failed because the target route is not connected.`, error);
-            case runtime_values_1.SubmitResult.NotFound:
-                return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `${operationName} failed because the actor route was not found.`, false, error);
-            default:
-                return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, `${operationName} failed with submit result ${error.result}.`, false, error);
-        }
-    }
     return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${operationName} failed before a reply was received.`, true, error);
 }
-function mapSubmitResult(result, operationName) {
-    switch (result) {
-        case runtime_values_1.SubmitResult.Ok:
-            return submitted();
-        case runtime_values_1.SubmitResult.Backpressured:
-        case runtime_values_1.SubmitResult.NotAdmitted:
-            return { status: submission_result_1.ZLinkSubmitStatus.Backpressured };
-        case runtime_values_1.SubmitResult.NotConnected:
-            return { status: submission_result_1.ZLinkSubmitStatus.RouteNotConnected };
-        case runtime_values_1.SubmitResult.NotFound:
-            return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
-        case runtime_values_1.SubmitResult.Terminated:
-            return { status: submission_result_1.ZLinkSubmitStatus.Shutdown };
-        default:
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, `${operationName} failed with submit result ${result}.`);
-    }
-}
-function submitted() {
-    return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
-}
-//  Ownership-aware Actor remote-reply translator (spec 32:81-118, 99-103):
-//  the reply comes from a remote target, so a fine framework failure code
-//  refines the coarse terminal, and a terminal-only conflict/busy is the
-//  target's owner/queue state (retryable stale/Unavailable), never a
-//  source-owned queue exhaustion. Backpressure never appears on this reply
-//  path. Internal kinds are preserved so the stale-actor re-resolve retry
-//  (isStaleActorError) keeps working.
-function actorFailureCodeKind(failureErrno) {
-    switch (failureErrno) {
-        case 3:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorAlreadyExists;
-        case 4:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorTypeMismatch;
-        case 7:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotTypeMismatch;
-        case 8:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound;
-        case 9:
-        case 14:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound;
-        case 12:
-        case 16:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError;
-        //  routeNotConnected(13) and a remote worker queue full(18) are Unavailable.
-        case 13:
-        case 18:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected;
-        case 15:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected;
-        case 19:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerTimedOut;
-        case 17:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
-        case 20:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerFailed;
-        case 21:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale;
-        case 33:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorGenerationStale;
-        case 34:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving;
-        case 35:
-            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RelocationDataLost;
-        default:
-            return undefined;
-    }
-}
 function actorTerminalKind(result) {
     switch (result) {
         case runtime_values_1.RequestResult.TimedOut:
@@ -599,7 +499,7 @@ function actorTerminalKind(result) {
         case runtime_values_1.RequestResult.NotConnected:
             return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected;
         //  A terminal-only conflict/busy on a remote actor reply is the target's
-        //  stale/owner state: retryable ActorLocationStale (-> Unavailable).
+        //  stale/owner state: ActorLocationStale (Unavailable).
         case runtime_values_1.RequestResult.Conflict:
         case runtime_values_1.RequestResult.Busy:
             return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale;
@@ -607,19 +507,18 @@ function actorTerminalKind(result) {
             return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
     }
 }
+// The shared table preserves Actor fine kinds; without a recognized fine code,
+// the remote owner/queue terminal supplies the classification.
 function mapRequestResult(result, failureErrno, operationName) {
-    const kind = actorFailureCodeKind(failureErrno) ?? actorTerminalKind(result);
+    const kind = (0, framework_errors_internal_1.internalFrameworkErrorKindFromWireFailureCode)(failureErrno) ?? actorTerminalKind(result);
     return (0, framework_errors_internal_1.createInternalFrameworkException)(kind, `${operationName} failed with request result ${result}` +
         (failureErrno !== 0 ? ` (failure code ${failureErrno}).` : '.'));
 }
-function mapRequestError(error, operationName) {
-    return mapRequestResult(error.result, error.failureErrno ?? 0, operationName);
-}
 function routeNotConnected(message, cause) {
     return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, message, true, cause);
 }
 function isStaleActorError(error) {
-    return (error instanceof contracts_2.ZLinkFrameworkException &&
+    return (error instanceof contracts_1.ZLinkFrameworkException &&
         (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
 }
 function actorLocationStale(actorId, cause) {

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

@@ -1,9 +1,7 @@
-import type { RoutingId, SpotId, ZLinkActorContext, ZLinkActorJoinEntrySpotCall, ZLinkActorJoinSpotCall, ZLinkBoundSession } from '../../contracts';
-import { type ZLinkMessageSerializer } from '../../contracts';
-import { ZLinkActorRuntimeState } from './actor-runtime-state';
-import type { ZLinkActorBoundSessionFactory, ZLinkActorJoinCoordinator } from './actor-runtime-contracts';
-import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
+import { type RoutingId, type SpotId, type ZLinkActorContext, type ZLinkActorJoinEntrySpotCall, type ZLinkActorJoinSpotCall, type ZLinkBoundSession, type ZLinkMessageSerializer } from '../../contracts';
 import { ZLINK_ACTOR_LIFECYCLE_SNAPSHOT, type ZLinkActorLifecycleSnapshotSource } from './actor-lifecycle-snapshot';
+import type { ZLinkActorBoundSessionFactory, ZLinkActorJoinCoordinator, ZLinkActorManagerOptions } from './actor-runtime-contracts';
+import { ZLinkActorRuntimeState } from './actor-runtime-state';
 export declare const ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME: unique symbol;
 export declare class DefaultZLinkActorContext implements ZLinkActorContext {
     private readonly state;

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

@@ -1,18 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkActorContext = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const runtime_message_1 = require("../backend/runtime-message");
 const configuration_1 = require("../configuration");
-const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
-const payload_codec_1 = require("../messaging/payload-codec");
-const actor_runtime_state_1 = require("./actor-runtime-state");
-const actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
+const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
+const execution_1 = require("../execution");
 const operation_identity_1 = require("../foundation/operation-identity");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const payload_codec_1 = require("../messaging/payload-codec");
 const actor_join_deferred_scope_1 = require("./actor-join-deferred-scope");
-const execution_1 = require("../execution");
-const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
+const actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
+const actor_runtime_state_1 = require("./actor-runtime-state");
+const DEFAULT_ACTOR_JOIN_TIMEOUT_MS = 5_000;
+const MAX_ACTOR_JOIN_TIMEOUT_MS = 2_147_483_647;
 exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = Symbol('zlink.actor.join-entry-spot-runtime');
 class DefaultZLinkActorContext {
     state;
@@ -105,7 +107,7 @@ class DefaultZLinkActorJoinSpotCall {
     spotId;
     request;
     messageSerializers;
-    timeoutMs = 5_000;
+    timeoutMs = DEFAULT_ACTOR_JOIN_TIMEOUT_MS;
     deferred = false;
     turn = (0, execution_1.captureZLinkSpotSerialTurn)();
     constructor(state, actor, coordinator, spotId, request, messageSerializers) {
@@ -146,7 +148,7 @@ class DefaultZLinkActorJoinSpotCall {
             discarded = true;
             this.state.endDeferredJoin();
             try {
-                await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId);
+                await this.coordinator.abortDeferredJoin?.(this.actor, this.state);
             }
             finally {
                 deadline.close();
@@ -164,7 +166,7 @@ class DefaultZLinkActorJoinSpotCall {
                         // The provisional ingress fence is installed only after the
                         // handler terminal. Target admission starts before reply encoding,
                         // while completion and finalization remain in execute().
-                        this.coordinator.beginDeferredJoin?.(this.actor, this.state, operationId);
+                        this.coordinator.beginDeferredJoin?.(this.actor, this.state);
                         pendingJoin = this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
                         if (this.turn === undefined) {
                             await pendingJoin.catch(() => undefined);
@@ -189,7 +191,7 @@ class DefaultZLinkActorJoinSpotCall {
                     catch (error) {
                         this.state.endDeferredJoin();
                         await this.coordinator
-                            .abortDeferredJoin?.(this.actor, this.state, operationId)
+                            .abortDeferredJoin?.(this.actor, this.state)
                             .catch(() => undefined);
                         await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
                         return;
@@ -231,7 +233,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
     coordinator;
     request;
     messageSerializers;
-    timeoutMs = 5_000;
+    timeoutMs = DEFAULT_ACTOR_JOIN_TIMEOUT_MS;
     deferred = false;
     turn = (0, execution_1.captureZLinkSpotSerialTurn)();
     constructor(state, actor, coordinator, request, messageSerializers) {
@@ -271,7 +273,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
             discarded = true;
             this.state.endDeferredJoin();
             try {
-                await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId);
+                await this.coordinator.abortDeferredJoin?.(this.actor, this.state);
             }
             finally {
                 deadline.close();
@@ -286,7 +288,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
                     prepared = true;
                     this.state.endDeferredJoin();
                     try {
-                        this.coordinator.beginDeferredJoin?.(this.actor, this.state, operationId);
+                        this.coordinator.beginDeferredJoin?.(this.actor, this.state);
                         pendingJoin = this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
                         if (this.turn === undefined) {
                             await pendingJoin.catch(() => undefined);
@@ -311,7 +313,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
                     catch (error) {
                         this.state.endDeferredJoin();
                         await this.coordinator
-                            .abortDeferredJoin?.(this.actor, this.state, operationId)
+                            .abortDeferredJoin?.(this.actor, this.state)
                             .catch(() => undefined);
                         await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
                         return;
@@ -375,8 +377,8 @@ function encodeJoinRequest(request, serializers) {
 }
 function validateJoinTimeout(timeoutMs) {
     const rounded = Math.ceil(timeoutMs);
-    if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > 2_147_483_647) {
-        throw new configuration_1.ZLinkConfigurationException('Actor join timeout must be a finite value from 1 through 2147483647 milliseconds.');
+    if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > MAX_ACTOR_JOIN_TIMEOUT_MS) {
+        throw new configuration_1.ZLinkConfigurationException(`Actor join timeout must be a finite value from 1 through ${MAX_ACTOR_JOIN_TIMEOUT_MS} milliseconds.`);
     }
     return rounded;
 }

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

@@ -1,12 +1,12 @@
-import { ZLinkFrameworkInternalErrorKind } from '../framework-errors-internal';
-import type { ActorRef, RoutingId } from '../../contracts';
+import { type ActorRef, type RoutingId } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import { ZLinkFrameworkInternalErrorKind } from '../framework-errors-internal';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import { type ZLinkActorMessageFollowContext, type ZLinkActorMessageFollowOwnerFence } from './actor-message-follow-context';
 import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
 import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
-import { type ZLinkActorMessageFollowContext, type ZLinkActorMessageFollowOwnerFence } from './actor-message-follow-context';
-export declare const DEFAULT_MESSAGE_FOLLOW_DURATION_MS = 30000;
+export declare const DEFAULT_MESSAGE_FOLLOW_DURATION_MS: number;
 export interface ZLinkActorHandoffPacket {
     readonly index: number;
     readonly header: string;
@@ -115,14 +115,14 @@ export declare class ZLinkActorHandoffCoordinator {
     private readonly replyRoutes;
     constructor(options: ZLinkActorHandoffCoordinatorOptions);
     begin(actorId: string, oldGeneration: bigint): void;
-    beginProvisional(actorId: string, operationId: string, oldGeneration: bigint): void;
+    beginProvisional(actorId: string, oldGeneration: bigint): void;
     private startHandoff;
     isActive(actorId: string): boolean;
     isProvisional(actorId: string): boolean;
-    promoteProvisional(actorId: string, operationId: string): void;
+    promoteProvisional(actorId: string): void;
     sealConnectionBoundIngress(actorId: string): void;
     activeSourceOwner(actorId: string): ZLinkActorMessageFollowOwnerFence | undefined;
-    releaseDeferred(actorId: string, operationId: string, dispatch?: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
+    releaseDeferred(actorId: string, dispatch?: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
     releaseCanceled(actorId: string, dispatch: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
     private admitHandoffPrefix;
     private admitPendingPrefix;
@@ -134,6 +134,12 @@ export declare class ZLinkActorHandoffCoordinator {
     private replayReleasedBacklog;
     private replayReleasedPending;
     private failReleasedPending;
+    /**
+     * Expired-owner terminal of a relocation (spec 28 §4.4): every pending
+     * record without a terminal fails once with `reason`. The handoff stays
+     * active, so the source never dispatches the Actor again.
+     */
+    failPending(actorId: string, reason: unknown): void;
     cancel(actorId: string): void;
     capture(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch): Promise<unknown> | undefined;
     snapshot(actorId: string): readonly ZLinkActorHandoffPacket[];

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

@@ -3,18 +3,18 @@ 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 Options_1 = require("../../contracts/Locations/Options");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const runtime_message_1 = require("../backend/runtime-message");
 const message_follow_suppression_registry_1 = require("../foundation/message-follow-suppression-registry");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 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 actor_packet_relay_wire_1 = require("./actor-packet-relay-wire");
+const actor_routed_json_request_1 = require("./actor-routed-json-request");
+exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = Options_1.zlinkDefaultLocationOptions.messageFollowDurationMs;
 const RELOCATION_REPLY_RETENTION_MS = 24 * 60 * 60 * 1_000;
 function requireExactTargetOwnerFence(actorId, fence) {
     if (fence === undefined) {
@@ -50,12 +50,12 @@ class ZLinkActorHandoffCoordinator {
             options.messageFollowDurationMs ?? exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS;
     }
     begin(actorId, oldGeneration) {
-        this.startHandoff(actorId, oldGeneration, { phase: 'relocating' });
+        this.startHandoff(actorId, oldGeneration, 'relocating');
     }
-    beginProvisional(actorId, operationId, oldGeneration) {
-        this.startHandoff(actorId, oldGeneration, { phase: 'provisional', operationId });
+    beginProvisional(actorId, oldGeneration) {
+        this.startHandoff(actorId, oldGeneration, 'provisional');
     }
-    startHandoff(actorId, oldGeneration, transition) {
+    startHandoff(actorId, oldGeneration, phase) {
         if (this.active.has(actorId)) {
             throw new Error(`Actor '${actorId}' already has an active packet handoff.`);
         }
@@ -98,8 +98,8 @@ class ZLinkActorHandoffCoordinator {
             oldNodeRidHex: sourceEvidence.nodeRidHex,
             sourceEvidence,
             sourceOwner,
-            phase: transition.phase,
-            ...(transition.phase === 'provisional' ? { operationId: transition.operationId } : {}),
+            phase,
+            deferredJoin: phase === 'provisional',
             connectionBoundSealed: false,
             pending: [],
             nextIndex: 0,
@@ -113,14 +113,11 @@ class ZLinkActorHandoffCoordinator {
     isProvisional(actorId) {
         return this.active.get(actorId)?.phase === 'provisional';
     }
-    promoteProvisional(actorId, operationId) {
+    promoteProvisional(actorId) {
         const handoff = this.active.get(actorId);
-        if (handoff === undefined) {
+        if (handoff?.phase !== 'provisional') {
             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) {
@@ -131,12 +128,12 @@ class ZLinkActorHandoffCoordinator {
     activeSourceOwner(actorId) {
         return this.active.get(actorId)?.sourceOwner;
     }
-    async releaseDeferred(actorId, operationId, dispatch, admission) {
+    async releaseDeferred(actorId, 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.`);
+        if (!handoff.deferredJoin) {
+            throw new Error(`Actor '${actorId}' packet handoff was not started by a deferred Join.`);
         }
         await this.releaseHandoff(actorId, handoff, dispatch ?? handoff.replay, admission);
     }
@@ -153,12 +150,12 @@ class ZLinkActorHandoffCoordinator {
      *
      * @internal
      */
-    admitDeferredPrefix(actorId, operationId, queue, preparation, start = Promise.resolve()) {
+    admitDeferredPrefix(actorId, 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.`);
+        if (!handoff.deferredJoin) {
+            throw new Error(`Actor '${actorId}' packet handoff was not started by a deferred Join.`);
         }
         return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
     }
@@ -396,6 +393,20 @@ class ZLinkActorHandoffCoordinator {
         }
         pending.reject?.(error);
     }
+    /**
+     * Expired-owner terminal of a relocation (spec 28 §4.4): every pending
+     * record without a terminal fails once with `reason`. The handoff stays
+     * active, so the source never dispatches the Actor again.
+     */
+    failPending(actorId, reason) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return;
+        for (const pending of handoff.pending.splice(0))
+            this.failReleasedPending(pending, reason);
+        handoff.snapshotIndex = -1;
+        handoff.pendingBytes = 0;
+    }
     cancel(actorId) {
         const handoff = this.active.get(actorId);
         if (handoff === undefined)
@@ -929,7 +940,7 @@ class ZLinkActorHandoffCoordinator {
             return duplicate.result;
         }
         const bytes = packetBytes(packet);
-        if (context.hopCount >= MAX_MESSAGE_FOLLOW_HOPS) {
+        if (context.hopCount >= actor_message_follow_context_1.ZLINK_MESSAGE_FOLLOW_MAX_HOPS) {
             this.options.onMarker?.('message_follow_rejected', actorId);
             return Promise.reject(actorLocationStale(actorId));
         }

package/dist/runtime/actors/actor-lifecycle-snapshot.js

@@ -5,6 +5,7 @@ exports.actorJoinIdentity = actorJoinIdentity;
 exports.createActorJoinRequest = createActorJoinRequest;
 exports.createActorMembership = createActorMembership;
 const configuration_1 = require("../configuration");
+const diagnostic_text_1 = require("../diagnostics/diagnostic-text");
 exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = Symbol('zlink.actor.lifecycle-snapshot');
 /**
  * Identity an admission callback observes. Join admission decides on the Actor's
@@ -37,7 +38,7 @@ function lifecycleSource(actor) {
         : undefined;
     // A caller can hand in a value that carries no Framework context at all, so the
     // failure path reports the configuration error instead of dereferencing it.
-    const actorId = context?.actorId ?? '<unknown>';
+    const actorId = (0, diagnostic_text_1.diagnosticTextOrAbsent)(context?.actorId);
     const snapshot = context?.[exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT];
     const source = snapshot === undefined ? undefined : snapshot.call(context);
     if (source === undefined) {