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 optional-module compositions — 6 October 2026

The fresh classic Homeworld prototypes now compose Skills, Discovery or both, with original unused Tech at three or more seats and/or original Stronghold Cards in Advanced at two or more seats. Basic/Advanced two–six unique base factions; both optional industry/card modules require Advanced3+. Existing leader-skills --discoveries and discovery private room entries preserve selected Homeworlds and original components; no parallel setup or save conversion. The runner adds ten profiles at stable bands6600–7500 while retaining existing6400/6500 names/seeds. Families homeworld-skills, homeworld-discovery and homeworld-discovery-skills add -tech, -stronghold or -stronghold-tech under those prerequisites.

Authorized PDF21–23 expressly permits variants together/separately. Original all14 offers, DS7/8, first-Storm industry ownership, end-Mentat held cards and native reserve placement remain. Nested battles get no Homeworld native bonus. Typed Suk returns use actual homes; support is already paid before rescue, while later Cistern income is a separate printed reward. Native saves still stay at their original home; the external Imperial split remains the implementation interpretation recorded below, not ordinary revival placement. Printed industry accrues once and pays at phase end; Guild-only transport is excluded. Held Arrakeen support and Carthag poison defense remain source-local, not borrowed by Homeworlds or Cistern. Physical cleanup precedes mandatory winner Tech choice without replaying armies or casualties.

New semantic cases14/14; affected union145/145 across17 files; types/lint and build pass. Original private room entry also exercises real combinations and rejects two-seat Tech/Basic Strongholds with the saved lobby unchanged. Four-policy original six-seat games cover ten added profiles: thirteen completed7879/7879 actions with207 JSON continuations on unchanged tree bf9b1f8a59f77494c1f2dcbd79326705aae1a00c37bc09bd3a157d4de9fb0851. One Advanced homeworld-discovery-stronghold seed20268015 stopped at turn8/Shipment after1110/1110/29 because an internal view-copy assertion treated four optional undefined advisor-response properties as different from JSON omission. That incidental assertion was deleted, not re-pinned; physical custody, rival-privacy checks and actual restored play remain. The preserved capture completes19 further actions. The same original fresh sample then completes1129/1129/30 on unchanged tree b47a9b126b4f7edf4a29a346fc124ee9427e22d7659c3f0762b0b16ad96fe2f2. Thus fourteen completed original samples total9008/9008/237 across two source batches, not one final-tree certificate or fourteen uninterrupted passes on the first tree. Reports/capture remain under /tmp/dune-homeworld-optional-*-20261006; no rules guard was bypassed.

Human QA: original HTTP four-seat lobbies, real host module toggles, original private CLI and explicit unplayed offer/card/token lotteries feed genuine action programmes. XJCJ3H3Wv17 actually submits trained Cistern Suk: three ordinary remain inside, reserves17/5 and Tanks0; Kaitain11 ordinary/ 1 Sardaukar, Salusa1/4. Separate Collection pays Cistern2; original industry and held-card custody remain. WM8E7CFGv17 actually chooses Spice Production from two real mandatory Tech options after two genuine Homeworld battles and original winner cleanup. Emperor retains one ordinary visitor in Southern Hemisphere, native home is empty, reserves14/4, Tanks2/0 and original parent army3 with1 Sardaukar. The defeated Fremen retains Axlotl; physical armies are not replaced by the Tech action. Both390px surfaces, choices and fresh resulting state were observed. These were working-tree controls, not a pushed revision/deployment claim. Both tabs closed; temporary human scripts removed.

Nexus, native expansion rosters, unrelated previews/variants and pending specific rulings remain separate in this checkpoint. Public starts, full combinations, comprehensive assurance, calibration and deployment stay open.

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.

Gameplay checkpoint e2dcebca35a89ed1e1d129b1fbc2428378b1d700 is pushed. An exact build and owned isolated-QA restart retain both originalv11 tables; each displays the full checkpoint revision at390px. The actual Homeworld guide paragraph renders without overflow. All QA tabs are closed and the temporary human lottery/staging scripts were removed. Exact container run37427758535/job112151199196 completed successfully; final job record confirms isolated storage/HTTP verification7 finished before publication9. No protected server was deployed.

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.