Dune/docs/ADVISOR_MATCHING.md

# Matching incoming Bene Gesserit groups

## 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 cutover still due

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. That separate parent/projection integration is pending;
this normal movement/shipment prototype does not certify it.