test(zakura): add header-sync reorg suite and reorg handoff docs

[p0mvn]

Motivation

The reorg work is being handed off to another engineer. This PR commits the durable context: the engineering handoff document, the original first-principles design plan, and the header-sync reorg test suite that pins the current behavior of every reorg-relevant path — including the three open gaps behind the 2026-07-07 testnet-4 wedge.

Solution

• REORG_HANDOFF.md — state of the world: what landed (test(state): add zakura header-store coherence harness with corruption repros #490/fix(state): validate linkage in zakura header-store writers #491/fix(state): verify zakura header-store invariants in consensus reads #493/fix(state): audit and optionally repair zakura header store at startup #497/fix(zakura): only advance and gossip NewBlocks that land on the best chain #500), the open stack (fix(state): own zakura header-store mutations with a single suffix-replacement primitive #495/feat(state): sequence branch switches as evaluate, body rollback, then header rewrite #496, plus stale test(zakura): restore the dropped test suite and cover the reorg stack end-to-end #498 and test(state): exercise pruning in the header-store coherence harness #499), the root-caused testnet-4 incident (seed-refusal divergence → UnknownAnchor → misclassification → scheduler assignment leak), where the existing cure lives (zakura/fallback-keeps-zakura-alive @ 9348039 + 6f8b4ad), and the ordered next steps (PRs A–C) with evidence index.
• REORG_PLAN.md — the original design document the shipped pillars implement (previously uncommitted, referenced throughout).
• Reorg test suite — 5 reactor scenario tests (zebra-network/src/zakura/header_sync/tests.rs, === Header-sync reorg suite ===) and 8 driver scenario tests (zebrad/src/commands/start.rs, zakura_header_sync_driver_tests). Tests pin current behavior; comments mark documented gaps so they can be flipped into regression tests as the fix PRs land. Validated on this exact base (e7bdbb4): the tests prove the testnet-4 wedge machinery is still present on this lineage.

Tests

• cargo test -p zebra-network --lib -- zakura:: — 679 passed
• cargo test -p zebrad --lib -- zakura_header_sync_driver_tests — 55 passed
• cargo test -p zebra-state --lib -- header_store_coherence — 44 passed
• cargo fmt --all -- --check and cargo clippy -p zebra-network -p zebrad --all-targets -- -D warnings clean

Specifications & References

• Incident evidence: zakura-testnet-4:/mnt/zakura-testnet-4-data/zakura-traces/ (commit_state.jsonl, header_sync.jsonl) — see REORG_HANDOFF.md §4/§7
• Cure to port: zakura/fallback-keeps-zakura-alive commits 9348039, 6f8b4ad

Follow-up Work

• PR A: port UnknownAnchor → ContextMismatch + store-anchored walk-back onto this lineage
• PR B: scheduler assignment-clearing on InvalidPeerRange commit failures
• PR C: surface outcome.reorged_at to the reactor (equal-height reorg hash staleness)
• Rebase/rework test(zakura): restore the dropped test suite and cover the reorg stack end-to-end #498; land test(state): exercise pruning in the header-store coherence harness #499

AI Disclosure

• Used Claude Code for the test suite implementation, the testnet-4 incident trace analysis, and drafting the handoff documents; all reviewed and validated locally.

[v12-auditor]

Note

Complete: Audit complete. V12 found one issue worth reviewing.

Open the full results here.

Finding	Severity	Details
F-96921	🟠 High	Header range assignments wedge sync Zakura header sync records which peers were assigned a forward GetHeaders range, but peer-failure paths retry that range without clearing the recorded assignment. A malicious peer can advertise a higher tip, receive a forward range, and answer with headers that fail to link; when the node is fully synced, the stale-anchor handler exits because best_header_tip <= verified_block_tip, so the reactor reports InvalidRange and retries without clearing the assignment. The state commit failure path has the same leak for InvalidPeerRange, because handle_header_range_commit_failed only clears assignments for Local failures. After three distinct peers fill HEADER_SYNC_FANOUT for the same range, pop_assignable will not hand that range to any peer, and ensure refuses to enqueue a replacement forward range at the same start height. Misbehavior handling is record-only, so the attacking peers remain connected and fresh honest peers advertising a higher tip cannot restore header-only forward progress; recovery depends on a separate full-block/body path covering the height or on the peers being forgotten.

And one more auto-invalidated finding.

Analyzed two files, diff e7bdbb4...2f8072e.