Complete VM dispatcher routing split

docs/PROJECT-STRUCTURE.md

@@ -172,15 +172,17 @@ the interpolation helpers consumed by retained-scene sampling. `engine/Age.Engin
 owns surface/movie transition queues, presentation activity and click-skip logic, diagnostics and dirty-reason
 accounting, and visible retained-scene snapshots.
 
-`engine/Age.Engine/Vm/VirtualMachine.cs` retains VM lifecycle, cross-domain state, and the proven top-level
+`engine/Age.Engine/Vm/VirtualMachine.cs` retains VM execution lifecycle, cross-domain state, and the proven
-opcode dispatcher. Its partial-class companion `engine/Age.Engine/Vm/VirtualMachine.Audio.cs` owns VM audio
+top-level opcode dispatcher; `Step` now contains only label grouping, domain routing, and the unknown-op fallback.
+Its partial-class companion `engine/Age.Engine/Vm/VirtualMachine.Audio.cs` owns VM audio
 state, BGM restart semantics, and the BGM/voice/SFX/mixer opcode handler; `Step` retains the audio labels and
 routes that family into the handler. `engine/Age.Engine/Vm/VirtualMachine.Movie.cs` owns modal/asynchronous/
 positioned movie playback, movie surface metadata/activity queries, and movie-mask transition dispatch; `Step`
-likewise retains and routes the movie labels. `engine/Age.Engine/Vm/VirtualMachine.Surface.cs` owns surface
+likewise retains and routes the movie labels. `engine/Age.Engine/Vm/VirtualMachine.Surface.cs` owns per-script
-allocation/loading, texture binding and sizing, mutable surface fill/copy, render-target control, and transient
+reload-policy reset/configuration, surface allocation/loading, texture binding and sizing, mutable surface
-surface release; its labels remain at their existing dispatcher positions around the retained numeric-glyph and
+fill/copy, render-target control, and individual/transient surface release; its labels remain at their existing
-object cases. `engine/Age.Engine/Vm/VirtualMachine.RetainedObjects.cs` owns retained-object registry queries,
+dispatcher positions around the retained numeric-glyph and object cases.
+`engine/Age.Engine/Vm/VirtualMachine.RetainedObjects.cs` owns retained-object registry queries,
 default-slot and geometry mutation, direct and range transforms, clone, and erase dispatch; animation, surface,
 ADV-binding, and presentation labels remain in their respective dispatcher groups.
 `engine/Age.Engine/Vm/VirtualMachine.Animation.cs` owns retained spritesheet and color channels, timed and cyclic
@@ -209,8 +211,9 @@ and native-style random-modulo dispatch; shared storage/address helpers remain i
 `engine/Age.Engine/Vm/VirtualMachine.ControlFlow.cs` owns local jumps/calls/returns, value-switch construction,
 ADV coroutine handler save/yield/resume, and bounded labeled-yield dispatch; process/root exit and cross-script
 lifecycle are routed separately. `engine/Age.Engine/Vm/VirtualMachine.ScriptLifecycle.cs` owns process/frame/root
-exit, ordinary cross-script calls, mounted append autoruns, and preloaded script-slot load/call dispatch; frame
+exit, native run-state compatibility, initial-root-run query, ordinary cross-script calls, mounted append autoruns,
-execution, script-provider access, and shared lifecycle state remain in `VirtualMachine.cs`.
+and preloaded script-slot load/call dispatch; frame execution, script-provider access, and shared lifecycle state
+remain in `VirtualMachine.cs`.
 `engine/Age.Engine/Vm/VirtualMachine.Values.cs` owns integer arithmetic, bitwise and comparison operations,
 string comparison/concatenation/conversion/move, native byte-length and CP932 operations, and the host-backed
 fullwidth string editor; shared operand storage, addressing, and native-string encoding remain in the coordinator.

docs/remake-architecture-and-roadmap.md

@@ -741,6 +741,13 @@ do not mix mechanical moves with semantic changes.
    initialization, public menu-state accessors, and host state remain centralized. Runtime validation remains
    green.
 
+   The nineteenth bounded `VirtualMachine.Step` routing closeout moved the final five recognized inline bodies:
+   script-entry surface-policy reset, surface-persistence flags, individual surface release, native run-state
+   compatibility, and initial-root-run query. They now route through the existing guarded surface and
+   script-lifecycle handlers. `Step` contains only opcode-label grouping, domain-handler routing, and its proven
+   unknown-op trace/fallback; the planned behavior-neutral physical decomposition is complete. Runtime validation
+   remains green.
+
    **Gate:** no externally visible behavior or command changes; generated artifacts are byte-identical where
    deterministic, and the corresponding engine, Python, Godot, and corpus validations remain green after
    each domain move.
@@ -1110,13 +1117,9 @@ layer's rendering diverges from ADV; save layout.
 ---
 
 ## 8. Immediate next step
-Continue step 2 of the **codebase consolidation** maintenance slice: behavior-neutral physical splits backed
+Begin step 3 of the **codebase consolidation** maintenance slice: clarify runtime contracts without changing
-by the tracked launcher and layered validation driver. With the planned `Main`, `GodotAdvHost`, and `GfxState`
+behavior or the aggregate host accepted by the VM. Start with a bounded interface-only slice that introduces
-domains isolated and the audio, movie, surface/texture, retained-object, animation, presentation, ADV-text,
+diagnostic and lifecycle host contracts beneath `IHost`, preserving current default implementations and existing
-text-history, ADV-service, input, timing, persistence, and memory/collection `VirtualMachine.Step` families routed
+host classes before separating the larger ADV, graphics, audio, movie, and input surfaces.
-through domain handlers, with control-flow/coroutine, process/root-exit/cross-script lifecycle, value,
-diagnostic, and runtime-setting dispatch now isolated as well, route the four remaining recognized opcode bodies
-for script entry/root state and surface reload policy into their existing domain handlers, leaving `Step` as the
-proven dispatcher and unknown-op fallback without changing public types, commands, and generated output.
 Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does
 not replace Phase B gameplay validation or the open cross-platform gates.

engine/Age.Engine/Vm/VirtualMachine.ScriptLifecycle.cs

@@ -9,6 +9,11 @@ public sealed partial class VirtualMachine
     {
         switch (label)
         {
+            case "u00415880":           // 0xd9 / semantics: clear-run-state-0x1000
+                return pc + 1;
+            case "get-initial-root-run": // 0x130 (out)
+                Write(a[0], _initialRootRun ? 1 : 0);
+                return pc + 1;
             case "throw-exit-request":
                 if (_o.IgnoreExitRequests) return pc + 1;
                 // Native op 0x1 throws Command_Exit_Exception through callbacks and nested script

engine/Age.Engine/Vm/VirtualMachine.Surface.cs

@@ -9,6 +9,12 @@ public sealed partial class VirtualMachine
     {
         switch (label)
         {
+            case "script-entry":
+                Gfx.ClearSurfaceReloadPolicies();
+                return pc + 1;
+            case "set-surface-persistence-flags": // 0x258 (slot)(flags): bit 0 = numbered-load reload
+                Gfx.SetSurfaceReloadOnRestore(unchecked((int)Read(a[0])), (Read(a[1]) & 1) != 0);
+                return pc + 1;
             case "create-texture":   // 0x1f8 (slot)(w)(h) — allocate a blank surface at the slot
                 _host.ReleaseSurface((int)Read(a[0]));
                 Gfx.CreateSurface((int)Read(a[0]));
@@ -68,6 +74,10 @@ public sealed partial class VirtualMachine
                 Gfx.SelectRenderTarget(Read(a[0])); return pc + 1;
             case "clear-render-target": // 0x20e: clear color to black and depth to one
                 _host.ClearRenderTarget(Gfx.CurrentRenderTargetSlot); return pc + 1;
+            case "gfx-elem-release":    // 0x1fa (surface slot)
+                _host.ReleaseSurface((int)Read(a[0]));
+                Gfx.ClearSurface((int)Read(a[0]));
+                return pc + 1;
             case "release-transient-surfaces": // 0x23d: native fixed range [42,1000)
                 Gfx.ReleaseSurfaceRange(42, 1000 - 42);
                 _host.ReleaseSurfaceRange(42, 1000 - 42); return pc + 1;

engine/Age.Engine/Vm/VirtualMachine.cs

@@ -1208,10 +1208,8 @@ public sealed partial class VirtualMachine
         switch (label)
         {
             case "script-entry":
-                Gfx.ClearSurfaceReloadPolicies(); return pc + 1;
             case "set-surface-persistence-flags": // 0x258 (slot)(flags): bit 0 = numbered-load reload
-                Gfx.SetSurfaceReloadOnRestore(unchecked((int)Read(a[0])), (Read(a[1]) & 1) != 0);
+                return StepSurface(label, a, pc);
-                return pc + 1;
             case "add":
             case "sub":
             case "mul":
@@ -1511,10 +1509,8 @@ public sealed partial class VirtualMachine
             case "set-audio-route-enabled":
                 return StepAudio(label, a, pc);
             case "u00415880":           // 0xd9 / semantics: clear-run-state-0x1000
-                return pc + 1;
             case "get-initial-root-run": // 0x130 (out)
-                Write(a[0], _initialRootRun ? 1 : 0);
+                return StepScriptLifecycle(label, a, pc);
-                return pc + 1;
             case "play-modal-movie-to-surface":
             case "u004221A0":
             case "play-movie-to-surface":
@@ -1568,7 +1564,7 @@ public sealed partial class VirtualMachine
             case "gfx-elem-erase":
                 return StepRetainedObject(label, a, pc);
             case "gfx-elem-release":    // 0x1fa (surface slot)
-                _host.ReleaseSurface((int)Read(a[0])); Gfx.ClearSurface((int)Read(a[0])); return pc + 1;
+                return StepSurface(label, a, pc);
             case "clone-gfx-object":
                 return StepRetainedObject(label, a, pc);
             case "gfx-blit-color":