]> git.hungrycats.org Git - bees/commitdiff
rewrite: tie canonical-src consolidation to a non-zero ref-op-cost scratch
authorZygo Blaxell <bees@furryterror.org>
Sun, 11 Oct 2026 06:57:35 +0000 (02:57 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sun, 11 Oct 2026 06:57:35 +0000 (02:57 -0400)
rewrite.prefer-canonical-src was only safe together with a non-zero
ref-op-cost: unpriced, consolidation piles references onto canonical
extents up to refs-max and re-canonicalizes along a chain.  Yet config
version 1 shipped it enabled with ref-op-cost = 0, the unsafe pairing,
and not the v0.11 behaviour that version 1 is meant to reproduce.

Remove the option.  The equal-reach tie-break and the Plan B pivot now
run exactly when ref-op-cost > 0, so version 1 (ref-op-cost = 0) spreads
references as v0.11 did, and version 2 (ref-op-cost = 53) consolidates as
before.  A config that still sets the key loads unchanged; the key is
ignored.  config-parse keeps the name in its kind table.

Assisted-by: Claude-Code:claude-opus-5-5
docs/config-file.md
docs/running.md
src/bees-config-v1.cc
src/bees-config-v2.cc
src/bees-config.cc
src/bees-plan.h
src/bees-scan-next.cc
src/bees.h

index 5a17bd041e660914a5d15548de89264dd12b23ca..40a9de42819e29b82e89b65b717a539344cf8f81 100644 (file)
@@ -424,6 +424,15 @@ removed.
   single extent, biasing the planner against dedupes that move a large
   reference cluster for little physical gain — a brake on the reference-cluster
   growth that low reference limits can otherwise cause.
+  * A non-zero value also makes the planner consolidate duplicates onto a
+    canonical extent.  When several source extents match a destination equally
+    well, it prefers the source that already has the most references, and it
+    re-centers a set of whole-extent duplicates on the most-referenced one, so
+    references gather in a star topology instead of spreading across arbitrary
+    sources.  `0` spreads them (the historical behavior).  Consolidation is
+    tied to this option because only a non-zero `ref-op-cost` bounds the
+    reference movement it drives: unpriced, references pile onto canonical
+    extents up to `refs-max` and re-canonicalize along a chain.
   * Default: `53`, the same as `ref-cost` (config version 1 and `v0.11`: `0`,
     which disables the term).
   * Accepts a [size value](config-format.md#size-values).
@@ -455,23 +464,6 @@ removed.
   * Default: `1.0`.
   * Accepts a [ratio value](config-format.md#ratio-values) (e.g. `1.0`, `50%`).
 
-* **`prefer-canonical-src`**
-  When several source extents match a destination equally well — they cover the
-  same span, so the choice between them does not change the plan's cost — prefer
-  the source that already has the most references.  This consolidates duplicates
-  onto a single canonical extent (a star topology) rather than spreading them
-  across arbitrary sources; when off, the first equally-good source is used and
-  references spread out (the historical behavior).
-  * Only safe with a non-zero [`ref-op-cost`](#rewrite-section).  Consolidation
-    concentrates references onto a few extents, and `ref-op-cost` is what prices
-    — and therefore bounds — the reference movement that concentration drives.
-    With `ref-op-cost = 0` there is no such bound: references pile onto canonical
-    extents up to `refs-max` and re-canonicalize along a chain, doing far more
-    reference-rewriting work than spreading them would.  Enable this only
-    together with a non-zero `ref-op-cost`.
-  * Default: `yes`.
-  * Accepts a [boolean value](config-format.md#boolean-values).
-
 * **`plan-max-vertices`**
   Boundary-vertex budget for the shortest-path coverage search.  The exact
   search is O(V²) in the boundary count V (the distinct match endpoints of a
index a08498cd6b083c58d812b8abd3157d9778331ce8..8da81d519419fe1a1396614bf1afdbe331a85f7c 100644 (file)
@@ -160,7 +160,7 @@ chosen plan and why it was chosen:
     prices).  `0` when the term is disabled or no destination reference
     shares metadata pages.
   * `pivot` — present when this destination belongs to a re-centered plan: with
-    `rewrite.prefer-canonical-src`, the dedupe star was pivoted onto a
+    a non-zero `rewrite.ref-op-cost`, the dedupe star was pivoted onto a
     higher-reference whole-extent duplicate, so this destination (possibly the
     scanned extent itself) is being deduped onto that canonical rather than the
     scanned extent surviving as the source.
index ff150436a86dbc503957a940073a3930144b2829..1177e538f31caeeb5bae27fc61ca824270879f5f 100644 (file)
@@ -647,7 +647,9 @@ static const char bees_config_v1[] = R"--v1-config--(
 
         # Space-debt weight per reference a plan rewrites (every dedupe/copy
         # FILE_EXTENT_SAME, including whole-extent dedupes ref-cost ignores).
-        # Size value in bytes; 0 disables.  See docs/config-file.md.
+        # Size value in bytes; 0 disables.  Non-zero also prefers the
+        # most-referenced source on equal-length matches.
+        # See docs/config-file.md.
         ref-op-cost = 0
 
         # Expected ratio of subvol metadata sharing between snapshots.
@@ -656,11 +658,6 @@ static const char bees_config_v1[] = R"--v1-config--(
         # 0 disables.  See docs/config-file.md.
         snapshot-sharing = 1.0
 
-        # Prefer the most-referenced source on equal-length dedupe matches, to
-        # consolidate duplicates onto a canonical extent.  Boolean; only safe
-        # with a non-zero ref-op-cost.  See docs/config-file.md.
-        prefer-canonical-src = yes
-
         # Boundary-vertex budget for the coverage search.  Above this V the
         # planner uses a linear greedy cover instead of the O(V^2) exact
         # search.  Integer count, or unlimited to disable the fallback.
index 61f3557d182ca564ae8175e6d80cbbd4481014b6..1ef6509866c84cea6d18b04cc19fa0cd3209a751 100644 (file)
@@ -125,8 +125,8 @@ static const char bees_config_v2[] = R"--v2-config--(
         # Percentage with %, or a size value (e.g. 128K, 1M - 4K).
         free-min = 128K
 
-        # Space-debt weight per reference a plan rewrites.  Prices the
-        # reference movement that prefer-canonical-src drives.
+        # Space-debt weight per reference a plan rewrites.  Non-zero also
+        # consolidates duplicates onto the most-referenced source.
         ref-op-cost = 53
 
 # The [resolve] section controls how bees maps physical addresses back to
index 0eab144f40309716751b9891613464aad677fbd9..40f8793351419a141967add2fb09ca0fd9a6be3d 100644 (file)
@@ -475,7 +475,9 @@ BeesConfig::load_rewrite_policy()
        rv.m_inode_locking       = load("rewrite.inode-locking",       bees_parse_bool);
        rv.m_keep_older          = load("rewrite.keep-older",          bees_parse_bool);
        rv.m_keep_newer          = load("rewrite.keep-newer",          bees_parse_bool);
-       rv.m_prefer_canonical_src = load("rewrite.prefer-canonical-src", bees_parse_bool);
+       // Consolidating onto the most-referenced source is only safe when
+       // ref-op-cost prices the reference movement it drives.
+       rv.m_prefer_canonical_src = rv.m_ref_op_cost > 0;
        {
                BEESTRACE("loading rewrite.read-size");
                rv.m_read_size = get("rewrite.read-size", bees_parse_size);
index 8413954f101a444cd0ae1ac0ffbf8592b466dc3b..6c3c9f84f989ffe39e87af956864ccc8a7c00bcd 100644 (file)
@@ -567,7 +567,7 @@ public:
        std::ostream &print(std::ostream &os) const override;
 
        /// Re-center the dedupe star on the highest-reference whole-extent
-       /// duplicate when prefer-canonical-src is set (see the definition); a no-op
+       /// duplicate when ref-op-cost > 0 (see the definition); a no-op
        /// otherwise.  Runs once after the candidate loop, before selection.
        void finalize() override;
 
index 177339d6fce9ee333f5caf9f7733b85c093b80f5..bbbae799c6e71fe50e0c4fbb5f9a40c9630c2f10 100644 (file)
@@ -1200,7 +1200,7 @@ scan_next_choose_match_plan(const BeesExtent &dst,
                for (const auto &match : group.m_matches) {
                        if (match.size() == 0) continue;
                        // Carry the src ref count as the search's equal-reach tie-break
-                       // (rewrite.prefer-canonical-src): prefer consolidating onto the
+                       // (rewrite.ref-op-cost > 0): prefer consolidating onto the
                        // higher-ref, canonical src.  When disabled leave it 0, which the
                        // search reads as "no preference" (ties resolve as before) and
                        // also skips the refs() lookup.  The lookup is layer-cached; the
@@ -1935,7 +1935,7 @@ struct DstPlan {
        /// paying the snapshot term are greppable; 0 when the term is off or
        /// no dst ref shares metadata pages.
        uint64_t m_sel_snap_extra = 0;
-       /// True when this dst belongs to a re-centered Plan B (prefer-canonical-src
+       /// True when this dst belongs to a re-centered Plan B (ref-op-cost > 0
        /// pivoted the star onto a higher-ref whole-extent duplicate, so this dst —
        /// possibly the former start — is deduped onto that canonical).  Logged as a
        /// "pivot" tag on the "plan:" line so re-centered plans are greppable.
@@ -2628,7 +2628,7 @@ struct BeesStartAsSrcPlan::Impl {
                bool                    m_whole_extent = false;
        };
        std::deque<Entry> m_entries;
-       /// Set by finalize() (prefer-canonical-src) when a whole-extent candidate
+       /// Set by finalize() (ref-op-cost > 0) when a whole-extent candidate
        /// outranks the start on reference count: the plan re-centers the dedupe
        /// star on that candidate, the start joins the destinations, and every
        /// destination dedupes onto this center instead of the start.  Empty means
@@ -2814,7 +2814,7 @@ BeesStartAsSrcPlan::process_candidate(
 void
 BeesStartAsSrcPlan::finalize()
 {
-       // prefer-canonical-src: if a whole-extent-duplicate candidate holds more
+       // ref-op-cost > 0: if a whole-extent-duplicate candidate holds more
        // references than the start, re-center the dedupe star on it.  Centering on
        // the highest-reference member minimizes the references the plan moves
        // (every other member's references move onto the center), and for a set of
@@ -2893,7 +2893,7 @@ BeesStartAsSrcPlan::srcs() const
 {
        // Return the src only when the plan has accepted at least one dst.  The src
        // is the start, unless finalize() re-centered the star on a higher-ref
-       // whole-extent candidate (prefer-canonical-src), in which case the start is
+       // whole-extent candidate (ref-op-cost > 0), in which case the start is
        // a dst and that candidate is the sole src.
        if (m_impl->m_entries.empty()) {
                return {};
@@ -3661,7 +3661,7 @@ scan_next_build_extent_plan(
                }
                const auto &start = pb->start();
 
-               // prefer-canonical-src re-centered the star on a higher-ref whole-extent
+               // ref-op-cost > 0 re-centered the star on a higher-ref whole-extent
                // duplicate (finalize()): the center is the sole src; the start and the
                // remaining candidates are the dsts.  The center is byte-identical to
                // the start over the whole extent, so a dst's match against the start
index 7b828c45fe3d8413e79729cb2aabe87cbf84d020..04537a84efbaa059ad6d0610b37ddd1328252aa4 100644 (file)
@@ -1504,10 +1504,8 @@ struct BeesRewritePolicy {
        /// arbitrary one; off spreads references across sources (the historical
        /// behavior).  Consolidating is only safe when reference moves are priced:
        /// with rewrite.ref-op-cost = 0 it concentrates references onto a few
-       /// extents with nothing to bound the resulting re-canonicalization, so pair
-       /// it with a non-zero ref-op-cost.  Authoritative default in
-       /// bees-config-v2.cc; the C++ initializer (false) is only the pre-load
-       /// value (a bool has no invalid sentinel — see code that sets it).
+       /// extents with nothing to bound the resulting re-canonicalization.  Not
+       /// a config key: derived from ref-op-cost > 0 when the policy is loaded.
        bool m_prefer_canonical_src = false;
        /// Boundary-vertex budget for the shortest-path coverage search.
        /// The exact search is O(V^2) in the boundary count V and holds the