# Frame-paced `sleep` — the SC0000 opening animates

> **⚠ OUTCOME CORRECTION (2026-07-08):** this spec's premise — that bare `sleep` paces the opening burst, so
> implementing it would make the opening animate — was **wrong**. `sleep` is correctly implemented and the
> one-shot dramatic pauses work, but the rapid CG/AE\* burst is not sleep-paced (trace shows no sleep between the
> draws) and did not animate. Canonical corrected result: `docs/phase-a-slice-plan.md` (A2b frame-paced sleep).
> Kept as-authored below for provenance.

**Date:** 2026-07-08
**Branch:** continues `feat/gfx-command-buffer`
**Slice goal:** make the SC0000 opening's `sleep`-paced retained-object burst (`AE001D → AE002B →
AE003B` surface swaps + the alpha-tween channel) actually animate on screen, by giving `sleep`
(`0xc8`) real timing. Activates the already-built per-object alpha-tween subsystem and the per-frame
compositor, both currently dormant because the burst runs instantly.

## Problem (root cause, verified)

The Godot compositor `Main.Recomposite()` already runs every `_Process` frame (~60 fps) and composites
the VM's **live** `GfxState` (`_vm.Gfx.SnapshotVisibleObjects()`, ascending-handle z-order, with the
wall-clock alpha tween applied). The infrastructure to *present per-frame* already exists.

The opening does **not** animate for exactly one reason: `sleep` (`0xc8`) is a GAP op — it has no VM
`case`, so it falls through to `pc+1` with **zero delay**. The VM runs the whole opening
load/draw/`sleep` burst to completion in microseconds on its background thread, so the compositor only
ever catches the **final** retained state. The intermediate `AE*` surface swaps are overwritten before
a single frame composites.

This is confirmed native-side (`docs/engine-re.md`): the engine is retained and does **not** block the
VM on present — animation runs in the host's per-frame loop while the VM is parked; `sleep` paces the
burst. Raw SC0000 bytecode shows `sleep 0x64 / 0x3e8 / 0x2ee` between paced retained-object draws.

**Therefore:** give `sleep` real timing (pause the VM thread) → the existing compositor catches each
intermediate frame → the opening animates. No new rendering machinery required.

## Non-goals (explicitly deferred)

- **Scene-coroutine framework** — `0x7b` / `0x7c` / `0x140`, the `G[0xaba5c]==1` re-entry gate, and the
  `label_125bd` slot-table setup. This is the interactive multi-object subsystem; it is not on the
  opening's linear path. Stays the "scene-coroutine backlog" item.
- **ADV native text** (`0x204` draw-string, `0x7a`) — text already renders via `IHost.ShowText`.
- **Audio/SFX cluster** (`0xb4/b5/b6/c2`) — separate self-contained slice.

## Design

### 1. RE task (bounded) — confirm `sleep` semantics

Decode the `0xc8` handler via the master dispatch table `handler(op) = ctx[0x26c93+op]` (read from
`FUN_00413860`, per `docs/engine-re.md`). Determine:

- **Time unit** of the operand. Operands seen: `0x64`(100), `0xc8`(200), `0x2ee`(750), `0x3e8`(1000),
  `0x1f4`(500), `0xfa0`(4000). Need to know: milliseconds, frames (÷60), or engine ticks. This gates
  correct pacing (getting it wrong makes the opening 60× too fast or slow).
- Confirm it is a **simple blocking pause** (busy/sleep loop or message-pump wait), not a
  clock-relative / conditional wait that would need extra state.

Annotate in Ghidra (rename `FUN_...` → `sleep_op_0xc8` + plate comment with the decode) and record the
finding in `docs/engine-re.md` and `vm-map/opcodes.toml` (op `0xc8`, source=investigation).

**Output of this task:** the unit conversion `operand → milliseconds` used by the Godot host.

### 2. Engine seam — `IHost.Sleep` + VM dispatch

- `IHost` gains `void Sleep(int milliseconds)`.
- `VirtualMachine` gains `case "sleep": _host.Sleep((int)Read(a[0])); return pc + 1;` (unit conversion
  applied in the op or the host per the RE — decided in the plan; simplest is the host converts).
- **Parity:** still `pc + 1` → step counts and emitted offsets are byte-identical; the only behavioral
  delta versus the current GAP fall-through is that the gated `Stub` trace event for `0xc8` is replaced
  by the op executing. No golden regen.
- The **9 non-Godot hosts** (`CaptureHost` + test doubles `RecHost`/`CountHost`/etc.) implement `Sleep`
  as a **no-op**. Headless and every `Age.Cli` path stay instant → `sweep` 284 exit / 13 STEP-LIMIT and
  all engine tests unchanged.

### 3. Godot host — real pause on the VM thread

`GodotAdvHost.Sleep(ms)` blocks the VM **background thread** for the (converted) duration — the same
thread `vm.Run()` executes on via `Task.Run`. This mirrors the existing `WaitForInput` semaphore
suspend, but time-based. The Godot **main thread is untouched**, so `_Process` → `Recomposite()` keeps
compositing and presenting during the pause. No deadlock (the VM thread is a throwaway task thread).

Safety / debugging:
- Optional total-duration cap so a pathological script can't hang the window indefinitely.
- Optional `--sleep-scale <f>` CLI knob (default 1.0) to speed up/slow down for inspection. Out of the
  critical path; include only if cheap.

### 4. Thread-safety audit (primary correctness risk)

Today the compositor already races the VM thread, but the mutation window is microseconds so nothing is
ever observed mid-write. Once the VM genuinely runs concurrently **for seconds**, `GfxState` reads and
writes truly overlap. Requirement:

- Every `GfxState` **mutator** (`GetOrCreate`, `draw-texture` bind, `SetSurface`, the anim ops,
  `Register`/`Release`, `EraseRange`, `CurrentObject` set) and the reader `SnapshotVisibleObjects()`
  must serialize on the existing `_lock`.
- `SnapshotVisibleObjects()` returns an **immutable copy** built under the lock (it largely does; audit
  and close gaps — several mutators currently lock, some may not).

This is the one place a subtle bug could hide; the audit is explicit work, not incidental.

### 5. `0x20c` present — minimal handling

Our compositor presents continuously, so an explicit present op is implicitly satisfied. During the RE
(Task 1) confirm whether `0x20c` merely presents the frame (→ mark `noop_headless`/`safe-noop` in
`opcodes.toml`, a free GAP-count shrink) or gates double-buffering (→ small handler). Default expectation:
`safe-noop`. Kept intentionally minimal.

### 6. Verification tooling — frame-sequence capture

A time-based effect cannot be verified by the existing single `--shot`. Add a Godot dev flag
`--shot-sequence <dir> [--frames N]` that saves one PNG per `_Process` frame across the opening (up to N
frames or scene end). Success criterion: the captured sequence shows `AE001D`, `AE002B`, `AE003B` as
**distinct** frames (the explosion stepping), not just the final CG. This is the agent's eyes for the
animation.

## Testing & parity

- **New engine test:** a synthesized scene (via `ScriptAssembler`) containing a `sleep` op, run against
  a recording host that asserts `Sleep` was invoked with the expected converted value. Synthesize test
  data; never disable a feature to keep a real scene matching a frozen number (standing project rule).
- **Regression guard:** `sweep` (headless) unchanged 284/13; all engine tests byte-identical (no-op
  sleep everywhere headless); `--selftest` unchanged (synthetic selftest scene has no `sleep`).
- **Visual verify:** `--shot-sequence` frame set shows the opening `AE*` burst animating.
- **Completeness gauge:** `tools/scene_opcode_coverage.py SC0000` — `0xc8` moves GAP→impl; `0x20c` likely
  GAP→safe-noop. Record the GAP delta.

## Docs to update on landing

- `docs/engine-re.md` — `sleep` (`0xc8`) handler decode + time unit; `0x20c` present disposition.
- `vm-map/opcodes.toml` — `0xc8` (name/semantics/source), `0x20c` (noop_headless if confirmed); rebuild.
- `docs/phase-a-slice-plan.md` — A2b frame-pacing slice result; the honest "AE* now animates" update.
- `docs/tools-reference.md` — `--shot-sequence` flag.
- Status memory (`himegari-port-status.md`) + `MEMORY.md` line — frame-pacing landed; coroutine still
  deferred.

## Risks

- **Time-unit wrong** → mitigated by Task 1 (RE before implementing) + visual verify.
- **GfxState race** → mitigated by the Task 4 audit + immutable snapshot.
- **Godot-headless real-time cost** → only `GodotAdvHost` blocks; CLI/headless hosts no-op. A headless
  Godot play of a sleep-heavy scene takes real wall-clock time, which is acceptable and `--shot`
  auto-advances; `--selftest` is unaffected.