@zlink-systems/framework 0.30.1 → 0.30.3

package/src/runtime/execution/index.ts

@@ -1,5 +1,4 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { ZLinkConfigurationException } from '../configuration';
 import { isAbortError } from '../abort';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -53,6 +52,7 @@ export class ZLinkSpotSerialTurn {
   private suspendedResolve: (() => void) | undefined;
   private suspendedPromise: Promise<void> | undefined;
   private suspendSignaled = false;
+  private yieldUsed = false;
   private owner: Promise<unknown> | undefined;
   private frameworkOperationsBlocked = false;
 
@@ -115,26 +115,41 @@ export class ZLinkSpotSerialTurn {
   }
 
   resetSuspension(): void {
+    this.yieldUsed = false;
     this.suspendSignaled = false;
     this.suspendedResolve = undefined;
     this.suspendedPromise = undefined;
   }
 
-  async yieldPromise<T>(pending: Promise<T>): Promise<T> {
-    if (!this.yieldAllowed) {
-      throw new ZLinkConfigurationException(
-        'yield requires a SpotWide User Spot or Instance Spot application handler.'
+  admitYield(): void {
+    const current = spotSerialTurnStorage.getStore();
+    if (
+      current?.turn !== this ||
+      !this.yieldAllowed ||
+      !current.executor.isActiveTurn(this, current.turnId) ||
+      this.yieldUsed
+    ) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        'Yield requires the current SpotWide application turn and may be used only once per turn.'
       );
     }
+    this.yieldUsed = true;
+  }
+
+  async yieldPromise<T>(pending: Promise<T>): Promise<T> {
+    this.admitYield();
     return await this.yieldFrameworkPromise(pending);
   }
 
   /** Suspends a turn only for a Framework-owned lifecycle boundary. */
   async yieldFrameworkPromise<T>(pending: Promise<T>): Promise<T> {
     this.signalSuspended();
-    const result = await pending;
-    await this.awaitResumePermit();
-    return result;
+    try {
+      return await pending;
+    } finally {
+      await this.awaitResumePermit();
+    }
   }
 
   async resumeOwnerUntilNextYield(): Promise<void> {
@@ -204,16 +219,18 @@ export function currentZLinkSpotSerialSourceId(): unknown {
 
 export function requireZLinkYieldTurn(capturedTurn?: ZLinkSpotSerialTurn): ZLinkSpotSerialTurn {
   const turn = capturedTurn ?? captureZLinkSpotSerialTurn();
-  if (turn === undefined || !turn.yieldAllowed) {
-    throw new ZLinkConfigurationException(
-      'yield requires a SpotWide User Spot or Instance Spot application handler.'
+  if (turn === undefined) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.InvalidOperation,
+      'Yield requires a current SpotWide application turn.'
     );
   }
+  turn.admitYield();
   return turn;
 }
 
 export interface ZLinkCapturedExecutionTurn {
-  yieldPromise<T>(pending: Promise<T>): Promise<T>;
+  yieldPromise<T>(operation: () => Promise<T>): Promise<T>;
   post(callback: () => void): void;
 }
 
@@ -223,7 +240,16 @@ export function captureZLinkExecutionTurn(): ZLinkCapturedExecutionTurn | undefi
     return undefined;
   }
   return {
-    yieldPromise: <T>(pending: Promise<T>) => current.turn.yieldPromise(pending),
+    yieldPromise: <T>(operation: () => Promise<T>) => {
+      const turn = requireZLinkYieldTurn(current.turn);
+      let pending: Promise<T>;
+      try {
+        pending = operation();
+      } catch (error) {
+        pending = Promise.reject(error);
+      }
+      return turn.yieldFrameworkPromise(pending);
+    },
     post: (callback: () => void) => {
       void current.executor.post(callback);
     }
@@ -241,7 +267,19 @@ export function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecut
 
 export interface ZLinkExecutionBarrierSeal {
   readonly generation: bigint;
-  readonly kind: 'close' | 'relocation';
+  readonly kind: 'close' | 'relocation' | 'activation';
+}
+
+function createExecutionBarrierAdmissionException(
+  seal: ZLinkExecutionBarrierSeal,
+  message: string
+) {
+  return createInternalFrameworkException(
+    seal.kind === 'close'
+      ? ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+      : ZLinkFrameworkInternalErrorKind.SpotMoving,
+    message
+  );
 }
 
 export interface ZLinkExecutionBarrierClaim {
@@ -282,20 +320,12 @@ export class ZLinkExecutionBarrier {
 
   enter(): ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim> {
     if (this.committedSeal !== undefined) {
-      throw createInternalFrameworkException(
-        this.committedSeal.kind === 'close'
-          ? ZLinkFrameworkInternalErrorKind.RequestRejected
-          : ZLinkFrameworkInternalErrorKind.SpotMoving,
+      throw createExecutionBarrierAdmissionException(
+        this.committedSeal,
         'ZLink execution barrier is committed.'
       );
     }
     if (this.currentSeal !== undefined) {
-      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 });
       });
@@ -374,10 +404,8 @@ export class ZLinkExecutionBarrier {
     if (!this.isCurrent(seal)) return false;
     this.currentSeal = undefined;
     this.committedSeal = seal;
-    const error = createInternalFrameworkException(
-      seal.kind === 'close'
-        ? ZLinkFrameworkInternalErrorKind.RequestRejected
-        : ZLinkFrameworkInternalErrorKind.SpotMoving,
+    const error = createExecutionBarrierAdmissionException(
+      seal,
       'ZLink execution barrier is committed.'
     );
     for (const waiter of this.admissionWaiters) waiter.reject(error);

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

@@ -1,6 +1,7 @@
 import { macrotaskBoundary } from '../abort';
 import {
   diagnosticWorkName,
+  startOutsideStateLane,
   guardStateLaneCompletion,
   isStructuralGuardEnabled,
   trackDiagnosticCompletion
@@ -10,6 +11,8 @@ export type ZLinkSerialWorkLane = 'application' | 'lifecycle';
 
 export interface ZLinkSerialWorkOptions {
   readonly onAdmitted?: () => void;
+  /** Transfers an unstarted durable record out of this FIFO in the owner turn. */
+  readonly onWithdrawable?: (withdraw: () => boolean) => void;
   readonly lane?: ZLinkSerialWorkLane;
   readonly payloadBytes?: number;
   readonly metadataBytes?: number;
@@ -167,12 +170,22 @@ export class ZLinkSerialExecutionQueue {
     return this.admit(operation, { lane: 'lifecycle' }, context, undefined, true);
   }
 
+  get retainsApplicationForLifecycle(): boolean {
+    return this.activeLifecycle?.context !== undefined;
+  }
+
   visitPendingApplication(visitor: (record: ZLinkSerialWorkRecord<unknown>) => void): void {
     for (const record of this.application.records) {
       if (record.mailbox === undefined) visitor(record);
     }
   }
 
+  get hasPendingDurableApplication(): boolean {
+    // Every application record accepted behind durable work inherits durable
+    // ownership, so the tail answers this without scanning the FIFO.
+    return this.application.records.at(-1)?.preparation !== undefined;
+  }
+
   get hasPendingWork(): boolean {
     return (
       this.consumer?.running === true ||
@@ -271,6 +284,18 @@ export class ZLinkSerialExecutionQueue {
       throw error;
     }
     options.onAdmitted?.();
+    options.onWithdrawable?.(() => {
+      const index = target.records.indexOf(record as SerialWorkRecord<unknown>);
+      if (index < 0) return false;
+      target.records.splice(index, 1);
+      record.preparationController?.abort(
+        new Error('Durable record transferred to another handoff.')
+      );
+      record.preparation?.cancel();
+      resolve(undefined as T);
+      release();
+      return true;
+    });
     this.scheduleDrain();
     return result;
   }
@@ -286,10 +311,12 @@ export class ZLinkSerialExecutionQueue {
     const consumer = this.consumer!;
     if (consumer.scheduled || consumer.running) return;
     consumer.scheduled = true;
-    queueMicrotask(() => {
-      consumer.scheduled = false;
-      void this.drain();
-    });
+    startOutsideStateLane(() =>
+      queueMicrotask(() => {
+        consumer.scheduled = false;
+        void this.drain();
+      })
+    );
   }
 
   /** Notifications carry no payload, admission sequence, result Promise, or host permit. */

package/src/runtime/execution/state-lane.ts

@@ -5,6 +5,7 @@ type ZLinkStateLaneWork<T> = () => Promise<T> | T;
 
 interface ZLinkStateLaneTurn {
   readonly lane: ZLinkStateLane;
+  readonly description: string;
   active: boolean;
 }
 
@@ -12,8 +13,19 @@ export function isStructuralGuardEnabled(): boolean {
   return process.env.ZLINK_NODE_STRUCTURAL_GUARD === '1' || process.env.NODE_ENV === 'test';
 }
 
+/** Detaches lane ownership while preserving the caller's other execution contexts. */
+export function startOutsideStateLane<T>(work: () => T): T {
+  return currentLaneStorage.exit(() =>
+    diagnosticTurnStorage === undefined ? work() : diagnosticTurnStorage.exit(work)
+  );
+}
+
 const currentLaneStorage = new AsyncLocalStorage<ZLinkStateLane>();
 const diagnosticPending = isStructuralGuardEnabled() ? new Map<number, string>() : undefined;
+const diagnosticLaneIds = isStructuralGuardEnabled()
+  ? new WeakMap<ZLinkStateLane, number>()
+  : undefined;
+let nextDiagnosticLane = 0;
 let nextDiagnosticWork = 0;
 const diagnosticTurnStorage =
   diagnosticPending === undefined ? undefined : new AsyncLocalStorage<ZLinkStateLaneTurn>();
@@ -145,10 +157,22 @@ if (isStructuralGuardEnabled()) {
     this: ZLinkStateLane,
     work: ZLinkStateLaneWork<T>
   ): Promise<T> {
-    const completion = run.call(this, () => runDiagnosticTurn(this, work)) as Promise<T>;
+    const release = registerDiagnosticWork(
+      `${diagnosticLaneName(this)} ${diagnosticWorkName(work)}`
+    );
+    let completion: Promise<T>;
+    try {
+      completion = run.call(this, () =>
+        runDiagnosticTurn(this, work, release.description)
+      ) as Promise<T>;
+    } catch (error) {
+      release();
+      throw error;
+    }
+    void completion.then(release, release);
     return guardStateLaneCompletion(
-      trackDiagnosticCompletion(completion, `state lane ${diagnosticWorkName(work)}`),
-      'another state lane completion',
+      completion,
+      `another state lane completion [${release.description}]`,
       this
     );
   };
@@ -158,10 +182,12 @@ if (isStructuralGuardEnabled()) {
     this: ZLinkStateLane,
     work: ZLinkStateLaneWork<void>
   ): boolean {
-    const release = registerDiagnosticWork(`state lane post ${diagnosticWorkName(work)}`);
+    const release = registerDiagnosticWork(
+      `${diagnosticLaneName(this)} post ${diagnosticWorkName(work)}`
+    );
     const accepted = tryPost.call(this, () => {
       try {
-        const result = runDiagnosticTurn(this, work);
+        const result = runDiagnosticTurn(this, work, release.description);
         if (result instanceof Promise) return result.finally(release);
         release();
         return result;
@@ -175,8 +201,12 @@ if (isStructuralGuardEnabled()) {
   };
 }
 
-function runDiagnosticTurn<T>(lane: ZLinkStateLane, work: ZLinkStateLaneWork<T>): Promise<T> | T {
-  const turn: ZLinkStateLaneTurn = { lane, active: true };
+function runDiagnosticTurn<T>(
+  lane: ZLinkStateLane,
+  work: ZLinkStateLaneWork<T>,
+  description: string
+): Promise<T> | T {
+  const turn: ZLinkStateLaneTurn = { lane, description, active: true };
   return diagnosticTurnStorage!.run(turn, () => {
     try {
       const result = work();
@@ -206,7 +236,10 @@ export function guardStateLaneCompletion<T>(
         return (onFulfilled: (value: T) => unknown, onRejected: (error: unknown) => unknown) => {
           const current = ZLinkStateLane.current;
           if (current !== undefined && current !== owner) {
-            throw new Error(`A state lane turn cannot wait for ${label}.`);
+            throw new Error(
+              `A state lane turn cannot wait for ${label}. ` +
+                `current turn: ${diagnosticTurnStorage?.getStore()?.description ?? UNKNOWN_DIAGNOSTIC_CALLER}`
+            );
           }
           return target.then(onFulfilled, onRejected);
         };
@@ -239,16 +272,29 @@ export function diagnosticWorkName(work: { readonly name: string }): string {
   return work.name.length > 0 ? work.name : '<anonymous>';
 }
 
-function registerDiagnosticWork(name: string): () => void {
-  if (diagnosticPending === undefined) return () => undefined;
+function diagnosticLaneName(lane: ZLinkStateLane): string {
+  let id = diagnosticLaneIds!.get(lane);
+  if (id === undefined) {
+    id = ++nextDiagnosticLane;
+    diagnosticLaneIds!.set(lane, id);
+  }
+  return `state lane #${id}`;
+}
+
+function registerDiagnosticWork(name: string): (() => void) & { readonly description: string } {
+  if (diagnosticPending === undefined) return Object.assign(() => undefined, { description: name });
   const id = ++nextDiagnosticWork;
   const frames = new Error().stack?.split('\n').slice(2) ?? [];
   const caller =
     frames
       .find((frame) => !frame.includes('state-lane.') && !frame.includes('serial-execution-queue.'))
       ?.trim() ?? UNKNOWN_DIAGNOSTIC_CALLER;
-  diagnosticPending.set(id, `${name} ${caller}`);
-  return () => {
-    diagnosticPending.delete(id);
-  };
+  const description = `${name} ${caller}`;
+  diagnosticPending.set(id, description);
+  return Object.assign(
+    () => {
+      diagnosticPending.delete(id);
+    },
+    { description }
+  );
 }

package/src/runtime/foundation/operation-registry.ts

@@ -24,11 +24,22 @@ export interface PendingOperation<T> {
   readonly promise: Promise<T>;
 }
 
+/**
+ * Receives an operation's terminal at the place it is taken from the
+ * registry. One long-lived observer serves every observed operation, so an
+ * observed registration creates no Promise or per-operation callback.
+ */
+export interface OperationObserver<T, Context> {
+  operationCompleted(id: bigint, value: T, context: Context | undefined): void;
+  operationFailed(id: bigint, reason: unknown, context: Context | undefined): void;
+}
+
 interface Entry<T, Context> {
   readonly context: Context | undefined;
-  readonly deadlineMs?: number;
-  readonly resolve: (value: T | PromiseLike<T>) => void;
-  readonly reject: (reason: unknown) => void;
+  deadlineMs?: number;
+  resolve?: (value: T | PromiseLike<T>) => void;
+  reject?: (reason: unknown) => void;
+  observer?: OperationObserver<T, Context>;
 }
 
 const systemClock: OperationClock = {
@@ -40,7 +51,14 @@ export class OperationRegistry<T, Context = unknown> {
   private readonly entries = new Map<bigint, Entry<T, Context>>();
   private nextId = 1n;
   private deadlineCursor?: MapIterator<[bigint, Entry<T, Context>]>;
+  /**
+   * A lower bound of the earliest pending deadline. Completed entries only
+   * leave it early; a full expiry pass replaces it with the exact value.
+   */
+  private earliestDeadlineMs = Number.POSITIVE_INFINITY;
+  private scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
   private closed = false;
+  private pendingCount = 0;
 
   constructor(
     private readonly clock: OperationClock = systemClock,
@@ -63,28 +81,56 @@ export class OperationRegistry<T, Context = unknown> {
       resolve = onResolve;
       reject = onReject;
     });
-    const entry: Entry<T, Context> = {
-      context,
-      deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
-      resolve,
-      reject
-    };
+    const deadlineMs = timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined;
+    const entry: Entry<T, Context> = { context, deadlineMs, resolve, reject };
     this.entries.set(id, entry);
-    if (this.entries.size === 1) this.onPendingChanged?.();
+    this.notePending(deadlineMs);
     return { id, promise };
   }
 
-  complete(id: bigint, value: T): boolean {
+  /** Registers an operation whose terminal goes to `observer` instead of a Promise. */
+  registerObserved(
+    timeoutMs: number,
+    observer: OperationObserver<T, Context>,
+    context?: Context
+  ): bigint {
+    if (this.closed) throw new Error('Operation registry is closed.');
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      throw new RangeError('timeoutMs must be a non-negative finite number.');
+    }
+    const id = this.nextId++;
+    const deadlineMs = this.clock.now() + timeoutMs;
+    this.entries.set(id, { context, deadlineMs, observer });
+    this.notePending(deadlineMs);
+    return id;
+  }
+
+  /** The time the next expiry pass has work, as a lower bound (spec 08 §4.2). */
+  nextDeadlineMs(): number {
+    return this.earliestDeadlineMs;
+  }
+
+  private notePending(deadlineMs: number | undefined): void {
+    this.pendingCount++;
+    const earlier = deadlineMs !== undefined && deadlineMs < this.earliestDeadlineMs;
+    if (earlier) this.earliestDeadlineMs = deadlineMs;
+    if (earlier || this.pendingCount === 1) this.onPendingChanged?.();
+  }
+
+  complete(id: bigint, value: T, terminalContextRetentionMs = 0): boolean {
     const entry = this.take(id);
     if (entry === undefined) return false;
-    entry.resolve(value);
+    if (entry.observer !== undefined) entry.observer.operationCompleted(id, value, entry.context);
+    else entry.resolve!(value);
+    this.retainTerminal(id, entry, terminalContextRetentionMs);
     return true;
   }
 
   fail(id: bigint, reason: unknown): boolean {
     const entry = this.take(id);
     if (entry === undefined) return false;
-    entry.reject(reason);
+    if (entry.observer !== undefined) entry.observer.operationFailed(id, reason, entry.context);
+    else entry.reject!(reason);
     return true;
   }
 
@@ -93,7 +139,7 @@ export class OperationRegistry<T, Context = unknown> {
   }
 
   isPending(id: bigint): boolean {
-    return this.entries.has(id);
+    return this.pendingEntry(id) !== undefined;
   }
 
   context(id: bigint): Context | undefined {
@@ -104,35 +150,67 @@ export class OperationRegistry<T, Context = unknown> {
     if (this.closed) return;
     this.closed = true;
     for (const id of this.entries.keys()) this.cancel(id, reason);
+    this.entries.clear();
     this.deadlineCursor = undefined;
   }
 
+  failAll(reason: unknown): void {
+    for (const id of this.entries.keys()) this.fail(id, reason);
+  }
+
   get size(): number {
-    return this.entries.size;
+    return this.pendingCount;
   }
 
   expire(nowMs: number, turnDeadlineMs: number): number {
     let expired = 0;
     while (this.clock.now() < turnDeadlineMs) {
-      this.deadlineCursor ??= this.entries.entries();
+      if (this.deadlineCursor === undefined) {
+        this.deadlineCursor = this.entries.entries();
+        this.scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
+      }
       const current = this.deadlineCursor.next();
       if (current.done === true) {
         this.deadlineCursor = undefined;
+        // Entries registered during the pass are appended and were scanned.
+        this.earliestDeadlineMs = this.scanEarliestDeadlineMs;
         break;
       }
       const [id, entry] = current.value;
-      if (entry.deadlineMs !== undefined && entry.deadlineMs <= nowMs) {
-        if (this.fail(id, new OperationTimeoutError(id))) expired++;
+      if (entry.deadlineMs === undefined) continue;
+      if (entry.deadlineMs <= nowMs) {
+        if (!this.isPending(id)) this.entries.delete(id);
+        else if (this.fail(id, new OperationTimeoutError(id))) expired++;
+      } else if (entry.deadlineMs < this.scanEarliestDeadlineMs) {
+        this.scanEarliestDeadlineMs = entry.deadlineMs;
       }
     }
     return expired;
   }
 
   private take(id: bigint): Entry<T, Context> | undefined {
-    const entry = this.entries.get(id);
+    const entry = this.pendingEntry(id);
     if (entry === undefined) return undefined;
     this.entries.delete(id);
-    if (this.entries.size === 0) this.onPendingChanged?.();
+    this.pendingCount--;
+    if (this.pendingCount === 0) this.onPendingChanged?.();
     return entry;
   }
+
+  private pendingEntry(id: bigint): Entry<T, Context> | undefined {
+    const entry = this.entries.get(id);
+    return entry !== undefined && (entry.resolve !== undefined || entry.observer !== undefined)
+      ? entry
+      : undefined;
+  }
+
+  private retainTerminal(id: bigint, entry: Entry<T, Context>, retentionMs: number): void {
+    if (this.closed || entry.context === undefined || retentionMs === 0) return;
+    entry.resolve = undefined;
+    entry.reject = undefined;
+    entry.observer = undefined;
+    entry.deadlineMs = this.clock.now() + retentionMs;
+    this.entries.set(id, entry);
+    this.earliestDeadlineMs = Math.min(this.earliestDeadlineMs, entry.deadlineMs);
+  }
 }