Dune/docs/GUILD_AMBASSADOR_RUNTIME_READINESS.md

# Guild Ambassador runtime readiness

Historical design review. The implemented contract and focused validation supersede the proposals below: [GUILD_AMBASSADOR_IMPLEMENTATION.md](GUILD_AMBASSADOR_IMPLEMENTATION.md).

Read-only architecture audit, 7 September 2026. Implement this as an independent reserve-entry intent under the existing Ambassador event, followed by a bounded completed-arrival receipt. Ordinary shipment has useful typed reserve, stance and reaction operations, but its validator and commit path spend an ordinary turn opportunity. Calling those functions unchanged would consume the beneficiary's shipment and disturb the original entrant's state.

This document describes current implementation contracts and explicit source questions for the separate rules review. It does not introduce a Guild Ambassador rule interpretation, enable expansion starts or claim full combined-game coverage. Runtime line references are approximate snapshot anchors.

## Printed guide versus current implementation

`game/ambassador-reference.ts:53` describes sending at most four reserve forces to any territory outside storm without spice payment. The earlier [effects audit](ECAZ_AMBASSADOR_EFFECTS_AUDIT.md) records E3 pp.8,15: the Guild example is a shipment that resolves before the original entrant continues. `implementedAmbassadorEffects` does not yet include Guild, so it is currently gated before token commitment or unavailable as a BG copy.

The primary beneficiary is Ecaz or its mutual ally. It is distinct from the original qualifying entrant, and its own arrival is excluded from triggering another Ecaz Ambassador. This bounds the main continuation just as in the Fremen effect. Shipment can additionally grant a separate Bene Gesserit force arrival. Its normal advisor stance excludes an Ambassador trigger, but it can encounter Terror; determine stance from the actual destination state rather than hardcoding every BG follow-up as an advisor. Effects or an intervening alliance can change the destination between primary arrival and follow-up.

Ordinary off-planet shipment classification, Fremen reserve exceptions, independent No-Field substitution and Guild prevention outside phase5 require the separate source review. Preserve those questions as such. They are not reasons to copy the existing ordinary-turn checks into the new effect or to invent payment for a free shipment.

## Reusable operations and exact ordinary side effects

| Existing function/type                          | Reusable behavior                                                                                                                                       | Must change or remain separate                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PendingShipment` at `engine.ts:675`            | Player, turn, destination sector, physical amount, elite allocation and advisor stance; optional own/allied No-Field identities.                        | Existing fields have no Ambassador event/source, independent opportunity identity or return contract. A dedicated intent or discriminated source is necessary; a free ordinary price is not sufficient.                                                                                                                                                             |
| `eliteChoice`, `place`                          | Preserve selected ordinary/elite reserve custody. Physical amount is inclusive of elites; deduct each typed pool once and add it once to destination.   | Validate against the explicit at-most-four limit and current reserve composition. Do not move from board groups, Tanks, reserves belonging to another player, or a Guild return/cross-shipment source.                                                                                                                                                              |
| `allowedEntry` at `5704` and `arrivalAsAdvisor` | Sector existence, destination storm, ordinary stronghold capacity and BG stance.                                                                        | Do not use the Advanced Fremen storm-shipment exception: the guide expressly excludes storm. Ecaz Occupy requires the same source-aware allied-side composition used by the new Fremen relocation helper. HMS direct-shipment permission is separate from its movement pointing-territory rule.                                                                     |
| `validatePhysicalShipment` at `11743`           | Current reserves/elites, arrival stance and destination checks, then price/contributor consistency.                                                     | It requires phase5, active beneficiary, unused ordinary shipment, normal price, funds/aid and normal Fremen Great Flat range. All of those are assumptions of this producer. New source validation must not require an ordinary turn, compute a fictitious rate or spend a pledge. Whether the source's destination grant changes Fremen range is a rules question. |
| `offerShipment` at `11836`                      | Guild prevention is offered before payment/arrival and independently of Guild's private hand. The exact pending destination/amount is exposed to Guild. | It immediately runs the ordinary validator. Route a new source to an independent validator and commit. A phase1 Ambassador parent cannot pass the existing special-Karama declaration's hardcoded phase5 fence.                                                                                                                                                     |
| `commitShipment` at `11866`                     | Typed reserve deduction and placement, native BG stance, tech trigger, then arrival-related controls.                                                   | It calls `finishShipmentPromises`, sets `p.shipped = true`, pays with ally, computes Guild income, clears `karamaShipping`, and opens possibly competing arrival controls. Do not invoke unchanged.                                                                                                                                                                 |
| `guildShip` action at `15500`                   | Some typed transport and destination helpers.                                                                                                           | It is board cross-/return transport or allied Fremen reserve transport, requires a Guild relationship and ordinary unused turn, and explicitly rejects concealed markers. It is not an Ambassador reserve-entry adapter.                                                                                                                                            |
| `finishAmbassador`                              | Finishes token cycle once and resumes the original entry's `none` or `wormRide` continuation.                                                           | Invoke only after prevention or all resulting arrival children finish, not immediately after reserve deduction.                                                                                                                                                                                                                                                     |

The new commit should preserve `active`, `movementRemaining`, Guild timing flags, Sapho ordering, both participants' ordinary `shipped`/`moved`, Hajr/Ornithopter state, `karamaShipping`, aid escrow and any original movement-card cohort. It must not emit the original entrant's shipment or movement a second time. The entrant resumes by making its remaining normal choices against the now-changed board.

## Proposed independent intent and completion contract

Names below are software design proposals, not printed terminology.

1. Keep the actual owner offer and BG-copy selection. After the token is committed, use a beneficiary-owned shipment-selection stage with the same parent event, token/copy provenance and original entrant/resume. The separate source review must settle zero-selection/unavailable-reserve behavior; do not invent an arbitrary buyer-style decline for a mandatory effect.
2. Quote a selection without mutation: `source: 'ambassador'`, `ambassadorEvent`, beneficiary, destination, amount, elite, stance, and explicit physical/marker kind. Check playing parent phase/turn and exact stage, current selection entitlement, safe typed reserve arithmetic, destination and applicable source restrictions. No phase5-active/unused-ordinary requirement. No price, payer or ally-split field is needed for a physical zero-cost shipment; if sharing a structural type, enforce cost and ally contribution exactly zero.
3. If a source-supported Guild-prevention window applies, save the exact intent before placement. A Guild allow must revalidate it and commit once. Guild prevention must clear only that independent intent and resume/finish its Ambassador opportunity according to the reviewed rule. It must not mark the beneficiary ordinarily shipped, rotate a No-Field event, touch forces, return a rate card, clear an unrelated rate benefit or replay the original entrant.
4. Commit physical reserve deduction/placement, any source-authorized technology accrual and one new shipment log exactly once. Save a completed arrival receipt including parent event, shipper, destination, committed amount/elite/marker identity, and the next bounded child. Postcommit validation treats this receipt as historical: later casualties, spent reserves, changed alliances or marker reveal cannot require replaying or revalidating the old shipment.
5. Resolve the chosen source-supported arrival ordering, then `finishAmbassador` once. Extend the new Fremen arrival continuation by a discriminated effect/source where operations are genuinely common; do not call its `currentFremenAmbassador` or forge `effect:'fremen'`. A separate Guild intent plus shared typed arrival return is sufficient; no global durable-action system is needed.

## Guild prevention and cancellation adapters

`validateGuildShipmentDecision` binds Guild owner, unspent special power, exact shipper/destination/count and rejects Fremen targets before calling ordinary shipment validation. `prepareSpecialKaramaIntent` for Guild currently additionally requires phase5 and copies `pendingShipment` into its prepared intent. The completed Guild-special branch discards the canonical Karama, marks its use, **sets the target's ordinary shipped flag**, potentially refunds the target's previously spent rate card, clears `karamaShipping`, and clears the pending shipment/decision.

A source branch is required at all three boundaries: declaration availability, exact saved-decision validation, and final denied-shipment commit. Source-scoped preflight must prove the return to this Ambassador before the Karama is consumed. The current cancellation message promises normal movement remains available; do not reuse it if the only stopped item was this independent bonus entry.

Do not transfer the unresolved ordinary rate-cancellation/refund policy into this free entry. There is no Ambassador shipment payment to refund. Existing source-bound BG conversion, Box, gift and special-Karama intent validation must preserve the new parent/intent event if permitted interruptions are retained. No one should infer Guild's card custody from whether the prevention offer exists.

## Off-planet arrival children

The existing `commitShipment` establishes the following operations, but its simultaneous-control assignment is not a complete ordering contract:

- After placement, `intrusion` can offer an existing BG fighting group a stance change.
- A non-Fremen shipper other than BG can create `followup:{shipment,destination}` when BG has reserves; after intrusion, `finishAdvisorReaction` opens the accompaniment decision.
- The ordinary `advisor` decision chooses Polar Sink or an Advanced accompanying destination sector, then opens a cancellable `advisor` response.
- Allowed advisor response consumes one BG reserve, places it, potentially accrues Heighliners, applies stance/lock, and invokes `openTerritoryEntry`. Cancellation currently just returns. Ordinary decline also just logs.
- Primary and BG arrivals can meet Moritani Terror. Current ordinary code invokes `openTerritoryEntry` while other responses/decisions may already exist; guards reject unsupported combinations. It cannot safely become the new bonus-entry ordering by omitting those guards.

The Guild effect needs a bounded return event on both `advisor` decision and response, not only `advisorFlip`/Intrusion. Decline, allow, printed cancellation and BG-counter cancellation must each advance the correct child once. After a successful BG placement, save that second entry separately from the beneficiary's historical primary receipt; Terror must bind to the actual BG entrant/amount/sector. Do not give BG a second follow-up in response to its own follow-up shipment.

`terminal-cancellation.ts` currently treats denied `advisor` as a phase5 terminal power; `karama-context.ts` currently returns no additional source for it. A Guild-Ambassador-owned advisor response in phase1, or one with an unfinished parent afterward, requires an explicit source-bound validator/successor. The new Fremen-specific advisor cancellation checker only accepts Fremen relocation provenance and cannot be reused by changing the event string alone.

Likewise extend Terror's cause/resume validator, Moritani alliance cancellation, Sabotage/Robbery discard-frame parent proof and automatic continuation to the actual new source. Existing Terror frames already retain the entire child entry and resume its suffix; preserve that model without replaying random victims, card disposal or force placement. The original parent can originate from a worm; all final paths must return through the parent once so `nextWormRide`, summoned-Nexus ordering and five-token replenishment remain intact.

Where two reactions compete, retain a named source-ordering boundary until separately resolved. Source-independent validators should still cover clean, single-child and already-supported sequential paths; a missing simultaneous-order ruling does not require withholding all reserve-entry implementation.

## Concealed No-Field versus physical reserves

The current own Richese shipment substitutes one concealed marker for the ordinary shipment; it deducts no physical reserves until a later reveal, charges the one-marker normal rate and assigns a fresh event on deployment. Allied No-Field instead uses a separate owner/recipient offer and payment allocation, reveals an existing own marker where required, and places physical forces immediately. These are distinct contracts.

`noFieldShipBlock` binds an unused active phase5 turn and forbids existing deployment. `noFieldAllyOfferBlock`, `alliedNoFieldQuote` and `quoteNoFieldCancellation` likewise bind the original ordinary opportunity and price/contributor assumptions. The cancellation helper records a turn-wide own or recipient block appropriate to that existing single normal shipment. Blind reuse would block or consume a different opportunity, or fail all independent declarations.

The rules review must classify whether the free at-most-four physical-reserve grant permits either substitution. If authorized, use the pure physical inventory/deployment helpers and a separate Ambassador event-scoped denial record. Specify whether the four-force cap measures physical forces or a substituted marker and whether any allied fee is overridden; do not infer eligibility from the marker's hidden value or manufacture a zero-cost allied payer choice. If not yet classified, expose physical reserve shipment while naming the marker-combination boundary. The existing marker movement support in the Fremen effect does not settle a new shipment substitution.

Preserve sealed custody in public views and precommit offers. A marker counts as one public presence, and a denied declaration must not reveal denomination, reserve materialization, replacement token identity or prior private custody. A new stale-event field must not collide with the Ambassador's own command event.

## Payments and other resources

A physical Guild Ambassador shipment has zero payment under the current guide. Consequently there is no spice for Guild shipment income, and no payment to a bank or ally. `guildShipmentIncome` has contributor-specific routing for positive ordinary fees; zero fee requires no response. It is a shipment, not a Treachery Card acquisition, so existing Emperor purchase-income, Harkonnen bonus and Ixian purchased-card replacement handlers are irrelevant. Never create a fake auction/sale or reuse the Richese Ambassador receipt for this effect.

`techIncome('heighliners', actor)` is a distinct accrued technology event, independent of price. The helper is phase5-only, excludes Guild as actor and triggers at most once per turn; the ordinary shipment caller additionally skips Fremen. Reuse that precise mechanism only after the source review classifies the new shipment and Fremen case. In phase1 the current helper accrues nothing. Do not add immediate spice to the token holder or trigger it merely because an intent was declared/stopped. BG's successful separate shipment has its own existing call but shares the token's once-per-turn stamp.

Shipment Truthtrance promises currently authorize only Basic/no-expansion ordinary physical reserve shipment and active-turn contexts. An expansion-only bonus shipment should not call `finishShipmentPromises` simply because it removes reserves. Preserve those mode gates and future source classification rather than marking an unrelated pledge fulfilled. Ordinary movement allowances, leaders, revival quotas and purchase resources have no role in the free physical-entry prefix.

## Focused implementation evidence

Use conserved development positions with actual entrant shipment/movement → owner trigger/BG copy, not synthetic paid sales or fake normal-shipment state. Cover:

- Ecaz self and each eligible allied beneficiary; typed ordinary/elite zero/one/four/max-reserve selections; storm/destination/mobile/capacity/Occupy boundaries; independent ordinary shipment still available afterward.
- Original entrant's first/last Ornithopter group, existing rate-card state, Guild timing/Sapho queue, paid arrival and remaining movement unchanged.
- Source-supported Guild allow/stop, exact pending replay rejection and hidden-hand-independent offers; initial and final-cost corruption checks.
- BG intrusion, accompaniment versus Polar Sink, cancel/decline/no-reserves, child Terror, and phase1 worm parent; source-unresolved simultaneous combinations remain clearly gated.
- Optional authorized No-Field branch with sealed identity, source-scoped cancellation, fresh event exactly once and no unintended physical reserve placement.
- JSON/fresh-auth private views, duplicate intents/final choices and racing SQL workers, one reserve change/tech stamp/token-cycle completion, and no random/discard/arrival replay. Empty legal options must finish or follow the explicitly selected unavailable-effect interpretation, and the room worker must schedule that authoritative normalization.

No production or tests were changed or run for this audit. Reviewed snapshots: `engine.ts` `bb68b622eb3a9e77dcc5bf8f2bcf0764c668d40dd410669e40e82b3dd99c2c13`; No-Field cancellation `7ea1288ef0e0f4fbf61a26731b5420dc8bfc085c08c32c41ee7672a4568b5de8`; Ambassador guide `10d4361945327361cc1a2b61814e9e77701b037a9fcf79ce0d60ab68313c2f08`; technology helper `2f5431e183ed8d1f2a0e73ae64ffecf4ce08a9c03cc365bc383b029c2a8f4514`. These identify the audit, not a future release.