Callgraph Schema Reference

Audience: Signals Guild, analyzer authors, integrators producing or consuming call graphs.

Scope: The stella.callgraph.v1 document schema — fields, enumerations, determinism rules, and migration from legacy formats.

Stella Ops represents every analyzed program as a call graph: nodes for symbols, edges for calls, and entrypoints for the surfaces that invoke them. The stella.callgraph.v1 schema below is the canonical, deterministic format that reachability analysis and risk scoring consume.

Schema Version

Current Version: stella.callgraph.v1

All call graphs should include the schema field set to stella.callgraph.v1. Legacy call graphs without this field are automatically migrated on ingestion.

Document Structure

A CallgraphDocument contains the following top-level fields:

Legacy Fields

These fields are preserved for backward compatibility:

Enumerations

CallgraphLanguage

Supported languages for call graph analysis:

SymbolVisibility

Access visibility levels for symbols:

EdgeKind

Edge classification based on analysis confidence:

EdgeReason

Reason codes explaining why an edge exists (critical for explainability):

EntrypointKind

Types of entrypoints:

EntrypointFramework

Frameworks that expose entrypoints:

EntrypointPhase

Execution phase for entrypoints:

Node Structure

A CallgraphNode represents a symbol (method, function, type) in the call graph:

{
  "id": "n001",
  "nodeId": "n001",
  "name": "GetWeatherForecast",
  "kind": "method",
  "namespace": "SampleApi.Controllers",
  "file": "WeatherForecastController.cs",
  "line": 15,
  "symbolKey": "SampleApi.Controllers.WeatherForecastController::GetWeatherForecast()",
  "artifactKey": "SampleApi.dll",
  "visibility": "Public",
  "isEntrypointCandidate": true,
  "attributes": {
    "returnType": "IEnumerable<WeatherForecast>",
    "httpMethod": "GET",
    "route": "/weatherforecast"
  },
  "flags": 3
}

Node Fields

Symbol Key Format

The symbolKey follows a canonical format:

{Namespace}.{Type}[`Arity][+Nested]::{Method}[`Arity]({ParamTypes})

Examples:

• System.String::Concat(string, string)
• MyApp.Controllers.UserController::GetUser(int)
• System.Collections.Generic.List1::Add(T)`

Edge Structure

A CallgraphEdge represents a call relationship between two symbols:

{
  "sourceId": "n001",
  "targetId": "n002",
  "from": "n001",
  "to": "n002",
  "type": "call",
  "kind": "Static",
  "reason": "DirectCall",
  "weight": 1.0,
  "offset": 42,
  "isResolved": true,
  "provenance": "static-analysis"
}

Edge Fields

Entrypoint Structure

A CallgraphEntrypoint represents a discovered entrypoint:

{
  "nodeId": "n001",
  "kind": "Http",
  "route": "/api/users/{id}",
  "httpMethod": "GET",
  "framework": "AspNetCore",
  "source": "attribute",
  "phase": "Runtime",
  "order": 0
}

Entrypoint Fields

Determinism Requirements

For reproducible analysis, call graphs must be deterministic:

1. Stable Ordering

   • Nodes must be sorted by id (ordinal string comparison)
   • Edges must be sorted by sourceId, then targetId
   • Entrypoints must be sorted by order

2. Enum Serialization

   • All enums serialize as camelCase strings
   • Example: EdgeReason.DirectCall → "directCall"

3. Timestamps

   • All timestamps must be UTC ISO 8601 format
   • Example: 2025-01-15T10:00:00Z

4. Content Hashing

   • The graphHash field should contain a stable content hash
   • Hash algorithm: SHA-256
   • Format: sha256:{hex-digest}

Schema Migration

Legacy call graphs without the schema field are automatically migrated:

1. Schema Field: Set to stella.callgraph.v1
2. Language Parsing: String language converted to CallgraphLanguage enum
3. Visibility Inference: Inferred from symbol key patterns:
   • Contains .Internal. → Internal
   • Contains ._ or < → Private
   • Default → Public
4. Edge Reason Inference: Based on legacy type field:
   • call, direct → DirectCall
   • virtual, callvirt → VirtualCall
   • newobj → NewObj
   • etc.
5. Entrypoint Inference: Built from legacy roots and candidate nodes
6. Symbol Key Generation: Built from namespace and name if missing

Validation Rules

Call graphs are validated against these rules:

1. All node id values must be unique
2. All edge sourceId and targetId must reference existing nodes
3. All entrypoint nodeId must reference existing nodes
4. Edge weight must be between 0.0 and 1.0
5. Artifacts referenced by nodes must exist in the artifacts list

Golden Fixtures

Reference fixtures for testing are located at: tests/reachability/fixtures/callgraph-schema-v1/

Related Documentation

• Reachability Signals — how reachability is computed over these call graphs.
• Unknowns Ranking Algorithm Reference — uses node centrality (betweenness) derived from this graph structure.
• Signals module overview — where callgraph ingestion fits in the reachability plane.
• Schema migration is implemented in src/Signals/StellaOps.Signals/Parsing/CallgraphSchemaMigrator.cs.