fix: validate presence and shape at the HSJ/XFORM bridge

[ms609]

Fixes #14
Fixes #13
Fixes #22

Three guard clauses at the HSJ/XFORM scoring bridge (src/ts_rcpp.cpp) and the collapse gate (src/ts_collapsed.cpp).

#14 (T-398) — unpack_hsj() segfault on present-but-NULL hsjTipLabels

hsjConfig$hsjTipLabels == NULL (element present, value NULL) passed containsElementNamed() but was then skipped by !Rf_isNull(), leaving scoring_mode = HSJ with an empty ds.tip_labels — score_hierarchy_block() then reads it unconditionally and segfaults. Fixed with an explicit presence/non-NULL check that Rcpp::stop()s. Review also surfaced a second entrance to the same crash class — a non-NULL but too-narrow hsjTipLabels that doesn't cover every hierarchy block's primary/secondary character index — closed with the same guard.

Pre-fix standalone reproduction (segfault, cannot be asserted from inside testthat since it kills the process):

$ Rscript -e "library(TreeSearch, lib.loc='.agent-hierarchy-guards-prefix'); library(TreeTools); testthat::test_dir('tests/testthat', filter='ts-hsj-xform-guards', package='TreeSearch')"
Segmentation fault
$ echo $?
139

#13 (T-397) — unpack_xform() had no dimension validation

Ported ts_sankoff_test()'s cost-matrix dimension check (guarded since 0856748f) and added guards for holes that function doesn't have either: combo_grid row count against n_states - 1, tip_sec_known dimensions (found in review), and out-of-range tip_states. Previously a mis-shaped-but-same-length cost matrix read garbage with no warning at all — Rcpp's Matrix::operator() only bounds-checks the linear offset, not (row, col) — and an out-of-range tip_states value corrupted the score via the 1e18 pool sentinel, which passes is.finite().

#22 (T-408) — collapse guard keyed on scoring_mode alone

ts_collapsed.cpp's two collapse guards (compute_collapsed_flags, compute_collapsed_flags_aggressive) disabled branch collapse for any HSJ/XFORM config, even one carrying no actual hierarchy data (hierarchy_blocks empty and sankoff_n_chars == 0) — a case collapse is provably safe for. Fixed to gate on hierarchy-data presence, matching the predicate DataSet::topology_independent() already uses (src/ts_data.h:292).

Verified the loosening is strictly confined to the no-data case: every config with real hierarchy_blocks/sankoff_n_chars still gets all-zero collapse flags exactly as before — the sibling #17 chip's reliance on this guard's current behaviour for non-degenerate configs is untouched. Confirmed by an independent external-reviewer pass and by the existing T-330 regression suite (test-ts-t330-collapse-hsj-xform.R), which still passes unchanged.

Pre-fix failures (confirmed by reverting src/ changes and rebuilding via the tarball recipe)

FAILURE: 'test-ts-hsj-xform-guards-no14.R:81:3' — Expected ts_driven_search(...) to throw an error. [cost_matrix]
FAILURE: 'test-ts-hsj-xform-guards-no14.R:115:3' — Expected ts_driven_search(...) to throw an error. [combo_grid]
FAILURE: 'test-ts-hsj-xform-guards-no14.R:149:3' — Expected ts_driven_search(...) to throw an error. [tip_states]
FAILURE: 'test-ts-hsj-xform-guards-no14.R:213:3' — Expected nrow(cp_hsj$trees[[1]]) to equal nrow(cp_ew$trees[[1]])
  actual: 10, expected: 8
[ FAIL 4 | WARN 0 | SKIP 0 | PASS 2 ]

(The T-398 test is excluded from this run since its pre-fix behaviour is a segfault that kills the process — see above.)

Post-fix

Full guard suite plus related HSJ/XFORM/collapse/resample suites: 509/509 pass, verified via a temp-library tarball install (R CMD build + R CMD INSTALL --library=.agent-hierarchy-guards) per AGENTS.md, not devtools::load_all().

Reviewed by an independent external-reviewer agent, scoped to correctness; it confirmed the three primary guards and the two adjacent gaps noted above, both now closed in this branch.

CI status

• ✅ ubuntu-arm64 (full R CMD check + tests) — passed.
• ❌ windows — fails at the "Set up R dependencies" step, but this is confirmed pre-existing, unrelated infra breakage: it reproduces identically on cpp-search tip itself right now (two direct cpp-search dispatches failed with the same signature in the last 20 minutes), DESCRIPTION is untouched by this branch, and it is root-caused and already tracked/fixed at #43 (MaxMin pak-resolution asymmetry between Linux/Windows pandoc auto-detect), verified working on feature/ci-maxmin-windows. Not duplicated here to avoid conflicting with that in-flight fix.

Mandatory checks

• Rscript .claude/tools/compile-attrs.R — arg counts match (no new exports).
• Rscript check_init.R — arg counts match.
• spelling::spell_check_test(vignettes = TRUE, ...) (exact tests/spelling.R invocation) — clean.
• No search-behaviour change; vignettes/search-algorithm.Rmd not touched (collapse behaviour on a degenerate config only, not the search itself).
• NEWS.md updated with the one user-visible surface (Resample() replicates that drop every hierarchy block from a unit now collapse like ordinary Fitch data).