@semiont/observability 0.5.29 → 0.5.31

package/dist/index.d.ts

@@ -110,12 +110,67 @@ interface JobQueueSnapshot {
     failed: number;
     cancelled: number;
 }
+/**
+ * A correlated reply was withheld from a subscriber that does not own its
+ * correlationId (CORRELATED-REPLY-ROUTING P5).
+ *
+ * Counts ONLY that case. A frame with no correlationId is a shape violation
+ * (warned, not counted), and a cid nobody claimed is the structural in-process
+ * case that fires constantly — counting either would drown the signal this
+ * metric exists to show: the fan-out amplification the delivery filter removes.
+ */
+declare function recordReplySuppressed(channel: string): void;
+/**
+ * An SSE resume could not be served and the client was told to fall back to
+ * cache. This degradation is CORRECT by design and therefore silent — which is
+ * exactly why it needs a number. A rising rate means clients are losing
+ * history, and nothing else in the stack says so.
+ */
+declare function recordResumeGap(reason: string): void;
+/**
+ * A request-shaped emit reached no subscriber, so the gateway synthesized its
+ * mapped failure (ARCHIVIST-STAYS-UP P3). By channel, this is the absence rate
+ * of the service that answers it — the difference between "it went down once"
+ * and "it is flapping."
+ */
+declare function recordUnanswerableRequest(channel: string): void;
+/** Claims held and reply payloads retained by a gateway's correlation registry. */
+interface CorrelationRegistrySnapshot {
+    claims: number;
+    retainedReplies: number;
+}
+/**
+ * Register a callback returning the gateway's correlation-registry occupancy.
+ *
+ * COUNTS, not bytes: retention is count-budgeted today (byte-budgeting is a
+ * known limit in CORRELATED-REPLY-ROUTING), so `retainedReplies` is a proxy for
+ * heap, not a measure of it. It is still the closest observable to the question
+ * two OOM investigations keep asking — a browse result can be 1-2 MB, and up to
+ * REPLY_RETENTION_MAX of them are held at once.
+ */
+declare function registerCorrelationRegistryProvider(provider: () => CorrelationRegistrySnapshot): void;
 /** Increment the bus-emit counter. Called at every transport `emit` site. */
 declare function recordBusEmit(channel: string, scope?: string): void;
 /** Record an in-process actor handler's duration. */
 declare function recordHandlerDuration(actor: string, channel: string, durationMs: number): void;
 /** Record a worker job's outcome and duration. */
 declare function recordJobOutcome(jobType: string, outcome: 'completed' | 'failed', durationMs: number): void;
+/**
+ * Record one stage of `EventStore.appendEvent` (ARCHIVIST-STAYS-UP P7).
+ *
+ * The append path is the one operation only the Archivist can perform, and it
+ * was entirely dark: reads had `recordHandlerDuration` and the bus had its own
+ * counters, while writes had nothing. Stage-labeled because the useful
+ * question is never "was the append slow" but WHICH PART — and `materialize`
+ * in particular does work proportional to a resource's annotation count, so it
+ * degrades with history rather than with load.
+ */
+declare function recordAppendStage(stage: 'persist' | 'materialize' | 'enrich' | 'publish', durationMs: number): void;
+/**
+ * Record a git invocation. Read the `add` count against events appended: one
+ * per event means deferred staging has stopped deduping.
+ */
+declare function recordGitCommand(command: string, durationMs: number): void;
 /**
  * Record a gather degraded by a projection read barrier: `'vectors'` — the
  * Smelter settle barrier timed out (semanticContext shipped absent);
@@ -142,6 +197,18 @@ declare function registerJobQueueProvider(provider: () => Promise<JobQueueSnapsh
  * (point count). Async to allow remote queries (Qdrant). Polled at
  * the metric-collection interval.
  */
+/**
+ * Register the Archivist's fact-pump backlog — facts appended to the record
+ * but not yet republished onto the bus.
+ *
+ * At rest this is zero. A value that climbs and does not come back means the
+ * pump is outrunning its transport, which is the leading hypothesis for the
+ * load-correlated heap growth in `bugs/absent-archivist-wedges-browse.md`
+ * (ARCHIVIST-STAYS-UP P5). The backlog is deliberately unbounded today, so
+ * this number is the only thing standing between "the pump is behind" and an
+ * OOM whose cause is inferred from RSS after the fact.
+ */
+declare function registerFactPumpDepthProvider(provider: () => number): void;
 declare function registerVectorIndexSizeProvider(provider: () => Promise<number> | number): void;
 /**
  * Record an inference call. Token counts are optional — providers that
@@ -156,6 +223,52 @@ declare function recordInferenceUsage(opts: {
     inputTokens?: number;
     outputTokens?: number;
 }): void;
+/**
+ * Record one detection model call (DETECTION-QUALITY-THROUGHPUT P1).
+ *
+ * The adapters already record provider/model/duration/tokens for every
+ * inference call. What they cannot know is the detection shape around it:
+ * which motivation asked, how big the piece was, how many annotations came
+ * back, how deep subdivision had descended, and whether this was the floor
+ * re-roll. Those are the facts that distinguish a healthy call from a
+ * expensive descent, and without them a slow detection run is one
+ * undifferentiated number.
+ *
+ * FAILED attempts are recorded too, and that is the point: the calls paid for
+ * and thrown away during a descent are exactly the cost later phases exist to
+ * avoid, so a record only of successes would hide the thing being optimized.
+ *
+ * Tokens are the PROVIDER's counts, passed through — never estimated. Absent
+ * means the provider did not report them.
+ */
+declare function recordDetectionCall(opts: {
+    label: string;
+    pieceChars: number;
+    durationMs: number;
+    items: number;
+    depth: number;
+    reroll: boolean;
+    outcome: 'success' | 'truncated' | 'timeout' | 'collapsed' | 'error';
+    inputTokens?: number;
+    outputTokens?: number;
+}): void;
+/**
+ * Record how one annotation got anchored (DETECTION-QUALITY-THROUGHPUT P5).
+ *
+ * The selector-vs-source check is already a WRITE-TIME INVARIANT — both
+ * `buildTextAnnotation` and `buildPdfAnnotation` throw on a selector that does
+ * not match its source — so mechanical correctness is guaranteed rather than
+ * sampled, and auditing it would measure a constant.
+ *
+ * What is genuinely uncertain is which anchoring METHOD got there. An `exact`
+ * the model quoted verbatim and that appears once is certain; one resolved by
+ * `first-of-many` (several occurrences, no usable context) or `fuzzy-match`
+ * picked a plausible occurrence and may have picked wrong. Those were visible
+ * only as log warnings — countable by a human reading worker output, which is
+ * how 47 of them went unreviewed. As a rate they are the precision number that
+ * sits beside the yield numbers.
+ */
+declare function recordAnchorOutcome(label: string, method: string): void;
 
-export { extractTraceparent, getActiveTraceparent, getLogTraceContext, injectTraceparent, recordBusEmit, recordGatherDegrade, recordHandlerDuration, recordInferenceUsage, recordJobOutcome, recordSubscriberConnect, recordSubscriberDisconnect, registerJobQueueProvider, registerVectorIndexSizeProvider, withActorSpan, withSpan, withTraceparent };
-export type { JobQueueSnapshot, TraceCarrier };
+export { extractTraceparent, getActiveTraceparent, getLogTraceContext, injectTraceparent, recordAnchorOutcome, recordAppendStage, recordBusEmit, recordDetectionCall, recordGatherDegrade, recordGitCommand, recordHandlerDuration, recordInferenceUsage, recordJobOutcome, recordReplySuppressed, recordResumeGap, recordSubscriberConnect, recordSubscriberDisconnect, recordUnanswerableRequest, registerCorrelationRegistryProvider, registerFactPumpDepthProvider, registerJobQueueProvider, registerVectorIndexSizeProvider, withActorSpan, withSpan, withTraceparent };
+export type { CorrelationRegistrySnapshot, JobQueueSnapshot, TraceCarrier };

package/dist/index.js

@@ -85,6 +85,11 @@ function getLogTraceContext() {
 var METER_NAME = "semiont";
 var meter = () => metrics.getMeter(METER_NAME);
 var _busEmitCounter;
+var _replySuppressedCounter;
+var _resumeGapCounter;
+var _unanswerableCounter;
+var _correlationRegistryGauge;
+var _correlationRegistryProvider;
 var _handlerDurationHistogram;
 var _jobOutcomeCounter;
 var _jobDurationHistogram;
@@ -96,6 +101,8 @@ var _sseSubscribers;
 var _jobQueueGauge;
 var _jobQueueProvider;
 var _vectorIndexSizeGauge;
+var _factPumpDepthGauge;
+var _factPumpDepthProvider;
 var _vectorIndexSizeProvider;
 function busEmitCounter() {
   if (!_busEmitCounter) {
@@ -164,6 +171,53 @@ function sseSubscribersCounter() {
   }
   return _sseSubscribers;
 }
+function replySuppressedCounter() {
+  if (!_replySuppressedCounter) {
+    _replySuppressedCounter = meter().createCounter("semiont.bus.reply.suppressed", {
+      description: "Correlated replies withheld from a non-owning subscriber"
+    });
+  }
+  return _replySuppressedCounter;
+}
+function recordReplySuppressed(channel) {
+  replySuppressedCounter().add(1, { "bus.channel": channel });
+}
+function resumeGapCounter() {
+  if (!_resumeGapCounter) {
+    _resumeGapCounter = meter().createCounter("semiont.bus.resume_gap", {
+      description: "SSE resumes that degraded to a gap because replay was unavailable"
+    });
+  }
+  return _resumeGapCounter;
+}
+function recordResumeGap(reason) {
+  resumeGapCounter().add(1, { "bus.resume_gap.reason": reason });
+}
+function unanswerableCounter() {
+  if (!_unanswerableCounter) {
+    _unanswerableCounter = meter().createCounter("semiont.bus.unanswerable", {
+      description: "Request emits that reached zero subscribers and were failed at the gateway"
+    });
+  }
+  return _unanswerableCounter;
+}
+function recordUnanswerableRequest(channel) {
+  unanswerableCounter().add(1, { "bus.channel": channel });
+}
+function registerCorrelationRegistryProvider(provider) {
+  _correlationRegistryProvider = provider;
+  if (!_correlationRegistryGauge) {
+    _correlationRegistryGauge = meter().createObservableGauge("semiont.bus.correlation.size", {
+      description: "Correlation registry occupancy: live claims and retained reply payloads"
+    });
+    _correlationRegistryGauge.addCallback((observer) => {
+      if (!_correlationRegistryProvider) return;
+      const snap = _correlationRegistryProvider();
+      observer.observe(snap.claims, { "correlation.kind": "claims" });
+      observer.observe(snap.retainedReplies, { "correlation.kind": "retained_replies" });
+    });
+  }
+}
 function recordBusEmit(channel, scope) {
   busEmitCounter().add(1, {
     "bus.channel": channel,
@@ -180,6 +234,32 @@ function recordJobOutcome(jobType, outcome, durationMs) {
   jobOutcomeCounter().add(1, { "job.type": jobType, "job.outcome": outcome });
   jobDurationHistogram().record(durationMs, { "job.type": jobType, "job.outcome": outcome });
 }
+var _appendStageHistogram;
+function appendStageHistogram() {
+  if (!_appendStageHistogram) {
+    _appendStageHistogram = meter().createHistogram("semiont.record.append.duration", {
+      description: "Time spent in one stage of appending an event to the record, labeled by stage: persist (JSONL write + git), materialize (view rebuild), enrich, publish. The Archivist's core write path.",
+      unit: "ms"
+    });
+  }
+  return _appendStageHistogram;
+}
+function recordAppendStage(stage, durationMs) {
+  appendStageHistogram().record(durationMs, { "record.stage": stage });
+}
+var _gitCommandHistogram;
+function gitCommandHistogram() {
+  if (!_gitCommandHistogram) {
+    _gitCommandHistogram = meter().createHistogram("semiont.git.duration", {
+      description: "Wall time of a git subprocess. Async \u2014 this is latency, not event-loop blockage. Staging is deduped, so the `add` count is far below the number of appended events.",
+      unit: "ms"
+    });
+  }
+  return _gitCommandHistogram;
+}
+function recordGitCommand(command, durationMs) {
+  gitCommandHistogram().record(durationMs, { "git.command": command });
+}
 function gatherDegradeCounter() {
   if (!_gatherDegradeCounter) {
     _gatherDegradeCounter = meter().createCounter("semiont.gather.degraded", {
@@ -214,6 +294,17 @@ function registerJobQueueProvider(provider) {
     });
   }
 }
+function registerFactPumpDepthProvider(provider) {
+  _factPumpDepthProvider = provider;
+  if (!_factPumpDepthGauge) {
+    _factPumpDepthGauge = meter().createObservableGauge("semiont.archivist.fact_pump.depth", {
+      description: "Facts appended to the record but not yet published to the bus. Zero at rest; a rising floor means the pump is behind its transport."
+    });
+    _factPumpDepthGauge.addCallback((observer) => {
+      if (_factPumpDepthProvider) observer.observe(_factPumpDepthProvider());
+    });
+  }
+}
 function registerVectorIndexSizeProvider(provider) {
   _vectorIndexSizeProvider = provider;
   if (!_vectorIndexSizeGauge) {
@@ -251,7 +342,73 @@ function recordInferenceUsage(opts) {
     });
   }
 }
+var _detectionCallCounter;
+var _detectionDurationHistogram;
+var _detectionItemsHistogram;
+var _detectionTokensHistogram;
+function detectionCallCounter() {
+  if (!_detectionCallCounter) {
+    _detectionCallCounter = meter().createCounter("semiont.detection.calls", {
+      description: "Detection model calls, labeled by motivation, outcome, subdivision depth and whether this was the floor re-roll."
+    });
+  }
+  return _detectionCallCounter;
+}
+function detectionDurationHistogram() {
+  if (!_detectionDurationHistogram) {
+    _detectionDurationHistogram = meter().createHistogram("semiont.detection.call.duration", {
+      description: "Wall time of one detection model call, including the attempts that failed and were retried smaller.",
+      unit: "ms"
+    });
+  }
+  return _detectionDurationHistogram;
+}
+function detectionItemsHistogram() {
+  if (!_detectionItemsHistogram) {
+    _detectionItemsHistogram = meter().createHistogram("semiont.detection.call.items", {
+      description: "Annotations returned by one detection call. Against the input size on the same record, this is yield."
+    });
+  }
+  return _detectionItemsHistogram;
+}
+function detectionTokensHistogram() {
+  if (!_detectionTokensHistogram) {
+    _detectionTokensHistogram = meter().createHistogram("semiont.detection.call.tokens", {
+      description: "Provider-reported tokens for one detection call, by direction. Deliberately separate from semiont.inference.tokens: that series is the authoritative total but carries no subdivision depth, and 'what does a depth-2 call cost' is the question every sizing decision asks."
+    });
+  }
+  return _detectionTokensHistogram;
+}
+function recordDetectionCall(opts) {
+  const attrs = {
+    "detection.label": opts.label,
+    "detection.outcome": opts.outcome,
+    "detection.depth": opts.depth,
+    "detection.reroll": opts.reroll
+  };
+  detectionCallCounter().add(1, attrs);
+  detectionDurationHistogram().record(opts.durationMs, attrs);
+  detectionItemsHistogram().record(opts.items, attrs);
+  if (opts.inputTokens !== void 0) {
+    detectionTokensHistogram().record(opts.inputTokens, { ...attrs, "detection.direction": "input" });
+  }
+  if (opts.outputTokens !== void 0) {
+    detectionTokensHistogram().record(opts.outputTokens, { ...attrs, "detection.direction": "output" });
+  }
+}
+var _anchorOutcomeCounter;
+function anchorOutcomeCounter() {
+  if (!_anchorOutcomeCounter) {
+    _anchorOutcomeCounter = meter().createCounter("semiont.detection.anchors", {
+      description: "Every annotation anchoring, labeled by the method that resolved it. EVERY outcome is counted, not just the risky ones, because a bare count of degraded anchors has no denominator \u2014 the rate is the precision signal."
+    });
+  }
+  return _anchorOutcomeCounter;
+}
+function recordAnchorOutcome(label, method) {
+  anchorOutcomeCounter().add(1, { "detection.label": label, "anchor.method": method });
+}
 
-export { extractTraceparent, getActiveTraceparent, getLogTraceContext, injectTraceparent, recordBusEmit, recordGatherDegrade, recordHandlerDuration, recordInferenceUsage, recordJobOutcome, recordSubscriberConnect, recordSubscriberDisconnect, registerJobQueueProvider, registerVectorIndexSizeProvider, withActorSpan, withSpan, withTraceparent };
+export { extractTraceparent, getActiveTraceparent, getLogTraceContext, injectTraceparent, recordAnchorOutcome, recordAppendStage, recordBusEmit, recordDetectionCall, recordGatherDegrade, recordGitCommand, recordHandlerDuration, recordInferenceUsage, recordJobOutcome, recordReplySuppressed, recordResumeGap, recordSubscriberConnect, recordSubscriberDisconnect, recordUnanswerableRequest, registerCorrelationRegistryProvider, registerFactPumpDepthProvider, registerJobQueueProvider, registerVectorIndexSizeProvider, withActorSpan, withSpan, withTraceparent };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @semiont/observability — public API.\n *\n * Universal surface (works in Node + browser). For SDK *initialization*,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n *\n * Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:\n *\n *   - `withSpan(name, fn, options?)` — wrap an async block in a span;\n *     `options` carries `kind` and `attrs`.\n *   - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span\n *     wrapper for bus-event handlers, with handler-duration recording.\n *   - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C\n *     trace-context propagation across the SSE channel (the bus payload\n *     gets a `_trace?: { traceparent }` sibling to `correlationId`).\n *   - `withTraceparent(carrier, fn)` — run `fn` with the incoming\n *     traceparent as the parent context.\n *   - `getActiveTraceparent()` — read the active span's traceparent for\n *     manual propagation (e.g. attaching to a fetch header or SSE field).\n *   - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line\n *     correlation.\n *   - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,\n *     `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,\n *     `recordInferenceUsage`) and gauge providers\n *     (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).\n *\n * No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability*()` runs.\n */\n\nimport {\n  context,\n  isSpanContextValid,\n  metrics,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n  trace,\n  type Attributes,\n  type Counter,\n  type Histogram,\n  type ObservableGauge,\n  type Span,\n  type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/**\n * Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T> | T,\n  options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n  const span = tracer().startSpan(name, {\n    kind: options?.kind ?? SpanKind.INTERNAL,\n    ...(options?.attrs ? { attributes: options.attrs } : {}),\n  });\n  try {\n    return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n  } catch (err) {\n    span.recordException(err as Error);\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: err instanceof Error ? err.message : String(err),\n    });\n    throw err;\n  } finally {\n    span.end();\n  }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/**\n * Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n */\nexport interface TraceCarrier {\n  /** W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). */\n  traceparent: string;\n  /** W3C `tracestate` header value (vendor-specific extensions). */\n  tracestate?: string;\n}\n\n/**\n * Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n */\nexport function getActiveTraceparent(): TraceCarrier | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  const traceparent = carrier['traceparent'];\n  if (!traceparent) return undefined;\n  return carrier['tracestate']\n    ? { traceparent, tracestate: carrier['tracestate'] }\n    : { traceparent };\n}\n\n/**\n * Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n */\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n  const carrier = getActiveTraceparent();\n  if (carrier) {\n    (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n  }\n  return payload;\n}\n\n/**\n * Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n */\nexport function extractTraceparent<T extends Record<string, unknown>>(\n  payload: T,\n): TraceCarrier | undefined {\n  const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n    | TraceCarrier\n    | undefined;\n  if (carrier !== undefined) {\n    delete (payload as Record<string, unknown>)[TRACE_FIELD];\n  }\n  if (!carrier || typeof carrier.traceparent !== 'string') return undefined;\n  return carrier;\n}\n\n/**\n * Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n */\nexport function withTraceparent<T>(\n  carrier: TraceCarrier | undefined,\n  fn: () => T,\n): T {\n  if (!carrier) return fn();\n  const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n  if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n  const ctx = propagation.extract(context.active(), carrierObj);\n  return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/**\n * Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n *\n * The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the gateway\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n */\nexport async function withActorSpan<T>(\n  actor: string,\n  channel: string,\n  fn: (span: Span) => Promise<T> | T,\n  extraAttrs?: Attributes,\n): Promise<T> {\n  const start = performance.now();\n  try {\n    return await withSpan(`actor.${actor}:${channel}`, fn, {\n      kind: SpanKind.CONSUMER,\n      attrs: {\n        actor,\n        'bus.channel': channel,\n        ...(extraAttrs ?? {}),\n      },\n    });\n  } finally {\n    recordHandlerDuration(actor, channel, performance.now() - start);\n  }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/**\n * Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n *\n * Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n */\nexport function getLogTraceContext(): { trace_id: string; span_id: string } | undefined {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter | undefined;\nlet _handlerDurationHistogram: Histogram | undefined;\nlet _jobOutcomeCounter: Counter | undefined;\nlet _jobDurationHistogram: Histogram | undefined;\nlet _gatherDegradeCounter: Counter | undefined;\nlet _inferenceCallsCounter: Counter | undefined;\nlet _inferenceTokensCounter: Counter | undefined;\nlet _inferenceDurationHistogram: Histogram | undefined;\nlet _sseSubscribers: UpDownCounter | undefined;\nlet _jobQueueGauge: ObservableGauge | undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> | JobQueueSnapshot) | undefined;\nlet _vectorIndexSizeGauge: ObservableGauge | undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> | number) | undefined;\n\n/** Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. */\nexport interface JobQueueSnapshot {\n  pending: number;\n  running: number;\n  complete: number;\n  failed: number;\n  cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n  if (!_busEmitCounter) {\n    _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n      description: 'Bus emits by channel and scope',\n    });\n  }\n  return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n  if (!_handlerDurationHistogram) {\n    _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n      description: 'In-process actor handler duration',\n      unit: 'ms',\n    });\n  }\n  return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n  if (!_jobOutcomeCounter) {\n    _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n      description: 'Worker job completions by type and outcome',\n    });\n  }\n  return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n  if (!_jobDurationHistogram) {\n    _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n      description: 'Worker job duration by type',\n      unit: 'ms',\n    });\n  }\n  return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n  if (!_inferenceCallsCounter) {\n    _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n      description: 'Inference API calls by provider, model, and outcome',\n    });\n  }\n  return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n  if (!_inferenceTokensCounter) {\n    _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n      description: 'Inference token usage by provider, model, and direction',\n    });\n  }\n  return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n  if (!_inferenceDurationHistogram) {\n    _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n      description: 'Inference call duration by provider, model, and outcome',\n      unit: 'ms',\n    });\n  }\n  return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n  if (!_sseSubscribers) {\n    _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n      description: 'Active SSE subscribers',\n    });\n  }\n  return _sseSubscribers;\n}\n\n/** Increment the bus-emit counter. Called at every transport `emit` site. */\nexport function recordBusEmit(channel: string, scope?: string): void {\n  busEmitCounter().add(1, {\n    'bus.channel': channel,\n    ...(scope ? { 'bus.scope': scope } : {}),\n  });\n}\n\n/** Record an in-process actor handler's duration. */\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n  handlerDurationHistogram().record(durationMs, {\n    actor,\n    'bus.channel': channel,\n  });\n}\n\n/** Record a worker job's outcome and duration. */\nexport function recordJobOutcome(jobType: string, outcome: 'completed' | 'failed', durationMs: number): void {\n  jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n  jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\nfunction gatherDegradeCounter(): Counter {\n  if (!_gatherDegradeCounter) {\n    _gatherDegradeCounter = meter().createCounter('semiont.gather.degraded', {\n      description: 'Gathers that degraded because an eventually-consistent projection did not catch up within its read barrier (vectors: absent semanticContext; graph: projection-lag failure). Labeled by projection.',\n    });\n  }\n  return _gatherDegradeCounter;\n}\n\n/**\n * Record a gather degraded by a projection read barrier: `'vectors'` — the\n * Smelter settle barrier timed out (semanticContext shipped absent);\n * `'graph'` — the Weaver applied barrier + poll floor exhausted (projection\n * lag surfaced as a distinct failure). Fleet-alertable counterpart of the\n * `[gather DEGRADED]` L4 breadcrumbs — a rising rate on either label means\n * that pipeline is not keeping up.\n */\nexport function recordGatherDegrade(projection: 'graph' | 'vectors'): void {\n  gatherDegradeCounter().add(1, { projection });\n}\n\n/** Increment the SSE subscriber gauge — call on `/bus/subscribe` open. */\nexport function recordSubscriberConnect(): void {\n  sseSubscribersCounter().add(1);\n}\n\n/** Decrement on disconnect. Pair with `recordSubscriberConnect`. */\nexport function recordSubscriberDisconnect(): void {\n  sseSubscribersCounter().add(-1);\n}\n\n/**\n * Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n */\nexport function registerJobQueueProvider(\n  provider: () => Promise<JobQueueSnapshot> | JobQueueSnapshot,\n): void {\n  _jobQueueProvider = provider;\n  if (!_jobQueueGauge) {\n    _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n      description: 'Job queue size by status',\n    });\n    _jobQueueGauge.addCallback(async (observer) => {\n      if (!_jobQueueProvider) return;\n      const snap = await _jobQueueProvider();\n      observer.observe(snap.pending, { 'job.status': 'pending' });\n      observer.observe(snap.running, { 'job.status': 'running' });\n      observer.observe(snap.complete, { 'job.status': 'complete' });\n      observer.observe(snap.failed, { 'job.status': 'failed' });\n      observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n    });\n  }\n}\n\n/**\n * Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n */\nexport function registerVectorIndexSizeProvider(\n  provider: () => Promise<number> | number,\n): void {\n  _vectorIndexSizeProvider = provider;\n  if (!_vectorIndexSizeGauge) {\n    _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n      description: 'Vector store point count',\n    });\n    _vectorIndexSizeGauge.addCallback(async (observer) => {\n      if (_vectorIndexSizeProvider) {\n        const value = await _vectorIndexSizeProvider();\n        observer.observe(value);\n      }\n    });\n  }\n}\n\n/**\n * Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n */\nexport function recordInferenceUsage(opts: {\n  provider: string;\n  model: string;\n  durationMs: number;\n  outcome: 'success' | 'error';\n  inputTokens?: number;\n  outputTokens?: number;\n}): void {\n  const baseAttrs = {\n    'inference.provider': opts.provider,\n    'inference.model': opts.model,\n    'inference.outcome': opts.outcome,\n  };\n  inferenceCallsCounter().add(1, baseAttrs);\n  inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n  if (opts.inputTokens != null && opts.inputTokens > 0) {\n    inferenceTokensCounter().add(opts.inputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'input',\n    });\n  }\n  if (opts.outputTokens != null && opts.outputTokens > 0) {\n    inferenceTokensCounter().add(opts.outputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'output',\n    });\n  }\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @semiont/observability — public API.\n *\n * Universal surface (works in Node + browser). For SDK *initialization*,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n *\n * Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:\n *\n *   - `withSpan(name, fn, options?)` — wrap an async block in a span;\n *     `options` carries `kind` and `attrs`.\n *   - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span\n *     wrapper for bus-event handlers, with handler-duration recording.\n *   - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C\n *     trace-context propagation across the SSE channel (the bus payload\n *     gets a `_trace?: { traceparent }` sibling to `correlationId`).\n *   - `withTraceparent(carrier, fn)` — run `fn` with the incoming\n *     traceparent as the parent context.\n *   - `getActiveTraceparent()` — read the active span's traceparent for\n *     manual propagation (e.g. attaching to a fetch header or SSE field).\n *   - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line\n *     correlation.\n *   - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,\n *     `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,\n *     `recordInferenceUsage`) and gauge providers\n *     (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).\n *\n * No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability*()` runs.\n */\n\nimport {\n  context,\n  isSpanContextValid,\n  metrics,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n  trace,\n  type Attributes,\n  type Counter,\n  type Histogram,\n  type ObservableGauge,\n  type Span,\n  type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/**\n * Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T> | T,\n  options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n  const span = tracer().startSpan(name, {\n    kind: options?.kind ?? SpanKind.INTERNAL,\n    ...(options?.attrs ? { attributes: options.attrs } : {}),\n  });\n  try {\n    return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n  } catch (err) {\n    span.recordException(err as Error);\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: err instanceof Error ? err.message : String(err),\n    });\n    throw err;\n  } finally {\n    span.end();\n  }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/**\n * Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n */\nexport interface TraceCarrier {\n  /** W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). */\n  traceparent: string;\n  /** W3C `tracestate` header value (vendor-specific extensions). */\n  tracestate?: string;\n}\n\n/**\n * Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n */\nexport function getActiveTraceparent(): TraceCarrier | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  const traceparent = carrier['traceparent'];\n  if (!traceparent) return undefined;\n  return carrier['tracestate']\n    ? { traceparent, tracestate: carrier['tracestate'] }\n    : { traceparent };\n}\n\n/**\n * Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n */\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n  const carrier = getActiveTraceparent();\n  if (carrier) {\n    (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n  }\n  return payload;\n}\n\n/**\n * Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n */\nexport function extractTraceparent<T extends Record<string, unknown>>(\n  payload: T,\n): TraceCarrier | undefined {\n  const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n    | TraceCarrier\n    | undefined;\n  if (carrier !== undefined) {\n    delete (payload as Record<string, unknown>)[TRACE_FIELD];\n  }\n  if (!carrier || typeof carrier.traceparent !== 'string') return undefined;\n  return carrier;\n}\n\n/**\n * Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n */\nexport function withTraceparent<T>(\n  carrier: TraceCarrier | undefined,\n  fn: () => T,\n): T {\n  if (!carrier) return fn();\n  const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n  if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n  const ctx = propagation.extract(context.active(), carrierObj);\n  return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/**\n * Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n *\n * The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the gateway\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n */\nexport async function withActorSpan<T>(\n  actor: string,\n  channel: string,\n  fn: (span: Span) => Promise<T> | T,\n  extraAttrs?: Attributes,\n): Promise<T> {\n  const start = performance.now();\n  try {\n    return await withSpan(`actor.${actor}:${channel}`, fn, {\n      kind: SpanKind.CONSUMER,\n      attrs: {\n        actor,\n        'bus.channel': channel,\n        ...(extraAttrs ?? {}),\n      },\n    });\n  } finally {\n    recordHandlerDuration(actor, channel, performance.now() - start);\n  }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/**\n * Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n *\n * Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n */\nexport function getLogTraceContext(): { trace_id: string; span_id: string } | undefined {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter | undefined;\nlet _replySuppressedCounter: Counter | undefined;\nlet _resumeGapCounter: Counter | undefined;\nlet _unanswerableCounter: Counter | undefined;\nlet _correlationRegistryGauge: ObservableGauge | undefined;\nlet _correlationRegistryProvider: (() => CorrelationRegistrySnapshot) | undefined;\nlet _handlerDurationHistogram: Histogram | undefined;\nlet _jobOutcomeCounter: Counter | undefined;\nlet _jobDurationHistogram: Histogram | undefined;\nlet _gatherDegradeCounter: Counter | undefined;\nlet _inferenceCallsCounter: Counter | undefined;\nlet _inferenceTokensCounter: Counter | undefined;\nlet _inferenceDurationHistogram: Histogram | undefined;\nlet _sseSubscribers: UpDownCounter | undefined;\nlet _jobQueueGauge: ObservableGauge | undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> | JobQueueSnapshot) | undefined;\nlet _vectorIndexSizeGauge: ObservableGauge | undefined;\nlet _factPumpDepthGauge: ObservableGauge | undefined;\nlet _factPumpDepthProvider: (() => number) | undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> | number) | undefined;\n\n/** Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. */\nexport interface JobQueueSnapshot {\n  pending: number;\n  running: number;\n  complete: number;\n  failed: number;\n  cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n  if (!_busEmitCounter) {\n    _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n      description: 'Bus emits by channel and scope',\n    });\n  }\n  return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n  if (!_handlerDurationHistogram) {\n    _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n      description: 'In-process actor handler duration',\n      unit: 'ms',\n    });\n  }\n  return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n  if (!_jobOutcomeCounter) {\n    _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n      description: 'Worker job completions by type and outcome',\n    });\n  }\n  return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n  if (!_jobDurationHistogram) {\n    _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n      description: 'Worker job duration by type',\n      unit: 'ms',\n    });\n  }\n  return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n  if (!_inferenceCallsCounter) {\n    _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n      description: 'Inference API calls by provider, model, and outcome',\n    });\n  }\n  return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n  if (!_inferenceTokensCounter) {\n    _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n      description: 'Inference token usage by provider, model, and direction',\n    });\n  }\n  return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n  if (!_inferenceDurationHistogram) {\n    _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n      description: 'Inference call duration by provider, model, and outcome',\n      unit: 'ms',\n    });\n  }\n  return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n  if (!_sseSubscribers) {\n    _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n      description: 'Active SSE subscribers',\n    });\n  }\n  return _sseSubscribers;\n}\n\nfunction replySuppressedCounter(): Counter {\n  if (!_replySuppressedCounter) {\n    _replySuppressedCounter = meter().createCounter('semiont.bus.reply.suppressed', {\n      description: 'Correlated replies withheld from a non-owning subscriber',\n    });\n  }\n  return _replySuppressedCounter;\n}\n\n/**\n * A correlated reply was withheld from a subscriber that does not own its\n * correlationId (CORRELATED-REPLY-ROUTING P5).\n *\n * Counts ONLY that case. A frame with no correlationId is a shape violation\n * (warned, not counted), and a cid nobody claimed is the structural in-process\n * case that fires constantly — counting either would drown the signal this\n * metric exists to show: the fan-out amplification the delivery filter removes.\n */\nexport function recordReplySuppressed(channel: string): void {\n  replySuppressedCounter().add(1, { 'bus.channel': channel });\n}\n\nfunction resumeGapCounter(): Counter {\n  if (!_resumeGapCounter) {\n    _resumeGapCounter = meter().createCounter('semiont.bus.resume_gap', {\n      description: 'SSE resumes that degraded to a gap because replay was unavailable',\n    });\n  }\n  return _resumeGapCounter;\n}\n\n/**\n * An SSE resume could not be served and the client was told to fall back to\n * cache. This degradation is CORRECT by design and therefore silent — which is\n * exactly why it needs a number. A rising rate means clients are losing\n * history, and nothing else in the stack says so.\n */\nexport function recordResumeGap(reason: string): void {\n  resumeGapCounter().add(1, { 'bus.resume_gap.reason': reason });\n}\n\nfunction unanswerableCounter(): Counter {\n  if (!_unanswerableCounter) {\n    _unanswerableCounter = meter().createCounter('semiont.bus.unanswerable', {\n      description: 'Request emits that reached zero subscribers and were failed at the gateway',\n    });\n  }\n  return _unanswerableCounter;\n}\n\n/**\n * A request-shaped emit reached no subscriber, so the gateway synthesized its\n * mapped failure (ARCHIVIST-STAYS-UP P3). By channel, this is the absence rate\n * of the service that answers it — the difference between \"it went down once\"\n * and \"it is flapping.\"\n */\nexport function recordUnanswerableRequest(channel: string): void {\n  unanswerableCounter().add(1, { 'bus.channel': channel });\n}\n\n/** Claims held and reply payloads retained by a gateway's correlation registry. */\nexport interface CorrelationRegistrySnapshot {\n  claims: number;\n  retainedReplies: number;\n}\n\n/**\n * Register a callback returning the gateway's correlation-registry occupancy.\n *\n * COUNTS, not bytes: retention is count-budgeted today (byte-budgeting is a\n * known limit in CORRELATED-REPLY-ROUTING), so `retainedReplies` is a proxy for\n * heap, not a measure of it. It is still the closest observable to the question\n * two OOM investigations keep asking — a browse result can be 1-2 MB, and up to\n * REPLY_RETENTION_MAX of them are held at once.\n */\nexport function registerCorrelationRegistryProvider(\n  provider: () => CorrelationRegistrySnapshot,\n): void {\n  _correlationRegistryProvider = provider;\n  if (!_correlationRegistryGauge) {\n    _correlationRegistryGauge = meter().createObservableGauge('semiont.bus.correlation.size', {\n      description: 'Correlation registry occupancy: live claims and retained reply payloads',\n    });\n    _correlationRegistryGauge.addCallback((observer) => {\n      if (!_correlationRegistryProvider) return;\n      const snap = _correlationRegistryProvider();\n      observer.observe(snap.claims, { 'correlation.kind': 'claims' });\n      observer.observe(snap.retainedReplies, { 'correlation.kind': 'retained_replies' });\n    });\n  }\n}\n\n/** Increment the bus-emit counter. Called at every transport `emit` site. */\nexport function recordBusEmit(channel: string, scope?: string): void {\n  busEmitCounter().add(1, {\n    'bus.channel': channel,\n    ...(scope ? { 'bus.scope': scope } : {}),\n  });\n}\n\n/** Record an in-process actor handler's duration. */\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n  handlerDurationHistogram().record(durationMs, {\n    actor,\n    'bus.channel': channel,\n  });\n}\n\n/** Record a worker job's outcome and duration. */\nexport function recordJobOutcome(jobType: string, outcome: 'completed' | 'failed', durationMs: number): void {\n  jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n  jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\nlet _appendStageHistogram: Histogram | undefined;\nfunction appendStageHistogram(): Histogram {\n  if (!_appendStageHistogram) {\n    _appendStageHistogram = meter().createHistogram('semiont.record.append.duration', {\n      description: 'Time spent in one stage of appending an event to the record, labeled by stage: persist (JSONL write + git), materialize (view rebuild), enrich, publish. The Archivist\\'s core write path.',\n      unit: 'ms',\n    });\n  }\n  return _appendStageHistogram;\n}\n\n/**\n * Record one stage of `EventStore.appendEvent` (ARCHIVIST-STAYS-UP P7).\n *\n * The append path is the one operation only the Archivist can perform, and it\n * was entirely dark: reads had `recordHandlerDuration` and the bus had its own\n * counters, while writes had nothing. Stage-labeled because the useful\n * question is never \"was the append slow\" but WHICH PART — and `materialize`\n * in particular does work proportional to a resource's annotation count, so it\n * degrades with history rather than with load.\n */\nexport function recordAppendStage(\n  stage: 'persist' | 'materialize' | 'enrich' | 'publish',\n  durationMs: number,\n): void {\n  appendStageHistogram().record(durationMs, { 'record.stage': stage });\n}\n\nlet _gitCommandHistogram: Histogram | undefined;\nfunction gitCommandHistogram(): Histogram {\n  if (!_gitCommandHistogram) {\n    _gitCommandHistogram = meter().createHistogram('semiont.git.duration', {\n      description: 'Wall time of a git subprocess. Async — this is latency, not event-loop blockage. Staging is deduped, so the `add` count is far below the number of appended events.',\n      unit: 'ms',\n    });\n  }\n  return _gitCommandHistogram;\n}\n\n/**\n * Record a git invocation. Read the `add` count against events appended: one\n * per event means deferred staging has stopped deduping.\n */\nexport function recordGitCommand(command: string, durationMs: number): void {\n  gitCommandHistogram().record(durationMs, { 'git.command': command });\n}\n\nfunction gatherDegradeCounter(): Counter {\n  if (!_gatherDegradeCounter) {\n    _gatherDegradeCounter = meter().createCounter('semiont.gather.degraded', {\n      description: 'Gathers that degraded because an eventually-consistent projection did not catch up within its read barrier (vectors: absent semanticContext; graph: projection-lag failure). Labeled by projection.',\n    });\n  }\n  return _gatherDegradeCounter;\n}\n\n/**\n * Record a gather degraded by a projection read barrier: `'vectors'` — the\n * Smelter settle barrier timed out (semanticContext shipped absent);\n * `'graph'` — the Weaver applied barrier + poll floor exhausted (projection\n * lag surfaced as a distinct failure). Fleet-alertable counterpart of the\n * `[gather DEGRADED]` L4 breadcrumbs — a rising rate on either label means\n * that pipeline is not keeping up.\n */\nexport function recordGatherDegrade(projection: 'graph' | 'vectors'): void {\n  gatherDegradeCounter().add(1, { projection });\n}\n\n/** Increment the SSE subscriber gauge — call on `/bus/subscribe` open. */\nexport function recordSubscriberConnect(): void {\n  sseSubscribersCounter().add(1);\n}\n\n/** Decrement on disconnect. Pair with `recordSubscriberConnect`. */\nexport function recordSubscriberDisconnect(): void {\n  sseSubscribersCounter().add(-1);\n}\n\n/**\n * Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n */\nexport function registerJobQueueProvider(\n  provider: () => Promise<JobQueueSnapshot> | JobQueueSnapshot,\n): void {\n  _jobQueueProvider = provider;\n  if (!_jobQueueGauge) {\n    _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n      description: 'Job queue size by status',\n    });\n    _jobQueueGauge.addCallback(async (observer) => {\n      if (!_jobQueueProvider) return;\n      const snap = await _jobQueueProvider();\n      observer.observe(snap.pending, { 'job.status': 'pending' });\n      observer.observe(snap.running, { 'job.status': 'running' });\n      observer.observe(snap.complete, { 'job.status': 'complete' });\n      observer.observe(snap.failed, { 'job.status': 'failed' });\n      observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n    });\n  }\n}\n\n/**\n * Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n */\n/**\n * Register the Archivist's fact-pump backlog — facts appended to the record\n * but not yet republished onto the bus.\n *\n * At rest this is zero. A value that climbs and does not come back means the\n * pump is outrunning its transport, which is the leading hypothesis for the\n * load-correlated heap growth in `bugs/absent-archivist-wedges-browse.md`\n * (ARCHIVIST-STAYS-UP P5). The backlog is deliberately unbounded today, so\n * this number is the only thing standing between \"the pump is behind\" and an\n * OOM whose cause is inferred from RSS after the fact.\n */\nexport function registerFactPumpDepthProvider(provider: () => number): void {\n  _factPumpDepthProvider = provider;\n  if (!_factPumpDepthGauge) {\n    _factPumpDepthGauge = meter().createObservableGauge('semiont.archivist.fact_pump.depth', {\n      description: 'Facts appended to the record but not yet published to the bus. Zero at rest; a rising floor means the pump is behind its transport.',\n    });\n    _factPumpDepthGauge.addCallback((observer) => {\n      if (_factPumpDepthProvider) observer.observe(_factPumpDepthProvider());\n    });\n  }\n}\n\nexport function registerVectorIndexSizeProvider(\n  provider: () => Promise<number> | number,\n): void {\n  _vectorIndexSizeProvider = provider;\n  if (!_vectorIndexSizeGauge) {\n    _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n      description: 'Vector store point count',\n    });\n    _vectorIndexSizeGauge.addCallback(async (observer) => {\n      if (_vectorIndexSizeProvider) {\n        const value = await _vectorIndexSizeProvider();\n        observer.observe(value);\n      }\n    });\n  }\n}\n\n/**\n * Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n */\nexport function recordInferenceUsage(opts: {\n  provider: string;\n  model: string;\n  durationMs: number;\n  outcome: 'success' | 'error';\n  inputTokens?: number;\n  outputTokens?: number;\n}): void {\n  const baseAttrs = {\n    'inference.provider': opts.provider,\n    'inference.model': opts.model,\n    'inference.outcome': opts.outcome,\n  };\n  inferenceCallsCounter().add(1, baseAttrs);\n  inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n  if (opts.inputTokens != null && opts.inputTokens > 0) {\n    inferenceTokensCounter().add(opts.inputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'input',\n    });\n  }\n  if (opts.outputTokens != null && opts.outputTokens > 0) {\n    inferenceTokensCounter().add(opts.outputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'output',\n    });\n  }\n}\n\nlet _detectionCallCounter: Counter | undefined;\nlet _detectionDurationHistogram: Histogram | undefined;\nlet _detectionItemsHistogram: Histogram | undefined;\nlet _detectionTokensHistogram: Histogram | undefined;\n\nfunction detectionCallCounter(): Counter {\n  if (!_detectionCallCounter) {\n    _detectionCallCounter = meter().createCounter('semiont.detection.calls', {\n      description: 'Detection model calls, labeled by motivation, outcome, subdivision depth and whether this was the floor re-roll.',\n    });\n  }\n  return _detectionCallCounter;\n}\n\nfunction detectionDurationHistogram(): Histogram {\n  if (!_detectionDurationHistogram) {\n    _detectionDurationHistogram = meter().createHistogram('semiont.detection.call.duration', {\n      description: 'Wall time of one detection model call, including the attempts that failed and were retried smaller.',\n      unit: 'ms',\n    });\n  }\n  return _detectionDurationHistogram;\n}\n\nfunction detectionItemsHistogram(): Histogram {\n  if (!_detectionItemsHistogram) {\n    _detectionItemsHistogram = meter().createHistogram('semiont.detection.call.items', {\n      description: 'Annotations returned by one detection call. Against the input size on the same record, this is yield.',\n    });\n  }\n  return _detectionItemsHistogram;\n}\n\nfunction detectionTokensHistogram(): Histogram {\n  if (!_detectionTokensHistogram) {\n    _detectionTokensHistogram = meter().createHistogram('semiont.detection.call.tokens', {\n      description: \"Provider-reported tokens for one detection call, by direction. Deliberately separate from semiont.inference.tokens: that series is the authoritative total but carries no subdivision depth, and 'what does a depth-2 call cost' is the question every sizing decision asks.\",\n    });\n  }\n  return _detectionTokensHistogram;\n}\n\n/**\n * Record one detection model call (DETECTION-QUALITY-THROUGHPUT P1).\n *\n * The adapters already record provider/model/duration/tokens for every\n * inference call. What they cannot know is the detection shape around it:\n * which motivation asked, how big the piece was, how many annotations came\n * back, how deep subdivision had descended, and whether this was the floor\n * re-roll. Those are the facts that distinguish a healthy call from a\n * expensive descent, and without them a slow detection run is one\n * undifferentiated number.\n *\n * FAILED attempts are recorded too, and that is the point: the calls paid for\n * and thrown away during a descent are exactly the cost later phases exist to\n * avoid, so a record only of successes would hide the thing being optimized.\n *\n * Tokens are the PROVIDER's counts, passed through — never estimated. Absent\n * means the provider did not report them.\n */\nexport function recordDetectionCall(opts: {\n  label: string;\n  pieceChars: number;\n  durationMs: number;\n  items: number;\n  depth: number;\n  reroll: boolean;\n  outcome: 'success' | 'truncated' | 'timeout' | 'collapsed' | 'error';\n  inputTokens?: number;\n  outputTokens?: number;\n}): void {\n  const attrs = {\n    'detection.label': opts.label,\n    'detection.outcome': opts.outcome,\n    'detection.depth': opts.depth,\n    'detection.reroll': opts.reroll,\n  };\n  detectionCallCounter().add(1, attrs);\n  detectionDurationHistogram().record(opts.durationMs, attrs);\n  detectionItemsHistogram().record(opts.items, attrs);\n  if (opts.inputTokens !== undefined) {\n    detectionTokensHistogram().record(opts.inputTokens, { ...attrs, 'detection.direction': 'input' });\n  }\n  if (opts.outputTokens !== undefined) {\n    detectionTokensHistogram().record(opts.outputTokens, { ...attrs, 'detection.direction': 'output' });\n  }\n}\n\nlet _anchorOutcomeCounter: Counter | undefined;\nfunction anchorOutcomeCounter(): Counter {\n  if (!_anchorOutcomeCounter) {\n    _anchorOutcomeCounter = meter().createCounter('semiont.detection.anchors', {\n      description: 'Every annotation anchoring, labeled by the method that resolved it. EVERY outcome is counted, not just the risky ones, because a bare count of degraded anchors has no denominator — the rate is the precision signal.',\n    });\n  }\n  return _anchorOutcomeCounter;\n}\n\n/**\n * Record how one annotation got anchored (DETECTION-QUALITY-THROUGHPUT P5).\n *\n * The selector-vs-source check is already a WRITE-TIME INVARIANT — both\n * `buildTextAnnotation` and `buildPdfAnnotation` throw on a selector that does\n * not match its source — so mechanical correctness is guaranteed rather than\n * sampled, and auditing it would measure a constant.\n *\n * What is genuinely uncertain is which anchoring METHOD got there. An `exact`\n * the model quoted verbatim and that appears once is certain; one resolved by\n * `first-of-many` (several occurrences, no usable context) or `fuzzy-match`\n * picked a plausible occurrence and may have picked wrong. Those were visible\n * only as log warnings — countable by a human reading worker output, which is\n * how 47 of them went unreviewed. As a rate they are the precision number that\n * sits beside the yield numbers.\n */\nexport function recordAnchorOutcome(label: string, method: string): void {\n  anchorOutcomeCounter().add(1, { 'detection.label': label, 'anchor.method': method });\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n"]}

package/dist/node.d.ts

@@ -30,6 +30,14 @@ interface NodeObservabilityConfig {
     /** Service version. Defaults to `0.0.0` if omitted. */
     serviceVersion?: string;
 }
+/**
+ * Which exporter metrics use. `console` wins even with an OTLP endpoint set —
+ * the readout for a bare process or CI with no collector; traces unaffected.
+ * Any other value (incl. unrecognised) leaves the endpoint to decide, so an
+ * unknown value cannot silently disable metrics. Exported and pure so tests
+ * assert the choice without mocking the exporter modules.
+ */
+declare function metricsExporterKind(endpoint: string | undefined, requested: string | undefined): 'otlp' | 'console';
 /**
  * Initialize OTel for the current process. Wires up both tracing and
  * metrics. Idempotent — calling twice is a no-op. Returns `true` if the
@@ -43,5 +51,5 @@ declare function initObservabilityNode(config: NodeObservabilityConfig): boolean
 /** Force-flush + shutdown both SDKs. Test cleanup, not production. */
 declare function shutdownObservabilityNode(): Promise<void>;
 
-export { initObservabilityNode, shutdownObservabilityNode };
+export { initObservabilityNode, metricsExporterKind, shutdownObservabilityNode };
 export type { NodeObservabilityConfig };

package/dist/node.js

@@ -1,3 +1,5 @@
+import { monitorEventLoopDelay } from 'perf_hooks';
+import { getHeapStatistics } from 'v8';
 import { context, trace, propagation, metrics } from '@opentelemetry/api';
 import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
 import { W3CTraceContextPropagator } from '@opentelemetry/core';
@@ -9,9 +11,22 @@ import { ConsoleSpanExporter, BasicTracerProvider, BatchSpanProcessor } from '@o
 import { ATTR_SERVICE_VERSION, ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
 
 // src/node.ts
+function heapStats() {
+  const mem = process.memoryUsage();
+  return {
+    heapUsed: mem.heapUsed,
+    heapTotal: mem.heapTotal,
+    heapLimit: getHeapStatistics().heap_size_limit,
+    rss: mem.rss
+  };
+}
 var tracerProviderInstance;
 var meterProviderInstance;
 var DEFAULT_METRIC_EXPORT_INTERVAL_MS = 3e4;
+function metricsExporterKind(endpoint, requested) {
+  if (requested === "console") return "console";
+  return endpoint ? "otlp" : "console";
+}
 function initObservabilityNode(config) {
   if (tracerProviderInstance) return false;
   if (process.env["OTEL_SDK_DISABLED"] === "true") return false;
@@ -30,7 +45,7 @@ function initObservabilityNode(config) {
   context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
   trace.setGlobalTracerProvider(tracerProviderInstance);
   propagation.setGlobalPropagator(new W3CTraceContextPropagator());
-  const metricExporter = endpoint ? new OTLPMetricExporter() : new ConsoleMetricExporter();
+  const metricExporter = metricsExporterKind(endpoint, process.env["OTEL_METRICS_EXPORTER"]) === "console" ? new ConsoleMetricExporter() : new OTLPMetricExporter();
   const intervalRaw = process.env["OTEL_METRIC_EXPORT_INTERVAL"];
   const exportIntervalMillis = intervalRaw ? Number.parseInt(intervalRaw, 10) : DEFAULT_METRIC_EXPORT_INTERVAL_MS;
   meterProviderInstance = new MeterProvider({
@@ -43,6 +58,28 @@ function initObservabilityNode(config) {
     ]
   });
   metrics.setGlobalMeterProvider(meterProviderInstance);
+  const loopDelay = monitorEventLoopDelay({ resolution: 10 });
+  loopDelay.enable();
+  const runtimeMeter = meterProviderInstance.getMeter("semiont-runtime");
+  runtimeMeter.createObservableGauge("semiont.runtime.event_loop.lag", {
+    description: "Event-loop delay percentiles over the last export interval. Time the process could not serve anything.",
+    unit: "ms"
+  }).addCallback((observer) => {
+    observer.observe(loopDelay.mean / 1e6, { "lag.stat": "mean" });
+    observer.observe(loopDelay.percentile(99) / 1e6, { "lag.stat": "p99" });
+    observer.observe(loopDelay.max / 1e6, { "lag.stat": "max" });
+    loopDelay.reset();
+  });
+  runtimeMeter.createObservableGauge("semiont.runtime.heap", {
+    description: "Process memory by kind. `limit` is V8's own ceiling, which is what the process dies at \u2014 not the container's allocation.",
+    unit: "By"
+  }).addCallback((observer) => {
+    const s = heapStats();
+    observer.observe(s.heapUsed, { "heap.stat": "used" });
+    observer.observe(s.heapTotal, { "heap.stat": "total" });
+    observer.observe(s.heapLimit, { "heap.stat": "limit" });
+    observer.observe(s.rss, { "heap.stat": "rss" });
+  });
   const shutdown = () => {
     Promise.all([
       tracerProviderInstance?.shutdown().catch(() => {
@@ -67,6 +104,6 @@ async function shutdownObservabilityNode() {
   meterProviderInstance = void 0;
 }
 
-export { initObservabilityNode, shutdownObservabilityNode };
+export { initObservabilityNode, metricsExporterKind, shutdownObservabilityNode };
 //# sourceMappingURL=node.js.map
 //# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/node.ts"],"names":[],"mappings":"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","file":"node.js","sourcesContent":["/**\n * Node SDK initialization. Call once at the process entry point\n * (gateway `index.ts`, `worker-main.ts`, `smelter-main.ts`).\n *\n * Configuration is via standard `OTEL_*` env vars:\n *   - `OTEL_SERVICE_NAME`           — service identity (e.g. `semiont-gateway`)\n *   - `OTEL_EXPORTER_OTLP_ENDPOINT` — collector endpoint (HTTP)\n *   - `OTEL_TRACES_SAMPLER`         — sampler (default: `parentbased_always_on`)\n *   - `OTEL_TRACES_SAMPLER_ARG`     — sampler ratio (default: `1.0`)\n *   - `OTEL_CONSOLE_EXPORTER=true`  — dev-only: emit spans + metrics to stderr\n *   - `OTEL_SDK_DISABLED=true`      — skip initialization entirely\n *\n * **Off-by-default invariant**: with neither `OTEL_EXPORTER_OTLP_ENDPOINT`\n * nor `OTEL_CONSOLE_EXPORTER=true` set, this function is a no-op and the\n * `@opentelemetry/api` no-op tracer takes over. This avoids accidentally\n * flooding production stderr (and CloudWatch) when an operator deploys\n * without configuring an exporter.\n *\n * Implementation note: this module wires `BasicTracerProvider` and\n * `MeterProvider` (both from the stable `@opentelemetry/sdk-trace-base`\n * 2.x line) directly, plus `AsyncLocalStorageContextManager` for Node\n * async-context propagation. We deliberately avoid `@opentelemetry/sdk-node`\n * because its `0.x` experimental versions cross-depend on older 2.0.x\n * SDKs, forcing npm to nest duplicate copies of the stable packages and\n * blowing up bundles for every consumer.\n */\n\nimport { context, metrics, propagation, trace } from '@opentelemetry/api';\nimport { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';\nimport { W3CTraceContextPropagator } from '@opentelemetry/core';\nimport { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';\nimport { resourceFromAttributes } from '@opentelemetry/resources';\nimport {\n  ConsoleMetricExporter,\n  MeterProvider,\n  PeriodicExportingMetricReader,\n} from '@opentelemetry/sdk-metrics';\nimport {\n  BasicTracerProvider,\n  BatchSpanProcessor,\n  ConsoleSpanExporter,\n} from '@opentelemetry/sdk-trace-base';\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from '@opentelemetry/semantic-conventions';\n\nexport interface NodeObservabilityConfig {\n  /** Service identity (e.g. `semiont-gateway`). Overridden by `OTEL_SERVICE_NAME`. */\n  serviceName: string;\n  /** Service version. Defaults to `0.0.0` if omitted. */\n  serviceVersion?: string;\n}\n\nlet tracerProviderInstance: BasicTracerProvider | undefined;\nlet meterProviderInstance: MeterProvider | undefined;\n\n/**\n * Default metric export interval. 30s mirrors the SDK default and gives\n * operators enough granularity without flooding the collector.\n */\nconst DEFAULT_METRIC_EXPORT_INTERVAL_MS = 30_000;\n\n/**\n * Initialize OTel for the current process. Wires up both tracing and\n * metrics. Idempotent — calling twice is a no-op. Returns `true` if the\n * SDK started, `false` if disabled, no exporter is configured, or\n * already initialized.\n *\n * Metrics export at `OTEL_METRIC_EXPORT_INTERVAL` ms (default 30s) to\n * the same `OTEL_EXPORTER_OTLP_ENDPOINT` as traces.\n */\nexport function initObservabilityNode(config: NodeObservabilityConfig): boolean {\n  if (tracerProviderInstance) return false;\n  if (process.env['OTEL_SDK_DISABLED'] === 'true') return false;\n\n  const endpoint = process.env['OTEL_EXPORTER_OTLP_ENDPOINT'];\n  const useConsole = process.env['OTEL_CONSOLE_EXPORTER'] === 'true';\n\n  // No exporter configured = no SDK init. The `@opentelemetry/api`\n  // no-op tracer takes over; `withSpan` still runs `fn` but emits\n  // nothing, `getActiveSpan()` returns a sentinel. Avoids flooding\n  // production stderr when no collector endpoint is set.\n  if (!endpoint && !useConsole) return false;\n\n  const resource = resourceFromAttributes({\n    [ATTR_SERVICE_NAME]: process.env['OTEL_SERVICE_NAME'] ?? config.serviceName,\n    [ATTR_SERVICE_VERSION]: config.serviceVersion ?? '0.0.0',\n  });\n\n  // Trace SDK\n  const traceExporter = endpoint ? new OTLPTraceExporter() : new ConsoleSpanExporter();\n  tracerProviderInstance = new BasicTracerProvider({\n    resource,\n    spanProcessors: [new BatchSpanProcessor(traceExporter)],\n  });\n\n  // Async-context propagation across `await` boundaries — equivalent\n  // to what NodeSDK installs internally, but pinned to the stable 2.x\n  // cohort.\n  context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());\n  trace.setGlobalTracerProvider(tracerProviderInstance);\n\n  // W3C trace-context propagator. Without this, `propagation.inject`\n  // and `propagation.extract` walk an empty propagator chain and\n  // silently do nothing — which means traceparent never makes it onto\n  // outgoing HTTP headers or SSE `_trace` payloads, and cross-service\n  // traces stay disconnected. NodeSDK registers this for you; bare\n  // BasicTracerProvider does not.\n  propagation.setGlobalPropagator(new W3CTraceContextPropagator());\n\n  // Metric SDK — same exporter selection as traces.\n  const metricExporter = endpoint ? new OTLPMetricExporter() : new ConsoleMetricExporter();\n  const intervalRaw = process.env['OTEL_METRIC_EXPORT_INTERVAL'];\n  const exportIntervalMillis = intervalRaw\n    ? Number.parseInt(intervalRaw, 10)\n    : DEFAULT_METRIC_EXPORT_INTERVAL_MS;\n\n  meterProviderInstance = new MeterProvider({\n    resource,\n    readers: [\n      new PeriodicExportingMetricReader({\n        exporter: metricExporter,\n        exportIntervalMillis: Number.isFinite(exportIntervalMillis) && exportIntervalMillis > 0\n          ? exportIntervalMillis\n          : DEFAULT_METRIC_EXPORT_INTERVAL_MS,\n      }),\n    ],\n  });\n  metrics.setGlobalMeterProvider(meterProviderInstance);\n\n  // Flush traces + metrics on shutdown so nothing is lost on SIGTERM/SIGINT.\n  const shutdown = () => {\n    Promise.all([\n      tracerProviderInstance?.shutdown().catch(() => {}),\n      meterProviderInstance?.shutdown().catch(() => {}),\n    ]).finally(() => {\n      tracerProviderInstance = undefined;\n      meterProviderInstance = undefined;\n    });\n  };\n  process.once('SIGTERM', shutdown);\n  process.once('SIGINT', shutdown);\n\n  return true;\n}\n\n/** Force-flush + shutdown both SDKs. Test cleanup, not production. */\nexport async function shutdownObservabilityNode(): Promise<void> {\n  await Promise.all([\n    tracerProviderInstance?.shutdown(),\n    meterProviderInstance?.shutdown(),\n  ]);\n  tracerProviderInstance = undefined;\n  meterProviderInstance = undefined;\n}\n"]}
+{"version":3,"sources":["../src/runtime-stats.ts","../src/node.ts"],"names":[],"mappings":"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","file":"node.js","sourcesContent":["/**\n * Process-runtime readings (ARCHIVIST-STAYS-UP P4).\n *\n * Node-only, and deliberately a plain function rather than a gauge callback:\n * the numbers are the thing worth testing, and a callback registered inside\n * an SDK is awkward to assert against.\n *\n * **Why `heapLimit` is the field that matters.** The Archivist died at\n * ~1016 MB inside a 2048 MB container (`bugs/absent-archivist-wedges-browse.md`)\n * — not because it exhausted the container, but because it hit V8's OWN\n * default old-space ceiling, which is derived from visible memory and lands\n * well under it. `heapUsed` alone cannot express \"how close to death is\n * this\"; only the pair can. It is also how a configured\n * `--max-old-space-size` is verified to have taken effect, rather than\n * assumed from the fact that someone set an env var.\n */\n\nimport { getHeapStatistics } from 'node:v8';\n\nexport interface HeapStats {\n  /** Live heap in use. */\n  heapUsed: number;\n  /** Heap V8 has currently reserved. */\n  heapTotal: number;\n  /** The ceiling V8 will die at — NOT the container's limit. */\n  heapLimit: number;\n  /** Resident set: everything, including buffers outside the JS heap. */\n  rss: number;\n}\n\nexport function heapStats(): HeapStats {\n  const mem = process.memoryUsage();\n  return {\n    heapUsed: mem.heapUsed,\n    heapTotal: mem.heapTotal,\n    heapLimit: getHeapStatistics().heap_size_limit,\n    rss: mem.rss,\n  };\n}\n","/**\n * Node SDK initialization. Call once at the process entry point\n * (gateway `index.ts`, `worker-main.ts`, `smelter-main.ts`).\n *\n * Configuration is via standard `OTEL_*` env vars:\n *   - `OTEL_SERVICE_NAME`           — service identity (e.g. `semiont-gateway`)\n *   - `OTEL_EXPORTER_OTLP_ENDPOINT` — collector endpoint (HTTP)\n *   - `OTEL_TRACES_SAMPLER`         — sampler (default: `parentbased_always_on`)\n *   - `OTEL_TRACES_SAMPLER_ARG`     — sampler ratio (default: `1.0`)\n *   - `OTEL_CONSOLE_EXPORTER=true`  — dev-only: emit spans + metrics to stderr\n *   - `OTEL_SDK_DISABLED=true`      — skip initialization entirely\n *\n * **Off-by-default invariant**: with neither `OTEL_EXPORTER_OTLP_ENDPOINT`\n * nor `OTEL_CONSOLE_EXPORTER=true` set, this function is a no-op and the\n * `@opentelemetry/api` no-op tracer takes over. This avoids accidentally\n * flooding production stderr (and CloudWatch) when an operator deploys\n * without configuring an exporter.\n *\n * Implementation note: this module wires `BasicTracerProvider` and\n * `MeterProvider` (both from the stable `@opentelemetry/sdk-trace-base`\n * 2.x line) directly, plus `AsyncLocalStorageContextManager` for Node\n * async-context propagation. We deliberately avoid `@opentelemetry/sdk-node`\n * because its `0.x` experimental versions cross-depend on older 2.0.x\n * SDKs, forcing npm to nest duplicate copies of the stable packages and\n * blowing up bundles for every consumer.\n */\n\nimport { monitorEventLoopDelay } from 'node:perf_hooks';\nimport { heapStats } from './runtime-stats';\nimport { context, metrics, propagation, trace } from '@opentelemetry/api';\nimport { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';\nimport { W3CTraceContextPropagator } from '@opentelemetry/core';\nimport { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';\nimport { resourceFromAttributes } from '@opentelemetry/resources';\nimport {\n  ConsoleMetricExporter,\n  MeterProvider,\n  PeriodicExportingMetricReader,\n} from '@opentelemetry/sdk-metrics';\nimport {\n  BasicTracerProvider,\n  BatchSpanProcessor,\n  ConsoleSpanExporter,\n} from '@opentelemetry/sdk-trace-base';\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from '@opentelemetry/semantic-conventions';\n\nexport interface NodeObservabilityConfig {\n  /** Service identity (e.g. `semiont-gateway`). Overridden by `OTEL_SERVICE_NAME`. */\n  serviceName: string;\n  /** Service version. Defaults to `0.0.0` if omitted. */\n  serviceVersion?: string;\n}\n\nlet tracerProviderInstance: BasicTracerProvider | undefined;\nlet meterProviderInstance: MeterProvider | undefined;\n\n/**\n * Default metric export interval. 30s mirrors the SDK default and gives\n * operators enough granularity without flooding the collector.\n */\nconst DEFAULT_METRIC_EXPORT_INTERVAL_MS = 30_000;\n\n/**\n * Which exporter metrics use. `console` wins even with an OTLP endpoint set —\n * the readout for a bare process or CI with no collector; traces unaffected.\n * Any other value (incl. unrecognised) leaves the endpoint to decide, so an\n * unknown value cannot silently disable metrics. Exported and pure so tests\n * assert the choice without mocking the exporter modules.\n */\nexport function metricsExporterKind(\n  endpoint: string | undefined,\n  requested: string | undefined,\n): 'otlp' | 'console' {\n  if (requested === 'console') return 'console';\n  return endpoint ? 'otlp' : 'console';\n}\n\n/**\n * Initialize OTel for the current process. Wires up both tracing and\n * metrics. Idempotent — calling twice is a no-op. Returns `true` if the\n * SDK started, `false` if disabled, no exporter is configured, or\n * already initialized.\n *\n * Metrics export at `OTEL_METRIC_EXPORT_INTERVAL` ms (default 30s) to\n * the same `OTEL_EXPORTER_OTLP_ENDPOINT` as traces.\n */\nexport function initObservabilityNode(config: NodeObservabilityConfig): boolean {\n  if (tracerProviderInstance) return false;\n  if (process.env['OTEL_SDK_DISABLED'] === 'true') return false;\n\n  const endpoint = process.env['OTEL_EXPORTER_OTLP_ENDPOINT'];\n  const useConsole = process.env['OTEL_CONSOLE_EXPORTER'] === 'true';\n\n  // No exporter configured = no SDK init. The `@opentelemetry/api`\n  // no-op tracer takes over; `withSpan` still runs `fn` but emits\n  // nothing, `getActiveSpan()` returns a sentinel. Avoids flooding\n  // production stderr when no collector endpoint is set.\n  if (!endpoint && !useConsole) return false;\n\n  const resource = resourceFromAttributes({\n    [ATTR_SERVICE_NAME]: process.env['OTEL_SERVICE_NAME'] ?? config.serviceName,\n    [ATTR_SERVICE_VERSION]: config.serviceVersion ?? '0.0.0',\n  });\n\n  // Trace SDK\n  const traceExporter = endpoint ? new OTLPTraceExporter() : new ConsoleSpanExporter();\n  tracerProviderInstance = new BasicTracerProvider({\n    resource,\n    spanProcessors: [new BatchSpanProcessor(traceExporter)],\n  });\n\n  // Async-context propagation across `await` boundaries — equivalent\n  // to what NodeSDK installs internally, but pinned to the stable 2.x\n  // cohort.\n  context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());\n  trace.setGlobalTracerProvider(tracerProviderInstance);\n\n  // W3C trace-context propagator. Without this, `propagation.inject`\n  // and `propagation.extract` walk an empty propagator chain and\n  // silently do nothing — which means traceparent never makes it onto\n  // outgoing HTTP headers or SSE `_trace` payloads, and cross-service\n  // traces stay disconnected. NodeSDK registers this for you; bare\n  // BasicTracerProvider does not.\n  propagation.setGlobalPropagator(new W3CTraceContextPropagator());\n\n  // Traces follow the endpoint; metrics additionally honour OTEL_METRICS_EXPORTER.\n  const metricExporter =\n    metricsExporterKind(endpoint, process.env['OTEL_METRICS_EXPORTER']) === 'console'\n      ? new ConsoleMetricExporter()\n      : new OTLPMetricExporter();\n  const intervalRaw = process.env['OTEL_METRIC_EXPORT_INTERVAL'];\n  const exportIntervalMillis = intervalRaw\n    ? Number.parseInt(intervalRaw, 10)\n    : DEFAULT_METRIC_EXPORT_INTERVAL_MS;\n\n  meterProviderInstance = new MeterProvider({\n    resource,\n    readers: [\n      new PeriodicExportingMetricReader({\n        exporter: metricExporter,\n        exportIntervalMillis: Number.isFinite(exportIntervalMillis) && exportIntervalMillis > 0\n          ? exportIntervalMillis\n          : DEFAULT_METRIC_EXPORT_INTERVAL_MS,\n      }),\n    ],\n  });\n  metrics.setGlobalMeterProvider(meterProviderInstance);\n\n  // The cause-AGNOSTIC detector for a blocked process: it rises whether the\n  // cause is a large JSON parse, GC, or a sync subprocess. Cheap — libuv keeps\n  // the histogram; we read percentiles and reset once per export interval.\n  const loopDelay = monitorEventLoopDelay({ resolution: 10 });\n  loopDelay.enable();\n  const runtimeMeter = meterProviderInstance.getMeter('semiont-runtime');\n  runtimeMeter\n    .createObservableGauge('semiont.runtime.event_loop.lag', {\n      description: 'Event-loop delay percentiles over the last export interval. Time the process could not serve anything.',\n      unit: 'ms',\n    })\n    .addCallback((observer) => {\n      observer.observe(loopDelay.mean / 1e6, { 'lag.stat': 'mean' });\n      observer.observe(loopDelay.percentile(99) / 1e6, { 'lag.stat': 'p99' });\n      observer.observe(loopDelay.max / 1e6, { 'lag.stat': 'max' });\n      loopDelay.reset();\n    });\n\n  // Heap (ARCHIVIST-STAYS-UP P4), on the SAME registration as lag rather than\n  // a second mechanism — they are read together when diagnosing a process\n  // that stopped answering, and splitting them would mean two things to wire.\n  //\n  // `limit` is the field that repays the effort: the Archivist died at\n  // ~1016 MB inside a 2048 MB container because V8's own default ceiling sits\n  // well under the container's. `used` alone cannot say how close to death a\n  // process is, and `limit` is what a configured --max-old-space-size changes\n  // — so this is also how that setting is VERIFIED rather than assumed.\n  runtimeMeter\n    .createObservableGauge('semiont.runtime.heap', {\n      description: \"Process memory by kind. `limit` is V8's own ceiling, which is what the process dies at — not the container's allocation.\",\n      unit: 'By',\n    })\n    .addCallback((observer) => {\n      const s = heapStats();\n      observer.observe(s.heapUsed, { 'heap.stat': 'used' });\n      observer.observe(s.heapTotal, { 'heap.stat': 'total' });\n      observer.observe(s.heapLimit, { 'heap.stat': 'limit' });\n      observer.observe(s.rss, { 'heap.stat': 'rss' });\n    });\n\n  // Flush traces + metrics on shutdown so nothing is lost on SIGTERM/SIGINT.\n  const shutdown = () => {\n    Promise.all([\n      tracerProviderInstance?.shutdown().catch(() => {}),\n      meterProviderInstance?.shutdown().catch(() => {}),\n    ]).finally(() => {\n      tracerProviderInstance = undefined;\n      meterProviderInstance = undefined;\n    });\n  };\n  process.once('SIGTERM', shutdown);\n  process.once('SIGINT', shutdown);\n\n  return true;\n}\n\n/** Force-flush + shutdown both SDKs. Test cleanup, not production. */\nexport async function shutdownObservabilityNode(): Promise<void> {\n  await Promise.all([\n    tracerProviderInstance?.shutdown(),\n    meterProviderInstance?.shutdown(),\n  ]);\n  tracerProviderInstance = undefined;\n  meterProviderInstance = undefined;\n}\n"]}

package/dist/process-logger.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/process-logger.ts"],"names":["trace"],"mappings":";;;;;AAqDA,wBAAA,CAAyB,MAAM;AAC7B,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,GAAA,CAAI,OAAA;AACb,CAAC,CAAA;AA+JM,SAAS,kBAAA,GAAwE;AACtF,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,EAAE,QAAA,EAAU,GAAA,CAAI,OAAA,EAAS,OAAA,EAAS,IAAI,MAAA,EAAO;AACtD;;;AC1MA,IAAM,kBAAA,GAAqB,OAAA,CAAQ,MAAA,CAAO,CAAC,IAAA,KAAS;AAClD,EAAA,MAAMA,SAAQ,kBAAA,EAAmB;AACjC,EAAA,IAAIA,MAAAA,EAAO;AACT,IAAA,IAAA,CAAK,WAAWA,MAAAA,CAAM,QAAA;AACtB,IAAA,IAAA,CAAK,UAAUA,MAAAA,CAAM,OAAA;AAAA,EACvB;AACA,EAAA,OAAO,IAAA;AACT,CAAC,CAAA,EAAE;AAEI,SAAS,oBAAoB,SAAA,EAA2B;AAC7D,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,SAAA,IAAa,MAAA;AACvC,EAAA,MAAM,SAAS,OAAA,CAAQ,GAAA,CAAI,UAAA,KAAe,QAAA,GACtC,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,QAAQ,MAAA,CAAO,SAAA,CAAU,EAAE,MAAA,EAAQ,uBAAuB,CAAA;AAAA,IAC1D,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,MAAA,CAAO,MAAA,CAAO,CAAC,EAAE,KAAA,EAAO,GAAA,EAAK,OAAA,EAAS,SAAA,EAAW,GAAG,IAAA,EAAK,KAAM;AACrE,MAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,MAAA,GAAS,CAAA,GAAI,CAAA,CAAA,EAAI,IAAA,CAAK,SAAA,CAAU,IAAI,CAAC,CAAA,CAAA,GAAK,EAAA;AAC5E,MAAA,OAAO,CAAA,EAAG,SAAS,CAAA,EAAA,EAAK,GAAA,CAAI,WAAA,EAAa,CAAA,GAAA,EAAM,SAAS,CAAA,EAAA,EAAK,OAAO,CAAA,EAAG,OAAO,CAAA,CAAA;AAAA,IAChF,CAAC;AAAA,GACH,GACA,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,OAAA,CAAQ,OAAO,SAAA,EAAU;AAAA,IACzB,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,OAAO,IAAA;AAAK,GACtB;AAEJ,EAAA,MAAM,MAAA,GAAS,QAAQ,YAAA,CAAa;AAAA,IAClC,KAAA;AAAA,IACA,WAAA,EAAa,EAAE,SAAA,EAAU;AAAA,IACzB,MAAA;AAAA,IACA,YAAY,CAAC,IAAI,OAAA,CAAQ,UAAA,CAAW,SAAS;AAAA,GAC9C,CAAA;AAED,EAAA,OAAO,MAAA;AACT","file":"process-logger.js","sourcesContent":["/**\n * @semiont/observability — public API.\n *\n * Universal surface (works in Node + browser). For SDK *initialization*,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n *\n * Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:\n *\n *   - `withSpan(name, fn, options?)` — wrap an async block in a span;\n *     `options` carries `kind` and `attrs`.\n *   - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span\n *     wrapper for bus-event handlers, with handler-duration recording.\n *   - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C\n *     trace-context propagation across the SSE channel (the bus payload\n *     gets a `_trace?: { traceparent }` sibling to `correlationId`).\n *   - `withTraceparent(carrier, fn)` — run `fn` with the incoming\n *     traceparent as the parent context.\n *   - `getActiveTraceparent()` — read the active span's traceparent for\n *     manual propagation (e.g. attaching to a fetch header or SSE field).\n *   - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line\n *     correlation.\n *   - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,\n *     `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,\n *     `recordInferenceUsage`) and gauge providers\n *     (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).\n *\n * No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability*()` runs.\n */\n\nimport {\n  context,\n  isSpanContextValid,\n  metrics,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n  trace,\n  type Attributes,\n  type Counter,\n  type Histogram,\n  type ObservableGauge,\n  type Span,\n  type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/**\n * Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T> | T,\n  options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n  const span = tracer().startSpan(name, {\n    kind: options?.kind ?? SpanKind.INTERNAL,\n    ...(options?.attrs ? { attributes: options.attrs } : {}),\n  });\n  try {\n    return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n  } catch (err) {\n    span.recordException(err as Error);\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: err instanceof Error ? err.message : String(err),\n    });\n    throw err;\n  } finally {\n    span.end();\n  }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/**\n * Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n */\nexport interface TraceCarrier {\n  /** W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). */\n  traceparent: string;\n  /** W3C `tracestate` header value (vendor-specific extensions). */\n  tracestate?: string;\n}\n\n/**\n * Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n */\nexport function getActiveTraceparent(): TraceCarrier | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  const traceparent = carrier['traceparent'];\n  if (!traceparent) return undefined;\n  return carrier['tracestate']\n    ? { traceparent, tracestate: carrier['tracestate'] }\n    : { traceparent };\n}\n\n/**\n * Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n */\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n  const carrier = getActiveTraceparent();\n  if (carrier) {\n    (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n  }\n  return payload;\n}\n\n/**\n * Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n */\nexport function extractTraceparent<T extends Record<string, unknown>>(\n  payload: T,\n): TraceCarrier | undefined {\n  const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n    | TraceCarrier\n    | undefined;\n  if (carrier !== undefined) {\n    delete (payload as Record<string, unknown>)[TRACE_FIELD];\n  }\n  if (!carrier || typeof carrier.traceparent !== 'string') return undefined;\n  return carrier;\n}\n\n/**\n * Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n */\nexport function withTraceparent<T>(\n  carrier: TraceCarrier | undefined,\n  fn: () => T,\n): T {\n  if (!carrier) return fn();\n  const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n  if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n  const ctx = propagation.extract(context.active(), carrierObj);\n  return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/**\n * Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n *\n * The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the gateway\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n */\nexport async function withActorSpan<T>(\n  actor: string,\n  channel: string,\n  fn: (span: Span) => Promise<T> | T,\n  extraAttrs?: Attributes,\n): Promise<T> {\n  const start = performance.now();\n  try {\n    return await withSpan(`actor.${actor}:${channel}`, fn, {\n      kind: SpanKind.CONSUMER,\n      attrs: {\n        actor,\n        'bus.channel': channel,\n        ...(extraAttrs ?? {}),\n      },\n    });\n  } finally {\n    recordHandlerDuration(actor, channel, performance.now() - start);\n  }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/**\n * Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n *\n * Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n */\nexport function getLogTraceContext(): { trace_id: string; span_id: string } | undefined {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter | undefined;\nlet _handlerDurationHistogram: Histogram | undefined;\nlet _jobOutcomeCounter: Counter | undefined;\nlet _jobDurationHistogram: Histogram | undefined;\nlet _gatherDegradeCounter: Counter | undefined;\nlet _inferenceCallsCounter: Counter | undefined;\nlet _inferenceTokensCounter: Counter | undefined;\nlet _inferenceDurationHistogram: Histogram | undefined;\nlet _sseSubscribers: UpDownCounter | undefined;\nlet _jobQueueGauge: ObservableGauge | undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> | JobQueueSnapshot) | undefined;\nlet _vectorIndexSizeGauge: ObservableGauge | undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> | number) | undefined;\n\n/** Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. */\nexport interface JobQueueSnapshot {\n  pending: number;\n  running: number;\n  complete: number;\n  failed: number;\n  cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n  if (!_busEmitCounter) {\n    _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n      description: 'Bus emits by channel and scope',\n    });\n  }\n  return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n  if (!_handlerDurationHistogram) {\n    _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n      description: 'In-process actor handler duration',\n      unit: 'ms',\n    });\n  }\n  return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n  if (!_jobOutcomeCounter) {\n    _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n      description: 'Worker job completions by type and outcome',\n    });\n  }\n  return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n  if (!_jobDurationHistogram) {\n    _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n      description: 'Worker job duration by type',\n      unit: 'ms',\n    });\n  }\n  return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n  if (!_inferenceCallsCounter) {\n    _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n      description: 'Inference API calls by provider, model, and outcome',\n    });\n  }\n  return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n  if (!_inferenceTokensCounter) {\n    _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n      description: 'Inference token usage by provider, model, and direction',\n    });\n  }\n  return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n  if (!_inferenceDurationHistogram) {\n    _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n      description: 'Inference call duration by provider, model, and outcome',\n      unit: 'ms',\n    });\n  }\n  return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n  if (!_sseSubscribers) {\n    _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n      description: 'Active SSE subscribers',\n    });\n  }\n  return _sseSubscribers;\n}\n\n/** Increment the bus-emit counter. Called at every transport `emit` site. */\nexport function recordBusEmit(channel: string, scope?: string): void {\n  busEmitCounter().add(1, {\n    'bus.channel': channel,\n    ...(scope ? { 'bus.scope': scope } : {}),\n  });\n}\n\n/** Record an in-process actor handler's duration. */\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n  handlerDurationHistogram().record(durationMs, {\n    actor,\n    'bus.channel': channel,\n  });\n}\n\n/** Record a worker job's outcome and duration. */\nexport function recordJobOutcome(jobType: string, outcome: 'completed' | 'failed', durationMs: number): void {\n  jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n  jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\nfunction gatherDegradeCounter(): Counter {\n  if (!_gatherDegradeCounter) {\n    _gatherDegradeCounter = meter().createCounter('semiont.gather.degraded', {\n      description: 'Gathers that degraded because an eventually-consistent projection did not catch up within its read barrier (vectors: absent semanticContext; graph: projection-lag failure). Labeled by projection.',\n    });\n  }\n  return _gatherDegradeCounter;\n}\n\n/**\n * Record a gather degraded by a projection read barrier: `'vectors'` — the\n * Smelter settle barrier timed out (semanticContext shipped absent);\n * `'graph'` — the Weaver applied barrier + poll floor exhausted (projection\n * lag surfaced as a distinct failure). Fleet-alertable counterpart of the\n * `[gather DEGRADED]` L4 breadcrumbs — a rising rate on either label means\n * that pipeline is not keeping up.\n */\nexport function recordGatherDegrade(projection: 'graph' | 'vectors'): void {\n  gatherDegradeCounter().add(1, { projection });\n}\n\n/** Increment the SSE subscriber gauge — call on `/bus/subscribe` open. */\nexport function recordSubscriberConnect(): void {\n  sseSubscribersCounter().add(1);\n}\n\n/** Decrement on disconnect. Pair with `recordSubscriberConnect`. */\nexport function recordSubscriberDisconnect(): void {\n  sseSubscribersCounter().add(-1);\n}\n\n/**\n * Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n */\nexport function registerJobQueueProvider(\n  provider: () => Promise<JobQueueSnapshot> | JobQueueSnapshot,\n): void {\n  _jobQueueProvider = provider;\n  if (!_jobQueueGauge) {\n    _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n      description: 'Job queue size by status',\n    });\n    _jobQueueGauge.addCallback(async (observer) => {\n      if (!_jobQueueProvider) return;\n      const snap = await _jobQueueProvider();\n      observer.observe(snap.pending, { 'job.status': 'pending' });\n      observer.observe(snap.running, { 'job.status': 'running' });\n      observer.observe(snap.complete, { 'job.status': 'complete' });\n      observer.observe(snap.failed, { 'job.status': 'failed' });\n      observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n    });\n  }\n}\n\n/**\n * Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n */\nexport function registerVectorIndexSizeProvider(\n  provider: () => Promise<number> | number,\n): void {\n  _vectorIndexSizeProvider = provider;\n  if (!_vectorIndexSizeGauge) {\n    _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n      description: 'Vector store point count',\n    });\n    _vectorIndexSizeGauge.addCallback(async (observer) => {\n      if (_vectorIndexSizeProvider) {\n        const value = await _vectorIndexSizeProvider();\n        observer.observe(value);\n      }\n    });\n  }\n}\n\n/**\n * Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n */\nexport function recordInferenceUsage(opts: {\n  provider: string;\n  model: string;\n  durationMs: number;\n  outcome: 'success' | 'error';\n  inputTokens?: number;\n  outputTokens?: number;\n}): void {\n  const baseAttrs = {\n    'inference.provider': opts.provider,\n    'inference.model': opts.model,\n    'inference.outcome': opts.outcome,\n  };\n  inferenceCallsCounter().add(1, baseAttrs);\n  inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n  if (opts.inputTokens != null && opts.inputTokens > 0) {\n    inferenceTokensCounter().add(opts.inputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'input',\n    });\n  }\n  if (opts.outputTokens != null && opts.outputTokens > 0) {\n    inferenceTokensCounter().add(opts.outputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'output',\n    });\n  }\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n","/**\n * Process-level structured logger for Node entry points.\n *\n * Used by long-lived Node processes (gateway, workers, smelter) that\n * want JSON-structured stdout with active-span trace correlation. The\n * `trace_id` / `span_id` fields are populated from the current OTel\n * span context via `getLogTraceContext` — this is the same Tier 3\n * correlation that lets a grep through stdout line up with the trace\n * UI without manual stitching.\n *\n * Reads `LOG_LEVEL` (default `info`) and `LOG_FORMAT` (`json` default,\n * `simple` for human-friendly dev output).\n *\n * Co-located with `getLogTraceContext` deliberately: this is the\n * only reasonably-shaped consumer of that helper, and putting them in\n * the same package keeps the trace-id wiring in one place.\n */\n\nimport winston from 'winston';\nimport type { Logger } from '@semiont/core';\nimport { getLogTraceContext } from './index.js';\n\nconst traceContextFormat = winston.format((info) => {\n  const trace = getLogTraceContext();\n  if (trace) {\n    info.trace_id = trace.trace_id;\n    info.span_id = trace.span_id;\n  }\n  return info;\n})();\n\nexport function createProcessLogger(component: string): Logger {\n  const level = process.env.LOG_LEVEL ?? 'info';\n  const format = process.env.LOG_FORMAT === 'simple'\n    ? winston.format.combine(\n        winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),\n        winston.format.errors({ stack: true }),\n        traceContextFormat,\n        winston.format.printf(({ level: lvl, message, timestamp, ...meta }) => {\n          const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';\n          return `${timestamp} [${lvl.toUpperCase()}] [${component}] ${message}${metaStr}`;\n        }),\n      )\n    : winston.format.combine(\n        winston.format.timestamp(),\n        winston.format.errors({ stack: true }),\n        traceContextFormat,\n        winston.format.json(),\n      );\n\n  const logger = winston.createLogger({\n    level,\n    defaultMeta: { component },\n    format,\n    transports: [new winston.transports.Console()],\n  });\n\n  return logger;\n}\n"]}
+{"version":3,"sources":["../src/index.ts","../src/process-logger.ts"],"names":["trace"],"mappings":";;;;;AAqDA,wBAAA,CAAyB,MAAM;AAC7B,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,GAAA,CAAI,OAAA;AACb,CAAC,CAAA;AA+JM,SAAS,kBAAA,GAAwE;AACtF,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,EAAE,QAAA,EAAU,GAAA,CAAI,OAAA,EAAS,OAAA,EAAS,IAAI,MAAA,EAAO;AACtD;;;AC1MA,IAAM,kBAAA,GAAqB,OAAA,CAAQ,MAAA,CAAO,CAAC,IAAA,KAAS;AAClD,EAAA,MAAMA,SAAQ,kBAAA,EAAmB;AACjC,EAAA,IAAIA,MAAAA,EAAO;AACT,IAAA,IAAA,CAAK,WAAWA,MAAAA,CAAM,QAAA;AACtB,IAAA,IAAA,CAAK,UAAUA,MAAAA,CAAM,OAAA;AAAA,EACvB;AACA,EAAA,OAAO,IAAA;AACT,CAAC,CAAA,EAAE;AAEI,SAAS,oBAAoB,SAAA,EAA2B;AAC7D,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,SAAA,IAAa,MAAA;AACvC,EAAA,MAAM,SAAS,OAAA,CAAQ,GAAA,CAAI,UAAA,KAAe,QAAA,GACtC,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,QAAQ,MAAA,CAAO,SAAA,CAAU,EAAE,MAAA,EAAQ,uBAAuB,CAAA;AAAA,IAC1D,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,MAAA,CAAO,MAAA,CAAO,CAAC,EAAE,KAAA,EAAO,GAAA,EAAK,OAAA,EAAS,SAAA,EAAW,GAAG,IAAA,EAAK,KAAM;AACrE,MAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,MAAA,GAAS,CAAA,GAAI,CAAA,CAAA,EAAI,IAAA,CAAK,SAAA,CAAU,IAAI,CAAC,CAAA,CAAA,GAAK,EAAA;AAC5E,MAAA,OAAO,CAAA,EAAG,SAAS,CAAA,EAAA,EAAK,GAAA,CAAI,WAAA,EAAa,CAAA,GAAA,EAAM,SAAS,CAAA,EAAA,EAAK,OAAO,CAAA,EAAG,OAAO,CAAA,CAAA;AAAA,IAChF,CAAC;AAAA,GACH,GACA,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,OAAA,CAAQ,OAAO,SAAA,EAAU;AAAA,IACzB,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,OAAO,IAAA;AAAK,GACtB;AAEJ,EAAA,MAAM,MAAA,GAAS,QAAQ,YAAA,CAAa;AAAA,IAClC,KAAA;AAAA,IACA,WAAA,EAAa,EAAE,SAAA,EAAU;AAAA,IACzB,MAAA;AAAA,IACA,YAAY,CAAC,IAAI,OAAA,CAAQ,UAAA,CAAW,SAAS;AAAA,GAC9C,CAAA;AAED,EAAA,OAAO,MAAA;AACT","file":"process-logger.js","sourcesContent":["/**\n * @semiont/observability — public API.\n *\n * Universal surface (works in Node + browser). For SDK *initialization*,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n *\n * Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:\n *\n *   - `withSpan(name, fn, options?)` — wrap an async block in a span;\n *     `options` carries `kind` and `attrs`.\n *   - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span\n *     wrapper for bus-event handlers, with handler-duration recording.\n *   - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C\n *     trace-context propagation across the SSE channel (the bus payload\n *     gets a `_trace?: { traceparent }` sibling to `correlationId`).\n *   - `withTraceparent(carrier, fn)` — run `fn` with the incoming\n *     traceparent as the parent context.\n *   - `getActiveTraceparent()` — read the active span's traceparent for\n *     manual propagation (e.g. attaching to a fetch header or SSE field).\n *   - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line\n *     correlation.\n *   - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,\n *     `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,\n *     `recordInferenceUsage`) and gauge providers\n *     (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).\n *\n * No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability*()` runs.\n */\n\nimport {\n  context,\n  isSpanContextValid,\n  metrics,\n  propagation,\n  SpanKind,\n  SpanStatusCode,\n  trace,\n  type Attributes,\n  type Counter,\n  type Histogram,\n  type ObservableGauge,\n  type Span,\n  type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/**\n * Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n */\nexport async function withSpan<T>(\n  name: string,\n  fn: (span: Span) => Promise<T> | T,\n  options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n  const span = tracer().startSpan(name, {\n    kind: options?.kind ?? SpanKind.INTERNAL,\n    ...(options?.attrs ? { attributes: options.attrs } : {}),\n  });\n  try {\n    return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n  } catch (err) {\n    span.recordException(err as Error);\n    span.setStatus({\n      code: SpanStatusCode.ERROR,\n      message: err instanceof Error ? err.message : String(err),\n    });\n    throw err;\n  } finally {\n    span.end();\n  }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/**\n * Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n */\nexport interface TraceCarrier {\n  /** W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). */\n  traceparent: string;\n  /** W3C `tracestate` header value (vendor-specific extensions). */\n  tracestate?: string;\n}\n\n/**\n * Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n */\nexport function getActiveTraceparent(): TraceCarrier | undefined {\n  const carrier: Record<string, string> = {};\n  propagation.inject(context.active(), carrier);\n  const traceparent = carrier['traceparent'];\n  if (!traceparent) return undefined;\n  return carrier['tracestate']\n    ? { traceparent, tracestate: carrier['tracestate'] }\n    : { traceparent };\n}\n\n/**\n * Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n */\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n  const carrier = getActiveTraceparent();\n  if (carrier) {\n    (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n  }\n  return payload;\n}\n\n/**\n * Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n */\nexport function extractTraceparent<T extends Record<string, unknown>>(\n  payload: T,\n): TraceCarrier | undefined {\n  const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n    | TraceCarrier\n    | undefined;\n  if (carrier !== undefined) {\n    delete (payload as Record<string, unknown>)[TRACE_FIELD];\n  }\n  if (!carrier || typeof carrier.traceparent !== 'string') return undefined;\n  return carrier;\n}\n\n/**\n * Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n */\nexport function withTraceparent<T>(\n  carrier: TraceCarrier | undefined,\n  fn: () => T,\n): T {\n  if (!carrier) return fn();\n  const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n  if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n  const ctx = propagation.extract(context.active(), carrierObj);\n  return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/**\n * Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n *\n * The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the gateway\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n */\nexport async function withActorSpan<T>(\n  actor: string,\n  channel: string,\n  fn: (span: Span) => Promise<T> | T,\n  extraAttrs?: Attributes,\n): Promise<T> {\n  const start = performance.now();\n  try {\n    return await withSpan(`actor.${actor}:${channel}`, fn, {\n      kind: SpanKind.CONSUMER,\n      attrs: {\n        actor,\n        'bus.channel': channel,\n        ...(extraAttrs ?? {}),\n      },\n    });\n  } finally {\n    recordHandlerDuration(actor, channel, performance.now() - start);\n  }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/**\n * Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n *\n * Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n */\nexport function getLogTraceContext(): { trace_id: string; span_id: string } | undefined {\n  const span = trace.getActiveSpan();\n  if (!span) return undefined;\n  const ctx = span.spanContext();\n  if (!isSpanContextValid(ctx)) return undefined;\n  return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter | undefined;\nlet _replySuppressedCounter: Counter | undefined;\nlet _resumeGapCounter: Counter | undefined;\nlet _unanswerableCounter: Counter | undefined;\nlet _correlationRegistryGauge: ObservableGauge | undefined;\nlet _correlationRegistryProvider: (() => CorrelationRegistrySnapshot) | undefined;\nlet _handlerDurationHistogram: Histogram | undefined;\nlet _jobOutcomeCounter: Counter | undefined;\nlet _jobDurationHistogram: Histogram | undefined;\nlet _gatherDegradeCounter: Counter | undefined;\nlet _inferenceCallsCounter: Counter | undefined;\nlet _inferenceTokensCounter: Counter | undefined;\nlet _inferenceDurationHistogram: Histogram | undefined;\nlet _sseSubscribers: UpDownCounter | undefined;\nlet _jobQueueGauge: ObservableGauge | undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> | JobQueueSnapshot) | undefined;\nlet _vectorIndexSizeGauge: ObservableGauge | undefined;\nlet _factPumpDepthGauge: ObservableGauge | undefined;\nlet _factPumpDepthProvider: (() => number) | undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> | number) | undefined;\n\n/** Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. */\nexport interface JobQueueSnapshot {\n  pending: number;\n  running: number;\n  complete: number;\n  failed: number;\n  cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n  if (!_busEmitCounter) {\n    _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n      description: 'Bus emits by channel and scope',\n    });\n  }\n  return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n  if (!_handlerDurationHistogram) {\n    _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n      description: 'In-process actor handler duration',\n      unit: 'ms',\n    });\n  }\n  return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n  if (!_jobOutcomeCounter) {\n    _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n      description: 'Worker job completions by type and outcome',\n    });\n  }\n  return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n  if (!_jobDurationHistogram) {\n    _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n      description: 'Worker job duration by type',\n      unit: 'ms',\n    });\n  }\n  return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n  if (!_inferenceCallsCounter) {\n    _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n      description: 'Inference API calls by provider, model, and outcome',\n    });\n  }\n  return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n  if (!_inferenceTokensCounter) {\n    _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n      description: 'Inference token usage by provider, model, and direction',\n    });\n  }\n  return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n  if (!_inferenceDurationHistogram) {\n    _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n      description: 'Inference call duration by provider, model, and outcome',\n      unit: 'ms',\n    });\n  }\n  return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n  if (!_sseSubscribers) {\n    _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n      description: 'Active SSE subscribers',\n    });\n  }\n  return _sseSubscribers;\n}\n\nfunction replySuppressedCounter(): Counter {\n  if (!_replySuppressedCounter) {\n    _replySuppressedCounter = meter().createCounter('semiont.bus.reply.suppressed', {\n      description: 'Correlated replies withheld from a non-owning subscriber',\n    });\n  }\n  return _replySuppressedCounter;\n}\n\n/**\n * A correlated reply was withheld from a subscriber that does not own its\n * correlationId (CORRELATED-REPLY-ROUTING P5).\n *\n * Counts ONLY that case. A frame with no correlationId is a shape violation\n * (warned, not counted), and a cid nobody claimed is the structural in-process\n * case that fires constantly — counting either would drown the signal this\n * metric exists to show: the fan-out amplification the delivery filter removes.\n */\nexport function recordReplySuppressed(channel: string): void {\n  replySuppressedCounter().add(1, { 'bus.channel': channel });\n}\n\nfunction resumeGapCounter(): Counter {\n  if (!_resumeGapCounter) {\n    _resumeGapCounter = meter().createCounter('semiont.bus.resume_gap', {\n      description: 'SSE resumes that degraded to a gap because replay was unavailable',\n    });\n  }\n  return _resumeGapCounter;\n}\n\n/**\n * An SSE resume could not be served and the client was told to fall back to\n * cache. This degradation is CORRECT by design and therefore silent — which is\n * exactly why it needs a number. A rising rate means clients are losing\n * history, and nothing else in the stack says so.\n */\nexport function recordResumeGap(reason: string): void {\n  resumeGapCounter().add(1, { 'bus.resume_gap.reason': reason });\n}\n\nfunction unanswerableCounter(): Counter {\n  if (!_unanswerableCounter) {\n    _unanswerableCounter = meter().createCounter('semiont.bus.unanswerable', {\n      description: 'Request emits that reached zero subscribers and were failed at the gateway',\n    });\n  }\n  return _unanswerableCounter;\n}\n\n/**\n * A request-shaped emit reached no subscriber, so the gateway synthesized its\n * mapped failure (ARCHIVIST-STAYS-UP P3). By channel, this is the absence rate\n * of the service that answers it — the difference between \"it went down once\"\n * and \"it is flapping.\"\n */\nexport function recordUnanswerableRequest(channel: string): void {\n  unanswerableCounter().add(1, { 'bus.channel': channel });\n}\n\n/** Claims held and reply payloads retained by a gateway's correlation registry. */\nexport interface CorrelationRegistrySnapshot {\n  claims: number;\n  retainedReplies: number;\n}\n\n/**\n * Register a callback returning the gateway's correlation-registry occupancy.\n *\n * COUNTS, not bytes: retention is count-budgeted today (byte-budgeting is a\n * known limit in CORRELATED-REPLY-ROUTING), so `retainedReplies` is a proxy for\n * heap, not a measure of it. It is still the closest observable to the question\n * two OOM investigations keep asking — a browse result can be 1-2 MB, and up to\n * REPLY_RETENTION_MAX of them are held at once.\n */\nexport function registerCorrelationRegistryProvider(\n  provider: () => CorrelationRegistrySnapshot,\n): void {\n  _correlationRegistryProvider = provider;\n  if (!_correlationRegistryGauge) {\n    _correlationRegistryGauge = meter().createObservableGauge('semiont.bus.correlation.size', {\n      description: 'Correlation registry occupancy: live claims and retained reply payloads',\n    });\n    _correlationRegistryGauge.addCallback((observer) => {\n      if (!_correlationRegistryProvider) return;\n      const snap = _correlationRegistryProvider();\n      observer.observe(snap.claims, { 'correlation.kind': 'claims' });\n      observer.observe(snap.retainedReplies, { 'correlation.kind': 'retained_replies' });\n    });\n  }\n}\n\n/** Increment the bus-emit counter. Called at every transport `emit` site. */\nexport function recordBusEmit(channel: string, scope?: string): void {\n  busEmitCounter().add(1, {\n    'bus.channel': channel,\n    ...(scope ? { 'bus.scope': scope } : {}),\n  });\n}\n\n/** Record an in-process actor handler's duration. */\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n  handlerDurationHistogram().record(durationMs, {\n    actor,\n    'bus.channel': channel,\n  });\n}\n\n/** Record a worker job's outcome and duration. */\nexport function recordJobOutcome(jobType: string, outcome: 'completed' | 'failed', durationMs: number): void {\n  jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n  jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\nlet _appendStageHistogram: Histogram | undefined;\nfunction appendStageHistogram(): Histogram {\n  if (!_appendStageHistogram) {\n    _appendStageHistogram = meter().createHistogram('semiont.record.append.duration', {\n      description: 'Time spent in one stage of appending an event to the record, labeled by stage: persist (JSONL write + git), materialize (view rebuild), enrich, publish. The Archivist\\'s core write path.',\n      unit: 'ms',\n    });\n  }\n  return _appendStageHistogram;\n}\n\n/**\n * Record one stage of `EventStore.appendEvent` (ARCHIVIST-STAYS-UP P7).\n *\n * The append path is the one operation only the Archivist can perform, and it\n * was entirely dark: reads had `recordHandlerDuration` and the bus had its own\n * counters, while writes had nothing. Stage-labeled because the useful\n * question is never \"was the append slow\" but WHICH PART — and `materialize`\n * in particular does work proportional to a resource's annotation count, so it\n * degrades with history rather than with load.\n */\nexport function recordAppendStage(\n  stage: 'persist' | 'materialize' | 'enrich' | 'publish',\n  durationMs: number,\n): void {\n  appendStageHistogram().record(durationMs, { 'record.stage': stage });\n}\n\nlet _gitCommandHistogram: Histogram | undefined;\nfunction gitCommandHistogram(): Histogram {\n  if (!_gitCommandHistogram) {\n    _gitCommandHistogram = meter().createHistogram('semiont.git.duration', {\n      description: 'Wall time of a git subprocess. Async — this is latency, not event-loop blockage. Staging is deduped, so the `add` count is far below the number of appended events.',\n      unit: 'ms',\n    });\n  }\n  return _gitCommandHistogram;\n}\n\n/**\n * Record a git invocation. Read the `add` count against events appended: one\n * per event means deferred staging has stopped deduping.\n */\nexport function recordGitCommand(command: string, durationMs: number): void {\n  gitCommandHistogram().record(durationMs, { 'git.command': command });\n}\n\nfunction gatherDegradeCounter(): Counter {\n  if (!_gatherDegradeCounter) {\n    _gatherDegradeCounter = meter().createCounter('semiont.gather.degraded', {\n      description: 'Gathers that degraded because an eventually-consistent projection did not catch up within its read barrier (vectors: absent semanticContext; graph: projection-lag failure). Labeled by projection.',\n    });\n  }\n  return _gatherDegradeCounter;\n}\n\n/**\n * Record a gather degraded by a projection read barrier: `'vectors'` — the\n * Smelter settle barrier timed out (semanticContext shipped absent);\n * `'graph'` — the Weaver applied barrier + poll floor exhausted (projection\n * lag surfaced as a distinct failure). Fleet-alertable counterpart of the\n * `[gather DEGRADED]` L4 breadcrumbs — a rising rate on either label means\n * that pipeline is not keeping up.\n */\nexport function recordGatherDegrade(projection: 'graph' | 'vectors'): void {\n  gatherDegradeCounter().add(1, { projection });\n}\n\n/** Increment the SSE subscriber gauge — call on `/bus/subscribe` open. */\nexport function recordSubscriberConnect(): void {\n  sseSubscribersCounter().add(1);\n}\n\n/** Decrement on disconnect. Pair with `recordSubscriberConnect`. */\nexport function recordSubscriberDisconnect(): void {\n  sseSubscribersCounter().add(-1);\n}\n\n/**\n * Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n */\nexport function registerJobQueueProvider(\n  provider: () => Promise<JobQueueSnapshot> | JobQueueSnapshot,\n): void {\n  _jobQueueProvider = provider;\n  if (!_jobQueueGauge) {\n    _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n      description: 'Job queue size by status',\n    });\n    _jobQueueGauge.addCallback(async (observer) => {\n      if (!_jobQueueProvider) return;\n      const snap = await _jobQueueProvider();\n      observer.observe(snap.pending, { 'job.status': 'pending' });\n      observer.observe(snap.running, { 'job.status': 'running' });\n      observer.observe(snap.complete, { 'job.status': 'complete' });\n      observer.observe(snap.failed, { 'job.status': 'failed' });\n      observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n    });\n  }\n}\n\n/**\n * Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n */\n/**\n * Register the Archivist's fact-pump backlog — facts appended to the record\n * but not yet republished onto the bus.\n *\n * At rest this is zero. A value that climbs and does not come back means the\n * pump is outrunning its transport, which is the leading hypothesis for the\n * load-correlated heap growth in `bugs/absent-archivist-wedges-browse.md`\n * (ARCHIVIST-STAYS-UP P5). The backlog is deliberately unbounded today, so\n * this number is the only thing standing between \"the pump is behind\" and an\n * OOM whose cause is inferred from RSS after the fact.\n */\nexport function registerFactPumpDepthProvider(provider: () => number): void {\n  _factPumpDepthProvider = provider;\n  if (!_factPumpDepthGauge) {\n    _factPumpDepthGauge = meter().createObservableGauge('semiont.archivist.fact_pump.depth', {\n      description: 'Facts appended to the record but not yet published to the bus. Zero at rest; a rising floor means the pump is behind its transport.',\n    });\n    _factPumpDepthGauge.addCallback((observer) => {\n      if (_factPumpDepthProvider) observer.observe(_factPumpDepthProvider());\n    });\n  }\n}\n\nexport function registerVectorIndexSizeProvider(\n  provider: () => Promise<number> | number,\n): void {\n  _vectorIndexSizeProvider = provider;\n  if (!_vectorIndexSizeGauge) {\n    _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n      description: 'Vector store point count',\n    });\n    _vectorIndexSizeGauge.addCallback(async (observer) => {\n      if (_vectorIndexSizeProvider) {\n        const value = await _vectorIndexSizeProvider();\n        observer.observe(value);\n      }\n    });\n  }\n}\n\n/**\n * Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n */\nexport function recordInferenceUsage(opts: {\n  provider: string;\n  model: string;\n  durationMs: number;\n  outcome: 'success' | 'error';\n  inputTokens?: number;\n  outputTokens?: number;\n}): void {\n  const baseAttrs = {\n    'inference.provider': opts.provider,\n    'inference.model': opts.model,\n    'inference.outcome': opts.outcome,\n  };\n  inferenceCallsCounter().add(1, baseAttrs);\n  inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n  if (opts.inputTokens != null && opts.inputTokens > 0) {\n    inferenceTokensCounter().add(opts.inputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'input',\n    });\n  }\n  if (opts.outputTokens != null && opts.outputTokens > 0) {\n    inferenceTokensCounter().add(opts.outputTokens, {\n      'inference.provider': opts.provider,\n      'inference.model': opts.model,\n      'inference.direction': 'output',\n    });\n  }\n}\n\nlet _detectionCallCounter: Counter | undefined;\nlet _detectionDurationHistogram: Histogram | undefined;\nlet _detectionItemsHistogram: Histogram | undefined;\nlet _detectionTokensHistogram: Histogram | undefined;\n\nfunction detectionCallCounter(): Counter {\n  if (!_detectionCallCounter) {\n    _detectionCallCounter = meter().createCounter('semiont.detection.calls', {\n      description: 'Detection model calls, labeled by motivation, outcome, subdivision depth and whether this was the floor re-roll.',\n    });\n  }\n  return _detectionCallCounter;\n}\n\nfunction detectionDurationHistogram(): Histogram {\n  if (!_detectionDurationHistogram) {\n    _detectionDurationHistogram = meter().createHistogram('semiont.detection.call.duration', {\n      description: 'Wall time of one detection model call, including the attempts that failed and were retried smaller.',\n      unit: 'ms',\n    });\n  }\n  return _detectionDurationHistogram;\n}\n\nfunction detectionItemsHistogram(): Histogram {\n  if (!_detectionItemsHistogram) {\n    _detectionItemsHistogram = meter().createHistogram('semiont.detection.call.items', {\n      description: 'Annotations returned by one detection call. Against the input size on the same record, this is yield.',\n    });\n  }\n  return _detectionItemsHistogram;\n}\n\nfunction detectionTokensHistogram(): Histogram {\n  if (!_detectionTokensHistogram) {\n    _detectionTokensHistogram = meter().createHistogram('semiont.detection.call.tokens', {\n      description: \"Provider-reported tokens for one detection call, by direction. Deliberately separate from semiont.inference.tokens: that series is the authoritative total but carries no subdivision depth, and 'what does a depth-2 call cost' is the question every sizing decision asks.\",\n    });\n  }\n  return _detectionTokensHistogram;\n}\n\n/**\n * Record one detection model call (DETECTION-QUALITY-THROUGHPUT P1).\n *\n * The adapters already record provider/model/duration/tokens for every\n * inference call. What they cannot know is the detection shape around it:\n * which motivation asked, how big the piece was, how many annotations came\n * back, how deep subdivision had descended, and whether this was the floor\n * re-roll. Those are the facts that distinguish a healthy call from a\n * expensive descent, and without them a slow detection run is one\n * undifferentiated number.\n *\n * FAILED attempts are recorded too, and that is the point: the calls paid for\n * and thrown away during a descent are exactly the cost later phases exist to\n * avoid, so a record only of successes would hide the thing being optimized.\n *\n * Tokens are the PROVIDER's counts, passed through — never estimated. Absent\n * means the provider did not report them.\n */\nexport function recordDetectionCall(opts: {\n  label: string;\n  pieceChars: number;\n  durationMs: number;\n  items: number;\n  depth: number;\n  reroll: boolean;\n  outcome: 'success' | 'truncated' | 'timeout' | 'collapsed' | 'error';\n  inputTokens?: number;\n  outputTokens?: number;\n}): void {\n  const attrs = {\n    'detection.label': opts.label,\n    'detection.outcome': opts.outcome,\n    'detection.depth': opts.depth,\n    'detection.reroll': opts.reroll,\n  };\n  detectionCallCounter().add(1, attrs);\n  detectionDurationHistogram().record(opts.durationMs, attrs);\n  detectionItemsHistogram().record(opts.items, attrs);\n  if (opts.inputTokens !== undefined) {\n    detectionTokensHistogram().record(opts.inputTokens, { ...attrs, 'detection.direction': 'input' });\n  }\n  if (opts.outputTokens !== undefined) {\n    detectionTokensHistogram().record(opts.outputTokens, { ...attrs, 'detection.direction': 'output' });\n  }\n}\n\nlet _anchorOutcomeCounter: Counter | undefined;\nfunction anchorOutcomeCounter(): Counter {\n  if (!_anchorOutcomeCounter) {\n    _anchorOutcomeCounter = meter().createCounter('semiont.detection.anchors', {\n      description: 'Every annotation anchoring, labeled by the method that resolved it. EVERY outcome is counted, not just the risky ones, because a bare count of degraded anchors has no denominator — the rate is the precision signal.',\n    });\n  }\n  return _anchorOutcomeCounter;\n}\n\n/**\n * Record how one annotation got anchored (DETECTION-QUALITY-THROUGHPUT P5).\n *\n * The selector-vs-source check is already a WRITE-TIME INVARIANT — both\n * `buildTextAnnotation` and `buildPdfAnnotation` throw on a selector that does\n * not match its source — so mechanical correctness is guaranteed rather than\n * sampled, and auditing it would measure a constant.\n *\n * What is genuinely uncertain is which anchoring METHOD got there. An `exact`\n * the model quoted verbatim and that appears once is certain; one resolved by\n * `first-of-many` (several occurrences, no usable context) or `fuzzy-match`\n * picked a plausible occurrence and may have picked wrong. Those were visible\n * only as log warnings — countable by a human reading worker output, which is\n * how 47 of them went unreviewed. As a rate they are the precision number that\n * sits beside the yield numbers.\n */\nexport function recordAnchorOutcome(label: string, method: string): void {\n  anchorOutcomeCounter().add(1, { 'detection.label': label, 'anchor.method': method });\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n","/**\n * Process-level structured logger for Node entry points.\n *\n * Used by long-lived Node processes (gateway, workers, smelter) that\n * want JSON-structured stdout with active-span trace correlation. The\n * `trace_id` / `span_id` fields are populated from the current OTel\n * span context via `getLogTraceContext` — this is the same Tier 3\n * correlation that lets a grep through stdout line up with the trace\n * UI without manual stitching.\n *\n * Reads `LOG_LEVEL` (default `info`) and `LOG_FORMAT` (`json` default,\n * `simple` for human-friendly dev output).\n *\n * Co-located with `getLogTraceContext` deliberately: this is the\n * only reasonably-shaped consumer of that helper, and putting them in\n * the same package keeps the trace-id wiring in one place.\n */\n\nimport winston from 'winston';\nimport type { Logger } from '@semiont/core';\nimport { getLogTraceContext } from './index.js';\n\nconst traceContextFormat = winston.format((info) => {\n  const trace = getLogTraceContext();\n  if (trace) {\n    info.trace_id = trace.trace_id;\n    info.span_id = trace.span_id;\n  }\n  return info;\n})();\n\nexport function createProcessLogger(component: string): Logger {\n  const level = process.env.LOG_LEVEL ?? 'info';\n  const format = process.env.LOG_FORMAT === 'simple'\n    ? winston.format.combine(\n        winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),\n        winston.format.errors({ stack: true }),\n        traceContextFormat,\n        winston.format.printf(({ level: lvl, message, timestamp, ...meta }) => {\n          const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';\n          return `${timestamp} [${lvl.toUpperCase()}] [${component}] ${message}${metaStr}`;\n        }),\n      )\n    : winston.format.combine(\n        winston.format.timestamp(),\n        winston.format.errors({ stack: true }),\n        traceContextFormat,\n        winston.format.json(),\n      );\n\n  const logger = winston.createLogger({\n    level,\n    defaultMeta: { component },\n    format,\n    transports: [new winston.transports.Console()],\n  });\n\n  return logger;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/observability",
-  "version": "0.5.29",
+  "version": "0.5.31",
   "description": "OpenTelemetry-based tracing for Semiont — Tier 2 of OBSERVABILITY.md. Process-init helpers (Node + Web), withSpan helper, W3C traceparent inject/extract for bus payloads. No-op when no exporter is configured.",
   "type": "module",
   "main": "dist/index.js",
@@ -63,16 +63,16 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/context-async-hooks": "^2.10.0",
-    "@opentelemetry/core": "^2.10.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
-    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/context-async-hooks": "^2.11.0",
+    "@opentelemetry/core": "^2.11.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/resources": "^2.11.0",
     "@opentelemetry/sdk-metrics": "^2.10.0",
-    "@opentelemetry/sdk-trace-base": "^2.10.0",
-    "@opentelemetry/sdk-trace-web": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@opentelemetry/sdk-trace-web": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
-    "@semiont/core": "0.5.29",
+    "@semiont/core": "0.5.31",
     "winston": "^3.17.0"
   }
 }