feat: common "snapshotting" code to copy canonical side-table data + index copy

[francesco-stacks]

Description

Add the snapshot module for copying chainstate side-tables (canonical data only) into a squashed output directory. This slice contains the shared copy framework (schema cloning, canonical fork-storage filtering) and the index side-table copy.

Validation and the remaining DBs (SPV, sortition, burnchain, staging blocks) are intentionally left out and will land in follow-up PRs.

Summary

• Add snapshot/common.rs: shared SQL utilities - schema cloning from the attached source, offline write sessions, drop/recreate of user indexes around bulk inserts, and path percent-encoding for ATTACH.
• Add snapshot/fork_storage.rs: MARF-aware __fork_storage copy - walk the squashed trie to collect the canonical leaf value_hash set, then stream-filter src.__fork_storage down to only those rows.
• Add snapshot/index.rs: copy canonical-only rows of the index side-tables, filtered by the squashed MARF's marf_squashed_blocks metadata;
  • signer_stats is additionally filtered by the derived max reward cycle.
  • Schema-only tables (staging_microblocks*, invalidated_microblocks_data, user_supporters) are schema-cloned but not populated.
• Add a test that fails if a future chainstate migration adds a table that isn't classified for the copy, so new tables can't be silently dropped.

Applicable issues

• fixes #

Additional info (benefits, drawbacks, caveats)

Checklist

• Test coverage for new or modified code paths
• For new Clarity features or consensus changes, add property tests (see docs/property-testing.md)
• Changelog fragment(s) or "no changelog" label added (see changelog.d/README.md)
• Required documentation changes (e.g., rpc/openapi.yaml for RPC endpoints, event-dispatcher.md for new events)
• New clarity functions have corresponding PR in clarity-benchmarking repo

[Copilot]

Pull request overview

Introduces a new snapshot module under chainstate::stacks::db that provides shared SQL utilities and a canonical-only copy of the chainstate index side-tables into a squashed output directory. This is the first slice of a series; validation and remaining DBs (SPV, sortition, burnchain, staging blocks) will follow.

Changes:

• Adds shared offline-copy framework in snapshot/common.rs (strict schema cloning from an attached src, offline write session with aggressive pragmas + ATTACH via percent-encoded file: URI, index drop/recreate around bulk inserts, drift-guard helpers).
• Adds MARF-aware snapshot/fork_storage.rs that walks the squashed trie to collect canonical leaf value_hashes and stream-filters src.__fork_storage.
• Adds snapshot/index.rs that copies canonical-only rows of index side-tables (filtered by marf_squashed_blocks), with a custom signer_stats cutoff derived from the canonical tip's reward cycle, and a drift-guard test ensuring future migrations can't silently drop tables.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
stackslib/src/chainstate/stacks/db/mod.rs	Registers the new snapshot submodule.
stackslib/src/chainstate/stacks/db/snapshot/mod.rs	Module wiring; re-exports copy_index_side_tables and IndexSideTableStats.
stackslib/src/chainstate/stacks/db/snapshot/common.rs	Shared SQL helpers: schema cloning, offline write session, index drop/recreate, drift-guard utilities.
stackslib/src/chainstate/stacks/db/snapshot/fork_storage.rs	MARF-aware collection of canonical leaf hashes and filtered __fork_storage copy.
stackslib/src/chainstate/stacks/db/snapshot/index.rs	Canonical-only copy of the chainstate index side-tables plus signer_stats cutoff logic.
stackslib/src/chainstate/stacks/db/snapshot/tests/mod.rs	Tests for the index copy, fork-storage filtering, staging blocks, and drift guard.
changelog.d/marf-snapshot-framework.added	Changelog fragment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.