feat(engine): Twinning Staff copy-count replacement

[danielbrock58]

Implements Twinning Staff and the broader "copy an additional time" replacement class.

What

"If you would copy a spell one or more times, instead copy it that many times plus an additional time. You may choose new targets for the additional copy."

Approach (building block, not a one-off)

• Modeled as a CopySpell replacement carrying a QuantityModification — the same shape as the token/counter doubling family (Doubling Season, Hardened Scales), so it generalizes to "plus N additional times", not just Twinning Staff.
• Parser composes nom combinators along independent axes (count / additional / singular-plural time(s)); no verbatim-phrase matching. Covers plus an additional time and plus N additional times.
• New CopyCountStatus enum (not a bool) guards the per-copy resume so the bonus applies to the copy event once, not per copy.

Rules fidelity (CR annotations verified against MagicCompRules)

• CR 707.10 — copying a spell vs. an ability (Staff affects spell copies only)
• CR 614.1 / 614.1a — replacement watches for an event that would happen; "instead" replacement
• CR 614.5 — a replacement effect doesn't invoke itself repeatedly (the anti-runaway guard)
• CR 616.1 — additive modifications are order-independent (no ordering choice needed)

Fixes

• Runaway copy loop when copying a targeted spell with Twinning Staff (each per-copy retarget pause re-applied the bonus → dozens of copies). Now exactly base + 1.

Tests

7 regression tests (parser base + plural/numbered variants; engine: +1 copy, zero-copy guard, opponent's Staff ignored, ability-copies excluded, targeted-spell no-runaway). Full engine suite: 434 passed, 0 failed.

Commits

• implement copy-count replacement
• stop runaway copy loop on targeted spells
• typed CopyCountStatus, modular plural parse, zero-copy guard
• correct CR annotations to verified rules
• avoid usize->u32 narrowing in the copy-count helper

[gemini-code-assist]

Code Review

This pull request implements MTG rules CR 707.10, CR 614.1a, and CR 614.5 to support copy-count replacement effects (such as Twinning Staff) for copy-spell abilities, introducing a CopyCountStatus enum to guard against runaway loops. The review feedback focuses on aligning the parser dispatch and implementation in oracle_replacement.rs with the R1 architectural rule, specifically recommending the elimination of scan_contains in favor of direct nom parser delegation and refactoring the manual loop into modular, composed nom combinators.

[gemini-code-assist]

[MEDIUM] Avoid using scan_contains for parsing dispatch. Evidence: crates/engine/src/parser/oracle_replacement.rs:407. Why it matters: Using scan_contains for parsing dispatch violates the R1 architectural rule of using nom combinators on the first pass. Suggested fix: Call parse_copy_count_replacement directly and let the nom parser handle the "would copy a spell" check.

    if let Some(def) = parse_copy_count_replacement(&lower, &text) {
        return Some(def);
    }

References

1. R1. Nom combinators on the first pass — no exceptions. Every new parser dispatch under crates/engine/src/parser/ must use nom 8.0 combinators or delegate to existing helpers. Findings: any new .contains("..."), .starts_with("..."), .ends_with("..."), .find("..."), or .split_once("...") used for parsing dispatch in non-test parser code. ^(link)

[gemini-code-assist]

[MEDIUM] Avoid verbatim string equality and fragile manual loops for parsing Oracle phrases. Instead, decompose compound phrases into modular, reusable parsers for constituent parts (such as the copy subject and the quantity modifier) and compose them using idiomatic nom combinator aggregates to prevent combinatorial explosion and improve maintainability.

fn parse_copy_spell_subject(input: &str) -> IResult<&str, &str> {
    tag("would copy a spell")(input)
}

fn parse_plus_modifier(input: &str) -> IResult<&str, u32> {
    let (input, _) = tag("plus ")(input)?;
    let (input, n) = alt((value(1u32, tag("an")), nom_primitives::parse_number))(input)?;
    let (input, _) = tag(" additional ")(input)?;
    let (input, _) = alt((tag("times"), tag("time")))(input)?;
    Ok((input, n))
}

fn parse_copy_count_replacement(lower: &str, original_text: &str) -> Option<ReplacementDefinition> {
    use crate::types::ability::QuantityModification;

    let additional = nom_on_lower(lower, lower, |i| {
        let (i, _) = take_until::<_, _, OracleError<'_>>("would copy a spell").parse(i)?;
        let (i, _) = parse_copy_spell_subject(i)?;
        
        let mut input = i;
        loop {
            if let Ok((remaining, n)) = parse_plus_modifier(input) {
                return Ok((remaining, n));
            }
            let (next_input, _) = nom::character::complete::anychar(input)?;
            input = next_input;
        }
    })
    .map(|(n, _)| n)?;

    Some(
        ReplacementDefinition::new(ReplacementEvent::CopySpell)
            .quantity_modification(QuantityModification::Plus { value: additional })
            .description(original_text.to_string()),
    )
}

References

1. R1. Nom combinators on the first pass — no exceptions. Every new parser dispatch under crates/engine/src/parser/ must use nom 8.0 combinators or delegate to existing helpers. ^(link)
2. Avoid verbatim string equality for parsing Oracle phrases as it bypasses the robust nom-based parser and creates fragile matches. Instead, decompose compound phrases into modular, reusable parsers for constituent parts and compose them using idiomatic combinator aggregates.