Counter incoming advisor matching before normal movement and shipment

Preserve residents and unused actions when one selected packet cannot match. Bind public matching receipts to private declarations and share packet-opportunity denials with legal bot filtering.

docs/ADVISOR_MATCHING.md

@@ -0,0 +1,97 @@
+# 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.