fix(cache): collapse the double whole-capsule pull into one shared single-flight gate (#1614)

[MichaelTaylor3d]

What changed

Closes DIG-Network/dig_ecosystem#1614.

On a read miss, two independent whole-capsule pulls fired for the same (store, root): Leg A, the §21 backfill-on-miss (maybe_backfill_capsule → gap_fill_generation → cache_fetch_and_cache → sync_module_from, tracked in Node::backfilling), and Leg B, the PR#108 P2P reshare (fetch_resource → spawn_capsule_reshare → CapsuleWarmer::warm, tracked in WarmRegistry). Two in-flight registries blind to each other → two transports, two whole-.dig writes → 2× bandwidth/disk/CPU on the flywheel's core loop. (Integrity was never at risk — both writers write_atomic + verify independently — but the cost was double what the SPEC describes.)

The fix — one shared single-flight acquisition gate keyed (store, root)

Both legs remain; they now claim against one WarmRegistry, so exactly one whole-capsule pull runs per (store, root) at a time. This was chosen over retiring §21 because neither leg subsumes the other: the P2P reshare cannot source on a peerless/stranger network (CapsuleWarmer::warm → Refused(PullFailed) with no holders, and it has no §21 fallback), so §21 (rpc.dig.net, the §5.3 read-ladder fallback) must remain the holder-acquisition path there. A shared gate is also race-free and covers both doubles — the Tier-2 peer-serve one and the verify-fail-fallthrough — where a naive single-site edit would miss the second.

The keys were already byte-identical across all three sites (CapsuleKey::Display == maybe_backfill's format!("{store}:{root}") == WarmRegistry's key), so the collapse is race-free by construction.

• lib.rs — backfilling: Mutex<HashSet<String>> → capsule_acquisition: Arc<WarmRegistry> (+ capsule_acquisition_gate() accessor); all 7 constructor sites updated.
• capsule_store.rs — maybe_backfill_capsule claims the shared gate, moving the guard into the spawned task; the origin / config / p2p_content / held gates are unchanged and still precede the claim (load-bearing for #1576/#1654 — never claim ahead of the gates).
• download.rs / peer.rs — wire_capsule_reshare takes the Arc<WarmRegistry> and the production call site passes the Node's capsule_acquisition_gate(), so both legs share one instance.
• module_reshare.rs — WarmRegistry::claim + WarmClaim raised to pub(crate).
• content_serve.rs untouched — the dedup is internal to the gate; the #1654 land_origin fold and tier ordering are preserved.

The max_concurrent = 4 cap now bounds total concurrent whole-capsule pulls across both transports (a beneficial tightening).

Verification

• New/migrated tests pass: capsule_acquisition_gate_is_a_single_shared_registry, backfill_defers_to_an_in_flight_reshare_on_the_shared_gate, reshare_defers_to_an_in_flight_backfill_on_the_shared_gate, a_warmer_shares_the_exact_registry_arc_it_was_built_with (Arc::ptr_eq), plus the migrated backfill_is_a_noop_without_a_peer_network (the peerless §21-fallback pin), backfill_skips_an_already_held_capsule, and the Local/Peer-origin control pair. The distinct-generation cap now governs both legs transitively (one shared registry).
• cargo fmt --all -- --check → exit 0 · cargo clippy -p dig-node-core --all-targets --all-features -- -D warnings → clean · cargo test -p dig-node-core → all pass except the 9 pre-existing port-binding/dual-stack env tests that fail identically on a clean tree (local-only; green in CI).
• SPEC.md §21.4 / §21.7 / §14.3 cost-model updated (a single read triggers at most one whole-capsule acquisition, and the two legs dedup against each other under one cap); DEVELOPMENT_LOG.md entry added. No SYSTEM.md / docs change (internal node behavior).

Version

fix: (internal bandwidth/cost fix; no public API / wire / RPC / .dig-format change; both legs still exist) → [workspace.package].version 0.74.4 → 0.74.5.

---

Generated by Claude Code