feat: add OpenTelemetry exporter

Author: MicroYui

.ai/ARCHITECTURE_SUMMARY.md

@@ -13,6 +13,7 @@ Agent / demo loop
      -> Retrieval Controller
      -> Admission Gate
      -> Profiler
+     -> Telemetry projection package (core exporter slice complete)
   -> PostgreSQL + pgvector source of truth
   -> CLI/JSON/Markdown report first; dashboard later
 ```
@@ -32,6 +33,7 @@ Longer-term documents also describe Redis/Celery, Elasticsearch, Neo4j, React da
 - **Context Packer:** emits structured blocks: active state, tool evidence, project constraints, profile/procedural/episodic memory, warnings.
 - **Profiler:** records phase-level latency, candidate counts, gate counts, token/cost fields when available.
 - **Evaluation/Demo:** compares vector-only versus state-aware/gated retrieval on deterministic cases.
+- **Telemetry Projection Package:** `docs/design/OTEL_OPENINFERENCE_EXPORTER_PLAN.md` core exporter slice is complete through Segment 4 closeout and final full-plan review hardening. The package provides redacted `memtrace.*` / OpenInference-compatible spans, noop/in-memory/JSONL/optional OTLP sinks, settings-driven factory construction with strict/header/sample-rate controls, a fail-open `TelemetryService`, post-persistence runtime hooks, and a minimal read-only run export endpoint returning counts/generic warnings only. Runtime hooks must not synchronously perform network OTLP export, must remain fail-open on hot paths (including projection reads), and must avoid duplicate run/step lifecycle span ids; CLI export and richer access/backfill surfaces remain deferred.
 
 ## Key Data Structures
 
@@ -60,6 +62,7 @@ Longer-term documents also describe Redis/Celery, Elasticsearch, Neo4j, React da
 - P0 write rules must not become a general NLP/extraction system by accident.
 - Provider capability snapshots and retrieval policy snapshots must stay non-secret.
 - Benchmarks must force deterministic providers even when real-provider env vars are set.
+- Telemetry export is an external egress surface: it must be disabled/noop by default, recursively redacted/capped, best-effort/fail-open on runtime hot paths, no synchronous network export from hot-path hooks, quota-governed for HTTP export surfaces, and read-only when projecting persisted run data. Access-level export/backfill remains future work.
 
 ## Persistence / Storage Design
 
@@ -69,4 +72,5 @@ Longer-term documents also describe Redis/Celery, Elasticsearch, Neo4j, React da
 ## External Integrations
 
 - Implemented: Python SDK/CLI/LangGraph adapter, TypeScript SDK, MCP server, and MCP config templates.
-- Future: OpenTelemetry/OpenInference exporter, React dashboard, and dedicated IDE extension if MCP adoption feedback shows editor-specific needs.
+- Latest completed feature: OpenTelemetry/OpenInference exporter via `docs/design/OTEL_OPENINFERENCE_EXPORTER_PLAN.md`; Segment 1 contracts/redaction/pure builders, Segment 2 exporters/settings/factory/service, Segment 3 runtime hooks/API/docs, and Segment 4 verification/closeout are complete.
+- Future: React dashboard and dedicated IDE extension if MCP adoption feedback shows editor-specific needs; vendor-specific LangSmith/Phoenix/Langfuse bridges remain deferred until explicitly selected as a separate bridge slice.

.ai/DECISIONS.md

@@ -235,7 +235,7 @@ Sources:
 - **Status:** accepted; implemented through R1-C2
 - **Context:** After Phase 4 and INT-A/INT-B/INT-C, MemTrace has substantial runtime/platform and integration capability: state-aware memory runtime, context compaction, failure-aware negative evidence, provider registry/key ontology, async/lifecycle/governance foundations, Python SDK/CLI/LangGraph adapter, TypeScript SDK, MCP server, MCP config templates, benchmark, replay, and reports. Remaining roadmap candidates such as OpenTelemetry/OpenInference exporter, advanced retrieval/storage, admin conflict workflow, and React dashboard are useful but either add new feature surfaces or assume public adoption paths already exist.
 - **Decision:** Select `docs/design/RELEASE_READINESS_PLAN.md` as the next implementation plan. R1 focuses on public adoption readiness: command inventory, README/user-doc rewrite, 5-minute demo/smoke consolidation, package metadata and package-shape checks, CI, release-hygiene guards, release checklist, verification, and ROADMAP/`.ai` closeout. R1 must not add runtime retrieval/gate/context-packing semantics. It must keep JS packages `private: true` unless publication is explicitly approved, avoid introducing a `dist/` build pipeline by default, use `oven-sh/setup-bun` in CI while documenting local temporary-Bun fallback, and make service/provider-dependent paths opt-in.
-- **Consequences:** R1 is now complete: public onboarding, user docs, smoke script, package metadata/package-shape checks, CI, release hygiene, release checklist, benchmark/reproduce closeout, and ROADMAP/`.ai` sync are in place. OpenTelemetry/OpenInference exporter becomes the recommended next feature slice, but README/public docs must not advertise OTel/LangSmith/Phoenix/Langfuse support as available until an exporter exists. Phase 5 retrieval/storage, admin/manual governance workflow, React dashboard, dedicated IDE extension, and automatic npm/PyPI publishing remain out of scope until explicitly selected.
+- **Consequences:** R1 is now complete: public onboarding, user docs, smoke script, package metadata/package-shape checks, CI, release hygiene, release checklist, benchmark/reproduce closeout, and ROADMAP/`.ai` sync are in place. At R1 closeout, OpenTelemetry/OpenInference exporter became the recommended next feature slice; this historical recommendation has since been superseded by ADR-031 / OTel Segment 4 closeout. README/public docs must still avoid advertising LangSmith/Phoenix/Langfuse direct vendor support unless a separate bridge slice is completed. Phase 5 retrieval/storage, admin/manual governance workflow, React dashboard, dedicated IDE extension, and automatic npm/PyPI publishing remain out of scope until explicitly selected.
 - **Sources:** `docs/design/RELEASE_READINESS_PLAN.md`, `.ai/PROJECT_STATE.md`, `.ai/IMPLEMENTATION_PLAN.md`, `.ai/OPEN_QUESTIONS.md`.
 
 ### ADR-027: Public docs classify quickstarts by runtime requirement
@@ -273,3 +273,12 @@ Sources:
 - **Decision:** Add `docs/release-checklist.md` as a manual maintainer checklist covering release scope selection, required verification, Python/JS package dry-run checks, artifact and secret hygiene, tagging notes, explicit publish decision gates, and rollback guidance. Keep `@memtrace/sdk` and `@memtrace/mcp-server` private by default; no automatic package publishing, `dist/` build pipeline, bundler, or declaration-emission workflow is added in R1.
 - **Consequences:** Maintainers have a repeatable release process while publication remains an explicit future decision. Release closeout can verify benchmark/reproduce and hygiene without creating package registry side effects.
 - **Sources:** `docs/release-checklist.md`, `README.md`, `docs/design/RELEASE_READINESS_PLAN.md` R1-C1/R1-C2.
+
+### ADR-031: OpenTelemetry/OpenInference exporter starts as a default-off projection, not vendor-specific runtime logic
+
+- **Date:** 2026-06-14
+- **Status:** accepted; implemented through Segment 4 closeout
+- **Context:** After R1, MemTrace has public onboarding, replay/report observability, SDK/MCP integration, provider/key ontology, governance, and reproducible benchmark coverage. The next recommended roadmap item is OpenTelemetry/OpenInference export so users can send MemTrace runtime evidence to external observability tools. Because telemetry is an egress surface and default quickstarts/CI must remain deterministic, directly adding LangSmith/Phoenix/Langfuse SDKs or always-on network export would increase dependency and leakage risk.
+- **Decision:** Implement `docs/design/OTEL_OPENINFERENCE_EXPORTER_PLAN.md` as a default-off OTLP/OpenInference core exporter. The exporter is a read-only projection over MemTrace DTOs and persisted records: pure semantic builders create redacted spans/events, a pluggable exporter protocol supports noop/in-memory/JSONL/optional OTLP sinks, and `TelemetryService` provides best-effort runtime hooks plus a minimal read-only run export API. Runtime hooks may build/enqueue spans but must not synchronously perform network OTLP export; OTLP delivery must use OTel SDK batching or an internal best-effort queue. `memtrace.*` attributes are the stable contract, while OpenInference-compatible keys are emitted only where safe as a compatibility layer. Vendor-specific LangSmith/Phoenix/Langfuse bridges are deferred; they may consume OTLP/OpenInference output externally but are not direct dependencies in this slice.
+- **Consequences:** Telemetry does not become a second source of truth and cannot change retrieval/gate/context-packing/benchmark semantics. Default local/dev/CI/reproduce behavior remains service-free and network-free. Segment 1 locks a stricter egress contract: `TelemetrySpan`/`TelemetryEvent` attributes exclude `None`, raw-content-like metadata keys (`prompt`, `query`, `content`, `raw_context`, `messages`, `context_blocks`, etc.) are redacted, benign token metric spellings are preserved, and optional-run-id builders fall back to stable record ids rather than a shared `unknown` trace. Segment 2 adds default-off exporter sinks and factory/service boundaries. Segment 3 wires runtime hooks after authoritative persistence, adds a minimal read-only `POST /v1/telemetry/export/runs/{run_id}` endpoint that returns counts/warnings only, and documents JSONL/OTLP usage plus vendor non-goals. Segment 3 detailed-review hardening keeps runtime hooks fail-open even when a fail-closed service is injected, avoids duplicate run/step lifecycle span ids, and applies existing `report_export` quota to the HTTP export surface. Segment 4 closeout verified targeted telemetry/runtime/API, affected runtime/API/observability, compileall, full pytest, benchmark/reproduce, release hygiene, and diff checks. CLI telemetry-export and richer access/backfill surfaces remain deferred. Future vendor bridges can be added behind the same exporter boundary after a separate bridge design.
+- **Sources:** `docs/design/OTEL_OPENINFERENCE_EXPORTER_PLAN.md`, `docs/design/ROADMAP.md` §6, `.ai/PROJECT_STATE.md`, `.ai/IMPLEMENTATION_PLAN.md`.