Reachability Callgraph Formats (richgraph-v1)

Audience: analyzer and lifter authors emitting static callgraphs for Stella Ops reachability.

Purpose

Normalize static callgraphs across languages so the Signals service can merge them with runtime traces and replay bundles deterministically. richgraph-v1 is the wire format every language lifter emits; this guide covers its core fields, per-language conventions, the CAS layout, and the validation rules Signals enforces on ingestion.

Core fields (per node/edge)

• nodes[].id — canonical SymbolID (language-specific, stable, lowercase where applicable).
• nodes[].kind — e.g., method/function/class/file.
• edges[].sourceId / edges[].targetId — SymbolIDs; edge types include call, import, inherit, reference.
• artifact — CAS paths for source graph files; include sha256, uri, optional generator (analyzer name/version).

Language-specific notes

• JVM: use JVM internal names; include signature for overloads.
• .NET/Roslyn: fully-qualified method token; include assembly and module for cross-assembly edges.
• Go SSA: package path + function; include receiver for methods.
• Node/Deno TS: module path + exported symbol; ES module graph only.
• Rust MIR: crate::module::symbol; monomorphized forms allowed if stable.
• Swift SIL: mangled name; demangled kept in metadata only.
• Shell/binaries: SymbolID = sym:binary:{sha256(file)\0section\0addr\0name\0linkage} via SymbolId.ForBinaryAddressed, include code_id = CodeId.ForBinarySegment(...) and set kind=binary.

CAS layout

• Store graph bundles under reachability_graphs/<hh>/<sha>.tar.zst.
• Bundle SHOULD contain meta.json with analyzer, version, language, component, and entry points (array).
• File order inside tar must be lexicographic to keep hashes stable.

Validation rules

• No duplicate node IDs; edges must reference existing nodes.
• Entry points list must be present (even if empty) for Signals recompute.
• Graph SHA-256 must match tar content; Signals rejects a mismatched SHA.
• Prefer ASCII; non-ASCII UTF-8 paths are allowed but must be Unicode-normalized (NFC).

V1 Schema Reference

The stella.callgraph.v1 schema provides enhanced fields for explainability:

• Edge Reasons: 13 reason codes explaining why edges exist
• Symbol Visibility: Public/Internal/Protected/Private access levels
• Typed Entrypoints: Framework-aware entrypoint detection

See the Callgraph Schema Reference for complete v1 schema documentation.

References

• V1 schema reference — full stella.callgraph.v1 field list.
• Runtime/static union schema — how static graphs merge with runtime facts.
• Reachability Evidence Delivery Guide — where this format fits in the evidence chain.