@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,7 +1,6 @@
-import type { RoutingId, Type, ZLinkSpot, ZLinkSpotInfo } from '../../contracts';
-import type { ZLinkLocalSpotCreateResult } from './spot-manager-internal-contracts';
-import { ZLinkSpotCloseReason } from '../../contracts';
+import { type RoutingId, type Type, type ZLinkSpot, type ZLinkSpotInfo, ZLinkSpotCloseReason } from '../../contracts';
 import type { ZLinkSpotActivation } from './spot-activation-state';
+import type { ZLinkLocalSpotCreateResult } from './spot-manager-internal-contracts';
 export { ZLinkSpotActivation } from './spot-activation-state';
 export interface ZLinkSpotActivationOperation {
     readonly owner: boolean;
@@ -28,9 +27,10 @@ export declare class ZLinkSpotActivationRegistry {
     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

@@ -1,14 +1,13 @@
 "use strict";
 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 framework_errors_internal_1 = require("../framework-errors-internal");
 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; } });
+const DEFAULT_ACTIVE_ACTIVATION_BATCH_SIZE = 64;
+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 {
     nextId = 1;
     activations = new Map();
@@ -32,30 +31,16 @@ class ZLinkSpotActivationRegistry {
     }
     resolve(meshName, spotId) {
         const key = spotActivationKey(meshName, spotId);
-        return this.closing.has(key) || this.failedClose.has(key) || this.staged.has(key)
-            ? undefined
-            : this.activations.get(key);
+        return this.staged.has(key) ? undefined : this.activations.get(key);
     }
     resolveUnique(spotId) {
         const matches = [...this.activations.values()].filter((activation) => String(activation.spotId) === String(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)));
+            !this.staged.has(spotActivationKey(activation.meshName, activation.spotId)));
         return matches.length === 1 ? matches[0] : undefined;
     }
     has(meshName, spotId) {
         const key = spotActivationKey(meshName, spotId);
-        return (!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);
+        return !this.staged.has(key) && this.activations.has(key);
     }
     list(meshName) {
         return [...this.activations.values()]
@@ -63,7 +48,7 @@ class ZLinkSpotActivationRegistry {
             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.staged.has(key);
         })
             .map((activation) => String(activation.spotId))
             .sort((left, right) => left.localeCompare(right))
@@ -72,10 +57,21 @@ 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;
     }
-    nextActiveActivationBatch(limit = 64) {
+    nextActiveActivationBatch(limit = DEFAULT_ACTIVE_ACTIVATION_BATCH_SIZE) {
         if (!Number.isInteger(limit) || limit <= 0)
             throw new RangeError('Activation scan limit must be positive.');
         if (this.activations.size === 0) {
@@ -165,30 +161,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,36 +181,23 @@ 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);
-        const closing = this.closing.get(key);
-        if (closing !== undefined) {
-            return {
-                owner: false,
-                ready: closing.ready
-                    .catch(() => undefined)
-                    .then(() => this.getOrBegin(meshName, spotType, spotId, create).ready)
-            };
-        }
-        if (this.failedClose.has(key)) {
-            return {
-                owner: false,
-                ready: Promise.reject(new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' cleanup has not completed.`))
-            };
-        }
         const existing = this.activations.get(key);
         if (existing !== undefined) {
-            if (existing.spotType !== spotType) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotTypeMismatch, `Spot '${spotId}' already exists with a different spot type.`);
-            }
             return {
                 owner: false,
-                ready: Promise.resolve({ spotId, state: contracts_1.ZLinkSpotCreateState.Existing })
+                ready: existing.serial.execute(() => {
+                    if (existing.spotType !== spotType) {
+                        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotTypeMismatch, `Spot '${spotId}' already exists with a different spot type.`);
+                    }
+                    return { spotId, state: contracts_1.ZLinkSpotCreateState.Existing };
+                })
             };
         }
         const pending = this.pending.get(key);

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(kind?: ZLinkExecutionBarrierSeal['kind']): 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(kind = 'relocation') {
+        return this.executionBarrier.seal(kind);
     }
     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';
@@ -36,26 +36,26 @@ export interface ZLinkSpotActivationLifecycleOptions {
     readonly routedTransport?: ZLinkSpotRoutedTransport;
     readonly addressTransport?: ZLinkSpotAddressTransport;
     readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
-    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;
     readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
     readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
     readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
-    readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+    readonly detachedTaskRunner: ZLinkDetachedTaskRunner;
     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 registerActivation: (activation: ZLinkSpotActivation) => void;
     readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
     readonly releaseLocation: (activation: ZLinkSpotActivation, meshName: string, spotId: RoutingId) => Promise<void>;
@@ -73,14 +73,15 @@ export declare class ZLinkSpotActivationLifecycle {
     private readonly cleanupStates;
     constructor(options: ZLinkSpotActivationLifecycleOptions);
     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>;
+    materializeInstance<TSpot extends ZLinkInstanceSpot>(meshName: string, instanceType: string, implementation: Type<TSpot>, spotId: RoutingId, objectGeneration: bigint, signal?: AbortSignal, serialOwner?: ZLinkSpotActivation): 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>;
+    cleanupFailedIncarnation(activation: ZLinkSpotActivation): Promise<void>;
     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;