up

docs/reachability/runtime-facts.md

@@ -0,0 +1,38 @@
+# Runtime Facts (Signals/Zastava) v0.1
+
+## Payload shapes
+- **Structured** (`POST /signals/runtime-facts`):
+  - `subject` (imageDigest | scanId | component+version)
+  - `callgraphId` (required)
+  - `events[]`: `{ symbolId, codeId?, purl?, buildId?, loaderBase?, processId?, processName?, socketAddress?, containerId?, evidenceUri?, hitCount, observedAt?, metadata{} }`
+- **Streaming NDJSON** (`POST /signals/runtime-facts/ndjson`): one JSON object per line with the same fields; supports `Content-Encoding: gzip`; callgraphId provided via query/header metadata.
+
+## Provenance/metadata
+- Signals stamps:
+  - `provenance.source` (defaults to `runtime` unless provided in metadata)
+  - `provenance.ingestedAt` (ISO-8601 UTC)
+  - `provenance.callgraphId`
+- Runtime hits are aggregated per `symbolId` (summing hitCount) before persisting and feeding scoring.
+
+## Validation
+- `symbolId` required; events list must not be empty.
+- `callgraphId` required and must resolve to a stored callgraph/union bundle.
+- Subject must yield a non-empty `subjectKey`.
+- Empty runtime stream is rejected.
+
+## Storage and cache
+- Stored alongside reachability facts in Mongo collection `reachability_facts`.
+- Runtime hits cached in Redis via `reachability_cache:*` entries; invalidated on ingest.
+
+## Interaction with scoring
+- Ingest triggers recompute: runtime hits added to prior facts’ hits, targets set to symbols observed, entryPoints taken from callgraph.
+- Reachability states include runtime evidence on the path; bucket/weight may be `runtime` when hits are present.
+- Unknowns registry stays separate; unknowns count still factors into fact score via pressure penalty.
+
+## Replay alignment
+- Runtime traces packaged under CAS namespace `runtime_traces`; referenced in replay manifest with `namespace` and `analysisId` to link to static graphs.
+
+## Determinism rules
+- Keep NDJSON ordering stable when generating bundles.
+- Use UTC timestamps; avoid environment-dependent metadata values.
+- No external network lookups during ingest.