Make clustering competitive: unify engine, add scaling and target-K

[ncborcherding]

Benchmarking for the manuscript showed bHIVE trailing on cytometry and single-cell data. It could not control the final cluster count and missed prominent cell populations. The matched-k analysis pinned the cause: about 80% of the ARI gap was the cluster-count heuristic, not prototype placement. This PR targets that directly and folds in the supporting fixes.

What changed

Unified engine. bHIVE() is now a thin wrapper over the AINet R6 engine. swarmbHIVE() and honeycombHIVE() call bHIVE(), so they inherit the C++ clonal-selection and suppression backends, Lloyd consolidation, scaling, target-K, and all composable immunology modules. The old pure-R loop is removed. swarmbHIVE() now forwards every grid column to bHIVE(), so any argument is tunable, not just nAntibodies/beta/epsilon.

Input scaling. New scale argument (none/zscore/robust/arcsinh), learned at fit and reapplied at predict. epsilon, mutation scale, and distances live in feature units, so scaling makes the same defaults behave consistently across datasets. affinityParams$alpha = "auto" sets the RBF bandwidth by the median heuristic, which matters in high dimensions where the fixed alpha=1 saturates the kernel.

Target-K clustering. New targetK argument forces exactly K clusters. Affinity maturation still finds where prototypes belong, then a seeded K-means refinement coerces the count: agglomerate when the network kept more than K, k-means++ split when fewer.

Rare-population protection. New coverageBoost seeds antibodies at the worst-covered points after maturation. honeycombHIVE() gains smallClusterAction (merge/keep/drop). Small clusters are now merged into the nearest prototype or kept, instead of being silently deleted.

Also adds epsilonQuantile for scale-free suppression and returns antibodies_unscaled for interpretation in original units.

Validation

Real Levine CyTOF, ARI on labeled cells:

Config	K	ARI
Before (emergent defaults)	40	0.263
targetK=14 + arcsinh + auto bandwidth	14	0.755
stock k-means K=14 (reference)	14	0.612

The new path fixes the cluster count, raises ARI 2.9x, and beats stock k-means on the same transformed data.

Compatibility

The historical return fields (antibodies, assignments, task) are unchanged. The return list gains antibodies_unscaled and, from bHIVE(), a model handle. Cosine affinity paired with a non-cosine distance now warns via the metric guard. Tests updated accordingly. All 643 tests pass.

Version bumped to 0.99.6.