OpenMaidEngine/docs/superpowers/specs/2026-07-08-frame-stepped-vm-design.md

Frame-stepped VM — design spec

• Date: 2026-07-08
• Status: design (awaiting review → implementation plan)
• Area: Age.Engine VM/host seam + Godot frontend
• Related RE: docs/engine-re.md — "Frame cadence — the interpreter tick" + "Frame cadence — live measurement"; docs/phase-a-slice-plan.md — "opening speed-through / engine-cadence"

Problem

The SC0000 opening visibly speeds through in our Godot port. Root cause (confirmed): our VM runs on a free-running background thread (Task.Run(() => vm.Run()) in godot/Main.cs) with no binding to real time. Only WaitForInput and Sleep pause it; the main-thread compositor samples GfxState at ~60 fps. So the VM executes a page's opcodes — and any auto-playing stretch — in microseconds, and the compositor only catches the final state. Distinct visible states that aren't separated by a sleep/wait collapse.

The native engine is cooperative and rate-limited: the interpreter advances a bounded number of opcodes per main-loop iteration; visible state therefore changes over real wall-clock time. Our fix must give the VM the same bounded wall-clock execution rate.

Live measurement (Frida, 2026-07-08 — the basis for the mechanism)

Read-only / import-only instrumentation of the running game (tools/frida/probe_frame_cadence.py, probe_present.py; see docs/engine-re.md "Frame cadence — live measurement"):

• Execution is rate-limited, not free-running. Active interpreter rate ≈ 1,788 operand-fetches/sec (peak ~5,796) in normal play — orders of magnitude below an unthrottled interpreter, so the engine is pacing itself.
• Fast-forward (Ctrl) scales the rate ~4× (≈7,738/sec avg, peak ~15,572), gated by the engine's own skip bit flags & 0x8000000. It runs more ops per unit time, it does not skip content.
• Rendering is Direct3D 9, uncapped. ddraw.dll is not loaded; the game renders via d3d9.dll. IDirect3DDevice9::Present fires ~1,908/sec (no vsync), BeginScene/EndScene never fire → it's a 2D StretchRect-style compositor. So there is no fixed display-frame cadence to match; Present rate ≈ op rate (~1 op per present). The meaningful pacing quantity is the wall-clock op rate, not a per-display-frame budget.

Correction this supersedes: an earlier draft of this spec used present (op 0x20c) as the frame boundary. Measurement killed that — present occurs only 7× statically / ~2× per opening run in our bytecode path, and the native present is uncapped anyway. The mechanism is now a wall-clock op-rate throttle.

Goals

1. The VM advances at a bounded wall-clock execution rate (~1,800 ops/sec target, tunable) so visible state changes over real time instead of instantly.
2. Keep the host behind IHost and the VM engine-agnostic — pacing lives at the seam + in the Godot host.
3. Preserve byte-identical headless parity (Steps / emitted lines / halt reasons) across all non-Godot hosts and the existing oracles (sweep, --selftest, engine tests).
4. Route all timing (the throttle, sleep, the anim tween) through one host-owned clock so a future speed multiplier scales everything coherently.

Non-goals (YAGNI)

• The Ctrl key / speed multiplier is NOT wired. Build the single-clock seam so the ~4× multiplier is a trivial later addition; no key handler, no multiplier value now. When added it must be ADV-mode-scoped (the native governor does not speed up gameplay/menus), so no global-speed assumption.
• No present/0x20c gating (rare + native present is uncapped), no transitions/tweens for CG pacing (CGs hard-swap; back-to-back loads are layers that correctly composite into one image), no pull-based VM rewrite (background thread stays), no automated pacing assertion (validated by the user on the build).

Design

Driving model (approach A: background thread + host-timed throttle)

The VM keeps its background thread and its recursive Run/RunFrame/Step unchanged. The only VM change is one host call per executed opcode; all pacing policy lives in the Godot host, mirroring the existing WaitForInput/Sleep suspend pattern (VM thread blocks on a host primitive; main-thread _Process releases it).

Interface change (IHost)

Add one method:

void FrameYield();   // called by the VM after each executed opcode; host paces / no-ops

Sleep(long) keeps its signature (only its Godot body changes to use the host clock). present-frame (0x20c) stays a no-op — it is NOT a gate. No other IHost changes.

VM change

In RunFrame, after each Step, call _host.FrameYield(). That is the whole VM change — the VM does not know the budget, the rate, or the multiplier; it just offers a yield point per opcode. (If per-op virtual dispatch shows up in headless profiling, batch to every K ops — parity is unaffected either way.)

Host-owned scalable clock + op-budget throttle (Godot)

The Godot host owns a single FrameClock (a pure, Godot-independent class in Age.Engine/Hosting, so it is unit-testable and off the Vm seam): monotonic virtual ms + a Speed factor (default 1.0; the future Ctrl hook). Advance(realDeltaSeconds) is called once per _Process. All host timing reads only this clock:

• FrameYield() (the throttle): increment an op counter; when it reaches opsPerFrame (the budget, scaled by Speed), block the VM thread until the next _Process advances the clock, then reset. So the VM runs ~opsPerFrame ops per real frame ⇒ ~opsPerFrame × displayFps ops/sec. Start opsPerFrame ≈ 30 (≈1,800 ops/sec at 60 fps) — tunable, calibrated by eye.
• Sleep(ms): block until the clock advances ms (replaces the raw Thread.Sleep).
• anim tween: reads FrameClock instead of Godot's raw wall clock.

Because the throttle, sleeps, and tweens share one clock, a future Speed = 4 scales all three together — the ~4× fast-forward — with no desync, and the multiplier stays entirely inside the host.

Concurrency

Same shape as WaitForInput: the VM background thread blocks on a host primitive; _Process advances the clock and releases waiters. GfxState access is already serialized on its re-entrant lock (sleep-race fix); the VM now runs concurrently with the compositor for real durations, so that lock discipline is relied upon (covered by GfxStateConcurrencyTests).

Parity (hard constraint)

• All non-Godot hosts implement FrameYield() as an empty method and keep Sleep() a no-op. The VM never blocks headless → Steps, emitted lines, halt reasons are byte-identical.
• Regression gates unchanged: Age.Cli sweep (284 exit / 13 STEP-LIMIT), Godot --selftest, engine tests.
• A trace-diff on a synthetic scene proves the added per-op FrameYield() (no-op headless) changes nothing the oracle observes.

Testing (synthesize, don't disable)

• FrameClock unit tests — deterministic Advance math + budget/deadline crossing at Speed=1 and other values; no real sleeping.
• Throttle gate test with a fake-clock host — a synthesized scene (ScriptAssembler) run through a test host whose clock is advanced by hand; assert the VM blocks after opsPerFrame ops and resumes on the next clock advance, and that Speed scales the budget.
• Parity trace-diff — synthetic scene through the no-op headless path == pre-change baseline.
• Regression — sweep counts unchanged; --selftest green.
• Pacing acceptance — the user validates the finished live build (tunes opsPerFrame by eye).

Affected components

File	Change
engine/Age.Engine/Hosting/IHost.cs	add void FrameYield()
engine/Age.Engine/Hosting/FrameClock.cs	new — pure virtual clock (NowMs, Speed, Advance); the op counter + thread-blocking live in the Godot host, not here
engine/Age.Engine/Vm/VirtualMachine.cs	call _host.FrameYield() after each Step in RunFrame
engine/Age.Engine/Hosting/CaptureHost.cs + all other non-Godot hosts	add empty FrameYield()
godot/GodotAdvHost.cs	FrameYield() = op-budget throttle on FrameClock; Sleep() blocks on FrameClock
godot/Main.cs	own FrameClock; Advance(delta) + release waiters each _Process; anim tween reads FrameClock
engine/Age.Engine.Tests/	new FrameClock, throttle-gate, parity trace-diff tests

Risks / open items

• opsPerFrame tuning: the initial ~30 (≈1,800 ops/sec) comes from live measurement; final value is dialed in visually. Op cost varies (a call-script vs a mov), so a pure op count is an approximation — acceptable for pacing, tune by eye.
• Per-op host call overhead in headless (empty FrameYield): negligible expected; batch to every K ops if profiling disagrees. Parity holds regardless.
• Concurrency: the VM now runs concurrently with the compositor for real durations; relies on the existing GfxState lock — watch for unlocked shared state during validation.
• Stretch (only if needed): confirm the 2D-composite model by hooking StretchRect/Clear — not required for the fix.