@zlink-systems/framework 0.30.1 → 0.30.2

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

@@ -12,6 +12,13 @@ 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;
 let nextDiagnosticWork = 0;

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);
+  }
 }