audit(observability): verify current-main telemetry and evidence boundaries #188

Scope

Evidence-first current-main audit for SemantIQ's own architecture, motivated by an external AI-agent observability reference. No external code is to be copied or vendored. This is a proposed bounded work item under #177 and #180, not an automatic release commitment.

Baseline inspected via GitHub connector: protected-main 979cf511e2fc57811fb3cef3766be1653a2e45f5 (2026-10-10). Recheck HEAD at execution time.

Repository evidence to reconcile

• packages/monitoring/src/index.ts currently only re-exports RuntimeMetrics as a type; packages/monitoring/README.md describes broader tracing/OpenTelemetry capabilities.
• packages/alpha-observability/src/index.ts re-exports Alpha runtime data structures.
• packages/evidence/src/trace-mapper-engine.ts implements approved-profile mapping to canonical Trace/TraceEvent with chaining.
• tests/unit/trace-mapping-provenance.test.ts exercises mapping and integrity.
• tests/unit/observability-dashboard.test.ts exercises snapshot and renderer tests, not evidence of deployed Grafana ingestion.
• Root docker-compose.yml defines Prometheus/Grafana containers, but operational ingestion into those services is not demonstrated by the inspected paths.
• Docs/ecosystem/INTEGRATION_GRAPH.md marks OTel/Prometheus/Grafana as SCAFFOLD at an older snapshot and explicitly calls for revalidation.
• Docs/OBSERVABILITY.md is a broad architecture vision; don't silently upgrade docs-only plans to verified runtime capability.

Checklist

• Audit actual runtime telemetry producers, consumers, configuration, and dependency graph on exact current main.
• Produce source/test evidence matrix: IMPLEMENTED / PARTIAL / CONTRACT_ONLY / SCAFFOLD / DOCS_ONLY.
• Trace end-to-end: execution → canonical TraceEvent → metrics/evidence → optional telemetry export.
• Reconcile marketing/README/docs with verified technical truth; link docs(ecosystem): mark evidence snapshots and bound publication-preparation guides #120 where appropriate.
• Catalogue privacy and provenance threats (event payloads, credentials, reasoning logs, filesystem paths).
• Record independent test gaps without claiming integrations are absent globally based on one package.
• Identify contracts that must be RFC/Core-reviewed before code changes.
• Feed reviewed conclusions into canonical roadmap roadmap: establish the current canonical SemantIQ product roadmap #177; classify NOW/NEXT/FUTURE only with maintainer review.

Acceptance

A reviewable evidence matrix with exact paths/commit/test output; a bounded ADR/RFC decision list; no new production or scientific claims. No external tool execution, benchmarking, release/tag, or changes to protected main in this issue.

Related: #177, #180, #120, #165.

Linked bounded follow-up work

• design(evidence): canonical agent-run telemetry correlation contract #189 — Canonical agent-run telemetry correlation contract; design gate after this audit.
• test(evidence): prove operational and behavioral outcomes remain distinct #191 — Deterministic operational-versus-behavioral outcome fixtures; after contract review.
• feat(observability): gate an opt-in OpenTelemetry export adapter #190 — Optional OpenTelemetry exporter; gated future under future: maintain a gated post-alpha capability horizon #178 until acceptance and explicit promotion.

Suggested sequencing: #188 → #189 → #191 → #190 (only if independently justified). Publish/merge a canonical product-roadmap entry through #177 rather than maintaining a parallel roadmap. The external friend's local Codex tool comparison remains a separate final experiment, not a dependency or imported implementation.

Execution log — 2026-10-10

• Created Draft PR #193 on docs/observability-evidence-audit from protected main 979cf511e2fc57811fb3cef3766be1653a2e45f5.
• Added a bounded current-main static evidence matrix at Docs/ecosystem/OBSERVABILITY_EVIDENCE_AUDIT_2026-10-10.md.
• Recorded trace-status/missingness, redaction/provenance and observability-vs-adjudication findings.
• Opened #192 for independent verification of nested digest-preimage coverage in the legacy normalizer.
• Verified PR docs(observability): record bounded telemetry evidence audit #193 is Draft/open/unmerged, changed-files listing contains one documentation file, and protected main remained at the audited SHA.
• Full-tree source/dependency review, direct runtime/CI execution, exact-head PR checks, maintainer acceptance and canonical Integration Graph refresh remain pending.
• Do not close audit(observability): verify current-main telemetry and evidence boundaries #188 merely because a draft evidence annex now exists. Do not promote design(evidence): canonical agent-run telemetry correlation contract #189/feat(observability): gate an opt-in OpenTelemetry export adapter #190/test(evidence): prove operational and behavioral outcomes remain distinct #191 to implementation without their stated gates.

No external code reused; no new benchmark result, runtime exporter, release or schema change.