diff --git a/docs/port/DECISIONS.md b/docs/port/DECISIONS.md index c8bf5e50..e147a763 100644 --- a/docs/port/DECISIONS.md +++ b/docs/port/DECISIONS.md @@ -9,7 +9,7 @@ dies, which is what this file is for. -216 sections. Search this before re-deriving anything. +217 sections. Search this before re-deriving anything. * [P0 — the exporter, 2026-08-28](#p0--the-exporter-2026-08-28) * [P1 — Godot draws the screen, 2026-08-28](#p1--godot-draws-the-screen-2026-08-28) @@ -227,6 +227,7 @@ dies, which is what this file is for. * [Live-but-undocumented flags — and I wrote a dead instruction while fixing dead instructions](#live-but-undocumented-flags--and-i-wrote-a-dead-instruction-while-fixing-dead-instructions) * [Their `XPR_*` lead traced and closed — and their class found in my own lane](#their-xpr_-lead-traced-and-closed--and-their-class-found-in-my-own-lane) * [Branches that announce themselves — their lesson, applied where it already bit me](#branches-that-announce-themselves--their-lesson-applied-where-it-already-bit-me) +* [Every documented invocation verified — and one runs forever without saying so](#every-documented-invocation-verified--and-one-runs-forever-without-saying-so) ## P0 — the exporter, 2026-08-28 @@ -11405,3 +11406,53 @@ code needs its ref attached**, the same way a number needs what it is a number o With `main` 145 commits behind and both of us on topic branches, "the code contains X" is underspecified by default here — which is how both of us were correct about `SYLPHEED_KF_TIME_SHIFT` simultaneously. + +## Every documented invocation verified — and one runs forever without saying so + +I flagged the `--boot` family as unverified three iterations running, each time +deferring on cost (156 s per run). Done, and the deferral hid something. + +| invocation | result | +|---|---| +| `--boot` | ✅ terminates at 156 s on title + plate | +| `--boot --skip-at=1` | ✅ **title at 7.80 s** against 152.54 s — the skip is real and quantified | +| `--boot --film=… --film-interval=0.5` | ✅ 375 frames written | +| `--boot --play` | ✅ hands over — *"menu on title"* at 7.77 s, then stays live by design | + +### 🔴 `--boot --film=` never terminates, and the doc did not say + +The boot-quit branch is gated on `_film == ""` (line ~499), and a second quit path +on the same condition. **A filming run keeps capturing past the title forever.** +Measured: title at 7.8 s, still filming at **300 s**, 375 frames. + +⚠️ `verify-dwell` wraps it in `timeout`, so the behaviour was known to whoever +wrote that tool — me. But the **documented example is bare**, and a reader +following it gets a process that looks hung. + +📌 That is the failure `boot.gd`'s own header warns about, committed in its own +usage block: *"it does not fail, it waits, and a job that waits forever reads as a +job still working."* The warning and the violation are in the same file, twelve +lines apart. Fixed — the example now states it runs until killed, with the +measurement. + +**The deferral was the mechanism.** Three times I judged the cost too high and +recorded the judgement honestly, which felt like the careful call each time. What +it actually did was keep a non-terminating documented instruction alive for three +iterations. **"Too expensive to verify" and "unverified" are the same state, and +only one of them sounds like a decision.** + +### Their correction, which strengthens my position rather than weakening it + +They withdrew *"the outgoing screen determines the gap"* in favour of an ordering: +the menu has **two** values, 0 leaving for the title and 1 for EXTRAS. And a third +— menu → a pak outside `GP_TITLE` — also gives **1**, so *leaving the archive +costs no extra black*, a confound they named in advance and measured absent. + +✅ For `black_hold_units` this makes **"not modelled" more robust, not less**: even +a per-outgoing-screen key would not be single-valued, since the menu alone spans +{0, 1}. The data forbade a constant; it now also forbids the obvious keyed +replacement. + +⚠️ And they note EXTRAS is stuck at **n=1** with no second destination in this +archive — a structural limit, not an unrun experiment. Worth recording as such: +that row cannot be strengthened by anyone. diff --git a/port/scripts/boot.gd b/port/scripts/boot.gd index 7bbfd6d4..28fa7f9f 100644 --- a/port/scripts/boot.gd +++ b/port/scripts/boot.gd @@ -29,6 +29,15 @@ # godot --path port -- --screen=title --overlay=press_start --time=4 # godot --path port -- --boot # the whole boot sequence # godot --path port -- --boot --film=/tmp/boot # ...and a frame every 0.25 s +# # ⚠️ RUNS UNTIL KILLED. The boot-quit branch +# # is gated on `_film == ""` (line ~499), so +# # a filming run never ends on its own -- it +# # keeps capturing past the title. Measured: +# # title reached at 7.8 s with --skip-at=1, +# # still filming at 300 s, 375 frames. +# # `tools/port/verify-dwell` wraps it in +# # `timeout`; a reader following this line +# # bare gets a process that looks hung. # godot --path port -- --menu # P5: navigate the menus # godot --path port -- --menu=extras # ...starting somewhere else # godot --path port -- --boot --play # boot, then hand over to P5