perf(exec): CSR-native adjacency without HashMap expansion (#340)

[DecisionNerd]

Summary

Consume persisted CSR through borrowable CSR-native adjacency views so traversal and analyst paths no longer expand the full base index into HashMap<u64, Vec<_>>.

Rebased onto main after #336+#338.

Changes

• CSR-native Adjacency with O(1) row lookup; directed / undirected / delta overlay without copying the base CSR
• Structural counters proving zero base-CSR expansion on hits
• Docs updated; peak-RSS evidence deferred to M4 scale runs

Testing

cargo test -p graphforge-storage --lib adjacency
cargo test -p graphforge-exec --lib adjacency
cargo clippy -p graphforge-storage -p graphforge-exec -p graphforge-api -- -D warnings

Closes #340

  

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Note

Replace HashMap-backed adjacency with CSR-native row access in graphforge-exec

• Adjacency lookups now use O(1) CSR row slices via a new AdjacencyInner enum (Empty, Map, Csr, Overlay, Undirected) instead of expanding the base CSR into a HashMap on every persisted hit.
• Introduces NeighborRow as a uniform, allocation-free iterator over neighbor entries regardless of backing (CSR, delta overlay, or HashMap).
• Delta chains attach a CsrDeltaOverlay that replaces only touched rows while serving untouched rows directly from the base CsrIndex, avoiding a full CSR copy.
• Undirected adjacency merges out and inbound rows on demand per node using merge_undirected_row rather than materializing a combined map.
• AdjacencyGraph in algorithm_graph.rs is refactored from HashMap<u64, Vec<AlgorithmEdge>> to flat CSR arrays (neighbor_row, neighbor_offsets, neighbor_edges); external method contracts are unchanged.
• Behavioral Change: Adjacency::neighbors now returns a NeighborRow instead of a slice reference; callers must use .iter() or .get().

^{Macroscope summarized 017ec94.}

Summary by CodeRabbit

• Performance

  • Improved graph traversal efficiency, especially for large datasets and persistent indexes.
  • Reduced memory usage by loading graph relationships lazily and avoiding unnecessary expansion.
  • Accelerated neighbor lookups with efficient row-based access.

• Reliability

  • Added safer handling for empty, isolated, out-of-range, and corrupted graph data.
  • Preserved consistent neighbor ordering across directed, undirected, and updated graph views.

• Compatibility

  • Added support for efficiently applying incremental graph updates without rebuilding complete indexes.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 819c27a9-b6a0-4fff-a1ee-4fa5398b1d71

📥 Commits

Reviewing files that changed from the base of the PR and between d0615a6 and 017ec94.

⛔ Files ignored due to path filters (3)

• docs/book/architecture/execution-model.md is excluded by !**/*.md, !**/docs/**
• docs/book/architecture/storage.md is excluded by !**/*.md, !**/docs/**
• docs/reference/scale-limits.md is excluded by !**/*.md, !**/docs/**

📒 Files selected for processing (5)

• crates/graphforge-exec/src/adjacency.rs
• crates/graphforge-exec/src/algorithm_graph.rs
• crates/graphforge-exec/src/lib.rs
• crates/graphforge-storage/src/adjacency.rs
• crates/graphforge-storage/src/adjacency_delta.rs

---

Walkthrough

The change introduces CSR-native adjacency views, bounded delta overlays, lazy undirected row merging, and CSR-backed algorithm graphs. It updates traversal access, public exports, persisted loading, scan fallback, projections, and related tests.

Changes

CSR-native adjacency execution

Layer / File(s)	Summary
Checked CSR row views crates/graphforge-storage/src/adjacency.rs	CsrIndex now provides checked borrowed row access through CsrRow, including iteration and indexed lookup.
Bounded CSR delta overlays crates/graphforge-storage/src/adjacency_delta.rs	CsrDeltaOverlay retains the base CSR and replaces only affected rows after filtering and sorting delta entries.
Lazy adjacency backings crates/graphforge-exec/src/adjacency.rs	Adjacency now supports scan maps, native CSR, overlays, and paired directed CSR views through NeighborRow. Persisted CSR loading avoids base expansion, and undirected rows merge lazily.
CSR-backed algorithm graphs crates/graphforge-exec/src/algorithm_graph.rs, crates/graphforge-exec/src/lib.rs	AdjacencyGraph stores CSR metadata and flat edges. Export, lookup, fixtures, corruption tests, and traversal iteration use the CSR representation.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Execution
  participant Adjacency
  participant CsrIndex
  participant CsrDeltaOverlay
  participant AlgorithmGraph
  Execution->>Adjacency: resolve adjacency backing
  Adjacency->>CsrIndex: read native CSR row
  Adjacency->>CsrDeltaOverlay: read affected overlay row
  CsrDeltaOverlay-->>Adjacency: return base or replaced row
  Adjacency-->>AlgorithmGraph: provide ordered NeighborRow
  AlgorithmGraph-->>Execution: traverse CSR-backed graph

Loading

Possibly related issues

• #343 — The new CSR-native adjacency row views provide the row-level access pattern described for deterministic PageRank updates.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/340-csr-native-execution-c6a4

---

_{Comment @coderabbitai help to get the list of available commands.}