@zlink-systems/framework 0.25.0 → 0.26.0

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

@@ -14,6 +14,7 @@ export interface ZLinkSpotCloseOperation {
     readonly started: boolean;
 }
 export declare class ZLinkSpotActivationRegistry {
+    private readonly isCommittedClose;
     private nextId;
     private readonly activations;
     private readonly staged;
@@ -23,14 +24,15 @@ export declare class ZLinkSpotActivationRegistry {
     private readonly emptyWaiters;
     private readonly lifecycleMetrics;
     private activeScan;
-    constructor(metrics?: import('../diagnostics').ZLinkRuntimeMetrics);
+    constructor(metrics?: import('../diagnostics').ZLinkRuntimeMetrics, isCommittedClose?: (meshName: string, spotId: RoutingId) => boolean);
     allocateSpotId(meshName: string): RoutingId;
     resolve(meshName: string, spotId: RoutingId): ZLinkSpotActivation | undefined;
     resolveUnique(spotId: RoutingId): ZLinkSpotActivation | undefined;
     has(meshName: string, spotId: RoutingId): boolean;
-    canClose(meshName: string, spotId: RoutingId): boolean;
     list(meshName: string): readonly ZLinkSpotInfo[];
     activeActivations(): readonly ZLinkSpotActivation[];
+    activationForClose(meshName: string, spotId: RoutingId): ZLinkSpotActivation | undefined;
+    finishClose(meshName: string, spotId: RoutingId): void;
     hasActiveActivations(): boolean;
     nextActiveActivationBatch(limit?: number): readonly ZLinkSpotActivation[];
     closingOperation(meshName: string, spotId: RoutingId): ZLinkSpotCloseOperation | undefined;

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

@@ -3,13 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActivationRegistry = exports.ZLinkSpotActivation = void 0;
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
-const spot_activation_state_1 = require("./spot-activation-state");
 const configuration_1 = require("../configuration");
 const abort_1 = require("../abort");
 const spot_lifecycle_metrics_1 = require("./spot-lifecycle-metrics");
-var spot_activation_state_2 = require("./spot-activation-state");
-Object.defineProperty(exports, "ZLinkSpotActivation", { enumerable: true, get: function () { return spot_activation_state_2.ZLinkSpotActivation; } });
+var spot_activation_state_1 = require("./spot-activation-state");
+Object.defineProperty(exports, "ZLinkSpotActivation", { enumerable: true, get: function () { return spot_activation_state_1.ZLinkSpotActivation; } });
 class ZLinkSpotActivationRegistry {
+    isCommittedClose;
     nextId = 1;
     activations = new Map();
     staged = new Set();
@@ -19,7 +19,8 @@ class ZLinkSpotActivationRegistry {
     emptyWaiters = new Set();
     lifecycleMetrics;
     activeScan;
-    constructor(metrics) {
+    constructor(metrics, isCommittedClose = () => false) {
+        this.isCommittedClose = isCommittedClose;
         this.lifecycleMetrics = new spot_lifecycle_metrics_1.ZLinkSpotLifecycleMetrics(metrics);
     }
     allocateSpotId(meshName) {
@@ -32,12 +33,16 @@ class ZLinkSpotActivationRegistry {
     }
     resolve(meshName, spotId) {
         const key = spotActivationKey(meshName, spotId);
-        return this.closing.has(key) || this.failedClose.has(key) || this.staged.has(key)
+        return this.isCommittedClose(meshName, spotId) ||
+            this.closing.has(key) ||
+            this.failedClose.has(key) ||
+            this.staged.has(key)
             ? undefined
             : this.activations.get(key);
     }
     resolveUnique(spotId) {
         const matches = [...this.activations.values()].filter((activation) => String(activation.spotId) === String(spotId) &&
+            !this.isCommittedClose(activation.meshName, activation.spotId) &&
             !this.staged.has(spotActivationKey(activation.meshName, activation.spotId)) &&
             !this.closing.has(spotActivationKey(activation.meshName, activation.spotId)) &&
             !this.failedClose.has(spotActivationKey(activation.meshName, activation.spotId)));
@@ -45,25 +50,22 @@ class ZLinkSpotActivationRegistry {
     }
     has(meshName, spotId) {
         const key = spotActivationKey(meshName, spotId);
-        return (!this.staged.has(key) &&
+        return (!this.isCommittedClose(meshName, spotId) &&
+            !this.staged.has(key) &&
             !this.closing.has(key) &&
             !this.failedClose.has(key) &&
             this.activations.has(key));
     }
-    canClose(meshName, spotId) {
-        const key = spotActivationKey(meshName, spotId);
-        return (!this.staged.has(key) &&
-            !this.closing.has(key) &&
-            !this.failedClose.has(key) &&
-            this.activations.get(key)?.canClose() === true);
-    }
     list(meshName) {
         return [...this.activations.values()]
             .filter((activation) => {
             if (activation.meshName !== meshName)
                 return false;
             const key = spotActivationKey(activation.meshName, activation.spotId);
-            return !this.staged.has(key) && !this.closing.has(key) && !this.failedClose.has(key);
+            return (!this.isCommittedClose(meshName, activation.spotId) &&
+                !this.staged.has(key) &&
+                !this.closing.has(key) &&
+                !this.failedClose.has(key));
         })
             .map((activation) => String(activation.spotId))
             .sort((left, right) => left.localeCompare(right))
@@ -72,6 +74,17 @@ class ZLinkSpotActivationRegistry {
     activeActivations() {
         return [...this.activations.values()];
     }
+    activationForClose(meshName, spotId) {
+        return this.activations.get(spotActivationKey(meshName, spotId));
+    }
+    finishClose(meshName, spotId) {
+        const key = spotActivationKey(meshName, spotId);
+        if (this.activations.delete(key))
+            this.lifecycleMetrics.closed('user');
+        this.staged.delete(key);
+        this.failedClose.delete(key);
+        this.resolveEmptyWaiters();
+    }
     hasActiveActivations() {
         return this.activations.size > 0;
     }
@@ -165,30 +178,14 @@ class ZLinkSpotActivationRegistry {
         }
         const operation = {};
         let completed = false;
-        let occupiedAfterQuiescence = false;
         const ready = Promise.resolve()
             .then(() => close(activation))
             .then(() => {
             completed = true;
-        })
-            .catch((error) => {
-            // The seal's post-quiescence recheck (spot-activation.ts
-            // closeAfterSeal) found a new join and released the seal instead of
-            // closing. The activation is already back to normal operation, so
-            // this is a "did not close" outcome, not a close failure.
-            if (error instanceof spot_activation_state_1.ZLinkSpotCloseOccupiedError) {
-                occupiedAfterQuiescence = true;
-                return;
-            }
-            throw error;
         })
             .finally(() => {
             if (this.closing.get(key) === operation) {
                 this.closing.delete(key);
-                if (occupiedAfterQuiescence) {
-                    this.resolveEmptyWaiters();
-                    return;
-                }
                 if (completed || resourcesReleased(activation)) {
                     this.activations.delete(key);
                     this.staged.delete(key);
@@ -201,13 +198,19 @@ class ZLinkSpotActivationRegistry {
                 this.resolveEmptyWaiters();
             }
         })
-            .then(() => !occupiedAfterQuiescence);
+            .then(() => true);
         Object.assign(operation, { activation, ready, started: true });
         this.closing.set(key, operation);
         return operation;
     }
     getOrBegin(meshName, spotType, spotId, create) {
         const key = spotActivationKey(meshName, spotId);
+        if (this.isCommittedClose(meshName, spotId)) {
+            return {
+                owner: false,
+                ready: Promise.reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, `Spot '${String(spotId)}' is Closing.`))
+            };
+        }
         const closing = this.closing.get(key);
         if (closing !== undefined) {
             return {

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

@@ -12,6 +12,7 @@ import { ZLinkExecutionBarrier, type ZLinkExecutionBarrierSeal } from '../execut
 import type { ZLinkTimerRelocationState } from './spot-timer';
 export type ZLinkSpotActivationDomain = {
     readonly kind: 'user';
+    readonly objectGeneration?: bigint;
     readonly executionMode: ZLinkUserSpotExecutionMode;
     readonly relocationCoordinationMode: ZLinkSpotRelocationCoordinationMode;
 } | {
@@ -39,16 +40,6 @@ export interface ZLinkSpotRelocationCapture {
     readonly seal: ZLinkExecutionBarrierSeal;
     readonly timers: readonly ZLinkTimerRelocationState[];
 }
-/**
- * Internal signal that a close seal reached quiescence but the activation
- * became occupied again while it waited (an actor join queued ahead of the
- * close finished after the eager pre-seal occupancy check). This is not a
- * close failure: the seal is released, the Spot stays open, and the caller
- * reports `close(...)` as `false` instead of throwing.
- */
-export declare class ZLinkSpotCloseOccupiedError extends Error {
-    constructor(spotId: RoutingId);
-}
 export declare class ZLinkSpotActivation {
     readonly meshName: string;
     readonly spotId: RoutingId;
@@ -81,7 +72,7 @@ export declare class ZLinkSpotActivation {
     completeConsumedRelocationBoundary(outcome: ZLinkSpotRelocationReadyOutcome): Promise<void>;
     notifyRelocatedBoundary(): Promise<void>;
     executeActor<T>(actorId: string, operation: (serial: ZLinkSpotSerialTurnExecutor) => Promise<T> | T): Promise<T>;
-    sealExecution(): ZLinkExecutionBarrierSeal;
+    sealExecution(drainsYieldedTurns?: boolean): ZLinkExecutionBarrierSeal;
     waitForExecutionQuiescence(seal: ZLinkExecutionBarrierSeal, signal?: AbortSignal): Promise<void>;
     abortExecutionSeal(seal: ZLinkExecutionBarrierSeal): boolean;
     commitExecutionSeal(seal: ZLinkExecutionBarrierSeal): boolean;

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

@@ -1,25 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkSpotActivation = exports.ZLinkSpotCloseOccupiedError = void 0;
+exports.ZLinkSpotActivation = void 0;
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
 const configuration_1 = require("../configuration");
 const abort_1 = require("../abort");
 const spot_serial_executor_1 = require("./spot-serial-executor");
 const execution_1 = require("../execution");
-/**
- * Internal signal that a close seal reached quiescence but the activation
- * became occupied again while it waited (an actor join queued ahead of the
- * close finished after the eager pre-seal occupancy check). This is not a
- * close failure: the seal is released, the Spot stays open, and the caller
- * reports `close(...)` as `false` instead of throwing.
- */
-class ZLinkSpotCloseOccupiedError extends Error {
-    constructor(spotId) {
-        super(`Spot '${String(spotId)}' became occupied while its close seal reached quiescence.`);
-    }
-}
-exports.ZLinkSpotCloseOccupiedError = ZLinkSpotCloseOccupiedError;
 class ZLinkSpotActivation {
     meshName;
     spotId;
@@ -68,7 +55,7 @@ class ZLinkSpotActivation {
         this.actorDispatch = options.actorDispatch;
     }
     get objectGeneration() {
-        return this.domain.kind === 'instance' ? this.domain.objectGeneration : undefined;
+        return this.domain.objectGeneration;
     }
     get executionMode() {
         return this.domain.kind === 'user'
@@ -171,8 +158,8 @@ class ZLinkSpotActivation {
     admitActorDurablePrefix(actorId, records) {
         return this.serialExecutor.admitActorDurablePrefix(actorId, records);
     }
-    sealExecution() {
-        return this.executionBarrier.seal();
+    sealExecution(drainsYieldedTurns = false) {
+        return this.executionBarrier.seal(drainsYieldedTurns);
     }
     waitForExecutionQuiescence(seal, signal) {
         return this.executionBarrier.waitForQuiescence(seal, signal);

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

@@ -6,7 +6,7 @@ import type { ZLinkSpotActorRequestHandlerRegistration, ZLinkSpotActorSendHandle
 import { ZLinkSpotCloseReason, ZLinkSpotRelocationCoordinationMode, ZLinkUserSpotExecutionMode } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
-import type { ZLinkBackendReceived, ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendTopicMessage } from '../backend/contracts';
+import type { ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendTopicMessage } from '../backend/contracts';
 import { ZLinkDispatchErrorReporter } from '../channels';
 import { type ZLinkRemoteBoundSessionTarget } from '../actors';
 import { ZLinkWorkerRuntime } from '../workers';
@@ -39,12 +39,12 @@ export interface ZLinkSpotActivationLifecycleOptions {
     readonly channelMeshNameForChannel?: (channelName: string) => string | undefined;
     readonly providerResolver?: ZLinkProviderResolver;
     readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly closeErrorSink?: import('../diagnostics/dispatch-error-port').ZLinkDispatchErrorSink;
     readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
     readonly workerRuntime: ZLinkWorkerRuntime;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
     readonly locationClaim: ZLinkSpotLocationClaim;
     readonly createNativeSpot?: (meshName: string, spotId: RoutingId, authority?: ZLinkNativeSpotAuthority) => ZLinkBackendSpot | undefined;
-    readonly createReceived?: () => ZLinkBackendReceived;
     readonly createTopicMessage?: () => ZLinkBackendTopicMessage;
     readonly nativeSpotNodeProvider?: (meshName: string) => ZLinkBackendSpotNode | undefined;
     readonly actorResolver?: (actorId: string) => ZLinkActor | undefined;
@@ -55,7 +55,9 @@ export interface ZLinkSpotActivationLifecycleOptions {
     readonly admission?: ZLinkRuntimeAdmissionGate;
     readonly statefulExecutionAllowed?: () => boolean;
     readonly leaveActor: (spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal, meshName?: string) => Promise<void>;
-    readonly closeSpot: (meshName: string, spotId: RoutingId, signal?: AbortSignal, reason?: ZLinkSpotCloseReason) => Promise<boolean>;
+    /** Starts a context Close request after its calling turn has ended. */
+    readonly requestContextClose: (activation: ZLinkSpotActivation, objectGeneration: bigint, signal?: AbortSignal) => Promise<boolean>;
+    readonly isSpotClosing: (activation: ZLinkSpotActivation) => boolean;
     readonly registerActivation: (activation: ZLinkSpotActivation) => void;
     readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
     readonly releaseLocation: (activation: ZLinkSpotActivation, meshName: string, spotId: RoutingId) => Promise<void>;
@@ -75,12 +77,12 @@ export declare class ZLinkSpotActivationLifecycle {
     materializeRelocation<TSpot extends ZLinkSpot | ZLinkInstanceSpot>(meshName: string, objectKind: 'user_spot' | 'instance_spot', stableType: string, implementation: Type<TSpot>, spotId: RoutingId, objectGeneration: bigint, authorityOwnerGeneration: bigint, signal?: AbortSignal): Promise<ZLinkSpotActivation>;
     materializeInstance<TSpot extends ZLinkInstanceSpot>(meshName: string, instanceType: string, implementation: Type<TSpot>, spotId: RoutingId, objectGeneration: bigint, signal?: AbortSignal): Promise<ZLinkSpotActivation>;
     discardInstance(activation: ZLinkSpotActivation): Promise<void>;
-    resourcesReleased(activation: ZLinkSpotActivation): boolean;
     create<TSpot extends ZLinkSpot>(meshName: string, spotType: Type<TSpot>, spotId: RoutingId, request: Message, signal?: AbortSignal, authority?: ZLinkNativeSpotAuthority): Promise<ZLinkLocalSpotCreateResult>;
     private createWithoutNativeSpot;
     private contextClose;
-    close(activation: ZLinkSpotActivation, signal?: AbortSignal, reason?: ZLinkSpotCloseReason): Promise<void>;
-    closeAfterSeal(activation: ZLinkSpotActivation, seal: import('../execution').ZLinkExecutionBarrierSeal, signal?: AbortSignal, reason?: ZLinkSpotCloseReason, deadline?: Date): Promise<void>;
+    sealForClose(activation: ZLinkSpotActivation, seal: import('../execution').ZLinkExecutionBarrierSeal, signal?: AbortSignal): Promise<void>;
+    /** Returns the OnClosing failure, which cleanup records and does not rethrow. */
+    cleanupClosedActivation(activation: ZLinkSpotActivation, reason?: ZLinkSpotCloseReason, deadline?: Date): Promise<unknown>;
     dispatchActorPacket(activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     private runCreateLifecycle;
     private cleanupActivation;

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

@@ -4,6 +4,7 @@ exports.ZLinkSpotActivationLifecycle = void 0;
 const contracts_1 = require("../../contracts");
 const abort_1 = require("../abort");
 const configuration_1 = require("../configuration");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const actors_1 = require("../actors");
 const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
 const payload_codec_1 = require("../messaging/payload-codec");
@@ -72,7 +73,7 @@ class ZLinkSpotActivationLifecycle {
             providerResolver: this.options.providerResolver,
             runtimeEventPublisher: this.options.runtimeEventPublisher,
             workerRuntime: this.options.workerRuntime,
-            close: this.contextClose(meshName, spotId, () => activation)
+            close: this.contextClose(objectGeneration, () => activation)
         };
         const context = objectKind === 'user_spot'
             ? (0, spot_context_1.createSpotContext)({
@@ -110,6 +111,7 @@ class ZLinkSpotActivationLifecycle {
                 domain: objectKind === 'user_spot'
                     ? {
                         kind: 'user',
+                        objectGeneration,
                         executionMode,
                         relocationCoordinationMode: this.options.userSpotRelocationCoordinationMode?.(meshName, implementation) ?? contracts_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
                     }
@@ -171,7 +173,7 @@ class ZLinkSpotActivationLifecycle {
             providerResolver: this.options.providerResolver,
             runtimeEventPublisher: this.options.runtimeEventPublisher,
             workerRuntime: this.options.workerRuntime,
-            close: this.contextClose(meshName, spotId, () => activation)
+            close: this.contextClose(objectGeneration, () => activation)
         });
         instance = await (0, spot_provider_1.createFreshProviderInstance)(implementation, this.options.providerResolver, context);
         Object.defineProperty(instance, 'context', {
@@ -241,13 +243,6 @@ class ZLinkSpotActivationLifecycle {
             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;
@@ -315,7 +310,7 @@ class ZLinkSpotActivationLifecycle {
             },
             ensureOperationAllowed: () => activation?.ensureContextOperationAllowed(),
             leaveActor: (actor, contextSignal) => this.options.leaveActor(spotId, actor, contextSignal, meshName),
-            close: this.contextClose(meshName, spotId, () => activation)
+            close: this.contextClose(spotGeneration, () => activation)
         });
         try {
             spot = await (0, spot_provider_1.createFreshProviderInstance)(spotType, this.options.providerResolver, context);
@@ -331,6 +326,7 @@ class ZLinkSpotActivationLifecycle {
                 spotId,
                 domain: {
                     kind: 'user',
+                    objectGeneration: spotGeneration,
                     executionMode,
                     relocationCoordinationMode: this.options.userSpotRelocationCoordinationMode?.(meshName, spotType) ??
                         contracts_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
@@ -408,7 +404,7 @@ class ZLinkSpotActivationLifecycle {
             },
             ensureOperationAllowed: () => activation?.ensureContextOperationAllowed(),
             leaveActor: (actor, contextSignal) => this.options.leaveActor(spotId, actor, contextSignal, meshName),
-            close: this.contextClose(meshName, spotId, () => activation)
+            close: this.contextClose(objectGeneration, () => activation)
         });
         spot = await (0, spot_provider_1.createFreshProviderInstance)(spotType, this.options.providerResolver, context);
         Object.defineProperty(spot, 'context', {
@@ -421,6 +417,7 @@ class ZLinkSpotActivationLifecycle {
             spotId,
             domain: {
                 kind: 'user',
+                objectGeneration,
                 executionMode,
                 relocationCoordinationMode: this.options.userSpotRelocationCoordinationMode?.(meshName, spotType) ??
                     contracts_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
@@ -437,31 +434,16 @@ class ZLinkSpotActivationLifecycle {
         });
         return await this.runCreateLifecycle(activation, spotType, request, locationClaim, undefined, signal);
     }
-    contextClose(meshName, spotId, activationProvider) {
-        return async (signal) => {
+    contextClose(objectGeneration, activationProvider) {
+        return (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;
+            if (activation === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'Spot context Close requires its active generation.');
             }
-            return await this.options.closeSpot(meshName, spotId, signal);
+            return this.options.requestContextClose(activation, objectGeneration, 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) {
+    async sealForClose(activation, seal, signal) {
         try {
             await activation.waitForExecutionQuiescence(seal, signal);
         }
@@ -469,19 +451,13 @@ class ZLinkSpotActivationLifecycle {
             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);
+    }
+    /** Returns the OnClosing failure, which cleanup records and does not rethrow. */
+    async cleanupClosedActivation(activation, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline) {
+        return await this.cleanupActivation(activation, activation.meshName, true, undefined, reason, deadline, true);
     }
     async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
         return await this.actorAdmission.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
@@ -536,25 +512,28 @@ class ZLinkSpotActivationLifecycle {
             throw error;
         }
     }
-    async cleanupActivation(activation, locationMeshName, notifyClosing, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline) {
+    async cleanupActivation(activation, locationMeshName, notifyClosing, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline, owningLifecycle = false) {
         (0, abort_1.throwIfAborted)(signal);
         const state = this.cleanupStates.get(activation) ?? {
             closingAttempted: false,
             timersDisposed: false,
+            serialDisposed: false,
             handlersDisposed: false,
+            actorDispatchDisposed: 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 = this.runCleanup(activation, locationMeshName, notifyClosing, reason, state, deadline, owningLifecycle).finally(() => {
             state.inFlight = undefined;
         });
         return await state.inFlight;
     }
-    async runCleanup(activation, locationMeshName, notifyClosing, reason, state, deadline) {
+    async runCleanup(activation, locationMeshName, notifyClosing, reason, state, deadline, owningLifecycle = false) {
         const errors = [];
+        let closingFailure;
         const cleanup = async (operation, completed) => {
             try {
                 await operation();
@@ -566,26 +545,51 @@ class ZLinkSpotActivationLifecycle {
         };
         if (notifyClosing && !state.closingAttempted) {
             state.closingAttempted = true;
-            await cleanup(() => (0, spot_closing_1.invokeSpotClosing)(activation.spot.onClosing?.bind(activation.spot), reason, deadline), () => undefined);
+            try {
+                // OnClosing is user code: it runs as a Framework turn through the
+                // execution gate while the Close lifecycle item keeps its FIFO slot.
+                await activation.serial.postBarrierTurn(() => (0, spot_closing_1.invokeSpotClosing)(activation.spot.onClosing?.bind(activation.spot), reason, deadline));
+            }
+            catch (error) {
+                // An OnClosing failure is diagnostic and cleanup continues. It is
+                // returned so host shutdown can classify its teardown outcome.
+                this.options.closeErrorSink?.reportRuntimeTaskException(`spot ${String(activation.spotId)} onClosing`, error);
+                closingFailure = error;
+            }
         }
         if (!state.timersDisposed) {
             await cleanup(() => activation.timers.dispose(), () => {
                 state.timersDisposed = true;
             });
         }
-        await cleanup(() => activation.serialExecutor.close(), () => undefined);
+        if (!state.serialDisposed && state.timersDisposed) {
+            await cleanup(() => owningLifecycle
+                ? activation.serialExecutor.closeChildren()
+                : activation.serialExecutor.close(), () => {
+                state.serialDisposed = true;
+            });
+        }
         if (!state.handlersDisposed) {
             await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(activation.spot), () => {
                 state.handlersDisposed = true;
             });
         }
+        if (!state.actorDispatchDisposed) {
+            await cleanup(() => activation.actorDispatch?.dispose(), () => {
+                state.actorDispatchDisposed = true;
+            });
+        }
         if (!state.nativeDisposed) {
-            await cleanup(() => activation.actorDispatch?.dispose(), () => undefined);
             await cleanup(() => activation.nativeSpot?.dispose(), () => {
                 state.nativeDisposed = true;
             });
         }
-        if (!state.locationReleased) {
+        if (!state.locationReleased &&
+            state.timersDisposed &&
+            state.serialDisposed &&
+            state.handlersDisposed &&
+            state.actorDispatchDisposed &&
+            state.nativeDisposed) {
             await cleanup(() => this.options.releaseLocation(activation, locationMeshName, activation.spotId), () => {
                 state.locationReleased = true;
             });
@@ -595,6 +599,7 @@ class ZLinkSpotActivationLifecycle {
         if (errors.length > 1) {
             throw new AggregateError(errors, `Spot '${activation.spotId}' cleanup failed.`);
         }
+        return closingFailure;
     }
     decodeCreateReply(reply) {
         if (reply === undefined) {

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

@@ -6,7 +6,7 @@ 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'>;
+type AdmissionOptions = Pick<ZLinkSpotActivationLifecycleOptions, 'actorHandoffRuntime' | 'admission' | 'actorResolver' | 'actorTransferRuntime' | 'boundSessionRuntime' | 'detachedTaskRunner' | 'dispatchErrors' | 'locationClaim' | 'messageSerializers' | 'nativeSpotNodeProvider' | 'createTopicMessage' | 'providerResolver' | 'runtimeEventPublisher' | 'routeToActorJoinPrewarm' | 'isSpotClosing'>;
 export declare class ZLinkSpotActorAdmissionCoordinator {
     private readonly options;
     constructor(options: AdmissionOptions);

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

@@ -21,9 +21,9 @@ class ZLinkSpotActorAdmissionCoordinator {
             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,
+            isSpotClosing: () => this.options.isSpotClosing(activation),
             actors: {
                 resolveActor: (actorId) => activation.hasDepartedActor(actorId)
                     ? undefined

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

@@ -1,6 +1,6 @@
 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 { ZLinkBackendActorRef, ZLinkBackendActorRecvInfo, ZLinkBackendSpot, ZLinkBackendTopicMessage } from '../backend/contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { RequestResult } from '../backend/runtime-values';
 type RuntimeMessage = Message;
@@ -47,9 +47,9 @@ export interface ZLinkDetachedTaskRunner {
 }
 interface ZLinkSpotActorJoinDispatchOptions {
     readonly nativeSpot: ZLinkBackendSpot;
-    readonly createReceived: () => ZLinkBackendReceived;
     readonly createTopicMessage: () => ZLinkBackendTopicMessage;
     readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly isSpotClosing?: () => boolean;
     readonly actors: ZLinkSpotActorAdmissionRuntime;
     readonly packets?: ZLinkSpotActorPacketRuntime;
     readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;

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

@@ -54,10 +54,9 @@ class ZLinkSpotActorJoinDispatch {
             dispatchErrors: options.dispatchErrors
         });
         this.routedFrames = new spot_routed_frame_dispatch_1.ZLinkSpotRoutedFrameDispatch({
-            nativeSpot: options.nativeSpot,
-            createReceived: options.createReceived,
             nativeSpotId: this.nativeSpotId,
             serial: options.serial,
+            isSpotClosing: options.isSpotClosing,
             resolveActor: actors.resolveActor,
             getTarget: () => actors.getTarget(),
             defaultAccept: actors.defaultAccept,
@@ -78,8 +77,7 @@ class ZLinkSpotActorJoinDispatch {
             messageSerializers: options.messageSerializers,
             providerResolver: options.providerResolver,
             dispatchErrors: options.dispatchErrors,
-            claimApplicationWork: options.claimApplicationWork,
-            waitIdle: waitSpotDispatchIdle
+            claimApplicationWork: options.claimApplicationWork
         });
         this.subscriptions = new spot_subscription_dispatch_1.ZLinkSpotSubscriptionDispatch({
             nativeSpot: options.nativeSpot,
@@ -175,7 +173,7 @@ class ZLinkSpotActorJoinDispatch {
                 await waitSpotDispatchIdle();
                 return;
             }
-            await this.nativeActorJoinAdmission.admit(request);
+            await this.options.serial.executeLifecycleOperation(() => this.nativeActorJoinAdmission.admit(request, this.options.isSpotClosing?.() === true));
         }
     }
 }

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

@@ -26,7 +26,7 @@ class ZLinkSpotActorLifecycleDrain {
             }
             if (actorRef === null || actorRef === undefined)
                 continue;
-            await this.options.serial.execute(() => {
+            await this.options.serial.executeLifecycleOperation(() => this.options.serial.execute(() => {
                 const actor = this.options.resolveActor(actorId);
                 if (actor === undefined) {
                     return undefined;
@@ -44,7 +44,7 @@ class ZLinkSpotActorLifecycleDrain {
                     return target.onDisconnectActor?.(actor);
                 }
                 return undefined;
-            });
+            }));
         }
     }
 }