dgb: rescope to the reachable readvertise path; label broadcast_share pre-wiring

A caller-side reachability trace shows DGB is not symmetric with btc/bch:
main_dgb.cpp binds no create/mint-share fn, so dgb::NodeImpl::broadcast_share
and notify_local_share have zero callers repo-wide -- DGB never mints a local
share today (#884). DGB's live path into send_shares is readvertise_best_share()
(ROOT-2 re-advert on best-change plus a 10s one-shot timer), which re-pushes
PEER-RECEIVED shares and deliberately bypasses the de-dup set.

Verified independently: set_mint_share_fn / set_create_share_fn / broadcast_share
/ notify_local_share have zero occurrences in main_dgb.cpp; the only
set_mint_share_fn binding in the tree is main_dash.cpp:1854 plus dgb's own
work_source_test. readvertise_best_share is called from node.cpp:1767 and 1774.
BTC (main_btc.cpp:1336 after lk.unlock() at :1323) and BCH
(pool_entrypoint.hpp:564 after lk.unlock() at :562) are both live and unchanged.

Changes:

- dgb: extract the readvertise recording rule into readvertise_and_record() and
  wire readvertise_best_share() through it. This is DGB's live reward-critical
  marking discipline: m_last_broadcast_to is what a peer disconnect within 10s
  converts into m_rejected_share_hashes, and the readvertise walk `continue`s
  past rejected hashes permanently. Recording the OFFERED batch would let a
  share the F3 gate merely withheld be blamed for someone else's drop and
  excluded from every future re-advert -- a propagation loss for the whole
  sharechain, since DGB re-advertises peer-received shares.

- dgb: rescope the KATs onto that live path. The gate cases (partition_backable)
  and the new DgbReadvertiseRecording cases drive code production executes; the
  broadcast_and_mark cases are renamed
  DgbBroadcastMarkingPrewired_NotReachedToday so no reader mistakes them for
  live protection. Removes the broadcast_share de-dup-walk KAT, which modelled
  an unreachable function -- the shape of the LTC #873 miss.

- dgb: label NodeImpl::broadcast_share in source as pre-wiring for #884. The F2
  fix stays so the seam is correct when the mint path is bound and so the three
  coins remain symmetric, but it protects nothing at runtime today.

- btc/bch: document the ROOT-2 interaction at readvertise_best(). Marking is now
  a strict subset of what the pre-fix code marked, so the walk breaks later or
  in the same place, never earlier: the re-advert re-pushes a superset of what
  it used to. Monotonically better, strictly better for head shares minted while
  no peer was connected. It does not fully close ROOT-2 here -- shares already
  accepted by another peer stay marked and the walk still breaks, as before.
  That needs the ltc/dgb-style de-dup-bypass readvertise; pre-existing, out of
  scope. No behaviour change in this commit for btc/bch.

Mutation-verified red on the DGB live path: recording the offered batch instead
of what was written reddens WithheldShareIsNeverBlamedForAPeerDrop; dropping the
empty-send skip reddens PeerThatReceivedNothingIsNotRecorded; deleting the gate
reddens 2 DgbBroadcastGate cases.

Author: frstrtr

src/impl/bch/node.cpp

@@ -1053,6 +1053,20 @@ uint256 NodeImpl::advertised_best_share()
     return uint256::ZERO;
 }
 
+// ROOT-2 re-advert. Unlike ltc/dgb (which have a dedicated readvertise that
+// bypasses the de-dup set), this delegates to broadcast_share, so the walk still
+// breaks on the first hash already in m_shared_share_hashes.
+//
+// Interaction with the F2 marking change: marking is now a strict SUBSET of what
+// the pre-fix code marked (only hashes a peer actually accepted). The walk breaks
+// later or in the same place, never earlier, so this re-advert re-pushes a
+// superset of what it used to — monotonically better, no regression. It is
+// strictly better in the case that motivated ROOT-2: head shares minted while no
+// peer was connected are no longer marked, so a peer that handshook during the
+// empty window now receives them. It does NOT fully close ROOT-2 here — head
+// shares already accepted by some OTHER peer stay marked and the walk still
+// breaks, exactly as before. Closing that needs the ltc/dgb-style de-dup-bypass
+// readvertise; pre-existing gap, out of scope for this change.
 void NodeImpl::readvertise_best()
 {
     if (m_peers.empty())

src/impl/btc/node.cpp

@@ -1135,6 +1135,20 @@ uint256 NodeImpl::advertised_best_share()
     return uint256::ZERO;
 }
 
+// ROOT-2 re-advert. Unlike ltc/dgb (which have a dedicated readvertise that
+// bypasses the de-dup set), this delegates to broadcast_share, so the walk still
+// breaks on the first hash already in m_shared_share_hashes.
+//
+// Interaction with the F2 marking change: marking is now a strict SUBSET of what
+// the pre-fix code marked (only hashes a peer actually accepted). The walk breaks
+// later or in the same place, never earlier, so this re-advert re-pushes a
+// superset of what it used to — monotonically better, no regression. It is
+// strictly better in the case that motivated ROOT-2: head shares minted while no
+// peer was connected are no longer marked, so a peer that handshook during the
+// empty window now receives them. It does NOT fully close ROOT-2 here — head
+// shares already accepted by some OTHER peer stay marked and the walk still
+// breaks, exactly as before. Closing that needs the ltc/dgb-style de-dup-bypass
+// readvertise; pre-existing gap, out of scope for this change.
 void NodeImpl::readvertise_best()
 {
     if (m_peers.empty())

src/impl/dgb/known_txs_retention.hpp

@@ -33,6 +33,22 @@
 //     try_to_lock missed, or there were no peers — because the de-dup set then
 //     breaks the walk forever and nothing re-pushes it.
 //
+//   readvertise_and_record() — DGB-ONLY. The marking discipline for the
+//     advertise-only ROOT-2 re-push, which is DGB's LIVE path (see below).
+//
+// DGB REACHABILITY — differs from btc/bch; read this before trusting the file.
+//   main_dgb.cpp binds NO create/mint-share fn, so dgb::NodeImpl::broadcast_share
+//   and notify_local_share have ZERO callers repo-wide: DGB never mints a local
+//   share today (tracked as #884). The live DGB path into send_shares is
+//   readvertise_best_share() (ROOT-2 re-advert, on best-change and on a timer),
+//   which re-pushes PEER-RECEIVED shares and deliberately bypasses the de-dup
+//   set. Therefore, on DGB:
+//     partition_backable()     — LIVE (send_shares, reached via readvertise)
+//     readvertise_and_record() — LIVE (readvertise_best_share)
+//     broadcast_and_mark()     — PRE-WIRED; dead until #884 binds the mint seam.
+//   Anything asserting the DGB gate through a locally-minted share broadcast is
+//   exercising a path production never takes.
+//
 // NOTE (de-dup): the same primitives now exist per-coin (btc/dgb/bch/dash) while
 // the LTC lane hoists all_txs_backable into src/core/. Once both land, these
 // per-coin headers should be collapsed onto that core hoist.
@@ -178,4 +194,38 @@ inline std::size_t broadcast_and_mark(MarkedSet& marked, Peers& peers,
     return actually_sent.size();
 }
 
+// Advertise-only ROOT-2 re-push (readvertise_best_share) — DGB's LIVE marking
+// path. Offers `to_send` to every peer via `send`, which reports what it
+// ACTUALLY wrote, and records that report — never the offered batch — through
+// `record(peer, sent)`. A peer that received nothing gets NO record at all.
+// Returns the number of peers reached.
+//
+// Why the recording rule is reward-critical and not cosmetic: m_last_broadcast_to
+// is what converts a peer disconnect within 10s into m_rejected_share_hashes
+// entries, and the readvertise walk `continue`s past every rejected hash —
+// permanently. Recording the OFFERED batch would let a share the F3 completeness
+// gate merely withheld be blamed for someone else's disconnect, turning a
+// transient, self-healing skip into permanent exclusion from every future
+// re-advert. DGB re-advertises PEER-RECEIVED shares, so that is a propagation
+// loss for the whole sharechain, not only for us.
+template <typename Peers, typename SendFn, typename RecordFn>
+inline std::size_t readvertise_and_record(Peers& peers,
+                                          const std::vector<uint256>& to_send,
+                                          SendFn send,
+                                          RecordFn record)
+{
+    if (to_send.empty())
+        return 0;
+
+    std::size_t peers_reached = 0;
+    for (auto& entry : peers) {
+        const std::vector<uint256> sent = send(entry.second);
+        if (sent.empty())
+            continue;   // nothing written -> nothing a later drop may blame
+        record(entry.second, sent);
+        ++peers_reached;
+    }
+    return peers_reached;
+}
+
 } // namespace dgb

src/impl/dgb/node.cpp

@@ -836,6 +836,12 @@ std::vector<uint256> NodeImpl::send_shares(peer_ptr peer,
     return sent;
 }
 
+// PRE-WIRING — NOT REACHED ON DGB TODAY (#884). main_dgb.cpp binds no
+// create/mint-share fn, so this function and notify_local_share have zero
+// callers repo-wide: DGB never mints a local share. The F2 mark-after-send fix
+// below is applied so the seam is correct on the day #884 binds the mint path,
+// and so btc/dgb/bch stay symmetric — it protects nothing at runtime yet. DGB's
+// LIVE send path is readvertise_best_share() above.
 void NodeImpl::broadcast_share(const uint256& share_hash)
 {
     // try_to_lock per the architectural rule (node.hpp:67) — see freeze
@@ -1111,16 +1117,19 @@ void NodeImpl::readvertise_best_share()
     if (to_send.empty())
         return;
 
+    // Advertise-only path: deliberately ignores the de-dup set, so nothing is
+    // marked here. But record only what was ACTUALLY written — a share the F3
+    // completeness gate withheld must not be blamed for a later peer drop, which
+    // would mark it rejected and make the walk above `continue` past it forever.
+    // This is DGB's LIVE reward-critical marking path; broadcast_share below is
+    // dead until the mint seam is bound (#884).
     auto now = std::chrono::steady_clock::now();
-    for (auto& [nonce, peer] : m_peers) {
-        // Advertise-only path: deliberately ignores the de-dup set, so nothing
-        // is marked here. Still record only what was ACTUALLY written — a
-        // gate-skipped share must not be blamed for a later peer drop (that
-        // would mark it rejected and block every future re-broadcast).
-        std::vector<uint256> sent = send_shares(peer, to_send);
-        if (!sent.empty())
+    readvertise_and_record(
+        m_peers, to_send,
+        [&](peer_ptr& peer) { return send_shares(peer, to_send); },
+        [&](peer_ptr& peer, const std::vector<uint256>& sent) {
             m_last_broadcast_to[peer->addr()] = {sent, now};
-    }
+        });
     LOG_INFO << "[readvertise] re-pushed " << to_send.size()
              << " head share(s) to " << m_peers.size() << " peer(s) (ROOT-2)";
 }