Harden movie playback lifecycle and diagnostics

docs/PROJECT-STRUCTURE.md

@@ -45,6 +45,7 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── extract_phase2.py                   batch: disasm + text + data extraction
     │   ├── extract_init.py, global_map.py …    *INIT parsers, global-var map builder
     │   ├── validate_opcode_table*.py           decode-coverage validators
+    │   ├── movie-corpus-gate/                  C# full-corpus FFmpeg decode/lifecycle acceptance tool
     │   └── probe_*.py                          format reverse-engineering probes (historical)
     │
     ├── bin/                                  3rd-party binaries we use (not ours, not the game's)

docs/asset-resolution-re.md

@@ -361,12 +361,15 @@ same completed state so a backend that starts but never signals EOF cannot hold
 reported combat stall survives this guard, capture the VM/service coordinate after `0x2518` and treat it as
 a separate BTL timed-presentation bug.
 
-The remaining implementation boundary is the already-planned decoder interface/factory plus a software
-MPEG backend that handles the installed non-16-aligned effects, and preservation of the destination
-surface's created dimensions instead of replacing every movie surface with the SC0000-specific 800x600
-value. Failure is now nonblocking and suppresses bogus still-AGF fallback. Regressions must cover at
-least a 280x352 effect (`MVB001`), a 400x400 effect (`MVB914`), immediate `0x23f` stop time, RGBA frame
-publication, completion, failure completion, and release.
+The FFmpeg replacement and destination-surface work are recorded in `docs/platform-portability.md` and
+`docs/phase-b-framework.md`. Movie identity also remains typed across the entire retained-surface lifecycle.
+The packed catalog is immutable while mounted, so once an id enters the movie path its `.AGF`-named MPEG
+payload cannot fall through to the ACGF still decoder before the first frame or after the last live binding
+is detached. The latter guard closes a real cross-thread cleanup window: BTL clears `GfxState` and releases
+the host surface in one VM instruction, while the compositor may hold a snapshot from immediately before
+that pair. Without remembered movie typing, the snapshot briefly attempted to decode MVB955/MVB004/MVB914
+as still images after successful playback and printed false `expected an ACGF image` warnings. This does not
+retain a frame or playback instance; it only prevents an immutable movie resource from being reclassified.
 
 ### Modal startup/ending movie resources (implemented 2026-07-20)
 

docs/phase-b-framework.md

@@ -605,7 +605,7 @@ dependency pin, corpus codec inventory, timing contract, and packaging rules liv
    and a monotonic clock, publish only due frames, delay EOF completion through the final presentation interval,
    and retain the existing watchdog. Make FFmpeg the default with no dimension/effect dispatch and exercise both
    non-modal `0x236` and modal/cancellable `0x20f` paths.
-4. **Next — run the installed-corpus gate.** Every one of the 213 MPEG payloads must open, report its expected display
+4. **Completed — run the installed-corpus gate.** Every one of the 213 MPEG payloads must open, report its expected display
    dimensions and a positive stop time, produce a correctly sized RGBA frame, maintain nondecreasing timestamps,
    reach EOF, and dispose within a bound. Normal tests use small project-authored 280-wide and aligned MPEG
    fixtures so decoder behavior is never disabled when the original install is absent; the full local sweep is
@@ -643,9 +643,47 @@ clock tests cover due-frame publication, final completion, cancellation, and fai
 formerly failing 280x352 `MVB961` and aligned `MVB908`. A natural headless SYSTEM4 smoke played and released
 `LOGO.AGF` at its reported 7288 ms, then opened 106919 ms `OP.AGF` and published its first frame before bounded
 shutdown. The user then confirmed the opening movies play correctly in a normal windowed run. The complete suite
-is 318 tests, the Godot build is warning-free, and threaded selftest passes. **NEXT:** run the 213-payload
-installed-corpus gate, then validate SC0000 CHAPTER and the original battle exchange before removing DirectShow
-or judging the tabled combat stall.
+is 318 tests, the Godot build is warning-free, and threaded selftest passes. That established the prerequisite
+for the installed-corpus gate recorded below.
+
+Step 4 completed on 2026-07-22. `tools/movie-corpus-gate` selects MPEG program streams by signature from the
+complete native-order VFS catalog and runs the unpaced FFmpeg session to EOF. The acceptance run discovered the
+expected 213 assets and passed all 213 under the 30-second per-item bound; every stream reported independent
+matching dimensions, positive duration/frame rate, correctly sized RGBA frames, nondecreasing timestamps,
+changing imagery, EOF, and clean teardown. The run decoded 15,788 frames across all twelve installed dimension
+variants in 8.1 seconds; the longest item, 263-second `ED.AGF`, decoded in 4.4 seconds. Detailed compatibility
+evidence lives in `docs/platform-portability.md`, and reproduction/report options live in
+`docs/tools-reference.md`. This moved acceptance to step 5's windowed SC0000 `CHAPTER`, aligned plus 280-wide
+combat effects, combat cleanup, and prior-stall checks. DirectShow remains unselected but in-tree until those
+manual checks pass.
+
+The first post-corpus combat recheck still stalled after an apparently absent effect. The ordinary Godot log
+ruled out an FFmpeg decode/EOF failure: both reached battle batches opened, published first frames, and stopped
+(`MVB005`/`MVB952`/`MVB913`, then `MVB921`/`MVB126`/`MVB953`) with no decoder failure or watchdog. F6 was added as
+an observe-only bounded JSON snapshot of the current/recent VM path, host waits, movie/surface lifecycle, and
+blocking finite gfx channels.
+
+The first F6 capture localized the stall exactly to BTL's `0x2492..0x2515` movie polling loop, parked at the
+16 ms sleep `BTL@0x250a`. Gfx had no blocking timed presentation, and the only real decoder (`MVB033`, surface
+44) was complete. Surfaces 7 and 8 nevertheless retained incomplete/no-frame registrations for already stopped
+`MVB953` and `MVB126`, so op `0x23a` could never clear. The user's observation that the last effect frame remained
+until replacement was the same ownership defect: movie frames, completion, and decoder dictionaries were keyed
+by shared resource id even though BTL can bind/restart one asset through multiple surfaces. Releasing one binding
+removed shared state while another surface registration survived forever.
+
+Movie ownership is now keyed by a unique playback instance; resource id is asset identity only. Each surface
+resolves its own instance frame/completion, replacing a surface invalidates late callbacks from only its prior
+instance, and releasing one of two same-resource playbacks cannot affect the other. Blank pre-roll surfaces no
+longer borrow a concurrent instance's frame, and console/timeline diagnostics include playback ids. Duplicate-
+resource and replacement regressions pass, as do all 327 engine tests, the zero-warning Godot build, threaded
+selftest, and the 213/213 unpaced corpus gate. A quick repeat of the same combat exchange no longer stalled.
+The run did expose false `AGF decode failed ... expected an ACGF image` lines after successful first frames and
+immediately before teardown. This was not FFmpeg failure: the compositor could retain a pre-release `GfxState`
+snapshot for one frame after the host detached the movie binding, then send the `.AGF`-named MPEG id through the
+still-image fallback. Runtime-learned movie resource typing now survives instance teardown and suppresses only
+that invalid fallback; it does not retain the frame or decoder. The focused cleanup regression, all 328 engine
+tests, zero-warning Godot build, and threaded selftest pass. **NEXT:** perform a longer combat/return-to-FIELD
+acceptance run, then delete DirectShow if the remaining live gate stays clean.
 
 **Mutable-surface fill/blend regression corrected.** The first visual recheck exposed BUNKI's menu interior
 as transparent. SYSTEM4 creates 800x600 surface 3 and fills it opaque white through `0x20b`; the metadata-only

docs/platform-portability.md

@@ -25,8 +25,8 @@ replaced before claiming portable exports.
 
 | Area | Current dependency | Runtime impact | Portability status / future action |
 |---|---|---|---|
-| AGE movie decode (`0x236` scene movies; `0x20f` modal LOGO/OP/ED) | `FfmpegMovieDecoder` is the selected live factory over the project-owned `native/age_movie_ffmpeg` ABI; `DirectShowMovieDecoder` remains unselected pending deletion | Windows-x64 live playback now covers formerly rejected 280-wide effects, but other native targets and the full 213-payload gate remain | Run the corpus and windowed live gates, then delete DirectShow and add target-specific native builds |
-| Movie integration | `MovieRuntime` owns `IMovieDecoder` from an injected factory; the FFmpeg worker paces PTS against a monotonic clock and supports cancellation/failure completion | Backend ownership is portable, while `Main` remains annotated Windows because only the win-x64 bundle is available | Add Linux/macOS builds and remove the Windows annotation after DirectShow is deleted |
+| AGE movie decode (`0x236` scene movies; `0x20f` modal LOGO/OP/ED) | `FfmpegMovieDecoder` is the selected live factory over the project-owned `native/age_movie_ffmpeg` ABI; `DirectShowMovieDecoder` remains unselected pending deletion | Windows-x64 passes the complete 213-payload installed-corpus gate; other native targets and the remaining windowed CHAPTER/combat checks are pending | Run the windowed live gates, then delete DirectShow and add target-specific native builds |
+| Movie integration | Each surface owns a unique playback-instance id; `MovieRuntime` owns `IMovieDecoder` from an injected factory, and the FFmpeg worker paces PTS against a monotonic clock with cancellation/failure completion | Concurrent/restarted uses of one asset have independent frame/completion/teardown state; `Main` remains annotated Windows because only the win-x64 bundle is available | Recheck the corrected combat lifecycle, then add Linux/macOS builds and remove the Windows annotation after DirectShow is deleted |
 | Movie audio | FFmpeg detects the audio stream but the current ABI returns video frames only | MPEG movie audio remains intentionally silent | Extend the ABI with timestamped PCM and select an audio/presentation clock; separate feature slice |
 | ADV font discovery | `godot/Main.cs` probes `C:/Windows/Fonts` for Japanese fonts | Harmless fallback today, but appearance depends on host fonts | Bundle/configure a redistributable font or add platform-specific discovery |
 | Filesystem semantics | Several filename and containment comparisons use `OrdinalIgnoreCase`; installed assets are conventionally uppercase | Needs validation on case-sensitive filesystems; may hide casing or containment mistakes | Add Linux/macOS tests with mixed-case synthetic roots and use filesystem-appropriate containment rules |
@@ -135,6 +135,16 @@ smoke completed 7288 ms `LOGO.AGF`, opened 106919 ms `OP.AGF`, and published fra
 DirectShow; the user subsequently confirmed both opening movies work in normal windowed playback. Full
 export/source-offer packaging and non-Windows builds remain outstanding.
 
+The Windows-x64 installed-corpus gate passed on 2026-07-22 with the pinned dependency: all 213 signature-selected
+MPEG payloads opened and reached EOF under a 30-second per-item bound. It decoded all 15,788 frames across twelve
+display sizes (120x120 through 800x600), independently matched sequence-header dimensions, found positive
+duration and frame-rate metadata, verified tightly packed RGBA size and nondecreasing timestamps, observed
+changing imagery in every asset, and closed every session. The set includes all 184 video-only and 29 audio-bearing
+streams; audio presence is detected but PCM remains intentionally undelivered. The 263-second `ED.AGF` was the
+slowest decode at 4.4 seconds in the deliberately unpaced gate, so its prior 30-second failure was test-harness
+whole-frame hashing overhead rather than a decoder incompatibility. The disposable machine report is
+`build/movie-corpus-ffmpeg.json`; invocation and report semantics are canonical in `docs/tools-reference.md`.
+
 ## Cross-platform validation gates
 
 Before advertising a platform as supported:

docs/tools-reference.md

@@ -72,6 +72,13 @@ All opcode knowledge (ABI, semantics, provenance, `depends_on`) is hand-edited *
 |---|---|---|---|
 | `locate_page.py` | Resolve a run-relative ADV page number to its canonical wait script/offset, last show-text instruction, call stack, and nearby disassembly. Pure selection/window logic is tested by `test_locate_page.py`. | `py -3.11 -X utf8 tools/locate_page.py SC0000 14 [--map <jsonl>] [--context N]` | `build/page-map-<SCENE>.jsonl` + script corpus → stdout |
 
+In a live Godot run, **F6** writes an observe-only stall snapshot under
+`user://diagnostics/stall-<timestamp>.json`, prints the absolute path, and copies
+`SCRIPT@offset · stall snapshot <path>` to the clipboard. The JSON contains the current call stack, a bounded
+128-instruction ring, VM/host wait flags, surface/movie completion state, decoder state, and the exact finite
+graphics channels capable of holding an op-`0x21c` presentation wait. Press it while the apparent stall is still
+active; unlike `--timeline-log`, it does not require a special launch or emit a continuous per-op stream.
+
 ## Native FFmpeg movie shim (Windows x64)
 
 These PowerShell tools build the selected Windows-x64 live movie backend. The dependency manifest pins an
@@ -81,6 +88,7 @@ immutable LGPL shared FFmpeg archive and SHA-256.
 |---|---|---|---|
 | `native/age_movie_ffmpeg/bootstrap-win64.ps1` | Download, hash-check, extract, and version-check the pinned FFmpeg SDK. Returns the resolved SDK root. | `.\\native\\age_movie_ffmpeg\\bootstrap-win64.ps1 [-Destination <dir>]` | `dependency-win64.json`, network/archive cache → disposable `build/downloads/`, `build/ffmpeg-sdk/` |
 | `native/age_movie_ffmpeg/build-win64.ps1` | Discover the MSVC x64 toolchain, build `age_movie_ffmpeg.dll`, and stage its exact shared-library/license dependencies. | `.\\native\\age_movie_ffmpeg\\build-win64.ps1 -SdkRoot <bootstrap-output> [-OutputDirectory <dir>]` | C ABI source + FFmpeg SDK → disposable `build/native/win-x64/` by default |
+| `tools/movie-corpus-gate` | Discover every MPEG program stream stored under an `.AGF` catalog entry, decode every video frame through the unpaced FFmpeg session, validate independent sequence dimensions, metadata, RGBA size, timestamps, EOF, timeout, and teardown, then emit a per-asset JSON report. Exit 0 means the expected corpus count and every asset passed; exit 1 is a gate failure; exit 2 means the native shim is absent. | `dotnet run --project tools/movie-corpus-gate -- --output build/movie-corpus-ffmpeg.json --expected-count 213 --max-item-ms 30000` · optional `--native-dir <dir>` | `SYS4INI.BIN` + loose/ALF VFS assets + staged FFmpeg shim → stdout progress + disposable `build/movie-corpus-ffmpeg.json` |
 
 The managed isolated probes load from `AGE_FFMPEG_NATIVE_DIR` when set, then application-local and
 `runtimes/win-x64/native` locations. Build the shim before running the `FfmpegShim*` tests; no original-game
@@ -88,6 +96,10 @@ movie is copied into the repository or native output. When `build/native/win-x64
 `dotnet build godot/Himegari.csproj` also stages the shim, its five DLL dependencies, and `FFmpeg-LICENSE.txt`
 beside `Himegari.dll` for development playback.
 
+The corpus gate intentionally bypasses presentation waits: it validates decode compatibility and lifecycle,
+not wall-clock playback pacing. `--expected-count` makes additions, omissions, or profile changes explicit;
+changing the pinned FFmpeg dependency requires rerunning this gate.
+
 ## Engine (C#) — VM core, CLI, Godot frontend
 
 The `engine/` .NET solution (`AgeEngine.sln`) is the runtime VM; `godot/` is the ADV frontend. Not