@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/channels/fanout-location-runtime.ts

@@ -6,23 +6,28 @@ import {
   type ZLinkFanoutPublisherDescriptor,
   type ZLinkLocationOwnerToken
 } from '../../contracts/Locations';
-import type { ZLinkFanoutLocationStore } from '../locations/internal-store-contracts';
 import {
   zlinkRuntimeDefaultLocationOptions,
   type ZLinkLocationOptionOverrides
 } from '../../contracts/Locations/Options';
-import type { ZLinkFrameworkRegistration } from '../configuration';
-import { buildAdvertisedEndpoint, ZLinkConfigurationException } from '../configuration';
-import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
+import { ZLINK_PROVIDER_MAX_PAGE_SIZE } from '../../contracts/Locations/Stores';
 import type { ZLinkBackendSubscriberSocket } from '../backend/contracts';
-import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
+import { type ZLinkFrameworkRegistration, ZLinkConfigurationException } from '../configuration';
+
 import { ZLinkStateLane } from '../execution/state-lane';
+import { discoveryAvailabilityForRuntimeState } from '../foundation/runtime-state-projections';
+import { closeResources, finishResourceCleanup } from '../foundation/event-loop-resources';
+import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
+import type { ZLinkFanoutLocationStore } from '../locations/internal-store-contracts';
+import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
 
-interface ActiveFanoutTarget {
+interface FanoutTarget {
   descriptor: ZLinkFanoutPublisherDescriptor;
+  connection?: ActiveFanoutConnection;
+}
+
+interface ActiveFanoutConnection {
   readonly connectionId: string;
-  readonly subscriber: ZLinkBackendSubscriberSocket;
-  reconnectEligible: boolean;
   stopReceiver: () => Promise<void>;
   state: 'connecting' | 'ready';
 }
@@ -39,7 +44,7 @@ export class ZLinkFanoutLocationRuntime {
       readonly lifecycleGeneration: bigint;
     }
   >();
-  private readonly connections = new Map<string, ActiveFanoutTarget>();
+  private readonly targets = new Map<string, FanoutTarget>();
   private controller?: AbortController;
   private timer?: NodeJS.Timeout;
 
@@ -95,18 +100,49 @@ export class ZLinkFanoutLocationRuntime {
       return current;
     });
     if (timer !== undefined) clearTimeout(timer);
-    const connectionIds = await this.lane.run(() => [...this.connections.keys()]);
-    await Promise.allSettled(connectionIds.map((id) => this.closeConnection(id)));
-    await this.removeLocalPublishers(signal);
+    const targets = await this.lane.run(() => [...this.targets]);
+    const targetResults = await Promise.allSettled(
+      targets.map(([id, target]) => this.removeTarget(id, target))
+    );
+    const publisherResults = await Promise.allSettled([this.removeLocalPublishers(signal)]);
+    finishResourceCleanup(
+      [...targetResults, ...publisherResults].flatMap((result) =>
+        result.status === 'rejected' ? [result.reason] : []
+      )
+    );
   }
 
   activeTargets(channelName: string): readonly ZLinkFanoutPublisherDescriptor[] {
-    return [...this.connections.values()]
-      .filter((target) => target.state === 'ready')
+    return [...this.targets.values()]
+      .filter((target) => target.connection?.state === 'ready')
       .map((target) => target.descriptor)
       .filter((descriptor) => descriptor.channelName === channelName);
   }
 
+  topologyTargets(channelName: string) {
+    if (!this.isAutomaticSubscriber(channelName)) return undefined;
+    return [...this.targets.values()]
+      .filter((target) => target.descriptor.channelName === channelName)
+      .map((target) => ({
+        channelName,
+        publisherRoutingId: String(target.descriptor.publisherRid),
+        lifecycleGeneration: target.descriptor.lifecycleGeneration,
+        descriptorRevision: target.descriptor.descriptorRevision,
+        advertisedEndpoint: target.descriptor.endpoint,
+        state:
+          target.descriptor.state === ZLinkFrameworkRuntimeState.Serving
+            ? target.connection?.state === 'ready'
+              ? ('serving' as const)
+              : ('preparing' as const)
+            : discoveryAvailabilityForRuntimeState(target.descriptor.state)
+      }));
+  }
+
+  private isAutomaticSubscriber(channelName: string): boolean {
+    const subscriber = this.registration.channels.get(channelName)?.subscriber;
+    return subscriber !== undefined && (subscriber.manualConnections?.length ?? 0) === 0;
+  }
+
   async reclaimOwnerRows(signal?: AbortSignal): Promise<void> {
     const owner = this.requireOwnerToken();
     const descriptors = await this.lane.run(() => [...this.localDescriptors]);
@@ -142,11 +178,9 @@ export class ZLinkFanoutLocationRuntime {
     const owner = this.requireOwnerToken();
     for (const [channelName, channel] of this.registration.channels) {
       if (channel.publisher === undefined) continue;
-      const publisher = this.sockets.publisher(channelName);
-      const endpoint = advertisedEndpoint(
-        publisher.lastEndpoint ?? channel.publisher.bind ?? '',
-        channel.publisher.advertiseHost
-      );
+      // Opening the publisher binds it and fixes its advertised endpoint.
+      this.sockets.publisher(channelName);
+      const endpoint = this.sockets.fanoutPublisherEndpoint(channelName) ?? '';
       if (endpoint.length === 0) {
         throw new ZLinkConfigurationException(
           `Fanout publisher '${channelName}' did not report a bound endpoint.`
@@ -217,74 +251,87 @@ export class ZLinkFanoutLocationRuntime {
   }
 
   private async reconcileSubscribers(signal?: AbortSignal): Promise<void> {
-    for (const [channelName, channel] of this.registration.channels) {
-      if (
-        channel.subscriber === undefined ||
-        (channel.subscriber.manualConnections?.length ?? 0) > 0
-      ) {
-        continue;
-      }
+    for (const channelName of this.registration.channels.keys()) {
+      if (!this.isAutomaticSubscriber(channelName)) continue;
+      const previous = this.topologyTargets(channelName)!;
       const rows = await this.listLivePublishers(channelName, signal);
       const desired = new Map(rows.map((row) => [fanoutConnectionId(row), row]));
       for (const [connectionId, descriptor] of desired) {
-        const current = await this.lane.run(() => this.connections.get(connectionId));
+        let current = await this.lane.run(() => this.targets.get(connectionId));
         if (current === undefined) {
-          await this.openConnection(connectionId, descriptor);
-          continue;
-        }
-        if (descriptor.descriptorRevision < current.descriptor.descriptorRevision) {
+          const created = { descriptor };
+          current = created;
+          await this.lane.run(() => this.targets.set(connectionId, created));
+        } else if (descriptor.descriptorRevision < current.descriptor.descriptorRevision) {
           continue;
-        }
-        if (descriptor.descriptorRevision === current.descriptor.descriptorRevision) {
+        } else if (descriptor.descriptorRevision === current.descriptor.descriptorRevision) {
           if (!sameFanoutDescriptor(descriptor, current.descriptor)) {
-            await this.closeConnection(connectionId);
+            await this.removeTarget(connectionId, current);
+            continue;
           }
+        } else if (!sameFanoutImmutableIdentity(descriptor, current.descriptor)) {
+          await this.removeTarget(connectionId, current);
           continue;
+        } else {
+          const target = current;
+          await this.lane.run(() => {
+            if (this.targets.get(connectionId) === target) target.descriptor = descriptor;
+          });
+          if (current.connection?.state === 'ready') {
+            this.sockets.admitFanoutPublisher(current.descriptor, connectionId);
+          }
         }
-        if (!sameFanoutImmutableIdentity(descriptor, current.descriptor)) {
-          await this.closeConnection(connectionId);
-          continue;
-        }
-        await this.lane.run(() => {
-          if (this.connections.get(connectionId) === current) current.descriptor = descriptor;
-        });
-        if (current.state === 'ready') {
-          this.sockets.admitFanoutPublisher(descriptor, connectionId);
-        }
+        await this.reconcileConnection(connectionId, current);
       }
-      const connections = await this.lane.run(() => [...this.connections]);
-      for (const [connectionId, current] of connections) {
+      const targets = await this.lane.run(() => [...this.targets]);
+      for (const [connectionId, current] of targets) {
         if (current.descriptor.channelName === channelName && !desired.has(connectionId)) {
-          await this.closeConnection(connectionId);
+          await this.removeTarget(connectionId, current);
         }
       }
+      const next = this.topologyTargets(channelName)!;
+      if (
+        previous.length !== next.length ||
+        previous.some(
+          (publisher, index) =>
+            publisher.publisherRoutingId !== next[index]!.publisherRoutingId ||
+            publisher.state !== next[index]!.state
+        )
+      ) {
+        this.sockets.notifyFanoutTopology(channelName);
+      }
     }
   }
 
-  private async openConnection(
-    connectionId: string,
-    descriptor: ZLinkFanoutPublisherDescriptor
-  ): Promise<void> {
-    let target: ActiveFanoutTarget | undefined;
+  private async reconcileConnection(connectionId: string, target: FanoutTarget): Promise<void> {
+    if (target.descriptor.state !== ZLinkFrameworkRuntimeState.Serving) {
+      await this.closeConnection(target);
+    } else if (target.connection === undefined) {
+      await this.openConnection(connectionId, target);
+    }
+  }
+
+  private async openConnection(connectionId: string, target: FanoutTarget): Promise<void> {
+    const descriptor = target.descriptor;
+    let connection: ActiveFanoutConnection | undefined;
     const subscriber = this.sockets.openFanoutSubscriberConnection(
       descriptor.channelName,
       connectionId,
       descriptor.endpoint,
       {
         onReady: () => {
-          const current = this.connections.get(connectionId);
-          if (target !== undefined && current === target) {
-            current.state = 'ready';
-            this.sockets.admitFanoutPublisher(descriptor, connectionId);
+          if (connection !== undefined && target.connection === connection) {
+            connection.state = 'ready';
+            this.sockets.admitFanoutPublisher(target.descriptor, connectionId);
           }
         },
         onTerminated: () => {
-          const current = this.connections.get(connectionId);
-          if (target !== undefined && current === target && current.reconnectEligible) {
-            this.sockets.removeFanoutPublisher(descriptor, connectionId);
-            current.state = 'connecting';
+          if (connection !== undefined && target.connection === connection) {
+            this.sockets.removeFanoutPublisher(target.descriptor, connectionId);
+            connection.state = 'connecting';
+            const terminated = connection;
             setImmediate(() => {
-              void this.replaceConnection(current).catch((error) =>
+              void this.replaceConnection(target, terminated).catch((error) =>
                 this.locationRuntime.reportDiscoveryFailure(error)
               );
             });
@@ -292,50 +339,76 @@ export class ZLinkFanoutLocationRuntime {
         }
       }
     );
-    target = {
-      descriptor,
+    connection = {
       connectionId,
-      subscriber,
-      reconnectEligible: true,
       stopReceiver: async () => {},
       state: 'connecting'
     };
-    await this.lane.run(() => this.connections.set(connectionId, target));
-    target.stopReceiver = this.onSubscriberOpened(descriptor.channelName, connectionId, subscriber);
+    const opened = connection;
+    await this.lane.run(() => (target.connection = opened));
+    connection.stopReceiver = this.onSubscriberOpened(
+      descriptor.channelName,
+      connectionId,
+      subscriber
+    );
   }
 
-  private async closeConnection(connectionId: string): Promise<void> {
-    const current = await this.lane.run(() => {
-      const target = this.connections.get(connectionId);
-      if (target !== undefined) {
-        target.reconnectEligible = false;
-        this.connections.delete(connectionId);
-      }
-      return target;
+  private async removeTarget(connectionId: string, target: FanoutTarget): Promise<void> {
+    const detached = await this.lane.run(() => {
+      if (this.targets.get(connectionId) !== target) return undefined;
+      this.targets.delete(connectionId);
+      return this.detachConnection(target);
     });
+    await this.closeDetachedConnection(target.descriptor, detached);
+  }
+
+  private async closeConnection(target: FanoutTarget): Promise<void> {
+    const detached = await this.lane.run(() => this.detachConnection(target));
+    await this.closeDetachedConnection(target.descriptor, detached);
+  }
+
+  private detachConnection(target: FanoutTarget): ActiveFanoutConnection | undefined {
+    const connection = target.connection;
+    target.connection = undefined;
+    return connection;
+  }
+
+  private async closeDetachedConnection(
+    descriptor: ZLinkFanoutPublisherDescriptor,
+    current: ActiveFanoutConnection | undefined
+  ): Promise<void> {
     if (current === undefined) return;
-    this.sockets.removeFanoutPublisher(current.descriptor, connectionId);
-    await current.stopReceiver();
-    await this.sockets.closeFanoutSubscriberConnection(connectionId);
+    this.sockets.removeFanoutPublisher(descriptor, current.connectionId);
+    await closeResources([
+      { close: () => current.stopReceiver() },
+      { close: () => this.sockets.closeFanoutSubscriberConnection(current.connectionId) }
+    ]);
   }
 
-  private async replaceConnection(expected: ActiveFanoutTarget): Promise<void> {
+  private async replaceConnection(
+    target: FanoutTarget,
+    expected: ActiveFanoutConnection
+  ): Promise<void> {
     const prepared = await this.lane.run(() => {
       const controller = this.controller;
       if (
-        this.connections.get(expected.connectionId) !== expected ||
-        !expected.reconnectEligible ||
+        this.targets.get(expected.connectionId) !== target ||
+        target.connection !== expected ||
         controller === undefined
       )
         return undefined;
-      return { controller, descriptor: expected.descriptor };
+      return controller;
     });
     if (prepared === undefined) {
       return;
     }
-    await this.closeConnection(expected.connectionId);
-    if (await this.lane.run(() => this.controller === prepared.controller)) {
-      await this.openConnection(expected.connectionId, prepared.descriptor);
+    await this.closeConnection(target);
+    if (
+      await this.lane.run(
+        () => this.controller === prepared && this.targets.get(expected.connectionId) === target
+      )
+    ) {
+      await this.reconcileConnection(expected.connectionId, target);
     }
   }
 
@@ -348,7 +421,7 @@ export class ZLinkFanoutLocationRuntime {
     do {
       const page = await this.store.listFanoutPublishers(
         channelName,
-        { pageSize: 1000, continuationToken },
+        { pageSize: ZLINK_PROVIDER_MAX_PAGE_SIZE, continuationToken },
         signal
       );
       rows.push(...page.items);
@@ -356,7 +429,6 @@ export class ZLinkFanoutLocationRuntime {
     } while (continuationToken !== undefined);
     const live: ZLinkFanoutPublisherDescriptor[] = [];
     for (const descriptor of rows) {
-      if (descriptor.state !== ZLinkFrameworkRuntimeState.Serving) continue;
       const lease = await this.storeOwnerLease(descriptor.ownerId, signal);
       if (
         lease.kind === 'found' &&
@@ -377,17 +449,24 @@ export class ZLinkFanoutLocationRuntime {
     const owner = this.locationRuntime.currentOwnerToken;
     if (owner === undefined) return;
     const descriptors = await this.lane.run(() => [...this.localDescriptors.values()]);
-    for (const descriptor of descriptors) {
-      await this.store.removeFanoutPublisher(
-        {
-          channelName: descriptor.channelName,
-          publisherRid: descriptor.publisherRid
-        },
-        owner,
-        signal
+    try {
+      await closeResources(
+        descriptors.map((descriptor) => ({
+          close: async () => {
+            await this.store.removeFanoutPublisher(
+              {
+                channelName: descriptor.channelName,
+                publisherRid: descriptor.publisherRid
+              },
+              owner,
+              signal
+            );
+          }
+        }))
       );
+    } finally {
+      await this.lane.run(() => this.localDescriptors.clear());
     }
-    await this.lane.run(() => this.localDescriptors.clear());
   }
 
   private requireOwnerToken(): ZLinkLocationOwnerToken {
@@ -412,16 +491,6 @@ export class ZLinkFanoutLocationRuntime {
   }
 }
 
-function advertisedEndpoint(boundEndpoint: string, advertiseHost: string | undefined): string {
-  const result = buildAdvertisedEndpoint(boundEndpoint, advertiseHost);
-  if (result === undefined) {
-    throw new ZLinkConfigurationException(
-      `Fanout publisher bound endpoint '${boundEndpoint}' cannot be advertised.`
-    );
-  }
-  return result;
-}
-
 function fanoutConnectionId(descriptor: ZLinkFanoutPublisherDescriptor): string {
   return (
     `${descriptor.channelName}\0${String(descriptor.publisherRid)}\0` +

package/src/runtime/channels/spot-direct-envelope.ts

@@ -3,7 +3,7 @@ import type { ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-
 import { ZLinkConfigurationException } from '../configuration';
 import { ZLinkChannelMessageKind } from './channel-envelope';
 
-const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
+export const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
 
 export function encodeSpotDirectEnvelope(
   kind: ZLinkChannelMessageKind.Request | ZLinkChannelMessageKind.Command,

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

@@ -1,3 +1,4 @@
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkFrameworkRegistration } from '../configuration';
 import { awaitWithAbort, throwIfAborted } from '../abort';
@@ -44,7 +45,8 @@ export class ZLinkSpotNodeRouteTransport {
     if (router === undefined) {
       return undefined;
     }
-    const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+    const effectiveTimeoutMs =
+      timeoutMs ?? this.registration.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     throwIfAborted(signal);
     const operation = router.requestToSpot(
       target.targetNodeRid,
@@ -74,7 +76,8 @@ export class ZLinkSpotNodeRouteTransport {
     if (router === undefined) {
       return undefined;
     }
-    const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+    const effectiveTimeoutMs =
+      timeoutMs ?? this.registration.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     throwIfAborted(signal);
     const operation = router.requestToSpot(
       target.targetNodeRid,

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);
 }