@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-routed-frame-dispatch.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotRoutedFrameDispatch = void 0;
+const spot_remote_route_codec_1 = require("./spot-remote-route-codec");
+const spot_native_flags_1 = require("./spot-native-flags");
+const spot_actor_packet_relay_dispatch_1 = require("./spot-actor-packet-relay-dispatch");
+const spot_route_packet_dispatch_1 = require("./spot-route-packet-dispatch");
+const spot_routed_actor_admission_1 = require("./spot-routed-actor-admission");
+const spot_routed_bound_session_dispatch_1 = require("./spot-routed-bound-session-dispatch");
+class ZLinkSpotRoutedFrameDispatch {
+    options;
+    routeDraining = false;
+    packetHandlers = new Map();
+    routedBoundSessionDispatch;
+    actorPacketRelayDispatch;
+    routePacketDispatch;
+    routedActorAdmission;
+    constructor(options) {
+        this.options = options;
+        this.routedBoundSessionDispatch = new spot_routed_bound_session_dispatch_1.ZLinkSpotRoutedBoundSessionDispatch({
+            channelCodecs: () => this.channelCodecs(),
+            routedBoundSessionReceiver: options.routedBoundSessionReceiver,
+            routedBoundSessionResponseReceiver: options.routedBoundSessionResponseReceiver,
+            routedBoundSessionErrorReceiver: options.routedBoundSessionErrorReceiver,
+            dispatchErrors: options.dispatchErrors
+        });
+        this.actorPacketRelayDispatch = new spot_actor_packet_relay_dispatch_1.ZLinkSpotActorPacketRelayDispatch({
+            actorPacketHandler: options.actorPacketHandler,
+            actorPacketTargetProvider: options.actorPacketTargetProvider,
+            bindRemoteSession: options.bindRemoteSession,
+            flowEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+        });
+        this.routePacketDispatch = new spot_route_packet_dispatch_1.ZLinkSpotRoutePacketDispatch({
+            packetHandlers: this.packetHandlers,
+            nativeSpotId: options.nativeSpotId,
+            serial: options.serial,
+            getTarget: options.getTarget,
+            providerResolver: options.providerResolver,
+            messageSerializers: options.messageSerializers,
+            dispatchErrors: options.dispatchErrors,
+            claimApplicationWork: options.claimApplicationWork
+        });
+        this.routedActorAdmission = new spot_routed_actor_admission_1.ZLinkSpotRoutedActorAdmission({
+            serial: options.serial,
+            getTarget: options.getTarget,
+            defaultAccept: options.defaultAccept,
+            routedActorTransferProvider: options.routedActorTransferProvider,
+            commitTransferredActor: options.commitTransferredActor,
+            messageSerializers: options.messageSerializers,
+            flowEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+        });
+    }
+    configurePacketHandlers(registrations) {
+        for (const registration of registrations) {
+            if (registration.kind !== 'packet') {
+                continue;
+            }
+            const packetName = registration.packetName ?? registration.handlerType.name;
+            const existing = this.packetHandlers.get(packetName) ?? [];
+            existing.push(registration);
+            this.packetHandlers.set(packetName, existing);
+        }
+    }
+    async drain(received = undefined, retryDeadlineMs = performance.now()) {
+        if (this.routeDraining) {
+            if (received !== undefined) {
+                try {
+                    await this.dispatch(received);
+                }
+                finally {
+                    received.close();
+                }
+            }
+            return;
+        }
+        this.routeDraining = true;
+        try {
+            if (received !== undefined) {
+                try {
+                    await this.dispatch(received);
+                }
+                finally {
+                    received.close();
+                }
+                received = undefined;
+            }
+            for (;;) {
+                received ??= this.options.createReceived();
+                try {
+                    if (!this.options.nativeSpot.recvRoute(received, spot_native_flags_1.ZLINK_RECV_DONT_WAIT)) {
+                        received.close();
+                        await this.options.waitIdle();
+                        return;
+                    }
+                }
+                catch (error) {
+                    if (isRouteRecvRetryable(error)) {
+                        closeReceivedQuietly(received);
+                        if (performance.now() < retryDeadlineMs) {
+                            setTimeout(() => void this.drain(undefined, retryDeadlineMs), 10);
+                        }
+                        return;
+                    }
+                    received.close();
+                    throw error;
+                }
+                try {
+                    await this.dispatch(received);
+                }
+                finally {
+                    received.close();
+                }
+                received = this.options.createReceived();
+            }
+        }
+        finally {
+            this.routeDraining = false;
+        }
+    }
+    async dispatchFromEvent(received) {
+        try {
+            await this.dispatch(received);
+        }
+        finally {
+            received.close();
+        }
+    }
+    channelCodecs() {
+        return this.options.messageSerializers === undefined
+            ? undefined
+            : { serializers: this.options.messageSerializers };
+    }
+    async dispatch(received) {
+        if (received.parts.length < 1) {
+            return;
+        }
+        if (await this.routedBoundSessionDispatch.dispatch(received)) {
+            return;
+        }
+        const actorPacketRelay = (0, spot_remote_route_codec_1.decodeRemoteActorPacketRelay)(received.parts, this.channelCodecs(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        if (actorPacketRelay !== undefined && await this.actorPacketRelayDispatch.dispatch(received, actorPacketRelay)) {
+            return;
+        }
+        if (await this.routePacketDispatch.dispatch(received)) {
+            return;
+        }
+        await this.routedActorAdmission.admit(received);
+    }
+}
+exports.ZLinkSpotRoutedFrameDispatch = ZLinkSpotRoutedFrameDispatch;
+function isRouteRecvRetryable(error) {
+    return typeof error === 'object' &&
+        error !== null &&
+        [201, 202, 204].includes(Number(error.result));
+}
+function closeReceivedQuietly(received) {
+    try {
+        received.close();
+    }
+    catch {
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { RoutingId, ZLinkSpot } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkApplicationWorkClaim } from '../admission';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import type { ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+interface ZLinkRoutedSpotPacketActivation {
+    readonly meshName?: string;
+    readonly spotId: RoutingId;
+    readonly spot: ZLinkSpot;
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly handlers: {
+        snapshot(): readonly ZLinkSpotHandlerRegistration[];
+    };
+}
+interface ZLinkRoutedSpotPacketDispatchOptions {
+    readonly resolveActivation: (spotId: RoutingId) => ZLinkRoutedSpotPacketActivation | undefined;
+    readonly claimApplicationWork?: (meshName: string) => ZLinkApplicationWorkClaim;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+}
+interface ZLinkRoutedSpotPacketContext {
+    readonly channelName: string;
+    readonly contentType?: string;
+    readonly workOptions?: ZLinkSerialWorkOptions;
+    readonly admissionTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Wait until a recovered activation has actually entered its first handler. */
+    readonly awaitFirstHandlerTurn?: boolean;
+}
+export declare class ZLinkRoutedSpotPacketDispatch {
+    private readonly options;
+    constructor(options: ZLinkRoutedSpotPacketDispatchOptions);
+    send(spotId: RoutingId, packetName: string | undefined, message: unknown, context: ZLinkRoutedSpotPacketContext): Promise<void>;
+    sendEncoded(spotId: RoutingId, packetName: string | undefined, decodePayload: () => unknown, context: ZLinkRoutedSpotPacketContext): Promise<void>;
+    request<TReply>(spotId: RoutingId, packetName: string | undefined, request: unknown, context: ZLinkRoutedSpotPacketContext): Promise<TReply>;
+    requestEncoded<TReply>(spotId: RoutingId, packetName: string | undefined, decodePayload: () => unknown, context: ZLinkRoutedSpotPacketContext): Promise<TReply>;
+    private dispatch;
+    private reportFailure;
+    private reportMissing;
+}
+export {};

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

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRoutedSpotPacketDispatch = void 0;
+const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const configuration_1 = require("../configuration");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+class ZLinkRoutedSpotPacketDispatch {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async send(spotId, packetName, message, context) {
+        await this.dispatch(spotId, packetName, () => message, context, false);
+    }
+    async sendEncoded(spotId, packetName, decodePayload, context) {
+        await this.dispatch(spotId, packetName, decodePayload, context, false);
+    }
+    async request(spotId, packetName, request, context) {
+        return await this.dispatch(spotId, packetName, () => request, context, true);
+    }
+    async requestEncoded(spotId, packetName, decodePayload, context) {
+        return await this.dispatch(spotId, packetName, decodePayload, context, true);
+    }
+    async dispatch(spotId, packetName, decodePayload, context, returnResponse) {
+        const activation = this.options.resolveActivation(spotId);
+        if (activation === undefined) {
+            this.reportMissing(spotId, packetName, context, returnResponse);
+            if (!returnResponse) {
+                return undefined;
+            }
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
+        }
+        const registrations = activation.handlers.snapshot().filter((registration) => registration.kind === 'packet' &&
+            (registration.packetName ?? registration.handlerType.name) === (packetName ?? ''));
+        if (registrations.length === 0) {
+            this.reportMissing(spotId, packetName, context, returnResponse);
+            if (!returnResponse) {
+                return undefined;
+            }
+            throw new configuration_1.ZLinkConfigurationException(`SPOT route handler not found: ${packetName}`);
+        }
+        let response;
+        let detached = false;
+        let resolveFirstHandlerTurn;
+        let rejectFirstHandlerTurn;
+        const firstHandlerTurn = context.awaitFirstHandlerTurn === true
+            ? new Promise((resolve, reject) => {
+                resolveFirstHandlerTurn = resolve;
+                rejectFirstHandlerTurn = reject;
+            })
+            : undefined;
+        void firstHandlerTurn?.catch(() => undefined);
+        const applicationClaim = activation.meshName === undefined
+            ? undefined
+            : this.options.claimApplicationWork?.(activation.meshName);
+        const runHandler = async () => {
+            try {
+                // Decode only after the Spot has acquired both application admission
+                // and its execution authority.
+                const payload = decodePayload();
+                for (const registration of registrations) {
+                    const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(activation.spot, registration.handlerType, this.options.providerResolver);
+                    resolveFirstHandlerTurn?.();
+                    resolveFirstHandlerTurn = undefined;
+                    (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
+                    response = await handler.handle(activation.spot, payload, {
+                        channelName: context.channelName,
+                        contentType: context.contentType,
+                        packetName: packetName,
+                        metadata: (0, contracts_1.zlinkMessageMetadata)({})
+                    });
+                }
+            }
+            catch (error) {
+                rejectFirstHandlerTurn?.(error);
+                throw error;
+            }
+        };
+        try {
+            if (!returnResponse) {
+                detached = true;
+                const detachedApplicationPermit = (0, application_job_queue_scope_1.detachApplicationJobPermit)();
+                try {
+                    await activation.serial.postOneWay(async () => {
+                        try {
+                            await runHandler();
+                        }
+                        finally {
+                            detachedApplicationPermit?.releaseAfterInternalProcessing();
+                            applicationClaim?.close();
+                        }
+                    }, (error) => this.reportFailure(spotId, packetName, context, false, error), context.workOptions, { signal: context.signal });
+                    await firstHandlerTurn;
+                }
+                catch (error) {
+                    detached = false;
+                    detachedApplicationPermit?.releaseAfterInternalProcessing();
+                    rejectFirstHandlerTurn?.(error);
+                    throw error;
+                }
+            }
+            else {
+                if (activation.serial.isCurrentTurn) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Spot '${spotId}' cannot await a request to its current serial turn.`);
+                }
+                await activation.serial.execute(runHandler, context.workOptions);
+            }
+        }
+        catch (error) {
+            this.reportFailure(spotId, packetName, context, returnResponse, error);
+            throw error;
+        }
+        finally {
+            if (!detached)
+                applicationClaim?.close();
+        }
+        return returnResponse ? response : undefined;
+    }
+    reportFailure(spotId, packetName, context, returnResponse, error) {
+        const frameworkErrorKind = error instanceof contracts_1.ZLinkFrameworkException
+            ? (0, framework_errors_internal_1.internalFrameworkErrorKind)(error)
+            : undefined;
+        this.options.dispatchErrors?.report({
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotRoute,
+            messageKind: returnResponse ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+            reason: frameworkErrorKind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerQueueFull
+                || frameworkErrorKind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded
+                ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Backpressure
+                : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+            action: returnResponse ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.FailCaller : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+            packetName,
+            channelName: context.channelName,
+            spotId: String(spotId),
+            error
+        });
+    }
+    reportMissing(spotId, packetName, context, returnResponse) {
+        this.options.dispatchErrors?.report({
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotRoute,
+            messageKind: returnResponse ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing,
+            action: returnResponse ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.FailCaller : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+            packetName,
+            channelName: context.channelName,
+            spotId: String(spotId)
+        });
+    }
+}
+exports.ZLinkRoutedSpotPacketDispatch = ZLinkRoutedSpotPacketDispatch;

package/dist/runtime/spots/spot-routing-internal.d.ts

@@ -0,0 +1,28 @@
+import type { RoutingId } from '../../contracts/Common';
+import type { ZLinkFrameworkRuntimeState, ZLinkSpotKind } from '../../contracts';
+export interface ZLinkSpotRouteResolver {
+    resolve(spotId: RoutingId, signal?: AbortSignal): Promise<ZLinkSpotRouteTarget>;
+    invalidate?(spotId: RoutingId): void;
+}
+export interface ZLinkSpotRouteTarget {
+    readonly routerChannelId: string;
+    readonly targetNodeRid: RoutingId;
+    readonly spotId: RoutingId;
+    readonly spotKind: ZLinkSpotKind;
+    /** Stable registered type for authority-backed User and Instance Spots. */
+    readonly stableType?: string;
+    /** Required for user Spot operations and absent for an Entry Spot route. */
+    readonly targetSpotGeneration?: bigint;
+    /** Authority fence used to install the resolved route in the stateful runtime. */
+    readonly targetNodeGeneration?: bigint;
+    /** Authority fence used to reject a superseded Spot owner. */
+    readonly authorityOwnerGeneration?: bigint;
+    /** Internal owner identity paired with ownerLeaseGeneration. */
+    readonly targetOwnerId?: string;
+    /** Exact owner lease generation paired with the authority route. */
+    readonly ownerLeaseGeneration?: bigint;
+    /** Store version paired with the authority fence. */
+    readonly authorityStoreVersion?: string;
+    /** Current state of the owning MeshNode, when the route was resolved from Location Store. */
+    readonly targetNodeState?: ZLinkFrameworkRuntimeState;
+}

package/dist/runtime/spots/spot-routing-internal.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,64 @@
+import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkSpot } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget, ZLinkDeferredJoinAcceptedRoot } from '../actors';
+import type { ZLinkActorHandoffDispatch } from '../actors/actor-handoff';
+import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
+import type { ZLinkRemoteActorJoinActor, ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
+import type { ZLinkBackendSpotNode } from '../backend/contracts';
+export interface ZLinkEntryActorRuntime {
+    resolveActor(actorId: string): ZLinkActor | undefined;
+    commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
+    destroyActor(node: ZLinkBackendSpotNode, entryNodeRid: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    routePacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef): Promise<{
+        readonly handled: boolean;
+        readonly response?: unknown;
+    }>;
+}
+export interface ZLinkSpotActorTransferRuntime {
+    prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string, signal?: AbortSignal, canonicalInventoryDigest?: string): Promise<ZLinkDeferredJoinAcceptedRoot>;
+    discardDeferredJoinAccepted(root: ZLinkDeferredJoinAcceptedRoot, signal?: AbortSignal): Promise<void>;
+    markDeferredJoinAcceptedCommitted(root: ZLinkDeferredJoinAcceptedRoot, actorRef: ActorRef, signal?: AbortSignal): Promise<ZLinkDeferredJoinAcceptedRoot>;
+    commitAndDeliverDeferredJoinAccepted(root: ZLinkDeferredJoinAcceptedRoot, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<ZLinkDeferredJoinAcceptedRoot>;
+    getOrCreateRoutedActor(actorId: string, actorType: string, actorRef?: ActorRef, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, actorCreateRequest?: Message, signal?: AbortSignal): Promise<ZLinkRemoteActorJoinActor>;
+    materializeRoutedActor: ZLinkRoutedActorTransferProvider;
+    commitRoutedActorAuthority(actor: ZLinkActor, sourceActorRef: ActorRef, transferId: string, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, deadlineAtMs: number, signal?: AbortSignal): Promise<import('../locations/internal-location-contracts').ZLinkAuthoritySnapshot>;
+    rememberRoutedActorTransferTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
+    claimNativeActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string): Promise<ZLinkNativeActorJoinSnapshot>;
+    claimRoutedActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string, joinedLocation?: {
+        readonly spotGeneration: bigint;
+        readonly membershipEpoch: bigint;
+    }): Promise<void>;
+    publishRoutedActorOwnership(actor: ZLinkActor): Promise<void>;
+    openRoutedActorSession(actor: ZLinkActor): Promise<void>;
+    bindRoutedActorRef(actor: ZLinkActor, actorRef: ActorRef): void;
+    commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
+    clearRoutedActor(actor: ZLinkActor): void;
+    rollbackNativeActorJoin(actor: ZLinkActor, snapshot: ZLinkNativeActorJoinSnapshot): Promise<void>;
+    rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
+    actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
+}
+export interface ZLinkNativeActorJoinSnapshot {
+    readonly spotId?: RoutingId;
+    readonly spot?: ZLinkSpot;
+    readonly locationSpotId?: RoutingId;
+    readonly spotMeshName?: string;
+    readonly actorRef?: ActorRef;
+    readonly spotGeneration?: bigint;
+    readonly membershipEpoch?: bigint;
+    readonly ownerNodeGeneration?: bigint;
+}
+export interface ZLinkSpotBoundSessionRuntime {
+    receiveRoutedBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, actorRef?: ActorRef, actorPacketTarget?: unknown, signal?: AbortSignal): Promise<void>;
+    receiveRoutedBoundSessionResponse(actorId: string, packetName: string, requestSeq: bigint, message: unknown, replyOptions: ZLinkActorResponseOptions, actorPacketTarget?: unknown, signal?: AbortSignal): Promise<void>;
+    receiveRoutedBoundSessionError(actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, actorPacketTarget?: unknown, signal?: AbortSignal): Promise<void>;
+    rememberRemoteBoundSessionTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
+    resolveRemoteBoundSessionTarget(sourceNodeRid: RoutingId, sourceSessionRid: RoutingId): ZLinkRemoteBoundSessionTarget | undefined;
+    actorPacketTargetForState(actorId: string): ZLinkRemoteActorPacketTarget | undefined;
+    sendActorResponse(actor: ZLinkActor, packetName: string, requestSeq: bigint, response: unknown, replyOptions: ZLinkActorResponseOptions, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, signal?: AbortSignal): Promise<void>;
+    sendActorError(actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, actorRef?: ActorRef, signal?: AbortSignal): Promise<void>;
+}
+export interface ZLinkSpotActorHandoffRuntime {
+    capture(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch): Promise<unknown> | undefined;
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/spots/spot-serial-executor.d.ts

@@ -0,0 +1,38 @@
+import { ZLinkUserSpotExecutionMode } from '../../contracts';
+import type { ZLinkExecutionBarrier } from '../execution';
+import type { ZLinkSerialSchedulerOptions, ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+/**
+ * Owns every application serial unit that belongs to one Spot activation.
+ *
+ * Node owns these maps synchronously: no Promise boundary occurs while a
+ * child is selected, created, or removed.
+ */
+export declare class ZLinkSpotSerialExecutor {
+    private readonly spotSerial;
+    private readonly executionMode;
+    private readonly sourceSpotId;
+    private readonly actorOptions?;
+    private readonly actorSerials;
+    private readonly timerSerials;
+    private readonly actorExecutors;
+    private executionBarrier;
+    private closing;
+    private closePromise;
+    constructor(spotSerial: ZLinkSpotSerialTurnExecutor, executionMode: ZLinkUserSpotExecutionMode, sourceSpotId: unknown, actorOptions?: ZLinkSerialSchedulerOptions | undefined);
+    setExecutionBarrier(barrier: ZLinkExecutionBarrier): void;
+    executeSpot<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    executeActor<T>(actorId: string, operation: (serial: ZLinkSpotSerialTurnExecutor) => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    executeTimer<T>(timerName: string, operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    isTimerExecuting(timerName: string): boolean;
+    executeLifecycle<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    /**
+     * Makes all child queues unreachable and completes them in one synchronous
+     * ownership turn. Already accepted work remains drainable.
+     */
+    close(): Promise<void>;
+    private actorExecutor;
+    private actorSerial;
+    private timerSerial;
+    private throwIfClosing;
+}

package/dist/runtime/spots/spot-serial-executor.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotSerialExecutor = void 0;
+const contracts_1 = require("../../contracts");
+const actors_1 = require("../actors");
+const spot_serial_turn_executor_1 = require("./spot-serial-turn-executor");
+/**
+ * Owns every application serial unit that belongs to one Spot activation.
+ *
+ * Node owns these maps synchronously: no Promise boundary occurs while a
+ * child is selected, created, or removed.
+ */
+class ZLinkSpotSerialExecutor {
+    spotSerial;
+    executionMode;
+    sourceSpotId;
+    actorOptions;
+    actorSerials = new Map();
+    timerSerials = new Map();
+    actorExecutors = new Map();
+    executionBarrier;
+    closing = false;
+    closePromise;
+    constructor(spotSerial, executionMode, sourceSpotId, actorOptions) {
+        this.spotSerial = spotSerial;
+        this.executionMode = executionMode;
+        this.sourceSpotId = sourceSpotId;
+        this.actorOptions = actorOptions;
+    }
+    setExecutionBarrier(barrier) {
+        if (this.executionBarrier !== undefined && this.executionBarrier !== barrier) {
+            throw new Error('ZLink Spot serial executor already belongs to another execution barrier.');
+        }
+        this.executionBarrier = barrier;
+        this.spotSerial.setExecutionBarrier(barrier);
+        for (const serial of this.actorSerials.values())
+            serial.setExecutionBarrier(barrier);
+        for (const serial of this.timerSerials.values())
+            serial.setExecutionBarrier(barrier);
+    }
+    executeSpot(operation, workOptions) {
+        return this.spotSerial.execute(operation, workOptions);
+    }
+    executeActor(actorId, operation, workOptions) {
+        return this.actorExecutor(actorId).execute(() => operation(this.actorSerial(actorId)), workOptions);
+    }
+    /** @internal Restores a durable Actor FIFO prefix without starting it. */
+    admitActorDurablePrefix(actorId, records) {
+        const serial = this.actorSerial(actorId);
+        return this.actorExecutor(actorId).admitDurablePrefix(records.map(record => ({
+            operation: executeChild => record.operation(child => executeChild(() => child(serial))),
+            preparation: record.preparation,
+            workOptions: record.workOptions
+        })));
+    }
+    executeTimer(timerName, operation, workOptions) {
+        return this.timerSerial(timerName).execute(operation, workOptions);
+    }
+    isTimerExecuting(timerName) {
+        if (this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide) {
+            return this.spotSerial.isExecuting;
+        }
+        return this.timerSerials.get(timerName)?.isExecuting ?? false;
+    }
+    executeLifecycle(operation, workOptions) {
+        return this.spotSerial.execute(operation, { ...workOptions, lane: 'lifecycle' });
+    }
+    /**
+     * Makes all child queues unreachable and completes them in one synchronous
+     * ownership turn. Already accepted work remains drainable.
+     */
+    close() {
+        if (this.closePromise !== undefined)
+            return this.closePromise;
+        this.closing = true;
+        const childSerials = [
+            ...this.actorSerials.values(),
+            ...this.timerSerials.values()
+        ];
+        const actorExecutors = [...this.actorExecutors.values()];
+        this.actorSerials.clear();
+        this.timerSerials.clear();
+        this.actorExecutors.clear();
+        this.closePromise = Promise.all([
+            this.spotSerial.close(),
+            ...childSerials.map(serial => serial.close()),
+            ...actorExecutors.map(executor => executor.close())
+        ]).then(() => undefined);
+        return this.closePromise;
+    }
+    actorExecutor(actorId) {
+        this.throwIfClosing();
+        let executor = this.actorExecutors.get(actorId);
+        if (executor === undefined) {
+            executor = new actors_1.ZLinkActorSerialExecutor(actorId, this.sourceSpotId, this.actorOptions);
+            this.actorExecutors.set(actorId, executor);
+        }
+        return executor;
+    }
+    actorSerial(actorId) {
+        if (this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide) {
+            return this.spotSerial;
+        }
+        this.throwIfClosing();
+        let serial = this.actorSerials.get(actorId);
+        if (serial === undefined) {
+            serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(false);
+            if (this.executionBarrier !== undefined)
+                serial.setExecutionBarrier(this.executionBarrier);
+            this.actorSerials.set(actorId, serial);
+        }
+        return serial;
+    }
+    timerSerial(timerName) {
+        if (this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide) {
+            return this.spotSerial;
+        }
+        this.throwIfClosing();
+        let serial = this.timerSerials.get(timerName);
+        if (serial === undefined) {
+            serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(false);
+            if (this.executionBarrier !== undefined)
+                serial.setExecutionBarrier(this.executionBarrier);
+            this.timerSerials.set(timerName, serial);
+        }
+        return serial;
+    }
+    throwIfClosing() {
+        if (this.closing)
+            throw new Error('The Spot serial executor is closed.');
+    }
+}
+exports.ZLinkSpotSerialExecutor = ZLinkSpotSerialExecutor;