@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -21,21 +21,151 @@ import {
 } from './runtime-observation-queue';
 import {
   runtimeStateIsReady,
-  topologyRuntimeIsReady
+  topologyRuntimeIsReady,
+  topologyObservationIsTerminal
 } from '../foundation/runtime-state-projections';
+import type {
+  ClientServerDescriptor,
+  FanoutPublisherDescriptor
+} from '../foundation/service-discovery-registry';
 
 export { RuntimeEventQueue } from './runtime-observation-queue';
 
 type RuntimeAccessor = () => ZLinkChannelRuntimeManager | undefined;
 type HostStateAccessor = () => ZLinkFrameworkRuntimeState;
-interface HostObserver {
-  readonly changed: () => void;
-  readonly stop: () => void;
+type TopologyStatus = ZLinkClientServerStatus | ZLinkFanoutStatus;
+interface TopologySource<T extends TopologyStatus> {
+  lastSnapshot?: T;
+  readonly observers: Set<RuntimeEventQueue<T>>;
+  stop?: () => void;
+}
+
+class TopologyStatusSources<T extends TopologyStatus> {
+  private readonly sources = new Map<string, TopologySource<T>>();
+
+  constructor(
+    private readonly read: (channelName: string, sequence: bigint) => T,
+    private readonly subscribe: (channelName: string, changed: () => void) => () => void,
+    private readonly equivalent: (left: T, right: T) => boolean
+  ) {}
+
+  snapshot(channelName: string): T {
+    let source = this.sources.get(channelName);
+    const current = source?.lastSnapshot;
+    if (current !== undefined && topologyObservationIsTerminal(current.state)) return current;
+    const snapshot = this.read(channelName, current?.sequence ?? 0n);
+    if (source === undefined) {
+      source = { observers: new Set() };
+      this.sources.set(channelName, source);
+    }
+    const published = this.publish(channelName, source, snapshot);
+    if (source.stop === undefined && !topologyObservationIsTerminal(published.state)) {
+      source.stop = this.subscribe(channelName, () => this.snapshot(channelName));
+    }
+    return published;
+  }
+
+  observe(
+    channelName: string,
+    capacity: number,
+    signal?: AbortSignal
+  ): AsyncIterable<ZLinkObservedStatus<T>> {
+    const queue = new RuntimeEventQueue<T>(capacity, signal);
+    const snapshot = this.snapshot(channelName);
+    const current = this.sources.get(channelName)!;
+    current.observers.add(queue);
+    queue.onClose(() => {
+      current.observers.delete(queue);
+    });
+    this.deliver(queue, snapshot, channelName);
+    return queue;
+  }
+
+  hostStateChanged(): void {
+    for (const channelName of this.sources.keys()) this.snapshot(channelName);
+  }
+
+  stopObservers(): void {
+    for (const [channelName, source] of this.sources) {
+      if (
+        source.lastSnapshot === undefined ||
+        topologyObservationIsTerminal(source.lastSnapshot.state)
+      )
+        continue;
+      this.publish(channelName, source, {
+        ...source.lastSnapshot,
+        state: ZLinkTopologyState.Stopped,
+        isReady: false
+      });
+    }
+  }
+
+  private publish(channelName: string, source: TopologySource<T>, snapshot: T): T {
+    const previous = source.lastSnapshot;
+    if (previous !== undefined && this.equivalent(previous, snapshot)) return previous;
+    source.lastSnapshot = {
+      ...snapshot,
+      sequence: (previous?.sequence ?? 0n) + 1n,
+      observedAt: new Date()
+    };
+    for (const queue of source.observers) this.deliver(queue, source.lastSnapshot, channelName);
+    if (topologyObservationIsTerminal(source.lastSnapshot.state)) {
+      source.stop?.();
+      source.stop = undefined;
+    }
+    return source.lastSnapshot;
+  }
+
+  private deliver(queue: RuntimeEventQueue<T>, snapshot: T, channelName: string): void {
+    if (topologyObservationIsTerminal(snapshot.state)) queue.seal(snapshot, channelName);
+    else queue.push(snapshot, channelName);
+  }
+}
+
+function sameTopologyState(left: TopologyStatus, right: TopologyStatus): boolean {
+  return left.state === right.state && left.isReady === right.isReady;
+}
+
+function samePeer(left: ZLinkPeerStatus, right: ZLinkPeerStatus): boolean {
+  return (
+    left.nodeRid === right.nodeRid &&
+    left.state === right.state &&
+    left.unavailableReason === right.unavailableReason
+  );
+}
+
+function sameClientServerStatus(
+  left: ZLinkClientServerStatus,
+  right: ZLinkClientServerStatus
+): boolean {
+  return (
+    sameTopologyState(left, right) &&
+    left.localRole === right.localRole &&
+    left.readyTargetCount === right.readyTargetCount &&
+    left.targets.length === right.targets.length &&
+    left.targets.every(
+      (target, index) =>
+        samePeer(target, right.targets[index]!) && target.weight === right.targets[index]!.weight
+    )
+  );
+}
+
+function sameFanoutStatus(left: ZLinkFanoutStatus, right: ZLinkFanoutStatus): boolean {
+  return (
+    sameTopologyState(left, right) &&
+    left.readyPublisherCount === right.readyPublisherCount &&
+    left.publishers.length === right.publishers.length &&
+    left.publishers.every((publisher, index) => samePeer(publisher, right.publishers[index]!))
+  );
 }
 
 export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRuntime {
-  private sequence = 0n;
-  private readonly hostObservers = new Set<HostObserver>();
+  private readonly sources = new TopologyStatusSources<ZLinkClientServerStatus>(
+    (channelName, sequence) => this.snapshotCore(channelName, sequence),
+    (channelName, changed) =>
+      this.requireRuntime().observeClientServerTopology(channelName, changed),
+    sameClientServerStatus
+  );
 
   constructor(
     private readonly runtime: RuntimeAccessor,
@@ -43,34 +173,19 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
   ) {}
 
   snapshot(channelName: string): ZLinkClientServerStatus {
-    return this.snapshotCore(channelName);
+    return this.sources.snapshot(channelName);
   }
 
-  private snapshotCore(channelName: string): ZLinkClientServerStatus {
+  private snapshotCore(channelName: string, sequence: bigint): ZLinkClientServerStatus {
     const topology = this.requireRuntime().clientServerTopology(channelName);
     if (topology.localRole === undefined) {
       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
-    }));
+    const targets = topology.descriptors.map((descriptor) =>
+      peerStatusForAvailability(descriptor, ZLinkTopologyReason.NoReadyTarget)
+    );
     const readyTargetCount = targets.filter(
       (target) => target.state === ZLinkPeerState.Ready && target.weight > 0
     ).length;
@@ -83,7 +198,7 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
       isReady,
       readyTargetCount,
       targets,
-      sequence: this.sequence,
+      sequence,
       observedAt: new Date()
     };
   }
@@ -93,72 +208,19 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
     capacity = ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY,
     signal?: AbortSignal
   ): AsyncIterable<ZLinkObservedStatus<ZLinkClientServerStatus>> {
-    const runtime = this.requireRuntime();
-    const queue = new RuntimeEventQueue<ZLinkClientServerStatus>(capacity, signal);
-    let lastSnapshot = this.snapshotCore(channelName);
-    const stop = runtime.observeClientServerTopology(channelName, () => {
-      this.sequence += 1n;
-      lastSnapshot = this.snapshotCore(channelName);
-      queue.push(lastSnapshot, channelName);
-    });
-    const hostObserver: HostObserver = {
-      changed: () => {
-        this.sequence += 1n;
-        lastSnapshot = this.snapshotCore(channelName);
-        queue.push(lastSnapshot, channelName);
-      },
-      stop: () => {
-        this.sequence += 1n;
-        let current = lastSnapshot;
-        try {
-          current = this.snapshotCore(channelName);
-          lastSnapshot = current;
-        } 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
-        );
-      }
-    };
-    this.hostObservers.add(hostObserver);
-    queue.onClose(() => {
-      stop();
-      this.hostObservers.delete(hostObserver);
-    });
-    return queue;
+    return this.sources.observe(channelName, capacity, signal);
   }
 
   hostStateChanged(): void {
-    for (const observer of this.hostObservers) {
-      try {
-        observer.changed();
-      } catch {
-        // Monitoring projection failures do not change host lifecycle results.
-      }
-    }
+    this.sources.hostStateChanged();
   }
 
   stopObservers(): void {
-    for (const observer of [...this.hostObservers]) {
-      try {
-        observer.stop();
-      } catch {
-        // The observer is still removed when its terminal snapshot fails.
-      }
-    }
-    this.hostObservers.clear();
+    this.sources.stopObservers();
   }
 
   isReady(channelName: string): boolean {
-    return this.snapshotCore(channelName).isReady;
+    return this.snapshot(channelName).isReady;
   }
 
   private requireRuntime(): ZLinkChannelRuntimeManager {
@@ -170,8 +232,11 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
 }
 
 export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
-  private sequence = 0n;
-  private readonly hostObservers = new Set<HostObserver>();
+  private readonly sources = new TopologyStatusSources<ZLinkFanoutStatus>(
+    (channelName, sequence) => this.snapshotCore(channelName, sequence),
+    (channelName, changed) => this.requireRuntime().observeFanoutTopology(channelName, changed),
+    sameFanoutStatus
+  );
 
   constructor(
     private readonly runtime: RuntimeAccessor,
@@ -179,29 +244,15 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
   ) {}
 
   snapshot(channelName: string): ZLinkFanoutStatus {
-    return this.snapshotCore(channelName);
+    return this.sources.snapshot(channelName);
   }
 
-  private snapshotCore(channelName: string): ZLinkFanoutStatus {
+  private snapshotCore(channelName: string, sequence: bigint): ZLinkFanoutStatus {
     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
-      }));
+      .descriptors.map((descriptor) =>
+        peerStatusForAvailability(descriptor, ZLinkTopologyReason.NoReadyPeer)
+      );
     const readyPublisherCount = publishers.filter(
       (publisher) => publisher.state === ZLinkPeerState.Ready
     ).length;
@@ -217,7 +268,7 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
       isReady: topologyRuntimeIsReady(hostState, readyPublisherCount),
       readyPublisherCount,
       publishers,
-      sequence: this.sequence,
+      sequence,
       observedAt: new Date()
     };
   }
@@ -227,68 +278,15 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
     capacity = ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY,
     signal?: AbortSignal
   ): AsyncIterable<ZLinkObservedStatus<ZLinkFanoutStatus>> {
-    const runtime = this.requireRuntime();
-    const queue = new RuntimeEventQueue<ZLinkFanoutStatus>(capacity, signal);
-    let lastSnapshot = this.snapshotCore(channelName);
-    const stop = runtime.observeFanoutTopology(channelName, () => {
-      this.sequence += 1n;
-      lastSnapshot = this.snapshotCore(channelName);
-      queue.push(lastSnapshot, channelName);
-    });
-    const hostObserver: HostObserver = {
-      changed: () => {
-        this.sequence += 1n;
-        lastSnapshot = this.snapshotCore(channelName);
-        queue.push(lastSnapshot, channelName);
-      },
-      stop: () => {
-        this.sequence += 1n;
-        let current = lastSnapshot;
-        try {
-          current = this.snapshotCore(channelName);
-          lastSnapshot = current;
-        } 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
-        );
-      }
-    };
-    this.hostObservers.add(hostObserver);
-    queue.onClose(() => {
-      stop();
-      this.hostObservers.delete(hostObserver);
-    });
-    return queue;
+    return this.sources.observe(channelName, capacity, signal);
   }
 
   hostStateChanged(): void {
-    for (const observer of this.hostObservers) {
-      try {
-        observer.changed();
-      } catch {
-        // Monitoring projection failures do not change host lifecycle results.
-      }
-    }
+    this.sources.hostStateChanged();
   }
 
   stopObservers(): void {
-    for (const observer of [...this.hostObservers]) {
-      try {
-        observer.stop();
-      } catch {
-        // The observer is still removed when its terminal snapshot fails.
-      }
-    }
-    this.hostObservers.clear();
+    this.sources.stopObservers();
   }
 
   private requireRuntime(): ZLinkChannelRuntimeManager {
@@ -299,6 +297,40 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
   }
 }
 
+function peerStatusForAvailability(
+  descriptor: Pick<ClientServerDescriptor, 'serverRoutingId' | 'weight' | 'state'>,
+  unavailableReason: ZLinkTopologyReason.NoReadyTarget
+): ZLinkClientServerTargetStatus;
+function peerStatusForAvailability(
+  descriptor: Pick<FanoutPublisherDescriptor, 'publisherRoutingId' | 'state'>,
+  unavailableReason: ZLinkTopologyReason.NoReadyPeer
+): ZLinkPeerStatus;
+function peerStatusForAvailability(
+  descriptor:
+    | Pick<ClientServerDescriptor, 'serverRoutingId' | 'weight' | 'state'>
+    | Pick<FanoutPublisherDescriptor, 'publisherRoutingId' | 'state'>,
+  noReadyReason: ZLinkTopologyReason.NoReadyTarget | ZLinkTopologyReason.NoReadyPeer
+): ZLinkClientServerTargetStatus | ZLinkPeerStatus {
+  let state = ZLinkPeerState.NotConnected;
+  let unavailableReason: ZLinkTopologyReason | undefined = noReadyReason;
+  switch (descriptor.state) {
+    case 'retiring':
+      state = ZLinkPeerState.Draining;
+      unavailableReason = ZLinkTopologyReason.Draining;
+      break;
+    case 'serving':
+      state = ZLinkPeerState.Ready;
+      unavailableReason = undefined;
+      break;
+    case 'preparing':
+      state = ZLinkPeerState.Connecting;
+      break;
+  }
+  return 'serverRoutingId' in descriptor
+    ? { nodeRid: descriptor.serverRoutingId, weight: descriptor.weight, state, unavailableReason }
+    : { nodeRid: descriptor.publisherRoutingId, state, unavailableReason };
+}
+
 function topologyStateForHost(state: ZLinkFrameworkRuntimeState): ZLinkTopologyState {
   switch (state) {
     case ZLinkFrameworkRuntimeState.Preparing:

package/src/runtime/disposal.ts

@@ -0,0 +1,19 @@
+export class RuntimeDisposal {
+  private task?: Promise<void> | null;
+
+  get started(): boolean {
+    return this.task !== undefined;
+  }
+
+  run(close: () => Promise<void>): Promise<void> {
+    if (this.task != null) return this.task;
+    const task = Promise.resolve()
+      .then(close)
+      .catch((error: unknown) => {
+        this.task = null;
+        throw error;
+      });
+    this.task = task;
+    return task;
+  }
+}

package/src/runtime/execution/index.ts

@@ -241,12 +241,7 @@ export function isCurrentZLinkSpotSerialTurn(executor: ZLinkSpotSerialTurnExecut
 
 export interface ZLinkExecutionBarrierSeal {
   readonly generation: bigint;
-  /**
-   * A Spot Close seal waits for yielded turns accepted before it and lets them
-   * resume (Spot address messaging §7 step 2); a relocation seal does not, and
-   * their continuation fails (execution gate §4).
-   */
-  readonly drainsYieldedTurns: boolean;
+  readonly kind: 'close' | 'relocation';
 }
 
 export interface ZLinkExecutionBarrierClaim {
@@ -270,32 +265,46 @@ 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.committed;
+    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();
   }
 
-  seal(drainsYieldedTurns = false): ZLinkExecutionBarrierSeal {
-    if (this.committed) {
+  seal(kind: ZLinkExecutionBarrierSeal['kind'] = 'relocation'): ZLinkExecutionBarrierSeal {
+    if (this.committedSeal !== undefined) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.SpotMoving,
         'ZLink execution barrier is committed.'
@@ -304,7 +313,7 @@ export class ZLinkExecutionBarrier {
     if (this.currentSeal !== undefined) {
       throw new Error('ZLink execution barrier is already sealed.');
     }
-    const seal = Object.freeze({ generation: ++this.generation, drainsYieldedTurns });
+    const seal = Object.freeze({ generation: ++this.generation, kind });
     this.currentSeal = seal;
     return seal;
   }
@@ -330,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;
@@ -341,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);
@@ -356,7 +390,7 @@ export class ZLinkExecutionBarrier {
   }
 
   private isQuiescent(seal: ZLinkExecutionBarrierSeal): boolean {
-    return this.activeClaims === 0 && (!seal.drainsYieldedTurns || this.suspendedClaims === 0);
+    return this.activeClaims === 0 && (seal.kind !== 'close' || this.suspendedClaims === 0);
   }
 
   private notifyQuiescence(): void {
@@ -366,10 +400,12 @@ export class ZLinkExecutionBarrier {
   private createClaim(): ZLinkExecutionBarrierClaim {
     this.activeClaims++;
     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();
     };
@@ -378,6 +414,10 @@ export class ZLinkExecutionBarrier {
       suspend: () => {
         if (state !== 'active') return;
         state = 'suspended';
+        if (!yielded) {
+          yielded = true;
+          this.yieldedTurnClaims++;
+        }
         this.activeClaims--;
         this.suspendedClaims++;
         this.notifyQuiescence();
@@ -385,8 +425,8 @@ export class ZLinkExecutionBarrier {
       resume: () => {
         if (state !== 'suspended') return state === 'active';
         if (
-          this.committed ||
-          (this.currentSeal !== undefined && !this.currentSeal.drainsYieldedTurns)
+          this.committedSeal !== undefined ||
+          (this.currentSeal !== undefined && this.currentSeal.kind !== 'close')
         ) {
           release();
           return false;