prep docs and service updates

docs/signals/unknowns-registry.md

@@ -0,0 +1,65 @@
+# Unknowns Registry (Signals) — November 2026
+
+This document defines the Unknowns Registry that turns unresolved identities or edges into first-class signals. It replaces the temporary notes from late 2026 advisories.
+
+## 1. Purpose
+
+When scanners or runtime probes cannot decisively map artifacts, symbols, or package identities, the gap is recorded as an **Unknown** instead of being dropped. Policy and scoring can then incorporate “unknowns pressure” to avoid silent false negatives.
+
+## 2. Data model (v0)
+
+```json
+{
+  "unknown_id": "unk:sha256:<type+scope+evidence>",
+  "observed_at": "2025-11-20T00:00:00Z",
+  "provenance": { "source": "Scanner|Signals|SbomService|Vexer", "host": "runner-42", "scan_id": "scan:..." },
+  "scope": { "artifact": { "type": "oci.image", "ref": "registry/app@sha256:..." }, "subpath": "/app/bin/libssl.so.3", "phase": "scan|runtime|build" },
+  "unknown_type": "identity_gap|version_conflict|hash_mismatch|missing_edge|runtime_shadow|policy_undecidable",
+  "evidence": { "raw": "dynsym missing for libssl.so.3", "signals": ["sym:memcpy", "import:SSL_free"] },
+  "transitive": { "depth": 1, "parents": ["pkg:deb/openssl@3.0.2"], "children": [] },
+  "confidence": { "p": 0.42, "method": "rule" },
+  "exposure_hints": { "surface": ["startup"], "runtime_hits": 0 },
+  "status": "open|triaged|suppressed|resolved",
+  "labels": ["reachability:possible", "sbom:incomplete"]
+}
+```
+
+## 3. API (idempotent)
+
+- `POST /unknowns/ingest` — upsert by `unknown_id`; repeat payloads are no-ops.
+- `GET /unknowns?artifact=...&status=open` — list unknowns for a target.
+- `POST /unknowns/{id}/triage` — update `status`/`labels`, attach rationale.
+- `GET /unknowns/metrics` — density by artifact / unknown_type / depth.
+
+All endpoints are additive; no hard deletes. Payloads must include tenant bindings and CAS URIs when evidence is stored externally.
+
+## 4. Producers
+
+- **Scanner**: unresolved symbol → package mapping (stripped binaries), missing build-id, ambiguous purl; log with `unknown_type=identity_gap` or `missing_edge`.
+- **Signals**: runtime hits that cannot map to a graph node or purl; unresolved call edges.
+- **SbomService**: conflicting versions for same path; hash mismatch between SBOM and observed file.
+- **Vexer/Policy**: advisory without trustable provenance (`unknown_type=policy_undecidable`).
+
+## 5. Consumers & scoring
+
+- Signals scoring adds `unknowns_pressure = f(density(depth<=1), runtime_shadow, policy_undecidable)` and feeds it into reachability/risk scores.
+- Policy can block `not_affected` claims when `unknowns_pressure` exceeds thresholds.
+- UI/CLI show unknown chips with reason and depth; operators can triage or suppress.
+
+## 6. Storage & CAS
+
+- Primary store: append-only KV/graph in Mongo (collections `unknowns`, `unknown_metrics`).
+- Evidence blobs: CAS under `cas://unknowns/{sha256}` for large payloads (runtime traces, partial SBOMs).
+- Include analyzer fingerprint + schema version in each record for replay.
+
+## 7. Integration checkpoints
+
+- Add writer hooks in Scanner/Signals once `richgraph-v1` and runtime ingestion surface unmapped items.
+- Extend reachability lattice docs to note `unknowns_pressure` input.
+- Add Grafana panel for unknown density per artifact/namespace.
+
+## 8. Acceptance criteria
+
+- APIs deployed with idempotent behavior and tenant guards.
+- At least two producer paths writing Unknowns (Scanner unresolved symbol; Signals runtime shadow).
+- Metrics endpoint shows density and trend; UI/CLI expose triage status.