Dune/docs/ADVANCED_SETUP_TEST_SEAM.md

Shared initializer seam and genuine base setup ordering

Implemented checkpoint, 7 September 2026. Scope: the six original factions, Basic/Advanced, two through six players, no expansions or optional modules. The shared initializer, persisted setup stages, private projections, bot stage guards and setup controls are implemented. The public Advanced and expansion start gates remain closed. This document supersedes its earlier proposed design; it does not certify complete Advanced readiness.

At this checkpoint the coordinator reports 1,446 registered unit/rules/client/component tests passed, including the 456-case Advanced setup matrix. Both new Basic calibration batches completed 192 games with 59,380 accepted actions and zero rejected candidates or checked failures. The final 119-test persistence suite also passed. The separate 456-game Advanced full study also completed, with 116,270 accepted actions and no rejected candidates or checked failures; its detailed evidence remains distinct from the setup matrix.

Published ordering and historical defect

The official base rulebook, printed p18, places BG prediction “After step 1 (Positions) in the Setup Phase”. Printed p6 orders the normal setup as Positions, traitor dealing/selection, starting spice, force placement, starting Treachery Cards, then the turn marker. Advanced BG placement follows Fremen placement and becomes a fighter when alone. Prediction therefore precedes private traitor/treachery information, and normal treachery dealing follows force-placement choices. GF9 base rulebook, pp6 and 18

The official CHOAM rulebook's Leader Skills variant changes the usual order: positions and BG prediction precede early treachery and skill dealing. That confirms that early treachery is a specified variant change, which is not part of this no-module setup. GF9 CHOAM & Richese, p8

The original source review used the publisher PDF/text /tmp/dune-rules/base.pdf and .txt, plus official-domain indexed results reproducing base p6/p18 and CHOAM p8. Its targeted November 2020 FAQ searches found no setup-prediction timing override. Direct fresh access to that FAQ returned HTTP403, so this is not a claim that every page of a newly downloaded FAQ was reread. This implementation update preserves those source facts and access limits; it does not claim new FAQ retrieval. GF9 November 2020 FAQ

Before this correction, the initializer dealt both private pools and fixed resources before accepting prediction, traitor or variable force-placement inputs. BG could see its cards and Fremen's chosen distribution before predicting; players could choose traitors or force placements with knowledge of starting treachery. That was an information-order defect in Basic as well as Advanced. The older calibration artifacts remain unaltered historical evidence of that implementation's behavior, not evidence that its setup matched the published order.

Implemented shared entry points

game/engine.ts now uses one private initializeSetup from both public start and the exported offline initializeBaseGameForAudit(state: Game): Game. The latter clones its input, validates a fresh isolated lobby, invokes the shared initializer and returns normalizeAutomaticGame(g). It never flips an already initialized Basic game into Advanced.

The public lobby dispatcher still checks host authority. Public start still requires at least two players and all players ready, and rejects Advanced, expansion factions and selected expansions. Maximum-six and duplicate-faction protection on the public path continue to come from valid lobby construction; this document does not claim that the isolated private start function validates every possible corrupted roster. newPlayer, createGame, joinGame, circle-selection and readiness actions remain the constructors used by setup and full-game audit fixtures.

The offline seam separately validates two through six unique player IDs/factions, an existing host, all players ready, base-only factions, no selected expansion or tech-token module, valid owned player circles, lobby/turn/phase freshness, and no existing decks, dealt cards, forces, resources, prediction, typed inventory or pending game work to replace. It rejects repeated initialization and leaves its input unchanged on success or failure. These are concrete fresh-lobby checks, not a general validator for every imaginable corrupted historical state.

There is no player action, HTTP route, query flag or allowUnsupported field that dispatches the audit initializer. Forged fields on public start do not bypass the mode gate. Ordinary room actions continue through applyAction; tests and the offline Advanced calibration import the seam directly. Public Basic and audit Basic initialization are compared on the corrected code under the same seeded shuffle stream.

Persisted stages and private information

Game.setupStage is optional and has exactly three values: prediction, traitors, and forces. These are setup substages, separate from the nine game phases. GameView.setupStage is null for non-setup and legacy rooms. Public setupPending contains only the IDs entitled to act at the current stage, never private card identities or prediction contents.

Stage	Automatic entry/continuation	Accepted input and information boundary
prediction	Fix circles, storm order/dialers and privately shuffle decks. Skip automatically if BG is absent.	Only BG locks its faction/turn prediction. Every hand, traitor pool and force placement is still empty, with starting spice unallocated. No rival receives the secret prediction.
traitors	Deal each participating faction its proper pool exactly once; Harkonnen automatically keeps its four.	Each remaining owner selects one of its own choices. Unused identities return to the traitor reserve. Hands remain empty; force-placement actions are rejected.
forces	After every traitor choice, allocate printed starting spice, fixed forces and Advanced typed reserves.	Fremen places ten tokens among permitted sectors. Advanced BG acts only after seated Fremen completes placement; if Fremen is absent, BG can place immediately. Hands remain empty until every required placement finishes.
Automatic completion	Clear setupStage, deal normal starting hand quantities once, and continue through existing setup/first-Storm routines.	No deal-confirmation or stage-advance action is required. The first Storm input starts with the correctly private complete starting hands.

Advanced Emperor receives five Sardaukar and Fremen three Fedaykin through the shared starting-force routine. Basic BG retains its fixed Polar Sink placement; Advanced BG receives its separate placement opportunity and normal stance settlement. The normal ten-turn marker is represented internally from game creation; this creates no early player choice. Privately shuffling undealt decks does not expose them through viewGame.

The authoritative setup dispatcher checks both action kind and entitled owner against the stage. All four bot profiles use the public stage before enumerating prediction, traitor and force candidates. They preserve the public BG prerequisite that seated Fremen must have completed its ten-force placement. The UI names the stage and waiting owners, hides premature controls, explains the BG wait, and says starting treachery remains undealt until force placement completes. Automatic steps have no extra confirmation control.

Legacy saved setup rooms without a stage keep their already-dealt hands and existing choice flow. They are not reset or redealt. Their already disclosed information cannot be made historically compliant by moving cards back into decks; the new order applies to newly initialized staged rooms. Non-setup saves similarly do not acquire a setup stage.

Completed focused verification

tests/base-setup-order.test.ts covers the following implemented behavior:

• Basic and Advanced stage order, owner rejection, private projection boundaries, immutable prediction, fixed starting resources, Fremen-before-BG placement, and automatic first-Storm entry.
• Fremen starting Fedaykin allocations zero through three over multiple sectors, rejected over-allocation without mutation, physical/typed force conservation, and printed starting hands and spice.
• Public Advanced rejection, forged bypass-field rejection, corrected Basic public/audit equality, malformed audit lobbies, repeated initialization and input immutability.
• Legacy no-stage completion without another hand deal.
• All 57 distinct base-faction subsets of sizes two through six, at all four homogeneous AI difficulties and both normal/reversed physical and actor orders: 456 completed setup cases. Every offered setup candidate is independently passed through actual applyAction, not merely the first candidate that succeeds. The matrix checks private views, no setup stalls, starting custody, elite totals, traitor/card inventory and initial Storm configuration. It is not exhaustive over every seat permutation or possible placement.

tests/bot-staged-setup.test.ts adds five named tests covering all profiles through genuine Basic/Advanced stages, absent BG/Fremen skips, stale projected premature choices, public-only pending IDs, private rival perturbations and legacy flow. The existing four advisor setup tests remain useful for human/AI ordering and printed placement exceptions. Fremen policy currently leaves its initial Fedaykin in reserve; that is legal, not demonstrated optimal. Focused tests deliberately exercise other legal distributions without introducing an unrelated strategy change.

The old tests/bots.test.ts scenario that completed Basic setup and then flipped advanced has now been replaced: the current test creates Advanced from the outset, calls the shared staged initializer, and runs all four AI profiles through full base scenarios. Its previous pass remains historical subsystem evidence and must not be relabeled as authentic setup coverage.

Persistence and full-game evidence boundaries

tests/base-setup-recovery.test.ts contains three new production-room/SQLite tests for private stage restoration, duplicate/stale stage-closing actions, automatic deal exactly once, absent-choice skips, and legacy completion without redealing. The harness reloads the actual room module against persistent SQLite state and exercises its normal optimistic-version writes. The final 119/119 persistence suite passed; terminal session 6233 was explicitly polled to exit 0, with log /tmp/dune-staged-setup-multiplayer-final.log. This is module-level restart and persistence evidence, distinct from a real running server restart.

The completed unchanged Basic study is recorded in AI_STAGED_SETUP_BASIC_CALIBRATION_20260907.md: two 96-game batches, seeds 20260909 and 20260922, 192/192 complete, 59,380 accepted actions, zero rejected candidates, deadlocks, action-limit outcomes, exceptions or selected invariant failures, with matching source fingerprints at both boundaries. It preserves the previous incorrect-setup checkpoint and explains why matching aggregate outcomes do not imply unchanged action order. This is four-player Basic evidence, not an Advanced certification or monotonic difficulty claim.

AI_ADVANCED_SETUP_CALIBRATION_20260907.md separately records the genuine Advanced pilot and the offline harness. The completed 20-game pilot had 7,727 accepted actions, zero rejected candidates or checked failures, and 354 JSON continuation round-trips. The 456-game full study completed with 116,270 accepted actions, 1,984 setup choices and 5,943 actual JSON continuation points; every attempted first candidate was accepted. Its first 20 rows exactly reproduce the pilot, so the pilot is not counted again. Its design uses all 57 rosters, four difficulty shifts and two seed blocks, with actual two-through-six-player marginals; it must not be conflated with the already completed 456-case setup matrix. Its periodic JSON restoration is offline continuation evidence, not D1 concurrency or real network/restart evidence.

The coordinator also verified genuine new Basic browser room WQKDSM8L without manual database staging: prediction preceded private traitors at version 9, when hands and forces were still empty; Fremen AI placement then led to the automatic deal and Storm at version 13, with one starting card in each of the three hands. A fresh invitation restored the prediction stage. The same Basic table subsequently completed atv347 with a turn5 Bene Gesserit victory under voluntary Brutal autopilot, and a fresh invitation restored the finished board and three-card private hand. This verifies the online Basic setup/game/reload path, not a full Advanced browser game or actual server restart.

Remaining readiness work

The initializer and setup information-order defect are now implemented and tested within the boundaries above. Remaining base-mode rules and unresolved interpretations in BASE_ADVANCED_READINESS_20260907.md and IMPLEMENTATION_STATUS.md still require resolution. Their original audit snapshots describe pre-fix setup; the coordinator has added current follow-up sections while preserving that history.

Full-game outcomes must be complemented by deliberately triggered special Karama, Truthtrance, advisor, elite casualty, captive, forecast and Guild timing scenarios. Random completion may never encounter a rare interaction or unfinished rule. Desktop/mobile private ownership, refresh/server recovery and complete Advanced browser acceptance remain separate evidence. Neither a shared initializer nor these passing setup cases authorizes opening the Advanced or expansion gate.