@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorAdmissionCoordinator = void 0;
+const actor_handoff_1 = require("../actors/actor-handoff");
+const routing_id_1 = require("../routing-id");
+const spot_actor_join_dispatch_1 = require("./spot-actor-join-dispatch");
+const spot_actor_packet_dispatch_1 = require("./spot-actor-packet-dispatch");
+class ZLinkSpotActorAdmissionCoordinator {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        const handoff = this.options.actorHandoffRuntime?.capture(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.dispatchActorPacketDirect(activation, actorId, replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef));
+        if (handoff !== undefined)
+            return await handoff;
+        return await this.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+    }
+    attachNativeActorJoinDispatch(activation, nativeSpot) {
+        if (nativeSpot === undefined)
+            return undefined;
+        const nativeDispatch = new spot_actor_join_dispatch_1.ZLinkSpotActorJoinDispatch({
+            nativeSpot,
+            createReceived: requireBackendValueFactory(this.options.createReceived, 'Received'),
+            createTopicMessage: requireBackendValueFactory(this.options.createTopicMessage, 'TopicMessage'),
+            serial: activation.serial,
+            actors: {
+                resolveActor: (actorId) => activation.hasDepartedActor(actorId)
+                    ? undefined
+                    : activation.resolveJoinedActor(actorId) ?? this.options.actorResolver?.(actorId),
+                getTarget: () => activation.spot,
+                defaultAccept: false,
+                transfer: this.options.actorTransferRuntime === undefined ? { kind: 'disabled' } : {
+                    kind: 'enabled',
+                    runtime: this.options.actorTransferRuntime
+                },
+                commitNativeActor: (actor) => this.commitNativeActorTransaction(activation, actor),
+                commitActorDeparture: (actorId) => activation.commitActorDeparture(actorId),
+                commitTransferredActor: (actor, backlog) => this.commitTransferredActorTransaction(activation, actor, backlog)
+            },
+            packets: {
+                handle: (delivery) => this.dispatchActorPacket(activation, delivery.actorId, delivery.parts, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef),
+                bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
+                    const node = this.options.nativeSpotNodeProvider?.(activation.meshName);
+                    if (node === undefined || (0, routing_id_1.routingIdsEqual)(sourceNodeRid, node.routingId))
+                        return;
+                    const target = this.options.boundSessionRuntime?.resolveRemoteBoundSessionTarget(sourceNodeRid, sourceSessionRid);
+                    if (target !== undefined) {
+                        this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(actor.actorId, target);
+                    }
+                    node.bindRemoteActorSession(actor, sourceNodeRid, sourceSessionRid);
+                },
+                replyNoBind: (info, parts, result) => this.options.nativeSpotNodeProvider?.(activation.meshName)?.replyActorNoBind(info, parts, result)
+            },
+            boundSessionRuntime: this.options.boundSessionRuntime,
+            messageSerializers: this.options.messageSerializers,
+            providerResolver: this.options.providerResolver,
+            dispatchErrors: this.options.dispatchErrors,
+            claimApplicationWork: this.options.admission === undefined
+                ? undefined
+                : () => this.options.admission.claim(activation.meshName, 'Spot route dispatch'),
+            detachedTaskRunner: this.options.detachedTaskRunner
+        });
+        nativeDispatch.attach();
+        return nativeDispatch;
+    }
+    /** @internal Dispatches a coordinator-owned replay without recapturing it. */
+    dispatchActorPacketDirect(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        return activation.executeActor(actorId, actorSerial => this.dispatchActorPacketInActorTurn(activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal));
+    }
+    /**
+     * Atomically restores one durable packet prefix at the Actor FIFO tail.
+     * The prefix itself is not an executing Actor record. Its child callbacks
+     * enter the Actor context one by one after the prefix reaches the head.
+     *
+     * @internal
+     */
+    admitActorPacketPrefix(activation, actorId, records) {
+        const terminals = activation.admitActorDurablePrefix(actorId, records.map(record => ({
+            operation: executeChild => record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => executeChild(actorSerial => this.dispatchActorPacketInActorTurn(activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef))),
+            preparation: record.preparation,
+            workOptions: { payloadBytes: record.payloadBytes }
+        })));
+        const terminal = Promise.allSettled(terminals).then(outcomes => {
+            const errors = outcomes.flatMap(outcome => outcome.status === 'rejected' ? [outcome.reason] : []);
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1) {
+                throw new AggregateError(errors, `Actor '${actorId}' durable prefix replay failed.`);
+            }
+        });
+        return { terminal };
+    }
+    dispatchActorPacketInActorTurn(activation, actorSerial, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        return new spot_actor_packet_dispatch_1.ZLinkSpotActorPacketDispatch({
+            spot: activation.spot,
+            spotId: () => String(activation.spotId),
+            registry: activation.actorHandlers,
+            serial: actorSerial,
+            resolveActor: (targetActorId) => activation.hasDepartedActor(targetActorId)
+                ? undefined
+                : activation.resolveJoinedActor(targetActorId) ?? this.options.actorResolver?.(targetActorId),
+            actorLeft: (targetActorId) => activation.hasDepartedActor(targetActorId),
+            onRemoteBoundSessionTarget: (targetActorId, target) => this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(targetActorId, target),
+            onDisconnectActor: (actor) => activation.serial.execute(() => activation.spot.onDisconnectActor?.(actor)),
+            actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(this.options.boundSessionRuntime),
+            actorErrorSender: this.options.boundSessionRuntime?.sendActorError.bind(this.options.boundSessionRuntime),
+            providerResolver: this.options.providerResolver,
+            messageSerializers: this.options.messageSerializers,
+            dispatchErrors: this.options.dispatchErrors,
+            routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
+        }).dispatch(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+    }
+    async commitNativeActorTransaction(activation, actor) {
+        const transfer = this.options.actorTransferRuntime;
+        let snapshot;
+        let rollbackMembership;
+        let routeSwitchStarted = false;
+        try {
+            snapshot = await transfer?.claimNativeActorLocation(actor, activation.spotId, activation.meshName);
+            transfer?.commitRoutedActor(actor, activation.spotId, activation.spot);
+            rollbackMembership = activation.commitActorJoin(actor);
+            activation.beginActorTransfer(actor.context.actorId);
+            await activation.serial.execute(() => activation.spot.onJoinedActor(actor));
+            routeSwitchStarted = true;
+            await transfer?.publishRoutedActorOwnership(actor);
+            await transfer?.openRoutedActorSession(actor);
+            activation.cancelActorTransfer(actor.context.actorId);
+        }
+        catch (error) {
+            if (routeSwitchStarted)
+                throw error;
+            rollbackMembership?.();
+            try {
+                if (snapshot !== undefined)
+                    await transfer?.rollbackNativeActorJoin(actor, snapshot);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], 'Native actor admission and rollback both failed.');
+            }
+            throw error;
+        }
+    }
+    async commitTransferredActorTransaction(activation, actor, backlog) {
+        const transfer = this.options.actorTransferRuntime;
+        let routeSwitchStarted = false;
+        try {
+            transfer?.commitRoutedActor(actor, activation.spotId, activation.spot);
+            activation.commitActorJoin(actor);
+            activation.beginActorTransfer(actor.context.actorId);
+            await activation.serial.execute(() => activation.spot.onJoinedActor(actor));
+            const results = backlog.length === 0
+                ? []
+                : await this.replayActorBacklog(activation, actor, backlog);
+            await transfer?.claimRoutedActorLocation(actor, activation.spotId, activation.meshName);
+            routeSwitchStarted = true;
+            await transfer?.publishRoutedActorOwnership(actor);
+            await transfer?.openRoutedActorSession(actor);
+            activation.cancelActorTransfer(actor.context.actorId);
+            return results;
+        }
+        catch (error) {
+            if (routeSwitchStarted)
+                throw error;
+            activation.commitActorDeparture(actor.context.actorId);
+            transfer?.clearRoutedActor(actor);
+            try {
+                await transfer?.rollbackRoutedActor(actor);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], 'Actor admission and rollback both failed.');
+            }
+            throw error;
+        }
+    }
+    async replayActorBacklog(activation, actor, backlog) {
+        return await (0, actor_handoff_1.replayActorHandoffBacklog)(backlog, (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.dispatchActorPacketDirect(activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef), (index) => this.options.runtimeEventPublisher?.publish({
+            sourceName: 'zlink.framework.actor-handoff',
+            timestamp: new Date(),
+            marker: 'backlog_enqueued',
+            actorId: actor.context.actorId,
+            index
+        }));
+    }
+}
+exports.ZLinkSpotActorAdmissionCoordinator = ZLinkSpotActorAdmissionCoordinator;
+function requireBackendValueFactory(factory, valueName) {
+    return () => {
+        if (factory === undefined) {
+            throw new Error(`Native Spot dispatch requires a backend ${valueName} factory.`);
+        }
+        return factory();
+    };
+}

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

@@ -0,0 +1,83 @@
+import type { RoutingId, ZLinkActor, ZLinkMessage, ZLinkMessageSerializer, ZLinkSpotActorJoinResult } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkBackendActorRef, ZLinkBackendActorRecvInfo, ZLinkBackendReceived, ZLinkBackendSpot, ZLinkBackendTopicMessage } from '../backend/contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { RequestResult } from '../backend/runtime-values';
+type RuntimeMessage = Message;
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import type { ZLinkApplicationWorkClaim } from '../admission';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
+import type { ZLinkSpotActorTransferRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
+/**
+ * Minimal lifecycle callback surface required by the native join and actor
+ * lifecycle drains. User and Entry Spots differ in ownership policy, but both
+ * drains only need the callbacks declared here.
+ */
+interface ZLinkActorJoinAdmissionTarget {
+    onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
+    onJoinedActor?(actor: ZLinkActor): Promise<void>;
+    onLeaveActor?(actor: ZLinkActor): Promise<void>;
+    onDisconnectActor?(actor: ZLinkActor): Promise<void>;
+}
+interface ZLinkSpotActorAdmissionRuntime {
+    readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
+    readonly getTarget: () => ZLinkActorJoinAdmissionTarget;
+    readonly defaultAccept: boolean;
+    readonly transfer: {
+        readonly kind: 'disabled';
+    } | {
+        readonly kind: 'enabled';
+        readonly runtime: ZLinkSpotActorTransferRuntime;
+    };
+    readonly commitNativeActor?: (actor: ZLinkActor) => Promise<void>;
+    readonly commitActorDeparture?: (actorId: string) => void;
+    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[]) => Promise<readonly ZLinkActorHandoffResult[]>;
+}
+interface ZLinkSpotActorPacketRuntime {
+    readonly handle: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
+    readonly bindRemoteSession?: (actor: ZLinkBackendActorRef, sourceNodeRid: RoutingId, sourceSessionRid: RoutingId, declaredTarget?: ZLinkRemoteBoundSessionTarget) => void;
+    readonly replyNoBind?: (info: ZLinkBackendActorRecvInfo, parts: readonly Message[], result: RequestResult) => void;
+}
+export interface ZLinkDetachedTaskRunner {
+    runDetached(taskName: string, callback: () => Promise<void>): void;
+}
+interface ZLinkSpotActorJoinDispatchOptions {
+    readonly nativeSpot: ZLinkBackendSpot;
+    readonly createReceived: () => ZLinkBackendReceived;
+    readonly createTopicMessage: () => ZLinkBackendTopicMessage;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly actors: ZLinkSpotActorAdmissionRuntime;
+    readonly packets?: ZLinkSpotActorPacketRuntime;
+    readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
+    readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+}
+export declare class ZLinkSpotActorJoinDispatch {
+    private readonly options;
+    private draining;
+    private redrainRequested;
+    private readonly nativeSpotId;
+    private readonly subscriptions;
+    private readonly actorLifecycleDrain;
+    private readonly actorPacketDrain;
+    private readonly nativeActorJoinAdmission;
+    private readonly routedFrames;
+    private readonly nativeSpot;
+    constructor(options: ZLinkSpotActorJoinDispatchOptions);
+    configureSubscriptions(registrations: readonly ZLinkSpotHandlerRegistration[]): void;
+    dispatchSubscriptionRecord(topic: string, parts: readonly RuntimeMessage[], sourceRid: RoutingId | null): Promise<void>;
+    dispose(): void;
+    attach(): void;
+    private runDetached;
+    private drain;
+    private redrainWasRequested;
+    private drainAvailableActorJoins;
+}
+export {};

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

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorJoinDispatch = void 0;
+const contracts_1 = require("../backend/contracts");
+const spot_actor_lifecycle_drain_1 = require("./spot-actor-lifecycle-drain");
+const spot_actor_packet_drain_1 = require("./spot-actor-packet-drain");
+const spot_native_flags_1 = require("./spot-native-flags");
+const spot_native_actor_join_admission_1 = require("./spot-native-actor-join-admission");
+const spot_routed_frame_dispatch_1 = require("./spot-routed-frame-dispatch");
+const spot_subscription_dispatch_1 = require("./spot-subscription-dispatch");
+const ZLINK_SPOT_DISPATCH_SUBJECT_SPOT = 1;
+const ZLINK_SPOT_DISPATCH_SUBJECT_CHANNEL_DEALER = 3;
+class ZLinkSpotActorJoinDispatch {
+    options;
+    draining = false;
+    redrainRequested = false;
+    nativeSpotId;
+    subscriptions;
+    actorLifecycleDrain;
+    actorPacketDrain;
+    nativeActorJoinAdmission;
+    routedFrames;
+    nativeSpot;
+    constructor(options) {
+        this.options = options;
+        const actors = options.actors;
+        const transfer = actors.transfer.kind === 'enabled' ? actors.transfer : undefined;
+        this.nativeSpot = options.nativeSpot;
+        this.nativeSpotId = String(options.nativeSpot.routingId);
+        this.actorLifecycleDrain = new spot_actor_lifecycle_drain_1.ZLinkSpotActorLifecycleDrain({
+            nativeSpot: options.nativeSpot,
+            serial: options.serial,
+            resolveActor: actors.resolveActor,
+            getTarget: actors.getTarget,
+            commitActorDeparture: actors.commitActorDeparture,
+            waitIdle: waitSpotDispatchIdle
+        });
+        this.actorPacketDrain = new spot_actor_packet_drain_1.ZLinkSpotActorPacketDrain({
+            messageSerializers: options.messageSerializers,
+            actorPacketHandler: options.packets?.handle,
+            bindRemoteActorSession: options.packets?.bindRemoteSession,
+            replyActorNoBind: options.packets?.replyNoBind,
+            waitIdle: waitSpotDispatchIdle,
+            flowEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+        });
+        this.nativeActorJoinAdmission = new spot_native_actor_join_admission_1.ZLinkSpotNativeActorJoinAdmission({
+            nativeSpot: options.nativeSpot,
+            serial: options.serial,
+            resolveActor: actors.resolveActor,
+            getTarget: actors.getTarget,
+            defaultAccept: actors.defaultAccept,
+            commitAcceptedActor: actors.commitNativeActor,
+            messageSerializers: options.messageSerializers,
+            dispatchErrors: options.dispatchErrors
+        });
+        this.routedFrames = new spot_routed_frame_dispatch_1.ZLinkSpotRoutedFrameDispatch({
+            nativeSpot: options.nativeSpot,
+            createReceived: options.createReceived,
+            nativeSpotId: this.nativeSpotId,
+            serial: options.serial,
+            resolveActor: actors.resolveActor,
+            getTarget: () => actors.getTarget(),
+            defaultAccept: actors.defaultAccept,
+            routedActorTransferProvider: transfer?.runtime.materializeRoutedActor.bind(transfer.runtime),
+            commitTransferredActor: actors.commitTransferredActor,
+            actorPacketHandler: options.packets?.handle,
+            bindRemoteSession: options.packets?.bindRemoteSession === undefined
+                ? undefined
+                : (actor, sourceNodeRid, sourceSessionRid, declaredTarget) => options.packets.bindRemoteSession({
+                    actorId: actor.actorId,
+                    generation: actor.objectGeneration,
+                    nodeRid: actor.nodeRid
+                }, sourceNodeRid, sourceSessionRid, declaredTarget),
+            routedBoundSessionReceiver: options.boundSessionRuntime?.receiveRoutedBoundSession.bind(options.boundSessionRuntime),
+            routedBoundSessionResponseReceiver: options.boundSessionRuntime?.receiveRoutedBoundSessionResponse.bind(options.boundSessionRuntime),
+            routedBoundSessionErrorReceiver: options.boundSessionRuntime?.receiveRoutedBoundSessionError.bind(options.boundSessionRuntime),
+            actorPacketTargetProvider: options.boundSessionRuntime?.actorPacketTargetForState.bind(options.boundSessionRuntime),
+            messageSerializers: options.messageSerializers,
+            providerResolver: options.providerResolver,
+            dispatchErrors: options.dispatchErrors,
+            claimApplicationWork: options.claimApplicationWork,
+            waitIdle: waitSpotDispatchIdle
+        });
+        this.subscriptions = new spot_subscription_dispatch_1.ZLinkSpotSubscriptionDispatch({
+            nativeSpot: options.nativeSpot,
+            createTopicMessage: options.createTopicMessage,
+            serial: options.serial,
+            getTarget: () => actors.getTarget(),
+            messageSerializers: options.messageSerializers,
+            providerResolver: options.providerResolver,
+            dispatchErrors: options.dispatchErrors,
+            waitIdle: waitSpotDispatchIdle
+        });
+    }
+    configureSubscriptions(registrations) {
+        this.subscriptions.configure(registrations);
+        this.routedFrames.configurePacketHandlers(registrations);
+    }
+    async dispatchSubscriptionRecord(topic, parts, sourceRid) {
+        await this.subscriptions.dispatchRecord(topic, parts, sourceRid);
+    }
+    dispose() {
+        this.actorPacketDrain.dispose();
+    }
+    attach() {
+        if (typeof this.nativeSpot.setDispatchHandler !== 'function') {
+            return;
+        }
+        this.nativeSpot.setDispatchHandler((info) => {
+            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.ActorJoinReadable) {
+                this.runDetached('spot actor join drain', () => this.drain());
+                return;
+            }
+            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.SubscribeReadable) {
+                this.runDetached('spot subscription drain', () => this.subscriptions.drain());
+                return;
+            }
+            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.ChannelReplyReadable) {
+                if (info.subjectKind === ZLINK_SPOT_DISPATCH_SUBJECT_CHANNEL_DEALER &&
+                    info.subjectHandle !== undefined) {
+                    this.nativeSpot.drainChannelReply(info.subjectHandle);
+                    return;
+                }
+                if (info.subjectKind === ZLINK_SPOT_DISPATCH_SUBJECT_SPOT ||
+                    info.subjectKind === undefined) {
+                    this.nativeSpot.drainReply();
+                }
+                return;
+            }
+            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.RoutedReadable) {
+                if (info.routed !== undefined && info.routed !== null) {
+                    this.runDetached('spot routed frame dispatch', () => this.routedFrames.dispatchFromEvent(info.routed));
+                }
+                return;
+            }
+            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.ActorReadable) {
+                this.runDetached('spot actor packet drain', () => this.actorPacketDrain.drain(info));
+                return;
+            }
+            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.ActorLifecycleReadable) {
+                this.runDetached('spot actor lifecycle drain', () => this.actorLifecycleDrain.drain());
+            }
+        });
+    }
+    runDetached(taskName, callback) {
+        if (this.options.detachedTaskRunner !== undefined) {
+            this.options.detachedTaskRunner.runDetached(taskName, callback);
+            return;
+        }
+        void callback().catch(() => undefined);
+    }
+    async drain() {
+        if (this.draining) {
+            this.redrainRequested = true;
+            return;
+        }
+        this.draining = true;
+        try {
+            do {
+                this.redrainRequested = false;
+                await this.drainAvailableActorJoins();
+            } while (this.redrainWasRequested());
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    redrainWasRequested() {
+        return this.redrainRequested;
+    }
+    async drainAvailableActorJoins() {
+        for (;;) {
+            const request = this.nativeSpot.recvActorJoin(spot_native_flags_1.ZLINK_RECV_DONT_WAIT);
+            if (request === null) {
+                await waitSpotDispatchIdle();
+                return;
+            }
+            await this.nativeActorJoinAdmission.admit(request);
+        }
+    }
+}
+exports.ZLinkSpotActorJoinDispatch = ZLinkSpotActorJoinDispatch;
+function waitSpotDispatchIdle() {
+    return new Promise((resolve) => setTimeout(resolve, 5));
+}

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

@@ -0,0 +1,22 @@
+import type { ZLinkActor } from '../../contracts';
+import type { ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+interface ZLinkSpotActorLifecycleTarget {
+    onJoinedActor?(actor: ZLinkActor): Promise<void> | void;
+    onLeaveActor?(actor: ZLinkActor): Promise<void> | void;
+    onDisconnectActor?(actor: ZLinkActor): Promise<void> | void;
+}
+interface ZLinkSpotActorLifecycleDrainOptions {
+    readonly nativeSpot: ZLinkBackendSpot;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
+    readonly getTarget: () => ZLinkSpotActorLifecycleTarget;
+    readonly commitActorDeparture?: (actorId: string) => void;
+    readonly waitIdle: () => Promise<void>;
+}
+export declare class ZLinkSpotActorLifecycleDrain {
+    private readonly options;
+    constructor(options: ZLinkSpotActorLifecycleDrainOptions);
+    drain(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActorLifecycleDrain = void 0;
+const spot_native_flags_1 = require("./spot-native-flags");
+const ZLINK_SPOT_ACTOR_LIFECYCLE_JOINED = 1;
+const ZLINK_SPOT_ACTOR_LIFECYCLE_LEFT = 2;
+const ZLINK_SPOT_ACTOR_LIFECYCLE_DISCONNECTED = 3;
+class ZLinkSpotActorLifecycleDrain {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async drain() {
+        for (;;) {
+            const event = this.options.nativeSpot.recvActorLifecycle(spot_native_flags_1.ZLINK_RECV_DONT_WAIT);
+            if (event === null) {
+                await this.options.waitIdle();
+                return;
+            }
+            const actorRef = event.kind === ZLINK_SPOT_ACTOR_LIFECYCLE_LEFT
+                ? event.info.previousActor
+                : event.info.currentActor;
+            const actorId = actorRef?.actorId;
+            if (actorId === undefined || this.options.resolveActor(actorId) === undefined) {
+                continue;
+            }
+            if (actorRef === null || actorRef === undefined)
+                continue;
+            await this.options.serial.execute(() => {
+                const actor = this.options.resolveActor(actorId);
+                if (actor === undefined) {
+                    return undefined;
+                }
+                const target = this.options.getTarget();
+                if (event.kind === ZLINK_SPOT_ACTOR_LIFECYCLE_JOINED) {
+                    return target.onJoinedActor?.(actor);
+                }
+                if (event.kind === ZLINK_SPOT_ACTOR_LIFECYCLE_LEFT) {
+                    return Promise.resolve(target.onLeaveActor?.(actor)).then(() => {
+                        this.options.commitActorDeparture?.(actorId);
+                    });
+                }
+                if (event.kind === ZLINK_SPOT_ACTOR_LIFECYCLE_DISCONNECTED) {
+                    return target.onDisconnectActor?.(actor);
+                }
+                return undefined;
+            });
+        }
+    }
+}
+exports.ZLinkSpotActorLifecycleDrain = ZLinkSpotActorLifecycleDrain;

package/dist/runtime/spots/spot-actor-membership.d.ts

@@ -0,0 +1,39 @@
+import type { RoutingId, ZLinkActor, ZLinkMessageSerializer, ZLinkSpot, ZLinkSpotActorJoinResult } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { Message } from '../../contracts/Common/Message';
+import { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkSpotActivation } from './spot-activation-state';
+import type { ZLinkSpotActorTransferRuntime } from './spot-runtime-ports';
+import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
+export interface ZLinkSpotActorMembershipOptions {
+    readonly resolveActivation: (spotId: RoutingId, meshName?: string) => ZLinkSpotActivation | undefined;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly entrySpotCallbacks?: {
+        onLeaveActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    };
+    readonly nodeRid?: RoutingId;
+    readonly nodeRidProvider?: (meshName: string) => RoutingId | undefined;
+    readonly entryNodeRid?: RoutingId;
+    readonly entryNodeRidProvider?: () => RoutingId | undefined;
+    readonly entrySpotIdProvider?: (meshName: string) => string | undefined;
+    readonly spotRouteResolver?: ZLinkSpotRouteResolver;
+    readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
+}
+export type ZLinkActorJoinRollback = () => Promise<void> | void;
+export declare class ZLinkSpotActorMembership {
+    private readonly options;
+    constructor(options: ZLinkSpotActorMembershipOptions);
+    admitActorJoin(spotId: RoutingId, actor: ZLinkActor, request: Message, commit: (spot: ZLinkSpot) => Promise<ZLinkActorJoinRollback | void> | ZLinkActorJoinRollback | void, signal?: AbortSignal, leaveSource?: () => Promise<void>, contentType?: string): Promise<ZLinkSpotActorJoinResult>;
+    leaveActor(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal, meshName?: string): Promise<void>;
+    notifyActorLeftAfterTransfer(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    prepareActorLeaveForTransfer(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    commitActorLeaveAfterTransfer(spotId: RoutingId, actorId: string): Promise<void>;
+    restoreActorAfterFailedTransfer(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    beginActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
+    cancelActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
+    notifyJoinedActorDisconnected(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<boolean>;
+    private requireActivation;
+    private createActorDispatcher;
+}