@zlink-systems/framework 0.26.0 → 0.28.0

package/src/runtime/spots/spot-activation-registry.ts

@@ -1,14 +1,22 @@
+import {
+  type RoutingId,
+  type Type,
+  type ZLinkSpot,
+  type ZLinkSpotInfo,
+  ZLinkSpotCloseReason,
+  ZLinkSpotCreateState
+} from '../../contracts';
+
+import { createAbortError } from '../abort';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
 } from '../framework-errors-internal';
-import type { RoutingId, Type, ZLinkSpot, ZLinkSpotInfo } from '../../contracts';
-import type { ZLinkLocalSpotCreateResult } from './spot-manager-internal-contracts';
-import { ZLinkSpotCreateState, ZLinkSpotCloseReason } from '../../contracts';
 import type { ZLinkSpotActivation } from './spot-activation-state';
-import { ZLinkConfigurationException } from '../configuration';
-import { createAbortError } from '../abort';
 import { ZLinkSpotLifecycleMetrics } from './spot-lifecycle-metrics';
+import type { ZLinkLocalSpotCreateResult } from './spot-manager-internal-contracts';
+const DEFAULT_ACTIVE_ACTIVATION_BATCH_SIZE = 64;
+
 export { ZLinkSpotActivation } from './spot-activation-state';
 
 interface PendingSpotActivation {
@@ -39,11 +47,7 @@ export class ZLinkSpotActivationRegistry {
   private readonly lifecycleMetrics: ZLinkSpotLifecycleMetrics;
   private activeScan: Iterator<ZLinkSpotActivation> | undefined;
 
-  constructor(
-    metrics?: import('../diagnostics').ZLinkRuntimeMetrics,
-    private readonly isCommittedClose: (meshName: string, spotId: RoutingId) => boolean = () =>
-      false
-  ) {
+  constructor(metrics?: import('../diagnostics').ZLinkRuntimeMetrics) {
     this.lifecycleMetrics = new ZLinkSpotLifecycleMetrics(metrics);
   }
 
@@ -58,35 +62,21 @@ export class ZLinkSpotActivationRegistry {
 
   resolve(meshName: string, spotId: RoutingId): ZLinkSpotActivation | undefined {
     const key = spotActivationKey(meshName, spotId);
-    return this.isCommittedClose(meshName, spotId) ||
-      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: RoutingId): ZLinkSpotActivation | undefined {
     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))
+        !this.staged.has(spotActivationKey(activation.meshName, activation.spotId))
     );
     return matches.length === 1 ? matches[0] : undefined;
   }
 
   has(meshName: string, spotId: RoutingId): boolean {
     const key = spotActivationKey(meshName, spotId);
-    return (
-      !this.isCommittedClose(meshName, spotId) &&
-      !this.staged.has(key) &&
-      !this.closing.has(key) &&
-      !this.failedClose.has(key) &&
-      this.activations.has(key)
-    );
+    return !this.staged.has(key) && this.activations.has(key);
   }
 
   list(meshName: string): readonly ZLinkSpotInfo[] {
@@ -94,12 +84,7 @@ export class ZLinkSpotActivationRegistry {
       .filter((activation) => {
         if (activation.meshName !== meshName) return false;
         const key = spotActivationKey(activation.meshName, activation.spotId);
-        return (
-          !this.isCommittedClose(meshName, activation.spotId) &&
-          !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))
@@ -126,7 +111,9 @@ export class ZLinkSpotActivationRegistry {
     return this.activations.size > 0;
   }
 
-  nextActiveActivationBatch(limit = 64): readonly ZLinkSpotActivation[] {
+  nextActiveActivationBatch(
+    limit: number = DEFAULT_ACTIVE_ACTIVATION_BATCH_SIZE
+  ): readonly ZLinkSpotActivation[] {
     if (!Number.isInteger(limit) || limit <= 0)
       throw new RangeError('Activation scan limit must be positive.');
     if (this.activations.size === 0) {
@@ -262,45 +249,19 @@ export class ZLinkSpotActivationRegistry {
     create: () => Promise<ZLinkLocalSpotCreateResult>
   ): ZLinkSpotActivationOperation {
     const key = spotActivationKey(meshName, spotId);
-    if (this.isCommittedClose(meshName, spotId)) {
-      return {
-        owner: false,
-        ready: Promise.reject(
-          createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.RequestRejected,
-            `Spot '${String(spotId)}' is Closing.`
-          )
-        )
-      };
-    }
-    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 ZLinkConfigurationException(`Spot '${spotId}' cleanup has not completed.`)
-        )
-      };
-    }
     const existing = this.activations.get(key);
     if (existing !== undefined) {
-      if (existing.spotType !== spotType) {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.SpotTypeMismatch,
-          `Spot '${spotId}' already exists with a different spot type.`
-        );
-      }
       return {
         owner: false,
-        ready: Promise.resolve({ spotId, state: ZLinkSpotCreateState.Existing })
+        ready: existing.serial.execute(() => {
+          if (existing.spotType !== spotType) {
+            throw createInternalFrameworkException(
+              ZLinkFrameworkInternalErrorKind.SpotTypeMismatch,
+              `Spot '${spotId}' already exists with a different spot type.`
+            );
+          }
+          return { spotId, state: ZLinkSpotCreateState.Existing };
+        })
       };
     }
 

package/src/runtime/spots/spot-activation-state.ts

@@ -262,8 +262,8 @@ export class ZLinkSpotActivation {
     return this.serialExecutor.admitActorDurablePrefix(actorId, records);
   }
 
-  sealExecution(drainsYieldedTurns = false): ZLinkExecutionBarrierSeal {
-    return this.executionBarrier.seal(drainsYieldedTurns);
+  sealExecution(kind: ZLinkExecutionBarrierSeal['kind'] = 'relocation'): ZLinkExecutionBarrierSeal {
+    return this.executionBarrier.seal(kind);
   }
 
   waitForExecutionQuiescence(seal: ZLinkExecutionBarrierSeal, signal?: AbortSignal): Promise<void> {

package/src/runtime/spots/spot-activation.ts

@@ -114,7 +114,6 @@ 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;
@@ -133,7 +132,7 @@ export interface ZLinkSpotActivationLifecycleOptions {
   readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
   readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
   readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
-  readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+  readonly detachedTaskRunner: ZLinkDetachedTaskRunner;
   readonly admission?: ZLinkRuntimeAdmissionGate;
   readonly statefulExecutionAllowed?: () => boolean;
   readonly leaveActor: (
@@ -148,7 +147,6 @@ export interface ZLinkSpotActivationLifecycleOptions {
     objectGeneration: bigint,
     signal?: AbortSignal
   ) => Promise<boolean>;
-  readonly isSpotClosing: (activation: ZLinkSpotActivation) => boolean;
   readonly registerActivation: (activation: ZLinkSpotActivation) => void;
   readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
   readonly releaseLocation: (
@@ -187,6 +185,9 @@ export class ZLinkSpotActivationLifecycle {
   >();
 
   constructor(private readonly options: ZLinkSpotActivationLifecycleOptions) {
+    if ((options.detachedTaskRunner as unknown) === undefined) {
+      throw new ZLinkConfigurationException('Spot activation requires a detached task runner.');
+    }
     this.actorAdmission = new ZLinkSpotActorAdmissionCoordinator(options);
   }
 
@@ -255,7 +256,7 @@ export class ZLinkSpotActivationLifecycle {
     const common = {
       meshName,
       spotId,
-      objectGeneration: toContextGeneration(objectGeneration),
+      objectGeneration: objectGeneration,
       outbound,
       timers,
       serial,
@@ -343,11 +344,22 @@ export class ZLinkSpotActivationLifecycle {
       this.options.registerActivation(activation);
       return activation;
     } catch (error) {
-      await timers.dispose().catch(() => undefined);
-      if (instance !== undefined) {
-        await disposeLifecycleHandlers(instance).catch(() => undefined);
+      const cleanup = await Promise.allSettled([
+        timers.dispose(),
+        ...(instance === undefined
+          ? []
+          : [disposeLifecycleHandlers(instance, this.options.detachedTaskRunner)]),
+        ...(nativeSpot === undefined ? [] : [Promise.resolve().then(() => nativeSpot.dispose())])
+      ]);
+      const cleanupErrors = cleanup
+        .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+        .map((result) => result.reason);
+      if (cleanupErrors.length > 0) {
+        throw new AggregateError(
+          [error, ...cleanupErrors],
+          `Spot '${spotId}' relocation materialization cleanup failed.`
+        );
       }
-      await nativeSpot?.dispose().catch(() => undefined);
       throw error;
     }
   }
@@ -358,9 +370,10 @@ export class ZLinkSpotActivationLifecycle {
     implementation: Type<TSpot>,
     spotId: RoutingId,
     objectGeneration: bigint,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    serialOwner?: ZLinkSpotActivation
   ): Promise<ZLinkSpotActivation> {
-    const serial = new ZLinkSpotSerialTurnExecutor(true, spotId);
+    const serial = serialOwner?.serial ?? new ZLinkSpotSerialTurnExecutor(true, spotId);
     const serialExecutor = new ZLinkSpotSerialExecutor(
       serial,
       ZLinkUserSpotExecutionMode.SpotWide,
@@ -394,7 +407,7 @@ export class ZLinkSpotActivationLifecycle {
     const context = createInstanceSpotContext({
       meshName,
       spotId,
-      objectGeneration: toContextGeneration(objectGeneration),
+      objectGeneration: objectGeneration,
       handlers: instanceHandlers,
       outbound,
       timers,
@@ -428,6 +441,7 @@ export class ZLinkSpotActivationLifecycle {
       timers,
       actorHandlers,
       handlers,
+      executionBarrier: serialOwner?.executionBarrier,
       externalActorCount: () => this.options.actorCountProvider?.(spotId) ?? 0
     });
     try {
@@ -445,14 +459,21 @@ export class ZLinkSpotActivationLifecycle {
           signal
         }
       );
-      await serial.execute(() => instance!.onInitialize?.());
+      await (serialOwner === undefined
+        ? serial.execute(() => instance!.onInitialize?.())
+        : serial.postBarrierTurn(() => instance!.onInitialize?.()));
       this.options.registerActivation(activation);
       return activation;
     } catch (error) {
-      await timers.dispose();
-      await disposeLifecycleHandlers(instance);
+      const cleanup = await Promise.allSettled([
+        timers.dispose(),
+        disposeLifecycleHandlers(instance, this.options.detachedTaskRunner)
+      ]);
+      const cleanupErrors = cleanup
+        .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+        .map((result) => result.reason);
       throw new AggregateError(
-        [error],
+        [error, ...cleanupErrors],
         `Instance Spot '${instanceType}' materialization failed for '${String(spotId)}'.`
       );
     }
@@ -481,7 +502,7 @@ export class ZLinkSpotActivationLifecycle {
       errors.push(error);
     }
     try {
-      await disposeLifecycleHandlers(activation.spot);
+      await disposeLifecycleHandlers(activation.spot, this.options.detachedTaskRunner);
     } catch (error) {
       errors.push(error);
     }
@@ -582,7 +603,7 @@ export class ZLinkSpotActivationLifecycle {
     const context = createSpotContext({
       meshName,
       spotId,
-      objectGeneration: toContextGeneration(spotGeneration),
+      objectGeneration: spotGeneration,
       handlers,
       outbound,
       timers,
@@ -665,9 +686,13 @@ export class ZLinkSpotActivationLifecycle {
         } else {
           const partialCleanup = await Promise.allSettled([
             timers.dispose(),
-            ...(spot === undefined ? [] : [disposeLifecycleHandlers(spot)]),
-            nativeSpot.dispose(),
-            this.options.locationClaim.release(locationClaim.meshName, spotId)
+            ...(spot === undefined
+              ? []
+              : [disposeLifecycleHandlers(spot, this.options.detachedTaskRunner)]),
+            Promise.resolve().then(() => nativeSpot.dispose()),
+            Promise.resolve().then(() =>
+              this.options.locationClaim.release(locationClaim.meshName, spotId)
+            )
           ]);
           const partialErrors = partialCleanup
             .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
@@ -714,7 +739,7 @@ export class ZLinkSpotActivationLifecycle {
     const context = createSpotContext({
       meshName,
       spotId,
-      objectGeneration: toContextGeneration(objectGeneration),
+      objectGeneration: objectGeneration,
       handlers,
       outbound,
       timers,
@@ -796,12 +821,7 @@ export class ZLinkSpotActivationLifecycle {
     seal: import('../execution').ZLinkExecutionBarrierSeal,
     signal?: AbortSignal
   ): Promise<void> {
-    try {
-      await activation.waitForExecutionQuiescence(seal, signal);
-    } catch (error) {
-      activation.abortExecutionSeal(seal);
-      throw error;
-    }
+    await activation.waitForExecutionQuiescence(seal, signal);
     if (!activation.commitExecutionSeal(seal)) {
       throw new Error(`Spot '${String(activation.spotId)}' close seal is stale.`);
     }
@@ -824,6 +844,18 @@ export class ZLinkSpotActivationLifecycle {
     );
   }
 
+  async cleanupFailedIncarnation(activation: ZLinkSpotActivation): Promise<void> {
+    await this.cleanupActivation(
+      activation,
+      activation.meshName,
+      false,
+      undefined,
+      ZLinkSpotCloseReason.ExplicitClose,
+      undefined,
+      true
+    );
+  }
+
   async dispatchActorPacket(
     activation: ZLinkSpotActivation,
     actorId: string,
@@ -1040,7 +1072,7 @@ export class ZLinkSpotActivationLifecycle {
     }
     if (!state.handlersDisposed) {
       await cleanup(
-        () => disposeLifecycleHandlers(activation.spot),
+        () => disposeLifecycleHandlers(activation.spot, this.options.detachedTaskRunner),
         () => {
           state.handlersDisposed = true;
         }
@@ -1064,6 +1096,13 @@ export class ZLinkSpotActivationLifecycle {
     }
     if (
       !state.locationReleased &&
+      // Spot messaging §7 step 3: an Instance Spot's ExplicitClose releases its authority
+      // through the Close operation's Closing fence; a User Spot still releases its location.
+      !(
+        owningLifecycle &&
+        reason === ZLinkSpotCloseReason.ExplicitClose &&
+        activation.domain.kind === 'instance'
+      ) &&
       state.timersDisposed &&
       state.serialDisposed &&
       state.handlersDisposed &&
@@ -1101,12 +1140,3 @@ export class ZLinkSpotActivationLifecycle {
     }
   }
 }
-
-function toContextGeneration(generation: bigint): number {
-  if (generation < 0n || generation > BigInt(Number.MAX_SAFE_INTEGER)) {
-    throw new ZLinkConfigurationException(
-      `Spot object generation '${generation}' cannot be represented by the Node.js public context.`
-    );
-  }
-  return Number(generation);
-}

package/src/runtime/spots/spot-actor-admission-coordinator.ts

@@ -16,7 +16,6 @@ import { ZLinkSpotActivation } from './spot-activation-state';
 import { ZLinkSpotActorJoinDispatch } from './spot-actor-join-dispatch';
 import { ZLinkSpotActorPacketDispatch } from './spot-actor-packet-dispatch';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkNativeActorJoinSnapshot } from './spot-runtime-ports';
 
 type AdmissionOptions = Pick<
   ZLinkSpotActivationLifecycleOptions,
@@ -34,7 +33,6 @@ type AdmissionOptions = Pick<
   | 'providerResolver'
   | 'runtimeEventPublisher'
   | 'routeToActorJoinPrewarm'
-  | 'isSpotClosing'
 >;
 
 export class ZLinkSpotActorAdmissionCoordinator {
@@ -97,7 +95,6 @@ export class ZLinkSpotActorAdmissionCoordinator {
         'TopicMessage'
       ),
       serial: activation.serial,
-      isSpotClosing: () => this.options.isSpotClosing(activation),
       actors: {
         resolveActor: (actorId) =>
           activation.hasDepartedActor(actorId)
@@ -112,10 +109,9 @@ export class ZLinkSpotActorAdmissionCoordinator {
                 kind: 'enabled',
                 runtime: this.options.actorTransferRuntime
               },
-        commitNativeActor: (actor) => this.commitNativeActorTransaction(activation, actor),
         commitActorDeparture: (actorId) => activation.commitActorDeparture(actorId),
-        commitTransferredActor: (actor, backlog) =>
-          this.commitTransferredActorTransaction(activation, actor, backlog)
+        commitTransferredActor: (actor, backlog, sealedSession) =>
+          this.commitTransferredActorTransaction(activation, actor, backlog, sealedSession)
       },
       packets: {
         handle: (delivery) =>
@@ -130,16 +126,6 @@ export class ZLinkSpotActorAdmissionCoordinator {
         bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
           const node = this.options.nativeSpotNodeProvider?.(activation.meshName);
           if (node === undefined || routingIdsEqual(sourceNodeRid, node.routingId)) return;
-          const target = this.options.boundSessionRuntime?.resolveRemoteBoundSessionTarget(
-            sourceNodeRid,
-            sourceSessionRid
-          );
-          if (target !== undefined) {
-            this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(
-              actor.actorId,
-              target
-            );
-          }
           node.bindRemoteActorSession(actor, sourceNodeRid, sourceSessionRid);
         },
         replyNoBind: (info, parts, result) =>
@@ -251,8 +237,6 @@ export class ZLinkSpotActorAdmissionCoordinator {
           : (activation.resolveJoinedActor(targetActorId) ??
             this.options.actorResolver?.(targetActorId)),
       actorLeft: (targetActorId) => activation.hasDepartedActor(targetActorId),
-      onRemoteBoundSessionTarget: (targetActorId, target) =>
-        this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(targetActorId, target),
       onDisconnectActor: (actor) =>
         activation.serial.execute(() => activation.spot.onDisconnectActor?.(actor)),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(
@@ -275,47 +259,11 @@ export class ZLinkSpotActorAdmissionCoordinator {
     );
   }
 
-  private async commitNativeActorTransaction(
-    activation: ZLinkSpotActivation,
-    actor: ZLinkActor
-  ): Promise<void> {
-    const transfer = this.options.actorTransferRuntime;
-    let snapshot: ZLinkNativeActorJoinSnapshot | undefined;
-    let rollbackMembership: (() => void) | undefined;
-    let routeSwitchStarted = false;
-    try {
-      snapshot = await transfer?.claimNativeActorLocation(
-        actor,
-        activation.spotId,
-        activation.meshName
-      );
-      transfer?.commitRoutedActor(actor, activation.spotId, activation.spot);
-      rollbackMembership = activation.commitActorJoin(actor);
-      activation.beginActorTransfer(actor.context.actorId);
-      await activation.serial.execute(() => activation.spot.onJoinedActor(actor));
-      routeSwitchStarted = true;
-      await transfer?.publishRoutedActorOwnership(actor);
-      await transfer?.openRoutedActorSession(actor);
-      activation.cancelActorTransfer(actor.context.actorId);
-    } catch (error) {
-      if (routeSwitchStarted) throw error;
-      rollbackMembership?.();
-      try {
-        if (snapshot !== undefined) await transfer?.rollbackNativeActorJoin(actor, snapshot);
-      } catch (rollbackError) {
-        throw new AggregateError(
-          [error, rollbackError],
-          'Native actor admission and rollback both failed.'
-        );
-      }
-      throw error;
-    }
-  }
-
   private async commitTransferredActorTransaction(
     activation: ZLinkSpotActivation,
     actor: ZLinkActor,
-    backlog: readonly ZLinkActorHandoffPacket[]
+    backlog: readonly ZLinkActorHandoffPacket[],
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
   ): Promise<readonly ZLinkActorHandoffResult[]> {
     const transfer = this.options.actorTransferRuntime;
     let routeSwitchStarted = false;
@@ -328,7 +276,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
         backlog.length === 0 ? [] : await this.replayActorBacklog(activation, actor, backlog);
       await transfer?.claimRoutedActorLocation(actor, activation.spotId, activation.meshName);
       routeSwitchStarted = true;
-      await transfer?.publishRoutedActorOwnership(actor);
+      await transfer?.publishRoutedActorOwnership(actor, sealedSession);
       await transfer?.openRoutedActorSession(actor);
       activation.cancelActorTransfer(actor.context.actorId);
       return results;