# Callgraph schema (stella.callgraph.v1)

Purpose
- Represent static and runtime call graphs for reachability.
- Preserve provenance, entrypoints, and explainable edge reasons.

Top-level fields
- schema: fixed string stella.callgraph.v1.
- nodes: symbol nodes with ids, names, and metadata.
- edges: call edges between nodes.
- entrypoints: entry nodes and routes.
- artifacts: optional artifacts list for mapping nodes to binaries.
- metadata: graph-level info (language, component, version, ingestedAt).
- graphHash: sha256 of canonical content for deduplication.

Core enumerations (examples)
- Language: DotNet, Java, Node, Python, Go, Rust, Binary.
- EdgeKind: static, heuristic, runtime.
- EdgeReason: directCall, virtualCall, reflectionString, dynamicImport, runtimeMinted.
- EntrypointKind: http, grpc, cli, job, event, timer, main.

Node shape (key fields)
- id, name, kind, namespace, file, line.
- symbolKey: canonical signature for the symbol.
- visibility: public, internal, protected, private.
- isEntrypointCandidate: boolean.
- attributes: extra metadata such as http method and route.

Edge shape (key fields)
- sourceId, targetId.
- kind, reason, weight, isResolved.
- candidates for unresolved dynamic dispatch.

Determinism rules
- Sort nodes by id, edges by sourceId then targetId, entrypoints by order.
- Enums serialize as camelCase strings.
- Timestamps use UTC ISO-8601.
- graphHash uses SHA-256 over canonical JSON.

Validation rules
- Node ids are unique.
- Edge endpoints reference existing nodes.
- Entrypoint nodeIds reference existing nodes.
- Edge weights are within 0.0 to 1.0.

Related references
- docs/signals/callgraph-formats.md
- docs/reachability/README.md