# 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.