save changes

docs/modules/signals/README.md

@@ -49,6 +49,7 @@ Key settings:
 ## Related Documentation
 
 - Architecture: `./architecture.md`
+- Contract: `./contracts/ebpf-micro-witness-determinism-profile.md`
 - Policy Engine: `../policy/`
 - VexLens: `../vex-lens/`
 - High-Level Architecture: `../../ARCHITECTURE_OVERVIEW.md`

docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md

@@ -0,0 +1,124 @@
+# eBPF Micro-Witness Determinism Profile v1.0.0
+
+**Status:** PLANNED  
+**Version:** 1.0.0  
+**Effective:** 2026-02-16  
+**Owner:** Signals Guild + Scanner Guild + Attestor Guild + Evidence Locker Guild  
+**Sprint:** `docs/implplan/SPRINT_20260216_001_Signals_ebpf_micro_witness_determinism_profile.md`
+
+---
+
+## 1. Purpose
+
+This profile defines the minimum deterministic contract for runtime eBPF "micro-witnesses" so replay yields the same symbolized result across distros/toolchains and in offline environments.
+
+---
+
+## 2. Contract Scope
+
+- Runtime collection and BTF selection (`Signals`).
+- Runtime witness payload schema and signing (`Scanner`).
+- DSSE and transparency evidence shape (`Attestor`).
+- Portable storage/export/indexing (`Evidence Locker`).
+
+---
+
+## 3. Runtime Loader Contract (BTF Selection)
+
+### 3.1 Selection order (mandatory)
+1. `/sys/kernel/btf/vmlinux`
+2. configured full-kernel BTF path (for example distro debug package path)
+3. split-BTF selected by `{kernel_release, arch}`
+
+### 3.2 Required emitted metadata
+
+```json
+{
+  "kernel_release": "6.8.0-45-generic",
+  "kernel_arch": "x86_64",
+  "btf": {
+    "source_kind": "kernel|external-vmlinux|split-btf",
+    "source_path": "/sys/kernel/btf/vmlinux",
+    "source_digest": "sha256:...",
+    "selection_reason": "kernel_btf_present"
+  }
+}
+```
+
+`source_path` and `source_digest` are mandatory for deterministic replay.
+
+---
+
+## 4. Deterministic Symbolization Contract
+
+Each runtime witness must carry deterministic symbolization inputs:
+
+```json
+{
+  "symbolization": {
+    "build_id": "gnu-build-id:...",
+    "debug_artifact_uri": "cas://symbols/by-build-id/gnu-build-id:.../artifact.debug",
+    "symbol_table_uri": "cas://symbols/by-build-id/gnu-build-id:.../symtab.json",
+    "symbolizer": {
+      "name": "llvm-symbolizer",
+      "version": "18.1.7",
+      "digest": "sha256:..."
+    },
+    "libc_variant": "glibc|musl",
+    "sysroot_digest": "sha256:..."
+  }
+}
+```
+
+At least one of `debug_artifact_uri` or `symbol_table_uri` must be present.
+
+---
+
+## 5. Witness Packaging Contract
+
+Each micro-witness must be exportable as:
+
+1. `trace.json` (canonical payload)
+2. `trace.dsse.json` (DSSE envelope)
+3. `trace.sigstore.json` (Sigstore bundle with signature/cert/transparency proof)
+
+Offline verification must use only bundle-contained material (no network dependency).
+
+---
+
+## 6. Evidence Locker Index Contract
+
+Evidence Locker must index runtime witness artifacts by:
+
+- `build_id`
+- `kernel_release`
+- `probe_id`
+- `policy_run_id`
+
+These keys are required for deterministic replay lookup and audit search.
+
+---
+
+## 7. Validation Matrix (minimum)
+
+- Kernel matrix: at least 3 supported kernel lines.
+- libc matrix: glibc + musl.
+- Verification modes: online + offline.
+- Determinism check: byte-identical replayed frame output for fixed input evidence.
+
+---
+
+## 8. Confirmed Gaps (2026-02-16 Baseline)
+
+- Hard BTF dependency with no split-BTF fallback metadata contract in collector:
+  - `src/Signals/__Libraries/StellaOps.Signals.Ebpf/Services/RuntimeSignalCollector.cs`
+- Probe load path is simulated and does not record selected BTF source:
+  - `src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/CoreProbeLoader.cs`
+- Runtime witness payload lacks required symbolization tuple fields:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs`
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/RuntimeObservation.cs`
+- Runtime witness generator implementation is missing:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/IRuntimeWitnessGenerator.cs`
+- Sigstore bundle (`trace.sigstore.json`) is not yet standardized in witness storage/export:
+  - `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/013_witness_storage.sql`
+  - `src/EvidenceLocker/__Libraries/StellaOps.EvidenceLocker.Export/Models/BundleManifest.cs`