adding comments for scan progress

code/duffle/gen/duffle.macs.h

@@ -50,14 +50,14 @@ WORD_COUNT(mac_gte_load_tri_verts, 18)
 #define mac_insert_ot_tag_f3(...) \
 	shift_lleft( R_T1, R_T1, S_(U4)/2)                        /* T1 = otz * S_(U4) (otz arg is implicit R_T1) */ \
 ,	add_u_self(  R_T1, R_OtBase)                              /* T1 = & OrderingTable[OTZ] */ \
-,	load_word(   R_AT, R_T1,         O_(PolyTag,bf_addr_len)) /* AT = old_ot_head */ \
+,	load_word(   R_AT, R_T1,         O_(PolyTag,code))        /* AT = old_ot_head */ \
 ,	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits) /* V0 = (5 - 1) << 24 = 4 << 24 */ \
 ,	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits))    /* Strip upper 8 bits (length from prev cell) → keep only low 24 */ \
 ,	or_u(        R_AT, R_AT, R_V0)                            /* Merge length */ \
-,	store_word(  R_AT, R_PrimCursor, O_(PolyTag,bf_addr_len)) /* prim->tag = packed(prim_length, old_addr) */ \
+,	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code))        /* prim->tag = packed(prim_length, old_addr) */ \
 ,	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits))    /* AT = (prim_length << 24) | old_addr */ \
 ,	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)) \
-,	store_word(  R_AT, R_T1,         O_(PolyTag,bf_addr_len)) /* OrderingTable[OTZ] = PrimCursor */
+,	store_word(  R_AT, R_T1,         O_(PolyTag,code))        /* OrderingTable[OTZ] = PrimCursor */
 WORD_COUNT(mac_insert_ot_tag_f3, 11)
 
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
@@ -65,14 +65,14 @@ WORD_COUNT(mac_insert_ot_tag_f3, 11)
 #define mac_insert_ot_tag_g4(...) \
 	shift_lleft( R_T1, R_T1, S_(U4)/2)                        /* T1 = otz * S_(U4) (otz arg is implicit R_T1) */ \
 ,	add_u_self(  R_T1, R_OtBase)                              /* T1 = & OrderingTable[OTZ] */ \
-,	load_word(   R_AT, R_T1,         O_(PolyTag,bf_addr_len)) /* AT = old_ot_head */ \
+,	load_word(   R_AT, R_T1,         O_(PolyTag,code))        /* AT = old_ot_head */ \
 ,	load_upper_i(R_V0, (S_(Poly_G4)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits) /* V0 = (9 - 1) << 24 = 8 << 24 */ \
 ,	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits))    /* Strip upper 8 bits (length from prev cell) → keep only low 24 */ \
 ,	or_u(        R_AT, R_AT, R_V0)                            /* Merge length */ \
-,	store_word(  R_AT, R_PrimCursor, O_(PolyTag,bf_addr_len)) /* prim->tag = packed(prim_length, old_addr) */ \
+,	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code))        /* prim->tag = packed(prim_length, old_addr) */ \
 ,	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits))    /* AT = (prim_length << 24) | old_addr */ \
 ,	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)) \
-,	store_word(  R_AT, R_T1,         O_(PolyTag,bf_addr_len)) /* OrderingTable[OTZ] = PrimCursor */
+,	store_word(  R_AT, R_T1,         O_(PolyTag,code))        /* OrderingTable[OTZ] = PrimCursor */
 WORD_COUNT(mac_insert_ot_tag_g4, 11)
 
 #define mac_pack_color_word(off, cmd, r, g, b) \

code/duffle/gp.h

@@ -378,7 +378,7 @@ enum {
 };
 typedef Struct_(PolyTag) {
 	union {
-		U4 bf_addr_len;
+		U4 code;
 		struct {
 			U4 addr: 24;
 			U4 len:  8;

code/duffle/lottes_tape.h

@@ -132,14 +132,14 @@ MipsAtomComp_(ac_gte_load_tri_verts) {
 MipsAtomComp_(ac_insert_ot_tag_f3) {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, R_OtBase),                              // T1 = & OrderingTable[OTZ]
-	load_word(   R_AT, R_T1,         O_(PolyTag,bf_addr_len)), // AT = old_ot_head
+	load_word(   R_AT, R_T1,         O_(PolyTag,code)),        // AT = old_ot_head
 	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits), // V0 = (5 - 1) << 24 = 4 << 24
 	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits)),    // Strip upper 8 bits (length from prev cell) → keep only low 24
 	or_u(        R_AT, R_AT, R_V0),                            // Merge length
-	store_word(  R_AT, R_PrimCursor, O_(PolyTag,bf_addr_len)), // prim->tag = packed(prim_length, old_addr)
+	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code)),        // prim->tag = packed(prim_length, old_addr)
 	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits)),    // AT = (prim_length << 24) | old_addr
 	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)),
-	store_word(  R_AT, R_T1,         O_(PolyTag,bf_addr_len)), // OrderingTable[OTZ] = PrimCursor
+	store_word(  R_AT, R_T1,         O_(PolyTag,code)),        // OrderingTable[OTZ] = PrimCursor
 };
 
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
@@ -147,14 +147,14 @@ MipsAtomComp_(ac_insert_ot_tag_f3) {
 MipsAtomComp_(ac_insert_ot_tag_g4) {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, R_OtBase),                              // T1 = & OrderingTable[OTZ]
-	load_word(   R_AT, R_T1,         O_(PolyTag,bf_addr_len)), // AT = old_ot_head
+	load_word(   R_AT, R_T1,         O_(PolyTag,code)),        // AT = old_ot_head
 	load_upper_i(R_V0, (S_(Poly_G4)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits), // V0 = (9 - 1) << 24 = 8 << 24
 	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits)),    // Strip upper 8 bits (length from prev cell) → keep only low 24
 	or_u(        R_AT, R_AT, R_V0),                            // Merge length
-	store_word(  R_AT, R_PrimCursor, O_(PolyTag,bf_addr_len)), // prim->tag = packed(prim_length, old_addr)
+	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code)),        // prim->tag = packed(prim_length, old_addr)
 	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits)),    // AT = (prim_length << 24) | old_addr
 	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)),
-	store_word(  R_AT, R_T1,         O_(PolyTag,bf_addr_len)), // OrderingTable[OTZ] = PrimCursor
+	store_word(  R_AT, R_T1,         O_(PolyTag,code)),        // OrderingTable[OTZ] = PrimCursor
 };
 
 /* Words: 3; Emits one (cmd|color) word to R_PrimCursor at the given

code/graphics_hello_psyq/hello_gpu.c

@@ -17,19 +17,19 @@ enum {
 };
 
 typedef U4 OrderingTable_Buffer[OrderingTbl_Len];
-typedef def_farray(OrderingTable_Buffer, 2);
+typedef Array_(OrderingTable_Buffer, 2);
 
 typedef B1 PrimitiveBuffer[PrimitiveBuff_Len];
-typedef def_farray(PrimitiveBuffer, 2);
-typedef def_struct(PrimitiveArena) {
+typedef Array_(PrimitiveBuffer, 2);
+typedef Struct_(PrimitiveArena) {
 	A2_PrimitiveBuffer buf;
 	U4                 used;
 };
 
 #define Cube_num_verts 8
-typedef def_farray(V3_S2, Cube_num_verts);
+typedef Array_(V3_S2, Cube_num_verts);
 #define Cube_num_faces 6
-typedef def_farray(V4_S2, Cube_num_faces);
+typedef Array_(V4_S2, Cube_num_faces);
 void ent_cube128_init(A8_V3_S2* verts, A6_V4_S2* faces) {
 	memory_copy(verts, & (A8_V3_S2) {
 		{ -128, -128, -128 },
@@ -40,7 +40,7 @@ void ent_cube128_init(A8_V3_S2* verts, A6_V4_S2* faces) {
 		{  128,  128, -128 },
 		{  128,  128,  128 },
 		{ -128,  128,  128 }
-	}, size_of(A8_V3_S2) );
+	}, S_(A8_V3_S2) );
 	memory_copy(faces, & (A6_V4_S2) {
 		{ 3, 2, 0, 1 },
 		{ 0, 1, 4, 5 },
@@ -48,10 +48,10 @@ void ent_cube128_init(A8_V3_S2* verts, A6_V4_S2* faces) {
 		{ 1, 2, 5, 6 },
 		{ 2, 3, 6, 7 },
 		{ 3, 0, 7, 4 },
-	}, size_of(A6_V4_S2) );
+	}, S_(A6_V4_S2) );
 	return;
 }
-typedef def_struct(Ent_Cube) {
+typedef Struct_(Ent_Cube) {
 	V3_S4 accel;
 	V3_S4 vel;
 	V3_S4 pos;
@@ -62,22 +62,22 @@ typedef def_struct(Ent_Cube) {
 };
 
 #define Floor_num_verts 4
-typedef def_farray(V3_S2, Floor_num_verts);
+typedef Array_(V3_S2, Floor_num_verts);
 #define Floor_num_faces 2
-typedef def_farray(V3_S2, Floor_num_faces);
+typedef Array_(V3_S2, Floor_num_faces);
 void ent_floor_init(A4_V3_S2* verts, A2_V3_S2* faces) {
 	memory_copy(verts, &(A4_V3_S2) {
 		{ -900, 0, -900 },
 		{ -900, 0,  900 },
 		{  900, 0, -900 },
 		{  900, 0,  900 },
-	}, size_of(A8_V3_S2));
+	}, S_(A8_V3_S2));
 	memory_copy(faces, & (A2_V3_S2) {
 		{ 0, 1, 2 },
 		{ 1, 3, 2 },
-	}, size_of(A2_V3_S2));
+	}, S_(A2_V3_S2));
 };
-typedef def_struct(Ent_Floor) {
+typedef Struct_(Ent_Floor) {
 	V3_S4 accel;
 	V3_S4 pos;
 	V3_S4 scale;
@@ -86,7 +86,7 @@ typedef def_struct(Ent_Floor) {
 	A2_V3_S2 faces;
 };
 
-typedef def_struct(SMemory) {
+typedef Struct_(SMemory) {
 	DoubleBuffer            screen_buf;
 	A2_OrderingTable_Buffer ordering_tbl;
 	PrimitiveArena          primitives;
@@ -108,7 +108,7 @@ B1* prim__alloc(U4 type_width, Str8 type_name) {
 	pa->used += type_width;
 	return next;
 }
-#define prim_alloc(type) (type*)prim__alloc(size_of(type), txt( stringify(type)))
+#define prim_alloc(type) (type*)prim__alloc(S_(type), slit( stringify(type)))
 
 void gp_screen_init_c11(DoubleBuffer* screen_buf, S2* active_buf_id)
 {

code/graphics_hello_psyq/hello_gpu.h

@@ -5,8 +5,8 @@
 #	include "duffle/gp.h"
 #endif
 
-typedef def_struct(DrawEnv_Packed) { U4 tag; U4 code[15]; };
-typedef def_struct(DrawEnv) {
+typedef Struct_(DrawEnv_Packed) { U4 tag; U4 code[15]; };
+typedef Struct_(DrawEnv) {
 	Rect_S2 clip_area;
 	A2_S2   drawing_offset;
 	Rect_S2 texture_window;
@@ -17,7 +17,7 @@ typedef def_struct(DrawEnv) {
 	RGB8    initial_bg_color;
 	DrawEnv_Packed dr_env; // reserved
 };
-typedef def_struct(DisplayEnv) {
+typedef Struct_(DisplayEnv) {
 	Rect_S2 display_area;
 	Rect_S2 screen;
 	B1      vinterlace;
@@ -25,9 +25,9 @@ typedef def_struct(DisplayEnv) {
 	B1      pad0;
 	B1      pad1;
 };
-typedef def_farray(DrawEnv,    2);
-typedef def_farray(DisplayEnv, 2);
-typedef def_struct(DoubleBuffer) {
+typedef Array_(DrawEnv,    2);
+typedef Array_(DisplayEnv, 2);
+typedef Struct_(DoubleBuffer) {
 	A2_DrawEnv    draw;
 	A2_DisplayEnv display;
 };
@@ -58,7 +58,7 @@ U4 vsync(U4 mode)     __asm__("VSync");
 
 void draw_orderingtbl(U4* buf) __asm__("DrawOTag");
 
-typedef def_struct(PolyTag) {
+typedef Struct_(PolyTag) {
 	U4   addr: 24;
 	U4   len:  8;
 	RGB8 color;
@@ -106,7 +106,7 @@ typedef def_struct(PolyTag) {
 // #define setLineF4(p)	set_len(p, 6),  set_code(p, 0x4c),(p)->pad = 0x55555555
 // #define setLineG4(p)	set_len(p, 9),  set_code(p, 0x5c),(p)->pad = 0x55555555, (p)->p2 = 0, (p)->p3 = 0
 
-typedef def_struct(Poly_F3) {
+typedef Struct_(Poly_F3) {
 	U4   tag;
 	RGB8 color;
 	B1   code;
@@ -120,14 +120,14 @@ typedef def_struct(Poly_F3) {
 	};
 };
 
-typedef def_struct(Poly_G3) {
+typedef Struct_(Poly_G3) {
 	U4    tag; RGB8 c0; B1 code;
 	V2_S2 p0;  RGB8 c1; B1 pad1;
 	V2_S2 p1;  RGB8 c2; B1 pad2;
 	V2_S2 p2;
 };
 
-typedef def_struct(Poly_F4) {
+typedef Struct_(Poly_F4) {
 	U4   tag;
 	RGB8 color;
 	B1   code;
@@ -142,7 +142,7 @@ typedef def_struct(Poly_F4) {
 	};
 };
 
-typedef def_struct(Poly_G4) {
+typedef Struct_(Poly_G4) {
 	U4    tag; RGB8 c0; B1 code;
 	V2_S2 p0;  RGB8 c1; B1 pad1;
 	V2_S2 p1;  RGB8 c2; B1 pad2;
@@ -150,7 +150,7 @@ typedef def_struct(Poly_G4) {
 	V2_S2 p3;
 };
 
-typedef def_struct(Tile) {
+typedef Struct_(Tile) {
 	U4      tag;
 	RGB8    color;
 	B1      code;
@@ -169,7 +169,7 @@ M3_S2* m3s2_scale      (M3_S2* mat, V3_S4* vec) __asm__("ScaleMatrix");
 // Rotation, Translation, Perspective
 
 S4 rtp_v3s2_raw(V3_S2* vec, S4* xy, S4* pp, S4* flag) __asm__("RotTransPers");
-FI_ S4 rtp_v3s2(V3_S2* vec, V2_S2* xy, A2_S2* pp, S4* flag) { return rtp_v3s2_raw(vec, cast(S4*R_, & xy->x), cast(S4*R_, pp), r_(flag)); }
+FI_ S4 rtp_v3s2(V3_S2* vec, V2_S2* xy, A2_S2* pp, S4* flag) { return rtp_v3s2_raw(vec, C_(S4*R_, & xy->x), C_(S4*R_, pp), r_(flag)); }
 
 S4 rtp_avg_nclip_a3_v3s2_raw(V3_S2* v0, V3_S2* v1, V3_S2* v2, S4* xy1, S4* xy2, S4* xy3, S4* pp, S4* otz, S4* flag) __asm__("RotAverageNclip3");
 FI_  S4 rtp_avg_nclip_a3_v3s2(
@@ -179,8 +179,8 @@ FI_  S4 rtp_avg_nclip_a3_v3s2(
 ){
 	return rtp_avg_nclip_a3_v3s2_raw(
 		v0, v1, v2, 
-		cast(S4*R_, xy0), cast(S4*R_, xy1), cast(S4*R_, xy2),
-		cast(S4*R_, pp),  cast(S4*R_, otz), cast(S4*R_, flag)
+		C_(S4*R_, xy0), C_(S4*R_, xy1), C_(S4*R_, xy2),
+		C_(S4*R_, pp),  C_(S4*R_, otz), C_(S4*R_, flag)
 	);
 }
 
@@ -192,8 +192,8 @@ FI_ S4 rtp_avg_nclip_a4_v3s2(
 ){
 	return rtp_avg_nclip_a4_v3s2_raw(
 		v0, v1, v2, v3,
-		cast(S4*R_, xy0), cast(S4*R_, xy1), cast(S4*R_, xy2), cast(S4*R_, xy3),
-		cast(S4*R_, pp),  cast(S4*R_, otz), cast(S4*R_, flag)
+		C_(S4*R_, xy0), C_(S4*R_, xy1), C_(S4*R_, xy2), C_(S4*R_, xy3),
+		C_(S4*R_, pp),  C_(S4*R_, otz), C_(S4*R_, flag)
 	);
 }
 

readme.md

@@ -6,19 +6,27 @@ A rest from the usual.
 
 ## Dependencies
 
-I will be programming from a Windows 11 machine:
+I will be programming from a Windows 11 machine (may eventually try this on the Steam Deck...):
 ![system_info](./docs/assets/system_info.png)
 
-```ps1
-# not really used yet for scripts (may never)
-scoop install lua
-```
-
 [armips](https://github.com/Kingcom/armips)
 
 * Supports doing bare-metal assembly for the ps1
 * `scoop install armips` or just clone and build..
 
+[luajit-2.1](https://github.com/LuaJIT/LuaJIT.git)
+
+```
+scoop install luajit
+```
+
+* Used for lua scripts
+* Particularly, ps1_meta.lua which is a staged metaprogram pass for the custom C11 Assembly DSL used in this codebase.
+
+[lpeg](https://github.com/roberto-ieru/LPeg.git)
+
+* Lua is slow (even jitted) so this helps.
+
 [pscx-redux](https://github.com/grumpycoders/pcsx-redux/): A collection of tools, research, hardware design, and libraries aiming at development and reverse engineering on the PlayStation 1.
 
 * Used as the runtime sandbox emulated the ps1
@@ -57,3 +65,4 @@ scoop install lua
 ![polys!](./docs/assets/pcsx-redux.main_2025-08-03_20-45-35.png)  
 ![hello_psyq!](./docs/assets/pcsx-redux_2025-08-05_23-01-19.png)
 ![cube!](./docs/assets/pcsx-redux_2025-10-11_03-04-01.png)
+![cube and floor!](./docs/assets/pcsx-redux_2026-07-10_22-47-02.png)

scripts/audit_lua_nesting.lua

@@ -1,5 +1,4 @@
---- audit_lua_nesting.lua — Walk Lua source files and flag any block
---- nesting deeper than 5 levels.
+--- audit_lua_nesting.lua — Walk Lua source files and flag any block nesting deeper than 5 levels.
 ---
 --- Usage:
 ---   luajit scripts/audit_lua_nesting.lua scripts/duffle.lua scripts/ps1_meta.lua
@@ -13,9 +12,8 @@
 ---   - `end`, `until`                                    -> depth -1
 ---   - `else`, `elseif`                                  -> depth unchanged
 ---
---- **Caveats**: doesn't handle string/comment state (will miscount
---- braces inside strings). For our metaprogram files (no embedded
---- code generation), this is acceptable.
+--- **Caveats**: doesn't fully handle string/comment state (will miscount braces inside multi-line strings or block comments). 
+--- For our metaprogram files (no embedded code generation), this is acceptable.
 
 local M = {}
 
@@ -28,17 +26,13 @@ local BLOCK_OPEN = {
     ["repeat"]  = true,
 }
 
-local function is_block_close(token)
-    return token == "end" or token == "until"
-end
+local function is_block_close(token) return token == "end" or token == "until" end
 
 -- (internal) Walk one source file and return a list of
--- {line, depth, token} entries where depth > MAX_NESTING.
+-- {line, depth, token} entries where depth > max_nesting.
 local function audit_file(path, max_nesting)
     local f = io.open(path, "r")
-    if not f then
-        error("Cannot open " .. path)
-    end
+    if not f then error("Cannot open " .. path) end
     local content = f:read("*a")
     f:close()
 
@@ -46,97 +40,93 @@ local function audit_file(path, max_nesting)
     local depth      = 0
     local line       = 1
     local pos        = 1
-    local len   = #content
-    local token_start = 0
+    local src_len    = #content
+    local token_idx  = 0
 
-    local function read_ident_at(p)
-        -- Lua ident: [a-zA-Z_][a-zA-Z0-9_]*
-        local start = p
-        if start > len then return nil end
-        local ch = content:sub(start, start)
-        if not (ch:match("[%a_]")) then return nil end
-        p = p + 1
-        while p <= len do
-            local c = content:sub(p, p)
-            if not (c:match("[%w_]")) then break end
-            p = p + 1
+    local function read_ident_at(start_pos)
+        local ident_start = start_pos
+        if ident_start > src_len then return nil end
+        local first_ch = content:sub(ident_start, ident_start)
+        if not (first_ch:match("[%a_]")) then return nil end
+        local scan = start_pos + 1
+        while scan <= src_len do
+            local ch = content:sub(scan, scan)
+            if not (ch:match("[%w_]")) then break end
+            scan = scan + 1
         end
-        return content:sub(start, p - 1), p
+        return content:sub(ident_start, scan - 1), scan
     end
 
-    local function skip_string_or_comment(p)
-        local ch = content:sub(p, p)
+    -- Skip past a string literal or comment starting at `start_pos`.
+    -- Returns the position just past the construct, or nil if `start_pos`
+    -- is not the start of a string/comment.
+    local function skip_string_or_comment(start_pos)
+        local ch = content:sub(start_pos, start_pos)
         if ch == '"' or ch == "'" then
-            -- String literal: skip to matching end-quote.
-            p = p + 1
-            while p <= len do
-                local c = content:sub(p, p)
+            local scan = start_pos + 1
+            while scan <= src_len do
+                local c = content:sub(scan, scan)
                 if c == "\\" then
-                    p = p + 2
+                    scan = scan + 2
                 elseif c == ch then
-                    p = p + 1
-                    break
+                    return scan + 1
                 else
-                    p = p + 1
+                    scan = scan + 1
                 end
             end
-            return p
-        elseif ch == "-" and content:sub(p + 1, p + 1) == "-" then
-            -- Lua comment: -- to end of line.
-            p = p + 2
-            if content:sub(p, p + 1) == "[[" and content:sub(p + 2, p + 3) == "[" then
+            return src_len + 1
+        elseif ch == "-" and content:sub(start_pos + 1, start_pos + 1) == "-" then
+            local scan = start_pos + 2
+            if content:sub(scan, scan + 1) == "[[" and content:sub(scan + 2, scan + 3) == "[" then
                 -- Long bracket comment [==[ ... ]==]
-                p = p + 2
+                scan = scan + 2
                 local eq = ""
-                while content:sub(p, p) == "=" do
+                while content:sub(scan, scan) == "=" do
                     eq = eq .. "="
-                    p = p + 1
+                    scan = scan + 1
                 end
                 local close_marker = "]" .. eq .. "]"
-                local close_pos = content:find(close_marker, p, true)
+                local close_pos = content:find(close_marker, scan, true)
                 if close_pos then
-                    p = close_pos + #close_marker
+                    return close_pos + #close_marker
                 else
-                    p = len + 1
+                    return src_len + 1
                 end
             else
-                while p <= len and content:sub(p, p) ~= "\n" do p = p + 1 end
+                while scan <= src_len and content:sub(scan, scan) ~= "\n" do scan = scan + 1 end
+                return scan + 1
             end
-            return p
-        elseif ch == "[" and content:sub(p + 1, p + 1) == "[" then
-            -- Long bracket string: [==[ ... ]==]
-            p = p + 2
+        elseif ch == "[" and content:sub(start_pos + 1, start_pos + 1) == "[" then
+            local scan = start_pos + 2
             local eq = ""
-            while content:sub(p, p) == "=" do
+            while content:sub(scan, scan) == "=" do
                 eq = eq .. "="
-                p = p + 1
+                scan = scan + 1
             end
             local close_marker = "]" .. eq .. "]"
-            local close_pos = content:find(close_marker, p, true)
+            local close_pos = content:find(close_marker, scan, true)
             if close_pos then
-                p = close_pos + #close_marker
+                return close_pos + #close_marker
             else
-                p = len + 1
+                return src_len + 1
             end
-            return p
         end
         return nil
     end
 
-    local token_count = 0
-    while pos <= len do
+    while pos <= src_len do
         local ch = content:sub(pos, pos)
         if ch == "\n" then line = line + 1 end
 
         local skip_to = skip_string_or_comment(pos)
         if skip_to then
-            for i = pos, skip_to - 1 do
-                if content:sub(i, i) == "\n" then line = line + 1 end
+            for scan = pos, skip_to - 1 do
+                if content:sub(scan, scan) == "\n" then line = line + 1 end
             end
             pos = skip_to
         elseif ch:match("[%a_]") then
             local tok, next_pos = read_ident_at(pos)
-            token_count = token_count + 1
+            token_idx = token_idx + 1
             if BLOCK_OPEN[tok] then
                 depth = depth + 1
                 if depth > max_nesting then
@@ -172,18 +162,17 @@ end
 if arg and arg[1] then
     local max_nesting = 5
     local files = {}
-    for i = 1, #arg do
-        if arg[i] == "--max" and arg[i + 1] then
-            max_nesting = tonumber(arg[i + 1]) or 5
+    for arg_idx = 1, #arg do
+        if arg[arg_idx] == "--max" and arg[arg_idx + 1] then
+            max_nesting = tonumber(arg[arg_idx + 1]) or 5
         else
-            files[#files + 1] = arg[i]
+            files[#files + 1] = arg[arg_idx]
         end
     end
 
     -- Accept either a directory or a file path. Directory args are
     -- expanded via `dir /b *.lua` (Windows) or `ls *.lua` (Unix).
     local function is_dir(p)
-        -- Try opening it as a file; if that succeeds, it's not a dir.
         local f = io.open(p, "r")
         if f then f:close() return false end
         return true

scripts/duffle.lua

@@ -5,20 +5,15 @@
 ---   - **Character classification** (`is_space`, `is_alpha`, `is_alnum`, `is_digit`, plus the byte-fast `_byte` variants).
 ---   - **String primitives** (`trim`, `dirname`, `basename_no_ext`, `find_byte`).
 ---   - **I/O primitives** (`read_file`, `write_file`, `ensure_dir`).
----   - **C-language scanner** (`skip_ws_and_cmt`, `skip_str_or_cmt`,
----     `read_ident`, `read_parens`, `read_braces`, `read_brackets`,
----     `read_balanced`, `scan_to_char`, `split_top_level_commas`).
+---   - **C-language scanner** (`skip_ws_and_cmt`, `skip_str_or_cmt`, `read_ident`, `read_parens`, `read_braces`, `read_brackets`, `read_balanced`, `scan_to_char`, `split_top_level_commas`).
 ---   - **Word-count loader** (`load_word_counts` for `WORD_COUNT(...)` metadata files).
 ---   - **Line lookup** (`LineIndex` returns an O(log N) `line_of(pos)` closure for source-mapping).
----   - **Domain tables** (`WAVE_CONTEXT_REGS`, `TAPE_ATOM_MACROS`,
----     `GTE_PIPELINE_LATENCY`, `GP0_CMD_SIZE`, `GP0_CMD_BY_SHAPE`,
----     `GP0_MACRO_CONTRIB`, `INSTRUCTION_LATENCY`).
----   - **Process-bootstrap helper** (`setup_package_path` — replaces the 8-line `arg[0]`-resolution boilerplate duplicated across 7 entry scripts)
+---   - **Domain tables** (`WAVE_CONTEXT_REGS`, `TAPE_ATOM_MACROS`, `GTE_PIPELINE_LATENCY`, `GP0_CMD_SIZE`, `GP0_CMD_BY_SHAPE`, `GP0_MACRO_CONTRIB`, `INSTRUCTION_LATENCY`).
+---   - **Process-bootstrap helper** (`setup_package_path`replaces the 8-line `arg[0]`-resolution boilerplate duplicated across 7 entry scripts)
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex.
 --- Lua 5.3 compatible; no `<close>`/`<toclose>`, no `continue`, no
---- 5.4 string.dump improvements. LuaJIT 5.1+extensions model is the
---- primary target.
+--- 5.4 string.dump improvements. LuaJIT 5.1+extensions model is the primary target.
 ---
 --- **No `:match` / `:gmatch` regex use anywhere**; all delimiter-
 --- splitting is hand-rolled or via LPeg (the regex-free PEG library).
@@ -81,30 +76,22 @@ local BYTE_DIGIT_9 = 57       -- '9'
 -- Section -1: Bootstrap (path-setup at module load)
 -- ════════════════════════════════════════════════════════════════════════════
 --
--- When duffle.lua is first loaded (via `dofile` from an entry script
--- or via `require` from a passes script), the code below runs and sets
--- `package.path` + `package.cpath` so subsequent `require`s resolve.
+-- When duffle.lua is first loaded (via `dofile` from an entry script or via `require` from a passes script), 
+-- the code below sruns and sets `package.path` + `package.cpath` so subsequent `require`s resolve.
 -- Idempotent: re-loads just re-set the same paths.
 --
 -- **Entry scripts** trigger this with one line:
---   `local duffle = dofile(arg[0]:match("(.*[/\\])") .. "/../duffle.lua")`
--- which runs this top-level + returns `M`.
+-- `local duffle = dofile(arg[0]:match("(.*[/\\])") .. "/../duffle.lua")` which runs this top-level + returns `M`.
 --
--- **Passes scripts** are loaded via `require("passes.X")` from the
--- entry script; by the time they run, the entry script has already
--- triggered this bootstrap, so the paths are set.
---
--- **Why `git rev-parse`?** Hardcoding paths like
--- `C:\\projects\\Pikuma\\ps1\\...` breaks portability. Git gives us
--- the canonical repo root regardless of where it lives.
+-- **Passes scripts** are loaded via `require("passes.X")` from the entry script; by the time they run, 
+-- the entry script has already triggered this bootstrap, so the paths are set.
 
 --- Resolve the repo root via `git rev-parse --show-toplevel` (cached).
 --- Returns a path with a trailing separator, or nil if not in a git repo.
 --- @return string|nil
 local function find_repo_root()
-	-- Cached in `package.loaded` (process-global) so all 8 entry scripts
-	-- + passes scripts share one git call. Without this, git rev-parse
-	-- runs once per script load = 8 × ~150ms = 1.2s wasted per build.
+	-- Cached in `package.loaded` (process-global) so all 8 entry scripts + passes scripts share one git call.
+	-- Without this, git rev-parse runs once per script load.
 	if package.loaded.__duffle_repo_root__ then return package.loaded.__duffle_repo_root__ end
 	local p = io.popen("git rev-parse --show-toplevel 2>nul")
 	local root
@@ -127,8 +114,7 @@ function M.setup_package_path()
 		os.exit(2)
 	end
 
-	-- From the repo root, derive both `scripts/` and `scripts/passes/`
-	-- so `require("duffle")` AND `require("passes.annotation")` resolve.
+	-- From the repo root, derive both `scripts/` and `scripts/passes/` so `require("duffle")` AND `require("passes.annotation")` resolve.
 	local scripts_dir = repo_root .. "scripts/"
 	local passes_dir  = repo_root .. "scripts/passes/"
 	package.path = scripts_dir .. "?.lua;"
@@ -137,49 +123,45 @@ function M.setup_package_path()
 		.. passes_dir .. "?/init.lua;"
 		.. package.path
 
--- cpath: only needed on Windows for the bundled lpeg.dll. (LPeg
--- is optional -- duffle.lua's `pcall(require, "lpeg")` falls back
--- to hand-rolled scanners if the .dll isn't loadable.)
+-- cpath: only needed on Windows for the bundled lpeg.dll. 
+-- (LPeg is optional -- duffle.lua's `pcall(require, "lpeg")` falls back to hand-rolled scanners if the .dll isn't loadable.)
 	if package.config:sub(1, 1) == "\\" then
 		package.cpath = repo_root .. "toolchain/luajit-2.1/lib/lua/5.1/?.dll;"
 			.. package.cpath
 	end
 end
 
--- NOTE: `M.setup_package_path()` is NOT auto-called here. The entry
--- scripts explicitly `dofile("duffle_paths.lua")` first, which calls
--- `M.setup_package_path()`. The function exists for the helper to use
--- (so the path-setup logic is centralized in duffle.lua).
+-- NOTE: `M.setup_package_path()` is NOT auto-called here. The entry scripts explicitly `dofile("duffle_paths.lua")` first, which calls `M.setup_package_path()`. 
+-- The function exists for the helper to use (so the path-setup logic is centralized in duffle.lua).
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Section 0: LPeg patterns (compiled once at module load)
 -- ════════════════════════════════════════════════════════════════════════════
 --
--- LPeg is a PEG library (no regex). All patterns below are first-class
--- pattern values; they're cheap to build and reuse.
+-- LPeg is a required dependency (PEG library, no regex). 
+-- It's loaded via `package.cpath` (configured by `duffle_paths.lua` to find `toolchain/lpeg/lpeg.dll`).
+-- There's no hand-rolled fallback. The original two-tier design added complexity for a 5-10x speedup that's
+-- only relevant at the high-level scanner stage; the byte-by-byte helpers in Section 1 are sufficient for the classification primitives.
 --
--- Note: lpeg is required lazily because Lua 5.5 may not have it on its
--- cpath at the same location as LuaJIT. We attempt the require and fall
--- back to the hand-rolled implementations if it fails.
-
+-- If the require fails, fail loud with an actionable message. The build script (`update_deps.ps1`) builds lpeg.dll into `toolchain/lpeg/`; 
+-- if it's missing, run `update_deps.ps1`.
 local lpeg_ok, lpeg = pcall(require, "lpeg")
-local lpeg_lib = nil
-local lpeg_alpha_pat, lpeg_alnum_pat, lpeg_ident_pat
-local lpeg_str_or_cmt_pat, lpeg_ws_and_cmt_pat
-local lpeg_scan_to_target_pat  -- generic "anything but target or balanced group" matcher
-
-if lpeg_ok then
-	lpeg_lib = lpeg
+if not lpeg_ok then
+	io.stderr:write("[duffle] require('lpeg') failed: ", lpeg, "\n")
+	io.stderr:write("[duffle] lpeg.dll not found on package.cpath.\n")
+	io.stderr:write("[duffle] Run 'scripts/update_deps.ps1' to build it into toolchain/lpeg/.\n")
+	os.exit(1)
+end
 local P, S, R = lpeg.P, lpeg.S, lpeg.R
 
 -- Character class patterns
 local alpha_pat  = R("AZ", "az") + P("_")
 local digit_pat  = R("09")
-	lpeg_alnum_pat = alpha_pat + digit_pat
+local lpeg_alnum_pat  = alpha_pat + digit_pat
 
 -- Identifier: alpha followed by zero+ alnum. Capture as a string.
-	lpeg_alpha_pat = alpha_pat
-	lpeg_ident_pat = lpeg.C(alpha_pat * lpeg_alnum_pat^0)
+local lpeg_alpha_pat = alpha_pat
+local lpeg_ident_pat = lpeg.C(alpha_pat * lpeg_alnum_pat^0)
 
 -- String literal: "..." with backslash escapes.
 local lpeg_str_pat = P('"') * (P(1) - S('"\\') + P('\\') * P(1))^0 * P('"')
@@ -190,20 +172,17 @@ if lpeg_ok then
 -- Block comment: /* ... */ (no nesting per C standard).
 local lpeg_block_cmt_pat = P("/*") * (P(1) - P("*/"))^0 * P("*/")
 -- String or comment (any of the four forms).
-	lpeg_str_or_cmt_pat = lpeg_str_pat + lpeg_chr_pat + lpeg_line_cmt_pat + lpeg_block_cmt_pat
+local lpeg_str_or_cmt_pat = lpeg_str_pat + lpeg_chr_pat + lpeg_line_cmt_pat + lpeg_block_cmt_pat
 
 -- Whitespace + comment skipper: zero+ (whitespace run | string | comment).
 local ws_pat = S(" \t\n\r\v\f")
-	lpeg_ws_and_cmt_pat = (ws_pat + lpeg_str_or_cmt_pat)^0
+local lpeg_ws_and_cmt_pat = (ws_pat + lpeg_str_or_cmt_pat)^0
 
 -- Generic "skip until target, but step over balanced groups" matcher.
 -- Used by scan_to_char for non-ident / non-bracket chars.
 -- We accept any single char except the target.
 -- The balanced-group stepping is handled by the caller (via read_balanced).
-	lpeg_scan_to_target_pat = function(target)
-		return (P(1) - P(target))^0
-	end
-end
+local lpeg_scan_to_target_pat = function(target) return (P(1) - P(target))^0  end
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Section 1: character classification (byte-based for hot loops)
@@ -213,14 +192,10 @@ end
 --   is_space(c), is_alpha(c), etc. — accept a single-char STRING (legacy)
 --   is_space_byte(b), is_alpha_byte(b), etc. — accept a single-byte INTEGER
 --
--- The byte-based versions are 5-10x faster in tight loops because they
--- avoid the string allocation per s:sub(i, i) call.
+-- The byte-based versions are 5-10x faster in tight loops because they avoid the string allocation per s:sub(pos, pos) call.
 
 -- Whitespace characters per C locale.
-function M.is_space_byte(b)
-	return b == BYTE_SPACE or b == BYTE_TAB or b == BYTE_NEWLINE
-		or b == BYTE_CR or b == BYTE_VT  or b == BYTE_FF
-end
+function M.is_space_byte(b) return b == BYTE_SPACE or b == BYTE_TAB or b == BYTE_NEWLINE or b == BYTE_CR or b == BYTE_VT  or b == BYTE_FF end
 
 -- Letters (a-z, A-Z) and underscore.
 function M.is_alpha_byte(b)
@@ -261,10 +236,8 @@ function M.is_alnum(c) return M.is_alpha(c) or M.is_digit(c) end
 
 -- Trim leading and trailing whitespace from a string.
 function M.trim(s)
-	local a = 1
-	while a <= #s and M.is_space_byte(s:byte(a)) do a = a + 1 end
-	local b = #s
-	while b >= a and M.is_space_byte(s:byte(b)) do b = b - 1 end
+	local a = 1;  while a <= #s and M.is_space_byte(s:byte(a)) do a = a + 1 end
+	local b = #s; while b >= a  and M.is_space_byte(s:byte(b)) do b = b - 1 end
 	return s:sub(a, b)
 end
 
@@ -314,31 +287,27 @@ end
 function M.read_file(path)
 	local  f = io.open(path, "r")
 	if not f then error("Cannot open " .. path) end
-	local content = f:read("*a")
-	f:close()
+	local content = f:read("*a"); f:close()
 	return content
 end
 
 function M.write_file(path, content)
 	local  f = io.open(path, "w")
 	if not f then error("Cannot write " .. path) end
-	f:write(content)
-	f:close()
+	f:write(content); f:close()
 end
 
--- Cache of directories already verified to exist in this process. Each
--- ensure_dir() call may otherwise spawn a `cmd.exe mkdir` (50-100ms
--- per call on Windows) — calling it inside per-source loops added 1.5+
--- seconds to the report pass. Cache makes ensure_dir idempotent within
--- the process lifetime (safe across passes; the dir state doesn't change).
+-- Cache of directories already verified to exist in this process.
+-- Each ensure_dir() call may otherwise spawn a `cmd.exe mkdir` (50-100ms per call on Windows) — calling it inside per-source loops added 1.5+
+-- seconds to the report pass. Cache makes ensure_dir idempotent within the process lifetime.
+-- (safe across passes; the dir state doesn't change).
 local _ensured_dirs = {}
 
 function M.ensure_dir(path)
 	if _ensured_dirs[path] then return end
 	_ensured_dirs[path] = true
 	local is_win = package.config:sub(1, 1) == "\\"
-	os.execute(is_win and ('if not exist "' .. path .. '" mkdir "' .. path .. '"')
-				  or ('mkdir -p "' .. path .. '" 2>/dev/null'))
+	os.execute(is_win and ('if not exist "' .. path .. '" mkdir "' .. path .. '"') or ('mkdir -p "' .. path .. '" 2>/dev/null'))
 end
 
 -- Test helper: clear the cache (used by tests + between process runs).
@@ -349,93 +318,33 @@ function M._reset_ensured_dirs() _ensured_dirs = {} end
 -- Section 4: C-language scanner primitives
 -- ════════════════════════════════════════════════════════════════════════════
 
--- LPeg-backed skipper when LPeg is available, hand-rolled fallback otherwise.
--- Returns position just past the construct, or `i` unchanged if no
--- string/comment starts at position i.
-function M.skip_str_or_cmt(s, i)
-	if lpeg_ok then
-		local new_pos = lpeg.match(lpeg_str_or_cmt_pat, s, i)
-		if new_pos then return new_pos end
-		return i
-	end
--- Hand-rolled fallback (kept for builds where LPeg isn't available).
-	local c = s:byte(i)
-	if c == BYTE_DQUOTE or c == BYTE_SQUOTE then  -- '"' or '\''
-		i = i + 1
-		while i <= #s do
-			local b = s:byte(i)
-			if b == BYTE_BACKSLASH then i = i + 2  -- '\\'
-			elseif b == c then return i + 1
-			else i = i + 1 end
-		end
-		return #s + 1
-	elseif c == BYTE_SLASH then  -- '/'
-		local nx = s:byte(i + 1)
-		if nx == BYTE_SLASH then  -- '//'
-			while i <= #s and s:byte(i) ~= BYTE_NEWLINE do i = i + 1 end
-			return i
-		elseif nx == BYTE_STAR then  -- '/*'
-			i = i + 2
-			while i <= #s - 1 do
-				if s:byte(i) == BYTE_STAR and s:byte(i + 1) == BYTE_SLASH then  -- '*/'
-					return i + 2
-				end
-				i = i + 1
-			end
-			return #s + 1
-		end
-	end
-	return i
+-- Skip a string or C-style comment starting at position `pos`.
+-- Returns the position just past the construct, or `pos` unchanged if no string/comment starts there. LPeg-backed.
+function M.skip_str_or_cmt(s, pos)
+	return lpeg.match(lpeg_str_or_cmt_pat, s, pos) or pos
 end
 
--- Skip whitespace AND C-style comments starting at position i.
--- LPeg-backed when available; ~5-10x faster than the hand-rolled version.
-function M.skip_ws_and_cmt(s, i)
-	if lpeg_ok then
-		local new_pos = lpeg.match(lpeg_ws_and_cmt_pat, s, i)
-		if new_pos then return new_pos end
-		return i
-	end
-	-- Hand-rolled fallback.
-	local len = #s
-	while i <= len do
-		if M.is_space_byte(s:byte(i)) then
-			i = i + 1
-		else
-			local nx = M.skip_str_or_cmt(s, i)
-			if nx > i then i = nx else break end
-		end
-	end
-	return i
+-- Skip whitespace AND C-style comments starting at position `pos`.
+-- LPeg-backed; ~5-10x faster than a hand-rolled byte-by-byte walker.
+function M.skip_ws_and_cmt(s, pos)
+	return lpeg.match(lpeg_ws_and_cmt_pat, s, pos) or pos
 end
 
--- Read a C-style identifier (alpha followed by zero+ alnum) starting at
--- position i. Returns the identifier string + the position just past it,
--- or nil + i if no identifier starts here.
-function M.read_ident(s, i)
-	if lpeg_ok then
-		local result = lpeg.match(lpeg_ident_pat, s, i)
-		if result then return result, i + #result end
-		return nil, i
-	end
-	-- Hand-rolled fallback.
-	if not M.is_alpha_byte(s:byte(i)) then return nil, i end
-	local a = i
-	i = i + 1
-	while i <= #s and M.is_alnum_byte(s:byte(i)) do i = i + 1 end
-	return s:sub(a, i - 1), i
+-- Read a C-style identifier (alpha followed by zero+ alnum) starting at position `pos`. 
+-- Returns the identifier string + the position just past it, or nil + pos if no identifier starts here. LPeg-backed.
+function M.read_ident(s, pos)
+	local result = lpeg.match(lpeg_ident_pat, s, pos)
+	if result then return result, pos + #result end
+	return nil, pos
 end
 
--- Read a balanced-delimited group (parens, braces, or brackets) starting
--- at position i. Returns the inner content (between the delimiters) +
--- the position just past the closing delimiter, or nil + i if `s[i]`
--- isn't `open_char`.
---
--- (Hand-rolled; the depth counting makes pure LPeg awkward here.)
-function M.read_balanced(s, open_char, close_char, i)
+-- Read a balanced-delimited group (parens, braces, or brackets) starting at position `pos`.
+-- Returns the inner content (between the delimiters) + the position
+-- just past the closing delimiter, or nil + pos if `s[pos]` isn't `open_char`.
+function M.read_balanced(s, open_char, close_char, pos)
 	local open_byte = open_char:byte()
-	if s:byte(i) ~= open_byte then return nil, i end
-	local pos   = i + 1
+	if s:byte(pos) ~= open_byte then return nil, pos end
+	pos = pos + 1
 	local len   = #s
 	local depth = 1
 	local a     = pos
@@ -450,19 +359,19 @@ function M.read_balanced(s, open_char, close_char, i)
 			pos = pos + 1
 		else
 			local nx = M.skip_str_or_cmt(s, pos)
-			pos = (nx > pos) and nx or (pos + 1)
+			if nx > pos then pos = nx else pos = pos + 1 end
 		end
 	end
 	return s:sub(a, pos - 1), pos + 1
 end
 
 -- Convenience specializations of read_balanced.
-M.read_parens   = function(s, i) return M.read_balanced(s, "(", ")", i) end
-M.read_braces   = function(s, i) return M.read_balanced(s, "{", "}", i) end
-M.read_brackets = function(s, i) return M.read_balanced(s, "[", "]", i) end
+M.read_parens   = function(s, pos) return M.read_balanced(s, "(", ")", pos) end
+M.read_braces   = function(s, pos) return M.read_balanced(s, "{", "}", pos) end
+M.read_brackets = function(s, pos) return M.read_balanced(s, "[", "]", pos) end
 
--- Scan forward from position `start` until we find a specific single byte
--- `target`, transparently stepping over balanced parens/braces/brackets.
+-- Scan forward from position `start` until we find a specific single byte `target`, 
+-- transparently stepping over balanced parens/braces/brackets.
 -- Returns the position of `target`, or nil if not found.
 function M.scan_to_char(s, target, start)
 	local target_byte = target:byte()
@@ -484,23 +393,18 @@ end
 -- Split a brace-body into top-level comma-separated tokens. Honors nested
 -- parens/braces/brackets and skips strings/comments.
 --
--- FIX (2026-07-09): split at top-level NEWLINES and SEMICOLONS too, AND
--- emit a token break after a top-level comment/string. Previous behavior
--- glued the macro call after a comment into the same token, so
--- `word_count_of_token` only saw the leading ident (often nil after
--- stripping the comment), undercounting the body. See Phase 1 of the
--- branch-offset regression investigation. Pure-comment / pure-string
--- chunks (which now appear between real statements) are filtered out so
--- they contribute 0 words instead of 1.
+-- FIX (2026-07-09): split at top-level NEWLINES and SEMICOLONS too, AND emit a token break after a top-level comment/string. 
+-- Previous behavior glued the macro call after a comment into the same token, so `word_count_of_token` only saw the 
+-- leading ident (often nil after stripping the comment), undercounting the body. See Phase 1 of the branch-offset regression  investigation. 
+-- Pure-comment / pure-string chunks (which now appear between real statements) are filtered out so they contribute 0 words instead of 1.
 function M.split_top_level_commas(body)
 	local tokens      = {}
 	local pos         = 1
 	local body_len    = #body
 	local token_start = 1
 
-	-- True iff `chunk` contains any non-whitespace, non-comment, non-string
-	-- content (i.e., real token material). Walks through ws + comments
-	-- individually so a chunk like "  /* trailing */ shift_lleft(...)"
+	-- True iff `chunk` contains any non-whitespace, non-comment, non-string content 
+	-- (i.e., real token material). Walks through ws + comments individually so a chunk like "  /* trailing */ shift_lleft(...)" 
 	-- is correctly classified as having real content (the macro call).
 	local function has_real_content(chunk)
 		local scan = 1
@@ -527,22 +431,14 @@ function M.split_top_level_commas(body)
 				if has_real_content(chunk) then
 					tokens[#tokens + 1] = chunk
 				elseif #tokens > 0 then
-					-- Pure comment/string chunk at top level (no
-					-- preceding instruction content within this chunk).
-					-- APPEND it to the LAST token so emit-context
-					-- callers (components.lua build_component_lines)
-					-- can convert `// trailing comment` to `/* */`
-					-- and emit it with the macro body. For word
-					-- counting, count_token_words only inspects the
-					-- leading ident, so a trailing comment doesn't
-					-- affect the count.
+					-- Pure comment/string chunk at top level (no preceding instruction content within this chunk).
+					-- APPEND it to the LAST token so emit-context callers (components.lua build_component_lines) 
+					-- can convert `// trailing comment` to `/* */` and emit it with the macro body.
+					-- For word counting, count_token_words only inspects the leading ident, so a trailing comment doesn't affect the count.
 					--
-					-- This is the second-half fix to commit 98e27c2:
-					-- the first fix correctly broke top-level comments
-					-- off from the NEXT statement (fixing macro-call
-					-- word counts); this fix preserves them on the
-					-- PREVIOUS statement (restoring the comments in
-					-- the emitted .macs.h output).
+					-- This is the second-half fix to commit 98e27c2: the first fix correctly broke top-level comments 
+					-- off from the NEXT statement (fixing macro-call word counts); 
+					-- This fix preserves them on the PREVIOUS statement (restoring the comments in the emitted .macs.h output).
 					tokens[#tokens] = tokens[#tokens] .. chunk
 				end
 			end
@@ -665,34 +561,23 @@ M.TAPE_ATOM_MACROS = {
 
 -- GTE pipeline-fill latency table (static-analysis Phase 1).
 --
--- For each `gte_cmdw_*` macro in code/duffle/gte.h, the minimum number
--- of consecutive COP2 "nop" words that MUST appear before any other
--- COP2 read or non-nop instruction (so the GTE pipeline latency is
--- fully retired).  Latencies are sourced from the doxygen comments
--- in gte.h (e.g. `* @brief Rotate, Translate and Perspective Triple
--- (23 cycles)` with body `Two nop words fill the COP2 pipeline
--- latency`).
+-- For each `gte_cmdw_*` macro in code/duffle/gte.h, the minimum number of consecutive COP2 "nop" words that MUST appear 
+-- before any other COP2 read or non-nop instruction (so the GTE pipeline latency is fully retired). 
+-- Latencies are sourced from the doxygen comments in gte.h 
+-- (e.g. `* @brief Rotate, Translate and Perspective Triple (23 cycles)` with body `Two nop words fill the COP2 pipeline latency`).
 --
--- The check (`scripts/passes/static_analysis.lua ::
--- check_gte_pipeline_fill`) walks each atom body, counts the
--- consecutive nop words after every `gte_cmdw_*` invocation, and
--- reports a finding if the count is below this minimum.  Aliases
--- are dereferenced before lookup (gté_cmdw_rtps_alias ->
--- gte_cmdw_rtps -> 2).
+-- The check (`scripts/passes/static_analysis.lua :: check_gte_pipeline_fill`) walks each atom body, 
+-- counts the consecutive nop words after every `gte_cmdw_*` invocation, and reports a finding if the count is below this minimum.  
+-- Aliases are dereferenced before lookup (gté_cmdw_rtps_alias -> gte_cmdw_rtps -> 2).
 -- 
--- Values verified against PSX-SPX gte.txt (rtpt 23cy / 8cy per divide
--- => 2 nops; nclip 8cy => 2 nops; avsz3/avsz4 14cy => 2 nops; op
--- single-cycle atomic => 0 nops; mvmva 8cy matrix-vector => 2 nops).
+-- Values verified against PSX-SPX gte.txt (rtpt 23cy / 8cy per divide => 2 nops; nclip 8cy => 2 nops; avsz3/avsz4 14cy => 2 nops; 
+-- op single-cycle atomic => 0 nops; mvmva 8cy matrix-vector => 2 nops).
 M.GTE_PIPELINE_LATENCY = {
-	-- Minimum number of consecutive `nop` words that must appear
-	-- IMMEDIATELY BEFORE a `gte_cmdw_<X>` invocation -- to retire
-	-- any preceding `lwc2` / `swc2` / pre-existing C2 state writes
-	-- before the GTE pipeline starts reading from V0/V1/V2 or
-	-- MAC0..3 / OTZ / IR0..3 at the command's issue cycle.
-	--
-	-- Values are from the doxygen comments in code/duffle/gte.h and
-	-- cross-checked against PSX-SPX `geometrytransformationenginegte.md`:
+	-- Minimum number of consecutive `nop` words that must appear IMMEDIATELY BEFORE a `gte_cmdw_<X>` invocation 
+	-- to retire any preceding `lwc2` / `swc2` / pre-existing C2 state writes before the GTE pipeline starts reading 
+	-- from V0/V1/V2 or MAC0..3 / OTZ / IR0..3 at the command's issue cycle.
 	--
+	-- Values are from the doxygen comments in code/duffle/gte.h and cross-checked against PSX-SPX `geometrytransformationenginegte.md`:
 	--   cmd      cycles  min pre-nops  rationale
 	--   rtps        14      2         8c per perspective divide + 6c for IR1..4 + mac write
 	--   rptt        22      2         3x rtps worth of pipeline depth
@@ -702,22 +587,16 @@ M.GTE_PIPELINE_LATENCY = {
 	--   mvmva        8      2         IR1..4 write + matrix work
 	--   op           5      0         output to MAC0 only (atomic 5c calc)
 	--
-	-- The `gte_rtpt()` / `gte_nclip()` / `gte_avsz3()` wrapper macros in
-	-- gte.h emit the pre-cmd nops internally (asm_words(nop, nop, ...)),
-	-- but THOSE WRAPPERS ARE NOT USED INSIDE ATOM BODIES in this
-	-- codebase. Every MipsAtom_(name) body uses raw `nop2,
-	-- gte_cmdw_<X>, ...` form instead -- that `nop2,` is the pre-fill
-	-- this check validates. So values here must reflect the source-level
-	-- convention, NOT the wrapper-internal pre-fill (which is invisible
-	-- at the source level).
+	-- The `gte_rtpt()` / `gte_nclip()` / `gte_avsz3()` wrapper macros in gte.h emit the pre-cmd nops internally (asm_words(nop, nop, ...)), 
+	-- but THOSE WRAPPERS ARE NOT USED INSIDE ATOM BODIES in this codebase. 
+	-- Every MipsAtom_(name) body uses raw `nop2, gte_cmdw_<X>, ...` form instead -- that `nop2,` is the pre-fill this check validates. 
+	-- So values here must reflect the source-level convention, NOT the wrapper-internal pre-fill (which is invisible at the source level).
 	--
-	-- Existing clean-atom bodies (cube_g4_face, floor_f3_face,
-	-- diag_gte) all emit `nop2,` before every `gte_cmdw_<X>` (which
-	-- matches values >= 2). The check passes them all.
+	-- Existing clean-atom bodies (cube_g4_face, floor_f3_face, diag_gte) all emit `nop2,` before every `gte_cmdw_<X>` (which matches values >= 2).
+	-- The check passes them all.
 	--
-	-- Aliases are listed separately because source code may use either
-	-- the alias or the canonical name. The check looks up the EXACT
-	-- macro text, so both forms must be in the table.
+	-- Aliases are listed separately because source code may use either the alias or the canonical name.
+	-- The check looks up the EXACT macro text, so both forms must be in the table.
 
 	-- Canonical macros (from code/duffle/gte.h)
 	["gte_cmdw_rtps"]   = 2,
@@ -764,8 +643,7 @@ M.GP0_CMD_SIZE = {
 }
 
 -- Shape suffix (after `ac_format_` / `mac_format_` prefix) -> GP0 cmd byte.
--- Lets the static-analysis check derive the cmd byte from a macro name
--- like `mac_format_g4_color` -> `g4` -> 0x38 -> 9 expected words.
+-- Lets the static-analysis check derive the cmd byte from a macro name like `mac_format_g4_color` -> `g4` -> 0x38 -> 9 expected words.
 M.GP0_CMD_BY_SHAPE = {
 	["f3"]  = 0x20, ["ft3"] = 0x24,
 	["f4"]  = 0x28, ["ft4"] = 0x2C,
@@ -773,11 +651,9 @@ M.GP0_CMD_BY_SHAPE = {
 	["g4"]  = 0x38, ["gt4"] = 0x3C,
 }
 
--- Per-macro prim-buffer contribution (NOT .text instruction count --
--- this is "how many 32-bit words does this macro write to the primitive
--- being built in main RAM"). Sum across `mac_format_X_color` +
--- `mac_gte_store_X_post_*` + `mac_insert_ot_tag_X` calls in an atom body
--- must equal GP0_CMD_SIZE[GP0_CMD_BY_SHAPE[shape]].
+-- Per-macro prim-buffer contribution 
+-- (NOT .text instruction count this is "how many 32-bit words does this macro write to the primitive being built in main RAM"). 
+-- Sum across `mac_format_X_color` + `mac_gte_store_X_post_*` + `mac_insert_ot_tag_X` calls in an atom body must equal GP0_CMD_SIZE[GP0_CMD_BY_SHAPE[shape]].
 M.GP0_MACRO_CONTRIB = {
 	["mac_format_f3_color"]                         = 1,
 	["mac_format_g3_color"]                         = 3,
@@ -790,26 +666,21 @@ M.GP0_MACRO_CONTRIB = {
 	["mac_insert_ot_tag_g4"]                        = 1,
 }
 
--- Per-macro cycle cost (best-case, no stalls). Used by the static-analysis
--- `count_atom_cycles` pass (Phase 3) to emit per-atom cycle budgets. The
--- counts cover the EXPANDED instruction sequence the macro emits (NOT just
--- the token it appears as in source). For example:
---
+-- Per-macro cycle cost (best-case, no stalls). Used by the static-analysis `count_atom_cycles` pass (Phase 3) to emit per-atom cycle budgets. 
+-- The counts cover the EXPANDED instruction sequence the macro emits (NOT just the token it appears as in source).
+-- For example: 
 --   mac_pack_color_word(off, cmd, r, g, b) emits:
 --     load_upper_i(R_AT, (cmd << 8) | b)        -- 1 cycle
 --     or_i_self(R_AT, (g << 8) | r)             -- 1 cycle
 --     store_word(R_AT, R_PrimCursor, off)       -- 1 cycle
 --                                              = 3 cycles total
 --
---   mac_yield emits a control-transfer sequence (load_word, add_ui_self,
---   jump_reg, nop) which "yields control" -- the atom body's cycle budget
---   doesn't include the yield's cost (we model it as 0; runtime cost
---   becomes part of the NEXT atom's prologue).
+--   mac_yield emits a control-transfer sequence (load_word, add_ui_self, jump_reg, nop) 
+--   which "yields control" the atom body's cycle budget doesn't include the yield's cost (we model it as 0; 
+--   runtime cost becomes part of the NEXT atom's prologue).
 --
--- GTE command values are the GTE instruction's intrinsic cycles (the
--- latency AFTER any pre-cmd `nop2` has retired). When the source emits
--- `nop2, gte_cmdw_X` the nops' cycles are added separately (1+1) plus
--- the gte_cmdw_X value here:
+-- GTE command values are the GTE instruction's intrinsic cycles (the latency AFTER any pre-cmd `nop2` has retired).
+-- When the source emits `nop2, gte_cmdw_X` the nops' cycles are added separately (1+1) plus the gte_cmdw_X value here:
 --   rtpt  = 21 + 2 nops = 23 total cycles  (matches PSX-SPX)
 --   rtps  = 12 + 2 nops = 14 total
 --   nclip =  6 + 2 nops = 8 total
@@ -935,14 +806,9 @@ M.INSTRUCTION_LATENCY = {
 	["atom_writes"]         = 0,
 }
 
--- Default cycle cost for unknown macros. The static-analysis pass adds 1
--- cycle per unknown token and emits a "new macro; update INSTRUCTION_LATENCY"
+-- Default cycle cost for unknown macros. 
+-- The static-analysis pass adds 1 cycle per unknown token and emits a "new macro; update INSTRUCTION_LATENCY"
 -- advisory so the cycle budget stays accurate as the codebase grows.
 M.UNKNOWN_INSTRUCTION_CYCLES = 1
 
--- Expose the lpeg_ok flag so callers can detect the LPeg-back path.
--- True when LPeg was successfully required and the patterns above were
--- compiled at module load time. False when running in fallback mode.
-M.lpeg_ok = lpeg_ok
-
 return M

scripts/duffle_paths.lua

@@ -1,63 +1,43 @@
---- duffle_paths.lua — Single-line bootstrap helper for the tape-atom
---- Lua scripts.
----
---- Each entry script (ps1_meta.lua, word_count_eval.lua, and the 5
---- passes/*.lua files) starts with:
+--- duffle_paths.lua — Single-line bootstrap helper for the tape-atom Lua scripts.
 ---
+--- Each entry script (ps1_meta.lua, word_count_eval.lua, and the 5 passes/*.lua files) starts with:
 ---   ```lua
 ---   local duffle = dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
 ---   ```
----
---- That single line: (a) locates this helper via `arg[0]`, (b) loads
---- it (which sets `package.path` + `package.cpath` via `git rev-parse`),
+--- That single line: (a) locates this helper via `arg[0]`, 
+--- (b) loads it (which sets `package.path` + `package.cpath` via `git rev-parse`),
 --- (c) returns the `M` table (a wrapper around the setup function). 
---- After this line, `require("duffle")` and `require("passes.X")` both
---- resolve normally.
----
---- **Why a helper instead of inline?**
----   - The 8-line path-setup boilerplate was duplicated across 7 entry
----     scripts (one per file). Single source of truth here.
----   - Mirrors the build script's pattern in `build_psyq.ps1`:
----     `$path_root = split-path -Path $PSScriptRoot -Parent;` then
----     derive everything from there.
----
---- **Why `git rev-parse --show-toplevel`?**
---- Hardcoding `C:\\projects\\Pikuma\\ps1\\...` breaks portability. Git
---- gives us the canonical repo root regardless of where the repo lives
---- on disk.
+--- After this line, `require("duffle")` and `require("passes.X")` both resolve normally.
 
 local M = {}
 
--- Cache key for the repo root. Stored in `package.loaded` (process-
--- global) so all 8 entry scripts + passes scripts share one git call.
--- Without this cache, `git rev-parse --show-toplevel` runs once per
--- script load = 8 × ~150ms = 1.2s wasted per build on Windows.
+-- Cache key for the repo root. Stored in `package.loaded` (process-global) so all 8 entry scripts + passes scripts share one git call.
+-- Without this cache, `git rev-parse --show-toplevel` runs once per script load.
 local CACHE_KEY = "__duffle_repo_root__"
 
 --- Resolve the repo root via git (cached after first call).
---- Returns a normalized path with a trailing forward-slash, or nil
---- if not in a git repo.
+--- Returns a normalized path with a trailing forward-slash, or nil if not in a git repo.
 --- @return string|nil
 local function find_repo_root()
 	if package.loaded[CACHE_KEY] then return package.loaded[CACHE_KEY] end
 	local p = io.popen("git rev-parse --show-toplevel 2>nul")
 	local root
-	if p then
-		root = p:read("*l")
-		p:close()
-	end
+	if p then root = p:read("*l"); p:close() end
 	if not root or root == "" then return nil end
-	-- Normalize to forward slashes (Windows accepts both, but mixed
-	-- `\` + `/` confuses LuaJIT's file APIs).
+	-- Normalize to forward slashes (Windows accepts both, but mixed `\` + `/` confuses LuaJIT's file APIs).
 	root = root:gsub("\\", "/")
 	if not root:match("/$") then root = root .. "/" end
 	package.loaded[CACHE_KEY] = root
 	return root
 end
 
---- Set `package.path` (for `require("duffle")` + `require("passes.X")`)
---- and `package.cpath` (for `lpeg.dll` on Windows).
---- Idempotent: safe to call multiple times (just re-sets the same paths).
+--- Set `package.path` (for `require("duffle")` + `require("passes.X")`) and
+--- `package.cpath` (for `lpeg.dll`).
+---
+--- This script does NOT touch the OS environment: no `os.setenv`, no `os.putenv`, no `$PATH` mods. 
+--- It just sets `package.path` and `package.cpath` (the standard Lua way to register module search dirs). 
+--- lpeg is built by `update_deps.ps1` to `toolchain/lpeg/`, 
+--- which we wire into `package.cpath` here (so `require("lpeg")` from `duffle.lua` resolves without any global state).
 function M.setup()
 	local repo_root = find_repo_root()
 	if not repo_root then
@@ -73,11 +53,12 @@ function M.setup()
 		.. passes_dir  .. "?/init.lua;"
 		.. package.path
 
-	if package.config:sub(1, 1) == "\\" then
-		package.cpath = repo_root .. "toolchain/luajit-2.1/lib/lua/5.1/?.dll;"
+	-- lpeg: built by `update_deps.ps1` to `toolchain/lpeg/lpeg.dll`.
+	-- Wire its directory into cpath so `require("lpeg")` resolves.
+	local lpeg_dir = repo_root .. "toolchain/lpeg/"
+	package.cpath = lpeg_dir .. "?.dll;"
 		.. package.cpath
 end
-end
 
 -- Run the setup as a side effect.
 M.setup()

scripts/passes/annotation.lua

@@ -1,32 +1,22 @@
 --- passes/annotation.lua — Atom-annotation DSL validator.
 ---
---- Validates `MipsAtom_(name) atom_info(atom_bind(Binds_X),
---- atom_reads(...), atom_writes(...)) { ... }` declarations in source files.
---- Also reads:
----   - `Binds_*` struct declarations (`typedef Struct_(Binds_X) { ... };`)
----   - `TAPE_WORDS(mac_X, N)` pragma directives (`#pragma` + `_Pragma`)
+--- Validates `MipsAtom_(name) atom_info(atom_bind(Binds_X), atom_reads(...), atom_writes(...)) { ... }` declarations in source files.
+--- Also reads: `Binds_*` struct declarations (`typedef Struct_(Binds_X) { ... };`)
 ---
 --- Writes:
----   - `<ctx.out_root>/<dir_basename>.errors.h` — one per module, with
----     `#error` directives on findings (the C compile will surface the
----     error)
----   - The annotations.txt report is rendered by `passes/report.lua`
----     from the per-module results stashed in `ctx.flags._annot_results`
----
---- **Ported from** `scripts/tape_atom_annotation_pass.lua:78-545 +
---- 1081-1407` (validation only — NOT rendering, which goes to
---- `passes/report.lua`).
+---   - `<ctx.out_root>/<dir_basename>.errors.h` — one per module, with `#error` directives on findings (the C compile will surface the error)
+---   - The annotations.txt report is rendered by `passes/report.lua` from the per-module results stashed in `ctx.flags._annot_results`
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible. See
---- `C:\projects\Pikuma\ps1-ai\conductor\code_styleguides\lua.md`.
-
--- ════════════════════════════════════════════════════════════════════════════
--- Module-scope requires + package.path setup
--- ════════════════════════════════════════════════════════════════════════════
+--- Lua 5.3 compatible
 
 -- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
-dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- both standalone and when require'd from the orchestrator.
+local _src = debug.getinfo(1, "S").source:sub(2)
+local _dir = _src:match("(.*[/\\])") or "./"
+dofile(_dir .. "../duffle_paths.lua")
 local duffle = require("duffle")
 local is_space            = duffle.is_space
 local is_alpha            = duffle.is_alpha
@@ -162,7 +152,7 @@ local BYTE_COMMA        = 44
 --- @field pragmas  table  -- reserved (currently always nil; legacy compat)
 
 --- ════════════════════════════════════════════════════════════════════════════
--- Hand-rolled split helpers (no regex patterns used)
+-- split helpers
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- Split a string at top-level commas. Used inside TAPE_ATOM_* macro
@@ -197,7 +187,6 @@ local function split_csv_top(s)
 end
 
 --- Split a string into whitespace-separated tokens.
---- Hand-rolled (no regex patterns).
 --- @param s string
 --- @return string[]
 local function split_ws(s)
@@ -222,11 +211,9 @@ end
 -- Parse TAPE_ATOM_ANNOT(...) calls
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Recognize a `atom_bind(...)`, `atom_reads(...)`, or `atom_writes(...)`
--- sub-call embedded inside an atom_info arg list. Returns the kind
--- ("atom_bind" / "atom_reads" / "atom_writes") and the inner content,
--- or nil if the token isn't a recognized sub-call form. Flattened via
--- a prefix lookup instead of a nested if/elseif chain.
+-- Recognize a `atom_bind(...)`, `atom_reads(...)`, or `atom_writes(...)` sub-call embedded inside an atom_info arg list. 
+-- Returns the kind ("atom_bind" / "atom_reads" / "atom_writes") and the inner content, or nil if the token isn't a recognized sub-call form. 
+-- Flattened via a prefix lookup instead of a nested if/elseif chain.
 local REGS_CALL_PREFIX = {
 	["atom_writes("] = { kind = "atom_writes", inner_offset = 13 },
 	["atom_reads("]  = { kind = "atom_reads",  inner_offset = 12 },
@@ -235,18 +222,14 @@ local REGS_CALL_PREFIX = {
 
 local function parse_regs_call(s)
 	if s:sub(-1) ~= ")" then return nil end
-	-- Try longest prefix first so "atom_writes(" wins over "atom_reads("
-	-- when both 12-char prefixes would otherwise match. Lengths:
+	-- Try longest prefix first so "atom_writes(" wins over "atom_reads(" when both 12-char prefixes would otherwise match.
+	-- Lengths:
 	--   atom_writes(  = 12 chars, offset 13
 	--   atom_reads(   = 11 chars, offset 12
 	--   atom_bind(    = 10 chars, offset 11
 	local spec = REGS_CALL_PREFIX[s:sub(1, 12)]
-	if not spec then
-		spec = REGS_CALL_PREFIX[s:sub(1, 11)]
-	end
-	if not spec then
-		spec = REGS_CALL_PREFIX[s:sub(1, 10)]
-	end
+	if not spec then spec = REGS_CALL_PREFIX[s:sub(1, 11)] end
+	if not spec then spec = REGS_CALL_PREFIX[s:sub(1, 10)] end
 	if not spec then return nil end
 	local inner = s:sub(spec.inner_offset, -2)
 	if spec.single_ident then
@@ -257,14 +240,10 @@ local function parse_regs_call(s)
 end
 
 -- Resolve any phase_* / R_* alias macros in a register list.
--- (Phase / region / cadence aliases have been dropped. Kept as an
--- identity function so callers can stay uniform.)
-local function resolve_reg_aliases(regs)
-	return regs
-end
+-- (Phase / region / cadence aliases have been dropped. Kept as an identity function so callers can stay uniform.)
+local function resolve_reg_aliases(regs) return regs end
 
--- Parse a comma-separated inner content (e.g. inside atom_reads(...))
--- into a list of trimmed identifiers with aliases resolved.
+-- Parse a comma-separated inner content (e.g. inside atom_reads(...)) into a list of trimmed identifiers with aliases resolved.
 local function parse_regs_list(inner)
 	local out = {}
 	for _, r in ipairs(split_csv_top(inner)) do
@@ -275,8 +254,7 @@ local function parse_regs_list(inner)
 end
 
 -- Parse a single token (from split_csv_top) into an arg entry.
--- Three forms: register-list call, bare identifier,
--- "other" (preserved as text).
+-- Three forms: register-list call, bare identifier, "other" (preserved as text).
 local function parse_arg_token(s)
 	local kind, inner = parse_regs_call(s)
 	if kind then
@@ -292,8 +270,8 @@ local function parse_arg_token(s)
 	return { kind = "other", value = s }
 end
 
---- Extract identifier args from a parenthesized group. Returns a list
---- of {kind, value} pairs where kind is one of:
+--- Extract identifier args from a parenthesized group. 
+--- Returns a list of {kind, value} pairs where kind is one of:
 ---   "ident"        -- a bare identifier (e.g. phase_work)
 ---   "atom_reads"   -- an atom_reads(...) call: value is the register list
 ---   "atom_writes"  -- an atom_writes(...) call: value is the register list
@@ -338,6 +316,7 @@ local function parse_pragma_operator(source, ident_pos, after_ident)
 		return nil, open_paren + 1
 	end
 	local str, str_end = read_parens(source, open_paren)
+	-- scan: _Pragma(<string>)
 	str = trim(str)
 	if str:sub(1, 1) ~= '"' or str:sub(-1) ~= '"' then
 		return nil, str_end
@@ -372,6 +351,7 @@ local function parse_pragma_directive(source, ident_pos, after_ident)
 		eol = eol + 1
 	end
 	local line_text = trim(source:sub(rest_start, eol - 1))
+	-- scan: #pragma <mac_name> tape_atom words=<N>
 	local tokens    = split_ws(line_text)
 	local entry
 	if #tokens >= 3 and tokens[2] == "tape_atom" and tokens[3]:sub(1, WORDS_KEY_PREFIX_LEN) == WORDS_KEY_PREFIX then
@@ -411,9 +391,11 @@ local function find_macro_word_annotations(source)
 			pos = skip_preprocessor_line(source, pos)
 		else
 		local ident, after_ident = read_ident(source, pos)
+		-- scan: <ident>
 		if not ident then
 			pos = pos + 1
 		elseif ident == PRAGMA_OPERATOR then
+			-- scan: _Pragma(...)
 			local entry, new_pos = parse_pragma_operator(source, pos, after_ident)
 			if entry then
 				local line_of = duffle.LineIndex(source)
@@ -422,6 +404,7 @@ local function find_macro_word_annotations(source)
 			end
 			pos = new_pos
 		elseif ident == PRAGMA_IDENT then
+			-- scan: #pragma <mac_name> tape_atom words=<N>
 			local entry, new_pos = parse_pragma_directive(source, pos, after_ident)
 			if entry then out[#out + 1] = entry end
 			pos = new_pos
@@ -470,9 +453,8 @@ local function parse_binds_body(body)
 end
 
 --- Try to parse a `typedef Struct_(Binds_X) { ... };` declaration.
---- Returns the parsed BindsStruct (if the form matched) and the new
---- source position. If the form didn't match, returns nil + a position
---- to continue scanning from.
+--- Returns the parsed BindsStruct (if the form matched) and the new source position.
+--- If the form didn't match, returns nil + a position to continue scanning from.
 --- @param source string
 --- @param ident_pos integer  -- position of the `typedef` ident start
 --- @param after_typedef integer -- position just past `typedef`
@@ -481,6 +463,7 @@ end
 local function parse_typedef_binds(source, ident_pos, after_typedef, line_of)
 	local after_type                   = skip_ws_and_cmt(source, after_typedef)
 	local type_ident, after_type_ident = read_ident(source, after_type)
+	-- scan: typedef <type_ident>
 	if type_ident ~= STRUCT_TYPE then
 		return nil, after_type_ident or (after_type + 1)
 	end
@@ -491,12 +474,15 @@ local function parse_typedef_binds(source, ident_pos, after_typedef, line_of)
 	end
 
 	local inner, after_paren = read_parens(source, open_paren)
+	-- scan: typedef Struct_(<name>)
 	local name               = trim(inner)
 
 	local brace = scan_to_char(source, "{", after_paren)
+	-- scan: typedef Struct_(<name>) {
 	if not brace then return nil, open_paren + 1 end
 
 	local body, after_brace = read_braces(source, brace)
+	-- scan: typedef Struct_(<name>) { <fields> }
 	local fields, bytes     = parse_binds_body(body)
 
 	-- Only emit Binds_* structs (other Struct_ typedefs are ignored).
@@ -528,9 +514,11 @@ local function find_binds_structs(source)
 			pos = skip_preprocessor_line(source, pos)
 		else
 		local ident, after_ident = read_ident(source, pos)
+		-- scan: <ident>
 		if not ident then
 			pos = pos + 1
 		elseif ident == "typedef" then
+			-- scan: typedef Struct_(<name>) { <fields> }
 			local binds_struct, new_pos = parse_typedef_binds(source, pos, after_ident, line_of)
 			if binds_struct then out[#out + 1] = binds_struct end
 			pos = new_pos
@@ -546,24 +534,21 @@ end
 -- Find every MipsAtom_(name) { ... } declaration in source
 -- ════════════════════════════════════════════════════════════════════════════
 
---- Read the next identifier token from `s` starting at `pos`, where the
---- identifier is a contiguous run of `[a-zA-Z0-9_]` characters (no
---- underscore-starting alpha-only constraint). Returns the ident + the
---- position just past it, or nil + pos if no identifier starts there.
+--- Read the next identifier token from `s` starting at `pos`, where the identifier is a contiguous run of `[a-zA-Z0-9_]` 
+--- characters (no underscore-starting alpha-only constraint). 
+--- Returns the ident + the position just past it, or nil + pos if no identifier starts there.
 --- @param s string
 --- @param pos integer
 --- @return string|nil, integer
 local function read_alnum_ident(s, pos)
-	local str_len = #s
-	while pos <= str_len and is_space(s:sub(pos, pos)) do pos = pos + 1 end
-	local start = pos
-	while pos <= str_len and is_alnum(s:sub(pos, pos)) do pos = pos + 1 end
+	local str_len = #s; while pos <= str_len and is_space(s:sub(pos, pos)) do pos = pos + 1 end
+	local start = pos;  while pos <= str_len and is_alnum(s:sub(pos, pos)) do pos = pos + 1 end
 	if pos == start then return nil, pos end
 	return s:sub(start, pos - 1), pos
 end
 
---- Find every `MipsAtom_(name)` declaration in source. (Just the name +
---- source line; the body is parsed separately by `parse_mips_atom`.)
+--- Find every `MipsAtom_(name)` declaration in source. 
+--- (Just the name + source line; the body is parsed separately by `parse_mips_atom`.)
 --- @param source string
 --- @return Atom[]
 local function find_atom_names(source)
@@ -576,6 +561,7 @@ local function find_atom_names(source)
 		if pos > str_len then break end
 
 		local ident, after_ident = read_ident(source, pos)
+		-- scan: <ident>
 		if not ident then
 			pos = pos + 1
 		elseif ident ~= ATOM_DECL then
@@ -586,13 +572,16 @@ local function find_atom_names(source)
 				pos = open_paren + 1
 			else
 				local inner, after_paren = read_parens(source, open_paren)
+				-- scan: MipsAtom_(<name>)
 				local name, _            = read_alnum_ident(inner, 1)
 				if name and name ~= "" then
 					out[#out + 1] = { line = line_of(pos), name = name }
 				end
 				local brace = scan_to_char(source, "{", after_paren)
+				-- scan: MipsAtom_(<name>) {
 				if brace then
 					local _, after_brace = read_braces(source, brace)
+					-- scan: MipsAtom_(<name>) { <body> }
 					pos                  = after_brace
 				else
 					pos = open_paren + 1
@@ -609,39 +598,24 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- True iff the parsed arg is a register-list call (any recognized form).
-local function is_regs_arg(a)
-	return a and (a.kind == "atom_reads" or a.kind == "atom_writes" or a.kind == "regs")
-end
+local function is_regs_arg(a) return a and (a.kind == "atom_reads" or a.kind == "atom_writes" or a.kind == "regs") end
 
---- Per-macro arg-shape handlers. Each takes (entry, args) and mutates
---- Per-atom_info sub-call dispatch. Each takes (entry, args) and mutates
---- entry.{reads, writes, binds, errors}. The new annotation shape is:
----
----   MipsAtom_(name) atom_info(
----        atom_bind(Binds_X)
----      , atom_reads(...)
----      , atom_writes(...)
----   ) { ... };
----
---- All sub-calls are order-independent; each is dispatched on its
---- `kind` (atom_bind / atom_reads / atom_writes) when parsed.
+--- Per-macro arg-shape handlers. Each takes (entry, args) and mutates Per-atom_info sub-call dispatch. 
+--- Each takes (entry, args) and mutates entry.{reads, writes, binds, errors}. 
+--- All sub-calls are order-independent; each is dispatched on its `kind` (atom_bind / atom_reads / atom_writes) when parsed.
 local ANNOT_ARG_HANDLERS = {}
 
 -- atom_info(atom_bind(Binds_X), atom_reads(...), atom_writes(...))
 function ANNOT_ARG_HANDLERS.info(entry, args)
 	for _, arg in ipairs(args) do
-		if arg.kind == "atom_bind" then
-			entry.binds = arg.value
-		elseif arg.kind == "atom_reads" then
-			entry.reads = arg.value
-		elseif arg.kind == "atom_writes" then
-			entry.writes = arg.value
+		if     arg.kind == "atom_bind"   then entry.binds  = arg.value
+		elseif arg.kind == "atom_reads"  then entry.reads  = arg.value
+		elseif arg.kind == "atom_writes" then entry.writes = arg.value
 		elseif arg.kind == "ident"       then
 			-- Reserved for future phase tokens. Currently ignored.
 			-- (Could be reintroduced as `phase_*` sub-calls of atom_info.)
 		else
-			entry.errors[#entry.errors + 1] = string.format(
-				"unexpected atom_info arg kind=%s value=%s", arg.kind, tostring(arg.value))
+			entry.errors[#entry.errors + 1] = string.format("unexpected atom_info arg kind=%s value=%s", arg.kind, tostring(arg.value))
 		end
 	end
 end
@@ -660,9 +634,9 @@ local function new_annot_entry(line, ident, name, kind)
 	}
 end
 
---- Try to parse an `atom_info(...)` call right after the `MipsAtom_(name)`
---- parens. Returns the annotation entry (if present) and the new source
---- position past the atom_info call. Returns nil if no atom_info follows.
+--- Try to parse an `atom_info(...)` call right after the `MipsAtom_(name)` parens.
+--- Returns the annotation entry (if present) and the new source position past the atom_info call.
+--- Returns nil if no atom_info follows.
 --- @param source string
 --- @param atom_name string
 --- @param after_mipsatom_paren integer  -- position past the MipsAtom_(...) close paren
@@ -671,14 +645,14 @@ end
 local function parse_atom_info_call(source, atom_name, after_mipsatom_paren, line_of)
 	local lookahead              = skip_ws_and_cmt(source, after_mipsatom_paren)
 	local look_ident, look_after = read_ident(source, lookahead)
+	-- scan: MipsAtom_(<name>) <look_ident>
 	if look_ident ~= ATOM_INFO then return nil, after_mipsatom_paren end
 
 	local info_open = skip_ws_and_cmt(source, look_after)
-	if source:byte(info_open) ~= BYTE_OPEN_PAREN then
-		return nil, info_open + 1
-	end
+	if source:byte(info_open) ~= BYTE_OPEN_PAREN then return nil, info_open + 1 end
 
 	local info_inner, info_after = read_parens(source, info_open)
+	-- scan: MipsAtom_(<name>) atom_info(<binds>, <reads>, <writes>)
 	local args                   = parse_atom_annot_args(info_inner)
 	local entry                  = new_annot_entry(line_of(lookahead), ATOM_INFO, atom_name, "info")
 	ANNOT_ARG_HANDLERS.info(entry, args)
@@ -686,9 +660,8 @@ local function parse_atom_info_call(source, atom_name, after_mipsatom_paren, lin
 end
 
 --- Find every `MipsAtom_(name) atom_info(...) { ... };` annotation in source.
---- Returns a list of annotation entries. Atoms without a following
---- `atom_info(...)` call produce NO entry (atoms without annotations are
---- valid in the new minimal shape).
+--- Returns a list of annotation entries. Atoms without a following `atom_info(...)` call produce NO entry
+--- (atoms without annotations are valid in the new minimal shape).
 --- @param source string
 --- @return AtomAnnotation[]
 local function find_atom_annotations(source)
@@ -705,6 +678,7 @@ local function find_atom_annotations(source)
 			pos = skip_preprocessor_line(source, pos)
 		else
 			local ident, after_ident = read_ident(source, pos)
+			-- scan: <ident>
 			if not ident then
 				pos = pos + 1
 			elseif ident == ATOM_DECL then
@@ -713,16 +687,20 @@ local function find_atom_annotations(source)
 					pos = open_paren + 1
 				else
 					local inner, after_paren = read_parens(source, open_paren)
+					-- scan: MipsAtom_(<name>)
 					local name, _ = read_alnum_ident(inner, 1)
 
 					local entry, new_pos = parse_atom_info_call(source, name, after_paren, line_of)
+					-- scan: MipsAtom_(<name>) atom_info(<binds>, <reads>, <writes>)
 					if entry then annots[#annots + 1] = entry end
 					pos = new_pos
 
 					-- Skip past the body { ... } if present.
 					local brace = scan_to_char(source, "{", pos)
+					-- scan: MipsAtom_(<name>) atom_info(...) {
 					if brace then
 						local _, after_brace = read_braces(source, brace)
+						-- scan: MipsAtom_(<name>) atom_info(...) { <body> }
 						pos = after_brace
 					end
 				end
@@ -790,21 +768,17 @@ local function validate(ctx, src)
 		end
 	end
 
-	-- 3. (Phase validity check DROPPED. Phases were removed from the
-	--    annotation DSL. They may be reintroduced later as sub-calls of
-	--    atom_info, at which point ordering checks will go here.)
+	-- 3. (Phase validity check DROPPED. Phases were removed from the annotation DSL. 
+	-- They may be reintroduced later as sub-calls of atom_info, at which point ordering checks will go here.)
 
 	-- 4. BIND atoms must reference a real Binds_* struct.
 	for _, a in ipairs(annots) do
 		if a.binds then
 			if not binds_index[a.binds] then
-				-- Demoted from error to warning (2026-07-10): the same
-				-- condition is now caught by passes/static_analysis.lua's
-				-- check_abi_handoff() as an error. Emitting a warning
-				-- here keeps the annotation pass from being stop-on-error
-				-- for the common test-fixture case, while still surfacing
-				-- the issue in the report. The static-analysis report
-				-- remains the source of truth for build-stopping errors.
+				-- Demoted from error to warning (2026-07-10): the same condition is now caught by passes/static_analysis.lua's
+				-- check_abi_handoff() as an error. Emitting a warning here keeps the annotation pass from being stop-on-error
+				-- for the common test-fixture case, while still surfacing the issue in the report. 
+				-- The static-analysis report remains the source of truth for build-stopping errors.
 				warnings[#warnings + 1] = {
 					line = a.line,
 					msg  = string.format("'%s' binds '%s' but no Struct_(%s) { ... } declaration found (also flagged as an error by check_abi_handoff in the static-analysis pass)", a.name, a.binds, a.binds),
@@ -880,15 +854,7 @@ local function validate(ctx, src)
 		check_macro_drift(m, ctx.shared.word_counts[m.name])
 	end
 
-	-- 8. (atom_<...> _Pragma validation DROPPED. The pragma macros
-	--    atom_resource / atom_region / atom_group / atom_cadence /
-	--    atom_async were removed from atom_dsl.h. They may be
-	--    reintroduced later as sub-calls of atom_info.)
-
-	-- 9. (CADENCE_ONDEMAND requires async check DROPPED. Same reason
-	--    as #8.)
-
-	-- 10. Information summary.
+	-- 8. Information summary.
 	info[#info + 1] = {
 		line = 0,
 		msg  = string.format("scanned: %d atom(s), %d annotation(s), %d macro-word-decl(s), %d binds struct(s)",
@@ -911,16 +877,13 @@ end
 -- Per-DIRECTORY (per-module) output: errors.h + annotations.txt
 -- ════════════════════════════════════════════════════════════════════════════
 --
--- Per-source reports were the old behavior; each source in the same
--- directory produced its own <basename>.errors.h + <basename>.annotations.txt,
--- which flooded build/gen/ with one report per header. The new behavior
--- aggregates per-DIRECTORY (one errors.h + one annotations.txt per module
--- basename). Directories with zero atoms/annotations are skipped (no
--- file emitted).
+-- Per-source reports were the old behavior; each source in the same directory produced its own <basename>.errors.h + <basename>.annotations.txt,
+-- which flooded build/gen/ with one report per header. 
+-- Aggregates per-DIRECTORY (one errors.h + one annotations.txt per module basename). 
+-- Directories with zero atoms/annotations are skipped (no file emitted).
 
---- Render `<dir_basename>.errors.h` with `#error` directives for every
---- error found across all sources in the directory. Empty directories
---- (no errors, no atoms) produce no file.
+--- Render `<dir_basename>.errors.h` with `#error` directives for every error found across all sources in the directory. 
+--- Empty directories (no errors, no atoms) produce no file.
 local function emit_module_errors_h(ctx, dir_basename, atoms_count, errors, sources)
 	if ctx.dry_run then return nil end
 	if atoms_count == 0 and #errors == 0 then
@@ -973,10 +936,8 @@ end
 
 local M = {}
 
--- Expose `validate` for downstream passes (e.g. report.lua) that need
--- to re-render the per-source results into a per-MODULE report. Keeping
--- it as a single shared function avoids the duplication that an
--- earlier version of report.lua had.
+-- Expose `validate` for downstream passes (e.g. report.lua) that need to re-render the per-source results into a per-MODULE report.
+-- Keeping it as a single shared function avoids the duplication that an earlier version of report.lua had.
 M.validate = validate
 
 --- @param ctx PassCtx
@@ -986,11 +947,9 @@ function M.run(ctx)
 	local errors   = {}
 	local warnings = {}
 
-	-- Per-DIRECTORY (per-module) aggregation. Group sources by `src.dir`,
-	-- validate every source in the dir, then emit ONE errors.h per dir
-	-- (skipping dirs with no atoms AND no errors). The actual
-	-- annotations.txt is rendered by passes/report.lua from the stashed
-	-- per-module results below.
+	-- Per-DIRECTORY (per-module) aggregation. Group sources by `src.dir`, validate every source in the dir, then emit ONE errors.h per dir 
+	-- (skipping dirs with no atoms AND no errors). 
+	-- The actual annotations.txt is rendered by passes/report.lua from the stashed per-module results below.
 	local by_dir = {}
 	for _, src in ipairs(ctx.sources) do
 		by_dir[src.dir] = by_dir[src.dir] or {}

scripts/passes/components.lua

@@ -1,19 +1,11 @@
 --- passes/components.lua — Component-macro header generator.
 ---
---- Walks every source for `MipsAtomComp_(ac_X) { body }` (and the
---- function-form `MipsAtomComp_Proc_(ac_X, { body })`) declarations
---- and emits a per-directory `<dir_basename>.macs.h` containing one
---- `#define mac_X(sig) \` macro per component + `WORD_COUNT(mac_X, N)`
+--- Walks every source for `MipsAtomComp_(ac_X) { body }` (and the function-form `MipsAtomComp_Proc_(ac_X, { body })`) declarations and 
+--- emits a per-directory `<dir_basename>.macs.h` containing one `#define mac_X(sig) \` macro per component + `WORD_COUNT(mac_X, N)` 
 --- entries for downstream offset computation.
 ---
---- **Ported from** `tape_atom_annotation_pass.lua:604-1079`
---- (`find_component_atoms`, `preceding_comment_block`,
---- `extract_arg_names`, `convert_line_comments_to_block`,
---- `compute_component_word_count`, `emit_component_macros_h`).
----
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible. See
---- `C:\projects\Pikuma\ps1-ai\conductor\code_styleguides\lua.md`.
+--- Lua 5.3 compatible.
 
 --- @class Component
 --- @field name    string
@@ -28,12 +20,13 @@
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Resolve `arg[0]` to an absolute-ish script directory so that
--- `require("duffle")` resolves against `scripts/` regardless of CWD.
--- Note: this boilerplate is duplicated in 6 other entry scripts; a
--- Phase-6 extraction target (`duffle.setup_package_path()`).
--- Bootstrap: see `ps1_meta.lua` for the rationale.
-dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
+-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- both standalone and when require'd from the orchestrator.
+local _src = debug.getinfo(1, "S").source:sub(2)
+local _dir = _src:match("(.*[/\\])") or "./"
+dofile(_dir .. "../duffle_paths.lua")
 local duffle          = require("duffle")
 local word_count_eval = require("word_count_eval")
 
@@ -97,23 +90,19 @@ local GEN_SUBDIR      = "gen"
 -- Local helpers (file I/O + path normalization)
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Write content to disk in binary mode so LF line endings are preserved on
--- Windows (text mode would convert LF -> CRLF, breaking byte-identical diffs
--- against git-tracked gen/*.macs.h files which are stored as LF).
+-- Write content to disk in binary mode so LF line endings are preserved on Windows 
+-- (text mode would convert LF -> CRLF, breaking byte-identical diffs against git-tracked gen/*.macs.h files which are stored as LF).
 -- @param path string
 -- @param content string
 local function write_file_lf(path, content)
 	local f = io.open(path, "wb")
 	if not f then error("Cannot write " .. path) end
-	f:write(content)
-	f:close()
+	f:write(content); f:close()
 end
 
--- Convert a (possibly relative) path to an absolute Windows path. The
--- pre-rework output's "// Source:" comment line used the absolute path
--- (e.g. "C:\projects\Pikuma\ps1\code\duffle\lottes_tape.h"); if we want
--- byte-identical output, we must normalize relative -> absolute before
--- emitting that comment.
+-- Convert a (possibly relative) path to an absolute Windows path. 
+-- The pre-rework output's "// Source:" comment line used the absolute path (e.g. "C:\projects\Pikuma\ps1\code\duffle\lottes_tape.h"); 
+-- If we want byte-identical output, we must normalize relative -> absolute before emitting that comment.
 -- @param path string
 -- @return string
 local function to_absolute_path(path)
@@ -126,8 +115,7 @@ local function to_absolute_path(path)
 	local cwd = p:read("*l")
 	p:close()
 	if not cwd then return path end
-	-- Normalize forward slashes to backslashes (Windows convention) on
-	-- both the cwd AND the relative path tail, so the join is uniform.
+	-- Normalize forward slashes to backslashes (Windows convention) on both the cwd AND the relative path tail, so the join is uniform.
 	cwd = cwd:gsub("/", "\\")
 	local tail = (path:gsub("/", "\\"))
 	return cwd .. "\\" .. tail
@@ -135,10 +123,6 @@ end
 
 local M = {}
 
--- ════════════════════════════════════════════════════════════════════════════
--- Ported helpers (verbatim from tape_atom_annotation_pass.lua:604-1079)
--- ════════════════════════════════════════════════════════════════════════════
-
 -- ════════════════════════════════════════════════════════════════════════════
 -- Function-args extraction (precedes MipsAtomComp_Proc_ invocations)
 -- ════════════════════════════════════════════════════════════════════════════
@@ -163,16 +147,13 @@ local function find_last_name_open_paren(source, name, before_pos)
 	return last_idx
 end
 
---- Find the args of the function declaration that immediately precedes
---- a `MipsAtomComp_Proc_` invocation of the given name. Returns the
---- args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil
---- if no function declaration is found.
+--- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
+--- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
 ---
 --- Convention: function form is
 ---   `FI_ MipsAtom ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
---- We find the LAST occurrence of `"ac_X("` before `before_pos` and
---- extract the args from inside the parens. We then verify the
---- preceding context ends with `MipsAtom` (the function-decl keyword
+--- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
+--- We then verify the preceding context ends with `MipsAtom` (the function-decl keyword
 --- with possible qualifiers between).
 ---
 --- @param source string
@@ -183,8 +164,7 @@ local function find_function_args_for(source, name, before_pos)
 	local last_idx = find_last_name_open_paren(source, name, before_pos)
 	if not last_idx then return nil end
 
-	-- Verify the preceding context ends with "MipsAtom" (with
-	-- possible qualifiers between).
+	-- Verify the preceding context ends with "MipsAtom" (with possible qualifiers between).
 	local before   = source:sub(1, last_idx - 1)
 	local trimmed  = duffle.trim(before)
 	if trimmed:sub(-#MIPS_ATOM) ~= MIPS_ATOM then
@@ -193,7 +173,9 @@ local function find_function_args_for(source, name, before_pos)
 	end
 
 	local open_paren = last_idx + #name  -- position of "("
+	-- scan: MipsAtom ac_X(
 	local inner      = duffle.read_parens(source, open_paren)
+	-- scan: MipsAtom ac_X(<args>)
 	if not inner then return nil end
 	return inner
 end
@@ -202,8 +184,7 @@ end
 -- Preceding-comment-block extraction
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Skip whitespace (space/tab/newline/CR) backward from `pos`, returning
--- the position of the first non-whitespace char.
+-- Skip whitespace (space/tab/newline/CR) backward from `pos`, returning the position of the first non-whitespace char.
 -- @param source string
 -- @param pos integer
 -- @return integer
@@ -237,8 +218,7 @@ local function find_block_comment_open(source, close_pos)
 	return open_at
 end
 
--- Walk back from `open_at` over leading spaces + tabs to include the
--- indentation before the `/*` in the captured comment.
+-- Walk back from `open_at` over leading spaces + tabs to include the indentation before the `/*` in the captured comment.
 -- @param source string
 -- @param open_at integer
 -- @return integer
@@ -255,8 +235,7 @@ local function extend_left_over_indent(source, open_at)
 	return start
 end
 
--- Walk back from `line_end` to the start of the source line (the most
--- recent `\n` or position 1).
+-- Walk back from `line_end` to the start of the source line (the most recent `\n` or position 1).
 -- @param source string
 -- @param line_end integer
 -- @return integer
@@ -269,9 +248,8 @@ local function find_line_start(source, line_end)
 end
 
 -- (internal) Capture one `/* ... */` block comment whose closing `*/`
--- ends at `close_end_pos`. Returns (block_text, new_scan_pos) where
--- `new_scan_pos` is where to continue scanning for more comments, or
--- nil if no block comment was found.
+-- ends at `close_end_pos`. Returns (block_text, new_scan_pos) where `new_scan_pos`
+-- is where to continue scanning for more comments, or nil if no block comment was found.
 local function capture_block_comment(source, close_end_pos)
 	local open_at = find_block_comment_open(source, close_end_pos)
 	if not open_at then return nil end
@@ -290,15 +268,11 @@ local function capture_line_comment(source, line_end_pos)
 	return nil
 end
 
---- Find the contiguous comment block immediately preceding `pos` in
---- `source`. Returns the comment text (with the `/* */` or `//` markers
---- preserved) or an empty string if no comment is adjacent.
+--- Find the contiguous comment block immediately preceding `pos` in `source`.
+--- Returns the comment text (with the `/* */` or `//` markers preserved) or an empty string if no comment is adjacent.
 ---
---- Used to copy signature comments from the source declaration
---- (`MipsAtomComp_` / `MipsAtomComp_Proc_` / function decl) over to the
---- generated `mac_X` macro, so LSP/IntelliSense displays the args doc.
----
---- No regex (per the no_regex constraint).
+--- Used to copy signature comments from the source declaration (`MipsAtomComp_` / `MipsAtomComp_Proc_` / function decl)
+--- over to the generated `mac_X` macro, so LSP/IntelliSense displays the args doc.
 ---
 --- @param source string
 --- @param pos integer
@@ -335,8 +309,7 @@ end
 -- Argument-name extraction
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Walk `trimmed` backward from `pos` over trailing whitespace /
--- asterisks / brackets, returning the position of the first
+-- Walk `trimmed` backward from `pos` over trailing whitespace / asterisks / brackets, returning the position of the first
 -- non-trailer character (i.e. the end of the identifier).
 -- @param trimmed string
 -- @param pos integer
@@ -372,8 +345,7 @@ local function trim_ident_back(trimmed, pos)
 	return back
 end
 
---- Extract just the parameter NAMES from a function-args string
---- (stripping type annotations). E.g.,
+--- Extract just the parameter NAMES from a function-args string (stripping type annotations). E.g.,
 ---   `"U4 off, U4 code, U1 r, U1 g, U1 b"`  ->  `{"off", "code", "r", "g", "b"}`
 ---   `"U4 *ptr"`                            ->  `{"ptr"}`
 ---   `""`                                   ->  nil
@@ -403,9 +375,8 @@ end
 -- Component scanner (bare + function forms)
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Parse the inner content of an `AtomComp_(name, ...)` call. Returns
--- (name, body_or_nil) — `body_or_nil` is non-nil iff this is the
--- function-form `MipsAtomComp_Proc_(name, { body })` invocation.
+-- Parse the inner content of an `AtomComp_(name, ...)` call. 
+-- Returns (name, body_or_nil) — `body_or_nil` is non-nil iff this is the function-form `MipsAtomComp_Proc_(name, { body })` invocation.
 -- @param inner string  -- the content between ( and ) of the AtomComp_ call
 --- @return string|nil, string|nil
 local function parse_atomcomp_inner(inner)
@@ -428,8 +399,7 @@ local function parse_atomcomp_inner(inner)
 end
 
 -- (internal) Try to extract a bare-form `MipsAtomComp_(ac_X)` declaration.
--- Bare form: `MipsAtomComp_(ac_X) { body }` — body comes from the brace block
--- AFTER the parens.
+-- Bare form: `MipsAtomComp_(ac_X) { body }` — body comes from the brace block AFTER the parens.
 -- @param source string
 -- @param name string      -- the `ac_X` ident from the parens
 --- @param ident_pos integer -- position of the `MipsAtomComp_` ident start
@@ -440,8 +410,10 @@ end
 --- @return Component|nil, integer  -- the component + new source position
 local function make_bare_component(source, name, ident_pos, after_paren, line_of, args, comment)
 	local brace = duffle.scan_to_char(source, "{", after_paren)
+	-- scan: <ident>(<name>) {
 	if not brace then return nil, after_paren + 1 end
 	local body, after_brace = duffle.read_braces(source, brace)
+	-- scan: <ident>(<name>) { <body> }
 	return {
 		line    = line_of(ident_pos),
 		name    = name:sub(AC_PREFIX_LEN + 1),  -- strip "ac_" prefix
@@ -481,6 +453,7 @@ local function find_component_atoms(source)
 		if pos > src_len then break end
 
 		local ident, after_ident = duffle.read_ident(source, pos)
+		-- scan: <ident>
 		local is_comp = ident == ATOM_COMP or ident == ATOM_COMP_PROC
 		if not ident then
 			pos = pos + 1
@@ -492,7 +465,9 @@ local function find_component_atoms(source)
 				pos = open_paren + 1
 			else
 				local inner, after_paren = duffle.read_parens(source, open_paren)
+				-- scan: <ident>(<args>)
 				local name, body = parse_atomcomp_inner(inner)
+				-- scan: <ident>(<name>)  OR  <ident>(<name>, { <body> })
 				if not name or name:sub(1, AC_PREFIX_LEN) ~= AC_PREFIX then
 					pos = open_paren + 1
 				else
@@ -500,11 +475,14 @@ local function find_component_atoms(source)
 					local comment = preceding_comment_block(source, pos)
 					if body == nil then
 						-- Bare form: body comes from the brace block after the parens.
+						-- scan: <ident>(<name>) {
 						local comp, new_pos = make_bare_component(source, name, pos, after_paren, line_of, args, comment)
+						-- scan: <ident>(<name>) { <body> }
 						if comp then out[#out + 1] = comp end
 						pos = new_pos
 					else
 						-- Function form: body was inside the parens.
+						-- scan: <ident>(<name>, { <body> })
 						out[#out + 1] = make_proc_component(name, body, pos, line_of, args, comment)
 						pos = after_paren
 					end
@@ -521,13 +499,11 @@ end
 
 -- Convert `//` line comments to `/* */` block comments in a token.
 --
--- C macros use `\` line-continuations; a `//` comment before `\` would
--- consume the continuation, breaking the macro. We convert `//` to
--- `/* */` so the multi-line macro structure is preserved.
+-- C macros use `\` line-continuations; a `//` comment before `\` would consume the continuation, 
+-- breaking the macro. We convert `//` to `/* */` so the multi-line macro structure is preserved.
 --
 -- Skips `//` sequences that are inside string or character literals
--- (a rough heuristic — sufficient for component bodies which don't
--- have those constructs).
+-- (a rough heuristic — sufficient for component bodies which don't have those constructs).
 --
 --- @param s string
 --- @return string
@@ -565,10 +541,8 @@ end
 -- Word-count computation (memoized recursive lookup)
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Strip the `mac_` prefix from a component-call ident so we can look it
--- up against the components-by-name table. Returns the ident unchanged
--- if it doesn't start with the prefix (so a non-component ident like
--- `mask_upper` falls through to the wc-table branch).
+-- Strip the `mac_` prefix from a component-call ident so we can look it up against the components-by-name table. Returns the ident unchanged
+-- if it doesn't start with the prefix (so a non-component ident like `mask_upper` falls through to the wc-table branch).
 -- @param ident string|nil
 -- @return string|nil
 local function strip_mac_prefix(ident)
@@ -579,9 +553,8 @@ local function strip_mac_prefix(ident)
 	return ident
 end
 
--- (internal) Recursive word-count lookup. `cache` is the memoization table
--- across all calls to `compute_component_word_count`; the in-progress
--- -1 sentinel detects cycles (A -> B -> A).
+-- (internal) Recursive word-count lookup. `cache` is the memoization table across all calls to `compute_component_word_count`; 
+-- the in-progress -1 sentinel detects cycles (A -> B -> A).
 -- @param name string -- the component name (without `mac_`)
 -- @param comp_by_name table<string, Component>
 -- @param wc table<string, integer>
@@ -618,17 +591,15 @@ local function word_count_rec(name, comp_by_name, wc, cache)
 	return n
 end
 
---- Compute the word count of a component body, accounting for macro
---- expansion. Each comma-separated entry in the body is a "slot" that
---- contributes its own word count. For most entries (regular MIPS
---- instructions) the count is 1. For `mac_Y(...)` calls, the count is
---- the word count of `mac_Y` (recursive lookup through `components`).
+--- Compute the word count of a component body, accounting for macro expansion.
+--- Each comma-separated entry in the body is a "slot" that contributes its own word count.
+--- For most entries (regular MIPS instructions) the count is 1. 
+--- For `mac_Y(...)` calls, the count is the word count of `mac_Y` (recursive lookup through `components`).
 --- For encoding macros with a known multi-word count (e.g. `mask_upper` = 2),
 --- the count is taken from `word_counts`.
 ---
---- The lookup is memoized via `word_count_rec` to avoid infinite recursion
---- (e.g. if two components referenced each other). This is the same
---- algorithm as the original `tape_atom_annotation_pass.lua` (commit 7d20a4d).
+--- The lookup is memoized via `word_count_rec` to avoid infinite recursion (e.g. if two components referenced each other).
+--- This is the same algorithm as the original `tape_atom_annotation_pass.lua` (commit 7d20a4d).
 ---
 --- @param c Component
 --- @param components Component[]
@@ -677,8 +648,7 @@ local function tokens_from_body(body)
 	return out
 end
 
---- Determine the macro signature: function-args list (function form)
---- or variadic-ignored (bare form).
+--- Determine the macro signature: function-args list (function form) or variadic-ignored (bare form).
 --- @param args_str string|nil
 --- @return string
 local function signature_from_args(args_str)
@@ -689,8 +659,8 @@ local function signature_from_args(args_str)
 	return "..."
 end
 
---- Strip the trailing `" \"` (space + backslash) line continuation
---- from the last body line. The last 2 chars are always that pair.
+--- Strip the trailing `" \"` (space + backslash) line continuation from the last body line.
+--- The last 2 chars are always that pair.
 local function strip_trailing_continuation(lines)
 	local last = lines[#lines]
 	if last:sub(-2) == " \\" then
@@ -698,9 +668,8 @@ local function strip_trailing_continuation(lines)
 	end
 end
 
---- Emit the `#define mac_X(sig) \<newline>\t<tok1> \<newline>,\t<tok2> ...`
---- block. Converts `//` line comments to `/* */` block comments in
---- each token so they don't break the C macro `\` line continuations.
+--- Emit the `#define mac_X(sig) \<newline>\t<tok1> \<newline>,\t<tok2> ...` block.
+--- Converts `//` line comments to `/* */` block comments in each token so they don't break the C macro `\` line continuations.
 local function emit_macro_body(lines, c, sig, tokens)
 	for tok_idx = 1, #tokens do
 		tokens[tok_idx] = convert_line_comments_to_block(tokens[tok_idx])
@@ -713,9 +682,8 @@ local function emit_macro_body(lines, c, sig, tokens)
 	strip_trailing_continuation(lines)
 end
 
---- Build the list of lines for one component (signature comment,
---- `#define mac_X(...)` line with backslash-continued tokens, then
---- `WORD_COUNT(mac_X, N)` entry).
+--- Build the list of lines for one component 
+--- (signature comment, `#define mac_X(...)` line with backslash-continued tokens, then `WORD_COUNT(mac_X, N)` entry).
 --- @param c Component
 --- @param components Component[]
 --- @param wc table<string, integer>
@@ -748,17 +716,14 @@ end
 -- Per-source emit logic
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Build the boilerplate header lines (the `#ifdef INTELLISENSE_DIRECTIVES`
--- block, the `// Auto-generated` comment, the `// Source:` line, and the
--- self-contained `WORD_COUNT` macro definition).
+-- Build the boilerplate header lines (the `#ifdef INTELLISENSE_DIRECTIVES` block, 
+-- the `// Auto-generated` comment, the `// Source:` line, and the self-contained `WORD_COUNT` macro definition).
 -- @param src SourceFile
 -- @return string[]
 local function header_boilerplate(src)
 	return {
-		-- #pragma once wrapped in #ifdef INTELLISENSE_DIRECTIVES, matching
-		-- the convention in lottes_tape.h. The build does manual unity
-		-- includes (the user controls include order), so the pragma
-		-- is only active for IDE/tooling.
+		-- #pragma once wrapped in #ifdef INTELLISENSE_DIRECTIVES, matching the convention in lottes_tape.h.  
+		-- The build does manual unity includes (the user controls include order), so the pragma is only active for IDE/tooling.
 		"#ifdef INTELLISENSE_DIRECTIVES",
 		"#pragma once",
 		"#endif",
@@ -767,8 +732,7 @@ local function header_boilerplate(src)
 		"// Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)",
 		"",
 		-- Self-contained: define WORD_COUNT if not already defined.
-		-- We use the same definition here so the auto-generated
-		-- entries below expand to compile-time constants whether
+		-- We use the same definition here so the auto-generated entries below expand to compile-time constants whether
 		-- the metadata file is included first or not.
 		"#ifndef WORD_COUNT",
 		"#define WORD_COUNT(name, count)  enum { words_##name = (count) };",
@@ -778,10 +742,9 @@ local function header_boilerplate(src)
 end
 
 -- Compute the output path for one source's `.macs.h` file.
--- The pre-rework convention uses the *directory* basename (not the
--- source file basename) — e.g. `code/duffle/lottes_tape.h` produces
--- `code/duffle/gen/duffle.macs.h`. This matches what the C codebase
--- #includes.
+-- The pre-rework convention uses the *directory* basename 
+-- (not the source file basename) — e.g. `code/duffle/lottes_tape.h` produces `code/duffle/gen/duffle.macs.h`. 
+-- This matches what the C codebase #includes.
 -- @param src SourceFile
 -- @return string  -- the output directory
 -- @return string  -- the full output path
@@ -791,13 +754,10 @@ local function compute_macs_h_path(src)
 	return out_dir, out_path
 end
 
---- Emit a per-source `.macs.h` header with the `mac_X` macros +
---- `WORD_COUNT` entries. Writes in BINARY mode so LF line endings are
---- preserved (the git blob is LF; Windows text-mode would emit CRLF and
---- break the byte-identical diff).
+--- Emit a per-source `.macs.h` header with the `mac_X` macros + `WORD_COUNT` entries. Writes in BINARY mode so LF line endings are
+--- preserved (the git blob is LF; Windows text-mode would emit CRLF and break the byte-identical diff).
 ---
---- Honors `ctx.dry_run`: prints the intended path but does not write
---- the file.
+--- Honors `ctx.dry_run`: prints the intended path but does not write the file.
 ---
 --- @param ctx PassCtx
 --- @param src SourceFile
@@ -833,8 +793,8 @@ end
 -- Pass entry
 -- ════════════════════════════════════════════════════════════════════════════
 
--- (internal) Extend `ctx.shared.word_counts` with this source's component
--- macros so offsets sees them without re-reading the file.
+-- (internal) Extend `ctx.shared.word_counts` with this source's component macros 
+-- so offsets sees them without re-reading the file.
 -- @param ctx PassCtx
 -- @param components Component[]
 local function update_shared_word_counts(ctx, components)

scripts/passes/duffle_paths.lua

@@ -1,85 +0,0 @@
---- duffle_paths.lua — Single-line bootstrap helper for the tape-atom
---- Lua scripts.
----
---- Each entry script (ps1_meta.lua, word_count_eval.lua, and the 5
---- passes/*.lua files) starts with:
----
----   ```lua
----   local duffle = dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
----   ```
----
---- That single line: (a) locates this helper via `arg[0]`, (b) loads
---- it (which sets `package.path` + `package.cpath` via `git rev-parse`),
---- (c) returns the `M` table (a wrapper around the setup function).
---- After this line, `require("duffle")` and `require("passes.X")` both
---- resolve normally.
----
---- **Why a helper instead of inline?**
----   - The 8-line path-setup boilerplate was duplicated across 7 entry
----     scripts (one per file). Single source of truth here.
----   - Mirrors the build script's pattern in `build_psyq.ps1`:
----     `$path_root = split-path -Path $PSScriptRoot -Parent;` then
----     derive everything from there.
----
---- **Why `git rev-parse --show-toplevel`?**
---- Hardcoding `C:\\projects\\Pikuma\\ps1\\...` breaks portability. Git
---- gives us the canonical repo root regardless of where the repo lives
---- on disk.
-
-local M = {}
-
--- Cache key for the repo root. Stored in `package.loaded` (process-
--- global) so all 8 entry scripts + passes scripts share one git call.
--- Without this cache, `git rev-parse --show-toplevel` runs once per
--- script load = 8 × ~150ms = 1.2s wasted per build on Windows.
-local CACHE_KEY = "__duffle_repo_root__"
-
---- Resolve the repo root via git (cached after first call).
---- Returns a normalized path with a trailing forward-slash, or nil
---- if not in a git repo.
---- @return string|nil
-local function find_repo_root()
-	if package.loaded[CACHE_KEY] then return package.loaded[CACHE_KEY] end
-	local p = io.popen("git rev-parse --show-toplevel 2>nul")
-	local root
-	if p then
-		root = p:read("*l")
-		p:close()
-	end
-	if not root or root == "" then return nil end
-	-- Normalize to forward slashes (Windows accepts both, but mixed
-	-- `\` + `/` confuses LuaJIT's file APIs).
-	root = root:gsub("\\", "/")
-	if not root:match("/$") then root = root .. "/" end
-	package.loaded[CACHE_KEY] = root
-	return root
-end
-
---- Set `package.path` (for `require("duffle")` + `require("passes.X")`)
---- and `package.cpath` (for `lpeg.dll` on Windows).
---- Idempotent: safe to call multiple times (just re-sets the same paths).
-function M.setup()
-	local repo_root = find_repo_root()
-	if not repo_root then
-		io.stderr:write("[duffle_paths] git rev-parse failed -- not in a git repo?\n")
-		os.exit(2)
-	end
-
-	local scripts_dir = repo_root .. "scripts/"
-	local passes_dir  = repo_root .. "scripts/passes/"
-	package.path = scripts_dir .. "?.lua;"
-		.. scripts_dir .. "?/init.lua;"
-		.. passes_dir  .. "?.lua;"
-		.. passes_dir  .. "?/init.lua;"
-		.. package.path
-
-	if package.config:sub(1, 1) == "\\" then
-		package.cpath = repo_root .. "toolchain/luajit-2.1/lib/lua/5.1/?.dll;"
-			.. package.cpath
-	end
-end
-
--- Run the setup as a side effect.
-M.setup()
-
-return M

scripts/passes/offsets.lua

@@ -1,28 +1,26 @@
 --- passes/offsets.lua — Branch-offset generator.
 ---
---- Scans every source for `MipsAtom_(name) { ... }` (and the raw
---- `MipsCode code_<name> { ... }` form) declarations, computes the
---- word offset from each `atom_offset(F, T)` marker to its target
---- `atom_label(T)` declaration, and emits `<dir_basename>.offsets.h`
---- with one `#define _atom_offset_F_T = N` per branch.
+--- Scans every source for `MipsAtom_(name) { ... }` (and the raw `MipsCode code_<name> { ... }` form) declarations, 
+--- computes the word offset from each `atom_offset(F, T)` marker to its target `atom_label(T)` declaration, 
+--- and emits `<dir_basename>.offsets.h` with one `#define _atom_offset_F_T = N` per branch.
 ---
---- The offset is `target_word - branch_word - 1` (the standard MIPS
---- branch-immediate encoding: branch_offset = relative_pc_in_words - 1).
+--- The offset is `target_word - branch_word - 1` (the standard MIPS branch-immediate encoding: branch_offset = relative_pc_in_words - 1).
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible. See
---- `C:\projects\Pikuma\ps1-ai\conductor\code_styleguides\lua.md`.
+--- Lua 5.3 compatible.
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Resolve `arg[0]` to an absolute-ish script directory so that
--- `require("duffle")` resolves against `scripts/` regardless of CWD.
--- Note: this boilerplate is duplicated in 6 other entry scripts; a
--- Phase-6 extraction target (`duffle.setup_package_path()`).
+-- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
 -- Bootstrap: see `ps1_meta.lua` for the rationale.
-dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- both standalone and when require'd from the orchestrator.
+local _src = debug.getinfo(1, "S").source:sub(2)
+local _dir = _src:match("(.*[/\\])") or "./"
+dofile(_dir .. "../duffle_paths.lua")
 local duffle = require("duffle")
 local word_count_eval = require("word_count_eval")
 local count_token_words = word_count_eval.count_token_words
@@ -140,10 +138,8 @@ end
 -- Marker-call helpers
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Extract comma-separated identifier args from a parenthesized group
--- after a function-like macro call. Returns (args, after_paren) where
--- `after_paren` is the position just past the closing `)`, or nil if
--- `token` did not start with `(`.
+-- Extract comma-separated identifier args from a parenthesized group after a function-like macro call.
+-- Returns (args, after_paren) where `after_paren` is the position just past the closing `)`, or nil if `token` did not start with `(`.
 -- @param token string
 -- @param after_ident integer
 -- @return string[], integer|nil
@@ -151,6 +147,7 @@ local function extract_ident_args(token, after_ident)
 	local arg_start = duffle.skip_ws_and_cmt(token, after_ident)
 	if token:sub(arg_start, arg_start) ~= "(" then return {}, nil end
 	local inner, after_paren = duffle.read_parens(token, arg_start)
+	-- scan: <marker>(<args>)
 
 	local args      = {}
 	local pos       = 1
@@ -172,8 +169,7 @@ local function extract_ident_args(token, after_ident)
 	return args, after_paren
 end
 
--- (internal) Record a `atom_label(name)` marker — `at_pos` is the
--- branch-free word position within the atom body.
+-- (internal) Record a `atom_label(name)` marker — `at_pos` is the branch-free word position within the atom body.
 -- @param labels table<string, integer>
 -- @param args string[]
 -- @param at_pos integer
@@ -191,8 +187,7 @@ local function record_offset_marker(branches, args, at_pos)
 	end
 end
 
---- Scan a single token for atom_label/atom_offset markers, walking through
---- balanced groups transparently (so nested calls are found).
+--- Scan a single token for atom_label/atom_offset markers, walking through balanced groups transparently (so nested calls are found).
 --- @param token string
 --- @param at_pos integer    -- the branch-free word position of this token in the body
 --- @param labels table<string, integer>
@@ -224,8 +219,7 @@ local function scan_for_atom_markers(token, at_pos, labels, branches)
 	end
 end
 
---- Find the end position (just past the closing ')') of the first
---- atom_label/atom_offset call in `tok`. Returns 0 if no such call.
+--- Find the end position (just past the closing ')') of the first atom_label/atom_offset call in `tok`. Returns 0 if no such call.
 --- @param tok string
 --- @return integer  -- 0 if no marker call found; otherwise end-1 (just past ')')
 local function find_marker_call_end(tok)
@@ -243,7 +237,9 @@ local function find_marker_call_end(tok)
 			pos = (nx > pos) and nx or (pos + 1)
 		else
 			local ident, after_ident = duffle.read_ident(tok, pos)
+			-- scan: <ident>
 			if ident == LABEL_MARKER or ident == OFFSET_MARKER then
+				-- scan: atom_label(<name>)  OR  atom_offset(<tag>, <target>)
 				local open_paren = duffle.skip_ws_and_cmt(tok, after_ident)
 				if tok:sub(open_paren, open_paren) == "(" then
 					local _, end_paren = duffle.read_parens(tok, open_paren)
@@ -261,8 +257,7 @@ end
 -- Atom scanner
 -- ════════════════════════════════════════════════════════════════════════════
 
---- Skip C qualifier keywords (`static`, `const`, etc.) and return the
---- position past the last qualifier.
+--- Skip C qualifier keywords (`static`, `const`, etc.) and return the position past the last qualifier.
 --- @param source string
 --- @param pos integer
 --- @return integer
@@ -276,8 +271,7 @@ local function skip_qualifiers(source, pos)
 end
 
 -- (internal) Try to parse the wrapped atom form: `MipsAtom_(<name>) { ... }`.
--- Returns the parsed Atom (name + body + position past body), or nil if
--- the form didn't match.
+-- Returns the parsed Atom (name + body + position past body), or nil if the form didn't match.
 -- @param source_text string
 -- @param after_pos integer   -- position just past `MipsAtom_`
 -- @return Atom|nil
@@ -285,6 +279,7 @@ local function try_wrapped_atom(source_text, after_pos)
 	local paren_pos = duffle.skip_ws_and_cmt(source_text, after_pos)
 	if source_text:sub(paren_pos, paren_pos) ~= "(" then return nil end
 	local inner, after_paren = duffle.read_parens(source_text, paren_pos)
+	-- scan: MipsAtom_(<name>)
 
 	local name_start = 1
 	while name_start <= #inner and duffle.is_space(inner:sub(name_start, name_start)) do
@@ -298,8 +293,10 @@ local function try_wrapped_atom(source_text, after_pos)
 	if    name == "" then return nil end
 
 	local  brace_pos = duffle.scan_to_char(source_text, "{", after_paren)
+	-- scan: MipsAtom_(<name>) {
 	if not brace_pos then return nil end
 	local body, after_brace = duffle.read_braces(source_text, brace_pos)
+	-- scan: MipsAtom_(<name>) { <body> }
 	return { name = name, body = body, after_brace = after_brace }
 end
 
@@ -310,18 +307,21 @@ end
 local function try_raw_atom(source_text, after_pos)
 	local next_pos = duffle.skip_ws_and_cmt(source_text, after_pos)
 	local next_ident, next_after = duffle.read_ident(source_text, next_pos)
+	-- scan: MipsCode <next_ident>
 	if not next_ident then return nil end
 	if not starts_with(next_ident, CODE_RAW_PREFIX) then return nil end
 	if #next_ident <= CODE_RAW_PREFIX_LEN then return nil end
 	local atom_name = next_ident:sub(CODE_RAW_PREFIX_LEN + 1)
+	-- scan: MipsCode code_<name>
 	local brace_pos = duffle.scan_to_char(source_text, "{", next_after)
+	-- scan: MipsCode code_<name> {
 	if not brace_pos then return nil end
 	local body, after_brace = duffle.read_braces(source_text, brace_pos)
+	-- scan: MipsCode code_<name> { <body> }
 	return { name = atom_name, body = body, after_brace = after_brace }
 end
 
---- Find every `MipsAtom_(name) { ... }` (or raw `MipsCode code_<name> { ... }`)
---- declaration in a source.
+--- Find every `MipsAtom_(name) { ... }` (or raw `MipsCode code_<name> { ... }`) declaration in a source.
 --- @param source_text string
 --- @return Atom[]
 local function find_atoms(source_text)
@@ -334,9 +334,11 @@ local function find_atoms(source_text)
 		pos = skip_qualifiers(source_text, pos);        if pos > src_len then break end
 
 		local ident, after = duffle.read_ident(source_text, pos)
+		-- scan: <ident>
 		if not ident then
 			pos = pos + 1
 		elseif ident == ATOM_PREFIX then
+			-- scan: MipsAtom_(<name>) { <body> }
 			local atom = try_wrapped_atom(source_text, after)
 			if atom then
 				atoms[#atoms + 1] = { name = atom.name, body = atom.body }
@@ -345,6 +347,7 @@ local function find_atoms(source_text)
 				pos = pos + 1
 			end
 		elseif ident == CODE_DECL then
+			-- scan: MipsCode code_<name> { <body> }
 			local atom = try_raw_atom(source_text, after)
 			if atom then
 				atoms[#atoms + 1] = { name = atom.name, body = atom.body }
@@ -364,9 +367,9 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- (internal) Count words emitted by the rest of `tok` after a marker call 
--- (the marker call itself emits 0 words, but the source pattern may bundle
--- the marker with the next instruction on the same line, separated by no
--- top-level comma). Returns the word count contributed by that rest.
+-- (the marker call itself emits 0 words, but the source pattern may bundle the marker with the next instruction on the same line, 
+-- separated by no top-level comma). 
+-- Returns the word count contributed by that rest.
 -- @param tok string
 -- @param word_counts table
 -- @return integer
@@ -413,8 +416,8 @@ end
 -- Offset computation + header generation
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Compute branch offsets as `target_word - branch_word - 1` (the
--- standard MIPS branch-immediate encoding).
+-- Compute branch offsets as `target_word - branch_word - 1`
+-- (the standard MIPS branch-immediate encoding).
 -- @param labels table<string, integer>
 -- @param branches table[]
 -- @return BranchOffset[]
@@ -523,9 +526,9 @@ local function process_source(ctx, src)
 	return out_path
 end
 
---- Run the offsets pass. For each source, emits a per-module
---- `<dir_basename>.offsets.h` containing `#define _atom_offset_F_T = N`
---- constants for every `atom_offset(F, T)` reference in the source's atoms.
+--- Run the offsets pass. 
+--- For each source, emits a per-module `<dir_basename>.offsets.h` containing `#define _atom_offset_F_T = N` constants for every `atom_offset(F, T)` reference
+--- in the source's atoms.
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)

scripts/passes/report.lua

@@ -20,21 +20,23 @@
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Resolve `arg[0]` to an absolute-ish script directory so that
--- `require("duffle")` resolves against `scripts/` regardless of CWD.
--- Note: this boilerplate is duplicated in 6 other entry scripts; a
--- Phase-6 extraction target (`duffle.setup_package_path()`).
+-- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
+-- Note: this boilerplate is duplicated in 6 other entry scripts; a Phase-6 extraction target (`duffle.setup_package_path()`).
 -- Bootstrap: see `ps1_meta.lua` for the rationale.
-dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- both standalone and when require'd from the orchestrator.
+local _src = debug.getinfo(1, "S").source:sub(2)
+local _dir = _src:match("(.*[/\\])") or "./"
+dofile(_dir .. "../duffle_paths.lua")
 local duffle = require("duffle")
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Section separators used in the rendered text reports. The thin rules
--- are hand-tuned to align with the per-section content width; do not
--- change without also checking the section renderers below.
+-- Section separators used in the rendered text reports.
+-- The thin rules are hand-tuned to align with the per-section content width; do not change without also checking the section renderers below.
 local RULE_THICK = "========================================================"
 local SECTION_HEADER_ATOMS     = "── Atoms ────────────────────────────────────────────────"
 local SECTION_HEADER_ANNOTS    = "── Annotations ──────────────────────────────────────────"
@@ -142,8 +144,7 @@ local PASS_NAME = "report"
 -- Per-MODULE annotation report (aggregated across all sources in a dir)
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Extract the basename (last path segment) of a forward- or back-slash
--- separated path. Returns the input unchanged if no separator is found.
+-- Extract the basename (last path segment) of a forward- or back-slash separated path. Returns the input unchanged if no separator is found.
 -- @param path string
 -- @return string
 local function source_basename(path)
@@ -301,8 +302,7 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- Render the per-project summary (`build/gen/annotation_validation.txt`).
---- Aggregates totals across all sources; lists per-source error counts
---- if any source has errors.
+--- Aggregates totals across all sources; lists per-source error counts if any source has errors.
 --- @param all_results AnnotationResult[]
 --- @return string
 local function render_project_report(all_results)
@@ -351,8 +351,7 @@ end
 -- Orchestration helpers
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Group source files by their `dir` field. Used to mirror the
--- per-DIRECTORY partitioning the annotation pass uses.
+-- Group source files by their `dir` field. Used to mirror the per-DIRECTORY partitioning the annotation pass uses.
 -- @param sources SourceFile[]
 -- @return table<string, SourceFile[]>  -- map of dir -> sources in that dir
 local function group_sources_by_dir(sources)
@@ -364,10 +363,8 @@ local function group_sources_by_dir(sources)
 	return by_dir
 end
 
--- (internal) Validate each source in `dir_sources` via the annotation pass,
--- tagging each result with `result.source = src.path` for downstream rendering.
--- Returns the list of module results + the flat list of all results (for the
--- project-wide summary).
+-- (internal) Validate each source in `dir_sources` via the annotation pass, tagging each result with `result.source = src.path` for downstream rendering.
+-- Returns the list of module results + the flat list of all results (for the project-wide summary).
 -- @param ctx PassCtx
 -- @param dir_sources SourceFile[]
 -- @return AnnotationResult[], AnnotationResult[]
@@ -411,9 +408,8 @@ end
 
 local M = {}
 
---- Run the report pass. Renders one `<dir_basename>.annotations.txt`
---- per source-directory that has content, plus the project-wide
---- `annotation_validation.txt` summary.
+--- Run the report pass. 
+--- Renders one `<dir_basename>.annotations.txt` per source-directory that has content, plus the project-wide `annotation_validation.txt` summary.
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
@@ -428,8 +424,7 @@ function M.run(ctx)
 
 	local all_results_for_summary = {}
 	for _, entry in ipairs(module_entries) do
-		debug_log("entry: dir=%s basename=%s atoms_count=%d dir_sources=%d\n",
-			entry.dir, entry.dir_basename, entry.atoms_count, #(by_dir[entry.dir] or {}))
+		debug_log("entry: dir=%s basename=%s atoms_count=%d dir_sources=%d\n", entry.dir, entry.dir_basename, entry.atoms_count, #(by_dir[entry.dir] or {}))
 
 		if entry.atoms_count > 0 or #(by_dir[entry.dir] or {}) > 0 then
 			local dir_sources                 = by_dir[entry.dir] or {}

scripts/passes/static_analysis.lua

@@ -1,52 +1,32 @@
 --- passes/static_analysis.lua — Per-atom static-analysis checks.
 ---
 --- The 5 checks currently shipped:
----   1. **GTE pipeline-fill** — every `gte_cmdw_*` invocation must be
----      preceded by the minimum number of `nop` words (per
----      `duffle.duffle.GTE_PIPELINE_LATENCY`) so the COP2 pipeline latency is
----      fully retired before the command issues.
----   2. **mac_yield uniformity** — every atom body must contain exactly
----      one `mac_yield()` call (control transfer pattern).
----   3. **ABI handoff** — every `atom_bind(Binds_X)` must reference a
----      `typedef Struct_(Binds_X) { ... }` declaration.
----   4. **GPU port-store shape** — per-shape (`f3`/`f4`/`g4`/etc.) the
----      sum of `mac_format_X_color` + `mac_gte_store_X_*` +
----      `mac_insert_ot_tag_X` words must equal the GP0 cmd's expected
----      packet size.
----   5. **per-atom cycle budget** — sum each atom body's instruction
----      latencies (per `duffle.duffle.INSTRUCTION_LATENCY`); report total.
+---   1. **GTE pipeline-fill** — every `gte_cmdw_*` invocation must be preceded by the minimum number of `nop` words
+---      (per `duffle.GTE_PIPELINE_LATENCY`) so the COP2 pipeline latency is fully retired before the command issues.
+---   2. **mac_yield uniformity** — every atom body must contain exactly one `mac_yield()` call (control transfer pattern).
+---   3. **ABI handoff** — every `atom_bind(Binds_X)` must reference a `typedef Struct_(Binds_X) { ... }` declaration.
+---   4. **GPU port-store shape** — per-shape (`f3`/`f4`/`g4`/etc.) the sum of `mac_format_X_color` + `mac_gte_store_X_*` +
+---      `mac_insert_ot_tag_X` words must equal the GP0 cmd's expected packet size.
+---   5. **per-atom cycle budget** — sum each atom body's instruction latencies (per `duffle.INSTRUCTION_LATENCY`); report total.
 ---
 --- The orchestrator (`ps1_meta.lua`) wires this module in via the
 --- PASSES table:
----   `["static-analysis"] = { module = "passes.static_analysis",
----                            kind   = "validation",
----                            deps   = {"word-counts", "components"},
----                            out    = { { kind = "report",
----                                         path_template = "<out_root>/<basename>.static_analysis.txt" } } }`
+---   `["static-analysis"] = { module = "passes.static_analysis", kind = "validation", deps = {"word-counts", "components"},
+---     out = { { kind = "report", path_template = "<out_root>/<basename>.static_analysis.txt" } } }`
 ---
---- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible. See
---- `C:\projects\Pikuma\ps1-ai\conductor\code_styleguides\lua.md`.
+--- **Conventions**: tabs (1/level), EmmyLua annotations, no regex, Lua 5.3 compatible. See `lua.md` in the ps1-ai styleguides.
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 
--- `duffle.setup_package_path()` resolves `arg[0]` and prepends `scripts/`
--- (and `scripts/passes/`) to `package.path`, so `require("duffle")`
--- resolves regardless of CWD. See `duffle.lua` for the implementation.
-
--- Bootstrap: see `ps1_meta.lua` for the rationale.
-dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
+local _src = debug.getinfo(1, "S").source:sub(2)
+local _dir = _src:match("(.*[/\\])") or "./"
+dofile(_dir .. "../duffle_paths.lua")
 local duffle = require("duffle")
 
--- Domain tables (single source of truth in duffle.lua).
-
-
-
-
-
-
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
@@ -132,7 +112,7 @@ local OUTPUT_EXTENSION = ".static_analysis.txt"
 --- @field atom       AtomBody
 --- @field tokens     Token[]     -- the tokens in the atom body, annotated
 --- @field findings   Finding[]   -- findings for this atom
---- @field total_cycles integer   -- sum of token cycle costs (Phase 3)
+--- @field total_cycles integer   -- sum of token cycle costs
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Source walkers
@@ -162,23 +142,24 @@ local OUTPUT_EXTENSION = ".static_analysis.txt"
 local function find_atom_bodies(source_text)
 	local line_of  = duffle.LineIndex(source_text)
 	local out      = {}
-	local len      = #source_text
-	local i        = 1
-	while i <= len do
-		i = duffle.skip_ws_and_cmt(source_text, i); if i > len then break end
+	local src_len = #source_text
+	local pos      = 1
+	while pos <= src_len do
+		pos = duffle.skip_ws_and_cmt(source_text, pos); if pos > src_len then break end
 		-- Skip preprocessor directives (#define / #include / #pragma /
 		-- etc). Otherwise the `#define MipsAtom_(sym) ...` definition
 		-- in lottes_tape.h gets matched as an atom named "sym" and
 		-- its `body` swallows the next real atom declaration via
 		-- duffle.scan_to_char("{", ...).
-		if source_text:sub(i, i) == "#" then
-			local j = i
-			while j <= len and source_text:byte(j) ~= 10 do j = j + 1 end
-			i = j + 1
+		if source_text:sub(pos, pos) == "#" then
+			local eol_pos = pos
+			while eol_pos <= src_len and source_text:byte(eol_pos) ~= 10 do eol_pos = eol_pos + 1 end
+			pos = eol_pos + 1
 		else
-			local ident, after = duffle.read_ident(source_text, i)
+			local ident, ident_end = duffle.read_ident(source_text, pos)
+		-- scan: <ident>
 		if not ident then
-			i = i + 1
+			pos = pos + 1
 		elseif ident == "MipsAtom_"
 		    or ident == "MipsAtomComp_"
 		    or ident == "MipsAtomComp_Proc_" then
@@ -190,69 +171,71 @@ local function find_atom_bodies(source_text)
 			else                                         kind = "comp_proc"
 			end
 
-			local open = duffle.skip_ws_and_cmt(source_text, after)
-			if source_text:sub(open, open) ~= "(" then
-				i = open + 1
+			local open_paren = duffle.skip_ws_and_cmt(source_text, ident_end)
+			if source_text:sub(open_paren, open_paren) ~= "(" then
+				pos = open_paren + 1
 			else
-				local inner, after_paren = duffle.read_parens(source_text, open)
+				local inner, after_paren = duffle.read_parens(source_text, open_paren)
+				-- scan: <ident>(<args>)
 
 				if kind == "comp_proc" then
 					-- MipsAtomComp_Proc_(sym, { body })
 					-- The body is inside the LAST `{ ... }` in the args
 					-- (the macro takes 2 args: sym name, then body in {}).
 					-- Find the last `{` in `inner`, then the matching `}`.
-					local last_open
-					for k = #inner, 1, -1 do
-						if inner:sub(k, k) == "{" then last_open = k; break end
+					local last_brace_pos
+					for search_pos = #inner, 1, -1 do
+						if inner:sub(search_pos, search_pos) == "{" then last_brace_pos = search_pos; break end
 					end
-					if not last_open then
-						i = open + 1
+					if not last_brace_pos then
+						pos = open_paren + 1
 					else
 						-- Walk forward to find matching `}` honoring balanced
 						-- ()/[] and strings. We could call duffle.read_braces
-						-- from last_open+1, but read_braces expects to start at
+						-- from last_brace_pos+1, but read_braces expects to start at
 						-- the brace itself. Inline the walk for clarity.
 						local depth = 1
-						local j = last_open + 1
-						while j <= #inner and depth > 0 do
-							local c = inner:byte(j)
+						local inner_pos = last_brace_pos + 1
+						while inner_pos <= #inner and depth > 0 do
+							local c = inner:byte(inner_pos)
 							if c == 123 then
-								depth = depth + 1; j = j + 1
+								depth = depth + 1; inner_pos = inner_pos + 1
 							elseif c == 125 then
 								depth = depth - 1
 								if depth == 0 then break end
-								j = j + 1
+								inner_pos = inner_pos + 1
 							elseif c == 40 then
-								local _, a = duffle.read_parens(inner, j); j = a
+								local _, a = duffle.read_parens(inner, inner_pos); inner_pos = a
 							elseif c == 91 then
-								local _, a = duffle.read_brackets(inner, j); j = a
+								local _, a = duffle.read_brackets(inner, inner_pos); inner_pos = a
 							elseif c == 34 or c == 39 then
-								j = duffle.duffle.skip_str_or_cmt(inner, j) + 1
+								inner_pos = duffle.skip_str_or_cmt(inner, inner_pos) + 1
 							else
-								j = j + 1
+								inner_pos = inner_pos + 1
 							end
 						end
 						if depth ~= 0 then
 							-- unmatched; bail
-							i = open + 1
+							pos = open_paren + 1
 						else
+							-- scan: <ident>(<name>, { <body> })
 							-- First ident in `inner` is the comp name.
 							local name_match = inner:match("^%s*([%w_]+)")
 							local name = name_match or "?"
-							local body     = inner:sub(last_open + 1, j - 1)
+							local body     = inner:sub(last_brace_pos + 1, inner_pos - 1)
 							-- body_off in full source: position right after the
-							-- LAST `{` in `inner`, which sits at `open+1+last_open`
-							-- (open+1 = just inside the outer paren, +last_open
-							-- = at the `{`).
-							local body_off = open + 1 + last_open
+							-- LAST `{` in `inner`, which sits at `open_paren+1+last_brace_pos`
+							-- (open_paren+1 = just inside the outer paren,
+							-- +last_brace_pos = at the `{`).
+							local body_off = open_paren + 1 + last_brace_pos
 							out[#out + 1] = {
-								line     = line_of(i),
+								line     = line_of(pos),
 								name     = name,
 								body     = body,
 								body_off = body_off + 1,
 								kind     = kind,
 							}
-							i = after_paren
+							pos = after_paren
 						end
 					end
 				else
@@ -260,34 +243,37 @@ local function find_atom_bodies(source_text)
 					-- MipsAtomComp_(sym) { body };
 					-- name is the first arg, body is the FIRST { ... } after
 					-- the paren.
-					local a = 1
-					while a <= #inner and inner:sub(a, a):match("[%s]") do a = a + 1 end
-					local b = a
-					while b <= #inner and inner:sub(b, b):match("[%w_]") do b = b + 1 end
-					local name = inner:sub(a, b - 1)
+					local name_start = 1
+					while name_start <= #inner and inner:sub(name_start, name_start):match("[%s]") do name_start = name_start + 1 end
+					local name_end = name_start
+					while name_end <= #inner and inner:sub(name_end, name_end):match("[%w_]") do name_end = name_end + 1 end
+					local name = inner:sub(name_start, name_end - 1)
+					-- scan: <ident>(<name>)
 					if name == "" then
-						i = open + 1
+						pos = open_paren + 1
 					else
 						local brace = duffle.scan_to_char(source_text, "{", after_paren)
+						-- scan: <ident>(<name>) {
 						if brace then
 							local body, after_brace = duffle.read_braces(source_text, brace)
+							-- scan: <ident>(<name>) { <body> }
 							local body_off = brace + 1
 							out[#out + 1] = {
-								line     = line_of(i),
+								line     = line_of(pos),
 								name     = name,
 								body     = body,
 								body_off = body_off,
 								kind     = kind,
 							}
-							i = after_brace
+							pos = after_brace
 						else
-							i = open + 1
+							pos = open_paren + 1
 						end
 					end
 				end
 			end
 		else
-			i = after
+			pos = ident_end
 		end
 		end  -- close the new preprocessor-skip else
 	end
@@ -309,11 +295,11 @@ local function build_body_line_index(body)
 	local index = {}
 	local len = #body
 	local newline_count = 0
-	for i = 1, len do
-		if i > 1 then
-			index[i] = newline_count + 1   -- line of `i` relative to body
+	for pos = 1, len do
+		if pos > 1 then
+			index[pos] = newline_count + 1   -- line of `pos` relative to body
 		end
-		if body:byte(i) == 10 then        -- '\n'
+		if body:byte(pos) == 10 then        -- '\n'
 			newline_count = newline_count + 1
 		end
 	end
@@ -324,7 +310,7 @@ end
 
 --- Count of COP2-nop words contributed by a single top-level token.
 --   `nop`                  -> 1
---   `nop2`                 -> 2 (i.e. `nop, nop` baked into one asm arg)
+--   `nop2`                 -> 2 (i.e. `nop, nop` baked into one asm word)
 --   `nop,` / `nop2,`        -> same as above; strip trailing comma defensively
 --   anything else          -> 0
 --
@@ -363,37 +349,37 @@ local function tokenize_body(body)
 		-- Find comma/newline/semicolon after this token. Read balanced
 		-- groups so commas inside parens/braces/brackets aren't treated
 		-- as separators. Comments / strings are skipped.
-		local i = rel
-		while i <= len do
-			local c = body:byte(i)
+		local scan = rel
+		while scan <= len do
+			local c = body:byte(scan)
 			if c == 44 then break end               -- ','
 			if c == 10 then break end               -- '\n'
 			if c == 59 then break end               -- ';'
 			if c == 40 then                         -- '('
-				local _, a = duffle.read_parens(body, i); i = a
+				local _, a = duffle.read_parens(body, scan); scan = a
 			elseif c == 123 then                     -- '{'
-				local _, a = duffle.read_braces(body, i); i = a
+				local _, a = duffle.read_braces(body, scan); scan = a
 			elseif c == 91 then                      -- '['
-				local _, a = duffle.read_brackets(body, i); i = a
+				local _, a = duffle.read_brackets(body, scan); scan = a
 			elseif c == 34 or c == 39 then           -- '"' or '\''
-				i = duffle.duffle.skip_str_or_cmt(body, i) + 1
+				scan = duffle.skip_str_or_cmt(body, scan) + 1
 			else
-				i = i + 1
+				scan = scan + 1
 			end
 		end
-		-- Extract token [rel .. i-1]
-		local tok = duffle.trim(body:sub(rel, i - 1))
+		-- Extract token [rel .. scan-1]
+		local tok = duffle.trim(body:sub(rel, scan - 1))
 		if    tok ~= "" then
 			out[#out + 1] = { tok = tok, rel = rel }
 		end
 		-- Move past the separator
-		if i <= len then
-			i = i + 1
+		if scan <= len then
+			 scan = scan + 1
 			-- Also skip whitespace before next token
-			local w = duffle.skip_ws_and_cmt(body, i)
-			if w > i then i = w end
+			local w = duffle.skip_ws_and_cmt(body, scan)
+			if    w > scan then scan = w end
 		end
-		rel = i
+		rel = scan
 	end
 	return out
 end
@@ -430,8 +416,7 @@ local function check_gte_pipeline_fill(atoms, findings, line_of)
 		local ti = 1
 		while ti <= tn do
 			local tok = tokens[ti].tok
-			local cmdw_full = tok:match("^(gte_cmdw_[%w_]+)%s*[,%)]")
-			              or tok:match("^(gte_cmdw_[%w_]+)%s*$")
+			local cmdw_full = tok:match("^(gte_cmdw_[%w_]+)%s*[,%)]") or tok:match("^(gte_cmdw_[%w_]+)%s*$")
 			if cmdw_full then
 				local variant = cmdw_full:match("^gte_cmdw_(.+)$")
 				local need    = duffle.GTE_PIPELINE_LATENCY[cmdw_full]
@@ -444,7 +429,7 @@ local function check_gte_pipeline_fill(atoms, findings, line_of)
 						check = "gte_pipeline_fill",
 						kind  = "warning",
 					msg   = string.format(
-							"%s at line %d uses `gte_cmdw_%s` but that macro is not in duffle.duffle.GTE_PIPELINE_LATENCY -- add a min_nops entry",
+						"%s at line %d uses `gte_cmdw_%s` but that macro is not in duffle.GTE_PIPELINE_LATENCY -- add a min_nops entry",
 						a.name, line, variant),
 					}
 					ti = ti + 1
@@ -514,13 +499,13 @@ local function check_mac_yield_uniformity(atoms, findings)
 
 		local count    = 0
 		local last_idx = 0
-		for i, t in ipairs(tokens) do
+		for tok_idx, t in ipairs(tokens) do
 			local tok = t.tok
 			-- Match `mac_yield(...)` or just `mac_yield`. The bareword
 			-- variant is rare in modern style but tolerated.
 			if tok:match("^mac_yield%s*%(") or tok == "mac_yield" then
 				count    = count + 1
-				last_idx = i
+				last_idx = tok_idx
 			end
 		end
 		local function line_for(idx)
@@ -554,8 +539,8 @@ local function check_mac_yield_uniformity(atoms, findings)
 				-- post-token is just `nop` or `nop2` or a branch with `, nop`
 				-- delay slot -- it's the standard "yield, then BD nop" idiom.
 				local post_non_nop = false
-				for j = last_idx + 1, #tokens do
-					local t = tokens[j].tok
+				for search_idx = last_idx + 1, #tokens do
+					local t = tokens[search_idx].tok
 					if    t ~= "" and t ~= "nop" and t ~= "nop2"
 					   and not t:match("%,%s*nop%)%s*$") then
 						post_non_nop = true
@@ -607,63 +592,68 @@ end
 local function find_binds_structs(source_text)
 	local line_of = duffle.LineIndex(source_text)
 	local out = {}
-	local len = #source_text
-	local i   = 1
-	while i <= len do
-		i = duffle.skip_ws_and_cmt(source_text, i); if i > len then break end
-		if source_text:sub(i, i) == "#" then
-			local j = i
-			while j <= len and source_text:byte(j) ~= 10 do j = j + 1 end
-			i = j + 1
+	local src_len = #source_text
+	local pos      = 1
+	while pos <= src_len do
+		pos = duffle.skip_ws_and_cmt(source_text, pos); if pos > src_len then break end
+		if source_text:sub(pos, pos) == "#" then
+			local eol_pos = pos
+			while eol_pos <= src_len and source_text:byte(eol_pos) ~= 10 do eol_pos = eol_pos + 1 end
+			pos = eol_pos + 1
 		else
-			local ident, after = duffle.read_ident(source_text, i)
+			local ident, ident_end = duffle.read_ident(source_text, pos)
+			-- scan: <ident>
 			if not ident then
-				i = i + 1
+				pos = pos + 1
 			elseif ident == "typedef" then
-				local j = duffle.skip_ws_and_cmt(source_text, after)
-				local id2, after2 = duffle.read_ident(source_text, j)
+				local after_typedef = duffle.skip_ws_and_cmt(source_text, ident_end)
+				local id2, id2_end  = duffle.read_ident(source_text, after_typedef)
+				-- scan: typedef <id2>
 				if id2 ~= "Struct_" then
-					i = after2 or (j + 1)
+					pos = id2_end or (after_typedef + 1)
 				else
-					local open = duffle.skip_ws_and_cmt(source_text, after2)
-					if source_text:sub(open, open) ~= "(" then
-						i = open + 1
+					local open_paren = duffle.skip_ws_and_cmt(source_text, id2_end)
+					if source_text:sub(open_paren, open_paren) ~= "(" then
+						pos = open_paren + 1
 					else
-						local inner, after_paren = duffle.read_parens(source_text, open)
+						local inner, after_paren = duffle.read_parens(source_text, open_paren)
+						-- scan: typedef Struct_(<name>)
 						local name = duffle.trim(inner)
 						local brace = duffle.scan_to_char(source_text, "{", after_paren)
+						-- scan: typedef Struct_(<name>) {
 						if not brace then
-							i = open + 1
+							pos = open_paren + 1
 						else
 							local body, after_brace = duffle.read_braces(source_text, brace)
+							-- scan: typedef Struct_(<name>) { <fields> }
 							local fields   = {}
 							local byte_off = 0
-							local k = 1
-							while k <= #body do
-								k = duffle.skip_ws_and_cmt(body, k); if k > #body then break end
-								local tid, tafter = duffle.read_ident(body, k)
-								if not tid then
-									k = k + 1
-								elseif tid == "U4" then
-									local fid, fafter = duffle.read_ident(body, duffle.skip_ws_and_cmt(body, tafter))
-									if fid then
-										fields[#fields + 1] = { name = fid, offset = byte_off }
+							local body_pos = 1
+							while body_pos <= #body do
+								body_pos = duffle.skip_ws_and_cmt(body, body_pos); if body_pos > #body then break end
+								local type_ident, type_end = duffle.read_ident(body, body_pos)
+								if not type_ident then
+									body_pos = body_pos + 1
+								elseif type_ident == "U4" then
+									local field_ident, field_end = duffle.read_ident(body, duffle.skip_ws_and_cmt(body, type_end))
+									if field_ident then
+										fields[#fields + 1] = { name = field_ident, offset = byte_off }
 										byte_off = byte_off + 4
 									end
-									k = fafter or (tafter + 1)
+									body_pos = field_end or (type_end + 1)
 								else
-									k = tafter + 1
+									body_pos = type_end + 1
 								end
 							end
 							if name:sub(1, 6) == "Binds_" then
-								out[#out + 1] = { line = line_of(i), name = name, fields = fields, bytes = byte_off }
+								out[#out + 1] = { line = line_of(pos), name = name, fields = fields, bytes = byte_off }
 							end
-							i = after_brace
+							pos = after_brace
 						end
 					end
 				end
 			else
-				i = after
+				pos = ident_end
 			end
 		end
 	end
@@ -678,77 +668,83 @@ end
 local function find_atom_info(source_text)
 	local line_of = duffle.LineIndex(source_text)
 	local out = {}
-	local len = #source_text
-	local i   = 1
-	while i <= len do
-		i = duffle.skip_ws_and_cmt(source_text, i); if i > len then break end
-		if source_text:sub(i, i) == "#" then
-			local j = i
-			while j <= len and source_text:byte(j) ~= 10 do j = j + 1 end
-			i = j + 1
+	local src_len = #source_text
+	local pos      = 1
+	while pos <= src_len do
+		pos = duffle.skip_ws_and_cmt(source_text, pos); if pos > src_len then break end
+		if source_text:sub(pos, pos) == "#" then
+			local eol_pos = pos
+			while eol_pos <= src_len and source_text:byte(eol_pos) ~= 10 do eol_pos = eol_pos + 1 end
+			pos = eol_pos + 1
 		else
-			local ident, after = duffle.read_ident(source_text, i)
+			local ident, ident_end = duffle.read_ident(source_text, pos)
+			-- scan: <ident>
 			if not ident then
-				i = i + 1
+				pos = pos + 1
 			elseif ident == "MipsAtom_" then
-				local open = duffle.skip_ws_and_cmt(source_text, after)
-				if source_text:sub(open, open) ~= "(" then
-					i = open + 1
+				local open_paren = duffle.skip_ws_and_cmt(source_text, ident_end)
+				if source_text:sub(open_paren, open_paren) ~= "(" then
+					pos = open_paren + 1
 				else
-					local inner, after_paren = duffle.read_parens(source_text, open)
-					local a = 1
-					while a <= #inner and inner:sub(a, a):match("[%s]") do a = a + 1 end
-					local b = a
-					while b <= #inner and inner:sub(b, b):match("[%w_]") do b = b + 1 end
-					local atom_name = inner:sub(a, b - 1)
+					local inner, after_paren = duffle.read_parens(source_text, open_paren)
+					-- scan: MipsAtom_(<name>)
+					local name_start = 1
+					while name_start <= #inner and inner:sub(name_start, name_start):match("[%s]") do name_start = name_start + 1 end
+					local name_end = name_start
+					while name_end <= #inner and inner:sub(name_end, name_end):match("[%w_]") do name_end = name_end + 1 end
+					local atom_name = inner:sub(name_start, name_end - 1)
 					local lookahead = duffle.skip_ws_and_cmt(source_text, after_paren)
-					local look_ident, look_after = duffle.read_ident(source_text, lookahead)
+					local look_ident, look_end = duffle.read_ident(source_text, lookahead)
+					-- scan: MipsAtom_(<name>) <look_ident>
 					if look_ident == "atom_info" then
-						local info_open = duffle.skip_ws_and_cmt(source_text, look_after)
+						local info_open = duffle.skip_ws_and_cmt(source_text, look_end)
 						if source_text:sub(info_open, info_open) == "(" then
 							local info_inner, info_after = duffle.read_parens(source_text, info_open)
+							-- scan: MipsAtom_(<name>) atom_info(<binds>, <reads>, <writes>)
 							local binds, reads, writes = nil, nil, nil
-							local j = 1
-							while j <= #info_inner do
-								j = duffle.skip_ws_and_cmt(info_inner, j); if j > #info_inner then break end
-								local sub_ident, sub_after = duffle.read_ident(info_inner, j)
+							local sub_pos = 1
+							while sub_pos <= #info_inner do
+								sub_pos = duffle.skip_ws_and_cmt(info_inner, sub_pos); if sub_pos > #info_inner then break end
+								local sub_ident, sub_end = duffle.read_ident(info_inner, sub_pos)
 								if not sub_ident then
-									j = j + 1
+									sub_pos = sub_pos + 1
 								elseif sub_ident == "atom_bind" then
-									local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_after)
+									local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
 									if info_inner:sub(sub_open, sub_open) == "(" then
 										local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
+										-- scan: atom_bind(<Binds_X>)
 										binds = duffle.trim(sub_inner)
-										j = sub_after2
+										sub_pos = sub_after2
 									else
-										j = sub_open + 1
+										sub_pos = sub_open + 1
 									end
 								elseif sub_ident == "atom_reads" or sub_ident == "atom_writes" then
 									local kind = sub_ident
-									local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_after)
+									local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
 									if info_inner:sub(sub_open, sub_open) == "(" then
 										local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
+										-- scan: atom_reads(<regs>)  OR  atom_writes(<regs>)
 										local regs = {}
-										local p = 1
-										while p <= #sub_inner do
-											p = duffle.skip_ws_and_cmt(sub_inner, p); if p > #sub_inner then break end
-											local pid, pa = duffle.read_ident(sub_inner, p)
-											if pid then
-												regs[#regs + 1] = duffle.trim(pid)
-												p = pa
+										local sub_inner_pos = 1
+										while sub_inner_pos <= #sub_inner do
+											sub_inner_pos = duffle.skip_ws_and_cmt(sub_inner, sub_inner_pos); if sub_inner_pos > #sub_inner then break end
+											local reg_ident, reg_end = duffle.read_ident(sub_inner, sub_inner_pos)
+											if reg_ident then
+												regs[#regs + 1] = duffle.trim(reg_ident)
+												sub_inner_pos = reg_end
 											else
-												p = p + 1
+												sub_inner_pos = sub_inner_pos + 1
 											end
-											if p > #sub_inner then break end
-											if sub_inner:sub(p, p) == "," then p = p + 1 end
+											if sub_inner_pos > #sub_inner then break end
+											if sub_inner:sub(sub_inner_pos, sub_inner_pos) == "," then sub_inner_pos = sub_inner_pos + 1 end
 										end
 										if kind == "atom_reads" then reads = regs else writes = regs end
-										j = sub_after2
+										sub_pos = sub_after2
 									else
-										j = sub_open + 1
+										sub_pos = sub_open + 1
 									end
 								else
-									j = sub_after
+									sub_pos = sub_end
 								end
 							end
 							out[#out + 1] = {
@@ -756,16 +752,16 @@ local function find_atom_info(source_text)
 								reads = reads or {}, writes = writes or {},
 								info_line = line_of(lookahead),
 							}
-							i = info_after
+							pos = info_after
 						else
-							i = info_open + 1
+							pos = info_open + 1
 						end
 					else
-						i = after_paren
+						pos = after_paren
 					end
 				end
 			else
-				i = after
+				pos = ident_end
 			end
 		end
 	end
@@ -820,6 +816,7 @@ local function check_abi_handoff(atoms, atom_infos, binds_index, findings)
 					if tok:match("^load_word%s*%(") then
 						if tok:find("R_TapePtr", 1, true) and tok:find("O_(" .. binds_name .. ",", 1, true) then
 							local field = tok:match(bind_re)
+							-- scan: load_word(R_*, R_TapePtr, O_(<Binds_X>, <field>))
 							if field then
 								found_field_seq[#found_field_seq + 1] = field
 								found_field_set[field]                = true
@@ -836,6 +833,7 @@ local function check_abi_handoff(atoms, atom_infos, binds_index, findings)
 					end
 				if tok:find("R_TapePtr", 1, true)
 				   and tok:find("S_(" .. binds_name .. ")", 1, true) then
+					-- scan: add_ui_self(R_TapePtr, S_(<Binds_X>))
 					found_advance = true
 				end
 				end
@@ -852,8 +850,8 @@ local function check_abi_handoff(atoms, atom_infos, binds_index, findings)
 				end
 
 				if #found_field_seq == #expected_field_seq then
-					for k = 1, #expected_field_seq do
-						if found_field_seq[k] ~= expected_field_seq[k] then
+					for field_idx = 1, #expected_field_seq do
+						if found_field_seq[field_idx] ~= expected_field_seq[field_idx] then
 							findings[#findings + 1] = {
 								atom  = a.name, line = a.line,
 								check = "abi_handoff", kind = "error",
@@ -913,8 +911,7 @@ local function check_gpu_portstore_shape(atoms, findings)
 				local tok = t.tok
 				-- Match `mac_format_<shape>_color(...)` and strip `_color`
 				-- to get the bare shape suffix (f3 / g4 / etc).
-				local shape = tok:match("^mac_format_([%w_]+)_color%s*%(")
-				            or tok:match("^mac_format_([%w_]+)_color%s*$")
+				local shape = tok:match("^mac_format_([%w_]+)_color%s*%(") or tok:match("^mac_format_([%w_]+)_color%s*$")
 				if shape and duffle.GP0_CMD_BY_SHAPE[shape] then
 					if not cmd_byte then
 						cmd_byte = duffle.GP0_CMD_BY_SHAPE[shape]
@@ -945,7 +942,9 @@ local function check_gpu_portstore_shape(atoms, findings)
 					findings[#findings + 1] = {
 						atom  = a.name, line = a.line,
 						check = "gpu_portstore_shape", kind = "warning",
-						msg = string.format("%s at line %d writes to R_PrimCursor via raw store_word(...) but uses no `mac_format_*_color`; the cmd byte + word count cannot be auto-validated. Consider migrating to `mac_format_X_color` + `mac_gte_store_X_post_*` + `mac_insert_ot_tag_X`.",
+						msg   = string.format("%s at line %d writes to R_PrimCursor via raw store_word(...)" 
+							.. " but uses no `mac_format_*_color`; the cmd byte + word count cannot be auto-validated." 
+							.. " Consider migrating to `mac_format_X_color` + `mac_gte_store_X_post_*` + `mac_insert_ot_tag_X`.",
 							a.name, a.line),
 					}
 				end
@@ -965,7 +964,7 @@ local function check_gpu_portstore_shape(atoms, findings)
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Check #5: per-atom cycle budget (Phase 3)
+-- Check #5: per-atom cycle budget
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- Compute the cycle cost of one token. The token is a string like
@@ -993,9 +992,9 @@ end
 --- walker uses them as branch targets.
 local function find_atom_labels(tokens)
 	local labels = {}
-	for i, t in ipairs(tokens) do
+	for tok_idx, t in ipairs(tokens) do
 		local name = t.tok:match("^atom_label%s*%(%s*([%w_]+)%s*%)")
-		if name then labels[name] = i end
+		if name then labels[name] = tok_idx end
 	end
 	return labels
 end
@@ -1005,20 +1004,20 @@ end
 --- `atom_offset(F, label)` call, the label name is recorded; otherwise
 --- the branch's target is unknown (likely a literal offset) and we
 --- record `false` as a sentinel. The CFG walker checks KEY PRESENCE
---- (via `is_branch(i)`) to decide whether a token is a branch; it
+--- (via `is_branch(tok_idx)`) to decide whether a token is a branch; it
 --- checks the value to decide whether the taken-path target is known.
---- (We can't use `nil` for the unknown-target case because `targets[i] = nil`
---- REMOVES the key from the Lua table, which would make `is_branch(i)`
+--- (We can't use `nil` for the unknown-target case because `targets[tok_idx] = nil`
+--- REMOVES the key from the Lua table, which would make `is_branch(tok_idx)`
 --- return false for both "not a branch" and "branch with unknown target".)
 local function find_branch_targets(tokens)
 	local targets = {}
-	for i, t in ipairs(tokens) do
+	for tok_idx, t in ipairs(tokens) do
 		if t.tok:match("^branch_[%w_]+%s*%(") then
 			-- branch_<cond>(rs, atom_offset(F, label))   or
 			-- branch_<cond>(rs, rt, atom_offset(F, label))
 			-- atom_offset's arg list is (flag, name); we want the name.
 			local label      = t.tok:match("atom_offset%s*%([^,]+,%s*([%w_]+)%s*%)")
-			targets[i] = label or false  -- `false` = known branch, unknown target
+			targets[tok_idx] = label or false  -- `false` = known branch, unknown target
 		end
 	end
 	return targets
@@ -1052,9 +1051,9 @@ local function analyze_atom_paths(atom)
 	local n           = #tokens
 	local costs       = {}
 	local unknown_set = {}
-	for i, t in ipairs(tokens) do
+	for tok_idx, t in ipairs(tokens) do
 		local c, _, unknown = token_cycles(t.tok)
-		costs[i] = c
+		costs[tok_idx] = c
 		if unknown then
 			unknown_set[t.tok:match("^([%w_]+)") or "?"] = true
 		end
@@ -1063,42 +1062,42 @@ local function analyze_atom_paths(atom)
 	-- A token is a terminator if it's `mac_yield` or `mac_yield(...)`.
 	-- The yield transfers control; we don't count its cost (the next
 	-- atom's prologue absorbs it).
-	local function is_terminator(i)
-		local tok = tokens[i].tok
+	local function is_terminator(tok_idx)
+		local  tok = tokens[tok_idx].tok
 		return tok == "mac_yield" or tok:match("^mac_yield%s*%(")
 	end
 
 	-- CFG successor function. Returns a list of next token indices for
 	-- the given position. Branch tokens produce 2 successors (fall-through
 	-- + taken); normal tokens produce 1 (next); terminators produce 0.
-	-- BD-slot absorption: a branch at i skips i+1 (the BD slot) in its
+	-- BD-slot absorption: a branch at tok_idx skips tok_idx+1 (the BD slot) in its
 	-- fall-through path; the BD slot's cost is added to the branch's
 	-- own cost instead (so it's counted once).
 	--
 -- A token is a "branch" if its index is a KEY in the `branches`
 -- map (regardless of whether the value is nil — a branch with
 -- nil target means "literal offset, taken path is unknown").
-	-- We check key-presence via `branches[i] ~= nil` because
-	-- `branches[i]` returns nil for both "absent" AND "present with
+-- We check key-presence via `branches[tok_idx] ~= nil` because
+-- `branches[tok_idx]` returns nil for both "absent" AND "present with
 -- nil value" — distinguishing them requires the key check.
-	local function is_branch(i)
-		local v = branches[i]
+	local function is_branch(tok_idx)
+		local v = branches[tok_idx]
 		if    v == nil then return false end
 		-- v is non-nil: either a string (atom_offset target) or false
 		-- (literal offset, no target). Both indicate a branch.
 		return true
 	end
-	local function successors(i)
-		local tok = tokens[i].tok
-		if is_terminator(i) then
-			return {}, i  -- empty list; term = i signals "path ends here"
+	local function successors(tok_idx)
+		local tok = tokens[tok_idx].tok
+		if is_terminator(tok_idx) then
+			return {}, tok_idx  -- empty list; term = tok_idx signals "path ends here"
 		end
-		if is_branch(i) then
-			local label = branches[i]  -- may be false for literal-offset branches
+		if is_branch(tok_idx) then
+			local label = branches[tok_idx]  -- may be false for literal-offset branches
 			local succ  = {}
-			-- Fall-through: skip the BD slot (i+1). Use i+2.
-			if i + 2 <= n then
-				succ[#succ + 1] = i + 2
+			-- Fall-through: skip the BD slot (tok_idx+1). Use tok_idx+2.
+			if tok_idx + 2 <= n then
+				succ[#succ + 1] = tok_idx + 2
 			end
 			-- Taken: only if the branch has a known atom_offset target.
 			if label then
@@ -1114,8 +1113,8 @@ local function analyze_atom_paths(atom)
 			return succ, nil
 		end
 		-- Normal token: just the next one
-		if i + 1 <= n then
-			return { i + 1 }, nil
+		if tok_idx + 1 <= n then
+			return { tok_idx + 1 }, nil
 		end
 		return {}, nil
 	end
@@ -1129,16 +1128,16 @@ local function analyze_atom_paths(atom)
 	local cycles_max = -1
 	local path_count = 0
 	local has_loops  = false
-	local function dfs(i, acc, visited)
+	local function dfs(tok_idx, acc, visited)
 		if path_count >= MAX_PATHS then return end
 		if _G._DEBUG_DFS then
-			io.stderr:write(string.format("dfs(i=%d, acc=%d)\n", i, acc))
+			io.stderr:write(string.format("dfs(tok_idx=%d, acc=%d)\n", tok_idx, acc))
 		end
-		if visited[i] then
+		if visited[tok_idx] then
 			has_loops = true
 			if _G._DEBUG_DFS_LOOP then
-				io.stderr:write(string.format("  -> LOOP at i=%d (tok=%s) acc=%d\n",
-					i, tokens[i].tok, acc))
+				io.stderr:write(string.format("  -> LOOP at tok_idx=%d (tok=%s) acc=%d\n",
+					tok_idx, tokens[tok_idx].tok, acc))
 			end
 			return
 		end
@@ -1146,14 +1145,14 @@ local function analyze_atom_paths(atom)
 		-- Add this token's cost. For a branch, ADD the BD-slot cost too
 		-- (and skip the BD slot in the successor list — already done in
 		-- `successors` above for fall-through; for taken path the BD
-		-- slot was at i+1 which is now skipped entirely).
-		local cost = costs[i]
-		if is_branch(i) and i + 1 <= n then
-			cost = cost + costs[i + 1]
+		-- slot was at tok_idx+1 which is now skipped entirely).
+		local cost = costs[tok_idx]
+		if is_branch(tok_idx) and tok_idx + 1 <= n then
+			cost = cost + costs[tok_idx + 1]
 		end
 		local new_acc = acc + cost
 
-		local succ, term = successors(i)
+		local succ, term = successors(tok_idx)
 		if term then
 			-- Terminator: record the path's cycle sum. We do NOT add
 			-- the terminator token to `visited` -- a path ends here, so
@@ -1166,18 +1165,18 @@ local function analyze_atom_paths(atom)
 			if new_acc > cycles_max then cycles_max = new_acc end
 			return
 		end
-		visited[i] = true
-		for _, next_i in ipairs(succ) do
-			dfs(next_i, new_acc, visited)
+		visited[tok_idx] = true
+		for _, next_tok_idx in ipairs(succ) do
+			dfs(next_tok_idx, new_acc, visited)
 		end
-		visited[i] = nil
+		visited[tok_idx] = nil
 	end
 	if n >= 1 then dfs(1, 0, {}) end
 
-	-- cycles_full: sum of every token's cost (the previous model; useful
-	-- for comparing against the path-aware min/max).
+	-- cycles_full: sum of every token's cost (the legacy sum-of-all-tokens
+	-- value; over-counts BD-slot nops relative to the path-aware min/max).
 	local cycles_full = 0
-	for i = 1, n do cycles_full = cycles_full + costs[i] end
+	for tok_idx = 1, n do cycles_full = cycles_full + costs[tok_idx] end
 
 	-- If no paths were recorded (e.g. atom body is empty), cycles_min/max
 	-- default to 0 (atom costs nothing). cycles_full is 0 too in that case.
@@ -1185,7 +1184,7 @@ local function analyze_atom_paths(atom)
 	if cycles_max == -1 then cycles_max = 0 end
 
 	local unknown_list = {}
-	for k in pairs(unknown_set) do unknown_list[#unknown_list + 1] = k end
+	for macro_name in pairs(unknown_set) do unknown_list[#unknown_list + 1] = macro_name end
 	table.sort(unknown_list)
 
 	-- branch_count: number of `branch_*(...)` tokens. (More useful than
@@ -1205,9 +1204,9 @@ local function analyze_atom_paths(atom)
 	}
 end
 
---- Backward-compat wrapper: returns total cycle count (the previous
---- "best case" value, which over-counts BD-slot nops) + unknown macro
---- list. New code should call `analyze_atom_paths(atom)` instead.
+--- Returns total cycle count (the sum-of-all-tokens value, which over-counts
+--- BD-slot nops) + unknown macro list. New code should call
+--- `analyze_atom_paths(atom)` instead.
 local function count_atom_cycles(atom)
 	local tokens = tokenize_body(atom.body)
 	local total  = 0
@@ -1220,7 +1219,7 @@ local function count_atom_cycles(atom)
 		end
 	end
 	local unknown_list = {}
-	for k in pairs(unknown_set) do unknown_list[#unknown_list + 1] = k end
+	for macro_name in pairs(unknown_set) do unknown_list[#unknown_list + 1] = macro_name end
 	return total, unknown_list
 end
 
@@ -1237,7 +1236,8 @@ local function check_per_atom_cycle_budget(atoms, findings)
 				findings[#findings + 1] = {
 					atom  = a.name, line = a.line,
 					check = "per_atom_cycle_budget", kind = "warning",
-					msg = string.format("%s at line %d uses macro `%s` which is not in duffle.INSTRUCTION_LATENCY; cycle count will be +%d per call (best-case). Add an entry to duffle.M.duffle.INSTRUCTION_LATENCY.",
+					msg   = string.format("%s at line %d uses macro `%s` which is not in duffle.INSTRUCTION_LATENCY; "
+						.. "cycle count will be +%d per call (best-case). Add an entry to duffle.INSTRUCTION_LATENCY.",
 						a.name, a.line, name, duffle.UNKNOWN_INSTRUCTION_CYCLES),
 				}
 			end
@@ -1269,7 +1269,7 @@ local function validate(ctx, src)
 	check_gpu_portstore_shape(atoms, findings)
 	check_per_atom_cycle_budget(atoms, findings)
 
-	-- Phase 3 cycle-budget output: attach per-path cycle data to each
+	-- Path-aware cycle-budget output: attach per-path cycle data to each
 	-- atom. Best-case (no-stall) cycle count with BD-slot absorbed; the
 	-- `cycles_full` field is the legacy sum-of-all-tokens value (kept
 	-- for backward compat; over-counts BD-slot nops).
@@ -1296,10 +1296,8 @@ local function validate(ctx, src)
 		-- either severity (errors for missing nops; warnings for unknown
 		-- cmdw macros not in the latency table). Bin by `kind`, not by
 		-- check name.
-		if f.kind == "error" then
-			errors[#errors + 1] = { line = f.line, msg = f.msg }
-		else
-			warnings[#warnings + 1] = { line = f.line, msg = f.msg }
+		if f.kind == "error" then errors  [#errors   + 1] = { line = f.line, msg = f.msg }
+		else                      warnings[#warnings + 1] = { line = f.line, msg = f.msg }
 		end
 	end
 	-- Per-source "scanned:" summary line. Includes the source basename
@@ -1317,7 +1315,7 @@ local function validate(ctx, src)
 		}
 	end
 
-	-- Phase 3: cycle-budget summary line. Per-path min/max totals.
+	-- Path-aware cycle-budget summary line. Per-path min/max totals.
 	if #atoms > 0 then
 		local total_min     = 0
 		local total_max     = 0
@@ -1427,10 +1425,8 @@ local function emit_static_analysis_txt(ctx, src, result)
 	return out_path
 end
 
--- (Old per-source emit function above kept for backward compat but no
--- longer called from M.run; replaced by `emit_module_static_analysis_txt`
--- which aggregates by directory. Kept because some test harnesses may
--- still call it directly.)
+-- (Old per-source emit function above; kept for backward compat but no longer called from M.run. 
+-- Replaced by `emit_module_static_analysis_txt` which aggregates by directory.)
 
 --- Per-directory emit. Aggregates atoms + findings across every source
 --- in `dir_sources` and writes a single report to
@@ -1513,15 +1509,13 @@ local function emit_module_static_analysis_txt(ctx, dir, dir_sources, atoms, fin
 		add(string.format("  ! line %d  %s", w.line, w.msg))
 	end
 
-	-- Per-atom cycle counts (Phase 3 path-aware). For each atom:
+	-- Per-atom cycle counts (path-aware). For each atom:
 	--   min   = shortest path through the body (earliest exit)
 	--   max   = longest path through the body (full fall-through)
 	--   br    = number of branch instructions
 	--   paths = number of distinct paths reached
 	-- Both min and max are best-case (no stalls); BD-slot nops are
-	-- absorbed into branch costs (MIPS semantics). The previous "best
-	-- case" model counted every token separately, which double-counted
-	-- BD-slot nops; the path-aware model is the MIPS-accurate value.
+	-- absorbed into branch costs (MIPS semantics).
 	add("")
 	add("── Per-atom cycle counts (path-aware, best case, no stalls) ─")
 	if #atoms == 0 then
@@ -1564,13 +1558,6 @@ local function emit_module_static_analysis_txt(ctx, dir, dir_sources, atoms, fin
 	-- 0 atoms are skipped (they're just header files that declared
 	-- no MipsAtom_ — they're already listed in the module's
 	-- "Sources:" section above).
-	--
-	-- TODO: per-source finding attribution. Currently we can't tell
-	-- which source a given error/warning came from (errors/warnings
-	-- only carry atom-name + line, not source-path). The per-atom
-	-- cycle section already shows which atoms are in which source
-	-- via the `(file_basename)` suffix. Adding source attribution to
-	-- error/warning would be a future enhancement.
 	for _, src in ipairs(dir_sources) do
 		local src_atoms = {}
 		for _, a in ipairs(atoms) do
@@ -1635,10 +1622,10 @@ function M.run(ctx)
 	local errors   = {}
 	local warnings = {}
 
-	-- Phase 3.7+: aggregate per-DIRECTORY (per-module). One
-	-- static_analysis.txt per source-directory, emitted only if the
-	-- directory contains at least one atom. Empty-source directories
-	-- (e.g. duffle headers with no atoms) produce no report.
+	-- Aggregate per-DIRECTORY (per-module). One static_analysis.txt per
+	-- source-directory, emitted only if the directory contains at least
+	-- one atom. Empty-source directories (e.g. duffle headers with no
+	-- atoms) produce no report.
 	--
 	-- Group sources by `src.dir`. The first component of `dir` is the
 	-- module name (e.g. "code/duffle" -> "duffle", "code/gte_hello" ->
@@ -1684,10 +1671,8 @@ function M.run(ctx)
 			end
 		end
 
-		-- Skip directories with zero atoms. The previous behavior emitted
-		-- a "<no atoms>" report per source; the new behavior emits nothing
-		-- at all (a directory with only headers / no MipsAtom_ is
-		-- "nothing to report").
+		-- Skip directories with zero atoms — a directory with only
+		-- headers / no MipsAtom_ is "nothing to report".
 		if #all_atoms == 0 then
 			-- Still aggregate errors/warnings so orchestrator sees them,
 			-- but don't write a file.

scripts/passes/word_count_eval.lua

@@ -1,44 +1,40 @@
---- word_count_eval.lua — Word-counting logic for the tape-atom metaprogram
---- pipeline.
+--- word_count_eval.lua — Word-counting logic for the tape-atom metaprogram pipeline.
 ---
 --- Three responsibilities:
----   1. **Public utilities** (used by `passes/components.lua`,
----      `passes/offsets.lua`, `passes/annotation.lua`):
+---   1. **Public utilities** (used by `passes/components.lua`, `passes/offsets.lua`, `passes/annotation.lua`):
 ---        - `M.count_token_words(token, wc)` — words emitted by one token
 ---        - `M.scan_dir(dir, suffix)` — glob walk for *.macs.h
 ---        - `M.count_body_words(body, wc)` — words emitted by an atom body
----   2. **Pass entry** `M.run(ctx)` — loads metadata.h + *.macs.h into
----      `ctx.shared.word_counts` for downstream passes.
+---   2. **Pass entry** `M.run(ctx)` — loads metadata.h + *.macs.h into `ctx.shared.word_counts` for downstream passes.
 ---   3. **Internal helpers** for the body scanner.
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible. See
---- `C:\projects\Pikuma\ps1-ai\conductor\code_styleguides\lua.md`.
+--- Lua 5.3 compatible.
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Resolve `arg[0]` to an absolute-ish script directory so that
--- `require("duffle")` resolves against `scripts/` regardless of CWD.
--- Note: this boilerplate is duplicated in 6 other entry scripts; a
--- Phase-6 extraction target (`duffle.setup_package_path()`).
+-- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
+-- Note: this boilerplate is duplicated in 6 other entry scripts; a Phase-6 extraction target (`duffle.setup_package_path()`).
 -- Bootstrap: see `ps1_meta.lua` for the rationale.
-dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
+local _src = debug.getinfo(1, "S").source:sub(2)
+local _dir = _src:match("(.*[/\\])") or "./"
+dofile(_dir .. "../duffle_paths.lua")
 local duffle = require("duffle")
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Windows separator chars — used to convert `dir /b /s` output (which uses
--- `\`) into POSIX paths (which our scripts expect).
+-- Windows separator chars — used to convert `dir /b /s` output (which uses `\`) into POSIX paths (which our scripts expect).
 local PATH_SEP_BACKSLASH = "\\"
 local PATH_SEP_FORWARD   = "/"
 
--- Glob command for Windows directory walk. `dir /b /s` lists all matching
--- files recursively with bare paths (no headers); `2>nul` discards the
--- "file not found" stderr when nothing matches.
+-- Glob command for Windows directory walk. `dir /b /s` lists all matching files recursively with bare paths (no headers); 
+-- `2>nul` discards the "file not found" stderr when nothing matches.
 local DIR_GLOB_CMD = 'dir /b /s "%s\\%s" 2>nul'
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -83,8 +79,7 @@ local M = {}
 
 --- Count words emitted by a single comma-separated token inside an atom body.
 --- For most tokens (regular MIPS instructions) this returns 1.
---- For `mac_X(...)` calls, this returns the resolved word count from `wc`
---- (recursively if needed). For `nop2` etc., returns wc[name].
+--- For `mac_X(...)` calls, this returns the resolved word count from `wc` (recursively if needed). For `nop2` etc., returns wc[name].
 --- For unknown macros, returns 1 and (optionally) warns.
 ---
 --- @param token string        -- a single token from split_top_level_commas
@@ -108,33 +103,71 @@ end
 -- └────────────────────────────────────────────────────────────────────┘
 
 --- Recursively scan a directory for files matching a glob suffix.
---- No regex per the no_regex constraint — uses plain byte matching
---- via `dir /b /s` on Windows.
+--- No regex per the no_regex constraint — uses plain byte matching via `dir /b /s` on Windows.
+---
+--- The `.macs.h` files produced by the components pass always live at `<project_root>/<module>/gen/`.
+--- We can shortcut the `dir /b /s` walk by listing modules first (one `dir /b /ad`), then walking each `<module>/gen/`
+--- (one `dir /b` per module, no recursion). 
+--- For projects with 2 modules and 0 .macs.h files, this drops the cost from ~52ms 
+--- (full recursive walk of the entire project tree) to ~5ms.
+---
+--- @param dir string        -- directory to scan (absolute or relative)
+--- @param suffix string     -- file pattern, e.g. "*.macs.h"
+--- @return string[]
+-- Cache the scan_dir result per (dir, suffix) in package.loaded. 
+-- Each `io.popen` call on Windows is ~50-100ms of subprocess overhead, so caching the result saves a fixed cost on every build.
+-- The cache persists for the lifetime of the Lua process (cleared when ps1_meta.lua exits).
+-- If a build removes/creates .macs.h files mid-process, the caller can invalidate by calling `M._invalidate_scan_cache()`.
+local SCAN_CACHE_KEY = "__word_count_eval_scan_cache__"
+
+--- Recursively scan a directory for files matching a glob suffix.
+--- No regex per the no_regex constraint — uses plain byte matching via `dir /b /s` on Windows.
 ---
 --- @param dir string        -- directory to scan (absolute or relative)
 --- @param suffix string     -- file pattern, e.g. "*.macs.h"
 --- @return string[]
 function M.scan_dir(dir, suffix)
+	local key = dir .. "\0" .. suffix
+
+	-- Check the in-process cache first. (Mostly helps when a build triggers multiple `M.run` calls -- e.g. 
+	-- the audit_lua_nesting script's stress tests but the cost is ~free either way.)
+	local cache = package.loaded[SCAN_CACHE_KEY]
+	if    cache and cache[key] then return cache[key] end
+
 	local results = {}
 	local pipe = io.popen(DIR_GLOB_CMD:format(dir, suffix))
-	if not pipe then return results end
+	if not pipe then
+		-- Cache the empty result too (avoids re-scan if the dir is genuinely empty -- e.g. a clean build before components has run yet).
+		cache      = cache or {}
+		cache[key] = results
+		package.loaded[SCAN_CACHE_KEY] = cache
+		return results
+	end
 	for raw_line in pipe:lines() do
 		local path = raw_line:gsub(PATH_SEP_BACKSLASH, PATH_SEP_FORWARD)
 		results[#results + 1] = path
 	end
 	pipe:close()
+
+	-- Cache the result.
+	cache      = cache or {}
+	cache[key] = results
+	package.loaded[SCAN_CACHE_KEY] = cache
+
 	return results
 end
 
+--- Invalidate the scan cache (call after creating new .macs.h files in the same Lua process — usually not needed).
+function M._invalidate_scan_cache() package.loaded[SCAN_CACHE_KEY] = nil end
+
 -- ┌────────────────────────────────────────────────────────────────────┐
 -- │ Shared utility: count_body_words                                   │
 -- └────────────────────────────────────────────────────────────────────┘
 
 --- Count words emitted by an entire atom body (a brace-delimited block).
 --- Splits by top-level commas; for each token, delegates to count_token_words.
---- Handles `atom_label(name)` / `atom_offset(tag, name)` markers (record at
---- current pos, do NOT advance pos; if the marker call bundles an instruction
---- after it, count that instruction too).
+--- Handles `atom_label(name)` / `atom_offset(tag, name)` markers 
+--- (record at current pos, do NOT advance pos; if the marker call bundles an instruction after it, count that instruction too).
 ---
 --- @param body string         -- brace-delimited atom body (without braces)
 --- @param wc WordCounts       -- the shared word-count table
@@ -151,10 +184,8 @@ function M.count_body_words(body, wc)
 		local is_marker = leading_ident == "atom_label" or leading_ident == "atom_offset"
 		if is_marker then
 			-- Marker call: record at current pos, do NOT advance pos.
-			-- But the source pattern may bundle the marker with the next
-			-- instruction on a new line (no top-level comma between them).
-			-- In that case, the rest of `tok` after the marker call is
-			-- a real instruction that must still be counted.
+			-- But the source pattern may bundle the marker with the next instruction on a new line (no top-level comma between them).
+			-- In that case, the rest of `tok` after the marker call is a real instruction that must still be counted.
 			local marker_end = M.find_marker_call_end(tok)
 			if marker_end > 0 and marker_end < #tok then
 				local rest = duffle.trim(tok:sub(marker_end + 1))
@@ -169,8 +200,7 @@ function M.count_body_words(body, wc)
 	return total
 end
 
---- Find the end position (just past the closing ')') of the first
---- atom_label/atom_offset call in `tok`. Returns 0 if no such call.
+--- Find the end position (just past the closing ')') of the first atom_label/atom_offset call in `tok`. Returns 0 if no such call.
 --- Internal helper for count_body_words.
 ---
 --- @param tok string
@@ -198,8 +228,8 @@ function M.find_marker_call_end(tok)
 	return 0
 end
 
--- (internal) If `ident` is `atom_label`/`atom_offset` followed by `(...)`,
--- return the position just past the closing ')'. Otherwise 0.
+-- (internal) If `ident` is `atom_label`/`atom_offset` followed by `(...)`, return the position just past the closing ')'. 
+-- Otherwise 0.
 -- @param tok string
 -- @param ident string|nil
 -- @param after_ident integer
@@ -216,10 +246,8 @@ end
 -- │ Pass entry: M.run(ctx) — "word-counts" pass                        │
 -- └────────────────────────────────────────────────────────────────────┘
 
---- Load metadata.h + scan for existing *.macs.h files into
---- ctx.shared.word_counts. Loading the .macs.h files is idempotent:
---- entries from later (current-build) .macs.h files override
---- metadata.h entries of the same name.
+--- Load metadata.h + scan for existing *.macs.h files into ctx.shared.word_counts.
+--- Loading the .macs.h files is idempotent: entries from later (current-build) .macs.h files override metadata.h entries of the same name.
 ---
 --- @param ctx PassCtx
 --- @return PassResult
@@ -244,7 +272,6 @@ function M.run(ctx)
 	end
 
 	ctx.shared.word_counts = wc
-
 	return { outputs = {}, errors = {}, warnings = {} }
 end
 

scripts/ps1_meta.lua

@@ -79,9 +79,7 @@ local PASS_FLAG_DISPATCH_KEY   = "__pass__"
 
 --- @class PassOutputEntry
 --- @field [string] string  -- dynamic shape; key is the output kind
-							 -- (e.g. "macs_h", "offsets_h", "errors_h",
-							 -- "annotations_txt", "static_analysis_txt",
-							 -- "summary_txt"), value is the path
+	-- (e.g. "macs_h", "offsets_h", "errors_h", "annotations_txt", "static_analysis_txt", "summary_txt"), value is the path
 
 --- @class Finding
 --- @field line integer  -- source line (or 0 for pass-level)
@@ -177,8 +175,7 @@ local ALL_PASS_NAMES = {
 	"offsets", "static-analysis", "report",
 }
 
---- Append every pass name to args.requested_set. Used by --all and
---- by the "default to --all if no pass flags were given" fallback.
+--- Append every pass name to args.requested_set. Used by --all and by the "default to --all if no pass flags were given" fallback.
 --- @param args ParsedArgs
 local function request_all_passes(args)
 	for _, n in ipairs(ALL_PASS_NAMES) do
@@ -186,11 +183,9 @@ local function request_all_passes(args)
 	end
 end
 
--- Per-flag handlers. Each handler takes (args, argv, i) and returns
--- the new i (so multi-arg flags like --source FILE advance it).
--- Returning nil + os.exit() handles termination flags (--help).
--- This replaces the 8-way `if/elseif/elseif...` chain that nested
--- 4 levels deep and made the dispatch logic hard to scan.
+-- Per-flag handlers. Each handler takes (args, argv, arg_idx) and returns the new arg_idx (so multi-arg flags like --source FILE advance it). 
+-- Returning nil + os.exit() handles termination flags (--help). This replaces the 8-way `if/elseif/elseif...` chain that nested 4 levels deep 
+-- and made the dispatch logic hard to scan.
 local FLAG_HANDLERS = {}
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -233,50 +228,25 @@ EXAMPLE:
 ]])
 end
 
--- Per-flag handlers. Each takes (args, argv, i) and returns the new i
--- (so multi-arg flags like --source FILE advance it). Termination
--- flags like --help call os.exit() instead. This replaces the 8-way
--- `if/elseif/elseif...` chain that nested 4 levels deep and made the
--- dispatch logic hard to scan.
+-- Per-flag handlers. Each takes (args, argv, arg_idx) and returns the new arg_idx (so multi-arg flags like --source FILE advance it).
+-- Termination flags like --help call os.exit() instead.
+-- This replaces the 8-way `if/elseif/elseif...` chain that nested 4 levels deep and made the dispatch logic hard to scan.
 --
--- Populated AFTER print_help so the --help handler can reference it
--- as an upvalue (Lua resolves locals at closure-call time, but if the
--- closure is defined before the local, it falls back to _G).
+-- Populated AFTER print_help so the --help handler can reference it as an upvalue (Lua resolves locals at closure-call time, 
+-- but if the closure is defined before the local, it falls back to _G). 
 FLAG_HANDLERS["--help"] = function(args)
 	print_help()
 	os.exit(0)
 end
 
-FLAG_HANDLERS["--dry-run"] = function(args)
-	args.dry_run = true
-end
+FLAG_HANDLERS["--dry-run"]      = function(args) args.dry_run = true end
+FLAG_HANDLERS["--verbose"]      = function(args) args.verbose = true end
+FLAG_HANDLERS["--source"]       = function(args, argv, arg_idx) args.sources[#args.sources + 1] = argv[arg_idx + 1]; return arg_idx + 1 end
+FLAG_HANDLERS["--metadata"]     = function(args, argv, arg_idx) args.metadata                   = argv[arg_idx + 1]; return arg_idx + 1 end
+FLAG_HANDLERS["--out-root"]     = function(args, argv, arg_idx) args.out_root                   = argv[arg_idx + 1]; return arg_idx + 1 end
+FLAG_HANDLERS["--project-root"] = function(args, argv, arg_idx) args.project_root               = argv[arg_idx + 1]; return arg_idx + 1 end
 
-FLAG_HANDLERS["--verbose"] = function(args)
-	args.verbose = true
-end
-
-FLAG_HANDLERS["--source"] = function(args, argv, i)
-	args.sources[#args.sources + 1] = argv[i + 1]
-	return i + 1
-end
-
-FLAG_HANDLERS["--metadata"] = function(args, argv, i)
-	args.metadata = argv[i + 1]
-	return i + 1
-end
-
-FLAG_HANDLERS["--out-root"] = function(args, argv, i)
-	args.out_root = argv[i + 1]
-	return i + 1
-end
-
-FLAG_HANDLERS["--project-root"] = function(args, argv, i)
-	args.project_root = argv[i + 1]
-	return i + 1
-end
-
--- Pass-flag handler. Reads the closed-set table, expands --all,
--- appends to requested_set. Single-statement, no nesting.
+-- Pass-flag handler. Reads the closed-set table, expands --all, appends to requested_set. Single-statement, no nesting.
 FLAG_HANDLERS[PASS_FLAG_DISPATCH_KEY] = function(args, a)
 	local name = PASS_FLAG_TO_NAME[a]
 	if name == ALL_PASSES_SENTINEL then
@@ -318,9 +288,7 @@ local function parse_args(argv)
 	end
 
 	-- Default: --all if no explicit pass flags.
-	if #args.requested_set == 0 then
-		request_all_passes(args)
-	end
+	if #args.requested_set == 0 then request_all_passes(args) end
 
 	-- Defaults: project_root = dirname(metadata).
 	if args.metadata and not args.project_root then
@@ -394,8 +362,7 @@ end
 -- Topological sort (Kahn's algorithm + cycle detection)
 -- ════════════════════════════════════════════════════════════════════════════
 
---- Compute the dep-closure of `requested_set`: include every pass name
---- transitively required by the requested set.
+--- Compute the dep-closure of `requested_set`: include every pass name transitively required by the requested set.
 ---
 --- @param passes table<string, PassDescriptor>
 --- @param requested_set string[]
@@ -431,8 +398,7 @@ local function count_entries(t)
 	return n
 end
 
---- Compute in-degrees for the Kahn sort: for each pass in `needed`,
---- the number of its deps that are also in `needed`.
+--- Compute in-degrees for the Kahn sort: for each pass in `needed`, the number of its deps that are also in `needed`.
 ---
 --- @param passes table<string, PassDescriptor>
 --- @param needed table<string, boolean>
@@ -450,8 +416,7 @@ local function compute_in_degrees(passes, needed)
 	return in_degree
 end
 
---- Seed the Kahn ready queue with passes whose in-degree is 0, sorted
---- alphabetically for deterministic execution order.
+--- Seed the Kahn ready queue with passes whose in-degree is 0, sorted alphabetically for deterministic execution order.
 ---
 --- @param in_degree table<string, integer>
 --- @return string[]
@@ -464,9 +429,8 @@ local function seed_ready_queue(in_degree)
 	return ready
 end
 
--- (internal) Pop the next ready pass, decrement the in-degree of every
--- remaining pass that depended on it (inserting newly-zero-degree passes
--- back into the ready queue), and append to `order`. Keeps `ready` sorted.
+-- (internal) Pop the next ready pass, decrement the in-degree of every remaining pass that depended on it
+-- (inserting newly-zero-degree passes back into the ready queue), and append to `order`. Keeps `ready` sorted.
 -- @param passes table<string, PassDescriptor>
 -- @param needed table<string, boolean>
 -- @param in_degree table<string, integer>
@@ -506,11 +470,9 @@ local function topo_sort(passes, requested_set)
 		process_next_ready(passes, needed, in_degree, ready, order)
 	end
 
-	-- Cycle detection: if order doesn't include all needed passes,
-	-- some are stuck with in_degree > 0 (the cycle closed on itself
-	-- before Kahn could process them). Without this check, a fully-
-	-- closed cycle (e.g. A -> B -> A) would silently return an empty
-	-- order list, leaving the orchestrator to dispatch nothing.
+	-- Cycle detection: if order doesn't include all needed passes, some are stuck with in_degree > 0 (the cycle closed on itself
+	-- before Kahn could process them). Without this check, a fully-closed cycle (e.g. A -> B -> A) would silently return an emspty order list, 
+	-- leaving the orchestrator to dispatch nothing.
 	if #order ~= count_entries(needed) then
 		for name, deg in pairs(in_degree) do
 			if deg > 0 then
@@ -527,8 +489,7 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- Render the dep graph as ASCII art. Output width capped at 78 columns.
---- Falls back to the simpler "Resolved dependency order" list only if
---- graph width exceeds terminal width.
+--- Falls back to the simpler "Resolved dependency order" list only if graph width exceeds terminal width.
 ---
 --- @param passes table<string, PassDescriptor>
 --- @param requested string[]  -- originally-requested passes (subset of closed)
@@ -539,12 +500,12 @@ local function render_dep_graph(passes, requested, closed)
 	local function add(s) lines[#lines + 1] = s end
 
 	add("[ps1_meta] Resolved dependency order (closed under deps):")
-	for i, name in ipairs(closed) do
+	for pass_idx, name in ipairs(closed) do
 		local p = passes[name]
 		local deps_str = (#p.deps == 0) and "(no deps)" or
 			"(deps: " .. table.concat(p.deps, ", ") .. ")"
 		add(string.format("  %d. %-22s %-45s [%s]",
-			i, name, deps_str, p.kind))
+			pass_idx, name, deps_str, p.kind))
 	end
 	add("")
 
@@ -591,8 +552,7 @@ end
 -- Main orchestrator
 -- ════════════════════════════════════════════════════════════════════════════
 
--- (internal) Push a pass's outputs + warnings into `ctx.upstream[name]`
--- for downstream passes to consume.
+-- (internal) Push a pass's outputs + warnings into `ctx.upstream[name]` for downstream passes to consume.
 -- @param ctx PassCtx
 -- @param pass_name string
 -- @param result PassResult
@@ -606,9 +566,8 @@ local function accumulate_pass_result(ctx, pass_name, result)
 	end
 end
 
--- (internal) If the pass's kind is in PASS_KIND_STOP_ON_ERROR and it
--- reported errors, write each error to stderr. Returns true if any
--- validation errors were reported.
+-- (internal) If the pass's kind is in PASS_KIND_STOP_ON_ERROR and it reported errors, write each error to stderr.
+-- Returns true if any validation errors were reported.
 -- @param pass_name string
 -- @param pass PassDescriptor
 -- @param result PassResult
@@ -625,15 +584,8 @@ local function report_validation_errors(pass_name, pass, result)
 	return true
 end
 
--- (internal) Run each pass in `order` in topological sequence. Tracks
--- `had_errors` instead of os.exit()ing mid-loop so the report pass (and
--- any other downstream pass) still runs and writes its per-module files.
--- The legacy behavior was os.exit(1) on the first error, which left
--- downstream per-module reports un-emitted; the 2026-07-10 change to
--- per-module aggregation made that visible to the user (build/gen had
--- only the partial reports from the failing pass), so we now complete
--- all passes and set the exit code at the end.
----
+-- (internal) Run each pass in `order` in topological sequence.
+--
 -- @param ctx PassCtx
 -- @param order string[]
 -- @return boolean  -- true if any validation errors were reported

scripts/update_deps.ps1

@@ -4,25 +4,37 @@ $path_code      = join-path $path_root 'code'
 $path_scripts   = join-path $path_root 'scripts'
 $path_toolchain = join-path $path_root 'toolchain'
 
+# Halt on any error (instead of PowerShell's default `Continue`).
+$ErrorActionPreference = 'Stop'
+
 $misc = join-path $PSScriptRoot 'helpers/misc.ps1'
 . $misc
 
 # TODO(Ed): Review usage of these deps
-# I orgiinally cloned them when starting to get to the C runtime usage of the course
+# I originally cloned them when starting to get to the C runtime usage of the course
 # However, based on the heavy reliance of the PSX.Dev extension I might fallback; also
 # The gdb server doesn't need the full repo and were only using the src/mips
 # which has a standalone repo (nuggets)
 # armips may not be used at all but I'm not sure...
+#
+# PCSX-Redux: built via MSBuild (VS2022) — automated in the build section below.
+# Requires: VS2022 with C++ desktop workload + PlatformToolset=v143 retarget.
+# The .vcxproj files request v145; we pass /p:PlatformToolset=v143 to MSBuild.
+# NuGet packages are restored automatically on first build.
+# Output: toolchain\pcsx-redux\vsprojects\x64\Debug\pcsx-redux.exe
 
 $url_armips     = 'https://github.com/Kingcom/armips.git'
 $url_pcsx_redux = 'https://github.com/grumpycoders/pcsx-redux.git'
 $url_psyq_iwyu  = 'https://github.com/johnbaumann/psyq_include_what_you_use.git'
+$url_lpeg       = 'https://github.com/roberto-ieru/LPeg.git'
 
 $path_armips     = join-path $path_toolchain 'armips'
 $path_pcsx_redux = join-path $path_toolchain 'pcsx-redux'
 $path_psyq_iwyu  = join-path $path_toolchain 'psyq_iwyu'
+$path_lpeg       = join-path $path_toolchain 'lpeg'
 
 clone-gitrepo $path_armips     $url_armips
+clone-gitrepo $path_lpeg       $url_lpeg
 clone-gitrepo $path_pcsx_redux $url_pcsx_redux
 clone-gitrepo $path_psyq_iwyu  $url_psyq_iwyu
 
@@ -37,3 +49,83 @@ pop-location
 # $path_pcsx_redux_binaries   = join-path $path_pcsx_redux_vsprojects 'x64/Release'
 
 # $psyq_obj_parser = join-path $path_pcsx_redux_binaries 'psyq-obj-parser.exe'
+
+# ════════════════════════════════════════════════════════════════════════════
+# PCSX-Redux — built via MSBuild (VS2022)
+#
+# Requires: Visual Studio 2022 with the C++ desktop workload.
+# The .vcxproj files target platform toolset v145, but VS2022 ships v143;
+# we pass /p:PlatformToolset=v143 to retarget at build time (no file edits).
+# NuGet packages (glfw, luajit.native, libFFmpeg-lite, x64sentry) are
+# restored automatically by MSBuild on first build.
+#
+# Output: toolchain\pcsx-redux\vsprojects\x64\Debug\pcsx-redux.exe
+# ════════════════════════════════════════════════════════════════════════════
+
+# Locate MSBuild from the VS2022 install (no hardcoded path — uses vswhere).
+$vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+if (-not (Test-Path $vswhere)) {
+	write-error "vswhere not found at '$vswhere'. Install Visual Studio 2022 with the C++ desktop workload."
+	exit 1
+}
+$msbuild_exe = & $vswhere -latest -products * -requires Microsoft.Component.MSBuild -find "MSBuild\**\Bin\MSBuild.exe" 2>$null | Select-Object -First 1
+if (-not $msbuild_exe) {
+	write-error "MSBuild not found via vswhere. Install Visual Studio 2022 with the C++ desktop workload."
+	exit 1
+}
+
+$path_pcsx_sln = join-path $path_pcsx_redux 'vsprojects\pcsx-redux.sln'
+&	$msbuild_exe $path_pcsx_sln /p:Configuration=Release /p:Platform=x64 /p:PlatformToolset=v143 /m /v:minimal
+
+# Locate luajit via scoop. `luajit.exe` is on PATH via scoop's shim;
+# we use `scoop prefix` to find the install root for the include dir
+# (needed to compile lpeg against luajit's headers).
+# If scoop or luajit is missing, fail fast with an actionable message.
+$luajit_prefix = & scoop prefix luajit 2>$null
+if (-not $luajit_prefix -or -not (Test-Path (Join-Path $luajit_prefix 'bin/luajit.exe'))) {
+	write-error "luajit not found via 'scoop prefix luajit'. Install via: scoop install luajit"
+	exit 1
+}
+
+# Discover the luajit include dir by globbing `include/luajit-*`.
+# This avoids hardcoding a specific version (e.g. `luajit-2.1`).
+$luajit_include_root = Join-Path $luajit_prefix 'include'
+$lua_inc_dir = Get-ChildItem -Path $luajit_include_root -Directory -Filter 'luajit-*' -ErrorAction SilentlyContinue |
+	Select-Object -First 1 -ExpandProperty FullName
+if (-not $lua_inc_dir) {
+	write-error "No 'luajit-*' include dir found under '$luajit_include_root'. The scoop luajit install may be broken."
+	exit 1
+}
+
+# Generate lpeg.dll by compiling the 6 source files directly.
+# `gcc` is on PATH (scoop's shim puts it there).
+# The source files: lpcap.c lpcode.c lpcset.c lpprint.c lptree.c lpvm.c
+# (per the lpeg makefile — no `make.lua` template generator in this version).
+# Link against luajit's import library (`libluajit-5.1.a`) for the Lua C API symbols (lua_*, luaL_*).
+$luajit_lib_dir = Join-Path $luajit_prefix 'lib'
+$lpeg_sources = @('lpcap.c', 'lpcode.c', 'lpcset.c', 'lpprint.c', 'lptree.c', 'lpvm.c')
+$lpeg_compile_args = @(
+	'-O2', '-shared',
+	"-I$lua_inc_dir",
+	"-L$luajit_lib_dir",
+	'-o', 'lpeg.dll'
+) + $lpeg_sources + @('-lluajit-5.1')
+push-location $path_lpeg
+&	gcc @lpeg_compile_args
+pop-location
+
+# ════════════════════════════════════════════════════════════════════════════
+# OpenBIOS — built from the PCSX-Redux source tree via make + mipsel-none-elf
+#
+# OpenBIOS is an open-source PS1 BIOS implementation (no retail BIOS dump needed). 
+# It builds with the MIPS cross-toolchain (`mipsel-none-elf-gcc`, on PATH via the `mips` toolchain installer) 
+# + `make` (on PATH via scoop).
+#
+# Output: toolchain\pcsx-redux\src\mips\openbios\openbios.bin
+# ════════════════════════════════════════════════════════════════════════════
+
+$path_openbios = join-path $path_pcsx_redux 'src\mips\openbios'
+push-location $path_openbios
+&	make clean
+&	make
+pop-location