Sylpheed/docs/re/structures/isl-conditions.md

✅ 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 <unknown: reached after a coroutine boundary> 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.