# Tetragon/eBPF Runtime Instrumentation Bridge (Runtime Witnesses, Build Correlation)

## Module
RuntimeInstrumentation

## Status
VERIFIED

## Description
Runtime trace ingestion and query bridge for Tetragon/eBPF evidence with privacy canonicalization, hot-symbol aggregation, runtime timeline correlation to build artifacts, and disabled-mode null-service fallback.

## Implementation Details
- **Runtime Traces API (ingest + query + score)**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/RuntimeTracesEndpoints.cs` -- `POST /api/v1/findings/{findingId}/runtime/traces` for ingestion and `GET` runtime traces/score retrieval.
- **Runtime Timeline API**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/RuntimeTimelineEndpoints.cs` -- timeline query endpoint with time-window and bucket options.
- **Runtime Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/RuntimeTracesContracts.cs` -- ingest request/response and runtime traces DTOs.
- **Runtime In-Memory Services**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/InMemoryRuntimeInstrumentationServices.cs` -- deterministic observation store, address canonicalization, hot-symbol hit aggregation, and timeline construction.
- **Runtime Null Service (disabled mode)**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/NullRuntimeTracesService.cs` -- accepts ingest requests and returns non-materialized query behavior when runtime instrumentation is disabled.
- **Runtime Wiring Toggle**: `src/Findings/StellaOps.Findings.Ledger.WebService/Program.cs` -- switches between in-memory runtime services and null runtime services via `findings:ledger:runtime:enabled`.
- **Runtime Signal Ingester**: `src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Services/RuntimeSignalIngester.cs` -- containment/blast-radius signal ingestion path used by unknowns analysis.
- **Signal Snapshot Builder**: `src/Findings/StellaOps.Findings.Ledger/Observations/SignalSnapshotBuilder.cs` -- signal snapshot composition for replay/audit workflows.

## E2E Test Plan
- [x] Submit a runtime trace event via the runtime traces endpoint and verify it is persisted and queryable.
- [x] Correlate runtime trace data to build artifact metadata and verify timeline details include component/artifact linkage.
- [x] Verify privacy filtering canonicalizes raw user-space memory addresses in returned symbol/file fields.
- [x] Verify hot-symbol tracking aggregates repeated symbol observations with higher hit counts.
- [x] Verify null runtime traces service handles requests without server errors when runtime instrumentation is disabled.
- [x] Query runtime timeline over a time range and verify chronological ordering and correlation metadata.

## Verification
- `run-001` (2026-02-11): failed behavioral verification, triaged/confirmed missing ingest and runtime service wiring.
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/tier1-build-check.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/tier2-api-check.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/triage.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/confirmation.json`
- `run-002` (2026-02-11): passed after fixes.
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/tier0-source-check.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/tier1-build-check.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/tier2-api-check.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/fix-summary.json`
  - `docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/retest-result.json`