Dune/docs/HOMEWORLD_RUNTIME_IMPLEMENTATION.md

Homeworld setup and native reserve runtime

9 September 2026. This checkpoint connects the physical Homeworld model to the authoritative game, player table and AI. Public Homeworld starts remain disabled. It does not certify Homeworld battles, occupation, card effects or complete Advanced/expansion games. The earlier component checkpoint remains in HOMEWORLD_IMPLEMENTATION.md.

Classic Skills and Discovery — 6 October 2026

Fresh private prototypes now support Homeworlds with either Leader Skills or Discovery: Basic/Advanced, two–six unique base factions, no other overlays. Use existing start-prototype.ts --profile leader-skills or --profile discovery on a fresh ready lobby with Homeworlds enabled. Genuine game runner profiles are homeworld-skills and homeworld-discovery. Original fourteen skill offers, seven Discovery cards/eight tokens, first hands and native placement remain authoritative; no existing save is converted.

The authorized root revision, physical PDF21–23, permits variants together or separately, keeps Homeworlds outside Arrakis and preserves their normal battle rules except printed modifications. This is permission to compose these prototypes, not a ruling for every interaction or a complete mode. Nullable custody now remains legal through actual skill assignment before the original force-placement stage.

Suk quotes use physical normal/elite casualties and real native or visiting Homeworld pools. A native save remains at that same home; it cannot redeploy freely. An external save returns to actual native reserve homes. When Emperor has both homes, human controls require an exact ordinary/elite allocation; minimal bots allocate the return to the primary home. Allowing both types at either native home is a prototype implementation interpretation, not the PDF22 ordinary-revival placement rule and not a new user/publisher ruling. The quote validates before mutation and conserves physical custody, Tanks and reserves. Battle costs, leader death and card cleanup do not repeat. Bureaucrat's existing invoice redirection now accepts this bounded profile. Discovery's original Maker, next-turn entry and nested shipment paths need no alternate mechanics.

Verification:17/17 new behavioral cases;94/94 affected tests across12 files; types/lint and build pass. Four original six-seat Basic/Advanced games using all four legal AI policies finish2330 accepted/2330 attempts,61 JSON continuations. Skills1125/1125/29 ran on unchanged source tree 4d3f1c5f99bf6a18cac6553a1ecb0bfbe4da35709e91f1384050506fbd98fc00; Discovery1205/1205/32 on 64c0b8ae5286bfdab9019222bb652bf99a7b1f1478eb5b16024844503c930412. Reports are /tmp/dune-homeworld-classic-{skills,discovery}-games-20261006/report.json. These are two source batches, not one final-tree certificate.

Human QA uses isolated existing QA persistence on local port3089, not the protected server. Original fresh human rooms, original CLI setup and explicit unplayed lotteries feed genuine engine action programmes; no held components are injected. At390px, 3NM6MS4Tv11 actually submits trained Suk rescue: Junction retains three ordinary visitors; Kaitain has11 ordinary/1 Sardaukar, Salusa1 ordinary/4 Sardaukar, reserves17/5 and Tanks0. CLQYLURHv11 actually submits next-turn Cistern entry for two ordinary/one Sardaukar: reserves17/4, Kaitain12/0, Salusa1/4, preserving the earlier actual turn-one internal move. Both rendered surfaces have document width390; fresh state and accessibility were observed after submission. Nested shipment has engine/runtime coverage, not an additional human submission claim.

Native expansion combinations, other overlays, Advanced Atreides Suk/KH, captured replacement, Diplomat Homeworld retreat and the separate Emperor Face Dance allocation question remain guarded. No public start, deployment, complete rules, recovery/privacy assurance or AI calibration is certified.

Implemented behavior

Game.homeworlds is optional for existing saves. An enabled fresh lobby stores {custody:null} until the genuine setup pipeline places forces, after prediction and traitor choices. Setup then records typed native reserves and Advanced Emperor's separate Salusa allocation. The offline-only initializer does not replace the public start gates or dispatch through the room API. It supports the currently implemented base/Ix deck sets; CHOAM/Richese and Ecaz/Moritani deck construction still rejects instead of substituting a different deck.

Native primary counts derive from the player's aggregate reserves; Salusa is an allocation within those totals. Foreign garrisons remain separate physical pools. Reads, actions and automatic normalization validate custody and all twenty physical counters, including special-counter identities across board, Tanks, native worlds and foreign worlds. Missing Salusa allocation is rejected, not reconstructed. Ixians have seven Cyborgs total, initially four in reserves and three in the mobile stronghold. The earlier custody limit of four is fixed.

Basic Homeworld setup retains Emperor's five Sardaukar and Fremen's three starred counters. They count as strength one in ordinary Basic combat and do not activate Advanced faction responses. Basic winner casualties preserve the owner's physical normal/special selection. Basic revival and Ghola preserve identity without imposing the Advanced one-special-counter-per-turn limit. Ixian special-counter rules retain their separate behavior.

The Advanced Emperor's emperorHomeworldMove action transfers an explicit normal/Sardaukar group between Kaitain and Salusa. The server checks current owner, phase, movement budget, pending controls and a public-state event. It spends one movement, charges no spice and conserves aggregate reserves. Starting with movement passes an unused shipment. A real Hajr supplies the second movement; active Ornithopter composition remains explicitly blocked. Homeworld permission is independent of ordinary faction Karama cancellation.

Ordinary native-to-Arrakis shipments now withdraw exact typed Homeworld sources. An omitted selection is inferred only when the allocation is unique; ambiguous partial draws from both Imperial worlds require explicit choices. The same transaction places the matching Arrakis counters once. The chronicle records the Homeworld sources and cost. No-Fields retain their separate source contract. Normal force revival, Emperor special-Karama force revival and Ghola deposit Advanced Emperor's normal forces on Kaitain and Sardaukar on Salusa, even when those counters previously moved between worlds. Other factions return to their one native reserve pool. Completed Ghola discard receipts bind the full Homeworld custody as well as aggregate counters.

The public table displays each native world's physical counts and population, with the full local-art card inspector. Emperor controls select a movement's origin and force types and the Salusa contribution to a combined shipment. Kaitain's complementary contribution is displayed and submitted explicitly. Invalid source counts disable submission; stale choices are revalidated by the server. Shared public helpers give all four AI levels legal typed shipment sources and a bounded transfer policy to restore Imperial population. They do not read opponent hands, decks, predictions or spice.

The server's shipment-completion search uses the same source helper. Its mixed-Imperial proof is tested as an internal future integration seam: actual Advanced Truthtrance shipment questions still remain Basic-gated.

Verification scope

• Genuine setup: sixteen six-seat setups span the eight supported factions, Basic/Advanced and all four profiles; another eight mixed-Ix setups cover two through five seats. Unsupported deck combinations reject unchanged. Prediction/traitor privacy, physical card uniqueness and JSON recovery pass.
• Actual actions: transfer, Hajr, wrong-owner/stale/blocked rejections, mixed native shipment and a Sardaukar's shipment → Storm death → revival on Salusa. Ghola's saved completed-effect frame drains once; changing only its Salusa allocation rejects despite unchanged aggregate counters.
• Basic counters: both Emperor and Fremen retain strength-one stars, legal casualty choices, repeated typed revival and Ghola. Ordinary Basic behavior without the module remains unchanged.
• AI: every offered movement/shipment candidate is individually accepted by the real dispatcher across all four levels. Explicit sources, unavoidable elite draws, hidden-information independence, Basic exclusions and no oscillating population repair are verified.
• In-memory production SQL: duplicate and competing transfer requests commit one version; fresh module instances and authentication restore the same physical state/private hand. Corrupt missing Salusa state rejects without writes. Unrelated rooms remain unchanged.

npm run check passes typecheck, lint and 3,152 offline tests. The final production build passes; npm test -- homeworld reference passes 106 focused cases. Logs: /tmp/dune-homeworld-runtime-check-final.log, /tmp/dune-homeworld-runtime-build-final.log, /tmp/dune-homeworld-runtime-focused-final.log, and /tmp/dune-homeworld-actions-engine-final.log.

The live browser used a new named QA room, VQ6ALGRE. Genuine setup preceded a documented conserved dual-source phase position. UI actions shipped three forces (one normal from Kaitain; one normal and one Sardaukar from Salusa), then moved three normal forces from Kaitain to Salusa. The final position has Kaitain 7 normal + 2 Sardaukar; Salusa 6 normal + 2 Sardaukar; Arrakeen three forces including one Sardaukar; seventeen reserves and seven spice. Refresh preserved it. Invalid source input disabled shipment, enlarged Kaitain opened from the table, and 390×844 inspection found no horizontal overflow in the world panels or inspector. Desktop card and phone movement screenshots were visually reviewed; this is bounded sampling, not full module acceptance.

Forty live HTTP tests pass. Twenty ordinary two-player Basic games finish 3,079 accepted actions with no rejected candidates or stalls, using seed 20261026 and unchanged source fingerprints. This small regression sample is not new strength calibration or Homeworld/full-player-count verification. All 2,617 pre-existing room versions and hashes remain unchanged. The separate QA room and thirty HTTP-test rooms were added. The development server remains running from the 07:53 UTC controlled restart; no hourly restart was yet due during this checkpoint. The removed automation stays removed.

Remaining integration

Homeworld population values currently describe physical state; they do not yet apply high/low advantages, charity/free-revival bonuses or occupation penalties. Foreign Homeworld shipment permissions, Guild sponsorship, alliance rules, occupation qualification/turnover, Homeworld combat and aftermath, explosions, all card effects, occupation Collection, Ecaz victory and full AI policies remain unfinished. Ordinary special arrival/return routes still need the reserve integration audit, including Ambassador, Face Dance, No-Field and card-specific destinations. Emperor transfer with Ornithopter is also pending.

Occupation history must remain distinct from population and current foreign forces. Some turnover/expiry interpretations still need source resolution. Do not infer a complete mode from a valid physical state or successful native transfer. No release gate, saved-game migration or hosting access was changed.