git.stella-ops.org/docs/reachability/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: when present, use ELF/PE symbol+offset; mark 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).

References

• Union schema: docs/reachability/runtime-static-union-schema.md
• Delivery guide: docs/reachability/DELIVERY_GUIDE.md