comisai 1.0.41 → 1.0.44

package/node_modules/@comis/observability-otel/dist/dashboard-metric-names.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The set of Prometheus metric names the exporter actually emits — counters with
+ * their `_total` suffix, gauges/observableGauges by name, and every histogram
+ * stem PLUS its `_bucket`/`_sum`/`_count` children. The drift guard asserts every
+ * dashboard panel `expr` and every recording/alert rule `expr` references ONLY a
+ * name in this set (PROM-04 / PROM-02).
+ */
+export declare const EMITTED_METRIC_NAMES: ReadonlySet<string>;
+/**
+ * Sorted array view of {@link EMITTED_METRIC_NAMES} — convenient for failure
+ * messages and the drift-guard's "did you mean" suggestions.
+ */
+export declare const EMITTED_METRIC_NAMES_SORTED: readonly string[];

package/node_modules/@comis/observability-otel/dist/dashboard-metric-names.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The emitted-metric-name SET — the truth set for the Grafana/Prometheus drift
+ * guard (PROM-04; design §6 WS7).
+ *
+ * Derived ENTIRELY from the single {@link METRIC_CATALOG} (Plan 01) so there is
+ * NO second definition to drift: the dashboards' panel `expr`s and the Prometheus
+ * recording/alert rule `expr`s are checked against {@link EMITTED_METRIC_NAMES},
+ * which is exactly the set of Prometheus series the exporter can actually emit.
+ * A renamed or removed catalog metric fails `grafana-dashboard-metrics.test.ts`
+ * instead of silently blanking a panel or a rule.
+ *
+ * **Histogram expansion.** A catalog histogram's `promName` is the STEM (e.g.
+ * `comis_run_duration_seconds`); at scrape time the exporter renders three child
+ * series — `<stem>_bucket`, `<stem>_sum`, `<stem>_count` — plus the bare stem is
+ * itself NOT a queryable series (PromQL references the children, e.g.
+ * `histogram_quantile(0.95, sum(rate(comis_run_duration_seconds_bucket[5m])))`).
+ * So for every `type: "histogram"` entry this set admits the stem AND its three
+ * families. Counters already carry the rendered `_total` suffix in `promName`
+ * (via {@link promNameFor}); gauges/observableGauges are their bare name.
+ *
+ * This is the ONE set both halves of the bidirectional drift guard consult:
+ *   (a) every dashboard panel `targets[].expr` metric ∈ this set, and
+ *   (b) every `prometheus/rules/*.yml` record/alert `expr` metric ∈ this set.
+ *
+ * @module
+ */
+import { METRIC_CATALOG } from "./metric-catalog.js";
+/** The three child series a Prometheus histogram renders at scrape time. */
+const HISTOGRAM_SUFFIXES = ["_bucket", "_sum", "_count"];
+/**
+ * Build the emitted-metric-name set from {@link METRIC_CATALOG}, expanding each
+ * histogram stem to admit its `_bucket`/`_sum`/`_count` families. Deterministic —
+ * a pure function of the frozen catalog.
+ */
+function buildEmittedMetricNames() {
+    const names = new Set();
+    for (const def of METRIC_CATALOG) {
+        names.add(def.promName);
+        if (def.type === "histogram") {
+            for (const suffix of HISTOGRAM_SUFFIXES) {
+                names.add(`${def.promName}${suffix}`);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * The set of Prometheus metric names the exporter actually emits — counters with
+ * their `_total` suffix, gauges/observableGauges by name, and every histogram
+ * stem PLUS its `_bucket`/`_sum`/`_count` children. The drift guard asserts every
+ * dashboard panel `expr` and every recording/alert rule `expr` references ONLY a
+ * name in this set (PROM-04 / PROM-02).
+ */
+export const EMITTED_METRIC_NAMES = Object.freeze(buildEmittedMetricNames());
+/**
+ * Sorted array view of {@link EMITTED_METRIC_NAMES} — convenient for failure
+ * messages and the drift-guard's "did you mean" suggestions.
+ */
+export const EMITTED_METRIC_NAMES_SORTED = Object.freeze([...EMITTED_METRIC_NAMES].sort());

package/node_modules/@comis/observability-otel/dist/exemplar-capability.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether the installed Prometheus pull surface can render OpenMetrics exemplars
+ * (a `trace_id` on a sample). Derived at build/load time by probing the installed
+ * exporter; `false` for `@opentelemetry/exporter-prometheus@0.219.0`. Gates Plan
+ * 03's PROM-04 exemplar test (strict vs documented-limitation).
+ */
+export declare const PROMETHEUS_EXEMPLARS_SUPPORTED: boolean;
+/** Human-readable description of what the probe inspected and the verdict it reached. */
+export declare const EXEMPLAR_CAPABILITY_NOTE: string;

package/node_modules/@comis/observability-otel/dist/exemplar-capability.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Build-time exemplar-capability probe (PROM-04 / Open Question A2).
+ *
+ * Exemplars (a `trace_id` riding on a sample) are the Grafana → `comis explain`
+ * drill-down primitive (E7) on the Prometheus PULL surface. They are exported
+ * ONLY in OpenMetrics format, and only when the exporter is configured for it —
+ * the OTel Collector's Prometheus exporter has an `enable_open_metrics` switch,
+ * but the JS SDK's `@opentelemetry/exporter-prometheus` has historically lagged.
+ *
+ * This module PROBES the installed exporter for an OpenMetrics/exemplar affordance
+ * and records the verdict in {@link PROMETHEUS_EXEMPLARS_SUPPORTED}. The verdict
+ * GATES Plan 03's PROM-04 test:
+ *   - `true`  → Plan 03 writes a STRICT exemplar-presence assertion on `/metrics`.
+ *   - `false` → Plan 03 documents the `/metrics`-pull limitation and realizes the
+ *               chart→explain drill-down via a panel data-link templated on a
+ *               `trace_id`-bearing alternative (the OTLP→collector path carries
+ *               exemplars regardless).
+ *
+ * The probe is conservative and NON-THROWING: a missing affordance is a `false`,
+ * never an error. It positively looks for an OpenMetrics/exemplar switch on the
+ * exporter's config options, its `DEFAULT_OPTIONS`, and its serializer surface;
+ * absence ⇒ `false`.
+ *
+ * Verified result for `@opentelemetry/exporter-prometheus@0.219.0` (its
+ * `ExporterConfig` = `{ prefix?, appendTimestamp?, endpoint?, host?, port?,
+ * preventServerStart?, metricProducers?, withResourceConstantLabels?,
+ * withoutScopeInfo?, withoutTargetInfo? }`, and the `PrometheusSerializer`
+ * constructor takes `(prefix?, appendTimestamp?, withResourceConstantLabels?,
+ * withoutTargetInfo?, withoutScopeInfo?)`): NO OpenMetrics / exemplar affordance →
+ * `PROMETHEUS_EXEMPLARS_SUPPORTED === false`.
+ *
+ * @module
+ */
+import { PrometheusExporter, PrometheusSerializer, } from "@opentelemetry/exporter-prometheus";
+/**
+ * Affordance tokens that, if present on the exporter's option keys / default
+ * options / serializer surface, would indicate OpenMetrics-exemplar support.
+ */
+const OPENMETRICS_AFFORDANCE_TOKENS = [
+    "openmetrics",
+    "exemplar",
+];
+/** True if any own/proto property name on `obj` contains an affordance token. */
+function hasAffordanceName(obj) {
+    if (!obj)
+        return false;
+    const names = new Set();
+    for (const k of Object.keys(obj))
+        names.add(k.toLowerCase());
+    const proto = Object.getPrototypeOf(obj);
+    if (proto && proto !== Object.prototype) {
+        for (const k of Object.getOwnPropertyNames(proto))
+            names.add(k.toLowerCase());
+    }
+    for (const name of names) {
+        if (OPENMETRICS_AFFORDANCE_TOKENS.some((tok) => name.includes(tok))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Probe the installed `@opentelemetry/exporter-prometheus` for an
+ * OpenMetrics/exemplar affordance. Returns `true` only on a POSITIVE find;
+ * any error or absence ⇒ `false`. Never throws.
+ */
+function probePrometheusExemplarSupport() {
+    try {
+        // 1. The exporter's static DEFAULT_OPTIONS enumerate every config key.
+        const defaultOptions = PrometheusExporter.DEFAULT_OPTIONS;
+        const optionKeys = defaultOptions ? Object.keys(defaultOptions) : [];
+        const optionHasAffordance = optionKeys.some((k) => OPENMETRICS_AFFORDANCE_TOKENS.some((tok) => k.toLowerCase().includes(tok)));
+        // 2. The exporter instance / prototype (request handler, force-flush, etc.).
+        const exporterProtoHasAffordance = hasAffordanceName(PrometheusExporter.prototype);
+        // 3. The serializer surface (where an OpenMetrics rendering path would live).
+        const serializerProtoHasAffordance = hasAffordanceName(PrometheusSerializer.prototype);
+        const supported = optionHasAffordance ||
+            exporterProtoHasAffordance ||
+            serializerProtoHasAffordance;
+        const note = supported
+            ? `OpenMetrics/exemplar affordance DETECTED on @opentelemetry/exporter-prometheus (option keys: [${optionKeys.join(", ")}]) — Plan 03 may write a strict exemplar-presence test on /metrics.`
+            : `No OpenMetrics/exemplar affordance on @opentelemetry/exporter-prometheus (ExporterConfig keys: [${optionKeys.join(", ")}]); the /metrics pull surface renders counters/histograms WITHOUT exemplars. Plan 03 must document this limitation and realize the chart→explain drill-down via a panel data-link (the OTLP→collector path carries exemplars).`;
+        return { supported, note };
+    }
+    catch (err) {
+        // A probe failure is an honest `false` (never claim support we can't verify).
+        return {
+            supported: false,
+            note: `exemplar-capability probe could not inspect @opentelemetry/exporter-prometheus (${err instanceof Error ? err.message : String(err)}); defaulting PROMETHEUS_EXEMPLARS_SUPPORTED to false.`,
+        };
+    }
+}
+const PROBE = probePrometheusExemplarSupport();
+/**
+ * Whether the installed Prometheus pull surface can render OpenMetrics exemplars
+ * (a `trace_id` on a sample). Derived at build/load time by probing the installed
+ * exporter; `false` for `@opentelemetry/exporter-prometheus@0.219.0`. Gates Plan
+ * 03's PROM-04 exemplar test (strict vs documented-limitation).
+ */
+export const PROMETHEUS_EXEMPLARS_SUPPORTED = PROBE.supported;
+/** Human-readable description of what the probe inspected and the verdict it reached. */
+export const EXEMPLAR_CAPABILITY_NOTE = PROBE.note;

package/node_modules/@comis/observability-otel/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@comis/observability-otel` — the monorepo's first OPT-IN extension package.
+ *
+ * Maps the existing `@comis/core` event bus (the `observability:*` /
+ * `security:*` signals 176/177 already emit) onto OpenTelemetry instruments,
+ * exposed on two surfaces from ONE metric definition: OTLP push (traces /
+ * metrics / logs) and a Prometheus `/metrics` pull. The daemon loads this
+ * package ONLY when `observability.otel.enabled || observability.prometheus.enabled`
+ * via a config-gated `await import("@comis/observability-otel")` — core and
+ * daemon build with this package's `dist/` absent (N2; see
+ * `test/architecture/build-without-extension.test.ts`).
+ *
+ * This barrel exposes:
+ *   - {@link OtelExporterDeps} — the type-only contract the daemon seam imports
+ *     (`import type { OtelExporterDeps } from "@comis/observability-otel"`), so
+ *     the daemon types the `await import()` result WITHOUT a static value-import
+ *     or a tsconfig project-reference.
+ *   - the single metric catalog (`METRIC_CATALOG` / `MetricDef` / `promNameFor`)
+ *     consumed by both the OTLP and Prometheus surfaces (Plan 02 — one mapping,
+ *     two readers).
+ *   - the build-time exemplar-capability probe (`PROMETHEUS_EXEMPLARS_SUPPORTED`).
+ *
+ * The runtime registration entry-point (`registerOtelExporter`) lands in Plan 02;
+ * this plan ships the skeleton, the catalog, and the probe.
+ *
+ * @module
+ */
+export { METRIC_CATALOG, METRIC_LABELS, promNameFor, } from "./metric-catalog.js";
+export type { MetricDef, MetricInstrumentType, MetricLabel, } from "./metric-catalog.js";
+export { EMITTED_METRIC_NAMES, EMITTED_METRIC_NAMES_SORTED, } from "./dashboard-metric-names.js";
+export { PROMETHEUS_EXEMPLARS_SUPPORTED, EXEMPLAR_CAPABILITY_NOTE, } from "./exemplar-capability.js";
+export { registerOtelExporter } from "./otel-exporter.js";
+export type { OtelExporterDeps, OtelExporterHandle } from "./otel-exporter.js";
+export { wireMetricMapping } from "./metric-mapping.js";
+export type { WireMetricMappingDeps, SpendCeilingsView } from "./metric-mapping.js";
+export { redactAttributes } from "./redact-attributes.js";
+export { emitTurnSpan } from "./traces.js";
+export type { TurnSpanArgs, SpanMessage } from "./traces.js";
+export type { SpendSnapshotReader } from "./spend-snapshot.js";

package/node_modules/@comis/observability-otel/dist/index.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `@comis/observability-otel` — the monorepo's first OPT-IN extension package.
+ *
+ * Maps the existing `@comis/core` event bus (the `observability:*` /
+ * `security:*` signals 176/177 already emit) onto OpenTelemetry instruments,
+ * exposed on two surfaces from ONE metric definition: OTLP push (traces /
+ * metrics / logs) and a Prometheus `/metrics` pull. The daemon loads this
+ * package ONLY when `observability.otel.enabled || observability.prometheus.enabled`
+ * via a config-gated `await import("@comis/observability-otel")` — core and
+ * daemon build with this package's `dist/` absent (N2; see
+ * `test/architecture/build-without-extension.test.ts`).
+ *
+ * This barrel exposes:
+ *   - {@link OtelExporterDeps} — the type-only contract the daemon seam imports
+ *     (`import type { OtelExporterDeps } from "@comis/observability-otel"`), so
+ *     the daemon types the `await import()` result WITHOUT a static value-import
+ *     or a tsconfig project-reference.
+ *   - the single metric catalog (`METRIC_CATALOG` / `MetricDef` / `promNameFor`)
+ *     consumed by both the OTLP and Prometheus surfaces (Plan 02 — one mapping,
+ *     two readers).
+ *   - the build-time exemplar-capability probe (`PROMETHEUS_EXEMPLARS_SUPPORTED`).
+ *
+ * The runtime registration entry-point (`registerOtelExporter`) lands in Plan 02;
+ * this plan ships the skeleton, the catalog, and the probe.
+ *
+ * @module
+ */
+// The single metric definition (name/type/unit/labels) — consumed by BOTH the
+// OTLP push and Prometheus pull surfaces in Plan 02, so the two readers can
+// never drift. The closed MetricLabel union is the no-high-cardinality guard.
+export { METRIC_CATALOG, METRIC_LABELS, promNameFor, } from "./metric-catalog.js";
+// The emitted-metric-name SET (derived from METRIC_CATALOG, histograms expanded
+// to their _bucket/_sum/_count families) — the truth set the Grafana/Prometheus
+// expr↔metric drift guard (`test/architecture/grafana-dashboard-metrics.test.ts`)
+// checks every panel + rule `expr` against (PROM-04 / PROM-02). One catalog, one
+// set, no second definition to drift.
+export { EMITTED_METRIC_NAMES, EMITTED_METRIC_NAMES_SORTED, } from "./dashboard-metric-names.js";
+// The build-time probe of the installed @opentelemetry/exporter-prometheus —
+// records whether the `/metrics` surface can render OpenMetrics exemplars
+// (gates Plan 03's PROM-04 test).
+export { PROMETHEUS_EXEMPLARS_SUPPORTED, EXEMPLAR_CAPABILITY_NOTE, } from "./exemplar-capability.js";
+// The runtime registration entry-point (the config-gated daemon seam in Plan 03
+// imports `OtelExporterDeps` type-only + calls `registerOtelExporter` via the
+// dynamic await import()) + the bus→instrument subscriber, the content-free
+// re-redaction boundary (E3), and the span helpers. Loaded ONLY via the daemon's
+// config-gated await import() (N2 — core/daemon never value-import this).
+export { registerOtelExporter } from "./otel-exporter.js";
+export { wireMetricMapping } from "./metric-mapping.js";
+export { redactAttributes } from "./redact-attributes.js";
+export { emitTurnSpan } from "./traces.js";

package/node_modules/@comis/observability-otel/dist/metric-catalog.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The SINGLE metric catalog (design §6 WS7; OTEL-02 / PROM-01).
+ *
+ * ONE definition of every Comis metric — its dotted OTel `otelName`, the rendered
+ * Prometheus `promName`, the instrument `type`, the base `unit`, and the
+ * low-cardinality `labels`. Plan 02's OTLP push surface (`PeriodicExportingMetricReader`)
+ * and Prometheus pull surface (`PrometheusExporter`) BOTH read this catalog, so
+ * the two surfaces render the SAME series and can never drift (Pitfall 2 — one
+ * `MeterProvider`, two readers, one catalog).
+ *
+ * Two invariants are enforced HERE, at the source, so Plans 02/03 cannot regress them:
+ *
+ *   1. **No high-cardinality label.** {@link MetricLabel} is a CLOSED union and
+ *      deliberately EXCLUDES `session`/`trace`/`user` (and every id variant). The
+ *      UUID `traceId` rides as a Prometheus EXEMPLAR / span attribute, never a
+ *      series label (Pitfall 4; threat T-178-03 — a label-cardinality DoS + PII
+ *      surface). `metric-catalog.test.ts` asserts no entry uses a forbidden label.
+ *
+ *   2. **`comis_build_info` carries `version` only — no `commit`.** No
+ *      `git rev-parse` runs at daemon boot (verified — Pitfall 7 / decision #5),
+ *      so a `commit` label would be a runtime-unavailable phantom. `version`
+ *      comes from `pkgJson.version` (`setup-logging.ts`).
+ *
+ * The dotted `otelName` ENCODES the Prometheus stem (minus the counter `_total`
+ * suffix): e.g. the histogram `comis.run.duration.seconds` renders
+ * `comis_run_duration_seconds`; the gauge `comis.build_info` renders
+ * `comis_build_info`. {@link promNameFor} is the deterministic dots→underscores +
+ * `_total`-on-counters rendering; every entry's `promName` round-trips through it
+ * (asserted in the test). The `unit` field is the OTel instrument unit (UCUM-ish:
+ * `usd`, `{token}`, `s`, `1`, `By`), distinct from the name's unit suffix.
+ *
+ * @module
+ */
+/**
+ * The CLOSED low-cardinality label union. Adding a label here is a deliberate act;
+ * `session`/`trace`/`user`/`sessionKey`/`traceId`/`userId` are intentionally
+ * absent (ids ride as exemplars — Pitfall 4). The union being closed IS the
+ * no-high-cardinality guard at the type level; the catalog test is the runtime guard.
+ */
+export type MetricLabel = "agent" | "tenant" | "provider" | "model" | "channel" | "operation" | "tool" | "reason" | "pricing_state" | "error_kind" | "outcome" | "type" | "scope" | "state" | "severity" | "kind" | "lane" | "version";
+/**
+ * The runtime mirror of {@link MetricLabel} (a frozen tuple). Used by the catalog
+ * test + Plan 02's instrument construction to validate a label set at runtime
+ * (the type union is erased at runtime). MUST stay in lockstep with the union.
+ */
+export declare const METRIC_LABELS: readonly ["agent", "tenant", "provider", "model", "channel", "operation", "tool", "reason", "pricing_state", "error_kind", "outcome", "type", "scope", "state", "severity", "kind", "lane", "version"];
+/** The OpenTelemetry instrument kind backing a metric. */
+export type MetricInstrumentType = "counter" | "gauge" | "histogram" | "observableGauge";
+/** One metric's complete, single-source definition. */
+export interface MetricDef {
+    /** The dotted OTel instrument name (encodes the Prometheus stem). */
+    readonly otelName: string;
+    /** The rendered Prometheus name (snake_case; `_total` on counters). */
+    readonly promName: string;
+    /** The OpenTelemetry instrument kind. */
+    readonly type: MetricInstrumentType;
+    /** The OTel instrument unit (UCUM-ish: `usd`, `{token}`, `s`, `1`, `By`; `""` for dimensionless meta gauges). */
+    readonly unit: string;
+    /** The closed low-cardinality label set for this series (ids ride as exemplars, never here). */
+    readonly labels: readonly MetricLabel[];
+    /** One-line human description (renders as Prometheus `# HELP`). */
+    readonly description: string;
+}
+/**
+ * Render a dotted OTel instrument name to its Prometheus name: dots → underscores,
+ * with a single `_total` suffix appended for counters (idempotent — not re-added
+ * if the dotted name already ends in `total`). Histograms/gauges get no suffix
+ * here (the exporter adds `_bucket`/`_sum`/`_count` to a histogram at scrape time;
+ * the catalog's `promName` is the stem). Deterministic — same input, same output.
+ */
+export declare function promNameFor(otelName: string, type: MetricInstrumentType): string;
+/**
+ * The comprehensive metric catalog — the design §6 WS7 table + the RESEARCH
+ * §"Metric Catalog + Sources" dotted names. Counts/enums only; every label is a
+ * {@link MetricLabel} (no high-cardinality id). The render-time `_total` suffix on
+ * counters and the histogram `_bucket`/`_sum`/`_count` sub-series are the
+ * exporter's job; this is the source set those derive from.
+ */
+export declare const METRIC_CATALOG: readonly MetricDef[];

package/node_modules/@comis/observability-otel/dist/metric-catalog.js

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The SINGLE metric catalog (design §6 WS7; OTEL-02 / PROM-01).
+ *
+ * ONE definition of every Comis metric — its dotted OTel `otelName`, the rendered
+ * Prometheus `promName`, the instrument `type`, the base `unit`, and the
+ * low-cardinality `labels`. Plan 02's OTLP push surface (`PeriodicExportingMetricReader`)
+ * and Prometheus pull surface (`PrometheusExporter`) BOTH read this catalog, so
+ * the two surfaces render the SAME series and can never drift (Pitfall 2 — one
+ * `MeterProvider`, two readers, one catalog).
+ *
+ * Two invariants are enforced HERE, at the source, so Plans 02/03 cannot regress them:
+ *
+ *   1. **No high-cardinality label.** {@link MetricLabel} is a CLOSED union and
+ *      deliberately EXCLUDES `session`/`trace`/`user` (and every id variant). The
+ *      UUID `traceId` rides as a Prometheus EXEMPLAR / span attribute, never a
+ *      series label (Pitfall 4; threat T-178-03 — a label-cardinality DoS + PII
+ *      surface). `metric-catalog.test.ts` asserts no entry uses a forbidden label.
+ *
+ *   2. **`comis_build_info` carries `version` only — no `commit`.** No
+ *      `git rev-parse` runs at daemon boot (verified — Pitfall 7 / decision #5),
+ *      so a `commit` label would be a runtime-unavailable phantom. `version`
+ *      comes from `pkgJson.version` (`setup-logging.ts`).
+ *
+ * The dotted `otelName` ENCODES the Prometheus stem (minus the counter `_total`
+ * suffix): e.g. the histogram `comis.run.duration.seconds` renders
+ * `comis_run_duration_seconds`; the gauge `comis.build_info` renders
+ * `comis_build_info`. {@link promNameFor} is the deterministic dots→underscores +
+ * `_total`-on-counters rendering; every entry's `promName` round-trips through it
+ * (asserted in the test). The `unit` field is the OTel instrument unit (UCUM-ish:
+ * `usd`, `{token}`, `s`, `1`, `By`), distinct from the name's unit suffix.
+ *
+ * @module
+ */
+/**
+ * The runtime mirror of {@link MetricLabel} (a frozen tuple). Used by the catalog
+ * test + Plan 02's instrument construction to validate a label set at runtime
+ * (the type union is erased at runtime). MUST stay in lockstep with the union.
+ */
+export const METRIC_LABELS = Object.freeze([
+    "agent",
+    "tenant",
+    "provider",
+    "model",
+    "channel",
+    "operation",
+    "tool",
+    "reason",
+    "pricing_state",
+    "error_kind",
+    "outcome",
+    "type",
+    "scope",
+    "state",
+    "severity",
+    "kind",
+    "lane",
+    "version",
+]);
+/**
+ * Render a dotted OTel instrument name to its Prometheus name: dots → underscores,
+ * with a single `_total` suffix appended for counters (idempotent — not re-added
+ * if the dotted name already ends in `total`). Histograms/gauges get no suffix
+ * here (the exporter adds `_bucket`/`_sum`/`_count` to a histogram at scrape time;
+ * the catalog's `promName` is the stem). Deterministic — same input, same output.
+ */
+export function promNameFor(otelName, type) {
+    const base = otelName.replace(/\./g, "_");
+    if (type === "counter" && !base.endsWith("_total")) {
+        return `${base}_total`;
+    }
+    return base;
+}
+/** Helper: build a {@link MetricDef}, deriving `promName` via {@link promNameFor}. */
+function def(otelName, type, unit, labels, description) {
+    return Object.freeze({
+        otelName,
+        promName: promNameFor(otelName, type),
+        type,
+        unit,
+        labels: Object.freeze([...labels]),
+        description,
+    });
+}
+/**
+ * The comprehensive metric catalog — the design §6 WS7 table + the RESEARCH
+ * §"Metric Catalog + Sources" dotted names. Counts/enums only; every label is a
+ * {@link MetricLabel} (no high-cardinality id). The render-time `_total` suffix on
+ * counters and the histogram `_bucket`/`_sum`/`_count` sub-series are the
+ * exporter's job; this is the source set those derive from.
+ */
+export const METRIC_CATALOG = Object.freeze([
+    // ── Tokens & cost ────────────────────────────────────────────────────────
+    def("comis.tokens", "counter", "{token}", ["agent", "tenant", "provider", "model", "operation", "type"], "Total tokens consumed (prompt/completion/total via the type label)."),
+    def("comis.cost.usd", "counter", "usd", ["agent", "tenant", "provider", "model", "operation"], "Corrected USD cost (the SDK-reconciled cost.total, not an estimate)."),
+    def("comis.cost_correction.usd", "counter", "usd", ["provider", "model"], "USD delta between the SDK-reported and Comis-corrected cost (costCorrection.delta)."),
+    // ── Cache ────────────────────────────────────────────────────────────────
+    def("comis.cache.saved.usd", "counter", "usd", ["agent", "provider", "model"], "USD saved versus an uncached prompt (savedVsUncached)."),
+    def("comis.cache.read_ratio", "histogram", "1", ["provider", "model"], "Distribution of cache-read tokens as a fraction of total tokens per turn."),
+    def("comis.cache.break", "counter", "1", ["reason", "scope"], "Prompt-cache breaks by reason (one of the 15 cache-break reasons) and scope."),
+    // NOTE: comis.cache.break.cost.usd was REMOVED (CR-01). The
+    // `observability:cache_break` bus event carries NO cost field — `estCostUsd`
+    // is COMPUTED downstream in obs-explain-signals.ts from persisted records, not
+    // emitted on the bus. Wiring it would require a NEW emit (violates N1 — the
+    // extension only subscribes existing signals), so the metric was genuinely
+    // unsourced and is removed from the catalog + every dashboard panel + every
+    // Prometheus rule (the cost-by-reason view lives in `comis explain`, not here).
+    // ── Pricing coverage (E1) ─────────────────────────────────────────────────
+    def("comis.pricing.turns", "counter", "1", ["state"], "Turns by pricing state (priced/free/unknown) — the pricing-coverage signal."),
+    def("comis.pricing.unknown", "counter", "1", ["provider", "model"], "Turns whose pricing state is unknown (the pricing-gap subset of pricing.turns)."),
+    // ── Spend kill-switch (WS3) ───────────────────────────────────────────────
+    def("comis.spend.usd", "observableGauge", "usd", ["scope"], "Current cumulative spend per scope (agent/tenant/global) from the spend accumulator."),
+    def("comis.spend.ceiling.usd", "observableGauge", "usd", ["scope"], "Configured spend ceiling per scope (the kill-switch limit)."),
+    def("comis.spend.headroom.usd", "observableGauge", "usd", ["scope"], "Remaining headroom (ceiling − current spend) per scope."),
+    def("comis.spend.warning", "counter", "1", ["scope"], "Spend-warning events (a reserve crossed warnAtFraction) by scope."),
+    def("comis.spend.exceeded", "counter", "1", ["scope"], "Spend-exceeded events (a reserve was refused at the ceiling) by scope."),
+    def("comis.spend.unpriceable", "counter", "1", ["scope"], "Unpriceable-spend events (a turn could not be priced) by scope."),
+    // ── Runtime / reliability ─────────────────────────────────────────────────
+    def("comis.run.duration.seconds", "histogram", "s", ["agent", "operation"], "Per-operation run duration in seconds (base unit)."),
+    def("comis.turns", "counter", "1", ["agent", "outcome"], "Completed turns by agent and outcome."),
+    def("comis.tool_calls", "counter", "1", ["agent", "tool", "outcome", "error_kind"], "Tool calls by agent, tool, outcome, and error kind."),
+    def("comis.breaker_trips", "counter", "1", ["agent", "tool"], "Circuit-breaker trips by agent and tool."),
+    def("comis.offloads", "counter", "1", ["agent", "tool"], "Large-result offloads by agent and tool."),
+    def("comis.sessions", "counter", "1", ["agent", "severity"], "Sessions observed by agent and severity (fleet rollup)."),
+    def("comis.sessions.degraded", "counter", "1", ["agent", "severity"], "Degraded sessions by agent and severity (fleet rollup)."),
+    // ── Security / audit (WS1) ────────────────────────────────────────────────
+    def("comis.audit_events", "counter", "1", ["kind", "outcome", "severity"], "Audit events by kind, outcome, and severity."),
+    def("comis.secret_access", "counter", "1", ["outcome"], "Secret-access events by outcome."),
+    def("comis.injection_detected", "counter", "1", ["outcome"], "Prompt-injection detections by outcome (counts only — no content)."),
+    // ── Recall (memory) ───────────────────────────────────────────────────────
+    def("comis.recall", "counter", "1", ["agent", "lane"], "Memory recalls by agent and lane."),
+    def("comis.recall.zero_hits", "counter", "1", ["agent", "lane"], "Memory recalls that returned zero hits, by agent and lane."),
+    // ── Meta / self-cardinality ───────────────────────────────────────────────
+    def("comis.build_info", 
+    // observableGauge — a constant series can only be emitted via a pull callback
+    // (registered in metric-mapping's wireMetaGauges).
+    "observableGauge", "", 
+    // version ONLY — NO commit (Pitfall 7 / decision #5: no git rev-parse at runtime).
+    ["version"], "Build info gauge (constant 1) carrying the daemon version label."),
+    def("comis.up", 
+    // observableGauge — constant 1 observed on every scrape (pull callback).
+    "observableGauge", "", [], "Exporter liveness gauge (constant 1 while the exporter runs)."),
+    def("comis.prometheus_series", "gauge", "", [], "Self-reported active series count (the cardinalityCap guard)."),
+]);

package/node_modules/@comis/observability-otel/dist/metric-mapping.d.ts

@@ -0,0 +1,60 @@
+/**
+ * OTEL-02 / PROM-01 — the bus-event → OTel-instrument subscriber.
+ *
+ * `wireMetricMapping(deps)` is the extension's whole metric INPUT surface. It
+ * follows the `obs-audit-sink.ts` `wireAuditSink` shape (one `eventBus.on` per
+ * source event), but maps each typed payload to a CONTENT-FREE OTel instrument
+ * increment off the single {@link METRIC_CATALOG} (Plan 01 — one definition, two
+ * readers, so the OTLP push and Prometheus pull surfaces can never drift).
+ *
+ * Two invariants are upheld HERE:
+ *   1. **Content-free / low-cardinality labels.** Every label is a catalog
+ *      {@link MetricLabel} (ids/enums/counts only). The AsyncLocalStorage
+ *      `traceId` is a UUID and rides as a span ATTRIBUTE / exemplar value
+ *      (Pitfall 4) — NEVER a metric label. Every attribute bag is additionally
+ *      routed through {@link redactAttributes} (E3 defense-in-depth) before it
+ *      reaches an instrument. Label VALUES are bounded too, not just KEYS: an
+ *      open-ended `reason` is mapped to the closed cache-break set (else `"other"`,
+ *      MD-02), and `provider`/`model` are the CONFIG-RESOLVED provider/model ids
+ *      (the value the resolver settled on for the turn — a closed-ish set of
+ *      configured aliases, NOT a raw request string), so a fat-fingered or
+ *      injected model ref cannot fan the series out per the chimera incident.
+ *   2. **No new emit (N1).** The extension only SUBSCRIBES the existing
+ *      `observability:*` / `security:*` signals 176/177 already emit.
+ *
+ * The spend `observableGauge`s (`comis.spend.{usd,ceiling.usd,headroom.usd}`)
+ * read `spendAccumulator.getSnapshot()` (Pitfall 3) through `addCallback` —
+ * headroom = ceiling − current spend per scope (ceiling from the injected
+ * config). They register ONLY when an accumulator is provided.
+ *
+ * @module
+ */
+import type { Meter } from "@opentelemetry/api";
+import type { TypedEventBus } from "@comis/core";
+import type { SpendSnapshotReader } from "./spend-snapshot.js";
+/** The per-scope ceilings the headroom gauge subtracts from (from config). */
+export interface SpendCeilingsView {
+    readonly perAgentUsd: number | null;
+    readonly perTenantUsd: number | null;
+    readonly daemonGlobalUsd: number | null;
+}
+/** Dependencies for {@link wireMetricMapping} (the `wireAuditSink` shape). */
+export interface WireMetricMappingDeps {
+    /** The OTel meter (built once off the single MeterProvider in the exporter). */
+    readonly meter: Meter;
+    /** The typed event bus — the extension's only input (subscribe, never emit). */
+    readonly eventBus: TypedEventBus;
+    /** The 177 spend accumulator's read accessor — the `comis_spend_*` gauge source. */
+    readonly spendAccumulator?: SpendSnapshotReader;
+    /** The per-scope spend ceilings (config) the headroom gauge subtracts from. */
+    readonly ceilings?: SpendCeilingsView;
+    /** The daemon version label for `comis_build_info` (from `pkgJson.version`; "unknown" when absent). */
+    readonly version?: string;
+}
+/**
+ * Subscribe the bus → instrument mapping. Returns nothing — the caller (the
+ * exporter) owns the MeterProvider's lifecycle. Each handler maps a typed payload
+ * to a content-free catalog instrument; the `traceId` (when present) rides as a
+ * span attribute / exemplar elsewhere, never as a metric label here.
+ */
+export declare function wireMetricMapping(deps: WireMetricMappingDeps): void;