[Experimental work in progress] Add experimental heuristic search for Gecode 6.5

.github/ci/generated-source-freshness.sh

@@ -225,7 +225,7 @@ normalize_generated_whitespace() {
   # Ignore any autom4te cache so output matches a clean source release.
   autoconf --force
   # Autoconf 2.72 appends blank lines after the generated script body; source
-  # releases retain exactly one final newline.
+  # releases have exactly one final newline.
   normalize_generated_whitespace configure
   uv run --script ./misc/genvarimp.py -typehpp "${vis_files[@]}" \
     > gecode/kernel/var-type.hpp

.github/workflows/build.yml

@@ -220,6 +220,7 @@ jobs:
       shell: bash
       run: >
         cmake -S "$GITHUB_WORKSPACE" -B "$GITHUB_WORKSPACE/build-ninja"
+        -DGECODE_ENABLE_EXPERIMENTAL=ON
         -G Ninja
         -DCMAKE_BUILD_TYPE=$BUILD_TYPE
         -DGECODE_ENABLE_QT=OFF

.zdev/_notes/fifteen-puzzle.md

@@ -0,0 +1,74 @@
+# 15-puzzle search integration
+
+The BAB-only example from `feature/open-cp` was integrated at parent commit
+`60325e4801d092ffad42b014bbca7708039b5826`. The MPG measurement matrix is
+finished. Task `open-search-037` delivered the extension and focused validation.
+Do not change MPG's source, results, or frozen measurement library.
+
+Task `open-search-038` carries forward the deferred goal correction from CP
+commit `81fff38e8e843e29c0d26a65e004fca1e926ee87`. The open model waits for board
+assignment before closing the path or requiring a successor; Manhattan distance
+stays in heuristic guidance. Upstream validation found that open BAB's default
+exceeds a 30-second Debug cutoff after losing early backward goal propagation.
+The default slowdown was addressed in task `open-search-039`.
+
+Task `open-search-039` carried that follow-up from CP commit
+`fc26a2a8fcb78d5b1c617e341a1ef13224f40019`. Assigned boards fail when their
+depth plus Manhattan distance exceeds the current move cap. A materialized
+board at the final cap is constrained to the goal, including after incumbent
+cuts. These rules preserve deferred construction and the heuristic extension.
+Focused Release validation completed the open defaults in 9–10 ms, with the
+two-board root, clone independence and pending-cap behavior checked separately.
+
+## Prepared extension
+
+Extend upstream `examples/fifteen-puzzle.cpp`, preserving its documentation,
+size validation, shared slide/goal rules, and separate open/fixed models.
+Upstream owns the example's CMake and Autoconf registration.
+
+- Add `bab`, `astar`, and `cabs` search selections.
+- Add open-model depth and both models' total Manhattan bounds:
+  `max(depth + Manhattan(current board), minimum length - 1)`.
+- Supply the same minimizing bound through `Search::HeuristicGuidance` to
+  A* and CABS. Use small engine adapters for `Script::run` and the default
+  unrestricted CABS widening policy.
+- Guard experimental registrations, guidance, and adapters with
+  `GECODE_HAS_EXPERIMENTAL`; keep BAB available in ordinary builds.
+- Use upstream `known_length()` in the open-model depth query. Update the
+  downstream TSPTW caller in `examples/tsptw-transition.hh` when integrating
+  the parent rename.
+
+Preserve standard `INT_VAL_MIN` branching. Length includes the start and moves
+are length minus one. The constructor posts the start unconditionally; the
+materialization transition returns for index zero. Keep this an educational
+example without an embedded oracle, optimum assertions, or benchmark machinery.
+
+Reference implementation:
+`/Users/zayenz/.codex/worktrees/bba6/MPG/rst/examples/src/fifteen-puzzle.cpp`.
+
+Build the example with experimental search enabled and disabled, and run
+small representative open/fixed cases
+through BAB, A*, and CABS. Use the existing example validation conventions;
+the extension does not need a new permanent test harness.
+
+## Repeated posting and memory
+
+The MPG/CP handoff reports roughly 698.5 MiB peak RSS for open BAB versus
+5.9 MiB for fixed BAB at scramble 16, limit 16, seed 3, with 780737 nodes in
+each run. These measurements are preliminary and have not been independently
+checked here. The growing result file is
+`/Users/zayenz/.codex/worktrees/bba6/MPG/rst/examples/results/fifteen-puzzle-engines-60s.csv`.
+
+Source inspection confirms that freshly posted propagators allocate
+`Kernel::GPI::Info` from shared space data (`gecode/kernel/core.hpp`,
+`Propagator::Propagator(Home)`). Clones reuse the existing pointer. GPI allocates
+entries monotonically in blocks and frees the blocks in its destructor
+(`gecode/kernel/gpi.hpp`). Open transitions repeatedly post new constraints,
+so this metadata can accumulate across explored states even after those spaces
+are deleted. The fixed formulation posts its constraints initially.
+
+Follow up by measuring allocation counts and memory attributable to GPI, and
+profiling runtime to distinguish posting/propagation costs from search costs.
+The inspected lifetime fits the reported RSS difference; its contribution
+still needs measurement. Any change to allocation or AFC sharing needs separate
+design work and should leave the ongoing comparison untouched.

.zdev/config.toml

@@ -0,0 +1,6 @@
+schema_version = 1
+
+[project]
+name = "gecode"
+record = "pull-request"
+trunk = "main"

.zdev/open-cp/TASKS.md

@@ -0,0 +1,11 @@
+<!-- Generated by zdev. Edit task files, not this summary. -->
+
+# Tasks: open-cp
+
+- Total: 0
+- Ready: 0
+- Blocked: 0
+- Done: 0
+
+| ID | Task | State | Blocked by |
+| --- | --- | --- | --- |

.zdev/open-cp/area.toml

@@ -0,0 +1,7 @@
+schema_version = 1
+tag = "open-cp"
+title = "Native open constraint programming"
+objective = "Provide the native open-list runtime used by standalone heuristic search."
+branch = "feature/open-cp"
+lifecycle = "open"
+base_commit = "6b7de57b0414fe2f8af3513743c9835840a3c019"

.zdev/open-cp/brief.md

@@ -0,0 +1,17 @@
+# Native open constraint programming
+
+## Objective
+
+Record the existing `feature/open-cp` parent used by standalone native search.
+
+## Boundaries
+
+The branch split does not change this parent branch. Its recorded base is main.
+
+## Testing
+
+No implementation or new tests belong to this parent registration.
+
+## Validation
+
+Check branch identity and ancestry when admitting dependent native search work.

.zdev/open-search/TASKS.md

@@ -0,0 +1,52 @@
+<!-- Generated by zdev. Edit task files, not this summary. -->
+
+# Tasks: open-search
+
+- Total: 41
+- Ready: 0
+- Blocked: 0
+- Done: 41
+
+| ID | Task | State | Blocked by |
+| --- | --- | --- | --- |
+| [open-search-001](tasks/001-deliver-sequential-a-with-incumbent-publication.md) | Deliver sequential A* with incumbent publication | done | — |
+| [open-search-002](tasks/002-deliver-standalone-widening-cabs.md) | Deliver standalone widening CABS | done | open-search-001 |
+| [open-search-003](tasks/003-configure-both-native-engines-through-optional-model-guidanc.md) | Configure both native engines through optional Model guidance | done | open-search-002 |
+| [open-search-004](tasks/004-compose-native-heuristic-engines-in-ordinary-space-portfolio.md) | Compose native heuristic engines in ordinary-Space portfolios | done | open-search-002 |
+| [open-search-005](tasks/005-establish-exact-tsptw-data-and-independent-checking.md) | Establish exact TSPTW data and independent checking | done | — |
+| [open-search-006](tasks/006-deliver-a-strong-conventional-cp-tsptw-model.md) | Deliver a strong conventional CP TSPTW model | done | open-search-005 |
+| [open-search-007](tasks/007-deliver-open-list-tsptw-transitions-and-an-eager-control.md) | Deliver open-list TSPTW transitions and an eager control | done | open-search-005 |
+| [open-search-008](tasks/008-add-optional-exact-state-and-pareto-pruning-to-a-and-cabs.md) | Add optional exact-state and Pareto pruning to A* and CABS | done | open-search-007 |
+| [open-search-009](tasks/009-add-cheap-tsptw-bounds-and-compare-residual-propagation.md) | Add cheap TSPTW bounds and compare residual propagation | done | open-search-006, open-search-007 |
+| [open-search-010](tasks/010-deliver-native-progressive-column-search-with-cbfs-mode.md) | Deliver native progressive column search with CBFS mode | done | open-search-006, open-search-008 |
+| [open-search-011](tasks/011-expose-state-pruning-and-column-search-through-optional-inte.md) | Expose state pruning and column search through optional integrations | done | open-search-008, open-search-010 |
+| [open-search-012](tasks/012-build-a-small-resumable-tsptw-comparison-runner.md) | Build a small resumable TSPTW comparison runner | done | open-search-006, open-search-007 |
+| [open-search-013](tasks/013-tune-and-freeze-the-conventional-gecode-baseline.md) | Tune and freeze the conventional Gecode baseline | done | open-search-006, open-search-012 |
+| [open-search-014](tasks/014-investigate-fixed-width-beam-stack-regeneration-in-gecode.md) | Investigate fixed-width beam-stack regeneration in Gecode | done | open-search-007, open-search-012 |
+| [open-search-015](tasks/015-investigate-suffix-compatible-beam-repair-with-existing-lns.md) | Investigate suffix-compatible beam repair with existing LNS | done | open-search-007, open-search-012, open-search-013 |
+| [open-search-016](tasks/016-evaluate-frozen-formulations-and-engines-on-held-out-tsptw.md) | Evaluate frozen formulations and engines on held-out TSPTW | done | open-search-009, open-search-010, open-search-012, open-search-013, open-search-014, open-search-015 |
+| [open-search-017](tasks/017-keep-column-frontier-selection-interruptible.md) | Keep column frontier selection interruptible | done | — |
+| [open-search-018](tasks/018-keep-benchmark-cleanup-and-proof-outcomes-honest.md) | Keep benchmark cleanup and proof outcomes honest | done | — |
+| [open-search-019](tasks/019-state-the-progress-and-incumbent-obligations-of-heuristic-se.md) | State the progress and incumbent obligations of heuristic search | done | — |
+| [open-search-020](tasks/020-compose-model-bounds-and-ranking-with-independent-dependenci.md) | Compose Model bounds and ranking with independent dependencies | done | — |
+| [open-search-021](tasks/021-let-the-owning-model-search-facade-accept-a-native-builder.md) | Let the owning Model search facade accept a native builder | done | — |
+| [open-search-022](tasks/022-compose-explicit-model-portfolio-recipes-with-native-heurist.md) | Compose explicit Model portfolio recipes with native heuristic builders | done | open-search-021 |
+| [open-search-023](tasks/023-expose-cabs-limits-in-the-model-driver.md) | Expose CABS limits in the Model driver | done | — |
+| [open-search-024](tasks/024-separate-persistent-descriptor-retention-from-search-schedul.md) | Separate persistent descriptor retention from search scheduling | done | — |
+| [open-search-025](tasks/025-share-resumable-choice-expansion-and-avoid-the-final-clone.md) | Share resumable Choice expansion and avoid the final clone | done | — |
+| [open-search-026](tasks/026-remove-cabs-full-beam-descriptor-recounts.md) | Remove CABS full-beam descriptor recounts | done | — |
+| [open-search-027](tasks/027-close-cabs-passes-when-discarded-work-is-bounded-out.md) | Close CABS passes when discarded work is bounded out | done | — |
+| [open-search-028](tasks/028-evaluate-a-cheap-tsptw-residual-deadline-filter.md) | Evaluate a cheap TSPTW residual deadline filter | done | open-search-018 |
+| [open-search-029](tasks/029-add-configurable-native-best-first-ordering.md) | Add configurable native best-first ordering | done | open-search-024, open-search-025 |
+| [open-search-030](tasks/030-evaluate-sequential-cadds-retained-fragment-search.md) | Evaluate sequential CADDS retained-fragment search | done | open-search-018, open-search-025 |
+| [open-search-031](tasks/031-reconstruct-standalone-native-search-on-open-cp.md) | Reconstruct standalone native search on open-cp | done | — |
+| [open-search-032](tasks/032-gate-heuristic-search-as-an-experimental-preview-and-separat.md) | Gate heuristic search as an experimental preview and separate experimental changelog entries | done | — |
+| [open-search-033](tasks/033-repair-reviewed-preparation-and-completion-contracts-and-com.md) | Repair reviewed preparation and completion contracts and compact CABS victims | done | — |
+| [open-search-034](tasks/034-remove-kernel-search-coupling-and-simplify-heuristic-search.md) | Remove kernel search coupling and simplify heuristic search examples | done | open-search-033 |
+| [open-search-035](tasks/035-invalidate-completion-witnesses-when-posting-through-an-exis.md) | Invalidate completion witnesses when posting through an existing Home | done | open-search-034 |
+| [open-search-036](tasks/036-check-all-validated-benchmark-tours-against-optimality-claim.md) | Check all validated benchmark tours against optimality claims | done | open-search-034 |
+| [open-search-037](tasks/037-add-heuristic-search-to-the-shared-fifteen-puzzle-example.md) | Add heuristic search to the shared fifteen-puzzle example | done | — |
+| [open-search-038](tasks/038-carry-deferred-goal-checks-into-the-heuristic-puzzle-example.md) | Carry deferred goal checks into the heuristic puzzle example | done | — |
+| [open-search-039](tasks/039-restore-pruning-in-the-deferred-open-puzzle-model.md) | Restore pruning in the deferred open puzzle model | done | — |
+| [open-search-040](tasks/040-use-scoped-nogpi-for-open-list-construction-across-the-stack.md) | Use scoped NoGPI for open-list construction across the stack | done | — |
+| [open-search-041](tasks/041-document-nogpi-on-open-list-materialization-methods.md) | Document NoGPI on open-list materialization methods | done | — |

.zdev/open-search/area.toml

@@ -0,0 +1,8 @@
+schema_version = 1
+tag = "open-search"
+title = "Heuristic search and open transition models"
+objective = "Add A* and complete anytime beam search to Gecode for ordinary and open models, demonstrate open TSPTW transitions, and validate correctness and practical search/memory trade-offs."
+branch = "feature/open-search"
+lifecycle = "open"
+parent = "open-cp"
+base_commit = "462123d05d8195fefa00dc9be7990ee2d08b1a82"