WI-143: per-article damage ledger in nzb-core

[thedancingdeveloper]

First code payload of the parity-in-flight initiative (Vogt WI-143, initiative parity-in-flight-damage-ledger-in-memory-par2-streaming-repair). Parent audit: WI-142.

What

A persisted per-article damage ledger in nzb-core — the shared truth the download engine (WI-145/146) and the streaming provider (WI-156+) both consult and update, so a hole learned once is not rediscovered.

• Migration v10: damage_ledger table keyed (scope_id, file_index, segment_number), created empty. No backfill from v9 history.retry_data: that blob (WI-133) is a retry checkpoint, not damage evidence — it has no failure reason, per-server evidence, TTL, or server fingerprint to reconstruct a confirmed miss from. (Convergence decision recorded on WI-133/WI-143.)
• crates/nzb-core/src/damage_ledger.rs: LedgerState (unknown / provisional_missing / confirmed_missing / present / unservable_file), per-server evidence (430 vs transport + timestamp), first_refused_at / confirmed_at / expires_at, server_fingerprint.
• All verdict rules in one function, apply_outcome (from zurg holes.go):
  • a transport failure never creates or refreshes a missing record;
  • a single 430 is provisional, confirming only once every enabled server has refused and ≥1s has passed since the first refusal;
  • a confirmed hole is believed for 24h, then a caller re-probes;
  • a change to the server set (fingerprint) invalidates the record.
• API on Database: ledger_note, ledger_consult, ledger_held_provisionally, ledger_file_gone_ratio, ledger_load_file. Callers translate their own failure taxonomy (nzb-dispatch::ArticleFailureKind) into Outcome (Present / Refused / Transport) — nzb-core does not depend on the dispatcher.

Tests

6 deterministic unit tests (injected clocks, in-memory DB) covering transient 430-then-200, 430 on every server, transport-on-the-last-server (never confirms), TTL-expiry re-probe, fingerprint invalidation, and the file-gone ratio. Full nzb-core suite: 128 passed. cargo fmt --check and cargo clippy -D warnings clean.

Scope notes

• The ledger is a pure nzb-core SQLite/state-machine unit with no NNTP dependency, so it is tested directly with controlled outcomes rather than via mock-nntp-server; end-to-end mock-NNTP coverage lands with WI-151 fixtures and the WI-144/145 wiring.
• Public-surface change is additive only, so the published nzbdav 0.5.7 consumer keeps building.
• The 16 KiB MD5 file-matcher move from nzbdav-pipeline is deferred to WI-144 (its consumer).
• Independent of the WI-168 version-floor PR (WI-168: nzb-* version floor + crate sync tooling and drift gate #139); no version bump here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TpoFnScdkRq7qxQLQZe1we