Integrate CHOAM Nexus Cunning Kull with source-aware costs

docs/CHOAM_KULL_DESIGN.md

@@ -22,7 +22,9 @@ The wider publisher cancellation scope across other physical copies or Worthless
 
 The explicit `kull` development profile admits Basic or Advanced CHOAM with classic factions, the physical CHOAM and Ix Treachery decks, and **no optional modules**. It does not introduce Ixian/Tleilaxu factions merely because their physical deck is present. Basic uses ordinary printed Karama; Advanced additionally admits BG substitutions and the existing legal special powers of that roster. `initializeKullGameForAudit` opts the newly initialized Game into `kullPreview`; older saved games and ordinary public starts are not retrofitted.
 
-The visible preview warning and closed expansion/module gates remain mandatory. Printed Kull's preview is not Nexus Cunning Kull, complete CHOAM, full expansion certification or deployed evidence. Checkpoint verification belongs to the integration owner, not this source/guidance update.
+The separate `nexus-kull` profile admits fresh two-to-six-seat Basic or Advanced native CHOAM plus classic factions, exactly the physical CHOAM/Ix Treachery decks and **Nexus alone**, without physical Sandtrout. `initializeNexusKullGameForAudit` sets `nexusKullPreview` and shared `kullPreview`; it does not retrofit new choices into saved games. Unallied native CHOAM with the actual CHOAM Nexus may choose eligible own canonical Treachery fuel at the pending Karama opportunity. Other expansion factions/modules, Semuta and Richese Betrayal remain excluded; other Nexus previews retain the Kull guard. See the [source/cost boundary](NEXUS_CHOAM_RULES.md#kull-source-cost-and-action-boundary) and [runtime evidence](NEXUS_CHOAM_RUNTIME.md#bounded-nexus-kull-profile).
+
+Both profiles require the visible preview warning and closed public expansion/module gates. The old `kull` profile remains printed-only without Nexus. This bounded Cunning interaction is verified locally, with broader verification **Partial**, not complete CHOAM, full Nexus/expansion certification or deployment evidence. Prior printed-Kull evidence remains scoped to the older preview.
 
 Ordinary cancellation with a live Truthtrance battle or shipment promise must pass the existing pure `assertKaramaPromiseFeasibility` post-cost proof. An unsupported/unprovable suffix is rejected actor-privately before a Kull offer or cost. Proven supported Voice, Prescience, elite, support and aid cancellation paths remain interruptible; no-obligation paths remain unaffected. This is an incomplete preview composition, **not** a publisher prohibition. Do not publicize an unvalidated attempt, release its promise or speculatively execute random effects merely to prove feasibility.
 
@@ -59,27 +61,27 @@ Special branches bypassing `spendKarama()`:
 
 ## State and API responsibilities
 
-The pure [Kull module](../game/choam-kull.ts) owns `KullPhaseRestriction`, `activeKullRestrictions`, `kullBlocksKarama`, restriction/attempt-stamp validation, `distinctKullCounter`, `kullNativeCostCards` and `kullCounterCards`. It validates stamped phase policy and conserved canonical physical-card binding without mutating a Game. The engine remains authoritative for live custody, validated ordinary uses, prepared `SpecialKaramaIntent`, response ownership and once-only continuation. A saved attempt must not contain an arbitrary client `Action`, function closure, cyclic state or whole-Game rollback snapshot.
+The pure [Kull module](../game/choam-kull.ts) owns `KullPhaseRestriction`, `activeKullRestrictions`, `kullBlocksKarama`, restriction/attempt-stamp validation, `distinctKullCounter`, `kullNativeCostCards`, `kullNexusCostCards` and `kullCounterCards`. It validates stamped phase policy and conserved canonical physical-card binding without mutating a Game. `kullNexusCostCards(held, physicalCards, reservedIds)` returns uniquely held canonical any-Treachery fuel excluding reservations; it infers neither Nexus presence, profile, phase nor promises. The engine remains authoritative for live source-specific promises/custody, actual Nexus and mode authorization, validated ordinary uses, prepared `SpecialKaramaIntent`, response ownership and once-only continuation. A saved attempt must not contain an arbitrary client `Action`, function closure, cyclic state or whole-Game rollback snapshot.
 
 The original and counter cards have different obligations. The original stays reserved until Kull settles; ordinary counter eligibility excludes that exact physical ID. A different printed Karama or eligible BG substitution may counter while Kull is pending. A BG counter's own conversion response must not overwrite the original intent or its suspended response.
 
-The consumer interface is `GameView.kullReaction`: `null` or `{ event, player, target, intent, cards, canDecline, blocked }`. It is present during the offer stage; the counter stage uses existing `responseControls`. `player` is the public CHOAM reactor, `target` the attempted activating player, and `intent` the ordinary purpose kind or the generic `special` label, never a special selection. All viewers see the same event/actors/intent; only CHOAM sees actual legal `cards` and `canDecline: true`. The current offer uses `blocked: null`, including no-card offers that CHOAM can decline. Countering reuses ordinary `card/mode: cancel` or `passResponse` actions. Never project raw special choices, saved response secrets, signatures, funding or either hidden hand.
+The consumer interface is `GameView.kullReaction`: `null` or `{ event, player, target, intent, plays, canDecline, blocked }`. The old `cards` array is removed. Each private play is `{ source: 'printed' | 'nexus', effect: 'kull', card: Card, event: string, blocked: string | null }`, separating the real selected fuel from the effect and source. It is present during the offer stage; the counter stage uses existing `responseControls`. `player` is the public CHOAM reactor, `target` the attempted activating player, and `intent` the ordinary purpose kind or generic `special` label, never a special selection. All viewers see the same event/actors/intent; only CHOAM receives its plays and `canDecline: true`; others get empty plays. The offer remains declinable with no legal cost. Countering reuses ordinary `card/mode: cancel` or `passResponse`. Never project special choices, saved secrets, signatures, funding or hidden hands, and never derive public opportunity timing from a secret Nexus or cost.
 
-`GameView.kullCounterEvent` is `null` or the same opaque public attempt event while the distinct-counter stage owns control, including a BG `worthlessKarama` overlay. Controls and bots use it only for precedence; legal physical choices still come from native `responseControls`. It reveals no original card, Kull cost or saved response payload. `GameView.karamaBlocked` is the current viewer's stamped activation-block reason or `null`, separate from a pending declaration; `kullPreview` supplies the visible opt-in warning.
+`GameView.kullCounterEvent` is `null` or the same opaque public attempt event while the distinct-counter stage owns control, including a BG `worthlessKarama` overlay. Controls and bots use it only for precedence; legal physical choices still come from native `responseControls`. It reveals no original card, Kull cost or saved response payload. `GameView.karamaBlocked` is the current viewer's stamped activation-block reason or `null`, separate from a pending declaration; `kullPreview` supplies the shared interception warning and `nexusKullPreview` identifies the new source capability.
 
-CHOAM submits `{ type: 'kullDecision', event, decline: true }` or `{ type: 'kullDecision', event, card }`. Bind event and actor before costs. The declared Kull is a real held printed card, not a manufactured card or a free power. Nexus Cunning is not admitted by this preview.
+CHOAM submits `{ type: 'kullDecision', event, decline: true }` or `{ type: 'kullDecision', event, source: 'printed' | 'nexus', card }`. **Source is mandatory on Use**, including the old printed path; no omitted-source compatibility remains. Bind actor, event, source and physical cost before mutation. Printed source is a held printed Kull; Nexus source is real eligible Treachery fuel plus the actual held CHOAM Nexus under the explicit new profile. No client effect, target, price or Nexus ID is admitted. Generic proactive `choamPowerAction` cannot play Kull.
 
 ## Settlement flow and cancellation
 
 1. Validate an actual activation before discard, payment, physical movement, once-use flags or random effects. Reject an already effective stamped phase restriction before costs. Invalid plays create no public offer and reveal no private payload.
 2. Save the exact typed intent and its parent ownership. Offer the same neutral CHOAM opportunity whether Kull is held or absent. Mere holding, transfer or nonactivation discard is not an attempted play.
-3. Declining resumes the original intent once, without another offer for that same attempt. Declaring Kull opens the ordinary CHOAM-effect response; **pending is not active**.
+3. Declining spends nothing and resumes the original intent once, without another offer for that same attempt. Declaring Kull opens the ordinary CHOAM-effect response; **pending is not active**. Accepted Nexus source immediately spends its physical CHOAM Nexus once using the existing Cunning receipt/history, while fuel remains held until success. A prevented declaration does not refund that Nexus.
 4. Resolve legal distinct counters using existing response ownership. The reserved original cannot cancel Kull. A valid counter follows its own ordinary consumption/conversion rules; it does not consume the original card as payment for the counter.
-5. On successful Kull, discard the exact Kull cost once, retain the original unplayed printed/BG card, leave the original special once-use unspent, and abort its effect. Restrict the **activating player**, not an allied shipment recipient, for the current turn/phase.
-6. If Kull is prevented, retain its cost and prevent that physical cost's effect for the phase under existing native CHOAM semantics. Resume the original attempt once. Recheck custody rather than substituting another same-name card.
+5. On successful Kull, discard the exact selected printed or Nexus fuel once, retain the original unplayed printed/BG card, leave the original special once-use unspent, and abort its effect and additional costs. Restrict the **activating player**, not an allied shipment recipient, for the current turn/phase. A Nexus fuel's actual canonical identity is unchanged; no Kull card is minted and Karama fuel is not also activated.
+6. If Kull is prevented, retain its selected fuel and prevent that physical cost's effect for the phase under existing native CHOAM semantics. An accepted Nexus declaration remains spent and its Cunning history completes canceled. Resume the original attempt once. Recheck exact custody rather than substituting another same-name card or restoring a whole Game.
 7. Stamp comparison expires the effective restriction on phase/turn change, not a temporary response, market or worm substep. It blocks Karama activations including substitutes, not ownership, trades or otherwise legal nonactivation discards.
 
-This is the approved development interpretation, not an official nested-priority clarification. JSON continuation must preserve the same ownership and exact physical cards without a second random draw, payment or replayed effect.
+This is the approved development interpretation, not an official nested-priority clarification. Accepted-declaration Nexus disposal and retained pending fuel reuse the existing Cunning application convention, not a newly located publisher Kull transaction rule. JSON continuation must bind original attempt, chosen source/fuel and Cunning receipt/history through suspended `pendingKull.resume`/Worthless or `pendingKarama` parents. Deleted/orphaned source, original or receipt ownership must reject before view, normalization, actions or SQL writes, not auto-resume or expose a private cost. Completed history must not require spent cards to remain forever in discard. There is no second random draw, payment, Nexus spend or replayed effect.
 
 ## Bene Gesserit conversion
 
@@ -105,10 +107,10 @@ Ordinary conversion behavior remains different: `spendKarama()` discards the BG
 ## Projection, UI, and AI
 
 - Public attempted-play metadata can include actor, purpose category, public recipient, and attempt ID. Do not expose raw continuation frames: they can contain private plans, hidden hand choices, revival terms, or future card transfers.
-- The CHOAM opportunity must not depend on its hand containing `ix-kull-wahad`; otherwise the presence of a prompt leaks possession. Its available reaction card and exact pending CHOAM card ID belong only in its private projection. Existing public `g.decision` projection must be reviewed before placing private fields in a new decision variant.
+- The CHOAM opportunity must not depend on holding `ix-kull-wahad`, CHOAM Nexus or eligible fuel; otherwise the prompt leaks possession. Its source-aware plays and exact selected fuel belong only in its private projection. Public viewers receive the same attempt metadata for CHOAM Nexus, an irrelevant Nexus, absent Nexus and no-cost hands. Saved private ownership must not enter public `g.decision` output.
 - Kull's settled target and stamped phase expiry are public. Selecting another player's shipment beneficiary must not change which player is restricted. Do not silently extend CHOAM's powers to an ally.
 - Bots must handle offer/decline, distinct counters, restored underlying decisions and blocked-activation filters. A card remaining physically in hand is not evidence the bot can play it. Prevent repeated invalid-action generation from proactive special and ordinary cancellation branches.
-- Preserve `choamWorthless.pending` during pending Kull and nested responses, just as with Jubba; an AI should not cash in the card it is currently using as protection/prevention unless it deliberately chooses to abandon that effect.
+- Preserve `choamWorthless.pending` during pending Kull and nested responses, just as with Jubba; it binds the actual selected printed/Nexus fuel so an AI does not accidentally cash in the card currently committed to prevention. The already spent Nexus is separate from that retained physical fuel.
 - Human controls describe the attempted purpose and distinguish pending Kull from a successful active restriction. The opt-in preview warning must remain visible; approved timing is product policy, not official completeness. Card inspection must not expose unplayed opponents' hands.
 
 ## Minimum validation plan
@@ -118,11 +120,13 @@ Ordinary conversion behavior remains different: `spendKarama()` discards the BG
 3. Successful block rejects a second activation in the same phase and permits one next phase; distinguish actor/beneficiary. Verify unsupported acquisition/holding restrictions were not added accidentally.
 4. Payment with enough spice, alternate usable Karama, blocked held Karama, stale funding, hand-limit changes and losing card custody. Confirm the deferred winning-overbid guard rejects before costs with the same private result whether hidden Kull is held or absent; no auction remedy is certified.
 5. Pending CHOAM cash-in, Fremen summon, Harkonnen exchange, revival-income preparation and Truthtrance feasibility; assert no response overwrite, false promise release, clone-search loop, duplicate random draw, or deadlock.
-6. Compare two states differing only in CHOAM's private Kull possession: rival/public opportunity shape must match. Check private selected special payloads and suspended contexts never appear in rival or spectator views.
+6. Compare printed-held/absent and CHOAM-Nexus/irrelevant-Nexus/absent-Nexus/no-fuel states: rival/public opportunity shape must match. Check private selected special payloads, source choices and suspended contexts never appear in rival or spectator views.
 7. All four AI difficulties must complete each new continuation, including no-Kull/blocked-Kull decline and a response resumed after cancellation. Browser-check the new decision and its pending/canceled state after reconnect.
 
 The original 6 September pass was a source/engine and document audit, not runtime verification. Its unanswered counter/BG proposals are superseded by the explicit 30 September selections above. The minimum validation plan remains a coverage contract, not a claim that every combination is verified.
 
+The new interaction has its own frozen evidence: types, lint, 6,022 offline tests, build, authenticated source-aware SQLite restart/races, four legal bot policies and actual Basic/Advanced CLI/runtime/phone weapon-fuel success and distinct prevention with refresh. Review repairs protect canonical descriptors, native suspended parents, reserved parent counters and CHOAM auction funding. Verified old printed counter saves migrate source binding without mutating callers or enabling Nexus; corrupt new-profile selections still reject. Local HTTP 49/55 retains four 503s and two timeouts; proxy-free CI and deployed acceptance remain separate. Historical printed-Kull and Richese results are not substituted for this proof. Full combinations and deferred auction remedies remain open.
+
 
 ## Implemented prerequisite: prepared special intents