perf(engine): hoist O(N^2) static-ability scans out of combat/untap legality loops

[matthewevans]

Problem

On a large token board (Unbeatable Squirrel Girl: 702 Squirrels + Cryptolith Rite, ~760 battlefield permanents), declaring attackers and passing priority crawled. Root cause: several combat/untap legality operations are O(N²) in battlefield size — each loops over N permanents and calls check_static_ability (itself an O(N) game_functioning_statics sweep) per element.

GameState uses im persistent collections, so cloning is O(1) — the cost is the repeated full-battlefield static scans, not memory.

Fix — early-gating (byte-identical)

Hoist a single "does any functioning static of MODE exist?" existence check before each loop, and gate the per-element scan behind it. Because check_static_ability returns false when no static of that mode exists (it continues on def.mode != mode), gate && check_static_ability(MODE, ctx) is byte-identical to the original call: when the gate is false the call would have returned false anyway; when true, the exact original call runs with its full CR gate stack intact (affected filter, condition, attack_defended scope CR 508.1d, per_player_condition CR 101.2/109.5). Precompute was rejected precisely because it would force re-implementing those matchers.

No verdict changes. No serialized-state change.

New building blocks (engine only)

• any_functioning_static_mode — the loop-invariant existence gate primitive (CR 604.1).
• CombatStaticGates::compute — one game_functioning_statics sweep → 5 attack-restriction existence flags, shared across the attacker seams.
• goading_players_for_creature_gated / gated must-attack helper — skip the goad sweep when no Goaded static exists, still returning the base goaded_by set (CR 701.15b).
• static_full_scans perf counter — incremented at the sole scan authority (check_static_ability), so revert-failing tests assert the per-element scan count stays 0 on restriction-free boards.

Gated seams

get_valid_attacker_ids, has_potential_attackers, validate_attackers, declare_attackers_with_bands (must-attack / scoped CantAttack / goad redirect), validate_blockers_for_player (MustBlock), execute_untap_with_choices + untap_excluded_ids (CantUntap), and a max_untap_subset_prompt early-bail. The untap path was the every-turn O(N²) — its regression guard drives the production execute_untap, not a prompt helper.

Tests

Revert-failing static_full_scans == 0 guards per seam, plus gate=true behavior tests (scoped/per-player CantAttack, MustBlock, CantUntap held tapped with scans > 0, goad redirect) proving no restriction is dropped.

Verification: cargo fmt clean, clippy -p engine --all-targets clean, cargo test -p engine --lib = 13690 passed / 0 failed.

Deferred (Tier-2 follow-ups)

• blocker_can_block_shadow (CanBlockShadow — pairwise/cold path, needs a different precompute shape).
• The AI single-permanent creature_must_attack wrapper (recomputes gates per call in AI enumerators; strictly faster than pre-fix, not a regression).
• Separately found O(N²): auto-pass legal_actions re-enumeration, taps_for_mana_aura_bonus, crew/saddle/station eligibility, expand_granted_activated_abilities.

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!