Connect occupied Homeworld economics and Bidding

docs/HOMEWORLD_OCCUPATION_RULES.md

@@ -2,7 +2,113 @@
 
 Runtime follow-up, 10 September 2026: [Tupile intelligence and qualification history](HOMEWORLD_TUPILE_INTELLIGENCE_RUNTIME.md#occupation-observation-boundaries) implement confirmed observations while retaining the unresolved entitlement and expiry questions below. The source audit remains historical evidence.
 
+## Occupied economics, Bidding and Advanced source cutover — 5 October 2026
+
+The supplied `UNOFFICIAL_Revised_Dune_Rulebook_v.2.3_web.pdf`, physical
+**page22**, is authorized for Advanced. Its occupation clause replaces the
+publisher boundary qualification with **sole foreign presence**, then retains
+that occupier’s advantages **until none of its forces remain**. This is the
+supplied revision’s rule, not a newly located GF9 erratum or a Basic ruling.
+An intervening foreign army, a later turn or native high population does not
+expire that retained Advanced source. Departure clears it; a later sole arrival
+creates a new epoch. Original ordered semantic snapshots prove these transitions;
+turn-boundary foreign presence alongside natives cannot invent Advanced
+qualification. Unobserved physical writes and missing history cannot mint an
+entitlement. Basic retains the historical pending guards below.
+
+The same fresh `homeworld-occupation` entry connects these original producers:
+
+| Printed source | Original consumer and ownership |
+| --- | --- |
+| Kaitain | Eligible paid Treachery receipt: native rounded-up half, occupied rounded-down half; buyer payment occurs once. |
+| Junction | Eligible other-player shipping receipt after original Guild-funded exclusions and routing; the existing two-odd-contributor guard remains. |
+| Richese income | Rounded-down half of actual seller net received, not the gross sale or contribution routed to Emperor. |
+| Southern Hemisphere | One completed actual native Collection aggregate, including settled shared and occupied-bank credits; round once and redistribute the already credited amount. |
+| Caladan | Native and occupier inspect the original admitted lot, never the occupier’s ally. Canceling native inspection hides its face from native while the separately admitted printed share survives. |
+| Ix | One controller chooses from the actual original pool; native setup and Technology remain native, without duplicate native pool knowledge. |
+| Richese cache choice | Original seller chooses auction method/direction first; occupier chooses only the physical cache card. Seller, lot, invoice and unbid disposition stay native. |
+| Giedi Prime | One original Harkonnen purchase bonus goes to occupier or reciprocal ally with actual receiver capacity and drawable stock, even if the buyer’s purchase filled its own hand. |
+
+Percentage income has a separate persisted source ledger, frozen eligible
+payment/Collection proof and exact suspended continuation. Keep-all or immediate
+ally allocation commits actual credits with its settled receipt, not a second
+payer debit or static Bank icon grant. Ordinary native income cancellation leaves
+its native portion in the Bank; the printed occupied portion remains separate.
+This cancellation composition uses the printed Homeworld immunity and original
+ordinary cancellation rules, not a dedicated retrieved worked FAQ.
+Richese’s existing source-blocked canceled-auction count remains guarded:
+occupied card selection is not authority to invent a sale after cancellation.
+
+Actual Collection percentage credits feed the original once-per-phase Giedi
+spice hook. Private producer proofs and suspended invoices stay server-private.
+Original receipt-free occupation captures may admit a new source lazily; no past
+percentage is back-awarded. Public starts, played-game conversion, other modules,
+occupied Tupile capacity/cleanup and exceptional Duke custody remain separate.
+See [percentage receipts](../game/homeworld-occupied-percentage.ts),
+[Bidding authority](../game/homeworld-occupied-bidding.ts) and
+[original consumer programs](../tests/homeworld-occupied-producers-engine.test.ts).
+
+### Original runtime and human evidence
+
+Final **247 affected cases in24 files**, types/lint and build pass. Actual
+programs retain original physical cards, paid invoices, typed forces, private
+lots, native terms and JSON continuations; all four policies take legal source
+choices. Controlled capacity/counter positions are labelled and conserved,
+including original Karama already dealt during random setup.
+
+Two real consumer defects were reproduced and repaired. Invalid bonus recipients
+now use the ordinary `RuleError` adapter; an actual authenticated request returns
+409 without changing the room version. Guild income could overwrite a concurrent
+BG accompaniment choice. The signed source suffix now retains it through the
+percentage choice and JSON; the original-snapshot smoke and native regression
+complete the subsequent actual advisor placement, not merely a copied decision.
+
+The pre-advisor-repair **50 genuine games** ran on unchanged tree
+`09cfdd1957d9ae4c807bce3c7c43edd66fe72b5c239c29cbadf3acca4253de9a`:
+**44 complete**,18,977 accepted/19,149 attempts/491 JSON continuations.
+All50 total22,383 accepted/22,580 attempts/580 JSON continuations.
+Six captures retain the four Basic occupation and two low-Tupile CHOAM guards;
+this is not a zero-rejection or complete-mode certificate.
+Five original Advanced captures finish **3,135 more accepted/3,136 attempts/
+83 JSON continuations** at original scenario seeds20263433/453/455/465/475.
+Resume restarts those seeds, not their lost original random streams.
+After the advisor repair, **five fresh six-seat Advanced games all finish**
+4,339 accepted/4,358 attempts/114 JSON continuations on unchanged tree
+`2ada89969c683b3ed263f39b9467f623205d83b765cb3639832ee10adf918aae`.
+The19 rejected candidates remain recorded, including existing arrival guards.
+
+Three original backed-up CLI setups preserve the real actors, decks and starting
+choices: **HH7VHT2U v21**, **4H5CZDMA v18** and **6K5JFNPH v18**.
+Real second-turn Nexus actions earn the alliances before labelled conserved
+positions. Refreshed390px controls have no root overflow:
+
+- HH7VHT2U pays Harkonnen5 once: Emperor10→13, Guild6→7 and Harkonnen12→8
+  after the1/1 Kaitain share. Harkonnen’s actual hand fills8; Atreides chooses
+  its ally Fremen for the one real bonus, whose hand1→2.
+- Its actual three-normal-force Kaitain shipment costs6: Emperor11→5,
+  Guild7→10, Atreides12→13 and Fremen3→5 after the1/2 Junction share.
+  The restored BG control sends its actual advisor into Hagga Basin afterward.
+- Original Collection has Fremen5 plus two actually shared2-spice bank grants:
+  total9, retained5, occupied4 allocated Guild1/Harkonnen3. **v72/Mentat**
+  ends with Emperor5/Guild17/Harkonnen11/Fremen10/Atreides13/BG9.
+  The five bank receipts and percentage settle once before original readiness.
+- 4H5CZDMA’s native seller chooses Once Around/counterclockwise; Guild chooses
+  only original Ornithopter. The actual5-spice Harkonnen purchase splits Richese
+  net as native3/occupied2, then Guild1/Harkonnen1: balances4→7/5→6/10→6.
+  A single real bonus reaches Atreides; **v29** preserves the next native lot.
+- 6K5JFNPH’s Guild alone sees the actual six-card Ix pool and returns original
+  Snooper to the top. **v25** retains five auction cards/five Guild-known faces,
+  native Ix-known0 and its unrelated Technology decision still owned by Ix.
+
+Only dedicated QA records changed; no game reset, public activation or credential
+disclosure. Reports/private receipts remain outside Git. These local receipts do
+not certify full Homeworlds, deferred assurance or deployed acceptance.
+
+
 ## Stable continuous occupation prototype — 5 October 2026
+Historical checkpoint `5e902e3`; its narrower Advanced lifecycle and absent
+percentage/Bidding paths are superseded by the source cutover above.
+
 
 The fresh local `homeworld-occupation` entry uses original two-through-six-seat
 Basic/Advanced setup, selected faction decks, thirteen physical card facts and
@@ -110,7 +216,7 @@ The following is an implementation design derived from those timing requirements
 
 A public qualification record needs no hand, Traitor, Face Dancer or sealed-plan data. Malformed initialized evidence must fail validation; a legacy save lacking history cannot be claimed to prove that no earlier qualifier existed. Resolving entitlement by scanning current armies alone would discard the distinction the publisher created.
 
-## Questions the retrieved sources do not settle
+## Basic source questions and historical publisher gaps
 
 | Concrete situation | Missing decision; do not silently substitute a policy |
 | --- | --- |