fix: RPC cache prefilling may cause data loss in GC

[hanabi1224]

Summary of changes

To fix an issue that we occasionally see state mismatches after enabling RPC cache prefilling

Changes introduced in this pull request:

Reference issue to close (if applicable)

Closes

Other information and links

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Outside contributions

• I have read and agree to the CONTRIBUTING document.
• I have read and agree to the AI Policy document. I understand that failure to comply with the guidelines will lead to rejection of the pull request.

Summary by CodeRabbit

Release Notes

Refactor

• Consolidated export functionality; users should leverage core export operations directly instead of helper functions
• Refined snapshot export logic with improved internal state computation handling

[coderabbitai]

Walkthrough

The PR removes the export_from_head public helper function from the chain module and refactors its caller to explicitly compute tipset state before calling the lower-level export API, eliminating the settings-store dependency chain.

Changes

Export API Refactor

Layer / File(s)	Summary
Remove export_from_head helper and update snapshot export src/chain/mod.rs, src/db/gc/snapshot.rs	The public async export_from_head helper is deleted from the chain module; its imports are cleaned up. The snapshot GC export_snapshot function is refactored to obtain head_ts directly from the state manager, compute tipset state explicitly (with VMTrace::NotTraced), and call crate::chain::export directly with the computed tipset, removing the dependency on the removed helper.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• ChainSafe/forest#6939: Main PR's refactor of chain export APIs and the ExportOptions structure with pluggable seen tracking is tightly coupled to this change, since both modify the same export entrypoints and call patterns.

Suggested reviewers

• LesnyRumcajs
• sudo-shashank
• akaladarshi

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: RPC cache prefilling may cause data loss in GC' directly addresses the PR's purpose and is substantiated by the changeset: removal of the export_from_head function and refactoring of snapshot GC export logic to use explicit state computation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 hm/fix-gc-with-cache-prefilling

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch hm/fix-gc-with-cache-prefilling

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/db/gc/snapshot.rs (1)

51-52: ⚡ Quick win

Add phase-specific context to the new GC export failures.

These two new ? sites will now surface without identifying whether GC failed during head-state recomputation or during snapshot export.

Proposed change

+use anyhow::Context as _;
use crate::interpreter::VMTrace;
use crate::prelude::*;
@@
self.chain_follower
.state_manager
.compute_tipset_state(
head_ts.shallow_clone(),
crate::state_manager::NO_CALLBACK,
VMTrace::NotTraced,
)
- .await?;+ .await+ .context("failed to recompute head tipset state before GC snapshot export")?;
let _ = crate::chain::export::<Sha256, _>(
db,
&head_ts,
self.recent_state_roots,
file,
@@
- )- .await?;+ )+ .await+ .context("failed to export GC snapshot")?;

As per coding guidelines **/*.rs: Use anyhow::Result<T> for most operations and add context with .context() when errors occur.

Also applies to: 246-267

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/db/gc/snapshot.rs` around lines 51 - 52, The two error-propagation sites
in the GC snapshot export flow need phase-specific context: locate the call that
recomputes the head state (e.g., the call to recompute_head_state or the
function that returns the recomputed head state) and wrap its `?` with
`.context("GC failed while recomputing head-state")`; likewise locate the call
that performs the snapshot export (e.g., export_snapshot/export or the function
that writes the snapshot) and wrap its `?` with `.context("GC failed while
exporting snapshot")`; apply the same `.context(...)` additions to the analogous
calls in the second block flagged (lines ~246-267) so all GC failure sites
report whether the error occurred during head-state recomputation or snapshot
export.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@src/db/gc/snapshot.rs`:
- Around line 51-52: The two error-propagation sites in the GC snapshot export
flow need phase-specific context: locate the call that recomputes the head state
(e.g., the call to recompute_head_state or the function that returns the
recomputed head state) and wrap its `?` with `.context("GC failed while
recomputing head-state")`; likewise locate the call that performs the snapshot
export (e.g., export_snapshot/export or the function that writes the snapshot)
and wrap its `?` with `.context("GC failed while exporting snapshot")`; apply
the same `.context(...)` additions to the analogous calls in the second block
flagged (lines ~246-267) so all GC failure sites report whether the error
occurred during head-state recomputation or snapshot export.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d989c043-60e3-47fb-af00-0cb350faf9e7

📥 Commits

Reviewing files that changed from the base of the PR and between 86d7eaf and 54548af.

📒 Files selected for processing (2)

• src/chain/mod.rs
• src/db/gc/snapshot.rs

[codecov]

Codecov Report

❌ Patch coverage is 0% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.41%. Comparing base (86d7eaf) to head (54548af).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/db/gc/snapshot.rs	0.00%	11 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/chain/mod.rs	85.32% <ø> (+8.46%)	⬆️
src/db/gc/snapshot.rs	0.00% <0.00%> (ø)

... and 7 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 86d7eaf...54548af. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.