# ✅ Every condition site, with its comparand — the clear conditions are readable This is what the whole ISL chain was for. `data/isl-stage02-conditions.txt` has existed for a long time as a **stale artefact with no generator** — `isl_report.py`'s own docstring says so. It has one now, and the conditions are resolved rather than printed as `special[N]`. ## ✅ The deque ops are an expression stack `isl-bytecode.md` names ops 21–24 `push.i`/`push.f`/`pop.i`/`pop.f` over deques at `phase+44` / `phase+64`. What they are *used for* is the missing piece: ``` set.i special[0] = 1 set.i special[1] = special[0] push.i ; save the comparand set.i local[0] = 1 set.i local[4] = 0x49 call unit_state(ADT308) ; result -> special[0] (clobbers it) pop.i ; restore comparand -> special[1] cmp.i special[0], special[1] beq -> 0xFEB4 ``` A textbook stack-machine lowering: **push the left operand, evaluate the right, pop, compare.** Tracking the stack through the decode is therefore enough to recover what every site actually tests. ### The evidence it is a stack, not something else | check | result | |---|---| | `push` vs `pop` across all 28 stages | **1877 vs 1877** | | files where the deque underflows or ends unbalanced | **0 of 28** | | Stage 02 `pop.i` sites immediately followed by `cmp.i` | **319 / 319** | | ops immediately preceding a `pop.i` | `call` ×313, `cmp.a` ×6 | Perfect balance with zero underflow across 28 independent files is not something a wrong model produces, and `pop.i` → `cmp.i` at 319/319 makes `pop.i` a reliable marker for a condition site. ## ✅ Result — disc-wide `isl.conditions()` walks the linear stream tracking `special[]`, `local[]` and the stack, then reports each compare with its branch: | | all 28 stages | |---|---| | condition sites | **7 563** | | **LHS honestly unresolved** | **402 — 5.3 %** (CFG dataflow; the linear walk left 756) | | RHS is a plain number | 7 544 — 99.7 % | 🔴 **The first version of this table claimed 0.0 % unresolved. That was wrong** — see *The correction* below. ~11.75 % of the operands it reported were derived from state that leaked across an unconditional jump. **Most-tested predicates disc-wide:** `hp_pct_test` 1955, `unit_state` 1257, `unit_relation` 796, `dist_lt` 450, `request_script_message` 425, `unit_alive` 413, `read_freg` 187. And they read as conditions: ``` 0x032F4 ph1 if unit_alive(TCN105) != 1 -> 0x3388 0x04D70 ph1 if unit_hp_pct(TCN001, Character_Player_Test) != 0 -> 0x51FC 0x2C4E0 ph3 if hp_pct_test(ADT308, 0) != 1 -> 0x2CF8C 0x30790 ph3 if dist_lt(ADT308, TCN000, 15000) != 1 -> 0x307B0 0x33FA0 ph3 if unit_state(ADT308) != 2 -> 0x34030 0x349E0 ph3 if unit_state(ADT308) == 1 -> 0x34A00 ``` `dist_lt(ADT308, TCN000, 15000)` — with the world unit established as 1 metre, that is a **15 km** proximity test. ## ✅ FIXED — and the cause was not what I expected The first version of this listing showed **`end_coroutine`** as the left-hand side of 34 comparisons disc-wide (15 in Stage 02). That is impossible — `end_coroutine` returns no value a script can test — and an impossible output is the bug reporting itself. ### 🔴 The obvious fix is REFUTED The plan recorded here was *"set `special[0]` only for built-ins that write `[phase+164]`"*. That would not have worked: `end_coroutine`'s handler `0x82272624` is ``` addi r11, r0, 1 addi r3, r0, 3 stw r11, 164(r31) ; it DOES write [phase+164] ``` so the filter would have kept it. Checking the handler before writing the filter is what caught this. ### ✅ The real cause: a coroutine boundary `end_coroutine` returns **3**, which *destroys the thread*. Execution does not continue past it — so the instructions that follow it in the **flat** stream belong to a **different routine**, and every value the tracker was carrying is stale. The linear walk that makes this decode possible at all is precisely what walks across that boundary. Resetting the tracker at `end_coroutine`: | A/B over all 28 stages, 7563 sites | | |---|---| | sites whose operands change | **34 — 0.45 %** | | LHS `end_coroutine` before → after | **34 → 0** | | left as an explicit unknown afterwards | **34 — 0.45 %** | **The two counts are equal, so the leak was confined to exactly the sites that displayed the impossible value** — the other 7 529 conditions were never affected. Those 34 now print `` rather than a wrong answer. 🟡 **They are recoverable but not recovered.** The right-hand side of each is still exact; only the left is lost. Resolving them means seeding the tracker at each coroutine **entry** rather than walking in from the previous routine, and the entries are available — `start_coroutine`'s target is staged slot 0. Not done. ## 🟡 Not settled * The **35 unnamed built-ins** still print as `builtinN` — `builtin103` (115 sites), `builtin105` (117) and `builtin16` (132) are the highest-traffic unknowns, and each is now a vtable-slot lookup away. * **Which condition guards each `END_PHASE`.** Every site is readable, but linking a condition to the phase exit it eventually reaches needs the control flow between them, which this listing does not follow. * Only Stage 02's artefact is committed; the other 27 generate from the same command but are not in the tree. ## 🔴 The correction — I fixed the instance, not the class The `end_coroutine` fix above was **too narrow**, and the giveaway was again an impossible output: the listing showed ``` if builtin80(TCT206) == 0 … == 1 … == 2 … == 3 … == 4 … == 5 ``` a six-way switch on a built-in that returns only **1 or 0**. Reading `builtin80`'s body (`0x82268460`) settles that it is not a predicate at all — it allocates a 20-byte object, stamps a vtable `0x820A8CB0`, a magic `0xAB0311BA` and the unit's live object into it, pushes it onto a queue via the same helper `push.i` uses, and returns 1, or 0 when the unit is absent. **It is a command.** Disassembling the site explains it: ``` 01B698 call builtin80(TCT206) 01B6A4 set.i global[76] = 0 01B6B0 jmp -> 0x1B738 01B6B8 jmp -> 0x1B738 01B6C0 cmp.i … <- reached ONLY by a branch from elsewhere ``` Two unconditional jumps sit between the call and the compare. **`op12` is unconditional, so the next instruction is never reached by fall-through** — and the tracker walked straight through it, exactly as it had walked through `end_coroutine`. One is a thread boundary and the other a block boundary, but they are the same defect: a linear walk cannot carry state across a point where control does not flow. | A/B over all 28 stages, 7563 sites | | |---|---| | sites whose operands change once `jmp` also resets | **889 — 11.75 %** | | LHS unresolved, before → after | 34 (0.45 %) → **756 (10.00 %)** | So the earlier "0.0 % unresolved" was not a strong result, it was a **missing check**: the walk always had *some* value to report, and reporting it was the bug. 10 % is the honest figure, and the remaining 90 % is now trustworthy for a reason — the state reaching those sites really does flow there. 🟡 **Recovering the 756 needs real dataflow.** Each is a block entered only by a branch, so its state is the *join* over its actual predecessors — a fixpoint over the CFG, not a linear pass. The branch targets are all known (`[phase+232] + word@+4`), so the CFG is available; the analysis is not written. **Method note worth keeping:** when the same defect appears twice, fix the class. Patching `end_coroutine` alone left 22× more bad sites in place than it removed, and only another impossible-looking output exposed them. ## ✅ Replaced by a CFG dataflow fixpoint — `isl_cfg.py` The linear walk's honest 10 % unknown was a floor imposed by the method, not by the data: a block entered only by a branch has *a* well-defined state, just not one a straight-line pass can see. So the walk is gone, replaced by a worklist fixpoint that joins each block's state over its **actual predecessors** — a value survives only if every predecessor agrees. | over all 28 stages | linear walk | CFG dataflow | |---|---|---| | instructions reached | (all, but with stale state) | **85.0 %** | | condition sites with an unknown LHS | 756 — 10.00 % | **402 — 5.32 %** | | of those, never reached at all | — | 389 | | joined away (predecessors genuinely disagree) | — | **13** | | **sites where both resolve but DISAGREE** | — | **161** | Those 161 are 161 more places the linear walk reported a confident wrong answer, on top of the 889 the `jmp` fix caught. ### ⚠️ Two zero-results that were both my bug The first CFG run reached only **36 %** of instructions and made things *worse* — 35 % unknown against the walk's 10 %. Two causes, and each surfaced as a suspiciously round zero: 1. **The phase bases reach almost nothing.** Most routines are **coroutines** the engine starts from its trigger queue, so they have no static predecessor at all. They must be seeded from every `start_coroutine` target. 2. **The seeding found ZERO entries in a file with 216 `start_coroutine` calls.** The target is staged in *two* steps — `special[0] = imm`, then `local[0] = special[0]` — and I matched only the direct-immediate form. Reachability went 36 % → 64 % → **85 %** as each was fixed. The lesson is the one this corpus keeps re-teaching: *a count that does not move when it should is the bug reporting itself.* Both times I checked because the number looked wrong, not because a test failed. ### 🟡 The 389 that remain are a real limit, not a gap Nothing in the bytecode starts them. They are entered from the **trigger queue at `phase+272`** — by data, not by code — so no purely static analysis reaches them. Resolving those needs the trigger table's contents, which is a separate question.