# M15 Runtime Foundation & Shared UI

## Status

- Plan: `M15_RUNTIME_FOUNDATION`
- Status: `COMPLETE`
- 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

```text
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 (`COMPLETE`)

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.

Closure: source `6061414` adds the five foundation primitives and the focused
`ABG_M15_FOUNDATION_OK` test. Godot headless execution passes with strict
diagnostics `0`.

### M15-C — Settings integration pilot (`COMPLETE`)

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

Closure: source `8a8fb33` wraps the validated `ABGEntrySettingsStore` behind
`ABGSettingsService`, injects it through `ABGAppServices`, and records
`ABGScreenContext` for Settings entry/return. The focused
`ABG_M15_SETTINGS_OK` test covers defaults, forwarding, corrupt JSON, v1
migration, caller/return/focus context and stack cleanup; the existing
`ABG_DEV1_SETTINGS_OK` regression remains green.

### M15-D — Focused verification and migration boundary (`COMPLETE`)

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

Closure: source-bound focused attempt `m15-foundation-settings` from source
`b5c78fdd0b349472bca9db2c44725d8240408bb8` passed
`ABG_M15_FOUNDATION_OK`, `ABG_M15_SETTINGS_OK` and `ABG_DEV1_SETTINGS_OK`
exactly once with strict diagnostics `0`, process-group cleanup and workspace
cleanup. The first-cycle audit from the same source passed
`ABG_MVP_FIRST_CYCLE_AUDIT_OK` exactly once with 128 normal `100%` frames,
strict diagnostics `0`, and complete runner cleanup. Its retained evidence is
`/private/tmp/aetherbound-guild-test-evidence/m15-mvp-audit/20260825T022152Z-90588`
with archive SHA-256
`2111605b18dc1c0a02f82e70a5aa05eaed6c80d76759d358757a48d0269d5182`.

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

## Final handoff

M15 is closed. The next page migration must activate a new durable plan and
must consume the shared foundation instead of adding another root-facade or
direct-settings path. Accepted MVP pages, historical Runtime adapters,
`.uid`/`.import` files and `prototype_incremental/` remain unchanged.