@zlink-systems/framework 0.26.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) {
@@ -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) {
@@ -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;

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) {
@@ -940,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) {

package/dist/runtime/actors/actor-local-native-join.d.ts

@@ -1,26 +1,31 @@
-import type { RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkMessageSerializer } from '../../contracts';
-import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
+import { type RoutingId, type ZLinkActor, type ZLinkActorJoinOperationId, type ZLinkMessageSerializer, type ZLinkSpot, type ZLinkSpotActorJoinResult } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
 import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import type { ZLinkLocationLifecycle } from '../locations';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
+import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
 import { ZLinkActorRuntimeState } from './actor-runtime-state';
 import type { ZLinkPostCommitActorBinder } from './post-commit-actor-binder';
-import type { ZLinkPostCommitActorLocation } from './post-commit-actor-location';
-import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
 export interface ZLinkLocalNativeActorJoinOptions {
-    readonly postCommitLocation?: ZLinkPostCommitActorLocation;
+    readonly locationLifecycle?: ZLinkLocationLifecycle;
+    readonly localSpotJoin?: (spotId: RoutingId, actor: ZLinkActor, request: Message, commit: (spot: ZLinkSpot) => Promise<void>, signal?: AbortSignal, leaveSource?: () => Promise<void>, contentType?: string) => Promise<ZLinkSpotActorJoinResult>;
+    readonly localEntryJoin?: (actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+    readonly localSourceLeave?: (actor: ZLinkActor, spotId: RoutingId | undefined, signal?: AbortSignal) => Promise<void>;
+    readonly reportSourceLeaveError: (error: unknown) => void;
     readonly postCommitBinder?: ZLinkPostCommitActorBinder;
     readonly completionTableProvider: () => ZLinkMeshCompletionTable | undefined;
     readonly actorJoinRelocation?: ZLinkActorJoinRelocation;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
 }
-/** Owns core-native actor joins and their local runtime state transition. */
+/** Selects local membership commits or remote Actor relocation. */
 export declare class ZLinkLocalNativeActorJoin {
     private readonly options;
     constructor(options: ZLinkLocalNativeActorJoinOptions);
     joinSpot(node: ZLinkBackendMeshNode, actor: ZLinkActor, state: ZLinkActorRuntimeState, actorRef: ZLinkBackendActorRef, spotId: RoutingId, spotRouteTarget: ZLinkSpotRouteTarget | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     joinEntrySpot(node: ZLinkBackendMeshNode, actor: ZLinkActor, state: ZLinkActorRuntimeState, actorRef: ZLinkBackendActorRef, nodeRid: RoutingId, spotRouteTarget: ZLinkSpotRouteTarget | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
+    private joinLocal;
     private waitForJoinCompletion;
     private relocateRemoteActorJoin;
     private requireCompletions;