@zlink-systems/framework 0.21.0 → 0.23.0

package/src/runtime/diagnostics/runtime-observation-queue.ts

@@ -1,7 +1,4 @@
-import type {
-  ZLinkObservationLoss,
-  ZLinkObservedStatus
-} from '../../contracts';
+import type { ZLinkObservationLoss, ZLinkObservedStatus } from '../../contracts';
 
 export const ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY = 64;
 export const ZLINK_SIGNED_OBSERVATION_LOSS_MAXIMUM = 9_223_372_036_854_775_807n;
@@ -55,9 +52,7 @@ class RuntimeObservationLossState {
   }
 
   recordDiscardedTerminal(): void {
-    this.discardedTerminal = saturatingObservationLossIncrement(
-      this.discardedTerminal
-    );
+    this.discardedTerminal = saturatingObservationLossIncrement(this.discardedTerminal);
   }
 
   snapshot(): ZLinkObservationLoss {
@@ -74,8 +69,11 @@ class RuntimeObservationLossState {
  * dispatcher; they never invoke an iterator continuation directly.
  */
 export class RuntimeEventQueue<T>
-  implements AsyncIterable<ZLinkObservedStatus<T>>, AsyncIterator<ZLinkObservedStatus<T>>,
-    RuntimeObservationDispatchTarget {
+  implements
+    AsyncIterable<ZLinkObservedStatus<T>>,
+    AsyncIterator<ZLinkObservedStatus<T>>,
+    RuntimeObservationDispatchTarget
+{
   private readonly intermediateBySource = new Map<unknown, RetainedObservation<T>>();
   private readonly terminalFifo: Array<RetainedObservation<T> | undefined> = [];
   private readonly terminalCountBySource = new Map<unknown, number>();
@@ -108,7 +106,9 @@ export class RuntimeEventQueue<T>
     }
   }
 
-  [Symbol.asyncIterator](): AsyncIterator<ZLinkObservedStatus<T>> { return this; }
+  [Symbol.asyncIterator](): AsyncIterator<ZLinkObservedStatus<T>> {
+    return this;
+  }
 
   next(): Promise<IteratorResult<ZLinkObservedStatus<T>>> {
     if (this.waitersCount === 0) {
@@ -126,7 +126,7 @@ export class RuntimeEventQueue<T>
         return Promise.resolve({ done: true, value: undefined });
       }
     }
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
       this.waiters.push(resolve);
       this.waitersCount += 1;
       if (this.hasRetained() || this.closed || this.completeWhenDrained) {
@@ -217,10 +217,7 @@ export class RuntimeEventQueue<T>
     }
     this.terminalFifo.push(this.retain(value, source));
     this.terminalCount += 1;
-    this.terminalCountBySource.set(
-      source,
-      (this.terminalCountBySource.get(source) ?? 0) + 1
-    );
+    this.terminalCountBySource.set(source, (this.terminalCountBySource.get(source) ?? 0) + 1);
     this.signalDispatcher();
   }
 
@@ -236,9 +233,8 @@ export class RuntimeEventQueue<T>
     const terminal = this.peekTerminal();
     const intermediate = this.oldestIntermediate();
     if (
-      terminal !== undefined
-      && (intermediate === undefined
-        || terminal.publishOrdinal <= intermediate.publishOrdinal)
+      terminal !== undefined &&
+      (intermediate === undefined || terminal.publishOrdinal <= intermediate.publishOrdinal)
     ) {
       return this.takeTerminal();
     }
@@ -248,9 +244,7 @@ export class RuntimeEventQueue<T>
   }
 
   private peekTerminal(): RetainedObservation<T> | undefined {
-    return this.terminalCount === 0
-      ? undefined
-      : this.terminalFifo[this.terminalHead];
+    return this.terminalCount === 0 ? undefined : this.terminalFifo[this.terminalHead];
   }
 
   private oldestIntermediate(): RetainedObservation<T> | undefined {
@@ -297,10 +291,7 @@ export class RuntimeEventQueue<T>
     if (this.terminalCount === 0) {
       this.terminalFifo.length = 0;
       this.terminalHead = 0;
-    } else if (
-      this.terminalHead >= 1024
-      && this.terminalHead * 2 >= this.terminalFifo.length
-    ) {
+    } else if (this.terminalHead >= 1024 && this.terminalHead * 2 >= this.terminalFifo.length) {
       this.terminalFifo.splice(0, this.terminalHead);
       this.terminalHead = 0;
     }
@@ -333,9 +324,7 @@ export class RuntimeEventQueue<T>
     return { status, loss: this.loss.snapshot() };
   }
 
-  private takeWaiter():
-    | ((result: IteratorResult<ZLinkObservedStatus<T>>) => void)
-    | undefined {
+  private takeWaiter(): ((result: IteratorResult<ZLinkObservedStatus<T>>) => void) | undefined {
     if (this.waitersCount === 0) return undefined;
     const waiter = this.waiters[this.waitersHead];
     this.waiters[this.waitersHead] = undefined;

package/src/runtime/diagnostics/topology-runtime-projections.ts

@@ -39,8 +39,7 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
 
   constructor(
     private readonly runtime: RuntimeAccessor,
-    private readonly hostState: HostStateAccessor =
-      () => ZLinkFrameworkRuntimeState.Serving
+    private readonly hostState: HostStateAccessor = () => ZLinkFrameworkRuntimeState.Serving
   ) {}
 
   snapshot(channelName: string): ZLinkClientServerStatus {
@@ -50,23 +49,30 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
   private snapshotCore(channelName: string): ZLinkClientServerStatus {
     const topology = this.requireRuntime().clientServerTopology(channelName);
     if (topology.localRole === undefined) {
-      throw new ZLinkConfigurationException(`ClientServer channel '${channelName}' is not registered.`);
+      throw new ZLinkConfigurationException(
+        `ClientServer channel '${channelName}' is not registered.`
+      );
     }
     const targets = topology.descriptors.map((descriptor): ZLinkClientServerTargetStatus => ({
       nodeRid: descriptor.serverRoutingId,
       weight: descriptor.weight,
-      state: descriptor.state === 'serving' ? ZLinkPeerState.Ready
-        : descriptor.state === 'retiring' ? ZLinkPeerState.Draining
-          : descriptor.state === 'preparing' ? ZLinkPeerState.Connecting
-            : ZLinkPeerState.NotConnected,
-      unavailableReason: descriptor.state === 'serving' && descriptor.weight > 0
-        ? undefined
-        : descriptor.state === 'retiring'
-          ? ZLinkTopologyReason.Draining
-          : ZLinkTopologyReason.NoReadyTarget
+      state:
+        descriptor.state === 'serving'
+          ? ZLinkPeerState.Ready
+          : descriptor.state === 'retiring'
+            ? ZLinkPeerState.Draining
+            : descriptor.state === 'preparing'
+              ? ZLinkPeerState.Connecting
+              : ZLinkPeerState.NotConnected,
+      unavailableReason:
+        descriptor.state === 'serving' && descriptor.weight > 0
+          ? undefined
+          : descriptor.state === 'retiring'
+            ? ZLinkTopologyReason.Draining
+            : ZLinkTopologyReason.NoReadyTarget
     }));
     const readyTargetCount = targets.filter(
-      target => target.state === ZLinkPeerState.Ready && target.weight > 0
+      (target) => target.state === ZLinkPeerState.Ready && target.weight > 0
     ).length;
     const hostState = this.hostState();
     const isReady = topologyRuntimeIsReady(hostState, readyTargetCount);
@@ -110,13 +116,16 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
         } catch {
           // The last complete projection remains valid after native teardown.
         }
-        queue.seal({
-          ...current,
-          state: ZLinkTopologyState.Stopped,
-          isReady: false,
-          sequence: this.sequence,
-          observedAt: new Date()
-        }, channelName);
+        queue.seal(
+          {
+            ...current,
+            state: ZLinkTopologyState.Stopped,
+            isReady: false,
+            sequence: this.sequence,
+            observedAt: new Date()
+          },
+          channelName
+        );
       }
     };
     this.hostObservers.add(hostObserver);
@@ -154,7 +163,8 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
 
   private requireRuntime(): ZLinkChannelRuntimeManager {
     const runtime = this.runtime();
-    if (runtime === undefined) throw new ZLinkConfigurationException('ClientServer runtime has not started.');
+    if (runtime === undefined)
+      throw new ZLinkConfigurationException('ClientServer runtime has not started.');
     return runtime;
   }
 }
@@ -165,8 +175,7 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
 
   constructor(
     private readonly runtime: RuntimeAccessor,
-    private readonly hostState: HostStateAccessor =
-      () => ZLinkFrameworkRuntimeState.Serving
+    private readonly hostState: HostStateAccessor = () => ZLinkFrameworkRuntimeState.Serving
   ) {}
 
   snapshot(channelName: string): ZLinkFanoutStatus {
@@ -174,21 +183,27 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
   }
 
   private snapshotCore(channelName: string): ZLinkFanoutStatus {
-    const publishers = this.requireRuntime().fanoutTopology(channelName).descriptors
-      .map((descriptor): ZLinkPeerStatus => ({
+    const publishers = this.requireRuntime()
+      .fanoutTopology(channelName)
+      .descriptors.map((descriptor): ZLinkPeerStatus => ({
         nodeRid: descriptor.publisherRoutingId,
-        state: descriptor.state === 'serving' ? ZLinkPeerState.Ready
-          : descriptor.state === 'retiring' ? ZLinkPeerState.Draining
-            : descriptor.state === 'preparing' ? ZLinkPeerState.Connecting
-              : ZLinkPeerState.NotConnected,
-        unavailableReason: descriptor.state === 'serving'
-          ? undefined
-          : descriptor.state === 'retiring'
-            ? ZLinkTopologyReason.Draining
-            : ZLinkTopologyReason.NoReadyTarget
+        state:
+          descriptor.state === 'serving'
+            ? ZLinkPeerState.Ready
+            : descriptor.state === 'retiring'
+              ? ZLinkPeerState.Draining
+              : descriptor.state === 'preparing'
+                ? ZLinkPeerState.Connecting
+                : ZLinkPeerState.NotConnected,
+        unavailableReason:
+          descriptor.state === 'serving'
+            ? undefined
+            : descriptor.state === 'retiring'
+              ? ZLinkTopologyReason.Draining
+              : ZLinkTopologyReason.NoReadyTarget
       }));
     const readyPublisherCount = publishers.filter(
-      publisher => publisher.state === ZLinkPeerState.Ready
+      (publisher) => publisher.state === ZLinkPeerState.Ready
     ).length;
     const hostState = this.hostState();
     const hostReady = runtimeStateIsReady(hostState);
@@ -235,13 +250,16 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
         } catch {
           // The last complete projection remains valid after native teardown.
         }
-        queue.seal({
-          ...current,
-          state: ZLinkTopologyState.Stopped,
-          isReady: false,
-          sequence: this.sequence,
-          observedAt: new Date()
-        }, channelName);
+        queue.seal(
+          {
+            ...current,
+            state: ZLinkTopologyState.Stopped,
+            isReady: false,
+            sequence: this.sequence,
+            observedAt: new Date()
+          },
+          channelName
+        );
       }
     };
     this.hostObservers.add(hostObserver);
@@ -275,7 +293,8 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
 
   private requireRuntime(): ZLinkChannelRuntimeManager {
     const runtime = this.runtime();
-    if (runtime === undefined) throw new ZLinkConfigurationException('Fanout runtime has not started.');
+    if (runtime === undefined)
+      throw new ZLinkConfigurationException('Fanout runtime has not started.');
     return runtime;
   }
 }

package/src/runtime/execution/index.ts

@@ -32,10 +32,7 @@ export type ZLinkExecutionArea = 'application' | 'infrastructure';
 
 const executionAreaStorage = new AsyncLocalStorage<ZLinkExecutionArea>();
 
-export function runZLinkExecutionArea<T>(
-  area: ZLinkExecutionArea,
-  operation: () => T
-): T {
+export function runZLinkExecutionArea<T>(area: ZLinkExecutionArea, operation: () => T): T {
   return executionAreaStorage.run(area, operation);
 }
 
@@ -140,7 +137,10 @@ export class ZLinkSpotSerialTurn {
       return;
     }
     await Promise.race([
-      owner.then(() => undefined, () => undefined),
+      owner.then(
+        () => undefined,
+        () => undefined
+      ),
       this.suspended
     ]);
   }
@@ -169,12 +169,8 @@ export function runZLinkSpotSerialTurn<T>(
   turn: ZLinkSpotSerialTurn,
   operation: () => Promise<T> | T
 ): Promise<T> {
-  return runZLinkExecutionArea(
-    'application',
-    () => spotSerialTurnStorage.run(
-      { executor, turnId, turn },
-      async () => operation()
-    )
+  return runZLinkExecutionArea('application', () =>
+    spotSerialTurnStorage.run({ executor, turnId, turn }, async () => operation())
   );
 }
 
@@ -194,18 +190,13 @@ export function captureZLinkSpotSerialTurn(
 /** Returns the physical Spot owner only while its captured turn owns the gate. */
 export function currentZLinkSpotSerialSourceId(): unknown {
   const current = spotSerialTurnStorage.getStore();
-  if (
-    current === undefined
-    || !current.executor.isActiveTurn(current.turn, current.turnId)
-  ) {
+  if (current === undefined || !current.executor.isActiveTurn(current.turn, current.turnId)) {
     return undefined;
   }
   return current.executor.sourceSpotId;
 }
 
-export function requireZLinkYieldTurn(
-  capturedTurn?: ZLinkSpotSerialTurn
-): ZLinkSpotSerialTurn {
+export function requireZLinkYieldTurn(capturedTurn?: ZLinkSpotSerialTurn): ZLinkSpotSerialTurn {
   const turn = capturedTurn ?? captureZLinkSpotSerialTurn();
   if (turn === undefined || !turn.yieldAllowed) {
     throw new ZLinkConfigurationException(
@@ -227,15 +218,19 @@ export function captureZLinkExecutionTurn(): ZLinkCapturedExecutionTurn | undefi
   }
   return {
     yieldPromise: <T>(pending: Promise<T>) => current.turn.yieldPromise(pending),
-    post: (callback: () => void) => { void current.executor.post(callback); }
+    post: (callback: () => void) => {
+      void current.executor.post(callback);
+    }
   };
 }
 
 export function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecutorLike): boolean {
   const current = spotSerialTurnStorage.getStore();
-  return current !== undefined
-    && current.executor === executor
-    && executor.isActiveTurn(current.turn, current.turnId);
+  return (
+    current !== undefined &&
+    current.executor === executor &&
+    executor.isActiveTurn(current.turn, current.turnId)
+  );
 }
 
 export interface ZLinkExecutionBarrierSeal {
@@ -306,10 +301,7 @@ export class ZLinkExecutionBarrier {
     return seal;
   }
 
-  async waitForQuiescence(
-    seal: ZLinkExecutionBarrierSeal,
-    signal?: AbortSignal
-  ): Promise<void> {
+  async waitForQuiescence(seal: ZLinkExecutionBarrierSeal, signal?: AbortSignal): Promise<void> {
     this.requireCurrent(seal);
     if (this.activeClaims === 0) return;
     if (signal?.aborted === true) throw signal.reason;

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

@@ -12,10 +12,11 @@ export interface ZLinkSerialSchedulerOptions {
   readonly lifecycleBurstLimit?: number;
 }
 
-export const ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS: Required<ZLinkSerialSchedulerOptions> = Object.freeze({
-  ownerTimeBudget: 10,
-  lifecycleBurstLimit: 8,
-});
+export const ZLINK_DEFAULT_SERIAL_SCHEDULER_OPTIONS: Required<ZLinkSerialSchedulerOptions> =
+  Object.freeze({
+    ownerTimeBudget: 10,
+    lifecycleBurstLimit: 8
+  });
 
 export interface ZLinkSerialWorkRecord<T> {
   readonly acceptedSequence: bigint;
@@ -102,10 +103,7 @@ export class ZLinkSerialExecutionQueue {
   /**
    * Enqueues a continuation for an already-admitted owner turn.
    */
-  submitContinuation<T>(
-    operation: () => Promise<T> | T,
-    context?: unknown
-  ): Promise<T> {
+  submitContinuation<T>(operation: () => Promise<T> | T, context?: unknown): Promise<T> {
     try {
       return this.admit(operation, { lane: 'application' }, context);
     } catch (error) {
@@ -125,12 +123,7 @@ export class ZLinkSerialExecutionQueue {
     context?: unknown,
     preparation?: ZLinkSerialWorkPreparation
   ): Promise<T> {
-    return this.admit(
-      operation,
-      { ...options, lane: 'application' },
-      context,
-      preparation
-    );
+    return this.admit(operation, { ...options, lane: 'application' }, context, preparation);
   }
 
   /**
@@ -160,14 +153,14 @@ export class ZLinkSerialExecutionQueue {
   }
 
   get hasPendingWork(): boolean {
-    return this.draining
-      || this.application.records.length > 0
-      || this.lifecycle.records.length > 0;
+    return (
+      this.draining || this.application.records.length > 0 || this.lifecycle.records.length > 0
+    );
   }
 
   whenIdle(): Promise<void> {
     if (!this.hasPendingWork) return Promise.resolve();
-    return new Promise(resolve => this.idleWaiters.push(resolve));
+    return new Promise((resolve) => this.idleWaiters.push(resolve));
   }
 
   /** Stops new submissions while allowing the accepted FIFO to finish. */
@@ -257,8 +250,10 @@ export class ZLinkSerialExecutionQueue {
         const record = selection.record;
         if (selection.lane === 'lifecycle') {
           const applicationHead = this.application.records[0]!;
-          if (this.application.records.length > 0
-              && !this.cancelPreparationForRearbitration(applicationHead)) {
+          if (
+            this.application.records.length > 0 &&
+            !this.cancelPreparationForRearbitration(applicationHead)
+          ) {
             waitingForPreparation = true;
             break;
           }
@@ -268,8 +263,7 @@ export class ZLinkSerialExecutionQueue {
           waitingForPreparation = true;
           break;
         }
-        if (record.preparationState === 'pending'
-            || record.preparationState === 'canceling') {
+        if (record.preparationState === 'pending' || record.preparationState === 'canceling') {
           waitingForPreparation = true;
           break;
         }
@@ -295,8 +289,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.application.records.length > 0 || this.lifecycle.records.length > 0)
+      ) {
         this.scheduleDrain();
       } else {
         if (this.application.records.length === 0 && this.lifecycle.records.length === 0) {
@@ -306,10 +302,12 @@ export class ZLinkSerialExecutionQueue {
     }
   }
 
-  private selectNext(): {
-    readonly lane: ZLinkSerialWorkLane;
-    readonly record: SerialWorkRecord<unknown>;
-  } | undefined {
+  private selectNext():
+    | {
+        readonly lane: ZLinkSerialWorkLane;
+        readonly record: SerialWorkRecord<unknown>;
+      }
+    | undefined {
     const applicationReady = this.application.records.length > 0;
     const lifecycleReady = this.lifecycle.records.length > 0;
     if (!applicationReady && !lifecycleReady) return undefined;
@@ -329,9 +327,7 @@ export class ZLinkSerialExecutionQueue {
     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();
     if (record !== selection.record) {
       throw new Error('The selected serial work record changed before owner claim.');
     }
@@ -340,10 +336,7 @@ export class ZLinkSerialExecutionQueue {
 
   private takeLifecycle(): ZLinkSerialWorkRecord<unknown> {
     this.lifecycleStreak += 1;
-    if (
-      this.application.records.length > 0
-      && this.lifecycleStreak >= this.lifecycleBurstLimit
-    ) {
+    if (this.application.records.length > 0 && this.lifecycleStreak >= this.lifecycleBurstLimit) {
       this.lifecycleDebt = true;
     }
     return this.lifecycle.records.shift()!;
@@ -375,7 +368,7 @@ export class ZLinkSerialExecutionQueue {
           record.preparationController = undefined;
           this.scheduleDrain();
         },
-        error => {
+        (error) => {
           if (record.preparationState === 'canceling' || controller.signal.aborted) {
             preparation.cancel();
             record.preparationState = 'idle';
@@ -390,9 +383,7 @@ export class ZLinkSerialExecutionQueue {
   }
 
   /** Returns false while an outstanding readiness attempt is being canceled. */
-  private cancelPreparationForRearbitration(
-    record: SerialWorkRecord<unknown>
-  ): boolean {
+  private cancelPreparationForRearbitration(record: SerialWorkRecord<unknown>): boolean {
     if (record.preparation === undefined || record.preparationState === 'idle') return true;
     if (record.preparationState === 'ready') {
       record.preparation.cancel();
@@ -438,5 +429,5 @@ function validateNonNegative(value: number, field: string): void {
 }
 
 function macrotaskBoundary(): Promise<void> {
-  return new Promise(resolve => setImmediate(resolve));
+  return new Promise((resolve) => setImmediate(resolve));
 }

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

@@ -66,8 +66,8 @@ export class ZLinkStateLane {
   throwIfReentrant(): void {
     if (this.isOnLane) {
       throw new Error(
-        'This code already runs on the state lane it is trying to enter. Call the component\'s '
-        + 'private state method directly instead of re-entering its public surface.'
+        "This code already runs on the state lane it is trying to enter. Call the component's " +
+          'private state method directly instead of re-entering its public surface.'
       );
     }
   }