]> git.hungrycats.org Git - bees/commitdiff
scan-next: enforce the src once-only rule at plan composition
authorZygo Blaxell <bees@furryterror.org>
Wed, 2 Sep 2026 03:02:45 +0000 (23:02 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sat, 10 Oct 2026 19:00:05 +0000 (15:00 -0400)
Each src block may be referenced at most once across the dedupe edges
of a single dst plan.  Overlapping src references within one plan
stack multiple new refs onto the same physical blocks, exploding
reference counts on extremely common data.  The rule has existed as a
design constraint but had no enforcement: the recent prefer-canonical-
src pivot bug produced plans that violated it freely, and only the
kernel's byte comparison stopped them (as "NO Dedup!" rejections).

Add scan_next_enforce_src_once_only(), called from
scan_next_try_build_dst_plan() on the chosen match list before the
plan tree is composed.  It groups the selected matches' src intervals
by src extent (bytenr when present, node identity for synthetic
extents) and checks each group for pairwise overlap.  On violation it
logs the full match table, bumps the plan_src_overlap counter, and
throws, so a violating plan is rejected before it can reach the
kernel and the callers' existing exception handling logs the trace
and skips the extent.

Every observed violation of the rule has also been a planner bug that
paired a dst with data the src never had, so this doubles as an early
loud failure for any future match-transposition defect.

Assisted-by: Claude-Code:claude-fable-5
Assisted-by: Claude-Code:claude-opus-5-5
src/bees-scan-next.cc

index 228b61858f83c57625198dc0bd29fd8d1b800df4..660f8523cce6ab72da1164cc8e7a1fe8842e51eb 100644 (file)
@@ -1858,6 +1858,61 @@ struct ExtentPlan {
        PlanCost m_total_cost;
 };
 
+/// Enforce the once-only rule at plan composition: each src block may
+/// be referenced at most once across the dedupe edges of a single dst
+/// plan.  Overlapping src references within one plan stack multiple
+/// new refs onto the same physical blocks, which explodes reference
+/// counts on extremely common data; every observed violation has also
+/// been a planner bug pairing a dst with data the src never had
+/// (match transposition onto a non-identical src).  Throws to reject
+/// the plan so it can never reach the kernel; callers log the
+/// exception and skip the extent.
+static void
+scan_next_enforce_src_once_only(
+       const BeesExtent &dst,
+       const vector<ExtentMatch> &matches)
+{
+       BEESTRACE("scan_next_enforce_src_once_only dst " << to_hex(dst.bytenr()));
+       // Key src extents by bytenr when they have one, node identity
+       // otherwise (synthetic extents), then check the src intervals
+       // under each key for pairwise overlap.
+       map<pair<uint64_t, const void *>, vector<pair<uint64_t, uint64_t>>> src_ranges;
+       for (const auto &m : matches) {
+               const auto bytenr = m.m_src.bytenr_opt();
+               const auto key = bytenr
+                       ? make_pair(*bytenr, static_cast<const void *>(nullptr))
+                       : make_pair(uint64_t(0),
+                               static_cast<const void *>(m.m_src.extent_sp().get()));
+               src_ranges[key].emplace_back(m.m_src_begin, m.m_src_end);
+       }
+       for (auto &p : src_ranges) {
+               auto &ranges = p.second;
+               sort(ranges.begin(), ranges.end());
+               for (size_t i = 1; i < ranges.size(); ++i) {
+                       if (ranges[i].first >= ranges[i - 1].second) {
+                               continue;
+                       }
+                       BEESCOUNT(plan_src_overlap);
+                       BEESLOGERR("once-only rule violation: dst "
+                               << to_hex(dst.bytenr()) << " plan references src blocks more than once");
+                       for (const auto &m : matches) {
+                               BEESLOGERR("  match dst [" << to_hex(m.m_dst_begin)
+                                       << ".." << to_hex(m.m_dst_end)
+                                       << ") src [" << to_hex(m.m_src_begin)
+                                       << ".." << to_hex(m.m_src_end)
+                                       << ") src extent " << m.m_src);
+                       }
+                       THROW_ERROR(runtime_error,
+                               "once-only rule violation: dst " << to_hex(dst.bytenr())
+                               << " src ranges [" << to_hex(ranges[i - 1].first)
+                               << ".." << to_hex(ranges[i - 1].second)
+                               << ") and [" << to_hex(ranges[i].first)
+                               << ".." << to_hex(ranges[i].second)
+                               << ") overlap");
+               }
+       }
+}
+
 /// Try to build a DstPlan for one dst extent given candidate sources.
 /// Returns nullopt if the plan is not viable (no matches, cost too
 /// high, or choose_match_plan rejects).
@@ -1883,6 +1938,8 @@ scan_next_try_build_dst_plan(
                [](const auto &lhs, const auto &rhs) {
                        return lhs.m_dst_begin < rhs.m_dst_begin;
                });
+       scan_next_enforce_src_once_only(dst, chosen->m_selected_matches);
+
        const auto plan_tree = scan_next_compose_plan_tree(
                dst, chosen->m_selected_matches);