Dune/docs/NEXUS_CHOAM_SECRET_ALLY.md

CHOAM Nexus Secret Ally prototype

13 September 2026. The Spice Collection trade is Prototyped in the development Nexus module. Its battle inspection alternative is still missing. This checkpoint does not enable normal Nexus starts, certify the full card family, or open a publication gate.

Source and behavior

The printed CHOAM card's Secret Ally panel allows a Worthless card to be discarded during Spice Collection for two spice, or a random unused opposing hand card to be inspected after a victory. The common source contract records the photographed publisher component and publisher lifecycle rules. Native Cunning has different costs and effects and is not reused as a substitute for this panel.

Only an unallied holder with CHOAM absent may use this trade, in Basic or Advanced. The server quotes the holder's actual Worthless cards. The player selects one; its printed identity and physical discard custody remain intact. Both that card and the CHOAM Nexus card are spent, and two spice are paid from the bank exactly once. No native faction identity, market sale, Cunning conversion, or Auditor payment is introduced. No blanket Nexus Karama immunity is inferred: this trade uses the absent-faction panel rather than a native CHOAM advantage.

Collection readiness remains optional; continuing without trading keeps the cards. The action cannot interrupt a decision, Truthtrance, committed discard, exchange, or queued automatic Collection choice. It may still be used while its owner is ready if Collection has not ended. Exhaustive simultaneous Collection combinations remain part of the later integration pass.

Connected paths

• game/nexus-choam-trade.ts provides the private quote and saved receipt checks. game/engine.ts applies payment, Nexus/card custody and the semantic fresh discard continuation. The completed history remains private server evidence.
• game/nexus-choam-trade-options.ts supplies the shared human/AI action. components/nexus-choam-trade.tsx provides a card picker, inspector, costs and availability reasons at the table. All four AI profiles use eligible trades.
• The existing JSON room state stores the receipt. No database migration or server restart is required. Recovery validates the already-paid outcome and retires the discard; it never credits spice a second time.

After-victory inspection audit

The other printed Secret Ally choice applies only after its holder wins a battle. It inspects exactly one random Treachery Card held by the opposing combatant that the opponent did not use in that battle. Normal and traitor wins qualify. Mutual-traitor and Lasgun-shield explosion results have no winner and do not. “Used” is the physical set already produced by the battle quote for the opponent, including a Cheap Hero, cards played in weapon or defense slots and a late Portable Snooper. A used card remains excluded if another effect later retains it. The effect neither transfers nor discards the inspected card.

The battle engine must preserve the opposing used-card IDs with the resolved battle event before mandatory loser disposal. The existing Auditor candidate filter is reusable because it removes exact physical used IDs from the current opposing hand. The Nexus effect still needs its own one-card sampler and receipt; it must not borrow Auditor survival, payment or cancellation behavior. A successful use discards the held CHOAM Nexus card once, records the sampled snapshot once and projects the face only to its holder. The public chronicle may name the use, winner and opponent, but not the inspected face.

The safe continuation point is the existing final finishBattle board boundary: after mandatory and optional battle-card cleanup, Moritani retention, battle income, technology, capture, Auditor, Face Dance and Caladan reinforcement, and before another battle or phase begins. No existing choice occurs at that point for every possible winner. Opening a pause only when the winner secretly holds the CHOAM Nexus card would reveal that hidden identity. Precommitting a conditional use before the result would remove the printed after-victory choice. A universal use-or-pass window would preserve secrecy and the full choice, but would also ask winners without the card to pass. The user has been asked which product exception to adopt; no timing policy is implemented while that answer is pending.

The retrieved Nexus sources neither establish an ordinary Karama response to this Secret Ally play nor grant blanket Nexus immunity. The Collection trade is currently direct and this inspection must not inherit the native Auditor's Karama/payment window by analogy. Cancellation remains an explicit later audit boundary rather than an invented prototype rule.

Focused evidence and remaining scope

Run npm test -- nexus-choam-trade. Focused cases cover Basic/Advanced payment, physical custody, all four AI profiles, private rendered controls, wrong-mode and stale action rejection, Truthtrance locking, damaged saved receipts and JSON continuation. Production SQLite tests exercise competing trades, seat restoration, replay rejection and an already-paid discard resume.

The after-victory inspection still needs an original battle receipt, exclusion of the opponent's used cards, a private one-card sample and composition with winner cleanup. Complete Nexus games, broader Homeworld interactions, strategic choice between the two Secret Ally uses and visual acceptance of that full family remain unfinished. Prototype evidence is deliberately narrower than complete compliance.