@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -1,6 +1,5 @@
 export interface OperationClock {
-  setTimeout(callback: () => void, delayMs: number): unknown;
-  clearTimeout(handle: unknown): void;
+  now(): number;
 }
 
 export class OperationTimeoutError extends Error {
@@ -26,32 +25,26 @@ export interface PendingOperation<T> {
 }
 
 interface Entry<T> {
-  readonly generation: bigint;
+  readonly deadlineMs?: number;
   readonly resolve: (value: T | PromiseLike<T>) => void;
   readonly reject: (reason: unknown) => void;
-  timer?: unknown;
 }
 
 const systemClock: OperationClock = {
-  setTimeout(callback, delayMs) {
-    // A request promise is live work.  Raw RouteMesh polling deliberately
-    // uses unref'ed timers, so this deadline is the handle that keeps a
-    // submit() caller alive until a reply, cancellation, or deadline settles.
-    return setTimeout(callback, delayMs);
-  },
-  clearTimeout(handle) {
-    clearTimeout(handle as NodeJS.Timeout);
-  }
+  now: () => performance.now()
 };
 
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
 export class OperationRegistry<T> {
   private readonly entries = new Map<bigint, Entry<T>>();
   private nextId = 1n;
-  private generation = 1n;
+  private deadlineCursor?: MapIterator<[bigint, Entry<T>]>;
   private closed = false;
 
-  constructor(private readonly clock: OperationClock = systemClock) {}
+  constructor(
+    private readonly clock: OperationClock = systemClock,
+    private readonly onPendingChanged?: () => void
+  ) {}
 
   register(
     timeoutMs: number,
@@ -62,23 +55,19 @@ export class OperationRegistry<T> {
       throw new RangeError('timeoutMs must be a non-negative finite number.');
     }
     const id = this.nextId++;
-    const generation = this.generation;
     let resolve!: Entry<T>['resolve'];
     let reject!: Entry<T>['reject'];
     const promise = new Promise<T>((onResolve, onReject) => {
       resolve = onResolve;
       reject = onReject;
     });
-    const entry: Entry<T> = { generation, resolve, reject };
+    const entry: Entry<T> = {
+      deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
+      resolve,
+      reject
+    };
     this.entries.set(id, entry);
-    // Durable senders classify exhaustion from admission history. Keep their
-    // identity and cancellation here without racing that decision with a timer.
-    if (timeoutOwner === 'registry') {
-      entry.timer = this.clock.setTimeout(
-        () => this.rejectIfCurrent(id, generation, new OperationTimeoutError(id)),
-        timeoutMs
-      );
-    }
+    if (this.entries.size === 1) this.onPendingChanged?.();
     return { id, promise };
   }
 
@@ -90,10 +79,6 @@ export class OperationRegistry<T> {
   }
 
   fail(id: bigint, reason: unknown): boolean {
-    return this.failCore(id, reason);
-  }
-
-  private failCore(id: bigint, reason: unknown): boolean {
     const entry = this.take(id);
     if (entry === undefined) return false;
     entry.reject(reason);
@@ -101,7 +86,7 @@ export class OperationRegistry<T> {
   }
 
   cancel(id: bigint, message?: string): boolean {
-    return this.failCore(id, new OperationCancelledError(id, message));
+    return this.fail(id, new OperationCancelledError(id, message));
   }
 
   isPending(id: bigint): boolean {
@@ -111,38 +96,36 @@ export class OperationRegistry<T> {
   close(reason = 'Operation registry closed.'): void {
     if (this.closed) return;
     this.closed = true;
-    this.generation++;
-    const pending = [...this.entries.entries()];
-    this.entries.clear();
-    for (const [, entry] of pending) this.clearTimer(entry);
-    for (const [id, entry] of pending) {
-      entry.reject(new OperationCancelledError(id, reason));
-    }
+    for (const id of this.entries.keys()) this.cancel(id, reason);
+    this.deadlineCursor = undefined;
   }
 
   get size(): number {
     return this.entries.size;
   }
 
-  private rejectIfCurrent(id: bigint, generation: bigint, reason: unknown): void {
-    const entry = this.entries.get(id);
-    if (entry === undefined || entry.generation !== generation) return;
-    this.entries.delete(id);
-    this.clearTimer(entry);
-    entry.reject(reason);
+  expire(nowMs: number, turnDeadlineMs: number): number {
+    let expired = 0;
+    while (this.clock.now() < turnDeadlineMs) {
+      this.deadlineCursor ??= this.entries.entries();
+      const current = this.deadlineCursor.next();
+      if (current.done === true) {
+        this.deadlineCursor = undefined;
+        break;
+      }
+      const [id, entry] = current.value;
+      if (entry.deadlineMs !== undefined && entry.deadlineMs <= nowMs) {
+        if (this.fail(id, new OperationTimeoutError(id))) expired++;
+      }
+    }
+    return expired;
   }
 
   private take(id: bigint): Entry<T> | undefined {
     const entry = this.entries.get(id);
     if (entry === undefined) return undefined;
     this.entries.delete(id);
-    this.clearTimer(entry);
+    if (this.entries.size === 0) this.onPendingChanged?.();
     return entry;
   }
-
-  private clearTimer(entry: Entry<T>): void {
-    if (entry.timer === undefined) return;
-    this.clock.clearTimeout(entry.timer);
-    entry.timer = undefined;
-  }
 }

package/src/runtime/foundation/raw-service-mesh-runtime.ts

@@ -1,3 +1,9 @@
+import { constants as osConstants } from 'node:os';
+import { ApplicationIngressRecordOwner } from '../application-jobs/application-ingress-record-owner';
+import type {
+  ApplicationJobPermitPort,
+  ApplicationJobQueuePort
+} from '../application-jobs/contracts';
 import type {
   ZLinkRawBindingPort,
   ZLinkRawHostPort,
@@ -5,23 +11,26 @@ import type {
   ZLinkRawRouterPort
 } from '../backend/raw-binding-port';
 import { RequestResult, SubmitResult } from '../backend/runtime-values';
-import type {
-  ApplicationJobPermitPort,
-  ApplicationJobQueuePort
-} from '../application-jobs/contracts';
-import { ApplicationIngressRecordOwner } from '../application-jobs/application-ingress-record-owner';
+import { enumWireRejectReason } from '../protocol/service_wire_codec.generated';
 import { OperationRegistry, type PendingOperation } from './operation-registry';
 import { ServiceLivenessRegistry, type ServiceLivenessTick } from './service-liveness-registry';
 import { ServiceMailbox, type ServiceMailboxRecord } from './service-mailbox';
 import {
-  ServiceTopologyRegistry,
   sameServiceNodeDescriptor,
+  ServiceTopologyRegistry,
   validateDescriptor,
   type AdmittedServicePeer,
   type PeerAdmissionResult,
-  type ServicePeerAdmissionExpectation,
-  type ServiceNodeDescriptor
+  type ServiceNodeDescriptor,
+  type ServicePeerAdmissionExpectation
 } from './service-topology-registry';
+import { createServiceWireCodec } from './service-wire-codec';
+import {
+  SERVICE_WIRE_MAGIC,
+  SERVICE_WIRE_MAJOR,
+  ServiceWireCommand,
+  ServiceWireFrameworkErrorCode
+} from './service-wire-constants.generated';
 import {
   decodeApplicationPayloadView,
   decodeChannelRequestHeader,
@@ -40,14 +49,11 @@ import {
   encodeReplyHeader,
   encodeRouteMeshAdmission,
   M6aServiceWireCommand,
-  type ServiceApplicationPayload,
-  ServiceWireProtocolError
+  ServiceWireProtocolError,
+  type ServiceApplicationPayload
 } from './service-wire-m6a-codec';
-import { createServiceWireCodec } from './service-wire-codec';
-import {
-  ServiceWireCommand,
-  ServiceWireFrameworkErrorCode
-} from './service-wire-constants.generated';
+
+const nativeErrnoValues = osConstants.errno;
 
 export type RawServicePumpResult =
   'noData' | 'infrastructure' | 'application' | 'dropped' | 'protocolError';
@@ -93,6 +99,7 @@ export type RawServiceIngressHandler = (
 ) => RawServicePumpResult | undefined | Promise<RawServicePumpResult | undefined>;
 
 export interface RawServiceMeshRuntimeOptions {
+  readonly onPendingOperationsChanged?: () => void;
   readonly descriptor: ServiceNodeDescriptor;
   readonly resolveAdvertisedEndpoint?: (boundEndpoint: string) => string;
   readonly probeIntervalMs?: number;
@@ -118,11 +125,15 @@ export interface RawServiceMeshRuntimeOptions {
 
 // Framework error code 13 (RequestTargetNotFound) is encoded as 14 on a
 // RequestResult.NotFound reply. Boundary transport results keep failureCode 0.
-const REQUEST_TARGET_NOT_FOUND_FAILURE_CODE = 14;
+const RAW_MESH_RECEIVE_RECORD_BUDGET = 64;
+const RAW_MESH_RECEIVE_BYTE_BUDGET = 4 * 1024 * 1024;
+export const RAW_MESH_RECEIVE_TIME_BUDGET_MS = 2;
+
+const REQUEST_TARGET_NOT_FOUND_FAILURE_CODE = ServiceWireFrameworkErrorCode.requestTargetNotFound;
 
 const livenessCodec = createServiceWireCodec({
-  magic: [0x5a, 0x4d],
-  major: 1,
+  magic: SERVICE_WIRE_MAGIC,
+  major: SERVICE_WIRE_MAJOR,
   commands: M6aServiceWireCommand
 });
 
@@ -135,7 +146,7 @@ export class RawServiceMeshRuntime {
   readonly mailbox: ServiceMailbox;
   readonly liveness: ServiceLivenessRegistry;
 
-  private readonly operations = new OperationRegistry<RawServiceRequestResult>();
+  private readonly operations: OperationRegistry<RawServiceRequestResult>;
   private readonly expectedPeers = new Map<
     string,
     {
@@ -144,6 +155,7 @@ export class RawServiceMeshRuntime {
       readonly endpoint?: string;
       readonly securityIdentity?: string;
       readonly lifecycleGeneration?: bigint;
+      helloSubmittedGeneration?: bigint;
     }
   >();
   private readonly endpointOnlyPeers = new Set<string>();
@@ -170,6 +182,7 @@ export class RawServiceMeshRuntime {
   private closed = false;
 
   constructor(options: RawServiceMeshRuntimeOptions) {
+    this.operations = new OperationRegistry(undefined, options.onPendingOperationsChanged);
     this.descriptor = options.descriptor;
     this.topology = new ServiceTopologyRegistry(options.descriptor);
     this.mailbox = new ServiceMailbox(options.onMailboxReady);
@@ -224,13 +237,16 @@ export class RawServiceMeshRuntime {
 
   connectPeer(endpoint: string, expected: ServiceNodeDescriptor): void {
     this.requireStarted().connectToRoutingId(expected.nodeRoutingId, endpoint);
-    this.expectedPeers.set(expected.nodeRoutingId, {
-      meshName: expected.meshName,
-      nodeRoutingId: expected.nodeRoutingId,
-      endpoint,
-      securityIdentity: expected.securityIdentity,
-      lifecycleGeneration: expected.lifecycleGeneration
-    });
+    this.expectedPeers.set(
+      expected.nodeRoutingId,
+      Object.assign(this.expectedPeers.get(expected.nodeRoutingId) ?? {}, {
+        meshName: expected.meshName,
+        nodeRoutingId: expected.nodeRoutingId,
+        endpoint,
+        securityIdentity: expected.securityIdentity,
+        lifecycleGeneration: expected.lifecycleGeneration
+      })
+    );
   }
 
   connectPeerByRoutingId(
@@ -240,13 +256,16 @@ export class RawServiceMeshRuntime {
     lifecycleGeneration?: bigint
   ): void {
     this.requireStarted().connectToRoutingId(nodeRoutingId, endpoint);
-    this.expectedPeers.set(nodeRoutingId, {
-      meshName: this.topology.localDescriptor().meshName,
+    this.expectedPeers.set(
       nodeRoutingId,
-      endpoint,
-      securityIdentity,
-      lifecycleGeneration
-    });
+      Object.assign(this.expectedPeers.get(nodeRoutingId) ?? {}, {
+        meshName: this.topology.localDescriptor().meshName,
+        nodeRoutingId,
+        endpoint,
+        securityIdentity,
+        lifecycleGeneration
+      })
+    );
   }
 
   expectPeerByRoutingId(
@@ -255,13 +274,16 @@ export class RawServiceMeshRuntime {
     securityIdentity?: string,
     lifecycleGeneration?: bigint
   ): void {
-    this.expectedPeers.set(nodeRoutingId, {
-      meshName: this.topology.localDescriptor().meshName,
+    this.expectedPeers.set(
       nodeRoutingId,
-      endpoint,
-      securityIdentity,
-      lifecycleGeneration
-    });
+      Object.assign(this.expectedPeers.get(nodeRoutingId) ?? {}, {
+        meshName: this.topology.localDescriptor().meshName,
+        nodeRoutingId,
+        endpoint,
+        securityIdentity,
+        lifecycleGeneration
+      })
+    );
   }
 
   connectPeerEndpoint(endpoint: string): void {
@@ -349,11 +371,25 @@ export class RawServiceMeshRuntime {
   }
 
   async announcePeer(nodeRoutingId: string): Promise<boolean> {
-    if (!this.expectedPeers.has(nodeRoutingId) || this.peerAdmissionSealed?.() === true)
+    const expected = this.expectedPeers.get(nodeRoutingId);
+    const generation = this.selectedRoutes.get(nodeRoutingId);
+    if (
+      expected === undefined ||
+      generation === undefined ||
+      expected.helloSubmittedGeneration === generation ||
+      this.peerAdmissionSealed?.() === true
+    )
       return false;
-    return this.send(nodeRoutingId, [
+    const accepted = await this.send(nodeRoutingId, [
       encodeRouteMeshAdmission(M6aServiceWireCommand.hello, this.topology.localDescriptor())
     ]);
+    if (
+      accepted &&
+      this.expectedPeers.get(nodeRoutingId) === expected &&
+      this.selectedRoutes.get(nodeRoutingId) === generation
+    )
+      expected.helloSubmittedGeneration = generation;
+    return accepted;
   }
 
   isPeerRouteReady(nodeRoutingId: string, lifecycleGeneration?: bigint): boolean {
@@ -371,11 +407,6 @@ export class RawServiceMeshRuntime {
   async announceExpectedPeers(): Promise<number> {
     let accepted = 0;
     for (const nodeRoutingId of this.expectedPeers.keys()) {
-      // Admission is a one-time fence for the current selected route.
-      // Re-sending Hello after the peer is admitted would re-run admission on
-      // every poll and reset the liveness record before application traffic
-      // can use the route. A peer whose selected route ended is removed by the
-      // route observer and remains eligible for the next admission attempt.
       if (this.topology.peer(nodeRoutingId) !== undefined) continue;
       if (await this.announcePeer(nodeRoutingId)) accepted++;
     }
@@ -419,7 +450,6 @@ export class RawServiceMeshRuntime {
     for (const peer of this.topology.peers()) {
       await this.send(peer.descriptor.nodeRoutingId, [update]);
     }
-    await this.announceExpectedPeers();
   }
 
   replaceDiscoveredNotRequired(descriptors: readonly ServiceNodeDescriptor[]): void {
@@ -449,23 +479,6 @@ export class RawServiceMeshRuntime {
     if (selection.kind !== 'selected') return selection.submitResult;
     const selected = selection.peer;
     const applicationFrame = this.applicationFrame(payload);
-    if (selected.descriptor.nodeRoutingId === this.descriptor.nodeRoutingId) {
-      const applicationJobOwner = await this.reserveLocalIngress();
-      try {
-        const applicationJob = await applicationJobOwner.acquire('application');
-        const accepted = this.mailbox.tryEnqueue({
-          owner: `channel:${channelName}`,
-          domain: 'application',
-          parts: [encodeChannelSendHeader(channelName), applicationFrame],
-          sourceRoutingId: this.descriptor.nodeRoutingId,
-          applicationJob
-        });
-        if (!accepted) applicationJob.close();
-        return accepted ? SubmitResult.Ok : SubmitResult.NotAdmitted;
-      } finally {
-        applicationJobOwner.close();
-      }
-    }
     return (await this.send(selected.descriptor.nodeRoutingId, [
       encodeChannelSendHeader(channelName),
       applicationFrame
@@ -503,7 +516,7 @@ export class RawServiceMeshRuntime {
 
   private selectChannelTarget(channelName: string): RawServiceChannelTargetSelection {
     const selected = this.topology.selectChannel(channelName, (peer) =>
-      this.isLocalOrReadyPeer(peer.descriptor.nodeRoutingId)
+      this.isPeerRouteReady(peer.descriptor.nodeRoutingId)
     );
     if (selected !== undefined) return { kind: 'selected', peer: selected };
     return this.topology.hasKnownChannelTarget(channelName)
@@ -522,10 +535,6 @@ export class RawServiceMeshRuntime {
         };
   }
 
-  private isLocalOrReadyPeer(nodeRoutingId: string): boolean {
-    return nodeRoutingId === this.descriptor.nodeRoutingId || this.isPeerRouteReady(nodeRoutingId);
-  }
-
   setServiceIngress(handler: RawServiceIngressHandler): void {
     if (this.serviceIngress !== undefined && this.serviceIngress !== handler) {
       throw new Error('Raw service ingress is already registered.');
@@ -600,20 +609,20 @@ export class RawServiceMeshRuntime {
     return this.receiveOne(nowMs, observe);
   }
 
-  setReadableHandler(handler: () => void): void {
+  setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void {
     this.requireStarted().setReadableHandler(handler);
   }
 
   /** Returns whether a receive budget ended before no-data; idle ticks only maintain peers. */
-  async pumpBatch(receiveReady = true): Promise<boolean> {
-    await this.observeSelectedRoutes();
+  async pumpBatch(receiveReady = true, routeReady = false): Promise<boolean> {
+    if (routeReady) await this.observeSelectedRoutes();
     const startedAtMs = performance.now();
     let messages = 0;
     let bytes = 0;
     const observe: RawServicePumpObserver = (_source, byteCount) => {
       bytes += byteCount;
     };
-    while (receiveReady && messages < 64 && !this.closed) {
+    while (receiveReady && messages < RAW_MESH_RECEIVE_RECORD_BUDGET && !this.closed) {
       const result = await this.receiveOne(performance.now(), observe);
       if (result === 'noData') {
         receiveReady = false;
@@ -622,7 +631,11 @@ export class RawServiceMeshRuntime {
       messages += 1;
       // Core owns the per-peer fair-queue cursor. The Framework limit bounds
       // the entire round, so changing peers does not renew its byte/count budget.
-      if (bytes >= 4 * 1024 * 1024 || performance.now() - startedAtMs >= 2) break;
+      if (
+        bytes >= RAW_MESH_RECEIVE_BYTE_BUDGET ||
+        performance.now() - startedAtMs >= RAW_MESH_RECEIVE_TIME_BUDGET_MS
+      )
+        break;
     }
     if (!this.closed) {
       await this.announceExpectedPeers();
@@ -758,7 +771,9 @@ export class RawServiceMeshRuntime {
           (expected.meshName !== descriptor.meshName ||
             expected.nodeRoutingId !== descriptor.nodeRoutingId)
         ) {
-          await this.send(received.sourceRid, [encodeReject(3)]);
+          await this.send(received.sourceRid, [
+            encodeReject(enumWireRejectReason('identityMismatch'))
+          ]);
           return 'infrastructure';
         }
         const result = this.admitPeer(
@@ -798,23 +813,7 @@ export class RawServiceMeshRuntime {
       }
       if (header.command === M6aServiceWireCommand.reject) {
         if (received.parts.length !== 1) return 'protocolError';
-        const reason = decodeReject(received.parts[0]!);
-        // Keep an already admitted peer: a reject of an earlier Hello on the
-        // same selected route does not end the admission that succeeded.
-        if (reason === 4 && this.topology.peer(received.sourceRid) === undefined) {
-          const expected = this.expectedPeers.get(received.sourceRid);
-          const local = this.topology.localDescriptor();
-          this.topology.markNotRequired({
-            ...local,
-            nodeRoutingId: received.sourceRid,
-            lifecycleGeneration: 1n,
-            descriptorRevision: 1n,
-            advertisedEndpoint: expected?.endpoint ?? local.advertisedEndpoint,
-            channels: [],
-            objectRole: 'client'
-          });
-          this.retireNotRequiredExpectedPeer(received.sourceRid);
-        }
+        decodeReject(received.parts[0]!);
         return 'infrastructure';
       }
       const peer = this.topology.peer(received.sourceRid);
@@ -945,6 +944,14 @@ export class RawServiceMeshRuntime {
     }
   }
 
+  expireOperations(nowMs: number, turnDeadlineMs: number): number {
+    return this.operations.expire(nowMs, turnDeadlineMs);
+  }
+
+  get pendingOperationCount(): number {
+    return this.operations.size;
+  }
+
   async tickLiveness(nowMs = performance.now()): Promise<ServiceLivenessTick> {
     const result = this.liveness.tick(nowMs);
     this.requireStarted();
@@ -982,6 +989,8 @@ export class RawServiceMeshRuntime {
     for (const [nodeRoutingId, generation] of this.selectedRoutes) {
       if (observed.get(nodeRoutingId) === generation) continue;
       changes++;
+      const expected = this.expectedPeers.get(nodeRoutingId);
+      if (expected !== undefined) delete expected.helloSubmittedGeneration;
       const peer = this.topology.peer(nodeRoutingId);
       if (peer !== undefined && peer.connectionId === routeConnectionId(generation)) {
         this.removePeer(peer);
@@ -1001,7 +1010,6 @@ export class RawServiceMeshRuntime {
 
   close(): void {
     if (this.closed) return;
-    this.closed = true;
     this.applicationJobStop.abort(
       new Error('Raw service runtime application job admission stopped.')
     );
@@ -1013,9 +1021,10 @@ export class RawServiceMeshRuntime {
       this.applicationJobQueue.unregisterReceiveFlowTarget?.(router);
     }
     const host = this.host;
+    if (host !== undefined) host.close();
     this.router = undefined;
     this.host = undefined;
-    if (host !== undefined) host.close();
+    this.closed = true;
   }
 
   private requestToTarget(
@@ -1046,14 +1055,11 @@ export class RawServiceMeshRuntime {
         for (;;) {
           const alternate = this.topology.selectChannel(channelName, (peer) => {
             const candidate = peer.descriptor.nodeRoutingId;
-            return !excludedTargets.has(candidate) && this.isLocalOrReadyPeer(candidate);
+            return !excludedTargets.has(candidate) && this.isPeerRouteReady(candidate);
           });
           if (alternate === undefined) break;
           selectedTargetNodeRoutingId = alternate.descriptor.nodeRoutingId;
-          if (
-            selectedTargetNodeRoutingId === this.descriptor.nodeRoutingId ||
-            this.isPeerRouteReady(selectedTargetNodeRoutingId)
-          ) {
+          if (this.isPeerRouteReady(selectedTargetNodeRoutingId)) {
             break;
           }
           excludedTargets.add(selectedTargetNodeRoutingId);
@@ -1077,10 +1083,7 @@ export class RawServiceMeshRuntime {
             return;
           }
           const accepted = this.mailbox.tryEnqueue({
-            owner:
-              channelName === undefined
-                ? `node:${this.descriptor.nodeRoutingId}`
-                : `channel:${channelName}`,
+            owner: `node:${this.descriptor.nodeRoutingId}`,
             domain: 'application',
             parts,
             sourceRoutingId: this.descriptor.nodeRoutingId,
@@ -1300,7 +1303,7 @@ function isAlreadyDisconnectedError(error: unknown): boolean {
   if (typeof error !== 'object' || error === null || !('nativeErrno' in error)) {
     return false;
   }
-  return (error as { readonly nativeErrno?: unknown }).nativeErrno === 2;
+  return (error as { readonly nativeErrno?: unknown }).nativeErrno === nativeErrnoValues.ENOENT;
 }
 
 /**
@@ -1378,17 +1381,13 @@ function immutableDescriptorMismatch(
   return undefined;
 }
 
-function admissionReason(result: PeerAdmissionResult): number {
+function admissionReason(result: Exclude<PeerAdmissionResult, 'admitted' | 'notRequired'>): number {
   switch (result) {
     case 'meshMismatch':
-      return 2;
+      return enumWireRejectReason('topologyMismatch');
     case 'staleDescriptor':
-      return 7;
+      return enumWireRejectReason('descriptorRevisionStale');
     case 'invalidDescriptor':
-      return 11;
-    case 'notRequired':
-      return 4;
-    case 'admitted':
-      return 1;
+      return enumWireRejectReason('invalidDescriptor');
   }
 }

package/src/runtime/foundation/runtime-state-projections.ts

@@ -1,4 +1,12 @@
-import { ZLinkFrameworkRuntimeState } from '../../contracts';
+import { ZLinkFrameworkRuntimeState, ZLinkTopologyState } from '../../contracts';
+
+export function runtimeObservationIsTerminal(state: ZLinkFrameworkRuntimeState): boolean {
+  return state === ZLinkFrameworkRuntimeState.Stopped;
+}
+
+export function topologyObservationIsTerminal(state: ZLinkTopologyState): boolean {
+  return state === ZLinkTopologyState.Stopped || state === ZLinkTopologyState.Failed;
+}
 
 export type MaintenanceAdmissionState =
   'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';