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.

Basic native and allied No-Field — 24 October 2026

Prototyped / Partial. Bare Basic Richese/Ecaz tables without optional modules now use No-Field for the whole Guild Ambassador grant. The source-selected provisional composition admits native concealed0/3/5 as one free marker without reserve withdrawal. Allied immediate materialization uses min(value, recipient reserves) within four, never an invented truncation of five available pieces. The specialized one/two-spice allied transport payment goes to Guild, or Bank when absent, despite the general free grant; this precedence remains provisional.

The beneficiary chooses the requested destination. Richese privately chooses its physical token and supplier/recipient/split payment; the beneficiary accepts or declines the exact offer before any transfer. A two-spice fee may split1/1. Either refusal returns the original physical shipment choice. Native Richese explicitly reveals an old marker first; accepted allied use reveals the old supplier marker once, then immediately materializes the new token from the recipient's own reserves. Normal token availability/history remains shared. Zero reserve counters do not erase a native concealed-marker opportunity.

New controls retain their event, supplier/beneficiary actor, exact server option, provisional guidance and busy/blocked reasons. Printed Karama prevents only this grant's marker substitution and retains the physical-force alternative. Ordinary shipment/movement, normal No-Field block flags and unrelated tariff benefits remain unchanged. Successful payment opens its exact Guild-income response before existing arrival continuation; canceling income keeps the paid shipment. New optional declaration/request fields and a committed marker receipt witness do not retrofit old physical receipts or change their zero-price validation.

Pure quotes live in game/guild-ambassador-no-field.ts; root integration covers authoritative declaration/consent, payment, token placement/revelation and the existing typed arrival parent. The ordinary physical quote remains separate. Basic minimal bots answer supplier/consent requests using their own projected options and can complete a native marker grant when no physical reserve remains. No strategy or strength calibration was added.

The final 13-file129/129 related union, npm run check:quick and production build pass. Fifteen gameplay/control/GameTable SSR journeys exercise native 0/3/5, actual old-marker reveal, zero reserves, allied consent/refusal, cap5→4, zero materialization, Guild/Bank payment, printed prevention, physical fallback and the original entrant's actual move/end. Eight existing-profile continuations accept12 proposals from native-empty or allied-request positions. Pure/controller regressions keep fees, token events, typed counts and legacy behavior covered.

Genuine three/four-seat Basic setup selects only original undealt cards/Spice and nine original packet rolls. Ecaz actually pays for two placements, forms an accepted alliance with Richese through its reusable token and declines its optional Basic Duke loan. Ecaz/Richese have already shipped normally; Harkonnen then pays for the real Guild-marker entry. Runtime sources retain53/71/74 actual actions. Native-empty and allied5/reserves4 cases separately stage prior conserved deployments into existing groups, not played movement. Source cases with actual held Karama keep the prevention response; ordinary hands autoallow. Feedback repaired a lost decision after native prior reveal, those response assumptions and three fixture type errors. Bounded source/continuation review found no remaining blocking issue.

Private proof: /home/quintine/.local/share/dune/checkpoints/20261024-guild-ambassador-no-field/, frozen-integrated/report.json, runtime-smoke.json, HTML/logs and verified-files.json. Before final prose: base4b2f4f3fa3853aa1acd46631d186c746a06842f8, source treed30c6163b8e7e07e73159f27f8dfb2e49726d88ec777b4ce377eb05bb48fd8a3, 2680 tracked/nonignored files unchanged throughout verification. Four final prose/reference overlays preserve code/test hashes; delivery checks links, evidence, reference syntax/keys, explicit staging and remote push.

This supersedes the earlier No-Field implementation gate below only for this Basic profile. Native Advanced, optional modules and wider originating-card or competing arrival combinations retain their separate boundaries. SSR uses framework aliases/CSS stubs and is not browser/visual/deployed acceptance. Complete rules, comprehensive saved-game/privacy/custody assurance and full AI remain unfinished. No saved room, D1, reset, restart or deployment operation.

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. This dated physical-only baseline is extended by the Basic No-Field controls above.

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: the24 October Basic prototype above supersedes the original implementation gate. Native Advanced and optional combined profiles remain gated; the combined cap and fee policy is provisional, without a direct publisher ruling.
• 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.