Struct GraphSnapshot 

pub struct GraphSnapshot { /* private fields */ }

Immutable snapshot of a CodeGraph for long-running queries.

GraphSnapshot holds Arc references to the graph components, providing a consistent view that is isolated from concurrent mutations.

Design

Snapshots are created via CodeGraph::snapshot() or ConcurrentCodeGraph::snapshot(). They are:

• Immutable: No mutation methods available
• Isolated: Independent of future graph mutations
• Cheap: Only Arc clones, no data copying
• Self-contained: Can outlive the original graph/lock

Usage

use sqry_core::graph::unified::concurrent::{ConcurrentCodeGraph, GraphSnapshot};

let graph = ConcurrentCodeGraph::new();

// Create snapshot for a long query
let snapshot: GraphSnapshot = graph.snapshot();

// Snapshot can be used independently
let _epoch = snapshot.epoch();

Implementations

impl GraphSnapshot

pub fn nodes(&self) -> &NodeArena

Returns a reference to the node arena.

pub fn edges(&self) -> &BidirectionalEdgeStore

Returns a reference to the bidirectional edge store.

pub fn strings(&self) -> &StringInterner

Returns a reference to the string interner.

pub fn files(&self) -> &FileRegistry

Returns a reference to the file registry.

pub fn indices(&self) -> &AuxiliaryIndices

Returns a reference to the auxiliary indices.

pub fn macro_metadata(&self) -> &NodeMetadataStore

Returns a reference to the macro boundary metadata store.

pub fn fact_epoch(&self) -> u64

Returns the monotonic fact-layer epoch.

pub fn node_provenance(&self, id: NodeId) -> Option<&NodeProvenance>

Looks up node provenance by NodeId.

pub fn edge_provenance(&self, id: EdgeId) -> Option<&EdgeProvenance>

Looks up edge provenance by EdgeId.

pub fn file_provenance(&self, id: FileId) -> Option<FileProvenanceView<'_>>

Returns a borrowed provenance view for a file.

pub fn scope_arena(&self) -> &ScopeArena

Returns a reference to the scope arena at snapshot time.

Participates in MVCC: the snapshot holds an Arc clone of the arena as it existed when snapshot() was called. Subsequent calls to set_scope_arena on the source CodeGraph do not affect this view.

pub fn alias_table(&self) -> &AliasTable

Returns a reference to the alias table at snapshot time.

Participates in MVCC: the snapshot holds an Arc clone of the table as it existed when snapshot() was called. Subsequent calls to set_alias_table on the source CodeGraph do not affect this view.

pub fn shadow_table(&self) -> &ShadowTable

Returns a reference to the shadow table at snapshot time.

Participates in MVCC: the snapshot holds an Arc clone of the table as it existed when snapshot() was called. Subsequent calls to set_shadow_table on the source CodeGraph do not affect this view.

pub fn scope_provenance_store(&self) -> &ScopeProvenanceStore

Returns a reference to the scope provenance store at snapshot time.

Participates in MVCC: the snapshot holds an Arc clone of the store as it existed when snapshot() was called. Subsequent calls to set_scope_provenance_store on the source CodeGraph do not affect this view.

pub fn scope_provenance(&self, id: ScopeId) -> Option<&ScopeProvenance>

Looks up scope provenance by ScopeId at snapshot time.

Returns None if the slot is out of range, vacant, or the stored generation does not match (stale handle).

pub fn scope_by_stable_id(&self, stable: ScopeStableId) -> Option<ScopeId>

Looks up the live ScopeId for a stable scope identity at snapshot time.

Returns None if no provenance record is registered for that stable id.

pub fn file_segments(&self) -> &FileSegmentTable

Returns a reference to the file segment table at snapshot time.

pub fn epoch(&self) -> u64

Returns the epoch at which this snapshot was taken.

This can be compared against the current graph epoch to detect if the graph has changed since the snapshot.

pub fn epoch_matches(&self, other_epoch: u64) -> bool

Returns true if this snapshot’s epoch matches the given epoch.

Use this to validate cursors before continuing pagination.

pub fn binding_plane(&self) -> BindingPlane<'_>

Returns a [BindingPlane] facade borrowing this snapshot’s lifetime.

The facade is the stable Phase 2 public API for scope/alias/shadow queries and witness-bearing resolution. It provides a single entry point (resolve) that returns both a BindingResult and an ordered step trace in a BindingResolution.

MVCC note

BindingPlane<'_> borrows from this snapshot, which is already an MVCC-consistent view of the graph at snapshot time. Callers from CodeGraph or ConcurrentCodeGraph should follow the two-line pattern so the snapshot lifetime is explicit:

// CodeGraph caller:
let snapshot = graph.snapshot();
let plane = snapshot.binding_plane();

// ConcurrentCodeGraph caller:
let read_guard = concurrent.read();
let snapshot = read_guard.snapshot();
let plane = snapshot.binding_plane();

pub fn find_by_pattern(&self, pattern: &str) -> Vec<NodeId>

Finds nodes matching a pattern.

Performs a simple substring match on node names and qualified names. Returns all matching node IDs.

Synthetic suppression (C_SUPPRESS): synthetic placeholder nodes — internal scaffolding the language plugins emit for binding-plane and scope analysis (e.g. the Go plugin’s <field:operand.field> field-access shadows and the <ident>@<offset> per-binding-site Variable nodes from the local-scope resolver) — are filtered out by default. Internal callers that need to reach these nodes (binding plane, scope / alias / shadow analysis) use Self::find_by_pattern_with_options with include_synthetic = true.

Performance

Optimized to iterate over unique strings in the interner (smaller set) rather than all nodes in the arena.

Arguments

• pattern - The pattern to match (substring search)

Returns

A vector of NodeIds for all matching nodes (synthetic placeholders excluded).

pub fn find_by_pattern_with_options( &self, pattern: &str, include_synthetic: bool, ) -> Vec<NodeId>

Finds nodes matching a pattern with explicit control over synthetic placeholder visibility.

include_synthetic = false is the default surface used by every user-facing caller (CLI search, MCP semantic_search / pattern_search / relation_query, etc.). Synthetic placeholders are suppressed via two parallel checks that must agree:

1. The authoritative NodeMetadata::Synthetic bit on the metadata store (crate::graph::unified::storage::metadata::NodeMetadataStore::is_synthetic).
2. The structural name-shape fallback (crate::graph::unified::storage::arena::NodeEntry::is_synthetic_placeholder_name) for V10 snapshots written before the synthetic bit existed and for cross-file unification losers that retained their name but lost their metadata entry.

Either check matching is sufficient to suppress the node. The design lives in docs/development/public-issue-triage/ under the C_SUPPRESS unit; see also the rationale in crate::graph::unified::storage::metadata::NodeMetadata::Synthetic.

include_synthetic = true is internal-only. The binding plane, scope resolver, and rebuild’s coverage gate use this path to reach synthetic nodes for their structural integrity checks. No CLI / MCP surface should ever pass true.

pub fn find_by_exact_name(&self, name: &str) -> Vec<NodeId>

Finds nodes whose interned simple or qualified name equals name byte-for-byte (case-sensitive).

This is the canonical surface for exact-name lookups — shared by the CLI --exact <pattern> shorthand (sqry-cli/src/commands/search.rs::run_regular_search) and the structural query planner’s name: predicate (sqry-db/src/planner/parse.rs, sqry-db/src/planner/execute.rs). Both surfaces are contract-bound (DAG B1_ALIGN) to return the same set against any fixture: the CLI calls this method directly, while the planner uses the same interner + by-name index pair internally when scanning, then applies the same synthetic filter.

Synthetic suppression. Synthetic placeholder nodes (Go-plugin <field:operand.field> shadows and <ident>@<offset> per-binding-site Variables; see Self::find_by_pattern_with_options for the full taxonomy) are excluded via Self::is_node_synthetic. There is no include_synthetic = true variant for the exact-match surface because the synthetic name shapes the structural fallback recognises (<…>, …@<offset>) cannot equal a user-typed name byte-for-byte; the metadata-bit channel is the only realistic leak vector and it is suppressed unconditionally.

Performance

O(1) interner lookup + O(matches) filter. If name is not interned the result is empty without scanning any nodes.

Arguments

• name - The exact name to look up (no glob, no regex).

Returns

Sorted, deduplicated NodeIds for every non-synthetic node whose entry.name or entry.qualified_name equals name. Returns an empty vector when name is not interned (i.e. no node could possibly carry that name).

pub fn is_node_synthetic(&self, node_id: NodeId) -> bool

Returns true if the node should be treated as a synthetic placeholder for user-facing surfaces.

Combines the metadata-store flag and the structural name-shape fallback (see Self::find_by_pattern_with_options for the full rationale). Returns false for missing nodes (an unknown NodeId is not “synthetic” — it is “not present”).

pub fn get_callees(&self, node: NodeId) -> Vec<NodeId>

Gets all callees of a node (functions called by this node).

Queries the forward edge store for all Calls edges from this node.

Arguments

• node - The node ID to query

Returns

A vector of NodeIds representing functions called by this node.

pub fn get_callers(&self, node: NodeId) -> Vec<NodeId>

Gets all callers of a node (functions that call this node).

Queries the reverse edge store for all Calls edges to this node.

Arguments

• node - The node ID to query

Returns

A vector of NodeIds representing functions that call this node.

pub fn iter_nodes(&self) -> impl Iterator<Item = (NodeId, &NodeEntry)>

Iterates over all nodes in the graph.

Returns an iterator yielding (NodeId, &NodeEntry) pairs for all occupied slots in the arena.

Returns

An iterator over (NodeId, &NodeEntry) pairs.

pub fn iter_edges( &self, ) -> impl Iterator<Item = (NodeId, NodeId, EdgeKind)> + '_

Iterates over all edges in the graph.

Returns an iterator yielding (source, target, EdgeKind) tuples for all edges in the forward edge store.

Returns

An iterator over edge tuples.

pub fn get_node(&self, id: NodeId) -> Option<&NodeEntry>

Gets a node entry by ID.

Returns a reference to the NodeEntry if the ID is valid, or None if the ID is invalid or stale.

Arguments

• id - The node ID to look up

Returns

A reference to the NodeEntry, or None if not found.

impl GraphSnapshot

pub fn resolve_symbol(&self, query: &SymbolQuery<'_>) -> SymbolResolutionOutcome

Resolves one symbol with explicit file-aware outcome classification.

pub fn find_symbol_candidates( &self, query: &SymbolQuery<'_>, ) -> SymbolCandidateOutcome

Finds ordered candidates from the first eligible non-empty bucket.

pub fn find_symbol_candidates_with_witness( &self, query: &SymbolQuery<'_>, ) -> SymbolCandidateSearchWitness

Finds ordered candidates from the first eligible non-empty bucket, preserving the bucket that produced them.

pub fn resolve_symbol_with_witness( &self, query: &SymbolQuery<'_>, ) -> SymbolResolutionWitness

Resolve one symbol while preserving witness metadata about the winning candidate bucket and ordered candidates.

pub fn resolve_file_scope( &self, file_scope: &FileScope<'_>, ) -> Result<ResolvedFileScope, FileScopeError>

Resolves an external file scope into an indexed file scope.

Errors

Returns FileScopeError::FileNotIndexed when the requested file scope is not present in the loaded graph indices.

pub fn normalize_symbol_query( &self, query: &SymbolQuery<'_>, file_scope: &ResolvedFileScope, ) -> NormalizedSymbolQuery

Normalizes a raw symbol query into canonical graph form.

pub fn resolve_global_symbol_ambiguity_aware( &self, symbol: &str, file_scope: FileScope<'_>, ) -> Result<NodeId, SymbolResolveError>

Resolve a symbol to one NodeId with a typed ambiguity error.

This is the single, shared resolver used by every CLI, LSP, and MCP surface that must collapse a user-supplied symbol name to one canonical node. It accepts both bare names (NeedTags) and fully-qualified names (main.SelectorSource.NeedTags or main::SelectorSource::NeedTags):

• For a fully-qualified name, the resolver normalizes native delimiters (.) to graph-canonical :: form and looks up the exact-qualified bucket. A unique match is the only acceptable resolution — there is no fuzzy fallback to simple-name candidates even if the qualified form has zero hits, because qualified names are a user contract.
• For a bare name, the resolver tries the exact-simple bucket and resolves the unique match. If two or more nodes share the simple name (e.g. a struct field and a local variable), it returns SymbolResolveError::Ambiguous with the candidate list.

The candidate list is sorted lexicographically by (qualified_name, file_path, start_line, start_column) and capped at AMBIGUOUS_SYMBOL_CANDIDATE_CAP.

Errors

• SymbolResolveError::NotFound — no nodes matched after both raw-form and dot-normalized lookups.
• SymbolResolveError::Ambiguous — two or more nodes matched the requested name in the most-specific eligible bucket.

File scope

file_scope follows the same semantics as SymbolQuery::file_scope:

• FileScope::Any — global resolution. Used by sqry impact, sqry-mcp dependency_impact, etc.
• FileScope::Path / FileScope::FileId — file-scoped resolution. Used by sqry explain and similar single-file-anchored commands.

Trait Implementations

impl Clone for GraphSnapshot

fn clone(&self) -> GraphSnapshot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GraphSnapshot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl GraphAccess for GraphSnapshot

fn nodes(&self) -> &NodeArena

Returns the node arena (read-only).

fn edges(&self) -> &BidirectionalEdgeStore

Returns the bidirectional edge store (read-only).

fn strings(&self) -> &StringInterner

Returns the string interner (read-only).

fn files(&self) -> &FileRegistry

Returns the file registry (read-only).

fn indices(&self) -> &AuxiliaryIndices

Returns the auxiliary indices (read-only).