Dune/docs/GUILD_AMBASSADOR_IMPLEMENTATION.md

Guild Ambassador implementation checkpoint

7 September 2026. The Guild Ambassador now provides an independent free physical reserve shipment for Ecaz or its ally, including a permitted Bene Gesserit copy. It is the eighth implemented ordinary Ambassador effect. This checkpoint does not enable full Ecaz, Advanced or expansion starts or establish complete expansion compliance.

Rules and bounded behavior

GUILD_AMBASSADOR_RULES.md records the primary sources and unresolved combinations. E3 pp.8,15 establishes the reserve grant and immediate shipment before the original entrant continues. The beneficiary may select one through four physical forces, including any required or chosen elites, and a clear destination sector. An explicit zero-force choice is implemented as the reading of “up to four”; the triggered token remains committed. No available reserves or board destination completes without moving forces under the documented unavailable-effect interpretation. An implementation-blocked arrival is not silently treated as a rules-impossible destination.

The pure quote preserves typed custody and validates board locations, storm, stronghold occupancy and reciprocal Ecaz Occupy. Fremen can enter outside their ordinary reinforcement radius, but cannot invoke their ordinary storm exception. Their classic southern reserves remain on-planet. Only Ixians may ship directly into their placed Hidden Mobile Stronghold. A direct BG shipment joins its existing advisors; otherwise it uses normal fighter arrival, without an invented movement-style flip choice.

The grant costs no spice: no bank/Guild transfer, pledge spending or ordinary rate-card consumption. It leaves ordinary shipment/movement flags, Hajr, queues, Guild timing, Sapho and the original entrant's Ornithopter cohort intact. It is separate from existing Basic-only Truthtrance shipment promises.

During phase five, an eligible Guild special Karama can prevent an off-planet declaration before placement. The exact intent survives the response. Stopping it returns to the Ambassador continuation without spending the beneficiary's ordinary shipment or altering an unrelated rate benefit. No phase-one Guild stop window is opened. Successful eligible off-planet shipments accrue Heighliner income once in its own phase, without requiring a payment. A Guild beneficiary alone does not trigger it, but a separate successful BG shipment can. Fremen reserve entry does not trigger these off-planet consequences.

The original entrant remains suspended while supported Intrusion, Terror and BG accompaniment resolve. BG receives its own sector/Polar Sink choices and may decline. E1 p.10 explicitly permits BG accompaniment into an Ixian shipment's HMS; this does not authorize independent BG direct shipment there. November FAQ p.4 governs same-territory advisor stance and existing locks. A secondary arriving fighter can trigger another Ambassador: the completed Guild effect transfers its original continuation to that new opportunity, preserving the original worm rider where applicable. The shipment and token completion are not replayed.

The durable receipt validates historical actor, event, token, quantity and child provenance rather than requiring old forces, alliances or storm positions to be restored after later effects. Printed and BG-converted Karama use the same source bindings. Cancellation of an accompanying power preserves the already completed main shipment. Separate Terror can act on either main or accompanying arrivals. The final child finishes before the entrant or remaining worm ride resumes.

Controls and AI

Only the beneficiary receives ambassadorEntry.shipment. The dedicated event-keyed form shows physical count, elite minimum/maximum, destination territory/sector, zero cost and an explicit Send no forces action. Server-projected blocked reasons disable submission and are associated with the controls. There is no payment dialog or No-Field selector.

All four AI profiles choose a positive projected legal shipment when available, preserve canonical elite allocation and otherwise choose zero. They filter blocked destinations before scoring. Offer/copy preference uses only the bot's own reserve availability, not an ally's hidden resources. For a source-bound BG follow-up, only its owner receives guildAmbassadorAdvisorChoices; UI and AI use the supplied sectors and blocking reasons. The AI falls back to Polar Sink or decline. Legacy accompaniment controls retain their prior behavior.

Remaining boundaries

• No-Field substitution remains unavailable pending the user's interpretation. The combined free price, four-force cap, concealed value and mandatory allied substitution fee have no direct publisher ruling established here. Moving an existing marker with the Fremen effect does not settle this shipment question.
• Simultaneous foreign-BG Intrusion/Terror and Ambassador/Terror remain explicit arrival gates. A rejected declaration commits no forces. The supported sequential or secondary cases do not resolve those competing priorities.
• Moritani Atomics Aftermath's shipment prohibition still requires its gated effect producer/state. Homeworlds, Discovery locations and their component modifiers require their own gated modules. The physical quote is not evidence that these absent combinations have been implemented.
• Tleilaxu Ambassador, complete Occupy combat/collection/victory, exceptional Duke custody and full optional-module combinations remain unfinished. The source-version conflict about Occupy combat rounding is unchanged.

Focused validation

At this documentation checkpoint, 78 new focused rules tests and six multiplayer tests pass: 21 physical/advisor quote tests, seven historical continuation tests, eight cancellation tests, five resume-provenance tests, 17 actual engine journeys, 17 AI tests and three independent runtime review tests. The six multiplayer cases use the production room module, authentication and SQLite compare-and-swap in isolated databases. Counts refer to these new files, not the larger historical suites that ran alongside some of them.

Evidence	Scope
tests/guild-ambassador-quote.test.ts, tests/guild-ambassador-advisor-quote.test.ts	All twelve beneficiary factions, Basic/Advanced quote constraints, typed minima, board/sector/HMS, Occupy, advisor stance and private-state independence. /tmp/dune-guild-ambassador-advisor.log: 21/21.
tests/guild-ambassador-continuation.test.ts	Historical source/custody validation, JSON, casualties, changed board/alliances and exact child binding. /tmp/dune-guild-ambassador-continuation.log: 7/7.
tests/guild-ambassador-cancellation.test.ts, tests/ambassador-resume.test.ts	Eight cancellation and five continuation-provenance cases; exercised alongside historical terminal and continuation tests in /tmp/dune-guild-ambassador-cancellation.log and /tmp/dune-ambassador-resume.log.
tests/guild-ambassador-engine.test.ts	Genuine entry/trigger/choice, zero, Guild allow/stop, phase-one worms, typed forces, original Ornithopter, BG decline/cancel/accept, HMS, Terror, Heighliner and a chained Ambassador. /tmp/dune-guild-ambassador-engine.log: 17/17.
tests/guild-ambassador-bots.test.ts	All four levels, own/ally reserves, mixed and elite-only allocation, private projection, BG copy, blocked destination/zero, storm sector and Polar Sink fallback. /tmp/dune-guild-ambassador-bots-integrated.log: 39/39 including 22 unchanged historical Ambassador tests.

Named formatting/lint and UI/AI typecheck pass; /tmp/dune-guild-advisor-ui-type.log is empty with exit zero. The AI blocked-accompaniment fallback test perturbs a genuine decision's projection to isolate policy; actual competing-arrival semantics are tested separately by the engine suites.

Integrated validation and browser checkpoint

The final registered suites pass 2,691 rules/client/component tests and 239 multiplayer tests (2,930 total). Typecheck, lint and the production build pass. Logs: /tmp/dune-guild-ambassador-rules-final.log, /tmp/dune-guild-ambassador-multiplayer-final.log, and /tmp/dune-guild-ambassador-{type,lint,build}-final.log.

tests/guild-ambassador-review.test.ts reproduces damaged pending-shipment saves and verifies their rejection at read, automatic normalization and state-writing boundaries. It also exercises an actual paid Box interruption and a phase-one summoned worm interrupting BG accompaniment, followed by cancellation and the original worm queue. The review found and fixed orphaned/mismatched source declarations: a ship-stage parent now requires either its beneficiary selection or the exact saved Guild decision, including suspended controls.

tests/guild-ambassador-recovery.test.ts covers six production-room SQLite cases: racing free selections, Guild allow/stop, BG allow/cancel and privacy, chained Ambassador restart in both phases, corrupted receipt rejection with zero writes, and automatic completion under competing workers when a recovered beneficiary has no reserves. These tests do not modify the live database.

Twenty Basic games using the established balanced runner completed across all four homogeneous difficulty levels and player counts two through six. They performed 10,640 accepted actions and 482 JSON continuations, with no rejected candidates, stalled games, exceptions or invariant failures. The run took 50.611 seconds. /tmp/dune-guild-ambassador-fullgames-final.json and its .log record seed 20261021, source fingerprint 3f6fcc84fec616f40afded1e92c990c727b4a4d5b9c853bffa56c06f2f22e51c, and unchanged source files during execution. This verifies Basic regression behavior, not expansion full-game compliance or relative AI strength. A separate earlier two-player mixed-level 20-game sample is retained at /tmp/dune-guild-ambassador-duel-games.json; it is not the balanced sample.

The private browser QA room 8S3MRDEK verified actual Guild trigger, zero-spice free shipment, desktop and 390×844 mobile controls, keyboard Tab/Return submission, refresh recovery before selection and after completion, and the automatic successful-effect notice. The free shipment reduced Ecaz reserves from 13 to 9 and added four forces once while preserving spice zero and ordinary shipment/movement counters. A separate real BG accompaniment position verified projected storm-sector disabling, mobile controls, allowed accompaniment, automatic resolution without unnecessary confirmations, the detailed chronicle and refresh recovery. The final QA state is version 109, waiting for the original entrant; BG has 19 reserves and one advisor at Wind Pass 14, Ecaz has 16 reserves and its four shipped forces there. QA snapshots are under /tmp/dune-guild-{ambassador,advisor}-qa-*.json with restricted permissions.

All 2,466 previously recorded non-QA rooms retain their versions and state hashes; later regression rooms are additional records. The controlled 11:51 UTC restart backed up and preserved all 2,497 room versions/state hashes, returned HTTP 200, and restored the authenticated browser at QA version 109. The known human game remained idle at version 14. Restricted backup and verification files are under /tmp/dune-maintenance-20260907T1151. Development session 21816 is running; the next hourly restart is due 12:51 UTC if active development continues and no human is actively playing. The browser viewport was reset after testing. The runtime-readiness document remains a dated design snapshot, superseded by this implemented contract. The hourly automation stays removed.

The final component inspection also unified the Ambassador tray and entry dialog coverage text, replacing the tray’s obsolete five-effect wording with the same eight-effect description. The enlarged Guild component was also inspected on desktop and at 390×844, including keyboard Escape dismissal. This presentation-only change leaves the measured game-source fingerprint unchanged; its final typecheck, named lint and rebuilt production bundle pass.