Dune/docs/AUTOMATIC_ACTIONS_AUDIT.md

# Automatic actions and player decisions

Read-only engine/UI/API audit, 2026-09-06, against the updated goal's requirement: automatic effects should not require confirmation; optional 1–2-second house-colored action notifications must not block play. Only this audit document was written. No rule or timing interpretation was changed.

## Safest concrete removals

| Current behavior                                                                                                                                                                                       | Why it is redundant                                                                                                                                                | Safe implementation boundary                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolveBattle` creates `battleLosses` even when `casualtyOptions` contains exactly one result (`game/engine.ts`, approximately 3753 and 3873).                                                        | There is no choice of unit mix. Even a zero-loss result can require a click. This differs from storm casualties, which already resolve a forced mix automatically. | Extract the existing settlement of the selected option from the `battleLosses` handler. Invoke it directly for one option. Preserve the following Ixian substitution decision, winner card-retention choice, and postbattle continuation. Do not bypass them by merely calling `finishBattle`.                                                                                                 |
| Every power owner must submit `passResponse` for its own power; completion currently counts every player (`game/engine.ts`, approximately 5695–5715; `components/game-table.tsx`, approximately 1495). | The same dispatcher explicitly forbids the owner from canceling its own power. This pass is not an ordinary Karama cancellation choice.                            | Count the owner as satisfied using public `response.owner`, while requiring all other participants' passes. Use one shared responder predicate for engine, bots and UI; normalize persisted windows and nested Worthless-Karama windows. Keep permitted Truthtrance/CHOAM overlays available while the actual responders decide. Do not globally auto-pass other players based on their hands. |
| `fullPlanRead` only accepts `{continue:true}` (`game/engine.ts`, approximately 6291); UI requires “Finish inspection.”                                                                                 | Opponent's plan is already committed, and the Atreides player's next meaningful action is preparing their own plan. The acknowledgement does not choose an effect. | Remove the extra blocking decision only with persistent private inspection in the ordinary plan editor. Preserve `fullPlan` target-first submission and authorized `insight`, including Truthtrance promises. A 1–2-second animation must not be the sole way to inspect a tactical plan. Legacy saved `fullPlanRead` can normalize to the plan editor without submitting a plan.              |

These findings are based on actual code branches, not a count of buttons labelled “Confirm.” No runtime reproductions were needed to establish the singleton branch or all-player response predicate; new integration tests remain necessary before modifying them.

The owner-pass reduction does not establish a new automatic deadline for other players. A player who has already passed can currently still use permitted overlays/cancel before the last responder passes; preserve those existing rights unless a separate authoritative timing change is made.

## Additional candidate requiring a narrower integration check

`beginPhase(7)` calls `collect(g)` immediately. The UI then presents “Ready for next phase” to every player even though collection has already happened. Current `collect` contains automatic stronghold/desert awards; no collection allocation choice is exposed in this baseline. A collection-result notification followed by the existing phase-end continuation would remove a likely acknowledgement-only pause.

Do **not** implement this by removing all phase readiness or skipping `nextPhase`: CHOAM phase-end market, technology settlement, future Ecaz co-collection choices, and any applicable phase-specific reactions must remain. Complete the current phase's real decisions first. Special CHOAM and Truthtrance currently have broad timing, so verify their existing before/after boundary semantics when advancing automatically. This candidate is less isolated than singleton casualties and is not certified as a universal all-expansions rule.

## Prompts that protect real choices

| Prompt/window                                                                    | Actual choice or reaction protected                                                                                                                                                                                              |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Storm movement confirmation                                                      | Weather Control and Family Atomics before movement. Do not move storm on a display timeout.                                                                                                                                      |
| Accept spice blow                                                                | Harvester timing; other current Spice Blow continuations also include Thumper, Nexus, Fremen special Karama and worm choices. A publicly Harvester-closed blow can be examined separately, not used to remove all spice windows. |
| Phase opening                                                                    | Amal, including an opportunity after a prior Amal. The engine deliberately offers the same window regardless of hidden ownership.                                                                                                |
| Opponents allowing powers                                                        | Ordinary Karama; Advanced BG Worthless conversion and nested cancellation. Income that looks automatic still has a cancellation window before settlement.                                                                        |
| Guild shipment, full-plan offer, revival stop                                    | Spending an optional special Karama versus preserving it; hand-independent offers prevent information leaks.                                                                                                                     |
| Charity/Revival ready                                                            | Remaining claims, revival resources, leader/force choices and other phase powers. Zero current payable revivals is not proof of no actions when special cards or resources can change.                                           |
| Winner card cleanup, Moritani retention, Poison Tooth                            | Keep/discard/activate choices remain even if one card is involved. One eligible card still offers keep versus discard.                                                                                                           |
| Advisor arrival/intrusion, Face Dancer, captured leader, Moritani/Ecaz placement | Optional effects, destinations, ownership or spending choices. Their availability is not equivalent to mandatory use.                                                                                                            |
| Mentat readiness                                                                 | Negotiation, later turn-end effects, Face Dancer replacement, Gamont and other faction choices; do not globally skip because victory has already been checked once.                                                              |
| Lobby readiness, battle-plan lock, storm dial                                    | Consent or sealed strategic decisions, never automatic acknowledgements.                                                                                                                                                         |

`choamTradeConfirm` is a genuine final assent after the ally specifies the returned card. `auctionPayment` can choose Karama versus spice. Do not remove either simply because it contains a confirmation label.

## Existing automatic behavior to preserve

- `stormCasualties` calls `kill` directly when the allowable elite-loss interval is a singleton; only a real mix choice creates `stormLosses`.
- `finishBattle` transfers a single available technology token directly; multiple tokens produce `techToken`.
- Empty winner-card cleanup proceeds immediately; combat with no remaining battles advances through its existing phase-end continuation.
- Force transfers, payments, resource awards, setup completion, predetermined casualties and battle results already commit on the server; they need presentation, not new acknowledgements.

Do not replace these with client confirmation steps merely to make animations visible.

## Privacy and multiplayer requirements

**Do not auto-pass based on a player's hidden hand.** A faster or absent Karama/Amal/Guild-special window would disclose that a player lacks a relevant card. A private local checkbox which emits an immediate pass only when a card is absent can leak through visible timing too. Removing a responder because they publicly own the power is different: that condition is already public and the rules branch prohibits self-cancellation.

Automatic rules resolution belongs in the authoritative engine on the disposable action clone, before the database compare-and-swap commits. `db/rooms.ts act` currently applies one action, runs AI, increments version and writes under room-version plus current-token authority. A deterministic normalization chain can share that transaction. It must stop at the first meaningful choice/reaction and use a bound that reports a real loop rather than silently dropping work. Do not imitate human confirmations from the browser or add client timer POSTs.

`continueRoomBots` already persists bounded AI batches with version fencing. It is not permission to advance human choices, and an animation completing must not call `advanceBots`, `ready`, or `passResponse`. Read-only GET/reconnect should project state; any migration that resolves a legacy redundant decision must happen at an explicit authoritative write, or a separately designed fenced continuation, never a mutating view.

## Nonblocking notification contract

The UI currently has ordinary game logs and reduced-motion CSS, but no audited structured automatic-action notification stream. `Game.log` contains `{seq,text}` and retains 250 entries; one persisted bot batch can produce many events and skip intermediate phase snapshots. A phase-name comparison alone cannot reliably report every action.

Prefer small server-authored public event metadata such as `{seq,kind,actorFaction,label}` alongside the settled result. Private effects need viewer-authorized metadata; do not infer secrets from full game state or put inspected cards into public events. Keep action names separate from player-generated names and arbitrary log parsing.

Display each notification for approximately 1–2 seconds, with faction colors and a readable action name. It must use no modal backdrop, focus trap, pointer interception or disabled gameplay state. Provide a local toggle, honor reduced motion, and keep a durable readable history. Turning it off must change only presentation. Keep a per-room processed sequence so refresh or stale poll cannot replay old notifications; initialize a newly joined/restored view at its current sequence. Coalesce excessive AI-batch notices rather than queueing minutes of stale animation. Avoid announcing the entire historical log through a live region on every update.

## Meaningful validation before changes land

1. Single-option Advanced casualties settle exactly once, including JSON legacy state; multiple options still ask. Ixian cyborg losses still offer legal substitution. Winner cleanup, Moritani retention, technology/capture/Face Dancer continuations remain intact.
2. Power owner is never a required pass; every other player remains eligible, including an ally. Windows remain identical for hidden-card variants. Nested BG conversion/counter and Truthtrance overlays restore the correct responders.
3. Special prescience proceeds to Atreides planning with persistent private opponent-plan visibility; the opponent cannot change it and other seats cannot inspect it. Refresh preserves the insight; no automatic battle plan is submitted.
4. Automatic settlement survives duplicate requests/concurrent CAS without duplicate payment, RNG, casualties or events. A disconnected owner's redundant acknowledgement cannot stall an otherwise settled window.
5. Notices remain nonblocking on desktop/mobile and keyboard; toggle/reduced-motion behavior does not affect room state. Reconnect and multi-event bot batches do not replay history or expose hidden identities.

Full scope remains gated. This is an implementation audit of the present runtime, not a claim that every future expansion effect is automatic or already covered.

## Implemented checkpoint (2026-09-06)

The candidate audit above describes the earlier baseline. Singleton auction payment and full-plan acknowledgement removal are now implemented. Exact funded split plus no usable Karama permits automatic payment; a real Karama choice remains explicit. Atreides retains private plan inspection until reveal, including when helping an ally. Legacy saved decisions recover via authenticated CAS continuation. Tests: automatic-decisions, full-plan, automatic-response-recovery, and the full 1,029 rules / 74 persistence checkpoint. Other candidate pauses still require their own timing audit.