Dune/docs/RICHESE_RESIDUAL_POISON_ENGINE_AUDIT.md

# Residual Poison: source and engine contract

## Semuta after a preparation Ready — 27 October 2026

**Prototyped / Partial.** A legal Residual Poison play still offers its public
fresh discard to Semuta when one combatant has already marked the current
pre-leader preparation ready. The signed continuation retains that actual
ready list, the single selected leader death and the physical card while the
neutral claim/pass resolves. The opponent's ready remains; the Poison player's
own earlier ready is reopened after the reaction, matching the native Poison
suffix. Existing committed-plan, inspection and pending-reward limits remain.

The printed Semuta ability reacts to another player's discard and the Poison
card is played before leader commitment; neither source imposes an empty
readiness list. The shared online readiness protocol and nesting remain an
implementation composition. [Native Basic runtime](../tests/semuta-residual-ready-runtime.test.ts)
uses actual purchase, shipment and battle, with a conserved staged Semuta card.
Wider interactions and final/deployed acceptance remain open.

Audit: 2026-09-06. The source findings below informed the bounded runtime integration recorded at the end. Historical hook and proposed-contract sections describe the pre-integration audit; they do not supersede the final checkpoint. Complete expansion compliance remains unverified.

The Advanced Harkonnen exclusion below is superseded by the
[18 October captive-death composition](#native-captive-death--18-october-2026).
Earlier timings, test totals and unimplemented-card statements remain historical.

## Answered Cunning follow-up — 26 October 2026

The pre-leader window now remains available after two answered nonleader
Cunning inspections. Under the 14 October choose-recommended authority, use
the existing native-first reconciliation after the single actual death:
preserve an independently possible native answer, then require the extra
answer to permit the same legal plan. Reopen only required original fields;
retain private observations and the original spent Nexus. No victim redraw,
second death/discard or new card payment occurs. Leader commitments and other
active interactions remain guarded. The priority is a provisional online
composition, not a publisher tie-break among incompatible surviving sets.
[Canonical inspection composition](NEXUS_ATREIDES_RULES.md#residual-poison-and-two-inspected-commitments).

## Evidence and confirmed effect

The publisher card face says **“Play on your opponent before choosing leaders in a battle.”** It then randomly sends one available leader of that faction to the Tanks, specifies **“No spice is collected for it”**, and requires disposal after use. The enlarged physical face was visually read at `/tmp/dune-rules/choam-residual-reading.png`, from the [photograph of the actual components](https://cdn.anyfinder.eu/assets/QsUJtVktEC87xwK08oLlwnKyaozUWfuaLzG0LFEn67ENEEVgNrDGoITy3608Dqe7), linked by the [product gallery](https://www.tabletopfinder.eu/en/boardgame/32692/dune-choam-richese). The photographer's printing/date is unverified; the evidence is the visible publisher text, not retailer commentary. Photograph SHA256: `9c1d3e65fa33489e7675055ed1fc932fefcb79f6053ee365ddee6737ae10b81f`.

The [GF9 CHOAM/Richese rulebook](https://www.gf9games.com/dune/wp-content/uploads/2021/11/CHOAM-Rulebook-low-res.pdf), pp5–6, supplies the ten-card inventory and normal discard routing. The readable publisher-authored local mirror is `/tmp/dune-rules/choam-lelekan-mirror.pdf` and `.txt`; provenance is recorded in `RICHESE_ACQUISITION_RULES.md`. Direct publisher PDF requests again returned 403. Bounded publisher-indexed searches for Residual Poison and its leader wording found no card-specific FAQ, priority exception or exceptional-leader pool ruling.

The effect targets the actual opposing combatant, not any chosen faction or an ally's opponent. It is a Special Treachery Card, not a poison weapon in a sealed battle plan. It has no activation payment, recipient consent, ordinary Karama cancellation, automatic traitor call, battle win, force loss, Face Dance, technology transfer or battle-income event. Discard the physical card once through normal routing; it does not return to the Richese cache. No Spice Bank, killer, Emperor or Tleilaxu income is generated by this death. Zoal needs no strength calculation because the card expressly produces no death bounty.

## Leader pool: composition versus unresolved custody

Use current control and current battle availability, not `target.leaders` alone. The [base rules](https://www.gf9games.com/dunegame/wp-content/uploads/Dune-Rulebook.pdf), pp10–11 and17, restrict leader use to one territory per turn, permit reuse in that territory, describe captive battle use and return, and exclude the Kwisatz Haderach from ordinary leader deaths. Thus the ordinary compositional pool is living controlled leader discs available in this territory; exclude leaders already used elsewhere, dead discs, native leaders currently controlled by someone else, Cheap Hero cards and the Kwisatz Haderach. Voice constraints on Treachery types do not make a physical leader unavailable.

The [Ixian/Tleilaxu rules](https://www.gf9games.com/dunegame/wp-content/uploads/2020/09/IxianAndTleilaxuRulebook.pdf), p7, expressly add revived foreign leaders to the Tleilaxu leader pool. Consequently a living controlled foreign ghola belongs in the ordinary available-leader composition, rather than acquiring immunity because its native faction differs. Zoal is one physical eligible disc, with the same random weight as another eligible disc. This is general-rule composition, not a retrieved Residual-specific answer.

The [Ecaz/Moritani clarification](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf), p9, distinguishes Duke Vidal's controller, one-battle tenure and Ecaz-only revival. A living currently controlled, battle-available Duke is not given poison immunity. Use his canonical separate physical disc; death must preserve his history in the Tanks and must not generate a fresh native disc, return him alive to supply, or revive him for the current controller. Existing unresolved advanced Harkonnen/Duke configurations remain implementation guards. Do not pretend those guards are printed immunity.

For ordinary available captives, the general battle-use rule supports pool inclusion. Technical death cleanup must clear the dead captive's temporary captivity correctly, preserve its native revival identity and apply immediate captive return if Harkonnen loses its last native leader. The base rules explicitly describe those return/death rules, but the retrieved material does not specify public disclosure of an unrevealed captive killed by this card. Current concealed-capture projection intentionally shows stale public leader status. Logging the victim's name unconditionally would defeat that policy. This exceptional visibility question merits an explicit unresolved guard or a verified disclosure policy; do not silently exclude only the secret captive from a supposedly uniform random pool. Likewise, nested captured-foreign-ghola or captured-Duke lifecycle cannot be inferred by copying a normal death counter update. Normal foreign-ghola control and the currently supported uncaptured Duke case are technical implementation work, not inherently source ambiguities.

## Timing and a usable multiplayer opportunity

The existing card guide narrows the face to before an opponent chooses a leader. The actual plural/general wording does not expressly authorize playing after the holder has committed its own leader. The conservative supported timing is before either combatant has committed a leader. Any complete sealed plan has chosen a leader, even if its identity is hidden. A leader-valued Prescience answer also chooses one; a nonleader answer does not itself do so. Do not inspect the hidden identity to decide whether timing is open.

Base p23 explicitly orders Voice before Prescience and allows Truthtrance throughout that interaction. It does not assign Residual Poison a position relative to those powers. The card supplies no aggressor-first privilege, turn-order rule for simultaneous plays, or authority to invalidate an already selected leader. A fixed Residual-before-Voice or Residual-after-Voice checkpoint would be a scheduling convention, not a verified special FAQ ruling.

Simply adding an anytime button before the first sealed plan is insufficient: the opponent or an AI can seal first before the holder receives a usable opportunity. Creating a public decision only when somebody holds Residual reveals possession. Automatically passing only the nonholders leaks the same information through progression.

A privacy-preserving implementation option is an identically projected **universal pre-leader opportunity for both combatants**, with genuine ready/pass decisions from both and no automatic nonholder passes. Its purpose is to relinquish an optional card opportunity, not confirm automatic bookkeeping. Keep the labels and public progression independent of possession. It must finish before leader-valued Prescience answers and full-plan sealing can close the opportunity. Preserve Voice-before-Prescience and active Truthtrance answering. A fixed ordering for this checkpoint still needs to be identified as application scheduling unless further authority resolves it; alternatively integrate readiness with preparation actions without inventing a faction-specific priority. Do not claim that a timeout alone supplies the same right. A later acquisition/revival reopening a previously relinquished opportunity is not answered by the retrieved card text.

## Current engine hooks and concrete risks

- `chooseBattle`, `battlePreparation`, `finishBattlePreparation`, `combatResponses`: establish the existing funding/power/Voice/Prescience/full-plan sequence. A new opportunity must persist through these continuations without replacing another owner's decision. `Battle.prepared` alone is not a sufficiently precise pre-leader boundary.
- `controlledLeaders` plus the availability predicate in `validatePlan`: suitable starting point for controlled physical discs, including the separate Duke. Do not use `captureCandidates` merely because its filter looks similar. Do not copy Terror Assassination's native-five-only pool or bounty: its text and support guards are different.
- `battlePlan`, `prescienceAnswer`, advanced `fullPlan`: close the opportunity at the correct public commitment boundary. Preserve target-first full-plan sealing and never reveal a selected leader merely to explain a disabled card. A previously answered nonleader Prescience constraint can become infeasible after a death; add explicit feasibility handling, not an unreachable mandatory plan.
- `reconcileBattlePromises`: opposing involuntary death can release an impossible promise; it must not reject a legal randomized hit and redraw until a promised leader survives. Unaffected promises remain binding. The holder's voluntary action must still respect its own existing commitments. Validate all nonrandom facts before drawing; do not consume RNG in private availability projection.
- `resolveBattle` currently owns a local death helper and later captive/Duke cleanup. Extract or call a dedicated non-battle leader-death operation rather than invoking battle resolution. Increment exactly one death, clear obsolete `usedAt`, repair custody, and then reconcile feasibility. Do not consume a living Duke merely because the card was used in his prospective battle.
- `projectLeader` conceals captured state from unauthorized viewers. A public victim field, random-pool count, rejection reason or before/after projection may pierce that concealment. Project only authorized information and guard unsupported secret-captive disclosure uniformly, not by looking at a hidden selected plan.
- `pendingNullentropy` and `resolveTruthAction` must retain their early lock/answer priority. Source-card commitments must reuse `transferCardBlock` for held gifts, saved accepted Ix replacement, Harkonnen return requirements and battle/Truthtrance commitments. The card can settle synchronously, so it needs no new cancellable response or long-lived played-card escrow. It must not overwrite a paused gift, auction or search simply because it is categorized as Special.

## Proposed action/state/projection contract

Bind the preparation opportunity to a server-generated battle event, not merely territory and turn, since several battles can occur in one territory.

```ts
// Scheduling choice must be documented separately from card rules.
Battle.preLeader?: {
  event: string;
  ready: string[]; // actual combatant declarations, never inferred from hand
};

{ type: 'card', card: canonicalResidualId,
  target: actualOpponentId, event: battleOpportunityEvent }
{ type: 'battlePreparationReady', event: battleOpportunityEvent }

// Entitled holder only; no opponent pool, leader choices or eligibility metadata.
residualPoison: null | { card: string; event: string | null; blocked: string | null };
```

Validate exact held card identity, actor/target, event, phase, pre-leader timing, source commitments, supported custody and nonempty actual pool before any mutation or RNG. The server selects one uniformly from physical eligible IDs, applies one no-bounty death, discards once, performs custody/promise reconciliation and preserves the battle and remaining preparation state. The request never chooses the victim or supplies the random index. A singleton pool settles without an acknowledgment. Resolve genuine choices only; do not add a victim-confirm dialog.

Keep random resolution inside the authoritative action clone and normal room CAS. Concurrent stale submissions may calculate private trial outcomes but only one commit is exposed. Retrying a committed version cannot kill another leader. Persist only the settled state/public-safe event, not an unredacted pool snapshot that leaks through views. Legacy battles already holding sealed plans must not reopen the timing window.

## Focused acceptance checklist

1. Ordinary participant/opponent, exact canonical card, correct event; outsider, same-faction nonparticipant, empty pool and stale/sealed use reject without card/death/RNG mutation.
2. Available same-territory used leader included; dead and elsewhere-used excluded; uniform eligible-disc selection; Cheap Hero and Kwisatz never selected.
3. Foreign ghola, ordinary captured leader, last-native Harkonnen death and supported Duke physical custody; explicit guard for unresolved concealed-captive disclosure/nested custody. Zoal death gives zero spice regardless of opponent leader.
4. Exactly one normal discard, no cache return, bounty, payment, force loss, battle win, capture, Face Dance or tech transfer; all physical leader/card histories conserved.
5. Guaranteed opportunity against fast human/AI sealing; identical nonholder/holder public checkpoint shape; no auto-pass possession oracle. Leader Prescience/full-plan commitments close timing without leaking identity.
6. Voice, nonleader Prescience, genuine Truthtrance overlay and an involuntarily impossible promise; keep unaffected constraints and finishable planning. No random validation or conditional redraw.
7. Reserved gift/accepted Ix/Harkonnen-return/paid Box cases, explicit parent preservation and no silent decision replacement.
8. JSON restoration, owner/outsider projection equality where secrets differ, authentic concurrent CAS, duplicate request/reconnect, four AI profiles and no extra confirmation for the resolved death.

No extra user question was sent. Guaranteed opportunity scheduling and exceptional secret-captive disclosure are the material outstanding boundaries; ordinary no-bounty death, controlled available-leader filtering, disposal and continuation are implementable technical work.

## Residual Poison runtime and CHOAM portrait checkpoint (2026-09-06)

- Canonical Residual Poison now has engine, private controls and all four AI policies. Before either combatant commits a leader, it uniformly selects one living, currently controlled opposing leader available in the battle territory, sends that physical disc to the Tanks and discards once. Same-territory reuse remains eligible; dead or elsewhere-used leaders, Cheap Heroes and the Kwisatz Haderach are excluded. There is no payment, bounty, force loss or automatic battle victory.
- A hand-independent shared preparation step gives both combatants an actual opportunity before leader commitment in Richese tables. Both choose readiness; no nonholder is silently passed. This is a disclosed application timing procedure, not a claimed publisher ordering rule. Active interactions retain priority. Exact saved battle events bind both actions and retries. No additional confirmation is added to the random death.
- Foreign ghola revival custody and Duke Vidal's physical disc/death history are preserved. Involuntary death reconciles impossible battle promises and reopens an impossible non-leader Prescience answer without redrawing the victim. All candidate death transitions and prospective hand commitments are validated before randomness. The still-secret Harkonnen captive disclosure ruling remains unresolved: Advanced Harkonnen tables guard the card based on their public configuration, never based on hidden captivity. See [RICHESE_RESIDUAL_POISON_ENGINE_AUDIT.md](RICHESE_RESIDUAL_POISON_ENGINE_AUDIT.md).
- The full registered suites pass **1,329/1,329 rules/client/component tests and 107/107 persisted/API tests**, with TypeScript, lint and production build passing. New focused coverage comprises seven pure, six root engine, seven independent review and four AI cases, plus three SQLite/CAS recovery cases. Logs: `/tmp/dune-residual-final-full.log` (34.00 seconds), `/tmp/dune-residual-final-multiplayer.log` (16.26 seconds), `/tmp/dune-residual-final-type.log`, `/tmp/dune-residual-final-lint.log`, `/tmp/dune-residual-final-build.log`. Existing No-Field tests now perform the genuine readiness actions; independent-battle privacy comparisons normalize only the new random public event IDs.
- The manual maintenance restart preserved all **1,175 saved room versions and exact state hashes**, including a real browser-created open preparation step in synthetic QA room QPNV5XJJ v29. Backup: `/tmp/dune-maintenance-20260906T1117/database.sqlite`. The known human room remained idle and unchanged. A fresh invitation restored the exact event and opponent readiness. Browser play then killed Flinto Kinnis once, left spice and forces unchanged, removed the card from hand and placed exactly one in discard. Ready resumed normal planning; the AI sealed a valid plan. Refresh retained v34, the same event, one death and one discard. All other 1,174 saved room hashes remained unchanged. No automation was recreated. Snapshots: `/tmp/dune-residual-browser-complete-v31.json` and `/tmp/dune-residual-browser-planning-v34.json`.
- Five original CHOAM portraits bring ordinary coverage to **45/60**, completing the six base factions plus Ixians, Tleilaxu and CHOAM. All forty earlier files and manifest entries remain unchanged. Full-resolution inspection, four existing asset tests, and actual 192px inspector / 80px circular browser review pass. The temporary contact-sheet server was stopped. See [CHOAM_PORTRAITS.md](CHOAM_PORTRAITS.md). Fifteen ordinary portraits and separate special-disc artwork remain unfinished.
- Five Richese effects remain inactive: Semuta Drug, Stone Burner, Mirror Weapon, Portable Snooper and Juice of Sapho. Other incomplete faction/module systems and unresolved interactions remain tracked. No full Advanced or expansion game was certified and no start gate was removed. The full goal remains active.

## Native captive death — 18 October 2026

**Prototyped / Partial.** Residual Poison now works with Advanced Harkonnen.
The random pool includes every living, currently controlled physical disc
available in the battle territory, including a concealed ordinary captive,
captured foreign Ghola and captured shared Duke. It never chooses a particular
leader at the player's request or redraws to preserve a commitment.

The selected disc suffers one ordinary death, with zero spice awarded. Its
identity/death becomes public and captivity ends. Unselected living captives
retain their concealment. A foreign Ghola keeps its existing Tleilaxu revival
custody; the shared Duke retains his one physical disc/death history while
temporary tenure and capture underlay end. Ecaz-only Duke revival is unchanged.
The existing common Skill hook returns a dead trained leader's card; no new
replacement assignment is created. Killing the last native Harkonnen leader
still returns surviving captives immediately, without executing them.

This public death is a **provisional source composition**, not an express
Residual Poison FAQ answer. The authorized supplied Advanced PDF, physical33
(printed31), permits undisclosed capture but gives the distinct execution-for-two
branch its face-down Tanks instruction. Its physical9 (printed7) supplies
ordinary death-history handling. The [official FAQ, p6](https://www.gf9games.com/dune/wp-content/uploads/2020/11/Dune-FAQ-Nov-2020.pdf)
gives execution its special private inspection and twice-dead treatment. The
physical Residual face specifies no bounty and no face-down exception. Applying
ordinary public Tanks handling avoids inventing a secret death or importing
execution's extra payment/death rule. It does not reveal living captures in
general or replace the [known trained-card inference](LEADER_SKILLS_CAPTURE.md).
The supplied file identity/authority remains in
[the source register](RULE_DECISIONS.md#authorized-source-amendment--1-october-2026).

The source-specific configuration/custody bans are removed. Existing exact-card,
event, participant, pre-leader, interaction and promise checks remain. The
private card control explains the consequence and provisional interpretation
in Advanced Harkonnen tables. Existing minimal policies consume the same legal
server option, without scoring a hidden victim pool or strategic refinement.

The Semuta suffix now finds the signed victim by its unique physical identity
across native rosters/shared Duke: a dead captive no longer belongs to its former
controller. The signature still binds the target, victim, committed battle and
complete physical state. Claiming the discarded card neither kills again nor
changes readiness or the battle's original continuation. Existing signature
bytes and neutral response procedure remain unchanged.

### Targeted proof and limits

One disjoint genuine-fixture lane, bounded source review and owner integration
pass **9 files74/74**, `npm run check:quick`, production build and actual-rule/
rendered-control smoke on one frozen source:

- Base commit `6c83148ead958a7071f755b598c76615b02e458c`; source tree
  `a0348b55b6ef2e5da6301982693f85c3bce09f2b883bda1b6fbe5669d0e281a9`,
  2,592 tracked/nonignored source files, including only a hash of the preserved
  untracked supplied PDF. Proof is local; no PDF is committed or republished.
- `tests/fixture-residual-poison-capture.ts` uses70 original public Advanced
  actions: real host start, opening bid1/seller purchase2, Harkonnen3/Emperor1
  Red Chasm and Richese1 Carthag shipments costing6/2/1, actual native battle win,
  optional random capture/keep and the second original battle. No postdeal hand,
  disc, force, wallet, clock or capture is installed. Only unopened original
  Spice positions and authoritative scalar lotteries are selected.
- `tests/residual-poison-capture-engine.test.ts` and runtime smoke select a native
  or captive disc from five actual eligible leaders, excluding the Harkonnen
  leader already used in Red Chasm. Each uses9 continuation actions through the
  shared opportunity, real plans/votes/final acknowledgement and completed
  Carthag battle. One death/discard, zero bounty and nonselected concealment
  remain. Four minimal profiles make eight legal card/readiness proposals and
  finish that battle; no strength calibration is claimed.
- `tests/residual-poison-custody.test.ts` uses separately labelled controlled
  probes for ordinary/captured-Ghola/shared-Duke death, last-native Harkonnen
  return and Semuta claim after physical custody ends. These are not additional
  original-action combined-module programmes. Existing core capture, trained
  capture and Homeworld/Semuta card regressions pass in the same affected union.
- Actual GameTable and card components render offered, busy, death and completed
  states. The new explanation is visible and busy disables the real play control.
  Framework aliases/CSS stubs mean no browser click or visual acceptance.

First targeted feedback repaired fixture assumptions only: a Once Around seller
gets its final raise after a real positive opening, and the resolved discard
sentinel is null. All affected checks then pass on unchanged rule source. Private
logs, source snapshots, rendered HTML and runtime results are in
`/home/quintine/.local/share/dune/checkpoints/20261018-residual-capture/`;
`frozen-integrated/report.json` is the complete passing batch. Final edits after
this proof are documentation/reference prose/evidence only, separately checked
against all verified file hashes before commit/push.

Wider combinations, complete modes, final privacy/custody/recovery assurance and
deployed acceptance remain open. No saved-room/database/reset/restart/deployment
operation was performed.