openup: EA model preparation (COD) - checklist, scripts, realizations intermediate

Per design-wi-2-architecture-cleanup.md §11.b/c: keyfob-station pipeline
studied (add-wi19-uc11.ps1, export-model-json.ps1). Platform gap: EA COM
pipeline is Windows-only; this session ran on Linux (no EABase.eapx found,
no pwsh) - .eapx skeleton NOT committed, documented in model/README.md
with the two path options. Landed:
- docs/openup/model/BUILD-CHECKLIST.md: full EA-session checklist
  (packages, 3 actors, 12 UCs with scenarios, 13 associations, 12
  realization packages / 36 elements) derived from use-case-model.md +
  uc-realization-mapping.md
- docs/openup/model/README.md: platform note, status, drift rule
- docs/openup/model/exports/uc-realizations.json: generated from mapping
  §2 via scripts/openup/markdown-to-json.py (tested locally)
- scripts/openup/build-model.ps1, export-model.ps1: adapted from keyfob
  patterns, Windows-gated (human gate per design §11.d)
- scripts/openup/markdown-to-json.py: local markdown -> JSON transform

docs/openup/model/BUILD-CHECKLIST.md

@@ -0,0 +1,203 @@
+# Skara Brae — EA Model Build Checklist (WI-2)
+
+Version 1.0 (2026-10-03) · Prepared by COD per `design-wi-2-architecture-cleanup.md` §11.b.4.
+Sources (authoritative, do not deviate): `docs/openup/requirements/use-case-model.md`,
+`docs/openup/analysis-design/uc-realization-mapping.md` (§1 tree, §2 realization table),
+`docs/openup/requirements/supplementary-specifications.md`, design note §3 (boundary rules).
+Drift rule: markdown and model must agree; a mismatch is a defect fixed in the same cycle.
+
+This checklist is written to be clicked through in EA **or** executed via
+`scripts/openup/build-model.ps1` (then verified below). The per-discipline element lists
+are complete: nothing outside them belongs in the WI-2 model.
+
+---
+
+## 0. Prerequisites (Windows machine — see model/README.md for why not Linux)
+
+1. skara-brae-common checked out (branch `wi-2-openup-docs` or later).
+2. EA installed and licensed. Copy the EA installation's empty-model template to the
+   model home:
+   `C:\Program Files\Sparx Systems\EA\EABase.eapx` → `docs/openup/model/skara-brae.eapx`
+   (exact install path may differ; the file is the standard empty `.eapx` template.
+   Do **not** derive the skeleton from keyfob-station's model — it carries keyfob content).
+3. PowerShell 5.1+ (built into Windows) for the script path.
+
+## 1. Model root
+
+- Rename the default model root to **`Skara Brae`** (keyfob equivalent: single model root).
+
+---
+
+## 2. Requirements discipline
+
+### 2.1 Package `Requirements`
+
+Create package **`Requirements`** directly under the model root.
+
+### 2.2 Package `Requirements / Vision`
+
+- Notes: purpose statement source = `docs/openup/requirements/vision.md` (the markdown is
+  the human-facing source; the model carries the product purpose in the package notes and
+  links, not a full copy).
+
+### 2.3 Package `Requirements / Use Case Model`
+
+**Actors (exactly 3)** — type `Actor`, notes verbatim from the Actors table:
+
+| Actor | Notes |
+|---|---|
+| `Player` | Authenticated user owning one or more characters (JWT role `player`). |
+| `Administrator` | Player with elevated rights (`role = admin`); may view any user's and any character's resources read-only. |
+| `Guest` | Unauthenticated caller; only register/login are open. |
+
+**Use cases (exactly 12)** — type `UseCase`, names verbatim:
+
+`UC-01 Register Account`, `UC-02 Authenticate`, `UC-03 Manage Characters`,
+`UC-04 Browse Game Catalogue`, `UC-05 Train Stat`, `UC-06 Manage Equipment`,
+`UC-07 Trade at Shop`, `UC-08 Run Adventure`, `UC-09 Heal at Temple`,
+`UC-10 Practice Bard Song`, `UC-11 Study Magic`, `UC-12 Level Up at Review Board`.
+
+Element notes: the UC's precondition line(s) verbatim from `use-case-model.md`; plus:
+- UC-05 note appends: *includes Regenerate Resources.*
+- UC-08 note appends: *includes Regenerate Resources, Resolve Combat. Exception: encounter
+  references an unknown enemy → 500 (post WI-2; previously a panic). WI-2 design driver
+  (`sb_core::adventure` extraction).*
+- Include targets are **sub-flows, not use case elements** (only 12 UCs exist) — model the
+  includes in the notes, **not** as `«include»` connectors.
+
+**Associations (exactly 13)** — type `Association`, Actor → UseCase:
+
+| Actor | Use cases |
+|---|---|
+| `Guest` | UC-01, UC-02 |
+| `Player` | UC-03, UC-04, UC-05, UC-06, UC-07, UC-08, UC-09, UC-10, UC-11, UC-12 |
+| `Administrator` | UC-03 (read-only) |
+
+**Scenarios** — stored on each use case (`Scenarios` collection), types are EA's
+`Basic Path` / `Alternate` / `Exception`. Naming and structuring rules used below
+(also implemented in `build-model.ps1`):
+- Markdown "Main success scenario" → scenario **Main Success Scenario** (`Basic Path`);
+  its numbered list items become ordered **steps**, each step's **Actor** = the leading
+  grammatical subject of the step text (`Player`/`Guest` → that actor; otherwise `System`).
+- Markdown "**Scenario (x):**" block → scenario named **x** (`Alternate`); prose text goes
+  into the scenario notes verbatim.
+- Markdown "**Alternate flows:**" prose → one scenario **Alternate flows** (`Alternate`),
+  prose verbatim in notes.
+- Markdown "**Exception:**" prose → scenario **Exception** (`Exception`), prose verbatim.
+- Precondition text rides on the scenario notes of the Main Success Scenario.
+- UC-11 has no labeled main scenario in the markdown; its first listed scenario
+  (view spellbook) serves as the Basic Path, the remaining "Scenario (x)" blocks as
+  `Alternate`.
+- Parenthetical actor remarks on a step text (e.g. UC-03 step 1 "(Admin may act for any
+  user)") move to the scenario notes to keep the step actionable; the wording is kept.
+
+| UC | Scenario (type) | Steps (Actor: text) / Notes |
+|---|---|---|
+| UC-01 | Main Success Scenario (Basic Path) | Guest: Guest submits name (3–32 chars) and password (≥ 6 chars). · System: System verifies the name is unused → 409 CONFLICT if taken. · System: System hashes the password (argon2), assigns the `player` role and the next id, persists the user. · System: System issues a JWT (HS256, `player` role) and returns `{token, user_id, name, role}`. |
+| UC-01 | Alternate flows (Alternate) | Notes: name length invalid → 400; password too short → 400; name taken → 409; hashing/token failure → 500. |
+| UC-02 | Main Success Scenario (Basic Path) | Guest: Guest submits name and password. · System: System finds the user (401 if unknown) and verifies the password hash (401 on mismatch). · System: System issues a JWT carrying the user's real role (`admin`/`player`) and returns `{token, user_id, name, role}`. |
+| UC-02 | Alternate flows (Alternate) | Notes: unknown name or wrong password → 401 UNAUTHORIZED; token creation failure → 500. |
+| UC-03 | Main Success Scenario (create) (Basic Path) | Notes: Admin may act for any user. · Player: Player submits character name, race, class for their user id. · System: System validates the target user exists (404) and the trimmed name is 1–32 chars (400). · System: System rolls stats (d6+5 base 6–16 per stat ± race modifiers), computes max HP/energy/nerve from class, grants starting gold (50) and level-1 class spells to casters. · System: System assigns the next character id, stores and persists the character; returns it fully. |
+| UC-03 | list/view (Alternate) | Notes: Player lists their characters (Admin: any user's); the system applies Regenerate Resources to each returned character and returns them. Viewing one character applies regen then returns it. |
+| UC-03 | Alternate flows (Alternate) | Notes: foreign user/character without admin role → 403 FORBIDDEN; user/character not found → 404; invalid name → 400. |
+| UC-04 | Main Success Scenario (Basic Path) | Player: Player requests the catalogue: races, classes, items (optional type/quality/slot filters), enemies, or adventure zones. · System: System returns static game data loaded from `skara-brae-common` JSON (class info is enriched with `is_caster`). |
+| UC-04 | Alternate flows (Alternate) | Notes: single item by unknown id → 404; filters may return an empty list (not an error). |
+| UC-05 | Main Success Scenario (Basic Path) | Notes: Precondition: character exists and caller may act on it. · Player: Player selects a training ground (strength / dexterity / constitution / intelligence / luck) and submits the stat name. · System: System applies Regenerate Resources. · System: System checks energy ≥ 1 and gold ≥ training cost (cost grows ~1.3× per 10 stat points). · System: System deducts 1 energy and the gold cost, increments the stat; constitution training recomputes max HP (current HP clamped). · System: System persists and returns `{success, message, character}`. |
+| UC-05 | Alternate flows (Alternate) | Notes: foreign character → 403; character not found → 404; not enough energy → 422; not enough gold → 422; unknown stat name → 400. |
+| UC-06 | Main Success Scenario (equip) (Basic Path) | Player: Player submits an item id from their inventory. · System: System moves the item from inventory to its slot; a previously equipped item in that slot returns to inventory. · System: System persists and returns the updated character. |
+| UC-06 | unequip (Alternate) | Notes: Player submits a slot name; the system moves the equipped item back to inventory. |
+| UC-06 | Alternate flows (Alternate) | Notes: foreign character → 403; character/item not found → 404; item not in inventory → 400; nothing equipped in slot → 400. |
+| UC-07 | Main Success Scenario (buy) (Basic Path) | Player: Player views the shop: always-stocked items plus rotating stock (with quantities) alongside their inventory. · Player: Player submits `buy` + item id. · System: System checks gold ≥ price (422), and for non-always-in-stock items decrements the limited stock (410 GONE if 0). · System: System deducts gold, adds the item to inventory, persists character and stock; returns `{success, message, gold}`. |
+| UC-07 | sell (Alternate) | Notes: Player submits `sell` + item id; system removes the first matching inventory item, pays half the item value, increments shop stock for non-permanent items. |
+| UC-07 | Alternate flows (Alternate) | Notes: unknown action or item not owned (sell) → 400; item not found → 404; insufficient gold → 422; stock exhausted → 410. |
+| UC-08 | Main Success Scenario (Basic Path) | Notes: Precondition: character exists and caller may act on it. · Player: Player requests an adventure for a zone (default `skara_brae_streets`). · System: System validates the zone (404) and applies Regenerate Resources. · System: System refuses incapacitated characters (HP ≤ 0 → 400) and characters with nerve below the zone cost (422); otherwise deducts the nerve cost. · System: System draws one enemy from the zone's weighted encounter table. · System: System resolves turn-based combat: open-ended d100 attack rolls, OB vs DB, RoleMaster crit tables with level-gap damage caps, active bard song effects, active spell damage/heal per round. · System: On player victory: XP and gold per the enemy definition, character HP set to the last round's defender HP, and loot dropped per-item chance rolls (only items existing in the catalogue). · System: On defeat: character HP set to 0; no rewards. · System: Spell-point upkeep is charged whenever a spell was active, win or lose. · System: System persists the character and returns `{zone, enemy, combat_log, loot}` (loot = item display names). |
+| UC-08 | Alternate flows (Alternate) | Notes: foreign character → 403; character/zone not found → 404; incapacitated → 400; insufficient nerve → 422. |
+| UC-08 | Exception (Exception) | Notes: encounter references an unknown enemy (data error) → 500 (post WI-2; previously a panic). |
+| UC-09 | Main Success Scenario (Basic Path) | Player: Player requests healing, optionally `partial`. · System: System computes missing HP; full heals all, partial heals half (rounded up); cost = amount healed, minimum 1 gold. · System: System checks gold (422), deducts it, restores HP, persists; returns `{hp, max_hp, gold, healed: true}`. |
+| UC-09 | Alternate flows (Alternate) | Notes: foreign character → 403; not found → 404; already at full HP → 400; insufficient gold → 422. |
+| UC-10 | Main Success Scenario (Basic Path) | Notes: Precondition: character class is Bard. · Player: Player views available songs (level-gated, with combat effect descriptions) and the active song. · Player: Player submits a song id; system validates level requirement (422) and sets it active; returns `{success, message, active_song}`. |
+| UC-10 | clear (Alternate) | Notes: submitting no song id clears the active song. |
+| UC-10 | Alternate flows (Alternate) | Notes: non-Bard → 403; unknown song → 404; level too low → 422; foreign character → 403; not found → 404. |
+| UC-11 | Main Success Scenario (view spellbook) (Basic Path) | Notes: Precondition: character belongs to a caster class (Mage→magician, Wizard, Conjurer, Sorcerer). Spell level = (character level / 3) + 1 — uncapped by code (level 100 → spell level 34); learn requests are validated to 1–7. · Player: Player requests their spellbook: caster class, current spell level, spell points, spells up to the achievable level (each marked known), and the learn-cost table for levels 2–7. |
+| UC-11 | learn spell level (Alternate) | Player: Player submits a spell level (1–7). · System: System validates caster class (403), level range (400), level not above the character's current spell level (422), gold ≥ learn cost (422), and that new spells exist (400). · System: System deducts gold, adds all unknown spell ids of that level, recomputes and refills max spell points; returns `{learned_count, spell_points, max_spell_points, gold}`. |
+| UC-11 | activate/clear active spell (Alternate) | Player: Player submits a spell id (or empty to clear). · System: System validates the spell is known (403), exists (404), and spell points suffice (422); deducts the spell's points and sets it active; returns `{active_spell, spell_points}`. |
+| UC-12 | Main Success Scenario (Basic Path) | Player: Player requests a level-up. · System: System validates: below max level 100, XP ≥ 18·100·(level)² for the next level (i.e. `xp_for_level(next)`), gold ≥ 500·next level. · System: System deducts the gold cost, increments the level, recomputes and fully restores HP/energy/nerve and max spell points; persists; returns `{success, message, character}`. |
+| UC-12 | Alternate flows (Alternate) | Notes: all of already at max level; not enough XP; not enough gold → 422. Foreign character → 403; not found → 404. |
+
+**Diagram** `Skara Brae Use Case Overview` (type `UseCase`): place all 3 actors (left
+column) and all 12 use cases (right grid).
+
+### 2.4 Package `Requirements / Supplementary Specifications`
+
+- One child element per top-level section of `requirements/supplementary-specifications.md`,
+  type `Requirement`, name = `SS-<n> <section title>` with the section's content in notes:
+  `1. Performance / Scalability`, `2. Reliability / Correctness`,
+  `3. Quality Gates (per-commit acceptance)`, `4. Data`, `5. Security`,
+  `6. Constraints`, `7. Usability / API`.
+- `Trace` connectors from each `SS-n` element to the use cases the section names
+  (the spec text cites the UCs; when it names none, leave untraced rather than guessing).
+
+---
+
+## 3. Analysis-Design discipline
+
+### 3.1 Package `Analysis-Design`
+
+Create package **`Analysis-Design`** under the model root (mapping §1 name — note:
+keyfob uses `Analysis & Design`; here the mapping document says `Analysis-Design` —
+follow the mapping).
+
+### 3.2 Package `Analysis-Design / Architecture Overview`
+
+- Notes: the dependency rule verbatim from `uc-realization-mapping.md` §2
+  ("all controllers/entities above live in `sb-core`/`sb-shared` …; the single current
+  violations (ShopService, HealingService, parts of MagicService in sb-api) are recorded
+  as debt … stale docs are defects") + design note §3 boundary rules.
+- Three cross-cutting elements (type `Class`, notes from the mapping's cross-cutting
+  paragraph):
+  1. `DomainError` — notes: `sb-core::error::DomainError` + `sb-api::routes::domain_status`
+     (status mapping table, design note §4.1) realize the error paths of UC-05/06/08/12.
+  2. `Constants` — notes: `sb-core::constants` realizes NFR "no magic numbers".
+  3. `Responses` — notes: `sb-api::routes::responses` realizes NFR-19 (wire-format freeze).
+
+### 3.3 Twelve realization packages
+
+For **each** entry in `docs/openup/model/exports/uc-realizations.json`
+(generated from mapping §2 — 12 packages, 36 elements):
+
+1. Package `UC-<NN> Realization` under `Analysis-Design`.
+2. Inside it, one `Collaboration` element named like the package, with a `Realization`
+   connector (Collaboration → the use case element in `Requirements / Use Case Model`).
+3. Inside it, one `Class` element per mapping row:
+   - Name = analysis class (e.g. `AdventureService`).
+   - Stereotype = `controller` / `entity` / `boundary` (mapping §2 column).
+   - Notes = the mapping's *Design element* cell verbatim, plus the *Notes* cell
+     (e.g. `` `sb-core::adventure::run_adventure` (**new, WI-2**) + `services::pick_enemy`
+     → `Result` (WI-2) — takes injected rng; `DomainError` (WI-2)``).
+4. One class diagram per realization package (name = package name), all its classes placed.
+
+Element counts for verification: UC-01:3, UC-02:2, UC-03:4, UC-04:2, UC-05:3, UC-06:3,
+UC-07:3, UC-08:5, UC-09:2, UC-10:3, UC-11:3, UC-12:3 — total 36.
+
+---
+
+## 4. Verification (design §11.d)
+
+1. Model opens clean (no missing-package errors).
+2. `Requirements → Use Case Model` shows exactly 3 actors + 12 use cases; every UC carries
+   its Main Success Scenario plus the alternates/exceptions from the table above, with
+   per-step actors.
+3. Spot-check two scenarios against `requirements/use-case-model.md` (recommended: UC-08
+   MSS — 9 steps, and UC-11 learn spell level — 3 steps).
+4. 12 `UC-N Realization` packages exist under `Analysis-Design` with the element counts
+   above; spot-check the UC-08 realization table against `uc-realization-mapping.md` §2.
+5. Association count is 13; there are no `«include»` connectors (includes live in UC notes).
+
+## 5. Export + commit (design §11.d.4–5)
+
+1. Run `scripts/openup/export-model.ps1` → regenerates
+   `docs/openup/model/exports/use-case-model.json`, `uc-realizations.json` and an XMI
+   backup; confirm the diff is expected (`uc-realizations.json` must be unchanged in
+   content — it was generated from the mapping markdown).
+2. Save the model; commit `.eapx` + `exports/` + `scripts/openup/` together as one commit
+   `openup: EA model WI-2 baseline` in **skara-brae-common**.