Combine current facts with future ground movement

docs/TRUTHTRANCE_MIXED_MOVEMENT.md

@@ -0,0 +1,122 @@
+# Truthtrance current facts and future ground movement
+
+## Mixed aggregate prototype — 26 October 2026
+
+**Prototyped / Partial.** The packet is
+`{kind:'mixedMovement',target,turn,mixed}`. The raw tree combines current
+`{kind:'fact',fact}` leaves, future `{kind:'action',action:{territory,minimum}}`
+leaves and full AND/OR. It uses the existing native Basic/Advanced phases0–5
+[ground-movement opportunity](TRUTHTRANCE_MOVEMENT_EXPRESSIONS.md), with no new
+mode/start permission. Both clause families are required in a mixed question.
+
+## Authority and conservative snapshot meaning
+
+Reuse the recorded [nonbattle source audit](TRUTHTRANCE_NONBATTLE_READINESS_20260907.md#source-basis),
+[November2020 FAQp8](https://www.gf9games.com/dune/wp-content/uploads/2020/11/Dune-FAQ-Nov-2020.pdf)
+current-turn/AND/OR authority and supplied Advanced physical39/printed37 public
+answer/compliance/release/unknown text. These sources do not prescribe an
+online solver. The existing [mixed-shipment model](COMPOUND_SHIPMENT_PROMISES.md)
+provides the current-fact snapshot/aggregate precedent. This conservative
+composition remains explicit provisional software interpretation under
+standing14October choose-recommended priority.
+
+Facts freeze at actual answer time. A fact about holding Hajr stays the
+answer-time fact after the same physical card is played and discarded. Later
+spending/forces/custody do not create a promise to preserve the earlier state.
+Only the complete yes/no answer is public. Individual fact answers and privately
+reduced branches are not separately published.
+
+For a definite Yes, unknown facts take the worst case false; for No, the worst
+case true. The remaining owned-action completion must guarantee that entire selected
+answer. The formula is positive AND/OR, so the conservative case guarantees the
+aggregate for all unresolved fact values. This does not infer correlations
+between unknown predicates. If neither definite answer has a known completion,
+unknown/save/change-question remains available. No negates the whole question,
+not each fact or action leaf.
+
+True Hajr OR move can settle Yes immediately. False Hajr AND move can settle No
+immediately. True Hajr AND move retains its future movement requirement;
+unknown forecast OR move Yes must actually move, while unknown forecast AND
+move No must avoid the qualifying group. Ordinary per-destination maximum
+progress, not summed smaller moves, remains.
+
+## Native integration and controls
+
+`game/mixed-action-question.ts` validates the full public tree before any
+short-circuit, with one16-leaf/depth4 budget including nested fact groups. The
+server's existing fact decoder and exact movement-leaf decoder remain authority.
+Public constants, targets, turns and other metadata cannot be forged inside
+clauses. The reusable compiler evaluates all fact leaves before folding known
+constants/identity children/singletons into an action-only residual.
+
+The engine converts that residual into the existing movement-expression ledger;
+there is one physical fulfillment ledger, not a second set of movement/payment
+rules. Raw `mixedMovementQuestions` metadata links the original question to its
+binding event. A constant aggregate needs no native binding. Existing owned
+search, card preservation, preparations, funding, range responses and actual
+owner finish retain their original behavior. Early readiness resets uniformly
+for definite mixed answers; no public branch-specific readiness cue is added.
+New mixed discard signatures include its metadata/binding while older record
+signatures keep their original shape.
+
+Only own raw question, aggregate answer/status and recorded native movement
+maxima are projected. Compiled residuals are filtered out of the public pure
+movement ledger, and raw internal metadata/frozen fact answers are not exposed.
+The native guide is still entitled only to its owner and exact live event.
+No separate public movement-fulfillment message reveals whether a private fact
+created a residual. Required whole-answer release and public physical actions
+retain their original aggregate information.
+
+The full controlled editor reuses current-fact and nested-fact fields, supports
+add/wrap/nest/switch/remove/collapse and preserves repairable invalid drafts.
+Preview/Ask retain the whole raw tree. The aggregate panel and pure/scalar
+movement panels show one shared exact guide. Four minimal policies answer and
+follow that native guide; strategy/calibration remain deferred.
+
+## Evidence and remaining gates
+
+Generic cases: `tests/mixed-action-question.test.ts`.
+Controlled cases: `tests/truth-mixed-movement-controls.test.tsx`.
+Original sources/cases: `tests/fixture-truth-mixed-movement.ts` and
+`tests/truth-mixed-movement-runtime.test.ts`. Twelve generic,eight controlled
+and16 native cases are included in the frozen **19-file,172/172** union.
+Types/lint, production build and nine native paths pass on the same unchanged
+source. Actual GameTable SSR renders29 times;16 actual guide callbacks submit
+native packets. One actual mixed editor meaning callback retains the complete
+raw tree through native Ask. Four minimal profiles actually answer and complete
+the native Hajr path on both Basic/Advanced original sources.
+
+| Original base33 source | Prefix actions | Further actions | Actual result |
+| --- | ---: | ---: | --- |
+| Basic frozen Hajr AND | 20 | 8 | Held-Hajr fact survives real disposal and two future groups |
+| Advanced frozen Hajr AND | 23 | 8 | Same snapshot with native post-movement Hajr timing |
+| Basic edited true OR | 20 | 5 | Actual AND→OR edit/Ask; immediate Yes, no native binding |
+| Basic false AND | 20 | 6 | Immediate No; a real named move remains legal |
+| Basic false OR | 20 | 6 | Yes requires the actual future group |
+| Basic true AND No | 20 | 6 | Qualifying group rejects; nonmatching group/real finish allowed |
+| Basic unknown OR Yes | 20 | 6 | Native unknown forecast cannot substitute for real movement |
+| Basic unknown AND No | 20 | 5 | Qualifying movement forbidden until actual owner finish |
+| Basic early Charity | 13 | 14 | Real later readiness/auction/shipment/movement path |
+
+Initial type feedback repairs a nested generic test union and explicit status
+fields on a controlled view; no production rule repair is needed for that
+feedback. The passing v2 source snapshot is
+`557dd5178963e1a868be972d1f44da91d4522d874fa38147970c8a106e9aad3a`
+(3153 files). Final evidence prose is a separate three-document overlay.
+Frozen proof/report/manifest:
+`/home/quintine/.local/share/dune/checkpoints/20261026-truth-mixed-movement-proof-v2/`;
+journeys/HTML: adjacent `20261026-truth-mixed-movement-runtime/`.
+SSR/editor/guide callbacks are local engine/control evidence, not DOM,
+hydration, browser/mobile or deployed acceptance.
+
+Sources inherit the original base33 Basic20/Advanced23 Hajr/Truthtrance setup
+and paid Polar shipment, plus Charity13. Native non-Fremen forecast supplies an
+actual unknown without installed knowledge. No extra clock, purse, hand, army,
+fact answer, promise or progress is installed. Controlled projections retain
+those labels rather than claiming original acquisition histories.
+
+Other action families, correlated-unknown reasoning, optional modules, broader
+faction/card/funding compositions, final rules/recovery/privacy/custody review
+and browser/mobile/deployed acceptance remain required. No complete mode is
+certified. No saved-game/database/server/reset/restart/deployment operation is
+performed by this batch.