git.stella-ops.org/docs/modules/reach-graph/guides/callgraph-formats.md

Reachability Callgraph Formats (richgraph-v1)

Purpose

Normalize static callgraphs across languages so Signals can merge them with runtime traces and replay bundles deterministically.

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 SHA256 must match tar content; Signals rejects mismatched SHA.
• Only ASCII; UTF-8 paths are allowed but must be 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 Callgraph Schema Reference for complete v1 schema documentation.

References

• V1 Schema Reference: docs/modules/signals/guides/callgraph-formats.md
• Union schema: docs/modules/reach-graph/schemas/runtime-static-union-schema.md
• Delivery guide: docs/modules/reach-graph/guides/DELIVERY_GUIDE.md