up

docs/reachability/callgraph-formats.md

@@ -0,0 +1,34 @@
+# 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`