@brutalist/mcp 1.8.0 → 1.9.0

package/dist/metrics/histogram.js

@@ -0,0 +1,114 @@
+/**
+ * Histogram — a cumulative histogram of observation values.
+ *
+ * The Prometheus convention: one `_bucket` series per upper bound plus a
+ * mandatory `+Inf` bucket, a `_count` series, and a `_sum` series. Buckets
+ * are CUMULATIVE — each bucket includes every lower bucket's observations.
+ *
+ * Buckets are declared once at construction. Per-label-set state includes:
+ *   - counts[i] — cumulative count for the i-th bucket (counts[bucketsAscending.length] = +Inf).
+ *   - sum      — cumulative sum of observed values (for quantile approximation).
+ *   - count    — total observations (equals counts[+Inf bucket]).
+ */
+import { escapeHelp, escapeLabelValue, serializeLabels } from './types.js';
+export function createHistogram(descriptor) {
+    validateBuckets(descriptor);
+    const state = new Map();
+    return {
+        descriptor,
+        observe(labels, value) {
+            if (!Number.isFinite(value)) {
+                throw new Error(`metrics: histogram "${descriptor.name}" observation must be finite (got ${value})`);
+            }
+            // Symmetric with `Counter.inc()`: negative inputs are rejected by
+            // throwing. The registry's duration histogram measures wall-clock
+            // time, which is semantically non-negative; a bad delta (e.g.,
+            // `Date.now() - futureTimestamp`) would otherwise contaminate every
+            // finite bucket AND negatively shift `_sum`, silently breaking any
+            // downstream quantile or SLO computation.
+            if (value < 0) {
+                throw new Error(`metrics: histogram "${descriptor.name}" observation must be >= 0 (got ${value})`);
+            }
+            const key = serializeLabels(descriptor.labelNames, labels);
+            let entry = state.get(key);
+            if (!entry) {
+                entry = {
+                    labels,
+                    counts: new Array(descriptor.buckets.length + 1).fill(0),
+                    sum: 0,
+                    count: 0
+                };
+                state.set(key, entry);
+            }
+            // Cumulative: increment every bucket whose upper bound >= value.
+            for (let i = 0; i < descriptor.buckets.length; i++) {
+                if (value <= descriptor.buckets[i]) {
+                    entry.counts[i] += 1;
+                }
+            }
+            // +Inf bucket always increments.
+            entry.counts[entry.counts.length - 1] += 1;
+            entry.sum += value;
+            entry.count += 1;
+        },
+        snapshot() {
+            const out = new Map();
+            for (const [key, entry] of state.entries()) {
+                out.set(key, {
+                    cumulative: entry.counts.slice(),
+                    sum: entry.sum,
+                    count: entry.count
+                });
+            }
+            return out;
+        },
+        render() {
+            const lines = [];
+            lines.push(`# HELP ${descriptor.name} ${escapeHelp(descriptor.help)}`);
+            lines.push(`# TYPE ${descriptor.name} histogram`);
+            if (state.size === 0) {
+                return lines.join('\n');
+            }
+            const keys = Array.from(state.keys()).sort();
+            for (const key of keys) {
+                const entry = state.get(key);
+                const labelPrefix = renderLabelPrefix(key, descriptor.labelNames);
+                for (let i = 0; i < descriptor.buckets.length; i++) {
+                    const bucket = descriptor.buckets[i];
+                    lines.push(`${descriptor.name}_bucket{${labelPrefix}le="${escapeLabelValue(String(bucket))}"} ${entry.counts[i]}`);
+                }
+                // +Inf bucket — total count.
+                lines.push(`${descriptor.name}_bucket{${labelPrefix}le="+Inf"} ${entry.counts[entry.counts.length - 1]}`);
+                lines.push(`${descriptor.name}_sum${key === '' ? '' : `{${key}}`} ${formatNumber(entry.sum)}`);
+                lines.push(`${descriptor.name}_count${key === '' ? '' : `{${key}}`} ${entry.count}`);
+            }
+            return lines.join('\n');
+        }
+    };
+}
+function renderLabelPrefix(key, _labelNames) {
+    // `le` is always the final label in bucket lines; put the existing labels first.
+    return key === '' ? '' : `${key},`;
+}
+function formatNumber(value) {
+    if (Number.isInteger(value)) {
+        return value.toString();
+    }
+    return value.toString();
+}
+function validateBuckets(descriptor) {
+    if (descriptor.buckets.length === 0) {
+        throw new Error(`metrics: histogram "${descriptor.name}" must have at least one bucket`);
+    }
+    for (let i = 0; i < descriptor.buckets.length; i++) {
+        const b = descriptor.buckets[i];
+        if (!Number.isFinite(b)) {
+            throw new Error(`metrics: histogram "${descriptor.name}" bucket ${i} is not finite (${b})`);
+        }
+        if (i > 0 && b <= descriptor.buckets[i - 1]) {
+            throw new Error(`metrics: histogram "${descriptor.name}" buckets must be strictly ascending ` +
+                `(bucket ${i} = ${b} <= bucket ${i - 1} = ${descriptor.buckets[i - 1]})`);
+        }
+    }
+}
+//# sourceMappingURL=histogram.js.map

package/dist/metrics/histogram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.js","sourceRoot":"","sources":["../../src/metrics/histogram.ts"],"names":[],"mappings":"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"}

package/dist/metrics/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Metrics module — barrel export.
+ *
+ * This is a TOOL, not wiring: nothing under `src/metrics/` imports from the
+ * debate, CLI-adapter, streaming, or logger modules. Call sites depend on
+ * this module; this module depends on nothing inside the project.
+ *
+ * Usage (composition root):
+ *
+ *   import { createMetricsRegistry } from './metrics/index.js';
+ *   const metrics = createMetricsRegistry();
+ *   // ... pass `metrics` into DebateOrchestratorDeps, CLIAgentOrchestrator, etc.
+ *
+ * Usage (test):
+ *
+ *   const metrics = createMetricsRegistry();
+ *   metrics.cliSpawnTotal.inc({ provider: 'claude', outcome: 'success' });
+ *   expect(metrics.getMetricsAsText()).toContain('brutalist_cli_spawn_total');
+ */
+export { createMetricsRegistry, PROMETHEUS_CONTENT_TYPE, DEBATE_DURATION_LABELS, DEBATE_DURATION_BUCKETS, ESCALATION_TIER_LABELS, CLI_SPAWN_LABELS, STREAMING_EVENT_LABELS } from './registry.js';
+export type { MetricsRegistry } from './registry.js';
+export type { Counter } from './counter.js';
+export type { Histogram, HistogramDescriptor, HistogramSnapshot } from './histogram.js';
+export type { LabelValues, MetricDescriptor, LabelKey } from './types.js';
+export { safeMetric } from './safe-metric.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExF,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/metrics/index.js

@@ -0,0 +1,22 @@
+/**
+ * Metrics module — barrel export.
+ *
+ * This is a TOOL, not wiring: nothing under `src/metrics/` imports from the
+ * debate, CLI-adapter, streaming, or logger modules. Call sites depend on
+ * this module; this module depends on nothing inside the project.
+ *
+ * Usage (composition root):
+ *
+ *   import { createMetricsRegistry } from './metrics/index.js';
+ *   const metrics = createMetricsRegistry();
+ *   // ... pass `metrics` into DebateOrchestratorDeps, CLIAgentOrchestrator, etc.
+ *
+ * Usage (test):
+ *
+ *   const metrics = createMetricsRegistry();
+ *   metrics.cliSpawnTotal.inc({ provider: 'claude', outcome: 'success' });
+ *   expect(metrics.getMetricsAsText()).toContain('brutalist_cli_spawn_total');
+ */
+export { createMetricsRegistry, PROMETHEUS_CONTENT_TYPE, DEBATE_DURATION_LABELS, DEBATE_DURATION_BUCKETS, ESCALATION_TIER_LABELS, CLI_SPAWN_LABELS, STREAMING_EVENT_LABELS } from './registry.js';
+export { safeMetric } from './safe-metric.js';
+//# sourceMappingURL=index.js.map

package/dist/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,eAAe,CAAC;AASvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/metrics/registry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * MetricsRegistry — the DI-friendly container for the four required metric
+ * surfaces (debate duration, escalation tier, CLI spawn, streaming events).
+ *
+ * `createMetricsRegistry()` is a FACTORY, not a singleton accessor. Two calls
+ * produce two completely independent registries — this is the property that
+ * makes tests in the consuming modules reliable: each test can construct a
+ * fresh registry and assert on its state without interference from other
+ * tests or from module-level state.
+ *
+ * Critical invariants (enforced by tests):
+ *   - No module-level `new` at import time.
+ *   - No environment-variable reads at import time.
+ *   - Factory is idempotent per call site: `createMetricsRegistry() !== createMetricsRegistry()`.
+ *   - `getMetricsAsText()` emits a valid Prometheus text-format 0.0.4 exposition.
+ */
+import type { Counter } from './counter.js';
+import type { Histogram } from './histogram.js';
+/**
+ * Labels for the debate orchestration duration histogram.
+ *   - outcome: `success` | `refused` | `error` (success means a non-refused
+ *     debate completed end-to-end; refused captures the constitutional refusal
+ *     path; error captures thrown/uncaught failures.)
+ *   - tier: the escalation tier at which the debate resolved; matches
+ *     `DebateTier` from `src/debate/constitutional.ts` — values:
+ *     `standard` | `escalated` | `decomposed`.
+ */
+export declare const DEBATE_DURATION_LABELS: readonly ["outcome", "tier"];
+/** Labels for the escalation tier counter. Tier values as above. */
+export declare const ESCALATION_TIER_LABELS: readonly ["tier"];
+/**
+ * Labels for CLI spawn outcomes.
+ *   - provider: `claude` | `codex` | `gemini`.
+ *   - outcome: `success` | `failure` | `timeout` | `refused`.
+ *     (Integration phase chooses the exact outcome; the metric accepts any
+ *     string but conventions SHOULD stick to the four above for consistent
+ *     PromQL grouping.)
+ */
+export declare const CLI_SPAWN_LABELS: readonly ["provider", "outcome"];
+/**
+ * Labels for streaming events.
+ *   - transport: `stdio` | `http` — the two canonical MCP transports, per
+ *     `src/streaming/STREAMING_ARCHITECTURE.md`.
+ *   - event_type: `agent_progress` | `agent_error` | `progress_update` | ...
+ *     matches `StreamingEvent.type` from `src/cli-agents.ts` conventions.
+ */
+export declare const STREAMING_EVENT_LABELS: readonly ["transport", "event_type"];
+/**
+ * Histogram buckets for debate durations, in seconds.
+ *
+ * Debates spawn multiple CLI agents (Claude/Codex/Gemini) and run 2-3 rounds;
+ * total latency ranges from ~seconds (cached path) to minutes (full 3-tier
+ * escalation with a cold start). These buckets give sensible resolution across
+ * that full range while keeping cardinality low enough for Prometheus storage.
+ */
+export declare const DEBATE_DURATION_BUCKETS: readonly number[];
+/**
+ * The metrics surface exported by a registry.
+ *
+ * Each property is a ready-to-use metric handle; instrumentation code only
+ * needs to call `inc()` / `observe()` and never sees the underlying registry.
+ */
+export interface MetricsRegistry {
+    /** Histogram: debate orchestration duration, seconds, labeled by outcome & tier. */
+    readonly debateOrchestrationDurationSeconds: Histogram<typeof DEBATE_DURATION_LABELS>;
+    /** Counter: total debates per escalation tier reached. */
+    readonly debateEscalationTierTotal: Counter<typeof ESCALATION_TIER_LABELS>;
+    /** Counter: CLI spawn attempts partitioned by provider and outcome. */
+    readonly cliSpawnTotal: Counter<typeof CLI_SPAWN_LABELS>;
+    /** Counter: streaming events dispatched per transport and event type. */
+    readonly streamingEventsTotal: Counter<typeof STREAMING_EVENT_LABELS>;
+    /**
+     * Render the full registry as a Prometheus text-format 0.0.4 exposition.
+     *
+     * Content-Type: `text/plain; version=0.0.4` (the constant is exported
+     * separately as `PROMETHEUS_CONTENT_TYPE` for the optional HTTP exposure
+     * that the integration phase may add).
+     */
+    getMetricsAsText(): string;
+}
+/**
+ * The Prometheus text exposition Content-Type.
+ *
+ * Per the 0.0.4 spec: `text/plain; version=0.0.4; charset=utf-8`.
+ */
+export declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/**
+ * Construct a fresh, independent metrics registry.
+ *
+ * Zero arguments keeps the signature minimal for composition-root wiring;
+ * customisation (buckets, label sets) is done by editing this file rather
+ * than exposing constructor knobs — this keeps every consumer's metric
+ * surface identical across test and production builds.
+ */
+export declare function createMetricsRegistry(): MetricsRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/metrics/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/metrics/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,8BAA+B,CAAC;AAEnE,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,mBAAoB,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,kCAAmC,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,sCAAuC,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAEpD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,kCAAkC,EAAE,SAAS,CAAC,OAAO,sBAAsB,CAAC,CAAC;IACtF,0DAA0D;IAC1D,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAC3E,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,gBAAgB,CAAC,CAAC;IACzD,yEAAyE;IACzE,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAEtE;;;;;;OAMG;IACH,gBAAgB,IAAI,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,6CAA6C,CAAC;AAElF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CA2CvD"}

package/dist/metrics/registry.js

@@ -0,0 +1,113 @@
+/**
+ * MetricsRegistry — the DI-friendly container for the four required metric
+ * surfaces (debate duration, escalation tier, CLI spawn, streaming events).
+ *
+ * `createMetricsRegistry()` is a FACTORY, not a singleton accessor. Two calls
+ * produce two completely independent registries — this is the property that
+ * makes tests in the consuming modules reliable: each test can construct a
+ * fresh registry and assert on its state without interference from other
+ * tests or from module-level state.
+ *
+ * Critical invariants (enforced by tests):
+ *   - No module-level `new` at import time.
+ *   - No environment-variable reads at import time.
+ *   - Factory is idempotent per call site: `createMetricsRegistry() !== createMetricsRegistry()`.
+ *   - `getMetricsAsText()` emits a valid Prometheus text-format 0.0.4 exposition.
+ */
+import { createCounter } from './counter.js';
+import { createHistogram } from './histogram.js';
+/**
+ * Labels for the debate orchestration duration histogram.
+ *   - outcome: `success` | `refused` | `error` (success means a non-refused
+ *     debate completed end-to-end; refused captures the constitutional refusal
+ *     path; error captures thrown/uncaught failures.)
+ *   - tier: the escalation tier at which the debate resolved; matches
+ *     `DebateTier` from `src/debate/constitutional.ts` — values:
+ *     `standard` | `escalated` | `decomposed`.
+ */
+export const DEBATE_DURATION_LABELS = ['outcome', 'tier'];
+/** Labels for the escalation tier counter. Tier values as above. */
+export const ESCALATION_TIER_LABELS = ['tier'];
+/**
+ * Labels for CLI spawn outcomes.
+ *   - provider: `claude` | `codex` | `gemini`.
+ *   - outcome: `success` | `failure` | `timeout` | `refused`.
+ *     (Integration phase chooses the exact outcome; the metric accepts any
+ *     string but conventions SHOULD stick to the four above for consistent
+ *     PromQL grouping.)
+ */
+export const CLI_SPAWN_LABELS = ['provider', 'outcome'];
+/**
+ * Labels for streaming events.
+ *   - transport: `stdio` | `http` — the two canonical MCP transports, per
+ *     `src/streaming/STREAMING_ARCHITECTURE.md`.
+ *   - event_type: `agent_progress` | `agent_error` | `progress_update` | ...
+ *     matches `StreamingEvent.type` from `src/cli-agents.ts` conventions.
+ */
+export const STREAMING_EVENT_LABELS = ['transport', 'event_type'];
+/**
+ * Histogram buckets for debate durations, in seconds.
+ *
+ * Debates spawn multiple CLI agents (Claude/Codex/Gemini) and run 2-3 rounds;
+ * total latency ranges from ~seconds (cached path) to minutes (full 3-tier
+ * escalation with a cold start). These buckets give sensible resolution across
+ * that full range while keeping cardinality low enough for Prometheus storage.
+ */
+export const DEBATE_DURATION_BUCKETS = [
+    0.5, 1, 2, 5, 10, 30, 60, 120, 300
+];
+/**
+ * The Prometheus text exposition Content-Type.
+ *
+ * Per the 0.0.4 spec: `text/plain; version=0.0.4; charset=utf-8`.
+ */
+export const PROMETHEUS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+/**
+ * Construct a fresh, independent metrics registry.
+ *
+ * Zero arguments keeps the signature minimal for composition-root wiring;
+ * customisation (buckets, label sets) is done by editing this file rather
+ * than exposing constructor knobs — this keeps every consumer's metric
+ * surface identical across test and production builds.
+ */
+export function createMetricsRegistry() {
+    const debateOrchestrationDurationSeconds = createHistogram({
+        name: 'brutalist_debate_orchestration_duration_seconds',
+        help: 'Wall-clock duration of a CLI debate orchestration from start to finish, in seconds.',
+        labelNames: DEBATE_DURATION_LABELS,
+        buckets: DEBATE_DURATION_BUCKETS
+    });
+    const debateEscalationTierTotal = createCounter({
+        name: 'brutalist_debate_escalation_tier_total',
+        help: 'Total debates that reached a given escalation tier (standard/escalated/decomposed).',
+        labelNames: ESCALATION_TIER_LABELS
+    });
+    const cliSpawnTotal = createCounter({
+        name: 'brutalist_cli_spawn_total',
+        help: 'Total CLI agent spawn attempts partitioned by provider and outcome.',
+        labelNames: CLI_SPAWN_LABELS
+    });
+    const streamingEventsTotal = createCounter({
+        name: 'brutalist_streaming_events_total',
+        help: 'Total streaming events dispatched, labeled by transport and event type.',
+        labelNames: STREAMING_EVENT_LABELS
+    });
+    return {
+        debateOrchestrationDurationSeconds,
+        debateEscalationTierTotal,
+        cliSpawnTotal,
+        streamingEventsTotal,
+        getMetricsAsText() {
+            // Blocks are separated by a single blank line; the final block ends
+            // with a trailing newline per the text format 0.0.4 convention.
+            const blocks = [
+                debateOrchestrationDurationSeconds.render(),
+                debateEscalationTierTotal.render(),
+                cliSpawnTotal.render(),
+                streamingEventsTotal.render()
+            ];
+            return blocks.join('\n') + '\n';
+        }
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/metrics/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/metrics/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,MAAM,CAAU,CAAC;AAEnE,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAM,CAAU,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,SAAS,CAAU,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,WAAW,EAAE,YAAY,CAAU,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG;CACnC,CAAC;AA4BF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,0CAA0C,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,kCAAkC,GAAG,eAAe,CAAC;QACzD,IAAI,EAAE,iDAAiD;QACvD,IAAI,EAAE,qFAAqF;QAC3F,UAAU,EAAE,sBAAsB;QAClC,OAAO,EAAE,uBAAuB;KACjC,CAAC,CAAC;IAEH,MAAM,yBAAyB,GAAG,aAAa,CAAC;QAC9C,IAAI,EAAE,wCAAwC;QAC9C,IAAI,EAAE,qFAAqF;QAC3F,UAAU,EAAE,sBAAsB;KACnC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,aAAa,CAAC;QAClC,IAAI,EAAE,2BAA2B;QACjC,IAAI,EAAE,qEAAqE;QAC3E,UAAU,EAAE,gBAAgB;KAC7B,CAAC,CAAC;IAEH,MAAM,oBAAoB,GAAG,aAAa,CAAC;QACzC,IAAI,EAAE,kCAAkC;QACxC,IAAI,EAAE,yEAAyE;QAC/E,UAAU,EAAE,sBAAsB;KACnC,CAAC,CAAC;IAEH,OAAO;QACL,kCAAkC;QAClC,yBAAyB;QACzB,aAAa;QACb,oBAAoB;QACpB,gBAAgB;YACd,oEAAoE;YACpE,gEAAgE;YAChE,MAAM,MAAM,GAAG;gBACb,kCAAkC,CAAC,MAAM,EAAE;gBAC3C,yBAAyB,CAAC,MAAM,EAAE;gBAClC,aAAa,CAAC,MAAM,EAAE;gBACtB,oBAAoB,CAAC,MAAM,EAAE;aAC9B,CAAC;YACF,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/metrics/safe-metric.d.ts

@@ -0,0 +1,25 @@
+/**
+ * safeMetric — isolate metric writes from business control flow.
+ *
+ * Metric emissions are side effects that MUST NOT propagate exceptions
+ * into the surrounding business logic. If a metric throw escaped into
+ * an outer try/catch (e.g., the per-turn try/catch in
+ * DebateOrchestrator.executeCLIDebate or the spawn try/catch in
+ * CLIAgentOrchestrator._executeCLI), the business layer would treat
+ * the metric failure as an operational failure — double-counting,
+ * double-pushing metadata, potentially re-emitting streaming events.
+ *
+ * This helper wraps each metric call in a local try/catch that swallows
+ * the exception and emits a warn-level log bound to
+ * `operation='metrics'`. The hot-path no-I/O invariant is preserved:
+ * `.warn` only fires on the rare exception path (contract-violating
+ * label input or registry misconfiguration), and no synchronous I/O is
+ * added on the happy path.
+ *
+ * This module is a TOOL — it imports only the logger type and has no
+ * other project dependencies. Call sites (debate, cli spawn) own the
+ * operation label.
+ */
+import type { StructuredLogger } from '../logger.js';
+export declare function safeMetric(log: StructuredLogger, op: string, fn: () => void): void;
+//# sourceMappingURL=safe-metric.d.ts.map

package/dist/metrics/safe-metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-metric.d.ts","sourceRoot":"","sources":["../../src/metrics/safe-metric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,wBAAgB,UAAU,CACxB,GAAG,EAAE,gBAAgB,EACrB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAgBN"}

package/dist/metrics/safe-metric.js

@@ -0,0 +1,41 @@
+/**
+ * safeMetric — isolate metric writes from business control flow.
+ *
+ * Metric emissions are side effects that MUST NOT propagate exceptions
+ * into the surrounding business logic. If a metric throw escaped into
+ * an outer try/catch (e.g., the per-turn try/catch in
+ * DebateOrchestrator.executeCLIDebate or the spawn try/catch in
+ * CLIAgentOrchestrator._executeCLI), the business layer would treat
+ * the metric failure as an operational failure — double-counting,
+ * double-pushing metadata, potentially re-emitting streaming events.
+ *
+ * This helper wraps each metric call in a local try/catch that swallows
+ * the exception and emits a warn-level log bound to
+ * `operation='metrics'`. The hot-path no-I/O invariant is preserved:
+ * `.warn` only fires on the rare exception path (contract-violating
+ * label input or registry misconfiguration), and no synchronous I/O is
+ * added on the happy path.
+ *
+ * This module is a TOOL — it imports only the logger type and has no
+ * other project dependencies. Call sites (debate, cli spawn) own the
+ * operation label.
+ */
+export function safeMetric(log, op, fn) {
+    try {
+        fn();
+    }
+    catch (err) {
+        // Security (Cycle 3 F36): the MetricsRegistry (Counter/Histogram)
+        // only throws synthetic label-validation errors with static strings
+        // today, but defense-in-depth says a future caller that passes
+        // user-controlled label values must not leak through this sink.
+        // Emit class-name only (err.name) — no payload. Do NOT add a
+        // nested try/catch around this warn call; F27/F28/F29 (logger-
+        // throw propagation) is suppressed by the convergence gate
+        // (see decisions.md Cycle 2 ASSESS).
+        log.forOperation('metrics').warn(`metric ${op} failed`, {
+            err: err instanceof Error ? (err.name ?? 'Error') : '<non-Error-thrown>',
+        });
+    }
+}
+//# sourceMappingURL=safe-metric.js.map

package/dist/metrics/safe-metric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-metric.js","sourceRoot":"","sources":["../../src/metrics/safe-metric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,MAAM,UAAU,UAAU,CACxB,GAAqB,EACrB,EAAU,EACV,EAAc;IAEd,IAAI,CAAC;QACH,EAAE,EAAE,CAAC;IACP,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kEAAkE;QAClE,oEAAoE;QACpE,+DAA+D;QAC/D,gEAAgE;QAChE,6DAA6D;QAC7D,+DAA+D;QAC/D,2DAA2D;QAC3D,qCAAqC;QACrC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE;YACtD,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,oBAAoB;SACzE,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/metrics/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared type primitives for the metrics module.
+ *
+ * `LabelValues` intentionally constrains label names at the type level: each
+ * metric declares a tuple of its label keys and consumers must supply every
+ * key — this catches missing-label bugs at compile time rather than exposing
+ * an untyped `Record<string, string>` to callers.
+ */
+/** Cardinality-safe label value map. Values are stringified before emission. */
+export type LabelValues<TLabels extends readonly string[]> = {
+    [K in TLabels[number]]: string | number;
+};
+/** Common metadata carried by every declared metric. */
+export interface MetricDescriptor<TLabels extends readonly string[]> {
+    /** Fully-qualified Prometheus metric name (e.g. `brutalist_debate_...`). */
+    readonly name: string;
+    /** One-line HELP text emitted in the exposition. */
+    readonly help: string;
+    /** The ordered label key tuple. */
+    readonly labelNames: TLabels;
+}
+/**
+ * The internal storage shape shared by Counter and Histogram.
+ * A metric keeps a map from `labelKey` (stable, deterministic serialization
+ * of its label values) to per-label-set state.
+ */
+export type LabelKey = string;
+/**
+ * Build a stable, deterministic label key from a label-value map.
+ *
+ * Labels are emitted in the order declared in `labelNames` so two equivalent
+ * maps always produce the same key regardless of call-site iteration order.
+ *
+ * Values are coerced to strings and newline/quote-escaped for safe embedding
+ * in the exposition text format.
+ */
+export declare function serializeLabels<TLabels extends readonly string[]>(labelNames: TLabels, values: LabelValues<TLabels>): LabelKey;
+/**
+ * Escape a label value for the Prometheus text format 0.0.4 exposition.
+ *
+ * The spec only mandates escaping of three characters inside a label value:
+ *   \\ -> \\\\    (backslash — must come FIRST so later-emitted escape
+ *                  sequences that include a literal `\` do not get their
+ *                  backslash doubled on a second pass. The single-pass
+ *                  character-walker below makes the order moot in practice
+ *                  because each input char is transformed exactly once,
+ *                  but we keep the documented ordering for clarity and
+ *                  parity with any future two-pass rewrite.)
+ *   "  -> \\"    (double quote — else the label value terminator is
+ *                  ambiguous and a crafted input can forge a label pair.)
+ *   \n -> \\n    (LF — else a newline injects a fake metric line.)
+ *
+ * We ALSO escape CR (`\r`) even though the 0.0.4 spec does not strictly
+ * require it: without CR escaping an input like `x\r\nmalicious_metric 1`
+ * ends the current line in any CRLF-aware parser (HTTP scrapers, browser
+ * views, log viewers) and forges a downstream metric line. The future
+ * integrate_observability phase may add HTTP exposition; escaping CR now
+ * removes a whole class of injection vectors before anyone exposes the
+ * exposition to untrusted network paths.
+ *
+ * Other control characters (C0 range 0x00-0x1F, DEL 0x7F, NUL) are passed
+ * through as-is. Rationale: (a) none of them can terminate a label value
+ * or inject a line break in the 0.0.4 grammar; (b) metric callers in this
+ * codebase build label values from closed sets (`claude`/`codex`/`gemini`,
+ * `success`/`failure`, etc.) so there is no realistic path for a NUL or
+ * bell character to reach this function; (c) stripping/rejecting them is
+ * policy, not encoding correctness — the integrate_observability phase can
+ * add a reject/sanitize layer at the call site if that policy is needed.
+ */
+export declare function escapeLabelValue(value: string): string;
+/**
+ * Escape a HELP text per the Prometheus text format 0.0.4 spec:
+ *   \\ -> \\\\
+ *   \n -> \\n
+ * (quote escaping is NOT required in HELP lines, only in label values.)
+ *
+ * CR is also escaped — same rationale as `escapeLabelValue`: downstream
+ * HTTP/browser tooling is CRLF-aware and an unescaped CR would forge
+ * subsequent lines in the exposition output.
+ */
+export declare function escapeHelp(value: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/metrics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gFAAgF;AAChF,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,SAAS,MAAM,EAAE,IAAI;KAC1D,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM;CACxC,CAAC;AAEF,wDAAwD;AACxD,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,SAAS,MAAM,EAAE;IACjE,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,SAAS,MAAM,EAAE,EAC/D,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAC3B,QAAQ,CAeV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAuBtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAehD"}