@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,601 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotActivationLifecycle = void 0;
+const contracts_1 = require("../../contracts");
+const abort_1 = require("../abort");
+const configuration_1 = require("../configuration");
+const actors_1 = require("../actors");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const payload_codec_1 = require("../messaging/payload-codec");
+const spot_provider_1 = require("./spot-provider");
+const spot_outbound_1 = require("./spot-outbound");
+const spot_handler_registry_1 = require("./spot-handler-registry");
+const spot_timer_1 = require("./spot-timer");
+const spot_serial_turn_executor_1 = require("./spot-serial-turn-executor");
+const spot_serial_executor_1 = require("./spot-serial-executor");
+const spot_context_1 = require("./spot-context");
+const spot_actor_admission_coordinator_1 = require("./spot-actor-admission-coordinator");
+const spot_activation_state_1 = require("./spot-activation-state");
+const spot_closing_1 = require("./spot-closing");
+class ZLinkSpotActivationLifecycle {
+    options;
+    actorAdmission;
+    cleanupStates = new WeakMap();
+    constructor(options) {
+        this.options = options;
+        this.actorAdmission = new spot_actor_admission_coordinator_1.ZLinkSpotActorAdmissionCoordinator(options);
+    }
+    async materializeRelocation(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, signal) {
+        const executionMode = objectKind === 'user_spot'
+            ? this.options.userSpotExecutionMode?.(meshName, implementation) ?? contracts_1.ZLinkUserSpotExecutionMode.SpotWide
+            : contracts_1.ZLinkUserSpotExecutionMode.SpotWide;
+        const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
+        const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, executionMode, spotId);
+        const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, implementation, objectKind === 'user_spot'
+            ? {
+                actorSendHandlers: this.options.spotActorSendHandlers,
+                actorRequestHandlers: this.options.spotActorRequestHandlers,
+                packetHandlers: this.options.spotPacketHandlers,
+                subscriptionHandlers: this.options.spotSubscriptionHandlers
+            }
+            : { packetHandlers: this.options.spotPacketHandlers });
+        const timers = new spot_timer_1.ZLinkSpotTimerRegistry(this.options.metrics, () => this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, undefined, this.options.statefulExecutionAllowed, (name, operation) => serialExecutor.executeTimer(name, operation), (name) => serialExecutor.isTimerExecuting(name), this.options.timerClock);
+        const outbound = new spot_outbound_1.DefaultZLinkSpotOutbound({
+            serial,
+            channelClient: this.options.channelClient,
+            spotPublisherClient: this.options.spotPublisherClient,
+            routedTransport: this.options.routedTransport,
+            spotRouterChannelIdForMesh: this.options.spotRouterChannelIdForMesh,
+            meshName,
+            addressTransport: this.options.addressTransport
+        });
+        const nativeSpot = this.options.createNativeSpot?.(meshName, spotId, {
+            objectKind,
+            stableType,
+            objectGeneration,
+            authorityOwnerGeneration
+        });
+        let instance;
+        let activation;
+        const common = {
+            meshName,
+            spotId,
+            objectGeneration: toContextGeneration(objectGeneration),
+            outbound,
+            timers,
+            serial,
+            getSpot: () => instance,
+            nodeRid: this.options.nodeRid,
+            nodeRidProvider: () => this.options.nodeRidProvider?.(meshName),
+            providerResolver: this.options.providerResolver,
+            runtimeEventPublisher: this.options.runtimeEventPublisher,
+            workerRuntime: this.options.workerRuntime,
+            close: this.contextClose(meshName, spotId, () => activation)
+        };
+        const context = objectKind === 'user_spot'
+            ? (0, spot_context_1.createSpotContext)({
+                ...common,
+                handlers,
+                relocationReady: () => {
+                    if (activation === undefined) {
+                        throw new configuration_1.ZLinkConfigurationException('Spot relocation readiness is unavailable before activation.');
+                    }
+                    return activation.relocationReadyCall();
+                },
+                ensureOperationAllowed: () => activation?.ensureContextOperationAllowed(),
+                leaveActor: (actor, contextSignal) => this.options.leaveActor(spotId, actor, contextSignal, meshName)
+            })
+            : (0, spot_context_1.createInstanceSpotContext)({
+                ...common,
+                handlers: new spot_handler_registry_1.DefaultZLinkInstanceSpotHandlerRegistry(handlers)
+            });
+        try {
+            instance = await (0, spot_provider_1.createFreshProviderInstance)(implementation, this.options.providerResolver, context);
+            Object.defineProperty(instance, 'context', {
+                configurable: true,
+                enumerable: false,
+                value: context
+            });
+            await instance.configure?.();
+            await (0, spot_timer_1.addSpotTimerRegistrations)(timers, implementation, spotId, instance, serial, { timerHandlers: this.options.spotTimerHandlers }, {
+                providerResolver: this.options.providerResolver,
+                runtimeEventPublisher: this.options.runtimeEventPublisher,
+                signal
+            });
+            activation = new spot_activation_state_1.ZLinkSpotActivation({
+                meshName,
+                spotId,
+                domain: objectKind === 'user_spot'
+                    ? {
+                        kind: 'user',
+                        executionMode,
+                        relocationCoordinationMode: this.options.userSpotRelocationCoordinationMode?.(meshName, implementation) ?? contracts_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
+                    }
+                    : { kind: 'instance', objectGeneration },
+                spotType: implementation,
+                spot: instance,
+                serial,
+                serialExecutor,
+                timers,
+                actorHandlers,
+                handlers,
+                externalActorCount: () => this.options.actorCountProvider?.(spotId) ?? 0,
+                nativeSpot,
+                metrics: this.options.metrics
+            });
+            this.options.registerActivation(activation);
+            return activation;
+        }
+        catch (error) {
+            await timers.dispose().catch(() => undefined);
+            if (instance !== undefined) {
+                await (0, handler_instance_scope_1.disposeLifecycleHandlers)(instance).catch(() => undefined);
+            }
+            await nativeSpot?.dispose().catch(() => undefined);
+            throw error;
+        }
+    }
+    async materializeInstance(meshName, instanceType, implementation, spotId, objectGeneration, signal) {
+        const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(true, spotId);
+        const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
+        const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const instanceHandlers = new spot_handler_registry_1.DefaultZLinkInstanceSpotHandlerRegistry(handlers);
+        (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, implementation, {
+            packetHandlers: this.options.spotPacketHandlers
+        });
+        const timers = new spot_timer_1.ZLinkSpotTimerRegistry(this.options.metrics, () => this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, undefined, this.options.statefulExecutionAllowed, (name, operation) => serialExecutor.executeTimer(name, operation), (name) => serialExecutor.isTimerExecuting(name), this.options.timerClock);
+        const outbound = new spot_outbound_1.DefaultZLinkSpotOutbound({
+            serial,
+            channelClient: this.options.channelClient,
+            spotPublisherClient: this.options.spotPublisherClient,
+            routedTransport: this.options.routedTransport,
+            spotRouterChannelIdForMesh: this.options.spotRouterChannelIdForMesh,
+            meshName,
+            addressTransport: this.options.addressTransport
+        });
+        let instance;
+        const context = (0, spot_context_1.createInstanceSpotContext)({
+            meshName,
+            spotId,
+            objectGeneration: toContextGeneration(objectGeneration),
+            handlers: instanceHandlers,
+            outbound,
+            timers,
+            serial,
+            getSpot: () => instance,
+            nodeRid: this.options.nodeRid,
+            nodeRidProvider: () => this.options.nodeRidProvider?.(meshName),
+            providerResolver: this.options.providerResolver,
+            runtimeEventPublisher: this.options.runtimeEventPublisher,
+            workerRuntime: this.options.workerRuntime,
+            close: this.contextClose(meshName, spotId, () => activation)
+        });
+        instance = await (0, spot_provider_1.createFreshProviderInstance)(implementation, this.options.providerResolver, context);
+        Object.defineProperty(instance, 'context', {
+            configurable: true,
+            enumerable: false,
+            value: context
+        });
+        const activation = new spot_activation_state_1.ZLinkSpotActivation({
+            meshName,
+            spotId,
+            domain: { kind: 'instance', objectGeneration },
+            spotType: implementation,
+            spot: instance,
+            serial,
+            serialExecutor,
+            timers,
+            actorHandlers,
+            handlers,
+            externalActorCount: () => this.options.actorCountProvider?.(spotId) ?? 0,
+        });
+        try {
+            await instance.configure?.();
+            await (0, spot_timer_1.addSpotTimerRegistrations)(timers, implementation, spotId, instance, serial, { timerHandlers: this.options.spotTimerHandlers }, {
+                providerResolver: this.options.providerResolver,
+                runtimeEventPublisher: this.options.runtimeEventPublisher,
+                signal
+            });
+            await serial.execute(() => instance.onInitialize?.());
+            this.options.registerActivation(activation);
+            return activation;
+        }
+        catch (error) {
+            await timers.dispose();
+            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(instance);
+            throw new AggregateError([error], `Instance Spot '${instanceType}' materialization failed for '${String(spotId)}'.`);
+        }
+    }
+    async discardInstance(activation) {
+        const errors = [];
+        try {
+            await activation.serial.execute(() => (0, spot_closing_1.invokeSpotClosing)(activation.spot.onClosing?.bind(activation.spot), contracts_1.ZLinkSpotCloseReason.ExplicitClose));
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await activation.timers.dispose();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await activation.serialExecutor.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(activation.spot);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `Instance Spot '${String(activation.spotId)}' cleanup failed.`);
+        }
+    }
+    resourcesReleased(activation) {
+        const state = this.cleanupStates.get(activation);
+        return state?.timersDisposed === true &&
+            state.handlersDisposed === true &&
+            state.nativeDisposed === true &&
+            state.locationReleased === true;
+    }
+    async create(meshName, spotType, spotId, request, signal, authority) {
+        const executionMode = this.options.userSpotExecutionMode?.(meshName, spotType)
+            ?? contracts_1.ZLinkUserSpotExecutionMode.SpotWide;
+        const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
+        const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, executionMode, spotId);
+        const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, spotType, {
+            actorSendHandlers: this.options.spotActorSendHandlers,
+            actorRequestHandlers: this.options.spotActorRequestHandlers,
+            packetHandlers: this.options.spotPacketHandlers,
+            subscriptionHandlers: this.options.spotSubscriptionHandlers
+        });
+        const timers = new spot_timer_1.ZLinkSpotTimerRegistry(this.options.metrics, () => this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, undefined, this.options.statefulExecutionAllowed, (name, operation) => serialExecutor.executeTimer(name, operation), (name) => serialExecutor.isTimerExecuting(name), this.options.timerClock);
+        let nativeSpot;
+        const outbound = new spot_outbound_1.DefaultZLinkSpotOutbound({
+            serial,
+            channelClient: this.options.channelClient,
+            spotPublisherClient: this.options.spotPublisherClient,
+            routedTransport: this.options.routedTransport,
+            spotRouterChannelIdForMesh: this.options.spotRouterChannelIdForMesh,
+            sourceSpotProvider: () => nativeSpot,
+            meshName,
+            addressTransport: this.options.addressTransport
+        });
+        // Core owns the lifecycle generation. Publish the location only after the
+        // formal Spot exists, so no synthetic generation can escape into routing.
+        nativeSpot = this.options.createNativeSpot?.(meshName, spotId, authority);
+        const spotGeneration = nativeSpot?.lifecycleGeneration;
+        if (nativeSpot === undefined || spotGeneration === undefined || spotGeneration <= 0n) {
+            await nativeSpot?.dispose();
+            if (!this.options.locationClaim.enabled) {
+                const unclaimed = { claimed: true, meshName: '' };
+                return await this.createWithoutNativeSpot(meshName, spotType, spotId, request, serial, serialExecutor, actorHandlers, handlers, timers, outbound, unclaimed, executionMode, authority?.objectGeneration ?? 0n, signal);
+            }
+            throw new configuration_1.ZLinkConfigurationException('Core Spot lifecycle generation is not available.');
+        }
+        const locationClaim = await this.options.locationClaim.claimUserSpot(meshName, spotId, spotType.name, spotGeneration);
+        if (!locationClaim.claimed) {
+            await nativeSpot.dispose();
+            return { spotId, state: contracts_1.ZLinkSpotCreateState.Existing };
+        }
+        let spot;
+        let activation;
+        let lifecycleStarted = false;
+        const context = (0, spot_context_1.createSpotContext)({
+            meshName,
+            spotId,
+            objectGeneration: toContextGeneration(spotGeneration),
+            handlers,
+            outbound,
+            timers,
+            serial,
+            getSpot: () => spot,
+            nodeRid: this.options.nodeRid,
+            nodeRidProvider: () => this.options.nodeRidProvider?.(meshName),
+            providerResolver: this.options.providerResolver,
+            runtimeEventPublisher: this.options.runtimeEventPublisher,
+            workerRuntime: this.options.workerRuntime,
+            relocationReady: () => {
+                if (activation === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException('Spot relocation readiness is unavailable before activation.');
+                }
+                return activation.relocationReadyCall();
+            },
+            ensureOperationAllowed: () => activation?.ensureContextOperationAllowed(),
+            leaveActor: (actor, contextSignal) => this.options.leaveActor(spotId, actor, contextSignal, meshName),
+            close: this.contextClose(meshName, spotId, () => activation)
+        });
+        try {
+            spot = await (0, spot_provider_1.createFreshProviderInstance)(spotType, this.options.providerResolver, context);
+            Object.defineProperty(spot, 'context', {
+                configurable: true,
+                enumerable: false,
+                value: context
+            });
+            // getOrCreateSpot registers the native Spot under this rid so core routes
+            // actor-join admission requests to it (createSpot alone does not register).
+            activation = new spot_activation_state_1.ZLinkSpotActivation({
+                meshName,
+                spotId,
+                domain: {
+                    kind: 'user',
+                    executionMode,
+                    relocationCoordinationMode: this.options.userSpotRelocationCoordinationMode?.(meshName, spotType) ?? contracts_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
+                },
+                spotType,
+                spot,
+                serial,
+                serialExecutor,
+                timers,
+                actorHandlers,
+                handlers,
+                externalActorCount: () => this.options.actorCountProvider?.(spotId) ?? 0,
+                nativeSpot,
+                metrics: this.options.metrics
+            });
+            const nativeDispatch = this.actorAdmission.attachNativeActorJoinDispatch(activation, nativeSpot);
+            activation.actorDispatch = nativeDispatch;
+            lifecycleStarted = true;
+            return await this.runCreateLifecycle(activation, spotType, request, locationClaim, nativeDispatch, signal);
+        }
+        catch (error) {
+            const cleanupErrors = [];
+            try {
+                if (activation !== undefined) {
+                    await this.cleanupActivation(activation, locationClaim.meshName, lifecycleStarted, signal);
+                }
+                else {
+                    const partialCleanup = await Promise.allSettled([
+                        timers.dispose(),
+                        ...(spot === undefined ? [] : [(0, handler_instance_scope_1.disposeLifecycleHandlers)(spot)]),
+                        nativeSpot.dispose(),
+                        this.options.locationClaim.release(locationClaim.meshName, spotId)
+                    ]);
+                    const partialErrors = partialCleanup
+                        .filter((result) => result.status === 'rejected')
+                        .map((result) => result.reason);
+                    if (partialErrors.length === 1)
+                        throw partialErrors[0];
+                    if (partialErrors.length > 1) {
+                        throw new AggregateError(partialErrors, `Spot '${spotId}' partial creation cleanup failed.`);
+                    }
+                }
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([error, ...cleanupErrors], `Spot '${spotId}' creation cleanup failed.`);
+            }
+            throw error;
+        }
+    }
+    async createWithoutNativeSpot(meshName, spotType, spotId, request, serial, serialExecutor, actorHandlers, handlers, timers, outbound, locationClaim, executionMode, objectGeneration, signal) {
+        let spot;
+        let activation;
+        const context = (0, spot_context_1.createSpotContext)({
+            meshName,
+            spotId,
+            objectGeneration: toContextGeneration(objectGeneration),
+            handlers,
+            outbound,
+            timers,
+            serial,
+            getSpot: () => spot,
+            nodeRid: this.options.nodeRid,
+            nodeRidProvider: () => this.options.nodeRidProvider?.(meshName),
+            providerResolver: this.options.providerResolver,
+            runtimeEventPublisher: this.options.runtimeEventPublisher,
+            workerRuntime: this.options.workerRuntime,
+            relocationReady: () => {
+                if (activation === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException('Spot relocation readiness is unavailable before activation.');
+                }
+                return activation.relocationReadyCall();
+            },
+            ensureOperationAllowed: () => activation?.ensureContextOperationAllowed(),
+            leaveActor: (actor, contextSignal) => this.options.leaveActor(spotId, actor, contextSignal, meshName),
+            close: this.contextClose(meshName, spotId, () => activation)
+        });
+        spot = await (0, spot_provider_1.createFreshProviderInstance)(spotType, this.options.providerResolver, context);
+        Object.defineProperty(spot, 'context', { configurable: true, enumerable: false, value: context });
+        activation = new spot_activation_state_1.ZLinkSpotActivation({
+            meshName,
+            spotId,
+            domain: {
+                kind: 'user',
+                executionMode,
+                relocationCoordinationMode: this.options.userSpotRelocationCoordinationMode?.(meshName, spotType) ?? contracts_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
+            },
+            spotType,
+            spot,
+            serial,
+            serialExecutor,
+            timers,
+            actorHandlers,
+            handlers,
+            externalActorCount: () => this.options.actorCountProvider?.(spotId) ?? 0,
+            metrics: this.options.metrics
+        });
+        return await this.runCreateLifecycle(activation, spotType, request, locationClaim, undefined, signal);
+    }
+    contextClose(meshName, spotId, activationProvider) {
+        return async (signal) => {
+            const activation = activationProvider();
+            // Native callbacks can cross a promise boundary that does not retain
+            // the serial turn context. Queue the close before calling the manager
+            // so the callback never waits for work behind its own serial turn.
+            if (activation?.serial.isExecuting === true && !activation.serial.isCurrentTurn) {
+                activation.requestClose();
+                const retry = activation.serial.post(() => this.options.closeSpot(meshName, spotId, signal));
+                this.options.detachedTaskRunner?.runDetached(`spot close ${String(spotId)}`, async () => { await retry; });
+                if (this.options.detachedTaskRunner === undefined) {
+                    void retry.catch(() => undefined);
+                }
+                return true;
+            }
+            return await this.options.closeSpot(meshName, spotId, signal);
+        };
+    }
+    async close(activation, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose) {
+        const seal = activation.sealExecution();
+        await this.closeAfterSeal(activation, seal, signal, reason);
+    }
+    async closeAfterSeal(activation, seal, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline) {
+        try {
+            await activation.waitForExecutionQuiescence(seal, signal);
+        }
+        catch (error) {
+            activation.abortExecutionSeal(seal);
+            throw error;
+        }
+        // The eager occupancy check that authorized this seal (startClose ->
+        // canClose()) ran before quiescence, so it can miss an actor join that
+        // was already queued on the serial executor at that moment. Recheck now
+        // that every turn admitted before the seal has finished, and release the
+        // seal instead of closing an occupied Spot.
+        if (!activation.canClose(reason)) {
+            activation.abortExecutionSeal(seal);
+            throw new spot_activation_state_1.ZLinkSpotCloseOccupiedError(activation.spotId);
+        }
+        if (!activation.commitExecutionSeal(seal)) {
+            throw new Error(`Spot '${String(activation.spotId)}' close seal is stale.`);
+        }
+        await this.cleanupActivation(activation, activation.meshName, true, signal, reason, deadline);
+    }
+    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        return await this.actorAdmission.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
+    }
+    /** @internal Dispatches a held Actor record after its handoff owner releases it. */
+    dispatchActorPacketDirect(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+        return this.actorAdmission.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+    }
+    /** @internal Atomically restores one durable Actor packet prefix. */
+    admitActorPacketPrefix(activation, actorId, records) {
+        return this.actorAdmission.admitActorPacketPrefix(activation, actorId, records);
+    }
+    async runCreateLifecycle(activation, spotType, request, locationClaim, nativeDispatch, signal) {
+        try {
+            await activation.spot.configure?.();
+            nativeDispatch?.configureSubscriptions(activation.handlers.snapshot());
+            await (0, spot_timer_1.addSpotTimerRegistrations)(activation.timers, spotType, activation.spotId, activation.spot, activation.serial, { timerHandlers: this.options.spotTimerHandlers }, {
+                providerResolver: this.options.providerResolver,
+                runtimeEventPublisher: this.options.runtimeEventPublisher,
+                signal
+            });
+            let createResponse;
+            await activation.serial.execute(async () => {
+                createResponse = await activation.spot.onCreate?.((0, payload_codec_1.wrapFrameworkPayloadMessage)(request, this.options.messageSerializers, (0, payload_codec_1.frameworkPayloadContentType)(request)));
+                if (createResponse?.accepted === false) {
+                    return;
+                }
+                await activation.spot.onInitialize?.();
+            });
+            if (createResponse?.accepted === false) {
+                await this.cleanupActivation(activation, locationClaim.meshName, false, signal);
+                return {
+                    spotId: activation.spotId,
+                    state: contracts_1.ZLinkSpotCreateState.Rejected,
+                    reply: this.decodeCreateReply(createResponse.reply)
+                };
+            }
+            this.options.registerActivation(activation);
+            return {
+                spotId: activation.spotId,
+                state: contracts_1.ZLinkSpotCreateState.Created,
+                reply: this.decodeCreateReply(createResponse?.reply)
+            };
+        }
+        catch (error) {
+            try {
+                await this.cleanupActivation(activation, locationClaim.meshName, true, signal);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], `Spot '${activation.spotId}' creation cleanup failed.`);
+            }
+            throw error;
+        }
+    }
+    async cleanupActivation(activation, locationMeshName, notifyClosing, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline) {
+        (0, abort_1.throwIfAborted)(signal);
+        const state = this.cleanupStates.get(activation) ?? {
+            closingAttempted: false,
+            timersDisposed: false,
+            handlersDisposed: false,
+            nativeDisposed: false,
+            locationReleased: false
+        };
+        this.cleanupStates.set(activation, state);
+        if (state.inFlight !== undefined)
+            return await state.inFlight;
+        state.inFlight = this.runCleanup(activation, locationMeshName, notifyClosing, reason, state, deadline)
+            .finally(() => { state.inFlight = undefined; });
+        return await state.inFlight;
+    }
+    async runCleanup(activation, locationMeshName, notifyClosing, reason, state, deadline) {
+        const errors = [];
+        const cleanup = async (operation, completed) => {
+            try {
+                await operation();
+                completed();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        };
+        if (notifyClosing && !state.closingAttempted) {
+            state.closingAttempted = true;
+            await cleanup(() => (0, spot_closing_1.invokeSpotClosing)(activation.spot.onClosing?.bind(activation.spot), reason, deadline), () => undefined);
+        }
+        if (!state.timersDisposed) {
+            await cleanup(() => activation.timers.dispose(), () => { state.timersDisposed = true; });
+        }
+        await cleanup(() => activation.serialExecutor.close(), () => undefined);
+        if (!state.handlersDisposed) {
+            await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(activation.spot), () => { state.handlersDisposed = true; });
+        }
+        if (!state.nativeDisposed) {
+            await cleanup(() => activation.actorDispatch?.dispose(), () => undefined);
+            await cleanup(() => activation.nativeSpot?.dispose(), () => { state.nativeDisposed = true; });
+        }
+        if (!state.locationReleased) {
+            await cleanup(() => this.options.releaseLocation(activation, locationMeshName, activation.spotId), () => { state.locationReleased = true; });
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `Spot '${activation.spotId}' cleanup failed.`);
+        }
+    }
+    decodeCreateReply(reply) {
+        if (reply === undefined) {
+            return undefined;
+        }
+        const message = (0, payload_codec_1.encodeFrameworkPayloadMessage)(reply, this.options.messageSerializers);
+        try {
+            return (0, payload_codec_1.decodeFrameworkPayloadMessage)(message, this.options.messageSerializers, undefined, (0, payload_codec_1.frameworkPayloadContentType)(message));
+        }
+        finally {
+            message.close();
+        }
+    }
+}
+exports.ZLinkSpotActivationLifecycle = ZLinkSpotActivationLifecycle;
+function toContextGeneration(generation) {
+    if (generation < 0n || generation > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new configuration_1.ZLinkConfigurationException(`Spot object generation '${generation}' cannot be represented by the Node.js public context.`);
+    }
+    return Number(generation);
+}

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

@@ -0,0 +1,20 @@
+import type { ActorRef } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import type { ZLinkBackendSpot } from '../backend/contracts';
+import { type ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkSpotActivationLifecycleOptions } from './spot-activation';
+import { ZLinkSpotActivation } from './spot-activation-state';
+import { ZLinkSpotActorJoinDispatch } from './spot-actor-join-dispatch';
+type AdmissionOptions = Pick<ZLinkSpotActivationLifecycleOptions, 'actorHandoffRuntime' | 'admission' | 'actorResolver' | 'actorTransferRuntime' | 'boundSessionRuntime' | 'detachedTaskRunner' | 'dispatchErrors' | 'locationClaim' | 'messageSerializers' | 'nativeSpotNodeProvider' | 'createReceived' | 'createTopicMessage' | 'providerResolver' | 'runtimeEventPublisher' | 'routeToActorJoinPrewarm'>;
+export declare class ZLinkSpotActorAdmissionCoordinator {
+    private readonly options;
+    constructor(options: AdmissionOptions);
+    dispatchActorPacket(activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    attachNativeActorJoinDispatch(activation: ZLinkSpotActivation, nativeSpot: ZLinkBackendSpot | undefined): ZLinkSpotActorJoinDispatch | undefined;
+    private dispatchActorPacketInActorTurn;
+    private commitNativeActorTransaction;
+    private commitTransferredActorTransaction;
+    private replayActorBacklog;
+}
+export {};