docs consolidation and others

docs/modules/reach-graph/guides/callgraph-formats.md

@@ -0,0 +1,44 @@
+# 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](../signals/callgraph-formats.md) 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`