Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
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.
124 lines
6.7 KiB
Markdown
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.
|