Skip to content

refactor: split the backtrack engine into focused collaborators#948

Merged
rasros merged 7 commits into
mainfrom
refactor/backtrack-engine
Jul 3, 2026
Merged

refactor: split the backtrack engine into focused collaborators#948
rasros merged 7 commits into
mainfrom
refactor/backtrack-engine

Conversation

@rasros

@rasros rasros commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

What changed

Decompose the backtrack BacktrackSolver/engine monolith into focused, single-responsibility pieces. Seven commits, each behavior-preserving:

  • Extract the 713-line B&B engine (private inner class ResumableMinimize) out of BacktrackSolver into its own top-level internal class. BacktrackSolver (976 lines) becomes a ~245-line Solver/Optimizer facade; the engine takes the solver via its constructor.
  • Extract PhaseSaving (phase-saving + target-phasing + rephase schedule), shared by the satisfaction path (driveSearch) and the engine — removing the duplicated phase logic and the loose array threading through applyPhase/capturePhase/backjumpAndLearn.
  • Extract DeadlinePoller (the adaptive cancel-check cadence), also shared by both paths.
  • Extract RestartController (Luby/Glucose restart policy + the Luby math), shared by both paths.
  • Extract PortfolioBoundExchange (level-0 cross-arm objective-floor and variable-bound sharing).
  • Decompose the 269-line runUntilEvent loop body into named descendStep / backtrackStep methods.

The incumbent state (best/bestObj/objVarBest) stays in the engine by design: it is read across pruning, both terminal builders, and the leaf handler, so hiding it behind a collaborator would be a leaky abstraction rather than an improvement.

Why

BacktrackSolver.kt (52K) welded a thin API facade to a giant stateful search engine, and the phase/cancel/restart bookkeeping was duplicated between the satisfaction and optimize paths. Splitting them separates concerns and dedups the two drivers.

Testing

Behavior-preserving throughout; covered by the existing backtrack/optimize suites, full check lintDocs green across JVM + native + wasm. Benchmarked A/B (core suite, branch vs merge-base): identical solve outcomes, and wall-time differences within the run-to-run noise floor (the same binary swings ~230ms between repeats on these sub-second instances), i.e. no measurable regression.

@rasros rasros changed the title refactor: extract ResumableMinimize engine out of BacktrackSolver refactor: split the backtrack engine into focused collaborators Jul 3, 2026
@rasros rasros merged commit 81df587 into main Jul 3, 2026
2 checks passed
@rasros rasros deleted the refactor/backtrack-engine branch July 3, 2026 14:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant