git.stella-ops.org/docs/reachability/runtime-facts.md

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 PostgreSQL table reachability_facts.
• Runtime hits cached in Valkey 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.