@zlink-systems/framework 0.10.0

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

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

package/src/runtime/spots/spot-serial-executor.ts

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

package/src/runtime/spots/spot-serial-turn-executor.ts

@@ -0,0 +1,319 @@
+import {
+  captureZLinkSpotSerialTurn,
+  isCurrentZLinkSpotSerialTurn,
+  runZLinkSpotSerialTurn,
+  ZLinkExecutionBarrier,
+  type ZLinkExecutionBarrierClaim,
+  ZLinkSpotSerialTurn
+} from '../execution';
+import type { SpotId } from '../../contracts';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+import {
+  ZLinkSerialExecutionQueue,
+  type ZLinkSerialSchedulerOptions,
+  type ZLinkSerialWorkOptions,
+  type ZLinkSerialWorkRecord
+} from '../execution/serial-execution-queue';
+import {
+  bindApplicationJobPermit,
+  hasApplicationJobPermit
+} from '../application-jobs/application-job-queue-scope';
+
+export class ZLinkSpotSerialTurnExecutor {
+  private readonly scheduler: ZLinkSerialExecutionQueue;
+  private depth = 0;
+  private turnSequence = 0;
+  private executionBarrier: ZLinkExecutionBarrier | undefined;
+  private resumedOwnerTurn: ZLinkSpotSerialTurn | undefined;
+  private lastActivityAtMs = performance.now();
+  activeTurnId = 0;
+
+  constructor(
+    private readonly yieldAllowed = true,
+    readonly sourceSpotId?: SpotId,
+    schedulerOptions?: ZLinkSerialSchedulerOptions
+  ) {
+    this.scheduler = new ZLinkSerialExecutionQueue(
+      (record) => this.runQueuedRecord(record),
+      {
+        ...schedulerOptions,
+        capacityError: schedulerOptions?.capacityError ?? (() =>
+          createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.WorkerQueueFull,
+            'Spot execution queue capacity was exceeded.'
+          ))
+      }
+    );
+  }
+
+  get isExecuting(): boolean {
+    return this.depth > 0;
+  }
+
+  get isCurrentTurn(): boolean {
+    return this.depth > 0 && isCurrentZLinkSpotSerialTurn(this);
+  }
+
+  get hasPendingWork(): boolean {
+    return this.scheduler.hasPendingWork;
+  }
+
+  get lastActivityAt(): number {
+    return this.lastActivityAtMs;
+  }
+
+  get currentTurn(): ZLinkSpotSerialTurn | undefined {
+    return captureZLinkSpotSerialTurn(this);
+  }
+
+  /** Stops new turns while allowing turns accepted before close to complete. */
+  close(): Promise<void> {
+    return this.scheduler.close();
+  }
+
+  /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
+  isActiveTurn(turn: ZLinkSpotSerialTurn, turnId: number): boolean {
+    return this.depth > 0
+      && (
+        this.resumedOwnerTurn === turn
+        || (turnId === this.activeTurnId && !turn.isSuspended)
+      );
+  }
+
+  setExecutionBarrier(barrier: ZLinkExecutionBarrier): void {
+    if (
+      this.executionBarrier !== undefined
+      && this.executionBarrier !== barrier
+    ) {
+      throw new Error('ZLink Spot serial executor already belongs to another execution barrier.');
+    }
+    if (this.turnSequence !== 0 && this.executionBarrier === undefined) {
+      throw new Error('ZLink execution barrier must be attached before the first serial turn.');
+    }
+    this.executionBarrier = barrier;
+  }
+
+  /** Runs `operation` in serial order, one turn at a time. */
+  execute<T>(
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions
+  ): Promise<T> {
+    if (this.isCurrentTurn) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        'A Spot serial turn cannot implicitly execute another turn for the same owner.'
+      );
+    }
+    return this.enqueueApplicationTurn(operation, workOptions);
+  }
+
+  /**
+   * Always enqueues `operation` as its own serial turn, even when called
+   * from within the currently active turn. Detached completion callbacks use
+   * this so they never run inline inside another callback's turn.
+   */
+  post<T>(
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions
+  ): Promise<T> {
+    return this.enqueueApplicationTurn(operation, workOptions);
+  }
+
+  /**
+   * Queues a one-way turn in serial order. Handler completion is reported
+   * through `onError` and never blocks the sender turn.
+   */
+  async postOneWay(
+    operation: () => Promise<unknown> | unknown,
+    onError: (error: unknown) => void,
+    workOptions: ZLinkSerialWorkOptions = {},
+    admission: {
+      readonly signal?: AbortSignal;
+    } = {}
+  ): Promise<void> {
+    this.lastActivityAtMs = performance.now();
+    let barrierClaim: ZLinkExecutionBarrierClaim | undefined;
+    try {
+      barrierClaim = await this.executionBarrier?.enter();
+      if (admission.signal?.aborted === true) {
+        throw new DOMException('The operation was aborted.', 'AbortError');
+      }
+      const options = {
+        ...workOptions,
+        lane: workOptions.lane ?? 'application'
+      };
+      const boundOperation = bindApplicationJobPermit(operation);
+      const submitted = hasApplicationJobPermit()
+        ? this.scheduler.submitPreAdmitted(boundOperation, options, barrierClaim)
+        : this.scheduler.submit(boundOperation, options, barrierClaim);
+      void submitted.catch(error => {
+        barrierClaim?.release();
+        onError(error);
+      });
+      // Let an empty owner queue begin its terminal handler turn before the
+      // ingress record is allowed to advance to the next owner.
+      await Promise.resolve();
+    } catch (error) {
+      barrierClaim?.release();
+      throw error;
+    }
+  }
+
+  /**
+   * Enqueues the framework-owned turn that completes a boundary while normal
+   * application admission remains sealed. Callers must release the matching
+   * barrier seal after this turn finishes.
+   */
+  postBarrierTurn<T>(
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions
+  ): Promise<T> {
+    return this.enqueueFrameworkTurn(operation, workOptions);
+  }
+
+  private async enqueueApplicationTurn<T>(
+    operation: () => Promise<T> | T,
+    workOptions: ZLinkSerialWorkOptions = {}
+  ): Promise<T> {
+    this.lastActivityAtMs = performance.now();
+    let barrierClaim: ZLinkExecutionBarrierClaim | undefined;
+    try {
+      barrierClaim = await this.executionBarrier?.enter();
+      return await this.submitQueuedTurn(operation, workOptions, barrierClaim);
+    } catch (error) {
+      barrierClaim?.release();
+      throw error;
+    }
+  }
+
+  private async enqueueFrameworkTurn<T>(
+    operation: () => Promise<T> | T,
+    workOptions: ZLinkSerialWorkOptions = {}
+  ): Promise<T> {
+    this.lastActivityAtMs = performance.now();
+    // Application admission crosses the async barrier boundary before it
+    // reaches the scheduler. Give an already-authorized framework turn that
+    // same boundary so it cannot overtake admitted application records.
+    await Promise.resolve();
+    return await this.submitQueuedTurn(operation, workOptions);
+  }
+
+  private async enqueueContinuationTurn<T>(
+    operation: () => Promise<T> | T
+  ): Promise<T> {
+    this.lastActivityAtMs = performance.now();
+    await Promise.resolve();
+    return await this.scheduler.submitContinuation(operation);
+  }
+
+  private submitQueuedTurn<T>(
+    operation: () => Promise<T> | T,
+    workOptions: ZLinkSerialWorkOptions,
+    barrierClaim?: ZLinkExecutionBarrierClaim
+  ): Promise<T> {
+    const options = {
+      ...workOptions,
+      lane: workOptions.lane ?? 'application'
+    };
+    const boundOperation = bindApplicationJobPermit(operation);
+    return hasApplicationJobPermit()
+      ? this.scheduler.submitPreAdmitted(boundOperation, options, barrierClaim)
+      : this.scheduler.submit(boundOperation, options, barrierClaim);
+  }
+
+  private runQueuedRecord(record: ZLinkSerialWorkRecord<unknown>): Promise<void> {
+    return this.runTurn(
+      record.operation,
+      (value) => record.resolve(value),
+      (error) => record.reject(error),
+      record.context as ZLinkExecutionBarrierClaim | undefined,
+      record.release
+    );
+  }
+
+  yieldPromise<T>(pending: Promise<T>): Promise<T> {
+    const turn = this.currentTurn;
+    if (turn === undefined) {
+      throw new Error('yield requires a framework Spot handler turn.');
+    }
+    return turn.yieldPromise(pending);
+  }
+
+  private runTurn<T>(
+    operation: () => Promise<T> | T,
+    resolve: (value: T) => void,
+    reject: (reason: unknown) => void,
+    barrierClaim?: ZLinkExecutionBarrierClaim,
+    release?: () => void
+  ): Promise<void> {
+    const turn = new ZLinkSpotSerialTurn(
+      (resumeTurn, resume, resumeReject) => this.postResume(resumeTurn, resume, resumeReject),
+      barrierClaim,
+      this.yieldAllowed
+    );
+    const wrapped = async () => {
+      this.depth += 1;
+      this.lastActivityAtMs = performance.now();
+      this.turnSequence += 1;
+      const turnId = this.turnSequence;
+      this.activeTurnId = turnId;
+      try {
+        return await runZLinkSpotSerialTurn(this, turnId, turn, operation);
+      } finally {
+        this.depth -= 1;
+        this.activeTurnId = 0;
+      }
+    };
+    const owner = wrapped();
+    turn.bindOwner(owner);
+    owner.then(
+      () => {
+        turn.releaseBoundExecutionClaim();
+        release?.();
+      },
+      () => {
+        turn.releaseBoundExecutionClaim();
+        release?.();
+      }
+    );
+    owner.then(resolve, reject);
+    return Promise.race([
+      owner.then(() => undefined, () => undefined),
+      turn.suspended
+    ]);
+  }
+
+  private postResume(
+    turn: ZLinkSpotSerialTurn,
+    resume: () => void,
+    reject: (reason: unknown) => void
+  ): boolean {
+    const barrier = this.executionBarrier;
+    const resumeClaim = barrier?.tryEnter();
+    if (barrier !== undefined && resumeClaim === undefined) {
+      reject(createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.SpotMoving,
+        'The yielded Spot turn cannot resume after its execution unit was sealed.'
+      ));
+      return true;
+    }
+    turn.bindExecutionClaim(resumeClaim);
+    void this.enqueueContinuationTurn(async () => {
+      this.resumedOwnerTurn = turn;
+      try {
+        turn.resetSuspension();
+        resume();
+        await turn.resumeOwnerUntilNextYield();
+      } finally {
+        if (this.resumedOwnerTurn === turn) this.resumedOwnerTurn = undefined;
+      }
+    }).catch((error) => {
+      turn.releaseBoundExecutionClaim();
+      reject(error);
+    });
+    return true;
+  }
+}