aetherbound-guild/docs/plans/M15_RUNTIME_FOUNDATION.md

M15 Runtime Foundation & Shared UI

Status

• Plan: M15_RUNTIME_FOUNDATION
• Status: IN_PROGRESS
• Activated: 2026-08-25
• Baseline: 0d7dcce (MVP_FIRST_CYCLE_COMPLETE, repository cleanup closed)
• Owner authorization: explicit instruction to begin the runtime architecture refactor and establish shared game-wide services/components.

Objective

Create the smallest reusable Runtime Foundation that can support future pages without forcing every page through the current main.gd / entry_shell.gd coupling. The first stopping point is an additive, tested foundation and a Settings integration boundary; the accepted MVP player flow must remain behaviorally unchanged.

Player/System Stopping Point

At the end of this plan's first boundary:

• the existing first-cycle route still launches and completes unchanged;
• settings data has one explicit service/repository boundary;
• shared UI primitives have no dependency on facade, current_screen, or page-specific domain state;
• a screen-stack/route context can represent the caller and return focus for Settings without copying settings logic into every page;
• the new foundation is available for the next page migration, but accepted pages are not mass-rewritten in this milestone.

Architecture Contract

Dependency direction

AppRoot / FlowRouter
  -> Page Controllers and Page Views
  -> Application Commands / Use Cases
  -> Domain Services
  -> Repositories / persistence

Page Views -> Shared UI primitives
Shared UI primitives -X-> facade, current_screen, domain services, Save files
Domain Services -X-> Control, Label, TextureRect, page nodes

Shared ownership classes

1. Global services: Settings, localization, audio, input/focus, save and screen navigation. One owner and one public boundary.
2. Shared UI primitives: tokens, theme, button states, rails, notices, dialogs and common icons. They receive view data and emit user intent.
3. Page patterns: optional shells such as a settings workspace or action dock. They may be configured by a page context, but do not own game rules.
4. Page-specific composition: world art, battle field, market board, risk relic and other authored layouts remain owned by their page module.

Ordered Steps

M15-A — Foundation contract and inventory (COMPLETE)

• Record the baseline, forbidden scope and ownership rules in this plan.
• Inventory current shared candidates (entry_chrome.gd, settings_store.gd, localization/font/assets and screen-return branches).
• Add the checkpoint pointer to this plan before product code changes.

Acceptance:

• this plan is the only active implementation plan;
• the current MVP and historical adapters are explicitly frozen;
• no .uid, .import, cache or prototype_incremental/ cleanup is included.

M15-B — Additive foundation types (IN_PROGRESS)

Add only the minimum new code under runtime/foundation/ and runtime/ui/shared/:

• app_services.gd — explicit service bundle, no global page lookups;
• screen_context.gd — caller/return-route/focus context;
• ui_tokens.gd — shared visual and layout constants;
• shared_button.gd — semantic button state/variant boundary;
• screen_stack.gd — route/overlay stack contract without replacing the current entry flow yet.

The additive layer must compile independently and have focused unit checks.

M15-C — Settings integration pilot (PENDING)

• Wrap the existing validated ABGEntrySettingsStore behind a foundation SettingsService boundary without changing the JSON schema or migration behavior.
• Pass a ScreenContext to Settings entry/return paths.
• Keep the existing Settings visuals and semantics until a later page-specific reconstruction step; this is an ownership refactor, not a visual redesign.

Acceptance:

• defaults, v1 migration, validation, atomic save and corrupt-file rejection remain covered;
• Title/Guild/Battle callers return to the correct screen and focus context;
• no page writes the settings file directly.

M15-D — Focused verification and migration boundary (PENDING)

• Run foundation-focused tests and the existing DEV-1 settings/entry checks.
• Run a normal 100% launch/settings/return smoke path at the current required fixtures; 130% remains non-blocking for this milestone.
• Run the MVP first-cycle audit to prove no route regression.
• Record the migration boundary and commit the smallest focused change.

Frozen Scope

• No mass rewrite of entry_shell.gd or main.gd.
• No changes to Company, Contract, Battle, reward, recovery or Save-v11 gameplay semantics.
• No new page visual redesign or asset generation.
• No iOS/export/package/signing work.
• No deletion of historical runtime, .uid, .import or provenance files.

Required Evidence

• Godot parse/import diagnostics: strict zero.
• Focused foundation tests and settings regression marker.
• Normal-render settings open/apply/discard/return evidence.
• Existing ABG_MVP_FIRST_CYCLE_AUDIT_OK remains green.
• Focused commit pushed before activating the next step.

Issue Register

• M15-ISSUE-01 — current entry_shell.gd owns both page composition and settings return logic. Resolved only when Settings has an explicit context boundary; visual extraction remains a later step.
• M15-ISSUE-02 — entry_chrome.gd contains multiple visual families in one class. It is retained as provenance/compatibility until shared variants are extracted and individually verified.

Commit Boundaries

• M15-A: plan/checkpoint activation commit.
• M15-B: additive foundation compile/test commit.
• M15-C: Settings integration commit.
• M15-D: focused evidence and closure commit.

Each boundary must pass its focused checks before the next step becomes active.