fix: enforce user constraints at the start-tree, pool-capture and collapse boundaries

[ms609]

Fixes #18
Fixes #1
Fixes #19

Three independent holes let a constraint stop binding the trees the caller is handed. They are one PR because #18 and #1 share the ungated pool capture verbatim, and #19 edits the same .PrepareConstraint() return and ts_collapse_pool signature that #18 touches.

What each fix does

#18 (T-402) — the start tree. run_single_replicate now repairs any constraint-violating start before anything takes its score as a baseline, falling back to a constrained Wagner build (itself repaired) when the heuristic repair does not take. Both documented mis-patch traps are structural consequences of one fact: a violating tree is drawn from a wider set of topologies than a legal one, so it scores better and is an unbeatable baseline for any later accept test. Acting at the boundary is the only placement that works.

#1 (T-324) — the pool capture. All three sites — interrupted and normal in the serial driver, plus the parallel worker — go through a new capture_satisfies_constraint(), which repairs then verifies, mirroring the fuse capture beside it. Discards are counted per thread and warned from the main thread, since Rf_warning() from a worker would corrupt the heap. With the pool gated, an empty pool under a constraint no longer falls back to the unvalidated start tree.

#19 (T-403) — the collapse. consZero is plumbed through .PrepareConstraint() to the kernel, which now also protects the node realising a split when no realising edge survives the contraction on its own. Protecting unconditionally would force resolution of branches the constraint does not ask for — the "unsupported non-constraint branches still collapse" half of the promise.

Repair vs reject on #18

I repaired in C++ and warned in R, rather than rejecting the start.

constraint is a guarantee about output; tree is a hint about where to start. When they conflict the guarantee has to win, but discarding the hint throws away the user's basin — and the motivating case in ?MaximizeParsimony is warm-starting from previously found optima, exactly where that basin is the point. A few SPR moves preserve it. The conflict is still the caller's to know about, so MaximizeParsimony() warns: either the tree or the constraint is not what they meant.

The warning uses the phyDat reading @param constraint documents (? taxa free on either side), which is a true statement about the user's contract. The repair triggers on the same reading.

Pre-fix failure output

Against a clean git archive build of 99b79d8f, tests/testthat/test-ts-constraint-holes.R fails 14 assertions:

FAILURE 'test-ts-constraint-holes.R:91' Expected `as.numeric(attr(one, "score"))` to equal 10.
  [1] 6 - 10 == -4
FAILURE 'test-ts-constraint-holes.R:92' Expected `AllShown(one, ...)` to equal `length(one)`.
  [1] 0 - 1 == -1
FAILURE 'test-ts-constraint-holes.R:105' Expected `as.numeric(attr(many, "score"))` to equal 10.
  [1] 6 - 10 == -4
FAILURE 'test-ts-constraint-holes.R:106' Expected `AllShown(many, ...)` to equal `length(many)`.
  [1] 0 - 1 == -1
FAILURE 'test-ts-constraint-holes.R:128' Expected `AllShown(result, ...)` to equal `length(result)`.
  [1] 84 - 85 == -1
FAILURE 'test-ts-constraint-holes.R:133' Expected `as.numeric(attr(result, "score"))` >= 10.
  Actual comparison: 6.0 < 10.0
FAILURE 'test-ts-constraint-holes.R:202' Expected `AllShown(collapsed, ...)` to equal `length(collapsed)`.
  [1] 0 - 1 == -1
[ FAIL 14 | PASS 4 ]

The constrained optimum is 10; 6 is the unconstrained optimum, which is what the frozen search reported. Line 128 is the pool test: 84 of 85 retained trees complied, one did not. Line 202 is the collapse test, which returned (a,(e,(c,d,g,h,(b,f)))) — no split separating {a,b} from {c,d}.

After the fix: 35 pass, 0 fail. Full suite 11748 pass, 0 fail.

A limitation now stated rather than silent

A constraint character is enforced as a single split throughout — the locked-node filter screens rearrangements on it, and impose_constraint() repairs to it and nothing else. A character with three or more states therefore has taxa nothing constrains.

An intermediate version judged captures by the stricter full-Fitch reading instead. A probe on a three-state constraint then discarded all four replicates and errored with an empty pool, where a partial answer existed — the search cannot reach a standard its own repair cannot produce. The gate follows the mapping, and .PrepareConstraint() now warns at input that an intermediate state is unconstrained.

Scope

Deliberately not fixed, filed as #54: a start tree that satisfies the constraint as documented but not the stricter exact-clade form the locked-node machinery enforces still freezes the replicate. It is not a regression (identical on 99b79d8f) and returns no wrong answer — strict implies loose, so every accepted tree satisfies the documented constraint — but the replicate does no work. Closing it means picking which reading is canonical and making it true at the Wagner and sector entry points too. vignettes/search-algorithm.Rmd states the distinction rather than papering over it.

The reachability question behind #1 (whether a satisfiable constraint's violation survives all 100 Wagner reshuffles) is left open per the issue: it needs a Hamilton probe. The proven inconsistency — missing gate, missing warning — is what this fixes.

Performance

The added checks sit on the constrained path. Interleaved A/B on Vinther2008, 20 replicates, paired seeds, against cpp-search:

	median ratio	slower	>10% slower	scores
constrained	0.95	7/20	4	identical
unconstrained	0.93	6/20	1	identical

An earlier revision measured 1.12 median with 11/20 seeds >10% slower. The check now short-circuits on the locked-node mapping, which is cheaper than the post-hoc Fitch check, so only an unmapped split pays for the latter.

Review

Three external-reviewer passes (AGENTS.md compliance, cold bug scan, git blame history) plus a self-review. They found: a fourth do.call splat site that broke Resample(constraint=, nReplicates > 1) outright with no test covering it; over-protection in the collapse rule; discarded replicates feeding the strategy bandit and coverage estimate; repair running after the deadline; and the multi-state gap above. All fixed.

CI

ubuntu-arm64 passes. The windows job fails at Set up R dependencies — Can't find package called MaxMin — before any code runs. This is pre-existing and branch-independent: cpp-search itself fails identically (runs 30929069059, 30927635697), as does every open feature branch, and feature/ci-maxmin-windows is addressing it separately.

🤖 Generated with Claude Code