@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-actor-membership.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorMembership = void 0;
+const contracts_1 = require("../../contracts");
+const abort_1 = require("../abort");
+const runtime_message_1 = require("../backend/runtime-message");
+const configuration_1 = require("../configuration");
+const actors_1 = require("../actors");
+const payload_codec_1 = require("../messaging/payload-codec");
+const routing_id_1 = require("../routing-id");
+class ZLinkSpotActorMembership {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType = 'application/json') {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.requireActivation(spotId);
+        const dispatcher = this.createActorDispatcher(activation);
+        const transaction = { committed: false };
+        let response;
+        try {
+            response = await dispatcher.evaluateActorJoin(actor, request, contentType);
+            if (response.accepted) {
+                if (leaveSource === undefined) {
+                    await this.options.entrySpotCallbacks?.onLeaveActor(actor, signal);
+                }
+                else {
+                    await leaveSource();
+                }
+                await dispatcher.commitActorJoin(actor, async () => {
+                    const rollback = await commit(activation.spot);
+                    if (rollback !== undefined)
+                        transaction.rollbackExternal = rollback;
+                    transaction.rollbackMembership = activation.commitActorJoin(actor);
+                    transaction.committed = true;
+                });
+            }
+        }
+        catch (error) {
+            if (transaction.committed) {
+                transaction.rollbackMembership?.();
+                await transaction.rollbackExternal?.();
+            }
+            throw error;
+        }
+        return {
+            accepted: response.accepted,
+            reply: response.reply === undefined
+                ? undefined
+                : (0, payload_codec_1.encodeFrameworkPayloadMessage)(response.reply, this.options.messageSerializers)
+        };
+    }
+    async leaveActor(spotId, actor, signal, meshName) {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.requireActivation(spotId, meshName);
+        const localEntryNodeRid = (meshName === undefined ? undefined : this.options.nodeRidProvider?.(meshName)) ??
+            this.options.entryNodeRidProvider?.() ??
+            this.options.entryNodeRid ??
+            this.options.nodeRid;
+        const entrySpotId = meshName === undefined
+            ? undefined
+            : this.options.entrySpotIdProvider?.(meshName);
+        const resolvedEntry = entrySpotId === undefined
+            ? undefined
+            : await this.options.spotRouteResolver?.resolve(entrySpotId, signal);
+        const entryNodeRid = resolvedEntry?.targetNodeRid ??
+            this.options.actorTransferRuntime?.actorEntryNodeRid(actor) ??
+            localEntryNodeRid;
+        if (entryNodeRid === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Spot actor leave requires an Entry Spot node routing id.');
+        }
+        const remoteEntry = localEntryNodeRid !== undefined && !(0, routing_id_1.routingIdsEqual)(entryNodeRid, localEntryNodeRid);
+        if (!remoteEntry) {
+            const leaveSource = async () => {
+                activation.beginActorTransfer(actor.context.actorId);
+                await activation.spot.onLeaveActor(actor);
+                activation.commitActorDeparture(actor.context.actorId);
+                this.options.actorTransferRuntime?.clearRoutedActor(actor);
+            };
+            // A Spot actor handler already owns this activation's serial turn.
+            // Complete its lifecycle transition inside that turn instead of trying
+            // to acquire a second turn for the same owner.
+            if (activation.serial.isCurrentTurn) {
+                await leaveSource();
+            }
+            else {
+                await activation.serial.execute(leaveSource);
+            }
+        }
+        const request = runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0));
+        try {
+            const context = actor.context;
+            const joinEntry = context[actors_1.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME](entryNodeRid, contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(request.data())), signal);
+            // An Actor request may leave its Spot before producing its terminal
+            // response.  Rejoining Entry can require control work that is queued
+            // behind this Spot turn, so retain the request's turn identity but yield
+            // the gate while that Framework operation is in flight.
+            const turn = activation.serial.currentTurn;
+            if (turn !== undefined) {
+                await turn.yieldFrameworkPromise(joinEntry);
+            }
+            else {
+                await joinEntry;
+            }
+        }
+        finally {
+            request.close();
+        }
+    }
+    async notifyActorLeftAfterTransfer(spotId, actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.requireActivation(spotId);
+        await activation.serial.execute(async () => {
+            activation.beginActorTransfer(actor.context.actorId);
+            await activation.spot.onLeaveActor(actor);
+            activation.commitActorDeparture(actor.context.actorId);
+        });
+    }
+    async prepareActorLeaveForTransfer(spotId, actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.requireActivation(spotId);
+        await activation.serial.execute(() => activation.spot.onLeaveActor(actor));
+    }
+    async commitActorLeaveAfterTransfer(spotId, actorId) {
+        const activation = this.requireActivation(spotId);
+        await activation.serial.execute(() => activation.commitActorDeparture(actorId));
+    }
+    async restoreActorAfterFailedTransfer(spotId, actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.requireActivation(spotId);
+        await activation.serial.execute(async () => {
+            activation.cancelActorTransfer(actor.context.actorId);
+            await activation.spot.onJoinedActor(actor);
+        });
+    }
+    async beginActorTransfer(spotId, actorId) {
+        const activation = this.requireActivation(spotId);
+        await activation.serial.execute(() => {
+            activation.beginActorTransfer(actorId);
+        });
+    }
+    async cancelActorTransfer(spotId, actorId) {
+        const activation = this.requireActivation(spotId);
+        await activation.serial.execute(() => {
+            activation.cancelActorTransfer(actorId);
+        });
+    }
+    async notifyJoinedActorDisconnected(spotId, actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.options.resolveActivation(spotId);
+        if (activation === undefined) {
+            return false;
+        }
+        const joinedActor = activation.resolveJoinedActor(actor.context.actorId);
+        if (joinedActor === undefined) {
+            return false;
+        }
+        await activation.serial.execute(() => activation.spot.onDisconnectActor?.(joinedActor));
+        return true;
+    }
+    requireActivation(spotId, meshName) {
+        const activation = this.options.resolveActivation(spotId, meshName);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
+        }
+        return activation;
+    }
+    createActorDispatcher(activation) {
+        return new actors_1.ZLinkSpotActorDispatcher({
+            registry: activation.actorHandlers,
+            spot: activation.spot,
+            providerResolver: this.options.providerResolver,
+            serial: activation.serial,
+            messageSerializers: this.options.messageSerializers
+        });
+    }
+}
+exports.ZLinkSpotActorMembership = ZLinkSpotActorMembership;

package/dist/runtime/spots/spot-actor-packet-dispatch.d.ts

@@ -0,0 +1,91 @@
+import type { ActorRef, ZLinkActor, ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import { ZLinkSpotActorHandlerRegistryRuntime } from '../actors';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+export interface ZLinkActorResponseOptions {
+    readonly metadata: ReadonlyMap<string, string>;
+    readonly compressPayload: boolean;
+}
+/** Internal two-phase terminal used when a routed request owns the reply. */
+export interface ZLinkActorRequestTerminal {
+    (response: unknown, preparedReply?: unknown): Promise<void> | void;
+    readonly prepare?: (response: unknown) => Promise<unknown> | unknown;
+}
+/** One admitted Actor packet and the routing context that must move with it. */
+export interface ZLinkActorPacketDelivery {
+    readonly actorId: string;
+    readonly parts: readonly Message[];
+    readonly returnResponse: boolean;
+    readonly remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget;
+    readonly fallbackActorRef?: ActorRef;
+    readonly requestTerminal?: ZLinkActorRequestTerminal;
+    readonly messageFollowOrigin?: ZLinkMessageFollowOrigin;
+}
+/**
+ * Spec 15 §4.2 relocation temporary queue: consulted when {@code
+ * resolveActor} finds nothing for an arrival that carries an exact object
+ * identity. Parks the arrival if an Actor Join admission attempt is in
+ * flight for {@code (actorId, objectGeneration)}, or reports not-found so
+ * the caller falls through to its existing missing-actor handling
+ * unchanged.
+ */
+export type ZLinkRouteToActorJoinPrewarm = (actorId: string, objectGeneration: bigint, arrival: {
+    readonly header: Buffer;
+    readonly payload: Buffer;
+    readonly returnResponse: boolean;
+    readonly remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget;
+    readonly fallbackActorRef?: ActorRef;
+    readonly requestTerminal?: ZLinkActorRequestTerminal;
+    readonly resolve: (value: unknown) => void;
+    readonly reject: (reason: unknown) => void;
+}) => 'parked' | 'not-found';
+interface ZLinkSpotActorPacketDispatchOptions {
+    readonly spot: ZLinkSpot | (() => ZLinkSpot);
+    readonly spotId: () => string;
+    readonly registry: ZLinkSpotActorHandlerRegistryRuntime;
+    readonly serial?: ZLinkSpotSerialTurnExecutor;
+    readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
+    readonly actorLeft?: (actorId: string) => boolean;
+    readonly routeBeforeLocal?: (delivery: ZLinkActorPacketDelivery) => Promise<{
+        readonly handled: boolean;
+        readonly response?: unknown;
+    } | undefined> | {
+        readonly handled: boolean;
+        readonly response?: unknown;
+    } | undefined;
+    readonly onRemoteBoundSessionTarget?: (actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined) => void;
+    readonly onDisconnectActor: (actor: ZLinkActor) => Promise<void>;
+    readonly actorResponseSender?: (actor: ZLinkActor, packetName: string, requestSeq: bigint, response: unknown, replyOptions: ZLinkActorResponseOptions, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, signal?: AbortSignal) => Promise<void> | void;
+    readonly actorErrorSender?: (actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef) => Promise<void> | void;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
+}
+export declare class ZLinkSpotActorPacketDispatch {
+    private readonly options;
+    constructor(options: ZLinkSpotActorPacketDispatchOptions);
+    dispatch(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: ZLinkActorRequestTerminal): Promise<unknown>;
+    dispatchDelivery(delivery: ZLinkActorPacketDelivery): Promise<unknown>;
+    private handleMissingActor;
+    /**
+     * Spec 15 §4.2 relocation temporary queue: parks one arrival for a
+     * missing Actor that carries an exact object identity, instead of
+     * dropping it (Send) or replying HandlerNotFound (Request). Returns
+     * {@code undefined} when no admission attempt owns this object — the
+     * caller falls through to its existing missing-actor handling unchanged.
+     * Header/payload are copied to owned buffers before parking so the
+     * arrival survives independently of the original {@link Message}
+     * lifetime.
+     */
+    private parkForActorJoinPrewarm;
+    private createPayloadDecoder;
+    private dispatchActorPacket;
+    private reportInvalidFrame;
+    private trace;
+}
+export {};

package/dist/runtime/spots/spot-actor-packet-dispatch.js

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorPacketDispatch = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const diagnostics_1 = require("../diagnostics");
+const flow_context_1 = require("../diagnostics/flow-context");
+const actors_1 = require("../actors");
+const protocol_1 = require("../streams/protocol");
+const payload_codec_1 = require("../messaging/payload-codec");
+const serial_work_size_1 = require("../execution/serial-work-size");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+class ZLinkSpotActorPacketDispatch {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    dispatch(actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        return this.dispatchDelivery({
+            actorId,
+            parts,
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef,
+            requestTerminal
+        });
+    }
+    async dispatchDelivery(delivery) {
+        const { actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal } = delivery;
+        if (parts.length < 2) {
+            this.reportInvalidFrame(actorId, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend);
+            return undefined;
+        }
+        //  Spec 26 §4.1: one level read per processing point — the same gate value
+        //  drives both the decode and the flow-context install.
+        const flowEnabled = this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true;
+        let header;
+        let requestDeadlineUnixMs;
+        try {
+            header = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(parts[0]), flowEnabled);
+            requestDeadlineUnixMs = header.kind === protocol_1.ZLinkStreamMessageKind.Request
+                ? (0, protocol_1.decodeActorRequestDeadlineUnixMs)((0, protocol_1.messageToBytes)(parts[0]))
+                : undefined;
+        }
+        catch (error) {
+            this.reportInvalidFrame(actorId, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend, error);
+            throw error;
+        }
+        return (0, flow_context_1.runWithFlow)((0, flow_context_1.createInboundFlow)(header.flowId, header.flowOrigin, flowEnabled), async () => {
+            const messageKind = header.kind === protocol_1.ZLinkStreamMessageKind.Request
+                ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest
+                : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend;
+            const action = messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest
+                ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError
+                : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop;
+            this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received, actorId, header, messageKind);
+            if (this.options.actorLeft?.(actorId) === true &&
+                header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+                return undefined;
+            }
+            if (remoteBoundSessionTarget !== undefined
+                && (0, actors_1.actorMessageFollowContext)(fallbackActorRef) === undefined) {
+                // A replayed handoff/Message Follow packet keeps its captured Session
+                // route solely for that packet's response. It cannot republish the
+                // predecessor route over a binding already confirmed by a later Actor
+                // owner turn.
+                this.options.onRemoteBoundSessionTarget?.(actorId, remoteBoundSessionTarget);
+            }
+            const routed = await this.options.routeBeforeLocal?.(delivery);
+            if (routed?.handled === true) {
+                return routed.response;
+            }
+            const actor = this.options.resolveActor(actorId);
+            if (actor === undefined) {
+                return this.handleMissingActor(actorId, parts, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+            }
+            if (header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+                this.options.onRemoteBoundSessionTarget?.(actorId, undefined);
+                await this.options.onDisconnectActor(actor);
+                return undefined;
+            }
+            const decodePayload = this.createPayloadDecoder(parts[1], header);
+            return this.dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, (0, serial_work_size_1.zlinkSerialWorkOptions)(parts[1].data().byteLength, (0, serial_work_size_1.zlinkMetadataByteLength)(header.metadata)));
+        });
+    }
+    async handleMissingActor(actorId, parts, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        if (this.options.routeToActorJoinPrewarm !== undefined
+            && fallbackActorRef !== undefined
+            && parts.length >= 2
+            //  A Request without a terminal has no way to complete once
+            //  migrated later — parking it would leave the caller hanging
+            //  forever with no reply route. Fall through to the existing
+            //  missing-actor handling for that shape instead.
+            && (messageKind !== ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest || requestTerminal !== undefined)) {
+            const parked = this.parkForActorJoinPrewarm(actorId, parts, messageKind, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal);
+            if (parked !== undefined)
+                return parked;
+        }
+        this.options.dispatchErrors?.report({
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+            messageKind,
+            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing,
+            action,
+            packetName: header.name,
+            spotId: this.options.spotId(),
+            actorId,
+            correlationId: header.correlationId ?? header.requestSeq?.toString()
+        });
+        if (messageKind !== ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest) {
+            return undefined;
+        }
+        const missingActorError = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound, `SPOT actor is not registered locally: ${actorId}`);
+        if (header.requestSeq !== undefined && !returnResponse && this.options.actorErrorSender !== undefined) {
+            await this.options.actorErrorSender(actorId, header.name, header.requestSeq, missingActorError, header.metadata, fallbackBoundSessionTarget, fallbackActorRef);
+            return undefined;
+        }
+        throw missingActorError;
+    }
+    /**
+     * Spec 15 §4.2 relocation temporary queue: parks one arrival for a
+     * missing Actor that carries an exact object identity, instead of
+     * dropping it (Send) or replying HandlerNotFound (Request). Returns
+     * {@code undefined} when no admission attempt owns this object — the
+     * caller falls through to its existing missing-actor handling unchanged.
+     * Header/payload are copied to owned buffers before parking so the
+     * arrival survives independently of the original {@link Message}
+     * lifetime.
+     */
+    parkForActorJoinPrewarm(actorId, parts, messageKind, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        const isRequest = messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest;
+        let resolve = () => undefined;
+        let reject = () => undefined;
+        const result = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        //  A Request's real reply must still travel through the exact mailbox
+        //  correlation the original caller captured in `requestTerminal` — not
+        //  through this method's own return value, which the caller only uses
+        //  to decide whether it still owes a reply itself. Wrapping keeps that
+        //  reply route intact across the (possibly much later) redelivery at
+        //  migration time while also releasing the original caller once the
+        //  real reply has gone out, so it never sends a premature empty one.
+        const wrappedRequestTerminal = requestTerminal === undefined
+            ? undefined
+            : Object.assign(async (response, preparedReply) => {
+                try {
+                    await requestTerminal(response, preparedReply);
+                    resolve(undefined);
+                }
+                catch (error) {
+                    reject(error);
+                    throw error;
+                }
+            }, { prepare: requestTerminal.prepare });
+        const route = this.options.routeToActorJoinPrewarm(actorId, fallbackActorRef.objectGeneration, {
+            header: Buffer.from(parts[0].data()),
+            payload: Buffer.from(parts[1].data()),
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef,
+            requestTerminal: wrappedRequestTerminal,
+            resolve,
+            reject
+        });
+        if (route !== 'parked')
+            return undefined;
+        //  A Send has no reply to wait for: the migrated redelivery still runs
+        //  in order later, but this caller's own await is done once parking is
+        //  confirmed.
+        if (!isRequest)
+            resolve(undefined);
+        return result;
+    }
+    createPayloadDecoder(message, header) {
+        return () => (0, payload_codec_1.decodeFrameworkTypedPayloadMessage)(message, this.options.messageSerializers, undefined, (0, protocol_1.streamCodecContentType)(header.codec), header.name);
+    }
+    async dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, workOptions) {
+        const spot = typeof this.options.spot === 'function'
+            ? this.options.spot()
+            : this.options.spot;
+        const dispatcher = new actors_1.ZLinkSpotActorDispatcher({
+            registry: this.options.registry,
+            spot,
+            providerResolver: this.options.providerResolver,
+            serial: this.options.serial,
+            serialWorkOptions: workOptions,
+            messageSerializers: this.options.messageSerializers,
+            onAdmitted: () => this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, actorId, header, messageKind),
+            onHandlerStart: () => {
+                // A transferred backlog is returned to the Actor queue as one FIFO
+                // prefix. Check the request deadline when its owner turn actually
+                // starts, not when that prefix is admitted.
+                if (messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest
+                    && requestDeadlineUnixMs !== undefined
+                    && Date.now() >= requestDeadlineUnixMs) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorId}' expired before handler admission.`);
+                }
+                (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
+                this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, actorId, header, messageKind);
+            }
+        });
+        try {
+            if (header.kind === protocol_1.ZLinkStreamMessageKind.Send) {
+                await dispatcher.dispatchSendDecoded(actor, header.name, decodePayload, {
+                    meshName: spot.context.meshName,
+                    metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
+                    correlationId: header.correlationId ?? undefined
+                });
+                this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend);
+                return undefined;
+            }
+            if (header.kind !== protocol_1.ZLinkStreamMessageKind.Request || header.requestSeq === undefined) {
+                this.options.dispatchErrors?.report({
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+                    messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest,
+                    reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame,
+                    action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                    packetName: header.name,
+                    spotId: this.options.spotId(),
+                    actorId
+                });
+                return undefined;
+            }
+            const requestSeq = header.requestSeq;
+            if (returnResponse && requestTerminal !== undefined) {
+                let preparedReply;
+                let preparedReplyReady = false;
+                await dispatcher.dispatchRequestThenDecoded(actor, header.name, decodePayload, {
+                    meshName: spot.context.meshName,
+                    metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
+                    correlationId: header.correlationId ?? header.requestSeq.toString()
+                }, async (response) => {
+                    this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest);
+                    await requestTerminal(response, preparedReplyReady ? preparedReply : undefined);
+                }, requestTerminal.prepare === undefined
+                    ? undefined
+                    : async (response) => {
+                        preparedReply = await requestTerminal.prepare(response);
+                        preparedReplyReady = true;
+                    });
+                return undefined;
+            }
+            if (returnResponse || this.options.actorResponseSender === undefined) {
+                const response = await dispatcher.dispatchRequestDecoded(actor, header.name, decodePayload, {
+                    meshName: spot.context.meshName,
+                    metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
+                    correlationId: header.correlationId ?? header.requestSeq.toString()
+                });
+                this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest);
+                return response;
+            }
+            await dispatcher.dispatchRequestThenDecoded(actor, header.name, decodePayload, {
+                meshName: spot.context.meshName,
+                metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
+                correlationId: header.correlationId ?? header.requestSeq.toString()
+            }, async (response, replyOptions) => {
+                this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest);
+                await this.options.actorResponseSender?.(actor, header.name, requestSeq, response, replyOptions, fallbackBoundSessionTarget, fallbackActorRef, undefined);
+            });
+            return undefined;
+        }
+        catch (error) {
+            this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+                messageKind,
+                reason: error instanceof contracts_1.ZLinkFrameworkException
+                    && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound
+                    ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing
+                    : error instanceof contracts_1.ZLinkFrameworkException
+                        && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed
+                        ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.PayloadDecodeFailed
+                        : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+                action,
+                packetName: header.name,
+                spotId: this.options.spotId(),
+                actorId,
+                correlationId: header.correlationId ?? header.requestSeq?.toString(),
+                error
+            });
+            if (messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest &&
+                header.requestSeq !== undefined &&
+                !returnResponse &&
+                this.options.actorErrorSender !== undefined) {
+                await this.options.actorErrorSender(actorId, header.name, header.requestSeq, error, header.metadata, fallbackBoundSessionTarget, fallbackActorRef);
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    reportInvalidFrame(actorId, messageKind, error) {
+        this.options.dispatchErrors?.report({
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+            messageKind,
+            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame,
+            action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+            spotId: this.options.spotId(),
+            actorId,
+            error
+        });
+    }
+    trace(outcome, actorId, header, messageKind) {
+        (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, outcome)?.trace({
+            outcome,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+            messageKind,
+            packetName: header.name,
+            spotId: this.options.spotId(),
+            actorId,
+            correlationId: header.correlationId ?? header.requestSeq?.toString()
+        });
+    }
+}
+exports.ZLinkSpotActorPacketDispatch = ZLinkSpotActorPacketDispatch;

package/dist/runtime/spots/spot-actor-packet-drain.d.ts

@@ -0,0 +1,40 @@
+import type { RoutingId, ZLinkMessageSerializer } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import { RequestResult } from '../backend/runtime-values';
+import type { ZLinkBackendActorRef, ZLinkBackendActorRecvInfo } from '../backend/contracts';
+import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
+export interface ZLinkActorDispatchPart {
+    readonly info: {
+        readonly actor: ZLinkBackendActorRef;
+        readonly sourceNodeRid?: RoutingId;
+        readonly sourceSessionRid?: RoutingId;
+        readonly requestId?: bigint;
+        readonly flags?: number;
+    };
+    readonly message: Message;
+    readonly more: boolean;
+}
+interface ZLinkSpotActorPacketDrainOptions {
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
+    readonly bindRemoteActorSession?: (actor: ZLinkBackendActorRef, sourceNodeRid: RoutingId, sourceSessionRid: RoutingId) => void;
+    readonly replyActorNoBind?: (info: ZLinkBackendActorRecvInfo, parts: readonly Message[], result: RequestResult) => void;
+    readonly waitIdle: () => Promise<void>;
+    readonly flowEnabled?: () => boolean;
+}
+export declare class ZLinkSpotActorPacketDrain {
+    private readonly options;
+    private readonly continuations;
+    constructor(options: ZLinkSpotActorPacketDrainOptions);
+    drain(info: {
+        recvActorPart(flags?: number): ZLinkActorDispatchPart | null;
+    }): Promise<void>;
+    dispose(): void;
+    private createNoBindReplyInfo;
+    private isActorRequest;
+    private dispatchNoBindActorRequest;
+    private encodeActorReplyFrame;
+    private consumeRemoteBoundSessionBind;
+    private flowEnabled;
+}
+export {};