@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,21 @@
+import type { ZLinkFlowOrigin } from '../../contracts';
+export interface ZLinkFlowContextValue {
+    readonly flowId: string;
+    readonly flowOrigin: ZLinkFlowOrigin;
+}
+export declare function currentFlowContext(): ZLinkFlowContextValue | undefined;
+export declare function currentOrCreateFlow(origin?: ZLinkFlowOrigin, createIfAbsent?: true): ZLinkFlowContextValue;
+export declare function currentOrCreateFlow(origin: ZLinkFlowOrigin, createIfAbsent: false): ZLinkFlowContextValue | undefined;
+export declare function currentOrCreateFlow(origin: ZLinkFlowOrigin, createIfAbsent: boolean): ZLinkFlowContextValue | undefined;
+export declare function runWithFlow<T>(flow: ZLinkFlowContextValue | undefined, callback: () => T): T;
+/**
+ * Call-scoped outbound flow scope shared by every outbound entry point
+ * (channel operations, mesh/route transports, spot address transport,
+ * native-fallback bound session). When tracing is enabled and no ambient
+ * flow exists, installs a fresh Application flow for the duration of
+ * `callback` only — the caller's async context is untouched afterwards
+ * (spec 27 §4). Envelope encoders and trace points inside the callback
+ * observe the same ambient flow, so the source-side hop stays coherent.
+ */
+export declare function runWithOutboundFlow<T>(enabled: boolean, callback: () => T): T;
+export declare function createInboundFlow(flowId?: string, flowOrigin?: ZLinkFlowOrigin, createIfAbsent?: boolean): ZLinkFlowContextValue | undefined;

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentFlowContext = currentFlowContext;
+exports.currentOrCreateFlow = currentOrCreateFlow;
+exports.runWithFlow = runWithFlow;
+exports.runWithOutboundFlow = runWithOutboundFlow;
+exports.createInboundFlow = createInboundFlow;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const flowStorage = new node_async_hooks_1.AsyncLocalStorage();
+function currentFlowContext() {
+    return flowStorage.getStore();
+}
+/**
+ * Returns the ambient flow context or, when absent and `createIfAbsent`, a
+ * fresh flow value. The returned value is NOT installed into the ambient
+ * async context (spec 27 §4/§6: flow scopes are call-scoped; a top-level
+ * outbound must not leave its flow behind in unrelated application work).
+ * Outbound entry points that need an ambient scope wrap their operation in
+ * {@link runWithOutboundFlow} instead.
+ */
+function currentOrCreateFlow(origin = 'Application', createIfAbsent = true) {
+    const current = currentFlowContext();
+    if (current !== undefined) {
+        return current;
+    }
+    if (!createIfAbsent) {
+        return undefined;
+    }
+    return { flowId: createFlowId(), flowOrigin: origin };
+}
+function runWithFlow(flow, callback) {
+    if (flow === undefined && currentFlowContext() === undefined) {
+        return callback();
+    }
+    return flowStorage.run(flow, callback);
+}
+/**
+ * Call-scoped outbound flow scope shared by every outbound entry point
+ * (channel operations, mesh/route transports, spot address transport,
+ * native-fallback bound session). When tracing is enabled and no ambient
+ * flow exists, installs a fresh Application flow for the duration of
+ * `callback` only — the caller's async context is untouched afterwards
+ * (spec 27 §4). Envelope encoders and trace points inside the callback
+ * observe the same ambient flow, so the source-side hop stays coherent.
+ */
+function runWithOutboundFlow(enabled, callback) {
+    if (!enabled || currentFlowContext() !== undefined) {
+        return callback();
+    }
+    return flowStorage.run({ flowId: createFlowId(), flowOrigin: 'Application' }, callback);
+}
+function createInboundFlow(flowId, flowOrigin, createIfAbsent = true) {
+    if (!createIfAbsent) {
+        return undefined;
+    }
+    return { flowId: flowId ?? createFlowId(), flowOrigin: flowOrigin ?? 'Inbound' };
+}
+function createFlowId() {
+    const bytes = (0, node_crypto_1.randomBytes)(16);
+    // 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);
+    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

@@ -0,0 +1,82 @@
+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 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';
+}
+/** 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. */
+export interface ZLinkRuntimeEventPublisher {
+    register<TEvent extends ZLinkRuntimeEvent>(handler: ZLinkRuntimeEventHandler<TEvent>): void;
+    publish<TEvent extends ZLinkRuntimeEvent>(event: TEvent): Promise<void>;
+}
+export declare class DefaultZLinkRuntimeEventPublisher implements ZLinkRuntimeEventPublisher {
+    private readonly handlers;
+    register<TEvent extends ZLinkRuntimeEvent>(handler: ZLinkRuntimeEventHandler<TEvent>): void;
+    publish<TEvent extends ZLinkRuntimeEvent>(event: TEvent): Promise<void>;
+}
+export declare class ZLinkSocketMonitoringSource {
+    private readonly registration;
+    private readonly monitor;
+    private readonly publisher;
+    private readonly enabledEvents;
+    constructor(registration: ZLinkSocketMonitoringRegistration, monitor: ZLinkBackendSocketMonitor, publisher: ZLinkRuntimeEventPublisher);
+    start(): void;
+    publish(raw: ZLinkBackendSocketMonitorEvent): Promise<void>;
+}
+export declare class ZLinkLocationRuntimeMonitoringSource {
+    private readonly registration;
+    private readonly query;
+    private readonly publisher;
+    private readonly lane;
+    private previousStatus?;
+    private previousTopology?;
+    private previousServiceSummary?;
+    private storeFailure;
+    constructor(registration: ZLinkPollingMonitoringRegistration, query: ZLinkLocationRuntimeQuery, publisher: ZLinkRuntimeEventPublisher);
+    pollOnce(signal?: AbortSignal): Promise<void>;
+    private markStoreFailureCore;
+    private markStoreRecoveredCore;
+    private publishIfChanged;
+    private previousSnapshotCore;
+    private updateSnapshotCore;
+}
+export declare class ZLinkLocationMonitoringEventEmitter {
+    private readonly registration;
+    private readonly publisher?;
+    static readonly disabled: ZLinkLocationMonitoringEventEmitter;
+    constructor(registration: {
+        readonly peer?: ZLinkLocationMonitoringRegistration;
+        readonly spot?: ZLinkLocationMonitoringRegistration;
+        readonly actor?: ZLinkLocationMonitoringRegistration;
+        readonly route?: ZLinkLocationMonitoringRegistration;
+    }, publisher?: ZLinkRuntimeEventPublisher | undefined);
+    peerRowUpdated(key: ZLinkLocationKey, peer: ZLinkPeerLocation): void;
+    peerRowRemoved(key: ZLinkLocationKey): void;
+    desiredSetChanged(change: ZLinkAutoConnectDesiredSetChange): void;
+    spotRowUpdated(key: ZLinkSpotLocationKey, spot: ZLinkSpotLocation): void;
+    spotRowRemoved(key: ZLinkSpotLocationKey): void;
+    spotResolveMiss(key: ZLinkSpotLocationKey): void;
+    actorRowUpdated(key: ZLinkActorLocationKey, actor: ZLinkActorLocation): void;
+    actorRowRemoved(key: ZLinkActorLocationKey): void;
+    actorResolveMiss(key: ZLinkActorLocationKey): void;
+    routeRowUpdated(key: ZLinkRouteLocationKey, route: ZLinkRouteLocation): void;
+    routeRowRemoved(key: ZLinkRouteLocationKey): void;
+    routeResolveMiss(key: ZLinkRouteLocationKey): void;
+    private publishPeer;
+    private publishSpotLocation;
+    private publishActor;
+    private publishRoute;
+    private publish;
+}
+export * from './topology-runtime-projections';
+export * from './message-flow';
+export * from './flow-context';
+export * from './runtime-metrics';

package/dist/runtime/diagnostics/index.js

@@ -0,0 +1,335 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+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.emitActorOwnerLeaseObservation = emitActorOwnerLeaseObservation;
+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; } });
+Object.defineProperty(exports, "ZLinkLocationPeerEventKind", { enumerable: true, get: function () { return internal_event_contracts_2.ZLinkLocationPeerEventKind; } });
+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');
+/** Emits high-cardinality resolver detail only on the existing relocation debug path. */
+function emitActorOwnerLeaseObservation(observation) {
+    if (process.env.ZLINK_DEBUG_FRAMEWORK_RELOCATION !== '1')
+        return;
+    console.error('[zlink.runtime.relocation]', 'actor_route.owner_lease_observed', observation);
+}
+class DefaultZLinkRuntimeEventPublisher {
+    handlers = [];
+    register(handler) {
+        this.handlers.push(handler);
+    }
+    async publish(event) {
+        for (const handler of this.handlers) {
+            try {
+                await handler.handle(event);
+            }
+            catch (error) {
+                console.error('[monitoring-event-dispatch]', error);
+                continue;
+            }
+        }
+    }
+}
+exports.DefaultZLinkRuntimeEventPublisher = DefaultZLinkRuntimeEventPublisher;
+class ZLinkSocketMonitoringSource {
+    registration;
+    monitor;
+    publisher;
+    enabledEvents;
+    constructor(registration, monitor, publisher) {
+        this.registration = registration;
+        this.monitor = monitor;
+        this.publisher = publisher;
+        validateSourceName(registration.sourceName);
+        this.enabledEvents = registration.events === undefined
+            ? undefined
+            : new Set(registration.events);
+    }
+    start() {
+        this.monitor.onEvent((event) => {
+            void this.publish(event);
+        });
+    }
+    publish(raw) {
+        const event = toSocketEvent(this.registration.sourceName, raw);
+        if (event === undefined) {
+            return Promise.resolve();
+        }
+        if (this.enabledEvents !== undefined && !this.enabledEvents.has(event.event)) {
+            return Promise.resolve();
+        }
+        return this.publisher.publish(event);
+    }
+}
+exports.ZLinkSocketMonitoringSource = ZLinkSocketMonitoringSource;
+class ZLinkLocationRuntimeMonitoringSource {
+    registration;
+    query;
+    publisher;
+    lane = new state_lane_1.ZLinkStateLane();
+    previousStatus;
+    previousTopology;
+    previousServiceSummary;
+    storeFailure = false;
+    constructor(registration, query, publisher) {
+        this.registration = registration;
+        this.query = query;
+        this.publisher = publisher;
+        validateSourceName(registration.sourceName);
+        validatePollingInterval('Location runtime', registration.intervalMs);
+    }
+    async pollOnce(signal) {
+        let status;
+        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)
+            ]));
+        }
+        catch (error) {
+            if (await this.lane.run(() => this.markStoreFailureCore())) {
+                await startOutsideStateLane(() => this.publisher.publish({
+                    sourceName: this.registration.sourceName,
+                    timestamp: new Date(),
+                    event: internal_event_contracts_1.ZLinkLocationRuntimeEventKind.StoreFailure
+                }));
+            }
+            return;
+        }
+        if (await this.lane.run(() => this.markStoreRecoveredCore())) {
+            await startOutsideStateLane(() => this.publisher.publish({
+                sourceName: this.registration.sourceName,
+                timestamp: new Date(),
+                event: internal_event_contracts_1.ZLinkLocationRuntimeEventKind.StoreRecovered
+            }));
+        }
+        await this.publishIfChanged(internal_event_contracts_1.ZLinkLocationRuntimeEventKind.StatusChanged, status);
+        await this.publishIfChanged(internal_event_contracts_1.ZLinkLocationRuntimeEventKind.TopologyChanged, topology.items);
+        await this.publishIfChanged(internal_event_contracts_1.ZLinkLocationRuntimeEventKind.ServiceSummaryChanged, serviceSummary.items);
+    }
+    markStoreFailureCore() {
+        if (this.storeFailure)
+            return false;
+        this.storeFailure = true;
+        return true;
+    }
+    markStoreRecoveredCore() {
+        if (!this.storeFailure)
+            return false;
+        this.storeFailure = false;
+        return true;
+    }
+    async publishIfChanged(event, snapshot) {
+        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 this.lane.run(() => this.updateSnapshotCore(event, current));
+    }
+    previousSnapshotCore(event) {
+        switch (event) {
+            case internal_event_contracts_1.ZLinkLocationRuntimeEventKind.StatusChanged:
+                return this.previousStatus;
+            case internal_event_contracts_1.ZLinkLocationRuntimeEventKind.TopologyChanged:
+                return this.previousTopology;
+            case internal_event_contracts_1.ZLinkLocationRuntimeEventKind.ServiceSummaryChanged:
+                return this.previousServiceSummary;
+            default:
+                return undefined;
+        }
+    }
+    updateSnapshotCore(event, current) {
+        switch (event) {
+            case internal_event_contracts_1.ZLinkLocationRuntimeEventKind.StatusChanged:
+                this.previousStatus = current;
+                return;
+            case internal_event_contracts_1.ZLinkLocationRuntimeEventKind.TopologyChanged:
+                this.previousTopology = current;
+                return;
+            case internal_event_contracts_1.ZLinkLocationRuntimeEventKind.ServiceSummaryChanged:
+                this.previousServiceSummary = current;
+                return;
+        }
+    }
+}
+exports.ZLinkLocationRuntimeMonitoringSource = ZLinkLocationRuntimeMonitoringSource;
+class ZLinkLocationMonitoringEventEmitter {
+    registration;
+    publisher;
+    static disabled = new ZLinkLocationMonitoringEventEmitter({}, undefined);
+    constructor(registration, publisher) {
+        this.registration = registration;
+        this.publisher = publisher;
+        for (const source of [registration.peer, registration.spot, registration.actor, registration.route]) {
+            if (source !== undefined) {
+                validateSourceName(source.sourceName);
+            }
+        }
+    }
+    peerRowUpdated(key, peer) {
+        this.publishPeer(internal_event_contracts_1.ZLinkLocationPeerEventKind.RowUpdated, { key, peer });
+    }
+    peerRowRemoved(key) {
+        this.publishPeer(internal_event_contracts_1.ZLinkLocationPeerEventKind.RowRemoved, { key });
+    }
+    desiredSetChanged(change) {
+        this.publishPeer(internal_event_contracts_1.ZLinkLocationPeerEventKind.DesiredSetChanged, { desiredSetChange: change });
+    }
+    spotRowUpdated(key, spot) {
+        this.publishSpotLocation(internal_event_contracts_1.ZLinkLocationSpotEventKind.RowUpdated, { key, spot });
+    }
+    spotRowRemoved(key) {
+        this.publishSpotLocation(internal_event_contracts_1.ZLinkLocationSpotEventKind.RowRemoved, { key });
+    }
+    spotResolveMiss(key) {
+        this.publishSpotLocation(internal_event_contracts_1.ZLinkLocationSpotEventKind.ResolveMiss, { key });
+    }
+    actorRowUpdated(key, actor) {
+        this.publishActor(internal_event_contracts_1.ZLinkLocationActorEventKind.RowUpdated, { key, actor });
+    }
+    actorRowRemoved(key) {
+        this.publishActor(internal_event_contracts_1.ZLinkLocationActorEventKind.RowRemoved, { key });
+    }
+    actorResolveMiss(key) {
+        this.publishActor(internal_event_contracts_1.ZLinkLocationActorEventKind.ResolveMiss, { key });
+    }
+    routeRowUpdated(key, route) {
+        this.publishRoute(internal_event_contracts_1.ZLinkLocationRouteEventKind.RowUpdated, { key, route });
+    }
+    routeRowRemoved(key) {
+        this.publishRoute(internal_event_contracts_1.ZLinkLocationRouteEventKind.RowRemoved, { key });
+    }
+    routeResolveMiss(key) {
+        this.publishRoute(internal_event_contracts_1.ZLinkLocationRouteEventKind.ResolveMiss, { key });
+    }
+    publishPeer(event, payload) {
+        const registration = this.registration.peer;
+        if (registration === undefined) {
+            return;
+        }
+        this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload });
+    }
+    publishSpotLocation(event, payload) {
+        const registration = this.registration.spot;
+        if (registration === undefined) {
+            return;
+        }
+        this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload });
+    }
+    publishActor(event, payload) {
+        const registration = this.registration.actor;
+        if (registration === undefined) {
+            return;
+        }
+        this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload });
+    }
+    publishRoute(event, payload) {
+        const registration = this.registration.route;
+        if (registration === undefined) {
+            return;
+        }
+        this.publish({ sourceName: registration.sourceName, timestamp: new Date(), event, ...payload });
+    }
+    publish(event) {
+        if (this.publisher === undefined) {
+            return;
+        }
+        void this.publisher.publish(event).catch((error) => {
+            console.error('[location-monitoring-event-dispatch]', error);
+        });
+    }
+}
+exports.ZLinkLocationMonitoringEventEmitter = ZLinkLocationMonitoringEventEmitter;
+__exportStar(require("./topology-runtime-projections"), exports);
+function toSocketEvent(sourceName, raw) {
+    const event = mapSocketEvent(raw.nativeEvent, raw.value);
+    if (event === undefined) {
+        return undefined;
+    }
+    return {
+        sourceName,
+        timestamp: new Date(),
+        event,
+        routingId: raw.routingId === undefined ? undefined : (0, routing_id_1.normalizeOpaqueRoutingId)(raw.routingId),
+        localAddr: raw.localAddr,
+        remoteAddr: raw.remoteAddr
+    };
+}
+function mapSocketEvent(nativeEvent, nativeValue) {
+    switch (nativeEvent) {
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.Connected:
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.Accepted:
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.Listening:
+            return internal_event_contracts_1.ZLinkSocketEventKind.Connected;
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.ConnectionReady:
+            return internal_event_contracts_1.ZLinkSocketEventKind.ConnectionReady;
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.Disconnected:
+            return nativeValue === BigInt(ZLINK_DISCONNECT_REASON_HANDSHAKE_FAILED)
+                ? internal_event_contracts_1.ZLinkSocketEventKind.HandshakeFailed
+                : internal_event_contracts_1.ZLinkSocketEventKind.Disconnected;
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.HandshakeFailedNoDetail:
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.HandshakeFailedProtocol:
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.HandshakeFailedAuth:
+            return internal_event_contracts_1.ZLinkSocketEventKind.HandshakeFailed;
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.PeerAdmissionChanged:
+            return internal_event_contracts_1.ZLinkSocketEventKind.PeerAdmissionChanged;
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.Closed:
+        case internal_event_contracts_1.ZLinkSocketNativeEventType.MonitorStopped:
+            return internal_event_contracts_1.ZLinkSocketEventKind.Closed;
+        default:
+            return undefined;
+    }
+}
+async function publishLocationRuntimeChange(publisher, sourceName, event, snapshot) {
+    const base = { sourceName, timestamp: new Date() };
+    const runtimeEvent = event === internal_event_contracts_1.ZLinkLocationRuntimeEventKind.StatusChanged
+        ? { ...base, event, status: snapshot }
+        : event === internal_event_contracts_1.ZLinkLocationRuntimeEventKind.TopologyChanged
+            ? { ...base, event, topology: snapshot }
+            : { ...base, event: internal_event_contracts_1.ZLinkLocationRuntimeEventKind.ServiceSummaryChanged, serviceSummary: snapshot };
+    await publisher.publish(runtimeEvent);
+}
+function startOutsideStateLane(work) {
+    return detachedStateLaneResource.runInAsyncScope(work);
+}
+function stableSnapshot(value) {
+    return JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? item.toString() : item);
+}
+function validateSourceName(sourceName) {
+    if (sourceName.trim().length === 0) {
+        throw new Error('Monitoring sourceName must not be empty.');
+    }
+}
+function validatePollingInterval(sourceKind, intervalMs) {
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new Error(`${sourceKind} monitoring intervalMs must be greater than zero.`);
+    }
+}
+__exportStar(require("./message-flow"), exports);
+__exportStar(require("./flow-context"), exports);
+__exportStar(require("./runtime-metrics"), exports);

package/dist/runtime/diagnostics/internal-event-contracts.d.ts

@@ -0,0 +1,139 @@
+import type { RoutingId } from '../../contracts/Common';
+import type { ZLinkLocationRuntimeStatus, ZLinkLocationServiceSummary, ZLinkLocationTopologyEntry } from '../../contracts/Locations';
+import type { ZLinkLocationAutoConnectType } from '../../contracts/Locations/Values';
+import type { ZLinkActorLocation, ZLinkPeerLocation, ZLinkRouteLocation, ZLinkSpotLocation } from '../../contracts/Locations/Rows';
+import type { ZLinkActorLocationKey, ZLinkRouteLocationKey, ZLinkSpotLocationKey } from '../../contracts/Locations/Keys';
+export interface ZLinkLocationMonitoringRegistration {
+    readonly sourceName: string;
+}
+export interface ZLinkSocketMonitoringRegistration {
+    readonly sourceName: string;
+    readonly events?: readonly ZLinkSocketEventKind[];
+}
+export interface ZLinkPollingMonitoringRegistration {
+    readonly sourceName: string;
+    readonly intervalMs: number;
+}
+export interface ZLinkRuntimeEvent {
+    readonly sourceName: string;
+    readonly timestamp: Date;
+}
+export interface ZLinkRuntimeEventHandler<TEvent extends ZLinkRuntimeEvent> {
+    handle(event: TEvent): Promise<void>;
+}
+export declare enum ZLinkSocketEventKind {
+    Connected = "connected",
+    ConnectionReady = "connectionReady",
+    Disconnected = "disconnected",
+    HandshakeFailed = "handshakeFailed",
+    PeerAdmissionChanged = "peerAdmissionChanged",
+    Closed = "closed"
+}
+export interface ZLinkSocketEvent extends ZLinkRuntimeEvent {
+    readonly event: ZLinkSocketEventKind;
+    readonly routingId?: RoutingId;
+    readonly localAddr: string;
+    readonly remoteAddr: string;
+}
+export declare enum ZLinkLocationRuntimeEventKind {
+    StatusChanged = 0,
+    TopologyChanged = 1,
+    ServiceSummaryChanged = 2,
+    StoreFailure = 3,
+    StoreRecovered = 4
+}
+export type ZLinkLocationRuntimeEvent = (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationRuntimeEventKind.StatusChanged;
+    readonly status: ZLinkLocationRuntimeStatus;
+}) | (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationRuntimeEventKind.TopologyChanged;
+    readonly topology: readonly ZLinkLocationTopologyEntry[];
+}) | (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationRuntimeEventKind.ServiceSummaryChanged;
+    readonly serviceSummary: readonly ZLinkLocationServiceSummary[];
+}) | (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationRuntimeEventKind.StoreFailure | ZLinkLocationRuntimeEventKind.StoreRecovered;
+});
+export declare enum ZLinkSpotEventKind {
+    TimerHandlerFailed = "timerHandlerFailed",
+    TimerStoppedAfterUnhandledException = "timerStoppedAfterUnhandledException"
+}
+export declare enum ZLinkSocketNativeEventType {
+    Connected = 1,
+    ConnectDelayed = 2,
+    ConnectRetried = 4,
+    Listening = 8,
+    BindFailed = 16,
+    Accepted = 32,
+    AcceptFailed = 64,
+    Closed = 128,
+    CloseFailed = 256,
+    Disconnected = 512,
+    MonitorStopped = 1024,
+    HandshakeFailedNoDetail = 2048,
+    ConnectionReady = 4096,
+    HandshakeFailedProtocol = 8192,
+    HandshakeFailedAuth = 16384,
+    PeerAdmissionChanged = 32768
+}
+export declare enum ZLinkLocationPeerEventKind {
+    RowUpdated = 0,
+    RowRemoved = 1,
+    DesiredSetChanged = 2
+}
+export declare enum ZLinkLocationSpotEventKind {
+    RowUpdated = 0,
+    RowRemoved = 1,
+    ResolveMiss = 2
+}
+export declare enum ZLinkLocationActorEventKind {
+    RowUpdated = 0,
+    RowRemoved = 1,
+    ResolveMiss = 2
+}
+export declare enum ZLinkLocationRouteEventKind {
+    RowUpdated = 0,
+    RowRemoved = 1,
+    ResolveMiss = 2
+}
+export interface ZLinkAutoConnectDesiredSetChange {
+    readonly autoConnectType: ZLinkLocationAutoConnectType;
+    readonly meshName: string;
+    readonly connectedEndpoints: readonly string[];
+    readonly disconnectedEndpoints: readonly string[];
+}
+export type ZLinkLocationPeerEvent = (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationPeerEventKind.RowUpdated;
+    readonly key: string;
+    readonly peer: ZLinkPeerLocation;
+}) | (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationPeerEventKind.RowRemoved;
+    readonly key: string;
+}) | (ZLinkRuntimeEvent & {
+    readonly event: ZLinkLocationPeerEventKind.DesiredSetChanged;
+    readonly desiredSetChange: ZLinkAutoConnectDesiredSetChange;
+});
+export type ZLinkLocationSpotEvent = ZLinkRuntimeEvent & ({
+    readonly event: ZLinkLocationSpotEventKind.RowUpdated;
+    readonly key: ZLinkSpotLocationKey;
+    readonly spot: ZLinkSpotLocation;
+} | {
+    readonly event: ZLinkLocationSpotEventKind.RowRemoved | ZLinkLocationSpotEventKind.ResolveMiss;
+    readonly key: ZLinkSpotLocationKey;
+});
+export type ZLinkLocationActorEvent = ZLinkRuntimeEvent & ({
+    readonly event: ZLinkLocationActorEventKind.RowUpdated;
+    readonly key: ZLinkActorLocationKey;
+    readonly actor: ZLinkActorLocation;
+} | {
+    readonly event: ZLinkLocationActorEventKind.RowRemoved | ZLinkLocationActorEventKind.ResolveMiss;
+    readonly key: ZLinkActorLocationKey;
+});
+export type ZLinkLocationRouteEvent = ZLinkRuntimeEvent & ({
+    readonly event: ZLinkLocationRouteEventKind.RowUpdated;
+    readonly key: ZLinkRouteLocationKey;
+    readonly route: ZLinkRouteLocation;
+} | {
+    readonly event: ZLinkLocationRouteEventKind.RowRemoved | ZLinkLocationRouteEventKind.ResolveMiss;
+    readonly key: ZLinkRouteLocationKey;
+});