@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,27 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkMessageFlowTracer = exports.telemetryLogger = exports.DEFAULT_ZLINK_DIAGNOSTICS = void 0;
+exports.ZLinkMessageFlowTracer = exports.DEFAULT_ZLINK_DIAGNOSTICS = void 0;
 exports.effectiveMessageFlow = effectiveMessageFlow;
 exports.messageFlowTracingEnabled = messageFlowTracingEnabled;
 exports.createMessageFlowModeCell = createMessageFlowModeCell;
 exports.createDiagnosticsContext = createDiagnosticsContext;
 exports.flowIfEnabled = flowIfEnabled;
 exports.traceSessionBindingControlDrop = traceSessionBindingControlDrop;
-const api_1 = require("@opentelemetry/api");
-const api_logs_1 = require("@opentelemetry/api-logs");
-const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const dispatch_error_details_1 = require("./dispatch-error-details");
 const flow_context_1 = require("./flow-context");
-const MESSAGE_FLOW_EVENT_ID = 'zlink.message_flow';
-const DISPATCH_ERROR_EVENT_ID = 'zlink.dispatch_error';
+const message_flow_record_1 = require("./message-flow-record");
+const message_flow_delivery_1 = require("./message-flow-delivery");
 exports.DEFAULT_ZLINK_DIAGNOSTICS = {
     messageFlow: 'errors',
     sampleRate: 1,
     includeMessageSizes: false
 };
-exports.telemetryLogger = api_logs_1.logs.getLogger('@zlink-systems/framework');
-const telemetryTracer = api_1.trace.getTracer('@zlink-systems/framework');
 let diagnosticsGeneration = 0n;
 function effectiveMessageFlow(ctx) {
     return ctx.liveMode.mode;
@@ -32,16 +27,17 @@ function effectiveMessageFlow(ctx) {
  * is the one decision every flow processing point reads.
  */
 function messageFlowTracingEnabled(mode) {
-    return contracts_1.MESSAGE_FLOW_MODE_RANK[mode] >= contracts_1.MESSAGE_FLOW_MODE_RANK.normal;
+    return ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[mode] >= ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK.normal;
 }
 function createMessageFlowModeCell(dispatch) {
     return { mode: dispatch?.diagnostics?.messageFlow ?? 'errors' };
 }
-function createDiagnosticsContext(dispatch, _providerResolver, liveMode) {
+function createDiagnosticsContext(dispatch, _providerResolver, liveMode, telemetryLease = (0, message_flow_delivery_1.openTelemetryLease)()) {
     return {
         diagnostics: dispatch?.diagnostics ?? exports.DEFAULT_ZLINK_DIAGNOSTICS,
         liveMode,
-        sourceMeshGeneration: ++diagnosticsGeneration
+        sourceMeshGeneration: ++diagnosticsGeneration,
+        telemetryLease
     };
 }
 function requiredMode(outcome, result) {
@@ -80,30 +76,34 @@ function traceSessionBindingControlDrop(flow, sourceRid, actorId, packetName, er
 }
 class ZLinkMessageFlowTracer {
     ctx;
-    errorSink;
     tracedEvents = 0;
-    providerFailures = 0;
+    telemetryLease;
     localSamplingSequence = 0n;
     errorsTracePoint;
     normalTracePoint;
     detailedTracePoint;
-    constructor(ctx, errorSink) {
+    constructor(ctx) {
         this.ctx = ctx;
-        this.errorSink = errorSink;
+        this.telemetryLease = ctx.telemetryLease ?? (0, message_flow_delivery_1.openTelemetryLease)();
     }
     enabled(outcome) {
         const mode = effectiveMessageFlow(this.ctx);
-        return contracts_1.MESSAGE_FLOW_MODE_RANK[mode] >= contracts_1.MESSAGE_FLOW_MODE_RANK[requiredMode(outcome)];
+        return (ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[mode] >= ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[requiredMode(outcome)] &&
+            (0, message_flow_delivery_1.messageFlowDelivery)().accepts(this.telemetryLease));
     }
     accepts(outcome) {
         return this.enabled(outcome);
     }
     begin(outcome, result, flowId, sourceMeshGeneration) {
         const mode = effectiveMessageFlow(this.ctx);
-        if (contracts_1.MESSAGE_FLOW_MODE_RANK[mode] < contracts_1.MESSAGE_FLOW_MODE_RANK[requiredMode(outcome, result)]) {
+        if (ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[mode] < ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[requiredMode(outcome, result)]) {
             return undefined;
         }
-        const samplingFlowId = flowId ?? (0, flow_context_1.currentFlowContext)()?.flowId;
+        if (!(0, message_flow_delivery_1.messageFlowDelivery)().accepts(this.telemetryLease))
+            return undefined;
+        const samplingFlowId = messageFlowTracingEnabled(mode)
+            ? (flowId ?? (0, flow_context_1.currentFlowContext)()?.flowId)
+            : undefined;
         if (!this.acceptsSample(outcome, result, samplingFlowId, sourceMeshGeneration)) {
             return undefined;
         }
@@ -129,27 +129,41 @@ class ZLinkMessageFlowTracer {
     }
     trace(flowInput) {
         const effectiveMode = effectiveMessageFlow(this.ctx);
-        if (contracts_1.MESSAGE_FLOW_MODE_RANK[effectiveMode] <
-            contracts_1.MESSAGE_FLOW_MODE_RANK[requiredMode(flowInput.outcome, flowInput.result)])
+        if (ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[effectiveMode] <
+            ZLinkDispatchOptions_1.MESSAGE_FLOW_MODE_RANK[requiredMode(flowInput.outcome, flowInput.result)])
+            return;
+        if (!(0, message_flow_delivery_1.messageFlowDelivery)().accepts(this.telemetryLease))
             return;
-        const ambient = (0, flow_context_1.currentFlowContext)();
-        const flowId = flowInput.flowId ?? ambient?.flowId;
+        const tracingEnabled = messageFlowTracingEnabled(effectiveMode);
+        const ambient = tracingEnabled ? (0, flow_context_1.currentFlowContext)() : undefined;
+        const flowId = tracingEnabled ? (flowInput.flowId ?? ambient?.flowId) : undefined;
         if (!this.acceptsSample(flowInput.outcome, flowInput.result, flowId, flowInput.sourceMeshGeneration))
             return;
         this.traceAcceptedAtMode(flowInput, effectiveMode, flowId, ambient?.flowOrigin);
     }
     traceAcceptedAtMode(flowInput, effectiveMode, acceptedFlowId, acceptedFlowOrigin) {
-        const ambient = (0, flow_context_1.currentFlowContext)();
-        const flowId = flowInput.flowId ?? acceptedFlowId ?? ambient?.flowId;
-        const flowOrigin = flowInput.flowOrigin ?? acceptedFlowOrigin ?? ambient?.flowOrigin;
+        if (!(0, message_flow_delivery_1.messageFlowDelivery)().accepts(this.telemetryLease))
+            return;
+        const tracingEnabled = messageFlowTracingEnabled(effectiveMode);
+        const ambient = tracingEnabled ? (0, flow_context_1.currentFlowContext)() : undefined;
+        const flowId = tracingEnabled
+            ? (flowInput.flowId ?? acceptedFlowId ?? ambient?.flowId)
+            : undefined;
+        const flowOrigin = tracingEnabled
+            ? (flowInput.flowOrigin ?? acceptedFlowOrigin ?? ambient?.flowOrigin)
+            : undefined;
         const flow = {
             ...flowInput,
-            ...(flowId === undefined ? {} : { flowId, flowOrigin }),
+            ...(tracingEnabled
+                ? flowId === undefined
+                    ? {}
+                    : { flowId, flowOrigin }
+                : { flowId: undefined, flowOrigin: undefined }),
             streamSessionId: flowInput.streamSessionId ?? ambient?.streamSessionId,
             effectiveMode
         };
         this.tracedEvents += 1;
-        this.publish(toTelemetryRecord(flow, effectiveMode === 'detailed' && this.ctx.diagnostics.includeMessageSizes
+        (0, message_flow_delivery_1.messageFlowDelivery)().submit(this.telemetryLease, (0, message_flow_record_1.toTelemetryRecord)(flow, effectiveMode === 'detailed' && this.ctx.diagnostics.includeMessageSizes
             ? flow.messageSize
             : undefined, 
         // Spec 26 §4: terminal elapsed time is a Detailed-level addition; the
@@ -167,7 +181,7 @@ class ZLinkMessageFlowTracer {
         return this.tracedEvents;
     }
     get providerFailureCount() {
-        return this.providerFailures;
+        return (0, message_flow_delivery_1.telemetryProviderFailureCount)();
     }
     sample(flowId, sourceMeshGeneration) {
         const rate = this.ctx.diagnostics.sampleRate;
@@ -183,264 +197,8 @@ class ZLinkMessageFlowTracer {
         this.localSamplingSequence += 1n;
         return this.localSamplingSequence;
     }
-    publish(record) {
-        this.publishToLogger(record);
-        this.publishToTrace(record);
-    }
-    publishToLogger(record) {
-        try {
-            const severity = record.severity === 'warning'
-                ? 'WARN'
-                : record.eventId === DISPATCH_ERROR_EVENT_ID
-                    ? 'ERROR'
-                    : 'INFO';
-            exports.telemetryLogger.emit({
-                eventName: record.eventId,
-                timestamp: record.timestamp,
-                severityNumber: api_logs_1.SeverityNumber[severity],
-                severityText: severity,
-                body: structuredLogBody(record),
-                attributes: structuredLogAttributes(record)
-            });
-        }
-        catch (error) {
-            this.reportProviderFailure('logger-provider', error);
-        }
-    }
-    publishToTrace(record) {
-        try {
-            const span = telemetryTracer.startSpan(record.eventId, {
-                attributes: traceAttributes(record)
-            });
-            if (record.eventId === DISPATCH_ERROR_EVENT_ID) {
-                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: record.reason });
-            }
-            span.end();
-        }
-        catch (error) {
-            this.reportProviderFailure('trace-provider', error);
-        }
-    }
-    reportProviderFailure(source, error) {
-        this.providerFailures += 1;
-        try {
-            this.errorSink.reportRuntimeTaskException(source, error);
-        }
-        catch {
-            // The fallback diagnostics path is isolated for the same reason.
-        }
-    }
 }
 exports.ZLinkMessageFlowTracer = ZLinkMessageFlowTracer;
-function toTelemetryRecord(flow, messageSizeBytes, durationSeconds) {
-    return {
-        severity: flow.severity,
-        eventId: flow.outcome === ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error
-            ? DISPATCH_ERROR_EVENT_ID
-            : MESSAGE_FLOW_EVENT_ID,
-        timestamp: new Date(),
-        phase: messageFlowPhase(flow.outcome),
-        outcome: flow.result ?? messageFlowOutcome(flow.outcome),
-        surface: messageFlowSurface(flow.surface),
-        messageKind: messageFlowKind(flow.messageKind),
-        reason: flow.errorReason,
-        action: flow.errorAction,
-        packetName: flow.packetName,
-        channelName: flow.channelName,
-        channelRouteKind: flow.channelRouteKind ?? channelRouteKind(flow.surface),
-        meshName: flow.meshName,
-        topic: flow.topic,
-        correlationId: flow.correlationId,
-        sourceRid: flow.sourceRid,
-        targetRid: flow.targetRid,
-        serverRid: flow.serverRid,
-        flowId: flow.flowId,
-        flowOrigin: flow.flowOrigin === undefined ? undefined : flow_context_1.FLOW_ORIGIN_VALUES[flow.flowOrigin],
-        spotId: flow.spotId,
-        instanceSpotType: flow.instanceSpotType,
-        activationState: flow.activationState,
-        actorId: flow.actorId,
-        streamSessionId: flow.streamSessionId,
-        commandId: flow.commandId,
-        messageSizeBytes,
-        durationSeconds,
-        errorType: flow.errorType,
-        errorMessage: flow.errorMessage,
-        errorCauseType: flow.errorCauseType,
-        errorCauseMessage: boundedText(flow.errorCauseMessage)
-    };
-}
-function traceAttributes(record) {
-    const attributes = {};
-    for (const [name, value] of Object.entries(record)) {
-        if (value === undefined || name === 'timestamp' || name === 'severity')
-            continue;
-        attributes[toSnakeCase(name)] = value instanceof Date ? value.toISOString() : value;
-    }
-    return attributes;
-}
-function structuredLogAttributes(record) {
-    //  기록의 attribute 이름은 Message flow tracing 3.2가 고정한다. 로그 본문의
-    //  `zlink flow:` 축약 key(`kind`, `mesh` …)와 다른 집합이다 —
-    //  structuredLogBodyAttributes를 참고.
-    return compactAttributes({
-        event_id: record.eventId,
-        timestamp: record.timestamp.toISOString(),
-        phase: record.phase,
-        surface: record.surface,
-        message_kind: record.messageKind,
-        mesh_name: record.meshName,
-        channel_name: record.channelName,
-        channel_route_kind: record.channelRouteKind,
-        source_rid: record.sourceRid,
-        target_rid: record.targetRid,
-        server_rid: record.serverRid,
-        packet_name: record.packetName,
-        topic: record.topic,
-        spot_id: record.spotId,
-        instance_spot_type: record.instanceSpotType,
-        activation_state: record.activationState,
-        actor_id: record.actorId,
-        stream_session_id: record.streamSessionId,
-        correlation_id: record.correlationId,
-        flow_id: record.flowId,
-        flow_origin: record.flowOrigin,
-        outcome: record.outcome,
-        reason: record.reason,
-        action: record.action,
-        command_id: record.commandId,
-        error_type: record.errorType,
-        error_message: record.errorMessage,
-        error_cause_type: record.errorCauseType,
-        error_cause_message: record.errorCauseMessage,
-        message_size_bytes: record.messageSizeBytes,
-        duration_seconds: record.durationSeconds
-    });
-}
-function structuredLogBodyAttributes(record) {
-    //  `zlink flow:` 본문 전용 축약 key — Message flow tracing "Structured log 대체 표기".
-    return compactAttributes({
-        event: record.eventId,
-        phase: record.phase,
-        surface: record.surface,
-        kind: record.messageKind,
-        mesh: record.meshName,
-        channel: record.channelName,
-        channel_route: record.channelRouteKind,
-        source_rid: record.sourceRid,
-        target_rid: record.targetRid,
-        server_rid: record.serverRid,
-        packet: record.packetName,
-        topic: record.topic,
-        spot: record.spotId,
-        instance_type: record.instanceSpotType,
-        activation_state: record.activationState,
-        actor: record.actorId,
-        session: record.streamSessionId,
-        corr: record.correlationId,
-        flow: record.flowId,
-        origin: record.flowOrigin,
-        outcome: record.outcome,
-        reason: record.reason,
-        action: record.action,
-        error_type: record.errorType,
-        error_message: record.errorMessage,
-        size: record.messageSizeBytes
-    });
-}
-function structuredLogBody(record) {
-    return `zlink flow: ${Object.entries(structuredLogBodyAttributes(record))
-        .map(([key, value]) => `${key}=${String(value)}`)
-        .join(' ')}`;
-}
-function compactAttributes(values) {
-    const attributes = {};
-    for (const [key, value] of Object.entries(values)) {
-        if (value !== undefined)
-            attributes[key] = value;
-    }
-    return attributes;
-}
-function messageFlowPhase(outcome) {
-    switch (outcome) {
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received:
-            return 'received';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted:
-            return 'admitted';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched:
-            return 'dispatched';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed:
-            return 'completed';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied:
-            return 'replied';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped:
-            return 'dropped';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent:
-            return 'sent';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.ReplyReceived:
-            return 'reply_received';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured:
-            return 'backpressured';
-        case ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error:
-            return undefined;
-    }
-}
-function messageFlowOutcome(outcome) {
-    if (outcome === ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error)
-        return 'failed';
-    if (outcome === ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured)
-        return 'backpressured';
-    if (outcome === ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped)
-        return 'dropped';
-    return 'succeeded';
-}
-function messageFlowSurface(surface) {
-    switch (surface) {
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Node:
-            return 'node';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Channel:
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel:
-            return 'channel';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotRoute:
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription:
-            return 'spot';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot:
-            return 'instance_spot';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor:
-            return 'actor';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession:
-            return 'stream';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.ActorRelocation:
-            return 'actor_relocation';
-        case ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.ClassicFanout:
-            return 'classic_fanout';
-    }
-}
-function messageFlowKind(kind) {
-    switch (kind) {
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request:
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest:
-            return 'request';
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send:
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend:
-            return 'send';
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Response:
-            return 'response';
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Error:
-            return 'error';
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Control:
-            return 'control';
-        case ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Publish:
-            throw new Error('Classic fanout publish must not create a normal message-flow record.');
-    }
-}
-function channelRouteKind(surface) {
-    if (surface === ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel)
-        return 'route_mesh';
-    if (surface === ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Channel)
-        return 'client_server';
-    return undefined;
-}
 function hashFlowId(flowId) {
     let hash = 0x811c9dc5;
     for (let index = 0; index < flowId.length; index += 1) {
@@ -449,9 +207,3 @@ function hashFlowId(flowId) {
     }
     return hash >>> 0;
 }
-function boundedText(value) {
-    return value === undefined ? undefined : value.slice(0, dispatch_error_details_1.ERROR_MESSAGE_MAX_LENGTH);
-}
-function toSnakeCase(value) {
-    return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-}

package/dist/runtime/diagnostics/runtime-metrics.d.ts

@@ -111,7 +111,7 @@ export declare const METRIC_NAMES: Readonly<{
     readonly HostApplicationJobQueuePressureTransitions: "zlink.host.application_job_queue.pressure_transitions";
     readonly HostApplicationJobQueueFlowStateConfigFailures: "zlink.host.application_job_queue.flow_state_config_failures";
 }>;
-declare const COUNTERS: Readonly<{
+export declare const COUNTER_UNITS: Readonly<{
     readonly "zlink.stream.connections.opened": "{connection}";
     readonly "zlink.stream.connections.closed": "{connection}";
     readonly "zlink.mesh_node.channel.selection_failures": "{failure}";
@@ -147,7 +147,7 @@ declare const HISTOGRAMS: Readonly<{
     readonly "zlink.host.relocation.duration": "s";
     readonly "zlink.host.shutdown.duration": "s";
 }>;
-type CounterName = keyof typeof COUNTERS;
+type CounterName = keyof typeof COUNTER_UNITS;
 type UpDownName = keyof typeof UP_DOWN_COUNTERS;
 type HistogramName = keyof typeof HISTOGRAMS;
 export declare class ZLinkRuntimeMetrics {
@@ -155,6 +155,7 @@ export declare class ZLinkRuntimeMetrics {
     constructor(provider?: ZLinkMeterProvider);
     count(name: CounterName | string, value?: number, attributes?: ZLinkMetricAttributes): void;
     change(name: UpDownName | string, value: number, attributes?: ZLinkMetricAttributes): void;
+    recordSpotCount(meshName: string, kind: 'entry' | 'user' | 'instance', delta: number): void;
     duration(name: HistogramName | string, seconds: number, attributes?: ZLinkMetricAttributes): void;
     histogram(name: HistogramName | string, value: number, _unit: string, attributes?: ZLinkMetricAttributes): void;
     registerMeshSnapshots(provider: () => ReadonlyArray<ZLinkRuntimeMetricMeshSnapshot>): ZLinkRuntimeMetricRegistration;
@@ -168,7 +169,7 @@ export declare class ZLinkRuntimeMetrics {
     recordChannelSelectionFailure(meshName: string, channelName: string, reason: string): void;
     recordMessageDropped(meshName: string, surface: string, messageKind: string, reason: string): void;
     startInstanceSpotActivation(meshName: string, instanceSpotType: string): ZLinkRuntimeMetricOperation;
-    startRelocation(meshName: string, objectKind: 'actor' | 'user_spot' | 'instance_spot', policy: 'recreate' | 'snapshot'): ZLinkRelocationMetricOperation;
+    startRelocation(meshName: string, objectKind: 'actor' | 'user_spot' | 'instance_spot', policy: 'recreate' | 'snapshot', onComplete?: (outcome: string) => void): ZLinkRelocationMetricOperation;
     recordInstanceSpotClaimConflict(meshName: string, instanceSpotType: string, reason: string): void;
     recordInstanceSpotTakeover(meshName: string, instanceSpotType: string, outcome: string): void;
     enabled(): boolean;

package/dist/runtime/diagnostics/runtime-metrics.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkRequestMetricOperation = exports.ZLinkRuntimeMetrics = exports.METRIC_NAMES = exports.NANOSECONDS_PER_SECOND = exports.MILLISECONDS_PER_SECOND = void 0;
+exports.ZLinkRequestMetricOperation = exports.ZLinkRuntimeMetrics = exports.COUNTER_UNITS = exports.METRIC_NAMES = exports.NANOSECONDS_PER_SECOND = exports.MILLISECONDS_PER_SECOND = void 0;
 const api_1 = require("@opentelemetry/api");
 const contracts_1 = require("../../contracts");
 exports.MILLISECONDS_PER_SECOND = 1000;
@@ -66,7 +66,7 @@ exports.METRIC_NAMES = Object.freeze({
     HostApplicationJobQueuePressureTransitions: 'zlink.host.application_job_queue.pressure_transitions',
     HostApplicationJobQueueFlowStateConfigFailures: 'zlink.host.application_job_queue.flow_state_config_failures'
 });
-const COUNTERS = Object.freeze({
+exports.COUNTER_UNITS = Object.freeze({
     [exports.METRIC_NAMES.StreamConnectionsOpened]: '{connection}',
     [exports.METRIC_NAMES.StreamConnectionsClosed]: '{connection}',
     [exports.METRIC_NAMES.MeshNodeChannelSelectionFailures]: '{failure}',
@@ -144,7 +144,7 @@ class MetricRegistry {
     hostCapacities = new Set();
     applicationJobQueuePressures = new Set();
     constructor(meter) {
-        for (const [name, unit] of Object.entries(COUNTERS)) {
+        for (const [name, unit] of Object.entries(exports.COUNTER_UNITS)) {
             this.counters.set(name, meter.createCounter(name, { unit }));
         }
         for (const [name, unit] of Object.entries(UP_DOWN_COUNTERS)) {
@@ -350,6 +350,9 @@ class ZLinkRuntimeMetrics {
     change(name, value, attributes) {
         safe(() => this.registry.upDown.get(name)?.add(value, attributes));
     }
+    recordSpotCount(meshName, kind, delta) {
+        this.change(exports.METRIC_NAMES.SpotCount, delta, { mesh_name: meshName, spot_kind: kind });
+    }
     duration(name, seconds, attributes) {
         this.histogram(name, Math.max(0, seconds), 's', attributes);
     }
@@ -423,7 +426,7 @@ class ZLinkRuntimeMetrics {
             }
         };
     }
-    startRelocation(meshName, objectKind, policy) {
+    startRelocation(meshName, objectKind, policy, onComplete) {
         const started = process.hrtime.bigint();
         const startAttributes = { mesh_name: meshName, object_kind: objectKind, policy };
         let completed = false;
@@ -441,6 +444,7 @@ class ZLinkRuntimeMetrics {
                 const terminal = { ...startAttributes, outcome };
                 this.count(exports.METRIC_NAMES.RelocationCompleted, 1, terminal);
                 this.duration(exports.METRIC_NAMES.RelocationDuration, Number(process.hrtime.bigint() - started) / exports.NANOSECONDS_PER_SECOND, terminal);
+                onComplete?.(outcome);
             }
         };
     }

package/dist/runtime/execution/index.d.ts

@@ -10,6 +10,7 @@ interface ZLinkSpotSerialTurnExecutorLike {
     post<T>(operation: () => Promise<T> | T): Promise<T>;
 }
 export type ZLinkExecutionArea = 'application' | 'infrastructure';
+export declare const detachedMeshDispatchScope: <R, TArgs extends any[]>(fn: (...args: TArgs) => R, ...args: TArgs) => R;
 export declare function runZLinkExecutionArea<T>(area: ZLinkExecutionArea, operation: () => T): T;
 export declare function currentZLinkExecutionArea(): ZLinkExecutionArea | undefined;
 export declare function requireZLinkInfrastructureExecutionArea(): void;

package/dist/runtime/execution/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkFrameworkExecutionState = exports.ZLinkRuntimeTaskRunner = exports.ZLinkRuntimeTaskErrorSink = exports.ZLinkExecutionBarrier = exports.ZLinkSpotSerialTurn = exports.ZLinkStateLane = void 0;
+exports.ZLinkFrameworkExecutionState = exports.ZLinkRuntimeTaskRunner = exports.ZLinkRuntimeTaskErrorSink = exports.ZLinkExecutionBarrier = exports.ZLinkSpotSerialTurn = exports.detachedMeshDispatchScope = exports.ZLinkStateLane = void 0;
 exports.runZLinkExecutionArea = runZLinkExecutionArea;
 exports.currentZLinkExecutionArea = currentZLinkExecutionArea;
 exports.requireZLinkInfrastructureExecutionArea = requireZLinkInfrastructureExecutionArea;
@@ -11,12 +11,15 @@ exports.requireZLinkYieldTurn = requireZLinkYieldTurn;
 exports.captureZLinkExecutionTurn = captureZLinkExecutionTurn;
 exports.isCurrentZLinkSpotSerialTurn = isCurrentZLinkSpotSerialTurn;
 const node_async_hooks_1 = require("node:async_hooks");
+const state_lane_1 = require("./state-lane");
 const abort_1 = require("../abort");
 const framework_errors_internal_1 = require("../framework-errors-internal");
-var state_lane_1 = require("./state-lane");
-Object.defineProperty(exports, "ZLinkStateLane", { enumerable: true, get: function () { return state_lane_1.ZLinkStateLane; } });
+var state_lane_2 = require("./state-lane");
+Object.defineProperty(exports, "ZLinkStateLane", { enumerable: true, get: function () { return state_lane_2.ZLinkStateLane; } });
 const spotSerialTurnStorage = new node_async_hooks_1.AsyncLocalStorage();
 const executionAreaStorage = new node_async_hooks_1.AsyncLocalStorage();
+// Capture once through the execution owners, independently of module load scope.
+exports.detachedMeshDispatchScope = (0, state_lane_1.startOutsideStateLane)(() => executionAreaStorage.exit(() => spotSerialTurnStorage.exit(() => node_async_hooks_1.AsyncLocalStorage.snapshot())));
 function runZLinkExecutionArea(area, operation) {
     return executionAreaStorage.run(area, operation);
 }

package/dist/runtime/execution/serial-execution-queue.d.ts

@@ -33,16 +33,28 @@ export interface ZLinkSerialWorkPreparation {
     prepare(signal: AbortSignal): Promise<void>;
     cancel(): void;
 }
+type SerialWorkRecord<T> = Omit<ZLinkSerialWorkRecord<T>, 'acceptedSequence'> & {
+    acceptedSequence: bigint;
+    readonly operationEnvelope: boolean;
+    readonly mailbox?: ZLinkSerialExecutionQueue;
+    readonly preparation?: ZLinkSerialWorkPreparation;
+    preparationState: 'idle' | 'pending' | 'canceling' | 'ready' | 'failed';
+    preparationController?: AbortController;
+    preparationError?: unknown;
+};
+interface ZLinkSerialAdmissionLane {
+    readonly records: Array<SerialWorkRecord<unknown>>;
+}
 /**
  * One event-loop serial execution queue per Spot, Actor mailbox, or Stream session.
  * Application work carries the host permit through the queue until the handler starts.
  */
 export declare class ZLinkSerialExecutionQueue {
-    private readonly executeRecord;
+    readonly executeRecord: (record: ZLinkSerialWorkRecord<unknown>) => Promise<void>;
     private readonly sharedOwner?;
-    private readonly application;
-    private readonly lifecycle;
-    private activeLifecycle?;
+    readonly application: ZLinkSerialAdmissionLane;
+    readonly lifecycle: ZLinkSerialAdmissionLane;
+    activeLifecycle?: ZLinkSerialWorkRecord<unknown>;
     private activeRecord?;
     /** The admitted node itself owns ready membership; no second readiness flag. */
     private ownerMembership?;
@@ -54,7 +66,7 @@ export declare class ZLinkSerialExecutionQueue {
     private lifecycleDebt;
     private claimStartedAt?;
     private closed;
-    private readonly idleWaiters;
+    readonly idleWaiters: Array<() => void>;
     constructor(executeRecord: (record: ZLinkSerialWorkRecord<unknown>) => Promise<void>, options?: ZLinkSerialSchedulerOptions, sharedOwner?: ZLinkSerialExecutionQueue | undefined);
     submit<T>(operation: () => Promise<T> | T, options?: ZLinkSerialWorkOptions, context?: unknown): Promise<T>;
     submitDetached<T>(operation: () => Promise<T> | T, onError: (error: unknown) => void, options?: ZLinkSerialWorkOptions, context?: unknown): void;
@@ -79,22 +91,23 @@ export declare class ZLinkSerialExecutionQueue {
     /** Stops admission within the lifecycle operation that owns this queue's close. */
     closeAdmission(): void;
     get admissionClosed(): boolean;
-    private admit;
-    private scheduleDrain;
+    admit<T>(operation: () => Promise<T> | T, options: ZLinkSerialWorkOptions | undefined, context?: unknown, preparation?: ZLinkSerialWorkPreparation, operationEnvelope?: boolean): Promise<T>;
+    scheduleDrain(): void;
     /** Notifications carry no payload, admission sequence, result Promise, or host permit. */
-    private enqueueMailboxTurn;
+    enqueueMailboxTurn(operation: () => void): void;
     /** Called only by the shared scheduler's consumer, never by a producer. */
     private consumeMailbox;
     private finishMailbox;
-    private drain;
+    drain(): Promise<void>;
     private prepareSelected;
-    private selectNext;
-    private takeSelected;
+    selectNext(): SerialWorkRecord<unknown> | undefined;
+    takeSelected(selected: SerialWorkRecord<unknown>): ZLinkSerialWorkRecord<unknown>;
     private takeLifecycle;
-    private takeApplication;
+    takeApplication(selected: SerialWorkRecord<unknown>): ZLinkSerialWorkRecord<unknown>;
     private startPreparation;
     /** Returns false while an outstanding readiness attempt is being canceled. */
     private cancelPreparationForRearbitration;
     private shouldYield;
-    private resolveIdleWaiters;
+    resolveIdleWaiters(): void;
 }
+export {};