Files
prometeu-runtime/discussion/lessons/DSC-0072-headless-memcard-reopen-io-progress/LSN-0076-native-io-progress-is-not-machine-progress.md
T
bquarkz c3589be1ad
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
fix(headless): wait for memcard bootstrap IO progress
Coordinate bounded native publication progress during frame advance while preserving watchdogs, guest budgets and resource ownership. Add controlled and packaged reopen regressions, clarify the runtime specs, and retain qualification evidence.
2026-11-10 23:26:40 +00:00

6.7 KiB

id, ticket, title, created, tags
id ticket title created tags
LSN-0076 headless-memcard-reopen-io-progress Native IO progress is not machine progress 2026-11-10
headless
memcard
testing
ownership

Context and published result

The headless owner now waits for native progress when a successful memcard bootstrap hook is still blocked on its queued or running publication. The wait stays outside machine ticks and inside the original frame advance. Ordinary asynchronous gameplay commits continue independently of this coordination.

Historical source: accepted DEC-0071, implemented through PLN-0202 from AGD-0075. The canonical contracts are Save Memory and MEMCARD, Headless Control and Memcard Controls. This lesson explains the published result rather than defining a new policy.

A tick watchdog can measure attempts without measuring useful work

An owner can repeatedly call firmware while an execution gate returns before the VM advances. In the original incident, 100,000 firmware attempts left the guest at logical frame zero and VM tick two, with native presentation IO pending. The host watchdog correctly reported exhausted attempts; that observation did not establish excessive guest instructions or a guest fault.

Increasing a guest budget would have changed the wrong quantity. The useful question is which dependency prevents progress, which owner can observe it, and which deadline governs it. Here the synchronous host owns the frame request, while an asynchronous storage worker owns the publication and its resources.

Wait on the execution dependency, not every active worker

The query follows the active GameRunning task's session: its bootstrap hook completed successfully, the memcard session still blocks execution, and native IO remains owned. That excludes an ordinary gameplay save whose caller can continue executing while storage works in parallel.

This distinction is operationally observable. A channel-controlled gameplay commit remains active while the guest completes its next frame. A bootstrap publication under the same kind of hold prevents the first frame until the worker returns or native supervision requests external action.

Notification ordering and clocks solve different problems

The owner reads a fresh lane progress stamp before every dependency observation and native poll. It then waits for actual progress, in requested intervals of at most 5 ms. Reusing a stamp indefinitely after another job finishes would turn later waits into immediate returns even while the relevant publication remains pending. A wake only permits another observation; it is not proof of success.

The request keeps its native deadlines from admission: cancellation at 500 ms and stop/escalation at 1 s. A separate owner guard expires 2 s after the first wait admission within that advance and never resets on wakes or reentry. Native action-required boundaries take precedence over that guard. Explicit-instant tests qualify the guard; actual blocked storage reaches native supervision first.

Machine execution keeps its 100,000 firmware-tick watchdog. Polling and waiting do not add simulated ticks, frames, input or instruction work. The frame request is neither replayed nor moved into boot.

Native supervision should return before another guest tick

While the bootstrap dependency remains held, the owner polls native work without executing another firmware tick. This lets it observe an unavailable card or restart requirement before allowing guest execution to proceed. The controlled failure case asserts zero completed frames, a paused guest and no fabricated VM fault.

Timeout and cessation remain separate. A blocked native operation can require external action while its worker still owns the file lock. Returning from an advance does not free that lock or its buffers. The integration test verifies ownership while the operation is held, then explicitly permits safe worker return before cleanup.

A reader can publish metadata without saving its own answer

The previous neutral reader intentionally imported no presentation or commit operation. That is a strong readback oracle: correct payload plus an unchanged whole image. It also leaves presentation during reopened bootstrap untested.

An additional neutral reader supplies presentation in its hook and verifies the existing bytes 0, 127, 128 and 255 without a slot write or payload commit. Its metadata publication is intentional. A distinct-process test sends exactly one first advance, checks its frame/tick state and captures the canonical game frame. The original no-presentation reader separately retains the whole-image oracle.

Optimized and debug execution expose different scheduling windows

The original installed probe failed intermittently in two of nineteen fresh processes. The controlled storage test establishes entry into the relevant write using a channel, holds it while observing the owner, and then permits completion. The old optimized host expired its tick watchdog while that write was held. The slower debug host could already let it finish before exhausting attempts.

The pre-fix release failure and corrected release qualification preserve that distinction. A green debug test alone would not have established the fix. Control of the IO phase and optimized execution complement each other.

Evidence and ownership boundary

The qualification summary records 1,125 passing workspace tests, 89 passing release tests, formatter and strict workspace clippy success, and all four packaged automation cases passing against the exact extracted macOS arm64 distribution. The generic workspace run has 16 ignored tests; the four packaged cases were separately executed successfully. Other manual/device and resource qualification cases remain ignored.

The baseline preserves the nineteen installed native probes and two original failure transcripts. Source deltas, source/binary/archive/schema hashes, native logs and the selected stable install's unchanged fingerprints remain in the qualification evidence. The archive is also retained alongside its isolated installation.

The runtime handoff identifies the qualified executable for the Studio owner. This delivery executes only provider tests with runtime-owned PBX/ABI fixtures. Studio/game builds and the consumer's Zelda/UI/MCP acceptance remain with that owner. Qualification is macOS arm64, not a cross-platform, physical power-cut or device-latency certification.