Planner redesign

[milroy]

Motivation

Although planner provides O(log n) search complexity for the resource state at a given time and O(log n) search complexity for "the earliest schedulable point where your resource requirement can be satisfied," planner is complex, predisposed to memory mismanagement, and hard to maintain. It provides a large C API that maintains state for the C++ objects it owns, and is unlikely to be used outside Fluxion.

Early testing in 2024 on El Capitan indicated that planner can become a bottleneck on large clusters with a large number of jobs. Unfortunately I don't know where the test data went. A possible cause of the unexpectedly bad scaling is that while the "earliest time" tree indeed performs an O(log n) search, planner must check that the interval starting from the earliest discovered time satisfies the resource request count. That search is linear and involves removing and reinserting nodes in the "earliest time" tree (mt_tree_*):

flux-sched/resource/planner/c/planner_c_interface.cpp

Lines 165 to 179 in 8e1718d

	while ((start_point = ctx->plan->mt_tree_get_mintime (request))) {
	at = start_point->at;
	if (at < on_or_after) {
	ctx->plan->mt_tree_remove (start_point);
	track_points (ctx->plan->get_avail_time_iter (), start_point);
	at = -1;
	} else if (span_ok (ctx, start_point, duration, request)) {
	ctx->plan->mt_tree_remove (start_point);
	track_points (ctx->plan->get_avail_time_iter (), start_point);
	if (static_cast<int64_t> (at + duration) > ctx->plan->get_plan_end ())
	at = -1;
	break;
	}
	}

The overall complexity is bounded below by O(n log n).

Boost.MultiIndex

With the goal of reproducing planner with a simplified code structure, I developed a prototype "planner2" based on Boost.MultiIndex: https://github.com/milroy/flux-sched/tree/planner-v2. After implementing a large number of planner unit tests, I realized that Boost.MultiIndex doesn't support two-dimensional search on composite keys (e.g., a time, resource count pair). The query is multi-dimensional, so there is no way to sort by time and guarantee a total order on resource count (or vice-versa). Put more simply, the current planner provides an augmented red-black tree search, while Boost.MultiIndex does not.

k-d tree

It possible to perform a single, O(log n) search that returns the earliest time at which a given number of resources is available for a desired interval of time. A k-d tree (specifically, 3-D here) provides this capability, while maintaining O(log n) insertion and removal: https://en.wikipedia.org/wiki/K-d_tree. It should be possible to implement the required functionality of planner with a single k-d tree. nanoflann provides a C++ header-only library with a k-d tree: https://github.com/jlblancoc/nanoflann

Boost.icl

Along the course of implementing planner features in "planner2" I discovered that handling searches on open and closed intervals results in iterator edge cases that require complicated gymnastics and conditionals. It would be nice to use an interval library like Boost.icl: https://www.boost.org/doc/libs/latest/libs/icl/doc/html/index.html. Boost.icl could handle interval computations and aggregation, storing a value per interval with the number of free resources, and the max length of time (extending beyond the interval end) for which at least that quantity is available. Then the value can be used together with the interval start time as a 3-D key in the k-d tree.

Handling max intervals to enable a single O(log n) search

Insertion a (time, resource count, max available interval) into Boost.icl would require computing the max length of time for which at least the current request quantity is available. To do so, the insertion must check the next interval to determine if the free count is greater than or equal to the current free count. If so, that max interval is added to the interval length to be inserted. Removals would be more complicated, because multiple earlier intervals could need their max available interval values updated. It would be possible to avoid a linear search for these intervals by embedding start times of max available intervals in each scheduled point time. The additional memory overhead and complexity may be prohibitive.

Proposed work

I propose the following investigation:

1. Profile the current planner to identify scalability limitations, identify bottlenecks, and understand memory usage.
2. Create an experimental implementation of a k-d tree-based planner based on nanoflann to determine if all planner functionality can be provided by a single data structure.
3. Create an experimental scheduled point interval implementation based on Boost.icl and determine if it simplifies the interval computations.

After those items are complete, we can assess whether further work and performance testing is warranted. Note that it may be worthwhile to restructure the current planner if some combination of new data structures can result in a more maintainable planner even without performance or memory-usage improvements.

Let me know what you think!

[milroy]

I had Claude Fable 5 take a look at this discussion and evaluate options. Here are its findings:

This document assesses the difficulty of replacing the Fluxion planner with a simpler, faster,
more maintainable V2; evaluates candidate data structures (augmented BST, k-d tree,
Boost.Geometry R*-tree, Boost.ICL); and proposes a staged migration that removes the C
interface first and swaps the storage backend second.

Executive summary

• Difficulty is moderate, and lower than it appears. The planner is a purely internal,
  uninstalled static library (no install() rule in resource/planner/c/CMakeLists.txt).
  Exactly nine files consume it, all C++, all in-tree. Removing the C interface has zero
  external blast radius. The dominant risk is not code volume but semantic drift on
  edge-case behavior that the DFU traverser depends on.
• The recommended backend is a single balanced tree keyed by time, augmented with
  subtree min/max of available resources plus a lazy range-add tag. Every planner
  operation becomes O(log n) except first-fit search, which becomes output-sensitive,
  mutation-free, and const. One structure replaces two, and the ~3,900-line vendored
  yggdrasil dependency can be dropped.
• k-d trees (including an ICL + k-d composite) and R*-trees are not suitable for the hot
  path. The window-feasibility query is fundamentally one-dimensional-with-aggregate, not
  spatial; multidimensional point/rectangle indexes pay Θ(n^(2/3)) worst-case searches,
  churn heavily under Fluxion's write-heavy workload, and reintroduce the
  multiple-structures-with-sync-protocol architecture that makes the current planner
  brittle. Detailed analysis in §5.3–§5.4.
• The two-stage approach (C removal + hardening, then backend swap) is the right call,
  with one addition: a "stage 0" that captures the semantic contract as tests and rebuilds a
  benchmark baseline (the El Capitan data from early 2024 is no longer available).

1. Current architecture assessment

The complexity of the current planner is concentrated in four architectural decisions, all
correctable without changing observable semantics:

1. The algorithms live in the C shim, not the class. span_ok, avail_at,
   avail_during, avail_resources_during, and span add/remove/reduce are implemented in
   planner_c_interface.cpp:139-222 against the planner class through a ~40-method
   accessor surface (sp_tree_insert, mt_tree_remove, get_span_lookup,
   set_avail_time_iter_set, … planner.hpp:63-94). The class is an anemic state bag — a
   mechanical artifact of the original C-to-C++ port. "Removing the C interface" is really
   "moving the algorithm into the class where it belongs."

2. Queries mutate the structure. avail_at (planner_c_interface.cpp:161-181) removes
   candidate points from the min-time (MT) tree and stashes them in m_avail_time_iter; the
   next planner operation must call restore_track_points to repair the tree. Searches
   therefore cannot be const, are not re-entrant, and correctness depends on every entry
   point remembering to restore. This is the largest single source of brittleness.

3. State is duplicated across two trees. at and remaining live in
   scheduled_point_t and are copied into the MT node on insert
   (mintime_resource_tree.cpp:217-229). Every value change requires the remove/reinsert
   dance in update_mintime_resource_tree (planner_c_interface.cpp:35-43) — a full RB
   delete + insert (with rebalancing rotations) just to update one integer.

4. The MT tree is keyed by the wrong dimension for the query. It is ordered by
   remaining (mintime_resource_tree.cpp:198-201) and augmented with subtree-min of at,
   so it can only answer point-in-time feasibility ("earliest changepoint with
   remaining ≥ R"), never window feasibility. Hence span_ok's linear verification
   walk. Worse, candidates are enumerated one changepoint at a time in time order, so every
   satisfying point inside a blocked run costs a full mintime-query + tree-remove +
   map-insert + eventual-restore cycle. This is the observed O(n log n), with poor constants.

Two costs deserve more attention than #1401 gives them:

• The pruning fast path is linear. planner_avail_resources_during and avail_during
  walk every changepoint in the queried window (planner_c_interface.cpp:183-222) and are
  called from the DFU traverser at essentially every vertex visit
  (dfu_impl.cpp:89,145,196,586,746). On a busy machine every visited vertex pays
  O(changepoints-in-window). This may account for as much of the large-system slowdown as
  avail_time_first.
• Per-vertex memory and copy cost. Every vertex carries schedule.plans,
  idata.x_checker, and per-subsystem idata.subplans
  (sched_data.hpp:32, infra_data.hpp:48-49). Each scheduled_point_t carries two
  intrusive RB node bases with back-pointers (~160 B/changepoint), and each planner carries
  two tree objects, three std::maps, a std::string, and iterator state. Deep copies
  (planner.cpp:412-476) rebuild both trees point-by-point in O(n log n) with pointer
  fix-ups.

2. Latent defects found during review

Worth fixing in stage 1 regardless of any redesign:

Location	Defect
planner_c_interface.cpp:478-487	avail_resources_during returns nullptr on ERANGE (and for at < plan_start via get_state); line 486 dereferences it unconditionally.
planner_c_interface.cpp:183-189	static bool avail_during(...) executes return -1 on ERANGE, which converts to true — an out-of-horizon window reports success (callers currently pre-validate, masking it).
planner_multi_c_interface.cpp:535-543	The all-removed check mspan_sum == (-1 * span_it->second.size()) compares int64_t against size_t arithmetic; it is correct only because two independent unsigned wraps cancel.
planner.cpp:544-572	planner_t constructors swallow bad_alloc into errno and leave plan == nullptr, creating half-constructed objects that most API entry points do not guard against.

3. The semantic contract V2 must preserve (or change deliberately)

These behaviors are load-bearing and must be captured as tests before any backend work:

• Changepoint-only answers, including the plateau edge. planner_avail_time_first
  returns only resource-state changepoints (planner.h:104-112). Sharper than documented:
  avail_at discards candidates < on_or_after (planner_c_interface.cpp:167-171), so a
  request over a free plateau whose last changepoint precedes on_or_after returns ENOENT
  even though avail_during succeeds for the same window (an empty planner queried at
  on_or_after > base_time returns ENOENT). The reservation loop depends on that
  ENOENT to fall through to the satisfiability probe at horizon end (dfu.cpp:191-207).
  Returning max(changepoint, on_or_after) instead is arguably more correct and improves
  utilization — but it changes observable scheduling behavior and must be an explicit,
  separately-tested decision.
• errno taxonomy as control flow. dfu.cpp:204 branches on ENOENT vs. ERANGE.
• Partial-cancel semantics. The -1 span-id sentinels and zero-count agfilter spans in
  planner_multi_reduce_span (planner_multi_c_interface.cpp:440-548) encode real
  RV1exec/partial-release behavior with t5xxx regression coverage.
• update_total clamping and the scheduled/remaining divergence.
  planner::update_total clamps remaining at 0 but leaves scheduled untouched
  (planner.cpp:236-247), so remaining ≠ total − scheduled after a shrinking update.
  scheduled is otherwise used only in ERANGE sanity checks
  (planner_c_interface.cpp:100,116). V2 should decide whether to keep scheduled at all —
  a contract decision, not an implementation detail.
• Span-id monotonicity per planner; equality semantics (planners_equal) used by schema
  tests; copy/assign value semantics used by graph clones
  (sched_data.cpp:31-59, infra_data.cpp:61-101).

4. Scope of the work

Work item	Size	Risk
Fold shim algorithms into planner / planner_multi	~1,400 lines rewritten in place	Low — same logic, same structures
Port consumers to the C++ API	9 files, ~60 call sites (readers ×3, schema ×3, traversers ×3)	Low — all C++; schema copy ctors collapse because planner already has copy/assign/==
Port unit tests	planner_test01/02, 1,691 lines	Low — assert-for-assert parity is the goal
New backend (stage 2)	~400–600 lines for tree + search + registry	The hard 20% — algorithmically well-understood, risk is semantic drift

5. Data structure analysis

5.1 The shape of the problem

The planner maintains a step function A(t) (available resources) over integer time and must
answer, among others:

first-fit: earliest t ≥ T₀ such that min over [t, t+d) of A ≥ R.

The decisive observation: this is a one-dimensional query with a contiguous-range
aggregate (min over a time window), parameterized by two thresholds (d, R). Structures
win or lose on whether their internal decomposition aligns with contiguous time ranges:

• In a balanced BST keyed by time, any window [t, t+d) decomposes into O(log n) canonical
  subtrees, so a min-of-window is answerable from O(log n) precomputed subtree aggregates.
• In a 3-D spatial index, the same window decomposes into Θ(n^(2/3)) cells in the worst
  case (see §5.3). Aggregation cannot rescue a decomposition that does not align with the
  query geometry.

Adding dimensions is a liability here, not an asset.

5.2 Recommended: one time-keyed tree, min/max-augmented, with lazy range-add

Invert the current MT-tree design: key by time, augment each node with subtree
min(remaining) and max(remaining), and add a lazy range-add tag
(segment-tree-style delta propagation). A separate span registry (id → {start, end, count})
replaces the span_t pointer web; changepoint endpoint refcounts survive.

Operation	Today	Augmented tree V2
avail_resources_at (floor lookup)	O(log n)	O(log n)
avail_during / avail_resources_during (window min)	O(k) walk (k = points in window)	O(log n) range-min
add_span / rem_span	O(k) walk + O(k log n) MT remove/reinsert churn	O(log n): split at 2 endpoints + lazy range-add of ∓R
avail_time_first	O(c log n), c = every qualifying changepoint tested, with tree mutation + restore protocol	O((r+1) log n), r = blocked runs crossed; const, stateless
Copy (graph clones)	O(n log n) two-tree rebuild + pointer fix-ups	O(n) structural copy (value semantics)

The first-fit search is a skip-scan: from candidate t, one min-augmented descent finds
the first blocker (remaining < R) in [t, t+d); if none, t is the answer. Otherwise one
max-augmented descent finds the first changepoint past the blocker with remaining ≥ R,
which becomes the next candidate. Every changepoint between the candidate and the blocker is
skipped without being visited — under the current design each of those costs a full
mintime-query/remove/stash cycle. avail_time_next becomes stateless (resume from the
previous answer's successor), which deletes m_avail_time_iter, m_current_request,
restore_track_points, and the embedded iterator protocols outright, and makes all queries
const (enabling read-parallel traversal later).

Honesty about worst cases. No comparison-based dynamic structure answers the
parametric window query (arbitrary d and R) in worst-case O(log n). For fixed R there
is a classical segment-tree augmentation (longest qualifying run per subtree:
prefix/suffix/best) that finds the leftmost window of length ≥ d in O(log n) — but the
qualifying set changes with R, and making it parametric costs O(n log n) space with complex
dynamic maintenance (per-R persistence / merge trees). The output-sensitive skip-scan is the
right engineering point: worst case no worse than today's O(n log n) on adversarial
comb-shaped profiles, near-O(log n) on realistic profiles where a request crosses few busy
peaks, and zero auxiliary structures.

Memory. ~64–80 B per changepoint in one allocation-friendly tree (or ~40 B amortized in
a B-tree variant) versus ~160 B across two intrusive trees today; the planner object shrinks
from two trees + three maps + string + iterators to one container + a few scalars. Multiplied
by three planners per vertex across millions of vertices, this is a material RSS reduction at
El Capitan scale, and O(n) value-semantic copies directly accelerate graph clones.

This design also removes yggdrasil (~3,900 vendored lines) and its trait-specialization and
intrusive-multiple-inheritance machinery — a large fraction of the planner's syntactic
complexity. A dedicated augmented treap or RB tree with lazy range-add is ~400 lines of
well-understood, exhaustively unit-testable code.

5.3 Why not a k-d tree — including the ICL + k-d composite

The strongest version of the proposal (steelman): maintain the availability profile with
Boost.ICL; derive the O(n) maximal free rectangles under the staircase (each rectangle
(t₁, t₂, h) = "h resources continuously free on [t₁, t₂)"; the
largest-rectangle-in-histogram argument bounds their count by n); index the tuples in a 3-D
k-d tree; answer first-fit with a single search. The query even decomposes into two
axis-aligned pieces: (a) an existence query for a rectangle with t₁ ≤ T₀, t₂ ≥ T₀ + d,
h ≥ R (answer: T₀ itself), and (b) a min-t₁ dominance query over rectangles with t₁ > T₀,
t₂ − t₁ ≥ d, h ≥ R. So the geometry can be made box-shaped. It still fails, for five
independent reasons — each individually disqualifying for the hot path:

1. There is no query-independent scalar to index. The searchable quantity per
   changepoint is W(t, R) = the longest window starting at t with min A ≥ R — a
   non-increasing staircase in R, not a number. The options are: one index per distinct R
   (unbounded family); materializing the per-changepoint staircase (Θ(n²) tuples in the
   worst case — precisely the nested profiles that backfilling toward a large reservation
   produces); or the maximal-rectangle decomposition above (O(n) objects, but see flux-sched needs testsuite and CI support #3). This
   is the same disease the current MT tree has: a point-indexed structure answering a
   window predicate needs post-hoc verification or materialized aggregates. k-d trees do
   not fix that; they inherit it.

2. k-d trees do not deliver polylog searches even statically. The worst case for
   orthogonal range / partial-match search in a balanced k-d tree is Θ(n^(1−1/D)) — for the
   3-D formulation, Θ(n^(2/3)) node visits per query (Lee & Wong 1977), against the
   O(log n) hoped for in Planner redesign #1401 and delivered by the augmented BST. The familiar
   "k-d ≈ O(log n)" is an empirical property of NN queries on well-spread, low-correlation
   point clouds. Scheduling rectangles are the opposite: strongly correlated and clustered
   (staircase profiles put all t₁ near "now" with height inversely related to width), which
   degrades axis-aligned pruning toward linear. Guaranteed-polylog 3-sided/dominance queries
   require range trees or priority search trees (O(log n)–O(log² n), O(n log n) space,
   dynamic fractional cascading when mutable) — heavyweight machinery that still sits on the
   broken decomposition of flux-sched needs testsuite and CI support #3.

3. Mutations invalidate indexed objects wholesale. A span add/remove perturbs A over
   [s, e), and every maximal rectangle intersecting that window is potentially reshaped,
   split, or merged — Θ(k) object deletes + reinserts per planner mutation, where k can be
   Θ(n) (one span across a wide free valley). Fluxion mutates on every scheduling action
   (allocate, reserve, cancel; EASY/CONSERVATIVE churn reservations continuously), so the
   composite's steady state is a rebuild-heavy index over a churning object set. The
   augmented profile tree has no such objects: its aggregate is implicit, recomputed on the
   O(log n) spine during each update, which is exactly why one structure suffices.

4. k-d trees are static by construction; nanoflann especially. Balance comes only from
   bulk median builds — there is no rotation-based rebalancing for k-d trees, so the
   correlated, "now"-clustered insertion order of a scheduler degenerates an incrementally
   built tree. nanoflann's dynamic adaptor is a Bentley–Saxe logarithmic forest: queries fan
   out over O(log n) static subtrees, deletion is a lazy mask, and reorganization means full
   rebuilds — Θ(n log n) latency spikes on the allocation critical path. Its query API is
   NN/radius; the constrained min-t₁ query needs a custom branch-and-bound traversal, i.e.,
   writing a bespoke k-d engine anyway — more code than the entire augmented BST, for
   polynomial instead of logarithmic worst case.

5. A composite is two-plus structures and a synchronization protocol — the current
   disease, reproduced. ICL profile + derived rectangle set + spatial index is three
   representations of one mutable truth. The existing planner's brittleness is precisely a
   two-representation sync problem (SP tree + MT tree + in_mt_resource_tree flags +
   stash/restore). V2's central win should be collapsing to one structure; the composite
   triples the invariant surface and directly contradicts the "simpler, more comprehensible"
   goals.

Two honest footnotes. First, the rectangle formulation naturally yields "start at T₀
mid-plateau" answers — silently changing the changepoint-only semantics of §3; any candidate
that "fixes" behavior as a side effect is a hazard, not a feature. Second, if a fast
satisfiability-only probe ("does any (d, R) slot exist at all?") ever becomes valuable
(cf. MATCH_ALLOCATE_W_SATISFIABILITY), it does not need k-d either: the Pareto frontier of
achievable (width, height) pairs is a staircase of O(n) points maintainable in an ordered
map with O(log n) lookup.

Where k-d/rectangle machinery does fit: offline analytics over a static snapshot —
fragmentation studies, utilization visualization, what-if packing — where bulk-load-once,
query-many amortizes beautifully. That belongs in tooling (e.g., a resource-query analysis
mode), never in the allocation path.

5.4 Why not Boost.Geometry R*-tree

The R*-tree shares objections #1, #3, and #5 wholesale (it would index the same rectangle
decomposition), and replaces #2/#4 with its own versions:

• Query shape. "Minimize t₁ subject to h ≥ R and usable width ≥ d" is not a native
  spatial predicate; it becomes best-first search with bounding-box pruning — no worst-case
  bound, and pruning quality depends on tree health.
• Update profile. bgi::rtree is at its best bulk-loaded (packing algorithm) and
  mostly static. Under sustained insert/remove churn, overlap grows and forced-reinsertion
  heuristics fire; there are no rebalancing guarantees comparable to an RB tree.
• Comprehensibility. R* split/reinsertion heuristics are the opposite of the stated
  simplicity goal.

Same verdict as k-d: legitimate for offline spatial analytics, wrong for the planner core.

5.5 Boost.ICL: adopt as the oracle, not the engine

icl::split_interval_map (the split_ variant preserves interval boundaries — important
for changepoint semantics) is nearly a drop-in reference implementation of the profile
arithmetic: span add/remove become interval +=/-= with automatic splitting. It is
std::map-backed with no aggregate augmentation, so window queries are linear scans — not the
performance answer. Its role: differential-testing oracle. Fuzz V2 with random operation
sequences and compare full profiles and query answers against the ICL model (and against the
stage-1 planner). This converts the scariest risk — silent semantic drift — into a
mechanical check.

5.6 planner_multi: galloping intersection

Today planner_multi_avail_time_first enumerates candidate times from planner[0] and
re-verifies every other resource per candidate (planner_multi_c_interface.cpp:240-261).
With per-resource skip-scans, coordinate instead: t ← max over resources of
next-feasible-start(t); repeat until fixpoint. Each round advances t past at least one
resource's blocked run. Same worst case, much better typical case, and no privileged
resource[0].

6. Staged plan

Stage 0 — contract + measurement (cheap; matches #1401's own step 1):

• Encode §3 as tests against the current planner (changepoint-only semantics including the
  plateau/ENOENT edge, errno taxonomy, reduce-span sentinels, update_total clamping,
  span-id monotonicity, equality semantics).
• Build the benchmark harness: a planner microbenchmark (operation mixes at
  n ∈ {10²…10⁶} changepoints) and a macro replay via resource-query with the conservative
  policy (maximum span density). Record the baseline the stage-2 swap must beat.

Stage 1 — remove the C interface; harden the C++ one (data structures unchanged):

• Move the shim algorithms into planner/planner_multi; delete the accessor surface and
  the planner_t double indirection; make planner a regular value type (copy/assign/==
  already exist — schedule_t and pool_infra_t copy logic collapses to defaulted
  members).
• Fix the API shape now so stage 2 causes zero consumer churn: const queries, a cursor
  object for first/next iteration (backed initially by the existing stash/restore mechanics,
  hidden behind the cursor's lifetime), std::span/string_view instead of parallel
  uint64_t*/char** arrays, expected-style errors at the C++ boundary.
• Port planner_test01/02 assert-for-assert (the unit-test parity goal); fix the §2
  defects; delete resource/planner/c/.
• Freeze semantics. The sharness suites (t1xxx–t6xxx) and ported unit tests must pass
  unchanged. Because the planner was never installed, nothing outside the repository can
  link it; blast radius is zero.

Stage 2 — backend swap behind the frozen interface:

• Implement the time-keyed min/max-augmented lazy-range-add tree plus the span registry.
• Differential-fuzz old backend vs. new backend vs. the ICL oracle on randomized operation
  sequences; run under the existing asan preset.
• Decide explicitly whether to keep or fix the plateau/ENOENT wart, with
  dfu.cpp:191-207 in view.
• Rework planner_multi first-fit as the galloping intersection (§5.6).
• Gate the merge on the stage-0 benchmarks.

Anti-goal: no pluggable-backend framework. One concrete implementation; the ICL oracle
lives in the test tree only. Two production representations of the same state is how the
current SP/MT sync problem arose.

7. Target API sketch (shape, not final)

class planner {  // regular value type
  public:
    std::optional<int64_t> find_first (int64_t on_or_after, uint64_t duration,
                                       int64_t count) const;   // stateless; resume by
                                                               // passing prev answer + 1
    bool avail_during (int64_t at, uint64_t duration, int64_t count) const;
    int64_t min_avail_during (int64_t at, uint64_t duration) const;  // O(log n) range-min
    expected<span_id, error> add_span (int64_t at, uint64_t duration, int64_t count);
    expected<void, error> remove_span (span_id);
    expected<bool, error> reduce_span (span_id, int64_t amount);  // true → fully removed
    // spans(): iterable view over the registry; no embedded iterator state
};

8. Bottom line

• Stage 1 is wide but mechanical: ~60 call sites, ~1,400 shim lines folded into the classes,
  1,691 test lines ported, four latent bugs fixed, planner.hpp roughly halved. Regression
  safety comes from assert-parity plus the unchanged sharness suites.
• Stage 2 is a contained piece of algorithm engineering (~400–600 lines) whose principal
  risk — semantic drift — is neutralized by stage 0's contract tests and stage 2's
  differential fuzzing.
• The winning structure is one time-keyed tree with min/max augmentation and lazy range-add:
  O(log n) for every mutation and window query, output-sensitive mutation-free first-fit,
  const queries, less memory, O(n) copies, and one structure to reason about instead of
  two (or, with the composites, three).
• k-d and R*-tree variants fail on query bounds (Θ(n^(2/3)) worst-case searches), on
  update churn (Θ(k) object invalidation per span operation over a materialized
  decomposition), on dynamism (no rebalancing; lazy deletes and rebuild spikes), and on the
  project's own simplicity goals (multiple synchronized representations). Reserve them for
  offline analytics over static snapshots.

References

• D.T. Lee, C.K. Wong, Worst-case analysis for region and partial region searches in
  multidimensional binary search trees and balanced quad trees, Acta Informatica 9, 1977 —
  Θ(n^(1−1/D)) k-d range-search bound.
• J.L. Bentley, J.B. Saxe, Decomposable searching problems I: static-to-dynamic
  transformation, J. Algorithms 1(4), 1980 — the logarithmic-forest method underlying
  nanoflann's dynamic adaptor.
• E.M. McCreight, Priority search trees, SIAM J. Comput. 14(2), 1985 — polylog 3-sided
  queries, for contrast with k-d bounds.
• CLRS ch. 14, Augmenting Data Structures — the subtree-aggregate pattern used by the
  recommended backend (and, in inverted form, by the current MT tree).
• Boost.ICL (split_interval_map), Boost.Geometry (bgi::rtree), nanoflann, ygg
  (yggdrasil) documentation.

[garlick]

"Anemic state bag" 🤣

Definitely saving that one.