feat(network): rework below-sync-start backfill as a forward cursor and rename anchor terminology

[p0mvn]

Summary

Replaces the disabled backward checkpoint backfill with a below-sync-start forward backfill: a second forward cursor sweeping genesis → trusted sync start that reuses the forward frontier's code path end to end — checkpoint-bounded finalized ranges with the one-block overlap, root verification via verify_supplied_roots_from_parts against a dedicated backfill history tree (seeded empty at genesis), and confirmed-prefix persistence into the commitment_roots_by_height serving index. A final non-finalized stitch range [sync_start ..= sync_start+1] confirms the sync-start height's own root (authenticated in-span against the trusted hash).

Key mechanics:

• Backfill progress is tracked by its own frontier, not the forward covered set (the stitch deliberately overlaps forward-covered heights); staleness is keyed to the backfill frontier (retire_stale_backfill + in-flight cancellation), so fanout duplicates of committed brackets are dropped instead of looping.
• Backfill commits never move best_header_tip, the sync-exchange frontier (driver skips publish_header_frontier on backfill: true), or body gaps; forward ranges are always assigned first.
• A backfill tree mismatch warns + counts (sync.header.backfill.tree_mismatch) and retries without dispatching the forward tree rebuild.
• Dormant by default behind BELOW_SYNC_START_BACKFILL_ENABLED = false (per-startup backfill_enabled, opted into by tests) until the node wiring consumes backfilled data — the targeted consumer is the VCT §10 roots-index serving backfill.

Also renames the overloaded "anchor" terminology across the header-sync layer (it collided with note-commitment anchors): trusted_sync_start, link_hash, StaleLinkFailures, rebase_*/HeaderRebased, peer-status sync_start_height, metric sync.header.history_tree.reanchor → .rebase. Config keys (anchor_height/anchor_hash) and the zebra-state API keep legacy names at the boundary.

Docs: new design doc docs/design/below-sync-start-backfill.md; verified-commitment-trees.md §6.4/§10/§12/§13/§14 updated.

Motivation

The backward backfill could not verify commitment roots (backward ranges fold onto the previous checkpoint's tree, which the reactor never tracks) and had no consumer, so it was disabled. Genesis is the one tree seed the reactor always knows, so a forward-from-genesis cursor achieves the same goal while reusing a single code path and producing fully header-authenticated roots.

Tests

• cargo fmt --all -- --check — clean
• cargo clippy -p zebra-network -p zebra-state -p zebrad --all-targets — clean
• cargo check --workspace --all-targets — clean
• cargo test -p zebra-network zakura — 709 passed
• cargo test -p zebra-state --lib — 311 passed
• cargo test -p zebrad --lib zakura — 52 passed
• Full cargo test --workspace not run locally (long); relying on CI.

New coverage: default-off regression, bracket scheduling + truncation rejection, checkpoint-end mismatch, root verification against the backfill tree (wrong root → misbehavior), frontier advance + stitch lifecycle without forward-frontier movement, forward-before-backfill ordering, late fanout drop without rebuild, state-side intermediate-anchor/idempotent re-commit, driver-side no-frontier-publish for backfill commits.

AI Disclosure

Implemented with Claude Code (design, implementation, and tests) from an approved plan; reviewed by the author.

[v12-auditor]

Note

Complete: Audit complete. No review-worthy issues remain after automatic triage. One finding was auto-invalidated.

Open the full results here.

Analyzed 30 files, diff 13b08b2...6df96b8.