Implement Guild Nexus Secret Ally shipping routes and recovery

docs/COMPONENT_INVENTORY.md

@@ -1,5 +1,7 @@
 # Component inventory and verification ledger
 
+**Guild Nexus Secret Ally update, 10 September 2026:** the existing card now supplies an explicit paid shipment choice, including physical cross/return selection and typed reserve or world-to-world sources. The holder keeps its own faction identity, forces and ordinary movement. No component is duplicated; existing full-card inspection remains shared. [NEXUS_GUILD_SECRET_ALLY_RUNTIME.md](NEXUS_GUILD_SECRET_ALLY_RUNTIME.md) records the supported routes and verification. Homeworld-return interpretation, concealed transport, Betrayal and complete module acceptance remain unfinished.
+
 **Guild Nexus Cunning update, 10 September 2026:** the existing native card now offers an immediate second paid shipment after the original combined turn. No new forces, markers or cards are created; the normal physical reserve, cross/return and Homeworld controls retain their source counts and price. A separate skip choice and unused Hajr control preserve actual movement history. [NEXUS_GUILD_CUNNING_RUNTIME.md](NEXUS_GUILD_CUNNING_RUNTIME.md) records runtime, interruption and recovery evidence. Guild Secret Ally, Betrayal, physical Ornithopter combinations and full module acceptance remain unfinished.
 
 **Richese Nexus Secret Ally update, 10 September 2026:** the existing held card now has a shipment choice that moves up to five actual counters at the one-counter price. It creates no No-Field marker, changes no component identity and retains typed Homeworld reserves and native Ixian direct HMS entry. Controls distinguish physical forces from charged forces, with the original card inspector unchanged. [NEXUS_RICHESE_RUNTIME.md](NEXUS_RICHESE_RUNTIME.md) records scope, recovery and verification; native two-marker Cunning, Betrayal and complete module acceptance remain unfinished.

docs/IMPLEMENTATION_STATUS.md

@@ -1,5 +1,7 @@
 # Dune implementation status
 
+**Guild Nexus Secret Ally checkpoint, 10 September 2026:** [NEXUS_GUILD_SECRET_ALLY_RUNTIME.md](NEXUS_GUILD_SECRET_ALLY_RUNTIME.md) records one explicitly selected Guild-priced shipment for an unallied holder with Guild absent. Reserve, physical cross/abstract-return and independently legal world-to-world routes preserve actual faction identity, typed custody, ordinary movement and bank payment. Fremen retain their free reinforcement choice; the separate paid southern route reaches beyond its range without storm privileges or off-planet triggers. Private controls and all four bot profiles share source-aware price/permission; binding shipment promises can rely on the card. Exact committed records and an independent outcome marker preserve arrival alliances and later movement without inventing native Guild responses. **Final types, lint, all 4,162 offline tests, production build and 40 HTTP/session tests pass.** Twenty-six new cases include real Moritani arrival alliances and production SQLite races, corruption rejection and private recovery. Review also repaired an older Cunning fixture's post-auction card-availability assumption; ten repeated runs passed 190 cases. Two three-seat browser rooms passed paid Fremen shipment/movement, mixed Emperor Homeworld shipment, desktop/phone controls and six private refreshes. The 03:46 UTC backed-up restart preserved all **3,612** opening games and restored twelve earlier private seats; final comparison preserves every opening version/hash, with two browser and thirty HTTP rooms added. Homeworld-return interpretation was asked of the user; that route, concealed transport, Betrayal and complete module/mode acceptance remain gated. Automation remains removed.
+
 **Guild Nexus Cunning checkpoint, 10 September 2026:** [NEXUS_GUILD_CUNNING_RUNTIME.md](NEXUS_GUILD_CUNNING_RUNTIME.md) records a second paid native Guild shipment within the original combined turn, followed only by unused Hajr movement. Original shipment/movement history, typed Homeworld sources, cross/return routes, interception and later entry effects retain their rules. Private controls and all four bot profiles share availability; new binding shipment promises recognize the extra opportunity. Native Karama and paid BG conversion preserve the original source, and countering conversion restores it. Independent review fixed a later Moritani alliance freezing the remaining Hajr continuation; transport validation also rejects a same-territory cross-shipment. **Final types, lint, all 4,136 offline tests, production build and 40 HTTP/session tests pass.** Thirty-seven new cases include genuine nested interruptions, pending-frame corruption and competing production SQLite requests. Two three-seat browser rooms passed second shipment/Hajr and cancellation, desktop/phone controls and six private refreshes. A raw internal event notice found visually was corrected and verified by final rendering tests; earlier pending screenshots precede that text correction. All **3,580** opening room versions/hashes remain unchanged, with two browser and thirty HTTP rooms added. Guild Secret Ally/Betrayal, the physical Ornithopter combination, remaining native cancellation/arrival gaps and complete module/mode acceptance remain gated. Existing server reused, no restart due; automation remains removed.
 
 **Richese Nexus Secret Ally checkpoint, 10 September 2026:** [NEXUS_RICHESE_RUNTIME.md](NEXUS_RICHESE_RUNTIME.md) records one-to-five actual reserve forces at the one-force price in the ordinary shipment pipeline. Native Guild/Fremen pricing, typed Homeworld reserves, native Ixian HMS entry, Guild prevention, BG accompaniment and real Terror entry retain their own rules. Private controls and all four bot levels share the quote; binding shipment promises recognize the affordable discounted source. Exact saved declarations and independent outcome markers protect pending and terminal history through corruption checks, competing SQL requests, Truthtrance and later turns. Review fixed the consumer's omitted native HMS destination. **Types, lint, all 4,099 offline tests, production build and 40 HTTP/session tests pass.** Thirty new cases and two three-seat browser rooms cover allowance/prevention, typed Emperor sources, desktop/phone controls and six private refreshes. The 02:48 UTC backed-up restart preserved all **3,548** opening games and restored twelve earlier private sessions. Final comparison leaves all opening versions/hashes unchanged, with two browser and thirty HTTP rooms added. Native Richese Cunning, Betrayal, foreign-Homeworld tariff integration and complete module/mode acceptance remain gated. The [Guild source audit](NEXUS_GUILD_RULES.md) prepares its distinct extra-shipment, borrowed-route and payment effects without claiming runtime completion. Automation remains removed.

docs/NEXUS_CARD_RUNTIME.md

@@ -1,5 +1,7 @@
 # Nexus cards: common lifecycle checkpoint
 
+**Later Guild Secret Ally runtime:** [NEXUS_GUILD_SECRET_ALLY_RUNTIME.md](NEXUS_GUILD_SECRET_ALLY_RUNTIME.md) records explicitly selected Guild prices, cross/return routes, typed Homeworld sources, paid Fremen reinforcement and committed shipment history. The card changes one shipment, without creating a native Guild or a real alliance. The Homeworld-return ruling and full module completion remain pending.
+
 The later [Richese Secret Ally checkpoint](NEXUS_RICHESE_RUNTIME.md) adds an ordinary physical reserve shipment priced as one force; its other effects and complete module acceptance remain gated.
 
 The later [Guild Cunning checkpoint](NEXUS_GUILD_CUNNING_RUNTIME.md) adds a separately recorded second shipment and remaining Hajr movement within the native Guild turn. Secret Ally, Betrayal and complete module acceptance remain unfinished.

docs/NEXUS_GUILD_RULES.md

@@ -1,5 +1,7 @@
 # Spacing Guild Nexus: shipment source contract
 
+**Later runtime checkpoints:** [Guild Cunning](NEXUS_GUILD_CUNNING_RUNTIME.md) implements the extra-shipment continuation. [Guild Secret Ally](NEXUS_GUILD_SECRET_ALLY_RUNTIME.md) implements supported paid routes using the [focused source resolution](NEXUS_GUILD_SECRET_ALLY_RULES.md). The original audit below remains historical source evidence; its Homeworld-return question has now been sent to the user.
+
 Source audit, 10 September 2026. This documents the three printed panels and their integration boundaries. It does not implement them or certify complete Guild, Homeworld, Nexus or expansion compliance. [Common Nexus lifecycle](NEXUS_CARD_RULES.md) and existing release gates continue to apply. No user question was sent during this audit.
 
 ## Primary evidence

docs/NEXUS_GUILD_SECRET_ALLY_RULES.md

@@ -0,0 +1,47 @@
+# Spacing Guild Nexus Secret Ally: route and price contract
+
+Source audit, 10 September 2026. This is a source-backed implementation contract, not certification of the whole card or either expansion module. The broader [Guild audit](NEXUS_GUILD_RULES.md) remains relevant to Cunning and Betrayal.
+
+## Evidence checked
+
+The original Guild component was visually reread in the [photograph of GF9's twelve Nexus cards](https://boardgamegeek.com/image/7767032/dune-ecaz-and-moritani), using the existing local inspection copy `/tmp/dune-nexus-cards.jpg`. Its Secret Ally panel grants Guild shipment rates and expressly adds cross-planet shipment or return to the holder's reserves as their shipping action. It applies when Guild is absent. It does not promise all Guild advantages.
+
+Fresh searches retrieved official [base rules](https://www.gf9games.com/dunegame/wp-content/uploads/Dune-Rulebook.pdf), [November 2020 FAQ](https://www.gf9games.com/dune/wp-content/uploads/2020/11/Dune-FAQ-Nov-2020.pdf), and [E3 rules](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf). Direct opening of the latter two URLs returned 403; their indexed publisher passages were checked against the existing E3 PDF/text. The [designers' page](https://futurepastimes.com/dune-board-game/) links the FAQ, but its short-link fetch failed. No Guild Secret Ally/Homeworld clarification was found in these sources. Tournament revisions and comments were not treated as official rulings.
+
+## Supported ordinary routes
+
+Use the holder's one ordinary shipping action in their own combined turn. Preserve their actual faction, typed counters, legal source group, stance and destination restrictions. The card does not add a second shipment or flexible Guild turn order. Rates apply to the whole selected physical group, rounding once upward. [GF9 base rules, pp19 and 23](https://www.gf9games.com/dunegame/wp-content/uploads/Dune-Rulebook.pdf#page=19)
+
+| Route | Price for `n` physical forces | Boundary |
+| --- | --- | --- |
+| Off-planet reserves to an Arrakis stronghold | `ceil(n / 2)` | Ordinary legal destination, including native Ixian direct HMS permission only |
+| Off-planet reserves to another Arrakis territory | `n` | Ordinary storm and occupancy restrictions |
+| One Arrakis territory to another | Same destination tariff | Guild cross-shipment; neither source nor destination may be in storm |
+| One Arrakis territory to own reserves, Homeworlds off | `ceil(n / 2)` | Explicit card grant; no second halving |
+| Fremen southern reserves to Arrakis through the paid card route | Same destination tariff | Paid cross-shipment; distinct from free native reinforcement |
+
+The printed return grant exceeds the ordinary Guild alliance: the November FAQ says an ordinary Guild ally cannot return to reserves. Do not accidentally remove the Nexus permission by reusing only the normal alliance predicate. The Guild is absent, so payment goes to the bank; no native Guild collection or interception owner is created. [GF9 November FAQ, p9](https://www.gf9games.com/dune/wp-content/uploads/2020/11/Dune-FAQ-Nov-2020.pdf#page=9)
+
+## Fremen composition
+
+The official FAQ explicitly permits allied Guild cross-shipment from Fremen reserves, treating them as one on-planet territory outside the board. Composing that interpretation with the Nexus cross-shipment grant supports a paid southern-reserve route without Great Flat range. It keeps normal cross-shipment storm exclusion. The free native reinforcement route, including its own Advanced storm rule, remains separate. This is a composition of published rules, not a Nexus-specific FAQ answer. [GF9 November FAQ, p5](https://www.gf9games.com/dune/wp-content/uploads/2020/11/Dune-FAQ-Nov-2020.pdf#page=5)
+
+Native Homeworld custody can represent the same outgoing reserves without creating another reserve pool. A paid Fremen source remains on-planet for effects that distinguish off-planet shipping. Likewise, cross-shipping existing Arrakis forces does not trigger an off-planet arrival merely because its price is paid. Preserve the actual source classification for BG accompaniment and Heighliner. [GF9 E1, p5](https://www.gf9.com/Portals/0/Documents/GF9/IxianAndTleilaxuRulebook.pdf#page=5)
+
+## Homeworld prices and the unresolved return
+
+**Price and permission are separate.** E3 already permits world-to-world shipment by non-Guild factions, with a one-spice-per-force tariff and Guild half price. The card's Guild-rate clause therefore supports `ceil(n / 2)` for an independently legal world-to-world invasion. This price composition borrows no high-Junction advantage and grants no new destination. Preserve the source custody and own/ally-world restrictions. [GF9 E3, p10](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf#page=10)
+
+**Arrakis to native reserves remains a material interpretation question when Homeworlds are enabled.** Reserves occupy native Homeworld discs; E3 expressly restricts Arrakis-to-Homeworld shipment to Guild, with a named Homeworld-advantage exception. The Nexus expressly grants reserve return. A card-specific exception is plausible, especially because it already exceeds normal alliance rights. Conversely, E3's specific Homeworld restriction can be read as limiting that grant. Its Nexus FAQ resolves neither reading. [GF9 E3, pp9–11 and 16](https://www.gf9games.com/dune/wp-content/uploads/EcazMoritani-Rulebook-LOWRES.pdf#page=9)
+
+The concrete question is whether Secret Ally's reserve-return permission overrides that restriction **for the holder's own native reserves**. An affirmative answer does not grant Arrakis-to-arbitrary-foreign-Homeworld transport. Until resolved, expose this particular return as unfinished; ordinary Arrakis routes and independently legal world-to-world discounted shipment need not be blocked.
+
+## Implementation boundaries
+
+Consume the actual held Nexus atomically with a validated paid declaration, preserving an original route, source, typed group, destination and price receipt. A rejected request must not spend it. Later continuations must match the original declaration rather than infer it from a current hand or reset a usage flag. Private offers reveal no other holder's Nexus identity.
+
+Reuse `guildShipmentCost` for paid cross/return tariffs. Do not price the paid Fremen route through `reserveShipmentCost`, whose native Fremen branch intentionally returns zero. World-to-world pricing needs an explicit quoted rate modifier after route validation; changing the player's faction to Guild would also change custody and permissions. The native `quoteGuildHomeworldShipment` explicitly enforces Guild identity and ordinary Guild counters, so it is not a safe borrowed-return adapter without a separately settled contract.
+
+Generic Karama cannot target an absent native Guild player. That does not establish universal immunity for every borrowed effect. Preserve supported arrival reactions and existing independent Karama payment routing; do not stack two Guild half-rate modifiers into quarter price. Richese concealed No-Field price/transport composition remains its separate documented boundary, without blocking actual physical groups unnecessarily.
+
+Required runtime evidence includes odd/even prices, all supported route types, typed custody, Fremen free-versus-paid choices and storm behavior, native Ixian HMS access, current-source rejection, actual entry continuations, replay/JSON recovery, private projections and concurrent persistence. This audit changed documentation only.

docs/NEXUS_GUILD_SECRET_ALLY_RUNTIME.md

@@ -0,0 +1,53 @@
+# Guild Nexus Secret Ally runtime
+
+The [source contract](NEXUS_GUILD_SECRET_ALLY_RULES.md) distinguishes printed Guild shipping rates and routes from a real alliance or native Guild faction powers. This checkpoint implements the absent-Guild holder's explicit use for one ordinary shipment. It does not certify complete Guild, Nexus, Homeworld or expansion play.
+
+## Authoritative shipment and custody
+
+An unallied holder chooses the card for an unused Shipment and Movement shipment. Merely holding it does not change prices or legal destinations. An ordinary reserve shipment costs the Guild tariff: round half a spice per physical force upward for a stronghold, and one spice per force elsewhere. Native Homeworld reserves retain their exact ordinary/special source allocation. Native Ixian access to the mobile stronghold remains separate.
+
+The same grant permits one-territory cross-shipment or a return to abstract reserves. Actual multi-sector ordinary and special counters are selected and transferred; a destination cannot be the origin territory. The action uses the normal shipment opportunity and leaves the holder's ordinary movement available. The grant conveys neither flexible Guild turn order nor collection of another player's shipping payment.
+
+Fremen can retain their ordinary free reinforcement option. Choosing the Nexus instead pays Guild rates and allows destinations beyond the free Great Flat range, with the paid route's storm exclusion. The existing reserve withdrawal pipeline preserves typed Homeworld custody. These on-planet southern reinforcements do not become off-planet shipping for advisor accompaniment or Heighliner income.
+
+For an independently legal world-to-world shipment, the Nexus changes only the price to half a spice per force, rounded upward. Actual foreign/native source custody, special counters, own-world return restriction and ally-world prohibition remain authoritative. The card does not grant arbitrary Arrakis-to-foreign-Homeworld transport or high-Junction sponsorship.
+
+The material interaction between the card's return to reserves and the Homeworld native-Guild route restriction has been asked of the user. Until resolved, returning to Homeworld reserves with this grant is unavailable. Concealed No-Field transport retains its existing separate implementation boundary.
+
+## Payment, arrival and saved history
+
+Guild is absent from the seated faction roster, so the card does not invent a native Guild interception, discount cancellation or income recipient. A valid use immediately discards the physical Nexus and commits the shipment and bank payment. Other factions' genuine arrival decisions still occur normally. A later alliance formed by a valid entry effect does not invalidate the already completed shipment.
+
+The [pure receipt](../game/nexus-guild-secret-ally.ts) records the absent-Guild roster, original owner and turn. The engine adds the exact committed reserve, cross or Homeworld declaration and a separate latest-outcome marker. These consistency checks preserve historical evidence without freezing later movement, resources, alliances or card custody. They are not cryptographic authentication of arbitrary replacement saves. A Secret Ally shipment cannot retain a fabricated native Guild interception.
+
+A binding Truthtrance shipment answer can use this explicitly selected discounted source. The completion search preserves the actual typed withdrawal and returns the matching card-use action only to the entitled respondent. Ordinary shipment or movement cannot evade an accepted promise.
+
+## Verification and remaining work
+
+Focused verification passes **26 new cases**: six pure receipt/tariff cases, seven authoritative engine cases, four production SQLite recovery cases, and nine controls/all-profile bot cases. Actual paths include typed Emperor cross/return and world-to-world shipment, Fremen paid versus free reinforcement, native Ixian HMS access, an affordable-only-through-Nexus Truthtrance witness, and real Moritani placement, later arrival alliance and ordinary movement. SQLite checks cover competing shipment requests, lost acknowledgment, exact source/price corruption, private views, unrelated-room preservation and reconnecting before an actual alliance reply. The production build also passes; full repository and live HTTP/browser evidence are recorded separately below. The remaining Homeworld-return interpretation, concealed transport, Guild Betrayal, other native cancellation interactions and complete expansion games retain their release gates.
+
+## Player controls and bot evidence
+
+The [source-aware options](../game/nexus-guild-secret-ally-options.ts) require the owned current offer, held Guild Nexus, absent native Guild and ordinary unused shipment. The main shipment selector is explicitly unchecked by default; a separate checkbox in the [Homeworld panel](../components/homeworld-shipment.tsx) applies the same card only to that independently legal route. Prices describe the selected source. Fremen retain their free native choice and see why the selected paid route permits destinations beyond its range while excluding storm. A selected card does not silently attach itself to an ordinary movement.
+
+The [transport preview](../game/transport-quote.ts) keeps physical groups, elite allocations, same-territory exclusion and native permission checks. It adds the exact card permission for cross-shipment and abstract reserve return, with explicit guidance for unsupported Homeworld return and paid Fremen reserve entry through the normal reserve selector. The [Homeworld quote](../game/homeworld-shipment-options.ts) validates source and destination custody before applying the chosen tariff. Native Guild Homeworld transport remains its own route.
+
+All four bot profiles generate Guild-priced reserve groups before filtering by ordinary affordability, consider paid Fremen destinations beyond the free range and use the explicit source for eligible cross/return candidates. Ordinary free or equally priced routes preserve the card. Homeworld candidates use the discounted budget only with a current legal offer. The shared payment filter recognizes Guild and Richese sources separately; existing shipment-promise filtering consumes the physical action and the server's current source-specific completion witness. This is legal-policy coverage, without additional AI calibration claims.
+
+Nine new consumer tests passed: six [controls cases](../tests/nexus-guild-secret-ally-controls.test.ts) and three [all-profile bot cases](../tests/nexus-guild-secret-ally-bots.test.ts). They cover Basic/Advanced explicit selection, odd/even prices, Fremen free versus paid and storm behavior, typed cross/return, combined Emperor Homeworld custody, native Ixian HMS access, private/stale/blocked source fences and affordability. Sixty-eight existing shipment, Homeworld, Richese, promise and reference regressions passed in a separate compatibility run. Owned-file lint passed. The cross-shipment tests document their conserved pre-declaration Arrakis staging; module setup, card ownership and actual submitted shipment effects use the engine.
+
+## Browser checkpoint
+
+Two fresh three-human rooms used final session IDs before genuine fixture initialization, then an exact lobby state/version compare-and-swap. No existing room was staged. In `SE4XQL2Y`, the Fremen player selected the paid card route for five forces to Arrakeen at three spice, then moved those five normally to Hagga Basin. The final version is 4, with 17 spice and 15 reserves. In `WBW3Q5B4`, the Emperor selected three ordinary Kaitain forces and two Salusa Sardaukar for a Guild-priced invasion of Giedi Prime. Five typed forces arrived at three spice; version 3 retains 15 native reserves, three reserve Sardaukar and zero spice, with ordinary movement unused.
+
+Desktop 1440px and phone 390px screenshots were captured and visually inspected. Both checkbox defaults, selected prices and physical source inputs were exercised through the real browser controls. The final Homeworld explanation displays the selected Guild tariff. No horizontal overflow or page errors occurred. All six private sessions were refreshed and restored with unchanged completed versions, no hidden opponent hand/traitor/spice disclosure and no internal shipment/history fields in the player view.
+
+The read-only `/tmp/dune-guild-secret-restore.cjs` verifies the six sessions; `/tmp/dune-guild-secret-preserve.cjs` compares the opening room baseline. All 3,612 original room state hashes and versions remained unchanged. Screenshots are `/tmp/dune-guild-secret-fremen-desktop.png`, `/tmp/dune-guild-secret-fremen-phone.png`, `/tmp/dune-guild-secret-emperor-desktop.png`, `/tmp/dune-guild-secret-emperor-phone.png` and `/tmp/dune-guild-secret-emperor-phone-sources.png`. Browser cross/abstract-return interactions were not separately exercised in these two rooms; their actual actions are covered by engine and consumer regressions. Full-check, build and HTTP totals are recorded by the final project checkpoint.
+
+## Integration verification
+
+The first broad check found one older Guild Cunning SQL fixture failure: a real intervening auction could distribute all Karama copies before an unnecessary acquisition from the draw pile. The fixture now removes that acquisition, reserves one existing physical Hajr before the intervening phases, and reuses an already-held matching card. It does not duplicate a card or take one from an opposing hand. Ten independent repeated runs passed the eleven Cunning engine and eight SQL cases each, 190 case executions in total.
+
+The live HTTP/session suite passes **40/40** cases. The controlled **03:46 UTC** restart backed up and preserved all **3,612** opening saved-game versions and state hashes. Twelve earlier private Guild Cunning/Richese seats restored without errors. After the two new browser rooms and thirty HTTP rooms, all opening games remain unchanged and the database contains **3,644** rooms. The current server remains running and no recurring automation was created.
+
+Final `npm run check` passes types, lint and **4,162/4,162 offline tests** with no skipped cases after both the fixture correction and selected-tariff display fix. The final production build also passes. These checks establish this recorded subsystem scope, not complete expansion or rules-mode acceptance.