comisai 1.0.44 → 1.0.46

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

@@ -3,12 +3,12 @@
  * `@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,
+ * `security:*` signals other layers 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
+ * daemon build with this package's `dist/` absent (see
  * `test/architecture/build-without-extension.test.ts`).
  *
  * This barrel exposes:
@@ -17,34 +17,33 @@
  *     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,
+ *     consumed by both the OTLP and Prometheus surfaces (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.
+ * The runtime registration entry-point (`registerOtelExporter`) and the
+ * bus→instrument subscriber are exposed below.
  *
  * @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
+// OTLP push and Prometheus pull surfaces, 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
+// checks every panel + rule `expr` against. 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).
+// records whether the `/metrics` surface can render OpenMetrics exemplars.
 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).
+// The runtime registration entry-point (the config-gated daemon seam imports
+// `OtelExporterDeps` type-only + calls `registerOtelExporter` via the dynamic
+// await import()) + the bus→instrument subscriber, the content-free re-redaction
+// boundary, and the span helpers. Loaded ONLY via the daemon's config-gated
+// await import() — core/daemon never value-import this.
 export { registerOtelExporter } from "./otel-exporter.js";
 export { wireMetricMapping } from "./metric-mapping.js";
 export { redactAttributes } from "./redact-attributes.js";

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

@@ -1,25 +1,25 @@
 /**
- * The SINGLE metric catalog (design §6 WS7; OTEL-02 / PROM-01).
+ * The SINGLE metric catalog.
  *
  * 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`)
+ * low-cardinality `labels`. The 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
+ * the two surfaces render the SAME series and can never drift (one
  * `MeterProvider`, two readers, one catalog).
  *
- * Two invariants are enforced HERE, at the source, so Plans 02/03 cannot regress them:
+ * Two invariants are enforced HERE, at the source, so later wiring 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.
+ *      series label (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`).
+ *      `git rev-parse` runs at daemon boot (verified), 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
@@ -34,13 +34,13 @@
 /**
  * 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
+ * absent (ids ride as exemplars). 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
+ * test + the 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"];
@@ -70,8 +70,7 @@ export interface MetricDef {
  */
 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
+ * The comprehensive metric catalog. 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.

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

@@ -1,26 +1,26 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The SINGLE metric catalog (design §6 WS7; OTEL-02 / PROM-01).
+ * The SINGLE metric catalog.
  *
  * 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`)
+ * low-cardinality `labels`. The 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
+ * the two surfaces render the SAME series and can never drift (one
  * `MeterProvider`, two readers, one catalog).
  *
- * Two invariants are enforced HERE, at the source, so Plans 02/03 cannot regress them:
+ * Two invariants are enforced HERE, at the source, so later wiring 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.
+ *      series label (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`).
+ *      `git rev-parse` runs at daemon boot (verified), 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
@@ -34,7 +34,7 @@
  */
 /**
  * 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
+ * test + the 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([
@@ -83,8 +83,7 @@ function def(otelName, type, unit, 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
+ * The comprehensive metric catalog. 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.
@@ -98,17 +97,16 @@ export const METRIC_CATALOG = Object.freeze([
     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
+    // NOTE: there is no comis.cache.break.cost.usd metric. 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) ─────────────────────────────────────────────────
+    // emitted on the bus. Wiring it would require a NEW emit (this extension only
+    // subscribes to existing signals), so the metric would be genuinely unsourced;
+    // the cost-by-reason view lives in `comis explain`, not here.
+    // ── Pricing coverage ─────────────────────────────────────────────────
     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) ───────────────────────────────────────────────
+    // ── Spend kill-switch ───────────────────────────────────────────────
     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."),
@@ -123,7 +121,7 @@ export const METRIC_CATALOG = Object.freeze([
     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) ────────────────────────────────────────────────
+    // ── Security / audit ────────────────────────────────────────────────
     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)."),
@@ -135,7 +133,7 @@ export const METRIC_CATALOG = Object.freeze([
     // 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 ONLY — NO commit (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).

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

@@ -1,29 +1,29 @@
 /**
- * OTEL-02 / PROM-01 — the bus-event → OTel-instrument subscriber.
+ * 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
+ * increment off the single {@link METRIC_CATALOG} (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
+ *      — NEVER a metric label. Every attribute bag is additionally
+ *      routed through {@link redactAttributes} (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
+ *      open-ended `reason` is mapped to the closed cache-break set (else `"other"`),
+ *      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.
+ *      injected model ref cannot fan the series out.
+ *   2. **No new emit.** The extension only SUBSCRIBES the existing
+ *      `observability:*` / `security:*` signals that other layers already emit.
  *
  * The spend `observableGauge`s (`comis.spend.{usd,ceiling.usd,headroom.usd}`)
- * read `spendAccumulator.getSnapshot()` (Pitfall 3) through `addCallback` —
+ * read `spendAccumulator.getSnapshot()` through `addCallback` —
  * headroom = ceiling − current spend per scope (ceiling from the injected
  * config). They register ONLY when an accumulator is provided.
  *
@@ -44,7 +44,7 @@ export interface WireMetricMappingDeps {
     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. */
+    /** The 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;

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

@@ -1,7 +1,7 @@
 import { METRIC_CATALOG } from "./metric-catalog.js";
 import { redactAttributes } from "./redact-attributes.js";
 /**
- * The closed set of cache-break reasons (MD-02). A RUNTIME mirror of the
+ * The closed set of cache-break reasons. A RUNTIME mirror of the
  * `CacheBreakReason` union in `@comis/agent`
  * (executor/cache-detection/cache-state-types.ts) — declared LOCALLY (not
  * imported) so the extension keeps its narrow dependency surface
@@ -10,7 +10,7 @@ import { redactAttributes } from "./redact-attributes.js";
  * The `observability:cache_break` bus payload types `reason` as a bare `string`
  * (wider than the union — the closed label union guarantees the KEY `reason`,
  * NOT its VALUE). An unknown reason reaching the `reason` LABEL verbatim is an
- * unbounded-cardinality series (T-178-07). {@link boundedReason} maps any value
+ * unbounded-cardinality series. {@link boundedReason} maps any value
  * outside this set to `"other"` before it becomes a label.
  *
  * MUST stay in lockstep with the union; if a new reason is added there, add it
@@ -35,7 +35,7 @@ const KNOWN_CACHE_BREAK_REASONS = new Set([
 ]);
 /**
  * Bound a cache-break `reason` to the closed set before it becomes a metric
- * label (MD-02). A known reason passes through verbatim; ANY other value (a new
+ * label. A known reason passes through verbatim; ANY other value (a new
  * emit, a bug, a hostile high-cardinality string) is bucketed to `"other"`, so a
  * single unexpected reason can never explode the `comis_cache_break_total`
  * series count.
@@ -77,7 +77,7 @@ function recordHistogram(instruments, otelName, value, labels) {
     histogram.record(value, redactAttributes(labels));
 }
 /**
- * Register the spend `observableGauge`s reading `getSnapshot()` (Pitfall 3). The
+ * Register the spend `observableGauge`s reading `getSnapshot()`. The
  * snapshot's `perAgent`/`perTenant`/`global` totals feed `comis.spend.usd`; the
  * config ceilings feed `comis.spend.ceiling.usd`; headroom = ceiling − spend per
  * scope feeds `comis.spend.headroom.usd`. Content-free: a closed `scope` label +
@@ -148,8 +148,8 @@ function wireSpendGauges(deps) {
 /**
  * Register the meta gauges `comis_up` (exporter-liveness; constant 1 while the
  * MeterProvider runs) and `comis_build_info{version}` (constant 1 carrying the
- * daemon version label — version ONLY, NO commit; Pitfall 7 / decision #5: no
- * git rev-parse at runtime). Both are pull-based `observableGauge`s — the only
+ * daemon version label — version ONLY, NO commit; no git rev-parse runs at
+ * daemon boot). Both are pull-based `observableGauge`s — the only
  * way to expose a constant series — observed on every scrape. `comis_up` going
  * absent (no scrape) IS the liveness signal the fleet dashboard alerts on.
  */
@@ -236,7 +236,7 @@ export function wireMetricMapping(deps) {
             agent: payload.agentId,
             outcome: turnOutcome(payload.finishReason, payload.stopReason),
         });
-        // Pricing coverage (E1): a turn that billed > $0 is `priced`, a $0 turn is
+        // Pricing coverage: a turn that billed > $0 is `priced`, a $0 turn is
         // `free` (local-first). The `unknown` state rides spend_unpriceable below.
         addCounter(instruments, "comis.pricing.turns", 1, {
             state: payload.cost.total > 0 ? "priced" : "free",
@@ -245,7 +245,7 @@ export function wireMetricMapping(deps) {
     // ── observability:cache_break → cache-break by reason + scope ──
     eventBus.on("observability:cache_break", (payload) => {
         addCounter(instruments, "comis.cache.break", 1, {
-            // MD-02: the payload types `reason` as a bare string (wider than the closed
+            // The payload types `reason` as a bare string (wider than the closed
             // CacheBreakReason union). Bound it to the known set — an unknown/new reason
             // is bucketed to "other" so it cannot explode the series cardinality.
             reason: boundedReason(payload.reason),
@@ -265,7 +265,7 @@ export function wireMetricMapping(deps) {
         // the spend.unpriceable label set — the catalog's spend.unpriceable carries
         // `scope` only; an unpriceable turn is not scoped by a ceiling, bare count).
         addCounter(instruments, "comis.spend.unpriceable", 1, {});
-        // E1 pricing-coverage: an unpriceable turn is the `unknown` pricing state +
+        // Pricing-coverage: an unpriceable turn is the `unknown` pricing state +
         // the per-(provider,model) pricing-gap counter (provider/model are config
         // ids — a model id is a config value, NOT user content; §2.7).
         addCounter(instruments, "comis.pricing.turns", 1, { state: "unknown" });

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

@@ -1,6 +1,6 @@
 import type { AppConfig, ClockPort, TypedEventBus, ComisLogger } from "@comis/core";
 import type { SpendSnapshotReader } from "./spend-snapshot.js";
-/** The dependency contract the daemon's config-gated load seam passes in (Plan 03 wires it). */
+/** The dependency contract the daemon's config-gated load seam passes in. */
 export interface OtelExporterDeps {
     /** The typed event bus the extension subscribes for live metric increments. */
     readonly eventBus: TypedEventBus;
@@ -8,7 +8,7 @@ export interface OtelExporterDeps {
     readonly clock: ClockPort;
     /** The resolved observability config (the `otel` / `prometheus` keys gate everything). */
     readonly observability: AppConfig["observability"];
-    /** The 177 spend accumulator's read accessor — the `comis_spend_*` gauge source. */
+    /** The spend accumulator's read accessor — the `comis_spend_*` gauge source. */
     readonly spendAccumulator?: SpendSnapshotReader;
     /** The daemon version label for `comis_build_info` (from `pkgJson.version`). */
     readonly version?: string;

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

@@ -1,21 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The OTLP + Prometheus exporter registration (OTEL-01/02 / PROM-01).
+ * The OTLP + Prometheus exporter registration.
  *
  * `registerOtelExporter` builds the OTel SDK surface from ONE metric definition
- * (the Plan 01 catalog, via `wireMetricMapping`) and TWO readers on a SINGLE
- * `MeterProvider` (decision #3 / Pitfall 2 — the OTLP `PeriodicExportingMetricReader`
+ * (the catalog, via `wireMetricMapping`) and TWO readers on a SINGLE
+ * `MeterProvider` (the OTLP `PeriodicExportingMetricReader`
  * AND the `PrometheusExporter`, each gated on its OWN enable flag so `/metrics`
  * serves STANDALONE with `otel.enabled:false`). It also wires a `NodeTracerProvider`
  * (OTLP traces, gated on `otel.enabled && otel.traces`) and a `LoggerProvider`
  * (OTLP logs, gated on `otel.enabled && otel.logs`).
  *
  * The `PrometheusExporter` opens its OWN loopback HTTP listener (host/port from
- * config — NOT the gateway; Pitfall 5). Transport: only the `-proto`
- * (HTTP/protobuf) exporters ship this phase; `protocol:'grpc'` falls back to
- * `-proto` with a WARN+hint (honest degradation — T-178-09). Exemplars are NOT
- * rendered on the pull surface (`PROMETHEUS_EXEMPLARS_SUPPORTED===false`); the
- * `traceId` rides as the `comis.trace_id` span attribute instead (Pitfall 4/6).
+ * config — NOT the gateway). Transport: only the `-proto` (HTTP/protobuf)
+ * exporters are used; `protocol:'grpc'` falls back to `-proto` with a WARN+hint
+ * (honest degradation). Exemplars are NOT rendered on the pull surface
+ * (`PROMETHEUS_EXEMPLARS_SUPPORTED===false`); the `traceId` rides as the
+ * `comis.trace_id` span attribute instead.
  *
  * Returns `{ shutdown }` so the daemon shutdown chain flushes + closes every
  * provider (the OTLP batches drain; the /metrics listener stops).
@@ -39,8 +39,8 @@ import { wireSeriesCardinality } from "./prometheus-surface.js";
  * never hang the daemon's shutdown chain: the OTLP HTTP exporter's flush retries
  * for ~10s+ against a dead endpoint, which would stall every daemon stop. We race
  * each disposal against this cap and move on — the telemetry on the wire is
- * best-effort, daemon liveness is not. (T-178-06's sibling: enabled-but-unavailable
- * must degrade, never block.)
+ * best-effort, daemon liveness is not. (enabled-but-unavailable must degrade,
+ * never block.)
  */
 const SHUTDOWN_STEP_TIMEOUT_MS = 2_000;
 function withTimeout(fn) {
@@ -62,7 +62,7 @@ export function registerOtelExporter(deps) {
     const { eventBus, observability, logger } = deps;
     const otel = observability.otel;
     const prometheus = observability.prometheus;
-    // Honest degradation (T-178-09): only the -proto transport ships; grpc warns + falls back.
+    // Honest degradation: only the -proto transport is used; grpc warns + falls back.
     if (otel.enabled && otel.protocol === "grpc") {
         logger?.warn({
             hint: "OTLP grpc transport is not shipped yet; falling back to http/protobuf. Set observability.otel.protocol: 'http/protobuf' to silence this. grpc is a documented later addition.",
@@ -71,7 +71,7 @@ export function registerOtelExporter(deps) {
     }
     const resource = resourceFromAttributes({ [ATTR_SERVICE_NAME]: "comis" });
     const shutdownFns = [];
-    // ── Metrics: ONE MeterProvider, readers:[otlp?, prometheus?] (Pitfall 2) ──
+    // ── Metrics: ONE MeterProvider, readers:[otlp?, prometheus?] ──
     const readers = [];
     let prometheusExporter;
     if (otel.enabled && otel.metrics) {
@@ -106,8 +106,8 @@ export function registerOtelExporter(deps) {
                 daemonGlobalUsd: observability.spend.daemonGlobalUsd,
             },
         });
-        // PROM-01: the comis_prometheus_series self-cardinality gauge + the
-        // cardinalityCap WARN-with-hint (the label-explosion guard, T-178-07).
+        // The comis_prometheus_series self-cardinality gauge + the
+        // cardinalityCap WARN-with-hint (the label-explosion guard).
         wireSeriesCardinality({
             meter,
             eventBus,

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

@@ -1,7 +1,7 @@
 /**
- * PROM-01 — the Prometheus pull-surface guards: the `comis_prometheus_series`
+ * The Prometheus pull-surface guards: the `comis_prometheus_series`
  * self-cardinality gauge + the `cardinalityCap` ENFORCEMENT (the label-explosion
- * DoS guard, T-178-07).
+ * DoS guard).
  *
  * The OTel `PrometheusExporter` itself (the loopback `/metrics` listener) is
  * constructed in `otel-exporter.ts` as one of the `MeterProvider` readers. This
@@ -11,7 +11,7 @@
  * `comis_prometheus_series` on every scrape, and a breach of `cardinalityCap`
  * emits a single WARN with a `hint` (re-armed when the count drops back below).
  *
- * The cap ACTUALLY BOUNDS the estimate (MD-02): once the distinct-key set
+ * The cap ACTUALLY BOUNDS the estimate: once the distinct-key set
  * reaches `cardinalityCap`, NEW distinct keys are no longer admitted — the excess
  * collapses into a single `"_overflow"` bucket — so the tracker's own memory and
  * the reported series count stay bounded at `cardinalityCap + 1` regardless of

package/node_modules/@comis/observability-otel/dist/prometheus-surface.js

@@ -9,7 +9,7 @@ export function wireSeriesCardinality(deps) {
     // Bounded by the label cardinality, NEVER by ids — this is the guard, not a leak.
     const seriesKeys = new Set();
     let breachWarned = false;
-    // The sentinel bucket every key past the cap collapses into (MD-02). Counts as
+    // The sentinel bucket every key past the cap collapses into. Counts as
     // ONE series, so the set size is hard-bounded at cardinalityCap + 1.
     const OVERFLOW_KEY = "_overflow";
     const track = (instrument, labels) => {
@@ -17,7 +17,7 @@ export function wireSeriesCardinality(deps) {
         // Already tracked (a re-seen series) — a no-op add either way.
         if (seriesKeys.has(key))
             return;
-        // MD-02: ENFORCE the cap. Once the distinct-key set is full, do NOT admit a
+        // ENFORCE the cap. Once the distinct-key set is full, do NOT admit a
         // new key — route it to the single "_overflow" bucket so the set (and thus
         // the tracker's memory + the reported count) cannot grow without bound. A
         // WARN alone would leave the Set growing, which is the DoS the cap prevents.

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

@@ -1,7 +1,7 @@
 /**
  * Re-redact an attribute object / log body at the exporter boundary.
  *
- * Two layers (CR-02): (1) the CLOSED ALLOWLIST — every key NOT in
+ * Two layers: (1) the CLOSED ALLOWLIST — every key NOT in
  * {@link ATTRIBUTE_ALLOWLIST} is DROPPED (the only posture that survives a
  * benign-keyed, no-prefix, high-entropy secret value); (2) `sanitizeForPersistence`
  * on the surviving allowed values as defense-in-depth (a credential keyed under

package/node_modules/@comis/observability-otel/dist/redact-attributes.js

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * OTEL-03 / E3 — content-free re-redaction at the exporter boundary.
+ * Content-free re-redaction at the exporter boundary.
  *
  * Every attribute object and every log-record body the extension emits passes
  * through {@link redactAttributes} FIRST — independent of whatever upstream
- * scrubbing happened. This is the additive E3 guarantee: even if a future
+ * scrubbing happened. This is the additive guarantee: even if a future
  * careless attribute addition (or the `captureContent`/`genaiSemconv` content
  * path) tries to smuggle a secret/message body into a span attribute, a metric
  * label, or a log body, the boundary strips it here.
  *
- * The boundary enforces a CLOSED ALLOWLIST (CR-02). `sanitizeForPersistence`
+ * The boundary enforces a CLOSED ALLOWLIST. `sanitizeForPersistence`
  * masks credential-KEYED fields (`apiKey`/`password`/`token`/`secret`/…) and
  * prefix-patterned secret VALUES (`sk-…`/`ghp_…`/`Bearer …`), but it canNOT
  * catch a high-entropy secret under a BENIGN key with no recognisable prefix
@@ -25,7 +25,7 @@
  * `token` — is still masked).
  *
  * Mirrors the `obs-audit-sink.ts` usage (`sanitizeForPersistence(...)` at the
- * 176 durable-sink boundary) — the same single chokepoint, here behind the
+ * durable-sink boundary) — the same single chokepoint, here behind the
  * allowlist gate.
  *
  * @module
@@ -66,8 +66,8 @@ const KNOWN_SPAN_ATTRIBUTE_KEYS = [
     "length",
 ];
 /**
- * The CLOSED allowlist of attribute keys permitted past the exporter boundary
- * (CR-02). Built ONCE from the {@link METRIC_LABELS} union (the metric labels)
+ * The CLOSED allowlist of attribute keys permitted past the exporter boundary.
+ * Built ONCE from the {@link METRIC_LABELS} union (the metric labels)
  * plus {@link KNOWN_SPAN_ATTRIBUTE_KEYS}. Adding a NEW emitted attribute is a
  * deliberate act: the new key must be added here (and is necessarily a
  * content-free id/count/enum to belong). A key absent from this set is DROPPED —
@@ -80,7 +80,7 @@ const ATTRIBUTE_ALLOWLIST = new Set([
 /**
  * Re-redact an attribute object / log body at the exporter boundary.
  *
- * Two layers (CR-02): (1) the CLOSED ALLOWLIST — every key NOT in
+ * Two layers: (1) the CLOSED ALLOWLIST — every key NOT in
  * {@link ATTRIBUTE_ALLOWLIST} is DROPPED (the only posture that survives a
  * benign-keyed, no-prefix, high-entropy secret value); (2) `sanitizeForPersistence`
  * on the surviving allowed values as defense-in-depth (a credential keyed under

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

@@ -1,13 +1,13 @@
 /**
  * The structural read-only spend-snapshot contract the daemon threads from the
- * 177 `SpendAccumulator` (`@comis/agent`) into this extension's `comis_spend_*`
+ * `SpendAccumulator` (`@comis/agent`) into this extension's `comis_spend_*`
  * observable gauges.
  *
  * Declared structurally (NOT imported from `@comis/agent`) so the extension does
  * not take a build-graph dependency on `@comis/agent` — the daemon, which owns
  * both references, injects the live accumulator (whose `getSnapshot()` shape is
- * byte-identical to this). Mirrors `SpendAccumulator.getSnapshot()` (178-01 Task
- * 3): content-free dollar counts keyed by the `${tenantId} ${agentId}` /
+ * byte-identical to this). Mirrors `SpendAccumulator.getSnapshot()`:
+ * content-free dollar counts keyed by the `${tenantId} ${agentId}` /
  * `tenantId` scope keys.
  *
  * Lives in its own module (not inlined in `index.ts`) so both the barrel and the
@@ -18,7 +18,7 @@
 /**
  * A read-only spend-totals accessor (the `comis_spend_*` gauge source). The maps
  * are fresh copies on the accumulator side — a caller cannot corrupt the
- * kill-switch counters (T-178-02). `perAgent` reflects BOTH billed spend and
+ * kill-switch counters. `perAgent` reflects BOTH billed spend and
  * in-flight reservations.
  */
 export interface SpendSnapshotReader {

package/node_modules/@comis/observability-otel/dist/spend-snapshot.js

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * The structural read-only spend-snapshot contract the daemon threads from the
- * 177 `SpendAccumulator` (`@comis/agent`) into this extension's `comis_spend_*`
+ * `SpendAccumulator` (`@comis/agent`) into this extension's `comis_spend_*`
  * observable gauges.
  *
  * Declared structurally (NOT imported from `@comis/agent`) so the extension does
  * not take a build-graph dependency on `@comis/agent` — the daemon, which owns
  * both references, injects the live accumulator (whose `getSnapshot()` shape is
- * byte-identical to this). Mirrors `SpendAccumulator.getSnapshot()` (178-01 Task
- * 3): content-free dollar counts keyed by the `${tenantId} ${agentId}` /
+ * byte-identical to this). Mirrors `SpendAccumulator.getSnapshot()`:
+ * content-free dollar counts keyed by the `${tenantId} ${agentId}` /
  * `tenantId` scope keys.
  *
  * Lives in its own module (not inlined in `index.ts`) so both the barrel and the

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

@@ -1,6 +1,6 @@
 /**
  * In-memory OTel exporter fixtures (test-only) — the deterministic, collector-free
- * assertion path for the exporter tests (OTEL-01/02/03 / PROM-01).
+ * assertion path for the exporter tests.
  *
  * Every test asserts against an `InMemorySpanExporter` / `InMemoryMetricExporter`
  * / `InMemoryLogRecordExporter` rather than a live OTLP collector, so the suite

package/node_modules/@comis/observability-otel/dist/test-harness.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * In-memory OTel exporter fixtures (test-only) — the deterministic, collector-free
- * assertion path for the exporter tests (OTEL-01/02/03 / PROM-01).
+ * assertion path for the exporter tests.
  *
  * Every test asserts against an `InMemorySpanExporter` / `InMemoryMetricExporter`
  * / `InMemoryLogRecordExporter` rather than a live OTLP collector, so the suite

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

@@ -1,13 +1,13 @@
 /**
- * OTEL-01 / OTEL-03 — per-turn / tool / graph span emission.
+ * Per-turn / tool / graph span emission.
  *
- * Comis's `RequestContext.traceId` is a UUID, NOT an OTel 16-byte trace id
- * (Pitfall 4): the OTel SDK manages real trace/span ids; the Comis UUID rides as
+ * Comis's `RequestContext.traceId` is a UUID, NOT an OTel 16-byte trace id:
+ * the OTel SDK manages real trace/span ids; the Comis UUID rides as
  * the `comis.trace_id` span ATTRIBUTE (and as the Prometheus exemplar value
- * source where supported — it is not on 0.219.0). The drill-down (E7) keys on the
+ * source where supported — it is not on 0.219.0). The drill-down keys on the
  * Comis `traceId` (what `obs.explain` accepts), not the OTel trace id.
  *
- * Content-free posture (E3): the 3 GenAI content span attributes
+ * Content-free posture: the 3 GenAI content span attributes
  * (`gen_ai.input.messages` / `gen_ai.output.messages` / `gen_ai.system_instructions`)
  * are spec-`Opt-In` → OMITTED entirely unless `captureContent:true`. Even when
  * captured, Comis emits a CONTENT-FREE structural summary (message roles +
@@ -15,8 +15,8 @@
  * through `redactAttributes` (`sanitizeForPersistence` at the boundary) so a
  * planted secret in a stray field cannot reach an attribute. This is the honest
  * content-free realization: `captureContent` toggles the PRESENCE of the
- * structural attrs, not the egress of user content (decision #8 / E3 — the raw
- * body never leaves the daemon). The `genaiSemconv` flag selects the attribute
+ * structural attrs, not the egress of user content — the raw
+ * body never leaves the daemon. The `genaiSemconv` flag selects the attribute
  * NAMESPACE (latest `gen_ai.provider.name` vs the pre-stable `gen_ai.system`).
  *
  * @module