@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -7,6 +7,7 @@ import {
   ZLinkSpotSerialTurn
 } from '../execution';
 import type { SpotId } from '../../contracts';
+import type { ZLinkFrameworkException } from '../../contracts/Errors/ZLinkFrameworkException';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
@@ -17,6 +18,11 @@ import {
   type ZLinkSerialWorkOptions,
   type ZLinkSerialWorkRecord
 } from '../execution/serial-execution-queue';
+import type { ZLinkSerialLifecycleContext } from '../execution/serial-execution-queue';
+
+export type ZLinkSpotApplicationTurnContext = ZLinkExecutionBarrierClaim & {
+  readonly replay?: (failure?: unknown) => Promise<unknown> | unknown;
+};
 import {
   bindApplicationJobPermit,
   hasApplicationJobPermit
@@ -29,6 +35,7 @@ export class ZLinkSpotSerialTurnExecutor {
   private executionBarrier: ZLinkExecutionBarrier | undefined;
   private resumedOwnerTurn: ZLinkSpotSerialTurn | undefined;
   private lastActivityAtMs = performance.now();
+  private lifecycleAdmissionClosed = false;
   activeTurnId = 0;
 
   constructor(
@@ -62,15 +69,41 @@ export class ZLinkSpotSerialTurnExecutor {
     return captureZLinkSpotSerialTurn(this);
   }
 
-  /** Stops new turns while allowing turns accepted before close to complete. */
-  close(): Promise<void> {
-    return this.scheduler.close();
+  /** Waits for turns admitted through the execution barrier to complete. */
+  whenIdle(): Promise<void> {
+    return this.scheduler.whenIdle();
   }
 
   closeAdmission(): void {
     this.scheduler.closeAdmission();
   }
 
+  /**
+   * Spot messaging §7 step 3: after Close ends this queue's admission, an Instance
+   * intent message is refused before admission as a released owner fence, and any
+   * other message finds no incarnation. Undefined while admission is open.
+   */
+  applicationAdmissionRefusal(instanceIntent: boolean): ZLinkFrameworkException | undefined {
+    if (!this.scheduler.admissionClosed) return undefined;
+    return instanceIntent
+      ? createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.SpotMoving,
+          'The Spot incarnation released its authority before admitting this Instance intent message.'
+        )
+      : createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+          'The Spot incarnation is closed.'
+        );
+  }
+
+  /**
+   * Spot messaging §7: once Close commits Closing, membership work can no longer
+   * enter this incarnation while Instance intent messages still queue behind Close.
+   */
+  setLifecycleAdmissionClosed(closed: boolean): void {
+    this.lifecycleAdmissionClosed = closed;
+  }
+
   /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
   isActiveTurn(turn: ZLinkSpotSerialTurn, turnId: number): boolean {
     return (
@@ -90,14 +123,18 @@ export class ZLinkSpotSerialTurnExecutor {
   }
 
   /** Runs `operation` in serial order, one turn at a time. */
-  execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {
+  execute<T>(
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions,
+    replay?: (failure?: unknown) => Promise<T>
+  ): 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);
+    return this.enqueueApplicationTurn(operation, workOptions, replay);
   }
 
   /**
@@ -119,12 +156,19 @@ export class ZLinkSpotSerialTurnExecutor {
     workOptions: ZLinkSerialWorkOptions = {},
     admission: {
       readonly signal?: AbortSignal;
-    } = {}
+    } = {},
+    replay?: (failure?: unknown) => Promise<unknown>
   ): Promise<void> {
     this.lastActivityAtMs = performance.now();
     let barrierClaim: ZLinkExecutionBarrierClaim | undefined;
     try {
-      barrierClaim = await this.executionBarrier?.enter();
+      const entry = this.executionBarrier?.enter();
+      barrierClaim = entry instanceof Promise ? await entry : entry;
+      const refusal = this.applicationAdmissionRefusal(replay !== undefined);
+      if (refusal !== undefined) throw refusal;
+      if (barrierClaim !== undefined && replay !== undefined) {
+        Object.assign(barrierClaim, { replay: bindApplicationJobPermit(replay) });
+      }
       if (admission.signal?.aborted === true) {
         throw new DOMException('The operation was aborted.', 'AbortError');
       }
@@ -161,19 +205,63 @@ export class ZLinkSpotSerialTurnExecutor {
     return this.enqueueFrameworkTurn(operation, workOptions);
   }
 
-  /** Holds this Spot's lifecycle FIFO until the full operation result settles. */
+  /** Admits membership work and holds the lifecycle FIFO until its result settles. */
   executeLifecycleOperation<T>(operation: () => Promise<T> | T): Promise<T> {
-    return this.scheduler.submitLifecycleOperation(operation);
+    let entry: ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim> | undefined;
+    try {
+      if (this.lifecycleAdmissionClosed) {
+        throw createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RequestRejected,
+          'Spot lifecycle admission is closed by a committed Close.'
+        );
+      }
+      entry = this.executionBarrier?.enter();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    const submit = (claim?: ZLinkExecutionBarrierClaim): Promise<T> => {
+      try {
+        return this.scheduler.submitLifecycleOperation(operation);
+      } catch (error) {
+        return Promise.reject(error);
+      } finally {
+        claim?.release();
+      }
+    };
+    return entry instanceof Promise ? entry.then(submit) : submit(entry);
+  }
+
+  /** Runs owner control work that establishes or completes its own admission seal. */
+  executeControlLifecycleOperation<T>(
+    operation: () => Promise<T> | T,
+    context?: ZLinkSerialLifecycleContext
+  ): Promise<T> {
+    try {
+      return this.scheduler.submitLifecycleOperation(operation, context);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
+  visitPendingApplication(visitor: (record: ZLinkSerialWorkRecord<unknown>) => void): void {
+    this.scheduler.visitPendingApplication(visitor);
   }
 
   private async enqueueApplicationTurn<T>(
     operation: () => Promise<T> | T,
-    workOptions: ZLinkSerialWorkOptions = {}
+    workOptions: ZLinkSerialWorkOptions = {},
+    replay?: (failure?: unknown) => Promise<T>
   ): Promise<T> {
     this.lastActivityAtMs = performance.now();
     let barrierClaim: ZLinkExecutionBarrierClaim | undefined;
     try {
-      barrierClaim = await this.executionBarrier?.enter();
+      const entry = this.executionBarrier?.enter();
+      barrierClaim = entry instanceof Promise ? await entry : entry;
+      const refusal = this.applicationAdmissionRefusal(replay !== undefined);
+      if (refusal !== undefined) throw refusal;
+      if (barrierClaim !== undefined && replay !== undefined) {
+        Object.assign(barrierClaim, { replay: bindApplicationJobPermit(replay) });
+      }
       return await this.submitQueuedTurn(operation, workOptions, barrierClaim);
     } catch (error) {
       barrierClaim?.release();
@@ -215,6 +303,19 @@ export class ZLinkSpotSerialTurnExecutor {
   }
 
   private runQueuedRecord(record: ZLinkSerialWorkRecord<unknown>): Promise<void> {
+    const context = record.context as ZLinkSpotApplicationTurnContext | undefined;
+    if (context?.replay !== undefined && record.operation === context.replay) {
+      context.release();
+      return Promise.resolve(this.executionBarrier?.enter()).then((claim) =>
+        this.runTurn(
+          record.operation,
+          (value) => record.resolve(value),
+          (error) => record.reject(error),
+          claim,
+          record.release
+        )
+      );
+    }
     return this.runTurn(
       record.operation,
       (value) => record.resolve(value),

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

@@ -24,13 +24,14 @@ import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
 import type { ZLinkExecutionBarrier } from '../execution';
 import { ZLinkStateLane } from '../execution/state-lane';
 import { AsyncResource } from 'node:async_hooks';
-import type { OperationClock } from '../foundation/operation-registry';
 
 const detachedTimerStateLaneResource = new AsyncResource('zlink:spot-timer');
 
-export interface ZLinkTimerClock extends OperationClock {
+export interface ZLinkTimerClock {
   now(): number;
   utcNow(): number;
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(handle: unknown): void;
 }
 
 const systemTimerClock: ZLinkTimerClock = {