@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/channels/fanout-location-runtime.js

@@ -4,8 +4,11 @@ exports.ZLinkFanoutLocationRuntime = void 0;
 const node_crypto_1 = require("node:crypto");
 const Locations_1 = require("../../contracts/Locations");
 const Options_1 = require("../../contracts/Locations/Options");
+const Stores_1 = require("../../contracts/Locations/Stores");
 const configuration_1 = require("../configuration");
 const state_lane_1 = require("../execution/state-lane");
+const runtime_state_projections_1 = require("../foundation/runtime-state-projections");
+const event_loop_resources_1 = require("../foundation/event-loop-resources");
 class ZLinkFanoutLocationRuntime {
     registration;
     sockets;
@@ -17,7 +20,7 @@ class ZLinkFanoutLocationRuntime {
     store;
     localDescriptors = new Map();
     publisherIdentities = new Map();
-    connections = new Map();
+    targets = new Map();
     controller;
     timer;
     constructor(registration, sockets, locationRuntime, stores, options, onSubscriberOpened) {
@@ -64,16 +67,39 @@ class ZLinkFanoutLocationRuntime {
         });
         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)]);
+        (0, event_loop_resources_1.finishResourceCleanup)([...targetResults, ...publisherResults].flatMap((result) => result.status === 'rejected' ? [result.reason] : []));
     }
     activeTargets(channelName) {
-        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) {
+        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 === Locations_1.ZLinkFrameworkRuntimeState.Serving
+                ? target.connection?.state === 'ready'
+                    ? 'serving'
+                    : 'preparing'
+                : (0, runtime_state_projections_1.discoveryAvailabilityForRuntimeState)(target.descriptor.state)
+        }));
+    }
+    isAutomaticSubscriber(channelName) {
+        const subscriber = this.registration.channels.get(channelName)?.subscriber;
+        return subscriber !== undefined && (subscriber.manualConnections?.length ?? 0) === 0;
+    }
     async reclaimOwnerRows(signal) {
         const owner = this.requireOwnerToken();
         const descriptors = await this.lane.run(() => [...this.localDescriptors]);
@@ -101,8 +127,9 @@ class ZLinkFanoutLocationRuntime {
         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 configuration_1.ZLinkConfigurationException(`Fanout publisher '${channelName}' did not report a bound endpoint.`);
             }
@@ -153,124 +180,150 @@ class ZLinkFanoutLocationRuntime {
         }
     }
     async reconcileSubscribers(signal) {
-        for (const [channelName, channel] of this.registration.channels) {
-            if (channel.subscriber === undefined ||
-                (channel.subscriber.manualConnections?.length ?? 0) > 0) {
+        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;
+                    const created = { descriptor };
+                    current = created;
+                    await this.lane.run(() => this.targets.set(connectionId, created));
                 }
-                if (descriptor.descriptorRevision < current.descriptor.descriptorRevision) {
+                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;
                     }
-                    continue;
                 }
-                if (!sameFanoutImmutableIdentity(descriptor, current.descriptor)) {
-                    await this.closeConnection(connectionId);
+                else if (!sameFanoutImmutableIdentity(descriptor, current.descriptor)) {
+                    await this.removeTarget(connectionId, current);
                     continue;
                 }
-                await this.lane.run(() => {
-                    if (this.connections.get(connectionId) === current)
-                        current.descriptor = descriptor;
-                });
-                if (current.state === 'ready') {
-                    this.sockets.admitFanoutPublisher(descriptor, connectionId);
+                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);
+                    }
                 }
+                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);
+            }
+        }
+    }
+    async reconcileConnection(connectionId, target) {
+        if (target.descriptor.state !== Locations_1.ZLinkFrameworkRuntimeState.Serving) {
+            await this.closeConnection(target);
+        }
+        else if (target.connection === undefined) {
+            await this.openConnection(connectionId, target);
         }
     }
-    async openConnection(connectionId, descriptor) {
-        let target;
+    async openConnection(connectionId, target) {
+        const descriptor = target.descriptor;
+        let connection;
         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) => this.locationRuntime.reportDiscoveryFailure(error));
+                        void this.replaceConnection(target, terminated).catch((error) => this.locationRuntime.reportDiscoveryFailure(error));
                     });
                 }
             }
         });
-        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);
     }
-    async closeConnection(connectionId) {
-        const current = await this.lane.run(() => {
-            const target = this.connections.get(connectionId);
-            if (target !== undefined) {
-                target.reconnectEligible = false;
-                this.connections.delete(connectionId);
-            }
-            return target;
+    async removeTarget(connectionId, target) {
+        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);
+    }
+    async closeConnection(target) {
+        const detached = await this.lane.run(() => this.detachConnection(target));
+        await this.closeDetachedConnection(target.descriptor, detached);
+    }
+    detachConnection(target) {
+        const connection = target.connection;
+        target.connection = undefined;
+        return connection;
+    }
+    async closeDetachedConnection(descriptor, current) {
         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 (0, event_loop_resources_1.closeResources)([
+            { close: () => current.stopReceiver() },
+            { close: () => this.sockets.closeFanoutSubscriberConnection(current.connectionId) }
+        ]);
     }
-    async replaceConnection(expected) {
+    async replaceConnection(target, expected) {
         const prepared = await this.lane.run(() => {
             const controller = this.controller;
-            if (this.connections.get(expected.connectionId) !== expected ||
-                !expected.reconnectEligible ||
+            if (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);
         }
     }
     async listLivePublishers(channelName, signal) {
         const rows = [];
         let continuationToken;
         do {
-            const page = await this.store.listFanoutPublishers(channelName, { pageSize: 1000, continuationToken }, signal);
+            const page = await this.store.listFanoutPublishers(channelName, { pageSize: Stores_1.ZLINK_PROVIDER_MAX_PAGE_SIZE, continuationToken }, signal);
             rows.push(...page.items);
             continuationToken = page.continuationToken;
         } while (continuationToken !== undefined);
         const live = [];
         for (const descriptor of rows) {
-            if (descriptor.state !== Locations_1.ZLinkFrameworkRuntimeState.Serving)
-                continue;
             const lease = await this.storeOwnerLease(descriptor.ownerId, signal);
             if (lease.kind === 'found' &&
                 lease.token.leaseGeneration === descriptor.leaseGeneration &&
@@ -288,13 +341,19 @@ class ZLinkFanoutLocationRuntime {
         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 (0, event_loop_resources_1.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());
     }
     requireOwnerToken() {
         const token = this.locationRuntime.currentOwnerToken;
@@ -316,13 +375,6 @@ class ZLinkFanoutLocationRuntime {
     }
 }
 exports.ZLinkFanoutLocationRuntime = ZLinkFanoutLocationRuntime;
-function advertisedEndpoint(boundEndpoint, advertiseHost) {
-    const result = (0, configuration_1.buildAdvertisedEndpoint)(boundEndpoint, advertiseHost);
-    if (result === undefined) {
-        throw new configuration_1.ZLinkConfigurationException(`Fanout publisher bound endpoint '${boundEndpoint}' cannot be advertised.`);
-    }
-    return result;
-}
 function fanoutConnectionId(descriptor) {
     return (`${descriptor.channelName}\0${String(descriptor.publisherRid)}\0` +
         descriptor.lifecycleGeneration.toString());

package/dist/runtime/channels/spot-direct-envelope.d.ts

@@ -1,5 +1,6 @@
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
 import { ZLinkChannelMessageKind } from './channel-envelope';
+export declare const SPOT_DIRECT_ENVELOPE = "zlink.framework.spot-direct.v1";
 export declare function encodeSpotDirectEnvelope(kind: ZLinkChannelMessageKind.Request | ZLinkChannelMessageKind.Command, channelName: string, packetName: string | undefined, payload: unknown, metadata?: ReadonlyMap<string, string>): MessageLike;
 export declare function decodeSpotDirectReply<TReply>(parts: readonly Message[]): TReply;

package/dist/runtime/channels/spot-direct-envelope.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPOT_DIRECT_ENVELOPE = void 0;
 exports.encodeSpotDirectEnvelope = encodeSpotDirectEnvelope;
 exports.decodeSpotDirectReply = decodeSpotDirectReply;
 const configuration_1 = require("../configuration");
-const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
+exports.SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
 function encodeSpotDirectEnvelope(kind, channelName, packetName, payload, metadata) {
     return Buffer.from(JSON.stringify({
-        marker: SPOT_DIRECT_ENVELOPE,
+        marker: exports.SPOT_DIRECT_ENVELOPE,
         kind,
         channelName,
         packetName,
@@ -19,7 +20,7 @@ function decodeSpotDirectReply(parts) {
         throw new configuration_1.ZLinkConfigurationException('Spot direct reply is missing.');
     }
     const reply = JSON.parse(parts[0].data().toString());
-    if (reply.marker !== SPOT_DIRECT_ENVELOPE) {
+    if (reply.marker !== exports.SPOT_DIRECT_ENVELOPE) {
         throw new configuration_1.ZLinkConfigurationException('Spot direct reply marker is invalid.');
     }
     if (reply.ok !== true) {

package/dist/runtime/channels/spot-node-route-transport.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotNodeRouteTransport = void 0;
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const abort_1 = require("../abort");
 const channel_envelope_1 = require("./channel-envelope");
 class ZLinkSpotNodeRouteTransport {
@@ -29,7 +30,7 @@ class ZLinkSpotNodeRouteTransport {
         if (router === undefined) {
             return undefined;
         }
-        const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+        const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS;
         (0, abort_1.throwIfAborted)(signal);
         const operation = router.requestToSpot(target.targetNodeRid, target.spotId, parts, effectiveTimeoutMs);
         return (0, abort_1.awaitWithAbort)(operation, signal, () => {
@@ -49,7 +50,7 @@ class ZLinkSpotNodeRouteTransport {
         if (router === undefined) {
             return undefined;
         }
-        const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+        const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS;
         (0, abort_1.throwIfAborted)(signal);
         const operation = router.requestToSpot(target.targetNodeRid, target.spotId, request, effectiveTimeoutMs);
         return (0, abort_1.awaitWithAbort)(operation, signal, () => {

package/dist/runtime/diagnostics/diagnostic-text.d.ts

@@ -0,0 +1,2 @@
+/** Formats absent diagnostic text consistently across the Node runtime. */
+export declare function diagnosticTextOrAbsent(value: string | null | undefined): string;

package/dist/runtime/diagnostics/diagnostic-text.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diagnosticTextOrAbsent = diagnosticTextOrAbsent;
+/** Formats absent diagnostic text consistently across the Node runtime. */
+function diagnosticTextOrAbsent(value) {
+    return value ?? '<none>';
+}

package/dist/runtime/diagnostics/dispatch-error-details.d.ts

@@ -1,3 +1,6 @@
+import { ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+export declare function dispatchReasonFromError(error: unknown): ZLinkDispatchErrorReason;
+export declare const ERROR_MESSAGE_MAX_LENGTH = 512;
 export declare function dispatchErrorDetails(error: unknown): {
     readonly errorType?: string;
     readonly errorMessage?: string;

package/dist/runtime/diagnostics/dispatch-error-details.js

@@ -1,7 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_MESSAGE_MAX_LENGTH = void 0;
+exports.dispatchReasonFromError = dispatchReasonFromError;
 exports.dispatchErrorDetails = dispatchErrorDetails;
-const ERROR_MESSAGE_MAX_LENGTH = 512;
+const ZLinkFrameworkException_1 = require("../../contracts/Errors/ZLinkFrameworkException");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+function dispatchReasonFromError(error) {
+    if (!(error instanceof ZLinkFrameworkException_1.ZLinkFrameworkException))
+        return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException;
+    const origin = (0, framework_errors_internal_1.internalFrameworkErrorKind)(error);
+    if (origin === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed)
+        return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.PayloadDecodeFailed;
+    if (origin === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale ||
+        origin === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorGenerationStale ||
+        origin === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving ||
+        origin === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving ||
+        origin === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale)
+        return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget;
+    switch (error.kind) {
+        case ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.NotFound:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing;
+        case ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ProtocolError:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame;
+        case ZLinkFrameworkException_1.ZLinkFrameworkErrorKind.ShuttingDown:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Shutdown;
+        default:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException;
+    }
+}
+exports.ERROR_MESSAGE_MAX_LENGTH = 512;
 const CREDENTIAL_PATTERNS = [
     [/Authorization\s*:\s*(?:(?:Bearer|Basic)\s+)?[^\s,;]+/gi, 'Authorization: <redacted>'],
     [/Bearer\s+[^\s,;]+/gi, 'Bearer <redacted>'],
@@ -51,5 +79,5 @@ function sanitizeErrorMessage(message) {
         pattern.lastIndex = 0;
         sanitized = sanitized.replace(pattern, replacement);
     }
-    return sanitized.slice(0, ERROR_MESSAGE_MAX_LENGTH);
+    return sanitized.slice(0, exports.ERROR_MESSAGE_MAX_LENGTH);
 }

package/dist/runtime/diagnostics/flow-context.d.ts

@@ -1,4 +1,10 @@
 import type { ZLinkFlowOrigin } from '../../contracts';
+/**
+ * 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 declare const FLOW_ORIGIN_VALUES: Readonly<Record<ZLinkFlowOrigin, string>>;
 export interface ZLinkFlowContextValue {
     readonly flowId: string;
     readonly flowOrigin: ZLinkFlowOrigin;

package/dist/runtime/diagnostics/flow-context.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOW_ORIGIN_VALUES = void 0;
 exports.currentFlowContext = currentFlowContext;
 exports.currentOrCreateFlow = currentOrCreateFlow;
 exports.runWithFlow = runWithFlow;
@@ -7,6 +8,19 @@ exports.runWithOutboundFlow = runWithOutboundFlow;
 exports.createInboundFlow = createInboundFlow;
 const node_async_hooks_1 = require("node:async_hooks");
 const node_crypto_1 = require("node:crypto");
+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).
+ */
+exports.FLOW_ORIGIN_VALUES = Object.freeze({
+    Inbound: 'inbound',
+    Timer: 'timer',
+    Application: 'application',
+    Lifecycle: 'lifecycle'
+});
 const flowStorage = new node_async_hooks_1.AsyncLocalStorage();
 function currentFlowContext() {
     return flowStorage.getStore();
@@ -57,12 +71,12 @@ function createInboundFlow(flowId, flowOrigin, createIfAbsent, streamSessionId)
     return { flowId: flowId ?? createFlowId(), flowOrigin: flowOrigin ?? 'Inbound', streamSessionId };
 }
 function createFlowId() {
-    const bytes = (0, node_crypto_1.randomBytes)(16);
+    const bytes = (0, node_crypto_1.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/dist/runtime/diagnostics/index.d.ts

@@ -1,15 +1,17 @@
 import type { ZLinkLocationRuntimeQuery } 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 { type ZLinkAutoConnectDesiredSetChange, type ZLinkLocationMonitoringRegistration, type ZLinkPollingMonitoringRegistration, type ZLinkRuntimeEvent, type ZLinkRuntimeEventHandler, type ZLinkSocketMonitoringRegistration } from './internal-event-contracts';
 export { ZLinkLocationActorEventKind, ZLinkLocationPeerEventKind, ZLinkLocationRouteEventKind, ZLinkLocationSpotEventKind, ZLinkSocketNativeEventType } from './internal-event-contracts';
-import type { ZLinkBackendSocketMonitor, ZLinkBackendSocketMonitorEvent } from '../backend';
 export interface ZLinkActorOwnerLeaseObservation {
     readonly actorId: string;
     readonly authorityGeneration: bigint;
     readonly remainingLeaseMs: number;
     readonly decision: 'owner_unavailable';
 }
+export declare function isRelocationDebugEnabled(): boolean;
+export declare function relocationDebug(marker: string, detail: Record<string, unknown>): void;
 /** Emits high-cardinality resolver detail only on the existing relocation debug path. */
 export declare function emitActorOwnerLeaseObservation(observation: ZLinkActorOwnerLeaseObservation): void;
 /** Runtime composition port. It is intentionally absent from the public contract barrel. */

package/dist/runtime/diagnostics/index.js

@@ -15,7 +15,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkLocationMonitoringEventEmitter = exports.ZLinkLocationRuntimeMonitoringSource = exports.ZLinkSocketMonitoringSource = exports.DefaultZLinkRuntimeEventPublisher = exports.ZLinkSocketNativeEventType = exports.ZLinkLocationSpotEventKind = exports.ZLinkLocationRouteEventKind = exports.ZLinkLocationPeerEventKind = exports.ZLinkLocationActorEventKind = void 0;
+exports.isRelocationDebugEnabled = isRelocationDebugEnabled;
+exports.relocationDebug = relocationDebug;
 exports.emitActorOwnerLeaseObservation = emitActorOwnerLeaseObservation;
+const node_async_hooks_1 = require("node:async_hooks");
+const state_lane_1 = require("../execution/state-lane");
+const routing_id_1 = require("../routing-id");
 const internal_event_contracts_1 = require("./internal-event-contracts");
 var internal_event_contracts_2 = require("./internal-event-contracts");
 Object.defineProperty(exports, "ZLinkLocationActorEventKind", { enumerable: true, get: function () { return internal_event_contracts_2.ZLinkLocationActorEventKind; } });
@@ -23,14 +28,19 @@ Object.defineProperty(exports, "ZLinkLocationPeerEventKind", { enumerable: true,
 Object.defineProperty(exports, "ZLinkLocationRouteEventKind", { enumerable: true, get: function () { return internal_event_contracts_2.ZLinkLocationRouteEventKind; } });
 Object.defineProperty(exports, "ZLinkLocationSpotEventKind", { enumerable: true, get: function () { return internal_event_contracts_2.ZLinkLocationSpotEventKind; } });
 Object.defineProperty(exports, "ZLinkSocketNativeEventType", { enumerable: true, get: function () { return internal_event_contracts_2.ZLinkSocketNativeEventType; } });
-const node_async_hooks_1 = require("node:async_hooks");
-const state_lane_1 = require("../execution/state-lane");
-const routing_id_1 = require("../routing-id");
 const ZLINK_DISCONNECT_REASON_HANDSHAKE_FAILED = 3;
 const detachedStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:location-runtime-monitoring-source');
+function isRelocationDebugEnabled() {
+    return process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION === '1';
+}
+function relocationDebug(marker, detail) {
+    if (!isRelocationDebugEnabled())
+        return;
+    console.error('[zlink.runtime.relocation]', marker, detail);
+}
 /** Emits high-cardinality resolver detail only on the existing relocation debug path. */
 function emitActorOwnerLeaseObservation(observation) {
-    if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION !== '1')
+    if (!isRelocationDebugEnabled())
         return;
     console.error('[zlink.runtime.relocation]', 'actor_route.owner_lease_observed', observation);
 }

package/dist/runtime/diagnostics/message-flow.d.ts

@@ -1,5 +1,5 @@
 import { type ZLinkDiagnosticsOptions, type ZLinkMessageFlowLogMode } from '../../contracts';
-import { ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome, type ZLinkRuntimeMessageFlowResult, type ZLinkRuntimeMessageFlowEvent } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import { ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome, type ZLinkRuntimeMessageFlowEvent, type ZLinkRuntimeMessageFlowResult } from '../../contracts/Dispatch/ZLinkDispatchOptions';
 import type { ZLinkDispatchErrorSink } from './dispatch-error-port';
 export interface ZLinkMessageFlowModeCell {
     mode: ZLinkMessageFlowLogMode;