@zlink-systems/framework 0.21.0 → 0.22.0

package/src/runtime/channels/spot-route-bridge-transport.ts

@@ -2,7 +2,11 @@ import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendSpotRouteBridge } from '../backend/contracts';
 import { ZLinkConfigurationException } from '../configuration';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import { closeMessages, decodeChannelReply, type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+import {
+  closeMessages,
+  decodeChannelReply,
+  type ZLinkChannelEnvelopeCodecRegistry
+} from './channel-envelope';
 import { appendParts } from './channel-multipart';
 import { awaitWithAbort } from '../abort';
 
@@ -16,13 +20,20 @@ export class ZLinkSpotRouteBridgeTransport {
     return this.bridges.has(routerChannelId);
   }
 
-  async send(target: ZLinkSpotRouteTarget, parts: readonly Message[], signal?: AbortSignal): Promise<void> {
+  async send(
+    target: ZLinkSpotRouteTarget,
+    parts: readonly Message[],
+    signal?: AbortSignal
+  ): Promise<void> {
     const bridge = this.requireBridge(target.routerChannelId);
     try {
-      await awaitWithAbort(appendParts(
-        bridge.send(target.routerChannelId, target.targetNodeRid, target.spotId),
-        parts
-      ).submit(), signal);
+      await awaitWithAbort(
+        appendParts(
+          bridge.send(target.routerChannelId, target.targetNodeRid, target.spotId),
+          parts
+        ).submit(),
+        signal
+      );
     } finally {
       closeMessages(parts);
     }
@@ -39,7 +50,9 @@ export class ZLinkSpotRouteBridgeTransport {
     const operation = appendParts(
       bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId),
       parts
-    ).timeout(timeoutMs ?? 0).submit();
+    )
+      .timeout(timeoutMs ?? 0)
+      .submit();
     const replyParts = await awaitWithAbort(operation, signal, () => {
       void operation.then(closeMessages, () => undefined);
     });
@@ -58,7 +71,8 @@ export class ZLinkSpotRouteBridgeTransport {
     signal?: AbortSignal
   ): Promise<readonly Message[]> {
     const bridge = this.requireBridge(target.routerChannelId);
-    const operation = bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId)
+    const operation = bridge
+      .request(target.routerChannelId, target.targetNodeRid, target.spotId)
       .message(request)
       .timeout(timeoutMs ?? this.defaultRequestTimeoutMs ?? 0)
       .submit();
@@ -69,7 +83,10 @@ export class ZLinkSpotRouteBridgeTransport {
 
   private requireBridge(routerChannelId: string): ZLinkBackendSpotRouteBridge {
     const bridge = this.bridges.get(routerChannelId);
-    if (bridge === undefined) throw new ZLinkConfigurationException(`Route channel '${routerChannelId}' has no SPOT route bridge.`);
+    if (bridge === undefined)
+      throw new ZLinkConfigurationException(
+        `Route channel '${routerChannelId}' has no SPOT route bridge.`
+      );
     return bridge;
   }
 }

package/src/runtime/channels/spot-route-dispatch-strategy.ts

@@ -1,7 +1,11 @@
 import type { Message } from '../../contracts/Common/Message';
 import type { RoutingId } from '../../contracts';
 import type { ZLinkFrameworkRegistration } from '../configuration';
-import type { ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendSpotRouteBridge } from '../backend/contracts';
+import type {
+  ZLinkBackendSpot,
+  ZLinkBackendSpotNode,
+  ZLinkBackendSpotRouteBridge
+} from '../backend/contracts';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import {
   encodeChannelEnvelopeParts,
@@ -103,9 +107,8 @@ export class ZLinkSpotRouteDispatchStrategy {
   ): Promise<void> {
     // Call-scoped flow (spec 27 §4): the envelope flow pair lives only for
     // the duration of this outbound call, never in the caller's context.
-    return runWithOutboundFlow(
-      this.options.flowCreationEnabled?.() ?? true,
-      () => this.routeSendToSpotScoped(spotRouteTarget, packetName, message, signal, metadata, timeoutMs)
+    return runWithOutboundFlow(this.options.flowCreationEnabled?.() ?? true, () =>
+      this.routeSendToSpotScoped(spotRouteTarget, packetName, message, signal, metadata, timeoutMs)
     );
   }
 
@@ -143,8 +146,10 @@ export class ZLinkSpotRouteDispatchStrategy {
       this.options.flowCreationEnabled?.() ?? true,
       metadata
     ) as readonly Message[];
-    if (this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId)
-      && await this.spotNodeTransport.send(spotRouteTarget, parts, signal)) {
+    if (
+      this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId) &&
+      (await this.spotNodeTransport.send(spotRouteTarget, parts, signal))
+    ) {
       return;
     }
     if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
@@ -169,9 +174,15 @@ export class ZLinkSpotRouteDispatchStrategy {
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<TReply> {
-    return runWithOutboundFlow(
-      this.options.flowCreationEnabled?.() ?? true,
-      () => this.routeRequestToSpotScoped<TReply>(spotRouteTarget, packetName, request, timeoutMs, signal, metadata)
+    return runWithOutboundFlow(this.options.flowCreationEnabled?.() ?? true, () =>
+      this.routeRequestToSpotScoped<TReply>(
+        spotRouteTarget,
+        packetName,
+        request,
+        timeoutMs,
+        signal,
+        metadata
+      )
     );
   }
 
@@ -219,7 +230,13 @@ export class ZLinkSpotRouteDispatchStrategy {
       if (namedSpotNodeRequest !== undefined) return namedSpotNodeRequest;
     }
     if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
-      return this.bridgeTransport.request<TReply>(spotRouteTarget, parts, codecs, timeoutMs, signal);
+      return this.bridgeTransport.request<TReply>(
+        spotRouteTarget,
+        parts,
+        codecs,
+        timeoutMs,
+        signal
+      );
     }
     if (this.targets.hasBoundRouteRouter(spotRouteTarget.routerChannelId)) {
       return this.routerSocketTransport.request<TReply>(
@@ -296,7 +313,13 @@ export class ZLinkSpotRouteDispatchStrategy {
     timeoutMs: number | undefined,
     signal?: AbortSignal
   ): Promise<readonly Message[]> {
-    return this.sourceSpotRouter.requestRaw(sourceSpot, spotRouteTarget, request, timeoutMs, signal);
+    return this.sourceSpotRouter.requestRaw(
+      sourceSpot,
+      spotRouteTarget,
+      request,
+      timeoutMs,
+      signal
+    );
   }
 
   async routeRequestRawToSpot(
@@ -318,12 +341,16 @@ export class ZLinkSpotRouteDispatchStrategy {
     if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
       return this.bridgeTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
     }
-    const spotNodeRequest = this.spotNodeTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+    const spotNodeRequest = this.spotNodeTransport.requestRaw(
+      spotRouteTarget,
+      request,
+      timeoutMs,
+      signal
+    );
     if (spotNodeRequest !== undefined) {
       return spotNodeRequest;
     }
 
     return this.routerSocketTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
   }
-
 }

package/src/runtime/channels/spot-route-target-resolver.ts

@@ -17,8 +17,9 @@ export class ZLinkSpotRouteTargetResolver {
     if (named?.router !== undefined) {
       return this.spotNodes?.get(routerChannelId);
     }
-    const channelOwners = [...this.registration.spotNodes.entries()]
-      .filter(([, node]) => Object.prototype.hasOwnProperty.call(node.meshChannels ?? {}, routerChannelId));
+    const channelOwners = [...this.registration.spotNodes.entries()].filter(([, node]) =>
+      Object.prototype.hasOwnProperty.call(node.meshChannels ?? {}, routerChannelId)
+    );
     if (channelOwners.length === 1) {
       return this.spotNodes?.get(channelOwners[0][0]);
     }
@@ -40,8 +41,10 @@ export class ZLinkSpotRouteTargetResolver {
   }
 
   localRouteNode(target: ZLinkSpotRouteTarget): ZLinkBackendSpotNode | undefined {
-    const routeNode = this.routeNode(target.routerChannelId) ?? this.spotNodes?.get(target.routerChannelId);
-    return routeNode !== undefined && routingIdsMatchSpotRoute(routeNode.routingId, target.targetNodeRid)
+    const routeNode =
+      this.routeNode(target.routerChannelId) ?? this.spotNodes?.get(target.routerChannelId);
+    return routeNode !== undefined &&
+      routingIdsMatchSpotRoute(routeNode.routingId, target.targetNodeRid)
       ? routeNode
       : undefined;
   }
@@ -55,8 +58,10 @@ export class ZLinkSpotRouteTargetResolver {
   }
 
   canRouteChannel(routerChannelId: string): boolean {
-    return this.registration.routeChannels.has(routerChannelId)
-      || this.spotNodeRouter(routerChannelId) !== undefined;
+    return (
+      this.registration.routeChannels.has(routerChannelId) ||
+      this.spotNodeRouter(routerChannelId) !== undefined
+    );
   }
 
   canRoutePacketChannel(routerChannelId: string): boolean {
@@ -73,15 +78,19 @@ export class ZLinkSpotRouteTargetResolver {
   hasNamedSpotNode(routerChannelId: string): boolean {
     return this.registration.spotNodes.has(routerChannelId);
   }
-
 }
 
-function routingIdsMatchSpotRoute(left: RoutingId | undefined, right: RoutingId | undefined): boolean {
+function routingIdsMatchSpotRoute(
+  left: RoutingId | undefined,
+  right: RoutingId | undefined
+): boolean {
   if (left === undefined || right === undefined) {
     return false;
   }
   const rightCandidates = spotRouteRoutingIdCandidates(right);
-  return [...spotRouteRoutingIdCandidates(left)].some(candidate => rightCandidates.has(candidate));
+  return [...spotRouteRoutingIdCandidates(left)].some((candidate) =>
+    rightCandidates.has(candidate)
+  );
 }
 
 function spotRouteRoutingIdCandidates(routingId: RoutingId): ReadonlySet<string> {

package/src/runtime/codecs/index.ts

@@ -12,7 +12,9 @@ import {
   type ZLinkCodecSerializerSelection
 } from '../../contracts/Configuration/CodecSerializerSelection';
 
-export class DefaultZLinkCodecRegistryBuilder implements ZLinkCodecRegistryBuilder, ZLinkCodecRegistrar {
+export class DefaultZLinkCodecRegistryBuilder
+  implements ZLinkCodecRegistryBuilder, ZLinkCodecRegistrar
+{
   private readonly serializers = new Map<string, ZLinkMessageSerializer>();
   private readonly serializerSelections = new Map<string, ZLinkCodecSerializerSelection>();
   private readonly streamCodecs = new Map<string, unknown>();
@@ -65,5 +67,4 @@ export class DefaultZLinkCodecRegistryBuilder implements ZLinkCodecRegistryBuild
     this.codecs.add(normalized);
     return this;
   }
-
 }

package/src/runtime/diagnostics/flow-context.ts

@@ -13,9 +13,18 @@ export function currentFlowContext(): ZLinkFlowContextValue | undefined {
   return flowStorage.getStore();
 }
 
-export function currentOrCreateFlow(origin?: ZLinkFlowOrigin, createIfAbsent?: true): ZLinkFlowContextValue;
-export function currentOrCreateFlow(origin: ZLinkFlowOrigin, createIfAbsent: false): ZLinkFlowContextValue | undefined;
-export function currentOrCreateFlow(origin: ZLinkFlowOrigin, createIfAbsent: boolean): ZLinkFlowContextValue | undefined;
+export function currentOrCreateFlow(
+  origin?: ZLinkFlowOrigin,
+  createIfAbsent?: true
+): ZLinkFlowContextValue;
+export function currentOrCreateFlow(
+  origin: ZLinkFlowOrigin,
+  createIfAbsent: false
+): ZLinkFlowContextValue | undefined;
+export function currentOrCreateFlow(
+  origin: ZLinkFlowOrigin,
+  createIfAbsent: boolean
+): ZLinkFlowContextValue | undefined;
 /**
  * Returns the ambient flow context or, when absent and `createIfAbsent`, a
  * fresh flow value. The returned value is NOT installed into the ambient

package/src/runtime/diagnostics/index.ts

@@ -47,10 +47,7 @@ export {
   ZLinkLocationSpotEventKind,
   ZLinkSocketNativeEventType
 } from './internal-event-contracts';
-import type {
-  ZLinkBackendSocketMonitor,
-  ZLinkBackendSocketMonitorEvent
-} from '../backend';
+import type { ZLinkBackendSocketMonitor, ZLinkBackendSocketMonitorEvent } from '../backend';
 import { AsyncResource } from 'node:async_hooks';
 import { ZLinkStateLane } from '../execution/state-lane';
 import { normalizeOpaqueRoutingId } from '../routing-id';
@@ -66,15 +63,9 @@ export interface ZLinkActorOwnerLeaseObservation {
 }
 
 /** Emits high-cardinality resolver detail only on the existing relocation debug path. */
-export function emitActorOwnerLeaseObservation(
-  observation: ZLinkActorOwnerLeaseObservation
-): void {
+export function emitActorOwnerLeaseObservation(observation: ZLinkActorOwnerLeaseObservation): void {
   if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION !== '1') return;
-  console.error(
-    '[zlink.runtime.relocation]',
-    'actor_route.owner_lease_observed',
-    observation
-  );
+  console.error('[zlink.runtime.relocation]', 'actor_route.owner_lease_observed', observation);
 }
 
 /** Runtime composition port. It is intentionally absent from the public contract barrel. */
@@ -111,9 +102,8 @@ export class ZLinkSocketMonitoringSource {
     private readonly publisher: ZLinkRuntimeEventPublisher
   ) {
     validateSourceName(registration.sourceName);
-    this.enabledEvents = registration.events === undefined
-      ? undefined
-      : new Set(registration.events);
+    this.enabledEvents =
+      registration.events === undefined ? undefined : new Set(registration.events);
   }
 
   start(): void {
@@ -155,38 +145,38 @@ export class ZLinkLocationRuntimeMonitoringSource {
     let topology;
     let serviceSummary;
     try {
-      [status, topology, serviceSummary] = await startOutsideStateLane(() => Promise.all([
-        this.query.getStatus(signal),
-        this.query.listTopology({}, undefined, signal),
-        this.query.listServiceSummaries({}, undefined, signal)
-      ]));
+      [status, topology, serviceSummary] = await startOutsideStateLane(() =>
+        Promise.all([
+          this.query.getStatus(signal),
+          this.query.listTopology({}, undefined, signal),
+          this.query.listServiceSummaries({}, undefined, signal)
+        ])
+      );
     } catch (error) {
       if (await this.lane.run(() => this.markStoreFailureCore())) {
-        await startOutsideStateLane(() => this.publisher.publish({
-          sourceName: this.registration.sourceName,
-          timestamp: new Date(),
-          event: LocationRuntimeEventKind.StoreFailure
-        } satisfies ZLinkLocationRuntimeEvent));
+        await startOutsideStateLane(() =>
+          this.publisher.publish({
+            sourceName: this.registration.sourceName,
+            timestamp: new Date(),
+            event: LocationRuntimeEventKind.StoreFailure
+          } satisfies ZLinkLocationRuntimeEvent)
+        );
       }
       return;
     }
 
     if (await this.lane.run(() => this.markStoreRecoveredCore())) {
-      await startOutsideStateLane(() => this.publisher.publish({
-        sourceName: this.registration.sourceName,
-        timestamp: new Date(),
-        event: LocationRuntimeEventKind.StoreRecovered
-      } satisfies ZLinkLocationRuntimeEvent));
+      await startOutsideStateLane(() =>
+        this.publisher.publish({
+          sourceName: this.registration.sourceName,
+          timestamp: new Date(),
+          event: LocationRuntimeEventKind.StoreRecovered
+        } satisfies ZLinkLocationRuntimeEvent)
+      );
     }
 
-    await this.publishIfChanged(
-      LocationRuntimeEventKind.StatusChanged,
-      status
-    );
-    await this.publishIfChanged(
-      LocationRuntimeEventKind.TopologyChanged,
-      topology.items
-    );
+    await this.publishIfChanged(LocationRuntimeEventKind.StatusChanged, status);
+    await this.publishIfChanged(LocationRuntimeEventKind.TopologyChanged, topology.items);
     await this.publishIfChanged(
       LocationRuntimeEventKind.ServiceSummaryChanged,
       serviceSummary.items
@@ -205,16 +195,16 @@ export class ZLinkLocationRuntimeMonitoringSource {
     return true;
   }
 
-  private async publishIfChanged(event: ZLinkLocationRuntimeEventKind, snapshot: unknown): Promise<void> {
+  private async publishIfChanged(
+    event: ZLinkLocationRuntimeEventKind,
+    snapshot: unknown
+  ): Promise<void> {
     const current = stableSnapshot(snapshot);
     const previous = await this.lane.run(() => this.previousSnapshotCore(event));
     if (current === previous) return;
-    await startOutsideStateLane(() => publishLocationRuntimeChange(
-      this.publisher,
-      this.registration.sourceName,
-      event,
-      snapshot
-    ));
+    await startOutsideStateLane(() =>
+      publishLocationRuntimeChange(this.publisher, this.registration.sourceName, event, snapshot)
+    );
     await this.lane.run(() => this.updateSnapshotCore(event, current));
   }
 
@@ -258,7 +248,12 @@ export class ZLinkLocationMonitoringEventEmitter {
     },
     private readonly publisher?: ZLinkRuntimeEventPublisher
   ) {
-    for (const source of [registration.peer, registration.spot, registration.actor, registration.route]) {
+    for (const source of [
+      registration.peer,
+      registration.spot,
+      registration.actor,
+      registration.route
+    ]) {
       if (source !== undefined) {
         validateSourceName(source.sourceName);
       }
@@ -313,36 +308,68 @@ export class ZLinkLocationMonitoringEventEmitter {
     this.publishRoute(RouteLocationEventKind.ResolveMiss, { key });
   }
 
-  private publishPeer(event: ZLinkLocationPeerEvent['event'], payload: Record<string, unknown>): void {
+  private publishPeer(
+    event: ZLinkLocationPeerEvent['event'],
+    payload: Record<string, unknown>
+  ): void {
     const registration = this.registration.peer;
     if (registration === undefined) {
       return;
     }
-    this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload } as ZLinkLocationPeerEvent);
+    this.publish({
+      sourceName: registration.sourceName,
+      timestamp: new Date(),
+      event,
+      ...payload
+    } as ZLinkLocationPeerEvent);
   }
 
-  private publishSpotLocation(event: ZLinkLocationSpotEvent['event'], payload: Record<string, unknown>): void {
+  private publishSpotLocation(
+    event: ZLinkLocationSpotEvent['event'],
+    payload: Record<string, unknown>
+  ): void {
     const registration = this.registration.spot;
     if (registration === undefined) {
       return;
     }
-    this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload } as ZLinkLocationSpotEvent);
+    this.publish({
+      sourceName: registration.sourceName,
+      timestamp: new Date(),
+      event,
+      ...payload
+    } as ZLinkLocationSpotEvent);
   }
 
-  private publishActor(event: ZLinkLocationActorEvent['event'], payload: Record<string, unknown>): void {
+  private publishActor(
+    event: ZLinkLocationActorEvent['event'],
+    payload: Record<string, unknown>
+  ): void {
     const registration = this.registration.actor;
     if (registration === undefined) {
       return;
     }
-    this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload } as ZLinkLocationActorEvent);
+    this.publish({
+      sourceName: registration.sourceName,
+      timestamp: new Date(),
+      event,
+      ...payload
+    } as ZLinkLocationActorEvent);
   }
 
-  private publishRoute(event: ZLinkLocationRouteEvent['event'], payload: Record<string, unknown>): void {
+  private publishRoute(
+    event: ZLinkLocationRouteEvent['event'],
+    payload: Record<string, unknown>
+  ): void {
     const registration = this.registration.route;
     if (registration === undefined) {
       return;
     }
-    this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload } as ZLinkLocationRouteEvent);
+    this.publish({
+      sourceName: registration.sourceName,
+      timestamp: new Date(),
+      event,
+      ...payload
+    } as ZLinkLocationRouteEvent);
   }
 
   private publish<TEvent extends ZLinkRuntimeEvent>(event: TEvent): void {
@@ -357,7 +384,10 @@ export class ZLinkLocationMonitoringEventEmitter {
 
 export * from './topology-runtime-projections';
 
-function toSocketEvent(sourceName: string, raw: ZLinkBackendSocketMonitorEvent): ZLinkSocketEvent | undefined {
+function toSocketEvent(
+  sourceName: string,
+  raw: ZLinkBackendSocketMonitorEvent
+): ZLinkSocketEvent | undefined {
   const event = mapSocketEvent(raw.nativeEvent as ZLinkSocketNativeEventType, raw.value);
   if (event === undefined) {
     return undefined;
@@ -408,11 +438,16 @@ async function publishLocationRuntimeChange<T>(
   snapshot: T
 ): Promise<void> {
   const base = { sourceName, timestamp: new Date() };
-  const runtimeEvent: ZLinkLocationRuntimeEvent = event === LocationRuntimeEventKind.StatusChanged
-    ? { ...base, event, status: snapshot as ZLinkLocationRuntimeStatus }
-    : event === LocationRuntimeEventKind.TopologyChanged
-      ? { ...base, event, topology: snapshot as readonly ZLinkLocationTopologyEntry[] }
-      : { ...base, event: LocationRuntimeEventKind.ServiceSummaryChanged, serviceSummary: snapshot as readonly ZLinkLocationServiceSummary[] };
+  const runtimeEvent: ZLinkLocationRuntimeEvent =
+    event === LocationRuntimeEventKind.StatusChanged
+      ? { ...base, event, status: snapshot as ZLinkLocationRuntimeStatus }
+      : event === LocationRuntimeEventKind.TopologyChanged
+        ? { ...base, event, topology: snapshot as readonly ZLinkLocationTopologyEntry[] }
+        : {
+            ...base,
+            event: LocationRuntimeEventKind.ServiceSummaryChanged,
+            serviceSummary: snapshot as readonly ZLinkLocationServiceSummary[]
+          };
   await publisher.publish(runtimeEvent);
 }
 
@@ -421,7 +456,7 @@ function startOutsideStateLane<T>(work: () => T): T {
 }
 
 function stableSnapshot(value: unknown): string {
-  return JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? item.toString() : item);
+  return JSON.stringify(value, (_key, item) => (typeof item === 'bigint' ? item.toString() : item));
 }
 
 function validateSourceName(sourceName: string): void {