dgb: M3 §7b wire DigiShield next-target into HeaderChain ingest gate

validate_and_append now enforces the DigiShield-computed next target on the
VALIDATE_SCRYPT path: the declared Scrypt target must EQUAL the next-target
computed over the Scrypt-only retarget window ending at the current tip
(assembled before the header is appended), the nBits-style consensus rule.

A configured HeaderChain(DigiShieldParams, window) arms the gate; a default-
constructed chain leaves target_timespan 0 so digishield_next_target() returns
the 0 sentinel and the gate is a no-op (existing retarget/work-accounting
tests run unconstrained, unchanged). A rejected header never mutates the chain
(size + cumulative work preserved).

+1 ingest-gate test vector (window 1, deterministic 7/8 next-target): wrong
target REJECTED with chain unchanged, exact target VALIDATED_SCRYPT crediting
work, continuity header bypasses the gate. Added INTO header_chain_test (no new
gtest target -> #143 NOT_BUILT trap avoided). 13/13 PASS, build EXIT=0.

Author: frstrtr

src/impl/dgb/coin/header_chain.hpp

@@ -157,6 +157,17 @@ inline uint64_t digishield_next_target(const RetargetWindow& rw,
 // Append order is oldest..newest; the retarget walk reads nearest-first.
 class HeaderChain {
 public:
+    HeaderChain() = default;
+
+    // Configure the consensus retarget gate: the DigiShield params + the
+    // Scrypt-only window depth validate_and_append enforces declared targets
+    // against. Default-constructed chains leave target_timespan == 0, which
+    // makes digishield_next_target() return 0 and the gate a no-op -- the
+    // retarget-window/work-accounting tests run unconstrained, exactly as
+    // before this slice.
+    HeaderChain(DigiShieldParams ds, std::size_t retarget_window)
+        : m_ds_params(ds), m_retarget_window(retarget_window) {}
+
     // Validate one header and, unless rejected, append it to the chain.
     // Work-neutrality SSOT: cumulative work advances iff header_credits_work()
     // — the SAME predicate scrypt_window_ancestors() consults for the retarget
@@ -171,15 +182,32 @@ class HeaderChain {
             return IngestResult::REJECTED;
 
         case HeaderDisposition::VALIDATE_SCRYPT:
+        {
             // PoW validate path. A zero target is not a validatable Scrypt
             // header (the embedded daemon's full scrypt(header) <= target
             // check lands with the daemon port; the structural guard here is
             // that a malformed target never credits work).
             if (h.target == 0)
                 return IngestResult::REJECTED;
+
+            // Consensus retarget gate: the declared target must equal the
+            // DigiShield next-target computed over the Scrypt-only window
+            // ending at the CURRENT tip (assembled BEFORE h is appended).
+            // expected == 0 means no Scrypt ancestor is in range yet
+            // (genesis/bootstrap) or the gate is unconfigured -- no retarget
+            // constraint is enforceable, so the header passes on its
+            // structural (non-zero) target alone. nBits-style exact match
+            // mirrors Bitcoin/DigiByte consensus: the header carries the
+            // required next-work value, not merely a target it satisfies.
+            const RetargetWindow rw = next_retarget_window(m_retarget_window);
+            const uint64_t expected = digishield_next_target(rw, m_ds_params);
+            if (expected != 0 && h.target != expected)
+                return IngestResult::REJECTED;
+
             m_chain.push_back(h);
             m_cumulative_work += work_from_target(h.target);  // credited
             return IngestResult::VALIDATED_SCRYPT;
+        }
 
         case HeaderDisposition::ACCEPT_BY_CONTINUITY:
         default:
@@ -237,6 +265,8 @@ class HeaderChain {
         return target == 0 ? 0 : (UINT64_MAX / target);
     }
 
+    DigiShieldParams          m_ds_params{};        // retarget gate params
+    std::size_t               m_retarget_window = 0; // Scrypt window depth
     std::vector<HeaderSample> m_chain;          // oldest .. newest
     uint64_t                  m_cumulative_work = 0;
 };

src/impl/dgb/test/header_chain_test.cpp

@@ -199,3 +199,41 @@ TEST(DigiShieldRetarget, ConsumesLiveScryptOnlyWindow)
     ASSERT_TRUE(rw.sufficient);
     EXPECT_EQ(digishield_next_target(rw, DigiShieldParams{225, 0}), 100u);
 }
+
+// ---------------------------------------------------------------------------
+// Ingest-path retarget gate: validate_and_append must demand the declared
+// Scrypt target EQUAL the DigiShield next-target computed over the Scrypt-only
+// window ending at the current tip (nBits-style exact consensus match). A
+// default-constructed chain leaves the gate unconfigured (target_timespan 0 ->
+// expected 0), so every test above runs unconstrained; this one configures it.
+//
+//   window depth 1, nominal 80. Window(1) over a lone Scrypt tip has
+//   actual_timespan 0 (front == back) -> damped = 80 + (0-80)/8 = 70, above the
+//   floor rail 60 -> next target = avg * 70/80 = avg * 7/8, deterministically.
+// ---------------------------------------------------------------------------
+TEST(HeaderChainValidate, IngestGateEnforcesDigiShieldNextTarget)
+{
+    HeaderChain hc(DigiShieldParams{80, 0}, /*retarget_window=*/1);
+
+    // Seed: empty window -> gate no-op, any non-zero target seeds the chain.
+    ASSERT_EQ(hc.validate_and_append({SCRYPT, 1000, 4096}),
+              IngestResult::VALIDATED_SCRYPT);
+
+    // Required next target = 4096 * 7/8 = 3584. A mismatch is consensus-invalid
+    // and must REJECT without mutating the chain (size + work unchanged).
+    const std::size_t size_before = hc.size();
+    const uint64_t    work_before = hc.cumulative_work();
+    EXPECT_EQ(hc.validate_and_append({SCRYPT, 1080, 4096}),
+              IngestResult::REJECTED);
+    EXPECT_EQ(hc.size(),            size_before);
+    EXPECT_EQ(hc.cumulative_work(), work_before);
+
+    // The exact DigiShield target is accepted and credits work.
+    EXPECT_EQ(hc.validate_and_append({SCRYPT, 1080, 3584}),
+              IngestResult::VALIDATED_SCRYPT);
+    EXPECT_GT(hc.cumulative_work(), work_before);
+
+    // Continuity headers bypass the retarget gate (work-neutral, no nBits).
+    EXPECT_EQ(hc.validate_and_append({SHA256D, 1090, 1}),
+              IngestResult::ACCEPTED_CONTINUITY);
+}