docs(runtime): define P9.1 modular architecture

docs/runtime/p9_1/RUNTIME_ARCHITECTURE_SPEC.md

@@ -0,0 +1,630 @@
+# P9.1 Runtime Architecture Specification
+
+> Status: expert input for PMO reconciliation
+> Baseline: `dec9574405043624acee0f4f81963d829e8d40e9`
+> Preserved product source: P9.0R10 at `41204acafa911a505f5b24a493aa032983e706d1`
+> Scope: behavior-equivalent extraction boundaries and P9.1 parallel write contract
+
+## 1. Decision Summary
+
+P9.1 shall keep `runtime/main.tscn` and its root `Control` as the only scene
+entry while reducing `runtime/main.gd` to a compatibility facade and
+composition root. Deterministic first-session rules move into plain
+`RefCounted` domain objects before new gameplay is added. Rendering and
+real-time playback consume immutable snapshots and domain-emitted facts; they
+do not calculate outcomes.
+
+The required dependency direction is:
+
+```text
+main.gd facade / composition root
+  -> ui/p9_1/* presenter and Control builders
+  -> presentation/* clock, animation, feedback and audio adapters
+  -> domain/p9_1/* session state, commands, battle fixtures and copy facts
+
+tests -> public facade during extraction
+tests -> domain/p9_1 APIs for P9.1 matrix and transaction tests
+domain/p9_1 -> no Node, Control, SceneTree, Input, AudioServer or frame clock
+```
+
+There is no event bus singleton and no autoload in this milestone. The root
+constructs dependencies explicitly. Domain commands return typed-by-contract
+`Dictionary` results because this repository currently uses GDScript without a
+schema library; every payload has a stable `kind`, required keys and value
+types documented below. Introducing a dependency, plugin or autoload would add
+global ownership and is not justified by this bounded slice.
+
+This document does not authorize runtime edits. The reconciled implementation
+contract must preserve P9.0R10 behavior and the Owner-accepted player arc.
+
+## 2. Baseline Inventory
+
+### 2.1 Current responsibilities and concrete symbols
+
+`runtime/main.gd` is 3,704 lines. It currently owns all of the following:
+
+| Responsibility | Mutable state or concrete symbols | Current coupling |
+|---|---|---|
+| Boot and navigation | `AppPage`, `page`, `run_boot_verification`, `enter_game`, `start_new_game`, `go_home`, `confirm_restart` | Page mutation immediately calls `render()` and audio cues. |
+| Session presentation settings | `locale`, `text_scale`, `reduced_motion`, `muted`, `toggle_*` | Localization and accessibility branches are read throughout rendering and animation. |
+| Recruit selection and formation | `selected_recruits`, `front_choice`, `rear_choice`, `formation_commit_count`, `toggle_recruit`, `assign_automatic_formation`, `commit_formation` | Rules, copy, sound and rerender are in the same methods. |
+| Run transactions | `coin`, `adaptation_*`, `guild_*`, `retained_item`, `added_rear`, `route_*`, `training_*`, reward flags | Selection validation, commit-once guards, spend/reward and page transition are interleaved. |
+| Battle fixture state | `battle_phase`, clocks, HP, event counters, `phase_impact_committed`, five elapsed/result times | The render frame calls state mutation through `_process`, `commit_phase_impact` and `advance_battle_phase`. |
+| Battle outcomes | `commit_phase_impact`, `commit_second_phase_impact`, `commit_third_phase_impact`, `commit_fourth_phase_impact`, `commit_fifth_phase_impact` | Outcome tables are page branches and call `play_cue()` plus `render()`. |
+| Causal explanations | `victory_explanation`, `second_result_explanation`, route/training/build helpers | Product facts, localized prose and presentation colors share the root script. |
+| Rendering | `render`, 20-plus `render_*` methods, button/style/actor helpers | Full `DisplayRoot` tree is destroyed and rebuilt on every render. Stable node names are test API. |
+| Playback | `ANIMATION_SPECS`, animation-state functions, `_process`, sprite positions, projectile | Domain phase, wall-clock time, animation frames and Control coordinates are coupled. |
+| Feedback and audio | `active_battle_feedback`, history, `emit_battle_feedback`, `update_battle_feedback_visual`, `play_cue` | Exactly-once outcome facts are stored in UI-shaped dictionaries and trigger platform services directly. |
+| Cleanup | `clear_experience`, `_exit_tree` | One long reset method owns all transient domain and presentation state. |
+
+The independent `runtime/domain/run_state.gd` and current `runtime/tests/p9_1_*`
+belong to an older opening-market lineage. They expose `game.run` and
+`AppPage.RUN`, neither of which exists in the P9.0R10 accepted runtime. They are
+not a second authority for this extraction and must not be merged into the new
+P9.1 first-session model by name alone. PMO must explicitly classify them as
+legacy/quarantined or separately restore that lineage before any runner claims
+they are part of the P9.0R1-R10 regression suite.
+
+### 2.2 Current event flow
+
+The accepted runtime uses this loop:
+
+```text
+Control signal callback
+  -> root method validates current page and mutable fields
+  -> method mutates values and page
+  -> play_cue()
+  -> render() rebuilds DisplayRoot
+
+_process(delta)
+  -> advances wall clocks and sprite positions
+  -> crossing impact time calls commit_phase_impact()
+  -> impact function mutates HP, appends feedback and plays audio
+  -> crossing phase duration calls advance_battle_phase()
+  -> phase completion mutates reward/page and rerenders
+```
+
+The problem is not that a render loop exists. The problem is that a skipped or
+duplicated render frame can currently enter the outcome mutation path. P9.1
+must make the deterministic command/impact transaction callable without a
+scene tree and make the real-time driver only request named impacts once.
+
+### 2.3 Existing regression seams
+
+The preserved P9.0 tests instantiate `res://main.tscn` and directly read or
+write root fields. Across the suite they rely on:
+
+- `game.AppPage` numeric names and `game.page`;
+- public state such as `front_choice`, `rear_choice`, HP, Coin, choices,
+  commit flags, phase clocks/counters and feedback history;
+- direct calls such as `advance_battle_phase`, `commit_phase_impact`,
+  transaction methods, copy helpers, `render` and `clear_experience`;
+- `ANIMATION_SPECS`, duration helpers, animation lookup and sprite references;
+- stable Control names searched recursively and real
+  `Input.parse_input_event` touch delivery;
+- exact marker output, strict diagnostic cleanup and fixed result values.
+
+This is an intentionally broad compatibility surface during extraction. Tests
+shall not all be rewritten to new APIs in the foundation step because doing so
+would remove the evidence that behavior was preserved. The facade keeps that
+surface until equivalent domain and UI contract tests pass at the same source
+revision; compatibility removal is a later integration action with explicit
+criteria in section 10.
+
+## 3. State Ownership
+
+Exactly one object owns each mutable value. Snapshots are deep copies and
+consumers must treat them as immutable.
+
+| Owner | Authoritative mutable state | Explicitly does not own |
+|---|---|---|
+| `RuntimeShell` (`main.gd`) | Dependency instances, boot verification fields, `render_pending`, compatibility property forwarding | Run outcomes, choice validity, HP/Coin calculations, UI-derived recommendations |
+| `PresentationSettings` | `locale`, `text_scale`, `reduced_motion`, `muted`, `audio_enabled` | Gameplay state or translated gameplay facts |
+| `FirstSessionState` | Current domain screen, selected members/order, all selection/commit flags, Coin, HP, rewards, route/growth state, current encounter progress, committed impact IDs and semantic fact history | Nodes, textures, positions, elapsed frame delta, audio |
+| `BattleFixture` | Immutable encounter phase definitions, durations, impact IDs and deterministic transition functions | Mutable progress/history, sprite references, animation frames, pixel coordinates, localized labels |
+| `BattleClock` | Playback elapsed seconds for current phase/encounter, result display time, active feedback display age | HP/Coin or whether an impact is legal |
+| `SessionPresenter` | Node references it created, ephemeral hover/focus and layout data | Any decision or outcome duplicated from domain state |
+| `AnimationPlayerAdapter` | Loaded textures, animation frame selection, actor base positions, projectile visual state | Domain phase transitions or impact commits |
+| `FeedbackPresenter` | Current rendered number/VFX node and display age | Feedback history or damage/heal calculation |
+| `AudioAdapter` | `AudioStreamPlayer` and generator playback lifecycle | Outcome choice or transaction state |
+
+The domain screen is not a Godot `Control`. Use stable domain names rather than
+numeric UI enum values:
+
+```text
+boot, title, main_menu, game_intro, settings, first_mission,
+recruit_selection, formation_review, yard,
+battle_1, result_1, adaptation, battle_2, result_2,
+guild_response, battle_3, result_3,
+route_board, route_review, battle_4, result_4,
+growth, growth_review, battle_5, session_result
+```
+
+The compatibility facade maps these names to the existing `AppPage` constants.
+Historical `FRONT_SELECTION` and `REAR_SELECTION` remain facade-only enum
+values and are never legal domain screens.
+
+## 4. Module and File Contract
+
+### 4.1 Foundation-owned shared extraction
+
+The foundation change creates and wires these stable boundaries before domain,
+UI and test workers start:
+
+| File | API and responsibility |
+|---|---|
+| `runtime/main.gd` | `RuntimeShell`; scene lifecycle, boot, dependency construction, facade properties/methods, render scheduling. No new P9.1 rule branches. |
+| `runtime/presentation/presentation_settings.gd` | Session-local locale, text scale, reduced-motion, mute, audio availability and low-power values; emits no gameplay event. |
+| `runtime/domain/p9_1/session_state.gd` | `FirstSessionState`; data container, `reset_transient()`, `snapshot()`, invariant checks. Initial implementation mirrors accepted fields exactly. |
+| `runtime/domain/p9_1/session_service.gd` | `FirstSessionService`; all selection and commit commands, screen transitions, rewards and encounter start/finish. |
+| `runtime/domain/p9_1/battle_fixture.gd` | Deterministic encounter definitions, `duration_for_phase`, `impact_time`, `commit_impact`, `complete_phase`; emits semantic facts without Node calls. |
+| `runtime/domain/p9_1/contracts.gd` | Stable screen, command, encounter, event and rejection string constants; snapshot schema version. |
+| `runtime/presentation/battle_clock.gd` | Converts `delta` to `impact_due` / `phase_due` requests; freezes during confirmation; owns elapsed display timing only. |
+| `runtime/presentation/animation_adapter.gd` | Asset library and animation frame lookup extracted without changing frames/timing. |
+| `runtime/presentation/audio_adapter.gd` | Existing generated SFX setup, cue playback, mute and cleanup. |
+| `runtime/ui/session_presenter.gd` | Existing render dispatch and render helpers moved behavior-equivalently; consumes snapshot and callbacks. |
+| `runtime/ui/widgets.gd` | Existing button, label, actor, bar and style builders; no domain reads. |
+| `runtime/compat/p9_0_root_facade.gd` | Mapping helpers used by `main.gd` to preserve test-visible properties, calls and `AppPage`. No independent mutable state. |
+
+If GDScript property forwarding makes `runtime/compat/p9_0_root_facade.gd`
+impractical as composition, keep the thin forwarding code in `main.gd`; do not
+use inheritance or duplicate fields merely to satisfy this proposed filename.
+The contract is one authoritative state object plus a compatible root surface.
+
+### 4.2 Domain APIs
+
+`FirstSessionService` exposes commands. Every command returns:
+
+```gdscript
+{
+  "ok": bool,
+  "code": StringName,       # stable success or rejection code
+  "events": Array[Dictionary],
+  "snapshot": Dictionary,  # deep copy after the attempt
+}
+```
+
+Required commands for the preserved and P9.1 path are:
+
+```text
+reset_transient
+open_new_session
+toggle_recruit(profession_id)
+review_formation
+revise_formation
+commit_formation
+choose_adaptation(item_id)
+commit_adaptation
+choose_guild_response(response_id)
+commit_guild_response
+choose_route(route_id)
+review_route
+cancel_route_review
+commit_route
+choose_growth(member_id)
+review_growth
+cancel_growth_review
+commit_growth
+commit_impact(encounter_id, phase, impact_id)
+complete_phase(encounter_id, phase)
+```
+
+Selection commands may change only selection state. Commit commands revalidate
+the entire precondition and either apply all effects once or apply nothing.
+Failures use stable codes such as `wrong_screen`, `invalid_id`,
+`selection_required`, `insufficient_coin`, `already_committed` and
+`stale_encounter`; UI copy is not stored in these codes.
+
+Direct field mutation is not part of the new domain API. Fixtures may use a
+test-only builder in `runtime/tests/support/p9_1_session_fixture.gd` to create a
+validated starting snapshot. Production UI never calls that builder.
+
+### 4.3 Snapshot schema
+
+`FirstSessionState.snapshot()` returns the domain fields in this minimum
+shape. `RuntimeShell.render_snapshot()` adds the `settings` section from
+`PresentationSettings` to a deep copy; it never writes settings into domain
+state.
+
+```gdscript
+{
+  "schema": 1,
+  "revision": int,                  # increases after successful commands only
+  "screen": StringName,
+  "settings": {                     # render snapshot only; composed by shell
+    "locale": StringName,
+    "text_scale": float,
+    "reduced_motion": bool,
+    "muted": bool,
+    "low_power": bool,
+  },
+  "party": {
+    "selected_ids": Array[StringName],
+    "ordered_ids": Array[StringName],
+    "lead_id": StringName,
+    "second_id": StringName,
+    "added_id": StringName,
+    "formation_commits": int,
+  },
+  "resources": {"coin": int},
+  "decisions": {
+    "adaptation": StringName,
+    "guild_response": StringName,
+    "route": StringName,
+    "growth_member": StringName,
+  },
+  "locks": {
+    "adaptation": bool,
+    "guild_response": bool,
+    "route": bool,
+    "growth": bool,
+  },
+  "encounter": {
+    "id": StringName,
+    "phase": int,
+    "playing": bool,
+    "front_hp": int,
+    "rear_hp": int,
+    "enemy_hp": int,
+    "committed_impacts": Array[StringName],
+    "elapsed": float,
+  },
+  "rewards": {
+    "battle_1": bool,
+    "route": bool,
+    "battle_5": bool,
+  },
+  "facts": Array[Dictionary],
+  "available_actions": Array[StringName],
+}
+```
+
+The pure domain snapshot omits `settings`; every other key above is domain
+owned. `available_actions` is domain-derived and allows buttons to enable without
+reimplementing validation. It is not a recommendation and cannot preselect.
+Settings are included only in the complete render input and cannot affect a
+command outcome or the domain revision.
+
+Every `party` member ID is stable and carries profession as member data. P9.1
+must not use UI positions such as `front`, `rear` or `added` as the durable
+identity for growth. The compatibility facade may map the current two-member
+fields while old tests remain.
+
+### 4.4 Semantic events and facts
+
+Domain output is an append-in-result event list, not a signal emitted from a
+Node. Events use these contracts:
+
+| `kind` | Required payload | Consumer |
+|---|---|---|
+| `screen_changed` | `from`, `to`, `cause` | Shell/presenter rerender and focus policy |
+| `selection_changed` | `decision`, `selected_id` | Presenter selection visuals |
+| `transaction_committed` | `transaction`, `decision_id`, `revision`, resource deltas | Result copy facts and tests |
+| `impact_committed` | `encounter_id`, `phase`, `impact_id`, `target_member_id` or `enemy`, `delta`, `qualifier`, `tier` | Feedback, audio and deterministic tests |
+| `encounter_finished` | `encounter_id`, final HP, elapsed fixture time | Presenter/result navigation |
+| `reward_committed` | `reward_id`, `coin_delta`, `coin_after` | Result facts and tests |
+| `run_cleared` | `reason` | Shell clears playback/presentation state |
+
+`qualifier` is a semantic key such as `block`, `evade_reduction`,
+`flank_counter`, `ranged_hit`, `heal`, `combo` or `finisher`, never localized
+prose. UI translation maps keys to Chinese/English. The event's exact `delta`
+is created inside the successful mutation, preserving the P9.0R3 rule that
+feedback is never inferred from animation or page entry.
+
+The `facts` array in a snapshot contains durable causal facts needed for the
+current diagnosis/result. Each fact has `fact_id`, `actor_id`, `action`,
+`target_id`, exact `delta` where applicable, `source_decision_id` and
+`encounter_id`. Result copy is formatted from these facts; it does not rerun
+party classification or outcome calculations.
+
+### 4.5 Presenter API
+
+`SessionPresenter` has one public render entry:
+
+```gdscript
+render(snapshot: Dictionary, actions: Dictionary[StringName, Callable]) -> void
+```
+
+The presenter may request domain actions only through named callbacks. A
+callback calls the service, passes returned events to presentation adapters,
+then schedules a render using the returned snapshot. The UI worker may add
+P9.1 screens and copy formatting under its owned path but cannot read service
+internals or calculate HP, Coin, ordering, coverage, choice value or results.
+
+The presenter continues to create the stable P9.0 Control names until legacy
+tests are retired. New P9.1 controls receive stable semantic names in the
+reconciled UX contract. Node names are input/test handles; labels are localized
+and must never be used as identifiers.
+
+### 4.6 Battle clock handshake
+
+The frame adapter receives the current encounter snapshot and returns requests:
+
+```gdscript
+advance(delta, encounter_snapshot, reduced_motion, paused) -> {
+  "impact_requests": Array[{"encounter_id", "phase", "impact_id"}],
+  "phase_complete": bool,
+  "phase_progress": float,
+}
+```
+
+The shell submits requests to the domain service. The service rejects duplicate
+`impact_id`, wrong phase or stale encounter. Only accepted
+`impact_committed` events reach feedback/audio. `phase_progress` drives visual
+interpolation and animation only. Reduced motion and low power may change
+sampling and translation but never impact order, fixture durations, final
+values or command availability.
+
+Headless tests bypass `BattleClock` and invoke named impacts/phase completion
+directly, proving domain results do not depend on FPS. One integration test
+must still drive large deltas across impact thresholds to prove the adapter
+requests each impact exactly once.
+
+## 5. Compatibility Facade
+
+During extraction, `runtime/main.gd` remains the API expected by P9.0 tests.
+Every facade value is computed from an owner; it is not separately stored.
+
+Required mappings include:
+
+- existing `AppPage` names and `page` getter/setter for fixture/capture tests;
+- selection, party, Coin, choice/commit, HP, phase, reward and feedback getters;
+- existing transaction method names, translating successful service events to
+  `play_cue` and `queue_render`;
+- `phase_duration`, `phase_impact_time`, `advance_battle_phase` and
+  `commit_phase_impact` delegating to fixture/clock/domain boundaries;
+- animation constants/helpers and sprite references delegating to presentation;
+- `render` and stable Control names delegating to `SessionPresenter`;
+- `clear_experience` calling domain reset plus clock/feedback cleanup exactly
+  once.
+
+Compatibility setters are allowed only for fields that existing capture/tests
+set directly. They shall call a clearly named test/compat patch function which
+revalidates the state before rendering. Production callbacks never use these
+setters. Any field that cannot be forwarded without two sources of truth blocks
+that extraction step; the foundation worker must keep it in the root until its
+owner can be singular.
+
+The facade shall contain no P9.1-only pair branching. New behavior enters the
+domain and presenter APIs and is wired by the later integration owner.
+
+## 6. Extraction Sequence and Regression Gates
+
+Each numbered step is a separate commit candidate. A step advances only when
+its focused checks and the serial accepted regression set pass with strict
+diagnostics clean. On failure, revert that step's commit or repair within the
+same owned files; never mask the failure by weakening or rewriting preserved
+assertions.
+
+### Step 0: Freeze evidence and classify the suite
+
+1. Record exact baseline source, Godot version and the ordered P9.0R1-R10 test
+   command/marker manifest in a runner-owned evidence file.
+2. Confirm the accepted suite count from the R10 closure evidence rather than
+   globbing every file named `p9_1_*`.
+3. Record the orphan opening-market lineage separately; do not delete it in
+   foundation extraction.
+
+Gate: clean baseline reproduces all 22 accepted R1-R10 tests, R10 matrix/touch,
+strict marker scan and cleanup. If it does not, terminal is redesign required
+at baseline reproducibility; extraction must not begin.
+
+### Step 1: Introduce state owner behind a no-op facade
+
+Create `contracts.gd`, `session_state.gd` and the compatibility forwarding
+surface. Initialize the state from the same defaults and delegate reset. Do not
+move transactions or change rendering.
+
+Gate: reset/default/navigation tests, Home/Restart cleanup, all direct root
+field assertions and full serial regression. Rollback: remove the state object
+and forwarding commit; no data migration exists.
+
+### Step 2: Extract selection and run transactions
+
+Move automatic formation, adaptation, guild response, route, growth, rewards
+and screen transition validation to `FirstSessionService`, in historical order.
+Keep root method names as wrappers. Every operation gains a focused atomicity
+test: invalid/insufficient/duplicate attempts leave snapshot and revision
+unchanged.
+
+Gate after each transaction family: its original focused test plus snapshot
+diff against baseline fixtures, then the serial suite. Rollback is per family;
+do not move all transactions in one unreviewable commit.
+
+### Step 3: Extract deterministic battle fixtures
+
+Move durations, impact timing, HP mutation and semantic event creation one
+encounter at a time from battle 1 through battle 5. Root methods delegate.
+First preserve exact P9.0R10 values and event order; no arbitrary-party
+post-battle-two behavior is added in this step.
+
+Gate per encounter: exact event sequence, deltas, HP/time, once-only impacts,
+reward, first-battle feedback and associated R1-R7 tests. R10 remains the final
+gate. Rollback only the most recent encounter extraction.
+
+### Step 4: Extract clock, animation, feedback and audio adapters
+
+Move time accumulation and visual playback after outcomes are already domain
+owned. Separate semantic event history from the single active presentation
+payload. Extract animation lookup/assets and audio lifecycle without changing
+timing, frames or accepted cues.
+
+Gate: R2 animation terminal bounds/dynamic slice, R3 exact feedback and reduced
+motion, R3 audio lifecycle, large-delta impact-once integration, Restart pause,
+Home cleanup and serial regression. Rollback adapters independently; domain
+tests must remain green even if presentation extraction is reverted.
+
+### Step 5: Extract presenter and widgets
+
+Move page dispatch, screen builders and shared Control/style helpers. Preserve
+node names, minimum touch size, layout, text scaling, locale behavior and root
+sprite references through the facade.
+
+Gate per screen family: domain/navigation, real parsed touch with direct and
+fallback zero, layout/capture at existing viewports, English 130%, reduced
+motion, mute, low-power representative state, portrait notice and serial
+regression. Use normal rendering, not only direct `render()` fixtures.
+
+### Step 6: Foundation closure
+
+The foundation source is ready for parallel work only when:
+
+- `main.gd` is a composition root/facade and has no authoritative outcome
+  calculation or P9.1-only rule branch;
+- all mutable values have one owner and snapshot/event schema tests pass;
+- domain tests run without instantiating `main.tscn`;
+- all accepted P9.0R1-R10 behavior remains green at one clean revision;
+- the exact parallel write paths in section 7 exist and compile;
+- PMO reconciles this document with game-design and UX/visual outputs.
+
+Rollback at closure is the last green step revision, not a mixed partial
+extraction. No parallel worker begins from a failing foundation branch.
+
+## 7. Non-Overlapping Parallel Writes
+
+The following is the implementation ownership contract after foundation is
+integrated. Directory ownership includes new files only unless an exact file is
+listed. Moving or renaming another role's file is a write to that file and is
+forbidden.
+
+| Role | Exact writes | Reads/consumes | Forbidden writes |
+|---|---|---|---|
+| Foundation | `runtime/main.gd`, `runtime/domain/p9_1/{contracts,session_state,session_service,battle_fixture}.gd`, `runtime/presentation/{presentation_settings,battle_clock,animation_adapter,audio_adapter,feedback_presenter}.gd`, `runtime/ui/{session_presenter,widgets}.gd`, `runtime/compat/p9_0_root_facade.gd` | Accepted source/contracts/tests | New P9.1 gameplay, test expectations, product behavior |
+| Domain | New files only under `runtime/domain/p9_1/content/` and `runtime/domain/p9_1/rules/` | Foundation domain APIs plus reconciled gameplay contract | `main.gd`; foundation API files; any `Control`, UI, tests or runners |
+| UI | New files only under `runtime/ui/p9_1/` | Snapshot/event schema plus reconciled UX contract | Domain/presentation logic; `main.gd`; shared presenter/widgets; tests/runners |
+| Tests | New files under `runtime/tests/p9_1/` and `runtime/tests/support/p9_1/` | Public domain/presenter contracts and frozen matrix | Existing P9.0 tests; production runtime; shared runner/entry files |
+| Integration | `runtime/main.gd`, exact foundation shared API files when reconciliation requires, shared P9.1 runner/manifest files, `runtime/project.godot` only if the frozen integration contract explicitly requires it | Domain, UI and test commits | Rewriting accepted P9.0 assertions; product expansion |
+
+The integration role is the only role allowed to wire new domain/UI modules
+into the shared facade, resolve schema mismatches, or edit shared runners.
+Integration must not silently absorb one role's duplicated calculation. A
+schema mismatch returns to the earliest producing role or receives an explicit
+reconciled contract amendment before integration.
+
+No parallel role owns `runtime/main.tscn`; the accepted one-root scene needs no
+edit for this architecture. If implementation proves otherwise, PMO must add
+that exact file to integration ownership before work, never let UI and
+integration both edit it.
+
+## 8. Test Architecture After Extraction
+
+### 8.1 Test layers
+
+1. **Pure domain tests** instantiate service/state/fixtures without a scene
+   tree. Cover the six unordered pairs, both adaptations, every reconciled
+   downstream choice, invalid transactions, deterministic events and reset.
+2. **Facade regressions** keep the accepted P9.0 tests unchanged while the
+   facade exists. They prove property/method/node compatibility.
+3. **Presenter contract tests** feed fixed snapshots/events and assert stable
+   controls, available/disabled actions, localized fact rendering and absence
+   of duplicated outcome logic.
+4. **Clock integration tests** drive normal, low-FPS/large-delta, reduced-motion
+   and paused paths and compare the final domain snapshot.
+5. **End-to-end parsed input** uses `Input.parse_input_event` ScreenTouch and
+   ScreenDrag through the complete session with fallback/direct zero.
+6. **Normal-render evidence** covers queue/action feedback, causal decisions
+   and result deltas at small/reference/large landscape, Chinese/English, 130%,
+   reduced motion, mute and low power.
+7. **Strict diagnostics** scan script/parse/resource/import/assertion/ObjectDB
+   and cleanup failures; the terminal marker must be unique.
+
+### 8.2 Contract assertions
+
+Add schema tests that reject:
+
+- mutable arrays/dictionaries leaking from snapshots;
+- UI code importing `battle_fixture.gd` or rule content directly;
+- domain files extending `Node`/`Control` or referencing `SceneTree`, `Input`,
+  `AudioServer`, textures, node paths or viewport size;
+- a successful command with no revision increment, or rejected command with a
+  state/revision change;
+- duplicate `impact_id`, reward or commit events;
+- presenter calculations of Coin/HP/coverage/result facts;
+- source files outside the owning role's write allowlist.
+
+Dependency-direction and write-scope checks may be small repository scripts;
+they must use parsed GDScript metadata where practical, with `rg` guards as a
+bounded additional check rather than claiming a full language parser.
+
+### 8.3 Baseline runner requirement
+
+The test worker shall create one serial runner manifest listing exact scripts,
+expected unique markers, timeout, required viewport/environment and strict log
+policy. It must not select tests by filename glob. The orphan opening-market
+files are separately named and have no effect on the R1-R10 pass claim until a
+future frozen goal reconciles them.
+
+## 9. Invariants
+
+These are mandatory at every green migration step and at P9.1 integration:
+
+1. A successful command is atomic and increases `revision` exactly once.
+2. A rejected command changes no snapshot field, event history, resource,
+   reward, clock or page.
+3. Formation order is derived from selected member identities, never click
+   order, and commits once.
+4. Choice selection is revisable and free; its commit locks once and is the
+   only spend/state-change boundary.
+5. An impact is keyed by encounter + phase + impact ID and commits at most once.
+6. Feedback is the exact semantic event created inside that impact mutation.
+7. Rewards commit only after their declared victory boundary and at most once.
+8. `reset_transient` clears all run and playback state while preserving
+   session-local presentation settings.
+9. Domain output is identical across render FPS, reduced motion, mute, low
+   power and viewport size.
+10. UI enables from `available_actions`, displays domain facts and never
+    predicts or recalculates outcomes.
+11. Chinese and English are formatting over the same semantic facts; locale
+    changes no domain snapshot except the shell-composed settings section.
+12. No path after battle two may use the R10 `later_preview_supports_pair`
+    limitation once P9.1 integration claims all six complete sessions.
+
+## 10. Legacy Adapters and Deletion Criteria
+
+| Legacy path | Why retained | Delete only when |
+|---|---|---|
+| Root `AppPage` and `page` facade | P9.0 tests and captures set/read it | Replacements cover every accepted transition and fixture, preserved tests are migrated in a dedicated reviewed commit, and no source uses it. |
+| Root public state properties | P9.0 tests directly assert/mutate them | Domain snapshot/builder tests plus facade-independent integration tests cover the same facts, and a reference search is empty. |
+| Root transaction wrappers | Existing touch/domain tests call them | All callbacks and tests call the service action map, parsed touch stays green, and reference search is empty. |
+| Root render/animation helpers and sprite refs | Layout/capture/animation tests inspect them | Presenter/animation contract tests and normal-render evidence replace each assertion, with no root references. |
+| Historical `FRONT_SELECTION` / `REAR_SELECTION` | Enum compatibility | No preserved evidence references them and automatic selection regressions pass after removal. |
+| `later_preview_supports_pair()` | R10 honestly stops exceptional pairs after battle two | All six pairs complete five battles with P9.1 matrix and end-to-end evidence; the method and UI boundary copy are then removed together. |
+| Orphan `domain/run_state.gd` and old `tests/p9_1_*` | Separate prior lineage, deletion not owned here | A frozen Goal classifies their product intent and either restores them as a separate module or removes them with independent evidence. |
+
+Deletion is always integration-owned, source-searched, tested and committed
+separately from feature addition. Compatibility aliases do not become a
+permanent alternative API.
+
+## 11. Integration Risks and Responses
+
+| Risk | Earliest detectable boundary | Required response |
+|---|---|---|
+| Two mutable sources of truth in root and state object | Step 1 snapshot/facade assertions | Stop; keep field in one owner or redesign forwarding. Never synchronize copies per frame. |
+| Rewritten tests pass while behavior regresses | Any extraction step | Preserve existing P9.0 assertions; compare exact markers, values, node names and normal rendering before test migration. |
+| Frame timing changes outcomes | Step 3/4 large-delta and headless tests | Outcome must move to named domain impacts; clock only requests them. |
+| Dictionary schema drifts between parallel workers | Parallel compile/schema tests | Reconcile constants/schema before wiring; no UI fallback keys or silent defaults for required fields. |
+| UI duplicates pair/coverage/result logic | Presenter contract/static dependency check | Return to UI role; consume facts and available actions instead. |
+| `main.gd` becomes a second integration battlefield | Parallel write audit | Only integration edits it after foundation; domain/UI/tests remain in exact owned paths. |
+| Legacy opening-market files are included in the wrong pass claim | Step 0 manifest | Quarantine in an explicit runner group and report separately. |
+| Full `DisplayRoot` rebuild loses focus/input or stale references | Step 5 touch/layout/cleanup | Preserve facade refs during extraction; later incremental rendering requires its own frozen behavior-equivalent step. |
+| Snapshot deep copies create low-power cost | Pure benchmark after correctness | Measure first. Optimize snapshot sections/revision caching without giving UI mutable references. |
+| Godot import/class cache makes isolated files appear valid | Foundation closure clean import | Run from clean import/cache evidence and compile every new script through the actual project. |
+| Compatibility layer never disappears | Integration closure audit | Apply deletion criteria and record remaining adapters with owner and follow-up; do not add new facade-only feature APIs. |
+
+## 12. Foundation Handoff Checklist
+
+Before the foundation developer is dispatched, the reconciled contract must
+answer each item with a stable reference:
+
+- final P9.1 screen names and whether `session_result` replaces or extends the
+  historical `THIRD_CYCLE_RESULT` label;
+- stable member IDs and decision IDs supplied by game design;
+- UX-owned new Control names and result fact ordering;
+- exact `facts` and `available_actions` required on each P9.1 screen;
+- low-power semantics that may affect presentation sampling only;
+- the exact accepted P9.0R1-R10 serial runner manifest and orphan-test policy;
+- final shared foundation paths and the three parallel write allowlists;
+- the source revision from which all parallel worktrees branch.
+
+If any item is unresolved, the earliest failed boundary is specification
+reconciliation; runtime extraction must remain frozen.