@zlink-systems/framework 0.25.0 → 0.26.0

package/src/runtime/backend/node/node-backend-adapter-support.ts

@@ -63,10 +63,6 @@ export function isRouteRecvRetryable(error: unknown): boolean {
   );
 }
 
-export function isPollerInterruptedError(error: unknown): boolean {
-  return error instanceof zlink.RecvError && error.nativeErrno === 4;
-}
-
 function isNativeBadAddress(error: { nativeErrno?: unknown; message?: unknown }): boolean {
   return error.nativeErrno === 14 || /Bad address/i.test(String(error.message ?? ''));
 }
@@ -176,32 +172,16 @@ export async function submitBindingRequest(
   }
 }
 
-export async function closeWithBusyRetry(target: { close(): void }): Promise<void> {
-  let lastError: unknown;
-  for (let attempt = 0; attempt < 8; attempt++) {
-    try {
-      target.close();
-      return;
-    } catch (error) {
-      if (isSuccessfulOrAlreadyShutdownCloseError(error)) {
-        return;
-      }
-      if (!isBusyCloseError(error)) {
-        throw error;
-      }
-      lastError = error;
-      await new Promise<void>((resolve) => setImmediate(resolve));
-    }
+/**
+ * Closes a binding handle once. An already closed or terminated handle counts as
+ * closed. A busy close propagates to the caller.
+ */
+export function closeBindingHandle(target: { close(): void }): void {
+  try {
+    target.close();
+  } catch (error) {
+    if (!isSuccessfulOrAlreadyShutdownCloseError(error)) throw error;
   }
-  throw lastError;
-}
-
-function isBusyCloseError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    'code' in error &&
-    [401, 404].includes((error as { code: number }).code)
-  );
 }
 
 function isSuccessfulOrAlreadyShutdownCloseError(error: unknown): boolean {

package/src/runtime/backend/node/node-event-loop-poller.ts

@@ -12,11 +12,19 @@ export class ZLinkNodeEventLoopPoller {
   private readableHandler: () => void;
   private disposed = false;
 
-  constructor(socket: Socket, pollCompletion: boolean, readableHandler: () => void) {
+  constructor(
+    socket: Socket,
+    pollCompletion: boolean,
+    readableHandler: () => void,
+    pollRoute = false
+  ) {
     this.readableHandler = readableHandler;
     try {
       const pollEvents: PollEventFlagValue[] = [zlink.PollEventFlag.PollIn];
       if (pollCompletion) pollEvents.push(zlink.PollEventFlag.PollCompletion);
+      // A ROUTER selected-route change (Core ROUTER §10.1) wakes the same
+      // handler, whose owner is the socket's one route observer.
+      if (pollRoute) pollEvents.push(zlink.PollEventFlag.PollRoute);
       this.poller.add(socket as BaseSocket, pollEvents, 0);
       socket.setReadableHandler(this.onReady);
     } catch (error) {
@@ -40,7 +48,11 @@ export class ZLinkNodeEventLoopPoller {
   private readonly onReady = (): void => {
     if (this.disposed) return;
     const ready = this.poller.wait(this.events, 0);
-    if (ready === 0 || this.events.hasEvent(0, zlink.PollEventFlag.PollIn)) {
+    if (
+      ready === 0 ||
+      this.events.hasEvent(0, zlink.PollEventFlag.PollIn) ||
+      this.events.hasEvent(0, zlink.PollEventFlag.PollRoute)
+    ) {
       this.readableHandler();
     }
   };

package/src/runtime/backend/node/node-raw-binding-port.ts

@@ -33,6 +33,7 @@ import type {
   ZLinkRawMonitorRecord,
   ZLinkRawReceivedRecord,
   ZLinkRawRouterPort,
+  ZLinkRawRouterRoute,
   ZLinkRawSocketPort
 } from '../raw-binding-port';
 export type {
@@ -43,6 +44,7 @@ export type {
   ZLinkRawMonitorRecord,
   ZLinkRawReceivedRecord,
   ZLinkRawRouterPort,
+  ZLinkRawRouterRoute,
   ZLinkRawSocketPort
 } from '../raw-binding-port';
 
@@ -131,8 +133,11 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
   private readonly eventLoopPoller: ZLinkNodeEventLoopPoller;
   private closed = false;
 
-  protected constructor(protected readonly socket: TSocket) {
-    this.eventLoopPoller = new ZLinkNodeEventLoopPoller(socket, true, () => {});
+  protected constructor(
+    protected readonly socket: TSocket,
+    pollRoute = false
+  ) {
+    this.eventLoopPoller = new ZLinkNodeEventLoopPoller(socket, true, () => {}, pollRoute);
   }
 
   setReadableHandler(handler: () => void): void {
@@ -236,7 +241,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
   }
 
   constructor(socket: RouterSocket, receiveTimeoutMs?: number) {
-    super(socket);
+    super(socket, true);
     socket.options.handover = true;
     socket.options.mandatory = true;
     socket.options.probe = true;
@@ -291,6 +296,14 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     }
   }
 
+  routesSnapshot(): readonly ZLinkRawRouterRoute[] {
+    this.requireOpen();
+    return this.socket.routesSnapshot().map((route) => ({
+      routingId: route.routingId.toString(),
+      routeGeneration: route.routeGeneration
+    }));
+  }
+
   receive(dontWait = false): ZLinkRawReceivedRecord | undefined {
     this.requireOpen();
     return receiveRecord(
@@ -450,6 +463,7 @@ function receiveRecord(
     return {
       sourceRid,
       sourceRoute,
+      routeGeneration: received.routeGeneration,
       ...(requestSeq === undefined ? {} : { requestSeq }),
       ...(receivedReply === undefined
         ? {}

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -7,6 +7,7 @@ import {
   encodeStreamWireHeader
 } from '@zlink-systems/stream-wire';
 import { disconnectStreamPeer } from './node-socket-backend-adapter';
+import { translateBindingResultError } from './node-backend-adapter-support';
 import { ZLinkFrameworkException } from '../../../contracts';
 import { internalFrameworkWireReply } from '../../framework-errors-internal';
 import {
@@ -105,7 +106,6 @@ import { buildAdvertisedEndpoint } from '../../../contracts/Configuration/Endpoi
 import { ZLinkConfigurationException } from '../../../contracts/Configuration/ConfigurationException';
 import type {
   ZLinkBackendActorRef,
-  ZLinkBackendActorSessionSendFence,
   ZLinkBackendObjectPlacement,
   ZLinkBackendMeshNode
 } from '../contracts';
@@ -116,7 +116,7 @@ const MULTIPART_PACKET_NAME = SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME;
 const MULTIPART_CONTENT_TYPE = SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE;
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 const MAX_DRAIN_RECORDS = 64;
-// Preserve the existing monitor/admission/liveness cadence. Only the binding
+// Preserve the existing route observation/admission/liveness cadence. Only the binding
 // readable handler admits receive work; this timer never probes the socket.
 const MESH_BACKEND_MAINTENANCE_INTERVAL_MS = 1;
 /**
@@ -186,6 +186,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     record: import('../../foundation/service-stateful-wire-codec').ServiceMessageFollowRecord
   ) => void;
   private dispatchErrors?: ZLinkDispatchErrorReporter;
+  private spotAdmissionProvider?: Parameters<ServiceStatefulRuntime['setSpotAdmissionProvider']>[0];
   private readonly peerDisconnectedHandlers = new Set<(endpoint: string) => void>();
   constructor(
     private readonly meshName: string,
@@ -241,6 +242,13 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.stateful?.setDispatchErrorReporter(reporter, this.meshName);
   }
 
+  setSpotAdmissionProvider(
+    provider: Parameters<ServiceStatefulRuntime['setSpotAdmissionProvider']>[0]
+  ): void {
+    this.spotAdmissionProvider = provider;
+    this.stateful?.setSpotAdmissionProvider(provider);
+  }
+
   setProtocolErrorHandler(
     handler: (record: {
       readonly sourceNodeRid: string;
@@ -394,6 +402,9 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       descriptor.nodeRoutingId,
       descriptor.lifecycleGeneration
     );
+    if (this.spotAdmissionProvider !== undefined) {
+      this.stateful.setSpotAdmissionProvider(this.spotAdmissionProvider);
+    }
     if (this.dispatchErrors !== undefined) {
       this.stateful.setDispatchErrorReporter(this.dispatchErrors, this.meshName);
     }
@@ -1327,14 +1338,12 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     actor: ZLinkBackendActorRef,
     expectedBindingGeneration: bigint,
     parts: MessageLike | readonly MessageLike[],
-    _flags?: number,
-    actorFence?: ZLinkBackendActorSessionSendFence
+    _flags?: number
   ): Promise<SubmitResultValue> {
     return (await this.requireStateful().sendBoundSession(
       actor,
       expectedBindingGeneration,
-      encodeMultipart(parts),
-      actorFence
+      encodeMultipart(parts)
     )) as SubmitResultValue;
   }
 
@@ -1524,7 +1533,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     const id = { high: 1n, low };
     void promise.then(
       (result) => this.enqueueCompletion(id, operationKind, result),
-      (error) => this.enqueueCompletion(id, operationKind, genericOperationFailure(error))
+      (error) => this.enqueueCompletion(id, operationKind, requestFailureResult(error))
     );
     return id;
   }
@@ -1536,7 +1545,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     const id = { high: 2n, low: pending.id };
     void pending.promise.then(
       (result) => this.enqueueCompletion(id, operationKind, result),
-      (error) => this.enqueueCompletion(id, operationKind, statefulOperationFailure(error))
+      (error) => this.enqueueCompletion(id, operationKind, requestFailureResult(error))
     );
     return id;
   }
@@ -2430,40 +2439,64 @@ function readyDomain(domain: ServiceMailboxDomain): number {
 }
 
 /**
- * Classifies a generic node/channel request rejection into a completion
- * terminal. Spec 32-framework-error-model:91-92 — a reply that could not be
- * decoded (ServiceWireProtocolError from the reply parser) is a protocol
- * failure, not connection loss; only genuine transport rejections collapse to
- * NotConnected.
+ * The one classification of a failed node/channel/stateful request into its
+ * completion terminal. A binding REQUEST result is Core's decision and is kept
+ * as is; a submit failure retains its Core meaning at the request boundary.
+ * A reply that could not be decoded is a protocol
+ * failure (spec 32-framework-error-model:91-92). The failure code is a wire
+ * code, so a Core result carries 0.
  */
-export function genericOperationFailure(error: unknown): RawServiceRequestResult {
+export function requestFailureResult(error: unknown): RawServiceRequestResult {
+  const failure = translateBindingResultError(error);
+  if (isZLinkBackendResultError(failure)) {
+    return {
+      terminalResult:
+        failure.operation === 'request' ? failure.result : submitFailureTerminal(failure.result),
+      failureCode: 0
+    };
+  }
   //  requestProtocolError(16): the schema terminal-failure-integrity rule
-  //  forbids a typed terminal (104) with failure none, so the synthesized
-  //  decode-failure pair is 104+16; genuine transport loss stays 109+0.
-  return error instanceof ServiceWireProtocolError
-    ? { terminalResult: RequestResult.ProtocolError, failureCode: 16 }
-    : { terminalResult: RequestResult.NotConnected, failureCode: 0 };
-}
-
-function statefulOperationFailure(error: unknown): RawServiceRequestResult {
-  if (error instanceof ZLinkFrameworkException) {
-    return internalFrameworkWireReply(error);
+  //  forbids a typed terminal (104) with failure none.
+  if (failure instanceof ServiceWireProtocolError) {
+    return { terminalResult: RequestResult.ProtocolError, failureCode: 16 };
   }
-  if (error instanceof OperationTimeoutError) {
-    return { terminalResult: RequestResult.TimedOut, failureCode: 0 };
+  if (failure instanceof ZLinkFrameworkException) {
+    return internalFrameworkWireReply(failure);
   }
-  if (isZLinkBackendResultError(error)) {
-    return {
-      terminalResult: error.result,
-      failureCode: error.nativeErrno ?? 0
-    };
+  if (failure instanceof OperationTimeoutError) {
+    return { terminalResult: RequestResult.TimedOut, failureCode: 0 };
   }
-  if (error instanceof OperationCancelledError) {
+  if (failure instanceof OperationCancelledError) {
     return { terminalResult: RequestResult.NotConnected, failureCode: 0 };
   }
   return { terminalResult: RequestResult.InternalError, failureCode: 17 };
 }
 
+function submitFailureTerminal(result: number): number {
+  switch (result) {
+    case SubmitResult.Backpressured:
+      return RequestResult.Backpressured;
+    case SubmitResult.NotConnected:
+      return RequestResult.NotConnected;
+    case SubmitResult.NotFound:
+      return RequestResult.NotFound;
+    case SubmitResult.NotAdmitted:
+      return RequestResult.Rejected;
+    case SubmitResult.InvalidHandle:
+    case SubmitResult.InvalidArgument:
+    case SubmitResult.ThreadViolation:
+      return RequestResult.InvalidArgument;
+    case SubmitResult.InvalidState:
+      return RequestResult.InvalidState;
+    case SubmitResult.NotSupported:
+      return RequestResult.NotSupported;
+    case SubmitResult.Terminated:
+      return RequestResult.Terminated;
+    default:
+      return RequestResult.InternalError;
+  }
+}
+
 function encodeMultipart(parts: MessageLike | readonly MessageLike[]) {
   const values = Array.isArray(parts) ? parts : [parts];
   if (values.length === 0) throw new TypeError('Multipart payload must contain at least one part.');

package/src/runtime/backend/node/node-socket-backend-adapter.ts

@@ -1,7 +1,7 @@
 import type { Socket } from '@zlink-systems/zlink';
 import type { ZLinkBackendObject } from '../contracts';
 import {
-  closeWithBusyRetry,
+  closeBindingHandle,
   disableSocketLinger,
   isBindingNotFound,
   isContextTerminatedError,
@@ -52,7 +52,7 @@ export function wrapSocket<T extends { close(): void }>(
     async dispose(): Promise<void> {
       eventLoopPoller?.dispose();
       disableSocketLinger(nativeInstance);
-      await closeWithBusyRetry(nativeInstance);
+      closeBindingHandle(nativeInstance);
     },
     close(): void {
       eventLoopPoller?.dispose();

package/src/runtime/backend/raw-binding-port.ts

@@ -2,6 +2,11 @@ export interface ZLinkRawReceivedRecord {
   readonly sourceRid: string;
   readonly sourceRoute: Uint8Array;
   readonly requestSeq?: bigint;
+  /**
+   * Core selected-route generation of the ROUTER route that delivered this
+   * record (Core ROUTER §10.1); 0n for a non-ROUTER receive. Equality only.
+   */
+  readonly routeGeneration: bigint;
   readonly reply?: (parts: readonly Uint8Array[]) => void;
   readonly parts: readonly Buffer[];
   /** Releases the ordinary Framework-owned receive record exactly once. */
@@ -37,6 +42,12 @@ export interface ZLinkRawMonitorPort {
   close(): void;
 }
 
+/** One row of the ROUTER selected-route snapshot (Core ROUTER §10.1). */
+export interface ZLinkRawRouterRoute {
+  readonly routingId: string;
+  readonly routeGeneration: bigint;
+}
+
 export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
   disconnectRid?(routingId: string): void;
   localEndpoint(): string;
@@ -49,6 +60,8 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
     timeoutMs: number
   ): Promise<readonly Buffer[]>;
   receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
+  /** The selected route of every RID. The socket's one route observer calls it. */
+  routesSnapshot(): readonly ZLinkRawRouterRoute[];
 }
 
 export interface ZLinkRawDealerPort extends ZLinkRawSocketPort {

package/src/runtime/channels/channel-clients.ts

@@ -138,17 +138,6 @@ export class DefaultZLinkFanoutClient implements ZLinkFanoutClient {
     );
   }
 
-  getListenerStatus(channelName: string): import('../../contracts').ZLinkFanoutListenerStatus {
-    this.requirePublisherChannel(channelName);
-    const status = this.requireTransport().getFanoutListenerStatus?.(channelName);
-    if (status === undefined) {
-      throw new ZLinkConfigurationException(
-        `Fanout publisher '${channelName}' has not reported a bound listener.`
-      );
-    }
-    return status;
-  }
-
   private requirePublisherChannel(channelName: string): void {
     if (!this.registration.fanoutPublishers.has(channelName)) {
       throw new ZLinkConfigurationException(

package/src/runtime/channels/channel-outbound-operations.ts

@@ -72,11 +72,7 @@ export class ZLinkChannelOutboundOperations {
     throwIfAborted(signal);
     const dealer = await this.sockets.awaitClientDealerForOutbound(channelName, signal);
     if (dealer === undefined) {
-      return {
-        status: this.sockets.hasKnownClientServerTargets(channelName)
-          ? ZLinkSubmitStatus.RouteNotConnected
-          : ZLinkSubmitStatus.TargetNotFound
-      };
+      return { status: ZLinkSubmitStatus.RouteNotConnected };
     }
     const parts = encodeChannelEnvelopeParts(
       ZLinkChannelMessageKind.Command,
@@ -185,12 +181,8 @@ export class ZLinkChannelOutboundOperations {
         deadlineAtMs === undefined ? undefined : Math.floor(deadlineAtMs - performance.now());
       if (dealer === undefined || (remainingMs !== undefined && remainingMs <= 0)) {
         throw createInternalFrameworkException(
-          this.sockets.hasKnownClientServerTargets(channelName)
-            ? ZLinkFrameworkInternalErrorKind.RouteNotConnected
-            : ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
-          this.sockets.hasKnownClientServerTargets(channelName)
-            ? `Channel '${channelName}' has known ClientServer targets but no ready server.`
-            : `Channel '${channelName}' has no ready ClientServer server.`
+          ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+          `Channel '${channelName}' has no ready ClientServer server.`
         );
       }
       const serverRid = this.sockets.selectedClientServerRid(channelName, dealer);

package/src/runtime/channels/channel-runtime-manager.ts

@@ -1,3 +1,4 @@
+import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { RoutingId } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -62,7 +63,8 @@ export class ZLinkChannelRuntimeManager {
       context,
       options.monitoringAdapter,
       options.oneWayFailureSink,
-      applicationJobQueue
+      applicationJobQueue,
+      options.listenerRecords
     );
     const codecs: ZLinkChannelEnvelopeCodecRegistry = {
       serializers: registration.messageSerializers
@@ -118,20 +120,6 @@ export class ZLinkChannelRuntimeManager {
     return { descriptors: this.sockets.fanoutActiveTargets(channelName) };
   }
 
-  getFanoutListenerStatus(channelName: string) {
-    const endpoint = this.sockets.fanoutPublisherEndpoint(channelName);
-    if (endpoint === undefined) {
-      throw new ZLinkConfigurationException(
-        `Fanout publisher '${channelName}' has not reported a bound listener.`
-      );
-    }
-    return {
-      channelName,
-      endpoint,
-      observedAt: new Date()
-    };
-  }
-
   observeClientServerTopology(channelName: string, changed: () => void): () => void {
     const monitor = this.sockets.clientServerMonitoringSource(channelName);
     monitor.onEvent(changed);
@@ -447,6 +435,7 @@ function splitMonitoringSocketSourceName(sourceName: string): readonly [string,
 }
 
 export interface ZLinkChannelRuntimeManagerOptions {
+  readonly listenerRecords?: ZLinkListenerRecords;
   readonly internalRouteSendHandlers?: ReadonlyMap<string, ZLinkRouteRuntimeSendHandler>;
   readonly internalRouteRequestHandlers?: ReadonlyMap<string, ZLinkRouteRuntimeRequestHandler>;
   readonly monitoringAdapter?: ZLinkMonitoringBackendAdapter;