@zlink-systems/framework 0.26.0 → 0.28.0

package/dist/runtime/actors/actor-authority-payload-codec.js

@@ -7,22 +7,33 @@ exports.decodeActorAuthorityPayload = decodeActorAuthorityPayload;
 exports.actorRelocationAuthorityApplicationPayload = actorRelocationAuthorityApplicationPayload;
 exports.relocatingActorAuthorityApplicationPayload = relocatingActorAuthorityApplicationPayload;
 exports.replaceActorRelocationAuthorityApplicationPayload = replaceActorRelocationAuthorityApplicationPayload;
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const contracts_1 = require("../../contracts");
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
+const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
 const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
+const service_wire_binary_primitives_1 = require("../foundation/service-wire-binary-primitives");
 const routing_id_1 = require("../routing-id");
 const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
 const AUTHORITY_VERSION = 1;
 const AUTHORITY_FLAGS = 0;
 const ACTOR_RELOCATION_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x50]);
-const MAXIMUM_BYTES = 1024 * 1024;
+const AUTHORITY_MINIMUM_BYTES = 15;
+const ACTOR_RELOCATION_MINIMUM_BYTES = 32;
+const ACTOR_RELOCATION_VERSION_WITHOUT_SESSION_FENCE = 5;
+const ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE = 6;
+const ACTOR_RELOCATION_FIRST_PHASE = 1;
+const ACTOR_RELOCATION_STEADY_PHASE = 4;
+const ENTRY_SPOT_WIRE_KIND = (0, contracts_1.zlinkSpotKindToWire)(contracts_1.ZLinkSpotKind.Entry);
+const USER_SPOT_WIRE_KIND = (0, contracts_1.zlinkSpotKindToWire)(contracts_1.ZLinkSpotKind.User);
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 /** Encodes the durable authority-payload-v1 envelope around one schema body. */
 function encodeCanonicalAuthorityPayload(value) {
     const body = Buffer.from(value.body);
     const envelope = concat(AUTHORITY_MAGIC, Buffer.of(AUTHORITY_VERSION), u16be(AUTHORITY_FLAGS), u32be(body.byteLength), body);
     const encoded = concat(envelope, u32be((0, service_relocation_runtime_1.crc32c)(envelope)));
-    if (encoded.byteLength > MAXIMUM_BYTES) {
-        throw new RangeError('Actor authority payload exceeds 1 MiB.');
+    if (encoded.byteLength > InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES) {
+        throw new RangeError(`Actor authority payload exceeds ${InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`);
     }
     return encoded;
 }
@@ -30,7 +41,8 @@ function encodeCanonicalAuthorityPayload(value) {
 function decodeCanonicalAuthorityPayload(payload) {
     try {
         const reader = new BigEndianReader(payload);
-        if (reader.bytes.byteLength < 15 || reader.bytes.byteLength > MAXIMUM_BYTES) {
+        if (reader.bytes.byteLength < AUTHORITY_MINIMUM_BYTES ||
+            reader.bytes.byteLength > InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES) {
             return undefined;
         }
         reader.expect(AUTHORITY_MAGIC);
@@ -52,7 +64,7 @@ function decodeCanonicalAuthorityPayload(payload) {
 /** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.Encode. */
 function encodeActorAuthorityPayload(value) {
     const spotKind = (0, contracts_1.zlinkSpotKindToWire)(value.currentSpotKind);
-    if (spotKind !== 1 && spotKind !== 2) {
+    if (spotKind !== ENTRY_SPOT_WIRE_KIND && spotKind !== USER_SPOT_WIRE_KIND) {
         throw new RangeError('Actor currentSpotKind must be Entry or User.');
     }
     const actor = concat(text8(value.stableType, 'stableType'), text8(value.actorId, 'actorId'), Buffer.of(value.state === 'creating' ? 0 : 1), text8(value.currentSpotId, 'currentSpotId'), nonzeroU64be(value.currentSpotGeneration, 'currentSpotGeneration'), Buffer.of(spotKind));
@@ -117,7 +129,7 @@ function actorRelocationAuthorityApplicationPayload(payload) {
     const current = decodeActorRelocationEnvelope(payload);
     return current === undefined
         ? Buffer.from(payload)
-        : current.phase === 4
+        : current.phase === ACTOR_RELOCATION_STEADY_PHASE
             ? Buffer.from(current.applicationPayload)
             : undefined;
 }
@@ -132,15 +144,16 @@ function replaceActorRelocationAuthorityApplicationPayload(payload, applicationP
         return Buffer.from(applicationPayload);
     const withoutChecksum = concat(current.prefix, i32le(applicationPayload.byteLength), applicationPayload);
     const encoded = concat(withoutChecksum, u32le((0, service_relocation_runtime_1.crc32c)(withoutChecksum)));
-    if (encoded.byteLength > MAXIMUM_BYTES) {
-        throw new RangeError('Actor relocation authority payload exceeds 1 MiB.');
+    if (encoded.byteLength > InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES) {
+        throw new RangeError(`Actor relocation authority payload exceeds ${InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES / (1024 * 1024)} MiB.`);
     }
     return encoded;
 }
 function decodeActorRelocationEnvelope(payload) {
     try {
         const bytes = Buffer.from(payload);
-        if (bytes.byteLength < 32 || bytes.byteLength > MAXIMUM_BYTES)
+        if (bytes.byteLength < ACTOR_RELOCATION_MINIMUM_BYTES ||
+            bytes.byteLength > InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES)
             return undefined;
         const checksumOffset = bytes.byteLength - 4;
         if (bytes.readUInt32LE(checksumOffset) !== (0, service_relocation_runtime_1.crc32c)(bytes.subarray(0, checksumOffset))) {
@@ -149,12 +162,13 @@ function decodeActorRelocationEnvelope(payload) {
         const reader = new LittleEndianReader(bytes.subarray(0, checksumOffset));
         reader.expect(ACTOR_RELOCATION_MAGIC);
         const version = reader.u16();
-        if (version !== 5 && version !== 6)
+        if (version !== ACTOR_RELOCATION_VERSION_WITHOUT_SESSION_FENCE &&
+            version !== ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE)
             return undefined;
         if (reader.take(16).every((byte) => byte === 0))
             return undefined;
         const phase = reader.u8();
-        if (phase < 1 || phase > 4)
+        if (phase < ACTOR_RELOCATION_FIRST_PHASE || phase > ACTOR_RELOCATION_STEADY_PHASE)
             return undefined;
         const isBound = reader.bool();
         if (isBound) {
@@ -169,7 +183,7 @@ function decodeActorRelocationEnvelope(payload) {
             const ownerLeaseGeneration = reader.u64();
             const sessionOwnerNodeGeneration = reader.u64();
             reader.u64();
-            if (version === 6) {
+            if (version === ACTOR_RELOCATION_VERSION_WITH_SESSION_FENCE) {
                 reader.text16();
                 reader.u64();
             }
@@ -184,7 +198,7 @@ function decodeActorRelocationEnvelope(payload) {
         }
         const prefix = Buffer.from(reader.bytes.subarray(0, reader.offset));
         const applicationLength = reader.i32();
-        if (applicationLength < 1 || applicationLength > MAXIMUM_BYTES)
+        if (applicationLength < 1 || applicationLength > InternalDefaults_1.AUTHORITY_ENVELOPE_MAX_BYTES)
             return undefined;
         const applicationPayload = Buffer.from(reader.take(applicationLength));
         if (!reader.done)
@@ -197,20 +211,22 @@ function decodeActorRelocationEnvelope(payload) {
 }
 function text8(value, name) {
     const bytes = Buffer.from(value, 'utf8');
-    if (bytes.byteLength < 1 || bytes.byteLength > 0xff || bytes.includes(0)) {
-        throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+    if (bytes.byteLength < 1 ||
+        bytes.byteLength > service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES ||
+        bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..${service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES} UTF-8 bytes without NUL.`);
     }
     return concat(Buffer.of(bytes.byteLength), bytes);
 }
 function rid(value, name) {
     const bytes = Buffer.from((0, routing_id_1.encodeRoutingIdStorageHex)(value), 'hex');
-    if (bytes.byteLength < 1 || bytes.byteLength > 0xff) {
-        throw new RangeError(`${name} must contain 1..255 bytes.`);
+    if (bytes.byteLength < 1 || bytes.byteLength > CoreTypes_1.ZLINK_MAX_ROUTING_ID_BYTES) {
+        throw new RangeError(`${name} must contain 1..${CoreTypes_1.ZLINK_MAX_ROUTING_ID_BYTES} bytes.`);
     }
     return concat(Buffer.of(bytes.byteLength), bytes);
 }
 function nonzeroU64be(value, name) {
-    if (value === 0n || value < 0n || value > 0xffffffffffffffffn) {
+    if (value === 0n || value < 0n || value > stream_wire_1.UINT64_MAX) {
         throw new RangeError(`${name} must be a non-zero u64.`);
     }
     const result = Buffer.alloc(8);

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

@@ -1,6 +1,6 @@
-import type { ActorRef, ZLinkActorClient, ZLinkActorRequestCall, ZLinkActorSendCall, ZLinkMessageSerializer } from '../../contracts';
+import { type ActorRef, type ZLinkActorClient, type ZLinkActorRequestCall, type ZLinkActorSendCall, type ZLinkMessageSerializer } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
+import { type ZLinkBackendMeshNode, type ZLinkMeshCompletionTable } from '../backend';
 import type { ZLinkStoreLocationResolvers } from '../locations';
 import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
 export interface ZLinkActorClientOptions {

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) {
@@ -26,24 +28,21 @@ class DefaultZLinkActorClient {
     }
     sendToActor(actorId, message) {
         requireActorId(actorId);
-        return new DefaultZLinkActorSendCall((packetName, metadata, signal) => this.send(actorId, packetName, message, metadata, signal), message);
+        return new DefaultZLinkActorSendCall((packetName, metadata) => this.send(actorId, packetName, message, metadata), message);
     }
     requestToActor(actorId, request) {
         requireActorId(actorId);
         return new DefaultZLinkActorRequestCall((packetName, timeoutMs, metadata, signal) => this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'async'), (packetName, timeoutMs, metadata, signal) => this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'yield'), actorId, request, this.options.defaultRequestTimeoutMs);
     }
-    async send(actorId, explicitPacketName, message, metadata, signal) {
-        (0, abort_1.throwIfAborted)(signal);
-        const route = await this.resolveActorRoute(actorId, signal);
+    async send(actorId, explicitPacketName, message, metadata) {
+        const route = await this.resolveActorRoute(actorId);
         const { meshName, actorRef: actor } = route;
         this.throwIfKnownStale(meshName, actor);
         const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Send, undefined, explicitPacketName, message, metadata);
         const messageFollow = createActorMessageFollowContext(route, parts, false);
         const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
         try {
-            const submissionCopies = (await this.options
-                .transportDeliveryGate?.()
-                ?.waitBeforeSubmit(actorId, 'oneWay', signal)) ?? 1;
+            const submissionCopies = (await this.options.transportDeliveryGate?.()?.waitBeforeSubmit(actorId, 'oneWay')) ?? 1;
             const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, false, routedActor);
             if (handoff !== undefined) {
                 const submissions = [handoff];
@@ -52,8 +51,8 @@ class DefaultZLinkActorClient {
                     if (duplicate !== undefined)
                         submissions.push(duplicate);
                 }
-                await (0, abort_1.awaitWithAbort)(Promise.all(submissions), signal);
-                return submitted();
+                await Promise.all(submissions);
+                return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
             }
             const node = this.requireNode(meshName);
             if (this.options.routeTransport !== undefined &&
@@ -66,8 +65,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 +88,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 +103,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 +117,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 +134,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 +193,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 +296,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) {
@@ -393,10 +367,10 @@ class DefaultZLinkActorSendCall {
         this.selectedMetadata.set(key, value);
         return this;
     }
-    async submit(signal) {
+    async submit() {
         ensureSingleSubmit(this.executed);
         this.executed = true;
-        const result = await this.submitter(this.packet ?? (0, packet_name_1.resolveFrameworkPacketName)(this.message, undefined, 'Actor'), this.selectedMetadata, signal);
+        const result = await this.submitter(this.packet ?? (0, packet_name_1.resolveFrameworkPacketName)(this.message, undefined, 'Actor'), this.selectedMetadata);
         (0, submission_result_1.requireOneWayCompletion)(result, 'Actor send', framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound);
     }
 }
@@ -493,97 +467,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 +496,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 +504,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));
         }