Implement five CHOAM Nexus Cunning effects with private costs and recovery

docs/COMPONENT_INVENTORY.md

@@ -1,5 +1,7 @@
 # Component inventory and verification ledger
 
+**CHOAM Nexus Cunning update, 10 September 2026:** the existing physical Nexus can fund one of five supported Worthless effects with an actual held Treachery Card of any category. Shared controls show the cost card separately from the selected effect and retain its full inspector; the engine preserves its canonical identity through allowance, cancellation and legitimate payment loss. No duplicate Worthless piece or artwork is created. The printed family has six effects: Kull Wahad remains unavailable. [NEXUS_CHOAM_RUNTIME.md](NEXUS_CHOAM_RUNTIME.md) records thirty new regressions, browser inspection and private recovery; complete CHOAM and module acceptance remain gated.
+
 **Emperor Nexus Cunning update, 10 September 2026:** five existing ordinary counters can temporarily count as Sardaukar for one Advanced battle after the native Karama response allows the declared enhancement. No starred piece is created or transferred; casualties remain ordinary counters. Shared strength/support limits drive the editor and bots, and public notices distinguish pending versus active roles. This uses existing Nexus and force components without new artwork. Five-counter eligibility, existing commitments and all other Emperor mode gates remain explicit. [NEXUS_SARDAUKAR_RUNTIME.md](NEXUS_SARDAUKAR_RUNTIME.md) records 35 new cases, browser inspection, private recovery and the full-project checks; complete module acceptance remains pending.
 
 **Bene Gesserit Nexus Cunning update, 10 September 2026:** existing physical advisors now have an owned whole-territory conversion checklist with counts, select-all control and explicit blocked reasons. One played Nexus card opens one Karama response for the entire public selection; no additional card, token or artwork is created. Legal selected groups become fighters in place without consuming shipment, movement or spice. Fresh accompanied advisors and storm cases remain explicitly pending rulings. Borrowed Voice, Betrayal and incomplete mode starts remain gated. [NEXUS_ADVISOR_RUNTIME.md](NEXUS_ADVISOR_RUNTIME.md) records the bounded runtime and verification status; final acceptance is pending.

docs/IMPLEMENTATION_STATUS.md

@@ -1,5 +1,7 @@
 # Dune implementation status
 
+**CHOAM Nexus Cunning checkpoint, 10 September 2026:** [NEXUS_CHOAM_RUNTIME.md](NEXUS_CHOAM_RUNTIME.md) records five native effects using one actual Treachery Card in Basic and Advanced. Shared controls inspect the real cost independently of the selected effect; all four bots use projected legality. Karama retains the cost and spent Nexus; actual intervening cash-in fizzles and resumes the original operation. Independent review fixed saved movement, revival and storm orders accepting valid-looking replacements. **Types, lint, all 4,042 offline tests, production build and 40 HTTP/session tests pass.** Thirty new cases include real paid Nullentropy, private views, physical disposal and concurrent SQLite outcomes. Two three-seat browser rooms passed phone declarations, allowance/cancellation and all six private refreshes. All **3,484** opening room versions/hashes remain unchanged; only two browser and thirty HTTP rooms were added. The printed family has six effects: Kull Wahad remains unavailable, as do unfinished Secret Ally/Betrayal and full module starts. Existing server reused, no restart due, automation remains removed.
+
 **Grumman stack cancellation checkpoint, 10 September 2026:** [GRUMMAN_PLACEMENT_CANCELLATION.md](GRUMMAN_PLACEMENT_CANCELLATION.md) records the reproduced failure of printed Karama against a native Mentat placement after a legal Collection stack. Cancellation now preserves the existing stack without requiring distinct occupied locations. Independent SQL review also fixed allowance accepting unrelated duplicate physical token IDs; both outcomes validate the same inventory. Existing denial semantics remain unchanged. **Types, lint, all 4,012 offline cases, production build and 40 HTTP/session cases pass.** Six new cases cover Basic/Advanced, low population, unchanged income, competing cancellation/allowance, private restoration and malformed records. Browser phone declaration, desktop/phone cancellation and three-seat refresh pass. The hourly restart preserved all **3,453** opening games and restored twelve earlier private seats; final comparison leaves those same versions/hashes unchanged, with one new browser room and thirty HTTP rooms added. New [Ixian replacement](NEXUS_IXIAN_REPLACEMENT_RULES.md) and [Fremen Nexus](NEXUS_FREMEN_RULES.md) audits record remaining source and privacy boundaries. No new Nexus effect or release gate was enabled; automation stays removed.
 
 **Emperor Nexus Cunning checkpoint, 10 September 2026:** [NEXUS_SARDAUKAR_RUNTIME.md](NEXUS_SARDAUKAR_RUNTIME.md) records five ordinary counters temporarily using Sardaukar strength and support in one Advanced battle. Physical counters, starred reserves and ordinary losses remain distinct. Shared editor and bot calculations handle the Fremen exception and Salusa support. Review fixed a canceled-enhancement Prescience deadlock and retained durable winner casualty choices across competing SQLite requests. **Types, lint, all 4,006 offline tests, production build and 40 HTTP/session tests pass.** Thirty-five new cases cover independent counter arithmetic, real Homeworld thresholds, future commitments, hidden information and recovery. Two three-seat browser rooms passed desktop/phone allowance, cancellation, reanswer, sealed planning and private refresh. All **3,421** opening room versions/hashes remain unchanged; only thirty HTTP rooms and two browser rooms were added. Fewer-than-five interpretation, Emperor Secret Ally, Betrayal and complete module acceptance remain gated. No release gate opened; no restart was due, and automation remains removed.

docs/NEXUS_CHOAM_RULES.md

@@ -0,0 +1,76 @@
+# CHOAM Nexus Cunning
+
+Source audit: 2026-09-10. This source audit defines native Cunning and its saved-receipt contract. The separate [runtime checkpoint](NEXUS_CHOAM_RUNTIME.md) implements five effects; this audit does not resolve the other CHOAM Nexus panels or lift any [Nexus/expansion release gate](NEXUS_CARD_RUNTIME.md).
+
+## Authority and printed scope
+
+The [original GF9 Nexus component photograph](https://boardgamegeek.com/image/7767032/dune-ecaz-and-moritani), independently inspected at `/tmp/dune-nexus-cards.jpg`, permits native CHOAM to discard any Treachery Card to use any Worthless Card special effect. The choice is one held physical card and one effect. It does not require holding the corresponding named Worthless card, transform the chosen card's printed identity, grant money, or supply a phase-long conversion permission.
+
+The [GF9 Ecaz & Moritani rulebook, p.11](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf#page=11) classifies Cunning as enhancement of a native advantage. The holder must remain unallied, and a played Nexus Card is discarded. Those common conditions still apply. Publisher-indexed text and the previously fetched [publisher-authored E3 mirror](https://gamers-hq.de/media/pdf/0f/7a/86/Dune_EcazMoritani_Rulebook_EN.pdf) were used; no community compilation supplies a ruling.
+
+CHOAM's Treachery advantage is on the ordinary faction-rules page, before its Advanced advantages. Therefore this Cunning is usable in Basic and Advanced; it is not CHOAM's separate once-per-game special Karama. [GF9 CHOAM & Richese rules, pp.7–8](https://www.gf9games.com/dune/wp-content/uploads/2021/11/CHOAM-Rulebook-low-res.pdf#page=7)
+
+## Six effects and their timing
+
+E2 lists **six**, not five. Five have current ordinary engine effect handlers; Kull Wahad retains its separate unfinished reaction subsystem.
+
+| Chosen effect | Printed outcome and timing |
+| --- | --- |
+| Baliset | During Shipment and Movement, prevent a player moving into a territory CHOAM occupies; shipment remains permitted. |
+| Jubba Cloak | Protect CHOAM forces in one territory from the moving storm. |
+| Kull Wahad | On a player's attempted Karama play, prevent that player playing Karama during this phase. |
+| Kulon | One extra territory of movement on CHOAM's own Shipment and Movement turn. |
+| La La La | During Revival, prevent a player taking Free Revival. |
+| Trip to Gamont | During Mentat Pause, return one other player's force to its reserves. |
+
+None lists an additional spice fee. Cunning changes the required card identity, not timing, targets or quantity. It does not grant an extra movement action, make Jubba protect spice, or make a shipment count as Baliset movement. [E2 p.7](https://www.gf9games.com/dune/wp-content/uploads/2021/11/CHOAM-Rulebook-low-res.pdf#page=7)
+
+A purchased or gifted card already in CHOAM's hand can supply the discard, including a Worthless card, weapon, defense, special card, Cheap Hero or Richese card. Existing reservations and binding commitments still matter. Do not require the selected card's name to match the effect or physically create a named Worthless card. Playing a printed Karama as this discard cost does not also activate its Karama power; no additional once-per-game use is earned or spent.
+
+## Cancellation and physical disposal
+
+E2's Karama table permits prevention of CHOAM's special-effect Worthless discard. Applying that rule to Cunning's enhancement is ordinary native-advantage composition: the selected Treachery card remains held when its discard is prevented, the chosen effect does not occur, and the already played Nexus stays spent. Use one ordinary CHOAM-effect response, not separate cancellation windows for conversion and effect. [E2 p.12](https://www.gf9games.com/dune/wp-content/uploads/2021/11/CHOAM-Rulebook-low-res.pdf#page=12), [E3 p.11](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf#page=11)
+
+This differs from Bene Gesserit's expressly discarded Worthless-as-Karama when that conversion is prevented. That specific FAQ consequence does not transfer to CHOAM. The general FAQ permits stopping one native-ability use; CHOAM's later table supplies its own phase-scoped wording. [GF9 November FAQ, p.7](https://www.gf9games.com/dune/wp-content/uploads/2020/11/Dune-FAQ-Nov-2020.pdf#page=7)
+
+On an allowed use, the **original physical card** crosses into discard exactly once. Its canonical descriptor remains intact. For example, a poison weapon discarded to obtain Kulon still qualifies for any applicable actual-discard Ecaz income; hand-discard Chemistry is not promoted to a poison weapon. A canceled declaration creates no such discard event, income or Semuta opportunity. Reuse the [Ecaz physical-discard contract](ECAZ_POISON_INCOME_RULES.md) and ordinary fresh-discard continuation; a selected effect label must never overwrite card type.
+
+The effect choice and native use may be public without revealing the rest of CHOAM's hand. Do not add a public poison-income message that identifies a privately discarded category. Preserve existing discard visibility. Successful disposal must pass through the current Semuta/reservation handling, and an interruption must resume the chosen effect and its original parent once. A later retrieval of the discarded card does not undo an already earned effect or permit replaying its receipt.
+
+## Existing boundaries to preserve
+
+- **Kull:** [the existing source update](CHOAM_KULL_SOURCE_UPDATE.md) leaves counter priority, BG conversion timing, interrupted-card custody and unfunded overbid recovery unresolved. Cunning does not settle those interactions. No new question was sent. Omitting Kull from a supported five-effect checkpoint must be explicit; it cannot be presented as all CHOAM Cunning.
+- **Phase cancellation scope:** the existing [Worthless continuation audit](CHOAM_WORTHLESS_CONTINUATION_AUDIT.md) records unresolved scope across other physical copies or effects. Current runtime binds a canceled physical card for the phase. A new Nexus use should preserve the selected policy rather than silently broaden or erase that historical restriction. The spent Nexus itself cannot be retried.
+- **Inherited effect boundaries:** fixed Ornithopter range versus Kulon, reactive movement/Revival/storm parents, special force custody, No-Field Gamont and other already documented exclusions remain properties of the selected effect. They are not reasons to reject an ordinary source-supported Cunning use with a different effect.
+- **No fresh hidden reaction policy:** native CHOAM's existing effect opportunities and public circumstances supply the interaction points. Extend those owner's controls without pausing only because a secret Nexus card exists, adding compulsory no-choice confirmations, or reopening another player's completed action. Kull retains its separate pending policy.
+
+## Pure saved receipt and integration contract
+
+This is engineering design, separate from publisher rules. Keep the authorization receipt independent from the physical card and the existing effect's continuation.
+
+```ts
+type NexusChoamEffect =
+  | 'baliset' | 'jubba' | 'kull' | 'kulon' | 'laLaLa' | 'gamont';
+
+type NexusChoamReceipt = {
+  version: 1;
+  event: string;
+  owner: string;
+  turn: number;
+  phase: number;
+  effect: NexusChoamEffect;
+  card: string; // original physical ID; server only
+  roster: { id: string; faction: FactionId }[];
+  signature: string;
+};
+```
+
+[game/nexus-choam.ts](../game/nexus-choam.ts) exports the six-name `CHOAM_NEXUS_EFFECTS` map, `NexusChoamEffect`, `NexusChoamContext`, `NexusChoamReceipt`, `createNexusChoam(context, owner, phase, card, effect)` and `validateNexusChoam(context, receipt)`. Context contains the current turn and ID/faction roster only. Intrinsic validation checks exact keys, effect/phase compatibility, original native owner/roster, nonempty card ID, safe numbers and signature. The event is `JSON.stringify(['nexusChoam', turn, phase, owner, card, effect])`. Kull's intrinsic timing admits phases 0–8; this does not authorize playing its still-gated effect. Historical validation neither reads private hands nor requires the card still held, CHOAM still unallied or the old Nexus still in discard. The engine owns canonical card validation, held Nexus/unallied eligibility, exact original effect source and physical custody.
+
+The engine should separately bind progress (`pending`, `canceled`, `discarded`, `complete`) and the exact original resume context. An independently retained latest-progress marker prevents deleting or rewinding the detailed frame from restoring the Nexus or causing another discard. Bind target, territory/sector, elite type, No-Field event and movement/revival/storm parent only where the selected effect uses them. Avoid freezing unrelated hidden hands, resource changes or nested response passes in a signature.
+
+Integrate through the existing native effect validator with an explicit selected effect, preserving the original selected Card. Do not construct a fake Worthless hand entry merely to satisfy name-based checks. On cancellation, validate and resume the existing denied suffix without applying or paying for the chosen effect. On allowed disposal, record the physical event before yielding to a fresh-discard child; the continuation must know whether the card and effect have already committed. Reject stale actor/event/effect/target/custody before costs or private output.
+
+Four focused pure tests in [tests/nexus-choam.test.ts](../tests/nexus-choam.test.ts) pass: six-effect timing, later-turn/reordered-roster recovery with private getter traps, edited receipt rejection, and malformed/foreign creation. Type-aware lint and whitespace checks pass. These are receipt checks, not gameplay integration certification.
+
+Meaningful integration tests should cover all five currently supported effects in their genuine producers, Basic/Advanced parity, arbitrary canonical card families, successful and canceled selected-card custody, normal Worthless parity, denied-card phase behavior, poison-income and fresh-discard children, real BG/Box interruption, exact saved parent, private owner projection, bots, JSON/CAS recovery and failed-action immutability. Kull is a named remaining effect until its own rules and runtime are resolved. No completed engine integration or gameplay verification is claimed here.

docs/NEXUS_CHOAM_RUNTIME.md

@@ -0,0 +1,43 @@
+# CHOAM Nexus Cunning runtime
+
+This checkpoint integrates native CHOAM Cunning with five existing Worthless effects, in Basic and Advanced. It does not complete CHOAM, Nexus or the expansions. The [source contract](NEXUS_CHOAM_RULES.md) lists **six** effects: Kull Wahad's Karama-prevention reaction remains explicitly unavailable. CHOAM Secret Ally and Betrayal remain outside this implementation.
+
+## Physical cost and timing
+
+An unallied CHOAM player holding the CHOAM Nexus chooses one actual held Treachery Card and one supported effect. The card need not have the corresponding Worthless name. The engine preserves its original identity, ownership and any reservations; it does not manufacture a named Worthless card or grant a turn-long conversion ability.
+
+The existing timing and target controls remain authoritative:
+
+- Jubba Cloak protects CHOAM forces in one threatened territory during its moving-storm response.
+- La La La prevents a selected player's free force revival, including the existing response before a mixed free/paid revival commits.
+- Baliset prevents movement into a CHOAM-occupied territory, including the existing declared-movement response. It does not prevent shipment.
+- Kulon adds one territory of range before an available CHOAM move, without granting another movement action. The fixed Ornithopter-range combination retains its existing ruling boundary.
+- Trip to Gamont returns one selected opposing physical force during Mentat. Existing typed-counter, No-Field and deferred-victory behavior remains in force.
+
+Playing Cunning spends its physical Nexus card and opens one ordinary CHOAM-effect Karama response. Cancellation leaves the selected Treachery Card held and the Nexus spent. Allowance discards the actual selected card once and applies the chosen effect. Its real discard category governs other consequences, including applicable private Ecaz income; the selected Worthless effect does not change that category.
+
+## Controls, policy and private information
+
+The engine's owner-only `choamWorthless.plays` separates `source`, `effect`, the actual `card`, an optional Nexus `event`, and a blocking reason. The original printed-card descriptor remains available. [Shared options](../game/choam-power-options.ts) construct ordinary card actions unchanged and add the explicit effect/event only for a Nexus use. They fence stale events, actor identity and current interruptions, and use the server's source-specific blocking reason.
+
+The [cost selector](../components/choam-power-cost.tsx) is reused by the existing [storm](../components/choam-storm.tsx), [revival/range](../components/choam-worthless.tsx), [movement prevention](../components/choam-baliset.tsx) and [force return](../components/choam-gamont.tsx) panels. It names and inspects the real cost card separately from the effect, supports transport-busy state, and exposes blocked choices without offering an illegal action. Kull Wahad has a visible unavailable explanation. Public response text identifies the chosen effect rather than disclosing the private cost card's name.
+
+All four bot profiles use the same projected plays. They preserve printed effects first, then prefer lower-value legal Nexus fuel, retaining their existing public-target policies. Easy's existing policy of allowing free revival remains unchanged. The ordinary Trip to Gamont preservation policy still reserves that printed card during a closing market or cash-in even though playing it must wait for the next legal window. These are legal policy extensions, not a new AI calibration claim.
+
+Existing reactive windows depend on public circumstances rather than whether CHOAM holds a matching card. Cunning uses those same windows, so holding a private Nexus card does not introduce an identifying public wait. Opponents receive no private cost list. Saved engine receipts, cancellation and physical disposal are handled by the engine; consumer code does not reconstruct an opportunity from card names or old saves. The existing fresh-discard/Semuta priority remains unfinished and gated; this checkpoint does not implement a Semuta interruption for these effects.
+
+## Recovery evidence
+
+The saved receipt binds the physical card, selected effect, original phase and owner, declared target and the specific suspended movement, revival, storm or Mentat context. Independent review reproduced legal-looking replacements of a pending movement quantity, revival quantity/price and storm distance. Those edits now reject before reads, automatic normalization or either outcome can write state. Historical completed records do not freeze unrelated future resources.
+
+Actual paid Nullentropy searches can suspend and restore the response. If CHOAM legitimately consumes the selected card in an intervening cash-in, Cunning fizzles with its Nexus still spent and resumes the original operation once. Cancellation retains the card and applies the existing phase block. Production SQLite tests cover private refresh and simultaneous cancellation versus the final pass; exactly one version wins.
+
+## Verification
+
+Five new consumer regressions are in [controls](../tests/nexus-choam-controls.test.ts) and [bots](../tests/nexus-choam-bots.test.ts). They exercise actual fixture-generated windows for all five supported effects, submitted source actions, the real cost-card inspector, blocked Kull and reserved cards, stale events, actor/interrupt fences, private-field traps, all four policies, and unchanged printed actions. The combined consumer, existing Worthless/storm/movement/Gamont, Nexus guidance and reference selection passed **150/150** tests. Type-aware lint passed for all owned code and tests; all nine local links in this document resolve. The log is `/tmp/dune-choam-consumer-tests.log`.
+
+Final integrated checks pass: **types, lint, all 4,042 offline tests, production build and 40 HTTP/session tests**. Thirty new cases cover the pure receipt, engine, consumers, independent saved-parent review and production SQLite matrices. Logs are `/tmp/dune-choam-{check,build,http}.log`.
+
+Two isolated three-seat browser rooms passed actual phone declarations, desktop/phone response inspection and all six private refreshes. `GDP8NNRE` version 4 allowed Baliset: the pending two-force movement was prevented, the three original source forces remained and the real Stunner payment was discarded. `WJTUH62T` version 5 canceled Jubba Cloak: Slip Tip stayed held, the Nexus stayed spent, and continuing the original storm removed four CHOAM and three opposing forces. No phone overflow or page errors were observed. `/tmp/dune-choam-restore.cjs` performs read-only private restoration checks.
+
+The opening backup and final comparison preserve all **3,484** older room versions and state hashes. Only two browser rooms and thirty HTTP-test rooms were added, for 3,516 total. The existing server was reused; no hourly restart was due. Automation remains removed. These checks do not certify a complete six-effect CHOAM advantage or full module play.