Struct CodeGraph 

pub struct CodeGraph { /* private fields */ }

Core graph with Arc-wrapped internals for O(1) CoW snapshots.

CodeGraph uses Arc for all internal components, enabling:

• O(1) snapshot creation via Arc cloning
• Copy-on-write semantics via Arc::make_mut
• Memory-efficient sharing between snapshots

Design

The Arc wrapping enables the MVCC pattern:

• Readers see a consistent snapshot at the time they acquired access
• Writers use Arc::make_mut to get exclusive copies only when mutating
• Multiple snapshots can coexist without copying data

Performance

• Snapshot creation: O(5) Arc clones ≈ <1μs
• Read access: Direct Arc dereference, no locking
• Write access: Arc::make_mut clones only if refcount > 1

Phase 2 binding-plane access

Use the two-line snapshot pattern to access BindingPlane:

let snapshot = graph.snapshot();
let plane = snapshot.binding_plane();
let resolution = plane.resolve(&query);

The two-line form is intentional: BindingPlane<'g> borrows from GraphSnapshot and the explicit snapshot handle makes the MVCC lifetime visible at the call site. The full Phase 2 scope/alias/shadow and witness-bearing resolution API is exposed through BindingPlane.

Implementations

impl CodeGraph

pub fn new() -> Self

Creates a new empty CodeGraph.

Example

use sqry_core::graph::unified::concurrent::CodeGraph;

let graph = CodeGraph::new();
assert_eq!(graph.epoch(), 0);

pub fn from_components( nodes: NodeArena, edges: BidirectionalEdgeStore, strings: StringInterner, files: FileRegistry, indices: AuxiliaryIndices, macro_metadata: NodeMetadataStore, ) -> Self

Creates a CodeGraph from existing components.

This is useful when building a graph from external data or reconstructing from serialized state.

pub fn snapshot(&self) -> GraphSnapshot

Creates a cheap snapshot of the graph.

This operation is O(5) Arc clones, which completes in <1μs. The snapshot is isolated from future mutations to the original graph.

Example

use sqry_core::graph::unified::concurrent::CodeGraph;

let graph = CodeGraph::new();
let snapshot = graph.snapshot();
// snapshot is independent of future mutations to graph

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 stamped on the most recently saved or loaded snapshot. Returns 0 for graphs that have not been persisted yet or were loaded from V7 snapshots.

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

Looks up node provenance by NodeId.

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

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

Looks up edge provenance by EdgeId.

Returns None if the EdgeId is out of range, the slot is vacant, or the edge is the invalid sentinel.

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

Returns a borrowed provenance view for a file.

Returns None for invalid/unregistered FileIds.

pub fn scope_arena(&self) -> &ScopeArena

Returns a reference to the scope arena derived during Phase 4e.

The arena is empty on freshly-constructed CodeGraph instances and is populated by calling phase4e_binding::derive_binding_plane.

pub fn alias_table(&self) -> &AliasTable

Returns a reference to the alias table derived during Phase 4e.

The table is empty on freshly-constructed CodeGraph instances and is populated by calling phase4e_binding::derive_binding_plane.

pub fn shadow_table(&self) -> &ShadowTable

Returns a reference to the shadow table derived during Phase 4e.

The table is empty on freshly-constructed CodeGraph instances and is populated by calling phase4e_binding::derive_binding_plane.

pub fn scope_provenance_store(&self) -> &ScopeProvenanceStore

Returns a reference to the scope provenance store derived during Phase 4e.

The store is empty on freshly-constructed CodeGraph instances and is populated by calling phase4e_binding::derive_binding_plane.

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

Looks up scope provenance by ScopeId.

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.

Returns None if no provenance record is registered for that stable id. The reverse index is populated by insert during Phase 4e and must be rebuilt after V9 deserialization.

pub fn file_segments(&self) -> &FileSegmentTable

Returns a reference to the file segment table.

pub fn epoch(&self) -> u64

Returns the current epoch.

pub fn nodes_mut(&mut self) -> &mut NodeArena

Returns a mutable reference to the node arena.

Uses Arc::make_mut for copy-on-write semantics: if other references exist (e.g., snapshots), the data is cloned.

pub fn edges_mut(&mut self) -> &mut BidirectionalEdgeStore

Returns a mutable reference to the bidirectional edge store.

Uses Arc::make_mut for copy-on-write semantics.

pub fn strings_mut(&mut self) -> &mut StringInterner

Returns a mutable reference to the string interner.

Uses Arc::make_mut for copy-on-write semantics.

pub fn files_mut(&mut self) -> &mut FileRegistry

Returns a mutable reference to the file registry.

Uses Arc::make_mut for copy-on-write semantics.

pub fn indices_mut(&mut self) -> &mut AuxiliaryIndices

Returns a mutable reference to the auxiliary indices.

Uses Arc::make_mut for copy-on-write semantics.

pub fn macro_metadata_mut(&mut self) -> &mut NodeMetadataStore

Returns a mutable reference to the macro boundary metadata store.

Uses Arc::make_mut for copy-on-write semantics.

pub fn nodes_and_strings_mut(&mut self) -> (&mut NodeArena, &mut StringInterner)

Returns mutable references to both the node arena and the string interner.

This avoids the borrow-conflict that arises when calling nodes_mut() and strings_mut() separately on &mut self.

pub fn rebuild_indices(&mut self)

Rebuilds auxiliary indices from the current node arena.

This avoids the borrow conflict that arises when calling nodes() and indices_mut() separately on &mut self. Uses disjoint field borrowing to access nodes (shared) and indices (mutable) simultaneously. Internally calls AuxiliaryIndices::build_from_arena which clears existing indices and rebuilds in a single pass without per-element duplicate checking.

As of Task 4 Step 4 Phase 2 this inherent method delegates to the generic [crate::graph::unified::build::parallel_commit::rebuild_indices] free function so the same implementation serves both the full-build (CodeGraph) and incremental-rebuild (RebuildGraph) pipelines. Call sites that hold a concrete CodeGraph can keep using graph.rebuild_indices(); incremental rebuild call sites should use the free function directly.

pub fn bump_epoch(&mut self) -> u64

Increments the epoch counter and returns the new value.

Called automatically by ConcurrentCodeGraph::write().

pub fn set_epoch(&mut self, epoch: u64)

Sets the epoch to a specific value.

This is primarily for testing or reconstruction from serialized state.

pub fn node_count(&self) -> usize

Returns the number of nodes in the graph.

This is a convenience method that delegates to nodes().len().

Example

use sqry_core::graph::unified::concurrent::CodeGraph;

let graph = CodeGraph::new();
assert_eq!(graph.node_count(), 0);

pub fn edge_count(&self) -> usize

Returns the number of edges in the graph (forward direction).

This counts edges in the forward store, including both CSR and delta edges.

Example

use sqry_core::graph::unified::concurrent::CodeGraph;

let graph = CodeGraph::new();
assert_eq!(graph.edge_count(), 0);

pub fn is_empty(&self) -> bool

Returns true if the graph contains no nodes.

This is a convenience method that delegates to nodes().is_empty().

Example

use sqry_core::graph::unified::concurrent::CodeGraph;

let graph = CodeGraph::new();
assert!(graph.is_empty());

pub fn indexed_files(&self) -> impl Iterator<Item = (FileId, &Path)>

Returns an iterator over all indexed file paths.

This is useful for enumerating all files that have been processed and added to the graph.

Example

use sqry_core::graph::unified::concurrent::CodeGraph;

let graph = CodeGraph::new();
for (file_id, path) in graph.indexed_files() {
    println!("File {}: {}", file_id.index(), path.display());
}

pub fn reverse_import_index(&self, file_id: FileId) -> Vec<FileId>

Returns the set of files that import one or more symbols exported by file_id, deduplicated and sorted ascending.

For every EdgeKind::Imports edge whose target node lives in file_id, the source node’s FileId is added to the result. Files are returned sorted by raw index so the result is deterministic across runs. The caller’s own file is never included — an Imports edge whose source and target both live in file_id is treated as a self-import and elided. Edges whose source node is no longer resolvable in the arena (tombstoned) are silently skipped.

This is the file-level view of Pass 4 cross-file Imports edges, used by the incremental rebuild engine to compute reverse-dependency closures: “if file X changes its exports, which files need to be re-linked?”

Complexity

O(|nodes_in_file_id| × avg_incoming_edges_per_node) amortized. Uses AuxiliaryIndices::by_file for O(1)-amortized per-file node lookup (HashMap-backed) and the bidirectional edge store’s reverse adjacency; no full-graph scan. A final O(R log R) sort over the deduplicated importer set (where R is the importer count) is negligible in practice since R ≤ file_count.

pub fn reverse_dependency_index(&self, file_id: FileId) -> Vec<FileId>

Returns the set of files that hold at least one live inter-file edge targeting a node in file_id, deduplicated and sorted ascending.

Unlike reverse_import_index — which filters to EdgeKind::Imports only — this helper treats every cross-file edge as a dependency signal: Calls, References, TypeOf, Inherits, Implements, FfiCall, HttpRequest, GrpcCall, WebAssemblyCall, DbQuery, TableRead, TableWrite, TriggeredBy, MessageQueue, WebSocket, GraphQLOperation, ProcessExec, FileIpc, ProtocolCall, and any future cross-file-capable variant. This is the reverse-dependency surface the incremental rebuild engine (Task 4 Step 4 Phase 3e) needs: when file_id changes, every file whose committed edges point into file_id’s nodes must re-enter the rebuild closure so its cross-file references survive the target-side tombstone-and-reparse cycle.

The caller’s own file is never included — an edge whose source and target both live in file_id is a self-reference and is elided. Edges whose source node is no longer resolvable in the arena (tombstoned) are silently skipped.

When to use this vs reverse_import_index

• reverse_import_index remains the right surface for consumers that specifically need import relationships (export surface analysis, module-dependency graphs, etc.).
• reverse_dependency_index is the right surface for incremental rebuild closure computation. Widening past imports is necessary because call sites, type references, trait implementations, FFI declarations, HTTP clients, and every other cross-file edge kind hold a committed edge into the target file that becomes stale the moment remove_file(target) tombstones its arena nodes. Leaving those files out of the closure leaves the committed edges pointing at the stale (pre-tombstone) node IDs — Phase 4c-prime only rewrites edges on re-parsed files’ PendingEdge sets, never committed edges owned by files outside the reparse scope.

Complexity

O(|nodes_in_file_id| × avg_incoming_edges_per_node) amortized — same bound as reverse_import_index. Uses AuxiliaryIndices::by_file for O(1)-amortized per-file node lookup and the bidirectional edge store’s reverse adjacency; no full-graph scan. Final O(R log R) sort over the deduplicated dependent set is negligible since R ≤ file_count.

Over-widening is expected and acceptable

The closure will include every file that references anything in file_id, not just files whose exports change. In common codebases this widens the reparse set modestly (a 10-file change may expand to 20–30 dependent files in a medium crate). Correctness requires the widening; minimality is a follow-up optimisation if profiling demands it.

pub fn confidence(&self) -> &HashMap<String, ConfidenceMetadata>

Returns the per-language confidence metadata.

This contains analysis confidence information collected during graph build, primarily used by language plugins (e.g., Rust) to track analysis quality.

pub fn merge_confidence(&mut self, language: &str, metadata: ConfidenceMetadata)

Merges confidence metadata for a language.

If confidence already exists for the language, this merges the new metadata (taking the lower confidence level and combining limitations). Otherwise, it inserts the new confidence.

pub fn set_confidence( &mut self, confidence: HashMap<String, ConfidenceMetadata>, )

Sets the confidence metadata map directly.

This is primarily used when loading a graph from serialized state.

pub fn assert_bucket_bijection(&self)

Assert the bijective bucket-membership invariant (A2 §F.1).

Four conditions must hold simultaneously: (a) every NodeId inside any per_file_nodes bucket maps to a live arena slot; (b) every NodeId appears in exactly one bucket (no duplicates across buckets, no duplicates within a bucket); (c) the bucket’s FileId matches the node’s own file field on NodeEntry; (d) when at least one bucket is populated, every live node in the arena is accounted for by some bucket.

Condition (d) is guarded on !seen.is_empty() so an empty-graph (no recorded buckets) publish boundary is vacuously consistent: legacy V7 snapshots, fresh CodeGraph::new() instances, and rebuilds on graphs that predate Gate 0c’s parallel-commit bucketing must not panic. Once any bucket is populated, every live arena slot must appear in a bucket.

Iter-2 B2 (verbatim): this check used to be documented as “vacuous until future per_file_nodes work lands”. Pulling base-plan Step 1 into Gate 0c retires that phrasing — the check is non-vacuous the moment parallel-parse commits nodes, which happens on every real build. The !seen.is_empty() guard now exists solely for the empty-graph corner case, not as a phased- delivery deferral.

The check is a no-op in release builds. Panics with a descriptive message on violation. This is intentional: publish- boundary violations are programmer errors that must surface loudly during CI / test runs.

pub fn assert_no_tombstone_residue_for(&self, dead: &HashSet<NodeId>)

Assert the pre-reuse tombstone-residue invariant (A2 §F.2).

Iterates every publish-visible NodeId-bearing structure on self and panics if any contains a node in dead. Called from RebuildGraph::finalize() step 14 against the set drained at step 8 — exactly one site per the plan’s §F / §H agreement.

No-op when dead is empty or in release builds.

impl CodeGraph

pub fn clone_for_rebuild(&self) -> RebuildGraph

Produce a fresh [RebuildGraph] from this graph’s current committed state, deep-cloning every Arc-wrapped component so the returned value is decoupled from future mutations to self.

The exhaustive destructure inside the @clone_inner arm of sqry_graph_fields! guarantees that every field on CodeGraph is mirrored into the returned [RebuildGraph]. Adding a field to CodeGraph without also adding it to the field list inside sqry_graph_fields! is a hard E0027 compile error on the let CodeGraph { .. } = self; destructure.

When to call this

Only the incremental-rebuild dispatcher (Task 4 Step 4) calls clone_for_rebuild, on the rebuild task’s background tokio context, against an Arc<CodeGraph> freshly obtained via ArcSwap::load_full(). The Arc’s refcount is 1 in the common case, so the underlying deep clones amount to Arc::get_mut- equivalent cost on each component.

Performance budget (A2 §H, line 734)

On a 384k-node / 1.3M-edge reference graph, this call must complete in < 50 ms. The daemon’s rebuild-latency benchmark tracks the budget; warning threshold 50 ms, hard record threshold 200 ms. Exceeding the warning logs but does not fail the rebuild.

Trait Implementations

impl Clone for CodeGraph

fn clone(&self) -> CodeGraph

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CodeGraph

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

Formats the value using the given formatter.

impl Default for CodeGraph

fn default() -> Self

Returns the “default value” for a type.

impl GraphAccess for CodeGraph

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).

impl GraphMemorySize for CodeGraph

fn heap_bytes(&self) -> usize

Estimates the total heap bytes owned by this CodeGraph.

Sums heap usage across every component the graph owns: node arena, bidirectional edge store (forward + reverse CSR + tombstones + delta buffer), string interner, file registry, auxiliary indices, sparse macro/classpath metadata, provenance stores, and the per-language confidence map. Used by the sqryd daemon’s admission controller and workspace retention reaper to enforce memory budgets.