39 lines
2.0 KiB
Markdown
39 lines
2.0 KiB
Markdown
# 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.
|