T-385: report the x-transformation score of the tree actually returned

[ms609]

Implements the already-decided Option 3 of dev/plans/2026-07-29-t374b-xform-rooting-policy.md. That decision's three merged commits (7a18a4b7 et al.) turned out to be docs only — no code implemented "make MaximizeParsimony's reported score and TreeLength() agree on one rooting".

Stacks on #277. Branched on top of claude/ci-easy-fixes so sense-check could pass and CI give a meaningful signal; merge #277 first. Only the last four commits here are T-385.

⚠️ Reviewer-critical: reported XFORM scores change

They rise, and will never fall — measured 178 → 183 on the repro. The new value is the length of the tree you are actually handed; the old one was the length at a rooting discarded during search. Documented in NEWS, ?MaximizeParsimony, ?RecodeHierarchy and vignettes/search-algorithm.Rmd. Only inapplicable = "xform" is affected.

The defect

XFORM's step matrix is asymmetric (gain nSec + 1 against loss 1), so a tree's length depends on where it is rooted — unlike the symmetric criteria. MaximizeParsimony reported result$best_score, recorded mid-search at whatever rooting the replicate held, while ts_collapse_pool hands every tree back re-rooted on tip 0.

Reproduced against tip a8fbba84 before writing any fix (36 tips / 6 blocks / nSec 2):

quantity	pre-fix	post-fix
reported attr(res, "score")	178	183
TreeLength() of all 32 returned trees	183	183
same topology over 8 rootings	178–183 (spread 5)	183 (spread 0)

The reported number was not wrong — 178 is attained by 2 of those 8 rootings. It was a value at a rooting the user never receives.

The fix

Canonicalise on the dataset's first taxon at both boundaries:

• TreeLength() — in both methods. The multiPhylo path previously rooted only trees that arrived unrooted (tree_length.R:298), so an already-rooted tree kept its own rooting. Rooted by name with tips re-aligned afterwards, never by an R reroot on the edge matrix (that permutes tips and mis-scores against tip_data).
• MaximizeParsimony() — rescore the returned pool through that same path, |pool| evaluations.

Not done, deliberately: min-over-rootings reporting. The plan calls it the better variant, but the deciding objection is cost — naively (2n-3)× on the Sankoff term, so a 4000-tip pool of 100 trees needs ~800k boundary evaluations. Affordably it needs an all-rootings up-down DP, which is Option 4's own piece of work.

HSJ reporting is untouched, gated on XFORM alone with the reason in the code: there rooting-invariance is required by the method (two-state DP, T-374's open half), so canonicalising would convert a wrong objective into a stably-wrong one.

Scope boundary — and a residue this surfaced

Pool membership is still decided on search-time scores taken at differing rootings, so returned trees need not share the canonical length. That is T-374's open residue (fixing it moves n_topologies semantics and interacts with collapse, unanalysed by the decision document) — but it is no longer silent: MaximizeParsimony() now warns and reports the smallest.

That warning immediately found a live instance in the existing suite: all-hierarchy xform data returns a pool spanning 7 to 9. It independently corroborates T-374's original "4 of 6 trees do not share a score", and is now pinned as an expect_warning so it reads as a documented expectation rather than noise — and so that if it ever stops firing, someone notices.

Tests

Two regression tests, both verified to fail against a pre-fix build in a throwaway worktree (spread 2 not 0; reported 46 against min 48) and pass after:

• The deterministic one carries an anti-vacuity guard: it first asserts, via ts_sankoff_test — untouched by this fix — that the raw kernel really is rooting-sensitive on its 8-tip input, so it cannot pass by scoring rooting-insensitive data.
• The end-to-end one asserts the actual contract (reported == min of the returned trees' canonical lengths), not the stronger "every tree shares it", which holds for its data but is not what the code promises.

Also corrects the three false root-invariance comments the plan lists (ts_tbr.cpp:123 and :3152, ts_rcpp.cpp's collapse reroot, MaximizeParsimony.R's collapse note).

Validation

All 8 jobs green on run 30662279563. (ubuntu-24.04 (4.1) failed once at "Set up R dependencies" with the Bioconductor 3.14 repos unreachable — Check package was skipped, so no code was tested; green on re-run.)

Locally, NOT_CRAN=true across xform, tree_length, hsj, t330, recode-hierarchy, resample-hierarchy, t306, prune-reinsert — 0 failures. spell_check_package() clean; check_man() clean.

🤖 Generated with Claude Code