Dune/docs/ADVISOR_MATCHING.md

# Matching incoming Bene Gesserit groups

## Fremen Ambassador relocation — 24 October 2026

**Prototyped / Partial.** The supplied revised
Advanced physical28 matching clause covers incoming shipping/moving groups;
physical17 permits preventing the group's flip. Fremen Ambassador relocation
can move a genuine BG ally's opposite-type group into its residents. This is a
separate matching operation before the physical transfer, not the later alone
conversion. Basic and same-type/empty arrivals retain their original behavior.

Native grant, token, phase, mutual ally, route, fresh-advisor locks and occupancy
remain the original producer's authority. After their quote succeeds, offer
matching before CHOAM's movement reaction, Sandmaster collection or any transfer.
The public ten-field source binds event, original Ambassador parent, owner,
turn/phase, origin, destination/sector, target stance and selected physical group.
The exact original order and parent signature stay private. An inactive ordinary
player may own this independent allied grant; do not use their normal moved
index as its identity. Existing normal matching sources retain their shape.

Under the existing provisional prevention policy, restore the original owned
move chooser while retaining the already-consumed trigger and all ordinary
allowances. Deny that same packet/destination/stance for this Ambassador event;
a sector, response UUID or optional fighter flag cannot retry it. Another
packet or destination remains available. Do not invent a trigger refund, a new
decline action or a turn-wide ban. Minimal bots and human drafts use the shared
quote to omit blocked packets. Allowance consumes the matching parent before
one original CHOAM/transfer/arrival suffix; original post-transfer mandatory
conversions retain their own timing. Already-recorded old continuations are
not reopened or replayed.

[Native fixture](../tests/fixture-advisor-ambassador-matching.ts) earns the
public Advanced BG/Ecaz/Atreides base33 setup, original Arrakeen advisor, paid
two-force Tuek's fighter group, real first-Revival Fremen placement, actual
turn-two Shai-Hulud/Nexus alliance and a paid third-party entrant. Ecaz selects
its genuinely allied BG beneficiary. No played force, hand, alliance, phase or
matching response is installed. Both direction payloads and later replacement
choices remain caller-owned. [Connected cases](../tests/advisor-ambassador-matching-engine.test.ts)
cover allowance/prevention, unchanged pending physical state, scoped retry and
different-packet/empty replacement, exact parent binding and minimal profiles.
The frozen batch passes **17 files358/358**, types/lint/build, six native
declaration/response/replacement/GameTable SSR journeys and eight existing-profile
paths with sixteen accepted response/replacement actions. Each source uses81
actual public actions. Both matching directions retain forces, stances, money
and allowances while pending. Allowance moves once without replaying the trigger;
prevention preserves that grant, rejects the original packet and admits either
the actual two-force packet or empty Polar Sink replacement. The no-matching
route retains the original Karama. Four existing profiles respond and choose a
legal replacement after prevention, without strategic refinement.

The first native allowance passes. Feedback only repairs an empty-source
zero/absence test assertion; the focused repair and final union pass. The native
runtime required no application source repair. Private proof and original-source
HTML live in
`/home/quintine/.local/share/dune/checkpoints/20261024-advisor-ambassador-matching/`.
`frozen-integrated-2/report.json` binds tree
`c2f21f81711c05ce6eb466d152fc65de53bb816dbcf04215e92fa3028e513107`,
2761 files on base `767bace7747ccf3cfb62600dc31cd47b2d46117b`.
Only checkpoint prose/reference overlays follow that proof, with separate
link/evidence/source-invariance review. SSR is not callback/hydration or browser
acceptance. Guild/Junction transport, two-origin gathering, wider modules and
final mode/browser/deployed acceptance remain open. No saved-room/D1/server/
reset/restart/deployment operation.

## Normal movement and reserve shipment — 24 October 2026

**Prototyped / Partial.** The supplied revised
Advanced rulebook physical28/printed26, E, explicitly marks its matching-type
shipping/movement bullet with the Karama icon. Physical17/printed15 identifies
the canceled operation as flipping one group to or from advisors. The same
physical28 section requires a single BG type throughout each territory. The
selected incoming packet matches the residents; this grants no permission to
flip the resident group or leave mixed types after arrival.

An opposite-type ground group now receives a counter before physical movement.
The packet may be a selected subset across sectors of its one origin. Existing
same-type movement has no flip and no extra matching response. The source gives
no fixed ordinary reserve side. Under the 14 October recommended policy,
provisionally retain the existing normal-fighter shipment default: ordinary
reserves joining resident advisors need matching, while reserves joining
fighters are ordinary placement. Basic is unchanged.

Neither source specifies the remedy for preventing this mandatory matching.
The selected provisional composition stops the one declaration before transfer,
shipment payment or action use. Residents and the incoming packet keep their
original location/type. Permit a legal replacement; do not invent a consumed
shipment/movement or a turn-wide ban. Prevent the same packet from matching in
that destination territory in the same owned opportunity. A different sector
in that destination is not a new packet. A different packet/destination or
later earned movement/turn is independent. Do not reuse the continuously-alone
hold from [already committed conversions](ADVISOR_AUTOMATIC_FLIPS.md).

The public ten-field source selects a fresh event, kind, owner, turn, native
movement index, origin, destination, sector, resident stance and selected
physical group. The original order and its exact signature remain in a private
parent. The shared pure quote owns current held groups, resident matching and
scoped denial; existing native code retains route, fresh-advisor locks,
occupancy, funding, card preparation and actual physical commitment. Consume
the private parent before resuming the original CHOAM movement or normal
shipment suffix once. Existing declaration card uses stay in their original
state; no new refund is invented.

Humans retain the standard Karama/Allow controls, with a persistent explanation
that this arrival has not happened. The personalized bot adapter uses the same
pure quote to omit prevented packets, keeping only minimal legal participation.
No strategic refinement or difficulty calibration is added.

[Native fixture](../tests/fixture-advisor-matching-move.ts) earns public Advanced
BG/Atreides/Emperor setup with original base33 and Atreides' original Karama.
BG's original advisor shares Arrakeen with ten Atreides. Actual first phases
and declined preparation precede a real one-force shipment into empty Basin9
for2, earning a separate fighter. Both directions between those original groups
are actual movement declarations. The recorded pre-shipment prefix also owns
a normal one-force reserve shipment into the Arrakeen advisors for1. No played
force, phase, wallet, hand, stance or counter is installed.

[Connected cases](../tests/advisor-matching-engine.test.ts) cover both outcomes,
unchanged precommit state, same-sector retry restraint, legal replacements,
already-matching movement and original-parent mismatch. Frozen **19
files244/244**, types/lint/build and seven native declaration/response/GameTable
SSR journeys pass, alongside twelve existing-profile responses and twelve
accepted legal replacements after prevention. Ground sources take34 actual
actions; the original pre-shipment prefix takes33. Both ground directions and
normal reserves preserve original residents and held packets while waiting.
Allowance moves the selected counter once; normal shipment pays1 and spends
its slot once. Prevention preserves forces, payment and the unused action,
rejects the same packet/destination and permits the earned same-type sector
reposition or an empty-territory shipment. Same-type movement creates no
matching response and retains the original Karama.

The focused first native allowance and final frozen batch pass. Standard
controls render; this is not a new callback/browser/mobile/deployed certificate.
Private proof and original-source HTML:
`/home/quintine/.local/share/dune/checkpoints/20261024-advisor-matching-groups/`.
`frozen-integrated/report.json` binds tree
`f1dc33ab54b8f74e98c7c6e7950fddf9dfd2a16cf0e4648cb2c0617cda23a061`,
2752 files on base `abf0305ddfe6883f49b9f34c1d4e879c47dcf4f2`.
Checkpoint prose/reference overlays are separately reviewed and hashed after
proof. Existing-mode completeness, special relocation, Guild/Homeworld,
Planetologist gathering and Spiritual Advisor matching remain open. No saved-
room/D1, reset, restart or deployment operation was performed.

## Spiritual Advisor source follow-up

Complete physical28 review also requires Polar Sink or decline when the
original shipment destination retains BG fighters, unless Intrusion changes
them first. Existing fighter-child ordering is provisional, not a specific
user override of that destination restriction. Preserve Basic. Target
availability must be shared by ordinary declarations, settlement, Guild
Ambassador quotes, projected controls and bots; keep Homeworld resource quotes
independent of destination legality.

The source does not expressly resolve the original destination itself being
Polar Sink with resident fighters. The recommended provisional composition
keeps the named Polar fallback and lets the incoming advisor packet match those
fighters under its own precommit matching counter, after the distinct Spiritual
Advisor shipping counter. The other faction's shipment is already committed
and cannot be undone. The separate parent, target projection and committed
alone-conversion follow-up is now tracked in [Spiritual Advisors](SPIRITUAL_ADVISORS.md);
the normal movement/shipment evidence above does not certify that follow-up.