@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorPacketDrain = void 0;
+const contracts_1 = require("../../contracts");
+const runtime_message_1 = require("../backend/runtime-message");
+const runtime_values_1 = require("../backend/runtime-values");
+const spot_remote_codec_1 = require("./spot-remote-codec");
+const spot_native_flags_1 = require("./spot-native-flags");
+const protocol_1 = require("../streams/protocol");
+const payload_codec_1 = require("../messaging/payload-codec");
+const ZLINK_SPOT_ACTOR_RECV_INFO_NO_BIND = 1;
+class ZLinkSpotActorPacketDrain {
+    options;
+    continuations = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async drain(info) {
+        const parts = [];
+        let actorId;
+        let actorRef;
+        let sourceNodeRid;
+        let sourceSessionRid;
+        let requestId;
+        let flags;
+        let packetKey;
+        try {
+            for (;;) {
+                const part = info.recvActorPart(spot_native_flags_1.ZLINK_RECV_DONT_WAIT);
+                if (part === null) {
+                    if (parts.length > 0 && packetKey !== undefined) {
+                        this.continuations.set(packetKey, {
+                            owner: continuationOwner(parts[0], this.flowEnabled()),
+                            parts: parts.splice(0)
+                        });
+                        return;
+                    }
+                    await this.options.waitIdle();
+                    return;
+                }
+                const currentPacketKey = actorPacketKey(part);
+                if (packetKey === undefined) {
+                    packetKey = currentPacketKey;
+                    const pending = this.continuations.get(currentPacketKey);
+                    if (pending !== undefined) {
+                        if (isStreamHeaderMessage(part.message, this.flowEnabled())) {
+                            closeMessages(pending.parts);
+                            this.continuations.delete(currentPacketKey);
+                            throw new Error(`Actor packet continuation '${pending.owner}' was replaced before completion.`);
+                        }
+                        this.continuations.delete(currentPacketKey);
+                        parts.push(...pending.parts);
+                    }
+                }
+                else if (packetKey !== currentPacketKey) {
+                    throw new Error('Native actor packet parts changed identity before the final part.');
+                }
+                actorId ??= part.info.actor.actorId;
+                actorRef ??= part.info.actor;
+                sourceNodeRid ??= part.info.sourceNodeRid;
+                sourceSessionRid ??= part.info.sourceSessionRid;
+                requestId ??= part.info.requestId;
+                flags ??= part.info.flags;
+                parts.push(part.message);
+                if (!part.more) {
+                    break;
+                }
+            }
+            const noBindInfo = this.createNoBindReplyInfo(actorRef, sourceNodeRid, sourceSessionRid, requestId, flags, parts);
+            if (this.consumeRemoteBoundSessionBind(actorRef, sourceNodeRid, sourceSessionRid, parts)) {
+                return;
+            }
+            if (((flags ?? 0) & ZLINK_SPOT_ACTOR_RECV_INFO_NO_BIND) === 0 &&
+                sourceNodeRid !== undefined &&
+                sourceSessionRid !== undefined) {
+                this.options.bindRemoteActorSession?.(actorRef, sourceNodeRid, sourceSessionRid);
+            }
+            if (this.options.actorPacketHandler === undefined) {
+                return;
+            }
+            if (noBindInfo !== undefined) {
+                await this.dispatchNoBindActorRequest(noBindInfo, actorId, parts, actorRef);
+            }
+            else {
+                await this.options.actorPacketHandler({
+                    actorId,
+                    parts,
+                    returnResponse: false,
+                    fallbackActorRef: actorRef
+                });
+            }
+        }
+        finally {
+            for (const part of parts) {
+                part.close();
+            }
+        }
+    }
+    dispose() {
+        for (const continuation of this.continuations.values())
+            closeMessages(continuation.parts);
+        this.continuations.clear();
+    }
+    createNoBindReplyInfo(actor, sourceNodeRid, sourceSessionRid, requestId, flags, parts) {
+        if (actor === undefined
+            || sourceNodeRid === undefined
+            || sourceSessionRid === undefined
+            || requestId === undefined
+            || requestId === 0n
+            || flags === undefined
+            || (flags & ZLINK_SPOT_ACTOR_RECV_INFO_NO_BIND) === 0
+            || this.options.replyActorNoBind === undefined
+            || !this.isActorRequest(parts)) {
+            return undefined;
+        }
+        return { actor, sourceNodeRid, sourceSessionRid, requestId, flags };
+    }
+    isActorRequest(parts) {
+        if (parts.length < 1) {
+            return false;
+        }
+        try {
+            const header = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(parts[0]), this.flowEnabled());
+            return header.kind === protocol_1.ZLinkStreamMessageKind.Request && header.requestSeq !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dispatchNoBindActorRequest(info, actorId, parts, actorRef) {
+        try {
+            const response = await this.options.actorPacketHandler?.({
+                actorId,
+                parts,
+                returnResponse: true,
+                fallbackActorRef: actorRef
+            });
+            this.options.replyActorNoBind?.(info, [this.encodeActorReplyFrame(parts[0], protocol_1.ZLinkStreamMessageKind.Response, response)], runtime_values_1.RequestResult.Ok);
+        }
+        catch (error) {
+            this.options.replyActorNoBind?.(info, [this.encodeActorReplyFrame(parts[0], protocol_1.ZLinkStreamMessageKind.Error, frameworkErrorPayload(error))], runtime_values_1.RequestResult.Ok);
+        }
+    }
+    encodeActorReplyFrame(requestHeaderPart, kind, payload) {
+        const requestHeader = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(requestHeaderPart), this.flowEnabled());
+        const encoded = (0, payload_codec_1.encodeFrameworkPayload)(payload, this.options.messageSerializers, kind === protocol_1.ZLinkStreamMessageKind.Response ? requestHeader.name : undefined, 'payload');
+        try {
+            //  encodeStreamFrame returns a fresh, unaliased array; view it without re-copying.
+            const frame = (0, protocol_1.encodeStreamFrame)({
+                kind,
+                codec: (0, protocol_1.streamCodecForContentType)(encoded.contentType),
+                flags: protocol_1.ZLinkStreamHeaderFlags.None,
+                requestSeq: requestHeader.requestSeq,
+                name: '',
+                metadata: new Map(),
+                correlationId: requestHeader.correlationId,
+                // Spec 27 §7: preserve the request flow pair on the reply while
+                // tracing is on; the gated decode above already strips it at Off.
+                flowId: requestHeader.flowId,
+                flowOrigin: requestHeader.flowOrigin
+            }, encoded.message.data());
+            return runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength));
+        }
+        finally {
+            encoded.message.close();
+        }
+    }
+    consumeRemoteBoundSessionBind(actor, sourceNodeRid, sourceSessionRid, parts) {
+        if (parts.length < 1) {
+            return false;
+        }
+        let header;
+        try {
+            header = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(parts[0]), this.flowEnabled());
+        }
+        catch {
+            return false;
+        }
+        if (header.name !== spot_remote_codec_1.REMOTE_BOUND_SESSION_BIND_PACKET) {
+            return false;
+        }
+        if (actor !== undefined && sourceNodeRid !== undefined && sourceSessionRid !== undefined) {
+            this.options.bindRemoteActorSession?.(actor, sourceNodeRid, sourceSessionRid);
+        }
+        return true;
+    }
+    flowEnabled() {
+        return this.options.flowEnabled?.() ?? true;
+    }
+}
+exports.ZLinkSpotActorPacketDrain = ZLinkSpotActorPacketDrain;
+function actorPacketKey(part) {
+    const info = part.info;
+    return [
+        String(info.actor.nodeRid),
+        info.actor.actorId,
+        info.actor.generation.toString(),
+        info.sourceNodeRid === undefined ? '' : String(info.sourceNodeRid),
+        info.sourceSessionRid === undefined ? '' : String(info.sourceSessionRid),
+        info.requestId?.toString() ?? '',
+        String(info.flags)
+    ].join('\u0000');
+}
+function continuationOwner(header, flowEnabled) {
+    try {
+        // Diagnostic label only; the gate keeps this from reading or validating
+        // the observation-only flow fields at Off (spec 27 §4).
+        const decoded = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(header), flowEnabled);
+        return `${decoded.name}:${decoded.requestSeq?.toString() ?? decoded.flowId ?? 'send'}`;
+    }
+    catch {
+        return 'invalid-header';
+    }
+}
+function isStreamHeaderMessage(message, flowEnabled) {
+    try {
+        (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(message), flowEnabled);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function closeMessages(messages) {
+    for (const message of messages)
+        message.close();
+}
+function frameworkErrorPayload(error) {
+    return {
+        message: error instanceof Error ? error.message : String(error),
+        kind: error instanceof contracts_1.ZLinkFrameworkException
+            ? error.kind
+            : contracts_1.ZLinkFrameworkErrorKind.InternalFailure
+    };
+}

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

@@ -0,0 +1,18 @@
+import { type ActorRef, type RoutingId } from '../../contracts';
+import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkRemoteActorPacketRelay } from './spot-remote-route-codec';
+import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
+interface ZLinkSpotActorPacketRelayDispatchOptions {
+    readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
+    readonly actorPacketTargetProvider?: (actorId: string) => ZLinkRemoteActorPacketTarget | undefined;
+    readonly bindRemoteSession?: (actor: ActorRef, sourceNodeRid: RoutingId, sourceSessionRid: RoutingId, declaredTarget?: ZLinkRemoteBoundSessionTarget) => void;
+    readonly flowEnabled?: () => boolean;
+}
+export declare class ZLinkSpotActorPacketRelayDispatch {
+    private readonly options;
+    constructor(options: ZLinkSpotActorPacketRelayDispatchOptions);
+    dispatch(received: BackendReceived, actorPacketRelay: ZLinkRemoteActorPacketRelay): Promise<boolean>;
+    private actorPacketTarget;
+}
+export {};

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

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorPacketRelayDispatch = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const runtime_message_1 = require("../backend/runtime-message");
+const protocol_1 = require("../streams/protocol");
+const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
+const routing_id_1 = require("../routing-id");
+const spot_route_replies_1 = require("./spot-route-replies");
+class ZLinkSpotActorPacketRelayDispatch {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async dispatch(received, actorPacketRelay) {
+        if (this.options.actorPacketHandler === undefined) {
+            return false;
+        }
+        const remoteBoundSessionTarget = actorPacketRelay.routerChannelId === undefined ||
+            actorPacketRelay.boundSessionTargetNodeRid === undefined ||
+            actorPacketRelay.boundSessionSpotId === undefined
+            ? undefined
+            : {
+                routerChannelId: actorPacketRelay.routerChannelId,
+                targetNodeRid: (0, routing_id_1.decodeRoutingId)(actorPacketRelay.boundSessionTargetNodeRid, undefined),
+                spotId: (0, routing_id_1.decodeRoutingId)(actorPacketRelay.boundSessionSpotId, undefined)
+            };
+        const header = runtime_message_1.ZLinkBufferMessage.from(Buffer.from(actorPacketRelay.header, 'base64'));
+        const payload = runtime_message_1.ZLinkBufferMessage.from(Buffer.from(actorPacketRelay.payload, 'base64'));
+        try {
+            const frameHeader = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(header), this.options.flowEnabled?.() ?? true);
+            if (frameHeader.name === actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_SESSION_BIND_PACKET) {
+                const actorRef = actorPacketRelay.bindingActorRef;
+                const sourceNodeRid = received.routingId;
+                if (frameHeader.kind !== protocol_1.ZLinkStreamMessageKind.Send ||
+                    actorRef === undefined ||
+                    sourceNodeRid === null ||
+                    this.options.bindRemoteSession === undefined) {
+                    throw new Error('Remote actor session binding requires a send, source route, and concrete actor ref.');
+                }
+                const binding = (0, actor_packet_relay_wire_1.decodeRemoteActorSessionBinding)((0, protocol_1.messageToBytes)(payload));
+                const declaredSourceNodeRid = binding.sessionNodeRid;
+                if (!(0, routing_id_1.routingIdsEqual)(sourceNodeRid, declaredSourceNodeRid)) {
+                    throw new Error('Remote actor session binding source did not match the declared session node.');
+                }
+                this.options.bindRemoteSession(actorRef, declaredSourceNodeRid, binding.sessionRid, remoteBoundSessionTarget === undefined
+                    ? undefined
+                    : {
+                        ...remoteBoundSessionTarget,
+                        sessionNodeRid: declaredSourceNodeRid,
+                        sessionRid: binding.sessionRid
+                    });
+                if ((0, spot_route_replies_1.hasReplyToken)(received.replyToken)) {
+                    (0, spot_route_replies_1.submitSpotRouteBridgeReply)(received, actorPacketRelay.envelope, {
+                        ok: true,
+                        response: { acknowledged: true }
+                    });
+                }
+                return true;
+            }
+            if (actorPacketRelay.messageFollowContext?.deadlineUnixMs !== undefined
+                && Date.now() >= actorPacketRelay.messageFollowContext.deadlineUnixMs) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorPacketRelay.actorId}' expired before target handler admission.`);
+            }
+            //  Spec 28 §5.2/§10 — a Message Follow relay is a one-way send that
+            //  preserves the ORIGINAL bound-session reply route. When the outer
+            //  transport cannot carry a bridge reply for such a followed request,
+            //  the inner dispatch must deliver its terminal completion (response
+            //  or error) through that original route via actorResponseSender/
+            //  actorErrorSender instead of returning it locally, where it would
+            //  be discarded. Non-follow relays keep the synchronous-return path.
+            const outerReplyable = (0, spot_route_replies_1.hasReplyToken)(received.replyToken);
+            const followedBoundSessionReply = !outerReplyable
+                && actorPacketRelay.messageFollowContext !== undefined
+                && remoteBoundSessionTarget !== undefined;
+            const response = await this.options.actorPacketHandler({
+                actorId: actorPacketRelay.actorId,
+                parts: [header, payload],
+                returnResponse: !followedBoundSessionReply,
+                remoteBoundSessionTarget,
+                fallbackActorRef: actorPacketRelay.actorRef
+            });
+            const actorPacketTarget = this.actorPacketTarget(actorPacketRelay.actorId);
+            if ((0, spot_route_replies_1.hasReplyToken)(received.replyToken)) {
+                (0, spot_route_replies_1.submitSpotRouteBridgeReply)(received, actorPacketRelay.envelope, { ok: true, response, actorPacketTarget });
+            }
+            return true;
+        }
+        catch (error) {
+            if ((0, spot_route_replies_1.hasReplyToken)(received.replyToken)) {
+                (0, spot_route_replies_1.submitSpotRouteBridgeReply)(received, actorPacketRelay.envelope, {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    errorKind: error instanceof contracts_1.ZLinkFrameworkException ? error.kind : undefined
+                });
+                return true;
+            }
+            throw error;
+        }
+        finally {
+            header.close();
+            payload.close();
+        }
+    }
+    actorPacketTarget(actorId) {
+        return (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.options.actorPacketTargetProvider?.(actorId));
+    }
+}
+exports.ZLinkSpotActorPacketRelayDispatch = ZLinkSpotActorPacketRelayDispatch;

package/dist/runtime/spots/spot-closing.d.ts

@@ -0,0 +1,2 @@
+import { ZLinkSpotCloseReason, type ZLinkSpotClosingContext } from '../../contracts';
+export declare function invokeSpotClosing(callback: ((context: ZLinkSpotClosingContext, cleanupSignal: AbortSignal) => Promise<void>) | undefined, reason: ZLinkSpotCloseReason, cleanupDeadline?: Date | number): Promise<void>;

package/dist/runtime/spots/spot-closing.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invokeSpotClosing = invokeSpotClosing;
+const DEFAULT_CLEANUP_TIMEOUT_MS = 30_000;
+async function invokeSpotClosing(callback, reason, cleanupDeadline = DEFAULT_CLEANUP_TIMEOUT_MS) {
+    if (callback === undefined)
+        return;
+    const deadline = new Date(cleanupDeadline instanceof Date
+        ? cleanupDeadline.getTime()
+        : Date.now() + cleanupDeadline);
+    const timeoutMs = Math.max(0, cleanupDeadline instanceof Date
+        ? cleanupDeadline.getTime() - Date.now()
+        : cleanupDeadline);
+    const controller = new AbortController();
+    let timer;
+    const expired = new Promise(resolve => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve();
+        }, timeoutMs);
+    });
+    try {
+        const operation = callback({ reason, deadline }, controller.signal);
+        await Promise.race([operation, expired]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/runtime/spots/spot-context.d.ts

@@ -0,0 +1,46 @@
+import type { RoutingId, SpotId, ZLinkActor, ZLinkEntrySpot, ZLinkEntrySpotContext, ZLinkInstanceSpotContext, ZLinkInstanceSpotHandlerRegistry, ZLinkSpot, ZLinkSpotContext, ZLinkSpotHandlerRegistry, ZLinkSpotOutbound, ZLinkSpotRelocationReadyCall } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import { ZLinkWorkerRuntime } from '../workers';
+import { type ZLinkSpotTimerRegistry } from './spot-timer';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+interface ZLinkEntrySpotContextOptions {
+    readonly spotId: SpotId;
+    readonly objectGeneration: number;
+    readonly nodeRid: RoutingId;
+    readonly handlers: ZLinkSpotHandlerRegistry;
+    readonly outbound: ZLinkSpotOutbound;
+    readonly timers: ZLinkSpotTimerRegistry;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly getEntrySpot: () => ZLinkEntrySpot;
+    readonly spotNodeName: string;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+    readonly workerRuntime: ZLinkWorkerRuntime;
+    readonly destroyActor?: (nodeRid: RoutingId, actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+}
+interface ZLinkSpotContextOptions {
+    readonly meshName: string;
+    readonly spotId: SpotId;
+    readonly objectGeneration: number;
+    readonly handlers: ZLinkSpotHandlerRegistry;
+    readonly outbound: ZLinkSpotOutbound;
+    readonly timers: ZLinkSpotTimerRegistry;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly getSpot: () => ZLinkSpot | undefined;
+    readonly nodeRid?: RoutingId;
+    readonly nodeRidProvider?: () => RoutingId | undefined;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+    readonly workerRuntime: ZLinkWorkerRuntime;
+    readonly close: (signal?: AbortSignal) => Promise<boolean>;
+    readonly leaveActor: (actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+    readonly relocationReady?: () => ZLinkSpotRelocationReadyCall;
+    readonly ensureOperationAllowed?: () => void;
+}
+export declare function createEntrySpotContext(options: ZLinkEntrySpotContextOptions): ZLinkEntrySpotContext;
+export declare function createSpotContext(options: ZLinkSpotContextOptions): ZLinkSpotContext;
+export declare function createInstanceSpotContext(options: Omit<ZLinkSpotContextOptions, 'handlers' | 'leaveActor'> & {
+    readonly handlers: ZLinkInstanceSpotHandlerRegistry;
+}): ZLinkInstanceSpotContext;
+export {};

package/dist/runtime/spots/spot-context.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEntrySpotContext = createEntrySpotContext;
+exports.createSpotContext = createSpotContext;
+exports.createInstanceSpotContext = createInstanceSpotContext;
+const configuration_1 = require("../configuration");
+const workers_1 = require("../workers");
+const spot_timer_1 = require("./spot-timer");
+function createEntrySpotContext(options) {
+    return withImmutableSpotIdentity({
+        meshName: options.spotNodeName,
+        spotId: options.spotId,
+        objectGeneration: options.objectGeneration,
+        nodeRid: options.nodeRid,
+        handlers: options.handlers,
+        outbound: options.outbound,
+        destroyActor(actor, signal) {
+            if (options.destroyActor === undefined) {
+                throw new configuration_1.ZLinkConfigurationException('Entry Spot actor destroy runtime is not started.');
+            }
+            return options.destroyActor(options.nodeRid, actor, signal);
+        },
+        addTimer(name, periodMs, handlerType, timerOptions, signal) {
+            return options.timers.add(name, periodMs, timerOptions, handlerType, options.serial, options.getEntrySpot(), options.providerResolver, signal, (0, spot_timer_1.createTimerDiagnostics)(options.spotNodeName, options.spotId, true, name, handlerType, options.runtimeEventPublisher));
+        },
+        runCpuWorker(work) {
+            return new workers_1.DefaultZLinkWorkerCall(options.serial, (timeoutMs, signal) => options.workerRuntime.scheduleCpu(work, timeoutMs, signal));
+        },
+        runIoWorker(work) {
+            return new workers_1.DefaultZLinkWorkerCall(options.serial, (timeoutMs, signal) => options.workerRuntime.scheduleIo(work, timeoutMs, signal));
+        }
+    });
+}
+function createSpotContext(options) {
+    return withImmutableSpotIdentity({
+        meshName: options.meshName,
+        spotId: options.spotId,
+        objectGeneration: options.objectGeneration,
+        nodeRid: contextNodeRid(options.nodeRidProvider?.() ?? options.nodeRid),
+        handlers: options.handlers,
+        get outbound() {
+            options.ensureOperationAllowed?.();
+            return options.outbound;
+        },
+        relocationReady: () => {
+            options.ensureOperationAllowed?.();
+            return options.relocationReady?.() ?? {
+                defer() {
+                    throw new configuration_1.ZLinkConfigurationException('Spot relocation readiness is not configured for application signaling.');
+                }
+            };
+        },
+        leaveActor: (actor, signal) => {
+            options.ensureOperationAllowed?.();
+            return options.leaveActor(actor, signal);
+        },
+        close: (signal) => {
+            options.ensureOperationAllowed?.();
+            return options.close(signal);
+        },
+        addTimer: (name, periodMs, handlerType, timerOptions, signal) => {
+            options.ensureOperationAllowed?.();
+            const spot = options.getSpot();
+            if (spot === undefined) {
+                throw new configuration_1.ZLinkConfigurationException('Spot timer cannot be registered before spot activation.');
+            }
+            return options.timers.add(name, periodMs, timerOptions, handlerType, options.serial, spot, options.providerResolver, signal, (0, spot_timer_1.createTimerDiagnostics)(String(options.spotId), options.spotId, false, name, handlerType, options.runtimeEventPublisher));
+        },
+        runCpuWorker: (work) => {
+            options.ensureOperationAllowed?.();
+            return new workers_1.DefaultZLinkWorkerCall(options.serial, (timeoutMs, signal) => options.workerRuntime.scheduleCpu(work, timeoutMs, signal));
+        },
+        runIoWorker: (work) => {
+            options.ensureOperationAllowed?.();
+            return new workers_1.DefaultZLinkWorkerCall(options.serial, (timeoutMs, signal) => options.workerRuntime.scheduleIo(work, timeoutMs, signal));
+        }
+    });
+}
+function createInstanceSpotContext(options) {
+    const common = {
+        meshName: options.meshName,
+        spotId: options.spotId,
+        objectGeneration: options.objectGeneration,
+        nodeRid: contextNodeRid(options.nodeRidProvider?.() ?? options.nodeRid),
+        handlers: options.handlers,
+        outbound: options.outbound,
+        close: options.close,
+        addTimer: (name, periodMs, handlerType, timerOptions, signal) => {
+            const spot = options.getSpot();
+            if (spot === undefined) {
+                throw new configuration_1.ZLinkConfigurationException('Instance Spot timer cannot be registered before activation.');
+            }
+            return options.timers.add(name, periodMs, timerOptions, handlerType, options.serial, spot, options.providerResolver, signal, (0, spot_timer_1.createTimerDiagnostics)(String(options.spotId), options.spotId, false, name, handlerType, options.runtimeEventPublisher));
+        },
+        runCpuWorker: (work) => new workers_1.DefaultZLinkWorkerCall(options.serial, (timeoutMs, signal) => options.workerRuntime.scheduleCpu(work, timeoutMs, signal)),
+        runIoWorker: (work) => new workers_1.DefaultZLinkWorkerCall(options.serial, (timeoutMs, signal) => options.workerRuntime.scheduleIo(work, timeoutMs, signal))
+    };
+    return withImmutableSpotIdentity(common);
+}
+function contextNodeRid(nodeRid) {
+    return nodeRid ?? '';
+}
+function withImmutableSpotIdentity(context) {
+    for (const key of ['meshName', 'spotId', 'objectGeneration', 'nodeRid']) {
+        Object.defineProperty(context, key, {
+            configurable: false,
+            enumerable: true,
+            writable: false,
+            value: context[key]
+        });
+    }
+    return context;
+}

package/dist/runtime/spots/spot-entry-activation.d.ts

@@ -0,0 +1,107 @@
+import type { ActorRef, RoutingId, Type, ZLinkActor, ZLinkActorCreateResponse, ZLinkChannelClient, ZLinkEntrySpot, ZLinkEntrySpotContext, ZLinkFanoutClient, ZLinkMessage, ZLinkMessageSerializer, ZLinkSpotPublisherClient } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import type { ZLinkEntrySpotActorRequestHandlerRegistration, ZLinkEntrySpotActorSendHandlerRegistration, ZLinkEntrySpotPacketHandlerRegistration, ZLinkEntrySpotSubscriptionHandlerRegistration, ZLinkEntrySpotTimerHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendReceived, ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendTopicMessage } from '../backend/contracts';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import { ZLinkWorkerRuntime } from '../workers';
+import { type ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
+import { type ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
+import { type ZLinkSpotRoutedTransport } from './spot-outbound';
+import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import { type ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import type { ZLinkEntryActorRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotActorHandoffRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
+interface ZLinkEntrySpotActivationOptions {
+    readonly entrySpotType: Type<ZLinkEntrySpot>;
+    readonly timerHandlers?: readonly ZLinkEntrySpotTimerHandlerRegistration[];
+    readonly packetHandlers?: readonly ZLinkEntrySpotPacketHandlerRegistration[];
+    readonly subscriptionHandlers?: readonly ZLinkEntrySpotSubscriptionHandlerRegistration[];
+    readonly actorSendHandlers?: readonly ZLinkEntrySpotActorSendHandlerRegistration[];
+    readonly actorRequestHandlers?: readonly ZLinkEntrySpotActorRequestHandlerRegistration[];
+    readonly nativeSpot: ZLinkBackendSpot;
+    readonly nativeNode: ZLinkBackendSpotNode;
+    readonly createReceived: () => ZLinkBackendReceived;
+    readonly createTopicMessage: () => ZLinkBackendTopicMessage;
+    readonly nodeRid: RoutingId;
+    readonly spotNodeName: string;
+    readonly channelClient?: ZLinkChannelClient;
+    readonly fanoutClient?: ZLinkFanoutClient;
+    readonly spotPublisherClient?: ZLinkSpotPublisherClient;
+    readonly routedTransport?: ZLinkSpotRoutedTransport;
+    readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
+    readonly channelMeshNameForChannel?: (channelName: string) => string | undefined;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+    readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+    readonly workerRuntime?: ZLinkWorkerRuntime;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly entryActorRuntime?: ZLinkEntryActorRuntime;
+    readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
+    readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
+    readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
+    readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+}
+export declare class ZLinkEntrySpotActivation {
+    private readonly options;
+    private readonly serial;
+    private readonly spotSerialExecutor;
+    private readonly timers;
+    private readonly actorHandlers;
+    private readonly handlers;
+    private readonly outbound;
+    private readonly workerRuntime;
+    private readonly lifecycleMetrics;
+    private readonly packetDispatch;
+    private readonly actorPacketDispatch;
+    private initialized;
+    private disposed;
+    private actorDispatch?;
+    entrySpot: ZLinkEntrySpot;
+    readonly context: ZLinkEntrySpotContext;
+    constructor(options: ZLinkEntrySpotActivationOptions);
+    /**
+     * The Entry Spot serial dispatch line for Entry Spot-owned callbacks such as
+     * lifecycle, timers, request continuations and worker completions. Actor
+     * packets use the target actor mailbox instead.
+     */
+    get serialExecutor(): ZLinkSpotSerialTurnExecutor;
+    get nodeRid(): RoutingId;
+    get spotId(): RoutingId;
+    dispatchSubscriptionRecord(topic: string, parts: readonly Message[], sourceRid: RoutingId | null): Promise<void>;
+    dispatchPacket(packetName: string | undefined, payload: unknown, context: {
+        readonly channelName: string;
+        readonly contentType?: string;
+    }, returnResponse: boolean): Promise<unknown>;
+    dispatchPacketEncoded(packetName: string | undefined, decodePayload: () => unknown, context: {
+        readonly channelName: string;
+        readonly contentType?: string;
+    }, returnResponse: boolean): Promise<unknown>;
+    create(): Promise<void>;
+    configure(): Promise<void>;
+    initialize(): Promise<void>;
+    dispose(deadline?: Date): Promise<void>;
+    notifyCreateActor(actor: ZLinkActor, createRequest: ZLinkMessage, signal?: AbortSignal): Promise<ZLinkActorCreateResponse>;
+    notifyJoinActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    /**
+     * Completes the stateful MeshNode return-to-Entry-Spot path after Core has
+     * accepted the membership reply. The native receive path performs the same
+     * actor-manager transaction in its admission callback.
+     */
+    commitServiceActorJoin(actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[], signal?: AbortSignal): Promise<void>;
+    /**
+     * Entry Spot membership does not have an application admission callback.
+     * The shared core round-trip therefore accepts a valid returning Actor and
+     * runs only the post-commit membership notification.
+     */
+    private attachActorJoinDispatch;
+    private commitEntryActorTransaction;
+    notifyLeaveActor(actor: ZLinkActor, signal?: AbortSignal, _actorRef?: ActorRef, _membershipEpoch?: bigint): Promise<void>;
+    notifyDisconnectActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    dispatchActorPacket(delivery: ZLinkActorPacketDelivery): Promise<unknown>;
+    private replayActorBacklog;
+    private dispatchActorPacketInsideMailbox;
+    private replyActorNoBind;
+}
+export {};