feat(analysis): static ability-graph combo-candidate extractor (Engine B, PR-4a)

[lgray]

🤖 AI text below 🤖

Combo-detector series

Part of the staged, offline-first infinite-combo / loop detector. Each PR links its predecessor so humans can follow the implementation trail end to end.

Pos	PR	Delivers
PR-0	#4092	ResourceVector + modulo-resource loop equality (additive, no behavior change).
PR-1	#4097	Analysis sim harness around GameRunner::act feeding ResourceVector.
PR-2	#4119	Net-progress detect_loop → LoopCertificate + loop-certificate corpus harness.
PR-3	#4480	Live mandatory-loop winner shortcut for drain-cascade combos (CR 704.5a).
PR-4a	#4493 (this PR)	Engine B static ability-graph extractor: graph scaffold + 5 effect families + SCC + candidate coverability.
PR-4b	#4534	Engine B effect/trigger breadth + life-symmetry cost.
PR-5	#4547	cargo combo-verify CLI over the 53-row corpus.

Predecessor: PR-3 — #4480 — #4480 (Engine A's live mandatory-loop winner shortcut; Engine B introduced here is the over-approximate static proposer that Engine A's sound confirmer downstream-filters).

---

What

Adds analysis::ability_graph — Engine B of the infinite-combo detector: an offline, static extractor that, given a list of card faces, builds a directed ability/resource graph, finds strongly-connected components (Tarjan), and emits candidate cycles naming the unbounded ResourceAxis each would pump. This is the over-approximate proposer; Engine A (detect_loop, already shipped) remains the sound, stateful confirmer. Either runs standalone. Purely additive — zero game-behavior change.

This is PR-4a of the static extractor, sliced from PR-4: the graph scaffold + the five priority effect families (mana, counter, damage, tap, cast) + SCC + candidate coverability. The remaining effect families, trigger-event edge breadth, and the life axis land in PR-4b.

Design highlights

• Four exhaustive, no-wildcard classifiers are compile-time drift gates — a new combo-relevant variant is a compile error until classified:
  • effect_projection over all 207 Effect variants (5 modeled, rest Unmodeled)
  • trigger_axis over all 169 TriggerMode variants (Some-set = {cast, counter, tap, mana})
  • impl From<&ResourceAxis> for AxisKey over all 16 ResourceAxis variants
  • the AbilityCost fold over all 29 variants (polarity/sign-aware)
• Recall-first edge keying: a single color-agnostic AxisKey::Mana (an off-color cost satisfied by off-color production is a deliberate, recall-safe false positive that Engine A's exact floating-pool color accounting filters downstream) and a single AxisKey::Landfall.
• Engine A is untouched. net_progress_for / unbounded_axes_for move from private loop_check fns to pub(crate) ResourceVector methods that detect_loop now delegates to — byte-identical logic. Engine B's PR-4-only unbounded_production coverability override lives only in ability_graph and never touches Engine A.
• CandidateCycle is a distinct type from LoopCertificate — an unconfirmed candidate must never masquerade as a sound certificate (soundness invariant).

Comprehensive Rules

Edge/coverability semantics annotated and grep-verified: CR 500.8 (extra phases), CR 701.21a (sacrifice), CR 701.26a/b (tap/untap), CR 732.2a (loop shortcut), CR 106.1 (mana), CR 119.1 (life), CR 120.1 (damage), CR 122.1 (counters), CR 704.5a, among others. (Tarjan / coverability are annotated as CS theory, not CR.)

Testing

• ability_graph unit tests + the analysis suite green; cargo fmt/clippy -D warnings clean; full cargo test -p engine green.
• Discriminating revert-probe-backed tests for each load-bearing rule: the unbounded-production coverability override, the {Q}-untap-cost → Tap edge, the sacrifice-event producer polarity, and the color-agnostic mana collapse (a colored producer feeding a generic cost forms a candidate — flips to 0 candidates under per-color keying).
• Real-data smoke: Priest of Titania + Umbral Mantle forms a candidate naming Mana(Green) from a committed fixture (skips gracefully when the gitignored card export is absent).

[gemini-code-assist]

Code Review

This pull request introduces Engine B, a static ability-graph extractor that generates offline candidate cycles by building a directed resource graph and finding strongly-connected components. It also refactors the controller-scoped net-progress logic in loop_check.rs and resource.rs to be shared between Engine A and Engine B. The review feedback highlights two violations of the style guide's prohibition on boolean fields (R2) for tracking model completeness, and identifies a correctness issue where player-keyed axes are hardcoded to the opponent instead of dynamically resolving the active player ID.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

R2 Violation: Use of bool field any_unmodeled

According to the Repository Style Guide (R2), bool fields should not be used to express the design space. Instead, we should parameterize with a typed enum to carry more meaning and allow for future extensibility.

Consider introducing a ModelCompleteness enum:

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ModelCompleteness {
    FullyModeled,
    ContainsUnmodeled,
}

And replacing any_unmodeled: bool with completeness: ModelCompleteness in both AbilityNode and CandidateCycle.

References

1. R2. No bool fields — parameterize with existing typed enums ^(link)

[gemini-code-assist]

R2 Violation: Use of bool field any_unmodeled

According to the Repository Style Guide (R2), bool fields should not be used to express the design space. Consider replacing any_unmodeled: bool with the ModelCompleteness enum suggested on AbilityNode.

References

1. R2. No bool fields — parameterize with existing typed enums ^(link)

[gemini-code-assist]

Correctness: Player-keyed axes should dynamically resolve the correct player ID

Currently, AxisKey::Damage, AxisKey::Life, and AxisKey::Library are hardcoded to map to OPPONENT in axis_key_to_resource. While this works for opponent-directed loops (like drain or mill), it is incorrect for controller-directed loops (such as unbounded lifegain or self-mill advantage engines).

By dynamically inspecting the net resource vector, we can correctly attribute the unbounded axis to either CONTROLLER or OPPONENT based on which player's resource is actually moving.

        AxisKey::Damage => {
            if net.damage_dealt.get(&CONTROLLER).copied().unwrap_or(0) > 0 {
                Some(ResourceAxis::DamageDealt(CONTROLLER))
            } else {
                Some(ResourceAxis::DamageDealt(OPPONENT))
            }
        }
        AxisKey::Life => {
            if net.life.get(&CONTROLLER).copied().unwrap_or(0) > 0 {
                Some(ResourceAxis::Life(CONTROLLER))
            } else {
                Some(ResourceAxis::Life(OPPONENT))
            }
        }
        AxisKey::Library => {
            if net.library_delta.get(&CONTROLLER).copied().unwrap_or(0) != 0 {
                Some(ResourceAxis::LibraryDelta(CONTROLLER))
            } else {
                Some(ResourceAxis::LibraryDelta(OPPONENT))
            }
        }

[matthewevans]

Thanks for the large Engine B pass. I found one blocker in the current head.

AbilityCost::OneOf is disjunctive runtime semantics, but fold_cost currently treats it the same as Composite:

AbilityCost::Composite { costs } | AbilityCost::OneOf { costs } => {
    for c in costs {
        fold_cost(acc, c);
    }
}

That sums every alternative cost into one node, so a card with {G} or {2} ends up requiring/spending both branches. The existing type docs say OneOf means the paying player chooses one branch, and the runtime/payability code confirms that by detouring to ActivationCostOneOfChoice and using any() payability for sub-costs. For the static candidate generator this is not just a conservative false positive: it can become a false negative by introducing extra required axes or net-negative mana that the real loop never has to pay.

Please model OneOf as alternative cost branches rather than an AND fold. A good regression would build a candidate where one OneOf branch closes the cycle but another branch would add an unrelated/unsustainable requirement; the candidate should still be emitted for the payable branch. Composite can stay as the all-subcost fold.

Evidence checked: current PR head f4d08533f81bdbd194678b3b6c260cfb95c64357, GitHub files API diff, exact-head CI green/CLEAN, and local worktree inspection. Relevant repository evidence: AbilityCost::OneOf docs in types/ability.rs describe one-of-payment semantics; runtime casting.rs routes it through ActivationCostOneOfChoice; cost_payability.rs treats it as payable when any branch is payable.

[lgray]

🤖 AI text below 🤖

Thanks for the careful review. All four items are addressed in 98c1bdb1e.

BLOCKER — fold_cost treated OneOf like Composite. Correct — folding OneOf as an AND sum invents required axes / net-negative mana that no single branch pays, which for a static candidate generator is a false negative. Split OneOf out into fold_one_of, an optimistic envelope over the branches: produces = ∪, requires = ∩ (only axes every branch requires are unavoidable), net = per-axis max with missing-component = 0 (a cost only one branch pays is dodgeable → drops to 0), unbounded = ∪, completeness = join. Because the static generator is a proposer (Engine A is the sound confirmer that filters false positives), this maximizes recall and never fabricates a requirement. Composite keeps the all-subcost AND-fold.

Regression added as you suggested: a candidate where one OneOf branch closes the cycle while another would add an unsustainable requirement is still emitted — reverting fold_one_of to the AND-fold drops the candidate count 1→0 and the test fails. CR 118.12a (the rule AbilityCost::OneOf is itself annotated with — disjunctive/alternative cost); Composite annotated CR 601.2h.

any_unmodeled: bool → ModelCompleteness enum (gemini R2). Replaced on AbilityNode, CandidateCycle, and NodeAcc, with an exhaustive (no-wildcard) lattice-join merge() — consistent with this PR's drift-gate discipline (a future finer-grained variant forces a compile error rather than being silently absorbed).

Player-keyed axes (gemini). axis_key_to_resource now resolves CONTROLLER vs OPPONENT for Damage/Life/Library from the net sign (controller-directed lifegain / self-mill vs opponent drain / mill).

clippy -D warnings: 0; analysis::ability_graph: 23/23 (4 new tests).

[lgray]

🤖 AI text below 🤖

Rebased onto current main and classified two enum variants that main added since the branch point, surfaced by the exhaustive drift gates: ManaProduction::AnyCombinationOfObjectColors → the count-driven colorless-sentinel group in project_mana_production; TriggerMode::EntersOrHauntedCreatureDies → the deferred-to-PR-4b None group in trigger_axis, beside its sibling HauntedCreatureDies. No wildcard added. Verified green with the full CI command (clippy --workspace --exclude phase-tauri --all-targets --features engine/proptest + cargo test -p engine).

[matthewevans]

Reviewed current head 3a4e9e5. Prior OneOf blocker is resolved with a disjunctive envelope plus discriminating regression coverage; Gemini R2/player-axis findings are addressed on head. Exact-head CI is green and local merge check with current main is conflict-free.

[lgray]

🤖 AI text below 🤖

Thanks for the review. The OneOf-as-AND-fold blocker you flagged was on head f4d08533f; it's already fixed in the current head 3a4e9e509 (the branch was force-pushed after a rebase onto main since your review). Pointers in the current head:

• OneOf is no longer AND-folded. fold_cost now routes it to a dedicated disjunctive fold:
  • crates/engine/src/analysis/ability_graph.rs:1108 — AbilityCost::OneOf { costs } => fold_one_of(acc, costs) (explicitly "NOT AND-fold").
  • fold_one_of at :1180 models the branches as alternatives via an optimistic per-axis envelope (produces ∪, requires ∩ / per-axis MAX with missing=0), so a {G} or {2} card never requires/spends both branches and an unsustainable branch can't introduce a false-negative required axis.
• Regression test matching your suggested shape (one branch closes the cycle, another would add an unsustainable requirement; candidate still emitted for the payable branch) at :2245, with a discrimination probe that reverts fold_one_of to the AND-fold.

Also addressed in the same head (gemini review comments):

• any_unmodeled: bool → typed ModelCompleteness enum (:927, lattice join), any_unmodeled fully removed.
• axis_key_to_resource now resolves the player by net sign instead of hardcoding OPPONENT (:1564, test axis_key_to_resource_resolves_player_by_net_sign at :2366).

CI is green on the current head. Could you re-review 3a4e9e509 when you have a moment? Happy to adjust further.