aevum-otel 0.6.0__tar.gz

aevum_otel-0.6.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+
+# Build
+dist/
+build/
+site/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Verify scripts (run locally, never commit)
+verify_*.py
+scripts/verify_*.py
+
+# Aevum development — never commit (Phase 0+)
+aevum_principles.key
+signed_principles_draft.yaml
+tools/sign_principles.py
+
+# Private keys — never commit
+*.key
+*.pem
+
+# OpenSSF Scorecard output (Phase 0+)
+results.sarif
+verify_phase3.py
+verify_phase7.py
+verify_phase8.py
+verify_phase*.py
+
+# Maintenance generated files — local only, never commit
+maintenance/generated/

aevum_otel-0.6.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: aevum-otel
+Version: 0.6.0
+Summary: Aevum — OpenTelemetry bridge complication. Routes sigchain events to OTel GenAI spans.
+Project-URL: Homepage, https://aevum.build
+Project-URL: Repository, https://github.com/aevum-labs/aevum
+Project-URL: Issues, https://github.com/aevum-labs/aevum/issues
+License-Expression: Apache-2.0
+Keywords: aevum,audit,genai,observability,opentelemetry,otel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: aevum-core>=0.6.0
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == 'otlp'
+Provides-Extra: otlp-http
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == 'otlp-http'
+Description-Content-Type: text/markdown
+
+# aevum-otel
+
+OpenTelemetry bridge complication for Aevum. Routes sigchain events to OTel GenAI spans.
+
+## Install
+
+```bash
+pip install aevum-otel
+# With OTLP HTTP exporter:
+pip install "aevum-otel[otlp-http]"
+# With OTLP gRPC exporter:
+pip install "aevum-otel[otlp]"
+```
+
+## Usage
+
+```python
+from aevum.core import Engine
+from aevum.otel import AevumOTelBridge
+
+bridge = AevumOTelBridge(service_name="my-service")
+engine = Engine()
+engine.install_complication(bridge, auto_approve=True)
+
+# All engine calls (ingest, query, etc.) now emit OTel GenAI spans.
+```
+
+## Privacy defaults
+
+By default only `audit_id` is emitted as `gen_ai.content.reference`. No prompt or response content is included.
+
+To opt in to richer attributes:
+
+```bash
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+```
+
+## GenAI semantic conventions
+
+For the latest experimental GenAI semconv:
+
+```bash
+export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+```
+
+See [OTel GenAI semconv documentation](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for details.
+
+## Tested exporters
+
+- Console exporter (always available via `opentelemetry-sdk`)
+- Grafana Tempo (document setup if environment permits — otherwise note as untested)
+- Langfuse (document setup if environment permits — otherwise note as untested)
+
+## License
+
+Apache-2.0

aevum_otel-0.6.0/README.md

@@ -0,0 +1,56 @@
+# aevum-otel
+
+OpenTelemetry bridge complication for Aevum. Routes sigchain events to OTel GenAI spans.
+
+## Install
+
+```bash
+pip install aevum-otel
+# With OTLP HTTP exporter:
+pip install "aevum-otel[otlp-http]"
+# With OTLP gRPC exporter:
+pip install "aevum-otel[otlp]"
+```
+
+## Usage
+
+```python
+from aevum.core import Engine
+from aevum.otel import AevumOTelBridge
+
+bridge = AevumOTelBridge(service_name="my-service")
+engine = Engine()
+engine.install_complication(bridge, auto_approve=True)
+
+# All engine calls (ingest, query, etc.) now emit OTel GenAI spans.
+```
+
+## Privacy defaults
+
+By default only `audit_id` is emitted as `gen_ai.content.reference`. No prompt or response content is included.
+
+To opt in to richer attributes:
+
+```bash
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+```
+
+## GenAI semantic conventions
+
+For the latest experimental GenAI semconv:
+
+```bash
+export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+```
+
+See [OTel GenAI semconv documentation](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for details.
+
+## Tested exporters
+
+- Console exporter (always available via `opentelemetry-sdk`)
+- Grafana Tempo (document setup if environment permits — otherwise note as untested)
+- Langfuse (document setup if environment permits — otherwise note as untested)
+
+## License
+
+Apache-2.0

aevum_otel-0.6.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aevum-otel"
+version = "0.6.0"
+description = "Aevum — OpenTelemetry bridge complication. Routes sigchain events to OTel GenAI spans."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+keywords = ["aevum", "opentelemetry", "otel", "observability", "genai", "audit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "aevum-core>=0.6.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-api>=1.27.0",
+]
+
+[project.optional-dependencies]
+otlp = [
+    "opentelemetry-exporter-otlp-proto-grpc>=1.27.0",
+]
+otlp-http = [
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.9",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://aevum.build"
+Repository = "https://github.com/aevum-labs/aevum"
+Issues = "https://github.com/aevum-labs/aevum/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevum"]
+
+[tool.uv.sources]
+aevum-core = { workspace = true }
+
+[tool.mypy]
+mypy_path = "src"
+strict = true
+python_version = "3.11"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 130
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I", "ANN"]
+ignore = ["ANN401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--tb=short"
+pythonpath = ["src", "tests"]

aevum_otel-0.6.0/src/aevum/otel/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Aevum Labs contributors
+"""
+aevum-otel — OpenTelemetry bridge complication for Aevum.
+
+Routes sigchain events to OpenTelemetry GenAI spans, publishing to any
+OTLP-compatible backend (Grafana Tempo, Langfuse, Jaeger, etc.).
+
+Privacy defaults:
+  - Only audit_id is emitted (as gen_ai.content.reference).
+  - No prompt, response, or payload content is emitted by default.
+  - Set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true to opt in.
+
+GenAI semantic conventions:
+  - Set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental for latest.
+
+Usage:
+    from aevum.core import Engine
+    from aevum.otel import AevumOTelBridge
+
+    bridge = AevumOTelBridge(service_name="my-service")
+    engine = Engine()
+    engine.install_complication(bridge, auto_approve=True)
+
+    # Events from engine.ingest(), engine.query(), etc. will now appear
+    # as OTel spans in your configured OTLP backend.
+"""
+
+from aevum.otel.bridge import AevumOTelBridge
+
+__version__ = "0.6.0"
+__all__ = ["AevumOTelBridge"]

aevum_otel-0.6.0/src/aevum/otel/bridge.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Aevum Labs contributors
+"""
+AevumOTelBridge — sigchain events → OTel GenAI spans.
+
+Privacy model:
+  Default: emit only audit_id as gen_ai.content.reference.
+  Opt-in:  set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+           to also emit event_type and actor in span attributes.
+
+The bridge registers itself as a ledger observer and emits one OTel span
+per AuditEvent. Span duration is always 0 (events are instantaneous writes).
+
+Complication manifest:
+  name: "aevum-otel-bridge"
+  version: "0.6.0"
+  capabilities: ["telemetry.otel"]
+
+Install via:
+    engine.install_complication(bridge, auto_approve=True)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aevum.core.audit.event import AuditEvent
+
+_logger = logging.getLogger("aevum.otel")
+
+_MANIFEST: dict[str, Any] = {
+    "name": "aevum-otel-bridge",
+    "version": "0.6.0",
+    "schema_version": "1.0",
+    "capabilities": ["telemetry.otel"],
+    "description": "Routes Aevum sigchain events to OTel GenAI spans.",
+    "author": "Aevum Labs",
+    "classification_max": 0,
+    "functions": ["ingest", "query", "review", "commit", "replay"],
+    "auth": {"public_key": None},
+}
+
+# OTel GenAI semantic convention attribute names
+_ATTR_AUDIT_ID = "gen_ai.content.reference"
+_ATTR_EVENT_TYPE = "aevum.event_type"
+_ATTR_ACTOR = "aevum.actor"
+_ATTR_SEQUENCE = "aevum.sequence"
+_ATTR_EPISODE_ID = "aevum.episode_id"
+
+
+def _capture_content_enabled() -> bool:
+    return (
+        os.environ.get(
+            "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", ""
+        ).lower()
+        in ("true", "1", "yes")
+    )
+
+
+class AevumOTelBridge:
+    """
+    OpenTelemetry bridge complication.
+
+    Subscribes to ledger events and emits OTel GenAI spans to the configured
+    OTLP endpoint (or any registered TracerProvider).
+
+    Args:
+        service_name:    OTel service name (default: "aevum").
+        tracer_provider: Optional pre-configured TracerProvider. If None,
+                         uses the global OTel TracerProvider.
+        endpoint:        Optional OTLP endpoint URL. If set, registers an
+                         OTLP HTTP exporter (requires aevum-otel[otlp-http]).
+                         If None, uses the global provider (e.g. console exporter
+                         configured by the host application).
+    """
+
+    name: str = "aevum-otel-bridge"
+
+    def __init__(
+        self,
+        *,
+        service_name: str = "aevum",
+        tracer_provider: Any | None = None,
+        endpoint: str | None = None,
+    ) -> None:
+        from opentelemetry import trace
+
+        self._service_name = service_name
+
+        if tracer_provider is not None:
+            self._tracer_provider = tracer_provider
+        elif endpoint is not None:
+            self._tracer_provider = self._build_otlp_provider(service_name, endpoint)
+        else:
+            self._tracer_provider = trace.get_tracer_provider()
+
+        self._tracer = self._tracer_provider.get_tracer(
+            "aevum.otel.bridge",
+            schema_url="https://opentelemetry.io/schemas/1.28.0",
+        )
+        self._latency_samples: list[float] = []
+
+    def _build_otlp_provider(self, service_name: str, endpoint: str) -> Any:
+        """Build a TracerProvider with OTLP HTTP exporter."""
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        try:
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+                OTLPSpanExporter,
+            )
+        except ImportError as exc:
+            raise ImportError(
+                "OTLP HTTP exporter requires: pip install 'aevum-otel[otlp-http]'"
+            ) from exc
+
+        resource = Resource.create({"service.name": service_name})
+        provider = TracerProvider(resource=resource)
+        exporter = OTLPSpanExporter(endpoint=endpoint)
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+        return provider
+
+    def manifest(self) -> dict[str, Any]:
+        return _MANIFEST
+
+    def set_event_observer(self, ledger: Any) -> None:
+        """Called by Engine.install_complication() to hook into ledger events."""
+        if hasattr(ledger, "add_observer"):
+            ledger.add_observer(self)
+        else:
+            _logger.warning(
+                "Ledger %r does not support add_observer — "
+                "AevumOTelBridge will not emit spans",
+                ledger,
+            )
+
+    def on_event(self, event: AuditEvent) -> None:
+        """
+        Called for each AuditEvent appended to the ledger.
+        Emits one OTel span per event.
+        """
+        import time  # noqa: PLC0415
+
+        from opentelemetry.trace import SpanKind, StatusCode
+
+        t0 = time.monotonic()
+        capture = _capture_content_enabled()
+
+        try:
+            with self._tracer.start_as_current_span(
+                f"aevum.{event.event_type}",
+                kind=SpanKind.INTERNAL,
+            ) as span:
+                # Always-safe: audit reference only
+                span.set_attribute(_ATTR_AUDIT_ID, event.audit_id())
+                span.set_attribute(_ATTR_SEQUENCE, event.sequence)
+
+                if event.episode_id:
+                    span.set_attribute(_ATTR_EPISODE_ID, event.episode_id)
+
+                if capture:
+                    # Opt-in: richer attributes
+                    span.set_attribute(_ATTR_EVENT_TYPE, event.event_type)
+                    span.set_attribute(_ATTR_ACTOR, event.actor)
+
+                span.set_status(StatusCode.OK)
+        except Exception as exc:  # noqa: BLE001
+            _logger.error("OTel span emission failed (suppressed): %s", exc)
+        finally:
+            elapsed_ms = (time.monotonic() - t0) * 1000
+            self._latency_samples.append(elapsed_ms)
+
+    def latency_p99_ms(self) -> float | None:
+        """Return the p99 latency in ms over all observed events, or None if no data."""
+        if not self._latency_samples:
+            return None
+        sorted_samples = sorted(self._latency_samples)
+        idx = int(len(sorted_samples) * 0.99)
+        return sorted_samples[min(idx, len(sorted_samples) - 1)]
+
+    def reset_latency_samples(self) -> None:
+        self._latency_samples.clear()

aevum_otel-0.6.0/tests/test_bridge.py

@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for AevumOTelBridge complication."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from aevum.otel import AevumOTelBridge
+
+
+def _make_bridge() -> tuple[AevumOTelBridge, InMemorySpanExporter]:
+    """Create a bridge wired to an in-memory span exporter for testing."""
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    bridge = AevumOTelBridge(service_name="test-service", tracer_provider=provider)
+    return bridge, exporter
+
+
+def _make_mock_event(
+    event_type: str = "ingest.accepted",
+    actor: str = "test-agent",
+    sequence: int = 1,
+    episode_id: str | None = None,
+) -> MagicMock:
+    event = MagicMock()
+    event.audit_id.return_value = "urn:aevum:audit:test-123"
+    event.event_type = event_type
+    event.actor = actor
+    event.sequence = sequence
+    event.episode_id = episode_id
+    return event
+
+
+# ── Manifest ──────────────────────────────────────────────────────────────────
+
+class TestManifest:
+    def test_manifest_name(self):
+        bridge = AevumOTelBridge()
+        assert bridge.manifest()["name"] == "aevum-otel-bridge"
+
+    def test_manifest_capabilities(self):
+        bridge = AevumOTelBridge()
+        assert "telemetry.otel" in bridge.manifest()["capabilities"]
+
+    def test_name_attribute(self):
+        bridge = AevumOTelBridge()
+        assert bridge.name == "aevum-otel-bridge"
+
+
+# ── Span emission ─────────────────────────────────────────────────────────────
+
+class TestSpanEmission:
+    def test_emits_span_per_event(self):
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event())
+        spans = exporter.get_finished_spans()
+        assert len(spans) == 1
+
+    def test_span_name_includes_event_type(self):
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event(event_type="session.start"))
+        spans = exporter.get_finished_spans()
+        assert spans[0].name == "aevum.session.start"
+
+    def test_span_has_audit_id_attribute(self):
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event())
+        spans = exporter.get_finished_spans()
+        attrs = dict(spans[0].attributes or {})
+        assert attrs.get("gen_ai.content.reference") == "urn:aevum:audit:test-123"
+
+    def test_span_has_sequence_attribute(self):
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event(sequence=42))
+        spans = exporter.get_finished_spans()
+        attrs = dict(spans[0].attributes or {})
+        assert attrs.get("aevum.sequence") == 42
+
+    def test_no_content_in_default_mode(self, monkeypatch):
+        monkeypatch.delenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", raising=False)
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event(actor="secret-agent"))
+        spans = exporter.get_finished_spans()
+        attrs = dict(spans[0].attributes or {})
+        # actor should NOT be emitted in default mode
+        assert "aevum.actor" not in attrs
+        assert "aevum.event_type" not in attrs
+
+    def test_content_emitted_when_opted_in(self, monkeypatch):
+        monkeypatch.setenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "true")
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event(event_type="ingest.accepted", actor="my-agent"))
+        spans = exporter.get_finished_spans()
+        attrs = dict(spans[0].attributes or {})
+        assert attrs.get("aevum.actor") == "my-agent"
+        assert attrs.get("aevum.event_type") == "ingest.accepted"
+
+    def test_episode_id_emitted_when_present(self):
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event(episode_id="ep-001"))
+        spans = exporter.get_finished_spans()
+        attrs = dict(spans[0].attributes or {})
+        assert attrs.get("aevum.episode_id") == "ep-001"
+
+    def test_episode_id_absent_when_none(self):
+        bridge, exporter = _make_bridge()
+        bridge.on_event(_make_mock_event(episode_id=None))
+        spans = exporter.get_finished_spans()
+        attrs = dict(spans[0].attributes or {})
+        assert "aevum.episode_id" not in attrs
+
+
+# ── Observer registration ─────────────────────────────────────────────────────
+
+class TestObserverRegistration:
+    def test_set_event_observer_registers_with_ledger(self):
+        bridge, _ = _make_bridge()
+        mock_ledger = MagicMock()
+        bridge.set_event_observer(mock_ledger)
+        mock_ledger.add_observer.assert_called_once_with(bridge)
+
+    def test_set_event_observer_warns_when_no_add_observer(self, caplog):
+        import logging
+        bridge, _ = _make_bridge()
+        ledger_without_observer = object()  # no add_observer method
+        with caplog.at_level(logging.WARNING, logger="aevum.otel"):
+            bridge.set_event_observer(ledger_without_observer)
+        assert any("add_observer" in r.message for r in caplog.records)
+
+
+# ── Error resilience ──────────────────────────────────────────────────────────
+
+class TestErrorResilience:
+    def test_on_event_does_not_raise_on_bad_event(self):
+        bridge, _ = _make_bridge()
+        bad_event = MagicMock()
+        bad_event.audit_id.side_effect = RuntimeError("broken")
+        # Should not raise
+        bridge.on_event(bad_event)
+
+
+# ── Latency ───────────────────────────────────────────────────────────────────
+
+class TestLatency:
+    def test_latency_p99_none_when_no_events(self):
+        bridge, _ = _make_bridge()
+        assert bridge.latency_p99_ms() is None
+
+    def test_latency_p99_populated_after_events(self):
+        bridge, _ = _make_bridge()
+        for _ in range(100):
+            bridge.on_event(_make_mock_event())
+        p99 = bridge.latency_p99_ms()
+        assert p99 is not None
+        assert p99 >= 0
+
+    def test_latency_reset(self):
+        bridge, _ = _make_bridge()
+        bridge.on_event(_make_mock_event())
+        bridge.reset_latency_samples()
+        assert bridge.latency_p99_ms() is None
+
+
+# ── Engine integration ────────────────────────────────────────────────────────
+
+class TestEngineIntegration:
+    def test_bridge_receives_events_from_engine(self, monkeypatch):
+        """Install bridge in Engine, verify spans are emitted."""
+        monkeypatch.setenv("AEVUM_DEV", "1")
+        from aevum.core.engine import Engine
+
+        exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(exporter))
+        bridge = AevumOTelBridge(service_name="eng-test", tracer_provider=provider)
+
+        engine = Engine()
+        engine.install_complication(bridge, auto_approve=True)
+
+        engine.ingest(
+            data={"note": "otel test"},
+            provenance={"source_id": "t", "chain_of_custody": ["t"], "classification": 0},
+            purpose="test-otel",
+            subject_id="u1",
+            actor="a1",
+        )
+
+        spans = exporter.get_finished_spans()
+        span_names = [s.name for s in spans]
+        # ingest.accepted span should be present
+        assert any("ingest" in n for n in span_names), f"No ingest span in: {span_names}"
+
+    def test_bridge_p99_latency_under_2ms(self, monkeypatch):
+        """
+        B-14: OTel latency overhead p99 must be < 2ms.
+        Uses in-memory span exporter (zero network overhead) to measure
+        pure bridge overhead.
+        """
+        monkeypatch.setenv("AEVUM_DEV", "1")
+        from aevum.core.engine import Engine
+
+        exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(exporter))
+        bridge = AevumOTelBridge(service_name="bench", tracer_provider=provider)
+
+        engine = Engine()
+        engine.install_complication(bridge, auto_approve=True)
+        bridge.reset_latency_samples()
+
+        for i in range(200):
+            engine.ingest(
+                data={"n": i},
+                provenance={"source_id": "t", "chain_of_custody": ["t"], "classification": 0},
+                purpose="bench",
+                subject_id=f"u{i}",
+                actor="a1",
+            )
+
+        p99 = bridge.latency_p99_ms()
+        assert p99 is not None
+        assert p99 < 2.0, f"p99 latency {p99:.3f}ms exceeds 2ms threshold"