@zlink-systems/framework 0.26.0 → 0.27.0

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

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

package/src/runtime/diagnostics/runtime-metrics.ts

@@ -1,11 +1,14 @@
-import type {
-  ZLinkHostCapacityStatus,
-  ZLinkMeter,
-  ZLinkMeterProvider,
-  ZLinkMetricAttributes
-} from '../../contracts';
-import { ZLinkMeters } from '../../contracts';
 import { metrics as openTelemetryMetrics } from '@opentelemetry/api';
+import {
+  type ZLinkHostCapacityStatus,
+  type ZLinkMeter,
+  type ZLinkMeterProvider,
+  type ZLinkMetricAttributes,
+  ZLinkMeters
+} from '../../contracts';
+
+export const MILLISECONDS_PER_SECOND = 1000;
+export const NANOSECONDS_PER_SECOND = 1e9;
 
 type CounterInstrument = ReturnType<ZLinkMeter['createCounter']>;
 type UpDownInstrument = ReturnType<ZLinkMeter['createUpDownCounter']>;
@@ -80,78 +83,143 @@ export interface ZLinkRelocationMetricOperation extends ZLinkRuntimeMetricOperat
   recordBytes(bytes: number): void;
 }
 
+export const METRIC_NAMES = Object.freeze({
+  StreamConnectionsOpened: 'zlink.stream.connections.opened',
+  StreamConnectionsClosed: 'zlink.stream.connections.closed',
+  MeshNodeChannelSelectionFailures: 'zlink.mesh_node.channel.selection_failures',
+  MeshNodeRequestTimeouts: 'zlink.mesh_node.request.timeouts',
+  MeshNodeMessagesDropped: 'zlink.mesh_node.messages.dropped',
+  RelocationStarted: 'zlink.relocation.started',
+  RelocationCompleted: 'zlink.relocation.completed',
+  RelocationCutoverTimeout: 'zlink.relocation.cutover_timeout',
+  InstanceSpotActivations: 'zlink.instance_spot.activations',
+  InstanceSpotClaimConflicts: 'zlink.instance_spot.claim.conflicts',
+  InstanceSpotTakeovers: 'zlink.instance_spot.takeovers',
+  LocationStoreErrors: 'zlink.location.store.errors',
+  LocationOwnerLeaseRenewFailures: 'zlink.location.owner_lease.renew.failures',
+  ObservabilityEventsOverflow: 'zlink.observability.events.overflow',
+  HostRelocationBlocked: 'zlink.host.relocation.blocked',
+  HostShutdownForced: 'zlink.host.shutdown.forced',
+  StreamConnectionsActive: 'zlink.stream.connections.active',
+  SpotCount: 'zlink.spot.count',
+  ActorCount: 'zlink.actor.count',
+  MeshNodeRequestsInflight: 'zlink.mesh_node.requests.inflight',
+  MeshNodeRequestDuration: 'zlink.mesh_node.request.duration',
+  RelocationDuration: 'zlink.relocation.duration',
+  RelocationBytes: 'zlink.relocation.bytes',
+  RelocationInterruption: 'zlink.relocation.interruption',
+  RelocationTargetResume: 'zlink.relocation.target_resume',
+  RelocationRouteConvergence: 'zlink.relocation.route_convergence',
+  InstanceSpotActivationDuration: 'zlink.instance_spot.activation.duration',
+  LocationOwnerLeaseRenewLateness: 'zlink.location.owner_lease.renew.lateness',
+  HostRelocationDuration: 'zlink.host.relocation.duration',
+  HostShutdownDuration: 'zlink.host.shutdown.duration',
+  MeshNodePeersConfigured: 'zlink.mesh_node.peers.configured',
+  MeshNodePeersConnected: 'zlink.mesh_node.peers.connected',
+  MeshNodePeersReady: 'zlink.mesh_node.peers.ready',
+  MeshNodeChannelsReadyMembers: 'zlink.mesh_node.channels.ready_members',
+  ObjectCapacityActive: 'zlink.object.capacity.active',
+  ObjectCapacityReserved: 'zlink.object.capacity.reserved',
+  ObjectCapacityLimit: 'zlink.object.capacity.limit',
+  SpotTypeCapacityActive: 'zlink.spot.type.capacity.active',
+  SpotTypeCapacityReserved: 'zlink.spot.type.capacity.reserved',
+  SpotTypeCapacityLimit: 'zlink.spot.type.capacity.limit',
+  ObjectActivationActive: 'zlink.object.activation.active',
+  ObjectActivationLimit: 'zlink.object.activation.limit',
+  InstanceSpotPendingMessages: 'zlink.instance_spot.pending.messages',
+  InstanceSpotPendingBytes: 'zlink.instance_spot.pending.bytes',
+  HostState: 'zlink.host.state',
+  HostCoreHwmEffectiveBudget: 'zlink.host.core_hwm.effective_budget',
+  HostCoreHwmApplied: 'zlink.host.core_hwm.applied',
+  HostCoreHwmAccounted: 'zlink.host.core_hwm.accounted',
+  HostCoreHwmCompletionAccounted: 'zlink.host.core_hwm.completion_accounted',
+  HostCoreHwmBlockedRatio: 'zlink.host.core_hwm.blocked_ratio',
+  HostApplicationJobQueueLimit: 'zlink.host.application_job_queue.limit',
+  HostApplicationJobQueueJobs: 'zlink.host.application_job_queue.jobs',
+  HostApplicationJobQueueCapacityWaiters: 'zlink.host.application_job_queue.capacity_waiters',
+  HostApplicationJobQueuePressureState: 'zlink.host.application_job_queue.pressure_state',
+  HostApplicationJobQueuePauseDuration: 'zlink.host.application_job_queue.pause_duration',
+  HostApplicationJobQueueCapacityWaits: 'zlink.host.application_job_queue.capacity_waits',
+  HostApplicationJobQueueCapacityWaitDuration:
+    'zlink.host.application_job_queue.capacity_wait_duration',
+  HostApplicationJobQueuePressureTransitions:
+    'zlink.host.application_job_queue.pressure_transitions',
+  HostApplicationJobQueueFlowStateConfigFailures:
+    'zlink.host.application_job_queue.flow_state_config_failures'
+} as const);
+
 const COUNTERS = Object.freeze({
-  'zlink.stream.connections.opened': '{connection}',
-  'zlink.stream.connections.closed': '{connection}',
-  'zlink.mesh_node.channel.selection_failures': '{failure}',
-  'zlink.mesh_node.request.timeouts': '{request}',
-  'zlink.mesh_node.messages.dropped': '{message}',
-  'zlink.relocation.started': '{relocation}',
-  'zlink.relocation.completed': '{relocation}',
-  'zlink.relocation.cutover_timeout': '{fallback}',
-  'zlink.instance_spot.activations': '{activation}',
-  'zlink.instance_spot.claim.conflicts': '{claim}',
-  'zlink.instance_spot.takeovers': '{takeover}',
-  'zlink.location.store.errors': '{error}',
-  'zlink.location.owner_lease.renew.failures': '{failure}',
-  'zlink.observability.events.overflow': '{event}',
-  'zlink.host.relocation.blocked': '{operation}',
-  'zlink.host.shutdown.forced': '{operation}'
+  [METRIC_NAMES.StreamConnectionsOpened]: '{connection}',
+  [METRIC_NAMES.StreamConnectionsClosed]: '{connection}',
+  [METRIC_NAMES.MeshNodeChannelSelectionFailures]: '{failure}',
+  [METRIC_NAMES.MeshNodeRequestTimeouts]: '{request}',
+  [METRIC_NAMES.MeshNodeMessagesDropped]: '{message}',
+  [METRIC_NAMES.RelocationStarted]: '{relocation}',
+  [METRIC_NAMES.RelocationCompleted]: '{relocation}',
+  [METRIC_NAMES.RelocationCutoverTimeout]: '{fallback}',
+  [METRIC_NAMES.InstanceSpotActivations]: '{activation}',
+  [METRIC_NAMES.InstanceSpotClaimConflicts]: '{claim}',
+  [METRIC_NAMES.InstanceSpotTakeovers]: '{takeover}',
+  [METRIC_NAMES.LocationStoreErrors]: '{error}',
+  [METRIC_NAMES.LocationOwnerLeaseRenewFailures]: '{failure}',
+  [METRIC_NAMES.ObservabilityEventsOverflow]: '{event}',
+  [METRIC_NAMES.HostRelocationBlocked]: '{operation}',
+  [METRIC_NAMES.HostShutdownForced]: '{operation}'
 } as const);
 
 const UP_DOWN_COUNTERS = Object.freeze({
-  'zlink.stream.connections.active': '{connection}',
-  'zlink.spot.count': '{spot}',
-  'zlink.actor.count': '{actor}',
-  'zlink.mesh_node.requests.inflight': '{request}'
+  [METRIC_NAMES.StreamConnectionsActive]: '{connection}',
+  [METRIC_NAMES.SpotCount]: '{spot}',
+  [METRIC_NAMES.ActorCount]: '{actor}',
+  [METRIC_NAMES.MeshNodeRequestsInflight]: '{request}'
 } as const);
 
 const HISTOGRAMS = Object.freeze({
-  'zlink.mesh_node.request.duration': 's',
-  'zlink.relocation.duration': 's',
-  'zlink.relocation.bytes': 'By',
-  'zlink.relocation.interruption': 's',
-  'zlink.relocation.target_resume': 's',
-  'zlink.relocation.route_convergence': 's',
-  'zlink.instance_spot.activation.duration': 's',
-  'zlink.location.owner_lease.renew.lateness': 's',
-  'zlink.host.relocation.duration': 's',
-  'zlink.host.shutdown.duration': 's'
+  [METRIC_NAMES.MeshNodeRequestDuration]: 's',
+  [METRIC_NAMES.RelocationDuration]: 's',
+  [METRIC_NAMES.RelocationBytes]: 'By',
+  [METRIC_NAMES.RelocationInterruption]: 's',
+  [METRIC_NAMES.RelocationTargetResume]: 's',
+  [METRIC_NAMES.RelocationRouteConvergence]: 's',
+  [METRIC_NAMES.InstanceSpotActivationDuration]: 's',
+  [METRIC_NAMES.LocationOwnerLeaseRenewLateness]: 's',
+  [METRIC_NAMES.HostRelocationDuration]: 's',
+  [METRIC_NAMES.HostShutdownDuration]: 's'
 } as const);
 
 const OBSERVABLE_GAUGES = Object.freeze({
-  'zlink.mesh_node.peers.configured': '{peer}',
-  'zlink.mesh_node.peers.connected': '{peer}',
-  'zlink.mesh_node.peers.ready': '{peer}',
-  'zlink.mesh_node.channels.ready_members': '{member}',
-  'zlink.object.capacity.active': '{object}',
-  'zlink.object.capacity.reserved': '{object}',
-  'zlink.object.capacity.limit': '{object}',
-  'zlink.spot.type.capacity.active': '{spot}',
-  'zlink.spot.type.capacity.reserved': '{spot}',
-  'zlink.spot.type.capacity.limit': '{spot}',
-  'zlink.object.activation.active': '{activation}',
-  'zlink.object.activation.limit': '{activation}',
-  'zlink.instance_spot.pending.messages': '{message}',
-  'zlink.instance_spot.pending.bytes': 'By',
-  'zlink.host.state': '{runtime}',
-  'zlink.host.core_hwm.effective_budget': 'By',
-  'zlink.host.core_hwm.applied': 'By',
-  'zlink.host.core_hwm.accounted': 'By',
-  'zlink.host.core_hwm.completion_accounted': 'By',
-  'zlink.host.core_hwm.blocked_ratio': '{ppm}',
-  'zlink.host.application_job_queue.limit': '{job}',
-  'zlink.host.application_job_queue.jobs': '{job}',
-  'zlink.host.application_job_queue.capacity_waiters': '{waiter}',
-  'zlink.host.application_job_queue.pressure_state': '{state}',
-  'zlink.host.application_job_queue.pause_duration': 's'
+  [METRIC_NAMES.MeshNodePeersConfigured]: '{peer}',
+  [METRIC_NAMES.MeshNodePeersConnected]: '{peer}',
+  [METRIC_NAMES.MeshNodePeersReady]: '{peer}',
+  [METRIC_NAMES.MeshNodeChannelsReadyMembers]: '{member}',
+  [METRIC_NAMES.ObjectCapacityActive]: '{object}',
+  [METRIC_NAMES.ObjectCapacityReserved]: '{object}',
+  [METRIC_NAMES.ObjectCapacityLimit]: '{object}',
+  [METRIC_NAMES.SpotTypeCapacityActive]: '{spot}',
+  [METRIC_NAMES.SpotTypeCapacityReserved]: '{spot}',
+  [METRIC_NAMES.SpotTypeCapacityLimit]: '{spot}',
+  [METRIC_NAMES.ObjectActivationActive]: '{activation}',
+  [METRIC_NAMES.ObjectActivationLimit]: '{activation}',
+  [METRIC_NAMES.InstanceSpotPendingMessages]: '{message}',
+  [METRIC_NAMES.InstanceSpotPendingBytes]: 'By',
+  [METRIC_NAMES.HostState]: '{runtime}',
+  [METRIC_NAMES.HostCoreHwmEffectiveBudget]: 'By',
+  [METRIC_NAMES.HostCoreHwmApplied]: 'By',
+  [METRIC_NAMES.HostCoreHwmAccounted]: 'By',
+  [METRIC_NAMES.HostCoreHwmCompletionAccounted]: 'By',
+  [METRIC_NAMES.HostCoreHwmBlockedRatio]: '{ppm}',
+  [METRIC_NAMES.HostApplicationJobQueueLimit]: '{job}',
+  [METRIC_NAMES.HostApplicationJobQueueJobs]: '{job}',
+  [METRIC_NAMES.HostApplicationJobQueueCapacityWaiters]: '{waiter}',
+  [METRIC_NAMES.HostApplicationJobQueuePressureState]: '{state}',
+  [METRIC_NAMES.HostApplicationJobQueuePauseDuration]: 's'
 } as const);
 
 const OBSERVABLE_COUNTERS = Object.freeze({
-  'zlink.host.application_job_queue.capacity_waits': '{wait}',
-  'zlink.host.application_job_queue.capacity_wait_duration': 's',
-  'zlink.host.application_job_queue.pressure_transitions': '{transition}',
-  'zlink.host.application_job_queue.flow_state_config_failures': '{failure}'
+  [METRIC_NAMES.HostApplicationJobQueueCapacityWaits]: '{wait}',
+  [METRIC_NAMES.HostApplicationJobQueueCapacityWaitDuration]: 's',
+  [METRIC_NAMES.HostApplicationJobQueuePressureTransitions]: '{transition}',
+  [METRIC_NAMES.HostApplicationJobQueueFlowStateConfigFailures]: '{failure}'
 } as const);
 
 type CounterName = keyof typeof COUNTERS;
@@ -191,10 +259,10 @@ class MetricRegistry {
 
   private observe(name: string, result: ZLinkObservableResult): void {
     if (
-      name === 'zlink.host.application_job_queue.pressure_state' ||
-      name === 'zlink.host.application_job_queue.pressure_transitions' ||
-      name === 'zlink.host.application_job_queue.pause_duration' ||
-      name === 'zlink.host.application_job_queue.flow_state_config_failures'
+      name === METRIC_NAMES.HostApplicationJobQueuePressureState ||
+      name === METRIC_NAMES.HostApplicationJobQueuePressureTransitions ||
+      name === METRIC_NAMES.HostApplicationJobQueuePauseDuration ||
+      name === METRIC_NAMES.HostApplicationJobQueueFlowStateConfigFailures
     ) {
       for (const provider of this.applicationJobQueuePressures) {
         try {
@@ -218,7 +286,7 @@ class MetricRegistry {
       }
       return;
     }
-    if (name === 'zlink.host.state') {
+    if (name === METRIC_NAMES.HostState) {
       for (const provider of this.hostStates) {
         try {
           result.observe(1, { state: provider() });
@@ -245,15 +313,15 @@ class MetricRegistry {
     snapshot: ZLinkApplicationJobQueuePressureMetricSnapshot,
     result: ZLinkObservableResult
   ): void {
-    if (name === 'zlink.host.application_job_queue.pressure_state') {
+    if (name === METRIC_NAMES.HostApplicationJobQueuePressureState) {
       result.observe(1, { state: snapshot.pressureState });
-    } else if (name === 'zlink.host.application_job_queue.pressure_transitions') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueuePressureTransitions) {
       result.observe(metricNumber(snapshot.runningTransitionCount), { state: 'running' });
       result.observe(metricNumber(snapshot.pausedTransitionCount), { state: 'paused' });
-    } else if (name === 'zlink.host.application_job_queue.pause_duration') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueuePauseDuration) {
       result.observe(nonNegative(snapshot.currentPauseDurationSeconds), { state: 'current' });
       result.observe(nonNegative(snapshot.cumulativePauseDurationSeconds), { state: 'cumulative' });
-    } else if (name === 'zlink.host.application_job_queue.flow_state_config_failures') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueueFlowStateConfigFailures) {
       result.observe(metricNumber(snapshot.flowStateConfigFailureCount));
     }
   }
@@ -265,30 +333,30 @@ class MetricRegistry {
   ): void {
     const core = snapshot.coreHwm;
     const jobs = snapshot.applicationJobQueue;
-    if (name === 'zlink.host.core_hwm.effective_budget') {
+    if (name === METRIC_NAMES.HostCoreHwmEffectiveBudget) {
       result.observe(metricNumber(core.effectiveBudgetBytes));
-    } else if (name === 'zlink.host.core_hwm.applied') {
+    } else if (name === METRIC_NAMES.HostCoreHwmApplied) {
       result.observe(metricNumber(core.totalAppliedHwmBytes));
-    } else if (name === 'zlink.host.core_hwm.accounted') {
+    } else if (name === METRIC_NAMES.HostCoreHwmAccounted) {
       result.observe(metricNumber(core.currentAccountedBytes), { state: 'current' });
       result.observe(metricNumber(core.peakAccountedBytes), { state: 'peak' });
-    } else if (name === 'zlink.host.core_hwm.completion_accounted') {
+    } else if (name === METRIC_NAMES.HostCoreHwmCompletionAccounted) {
       result.observe(metricNumber(core.completionCurrentAccountedBytes), { state: 'current' });
       result.observe(metricNumber(core.completionPeakAccountedBytes), { state: 'peak' });
-    } else if (name === 'zlink.host.core_hwm.blocked_ratio') {
+    } else if (name === METRIC_NAMES.HostCoreHwmBlockedRatio) {
       result.observe(metricNumber(core.blockedRatioPpm));
-    } else if (name === 'zlink.host.application_job_queue.limit') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueueLimit) {
       result.observe(metricNumber(jobs.effectiveMaxQueuedApplicationJobs));
-    } else if (name === 'zlink.host.application_job_queue.jobs') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueueJobs) {
       result.observe(metricNumber(jobs.reservedSupplyPermits), { state: 'reserved' });
       result.observe(metricNumber(jobs.queuedApplicationJobs), { state: 'queued' });
       result.observe(metricNumber(jobs.permitsInUse), { state: 'in_use' });
       result.observe(metricNumber(jobs.peakPermitsInUse), { state: 'peak' });
-    } else if (name === 'zlink.host.application_job_queue.capacity_waiters') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueueCapacityWaiters) {
       result.observe(metricNumber(jobs.capacityWaiters));
-    } else if (name === 'zlink.host.application_job_queue.capacity_waits') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueueCapacityWaits) {
       result.observe(metricNumber(jobs.capacityWaitCount));
-    } else if (name === 'zlink.host.application_job_queue.capacity_wait_duration') {
+    } else if (name === METRIC_NAMES.HostApplicationJobQueueCapacityWaitDuration) {
       result.observe(nonNegative(jobs.capacityWaitDurationSeconds));
     }
   }
@@ -300,13 +368,13 @@ class MetricRegistry {
   ): void {
     const mesh = { mesh_name: snapshot.meshName };
     const peer = { ...mesh, source: snapshot.source };
-    if (name === 'zlink.mesh_node.peers.configured')
+    if (name === METRIC_NAMES.MeshNodePeersConfigured)
       result.observe(nonNegative(snapshot.configuredPeers), peer);
-    else if (name === 'zlink.mesh_node.peers.connected')
+    else if (name === METRIC_NAMES.MeshNodePeersConnected)
       result.observe(nonNegative(snapshot.connectedPeers), peer);
-    else if (name === 'zlink.mesh_node.peers.ready')
+    else if (name === METRIC_NAMES.MeshNodePeersReady)
       result.observe(nonNegative(snapshot.readyPeers), peer);
-    else if (name === 'zlink.mesh_node.channels.ready_members') {
+    else if (name === METRIC_NAMES.MeshNodeChannelsReadyMembers) {
       for (const channel of snapshot.channels) {
         result.observe(nonNegative(channel.readyMembers), {
           ...mesh,
@@ -332,18 +400,18 @@ class MetricRegistry {
           stable_type: capacity.stableType
         });
       }
-    } else if (name === 'zlink.object.activation.active') {
+    } else if (name === METRIC_NAMES.ObjectActivationActive) {
       result.observe(nonNegative(snapshot.activation.active), mesh);
-    } else if (name === 'zlink.object.activation.limit') {
+    } else if (name === METRIC_NAMES.ObjectActivationLimit) {
       result.observe(nonNegative(snapshot.activation.limit), mesh);
-    } else if (name === 'zlink.instance_spot.pending.messages') {
+    } else if (name === METRIC_NAMES.InstanceSpotPendingMessages) {
       for (const instance of snapshot.instanceSpots) {
         result.observe(nonNegative(instance.pendingMessages), {
           ...mesh,
           instance_spot_type: instance.instanceSpotType
         });
       }
-    } else if (name === 'zlink.instance_spot.pending.bytes') {
+    } else if (name === METRIC_NAMES.InstanceSpotPendingBytes) {
       for (const instance of snapshot.instanceSpots) {
         result.observe(nonNegative(instance.pendingBytes), {
           ...mesh,
@@ -429,11 +497,11 @@ export class ZLinkRuntimeMetrics {
   }
 
   recordLocationStoreError(operation: string): void {
-    this.count('zlink.location.store.errors', 1, { operation });
+    this.count(METRIC_NAMES.LocationStoreErrors, 1, { operation });
   }
 
   recordOwnerLeaseRenewFailure(scopeKind: 'mesh' | 'channel', scopeName: string): void {
-    this.count('zlink.location.owner_lease.renew.failures', 1, {
+    this.count(METRIC_NAMES.LocationOwnerLeaseRenewFailures, 1, {
       scope_kind: scopeKind,
       scope_name: scopeName
     });
@@ -444,14 +512,14 @@ export class ZLinkRuntimeMetrics {
     scopeKind: 'mesh' | 'channel',
     scopeName: string
   ): void {
-    this.duration('zlink.location.owner_lease.renew.lateness', seconds, {
+    this.duration(METRIC_NAMES.LocationOwnerLeaseRenewLateness, seconds, {
       scope_kind: scopeKind,
       scope_name: scopeName
     });
   }
 
   recordChannelSelectionFailure(meshName: string, channelName: string, reason: string): void {
-    this.count('zlink.mesh_node.channel.selection_failures', 1, {
+    this.count(METRIC_NAMES.MeshNodeChannelSelectionFailures, 1, {
       mesh_name: meshName,
       channel_name: channelName,
       reason
@@ -464,7 +532,7 @@ export class ZLinkRuntimeMetrics {
     messageKind: string,
     reason: string
   ): void {
-    this.count('zlink.mesh_node.messages.dropped', 1, {
+    this.count(METRIC_NAMES.MeshNodeMessagesDropped, 1, {
       mesh_name: meshName,
       surface,
       message_kind: messageKind,
@@ -487,10 +555,10 @@ export class ZLinkRuntimeMetrics {
           instance_spot_type: instanceSpotType,
           outcome
         };
-        this.count('zlink.instance_spot.activations', 1, attributes);
+        this.count(METRIC_NAMES.InstanceSpotActivations, 1, attributes);
         this.duration(
-          'zlink.instance_spot.activation.duration',
-          Number(process.hrtime.bigint() - started) / 1e9,
+          METRIC_NAMES.InstanceSpotActivationDuration,
+          Number(process.hrtime.bigint() - started) / NANOSECONDS_PER_SECOND,
           attributes
         );
       }
@@ -505,20 +573,20 @@ export class ZLinkRuntimeMetrics {
     const started = process.hrtime.bigint();
     const startAttributes = { mesh_name: meshName, object_kind: objectKind, policy };
     let completed = false;
-    this.count('zlink.relocation.started', 1, startAttributes);
+    this.count(METRIC_NAMES.RelocationStarted, 1, startAttributes);
     return {
       recordBytes: (bytes: number): void => {
         if (completed || bytes < 0) return;
-        this.histogram('zlink.relocation.bytes', bytes, 'By', startAttributes);
+        this.histogram(METRIC_NAMES.RelocationBytes, bytes, 'By', startAttributes);
       },
       complete: (outcome: string): void => {
         if (completed) return;
         completed = true;
         const terminal = { ...startAttributes, outcome };
-        this.count('zlink.relocation.completed', 1, terminal);
+        this.count(METRIC_NAMES.RelocationCompleted, 1, terminal);
         this.duration(
-          'zlink.relocation.duration',
-          Number(process.hrtime.bigint() - started) / 1e9,
+          METRIC_NAMES.RelocationDuration,
+          Number(process.hrtime.bigint() - started) / NANOSECONDS_PER_SECOND,
           terminal
         );
       }
@@ -530,7 +598,7 @@ export class ZLinkRuntimeMetrics {
     instanceSpotType: string,
     reason: string
   ): void {
-    this.count('zlink.instance_spot.claim.conflicts', 1, {
+    this.count(METRIC_NAMES.InstanceSpotClaimConflicts, 1, {
       mesh_name: meshName,
       instance_spot_type: instanceSpotType,
       reason
@@ -538,7 +606,7 @@ export class ZLinkRuntimeMetrics {
   }
 
   recordInstanceSpotTakeover(meshName: string, instanceSpotType: string, outcome: string): void {
-    this.count('zlink.instance_spot.takeovers', 1, {
+    this.count(METRIC_NAMES.InstanceSpotTakeovers, 1, {
       mesh_name: meshName,
       instance_spot_type: instanceSpotType,
       outcome
@@ -559,21 +627,21 @@ export class ZLinkRequestMetricOperation {
     private readonly meshName: string,
     private readonly surface: 'node' | 'channel' | 'spot' | 'instance_spot' | 'actor'
   ) {
-    metrics.change('zlink.mesh_node.requests.inflight', 1, this.baseAttributes());
+    metrics.change(METRIC_NAMES.MeshNodeRequestsInflight, 1, this.baseAttributes());
   }
 
   complete(outcome: string): void {
     if (this.completed) return;
     this.completed = true;
     const attributes = this.baseAttributes();
-    this.metrics.change('zlink.mesh_node.requests.inflight', -1, attributes);
+    this.metrics.change(METRIC_NAMES.MeshNodeRequestsInflight, -1, attributes);
     this.metrics.duration(
-      'zlink.mesh_node.request.duration',
-      Number(process.hrtime.bigint() - this.started) / 1e9,
+      METRIC_NAMES.MeshNodeRequestDuration,
+      Number(process.hrtime.bigint() - this.started) / NANOSECONDS_PER_SECOND,
       { ...attributes, outcome }
     );
     if (outcome === 'timed_out') {
-      this.metrics.count('zlink.mesh_node.request.timeouts', 1, attributes);
+      this.metrics.count(METRIC_NAMES.MeshNodeRequestTimeouts, 1, attributes);
     }
   }
 

package/src/runtime/diagnostics/runtime-observation-queue.ts

@@ -1,3 +1,4 @@
+import { shouldCompactBackingArray } from '../admission';
 import type { ZLinkObservationLoss, ZLinkObservedStatus } from '../../contracts';
 
 export const ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY = 64;
@@ -291,7 +292,7 @@ export class RuntimeEventQueue<T>
     if (this.terminalCount === 0) {
       this.terminalFifo.length = 0;
       this.terminalHead = 0;
-    } else if (this.terminalHead >= 1024 && this.terminalHead * 2 >= this.terminalFifo.length) {
+    } else if (shouldCompactBackingArray(this.terminalHead, this.terminalFifo.length)) {
       this.terminalFifo.splice(0, this.terminalHead);
       this.terminalHead = 0;
     }
@@ -333,7 +334,7 @@ export class RuntimeEventQueue<T>
     if (this.waitersCount === 0) {
       this.waiters.length = 0;
       this.waitersHead = 0;
-    } else if (this.waitersHead >= 1024 && this.waitersHead * 2 >= this.waiters.length) {
+    } else if (shouldCompactBackingArray(this.waitersHead, this.waiters.length)) {
       this.waiters.splice(0, this.waitersHead);
       this.waitersHead = 0;
     }