Skip to main content

Snapshot Format

Snapshots are immutable analysis artifacts stored in memory and optionally persisted as JSON. They are the handoff point between analysis and query.

Top-Level Fields​

  • id
  • project_root
  • created_at
  • nodes
  • edges
  • project_modules
  • diagnostics

The persisted JSON form only contains stable data needed to reconstruct the snapshot payload.

project_modules is the canonical ownership set for deciding whether module-owned symbols belong to the analyzed project or to external code.

Node and Edge Collections​

Nodes and edges are stored in canonical method/file/module form before query-time projection.

  • nodes carry canonical identity, location, and metadata
  • edges carry canonical identity, confidence, and evidence
  • overload and external-group metadata are already normalized before query time

Runtime-Only Fields​

SnapshotRecord also holds runtime-only indexes that are not part of persisted JSON:

  • runtime_ready
  • allowed_source_files
  • node_by_id
  • adjacency indexes
  • layer graph caches

These are built lazily to keep the persisted format simple while keeping queries fast.

Query-Time Layers​

Snapshots are queried through three layers:

  • method
  • file
  • module

The snapshot itself remains canonical; projection and aggregation happen at query time.

Query responses may add context-specific metadata such as:

  • pagination state
  • reachability depth info
  • node_appearance

Those are not snapshot fields; they are query results derived from snapshots.