From dc78a92ecdb0852d1c37031d1274f027b70ef252 Mon Sep 17 00:00:00 2001 From: gamer147 Date: Tue, 7 Jul 2026 00:17:25 -0400 Subject: [PATCH] =?UTF-8?q?docs(phase-b):=20design=20=E2=80=94=20cross-sce?= =?UTF-8?q?ne=20state=20(persistent=20globals=20+=20runner)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- ...-07-07-phase-b-cross-scene-state-design.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-07-phase-b-cross-scene-state-design.md diff --git a/docs/superpowers/specs/2026-07-07-phase-b-cross-scene-state-design.md b/docs/superpowers/specs/2026-07-07-phase-b-cross-scene-state-design.md new file mode 100644 index 0000000..04afcad --- /dev/null +++ b/docs/superpowers/specs/2026-07-07-phase-b-cross-scene-state-design.md @@ -0,0 +1,105 @@ +# Design: Phase B — Cross-Scene State (persistent globals + a state-carrying runner) + +Status: **approved-by-delegation (owner asleep; autonomous Phase B mandate)** · Date: 2026-07-07 +Related: `docs/remake-architecture-and-roadmap.md` (Phase B), `docs/phase-a-slice-plan.md` +(A2b-Geometry — the state-divergence finding that motivates this), `engine/Age.Engine` +(`Vm/VirtualMachine.cs`), `engine/Age.Cli/Program.cs`. + +## Problem / goal + +Every VM run today is a **single scene in isolation** with an empty global bank. But the session's +biggest finding is that most divergence from the real game — the bg/sprite geometry drift, the 12 +state-gated EMPTY scenes, Lily's form-gated voices — is **state divergence**: the real game carries a +persistent global store across scenes (boot init → scene → scene …), so scenes take branches our +fresh-state VM never reaches. + +The foundational Frida-free step is therefore **cross-scene state**: a persistent global bank that +survives scene boundaries, seedable up front, so we can (a) run a boot script then a scene with its +state, (b) seed known flags (chapter, form) and observe scenes branch correctly, and (c) later drive a +real multi-scene sequence. This is pure bytecode execution — no Frida, no packer, no unsolved +call-script registry (the scene *sequence* is supplied; auto-chaining via SCJUMP is a later slice). + +**Goal:** a reusable `GameSession` in `Age.Engine` that owns a persistent global store and runs scenes +into it, plus an `Age.Cli play` mode that runs a supplied scene sequence carrying state (with optional +seeds) and dumps the combined dialogue. Headless, deterministic, unit-tested. + +## Scope + +**In:** +- `Age.Engine/Vm/GameSession.cs` — persistent `Globals`/`GlobalStrings`; `RunScene(script, host)` seeds + a fresh `VirtualMachine` from session state, runs it, and merges the final state back. Returns a small + result (emitted lines, halt reason, steps). +- Seeding API: `Seed(int addr, long value)` / `SeedString(int addr, string)`. +- `Age.Cli play [0xADDR=VAL ...]` — run a sequence carrying state; print per-scene dialogue + counts + halt, and the combined emitted line count. Reuses `CaptureHost`. +- Unit tests: state persists A→B; SC0000 via `GameSession` is byte-identical to a single run (186 lines); + a seeded global is visible to the scene and changes an observable (branch/emit). + +**Out (later slices):** SCJUMP-driven auto-sequencing, `call-script` id→code resolution, the input/ +hotspot model (interactive/EMPTY scenes), save-file (de)serialization of the store, Godot wiring of +`GameSession`. This slice is the state *substrate*; those consume it. + +## Architecture + +### `Age.Engine/Vm/GameSession.cs` (new) +```csharp +public sealed class GameSession +{ + public Dictionary Globals { get; } = new(); + public Dictionary GlobalStrings { get; } = new(); + + public void Seed(int addr, long value) => Globals[addr] = value; + public void SeedString(int addr, string value)=> GlobalStrings[addr] = value; + + public SceneResult RunScene(Script script, OpcodeTable table, IHost host, VmOptions? o = null) + { + var vm = new VirtualMachine(script, table, host, o); + foreach (var kv in Globals) vm.Globals[kv.Key] = kv.Value; + foreach (var kv in GlobalStrings) vm.GlobalStrings[kv.Key] = kv.Value; + vm.Run(); + // merge final state back (globals are one flat space; last write wins — matches the engine) + foreach (var kv in vm.Globals) Globals[kv.Key] = kv.Value; + foreach (var kv in vm.GlobalStrings) GlobalStrings[kv.Key] = kv.Value; + return new SceneResult(vm.Emitted.ToList(), vm.HaltReason, vm.Steps); + } +} +public sealed record SceneResult(IReadOnlyList<(int Offset, string Text)> Emitted, string? Halt, long Steps); +``` +Seam rule preserved: `GameSession` lives in `Vm`, references only `Model`/`Hosting` (never `Sys4`). The +VM itself is unchanged (its `Globals`/`GlobalStrings` are already public and pre-seedable — the `audio`/ +`gfx` CLI modes already write them before `Run`), so **trace/selftest parity is untouched**. + +### `Age.Cli play` (Program.cs) +`play SC0000.BIN SC0030.BIN 0xa57=1` → build a `GameSession`, apply seeds, `RunScene` each in order +through a `CaptureHost`, print `scene: N lines (halt …)` per scene and the carried global count. Mirrors +the existing `audio`/`gfx` seed-arg parsing. + +## Data flow +``` +seeds ──► GameSession.Globals ──►┐ + ├─ RunScene(A): VM seeded from session → runs → merge back ─► session grows +scene A ──────────────────────►─┘ +scene B ──► RunScene(B): VM seeded from session (now includes A's writes) → runs → merge back +``` + +## Testing / verification +1. **Persistence (synthetic):** script A = `mov (global-int 0x5000) 0x2a; exit`; script B = `show-text` + guarded by `jcc (global-int 0x5000)`… — simplest: A sets `G[0x5000]=42`, then assert + `session.Globals[0x5000]==42` after `RunScene(A)`, and that `RunScene(B)` sees it. Build scripts + in-memory (as `TextureGeometryTests` does) so it's deterministic and needs no corpus. +2. **Parity:** `GameSession.RunScene(SC0000)` emits exactly the 186 offsets of the single-run trace + (`build/vm0-trace.json`) — proves the session wrapper doesn't perturb execution. +3. **Seeding changes behavior:** seed `G[0xa57]=1` (Lily form A) before SC0000 and assert the emitted + set differs from the unseeded run (the form-gated lines now execute) — the headless analogue of the + audio finding, and the first concrete demonstration that state seeding works end-to-end. +4. **CLI smoke:** `Age.Cli play SC0000.BIN` runs and prints a sane summary; engine suite stays green. + +## Risks / open questions +- **Merge semantics:** globals are one flat space; merging the VM's full final map back into the session + (last-write-wins) matches the engine's single global bank. Local frames are per-call and correctly do + NOT persist (they live in the VM, not the session). ✓ +- **Which globals are "state" vs scratch:** we carry *all* of them (the engine does). Transient scratch + registers (e.g. `G[0x62424]`) get overwritten next use — harmless. No filtering needed. +- **Scene sequence source:** supplied by the caller here; SCJUMP-driven sequencing is a later slice and + does not block this substrate. +- **No divergence risk to A1/A2:** the VM is untouched; parity test (2) is the guardrail.