fix(mirror): bond-verification budget hardening (#527) + aggregate authentication budget (#481)

[MichaelTaylor3d]

Summary

Closes #527. Closes #481 (its item 1, the last remaining item -- items 2/3 already shipped in #529).

Both tickets, in full: dig-node#527 (all four items) and dig-node#481 item 1.

Both tickets were correctly deferred while bond_verify.rs's chain-verification leg was dead code (peer_declaration hardcoded to NotReadable). #501 (merged as 0a01c671) replaced that stub, and an independent re-audit posted per-item verdicts on both tickets on 2026-09-03 confirming all findings are now LIVE and REACHABLE. This PR fixes them.

What changed

dig-node#527 item 1 — repeat-coin-id ledger bypass (HIGH). ReadAdmission::admit let a REPEAT of an already-seen unproven coin id skip the per-claimant distinct-id cap and cost only the process-wide token bucket. A coin that never declares its claimant returns Unverified, which is deliberately never cached — so one fabricated (peer_id, coin_id) pair, sustained at the bucket's ~1/sec refill, could hold the entire process-wide verification budget at zero forever, silencing every other claimant's bond verification. Fixed with a per-(claimant, coin_id) retry cooldown (UNPROVEN_COIN_RETRY_COOLDOWN = VERDICT_TTL), independent of the distinct-id ledger.

dig-node#527 item 2 — budget consulted after a read, not before (LOW-MEDIUM). current_requirement() (a synchronous file read + JSON parse) was evaluated as an eager function argument to verify_against_chain, which Rust runs before admit() — so a claim the budget was always going to refuse still paid the read. admitted_verdict_for now takes required_collateral: impl FnOnce() -> Option<u64> and only calls it after admit() succeeds.

dig-node#527 item 3 — stale doc (LOW, docs-only). VERIFICATION_BURST's doc still described "two blocking HTTPS reads through the node's ONE shared ChiaQuery client," contradicting the shipped call site, which reads through corroborated_chain_source (peer-corroborated, api.coinset.org first) since #503. Corrected.

dig-node#527 item 4 — floor vacuity below 3 peers (HIGH, structural). The shared DialedPeerSample cache both the sync path (floor 2) and the bond path (floor 3) draw from only checked the SYNC floor for reusability, so a 2-peer sample reported itself "usable" while tally_with_floor(_, 3) can only ever produce Insufficient → Unverified from it — every bond claim in that window paid a token, a ledger slot and a real 2-peer query round for a structurally guaranteed non-answer. Added PeerSample::live_count_hint() (default None, so no other implementor's behaviour changes) — a cheap, non-dialling peek — and a pre-check in verify_against_chain that skips the read when the hint proves the sample cannot meet the caller's floor. Deliberately does not force an extra redraw on a floor miss: that would trade one wasted read for a redial storm against the same thin network on every subsequent claim, which is worse than the defect it fixes (network topology is what it is; a redraw wouldn't change the outcome, only the cost).

dig-node#481 item 1 — aggregate authentication budget (HIGH → the real severity is availability, see the ticket's own decision comment). MAX_AUTHENTICATION_ATTEMPTS (128) bounded one create() call, not the pass, and — as the decision comment on #481 measured — the create loop breaks on first failure, so at ≥128 planted coins a stranger can permanently stop a node from bonding at all, off a one-time ~0.00013 XCH spend. Per the shape already decided on the ticket: added AuthVerdict::{Final,Transient} to authenticate's refusal (four of its five reasons are pure functions of immutable chain data and can never flip for the same coin id; "its creating spend is not on chain" stays Transient and is never cached, since a lagging/reorging source can flip it to Some on a later read — caching it would permanently blacklist a coin the node genuinely owns). Added a process-wide AuthMemo that remembers Final refusals by coin id, pruned each selection to the intersection with that selection's own live pool (len() <= pool.len(), plus a 50,000-entry backstop).

Failure direction of every bound touched

• Item 1's cooldown: fails toward re-asking too rarely, never toward wrongly promoting a bond (a genuine coin re-declares within VERDICT_TTL anyway).
• Item 4's pre-check: fails OPEN on None (nothing drawn yet) into the real read — never reads a hint as a refusal. Deliberately does not add a new redraw trigger, to avoid a redial storm.
• mirror funding: per-PASS authentication budget, the discarded skip count, and the rival FundingObservation #481's memo: only Final (immutable-data) refusals are ever cached; Transient is a hard type-level exclusion (AuthVerdict has no Default, no exhaustive-avoiding escape — every call site names a variant), so a future refusal reason cannot silently inherit "cache forever" by omission. A full memo refuses NEW entries rather than evicting held ones (same anti-amplification shape as bond_verify's own VerdictCache).

SPEC.md

§25's per-claimant ledger clause now states the repeat cooldown; a new clause states the peer-sample floor pre-check and its no-forced-redraw rule.

Evidence

• cargo build -p dig-node-service (+ dig-wallet): clean, exit 0.
• cargo clippy -p dig-node-service -p dig-wallet --lib --tests -- -D warnings: clean, exit 0 (one type_complexity finding fixed via a ClaimantLedger type alias).
• rustfmt --check on every touched file: clean.
• cargo test -p dig-node-service --lib: 810 passed, 0 failed, 0 filtered (full crate, no filter — count checked, not just exit status).
• cargo test -p dig-wallet --lib sage::: 718 passed, 0 failed, 1 ignored (pre-existing), 83 filtered (filter excludes non-sage tests in the crate; nonzero passed confirms the filter matched).
• 4 new regression tests, all passing: a_repeated_unproven_coin_id_stops_costing_a_fresh_read_every_attempt, a_sample_below_the_required_floor_is_recognised_without_a_read, a_finally_refused_coin_is_recalled_and_pruned_with_the_pool, the_memo_bound_refuses_new_entries_rather_than_evicting_held_ones.
• Rebuilt + retested after merging origin/main (picked up fix(peer): count accepted inbound peers in the connected pool #402, test(peer): prove bring-up installs the downstream engines on the real genesis (#240) #533): still 810/810.

Blast radius

dig-node-service::mirror::{bond_verify,funding} (both touched modules already own this logic — no new module). dig-wallet::sage::{peer_reads,peer_reads::dialed,corroborated_source}: added one default trait method (PeerSample::live_count_hint, default None — zero behaviour change for ScriptedTips/NoPeers/ScriptedSample test doubles, confirmed by dig-wallet's full sage:: suite staying green) and two small inherent methods (PeerCorroboratedReads::live_count_hint, CorroboratedChainSource::{required_floor,live_peer_hint}) — no existing signature changed. dig-wallet is a path dependency internal to this repo's own workspace (not a published modules/crates/ crate), so no separate crate version bump applies.

Scope note

This PR closes #527 in full and the LAST remaining item of #481 (items 2/3 shipped in #529). It does not touch #513 (already closed) or anything outside these two tickets.

Co-Authored-By: Claude noreply@anthropic.com