refactor(network): make the resident gate the single block-sync memory authority

[p0mvn]

Motivation

Zakura block sync currently has two overlapping memory ceilings with different units and lifecycles: the wire-byte ByteBudget and the resident look-ahead gate. Retained bodies are represented in both, which duplicates accounting and requires an asynchronous shed-and-fund path to preserve floor progress.

This ports valargroup/zebra#415 onto current Zakura main so retained-memory admission has one authority and request pacing remains independent of commit speed.

Refs ZCA-742.

Solution

• Make the resident look-ahead gate the sole authority for retained reorder, applying, and sequencer-input bodies.
• Restrict ByteBudget to outstanding request reservations and release each reservation when its body arrives.
• Replace asynchronous floor shedding with a synchronous, bounded floor-request overdraft.
• Decouple max_inflight_block_bytes from retained-memory configuration and preserve the checkpoint-range floor on the resident budget.
• Update work-queue ledgers, fuzz invariants, configuration documentation, traces, and changelog semantics.

Port notes

The source branch did not apply cleanly because Zakura main has diverged since the original PR:

• Preserved Zakura bootstrap defaults and warnings while replacing the old checkpoint-range request-budget clamp.
• Adapted Zakura's detailed work-return diagnostics from the removed Held ledger state to release-at-receipt semantics.
• Preserved the MSRV-compatible atomic decrement implementation and latest-wins sequencer trace publication.
• Reconciled Zakura's compact changelog with the source PR's operator-facing configuration notice.

The final port is intentionally squashed to one commit and omits unrelated diagnostic/comment churn from the source branch.

Tests

Passed:

• cargo fmt --all -- --check
• markdownlint CHANGELOG.md zakura-network/src/zakura/block_sync/README.md --config .trunk/configs/.markdownlint.yaml
• cargo clippy -p zakura-network --all-targets -- -D warnings
• cargo test -p zakura-network zakura::block_sync — 222 passed
• IDE diagnostics for changed Rust files

Earlier local broad runs were partially blocked on macOS loopback binding and long-running node integration tests. The initial PR head passed the complete Linux CI unit-test shards, network-dependent acceptance tests, Clippy, MSRV, crate builds, and Zakura E2E gate; CI will rerun against this cleaned head.

The source PR also reports three alternating 100K-mainnet A/B runs with no measurable throughput or RSS regression and a deep-chain soak through approximately height 980K.

Specifications & References

• Source implementation and live validation: valargroup/zebra#415

Follow-up Work

• Continue calibrating resident-memory and block-count limits from production traces.

AI Disclosure

• No AI tools were used in this PR
• AI tools were used: Cursor was used to port the source change, reconcile Zakura-specific conflicts, reduce review churn, run verification, and prepare the PR description.

PR Checklist

• The PR title follows conventional commits format: type(scope): description
• The PR follows the contribution guidelines.
• This change was previously discussed and implemented in the source PR linked above.
• The focused solution is tested; local full-suite limitations are disclosed above.
• The documentation and changelog are up to date.

[v12-auditor]

Note

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

Open the full results here.

Finding	Severity	Details
F-98785	🟡 Medium	Capped peer stalls floor A no-progress-capped peer can still be treated as the preferred floor server by other peer routines. try_fill stops issuing any requests for a peer once requests_without_block_progress reaches its cap, but floor_has_preferred_unsaturated_server only considers servability, available slots, and RTprop when deciding whether another peer should defer the floor. An attacker can first serve one body quickly to obtain block progress and a favorable RTprop, then stop serving until it reaches the no-progress cap while remaining connected until the liveness deadline. Honest peers with worse RTprop then defer their floor arm to the capped attacker, and the fallback lane refuses to take the same floor-priority start. The current floor height can remain pending despite honest servable peers being available.

And three more auto-invalidated findings.

Analyzed 17 files, diff 7afa5bb...832870e.

[evan-forbes]

very very minor non blocking comment, otherwise this is super dope!

5 spots still reference the deleted Held state / settle_active_reserved_height / FundFloorReservation — peer_routine.rs:931-934, :1181-1186, :1750, sequencer_task.rs:746-748, guard.rs:125-130. A future fix reading these could re-break the balance.