@zlink-systems/framework 0.26.0 → 0.28.0

package/src/runtime/actors/actor-client.ts

@@ -1,41 +1,57 @@
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind
-} from '../framework-errors-internal';
+  type ActorRef,
+  type RoutingId,
+  type ZLinkActorClient,
+  type ZLinkActorRequestCall,
+  type ZLinkActorSendCall,
+  type ZLinkMessageSerializer,
+  ZLinkFrameworkErrorKind,
+  ZLinkFrameworkException,
+  ZLinkSpotKind
+} from '../../contracts';
+
+import { ZLINK_MAX_ACTOR_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import type { Message } from '../../contracts/Common/Message';
+import { throwIfAborted } from '../abort';
+import {
+  type ZLinkBackendActorRef,
+  type ZLinkBackendMeshNode,
+  type ZLinkMeshCompletionTable,
+  closeMeshCompletion
+} from '../backend';
+
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import {
+  isZLinkBackendResultError,
   RequestResult,
   SubmitResult,
-  isZLinkBackendResultError,
   ZLINK_BACKEND_SEND_NONE
 } from '../backend/runtime-values';
-import type {
-  ActorRef,
-  RoutingId,
-  ZLinkActorClient,
-  ZLinkActorRequestCall,
-  ZLinkActorSendCall,
-  ZLinkMessageSerializer
-} from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
-import { ZLinkFrameworkException, ZLinkFrameworkErrorKind } from '../../contracts';
+import { ZLinkConfigurationException } from '../configuration';
+import {
+  captureZLinkSpotSerialTurn,
+  currentZLinkSpotSerialSourceId,
+  requireZLinkYieldTurn,
+  type ZLinkSpotSerialTurn
+} from '../execution';
+import { remainingActorRequestTimeout, waitActorReply } from './actor-request-deadline';
 import {
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  internalFrameworkErrorKindFromWireFailureCode,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
+import type { ZLinkResolvedActorRoute, ZLinkStoreLocationResolvers } from '../locations';
+import { resolveFrameworkPacketName } from '../messaging/packet-name';
+import { decodeFrameworkPayloadMessage, encodeFrameworkPayload } from '../messaging/payload-codec';
+import {
+  classifySubmitResult,
   requireOneWayCompletion,
   throwAlreadySubmitted,
   ZLinkSubmitStatus,
   type ZLinkSubmitResult
 } from '../messaging/submission-result';
-import type { Message } from '../../contracts/Common/Message';
-import type {
-  ZLinkBackendActorRef,
-  ZLinkBackendMeshNode,
-  ZLinkMeshCompletionTable
-} from '../backend';
-import { closeMeshCompletion } from '../backend';
-import { awaitWithAbort, throwIfAborted } from '../abort';
-import { encodeFrameworkPayload, decodeFrameworkPayloadMessage } from '../messaging/payload-codec';
-import { resolveFrameworkPacketName } from '../messaging/packet-name';
 import {
   actorRequestDeadlineMetadata,
   decodeStreamHeader,
@@ -45,11 +61,7 @@ import {
   ZLinkStreamHeaderFlags,
   ZLinkStreamMessageKind
 } from '../streams/protocol';
-import type { ZLinkStoreLocationResolvers } from '../locations';
-import type { ZLinkResolvedActorRoute } from '../locations';
-import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
-import { encodeRemoteActorPacketRelayPayload } from './actor-packet-relay-wire';
-import { requestRoutedJsonReply } from './actor-routed-json-request';
+import { currentZLinkActorExecution } from './actor-execution-context';
 import {
   attachActorMessageFollowContext,
   createInitialActorMessageFollowContext,
@@ -57,13 +69,11 @@ import {
   type ZLinkActorMessageFollowContext
 } from './actor-message-follow-context';
 import {
-  captureZLinkSpotSerialTurn,
-  currentZLinkSpotSerialSourceId,
-  requireZLinkYieldTurn,
-  type ZLinkSpotSerialTurn
-} from '../execution';
-import { ZLinkConfigurationException } from '../configuration';
-import { currentZLinkActorExecution } from './actor-execution-context';
+  encodeRemoteActorPacketRelayPayload,
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
+} from './actor-packet-relay-wire';
+import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
+import { requestRoutedJsonReply } from './actor-routed-json-request';
 
 export interface ZLinkActorClientOptions {
   readonly nodeProvider: (meshName: string) => ZLinkBackendMeshNode | undefined;
@@ -100,7 +110,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   sendToActor(actorId: string, message: unknown): ZLinkActorSendCall {
     requireActorId(actorId);
     return new DefaultZLinkActorSendCall(
-      (packetName, metadata, signal) => this.send(actorId, packetName, message, metadata, signal),
+      (packetName, metadata) => this.send(actorId, packetName, message, metadata),
       message
     );
   }
@@ -122,11 +132,9 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     actorId: string,
     explicitPacketName: string | undefined,
     message: unknown,
-    metadata: ReadonlyMap<string, string>,
-    signal?: AbortSignal
+    metadata: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult> {
-    throwIfAborted(signal);
-    const route = await this.resolveActorRoute(actorId, signal);
+    const route = await this.resolveActorRoute(actorId);
     const { meshName, actorRef: actor } = route;
     this.throwIfKnownStale(meshName, actor);
     const parts = this.createPacketParts(
@@ -140,9 +148,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     const routedActor = attachActorMessageFollowContext(actor, messageFollow);
     try {
       const submissionCopies =
-        (await this.options
-          .transportDeliveryGate?.()
-          ?.waitBeforeSubmit(actorId, 'oneWay', signal)) ?? 1;
+        (await this.options.transportDeliveryGate?.()?.waitBeforeSubmit(actorId, 'oneWay')) ?? 1;
       const handoff = this.options.handoffCapture?.(
         meshName,
         actor.actorId,
@@ -162,8 +168,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
           );
           if (duplicate !== undefined) submissions.push(duplicate);
         }
-        await awaitWithAbort(Promise.all(submissions), signal);
-        return submitted();
+        await Promise.all(submissions);
+        return { status: ZLinkSubmitStatus.Submitted };
       }
       const node = this.requireNode(meshName);
       if (
@@ -181,9 +187,9 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
             returnResponse: false,
             messageFollowContext: messageFollow
           }),
-          { packetName: '__zlink.actor.packet.relay' }
+          { packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET }
         );
-        return submitted();
+        return { status: ZLinkSubmitStatus.Submitted };
       }
       return await this.submitActorSend(meshName, toBackendActorRef(actor), parts);
     } catch (error) {
@@ -214,7 +220,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       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 &&
@@ -248,10 +254,13 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     );
     const routedActor = attachActorMessageFollowContext(actor, messageFollow);
     try {
+      const delivery = this.options
+        .transportDeliveryGate?.()
+        ?.waitBeforeSubmit(actorId, 'request', signal);
       const submissionCopies =
-        (await this.options
-          .transportDeliveryGate?.()
-          ?.waitBeforeSubmit(actorId, 'request', signal)) ?? 1;
+        delivery === undefined
+          ? 1
+          : ((await waitActorReply(delivery, actorId, deadlineMs, signal)) ?? 1);
       const handoff = this.options.handoffCapture?.(
         meshName,
         actor.actorId,
@@ -273,9 +282,11 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
           );
           if (duplicate !== undefined) submissions.push(duplicate);
         }
-        const replies = await waitHandoffReply<unknown[]>(
+        const replies = await waitActorReply<unknown[]>(
           Promise.all(submissions),
-          remainingActorRequestTimeout(actorId, deadlineMs)
+          actorId,
+          deadlineMs,
+          signal
         );
         return replies[0] as TReply;
       }
@@ -302,7 +313,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
 
   private async resolveActorRoute(
     actorId: string,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    deadlineMs?: number
   ): Promise<ZLinkResolvedActorRoute> {
     const resolver = this.options.locationResolver();
     if (resolver === undefined) {
@@ -311,7 +323,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         '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 createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,
@@ -390,7 +402,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   ): Promise<ZLinkSubmitResult> {
     const node = this.requireNode(meshName);
     try {
-      return mapSubmitResult(
+      return classifySubmitResult(
         await node.sendToActor(actor, toMessageLikeParts(parts), {
           flags: ZLINK_BACKEND_SEND_NONE
         }),
@@ -398,11 +410,9 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       );
     } catch (error) {
       if (isZLinkBackendResultError(error)) {
-        return mapSubmitResult(error.result, 'Actor send');
+        return classifySubmitResult(error.result, 'Actor send', error.phase);
       }
-      throw isZLinkBackendResultError(error)
-        ? mapRequestError(error, 'Actor send')
-        : mapSubmitError(error, 'Actor send');
+      throw mapSubmitError(error, 'Actor send');
     }
   }
 
@@ -560,53 +570,12 @@ function remoteRelayErrorKind(value: unknown): ZLinkFrameworkInternalErrorKind {
     : ZLinkFrameworkInternalErrorKind.RequestFailed;
 }
 
-function remainingActorRequestTimeout(
-  actorId: string,
-  deadlineMs: number | undefined
-): number | undefined {
-  if (deadlineMs === undefined) return undefined;
-  const remaining = deadlineMs - performance.now();
-  if (remaining <= 0) {
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-      `Actor request '${actorId}' exceeded its deadline before submission.`
-    );
-  }
-  return Math.max(1, Math.ceil(remaining));
-}
-
 function requireActorId(actorId: string): void {
   const byteLength = Buffer.byteLength(actorId, 'utf8');
-  if (byteLength < 1 || byteLength > 255) {
-    throw new ZLinkConfigurationException('Actor ID must contain 1..255 UTF-8 bytes.');
-  }
-}
-
-async function waitHandoffReply<TReply>(
-  reply: Promise<unknown>,
-  timeoutMs: number | undefined
-): Promise<TReply> {
-  if (timeoutMs === undefined) return (await reply) as TReply;
-  let deadline: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      reply as Promise<TReply>,
-      new Promise<TReply>((_resolve, reject) => {
-        deadline = setTimeout(
-          () =>
-            reject(
-              createInternalFrameworkException(
-                ZLinkFrameworkInternalErrorKind.RequestFailed,
-                'Actor handoff request timed out.',
-                true
-              )
-            ),
-          timeoutMs
-        );
-      })
-    ]);
-  } finally {
-    if (deadline !== undefined) clearTimeout(deadline);
+  if (byteLength < 1 || byteLength > ZLINK_MAX_ACTOR_ID_BYTES) {
+    throw new ZLinkConfigurationException(
+      `Actor ID must contain 1..${ZLINK_MAX_ACTOR_ID_BYTES} UTF-8 bytes.`
+    );
   }
 }
 
@@ -689,8 +658,7 @@ class DefaultZLinkActorSendCall implements ZLinkActorSendCall {
   constructor(
     private readonly submitter: (
       packetName: string | undefined,
-      metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
+      metadata: ReadonlyMap<string, string>
     ) => Promise<ZLinkSubmitResult>,
     private readonly message: unknown
   ) {}
@@ -705,13 +673,12 @@ class DefaultZLinkActorSendCall implements ZLinkActorSendCall {
     return this;
   }
 
-  async submit(signal?: AbortSignal): Promise<void> {
+  async submit(): Promise<void> {
     ensureSingleSubmit(this.executed);
     this.executed = true;
     const result = await this.submitter(
       this.packet ?? resolveFrameworkPacketName(this.message, undefined, 'Actor'),
-      this.selectedMetadata,
-      signal
+      this.selectedMetadata
     );
     requireOneWayCompletion(
       result,
@@ -861,7 +828,7 @@ function decodeActorReplyPayload<TReply>(
     payload,
     serializers,
     undefined,
-    'application/json',
+    ZlinkStreamContentType.Json,
     packetName,
     'reply'
   );
@@ -871,29 +838,6 @@ function mapSubmitError(error: unknown, operationName: string): Error {
   if (error instanceof ZLinkFrameworkException) {
     return error;
   }
-  if (isZLinkBackendResultError(error)) {
-    switch (error.result) {
-      case SubmitResult.NotConnected:
-        return routeNotConnected(
-          `${operationName} failed because the target route is not connected.`,
-          error
-        );
-      case SubmitResult.NotFound:
-        return createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,
-          `${operationName} failed because the actor route was not found.`,
-          false,
-          error
-        );
-      default:
-        return createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestFailed,
-          `${operationName} failed with submit result ${error.result}.`,
-          false,
-          error
-        );
-    }
-  }
   return createInternalFrameworkException(
     ZLinkFrameworkInternalErrorKind.RouteNotConnected,
     `${operationName} failed before a reply was received.`,
@@ -902,79 +846,6 @@ function mapSubmitError(error: unknown, operationName: string): Error {
   );
 }
 
-function mapSubmitResult(result: number, operationName: string): ZLinkSubmitResult {
-  switch (result) {
-    case SubmitResult.Ok:
-      return submitted();
-    case SubmitResult.Backpressured:
-    case SubmitResult.NotAdmitted:
-      return { status: ZLinkSubmitStatus.Backpressured };
-    case SubmitResult.NotConnected:
-      return { status: ZLinkSubmitStatus.RouteNotConnected };
-    case SubmitResult.NotFound:
-      return { status: ZLinkSubmitStatus.TargetNotFound };
-    case SubmitResult.Terminated:
-      return { status: ZLinkSubmitStatus.Shutdown };
-    default:
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestFailed,
-        `${operationName} failed with submit result ${result}.`
-      );
-  }
-}
-
-function submitted(): ZLinkSubmitResult {
-  return { status: 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: number): ZLinkFrameworkInternalErrorKind | undefined {
-  switch (failureErrno) {
-    case 3:
-      return ZLinkFrameworkInternalErrorKind.ActorAlreadyExists;
-    case 4:
-      return ZLinkFrameworkInternalErrorKind.ActorTypeMismatch;
-    case 7:
-      return ZLinkFrameworkInternalErrorKind.SpotTypeMismatch;
-    case 8:
-      return ZLinkFrameworkInternalErrorKind.ActorSessionNotBound;
-    case 9:
-    case 14:
-      return ZLinkFrameworkInternalErrorKind.RequestTargetNotFound;
-    case 12:
-    case 16:
-      return ZLinkFrameworkInternalErrorKind.RequestProtocolError;
-    //  routeNotConnected(13) and a remote worker queue full(18) are Unavailable.
-    case 13:
-    case 18:
-      return ZLinkFrameworkInternalErrorKind.RouteNotConnected;
-    case 15:
-      return ZLinkFrameworkInternalErrorKind.RequestRejected;
-    case 19:
-      return ZLinkFrameworkInternalErrorKind.WorkerTimedOut;
-    case 17:
-      return ZLinkFrameworkInternalErrorKind.RequestFailed;
-    case 20:
-      return ZLinkFrameworkInternalErrorKind.WorkerFailed;
-    case 21:
-      return ZLinkFrameworkInternalErrorKind.ActorLocationStale;
-    case 33:
-      return ZLinkFrameworkInternalErrorKind.ActorGenerationStale;
-    case 34:
-      return ZLinkFrameworkInternalErrorKind.ActorMoving;
-    case 35:
-      return ZLinkFrameworkInternalErrorKind.RelocationDataLost;
-    default:
-      return undefined;
-  }
-}
-
 function actorTerminalKind(result: number): ZLinkFrameworkInternalErrorKind {
   switch (result) {
     case RequestResult.TimedOut:
@@ -990,7 +861,7 @@ function actorTerminalKind(result: number): ZLinkFrameworkInternalErrorKind {
     case RequestResult.NotConnected:
       return 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 RequestResult.Conflict:
     case RequestResult.Busy:
       return ZLinkFrameworkInternalErrorKind.ActorLocationStale;
@@ -999,8 +870,11 @@ function actorTerminalKind(result: number): ZLinkFrameworkInternalErrorKind {
   }
 }
 
+// The shared table preserves Actor fine kinds; without a recognized fine code,
+// the remote owner/queue terminal supplies the classification.
 function mapRequestResult(result: number, failureErrno: number, operationName: string): Error {
-  const kind = actorFailureCodeKind(failureErrno) ?? actorTerminalKind(result);
+  const kind =
+    internalFrameworkErrorKindFromWireFailureCode(failureErrno) ?? actorTerminalKind(result);
   return createInternalFrameworkException(
     kind,
     `${operationName} failed with request result ${result}` +
@@ -1008,13 +882,6 @@ function mapRequestResult(result: number, failureErrno: number, operationName: s
   );
 }
 
-function mapRequestError(
-  error: { readonly result: number; readonly failureErrno?: number },
-  operationName: string
-): Error {
-  return mapRequestResult(error.result, error.failureErrno ?? 0, operationName);
-}
-
 function routeNotConnected(message: string, cause?: unknown): ZLinkFrameworkException {
   return createInternalFrameworkException(
     ZLinkFrameworkInternalErrorKind.RouteNotConnected,

package/src/runtime/actors/actor-context.ts

@@ -1,45 +1,51 @@
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
-import type {
-  RoutingId,
-  SpotId,
-  ZLinkActor,
-  ZLinkActorContext,
-  ZLinkActorJoinCompletion,
-  ZLinkActorJoinEntrySpotCall,
-  ZLinkActorJoinSpotCall,
-  ZLinkBoundSession,
-  ZLinkBoundSessionSendCall
+  type RoutingId,
+  type SpotId,
+  type ZLinkActor,
+  type ZLinkActorContext,
+  type ZLinkActorJoinCompletion,
+  type ZLinkActorJoinEntrySpotCall,
+  type ZLinkActorJoinSpotCall,
+  type ZLinkBoundSession,
+  type ZLinkBoundSessionSendCall,
+  ZLinkEncodedPayload,
+  ZLinkFrameworkException,
+  ZLinkMessage,
+  type ZLinkMessageSerializer
 } from '../../contracts';
-import { ZLinkEncodedPayload, ZLinkFrameworkException, ZLinkMessage } from '../../contracts';
+
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import { type ZLinkMessageSerializer } from '../../contracts';
-import { ZLinkConfigurationException } from '../configuration';
 import {
-  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
   ZLinkDispatchErrorSurface,
-  ZLinkDispatchMessageKind
+  ZLinkDispatchMessageKind,
+  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
+import { ZLinkConfigurationException } from '../configuration';
+import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
+import { captureZLinkSpotSerialTurn } from '../execution';
+import { createRandomOperationIdentity } from '../foundation/operation-identity';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
-import { ZLinkActorRuntimeState, toFrameworkActorRef } from './actor-runtime-state';
-import type {
-  ZLinkActorBoundSessionFactory,
-  ZLinkActorJoinCoordinator
-} from './actor-runtime-contracts';
-import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
+import { deferActorJoin } from './actor-join-deferred-scope';
 import {
   ZLINK_ACTOR_LIFECYCLE_SNAPSHOT,
   type ZLinkActorLifecycleSnapshotSource
 } from './actor-lifecycle-snapshot';
-import { createRandomOperationIdentity } from '../foundation/operation-identity';
-import { deferActorJoin } from './actor-join-deferred-scope';
-import { captureZLinkSpotSerialTurn } from '../execution';
-import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
+import type {
+  ZLinkActorBoundSessionFactory,
+  ZLinkActorJoinCoordinator,
+  ZLinkActorManagerOptions
+} from './actor-runtime-contracts';
+import { ZLinkActorRuntimeState, toFrameworkActorRef } from './actor-runtime-state';
+const DEFAULT_ACTOR_JOIN_TIMEOUT_MS = 5_000;
+
+const MAX_ACTOR_JOIN_TIMEOUT_MS = 2_147_483_647;
 
 export const ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = Symbol('zlink.actor.join-entry-spot-runtime');
 
@@ -166,7 +172,7 @@ export class DefaultZLinkActorContext implements ZLinkActorContext {
 }
 
 class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
-  private timeoutMs = 5_000;
+  private timeoutMs: number = DEFAULT_ACTOR_JOIN_TIMEOUT_MS;
   private deferred = false;
   private readonly turn = captureZLinkSpotSerialTurn();
 
@@ -305,7 +311,7 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
 }
 
 class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall {
-  private timeoutMs = 5_000;
+  private timeoutMs: number = DEFAULT_ACTOR_JOIN_TIMEOUT_MS;
   private deferred = false;
   private readonly turn = captureZLinkSpotSerialTurn();
 
@@ -480,9 +486,9 @@ function encodeJoinRequest(
 
 function validateJoinTimeout(timeoutMs: number): number {
   const rounded = Math.ceil(timeoutMs);
-  if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > 2_147_483_647) {
+  if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > MAX_ACTOR_JOIN_TIMEOUT_MS) {
     throw new ZLinkConfigurationException(
-      'Actor join timeout must be a finite value from 1 through 2147483647 milliseconds.'
+      `Actor join timeout must be a finite value from 1 through ${MAX_ACTOR_JOIN_TIMEOUT_MS} milliseconds.`
     );
   }
   return rounded;

package/src/runtime/actors/actor-handoff.ts

@@ -1,45 +1,47 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind
-} from '../framework-errors-internal';
-import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import type { ActorRef, RoutingId } from '../../contracts';
-import { ZLinkFrameworkException } from '../../contracts';
+import { type ActorRef, type RoutingId, ZLinkFrameworkException } from '../../contracts';
+
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import { zlinkDefaultLocationOptions } from '../../contracts/Locations/Options';
+import { releaseApplicationJobPermitForDurableHandoff } from '../application-jobs/application-job-queue-scope';
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import {
   MessageFollowSuppressionRegistry,
   type MessageFollowSuppressionFence
 } from '../foundation/message-follow-suppression-registry';
-import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import {
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
 import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
-import { releaseApplicationJobPermitForDurableHandoff } from '../application-jobs/application-job-queue-scope';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import { decodeActorRequestDeadlineUnixMs, decodeStreamHeader } from '../streams/protocol';
-import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
-import { requestRoutedJsonReply } from './actor-routed-json-request';
-import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
-import {
-  encodeMessageFollowRemoteActorPacketRelayPayload,
-  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
-} from './actor-packet-relay-wire';
 import {
   actorMessageFollowContext,
   actorMessageFollowPayloadChecksum,
-  attachActorMessageFollowContext,
   advanceActorMessageFollowContext,
+  attachActorMessageFollowContext,
   createMessageFollowId,
   messageFollowOwnerFenceKey,
   messageFollowOwnerFencesEqual,
   messageFollowOwnerNodeRid,
   ownerFence,
   verifyActorMessageFollowPayload,
+  ZLINK_MESSAGE_FOLLOW_MAX_HOPS,
   type ZLinkActorMessageFollowContext,
   type ZLinkActorMessageFollowOwnerFence
 } from './actor-message-follow-context';
+import {
+  encodeMessageFollowRemoteActorPacketRelayPayload,
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
+} from './actor-packet-relay-wire';
+import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
+import { requestRoutedJsonReply } from './actor-routed-json-request';
+import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
 
-export const DEFAULT_MESSAGE_FOLLOW_DURATION_MS = 30_000;
-const MAX_MESSAGE_FOLLOW_HOPS = 8;
+export const DEFAULT_MESSAGE_FOLLOW_DURATION_MS =
+  zlinkDefaultLocationOptions.messageFollowDurationMs;
 const RELOCATION_REPLY_RETENTION_MS = 24 * 60 * 60 * 1_000;
 
 export interface ZLinkActorHandoffPacket {
@@ -1445,7 +1447,7 @@ export class ZLinkActorHandoffCoordinator {
       return duplicate.result;
     }
     const bytes = packetBytes(packet);
-    if (context.hopCount >= MAX_MESSAGE_FOLLOW_HOPS) {
+    if (context.hopCount >= ZLINK_MESSAGE_FOLLOW_MAX_HOPS) {
       this.options.onMarker?.('message_follow_rejected', actorId);
       return Promise.reject(actorLocationStale(actorId));
     }