Separate Spiritual Advisor shipment matching and alone conversion

Apply the Advanced retained-fighter target cutover through shared quotes and controls. Preserve committed foreign shipments while handling free-packet shipping, Polar matching, actual placement and original arrival once.

docs/SPIRITUAL_ADVISORS.md

@@ -0,0 +1,113 @@
+# Spiritual Advisor shipment, matching and conversion
+
+## Advanced source cutover — 24 October 2026
+
+**Prototyped / Partial.** Supplied revised Advanced
+physical28/printed26 ships an advisor, permits accompanying the original
+shipment or using Polar Sink, and redirects retained non-Polar fighters to
+Polar Sink or decline. Original Intrusion may first change those residents to
+advisors. The same page's mandatory alone conversion has no Polar Sink exception;
+physical17's group-flip counter remains separate from its shipping counter.
+Do not treat the free packet as an ordinary paid fighter shipment.
+
+Normal and Guild Ambassador declarations, the Guild quote, projected choices,
+human controls and minimal bots now share the target restriction. Homeworld
+reserve/population limits remain resource quotes, independently of target
+legality. Basic is unchanged. Already-recorded declarations without the new
+Spiritual source retain their original one-shot settlement protocol; fresh
+Advanced declarations use an explicit seven-field source and private frame.
+This is a source cutover, not permission to reset or recreate saved games.
+
+## Original grant and distinct responses
+
+The public source contains event, owner, turn, phase, territory, sector and
+amount. A private frame retains the original owned chooser, committed foreign
+parent, selected order and exact signatures. Current and parked responses own
+that same source. No private parent, No-Field identity, resource proof or
+signature is copied into response/Karama source selection.
+
+1. **Shipping.** Choose a legal target and ordinary reserve amount, then offer
+   the separate Spiritual Advisor shipping counter. Prevention ends this free
+   packet without a reserve withdrawal. The other faction's original physical
+   shipment and payment are already committed.
+2. **Matching.** If the named Polar fallback has BG fighters, the incoming
+   advisor packet must match them. Under the 14 October recommended policy,
+   provisionally allow that Polar fallback even if it was the original shipment
+   destination, then offer matching before placement. Residents never change.
+   Prevention restores the original owned chooser. That same packet/destination
+   is unavailable for this original foreign-shipment opportunity; changing
+   sector or accompanying/fallback labels cannot retry it. A different legal
+   amount or decline remains available. Neither page expressly resolves this
+   Polar corner or cancellation remedy; do not call it a publisher exception.
+3. **Placement and alone conversion.** Withdraw actual native reserves, place
+   the free packet, grant original Tech income and log placement once. Advanced
+   arrivals start advisor-side unless matching into resident fighters. If alone,
+   capture the whole actual group before settlement can silently make it a
+   fighter, then offer the independent conversion counter. Prevention retains
+   the actual arrival, withdrawal/income and existing provisional continuously-
+   alone hold. Joining an existing held advisor group preserves that occurrence
+   rather than rearming conversion.
+
+Revalidate target/resource availability before placement, including before
+offering matching. A no-longer-available declaration restores the original
+chooser without moving a force. Never rerun reserve or population availability
+after withdrawal; validate the committed deposit and original parent instead.
+
+## Original continuation
+
+The queued ordinary foreign arrival stays paused while the frame owns its
+choice or responses. Clear the frame and immediately open the actual BG arrival
+before draining that queue. Guild Ambassador keeps its original `advisor` stage
+until all counters finish. Its extracted suffix records `advisorArrival` and
+`finish`, then retains the existing child/outer-continuation handoff. An eligible
+BG child retires the Guild parent first; original worm/Homeworld tags and
+`guildAdvisorOrigin` follow the original suffix. No transfer, income, token use
+or original foreign entry is replayed.
+
+The legacy path is explicitly for an already-declared response format, not an
+option exposed to current callers. Controlled legacy tests preserve those
+callback checks without claiming fresh permission or a genuine saved-game
+capture. Complete recovery/custody/privacy assurance stays in the final phase.
+
+## Prototype evidence and limits
+
+[Native fixture](../tests/fixture-spiritual-advisor-flow.ts) earns ordinary
+public Advanced BG/Atreides/Emperor sources and bare E3 BG/Ecaz/Atreides Guild
+Ambassador sources with original base33 and Atreides' original Karama. Original
+BG setup in empty Tuek's or Polar Sink becomes fighters. Actual foreign shipping
+then earns declined Intrusion, accepted Intrusion/advisors, or Polar fighters.
+Guild sources earn their original packet, paid token/entrant and actual free
+child shipment. The earlier ordinary accompaniment is explicitly declined.
+No played force, hand, wallet, phase, stance or new response is installed.
+
+[Connected cases](../tests/spiritual-advisor-engine.test.ts) cover fresh target
+rejection, separate shipping prevention, both Polar matching/alone outcomes,
+accepted Intrusion, exact parent binding and a second genuine foreign shipment
+joining a held group. Explicit controlled late-stance cases test revalidation.
+The final frozen batch passes **22 files390/390**, types/lint/build, fifteen
+native declaration/response/GameTable SSR journeys and two explicitly controlled
+late-stance cases. Ordinary sources use35 actions for retained/Polar fighters or
+37 for accepted Intrusion; Guild sources use45 or48 respectively. The fifteen
+journeys cover target rejection/decline, shipping prevention, both matching and
+alone-conversion outcomes, same-type Intrusion and the second genuine foreign
+grant joining a held group. Twenty-four existing-profile paths across four
+difficulties, two parents and three stances accept72 actions through choices,
+shipping and later responses or restored decline. This is minimal legal
+participation, without strategic refinement.
+
+Feedback updates four older assertions to follow the independent matching
+response and preferred public choices. The focused four repairs pass before
+the final union. The first native runtime passed without application fixes.
+Private source proof lives in
+`/home/quintine/.local/share/dune/checkpoints/20261024-spiritual-advisor-flow/`:
+`frozen-integrated-2/report.json` binds tree
+`403d1a46ccdc0fbe353546a870d858fdb80340cb2c20533e87667dd414df6fe0`,
+2757 files on base `438a5692a644305360199da920760e25fee8d15f`.
+Only checkpoint prose/reference overlays follow the frozen proof; their links,
+evidence paths and source invariance are separately reviewed.
+
+Full Homeworld/Tech/Nexus/No-Field combinations, other matching producers,
+all valid modes and final browser/deployed assurance remain open. Standard
+controls are reused; SSR is not callback/hydration or desktop/mobile browser
+acceptance. No saved-room/D1/server/reset/restart/deployment operation was needed.
+No strategic AI work is authorized by this prototype.