Dune/docs/MIRROR_WEAPON_ENGINE_AUDIT.md

Mirror Weapon: source and engine integration audit

Audited 6 September 2026. This is a proposed implementation contract, not activation or verification of Mirror Weapon gameplay. No runtime file was changed by this audit. Richese and combined expansion starts remain gated.

7 September follow-up: Portable Snooper and Stone Burner now have runtime foundations, superseding the historical absence noted below. A shared physical/effective weapon resolver and ordinary attack/explosion integration are recorded in EFFECTIVE_BATTLE_WEAPONS.md. Mirror plan admission remains disabled; copied choices, full outcome and cleanup integration are unfinished. Fresh bounded publisher retrieval did not settle the pending copied-disposal question.

Primary evidence and a retention correction

The actual face was visually reread at /tmp/dune-rules/choam-mirror-reading.png, alongside Stone Burner at choam-stone-reading.png. Both derive from the physical-component photograph recorded with its hash and limitations in RICHESE_COMPONENTS.md. This is publisher text visible on a physical component; the photographer, publication date and complete printing history remain unverified. No photograph is imported into the application.

Mirror Weapon is one physical Weapon / Special, canonical ID richese-mirror-weapon. Its instruction is to commit it in a Battle Plan, copy the opposing revealed weapon only when that card actually counts as a weapon, and use the copy first when order matters. Its final instruction is “Discard after use.” It does not supply a target selector, a selection of arbitrary weapons, or another player's physical card.

The CHOAM & Richese rulebook, pp4–6, establishes replacement Tooth/Artillery cards, one separate ten-card cache, and normal Treachery discard routing. Local publisher-text mirror: /tmp/dune-rules/choam-lelekan-mirror.pdf and .txt. Direct GF9 retrieval returned 403; fresh official indexed excerpts corroborated p4. Bounded official-domain Mirror searches yielded no card-specific clarification.

Do not infer compulsory winner disposal from that footer alone. The November 2020 FAQ, p8, gives winning battle cards a general keep option even without printed retention wording. Page1 expressly makes used Tooth and Artillery exceptions, including when their player wins; an unactivated winning Tooth can be kept. The 2021 Mirror face adds no explicit winner exception. Recommended ordinary composition is that a winning Mirror can be retained; copying a disposable weapon raises a separate inheritance question below. This corrects the earlier inventory's overly definite mandatory-discard interpretation without claiming a new Mirror erratum. Losing and mutual-loss cleanup still discard played cards normally. A traitor-decided battle preempts weapon effects under the base rules, pp10–11.

Weapon matrix

Here “copy” means an effective attack belonging to the Mirror player, evaluated against the relevant defenses. It never changes ownership or identity of the opposing card. Descriptions of already supported attacks below map to game/battle-cards.ts; their base/Ix behavior is reused rather than replaced.

Opposing revealed selection	Mirror behavior and integration consequence
Ordinary projectile, including Ix Hunter Seeker	Effective projectile attack. Resolve against the other player's projectile defense. Both original and copied attacks apply; using the copy first does not make ordinary combat an alternating combat system.
Ordinary poison, including Ix Basilia	Effective poison attack. Apply existing poison-defense behavior, including supported Portable Snooper.
Lasgun	Effective Lasgun. Feed the effective weapon into explosion detection, not merely ordinary leader lethality. Any actual Shield/Shield Snooper involved still produces the existing territory-wide explosion unless traitors preempt it.
Poison Blade	Copy both projectile and poison attack properties together. Do not ask the Mirror owner to select one.
Weirding Way in the weapon slot	Copy its projectile weapon role.
Chemistry in the weapon slot	Copy its poison weapon role. The opponent's pair must already be legal. Do not retroactively require the Mirror holder to possess the other defense that made the original Chemistry legal: Mirror is the committed weapon, and copies a card which already counts as a weapon.
Weirding Way or Chemistry in the defense slot	Do not copy that defense. Inspect the opponent's actual weapon slot instead, which may contain another valid weapon or nothing.
Poison Tooth	Copy the optional post-reveal attack, not the original owner's eventual answer. The Mirror owner chooses activation first, then the original owner chooses. Persist two separate choices. Reuse the established self-and-opponent attack evaluation; do not apply deaths between these declarations or count a leader death twice. Copy-related physical-card retention remains unresolved below.
Artillery Strike	Copy the attack on both leaders, suppression of surviving leader strength, and no-bounty battle effect. Apply battle-wide suppression once, not twice. No extra mode choice is created. Copy-related physical-card retention remains unresolved below.
Stone Burner	The copied effect has its own post-reveal choice, made before the original user's choice. Both effects replace ordinary leader/dial comparison with the same undialed-token comparison. A kill choice cannot be undone by the later ignore-strength choice. Underlying Stone Burner outcome/casualty implementation is not present, so do not silently reduce this to ordinary weapon kills.
No weapon, or Worthless in place of a weapon	No effective attack. Mirror remains its physical committed Weapon / Special; an occupied slot alone is insufficient evidence of an opposing weapon.
Reinforcements or Harass & Withdraw in place of a weapon	No effective attack from those cards. The Ecaz/Moritani rulebook p11 explicitly says they do not count as a weapon or defense. Their other effects are independent.
A second Mirror	Not a reachable legal physical inventory: the verified collection has exactly one. Reject duplicated physical custody. A future variant adding another copy needs a cycle rule; do not invent an infinite recursion or pretend two copies become an ordinary attack.

The existing FAQ-backed defense distinctions must survive copying: Chemistry defense protects against Tooth; Snooper-style protection does not. Shield Snooper is a shield, while defensive Weirding Way is not; the latter does not protect against Lasgun or Artillery. Generic versus named Voice applies to actual declared roles. These distinctions are confirmed by November FAQ pp4–5,8–9 and Ixian/Tleilaxu rules p11. Mirror should have a named Special-weapon Voice identity before revelation, not be classified using the opposing hidden weapon.

Preserve declarations, transform only effective resolution

1. Admit only the strict canonical Mirror as a weapon. Do not admit every kind: 'special' card. Mirror can support Weirding Way's alternate defense role because it is a real weapon even if it ultimately copies no attack.
2. Keep the original committed weapon ID in plans, ordinary Atreides prescience, whole-plan insight and Truthtrance promises. Revealing Mirror to Atreides is revealing Mirror, not revealing a future synthesized opposing weapon. Do not perform a hidden two-plan lookup in a public or owner-only projection.
3. After both plans actually reveal, derive an effective descriptor from those revealed physical faces and selected slots. A suitable pure helper is resolveBattleWeapons({attacker:{weapon,defense},defender:{weapon,defense}}). Each descriptor should retain physicalId, copiedFrom or null, effective attack kind, any post-reveal choice, and ordering dependencies. Do not overwrite a Card's name/kind/ID to make existing helpers accidentally work.
4. Bind any new choice queue to the battle event. With a copied Tooth or Stone Burner, order the Mirror choice before the corresponding original choice, irrespective of storm order. Use ordinary existing order where no copy dependency exists. Exact repeated submissions must not repeat a choice, random effect, casualty or payment.
5. Resolve traitors and explosion precedence, then calculate ordinary or special battle effects. Copy-first is not permission to skip the second ordinary weapon because its leader would die. Existing ordinary battle rules allow both leaders to die.
6. Derive retention from physical card identity plus actual effect use, separately from attack descriptors. Used-card lists, discard, Moritani retention, winner optional disposal, private hand custody and public inspectors must continue to refer to the physical Mirror, never to a second copy of the opponent's card.

Concrete current hook map

Location	Required change before activation
game/battle-cards.ts: kind arrays, pair/Voice helpers	Introduce strict identity-aware weapon admission and declared-role matching. Existing WEAPON_KINDS.includes(card.kind) cannot recognize a canonical Mirror transported as special. Avoid changing every Special's role.
engine.ts: validatePlan, findReachableBattlePlan, feasiblePrescience	Use the same legal weapon admission. Preserve physical IDs and promised slots in all plan searches; a selector-only change would leave authoritative plans impossible.
nextRevealedDecision	Currently detects physical poisonTooth and iterates storm order. It misses a copy entirely and orders it incorrectly. Replace or extend with a persisted effective-choice queue.
resolveBattle: explosion and battleCardEffects	Explosion currently checks physical kind === 'lasgun'. Both explosion and normal effects need the same effective descriptor, including own-side attacks and global suppression.
canRetainBattleCard and Moritani cleanup	Keep a shared physical cleanup policy. Do not turn the Mirror into a disposable physical Tooth by mutating its kind. Resolve the copy-disposal question before enabling affected pairings.
game/bots.ts: plan candidates, weaponKills, battleCardEffects, Tooth decision	Use legal physical candidates and effective attacks only from legitimately known plans. A hidden opposing hand is not an AI input. Handle ordered post-reveal copy decisions with the same effect evaluator.
Battle plan, revealed components and Rules presentation	Name and inspect the original Mirror. An additional public description can name the copied revealed weapon after both plans reveal. No extra acknowledgement is needed for a deterministic copy.

Portable Snooper is concurrently being integrated by the parent. Consume its final shared effective-defense helper and supplemental public defense state; do not duplicate or replace that work.

Genuine unresolved boundaries and recommended scope

• Copied compulsory disposal: the FAQ names physical Tooth/Artillery, while Mirror copies a weapon. The retrieved primary sources do not explicitly say whether their disposal exception also applies to the physical Mirror. Separate combat effects from cleanup and obtain a ruling before certifying those pairings. This does not justify blocking ordinary projectile/poison/Lasgun/Poison Blade/selected-role copies.
• Stone Burner foundation: the full effect is presently unsupported. Basic undialed counts follow physical forces minus dialed losses; ties use ordinary aggressor priority unless overridden. Advanced mixed/support-dependent dials can permit different physical casualty allocations, which now affect who wins; the present engine chooses those only for an already determined winner. Stone's original choice and allocation timing must be implemented/audited before its copied form. This is an underlying special-outcome problem, not uncertainty over whether Mirror copies a valid weapon.
• Higher modules: inactive leader skills may modify attacks, defenses or card roles. No combined leader-skill certification follows from the matrix. Two physical Mirrors are outside the verified inventory rather than a normal supported interaction.

Required verification before claiming the slice

Tests should cover every matrix row in both attacker/defender positions; paired defenses; no-attack copies; Mirror plus defensive Weirding Way; named Voice and physical prescience/Truth commitments; Lasgun explosion including advisors/spice and traitor preemption; copied Tooth choice order independent of storm order; once-only global Artillery suppression; exact physical retention/discard policy after its ruling; Moritani eligible-card filtering; JSON restoration between reveal and choices; stale event rejection; and identical unauthorized projections with different opposing hands. Run all four AI profiles through a complete supported battle, including a Mirror with no useful copy, without an acknowledgement or deadlock.

Five facets remain partial: source audit and component text are present; authoritative behavior, player controls, AI and integrated verification have not been activated by this document. Existing tests of ordinary battle cards are useful regression evidence, not proof of Mirror behavior.

Pending user clarification (2026-09-06)

The coordinating agent asked whether a Mirror copying an activated Poison Tooth or Artillery must inherit that card’s mandatory discard on victory, or whether the physical Mirror uses ordinary winner retention. No answer has been received at this checkpoint. The question does not concern Portable Snooper, whose ordinary winner retention follows the general FAQ. Do not infer an answer from the first preselected UI option or elapsed time.