Host rAF Worker contract repair — 2026-11-04
The repaired test/test-host-raf-present.js now uses the real ThreadManager
for bootstrap scheduling and drives the actual host/renderer/filter publication
path. It also exposed and fixes a host defect: a failed display at a completed
Worker boundary stopped guest execution, whereas the same failure in an ordinary
rAF callback allowed subsequent slices and frames to continue.
Evidence is retained in scratch/runs/20261104-host-raf-worker-contract/.
The starting commit is c170f6c606f76f2e3899535bc1136c0e0e0effde.
first-failure.log reproduces the stale fixture failure described in
the display-failure repair note
and its retained baseline-host-raf-present.log: the fixture provided
spawnPending, but the host called startPendingWorkers.
Current contract and retained coverage
Changing that name would preserve an incorrect expectation. Worker bootstrap
now runs in the background because DLL_THREAD_ATTACH can wait on a lock owned
by the creator. Explicit readiness callers can still join spawnPending().
The replacement case instantiates the real manager with deterministic metadata,
interpreter exports and Worker transport. Across successive actual host steps it
checks that bootstrap starts exactly once, main runs while bootstrap is pending,
the pending child cannot run and its handle remains unsignaled. Guest ticks,
audio completion and wave callback pumps continue. The host passes the manager's
DLL/thunk sync state to main and publishes main's completed thunk high-water
state back before the next slice. After readiness, the real runnable selector
admits the child; the stopped variant admits no further slice or successor.
The original presentation cases remain: newest-frame coalescing, no upload before rAF, held-slice due-frame publication, long-slice rearming, locked-surface retry, idle shutdown of the frame chain, stop/trap final flush, GDI pacing, redundant renderer-rAF cancellation, synchronous no-rAF behavior and separate HUD upload and guest-present counters. The obsolete blocking-readiness assertions are replaced by the current bootstrap contract, including its stopped variant.
Four added integration variants execute shipped host and renderer scheduling
methods with a shared controllable rAF queue and the actual presentation filter
on small RasterCanvas surfaces: false-return and throwing display failures,
each between slices and after rAF deferral during a held slice. They check that
held publication retains queued damage without counting an upload; failed
display consumes the callback, unwinds repaint and slice holds, and never calls
the upload metric. A subsequent slice continues the service pump, and new
ordinary scheduleRepaint() damage publishes exactly once through the normal
host boundary/rAF chain. No direct recovery repaint is injected. The actual
renderer rAF is cancelled by the host after composition.
Production defect and fix
boundary-fail-before.log preserves the first production failure: running
became false at “display failure must not stop guest services”. The deferred
_presentAtBoundary() call to _presentNow() propagated the renderer exception
into _runThreaded()'s fatal catch, which called stop(). This made an incidental
rAF/Worker overlap determine whether a display failure stopped the application.
The host now catches and reports failure specifically around that deferred
scheduled _presentNow() invocation. It consumes the failed frame without
rearming a retry, counting an upload or stopping guest services. Later ordinary
damage can schedule a fresh frame. Direct _presentNow() and ordinary rAF
exceptions still propagate. Synchronous no-rAF behavior is unchanged. The
callback census host-file hash and review reason are refreshed; no guest
callback lifetime, invocation ownership or renderer implementation changes.
The final regression against the exact Git pre-fix host fails at the service
continuity assertion (before-control.log). Two further in-memory negative
controls reject joining bootstrap and ignoring the Worker publication hold.
check-controls.cjs retrieves old source from Git without writing a source
snapshot; verify.py reproduces the focused checks and controls.
Validation and limits
The repaired host suite, 11 renderer-display cases, Worker repaint boundary,
bootstrap progress and retirement, presentation filter, browser-shell Worker
slice selection, Worker vblank yield, tier membership, callback census mutation
tests and census reconciliation pass. These are offline tests, including small
Node Worker/RPC fixtures, without a browser or game. The locked full build
flock /tmp/wine-build.lock bash tools/build.sh passes (build.log).
One neighboring test is excluded from passing checks:
test/test-worker-input-slice-wake.js:119 expects the first slice synchronously,
before the host's awaited boundary pump finishes. Its configured-slice assertion
fails identically with the exact pre-fix host; both logs are retained as
test-worker-input-slice-wake.log and baseline-worker-input-slice-wake.log.
That unowned test remains unchanged. This is not a passing input-wake result.
The fixtures establish caller scheduling, failure propagation, accounting and recovery. They establish no engine-render completion, viewport/player identity, selected game layers, immutable backend readback, PNG transaction, real GPU output or Deus Ex gameplay/full-capture qualification. The missing capture linkage in the predecessor note remains missing. No fake identities or capture tokens were introduced, and no browser, box, game input, public deployment, runtime lifecycle action, subworker or successor task was used. No box was assigned: ID/state/expiry are not applicable; coordinator box ownership remains unchanged.
Git remains the source archive. The run retains exact Git SHAs, relevant binary diffs, the owned new-note patch, file/module hashes and unique logs/helpers. It contains no source-tree archive or media copy. Next work is the remaining owning engine/viewport/source-to-immutable-readback contract; the unrelated input-wake fixture also needs its own current async-host contract repair.