@adjudicate/observability 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Rodolpho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/audit-spans.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OTLP-shaped audit span exporter.
+ *
+ * Wraps any `AuditSink` and, in addition to the underlying durable emit,
+ * pushes one `audit.span` event per AuditRecord into the configured
+ * Exporter. The span name is `adjudicate.audit.<intentKind>` and the
+ * attributes carry the headline fields used for trace correlation
+ * (intentHash, decision, basis-code count, …).
+ *
+ * The wrapper is NOT a sink replacement. Durability is the inner sink's
+ * job; this just sprays a parallel trace. If the inner emit rejects, the
+ * wrapper rethrows (so the kernel's existing durability story is unchanged)
+ * but the span has still been exported — observability is best-effort and
+ * never blocks the audit path.
+ *
+ * Wiring:
+ *
+ *     const wrapped = createOtlpAuditSpanExporter({
+ *       inner: postgresAuditSink,
+ *       exporter,
+ *     });
+ *     await adjudicateAndAudit({ envelope, state, policy, sink: wrapped });
+ */
+import type { AuditSink } from "@adjudicate/core";
+import type { Exporter } from "./exporter.js";
+export interface OtlpAuditSpanExporterOptions {
+    /** Inner durable sink. The wrapper delegates `.emit()` to this. */
+    readonly inner: AuditSink;
+    readonly exporter: Exporter;
+    /** Optional Pack identifier stamped on every span. */
+    readonly packId?: string;
+    /** Optional Pack policy version stamped on every span. */
+    readonly policyVersion?: string;
+}
+export declare function createOtlpAuditSpanExporter(opts: OtlpAuditSpanExporterOptions): AuditSink;
+//# sourceMappingURL=audit-spans.d.ts.map

package/dist/audit-spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-spans.d.ts","sourceRoot":"","sources":["../src/audit-spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,eAAe,CAAC;AAG7D,MAAM,WAAW,4BAA4B;IAC3C,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,4BAA4B,GACjC,SAAS,CAgBX"}

package/dist/audit-spans.js

@@ -0,0 +1,77 @@
+/**
+ * OTLP-shaped audit span exporter.
+ *
+ * Wraps any `AuditSink` and, in addition to the underlying durable emit,
+ * pushes one `audit.span` event per AuditRecord into the configured
+ * Exporter. The span name is `adjudicate.audit.<intentKind>` and the
+ * attributes carry the headline fields used for trace correlation
+ * (intentHash, decision, basis-code count, …).
+ *
+ * The wrapper is NOT a sink replacement. Durability is the inner sink's
+ * job; this just sprays a parallel trace. If the inner emit rejects, the
+ * wrapper rethrows (so the kernel's existing durability story is unchanged)
+ * but the span has still been exported — observability is best-effort and
+ * never blocks the audit path.
+ *
+ * Wiring:
+ *
+ *     const wrapped = createOtlpAuditSpanExporter({
+ *       inner: postgresAuditSink,
+ *       exporter,
+ *     });
+ *     await adjudicateAndAudit({ envelope, state, policy, sink: wrapped });
+ */
+import { SEMCONV } from "./semconv.js";
+export function createOtlpAuditSpanExporter(opts) {
+    return {
+        async emit(record) {
+            // Emit the span first; if the inner sink throws, we still want a trace
+            // of the attempt. The exporter is best-effort and swallows its own
+            // errors so observability never disturbs the durability path.
+            const span = recordToSpan(record, opts);
+            try {
+                opts.exporter.export(span);
+            }
+            catch {
+                /* swallow */
+            }
+            // Durability path — the wrapper is transparent to its inner sink.
+            await opts.inner.emit(record);
+        },
+    };
+}
+function recordToSpan(record, opts) {
+    return {
+        kind: "audit.span",
+        name: `adjudicate.audit.${record.envelope.kind}`,
+        at: record.at,
+        attributes: {
+            [SEMCONV.INTENT_KIND]: record.envelope.kind,
+            [SEMCONV.DECISION_KIND]: record.decision.kind,
+            [SEMCONV.TAINT]: record.envelope.taint,
+            [SEMCONV.INTENT_HASH]: record.intentHash,
+            [SEMCONV.LATENCY_MS]: record.durationMs,
+            "adjudicate.basis.count": record.decision_basis.length,
+            ...(record.resourceVersion !== undefined
+                ? { "adjudicate.resource.version": record.resourceVersion }
+                : {}),
+            ...(record.plan?.planFingerprint !== undefined
+                ? { "adjudicate.plan.fingerprint": record.plan.planFingerprint }
+                : {}),
+            ...(record.kernelIdentity !== undefined
+                ? {
+                    "adjudicate.kernel.id": record.kernelIdentity.id,
+                    "adjudicate.kernel.version": record.kernelIdentity.version,
+                }
+                : {}),
+            ...(opts.packId !== undefined ? { [SEMCONV.PACK_ID]: opts.packId } : {}),
+            ...(opts.policyVersion !== undefined
+                ? { [SEMCONV.POLICY_VERSION]: opts.policyVersion }
+                : {}),
+        },
+        // Full record for ingestion pipelines that want everything. Exporters
+        // that don't care can ignore `body`.
+        body: record,
+    };
+}
+//# sourceMappingURL=audit-spans.js.map

package/dist/audit-spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-spans.js","sourceRoot":"","sources":["../src/audit-spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAYvC,MAAM,UAAU,2BAA2B,CACzC,IAAkC;IAElC,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,MAAmB;YAC5B,uEAAuE;YACvE,mEAAmE;YACnE,8DAA8D;YAC9D,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACxC,IAAI,CAAC;gBACH,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,aAAa;YACf,CAAC;YACD,kEAAkE;YAClE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CACnB,MAAmB,EACnB,IAAkC;IAElC,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,oBAAoB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAChD,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,UAAU,EAAE;YACV,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;YAC3C,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;YAC7C,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK;YACtC,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU;YACxC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU;YACvC,wBAAwB,EAAE,MAAM,CAAC,cAAc,CAAC,MAAM;YACtD,GAAG,CAAC,MAAM,CAAC,eAAe,KAAK,SAAS;gBACtC,CAAC,CAAC,EAAE,6BAA6B,EAAE,MAAM,CAAC,eAAe,EAAE;gBAC3D,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,KAAK,SAAS;gBAC5C,CAAC,CAAC,EAAE,6BAA6B,EAAE,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE;gBAChE,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS;gBACrC,CAAC,CAAC;oBACE,sBAAsB,EAAE,MAAM,CAAC,cAAc,CAAC,EAAE;oBAChD,2BAA2B,EAAE,MAAM,CAAC,cAAc,CAAC,OAAO;iBAC3D;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,CAAC,IAAI,CAAC,aAAa,KAAK,SAAS;gBAClC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE;gBAClD,CAAC,CAAC,EAAE,CAAC;SACR;QACD,sEAAsE;QACtE,qCAAqC;QACrC,IAAI,EAAE,MAAM;KACb,CAAC;AACJ,CAAC"}

package/dist/ecosystem-telemetry.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Ecosystem telemetry — local-first, opt-in, deterministic.
+ *
+ * Post-v1 the framework must evolve from evidence. This module gives
+ * adopters a structured way to *locally* aggregate that evidence into
+ * snapshots they can later choose to share. It is the substrate behind
+ * "adoption telemetry hooks" without any of the substrate behind
+ * "phone-home telemetry."
+ *
+ * Design invariants (enforced by the public surface, not by trust):
+ *
+ *   1. Opt-in only. The kernel never instantiates these aggregators;
+ *      adopters must construct them explicitly.
+ *   2. Local-first. The module contains zero network code, zero file
+ *      I/O. A snapshot is a value the adopter chooses what to do with.
+ *   3. Privacy-preserving. The aggregators record taxonomy entries
+ *      (codes, kinds, categories) — never adopter payloads, never
+ *      intent payloads, never personally identifiable strings.
+ *   4. Deterministic. Same input sequence → identical snapshot. No
+ *      clock, no RNG, no environmental capture inside the aggregator.
+ *      Wall-clock attribution is the caller's responsibility.
+ *   5. Bounded cardinality. Each category caps its key-space so a
+ *      runaway Pack cannot inflate the snapshot.
+ *
+ * What the aggregators DON'T do:
+ *
+ *   - They do not export to any wire protocol.
+ *   - They do not subscribe to kernel sinks automatically.
+ *   - They do not coalesce across processes or hosts.
+ *   - They never observe the envelope payload, the LLM history, or
+ *     any string that originated from an LLM.
+ *
+ * If an adopter wires the snapshot to a metrics backend, that is their
+ * production decision — and the snapshot shape is explicitly designed
+ * to remain stable across minor versions so dashboards survive bumps.
+ */
+import type { AuditRecord, Decision, ReplayMismatch, Refusal } from "@adjudicate/core";
+/**
+ * Closed taxonomy of operational incident classes the runtime can
+ * encounter. Mirrors the operator runbook categories so an incident
+ * channel can route on a single key.
+ *
+ * Additions are MINOR. Removals are MAJOR (would invalidate downstream
+ * alert rules).
+ */
+export type OperationalIncidentClass = "kill_switch_storm" | "kill_switch_split_brain" | "audit_sink_outage" | "audit_event_bus_failure" | "replay_drift_mass" | "replay_drift_single" | "integrity_failure" | "deferred_resume_stuck" | "confirmation_token_loss" | "pack_signature_invalid" | "pack_signature_missing" | "rate_limit_threshold_breach" | "guard_panic_storm" | "shadow_divergence_spike";
+/**
+ * Closed taxonomy of replay-failure root causes. Distinct from
+ * `ReplayMismatchKind` — that is the *shape* of the divergence; this
+ * is the inferred *cause*. The classifier is purposefully conservative:
+ * unknown shapes fall into `unclassified` rather than being guessed.
+ *
+ * Additions are MINOR.
+ */
+export type ReplayFailureClass = "decision_kind_changed" | "basis_added" | "basis_removed" | "basis_swapped" | "refusal_code_changed" | "unclassified";
+/**
+ * Closed taxonomy of analyzer-diagnostic outcomes when adopters tag
+ * them. The kernel never tags — only the adopter, after triage. Used to
+ * separate true positives from noise without leaking the diagnostic
+ * detail (which can carry source identifiers).
+ *
+ * Additions are MINOR.
+ */
+export type AnalyzerTriageOutcome = "true_positive" | "false_positive" | "by_design" | "wont_fix" | "deferred";
+/**
+ * One slot of a Pack-ecosystem snapshot. Tracks how many *unique*
+ * Pack ids the local process has observed, bucketed by the Pack's
+ * `contract` field. Never records the Pack id itself — the bucket
+ * counter alone is the carry-out value.
+ */
+export interface PackEcosystemSnapshot {
+    /** Number of distinct Pack ids observed, by contract version. */
+    readonly packsByContract: Readonly<Record<string, number>>;
+    /** Distribution of declared quality tiers across observed manifests. */
+    readonly qualityTiers: Readonly<Record<string, number>>;
+    /** Distribution of signature algorithms seen on verified packs. */
+    readonly signatureAlgorithms: Readonly<Record<string, number>>;
+    /** Pack trust verifications classified by outcome. */
+    readonly trustOutcomes: Readonly<Record<string, number>>;
+}
+/**
+ * One slot of a decision distribution snapshot. Maps `Decision.kind` to
+ * a count. Refusal codes (when present) are nested under a closed
+ * vocabulary bucket; basis codes are reported as a `category` bucket
+ * only (never the per-code key) to keep cardinality bounded.
+ */
+export interface DecisionDistributionSnapshot {
+    readonly byKind: Readonly<Record<string, number>>;
+    readonly refusalByCode: Readonly<Record<string, number>>;
+    readonly basisByCategory: Readonly<Record<string, number>>;
+}
+export interface ReplayFailureSnapshot {
+    readonly byClass: Readonly<Record<ReplayFailureClass, number>>;
+    readonly total: number;
+}
+export interface AnalyzerTriageSnapshot {
+    readonly byDiagnosticCode: Readonly<Record<string, Readonly<Record<AnalyzerTriageOutcome, number>>>>;
+    readonly totals: Readonly<Record<AnalyzerTriageOutcome, number>>;
+}
+export interface SemconvAdoptionSnapshot {
+    /** Number of times each `adjudicate.*` attribute was emitted locally. */
+    readonly emissionsByAttribute: Readonly<Record<string, number>>;
+    /**
+     * Number of attributes that were emitted but are *not* in the local
+     * `SEMCONV` constant — a signal that an adopter or extension is
+     * minting their own keys. Bucket only; never the attribute string.
+     */
+    readonly unknownAttributeCount: number;
+}
+export interface MigrationPainSnapshot {
+    /** Codemod name → number of files visited. */
+    readonly codemodVisits: Readonly<Record<string, number>>;
+    /** Codemod name → number of files modified. */
+    readonly codemodModifications: Readonly<Record<string, number>>;
+    /** Codemod name → number of files where the rule did not apply (no-op). */
+    readonly codemodNoops: Readonly<Record<string, number>>;
+}
+export interface IncidentSnapshot {
+    readonly byClass: Readonly<Record<OperationalIncidentClass, number>>;
+    readonly total: number;
+}
+/**
+ * The top-level snapshot. JSON-serializable. Stable shape across
+ * minor versions. Adopters who ship snapshots to a backend should
+ * version-pin to the `schemaVersion`.
+ */
+export interface EcosystemTelemetrySnapshot {
+    readonly schemaVersion: 1;
+    readonly pack: PackEcosystemSnapshot;
+    readonly decisions: DecisionDistributionSnapshot;
+    readonly replayFailures: ReplayFailureSnapshot;
+    readonly analyzerTriage: AnalyzerTriageSnapshot;
+    readonly semconvAdoption: SemconvAdoptionSnapshot;
+    readonly migrationPain: MigrationPainSnapshot;
+    readonly incidents: IncidentSnapshot;
+}
+/**
+ * Per-aggregator cardinality caps. When exceeded, additional keys are
+ * absorbed into a designated `__overflow__` bucket so the snapshot
+ * shape stays bounded. The defaults are intentionally generous for
+ * single-process aggregation; adopters running shared aggregators
+ * should tighten them.
+ */
+export interface EcosystemTelemetryOptions {
+    readonly maxPackKeys?: number;
+    readonly maxBasisCategories?: number;
+    readonly maxRefusalCodes?: number;
+    readonly maxAttributeKeys?: number;
+    readonly maxDiagnosticCodes?: number;
+    readonly maxCodemodKeys?: number;
+}
+/**
+ * The aggregator. Adopters call observation methods; the aggregator
+ * accumulates bounded counters. `snapshot()` returns a JSON-stable
+ * value. `reset()` is provided for tests and for periodic flush-and-
+ * reset rotations (e.g., snapshot-per-hour).
+ *
+ * Every observation method is synchronous and total: no I/O, no
+ * throws, no allocations beyond the counter.
+ */
+export interface EcosystemTelemetry {
+    observePackInstallation(packId: string, contract: string): void;
+    observePackManifest(qualityTier: string | null): void;
+    observePackTrust(outcome: "ok" | "missing" | "invalid" | "unverified"): void;
+    observePackSignature(algorithm: string): void;
+    observeDecision(decision: Decision): void;
+    observeRefusal(refusal: Refusal): void;
+    observeAuditRecord(record: AuditRecord): void;
+    observeReplayMismatch(mismatch: ReplayMismatch): void;
+    observeAnalyzerTriage(diagnosticCode: string, outcome: AnalyzerTriageOutcome): void;
+    observeSemconvEmission(attribute: string, knownAttributes: ReadonlySet<string>): void;
+    observeCodemod(name: string, outcome: "visited" | "modified" | "noop"): void;
+    observeIncident(klass: OperationalIncidentClass): void;
+    snapshot(): EcosystemTelemetrySnapshot;
+    reset(): void;
+}
+export declare function createEcosystemTelemetry(options?: EcosystemTelemetryOptions): EcosystemTelemetry;
+/**
+ * Classify a single replay mismatch into a closed taxonomy entry. Pure;
+ * useful both inside the aggregator and standalone for adopters who
+ * want to bucket their own replay report into operational categories.
+ */
+export declare function classifyReplayFailure(mismatch: ReplayMismatch): ReplayFailureClass;
+/**
+ * Canonical JSON serialization of a snapshot. Useful when an adopter
+ * wants byte-identical snapshots across processes (e.g., for diffing
+ * weekly aggregates). Sorts every object key recursively.
+ */
+export declare function serializeEcosystemSnapshot(snapshot: EcosystemTelemetrySnapshot): string;
+//# sourceMappingURL=ecosystem-telemetry.d.ts.map

package/dist/ecosystem-telemetry.d.ts.map

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

package/dist/ecosystem-telemetry.js

@@ -0,0 +1,331 @@
+/**
+ * Ecosystem telemetry — local-first, opt-in, deterministic.
+ *
+ * Post-v1 the framework must evolve from evidence. This module gives
+ * adopters a structured way to *locally* aggregate that evidence into
+ * snapshots they can later choose to share. It is the substrate behind
+ * "adoption telemetry hooks" without any of the substrate behind
+ * "phone-home telemetry."
+ *
+ * Design invariants (enforced by the public surface, not by trust):
+ *
+ *   1. Opt-in only. The kernel never instantiates these aggregators;
+ *      adopters must construct them explicitly.
+ *   2. Local-first. The module contains zero network code, zero file
+ *      I/O. A snapshot is a value the adopter chooses what to do with.
+ *   3. Privacy-preserving. The aggregators record taxonomy entries
+ *      (codes, kinds, categories) — never adopter payloads, never
+ *      intent payloads, never personally identifiable strings.
+ *   4. Deterministic. Same input sequence → identical snapshot. No
+ *      clock, no RNG, no environmental capture inside the aggregator.
+ *      Wall-clock attribution is the caller's responsibility.
+ *   5. Bounded cardinality. Each category caps its key-space so a
+ *      runaway Pack cannot inflate the snapshot.
+ *
+ * What the aggregators DON'T do:
+ *
+ *   - They do not export to any wire protocol.
+ *   - They do not subscribe to kernel sinks automatically.
+ *   - They do not coalesce across processes or hosts.
+ *   - They never observe the envelope payload, the LLM history, or
+ *     any string that originated from an LLM.
+ *
+ * If an adopter wires the snapshot to a metrics backend, that is their
+ * production decision — and the snapshot shape is explicitly designed
+ * to remain stable across minor versions so dashboards survive bumps.
+ */
+const DEFAULTS = {
+    maxPackKeys: 256,
+    maxBasisCategories: 64,
+    maxRefusalCodes: 128,
+    maxAttributeKeys: 256,
+    maxDiagnosticCodes: 128,
+    maxCodemodKeys: 64,
+};
+const OVERFLOW = "__overflow__";
+/**
+ * Bounded-key counter. Increment never throws; over-cap keys land in
+ * the overflow bucket so the snapshot's cardinality is provably
+ * bounded regardless of input.
+ */
+class BoundedCounter {
+    cap;
+    map = new Map();
+    constructor(cap) {
+        this.cap = cap;
+    }
+    add(key, delta = 1) {
+        if (this.map.has(key)) {
+            this.map.set(key, (this.map.get(key) ?? 0) + delta);
+            return;
+        }
+        if (this.map.size >= this.cap) {
+            this.map.set(OVERFLOW, (this.map.get(OVERFLOW) ?? 0) + delta);
+            return;
+        }
+        this.map.set(key, delta);
+    }
+    snapshot() {
+        const out = {};
+        const keys = [...this.map.keys()].sort();
+        for (const key of keys) {
+            out[key] = this.map.get(key) ?? 0;
+        }
+        return out;
+    }
+}
+class PackUniqueSet {
+    cap;
+    seen = new Set();
+    byContract = new BoundedCounter(32);
+    constructor(cap) {
+        this.cap = cap;
+    }
+    observe(packId, contract) {
+        if (this.seen.has(packId))
+            return;
+        if (this.seen.size >= this.cap)
+            return;
+        this.seen.add(packId);
+        this.byContract.add(contract);
+    }
+    snapshot() {
+        return this.byContract.snapshot();
+    }
+}
+const INCIDENT_CLASSES = [
+    "kill_switch_storm",
+    "kill_switch_split_brain",
+    "audit_sink_outage",
+    "audit_event_bus_failure",
+    "replay_drift_mass",
+    "replay_drift_single",
+    "integrity_failure",
+    "deferred_resume_stuck",
+    "confirmation_token_loss",
+    "pack_signature_invalid",
+    "pack_signature_missing",
+    "rate_limit_threshold_breach",
+    "guard_panic_storm",
+    "shadow_divergence_spike",
+];
+const TRIAGE_OUTCOMES = [
+    "true_positive",
+    "false_positive",
+    "by_design",
+    "wont_fix",
+    "deferred",
+];
+function emptyIncidentMap() {
+    const out = {};
+    for (const klass of INCIDENT_CLASSES)
+        out[klass] = 0;
+    return out;
+}
+function emptyTriageMap() {
+    const out = {};
+    for (const outcome of TRIAGE_OUTCOMES)
+        out[outcome] = 0;
+    return out;
+}
+export function createEcosystemTelemetry(options = {}) {
+    const opts = { ...DEFAULTS, ...options };
+    let pack = makeState();
+    function makeState() {
+        return {
+            packs: new PackUniqueSet(opts.maxPackKeys),
+            qualityTiers: new BoundedCounter(16),
+            signatureAlgorithms: new BoundedCounter(8),
+            trustOutcomes: new BoundedCounter(8),
+            decisionKinds: new BoundedCounter(8),
+            refusalCodes: new BoundedCounter(opts.maxRefusalCodes),
+            basisCategories: new BoundedCounter(opts.maxBasisCategories),
+            replayByClass: emptyReplayMap(),
+            replayTotal: 0,
+            analyzerByCode: new Map(),
+            analyzerTotals: emptyTriageMap(),
+            semconvEmissions: new BoundedCounter(opts.maxAttributeKeys),
+            semconvUnknown: 0,
+            codemodVisits: new BoundedCounter(opts.maxCodemodKeys),
+            codemodModifications: new BoundedCounter(opts.maxCodemodKeys),
+            codemodNoops: new BoundedCounter(opts.maxCodemodKeys),
+            incidents: emptyIncidentMap(),
+            incidentTotal: 0,
+        };
+    }
+    function emptyReplayMap() {
+        return {
+            decision_kind_changed: 0,
+            basis_added: 0,
+            basis_removed: 0,
+            basis_swapped: 0,
+            refusal_code_changed: 0,
+            unclassified: 0,
+        };
+    }
+    return {
+        observePackInstallation(packId, contract) {
+            pack.packs.observe(packId, contract);
+        },
+        observePackManifest(qualityTier) {
+            pack.qualityTiers.add(qualityTier ?? "unset");
+        },
+        observePackTrust(outcome) {
+            pack.trustOutcomes.add(outcome);
+        },
+        observePackSignature(algorithm) {
+            pack.signatureAlgorithms.add(algorithm);
+        },
+        observeDecision(decision) {
+            pack.decisionKinds.add(decision.kind);
+            for (const b of decision.basis) {
+                pack.basisCategories.add(b.category);
+            }
+            if (decision.kind === "REFUSE") {
+                pack.refusalCodes.add(decision.refusal.code);
+            }
+        },
+        observeRefusal(refusal) {
+            pack.refusalCodes.add(refusal.code);
+        },
+        observeAuditRecord(record) {
+            pack.decisionKinds.add(record.decision.kind);
+            for (const b of record.decision.basis) {
+                pack.basisCategories.add(b.category);
+            }
+            if (record.decision.kind === "REFUSE") {
+                pack.refusalCodes.add(record.decision.refusal.code);
+            }
+        },
+        observeReplayMismatch(mismatch) {
+            pack.replayTotal++;
+            pack.replayByClass[classifyReplayFailure(mismatch)]++;
+        },
+        observeAnalyzerTriage(diagnosticCode, outcome) {
+            pack.analyzerTotals[outcome]++;
+            let bucket = pack.analyzerByCode.get(diagnosticCode);
+            if (!bucket) {
+                if (pack.analyzerByCode.size >= opts.maxDiagnosticCodes) {
+                    bucket = pack.analyzerByCode.get(OVERFLOW);
+                    if (!bucket) {
+                        bucket = emptyTriageMap();
+                        pack.analyzerByCode.set(OVERFLOW, bucket);
+                    }
+                }
+                else {
+                    bucket = emptyTriageMap();
+                    pack.analyzerByCode.set(diagnosticCode, bucket);
+                }
+            }
+            bucket[outcome]++;
+        },
+        observeSemconvEmission(attribute, knownAttributes) {
+            pack.semconvEmissions.add(attribute);
+            if (!knownAttributes.has(attribute)) {
+                pack.semconvUnknown++;
+            }
+        },
+        observeCodemod(name, outcome) {
+            if (outcome === "visited")
+                pack.codemodVisits.add(name);
+            if (outcome === "modified")
+                pack.codemodModifications.add(name);
+            if (outcome === "noop")
+                pack.codemodNoops.add(name);
+        },
+        observeIncident(klass) {
+            pack.incidents[klass]++;
+            pack.incidentTotal++;
+        },
+        snapshot() {
+            const analyzerByDiagnosticCode = {};
+            const codeKeys = [...pack.analyzerByCode.keys()].sort();
+            for (const key of codeKeys) {
+                const value = pack.analyzerByCode.get(key);
+                if (value !== undefined)
+                    analyzerByDiagnosticCode[key] = { ...value };
+            }
+            return {
+                schemaVersion: 1,
+                pack: {
+                    packsByContract: pack.packs.snapshot(),
+                    qualityTiers: pack.qualityTiers.snapshot(),
+                    signatureAlgorithms: pack.signatureAlgorithms.snapshot(),
+                    trustOutcomes: pack.trustOutcomes.snapshot(),
+                },
+                decisions: {
+                    byKind: pack.decisionKinds.snapshot(),
+                    refusalByCode: pack.refusalCodes.snapshot(),
+                    basisByCategory: pack.basisCategories.snapshot(),
+                },
+                replayFailures: {
+                    byClass: { ...pack.replayByClass },
+                    total: pack.replayTotal,
+                },
+                analyzerTriage: {
+                    byDiagnosticCode: analyzerByDiagnosticCode,
+                    totals: { ...pack.analyzerTotals },
+                },
+                semconvAdoption: {
+                    emissionsByAttribute: pack.semconvEmissions.snapshot(),
+                    unknownAttributeCount: pack.semconvUnknown,
+                },
+                migrationPain: {
+                    codemodVisits: pack.codemodVisits.snapshot(),
+                    codemodModifications: pack.codemodModifications.snapshot(),
+                    codemodNoops: pack.codemodNoops.snapshot(),
+                },
+                incidents: {
+                    byClass: { ...pack.incidents },
+                    total: pack.incidentTotal,
+                },
+            };
+        },
+        reset() {
+            pack = makeState();
+        },
+    };
+}
+/**
+ * Classify a single replay mismatch into a closed taxonomy entry. Pure;
+ * useful both inside the aggregator and standalone for adopters who
+ * want to bucket their own replay report into operational categories.
+ */
+export function classifyReplayFailure(mismatch) {
+    if (mismatch.kind === "DECISION_KIND")
+        return "decision_kind_changed";
+    if (mismatch.kind === "REFUSAL_CODE_DRIFT")
+        return "refusal_code_changed";
+    if (mismatch.kind === "BASIS_DRIFT") {
+        const missing = mismatch.basisDelta?.missing.length ?? 0;
+        const extra = mismatch.basisDelta?.extra.length ?? 0;
+        if (missing > 0 && extra === 0)
+            return "basis_removed";
+        if (missing === 0 && extra > 0)
+            return "basis_added";
+        if (missing > 0 && extra > 0)
+            return "basis_swapped";
+    }
+    return "unclassified";
+}
+/**
+ * Canonical JSON serialization of a snapshot. Useful when an adopter
+ * wants byte-identical snapshots across processes (e.g., for diffing
+ * weekly aggregates). Sorts every object key recursively.
+ */
+export function serializeEcosystemSnapshot(snapshot) {
+    return canonicalJson(snapshot);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`);
+    return `{${parts.join(",")}}`;
+}
+//# sourceMappingURL=ecosystem-telemetry.js.map