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

124 lines
6.7 KiB
Markdown

---
id: LSN-0076
ticket: headless-memcard-reopen-io-progress
title: Native IO progress is not machine progress
created: 2026-11-10
tags: [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](../../../docs/specs/runtime/08-save-memory-and-memcard.md),
[Headless Control](../../../docs/specs/runtime/11-portability-and-cross-platform-execution.md#131-control-contract)
and [Memcard Controls](../../../docs/specs/runtime/11a-headless-automation-protocol.md#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](evidence/qualification/red-controlled-release.log)
and corrected [release qualification](evidence/qualification/release.log) 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](evidence/summary.json) 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](evidence/baseline/review-summary.json) 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](runtime-handoff.md) 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.