@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/execution/index.ts

@@ -66,17 +66,15 @@ export class ZLinkSpotSerialTurn {
     readonly yieldAllowed: boolean
   ) {}
 
-  bindExecutionClaim(claim: ZLinkExecutionBarrierClaim | undefined): void {
-    if (this.executionClaim !== undefined) {
-      throw new Error('ZLink Spot serial turn already owns an execution claim.');
-    }
-    this.executionClaim = claim;
-  }
-
   get isSuspended(): boolean {
     return this.suspendSignaled;
   }
 
+  /** False when a seal that does not drain yielded turns won before this resume. */
+  resumeExecutionClaim(): boolean {
+    return this.executionClaim?.resume() ?? true;
+  }
+
   releaseBoundExecutionClaim(): void {
     this.executionClaim?.release();
     this.executionClaim = undefined;
@@ -96,6 +94,14 @@ export class ZLinkSpotSerialTurn {
     this.owner = owner;
   }
 
+  /** Settles when the whole turn ends by any path, including yielded continuations. */
+  get completion(): Promise<void> {
+    return (this.owner ?? Promise.resolve()).then(
+      () => undefined,
+      () => undefined
+    );
+  }
+
   blockFrameworkOperations(): void {
     this.frameworkOperationsBlocked = true;
   }
@@ -150,7 +156,7 @@ export class ZLinkSpotSerialTurn {
       return;
     }
     this.suspendSignaled = true;
-    this.releaseBoundExecutionClaim();
+    this.executionClaim?.suspend();
     this.suspendedResolve?.();
   }
 
@@ -235,10 +241,14 @@ export function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecut
 
 export interface ZLinkExecutionBarrierSeal {
   readonly generation: bigint;
+  readonly kind: 'close' | 'relocation';
 }
 
 export interface ZLinkExecutionBarrierClaim {
   release(): void;
+  /** The turn yielded; it no longer runs until resume() admits it again. */
+  suspend(): void;
+  resume(): boolean;
 }
 
 interface ZLinkExecutionBarrierWaiter {
@@ -254,40 +264,47 @@ interface ZLinkExecutionBarrierWaiter {
 export class ZLinkExecutionBarrier {
   private generation = 0n;
   private activeClaims = 0;
+  private suspendedClaims = 0;
+  /** Claims whose turn has started and yielded at least once, until released. */
+  private yieldedTurnClaims = 0;
   private currentSeal: ZLinkExecutionBarrierSeal | undefined;
   private readonly admissionWaiters: ZLinkExecutionBarrierWaiter[] = [];
   private readonly quiescenceWaiters = new Set<() => void>();
-  private committed = false;
+  private committedSeal?: ZLinkExecutionBarrierSeal;
+
+  get isSealed(): boolean {
+    return this.currentSeal !== undefined || this.committedSeal !== undefined;
+  }
+
+  get isCloseSealed(): boolean {
+    return (this.currentSeal ?? this.committedSeal)?.kind === 'close';
+  }
 
-  async enter(): Promise<ZLinkExecutionBarrierClaim> {
-    if (this.committed) {
+  enter(): ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim> {
+    if (this.committedSeal !== undefined) {
       throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotMoving,
+        this.committedSeal.kind === 'close'
+          ? ZLinkFrameworkInternalErrorKind.RequestRejected
+          : ZLinkFrameworkInternalErrorKind.SpotMoving,
         'ZLink execution barrier is committed.'
       );
     }
     if (this.currentSeal !== undefined) {
-      return await new Promise<ZLinkExecutionBarrierClaim>((resolve, reject) => {
+      if (this.currentSeal.kind === 'close') {
+        throw createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RequestRejected,
+          'ZLink execution barrier is sealed for Close.'
+        );
+      }
+      return new Promise<ZLinkExecutionBarrierClaim>((resolve, reject) => {
         this.admissionWaiters.push({ resolve, reject });
       });
     }
     return this.createClaim();
   }
 
-  /**
-   * Re-enters a previously yielded application turn only while admission is
-   * open. A continuation must fail instead of waiting behind a relocation
-   * seal that already won the turn-boundary race.
-   */
-  tryEnter(): ZLinkExecutionBarrierClaim | undefined {
-    if (this.committed || this.currentSeal !== undefined) {
-      return undefined;
-    }
-    return this.createClaim();
-  }
-
-  seal(): ZLinkExecutionBarrierSeal {
-    if (this.committed) {
+  seal(kind: ZLinkExecutionBarrierSeal['kind'] = 'relocation'): ZLinkExecutionBarrierSeal {
+    if (this.committedSeal !== undefined) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.SpotMoving,
         'ZLink execution barrier is committed.'
@@ -296,17 +313,19 @@ export class ZLinkExecutionBarrier {
     if (this.currentSeal !== undefined) {
       throw new Error('ZLink execution barrier is already sealed.');
     }
-    const seal = Object.freeze({ generation: ++this.generation });
+    const seal = Object.freeze({ generation: ++this.generation, kind });
     this.currentSeal = seal;
     return seal;
   }
 
   async waitForQuiescence(seal: ZLinkExecutionBarrierSeal, signal?: AbortSignal): Promise<void> {
     this.requireCurrent(seal);
-    if (this.activeClaims === 0) return;
+    if (this.isQuiescent(seal)) return;
     if (signal?.aborted === true) throw signal.reason;
     await new Promise<void>((resolve, reject) => {
       const complete = () => {
+        if (!this.isQuiescent(seal)) return;
+        this.quiescenceWaiters.delete(complete);
         signal?.removeEventListener('abort', abort);
         resolve();
       };
@@ -320,6 +339,29 @@ export class ZLinkExecutionBarrier {
     this.requireCurrent(seal);
   }
 
+  /**
+   * Spot messaging §7 step 1: a Close that keeps admission open still lets every
+   * already-started (yielded) turn finish in its generation before cleanup.
+   */
+  async waitForStartedTurns(signal?: AbortSignal): Promise<void> {
+    if (this.yieldedTurnClaims === 0) return;
+    if (signal?.aborted === true) throw signal.reason;
+    await new Promise<void>((resolve, reject) => {
+      const complete = () => {
+        if (this.yieldedTurnClaims !== 0) return;
+        this.quiescenceWaiters.delete(complete);
+        signal?.removeEventListener('abort', abort);
+        resolve();
+      };
+      const abort = () => {
+        this.quiescenceWaiters.delete(complete);
+        reject(signal?.reason);
+      };
+      this.quiescenceWaiters.add(complete);
+      signal?.addEventListener('abort', abort, { once: true });
+    });
+  }
+
   abort(seal: ZLinkExecutionBarrierSeal): boolean {
     if (!this.isCurrent(seal)) return false;
     this.currentSeal = undefined;
@@ -331,9 +373,11 @@ export class ZLinkExecutionBarrier {
   commit(seal: ZLinkExecutionBarrierSeal): boolean {
     if (!this.isCurrent(seal)) return false;
     this.currentSeal = undefined;
-    this.committed = true;
+    this.committedSeal = seal;
     const error = createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.SpotMoving,
+      seal.kind === 'close'
+        ? ZLinkFrameworkInternalErrorKind.RequestRejected
+        : ZLinkFrameworkInternalErrorKind.SpotMoving,
       'ZLink execution barrier is committed.'
     );
     for (const waiter of this.admissionWaiters) waiter.reject(error);
@@ -345,18 +389,52 @@ export class ZLinkExecutionBarrier {
     return this.currentSeal?.generation === seal.generation;
   }
 
+  private isQuiescent(seal: ZLinkExecutionBarrierSeal): boolean {
+    return this.activeClaims === 0 && (seal.kind !== 'close' || this.suspendedClaims === 0);
+  }
+
+  private notifyQuiescence(): void {
+    for (const waiter of [...this.quiescenceWaiters]) waiter();
+  }
+
   private createClaim(): ZLinkExecutionBarrierClaim {
     this.activeClaims++;
-    let released = false;
+    let state: 'active' | 'suspended' | 'released' = 'active';
+    let yielded = false;
+    const release = () => {
+      if (state === 'released') return;
+      if (state === 'active') this.activeClaims--;
+      else this.suspendedClaims--;
+      if (yielded) this.yieldedTurnClaims--;
+      state = 'released';
+      this.notifyQuiescence();
+    };
     return {
-      release: () => {
-        if (released) return;
-        released = true;
+      release,
+      suspend: () => {
+        if (state !== 'active') return;
+        state = 'suspended';
+        if (!yielded) {
+          yielded = true;
+          this.yieldedTurnClaims++;
+        }
         this.activeClaims--;
-        if (this.activeClaims === 0) {
-          for (const waiter of this.quiescenceWaiters) waiter();
-          this.quiescenceWaiters.clear();
+        this.suspendedClaims++;
+        this.notifyQuiescence();
+      },
+      resume: () => {
+        if (state !== 'suspended') return state === 'active';
+        if (
+          this.committedSeal !== undefined ||
+          (this.currentSeal !== undefined && this.currentSeal.kind !== 'close')
+        ) {
+          release();
+          return false;
         }
+        state = 'active';
+        this.suspendedClaims--;
+        this.activeClaims++;
+        return true;
       }
     };
   }

package/src/runtime/execution/serial-execution-queue.ts

@@ -1,3 +1,11 @@
+import { macrotaskBoundary } from '../abort';
+import {
+  diagnosticWorkName,
+  guardStateLaneCompletion,
+  isStructuralGuardEnabled,
+  trackDiagnosticCompletion
+} from './state-lane';
+
 export type ZLinkSerialWorkLane = 'application' | 'lifecycle';
 
 export interface ZLinkSerialWorkOptions {
@@ -21,7 +29,7 @@ export const ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS: Required<ZLinkSerialSchedul
 export interface ZLinkSerialWorkRecord<T> {
   readonly acceptedSequence: bigint;
   readonly lane: ZLinkSerialWorkLane;
-  readonly operation: () => Promise<T> | T;
+  operation: () => Promise<T> | T;
   readonly context?: unknown;
   resolve(value: T): void;
   reject(reason: unknown): void;
@@ -30,6 +38,11 @@ export interface ZLinkSerialWorkRecord<T> {
   fail(reason: unknown): void;
 }
 
+/** The active lifecycle owner decides which existing application records can run. */
+export interface ZLinkSerialLifecycleContext {
+  canExecuteApplication(record: ZLinkSerialWorkRecord<unknown>): boolean;
+}
+
 /** Readiness work that must complete without claiming the serial owner. */
 export interface ZLinkSerialWorkPreparation {
   prepare(signal: AbortSignal): Promise<void>;
@@ -38,6 +51,7 @@ export interface ZLinkSerialWorkPreparation {
 
 type SerialWorkRecord<T> = Omit<ZLinkSerialWorkRecord<T>, 'acceptedSequence'> & {
   acceptedSequence: bigint;
+  readonly operationEnvelope: boolean;
   readonly preparation?: ZLinkSerialWorkPreparation;
   preparationState: 'idle' | 'pending' | 'canceling' | 'ready' | 'failed';
   preparationController?: AbortController;
@@ -55,6 +69,7 @@ interface ZLinkSerialAdmissionLane {
 export class ZLinkSerialExecutionQueue {
   private readonly application: ZLinkSerialAdmissionLane;
   private readonly lifecycle: ZLinkSerialAdmissionLane;
+  private activeLifecycle?: ZLinkSerialWorkRecord<unknown>;
   private readonly ownerTimeBudget: number;
   private readonly lifecycleBurstLimit: number;
   private nextAcceptedSequence = 1n;
@@ -138,23 +153,24 @@ export class ZLinkSerialExecutionQueue {
     return this.admit(operation, options, context);
   }
 
-  snapshot(): {
-    readonly applicationMessages: number;
-    readonly applicationBytes: number;
-    readonly lifecycleMessages: number;
-    readonly lifecycleBytes: number;
-  } {
-    return {
-      applicationMessages: this.application.records.length,
-      applicationBytes: 0,
-      lifecycleMessages: this.lifecycle.records.length,
-      lifecycleBytes: 0
-    };
+  /** Holds lifecycle FIFO through an operation result while its application turns can run. */
+  submitLifecycleOperation<T>(
+    operation: () => Promise<T> | T,
+    context?: ZLinkSerialLifecycleContext
+  ): Promise<T> {
+    return this.admit(operation, { lane: 'lifecycle' }, context, undefined, true);
+  }
+
+  visitPendingApplication(visitor: (record: ZLinkSerialWorkRecord<unknown>) => void): void {
+    for (const record of this.application.records) visitor(record);
   }
 
   get hasPendingWork(): boolean {
     return (
-      this.draining || this.application.records.length > 0 || this.lifecycle.records.length > 0
+      this.draining ||
+      this.activeLifecycle !== undefined ||
+      this.application.records.length > 0 ||
+      this.lifecycle.records.length > 0
     );
   }
 
@@ -165,15 +181,25 @@ export class ZLinkSerialExecutionQueue {
 
   /** Stops new submissions while allowing the accepted FIFO to finish. */
   close(): Promise<void> {
-    this.closed = true;
+    this.closeAdmission();
     return this.whenIdle();
   }
 
+  /** Stops admission within the lifecycle operation that owns this queue's close. */
+  closeAdmission(): void {
+    this.closed = true;
+  }
+
+  get admissionClosed(): boolean {
+    return this.closed;
+  }
+
   private admit<T>(
     operation: () => Promise<T> | T,
     options: ZLinkSerialWorkOptions,
     context?: unknown,
-    preparation?: ZLinkSerialWorkPreparation
+    preparation?: ZLinkSerialWorkPreparation,
+    operationEnvelope = false
   ): Promise<T> {
     if (this.closed) throw new Error('The serial execution queue is closed.');
     const lane = options.lane ?? 'application';
@@ -189,6 +215,14 @@ export class ZLinkSerialExecutionQueue {
     const release = (): void => {
       if (released) return;
       released = true;
+      if (this.activeLifecycle === record) {
+        this.activeLifecycle = undefined;
+        if (this.application.records.length > 0 || this.lifecycle.records.length > 0) {
+          this.scheduleDrain();
+        } else if (!this.draining) {
+          this.resolveIdleWaiters();
+        }
+      }
     };
     const resolve = (value: T): void => {
       if (settled) return;
@@ -204,6 +238,7 @@ export class ZLinkSerialExecutionQueue {
       acceptedSequence: 0n,
       lane,
       operation,
+      operationEnvelope,
       context,
       preparation,
       preparationState: preparation === undefined ? 'ready' : 'idle',
@@ -275,7 +310,25 @@ export class ZLinkSerialExecutionQueue {
         }
         this.claimStartedAt ??= performance.now();
         try {
-          await this.executeRecord(record);
+          if (record.operationEnvelope) {
+            try {
+              const outcome = record.operation();
+              void Promise.resolve(outcome).then(
+                (value) => {
+                  record.resolve(value);
+                  record.release();
+                },
+                (error) => {
+                  record.reject(error);
+                  record.release();
+                }
+              );
+            } catch (error) {
+              record.fail(error);
+            }
+          } else {
+            await this.executeRecord(record);
+          }
         } catch (error) {
           record.fail(error);
         } finally {
@@ -289,13 +342,10 @@ export class ZLinkSerialExecutionQueue {
     } finally {
       this.draining = false;
       this.claimStartedAt = undefined;
-      if (
-        !waitingForPreparation &&
-        (this.application.records.length > 0 || this.lifecycle.records.length > 0)
-      ) {
+      if (!waitingForPreparation && this.selectNext() !== undefined) {
         this.scheduleDrain();
       } else {
-        if (this.application.records.length === 0 && this.lifecycle.records.length === 0) {
+        if (!this.hasPendingWork) {
           this.resolveIdleWaiters();
         }
       }
@@ -308,26 +358,34 @@ export class ZLinkSerialExecutionQueue {
         readonly record: SerialWorkRecord<unknown>;
       }
     | undefined {
-    const applicationReady = this.application.records.length > 0;
-    const lifecycleReady = this.lifecycle.records.length > 0;
+    const lifecycleOwner = this.activeLifecycle?.context as ZLinkSerialLifecycleContext | undefined;
+    const applicationRecord =
+      lifecycleOwner === undefined
+        ? this.application.records[0]
+        : this.application.records.find((record) => lifecycleOwner.canExecuteApplication(record));
+    const applicationReady = applicationRecord !== undefined;
+    const lifecycleReady = this.activeLifecycle === undefined && this.lifecycle.records.length > 0;
     if (!applicationReady && !lifecycleReady) return undefined;
     if (!applicationReady) {
       return { lane: 'lifecycle', record: this.lifecycle.records[0]! };
     }
     if (!lifecycleReady) {
-      return { lane: 'application', record: this.application.records[0]! };
+      return { lane: 'application', record: applicationRecord! };
     }
     if (!this.lifecycleDebt && this.lifecycleStreak < this.lifecycleBurstLimit) {
       return { lane: 'lifecycle', record: this.lifecycle.records[0]! };
     }
-    return { lane: 'application', record: this.application.records[0]! };
+    return { lane: 'application', record: applicationRecord! };
   }
 
   private takeSelected(selection: {
     readonly lane: ZLinkSerialWorkLane;
     readonly record: SerialWorkRecord<unknown>;
   }): ZLinkSerialWorkRecord<unknown> {
-    const record = selection.lane === 'lifecycle' ? this.takeLifecycle() : this.takeApplication();
+    const record =
+      selection.lane === 'lifecycle'
+        ? this.takeLifecycle()
+        : this.takeApplication(selection.record);
     if (record !== selection.record) {
       throw new Error('The selected serial work record changed before owner claim.');
     }
@@ -339,13 +397,17 @@ export class ZLinkSerialExecutionQueue {
     if (this.application.records.length > 0 && this.lifecycleStreak >= this.lifecycleBurstLimit) {
       this.lifecycleDebt = true;
     }
-    return this.lifecycle.records.shift()!;
+    const record = this.lifecycle.records.shift()!;
+    this.activeLifecycle = record;
+    return record;
   }
 
-  private takeApplication(): ZLinkSerialWorkRecord<unknown> {
+  private takeApplication(selected: SerialWorkRecord<unknown>): ZLinkSerialWorkRecord<unknown> {
     this.lifecycleStreak = 0;
     this.lifecycleDebt = false;
-    return this.application.records.shift()!;
+    if (this.application.records[0] === selected) return this.application.records.shift()!;
+    const index = this.application.records.indexOf(selected);
+    return this.application.records.splice(index, 1)[0]!;
   }
 
   private startPreparation(record: SerialWorkRecord<unknown>): void {
@@ -410,6 +472,93 @@ export class ZLinkSerialExecutionQueue {
   }
 }
 
+if (isStructuralGuardEnabled()) {
+  const submit = ZLinkSerialExecutionQueue.prototype.submit;
+  ZLinkSerialExecutionQueue.prototype.submit = function <T>(
+    this: ZLinkSerialExecutionQueue,
+    operation: () => Promise<T> | T,
+    options: ZLinkSerialWorkOptions = {},
+    context?: unknown
+  ): Promise<T> {
+    return guardStateLaneCompletion(
+      trackDiagnosticCompletion(
+        submit.call(this, operation, options, context) as Promise<T>,
+        `serial ${options.lane ?? 'application'} ${diagnosticWorkName(operation)}`
+      ),
+      'serial completion'
+    );
+  };
+
+  const submitPreAdmitted = ZLinkSerialExecutionQueue.prototype.submitPreAdmitted;
+  ZLinkSerialExecutionQueue.prototype.submitPreAdmitted = function <T>(
+    this: ZLinkSerialExecutionQueue,
+    operation: () => Promise<T> | T,
+    options: ZLinkSerialWorkOptions = {},
+    context?: unknown
+  ): Promise<T> {
+    return guardStateLaneCompletion(
+      trackDiagnosticCompletion(
+        submitPreAdmitted.call(this, operation, options, context) as Promise<T>,
+        `serial ${options.lane ?? 'application'} ${diagnosticWorkName(operation)}`
+      ),
+      'serial completion'
+    );
+  };
+
+  const submitContinuation = ZLinkSerialExecutionQueue.prototype.submitContinuation;
+  ZLinkSerialExecutionQueue.prototype.submitContinuation = function <T>(
+    this: ZLinkSerialExecutionQueue,
+    operation: () => Promise<T> | T,
+    context?: unknown
+  ): Promise<T> {
+    return guardStateLaneCompletion(
+      trackDiagnosticCompletion(
+        submitContinuation.call(this, operation, context) as Promise<T>,
+        `serial continuation ${diagnosticWorkName(operation)}`
+      ),
+      'serial completion'
+    );
+  };
+
+  const admitDurablePrefix = ZLinkSerialExecutionQueue.prototype.admitDurablePrefix;
+  ZLinkSerialExecutionQueue.prototype.admitDurablePrefix = function <T>(
+    this: ZLinkSerialExecutionQueue,
+    operation: () => Promise<T> | T,
+    options: ZLinkSerialWorkOptions = {},
+    context?: unknown,
+    preparation?: ZLinkSerialWorkPreparation
+  ): Promise<T> {
+    return guardStateLaneCompletion(
+      trackDiagnosticCompletion(
+        admitDurablePrefix.call(this, operation, options, context, preparation) as Promise<T>,
+        `serial durable ${diagnosticWorkName(operation)}`
+      ),
+      'serial completion'
+    );
+  };
+
+  const submitLifecycleOperation = ZLinkSerialExecutionQueue.prototype.submitLifecycleOperation;
+  ZLinkSerialExecutionQueue.prototype.submitLifecycleOperation = function <T>(
+    this: ZLinkSerialExecutionQueue,
+    operation: () => Promise<T> | T
+  ): Promise<T> {
+    return guardStateLaneCompletion(
+      trackDiagnosticCompletion(
+        submitLifecycleOperation.call(this, operation) as Promise<T>,
+        `serial lifecycle ${diagnosticWorkName(operation)}`
+      ),
+      'serial completion'
+    );
+  };
+
+  const whenIdle = ZLinkSerialExecutionQueue.prototype.whenIdle;
+  ZLinkSerialExecutionQueue.prototype.whenIdle = function (
+    this: ZLinkSerialExecutionQueue
+  ): Promise<void> {
+    return guardStateLaneCompletion(whenIdle.call(this), 'serial completion');
+  };
+}
+
 function createLane(): ZLinkSerialAdmissionLane {
   return {
     records: []
@@ -427,7 +576,3 @@ function validateNonNegative(value: number, field: string): void {
     throw new RangeError(`${field} must be a non-negative safe integer.`);
   }
 }
-
-function macrotaskBoundary(): Promise<void> {
-  return new Promise((resolve) => setImmediate(resolve));
-}