Implement bounded Richese Nexus Betrayal auctions

docs/NEXUS_RICHESE_RULES.md

@@ -1,6 +1,6 @@
 # Richese Nexus source contract
 
-Audited 10 September 2026. This separates the ordinary Secret Ally shipment from native Cunning's two-marker operation. It does not certify either implementation or open the Nexus release gate. See [common Nexus rules](NEXUS_CARD_RULES.md), [No-Field custody](RICHESE_NO_FIELD_RULES.md), and [allied No-Field distinctions](RICHESE_ALLIED_SHIPMENT_AUDIT.md).
+Audited 10 September 2026, with a bounded Betrayal implementation contract added 30 September. This separates the ordinary Secret Ally shipment, native Cunning's two-marker operation and Betrayal's two auction outcomes. It does not certify full-family implementation or open the Nexus release gate. See [common Nexus rules](NEXUS_CARD_RULES.md), [auction custody and source boundaries](RICHESE_AUCTION_RULES.md), [No-Field custody](RICHESE_NO_FIELD_RULES.md), and [allied No-Field distinctions](RICHESE_ALLIED_SHIPMENT_AUDIT.md).
 
 ## Printed effects and source status
 
@@ -8,6 +8,8 @@ The Richese panel was freshly read from the [original photographed GF9 cards](ht
 
 Common eligibility requires **Richese absent**, not Guild absent, for Secret Ally. A native Guild player may hold it. A holder cannot retain a Nexus card when entering an alliance, and play consumes the card. E3 contains no Richese-specific Nexus FAQ. [GF9 E3 p.11 and p.16](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf#page=11)
 
+The photographed Betrayal panel has two alternatives: stop Richese buying a Richese Treachery Card by discarding that intended card without payment, **or** redirect the payment for a card Richese sells to the Spice Bank. Both spend the same physical Richese Nexus card; they are not two uses or a generic cancellation of Richese income. The panel's source is the [original GF9 component photograph](https://boardgamegeek.com/image/7767032/dune-ecaz-and-moritani), semantically transcribed in `game/nexus-card-reference.ts`. Auction origin, payment routing and still-earned purchase consequences compose with [GF9 E2 pp.4–6 and 10–12](https://www.gf9games.com/dune/wp-content/uploads/2021/11/CHOAM-Rulebook-low-res.pdf), as audited in the auction contract; no tournament amendment supplies authority.
+
 Official indexed excerpts, the original component photograph, and cached E3 publisher-authored text were inspected. Direct retrieval of the official base/November FAQ PDFs returned 403. The older local base/E2 cache paths named by historical documents are no longer present in this workspace; those historical claims were checked against fresh publisher excerpts where used below.
 
 ## Secret Ally: ordinary shipment composition
@@ -66,7 +68,7 @@ The connected path is deliberately narrower than every possible E2 composition:
 
 The card is discarded at declaration. The native No-Field Karama cancellation precedes settlement and preserves the two tokens, reserves, spice and ordinary shipment allowance but not the card. Advanced Guild special prevention also leaves the physical shipment unpaid and unplaced while consuming the attempted shipment allowance and the card. Otherwise the pair is one arrival, costs the ordinary one-marker price, immediately reveals one chosen denomination and places up to that value of actual normal forces from current reserves in the destination. Only the other token remains concealed, publicly counting as one force; it draws from then-current reserves on its later native reveal. The immediate group plus the concealed marker count as actual presence for subsequent territory-entry and board logic, not two independent shipments.
 
-An owner-only control distinguishes ordinary No-Field, Smuggler and Nexus pair choices. All four bot profiles have a minimal legal pair candidate. The pending frame binds both physical identities, owner, token event, destination and one-marker price through JSON and in-memory SQLite CAS recovery. Public logs disclose the immediate faceup value/actual force count after settlement; the rival projection contains no concealed token identity or owner-only offer. Signatures detect partial saved-frame corruption, not arbitrary save forgery. Combined modules, allied No-Fields, high-Richese additional-force effects, Betrayal, later faceup display mechanics and full Nexus acceptance remain open.
+An owner-only control distinguishes ordinary No-Field, Smuggler and Nexus pair choices. All four bot profiles have a minimal legal pair candidate. The pending frame binds both physical identities, owner, token event, destination and one-marker price through JSON and in-memory SQLite CAS recovery. Public logs disclose the immediate faceup value/actual force count after settlement; the rival projection contains no concealed token identity or owner-only offer. Signatures detect partial saved-frame corruption, not arbitrary save forgery. Combined modules, allied No-Fields, high-Richese additional-force effects, later faceup display mechanics and full Nexus acceptance remain open. Betrayal now has its separate bounded auction contract below; the Cunning evidence does not verify that path.
 
 ## Existing integration points and verification
 
@@ -75,3 +77,50 @@ An owner-only control distinguishes ordinary No-Field, Smuggler and Nexus pair c
 `game/homeworld-shipment.ts` and the Guild Homeworld adapter own non-Arrakis routes; they should not be bypassed with a forged static board destination. `game/richese-no-field.ts` owns physical markers and should not be initialized for absent-faction Secret Ally.
 
 Required focused evidence: 1/5 actual-force shipments with unchanged price; normal/elite mixtures; Guild present/absent/native-holder and active bank-rate payment; Fremen retained geography/free price; native Homeworld source custody; occupancy/storm rejection before costs; Guild allowance/prevention; real BG/Terror/Ambassador continuations using actual counts; all-seat projections; and persisted pending/complete/stopped histories with concurrent and rejected-action immutability. Complete Cunning and broader module acceptance remain separate work.
+
+## Bounded Betrayal auction contract — 30 September 2026
+
+### Entry and actual cost
+
+The explicit local `richese-betrayal` profile is for genuine fresh Basic or Advanced games with CHOAM and Richese, two to six seats, and otherwise classic factions. It selects the physical CHOAM Treachery deck and Nexus module, with no other optional modules; Ixians, Tleilaxu, Ecaz, Moritani, Semuta and Kull previews are outside this boundary. `initializeRicheseBetrayalGameForAudit(state: Game): Game` is the engine admission seam. Existing games and other preview profiles do not silently gain this behavior. Ordinary public expansion starts and full Nexus/Richese certification remain closed.
+
+Use requires an **unallied** holder whose actual native faction is not Richese, native Richese seated, and the one physical Richese Nexus card in that holder's separate custody. Spending it moves that singleton to Nexus discard once. No ordinary Treachery card, Karama, hand slot or extra spice is the activation cost. Current own-card promises and committed-resource legality still apply before acceptance; merely possessing the face is not sufficient. Passing keeps the Nexus card and spends nothing.
+
+### Prepayment veto versus recipient override
+
+| Alternative | Connected trigger | Physical card and spice result |
+| --- | --- | --- |
+| Purchase veto | Richese wins its own **public cache** lot through Once Around or Silent bidding, before debit or acquisition | Move the exact selected cache card to ordinary Treachery discard, not Richese's hand, cache return or out-of-game removal. Do not debit the buyer or ally, and do not pay Richese, Emperor or bank. No purchase was made, so no Harkonnen purchase bonus is created. Retire the original lot/round continuation once. |
+| Sale diversion | Another buyer wins a cache lot or concealed Advanced Black Market lot (normal, Once Around or Silent), with a positive payment otherwise due to Richese | Keep the original winner, price, own/authorized-ally contributions and physical delivery. Route that same payment to the bank instead of Richese; Richese receives zero sale income. The buyer is charged only once, not a second bank fee. Existing earned buyer consequences, including the Harkonnen bonus when applicable, continue once. |
+
+Richese buying its own cache normally pays Emperor/bank. That invoice is the purchase-veto alternative, **not** a sale payment owed to Richese. A zero result/free cache keep or unsold Black Market retention is not a positive sale. Existing exhausted-cache/ordering guards, positive Black Market seller-bid guards and special-acquisition guards remain; this panel does not settle their source questions.
+
+Normal-deck Richese self-purchases can conceal whether the physical card belongs to the Richese family. They are **not connected** by this first boundary. The private advanced special-Karama cache acquisition has a separate activating card and once-per-game ordering and is also **not a connected veto trigger**. Native statements about whether Karama can cancel that special power do not establish whether Nexus Betrayal applies to it. Do not certify either producer by borrowing an unrelated native exception.
+
+The interruption belongs inside `settleRicheseLot`, after native responses and any entitled Atreides peek have finished and the sold quote is valid, but before `payWithAlly`, source removal or hand delivery. Source/recipient facts come from that original quote, not a client-selected target, card, amount or recipient. Unsupported counter overlays or any-time effects that the receipt cannot resume must be prevented before entry, not suppressed after money moves. A diversion is a recipient override, not a refund, re-purchase or replay of bidding.
+
+The current preflight requires a playing Bidding-stage Richese lot with no ordinary auction/sale, response, decision, phase opening, active Truthtrance, Karama, Nullentropy/discard, Kull/CHOAM conversion or market, Ixian allied replacement, Richese gift/purchase-income/Technology, or pending Nexus traitor exchange overlay. The original quote proves exact budget, representable sale/bonus continuation, exhausted-cache guards and binding shipment-completion feasibility before the pause. While pending, only the exact reaction choices and bot advancement are admitted; another any-time effect cannot mutate the reserved transaction. Spending the holder's Nexus must preserve that holder's own binding shipment promises. An involuntary purchase veto does not assume the target acquired the card or spent the price; opponent promises made impossible by that prevention use existing native reconciliation/release. These are bounded continuation guards, not blanket publisher immunity. The cache veto is a direct ordinary discard; the profile does not compose it with Semuta.
+
+### Neutral application protocol and privacy
+
+The pause is uniform for all **publicly possible** responders: other-faction unallied seats with publicly visible held-Nexus presence. Required/pass IDs depend only on roster, alliances and that presence, never on a secret held identity. If no seat is publicly possible, the original purchase automatically continues. Otherwise each required seat may pass, including a holder of an irrelevant Nexus card. Only the privately eligible Richese-card holder sees Use. Once all required seats pass, settle the original quoted purchase once; an accepted Use commits its one alternative and closes that opportunity.
+
+This neutral acknowledgement is an explicit application protocol to preserve concealed custody, **not** printed publisher timing or a general ruling about simultaneous Nexus/Karama priority. A holder-only pause would reveal a secret card. Replacing a relevant hidden card with an irrelevant hidden card must not change the public pause, event or auction terms.
+
+`GameView.richeseBetrayalPreview` identifies the opt-in profile. `GameView.richeseBetrayalReaction` is null or `{ event, kind, target, buyer, source, price, canPass, hasPassed, canUse, blocked }`, with `kind: 'purchase' | 'sale'` and `source: 'cache' | 'blackMarket'`. Every seat sees the same public event, kind, Richese target, original buyer, source and price. Purchase requires cache and buyer equal to target; sale requires another buyer. `canPass` and `hasPassed` concern only the viewer's public acknowledgement; `canUse` and `blocked` concern only that viewer's actual private eligibility.
+
+The reaction contains no target physical card, hidden Black Market face, payer spice, ally balances, opponent hand, private Nexus identity, raw source frame, signature or deck order. Public cache faces remain available through existing entitled inspectors. A Black Market claim is not the unknown face; the new reaction grants no new inspection permission. Existing Atreides or owner entitlement remains separate. Public Nexus face reference is a catalog, not proof that anyone holds that face.
+
+Clients submit exactly `{ type: 'richeseBetrayalPass', event }` or `{ type: 'richeseBetrayalUse', event }`. The server checks actor/event and exact keys and supplies the original target/card/price/recipient from private state. Human controls and all four minimal legal bot policies consume the same projected eligibility; no consumer guesses Use from physical custody alone. Pending acknowledgement replaces underlying auction actions rather than letting them charge or advance the lot early.
+
+### Saved continuation and verification status
+
+A typed private frame/receipt binds the original round, lot, physical card, Richese owner, buyer, price/funding, source custody and continuation ownership. Independent pending/completed cursor evidence prevents deletion or orphaning of that frame from automatically settling a purchase. Reconnect resumes the exact opportunity, recorded passes and committed outcome without rerolling, replaying a raw Action, rolling back a full Game or echoing payment. Intrinsic committed history must remain valid after the Nexus or purchased/discarded Treachery card subsequently moves; it must not require an old card to stay in discard forever.
+
+The implemented state names are `Game.pendingRicheseBetrayal` for `{ receipt, lot, quote, signature }` and independent `Game.richeseBetrayal` for `{ sequence, current, completed }`. The receipt carries event/turn/sequence, original round/lot, private invoice, public-required IDs, recorded passes, `pending | passed | used` stage, actor and Nexus-discard index. Its invoice includes the original recipient, price, own/ally contribution split, donor and private physical card. The source signature binds live original custody/funding/continuation; historical completed receipts keep intrinsic evidence rather than asserting present discard location. These deterministic signatures detect inconsistency, not arbitrary save forgery, and are never part of the player reaction projection.
+
+Implementation responsibilities are `game/nexus-richese-betrayal.ts` for pure invoice/source/eligibility and receipt invariants; `game/engine.ts` and `game/auction-continuation-quote.ts` for settlement, projection and finalizer fences; `components/nexus-richese-betrayal.tsx` and `game/bot-nexus-richese-betrayal.ts` for real private Use/public pass/wait consumers. The internal player topic is `nexus-richese-betrayal` in `game/reference.ts`; player navigation remains internal-only.
+
+**Verification: Partial, with the bounded runtime verified locally.** TypeScript, lint, all 5,953 offline tests and the app build pass; eight focused files pass 80 cases. The five dedicated suites cover purchase veto/all-pass, cache and concealed Black Market diversion, exact Nexus/card/spice/escrow custody, native Harkonnen bonus and cancellation, private identity parity, rejected-action immutability, all four legal bot profiles, real table controls and authenticated SQLite restart/concurrency/orphan rejection. Independent economy and persistence reviews exposed an erroneous second donor debit and a post-bonus exhausted-cache deadlock; both are fixed with regressions. Preflight consumes already pledged escrow and validates the deterministic next boundary before reserving an opportunity.
+
+Actual `richese-betrayal` CLI entry, source runtime settlement and 390-pixel browser controls were exercised in disposable QA rooms: Basic purchase Use discards without debit/delivery; Advanced purchase Pass preserves the Nexus and performs the original purchase; Basic cache and Advanced Black Market Use send the six-spice payment to bank once while delivering the exact card. Refresh retains each completed event and physical custody; the Black Market holder sees no unknown face inspector. No existing human game or seat was changed. Local Wrangler HTTP passes 51/55: three POST 503s and one Advanced-preview timeout prevent a green local HTTP claim. Proxy-free container CI and live NAS evidence are separate; no deployed acceptance or full Richese/Nexus completion is claimed.