feat(network): verify Zakura header-sync commitment roots before persisting

[p0mvn]

Motivation

This ports valargroup/zebra#458 onto the migrated zakura-core/zakura repository. In the header-sync network layer, Zakura must authenticate peer-supplied note-commitment / auth-data roots against block header commitments before writing anything unvalidated to the database.

A block header commits to the history tree as of its parent, so the root for height H is only confirmed once header H + 1 validates against the tree that includes H. A contiguous delivery [start..=end] therefore confirms roots only for [start..=end - 1]; the tip's root stays unconfirmed and is re-delivered by the next overlapping range. This makes the trust boundary a persisted-state invariant: the commit path accepts only the header-authenticated confirmed prefix (exactly one root shorter than the headers, or an empty vector for checkpoint backfill), so the unconfirmed tip root can never reach disk.

Solution

The change is the upstream PR#458 diff, rebased first onto valargroup/zebra ironwood-main (to resolve the semantic conflicts against the intervening zakura header-store work) and then replayed onto zakura main:

• Verify-before-persist in the header-sync commit path: the store enforces roots.is_empty() || roots.len() + 1 == headers.len(), aligns each present root to its header height, and — on any overlap with a committed body — keeps the verified row (committed roots win).
• One-block overlap forward requests ([X-3999, X], [X, X+3999], …) so each range's tip root is confirmed by the successor header in the next range.
• Startup reconstruction rebuilds the in-memory ZIP-221 history tree by appending durable confirmed roots from the verified body tip up to the highest contiguous frontier, then resumes header sync from frontier + 1.
• Lazy rebuild + tip reanchor when a forward range finds the tree behind a non-Zakura (checkpoint/legacy) commit, plus reorg reanchoring to the verified block tip.
• Root verification, the overlap, and the tree are all bounded to the verified-commitment-trees fast-sync handoff (the last checkpoint); above it, header sync runs plainly.
• Rebuilt the backward/checkpoint header backfill path so it coexists with forward-only sync (currently disabled by default).

Conflict resolution notes (port-specific)

The two-step rebase isolated the semantic conflicts (all in the zakura header-store area that landed on both repos) from the mechanical rename/CI conflicts. Beyond the upstream diff, three integration fixes were needed because the target already contained header-store work authored after PR#458's base:

• commit_header_range writer: kept ironwood's UnlinkedRange linkage check while adopting the PR's optional-tip-root (.get(index)) semantics.
• header_store_coherence harness (ops.rs): now delivers the confirmed prefix (tip root omitted) so it exercises the shape the production commit path enforces.
• block_reorg_drops_conflicting_provisional_roots_before_reconstruction: the conflicting height-1 reorg block now links to genesis (differing by nonce) instead of using a bogus parent hash, so the header-store linkage guard admits the reorg instead of refusing it as a non-linking no-op.

Tests

All automated, on the ported branch against zakura main:

• cargo fmt --all -- --check — clean
• cargo clippy --workspace --all-targets -- -D warnings — clean
• cargo check --workspace --all-targets — clean
• cargo test -p zebra-state --lib — 347 passed (incl. header_store_coherence scenarios + property test, and the reorg/root-drop test)
• cargo test -p zebra-network --lib — 912 passed (108 zakura::header_sync tests incl. the new root-verification, overlap, lazy-rebuild, and duplicate-disconnect cases). One fuzz test (fuzz_reliability_discounts_dropping_carrier) is load-sensitive and passes reliably in isolation (3/3); it is pre-existing flakiness the PR base commit #475 already targeted.
• cargo test -p zebrad --lib commands::start / datadir — 63 + 14 passed
• cargo test -p zebra-chain --lib commitment_aux — 9 passed

Specifications & References

• Upstream PR: feat(network): verify Zakura header-sync commitment roots before persisting valargroup/zebra#458
• Design doc updated in this PR: docs/design/verified-commitment-trees.md

AI Disclosure

• AI tools were used: Claude Code performed the two-step rebase, resolved merge conflicts, made the three port-specific integration fixes, and ran the verification suite. The change itself is the upstream PR authored by the contributor.