@zlink-systems/framework 0.26.0 → 0.28.0

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

@@ -32,8 +32,6 @@ export interface ZLinkLocalSpotRouteDispatcher {
     message: unknown,
     context: {
       readonly channelName: string;
-      readonly admissionTimeoutMs?: number;
-      readonly signal?: AbortSignal;
       readonly metadata?: ReadonlyMap<string, string>;
     }
   ): Promise<void>;
@@ -101,14 +99,12 @@ export class ZLinkSpotRouteDispatchStrategy {
     spotRouteTarget: ZLinkSpotRouteTarget,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    timeoutMs?: number
+    metadata?: ReadonlyMap<string, string>
   ): 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)
+      this.routeSendToSpotScoped(spotRouteTarget, packetName, message, metadata)
     );
   }
 
@@ -116,11 +112,8 @@ export class ZLinkSpotRouteDispatchStrategy {
     spotRouteTarget: ZLinkSpotRouteTarget,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    timeoutMs?: number
+    metadata?: ReadonlyMap<string, string>
   ): Promise<void> {
-    throwIfAborted(signal);
     const localSpotRouteNode = this.targets.localRouteNode(spotRouteTarget);
     if (localSpotRouteNode !== undefined) {
       await this.localTransport.send(
@@ -128,9 +121,7 @@ export class ZLinkSpotRouteDispatchStrategy {
         spotRouteTarget.spotId,
         packetName,
         message,
-        signal,
-        metadata,
-        timeoutMs
+        metadata
       );
       return;
     }
@@ -148,22 +139,22 @@ export class ZLinkSpotRouteDispatchStrategy {
     ) as readonly Message[];
     if (
       this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId) &&
-      (await this.spotNodeTransport.send(spotRouteTarget, parts, signal))
+      (await this.spotNodeTransport.send(spotRouteTarget, parts))
     ) {
       return;
     }
     if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
-      await this.bridgeTransport.send(spotRouteTarget, parts, signal);
+      await this.bridgeTransport.send(spotRouteTarget, parts);
       return;
     }
     if (this.targets.hasBoundRouteRouter(spotRouteTarget.routerChannelId)) {
-      await this.routerSocketTransport.send(spotRouteTarget, parts, ZLINK_SEND_DONT_WAIT, signal);
+      await this.routerSocketTransport.send(spotRouteTarget, parts, ZLINK_SEND_DONT_WAIT);
       return;
     }
-    if (await this.spotNodeTransport.send(spotRouteTarget, parts, signal)) {
+    if (await this.spotNodeTransport.send(spotRouteTarget, parts)) {
       return;
     }
-    await this.routerSocketTransport.send(spotRouteTarget, parts, ZLINK_SEND_DONT_WAIT, signal);
+    await this.routerSocketTransport.send(spotRouteTarget, parts, ZLINK_SEND_DONT_WAIT);
   }
 
   routeRequestToSpot<TReply>(
@@ -291,19 +282,9 @@ export class ZLinkSpotRouteDispatchStrategy {
     spotRouteTarget: ZLinkSpotRouteTarget,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    timeoutMs?: number
+    metadata?: ReadonlyMap<string, string>
   ): Promise<void> {
-    await this.sourceSpotRouter.send(
-      sourceSpot,
-      spotRouteTarget,
-      packetName,
-      message,
-      signal,
-      metadata,
-      timeoutMs
-    );
+    await this.sourceSpotRouter.send(sourceSpot, spotRouteTarget, packetName, message, metadata);
   }
 
   routeRequestRawFromSpotToSpot(

package/src/runtime/diagnostics/diagnostic-text.ts

@@ -0,0 +1,4 @@
+/** Formats absent diagnostic text consistently across the Node runtime. */
+export function diagnosticTextOrAbsent(value: string | null | undefined): string {
+  return value ?? '<none>';
+}

package/src/runtime/diagnostics/dispatch-error-details.ts

@@ -1,4 +1,39 @@
-const ERROR_MESSAGE_MAX_LENGTH = 512;
+import {
+  ZLinkFrameworkErrorKind,
+  ZLinkFrameworkException
+} from '../../contracts/Errors/ZLinkFrameworkException';
+import { ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import {
+  internalFrameworkErrorKind,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
+
+export function dispatchReasonFromError(error: unknown): ZLinkDispatchErrorReason {
+  if (!(error instanceof ZLinkFrameworkException)) return ZLinkDispatchErrorReason.HandlerException;
+  const origin = internalFrameworkErrorKind(error);
+  if (origin === ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed)
+    return ZLinkDispatchErrorReason.PayloadDecodeFailed;
+  if (
+    origin === ZLinkFrameworkInternalErrorKind.SpotGenerationStale ||
+    origin === ZLinkFrameworkInternalErrorKind.ActorGenerationStale ||
+    origin === ZLinkFrameworkInternalErrorKind.SpotMoving ||
+    origin === ZLinkFrameworkInternalErrorKind.ActorMoving ||
+    origin === ZLinkFrameworkInternalErrorKind.ActorLocationStale
+  )
+    return ZLinkDispatchErrorReason.StaleTarget;
+  switch (error.kind) {
+    case ZLinkFrameworkErrorKind.NotFound:
+      return ZLinkDispatchErrorReason.HandlerMissing;
+    case ZLinkFrameworkErrorKind.ProtocolError:
+      return ZLinkDispatchErrorReason.InvalidFrame;
+    case ZLinkFrameworkErrorKind.ShuttingDown:
+      return ZLinkDispatchErrorReason.Shutdown;
+    default:
+      return ZLinkDispatchErrorReason.HandlerException;
+  }
+}
+
+export const ERROR_MESSAGE_MAX_LENGTH = 512;
 
 const CREDENTIAL_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
   [/Authorization\s*:\s*(?:(?:Bearer|Basic)\s+)?[^\s,;]+/gi, 'Authorization: <redacted>'],

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

@@ -1,6 +1,20 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomBytes } from 'node:crypto';
 import type { ZLinkFlowOrigin } from '../../contracts';
+const FLOW_UUID_BYTES = 16;
+const FLOW_UUID_VARIANT_BYTE = 8;
+
+/**
+ * Spec 27 §3 defines the flow_origin value set as lowercase
+ * (`inbound|timer|application|lifecycle`); every language emits these exact
+ * strings so records remain comparable across runtimes (spec 26 §3.1).
+ */
+export const FLOW_ORIGIN_VALUES: Readonly<Record<ZLinkFlowOrigin, string>> = Object.freeze({
+  Inbound: 'inbound',
+  Timer: 'timer',
+  Application: 'application',
+  Lifecycle: 'lifecycle'
+});
 
 export interface ZLinkFlowContextValue {
   readonly flowId: string;
@@ -84,12 +98,12 @@ export function createInboundFlow(
 }
 
 function createFlowId(): string {
-  const bytes = randomBytes(16);
+  const bytes = randomBytes(FLOW_UUID_BYTES);
   // Date.now() is always within 48 bits, which is exactly the UUIDv7
   // timestamp field.
   bytes.writeUIntBE(Date.now(), 0, 6);
   bytes[6] = 0x70 | (bytes[6] & 0x0f);
-  bytes[8] = 0x80 | (bytes[8] & 0x3f);
+  bytes[FLOW_UUID_VARIANT_BYTE] = 0x80 | (bytes[FLOW_UUID_VARIANT_BYTE] & 0x3f);
   const hex = bytes.toString('hex');
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }

package/src/runtime/diagnostics/index.ts

@@ -1,37 +1,41 @@
+import { AsyncResource } from 'node:async_hooks';
 import type {
   ZLinkLocationRuntimeQuery,
   ZLinkLocationRuntimeStatus,
-  ZLinkLocationTopologyEntry,
-  ZLinkLocationServiceSummary
+  ZLinkLocationServiceSummary,
+  ZLinkLocationTopologyEntry
 } from '../../contracts';
-import type {
-  ZLinkActorLocation,
-  ZLinkPeerLocation,
-  ZLinkRouteLocation,
-  ZLinkSpotLocation
-} from '../../contracts/Locations/Rows';
 import type {
   ZLinkActorLocationKey,
   ZLinkLocationKey,
   ZLinkRouteLocationKey,
   ZLinkSpotLocationKey
 } from '../../contracts/Locations/Keys';
+import type {
+  ZLinkActorLocation,
+  ZLinkPeerLocation,
+  ZLinkRouteLocation,
+  ZLinkSpotLocation
+} from '../../contracts/Locations/Rows';
+import type { ZLinkBackendSocketMonitor, ZLinkBackendSocketMonitorEvent } from '../backend';
+import { ZLinkStateLane } from '../execution/state-lane';
+import { normalizeOpaqueRoutingId } from '../routing-id';
 import {
-  ZLinkLocationRuntimeEventKind as LocationRuntimeEventKind,
   ZLinkLocationActorEventKind as ActorLocationEventKind,
+  ZLinkLocationRuntimeEventKind as LocationRuntimeEventKind,
   ZLinkLocationPeerEventKind as PeerLocationEventKind,
   ZLinkLocationRouteEventKind as RouteLocationEventKind,
-  ZLinkLocationSpotEventKind as SpotLocationEventKind,
   ZLinkSocketEventKind as SocketEventKind,
-  ZLinkSocketNativeEventType,
   ZLinkSocketNativeEventType as SocketNativeEventType,
+  ZLinkLocationSpotEventKind as SpotLocationEventKind,
+  ZLinkSocketNativeEventType,
   type ZLinkAutoConnectDesiredSetChange,
   type ZLinkLocationActorEvent,
   type ZLinkLocationMonitoringRegistration,
   type ZLinkLocationPeerEvent,
+  type ZLinkLocationRouteEvent,
   type ZLinkLocationRuntimeEvent,
   type ZLinkLocationRuntimeEventKind,
-  type ZLinkLocationRouteEvent,
   type ZLinkLocationSpotEvent,
   type ZLinkPollingMonitoringRegistration,
   type ZLinkRuntimeEvent,
@@ -40,6 +44,7 @@ import {
   type ZLinkSocketEventKind,
   type ZLinkSocketMonitoringRegistration
 } from './internal-event-contracts';
+
 export {
   ZLinkLocationActorEventKind,
   ZLinkLocationPeerEventKind,
@@ -47,10 +52,6 @@ export {
   ZLinkLocationSpotEventKind,
   ZLinkSocketNativeEventType
 } from './internal-event-contracts';
-import type { ZLinkBackendSocketMonitor, ZLinkBackendSocketMonitorEvent } from '../backend';
-import { AsyncResource } from 'node:async_hooks';
-import { ZLinkStateLane } from '../execution/state-lane';
-import { normalizeOpaqueRoutingId } from '../routing-id';
 
 const ZLINK_DISCONNECT_REASON_HANDSHAKE_FAILED = 3;
 const detachedStateLaneResource = new AsyncResource('zlink:location-runtime-monitoring-source');
@@ -62,9 +63,18 @@ export interface ZLinkActorOwnerLeaseObservation {
   readonly decision: 'owner_unavailable';
 }
 
+export function isRelocationDebugEnabled(): boolean {
+  return process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION === '1';
+}
+
+export function relocationDebug(marker: string, detail: Record<string, unknown>): void {
+  if (!isRelocationDebugEnabled()) return;
+  console.error('[zlink.runtime.relocation]', marker, detail);
+}
+
 /** Emits high-cardinality resolver detail only on the existing relocation debug path. */
 export function emitActorOwnerLeaseObservation(observation: ZLinkActorOwnerLeaseObservation): void {
-  if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION !== '1') return;
+  if (!isRelocationDebugEnabled()) return;
   console.error('[zlink.runtime.relocation]', 'actor_route.owner_lease_observed', observation);
 }
 

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

@@ -1,4 +1,4 @@
-import { SpanStatusCode, trace as openTelemetryTrace, type Attributes } from '@opentelemetry/api';
+import { trace as openTelemetryTrace, SpanStatusCode, type Attributes } from '@opentelemetry/api';
 import { logs as openTelemetryLogs, SeverityNumber } from '@opentelemetry/api-logs';
 import {
   MESSAGE_FLOW_MODE_RANK,
@@ -10,11 +10,14 @@ import {
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind,
   ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
-  type ZLinkRuntimeMessageFlowResult,
-  type ZLinkRuntimeMessageFlowEvent
+  type ZLinkRuntimeMessageFlowEvent,
+  type ZLinkRuntimeMessageFlowResult
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import { ERROR_MESSAGE_MAX_LENGTH } from './dispatch-error-details';
 import type { ZLinkDispatchErrorSink } from './dispatch-error-port';
-import { currentFlowContext } from './flow-context';
+import { currentFlowContext, FLOW_ORIGIN_VALUES } from './flow-context';
+const MESSAGE_FLOW_EVENT_ID = 'zlink.message_flow';
+const DISPATCH_ERROR_EVENT_ID = 'zlink.dispatch_error';
 
 export interface ZLinkMessageFlowModeCell {
   mode: ZLinkMessageFlowLogMode;
@@ -34,11 +37,11 @@ export const DEFAULT_ZLINK_DIAGNOSTICS: ZLinkDiagnosticsOptions = {
 
 const telemetryLogger = openTelemetryLogs.getLogger('@zlink-systems/framework');
 const telemetryTracer = openTelemetryTrace.getTracer('@zlink-systems/framework');
-const ERROR_MESSAGE_MAX_LENGTH = 512;
+
 let diagnosticsGeneration = 0n;
 
 interface ZLinkTelemetryRecord {
-  readonly eventId: 'zlink.message_flow' | 'zlink.dispatch_error';
+  readonly eventId: typeof MESSAGE_FLOW_EVENT_ID | typeof DISPATCH_ERROR_EVENT_ID;
   readonly timestamp: Date;
   readonly phase?: string;
   readonly outcome: ZLinkRuntimeMessageFlowResult;
@@ -300,12 +303,12 @@ export class ZLinkMessageFlowTracer {
   private publishToLogger(record: ZLinkTelemetryRecord): void {
     try {
       const severityNumber =
-        record.eventId === 'zlink.dispatch_error' ? SeverityNumber.ERROR : SeverityNumber.INFO;
+        record.eventId === DISPATCH_ERROR_EVENT_ID ? SeverityNumber.ERROR : SeverityNumber.INFO;
       telemetryLogger.emit({
         eventName: record.eventId,
         timestamp: record.timestamp,
         severityNumber,
-        severityText: record.eventId === 'zlink.dispatch_error' ? 'ERROR' : 'INFO',
+        severityText: record.eventId === DISPATCH_ERROR_EVENT_ID ? 'ERROR' : 'INFO',
         body: structuredLogBody(record),
         attributes: structuredLogAttributes(record)
       });
@@ -319,7 +322,7 @@ export class ZLinkMessageFlowTracer {
       const span = telemetryTracer.startSpan(record.eventId, {
         attributes: traceAttributes(record)
       });
-      if (record.eventId === 'zlink.dispatch_error') {
+      if (record.eventId === DISPATCH_ERROR_EVENT_ID) {
         span.setStatus({ code: SpanStatusCode.ERROR, message: record.reason });
       }
       span.end();
@@ -338,18 +341,6 @@ export class ZLinkMessageFlowTracer {
   }
 }
 
-/**
- * Spec 27 §3 defines the flow_origin value set as lowercase
- * (`inbound|timer|application|lifecycle`); every language emits these exact
- * strings so records remain comparable across runtimes (spec 26 §3.1).
- */
-const FLOW_ORIGIN_TELEMETRY_VALUES: Record<ZLinkFlowOrigin, string> = {
-  Inbound: 'inbound',
-  Timer: 'timer',
-  Application: 'application',
-  Lifecycle: 'lifecycle'
-};
-
 function toTelemetryRecord(
   flow: ZLinkRuntimeMessageFlowEvent,
   messageSizeBytes: number | undefined,
@@ -358,8 +349,8 @@ function toTelemetryRecord(
   return {
     eventId:
       flow.outcome === ZLinkMessageFlowOutcome.Error
-        ? 'zlink.dispatch_error'
-        : 'zlink.message_flow',
+        ? DISPATCH_ERROR_EVENT_ID
+        : MESSAGE_FLOW_EVENT_ID,
     timestamp: new Date(),
     phase: messageFlowPhase(flow.outcome),
     outcome: flow.result ?? messageFlowOutcome(flow.outcome),
@@ -377,8 +368,7 @@ function toTelemetryRecord(
     targetRid: flow.targetRid,
     serverRid: flow.serverRid,
     flowId: flow.flowId,
-    flowOrigin:
-      flow.flowOrigin === undefined ? undefined : FLOW_ORIGIN_TELEMETRY_VALUES[flow.flowOrigin],
+    flowOrigin: flow.flowOrigin === undefined ? undefined : FLOW_ORIGIN_VALUES[flow.flowOrigin],
     spotId: flow.spotId,
     instanceSpotType: flow.instanceSpotType,
     activationState: flow.activationState,