Add Target::max_weight, built on the metric-decides-change refactor (#49)

[evanlinjin]

Alternative to #48 for capping transaction weight during coin selection (e.g. for TRUC / BIP-431 packages limited to 10,000 / 1,000 vB).

This version is built on top of the metric-decides-change refactor that just landed in #49, and that turns out to matter a lot for correctness — see below.

Approach

• Target::max_weight: Option<u64> — a feasibility constraint (the sibling of the value target: a lower bound on value, this an upper bound on weight).
• is_target_met is kept value-only / monotone; the weight cap is a separate, anti-monotone predicate CoinSelector::is_within_max_weight. Keeping these apart is what preserves the monotonicity that BnB bounds and is_selection_possible rely on.
• Enforcement lives in the metric (which, post-feat!: BnB metrics decide the change output themselves #49, owns the change decision): LowestFee::drain_value refuses a change output that would bust the cap, score rejects any over-cap selection, and bound hard-prunes subtrees whose lightest (no-drain) form already busts the cap.
• is_selection_possible becomes an exact value probe plus a greedy value-per-weight weight probe.

Why build on #49 instead of folding into Target/is_target_met

Folding the cap into is_target_met (as in #48) makes that predicate anti-monotone, which breaks two things:

1. is_selection_possible starts returning false negatives (it selects all effective inputs — max value and max weight — then checks the now-weight-aware is_target_met).
2. More seriously, LowestFee's bound becomes inadmissible. When the cap forces a descendant to be changeless (the change is refused for weight), that descendant can score below an ancestor's bound, so BnB prunes the branch and returns a suboptimal selection.

The second point is the interesting one: on the pre-#49 min_value change policy this bug is real and reproducible. On the #49 base it disappears — because change is now decided economically (only added when it lowers the long-term fee), the bound's existing "a descendant can't improve by removing worthwhile change" proof stays valid even when the cap forces changelessness. So the weight hard-prune is sufficient and no extra bound term is needed. This is the core reason this PR targets the refactored base.

Testing

• max_weight is threaded through every LowestFee proptest, so BnB is compared against exhaustive search with the cap active.
• New exact_selection_possible oracle (exhaustive, reuses the real is_target_met/is_within_max_weight, independent of the BnB prune) + a bnb_respects_max_weight proptest (4096 cases) asserting BnB feasibility matches the oracle and that is_selection_possible never over-claims.
• Fixed compare_against_benchmarks to filter benchmarks by score().is_some() rather than value-only is_target_met, so an over-cap benchmark (e.g. select_all under a tight cap) isn't mistaken for a valid solution.

Note

Breaking change: the Target { .. } literal now requires a max_weight field.

🤖 Generated with Claude Code