Sylpheed/docs/re/structures/isl-phase-guards.md

✅ What each phase exit requires — the per-phase clear conditions

This is what the ISL thread was for. BACKLOG.md framed it as "which condition guards each END_PHASE", and with the CFG from isl-conditions it is a graph query rather than new machinery. Artefact: ../data/isl-stage02-phase-guards.txt, generator isl_report.py phase-guards.

🔴 The obvious query is WRONG here — tried first, and it fails quietly

The natural definition of a guard is one successor reaches END_PHASE and the other does not. I implemented that first. It reports, for Stage 02:

phase	1	2	3
"guards" found	1	62	1

and the single condition it finds in phases 1 and 3 is the same one — read_freg(0) < 1200, a timeout. Every objective test is missed.

The reason is the shape of the language. The dominant idiom here is a poll loop: if still-alive: jump back. The loop-back branch reaches the exit too — one iteration later — so neither successor discriminates and the clear condition is invisible to a reachability test. The asymmetric 1 / 62 / 1 is what exposed it; a uniform number would have looked plausible and been wrong.

✅ Dominance has no such blind spot

A condition dominates an exit when every path from an entry to that END_PHASE passes through it — so it is a necessary condition for the phase to end that way. A poll loop's test dominates its own exit, so the idiom that defeats reachability is handled by construction.

Iterative dominators over the CFG, converging in 3 passes, reaching 15 670 of 18 739 instructions (83.6 %).

Practical note: the first run was OOM-killed. 6 743 reachable nodes each carrying a Python set of up to 6 743 elements is ~45 M objects. Integer bitmasks fit in seconds.

✅ What Stage 02 actually requires

Every exit in all three phases is dominated by

unit_hp_pct(TCN001, Character_Player_Test) != 0

— the player's own ship being alive. That is the universal precondition, and it falls out of the analysis rather than being assumed.

Then, per phase:

phase	exit at	necessary conditions beyond the player being alive
1	0x0051E4	random(3) == 0
1	0x005828	hp_pct_test(TCN004, 0) != 1, random(5) == 0
1	0x006010	hp_pct_test(TCN004…), read_freg(0) <= 210, hp_pct_test(ADT102, 0) != 1, ADT107, ADT113
1	0x006260	hp_pct_test(TCN004…), read_freg(0) <= 210, read_freg(0) < 1200
2	0x019934	hp_pct_test(TCT206, 0) != 1
2	0x01AC44	TCT206, builtin7(TCT206, 1, Route_TCT206_p2S, …, 500) == 1, global[4] == 0, global[4] != 1
2	0x0249F0	hp_pct_test(ADN202, 0) != 1, unit_state(TCT206) != 1
3	0x02C1E0	hp_pct_test(TCN004…), global[112] < 4
3	0x02CF74	+ read_freg(0) <= 300, hp_pct_test(ADT301, 0) != 1, ADT302
3	0x02D1DC	+ read_freg(0) < 1200

The hp_pct_test(ADTnnn, 0) != 1 chains are the objective kills; read_freg(0) is a phase clock (<= 210, <= 300 gates, < 1200 the timeout); random(3) and random(5) dominate only the exits that pick one of several closing lines.

🟡 Two exits are unreachable, and that is informative

0x01482C and 0x034A10 — both FORCE_END_PHASE — are reachable from no static entry. That agrees with the independently measured 389 unreachable routines: they are started from the trigger queue at phase+272, by data rather than code. So a purely static reading cannot say what forces those exits.

✅ All 28 stages — ../data/isl-phase-guards-all.txt

isl_report.py <dir> phase-guards runs the whole disc. 177 phase exits, of which only 5 (2.8 %) are reachable from no static entry.

CFG reach, best	Stage 25 — 95.8 %
CFG reach, worst	Stage 26 — 69.5 %
median conditions per exit	~4

✅ An independent cross-check, 6 / 6

The six tutorial stages (S18–S23) each have exactly one exit with exactly one dominating condition, and it is the same one every time:

END_PHASE  <-  builtin104() != 1

isl-builtins.md reached built-in 104 from a completely different direction — call-site usage — and recorded it as "S18–S23 only … followed by wait_s 39/39, preceded by end_coroutine 37/39 … a textbook poll loop". Usage said it was the tutorial's polled test; dominance says it is the tutorial's clear condition. Two unrelated methods, six for six. That the 1.0-condition uniformity turned out to be real rather than a degenerate result is the check worth having run.

Stage 16, the corpus outlier, also reads

mission-script-ssb.md flags S16 as the stage whose script may be compiled C++. Its exits resolve anyway, and sensibly:

ph1  END_PHASE        read_freg(0) < 600 ; player_gauge0_test(0) != 1 ; player_gauge1_test(0) != 1
ph1  FORCE_END_PHASE  builtin141(TCN001, 1, 2, 0, 0, 0, 1000, 5, 100, 100) != 1 ;
                      builtin141(TCN001, 1, 2, 0, -4000, 0, 1000, 5, 100, 100) != 1 ; global[0] != 1

The two builtin141 calls differ in one argument (0 vs -4000), which is the shape of a position or zone test — but it is unread, so it is not named.

🟡 Not settled

• Dominance gives necessary, not sufficient, conditions. ✅ Done — see Necessary vs sufficient below.
• One condition in the phase-2 list still prints <unknown> <= 240 — one of the 402 sites the CFG cannot resolve.
• builtin7 and read_freg's units are unread; read_freg(0) behaves like seconds against the 210 / 300 / 1200 gates but that is not established.

✅ Necessary vs sufficient — the exits now name their TRIGGER

Dominance says the exit cannot happen unless a condition holds. A port also needs the other half: once it holds, does the exit have to happen?

That is a must-reach set — nodes from which an END_PHASE is unavoidable — computed as a least fixpoint: n qualifies when it has successors and all of them qualify. Deliberately conservative: a loop never enters the set, which is the honest answer, because a poll loop reaches its exit only if the polled predicate eventually becomes true, and that is a liveness property, not a graph one.

A dominating condition is then a TRIGGER when the successor it branches to on being satisfied lies in that set.

Over all 28 stages: 732 dominating conditions, 234 of them triggers (31.97 %).

And the split lands exactly where it should. Stage 02's phase-1 objective exit:

precond  unit_hp_pct(TCN001, Character_Player_Test) != 0
precond  hp_pct_test(TCN004, 0) != 1
precond  read_freg(0) <= 210
precond  hp_pct_test(ADT102, 0) != 1
precond  hp_pct_test(ADT107, 0) != 1
precond  hp_pct_test(ADT113, 0) != 1
TRIGGER  hp_pct_test(ADN101, 0) != 1

Six preconditions and one thing that actually fires it — destroying ADN101. That is a sentence a port can implement.

Triggers per exit, 172 reachable exits

triggers	exits
0	42
1	89
2–4	35
5–13	6

The 42 with none are not a failure — they are the exits no branch fires. Stage 02's 0x006260 is one: its last necessary condition is read_freg(0) < 1200, a timeout. Time passing is not a property of the graph, so a graph analysis correctly declines to call it a trigger.

🟡 "The first trigger is the point of no return" — 33 / 41, not a rule

Where an exit has several triggers, the natural reading is that they form a forced tail and the first is where the outcome is decided. Tested on the 41 multi-trigger exits: 33 hold, 8 do not — a precondition appears after a trigger.

The likely cause is that the listing is ordered by file offset, which is not execution order: coroutines and jumps let a lower offset run later. So the reading is a useful heuristic and not a property, and it is recorded that way rather than asserted.