Dune/docs/SMUGGLER_BATTLE.md

Smuggler battle collection

20 September 2026. Prototyped, with Partial rules coverage. New battles in the base-faction Leader Skills preview connect the lower Smuggler effect in Basic and Advanced games. Public module, mode and publication gates remain closed.

Native Discovery legal participation — 6 October 2026

Three genuine native Skills/Discovery/Tech captures had legal hidden-trainer plans but no bot candidate: the policy recomputed full-state module admission against a player view that intentionally lacks private/internal configuration. The engine now projects smugglerCollectionSupported beside the existing saved battle format flag; bots use that authoritative rule result rather than reconstructing the module profile. Modified-strength and multiple-positive-pile guards applied to each actual plan at that checkpoint; the 9 October allocation policy below replaces only the latter. No public mode or strategy tuning is added. All three original captures finish without rejection. Source trees/counts and limits are in the native Discovery evidence.

Rule and timing contract

The source follow-up combines the printed reveal-time collection with the common requirement that the selected skilled leader survive. The card does not require winning or retaining forces. A captured skilled leader grants its lower effect to its controller.

At public plan reveal the server records the battle, controller, selected leader, plans, skill posture and territory's existing positive spice piles. The amount is the smaller of their aggregate total and the unmodified disc strength. This pending amount is not personal spice and cannot fund a sealed plan or another payment. After survival is known, the server transfers it once, including for a surviving loser, before Sandmaster adds any after-victory spice. A pile drained to zero cannot receive Sandmaster's addition. This deferred settlement and ordering remain explicit timing inferences, not a newly discovered publisher ruling.

A weapon death, opposing or mutual Traitor, or Lasgun–Shield explosion voids the collection. A successful sole own Traitor call can leave the Smuggler alive and eligible. A void receipt changes no pile; it cannot restore spice destroyed by an explosion. Capture return/death cleanup follows settlement without paying the original owner. This board transfer is neither bank income nor another player's payment, so it does not invoke Banker or Bureaucrat payment handling.

Connected behavior

• A shared admission quote serves the server, player controls and four AI profiles. Public mode flags and the player's own chosen plan determine the guard; an opponent's concealed cards do not control eligibility.
• Guidance explains the pending amount, survival and spending restriction. Single-pile collection remains automatic with no acknowledgement. Partial multi-pile collection asks only the surviving controller to choose concrete sectors; collecting all or none remains automatic. The choice has no decline.
• AI candidates omit optional Kwisatz when selecting Smuggler and reject other unsupported modified plans. Native face-up skilled discs remain unavailable to battle selection; captives and existing mandatory concealment retain their legal paths. UI availability and the submitted Kwisatz value share one check.
• Existing single-pile signed receipts have JSON/SQLite continuation evidence. Multi-pile choices retain the same battle binding and have changed-path JSON and real-engine control smoke; comprehensive persistence assurance remains deferred until all rules are implemented. Reads/actions reject changed plans, receipts, pile or identity. Public views expose the selected leader, controller and pending amount only after reveal; the internal binding frame is never projected. Concurrent final votes use the existing versioned room write to prevent duplicate collection.
• Battles already saved without the new version keep their original behavior. Subsequent battles use the new flow. There is no database migration or reset.

Multi-pile allocation policy and pure API — 9 October 2026

The printed collection amount applies to the territory's aggregate existing spice, capped by the unmodified leader strength. The available source does not specify which sectors supply a partial multi-pile collection. Owner-selectable sectors are a provisional prototype allocation policy, not a publisher ruling. The owner controls only distribution, never the mandatory amount. Controls appear after revealed outcome establishes survival and before physical settlement, preceding any Sandmaster placement choice. Inputs start with a legal deterministic fill and require the exact total within each revealed pile's capacity.

game/smuggler-battle.ts preserves legacy receipt fields and signatures:

• SmugglerBattleReceipt retains key, before, amount, stage, and its original battle binding. Multi-pile receipts add piles?: Record<string, number>, use key: null, and set before to the aggregate total. Signed owner choices add allocations?: Record<string, number>. Single-pile and empty receipts retain their original shape.
• smugglerBattleAllocationRequired(receipt, survives): boolean reports a missing choice only for a surviving pending receipt with at least two positive piles and 0 < amount < before. All/none collection and death need no choice.
• chooseSmugglerBattleAllocation(receipt, allocations): SmugglerBattleReceipt verifies the pending signature, accepts only reveal-time positive keys and nonnegative safe integers within their recorded capacities, requires a total exactly equal to amount, omits zero entries, and returns a new signed receipt without mutating its input.
• settleSmugglerBattle(receipt, survives, spice) verifies the signed receipt and unchanged reveal-time positive piles, requires the surviving ambiguous choice, debits those concrete sectors, and returns { receipt, amount, spice }. Death returns a signed void receipt with zero transfer; forced all/none collection is automatic. A settled receipt cannot be settled twice.
• SmugglerBattleCollectionOffer is the owner-only public shape { event: string, player: string, territory: string, amount: number, piles: Record<string, number> }. SmugglerBattleCollection({ offer, busy, act }) inspects only those public piles and submits { type: 'decision', event, allocations }; noninteger, over-limit and incorrect-total selections cannot be submitted.

Focused pure regressions cover differing valid sector debits, immutable allocation rejection, omitted zeroes, same-total reveal-pile redistribution, choice-signature corruption, death/all/none automation and legacy single-pile settlement. These regressions specify prototype allocation boundaries, not new printed rulings.

Boundaries and evidence

Kwisatz, separate trainer bonuses and Stunner still await the existing modifier question; no user answer is assumed. Expansion rosters/cards, the independent Ecaz card variant and other optional modules remain guarded before the Smuggler plan seals. These development restrictions are not rules that forbid those combinations in the physical game. Stone Burner and other expansion combinations therefore have no connected acceptance claim here.

Focused engine tests cover winners/losers in both modes, empty/short piles, zero surviving forces, death and Traitor outcomes, explosion, capture custody, Sandmaster order, corruption, immutable rejection, legacy continuation and all four bot profiles. SQLite tests cover authenticated restart, private projection, concurrent final votes and replay rejection. Browser and full-game sample scope, required check/build/HTTP results, preservation and verified Git delivery are recorded in the private source-bound checkpoint and commit message. This does not certify every Leader Skill or combined-module interaction.