@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-route-replies.d.ts

@@ -0,0 +1,17 @@
+import type { ZLinkBackendMessageLike as MessageLike, ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import { decodeChannelEnvelope } from '../channels/channel-envelope';
+import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
+import type { ZLinkDecodedRemoteActorJoinRequest } from './spot-remote-codec';
+export interface ZLinkRouteReplySubmitOperation {
+    message(message: MessageLike): ZLinkRouteReplySubmitOperation;
+    submit(): void;
+}
+export declare function submitRouteReply(operation: ZLinkRouteReplySubmitOperation): boolean;
+export declare function submitRoutePayloadReply(received: BackendReceived, envelope: ReturnType<typeof decodeChannelEnvelope> | undefined, payload: unknown): boolean;
+export declare function submitSpotRouteBridgeReply(received: BackendReceived, envelope: ReturnType<typeof decodeChannelEnvelope> | undefined, payload: Parameters<typeof encodeSpotRouteBridgeReply>[0]): boolean;
+export declare function submitRoutedActorJoinReply(received: BackendReceived, decoded: ZLinkDecodedRemoteActorJoinRequest, payload: unknown): boolean;
+export declare function submitRoutedActorJoinError(received: BackendReceived, decoded: ZLinkDecodedRemoteActorJoinRequest, error: unknown): boolean;
+export declare function appendRouteReplyParts(operation: {
+    message(message: MessageLike): ZLinkRouteReplySubmitOperation;
+}, parts: readonly MessageLike[]): ZLinkRouteReplySubmitOperation;
+export declare function hasReplyToken(replyToken: unknown | null): boolean;

package/dist/runtime/spots/spot-route-replies.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitRouteReply = submitRouteReply;
+exports.submitRoutePayloadReply = submitRoutePayloadReply;
+exports.submitSpotRouteBridgeReply = submitSpotRouteBridgeReply;
+exports.submitRoutedActorJoinReply = submitRoutedActorJoinReply;
+exports.submitRoutedActorJoinError = submitRoutedActorJoinError;
+exports.appendRouteReplyParts = appendRouteReplyParts;
+exports.hasReplyToken = hasReplyToken;
+const channel_envelope_1 = require("../channels/channel-envelope");
+const configuration_1 = require("../configuration");
+const spot_route_reply_wire_1 = require("./spot-route-reply-wire");
+function submitRouteReply(operation) {
+    try {
+        operation.submit();
+        return true;
+    }
+    catch (error) {
+        if (isNativeBadAddress(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function submitRoutePayloadReply(received, envelope, payload) {
+    if (envelope === undefined) {
+        return submitRouteReply(received.reply()
+            .message(Buffer.from(JSON.stringify(payload))));
+    }
+    return submitRouteReply(appendRouteReplyParts(received.reply(), (0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, payload)));
+}
+function submitSpotRouteBridgeReply(received, envelope, payload) {
+    return submitRoutePayloadReply(received, envelope, (0, spot_route_reply_wire_1.encodeSpotRouteBridgeReply)(payload));
+}
+function submitRoutedActorJoinReply(received, decoded, payload) {
+    if (decoded.raw) {
+        return submitRouteReply(received.reply()
+            .message(Buffer.from(JSON.stringify(payload))));
+    }
+    return submitRouteReply(appendRouteReplyParts(received.reply(), (0, channel_envelope_1.encodeChannelReplyParts)(requireRoutedActorJoinEnvelope(decoded).header, payload)));
+}
+function submitRoutedActorJoinError(received, decoded, error) {
+    if (decoded.raw) {
+        return submitRoutedActorJoinReply(received, decoded, {
+            accepted: false,
+            actorNodeRid: '',
+            actorId: decoded.actorId,
+            actorGeneration: '0'
+        });
+    }
+    return submitRouteReply(appendRouteReplyParts(received.reply(), (0, channel_envelope_1.encodeChannelErrorReplyParts)(requireRoutedActorJoinEnvelope(decoded).header, error instanceof Error ? error.message : String(error))));
+}
+function appendRouteReplyParts(operation, parts) {
+    if (parts.length === 0) {
+        throw new configuration_1.ZLinkConfigurationException('Spot route reply must contain at least one part.');
+    }
+    let current = operation.message(parts[0]);
+    for (let index = 1; index < parts.length; index++) {
+        current = current.message(parts[index]);
+    }
+    return current;
+}
+function hasReplyToken(replyToken) {
+    return replyToken !== null;
+}
+function requireRoutedActorJoinEnvelope(decoded) {
+    if (decoded.envelope === undefined) {
+        throw new configuration_1.ZLinkConfigurationException('Routed actor join channel envelope is missing.');
+    }
+    return decoded.envelope;
+}
+function isNativeBadAddress(error) {
+    return typeof error === 'object' &&
+        error !== null &&
+        Number(error.nativeErrno) === 14;
+}

package/dist/runtime/spots/spot-route-reply-wire.d.ts

@@ -0,0 +1,10 @@
+import type { ZLinkRemoteActorPacketTargetWire } from '../actors/actor-packet-relay-wire';
+export interface ZLinkSpotRouteBridgeReplyPayload {
+    readonly ok: boolean;
+    readonly response?: unknown;
+    readonly error?: unknown;
+    readonly errorKind?: unknown;
+    readonly deferredResponse?: boolean;
+    readonly actorPacketTarget?: ZLinkRemoteActorPacketTargetWire;
+}
+export declare function encodeSpotRouteBridgeReply(payload: ZLinkSpotRouteBridgeReplyPayload): ZLinkSpotRouteBridgeReplyPayload;

package/dist/runtime/spots/spot-route-reply-wire.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSpotRouteBridgeReply = encodeSpotRouteBridgeReply;
+function encodeSpotRouteBridgeReply(payload) {
+    return payload;
+}

package/dist/runtime/spots/spot-routed-actor-admission.d.ts

@@ -0,0 +1,36 @@
+import type { ZLinkActor, ZLinkMessage, ZLinkMessageSerializer, ZLinkSpotActorJoinResult } from '../../contracts';
+import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import { type ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+interface ZLinkRoutedActorAdmissionTarget {
+    onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
+}
+interface ZLinkSpotRoutedActorAdmissionOptions {
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly getTarget: () => ZLinkRoutedActorAdmissionTarget;
+    readonly defaultAccept: boolean;
+    readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
+    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[]) => Promise<readonly ZLinkActorHandoffResult[]>;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly pendingAdmissionTimeoutMs?: number;
+    /** Spec 27 §4: with tracing Off, inbound flow fields are neither validated nor carried forward. */
+    readonly flowEnabled?: () => boolean;
+}
+export declare class ZLinkSpotRoutedActorAdmission {
+    private readonly options;
+    private readonly pending;
+    constructor(options: ZLinkSpotRoutedActorAdmissionOptions);
+    admit(received: BackendReceived): Promise<boolean>;
+    private admitTransfer;
+    private commitTransfer;
+    private evaluateAdmission;
+    private evaluateCommit;
+    private runJoinCallback;
+    private requireMatchingTransfer;
+    private scheduleExpiration;
+    private closeDecoded;
+    private decodeRemoteActorJoinRequest;
+    private channelCodecs;
+}
+export {};

package/dist/runtime/spots/spot-routed-actor-admission.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotRoutedActorAdmission = void 0;
+const runtime_message_1 = require("../backend/runtime-message");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const payload_codec_1 = require("../messaging/payload-codec");
+const routing_id_1 = require("../routing-id");
+const spot_remote_codec_1 = require("./spot-remote-codec");
+const spot_route_replies_1 = require("./spot-route-replies");
+class ZLinkSpotRoutedActorAdmission {
+    options;
+    pending = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async admit(received) {
+        if (received.replyToken === null) {
+            return false;
+        }
+        const decoded = this.decodeRemoteActorJoinRequest(received.parts, received);
+        if (decoded === undefined) {
+            return false;
+        }
+        if (decoded.phase === 'admission') {
+            await this.admitTransfer(decoded, received);
+            return true;
+        }
+        if (decoded.phase === 'commit') {
+            await this.commitTransfer(decoded, received);
+            return true;
+        }
+        try {
+            (0, spot_route_replies_1.submitRoutedActorJoinError)(received, decoded, new Error('Remote actor join requires admission and commit phases.'));
+        }
+        finally {
+            this.closeDecoded(decoded);
+        }
+        return true;
+    }
+    async admitTransfer(decoded, received) {
+        try {
+            if (decoded.transferId === undefined) {
+                throw new Error('Remote actor transfer admission requires a transfer id.');
+            }
+            const existing = this.pending.get(decoded.transferId);
+            if (existing !== undefined) {
+                this.requireMatchingTransfer(existing, decoded);
+                const reply = existing.admissionReply ?? await existing.admissionTask;
+                if (reply === undefined)
+                    throw new Error(`Remote actor transfer '${decoded.transferId}' has no admission result.`);
+                (0, spot_route_replies_1.submitRoutedActorJoinReply)(received, decoded, reply);
+                return;
+            }
+            const pending = {
+                actorId: decoded.actorId,
+                actorType: decoded.actorType,
+                phase: 'admitting'
+            };
+            this.pending.set(decoded.transferId, pending);
+            pending.admissionTask = this.evaluateAdmission(decoded, pending);
+            const admissionReply = await pending.admissionTask;
+            (0, spot_route_replies_1.submitRoutedActorJoinReply)(received, decoded, admissionReply);
+        }
+        catch (error) {
+            (0, spot_route_replies_1.submitRoutedActorJoinError)(received, decoded, error);
+        }
+        finally {
+            this.closeDecoded(decoded);
+        }
+    }
+    async commitTransfer(decoded, received) {
+        try {
+            const transferId = decoded.transferId;
+            if (transferId === undefined) {
+                throw new Error('Remote actor transfer commit requires a transfer id.');
+            }
+            const pending = this.pending.get(transferId);
+            if (pending === undefined || pending.actorId !== decoded.actorId || pending.actorType !== decoded.actorType) {
+                throw new Error(`Remote actor transfer '${transferId}' does not have a matching admission.`);
+            }
+            if (pending.phase === 'rejected') {
+                throw new Error(`Remote actor transfer '${transferId}' admission was rejected.`);
+            }
+            if (pending.commitTask === undefined) {
+                if (pending.phase !== 'admitted') {
+                    throw new Error(`Remote actor transfer '${transferId}' is not ready to commit.`);
+                }
+                pending.phase = 'committing';
+                if (pending.deadline !== undefined)
+                    clearTimeout(pending.deadline);
+                pending.commitTask = this.evaluateCommit(decoded, transferId, pending);
+            }
+            const commitReply = pending.commitReply ?? await pending.commitTask;
+            (0, spot_route_replies_1.submitRoutedActorJoinReply)(received, decoded, commitReply);
+        }
+        catch (error) {
+            (0, spot_route_replies_1.submitRoutedActorJoinError)(received, decoded, error);
+        }
+        finally {
+            this.closeDecoded(decoded);
+        }
+    }
+    async evaluateAdmission(decoded, pending) {
+        try {
+            const response = await this.runJoinCallback(decoded, decoded.request);
+            const reply = response.reply === undefined
+                ? undefined
+                : (0, payload_codec_1.encodeFrameworkPayloadMessage)(response.reply, this.options.messageSerializers);
+            try {
+                const actorRef = decoded.actorRef;
+                const admissionReply = {
+                    accepted: response.accepted,
+                    actorNodeRid: String(actorRef?.nodeRid ?? ''),
+                    actorNodeRidHex: actorRef?.nodeRid === undefined ? undefined : (0, routing_id_1.routingIdWireHex)(actorRef.nodeRid),
+                    actorId: decoded.actorId,
+                    actorGeneration: (actorRef?.generation ?? 0n).toString(),
+                    reply: reply?.data().toString('base64')
+                };
+                pending.phase = response.accepted ? 'admitted' : 'rejected';
+                pending.admissionReply = admissionReply;
+                this.scheduleExpiration(decoded.transferId, pending);
+                return admissionReply;
+            }
+            finally {
+                reply?.close();
+            }
+        }
+        catch (error) {
+            this.scheduleExpiration(decoded.transferId, pending);
+            throw error;
+        }
+    }
+    async evaluateCommit(decoded, transferId, pending) {
+        try {
+            if (decoded.transferState === undefined || this.options.routedActorTransferProvider === undefined) {
+                throw new Error('Remote actor transfer commit cannot materialize the target actor.');
+            }
+            const { actor, actorRef } = await this.options.routedActorTransferProvider(decoded.actorId, decoded.actorType, decoded.transferAdapterKey, decoded.transferState, decoded.actorEntryNodeRid, decoded.remoteBoundSessionTarget);
+            const handoffResults = await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog) ?? [];
+            const commitReply = {
+                accepted: true,
+                actorNodeRid: String(actorRef.nodeRid),
+                actorNodeRidHex: (0, routing_id_1.routingIdWireHex)(actorRef.nodeRid),
+                actorId: actorRef.actorId,
+                actorGeneration: actorRef.generation.toString(),
+                handoffResults
+            };
+            pending.phase = 'committed';
+            pending.commitReply = commitReply;
+            this.scheduleExpiration(transferId, pending);
+            return commitReply;
+        }
+        catch (error) {
+            this.scheduleExpiration(transferId, pending);
+            throw error;
+        }
+    }
+    runJoinCallback(decoded, request) {
+        const target = this.options.getTarget();
+        const joinPayload = (0, payload_codec_1.wrapFrameworkPayloadMessage)(request, this.options.messageSerializers, decoded.requestContentType);
+        const actorRef = decoded.actorRef;
+        if (actorRef === undefined) {
+            // The commit half of the routed transfer materializes the Actor from this
+            // ActorRef, so a request without one is rejected before admission runs
+            // rather than after the application already accepted it.
+            throw new Error(`Remote actor '${decoded.actorId}' join identity is missing its ActorRef.`);
+        }
+        return this.options.serial.execute(async () => this.options.defaultAccept || target.onActorJoin === undefined
+            ? { accepted: this.options.defaultAccept }
+            : target.onActorJoin(actorRef.actorId, joinPayload));
+    }
+    requireMatchingTransfer(pending, decoded) {
+        if (pending.actorId !== decoded.actorId || pending.actorType !== decoded.actorType) {
+            throw new Error(`Remote actor transfer '${decoded.transferId}' identity does not match its first request.`);
+        }
+    }
+    scheduleExpiration(transferId, pending) {
+        if (pending.deadline !== undefined)
+            clearTimeout(pending.deadline);
+        pending.deadline = setTimeout(() => {
+            if (this.pending.get(transferId) === pending)
+                this.pending.delete(transferId);
+        }, this.options.pendingAdmissionTimeoutMs ?? 30_000);
+        pending.deadline.unref();
+    }
+    closeDecoded(decoded) {
+        decoded.request.close();
+        decoded.actorCreateRequest?.close();
+        decoded.transferState?.close();
+    }
+    decodeRemoteActorJoinRequest(parts, received) {
+        if (parts.length < 2 || parts[0].data().length === 0) {
+            if (parts.length !== 1 || parts[0].data().length === 0) {
+                return undefined;
+            }
+            try {
+                const payload = JSON.parse(parts[0].data().toString());
+                if (payload.packetName !== spot_remote_codec_1.REMOTE_ACTOR_JOIN_PACKET ||
+                    !(0, spot_remote_codec_1.isRemoteActorJoinPayload)(payload)) {
+                    return undefined;
+                }
+                return (0, spot_remote_codec_1.decodeRemoteActorJoinPayload)(payload, runtime_message_1.ZLinkBufferMessage.from(Buffer.from(payload.request, 'base64')), received, true);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        try {
+            const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(parts, undefined, this.options.flowEnabled?.() ?? true);
+            if (envelope.packetName !== spot_remote_codec_1.REMOTE_ACTOR_JOIN_PACKET) {
+                return undefined;
+            }
+            const payload = (0, channel_envelope_1.decodeChannelPayload)(envelope, this.channelCodecs());
+            if (!(0, spot_remote_codec_1.isRemoteActorJoinPayload)(payload)) {
+                return undefined;
+            }
+            return (0, spot_remote_codec_1.decodeRemoteActorJoinPayload)(payload, runtime_message_1.ZLinkBufferMessage.from(Buffer.from(payload.request, 'base64')), received, false, envelope);
+        }
+        catch {
+            try {
+                const header = JSON.parse(parts[0].data().toString());
+                if (header.packetName !== spot_remote_codec_1.REMOTE_ACTOR_JOIN_PACKET ||
+                    !(0, spot_remote_codec_1.hasRemoteActorJoinIdentity)(header) ||
+                    parts.length < 2) {
+                    return undefined;
+                }
+                return (0, spot_remote_codec_1.decodeRemoteActorJoinPayload)(header, runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(parts[1].data())), received, true);
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    channelCodecs() {
+        return this.options.messageSerializers === undefined
+            ? undefined
+            : { serializers: this.options.messageSerializers };
+    }
+}
+exports.ZLinkSpotRoutedActorAdmission = ZLinkSpotRoutedActorAdmission;

package/dist/runtime/spots/spot-routed-bound-session-dispatch.d.ts

@@ -0,0 +1,19 @@
+import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import type { ActorRef } from '../../contracts';
+import type { ZLinkChannelEnvelopeCodecRegistry } from '../channels/channel-envelope';
+import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+interface ZLinkSpotRoutedBoundSessionDispatchOptions {
+    readonly channelCodecs: () => ZLinkChannelEnvelopeCodecRegistry | undefined;
+    readonly routedBoundSessionReceiver?: (actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, actorRef?: ActorRef, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
+    readonly routedBoundSessionResponseReceiver?: (actorId: string, packetName: string, requestSeq: bigint, message: unknown, replyOptions: ZLinkActorResponseOptions, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
+    readonly routedBoundSessionErrorReceiver?: (actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+}
+export declare class ZLinkSpotRoutedBoundSessionDispatch {
+    private readonly options;
+    constructor(options: ZLinkSpotRoutedBoundSessionDispatchOptions);
+    dispatch(received: BackendReceived): Promise<boolean>;
+    private replyOk;
+}
+export {};

package/dist/runtime/spots/spot-routed-bound-session-dispatch.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotRoutedBoundSessionDispatch = void 0;
+const spot_remote_route_codec_1 = require("./spot-remote-route-codec");
+const spot_route_replies_1 = require("./spot-route-replies");
+const flow_context_1 = require("../diagnostics/flow-context");
+class ZLinkSpotRoutedBoundSessionDispatch {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async dispatch(received) {
+        const boundSessionSend = (0, spot_remote_route_codec_1.decodeRemoteBoundSessionSend)(received.parts, this.options.channelCodecs(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        if (boundSessionSend !== undefined) {
+            await (0, flow_context_1.runWithFlow)((0, flow_context_1.createInboundFlow)(boundSessionSend.flowId ?? boundSessionSend.envelope?.header.flowId, boundSessionSend.flowOrigin ?? boundSessionSend.envelope?.header.flowOrigin, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true), () => this.options.routedBoundSessionReceiver?.(boundSessionSend.actorId, boundSessionSend.message, boundSessionSend.packetName, boundSessionSend.metadata, boundSessionSend.actorRef, boundSessionSend.actorPacketTarget));
+            if ((0, spot_route_replies_1.hasReplyToken)(received.replyToken)) {
+                (0, spot_route_replies_1.submitRoutePayloadReply)(received, boundSessionSend.envelope, { ok: true });
+            }
+            return true;
+        }
+        const boundSessionResponse = (0, spot_remote_route_codec_1.decodeRemoteBoundSessionResponse)(received.parts, this.options.channelCodecs(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        if (boundSessionResponse !== undefined) {
+            await this.options.routedBoundSessionResponseReceiver?.(boundSessionResponse.actorId, boundSessionResponse.packetName, boundSessionResponse.requestSeq, boundSessionResponse.message, {
+                metadata: boundSessionResponse.metadata,
+                compressPayload: boundSessionResponse.compressPayload
+            }, boundSessionResponse.actorPacketTarget);
+            this.replyOk(received);
+            return true;
+        }
+        const boundSessionError = (0, spot_remote_route_codec_1.decodeRemoteBoundSessionError)(received.parts, this.options.channelCodecs(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        if (boundSessionError !== undefined) {
+            await this.options.routedBoundSessionErrorReceiver?.(boundSessionError.actorId, boundSessionError.packetName, boundSessionError.requestSeq, boundSessionError.error, boundSessionError.metadata, boundSessionError.actorPacketTarget);
+            this.replyOk(received);
+            return true;
+        }
+        return false;
+    }
+    replyOk(received) {
+        if (!(0, spot_route_replies_1.hasReplyToken)(received.replyToken)) {
+            return;
+        }
+        (0, spot_route_replies_1.submitRouteReply)(received.reply()
+            .message(Buffer.from(JSON.stringify({ ok: true }))));
+    }
+}
+exports.ZLinkSpotRoutedBoundSessionDispatch = ZLinkSpotRoutedBoundSessionDispatch;

package/dist/runtime/spots/spot-routed-frame-dispatch.d.ts

@@ -0,0 +1,54 @@
+import type { ZLinkActor, ZLinkMessage, ZLinkMessageSerializer, ZLinkSpot, ZLinkSpotActorJoinResult } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { RoutingId } from '../../contracts';
+import type { ActorRef } from '../../contracts/Common/ActorRef';
+import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkBackendReceived, ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkActorPacketDelivery, ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
+import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import type { ZLinkApplicationWorkClaim } from '../admission';
+import type { ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+interface ZLinkRoutedFrameAdmissionTarget {
+    onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
+}
+interface ZLinkSpotRoutedFrameDispatchOptions {
+    readonly nativeSpot: ZLinkBackendSpot;
+    readonly createReceived: () => ZLinkBackendReceived;
+    readonly nativeSpotId: string;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
+    readonly getTarget: () => ZLinkRoutedFrameAdmissionTarget & ZLinkSpot;
+    readonly defaultAccept: boolean;
+    readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
+    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[]) => Promise<readonly ZLinkActorHandoffResult[]>;
+    readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
+    readonly routedBoundSessionReceiver?: (actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, actorRef?: ActorRef, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
+    readonly routedBoundSessionResponseReceiver?: (actorId: string, packetName: string, requestSeq: bigint, message: unknown, replyOptions: ZLinkActorResponseOptions, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
+    readonly routedBoundSessionErrorReceiver?: (actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
+    readonly actorPacketTargetProvider?: (actorId: string) => ZLinkRemoteActorPacketTarget | undefined;
+    readonly bindRemoteSession?: (actor: ActorRef, sourceNodeRid: RoutingId, sourceSessionRid: RoutingId, declaredTarget?: ZLinkRemoteBoundSessionTarget) => void;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
+    readonly waitIdle: () => Promise<void>;
+}
+export declare class ZLinkSpotRoutedFrameDispatch {
+    private readonly options;
+    private routeDraining;
+    private readonly packetHandlers;
+    private readonly routedBoundSessionDispatch;
+    private readonly actorPacketRelayDispatch;
+    private readonly routePacketDispatch;
+    private readonly routedActorAdmission;
+    constructor(options: ZLinkSpotRoutedFrameDispatchOptions);
+    configurePacketHandlers(registrations: readonly ZLinkSpotHandlerRegistration[]): void;
+    drain(received?: ZLinkBackendReceived | undefined, retryDeadlineMs?: number): Promise<void>;
+    dispatchFromEvent(received: ZLinkBackendReceived): Promise<void>;
+    private channelCodecs;
+    private dispatch;
+}
+export {};