fix: loosen constraint matching to the documented free-taxa contract

[ms609]

Fixes #54

The maintainer picked "loosen the machinery to match the documented contract",
and that is what this does. ?MaximizeParsimony's @param constraint promises
the phyDat reading — a returned tree is compliant when some edge separates the
taxa coded 1 from those coded 0, with ?-coded taxa free on either side.
The locked-node machinery enforced a strictly stronger one: some node's tip set
had to equal the 1 group (or its exact complement), free taxa excluded.

vignettes/tree-search.Rmd already told users "The position of taxa not listed
in a constraint will not be constrained." That sentence was false before this
change — an unlisted taxon was pinned to the far side of the constraint — and is
true after it.

One reading, at every entry point

.PrepareConstraint() folds both groups into consSplitMatrix as 1 / 0 /
NA, NA marking a free taxon; build_constraint() reads any value that is
neither 1 nor 0 as free. A hand-built 0/1 matrix therefore still means "no
free tips" and takes exactly the old path — which is what the existing tests and
build_constraint_from_bitsets()'s consensus splits rely on. No Rcpp signature
changed, so RcppExports and TreeSearch-init.c are untouched.

ts::node_displays_split() (ts_constraint.h) is now the definition of
"this node displays the split", called by every implementation that used to
answer it separately:

Entry point	Was	Now
map_constraint_nodes() (search/TBR)	exact match, internal nodes only	shared predicate, both polarities, tips included
wagner_tree_displays_constraint() (Wagner build)	exact match, root skipped	shared predicate, root included
ts_collapse_pool() (output collapse)	exact match	shared predicate, tightest displaying node
violates_constraint_posthoc() (retry/revert)	already loose	unchanged

classify_clip_constraints() reads "outside" as the apart-group rather than as
~split_tips, so a clip of purely free taxa is UNCONSTRAINED; and a clip whose
own tip set displays the split is UNCONSTRAINED too, because it carries the
constraint with it — the node at whatever attachment point it lands on has
exactly the clip's tip set, and TBR's rerooting cannot change that.
regraft_violates_constraint() uses the end of the displaying chain that permits
most per question: the highest node for a clip that must land inside, the
tightest for one that must land outside. impose_constraint() no longer counts a
documented-compliant tree as violating, and never moves a free taxon when it does
repair one.

map_constraint_nodes() also scans tips now. tree.postorder holds only
internal nodes, so a single-taxon group — whose "clade" is the tip itself —
mapped to nothing and froze the replicate the same way.

The issue understated one thing

The issue says "no wrong answer is ever returned". That holds for the search but
not for the returned result. ts_collapse_pool() identified the branch realising
a constraint by exact match too, so with free taxa it protected nothing and the
separating edge was contracted away. Deterministically, on
(((a,e),(b,f)),(c,d)) with cons = c(a=1, b=1, c=0, d=0, e:f="?"):

before: (a,(e,(c,d,(b,f))));    separates {a,b} from {c,d}: FALSE
after:  (a,(e,((b,f),(c,d))));  separates {a,b} from {c,d}: TRUE

Independently reproduced by review: 3 of 30 seeds on a 12-taxon panel returned a
violating tree before, 0 after. It now has its own regression test.

Behaviour change that needs your eye

A constraint character whose 1 or 0 group holds fewer than two taxa is now
ignored, with a warning. Every tree separates such a group from the rest, so it
constrains nothing under the documented contract — but this is wider than "no 0
taxa": it also drops a one-taxon 0 group, which is how some users write "make
these taxa a clade" (c(a=1, b=1, c=1, d=0) with the rest left ?).

Under the loose reading that constraint no longer guarantees {a,b,c} monophyly
whether or not the row is kept — that follows from the fix you chose, not from
the filter. Keeping it would only add a spurious search restriction with no
guarantee attached, so it is dropped and the user is told. Both vignette examples
in tree-search.Rmd code every taxon explicitly and are unaffected.

The test is symmetric in the two groups, which the old one was not: since
build_constraint() swaps the groups to canonicalise, they are interchangeable,
yet c(a=1, b=1, c=0) and c(a=0, b=0, c=1) used to be treated differently.
NEWS carries both halves. If you would rather this stayed enforced, say so and
I will keep the row and restrict only the spurious part.

Deliberately not done

• random_constrained_tree() still nests the together-group as an exact clade,
  so a free taxon never starts inside the constrained group. Every tree it
  builds is compliant, so this is a sampling limitation, not a correctness one;
  widening it changes which start trees the search sees, which is a
  search-quality change to measure on its own. Documented in place.
• The constraint_node_hi anchor (the "must land inside" end of the chain) is
  sound and is the correct reading, but its search benefit is unmeasured —
  on a 30-seed panel it was within noise of using the tight anchor alone, and no
  test discriminates it, because TBR can usually reach the same topology by
  clipping a free taxon instead. Its cost is one parent walk per split per remap,
  bounded well below the postorder scan it accompanies.

Verification

• 26 constraint / Wagner / collapse / driven / resample / sector suites pass, 0
  failures, 0 warnings.
• New tests/testthat/test-ts-constraint-free-taxa.R: the freeze (TBR-only, so
  no other phase can mask it), end-to-end compliance, the collapse regression,
  the Wagner build, the .PrepareConstraint encoding, and an over-loosening
  guard that a pure 0/1 constraint is still enforced exactly. 12 of its
  assertions fail against a pre-fix build of the same tree. The Wagner
  assertion is the sharpest: pre-fix the tightest node covering {a,b} and
  avoiding {c,d} is exactly {a,b} in 25 of 25 seeds — every ? taxon
  forced out — and holds a free taxon in all 25 after.
• Randomised fuzz, 200 datasets with genuine free taxa: 0 contract violations.
• Three independent reviews (correctness, Wagner/search parity, conventions);
  every finding is addressed in the follow-up commits or answered above.

🤖 Generated with Claude Code

[ms609]

Conflicts resolved; two decisions worth your eye

Rebuilt against the trunk twice — cpp-search moved under me mid-resolution
(#59 landed, then #75). Now merged up to e0629be6.

The textual conflicts were NEWS.md, vignettes/search-algorithm.Rmd and
src/ts_rcpp.cpp, but the real overlap was semantic: #59 reads the contract
the same way this PR does, having independently implemented the free-taxa
test in the collapse pass. It just routed the apart-group to C++ as a second
matrix (consZero) beside consSplitMatrix, where this branch folds both
groups into consSplitMatrix as 1/0/NA.

Two channels for one fact is the shape of the bug this PR fixes, so I kept one.

1. Dropped consZero from ts_collapse_pool() (10 args → 9).
The folded matrix already carries both groups, and it is the channel every
search kernel takes — consZero reached only the collapse pass, which is why
map_constraint_nodes() could not see the apart group in the first place.
TreeSearch-init.c updated to match; compile-attrs.R clean. Left alone in
the auto-merge, the two encodings would have silently disagreed:
row_bits() tests truthiness, and NA_INTEGER is truthy, so every free tip
would have joined the together-group.

2. Took #59's collapse rule over mine. Mine pinned the tightest realising
node unconditionally; #59 protects one only when no realising node already
survives the contraction. #59's is right — protecting unconditionally resolves
a branch the constraint never asked for, against the "unsupported
non-constraint branches still collapse" half of the promise. Restated with the
shared ts::node_displays_split(); the exact-match block #59 kept alongside it
is subsumed (it only ever considered flagged nodes, so it was a strict subset).

Also: .ConstraintViolated() now reads == 1 rather than truthiness — same
NA_INTEGER trap on the R side, where it would have propagated through the
postorder accumulation and made every comparison NA; and
constraint_satisfied()'s comment no longer claims the locked-node mapping is
the stronger test, since it now asks exactly the documented question.

The vignette keeps #59's "Starting trees under a constraint" section and drops
its closing paragraph, which described the strict/loose divergence as
deliberate — no longer true.

Verification: full suite 11971 pass / 0 fail (4 warnings, all pre-existing
MaddisonSlatkin profile warnings); constraint, collapse, AdditionTree,
na-oracle and hsj-xform suites 659 pass / 0 fail against the final tree;
spell-check clean. GHA
31010157018
running.

Unchanged and still flagged from before: the inert-character filter drops a
1 or 0 group of fewer than two taxa, which is wider than the old test
and covers the c(a=1, b=1, c=1, d=0) clade idiom. Say the word and I will
narrow it to the vacuous half.