Record decided-box contract blocker

docs/HANDOFF.md

@@ -16,19 +16,19 @@ baseline this work must preserve or improve. `/home/bob/repos/iris-pr18` has
 since moved to a different WIP branch; do not use that checkout as #18.
 
 The continuation is `/home/bob/repos/iris-layout-experiment`, branch
-`wip/transparent-frames`, head **`49cec82`**, three commits over **`34cafb6`**.
-It implements transparent frames and several useful simplifications, but it
-is not ready to replace #18:
+`wip/transparent-frames`, head **`4328eac`**, five commits over **`34cafb6`**.
+It implements transparent frames, pins the two open failures, and corrects
+`Scroll`'s content length, but it is not ready to replace #18:
 
 - the shrinker disagrees warm versus cold at seed 2 (`repaint`) and seed 108
   (`reorder`) at depth 5;
 - `many` and `resize` still do more work than #18 on a deep tree;
 - a resolved `leftover` share does not yet narrow its child's frame;
-- `Scroll` incorrectly treats `leftover` as a whole extra viewport.
+- step 3 exposed a widget-contract question that must be planned before the
+  retained protocol can change; see **Step 3 stop** below.
 
-The app's Iris pin is unchanged. Both experimental patches used to isolate
-the open failures were reverted; the experiment checkout was clean at
-`49cec82` when last inspected.
+The app's Iris pin is unchanged. The step 3 experiment described below was
+reverted; the experiment checkout was clean at `4328eac` when last inspected.
 
 ## The two rules to protect
 
@@ -171,6 +171,12 @@ papering over it.
 
 ### 1. Pin the two failures as focused tests
 
+**Done in `b842e4f`.** The named tests reproduce the mismatch at `49cec82` and
+remain intentionally red until the protocol repair:
+
+- `unsettled::repainting_a_stack_uses_the_box_its_sizing_child_decided`;
+- `unsettled::reordering_nested_spans_keeps_the_answer_from_the_decided_box`.
+
 Turn the shrunk seed 2 and seed 108 trees from `docs/LAYOUT_LOG.md` into fast,
 named regression tests. Each must demonstrate the present warm/cold mismatch
 at `49cec82`, then pass because both paths select the same tree and boxes—not
@@ -188,6 +194,10 @@ Check the ordinary suite and each new test individually.
 
 ### 2. Correct `Scroll`'s content length
 
+**Done in `4328eac`.** The four focused cases pass, as do the release fast
+oracle and the depth-5 counterexample seeds 184, 246, 292 and 372. The debug
+suite has 112 passing tests and only the two intentionally red tests above.
+
 Replace its `apply_leftover` content sizing with the fixed-part calculation
 above. Add focused cases for:
 
@@ -204,6 +214,30 @@ fresh-answer experiment (seeds 184, 246, 292 and 372).
 
 ### 3. Evaluate children in parent-decided boxes
 
+**STOP: this step needs planning before implementation continues.** A direct
+implementation was tried and fully reverted. It always kept the fresh answer,
+made placement reuse-or-translate (asserting if the retained drawing did not
+hold), asked `Span` children provisionally in the whole box before decided
+placement, gave `Stack` overlays the sizing child's reported box, and changed
+the random `Branch` tail to `Part::Of(40px..FULL)`. Both new focused tests
+passed, but 17 ordinary suite tests failed.
+
+Several failures state a load-bearing contract contrary to this plan rather
+than exposing another container bug. `ReadsBox` and `ReadsWidth` deliberately
+read the offered box, report one quarter of it, and their tests require two
+draws: one to answer and one in the answer-derived box. The tests' own comment
+says those draws come in pairs. `a_widget_asked_again_on_another_layer_is_drawn_there`
+likewise requires a second draw when placement changes the layer. Other
+failures include root resize/one-step validity tests, region-node placement,
+and `a_one_pixel_line_keeps_its_pixel_through_a_chain`.
+
+The unresolved decision is therefore public widget semantics, not another
+definition of measurement: either a widget must now guarantee that a drawing
+holds for the answer box it reports (and the contrary tests, documentation,
+and any real widgets must be redesigned), or placement sometimes has to run
+the body in an answer-derived box, contradicting the decided-box rule. Do not
+resume step 3 until that choice and its migration are written into the plan.
+
 Change placement so an answer-derived box never runs a container body.
 Placing becomes reuse-or-translate. Remove the offer/measurement gate and
 its retained bookkeeping only as each caller stops needing it; do not leave