diff --git a/docs/port/DECISIONS.md b/docs/port/DECISIONS.md index b0167c22..1116ac72 100644 --- a/docs/port/DECISIONS.md +++ b/docs/port/DECISIONS.md @@ -9,7 +9,7 @@ dies, which is what this file is for. -220 sections. Search this before re-deriving anything. +221 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) @@ -231,6 +231,7 @@ dies, which is what this file is for. * [🔴 I promoted an unverified claim of theirs to a fact, against data I had authored](#i-promoted-an-unverified-claim-of-theirs-to-a-fact-against-data-i-had-authored) * [The half-guard they named, tested — and it found a real gap on first use](#the-half-guard-they-named-tested--and-it-found-a-real-gap-on-first-use) * [The ordered pair determines the gap — and nothing declared predicts it](#the-ordered-pair-determines-the-gap--and-nothing-declared-predicts-it) +* [The overlay leaf-pin fix, verified live with a negative control](#the-overlay-leaf-pin-fix-verified-live-with-a-negative-control) ## P0 — the exporter, 2026-08-28 @@ -11597,3 +11598,46 @@ have no way to tell the difference with the data that exists. *two* candidate models positively excluded rather than one, and the surviving shape harder than when I escalated the decision. Their advice stands and I agree: don't key it. + +## The overlay leaf-pin fix, verified live with a negative control + +I recorded that fix as *"currently inert — `press_start` carries no leaf, so +nothing verifies it in a live case."* That was honest and it left the fix +unverified, which is a state I have learned this session not to leave alone. + +**`title` carries the leaves**, so raising it *as* an overlay exercises the path: + +| | overlay pins reported | renders at leaf-time 0 vs 4 | +|---|---|---| +| **pre-fix** (line reverted) | — | **identical** — the pin does not reach | +| **post-fix** | `overlay(leaf=0.0)` → `overlay(leaf=240.0)` | **differ, max 105.86** | + +✅ **A proper before/after**: the negative control shows the failure the fix +removes, rather than only showing the fixed state working. Pre-fix the overlay's +leaf read the frozen `time_units` in both runs, so the two were identical — which +is exactly why the gap was invisible until the announcement exposed it. + +⚠️ **The configuration is synthetic.** `--overlay=title` over `main_menu` is +something the game never does. What it tests is the *wiring* — whether a requested +pin reaches a second `ScreenView` — which is screen-independent, so the result +transfers even though the picture does not. + +### A process failure worth keeping + +I reverted the fix with a text patch to run the control, and **the restore script +half-failed**: it removed the line and then threw on the way to putting it back. +The tree was left without the fix. + +🔴 **What caught it was two independent checks disagreeing.** `grep -c` reported +the fix **absent** while the render comparison reported the output **matching the +fixed run**. Both cannot be true. Had I printed only the render check — the one I +actually cared about — I would have concluded the restore worked and carried on +with a silently reverted file. + +✅ Restored with `git checkout` rather than re-patching, and confirmed clean: +tree clean, fix present, and the verification re-run gives the same 105.86. + +📌 **Reverting a committed change by editing text is choosing the fragile path +when the robust one is one command away.** Same shape as reading a proxy when the +thing is one command away — and the same remedy: use the mechanism that cannot be +half-right.