@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,612 @@
+"use strict";
+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 contracts_1 = require("../../contracts");
+const contracts_2 = require("../../contracts");
+const submission_result_1 = require("../messaging/submission-result");
+const backend_1 = require("../backend");
+const abort_1 = require("../abort");
+const payload_codec_1 = require("../messaging/payload-codec");
+const packet_name_1 = require("../messaging/packet-name");
+const protocol_1 = require("../streams/protocol");
+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) {
+        this.options = options;
+    }
+    sendToActor(actorId, message) {
+        requireActorId(actorId);
+        return new DefaultZLinkActorSendCall((packetName, metadata, signal) => this.send(actorId, packetName, message, metadata, signal), 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);
+        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 handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, false, routedActor);
+            if (handoff !== undefined) {
+                const submissions = [handoff];
+                for (let copy = 1; copy < submissionCopies; copy++) {
+                    const duplicate = this.options.handoffCapture?.(meshName, actor.actorId, parts, false, routedActor);
+                    if (duplicate !== undefined)
+                        submissions.push(duplicate);
+                }
+                await (0, abort_1.awaitWithAbort)(Promise.all(submissions), signal);
+                return submitted();
+            }
+            const node = this.requireNode(meshName);
+            if (this.options.routeTransport !== undefined
+                && String(node.status().routingId) !== String(actor.nodeRid)) {
+                await this.options.routeTransport.sendToSpot(remoteActorRouteTarget(route), (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
+                    actorId,
+                    header: parts[0].data(),
+                    payload: parts[1].data(),
+                    bindingActorRef: actor,
+                    actorRef: actor,
+                    returnResponse: false,
+                    messageFollowContext: messageFollow
+                }), { packetName: '__zlink.actor.packet.relay' });
+                return submitted();
+            }
+            return await this.submitActorSend(meshName, toBackendActorRef(actor), parts);
+        }
+        catch (error) {
+            if (isStaleActorError(error)) {
+                this.invalidateActorRoute(actorId);
+                this.options.staleActorRefReporter?.(meshName, actor.actorId);
+                throw actorLocationStale(actor.actorId, error);
+            }
+            throw error;
+        }
+        finally {
+            closeMessages(parts);
+        }
+    }
+    async request(actorId, explicitPacketName, request, timeoutMs, metadata, signal, waitPolicy = 'async') {
+        (0, abort_1.throwIfAborted)(signal);
+        const sourceSpotId = (0, actor_execution_context_1.currentZLinkActorExecution)()?.spotId
+            ?? (0, execution_1.currentZLinkSpotSerialSourceId)();
+        const effectiveTimeoutMs = timeoutMs ?? this.options.defaultRequestTimeoutMs;
+        const deadlineMs = effectiveTimeoutMs === undefined
+            ? undefined
+            : performance.now() + effectiveTimeoutMs;
+        const deadlineUnixMs = effectiveTimeoutMs === undefined
+            ? undefined
+            : Date.now() + effectiveTimeoutMs;
+        const route = await this.resolveActorRoute(actorId, signal);
+        if (waitPolicy === 'async'
+            && sourceSpotId !== undefined
+            && sameSpotRoute(sourceSpotId, route)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `An Actor request cannot await Actor '${actorId}' on the current Spot while holding its execution claim.`);
+        }
+        const { meshName, actorRef: actor } = route;
+        this.throwIfKnownStale(meshName, actor);
+        const operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+        const correlationId = (0, actor_message_follow_context_1.createMessageFollowId)();
+        const requestSequence = BigInt(`0x${operationId.slice(16)}`);
+        const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Request, requestSequence === 0n ? 1n : requestSequence, explicitPacketName, request, mergeActorRequestMetadata(metadata, deadlineUnixMs), correlationId);
+        const messageFollow = createActorMessageFollowContext(route, parts, true, deadlineUnixMs, correlationId, operationId);
+        const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
+        try {
+            const submissionCopies = await this.options.transportDeliveryGate?.()?.waitBeforeSubmit(actorId, 'request', signal) ?? 1;
+            const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs);
+            if (handoff !== undefined) {
+                const submissions = [handoff];
+                for (let copy = 1; copy < submissionCopies; copy++) {
+                    const duplicate = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs);
+                    if (duplicate !== undefined)
+                        submissions.push(duplicate);
+                }
+                const replies = await waitHandoffReply(Promise.all(submissions), remainingActorRequestTimeout(actorId, deadlineMs));
+                return replies[0];
+            }
+            return await this.submitActorRequest(meshName, toBackendActorRef(actor), parts, remainingActorRequestTimeout(actorId, deadlineMs), signal, route, messageFollow);
+        }
+        catch (error) {
+            if (isStaleActorError(error)) {
+                this.invalidateActorRoute(actorId);
+                this.options.staleActorRefReporter?.(meshName, actor.actorId);
+                throw actorLocationStale(actor.actorId, error);
+            }
+            throw error;
+        }
+        finally {
+            closeMessages(parts);
+        }
+    }
+    async resolveActorRoute(actorId, signal) {
+        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);
+        if (resolution.kind === 'missing') {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor route '${actorId}' was not found.`);
+        }
+        if (resolution.kind === 'owner_unavailable') {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteUnavailable, `Actor route '${actorId}' owner lease is unavailable.`);
+        }
+        return resolution.route;
+    }
+    invalidateActorRoute(actorId) {
+        this.options.locationResolver()?.invalidateActorRoute(actorId);
+    }
+    throwIfKnownStale(meshName, actor) {
+        if (this.options.staleActorRefPredicate?.(meshName, actor) !== true)
+            return;
+        this.invalidateActorRoute(actor.actorId);
+        this.options.staleActorRefReporter?.(meshName, actor.actorId);
+        throw actorLocationStale(actor.actorId, undefined);
+    }
+    createPacketParts(kind, requestSeq, explicitPacketName, message, metadata, correlationId) {
+        const packetName = (0, packet_name_1.resolveFrameworkPacketName)(message, explicitPacketName, 'Actor');
+        const flags = (requestSeq === undefined ? protocol_1.ZLinkStreamHeaderFlags.None : protocol_1.ZLinkStreamHeaderFlags.HasRequestSeq)
+            | (metadata.size === 0 ? protocol_1.ZLinkStreamHeaderFlags.None : protocol_1.ZLinkStreamHeaderFlags.HasMetadata)
+            | (correlationId === undefined
+                ? protocol_1.ZLinkStreamHeaderFlags.None
+                : protocol_1.ZLinkStreamHeaderFlags.HasCorrelationId);
+        const encoded = (0, payload_codec_1.encodeFrameworkPayload)(message, this.options.messageSerializers, packetName, 'payload');
+        try {
+            const header = (0, protocol_1.encodeStreamHeader)({
+                kind,
+                codec: (0, protocol_1.streamCodecForContentType)(encoded.contentType),
+                flags,
+                requestSeq,
+                name: packetName,
+                metadata,
+                correlationId
+            });
+            return [
+                //  encodeStreamHeader returns a fresh, unaliased array; wrap it
+                //  without re-copying.
+                runtime_message_1.ZLinkBufferMessage.fromOwned(toOwnedBuffer(header)),
+                encoded.message
+            ];
+        }
+        catch (error) {
+            encoded.message.close();
+            throw error;
+        }
+    }
+    async submitActorSend(meshName, actor, parts) {
+        const node = this.requireNode(meshName);
+        try {
+            return mapSubmitResult(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');
+            }
+            throw (0, runtime_values_1.isZLinkBackendResultError)(error)
+                ? mapRequestError(error, 'Actor send')
+                : mapSubmitError(error, 'Actor send');
+        }
+    }
+    async submitActorRequest(meshName, actor, parts, timeoutMs, signal, route, messageFollowContext) {
+        const node = this.requireNode(meshName);
+        if (this.options.routeTransport !== undefined
+            && String(node.status().routingId) !== String(actor.nodeRid)
+            && route !== undefined) {
+            const relay = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
+                actorId: actor.actorId,
+                header: parts[0].data(),
+                payload: parts[1].data(),
+                bindingActorRef: {
+                    actorId: actor.actorId,
+                    objectGeneration: actor.generation,
+                    meshName,
+                    nodeRid: actor.nodeRid
+                },
+                actorRef: {
+                    actorId: actor.actorId,
+                    objectGeneration: actor.generation,
+                    meshName,
+                    nodeRid: actor.nodeRid
+                },
+                returnResponse: true,
+                messageFollowContext
+            });
+            const reply = await (0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routeTransport, remoteActorRouteTarget(route), relay, { timeoutMs, signal }, `Remote Actor request is not available for '${actor.actorId}'.`, (replyParts) => JSON.parse(replyParts[0]?.getString('utf8') ?? '{}'));
+            if (reply.ok !== true) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(remoteRelayErrorKind(reply.errorKind), typeof reply.error === 'string' ? reply.error : `Remote Actor request failed for '${actor.actorId}'.`);
+            }
+            return reply.response;
+        }
+        const completions = this.options.completionTableProvider(meshName);
+        if (completions === undefined) {
+            throw routeNotConnected('Actor request requires a running MeshNode completion table.');
+        }
+        const completion = await completions.submit(() => node.requestToActor(actor, toMessageLikeParts(parts), {
+            flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
+            timeoutMs
+        }), signal);
+        if (completion.terminalResult !== runtime_values_1.RequestResult.Ok) {
+            (0, backend_1.closeMeshCompletion)(completion);
+            throw mapRequestResult(completion.terminalResult, completion.failureErrno, 'Actor request');
+        }
+        return decodeActorReply(completion.parts, this.options.messageSerializers, (0, protocol_1.decodeStreamHeader)(parts[0].data()).name);
+    }
+    requireNode(meshName) {
+        const node = this.options.nodeProvider(meshName);
+        if (node === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Actor client requires a running MeshNode for RouteMesh '${meshName}'.`, true);
+        }
+        return node;
+    }
+}
+exports.DefaultZLinkActorClient = DefaultZLinkActorClient;
+function remoteActorRouteTarget(route) {
+    if (route.enclosingSpotRoute !== undefined) {
+        return route.enclosingSpotRoute;
+    }
+    return {
+        routerChannelId: route.meshName,
+        targetNodeRid: route.actorRef.nodeRid,
+        spotId: (route.spotId ?? String(route.actorRef.nodeRid)),
+        spotKind: route.spotId === undefined ? contracts_1.ZLinkSpotKind.Entry : contracts_1.ZLinkSpotKind.User,
+        targetSpotGeneration: route.spotGeneration ?? route.ownerNodeGeneration,
+        targetNodeGeneration: route.ownerNodeGeneration,
+        targetOwnerId: route.ownerId,
+        ownerLeaseGeneration: route.ownerLeaseGeneration,
+        authorityOwnerGeneration: route.authorityOwnerGeneration,
+        authorityStoreVersion: route.authorityStoreVersion
+    };
+}
+function createActorMessageFollowContext(route, parts, request, deadlineUnixMs, correlationId, operationId) {
+    if (typeof route.ownerId !== 'string' || route.ownerId.length === 0
+        || typeof route.ownerLeaseGeneration !== 'bigint'
+        || route.ownerLeaseGeneration <= 0n
+        || typeof route.ownerNodeGeneration !== 'bigint'
+        || route.ownerNodeGeneration <= 0n
+        || typeof route.authorityOwnerGeneration !== 'bigint'
+        || route.authorityOwnerGeneration <= 0n
+        || typeof route.actorRef.objectGeneration !== 'bigint'
+        || route.actorRef.objectGeneration <= 0n) {
+        throw actorLocationStale(route.actorRef.actorId, new Error('Resolved Actor route does not contain an exact authority owner fence.'));
+    }
+    return (0, actor_message_follow_context_1.createInitialActorMessageFollowContext)(route, parts, request, deadlineUnixMs, correlationId, operationId);
+}
+function remoteRelayErrorKind(value) {
+    return Object.values(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind).includes(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);
+    }
+}
+async function forwardEncodedActorPacket(node, completions, actor, header, payload, returnResponse, timeoutMs, serializers) {
+    const target = toBackendActorRef(actor);
+    const parts = [header, payload];
+    const packetName = (0, protocol_1.decodeStreamHeader)(header).name;
+    if (!returnResponse) {
+        if (await node.sendToActor(target, parts, { flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE }) !== runtime_values_1.SubmitResult.Ok) {
+            throw routeNotConnected('Actor handoff send submit was not accepted.');
+        }
+        return undefined;
+    }
+    const completion = await completions.submit(() => node.requestToActor(target, parts, {
+        flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
+        timeoutMs
+    }));
+    if (completion.terminalResult !== runtime_values_1.RequestResult.Ok) {
+        (0, backend_1.closeMeshCompletion)(completion);
+        throw mapRequestResult(completion.terminalResult, completion.failureErrno, 'Actor handoff request');
+    }
+    return decodeActorReply(completion.parts, serializers, packetName);
+}
+function toBackendActorRef(actor) {
+    return {
+        nodeRid: actor.nodeRid,
+        actorId: actor.actorId,
+        generation: actor.objectGeneration
+    };
+}
+function toMessageLikeParts(parts) {
+    //  The caller keeps every part open until the awaited backend submit
+    //  completes and the backend consumes the parts synchronously during
+    //  multipart encoding, so borrowing the buffers avoids a payload copy.
+    return parts.map((part) => part.data());
+}
+/** Zero-copy Buffer view over a freshly allocated, unaliased byte array. */
+function toOwnedBuffer(bytes) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function mergeActorRequestMetadata(metadata, deadlineUnixMs) {
+    if (deadlineUnixMs === undefined)
+        return metadata;
+    const merged = new Map(metadata);
+    for (const [key, value] of (0, protocol_1.actorRequestDeadlineMetadata)(deadlineUnixMs)) {
+        merged.set(key, value);
+    }
+    return merged;
+}
+class DefaultZLinkActorSendCall {
+    submitter;
+    message;
+    packet;
+    selectedMetadata = new Map();
+    executed = false;
+    constructor(submitter, message) {
+        this.submitter = submitter;
+        this.message = message;
+    }
+    packetName(packetName) {
+        this.packet = packetName;
+        return this;
+    }
+    metadata(key, value) {
+        this.selectedMetadata.set(key, value);
+        return this;
+    }
+    async submit(signal) {
+        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);
+        (0, submission_result_1.requireOneWayCompletion)(result, 'Actor send', framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound);
+    }
+}
+class DefaultZLinkActorRequestCall {
+    asyncSubmitter;
+    yieldSubmitter;
+    targetActorId;
+    request;
+    defaultRequestTimeoutMs;
+    packet;
+    timeoutMs;
+    executed = false;
+    selectedMetadata = new Map();
+    turn = (0, execution_1.captureZLinkSpotSerialTurn)();
+    constructor(asyncSubmitter, yieldSubmitter, targetActorId, request, defaultRequestTimeoutMs) {
+        this.asyncSubmitter = asyncSubmitter;
+        this.yieldSubmitter = yieldSubmitter;
+        this.targetActorId = targetActorId;
+        this.request = request;
+        this.defaultRequestTimeoutMs = defaultRequestTimeoutMs;
+    }
+    packetName(packetName) {
+        this.packet = packetName;
+        return this;
+    }
+    metadata(key, value) {
+        this.selectedMetadata.set(key, value);
+        return this;
+    }
+    timeout(timeoutMs) {
+        this.timeoutMs = timeoutMs;
+        return this;
+    }
+    submit(signal) {
+        return this.execute('async', signal);
+    }
+    yield(signal) {
+        this.rejectSelfActorRequest();
+        const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
+        const pending = this.execute('yield', signal);
+        return turn.yieldPromise(pending);
+    }
+    execute(waitPolicy, signal) {
+        ensureSingleSubmit(this.executed);
+        this.rejectSelfActorRequest();
+        this.executed = true;
+        (0, abort_1.throwIfAborted)(signal);
+        const submitter = waitPolicy === 'async'
+            ? this.asyncSubmitter
+            : this.yieldSubmitter;
+        return submitter(this.packet ?? (0, packet_name_1.resolveFrameworkPacketName)(this.request, undefined, 'Actor'), this.timeoutMs ?? this.defaultRequestTimeoutMs, this.selectedMetadata, signal);
+    }
+    rejectSelfActorRequest() {
+        const current = (0, actor_execution_context_1.currentZLinkActorExecution)();
+        if (current?.actorId !== this.targetActorId)
+            return;
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Actor '${this.targetActorId}' cannot request itself while retaining its Actor FIFO claim.`);
+    }
+}
+function sameSpotRoute(sourceSpotId, route) {
+    const targetSpotId = route.enclosingSpotRoute?.spotId ?? route.spotId;
+    return targetSpotId !== undefined
+        && String(sourceSpotId) === String(targetSpotId);
+}
+function decodeActorReply(reply, serializers, packetName) {
+    try {
+        if (reply.length === 1) {
+            const frame = (0, protocol_1.tryDecodeStreamFrame)(reply[0].data());
+            if (frame !== undefined) {
+                const header = (0, protocol_1.decodeStreamHeader)(frame.header);
+                const payload = runtime_message_1.ZLinkBufferMessage.from(frame.payload);
+                try {
+                    return decodeActorReplyPayload(header.kind, payload, serializers, packetName);
+                }
+                finally {
+                    payload.close();
+                }
+            }
+        }
+        if (reply.length >= 2) {
+            const header = (0, protocol_1.decodeStreamHeader)(reply[0].data());
+            return decodeActorReplyPayload(header.kind, reply[1], serializers, packetName);
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, 'Actor request reply is empty.');
+    }
+    finally {
+        closeMessages(reply);
+    }
+}
+function closeMessages(parts) {
+    for (const part of parts)
+        part.close();
+}
+function decodeActorReplyPayload(kind, payload, serializers, packetName) {
+    if (kind === protocol_1.ZLinkStreamMessageKind.Error) {
+        const error = (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload, serializers);
+        const wireKind = error.kind;
+        const publicKind = typeof wireKind === 'number'
+            && Number.isInteger(wireKind)
+            && wireKind >= contracts_2.ZLinkFrameworkErrorKind.NotFound
+            && wireKind <= contracts_2.ZLinkFrameworkErrorKind.InternalFailure
+            ? wireKind
+            : contracts_2.ZLinkFrameworkErrorKind.InternalFailure;
+        throw new contracts_2.ZLinkFrameworkException(publicKind, error.message ?? 'Actor request failed.');
+    }
+    return (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload, serializers, undefined, 'application/json', packetName, 'reply');
+}
+function mapSubmitError(error, operationName) {
+    if (error instanceof contracts_2.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 CapacityExceeded. 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:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded;
+        case runtime_values_1.RequestResult.NotFound:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound;
+        case runtime_values_1.RequestResult.Terminated:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown;
+        case runtime_values_1.RequestResult.ProtocolError:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError;
+        case runtime_values_1.RequestResult.Rejected:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected;
+        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).
+        case runtime_values_1.RequestResult.Conflict:
+        case runtime_values_1.RequestResult.Busy:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale;
+        default:
+            return framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
+    }
+}
+function mapRequestResult(result, failureErrno, operationName) {
+    const kind = actorFailureCodeKind(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
+        && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale;
+}
+function actorLocationStale(actorId, cause) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor route '${actorId}' is stale after re-resolve.`, true, cause);
+}
+function ensureSingleSubmit(executed) {
+    if (executed) {
+        (0, submission_result_1.throwAlreadySubmitted)('Actor client call');
+    }
+}

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

@@ -0,0 +1,26 @@
+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 { ZLINK_ACTOR_LIFECYCLE_SNAPSHOT, type ZLinkActorLifecycleSnapshotSource } from './actor-lifecycle-snapshot';
+export declare const ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME: unique symbol;
+export declare class DefaultZLinkActorContext implements ZLinkActorContext {
+    private readonly state;
+    private readonly joinCoordinator;
+    private readonly messageSerializers;
+    private readonly meshNameProvider;
+    readonly boundSession: ZLinkBoundSession;
+    private resolvedMeshName;
+    constructor(state: ZLinkActorRuntimeState, joinCoordinator: ZLinkActorJoinCoordinator | undefined, boundSessionFactory: ZLinkActorBoundSessionFactory | undefined, messageSerializers: ReadonlyMap<string, ZLinkMessageSerializer> | undefined, meshNameProvider: ZLinkActorManagerOptions['actorMeshNameProvider']);
+    get meshName(): string;
+    get actorId(): string;
+    get objectGeneration(): bigint;
+    get spotId(): SpotId | undefined;
+    [ZLINK_ACTOR_LIFECYCLE_SNAPSHOT](): ZLinkActorLifecycleSnapshotSource;
+    joinSpot(spotId: SpotId, request?: unknown): ZLinkActorJoinSpotCall;
+    joinEntrySpot(request?: unknown): ZLinkActorJoinEntrySpotCall;
+    [ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME](nodeRid: RoutingId | undefined, request: unknown, signal?: AbortSignal): Promise<boolean>;
+    private requireActor;
+    private requireJoinCoordinator;
+}