Fix off by one ahead issue with stepping into atoms. Support for local register symbols used in atoms + atom bindings locals in gdb.

.vscode/launch.json

@@ -4,7 +4,7 @@
 	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 	"version": "0.2.0",
 	"configurations": [
-		{
+{
 			"name": "Debug: Hello Psy-Q!",
 			"type": "gdb",
 			"request": "attach",
@@ -12,6 +12,10 @@
 			"remote": true,
 			"cwd": "${workspaceRoot}/build",
 			"valuesFormatting": "parseText",
+			"registerLimit": "1-32",
+			"frameFilters": false,
+			"showDevDebugOutput": false,
+			"printCalls": false,
 			"stopAtConnect": true,
 			"gdbpath": "gdb-multiarch",
 			"windows": {
@@ -21,9 +25,16 @@
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_psyq.elf",
+			"setupCommands": [
+				{ "text": "set mi-async off" },
+				{ "text": "set remotetimeout 0" },
+				{ "text": "set logging file build/gen/hello_gte.gdb.log" },
+				{ "text": "set logging redirect on" }
+			],
 			"autorun": [
 				"monitor reset shellhalt",
 				"load hello_psyq.elf",
+				"source scripts/gdb/gdb_tape_atoms.gdb",
 				"tbreak main",
 				"continue"
 			]
@@ -36,6 +47,10 @@
 			"remote": true,
 			"cwd": "${workspaceRoot}/build",
 			"valuesFormatting": "parseText",
+			"registerLimit": "1-32",
+			"frameFilters": false,
+			"showDevDebugOutput": false,
+			"printCalls": false,
 			"stopAtConnect": true,
 			"gdbpath": "gdb-multiarch",
 			"windows": {
@@ -45,6 +60,12 @@
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_gpu.elf",
+			"setupCommands": [
+				{ "text": "set mi-async off" },
+				{ "text": "set remotetimeout 0" },
+				{ "text": "set logging file build/gen/hello_gte.gdb.log" },
+				{ "text": "set logging redirect on" }
+			],
 			"autorun": [
 				"monitor reset shellhalt",
 				"load hello_gpu.elf",
@@ -60,6 +81,10 @@
 			"remote": true,
 			"cwd": "${workspaceRoot}/build",
 			"valuesFormatting": "parseText",
+			"registerLimit": "1-32",
+			"frameFilters": false,
+			"showDevDebugOutput": false,
+			"printCalls": false,
 			"stopAtConnect": true,
 			"gdbpath": "gdb-multiarch",
 			"windows": {
@@ -69,12 +94,54 @@
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_gte.elf",
+			"setupCommands": [
+				{ "text": "set mi-async off" },
+				{ "text": "set remotetimeout 0" },
+				{ "text": "set logging file build/gen/hello_gte.gdb.log" },
+				{ "text": "set logging redirect on" }
+			],
 			"autorun": [
 				"monitor reset shellhalt",
 				"load hello_gte.elf",
 				"tbreak main",
 				"continue"
 			]
+		},
+		{
+			"name": "Debug: Hello GTE Psy-Q! (atoms debug — DWARF-injected)",
+			"type": "gdb",
+			"request": "attach",
+			"target": "localhost:3333",
+			"remote": true,
+			"cwd": "${workspaceRoot}",
+			"valuesFormatting": "parseText",
+			"registerLimit": "1-32",
+			"frameFilters": false,
+			"showDevDebugOutput": false,
+			"printCalls": false,
+			"stopAtConnect": true,
+			"gdbpath": "gdb-multiarch",
+			"windows": {
+				"gdbpath": "gdb-multiarch.exe"
+			},
+			"osx": {
+				"gdbpath": "gdb"
+			},
+			"executable": "${workspaceRoot}/build/hello_gte.dwarf-injected.elf",
+			"setupCommands": [
+				{ "text": "set mi-async off" },
+				{ "text": "set remotetimeout 0" },
+				{ "text": "set logging file build/gen/hello_gte.gdb.log" },
+				{ "text": "set logging redirect on" }
+			],
+			"autorun": [
+				"monitor reset shellhalt",
+				"load build/hello_gte.dwarf-injected.elf",
+				"source scripts/gdb/gdb_tape_atoms.gdb",
+				"tbreak main",
+				"continue"
+			]
 		}
 	]
 }
+

code/duffle/lottes_tape.h

@@ -14,7 +14,7 @@ typedef U4 const MipsCode;
 typedef Slice_(MipsCode);
 typedef Slice_MipsCode MipsAtom;
 
-#define MipsAtom_(sym) MipsCode tmpl(code,sym) [] align_(4) =
+#define MipsAtom_(sym) MipsCode sym [] align_(4) =
 
 // Bare form: file-scope declaration with hardcoded body.
 // Used for components with no args (e.g., ac_load_tri_indices) or identifier-args (hardcoded register names).
@@ -89,13 +89,13 @@ FI_ void        tb_init(TapeBuilder* tb, FArena* arena) { tb->ptr = arena->start
 FI_ TapeBuilder tb_make_old(             FArena* arena) { return (TapeBuilder){ arena->start, 0 }; }
 FI_ TapeBuilder tb_make(Slice mem) { return (TapeBuilder){ mem.ptr, mem.len, 0 }; }
 
-#define tb_emit_(tb, atom) tb_emit(tb, tmpl(code,atom))
+#define tb_emit_(tb, atom) tb_emit(tb, atom)
 FI_ void tb_emit(TapeBuilder* tb, MipsCode* atom) { u4_r(tb->ptr)[tb->used] = u4_(atom); ++ tb->used; }
 FI_ void tb_data(TapeBuilder* tb, U4        data) { u4_r(tb->ptr)[tb->used] = u4_(data); ++ tb->used; }
 
-FI_ Slice_U4 tb_end  (TapeBuilder* tb) { tb_emit(tb,code_tape_exit); return (Slice_U4){ C_(U4*,tb->ptr), tb->used }; }
+FI_ Slice_U4 tb_end  (TapeBuilder* tb) { tb_emit(tb,tape_exit); return (Slice_U4){ C_(U4*,tb->ptr), tb->used }; }
 FI_ Slice_U4 tb_slice(TapeBuilder  tb) {                             return (Slice_U4){ C_(U4*,tb.ptr),  tb.used }; }
-#define tb_scope(tb) for(U4 tbs_once=0;tbs_once==0;++tbs_once,tb_emit(tb,code_tape_exit))
+#define tb_scope(tb) for(U4 tbs_once=0;tbs_once==0;++tbs_once,tb_emit(tb,tape_exit))
 
 #pragma endregion Tape Drive
 
@@ -237,9 +237,8 @@ FI_ void atombuilder_unroll(MipsAtomBuilder_R ab, Slice_MipsCode_R code) {
 
 // When done authoring, utilize this to cap-off the atom
 FI_ void atombuilder_end(MipsAtomBuilder_R ab) {
-	LP_ MipsAtom_(yield) { mac_yield() };
-	mem_copy(ab->start, u4_(code_yield), S_(code_yield));
-	mem_bump(ab->start, ab->capacity, & ab->used, S_(code_yield));
+	mem_copy(ab->start, u4_(ac_yield), S_(ac_yield));
+	mem_bump(ab->start, ab->capacity, & ab->used, S_(ac_yield));
 }
 
 #define mipsatom_from_builder(ab) (MipsAtom){ab.start, ab.used}

code/gte_hello/hello_gte.c

@@ -261,7 +261,7 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 
 		LP_ U4 mem_temp_tape[512]; FArena tape_arena; farena_init(& tape_arena, slice_ut_arr(mem_temp_tape));
 		TapeBuilder tb = tb_make_old(&tape_arena); tb_scope(& tb) {
-			tb_emit(& tb, code_rbind_cube_g4_face);
+			tb_emit(& tb, rbind_cube_g4_face);
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.cube.faces));
 				tb_data(& tb, u4_(smem.cube.verts));
@@ -269,10 +269,10 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 
 			for (U4 i = 0; i < Cube_num_faces; i++) {
 				// Two triangles per quad face: (x,y,z) and (x,z,w)
-				tb_emit(& tb, code_cube_g4_face);
+				tb_emit(& tb, cube_g4_face);
 			}
 
-			tb_emit(& tb, code_sync_primitive_arena);
+			tb_emit(& tb, sync_primitive_arena);
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
@@ -350,20 +350,20 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		// Prepare the tape. (Push protocol to tape)
 		LP_ U4 mem_temp_tape[512];
 		TapeBuilder tb = tb_make(slice_ut_arr(mem_temp_tape)); tb_scope(& tb) {
-			tb_emit(& tb, code_set_gte_world);
+			tb_emit(& tb, set_gte_world);
 				tb_data(& tb, u4_(& smem.tform_world));
 
-			tb_emit(& tb, code_rbind_floor_f3_face);
+			tb_emit(& tb, rbind_floor_f3_face);
 			// TODO(Ed): Just use a single context struct ref
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.floor.faces));
 				tb_data(& tb, u4_(smem.floor.verts));
 				tb_data(& tb, u4_(ordering_buf));
 			for (U4 i = 0; i < Floor_num_faces; i++) {
-				tb_emit(& tb, code_floor_f3_face);
+				tb_emit(& tb, floor_f3_face);
 			}
-			// After code_floor_f3_face iterations complete, the primitive arena's used counter needs updating.
-			tb_emit(& tb, code_sync_primitive_arena);
+			// After floor_f3_face iterations complete, the primitive arena's used counter needs updating.
+			tb_emit(& tb, sync_primitive_arena);
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}

code/gte_hello/hello_gte_tape.c

@@ -27,10 +27,10 @@ internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri)
 ,	atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
-	load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)), 
-	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)), 
-	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)), 
-	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)), 
+	load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)),
+	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
+	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
+	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
@@ -41,7 +41,7 @@ internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri)
  *  Reads 4 indices from R_FaceCur (V4_S2 = 8 bytes), loads 4 vertices into
  *  the GTE, runs the PsyQ RotAverageNclip4 sequence, and renders a Poly_G4.
  */
-internal 
+internal
 MipsAtom_(cube_g4_face) atom_info(
 		atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase),
 		atom_writes(R_PrimCursor, R_FaceCursor)
@@ -94,21 +94,21 @@ typedef Struct_(Binds_FloorTri) {
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
-internal 
+internal
 MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri)
 	, atom_reads(R_TapePtr)
 	, atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
-	load_word(R_PrimCursor, R_TapePtr, O_(Binds_FloorTri,PrimCursor)), 
-	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)), 
-	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)), 
-	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)), 
+	load_word(R_PrimCursor, R_TapePtr, O_(Binds_FloorTri,PrimCursor)),
+	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
+	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
+	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 
-internal 
+internal
 MipsAtom_(floor_f3_face) atom_info(
 	, atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 	, atom_writes(R_PrimCursor, R_FaceCursor)
@@ -117,7 +117,7 @@ MipsAtom_(floor_f3_face) atom_info(
 	mac_gte_load_tri_verts(R_T0, R_T1, R_T2),
 	nop2, gte_cmdw_rotate_translate_perspective_triple,
 	nop2, gte_cmdw_nclip,
- 
+
 	/* Culling (Branch forward if Backface) */
 	nop2, gte_mv_from_data_r(R_T0, C2_MAC0),
 	nop,
@@ -125,21 +125,21 @@ MipsAtom_(floor_f3_face) atom_info(
 	/* Format Primitive */
 	mac_format_f3_color(0xFF, 0xFF, 0xFF),  // RGB-form (R=FF, G=FF, B=FF = white)
 	mac_gte_store_f3_post_rtpt(),
-	
+
 	/* Calculate Depth */
-	nop2, gte_avg_sort_z3,            
-	nop2, gte_mv_from_data_r(R_T1, C2_OTZ),      
+	nop2, gte_avg_sort_z3,
+	nop2, gte_mv_from_data_r(R_T1, C2_OTZ),
 	/* Bounds Check OTZ < 2048 (Branch forward to skip insertion) */
-	add_ui(      R_AT, R_0,  OrderingTbl_Len),   
-	set_lt_u(    R_AT, R_T1, R_AT), 
-	branch_equal(R_AT, R_0,  atom_offset(bounds_chk, floor_f3_face_exit)), nop, 
+	add_ui(      R_AT, R_0,  OrderingTbl_Len),
+	set_lt_u(    R_AT, R_T1, R_AT),
+	branch_equal(R_AT, R_0,  atom_offset(bounds_chk, floor_f3_face_exit)), nop,
 	/* Insert into Ordering Table Linked List */
 	mac_insert_ot_tag_f3(),
 	add_ui_self(R_PrimCursor, S_(Poly_F3)), /* Advance Prim Cursor (5 words) */
 		// Note(Ed): No bounds checking, should be checked before atom runs.
 
 /* Advance Input Cursor & Yield (Both branch targets land here) */
-atom_label(floor_f3_face_exit) 
+atom_label(floor_f3_face_exit)
 	add_ui_self(R_FaceCursor, S_(S2) * 4),  /* Advance Face Cursor (4 * S2 = 8 bytes) */
 	mac_yield()
 };
@@ -150,7 +150,7 @@ internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitive
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
-	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),      
+	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor

readme.md

@@ -27,6 +27,13 @@ scoop install luajit
 
 * Lua is slow (even jitted) so this helps.
 
+[lfs (LuaFileSystem)](https://github.com/lunarmodules/luafilesystem)
+
+* Native directory enumeration + `mkdir` for the build scripts.
+* Used by `passes/word_count_eval.lua :: scan_dir` (native walk vs. `dir /b /s` subprocess,
+  ~2ms vs. ~56ms) and by `duffle.lua :: ensure_dir` + `to_absolute_path` (avoids
+  `cmd.exe mkdir` + `cd` shell spawns, ~50ms each).
+
 [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

scratch/gte_debug.lua

@@ -0,0 +1,30 @@
+-- gte_debug.lua — defensive version + prints error context.
+local ok, err = pcall(function()
+    print("[debug] PCSX exists:", PCSX ~= nil)
+    print("[debug] PCSX.WebServer exists:", PCSX and PCSX.WebServer ~= nil)
+    print("[debug] PCSX.WebServer.Handlers exists:", PCSX and PCSX.WebServer and PCSX.WebServer.Handlers ~= nil)
+    if not PCSX.WebServer then
+        print("[debug] creating PCSX.WebServer...")
+        PCSX.WebServer = {}
+    end
+    if not PCSX.WebServer.Handlers then
+        print("[debug] creating PCSX.WebServer.Handlers...")
+        PCSX.WebServer.Handlers = {}
+    end
+    print("[debug] type of Handlers:", type(PCSX.WebServer.Handlers))
+
+    PCSX.WebServer.Handlers.gte = function(req)
+        local r = PCSX.getRegisters()
+        local out = { "pc=0x" .. string.format("%x", r.pc) }
+        for i = 0, 31 do
+            out[#out + 1] = string.format("D[%d]=0x%08x C[%d]=0x%08x",
+                i, r.CP2D.r[i], i, r.CP2C.r[i])
+        end
+        return table.concat(out, "\n")
+    end
+    print("[debug] handler registered")
+end)
+
+if not ok then
+    print("[debug] ERROR: " .. tostring(err))
+end

scripts/audit_lua_nesting.lua

@@ -168,28 +168,18 @@ if arg and arg[1] then
 	end
 
 	-- Accept either a directory or a file path. Directory args are
-	-- expanded via `dir /b *.lua` (Windows) or `ls *.lua` (Unix).
+	-- expanded via lfs.dir (native, no subprocess).
+	local lfs = require("lfs")
 	local function is_dir(p)
-		local f = io.open(p, "r")
-		if    f then f:close() return false end
-		return true
+		return lfs.attributes(p, "mode") == "directory"
 	end
 	local function list_lua(dir)
 		local out = {}
-		local cmd
-		if package.config:sub(1, 1) == "\\" then
-			cmd = 'dir /b "' .. dir .. '\\*.lua" 2>nul'
-		else
-			cmd = 'ls -1 "' .. dir .. '"/*.lua 2>/dev/null'
-		end
-		local p = io.popen(cmd)
-		if p then
-			for line in p:lines() do
-				if line:match("%.lua$") then
-					out[#out + 1] = dir .. "/" .. line
-				end
+		if not is_dir(dir) then return out end
+		for entry in lfs.dir(dir) do
+			if entry:match("%.lua$") then
+				out[#out + 1] = dir .. "/" .. entry
 			end
-			p:close()
 		end
 		return out
 	end

scripts/build_psyq.ps1

@@ -321,11 +321,12 @@ function ps1-meta { param(
 		[Parameter(Mandatory=$true)][string[]]$sources,
 		[Parameter(Mandatory=$true)][string]$metadata,
 		[string]$out_root = (join-path $path_build 'gen'),
-		[string[]]$passes = @('--all')
+		[string[]]$passes = @('--all'),
+		[string[]]$extra_args = @()
 	)
 	$script = join-path $path_scripts 'ps1_meta.lua'
 	write-host "ps1-meta  $($sources.Count) source(s), passes=$($passes -join ',')" ` -ForegroundColor Magenta
-	$arg_list = @($passes) + @('--metadata', $metadata) + @('--out-root', $out_root)
+	$arg_list = @($passes) + @('--metadata', $metadata) + @('--out-root', $out_root) + @($extra_args)
 	foreach ($s in $sources) { $arg_list += @('--source', $s) }
 	& luajit $script @arg_list
 	if ($LASTEXITCODE -ne 0) {
@@ -383,6 +384,111 @@ function build-gte_hello {
 	)
 	link-modules $link_modules $elf $link_args
 	make-binary $elf $exe
+
+	# TODO(Ed): Do both -gdb-runtime and dwarf-injection passes in a single ps1-meta call.
+
+	# Post-link: emit ONLY build/gen/gdb_tape_atoms_runtime.gdb.
+	# The per-source *.atoms.sourcemap.txt was already generated by the pre-link --all call,
+	# so we skip --atoms-source-map here to avoid re-doing the work. 
+	# The gdb-runtime emission requires --elf (for nm-based address lookup) so it MUST happen post-link.
+	ps1-meta -sources $atom_sources -metadata $path_atom_metadata `
+		-out_root (join-path $path_build 'gen') `
+		-passes @('--gdb-runtime') `
+		-extra_args @('--elf', $elf)
+	# F' + G' consolidated: --dwarf-injection now emits 7 .bin blobs 
+	# (.debug_line, .debug_aranges, .debug_rnglists, .debug_info, .debug_abbrev, .debug_str, .debug_loc) all in one pass.
+	ps1-meta -sources $atom_sources -metadata $path_atom_metadata `
+		-out_root (join-path $path_build 'gen') `
+		-passes @('--dwarf-injection') `
+		-extra_args @('--elf', $elf)
+
+	#TODO(Ed): Move the below into ps-1 meta pass to reduce syscall latency?
+
+	# F' track: post-link DWARF injection. The new Lua pass writes build/gen/<basename>.dwarf_*.bin blobs; 
+	# we splice them into a COPY of the ELF via objcopy --update-section (works fine from PowerShell).
+	# The un-injected $elf + $exe are unchanged (shipping binary).
+	$dwarfLineBin    = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_line.bin'
+	$dwarfArangesBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_aranges.bin'
+	$dwarfRnglistsBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_rnglists.bin'
+	$injectElf       = Join-Path $path_build 'hello_gte.dwarf-injected.elf'
+	if ((Test-Path $dwarfLineBin) -and (Test-Path $dwarfArangesBin) -and (Test-Path $dwarfRnglistsBin)) 
+	{
+		Write-Host "[build] DWARF-injecting $elf -> $injectElf"
+		Copy-Item -LiteralPath $elf -Destination $injectElf
+		& $Objcopy --update-section ".debug_line=$dwarfLineBin"    $injectElf
+		$last_exit_code_error = $LASTEXITCODE -ne 0
+		if ($last_exit_code_error) {
+			Write-Warning "[build] objcopy .debug_line update failed (exit $LASTEXITCODE); removing $injectElf"
+			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
+			return;
+		} 
+		& $Objcopy --update-section ".debug_aranges=$dwarfArangesBin" $injectElf
+		$last_exit_code_error = $LASTEXITCODE -ne 0
+		if ($LASTEXITCODE -ne 0) {
+			Write-Warning "[build] objcopy .debug_aranges update failed (exit $LASTEXITCODE); removing $injectElf"
+			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
+			return;
+		}
+		& $Objcopy --update-section ".debug_rnglists=$dwarfRnglistsBin" $injectElf
+		if ($LASTEXITCODE -ne 0) {
+			Write-Warning "[build] objcopy .debug_rnglists update failed (exit $LASTEXITCODE); removing $injectElf"
+			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
+		} 
+		else 
+		{
+			# Baked atoms execute from RAM but are emitted as C data arrays, so their ELF sections lack SHF_EXECINSTR. 
+			# GDB discards line rows for non-code sections. 
+			# Mark only the debug-copy sections executable; the shipping ELF and PS-EXE remain byte/flag unchanged.
+			& $Objcopy `
+				--set-section-flags ".rodata=alloc,load,readonly,code,contents" `
+				--set-section-flags ".data=alloc,load,data,code,contents" `
+				$injectElf
+			if ($LASTEXITCODE -ne 0) {
+				Write-Warning "[build] objcopy atom-section flag update failed (exit $LASTEXITCODE); removing $injectElf"
+				Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
+			} else {
+				Write-Host "[build] DWARF-injected ELF: $injectElf"
+			}
+		}
+	}
+
+	# G' (atom locals) is now part of --dwarf-injection.
+	# The F' splice block above already covered .debug_line / .debug_aranges / .debug_rnglists;
+	# we extend the same Copy-Item + objcopy chain to splice the G' 4 sections
+	# (.debug_info, .debug_abbrev, .debug_str via --update-section; .debug_loc via --add-section since it doesn't exist in the source ELF).
+	$dwarfInfoBin   = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_info.bin'
+	$dwarfAbbrevBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_abbrev.bin'
+	$dwarfStrBin    = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_str.bin'
+	$dwarfLocBin    = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_loc.bin'
+	if ((Test-Path $dwarfInfoBin) -and (Test-Path $dwarfAbbrevBin) -and (Test-Path $dwarfStrBin) -and (Test-Path $dwarfLocBin)) 
+	{
+		Write-Host "[build] G' atom-locals: splicing .debug_info/.debug_abbrev/.debug_str/.debug_loc into $injectElf"
+		& $Objcopy --update-section ".debug_info=$dwarfInfoBin"     $injectElf
+		$last_exit_code_error = ($LASTEXITCODE -ne 0) 
+		if ($last_exit_code_error) {
+			Write-Warning "[build] objcopy .debug_info update failed (exit $LASTEXITCODE)"
+			return;
+		} 
+		& $Objcopy --update-section ".debug_abbrev=$dwarfAbbrevBin" $injectElf
+		if ($LASTEXITCODE -ne 0) {
+			Write-Warning "[build] objcopy .debug_abbrev update failed (exit $LASTEXITCODE)"
+			return;
+		} 
+		& $Objcopy --update-section ".debug_str=$dwarfStrBin"      $injectElf
+		if ($LASTEXITCODE -ne 0) {
+			Write-Warning "[build] objcopy .debug_str update failed (exit $LASTEXITCODE)"
+		} 
+		else 
+		{
+			# .debug_loc doesn't exist in the source ELF; --add-section creates it.
+			& $Objcopy --add-section ".debug_loc=$dwarfLocBin"     $injectElf
+			if ($LASTEXITCODE -ne 0) {
+				Write-Warning "[build] objcopy .debug_loc add-section failed (exit $LASTEXITCODE)"
+			} else {
+				Write-Host "[build] G' atom-locals-injected: $injectElf"
+			}
+		}
+	}
 }
 build-gte_hello
 

scripts/duffle.lua

@@ -12,19 +12,13 @@
 ---   - **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.
----
---- **No `:match` / `:gmatch` regex use anywhere**; 
---- all delimiter-splitting is hand-rolled or via LPeg (the regex-free PEG library).
 
 local M = {}
 
--- Optional native extension: lfs (LuaFileSystem). When present, ensure_dir uses
--- lfs.attributes + lfs.mkdir instead of spawning `cmd.exe mkdir` — saves ~55ms per
--- unique directory on Windows. Built by `update_deps.ps1` to `toolchain/lfs/lfs.dll`
--- and wired into package.cpath by `scripts/duffle_paths.lua`.
-local lfs = pcall(require, "lfs") and require("lfs") or nil
+-- Required native extension: lfs (LuaFileSystem). Built by `update_deps.ps1` to
+-- `toolchain/lfs/lfs.dll` and wired into package.cpath by `scripts/duffle_paths.lua`.
+-- If lfs is missing, `require` throws — fail loud per the build-tool convention.
+local lfs = require("lfs")
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Cross-file type aliases
@@ -47,96 +41,55 @@ local lfs = pcall(require, "lfs") and require("lfs") or nil
 -- ASCII byte constants
 -- ════════════════════════════════════════════════════════════════════════════
 
-local BYTE_SPACE      = 32    -- ' '
-local BYTE_TAB        = 9     -- '\t'
-local BYTE_NEWLINE    = 10    -- '\n'
-local BYTE_CR         = 13    -- '\r'
-local BYTE_VT         = 11    -- '\v'
-local BYTE_FF         = 12    -- '\f'
+local BYTE_SPACE      = 0x20    -- ' '
+local BYTE_TAB        = 0x09    -- '\t'
+local BYTE_NEWLINE    = 0x0A    -- '\n'
+local BYTE_CR         = 0x0D    -- '\r'
+local BYTE_VT         = 0x0B    -- '\v'
+local BYTE_FF         = 0x0C    -- '\f'
 
-local BYTE_UNDERSCORE = 95    -- '_'
-local BYTE_DOT        = 46    -- '.'
-local BYTE_SLASH      = 47    -- '/'
-local BYTE_BACKSLASH  = 92    -- '\\'
-local BYTE_STAR       = 42    -- '*'
-local BYTE_DQUOTE     = 34    -- '"'
-local BYTE_SQUOTE     = 39    -- '\''
-local BYTE_COMMA      = 44    -- ','
-local BYTE_SEMI       = 59    -- ';'
+local BYTE_UNDERSCORE = 0x5F    -- '_'
+local BYTE_DOT        = 0x2E    -- '.'
+local BYTE_SLASH      = 0x2F    -- '/'
+local BYTE_BACKSLASH  = 0x5C    -- '\\'
+local BYTE_STAR       = 0x2A    -- '*'
+local BYTE_DQUOTE     = 0x22    -- '"'
+local BYTE_SQUOTE     = 0x27    -- '\''
+local BYTE_COMMA      = 0x2C    -- ','
+local BYTE_SEMI       = 0x3B    -- ';'
 
-local BYTE_OPEN_PAREN  = 40   -- '('
-local BYTE_OPEN_BRACE  = 123  -- '{'
-local BYTE_OPEN_BRACK  = 91   -- '['
+local BYTE_OPEN_PAREN  = 0x28   -- '('
+local BYTE_OPEN_BRACE  = 0x7B   -- '{'
+local BYTE_OPEN_BRACK  = 0x5B   -- '['
 
-local BYTE_LOWER_A = 97       -- 'a'
-local BYTE_LOWER_Z = 122      -- 'z'
-local BYTE_UPPER_A = 65       -- 'A'
-local BYTE_UPPER_Z = 90       -- 'Z'
+local BYTE_LOWER_A = 0x61       -- 'a'
+local BYTE_LOWER_Z = 0x7A       -- 'z'
+local BYTE_UPPER_A = 0x41       -- 'A'
+local BYTE_UPPER_Z = 0x5A       -- 'Z'
 
-local BYTE_DIGIT_0 = 48       -- '0'
-local BYTE_DIGIT_9 = 57       -- '9'
+local BYTE_DIGIT_0 = 0x30       -- '0'
+local BYTE_DIGIT_9 = 0x39       -- '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 sruns and sets `package.path` + `package.cpath` so subsequent `require`s resolve.
--- Idempotent: re-loads just re-set the same paths.
+-- Path setup is done by `scripts/duffle_paths.lua`, which derives the repo
+-- root from `debug.getinfo(1, "S").source` (NO subprocess, ~0ms) and
+-- then calls `require("duffle")`. The prior `io.popen("git rev-parse ...")`
+-- approach in this section was removed during F'' because:
 --
--- **Entry scripts** trigger this with one line:
--- `local duffle = dofile(arg[0]:match("(.*[/\\])") .. "/../duffle.lua")` which runs this top-level + returns `M`.
+--   1. Every entry script + every passes script now uses
+--      `dofile("duffle_paths.lua")` (14 call sites; verified via grep).
+--      The `find_repo_root` / `setup_package_path` defined here was dead
+--      code in practice.
+--   2. `git rev-parse` costs ~100-180ms per subprocess spawn on Windows.
+--      `debug.getinfo` is <1ms. There's no reason to keep the slow path
+--      even as a "fallback".
 --
--- **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.
-	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
-	if p then
-		root = p:read("*l")
-		p:close()
-	end
-	if not root or root == "" then return nil end
-	if not root:match("[/\\]$") then root = root .. "/" end
-	package.loaded.__duffle_repo_root__ = root
-	return root
-end
-
---- Set `package.path`  (for `require("duffle")` + `require("passes.X")`)
---- and `package.cpath` (for `lpeg.dll` on Windows).
-function M.setup_package_path()
-	local repo_root = find_repo_root()
-	if not repo_root then
-		io.stderr:write("[duffle] git rev-parse failed -- not in a git repo?\n")
-		os.exit(2)
-	end
-
-	-- 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;"
-		.. scripts_dir .. "?/init.lua;"
-		.. passes_dir .. "?.lua;"
-		.. 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.)
-	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).
+-- If a future use case ever needs to load `duffle.lua` WITHOUT going
+-- through `duffle_paths.lua`, set `package.path` manually before `require`.
+-- See `docs/guide_metaprogram_ssdl.md` §"I/O primitives" for the pattern.
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Section 0: LPeg patterns (compiled once at module load)
@@ -179,7 +132,7 @@ local lpeg_block_cmt_pat = P("/*") * (P(1) - P("*/"))^0 * P("*/")
 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")
+local ws_pat              = S(" \t\n\r\v\f")
 local lpeg_ws_and_cmt_pat = (ws_pat + lpeg_str_or_cmt_pat)^0
 
 -- Generic "skip until target, but step over balanced groups" matcher.
@@ -191,11 +144,9 @@ local lpeg_scan_to_target_pat = function(target) return (P(1) - P(target))^0  en
 -- ════════════════════════════════════════════════════════════════════════════
 -- Section 1: character classification (byte-based for hot loops)
 -- ════════════════════════════════════════════════════════════════════════════
---
 -- Two APIs:
 --   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(pos, pos) call.
 
 -- Whitespace characters per C locale.
@@ -215,8 +166,8 @@ function M.is_digit_byte(b) return b and b >= BYTE_DIGIT_0 and b <= BYTE_DIGIT_9
 -- Letter OR digit OR underscore.
 function M.is_alnum_byte(b) return M.is_alpha_byte(b) or M.is_digit_byte(b) end
 
--- String-based wrappers (kept for callers that already have a single-char
--- string; the byte versions are what the hot loops should call).
+-- String-based wrappers (kept for callers that already have a single-char string;
+-- the byte versions are what the hot loops should call).
 function M.is_space(c)
 	if type(c) == "number" then return M.is_space_byte(c) end
 	return c == " "  or c == "\t" or c == "\n" or c == "\r" or c == "\v" or c == "\f"
@@ -246,7 +197,6 @@ function M.trim(s)
 end
 
 -- Linear-search for a single-byte target in a string.
--- (Phase 3 retained this for places where LPeg is overkill.)
 -- @param haystack string
 -- @param target integer  -- byte value
 -- @param start integer   -- optional 1-indexed start (default 1)
@@ -311,11 +261,30 @@ function M.write_file_lf(path, content)
 	f:write(content); f:close()
 end
 
+-- Return `{path, ...}` for files in `out_root` whose basename matches
+-- `pattern` (Lua pattern, NOT regex — `%.` not `\.`). Empty list if
+-- `out_root` doesn't exist or matches nothing.
+--
+-- **Cost:** ~2ms native (lfs.dir) vs ~56ms subprocess (`dir /b`).
+-- @param out_root Path
+-- @param pattern string  -- Lua pattern matched against basename only
+-- @return string[]
+function M.list_dir(out_root, pattern)
+	local files = {}
+	if lfs.attributes(out_root, "mode") ~= "directory" then return files end
+	for entry in lfs.dir(out_root) do
+		if entry:match(pattern) then
+			files[#files + 1] = out_root .. "\\" .. entry
+		end
+	end
+	return files
+end
+
 -- Convert a (possibly relative) path to an absolute path, using CWD if needed.
 -- Normalizes forward slashes to backslashes on Windows.
 -- Used for byte-identical emit: the // Source: comment line uses the absolute path.
 --
--- The CWD is memoized (one `io.popen("cd")` per process — ~50ms on Windows).
+-- The CWD is memoized on first call (one lfs.currentdir() per process — ~0ms).
 -- Without the cache, calling this per-source in the components pass added ~1.5s to a 30-source build.
 -- @param path string
 -- @return string
@@ -329,16 +298,8 @@ function M.to_absolute_path(path)
 		_absolute_path_cache[path] = result
 		return result
 	end
-	-- Native: lfs.currentdir() is ~0ms vs io.popen("cd") at ~50ms per call.
-	local cwd
-	if lfs then
-		cwd = lfs.currentdir()
-	else
-		local p = io.popen("cd")
-		if not p then _absolute_path_cache[path] = path; return path end
-		cwd = p:read("*l")
-		p:close()
-	end
+	-- lfs.currentdir() is ~0ms vs io.popen("cd") at ~50ms per call on Windows.
+	local cwd = lfs.currentdir()
 	if not cwd then _absolute_path_cache[path] = path; return path end
 	cwd = cwd:gsub("/", "\\")
 	local tail = (path:gsub("/", "\\"))
@@ -356,15 +317,9 @@ local _ensured_dirs = {}
 function M.ensure_dir(path)
 	if _ensured_dirs[path] then return end
 	_ensured_dirs[path] = true
-	if lfs then
-		-- Native: ~0ms when dir exists (the common case). lfs.mkdir on a new dir is ~2ms (no shell spawn).
-		-- Falls through silently if lfs.mkdir fails (e.g. permission denied); the subsequent write_file will surface the error.
-		if lfs.attributes(path, "mode") ~= "directory" then lfs.mkdir(path) end
-	else
-		-- Fallback: shell mkdir. Slow (~55ms per call on Windows due to cmd.exe spawn) but works without lfs.
-		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'))
-	end
+	-- lfs.attributes + lfs.mkdir: ~0ms when dir exists, ~2ms when creating. No shell spawn.
+	-- Falls through silently if lfs.mkdir fails (e.g. permission denied); the subsequent write_file will surface the error.
+	if lfs.attributes(path, "mode") ~= "directory" then lfs.mkdir(path) end
 end
 
 -- Test helper: clear the cache (used by tests + between process runs).
@@ -374,7 +329,7 @@ function M._reset_ensured_dirs() _ensured_dirs = {} end
 -- Group a list of `SourceFile`-shaped records by their `dir` field.
 -- Used by the annotation / static-analysis / report passes to partition sources into per-DIRECTORY (per-module) buckets
 -- before emitting per-module reports. Insertion order preserved within each bucket (matches source order in `ctx.sources`).
--- @param sources table[]   -- list of source records (each having a `dir` string field)
+-- @param sources table[]          -- list of source records (each having a `dir` string field)
 -- @return table<string, table[]>  -- map of `dir` -> sources in that dir
 function M.group_sources_by_dir(sources)
 	local by_dir = {}
@@ -390,7 +345,7 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- 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.
+-- Returns the position just past the construct, or `pos` unchanged if no string/comment starts there.
 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 `pos`.
@@ -398,7 +353,7 @@ function M.skip_str_or_cmt(s, pos) return lpeg.match(lpeg_str_or_cmt_pat, s, pos
 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 `pos`. 
--- Returns the identifier string + the position just past it, or nil + pos if no identifier starts here. LPeg-backed.
+-- Returns the identifier string + the position just past it, or nil + pos if no identifier starts here.
 function M.read_ident(s, pos)
 	local result = lpeg.match(lpeg_ident_pat, s, pos)
 	if    result then return result, pos + #result end
@@ -543,8 +498,8 @@ function M.split_top_level_commas(body)
 
 	while pos <= body_len do
 		local  c = body:byte(pos)
-		if     c == BYTE_OPEN_PAREN then local _, a = M.read_parens(body, pos); pos = a -- scan: ... ( <balanced> ...
-		elseif c == BYTE_OPEN_BRACE then local _, a = M.read_braces(body, pos); pos = a -- scan: ... { <balanced> ...
+		if     c == BYTE_OPEN_PAREN then local _, a = M.read_parens(body, pos);   pos = a -- scan: ... ( <balanced> ...
+		elseif c == BYTE_OPEN_BRACE then local _, a = M.read_braces(body, pos);   pos = a -- scan: ... { <balanced> ...
 		elseif c == BYTE_OPEN_BRACK then local _, a = M.read_brackets(body, pos); pos = a -- scan: ... ( <balanced> ...
 		elseif c == BYTE_COMMA then
 			-- scan: ... <token> , <next> ...
@@ -585,8 +540,9 @@ end
 -- Moved here from passes/static_analysis.lua so all passes can share the memoized
 -- per-body tokenization. The memoization key is the body string (immutable per pass).
 
-local _tokenize_body_cache    = {}
-local _body_line_index_cache  = {}
+local _tokenize_body_cache        = {}
+local _tokenize_body_simple_cache = {}
+local _body_line_index_cache      = {}
 
 --- Tokenize the body inner-text into a flat list of `{tok, rel}` pairs.
 --- `tok` is the trimmed token string; `rel` is the byte offset within `body`.
@@ -606,13 +562,22 @@ function M.tokenize_body(body)
 		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 = M.read_parens   (body, scan); scan = a -- '('
-			elseif c == 123           then local _, a = M.read_braces   (body, scan); scan = a -- '{'
-			elseif c == 91            then local _, a = M.read_brackets (body, scan); scan = a -- '['
-			elseif c == 34 or c == 39 then scan       = M.skip_str_or_cmt(body, scan) + 1     -- '"' or '\''
+			-- Terminator bytes (delimit a token at the top level): ',' = 0x2C,
+			-- '\n' = 0x0A, ';' = 0x3B. These also appear as separators between
+			-- argument lists inside the parens/braces/brackets, so we stop the
+			-- scan when we hit any of them.
+			if     c == BYTE_COMMA   then break end
+			if     c == BYTE_NEWLINE then break end
+			if     c == BYTE_SEMI    then break end
+			-- Group opener bytes (consume the balanced group via the matching reader):
+			-- '(' = 0x28, '{' = 0x7B, '[' = 0x5B.
+			if     c == BYTE_OPEN_PAREN then local _, a = M.read_parens   (body, scan); scan = a
+			elseif c == BYTE_OPEN_BRACE then local _, a = M.read_braces   (body, scan); scan = a
+			elseif c == BYTE_OPEN_BRACK then local _, a = M.read_brackets (body, scan); scan = a
+			-- String-literal byte ('"' = 0x22 or '\'' = 0x27): skip past the
+			-- quoted region in one shot.
+			elseif c == BYTE_DQUOTE or c == BYTE_SQUOTE then
+				scan = M.skip_str_or_cmt(body, scan) + 1
 			else
 				scan = scan + 1
 			end
@@ -633,12 +598,15 @@ end
 --- Tokenize the body into a flat list of trimmed string tokens (preserves comments).
 --- Uses `split_top_level_commas` (which appends trailing comments to the previous token)
 --- so the components pass can emit `/* Words: ... */` comments in the .macs.h output.
+--- Memoized on body string (R7 lift; mirror of M.tokenize_body's memoization).
 --- @param body string
 --- @return string[]
 function M.tokenize_body_simple(body)
+	if _tokenize_body_simple_cache[body] ~= nil then return _tokenize_body_simple_cache[body] end
 	local tokens = M.split_top_level_commas(body)
 	local out = {}
 	for i = 1, #tokens do out[i] = M.trim(tokens[i]) end
+	_tokenize_body_simple_cache[body] = out
 	return out
 end
 
@@ -655,7 +623,9 @@ function M.build_body_line_index(body)
 		if pos > 1 then
 			index[pos] = newline_count + 1
 		end
-		if body:byte(pos) == 10 then
+		-- Newline byte = 0x0A (BYTE_NEWLINE). Counts line boundaries so the
+		-- index maps each source-byte offset → its 1-based line number.
+		if body:byte(pos) == BYTE_NEWLINE then
 			newline_count = newline_count + 1
 		end
 	end
@@ -683,11 +653,11 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 function M.load_word_counts(metadata_path)
-	local counts      = {}
-	local content     = M.read_file(metadata_path)
-	local len         = #content
-	local pos         = 1
-	local prefix      = "WORD_COUNT("
+	local counts  = {}
+	local content = M.read_file(metadata_path)
+	local len     = #content
+	local pos     = 1
+	local prefix  = "WORD_COUNT("
 	while pos <= len do
 		local nl       = M.find_byte(content, BYTE_NEWLINE, pos)
 		local line_end = nl or (len + 1)
@@ -707,8 +677,6 @@ function M.load_word_counts(metadata_path)
 	return counts
 end
 
-
--- ════════════════════════════════════════════════════════════════════════════
 -- ══════════════════════════════════════════════════
 -- Section 6: LineIndex (perf fix — replaces the per-call rescan line_of)
 -- ══════════════════════════════════════════════════
@@ -747,10 +715,9 @@ M.WAVE_CONTEXT_REGS = {
 
 -- The annotation DSL has been reduced to a single annotation macro:
 --   atom_info(atom_bind(Binds_X), atom_reads(...), atom_writes(...))
--- All phase / region / cadence / async / resource / group tokens have
--- been dropped. They may be reintroduced later as optional sub-calls
--- of atom_info; for now, the parser only recognizes atom_info + its
--- three sub-calls (atom_bind, atom_reads, atom_writes).
+-- All phase / region / cadence / async / resource / group tokens have been dropped.
+-- They may be reintroduced later as optional sub-calls of atom_info; 
+-- for now, the parser only recognizes atom_info + its three sub-calls (atom_bind, atom_reads, atom_writes).
 M.TAPE_ATOM_MACROS = {
 	["atom_info"] = { kind = "info", binds = false },
 }
@@ -1026,7 +993,7 @@ M.INSTRUCTION_LATENCY = {
 	["atom_writes"]         = 0,
 }
 
--- Default cycle cost for unknown macros. 
+-- 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

scripts/duffle_paths.lua

@@ -30,47 +30,25 @@ local CACHE_KEY = "__duffle_repo_root__"
 --- Replaces the prior `io.popen("git rev-parse --show-toplevel")` approach, which cost ~100-180ms per
 --- LuaJIT process on Windows due to git's CLI startup. The path-derive approach costs <1ms.
 ---
---- If this script's path can't be parsed (shouldn't happen — dofile/debug.getinfo always populates source),
---- fall back to a defensive walk: starting from this script's directory, walk UP until we find a parent that
---- contains a `scripts/` directory. The first match is the repo root.
+--- If `debug.getinfo` can't parse this script's path (shouldn't happen — dofile always populates source),
+--- return nil and let `M.setup()` fail loud.
 --- @return string|nil
 local function find_repo_root()
 	if package.loaded[CACHE_KEY] then return package.loaded[CACHE_KEY] end
 
 	local source = debug.getinfo(1, "S").source
 	-- Strip the leading `@` (Lua's dofile marker) and the trailing `/duffle_paths.lua` filename.
-	-- What remains is the directory containing this script, i.e. `<repo>/scripts/` (with trailing slash or not).
+	-- What remains is the directory containing this script, i.e. `<repo>/scripts/`.
 	local scripts_dir = source and source:match("^@?(.*)[/\\]duffle_paths%.lua$")
-	if scripts_dir then
-		-- The repo root is the parent of `scripts/`. Strip the trailing `scripts/` (with or without trailing slash).
-		local root = scripts_dir:gsub("scripts[\\/]?$", "")
-		root = root:gsub("\\", "/")
-		if root == "" then root = "./" end
-		if not root:match("/$") then root = root .. "/" end
-		package.loaded[CACHE_KEY] = root
-		return root
-	end
+	if not scripts_dir then return nil end
 
-	-- Defensive fallback: walk UP from this script's directory until we find a parent that contains `scripts/`.
-	-- In practice this branch never fires — debug.getinfo always returns a source for dofile()'d chunks.
-	local lfs = pcall(require, "lfs") and require("lfs") or nil
-	if lfs then
-		local dir = source and source:match("^@?(.*[/\\])") or "./"
-		dir = dir:gsub("\\", "/")
-		while dir and dir ~= "" do
-			local candidate_scripts = dir .. "scripts"
-			if lfs.attributes(candidate_scripts, "mode") == "directory" then
-				dir = dir:gsub("/$", "")
-				package.loaded[CACHE_KEY] = dir .. "/"
-				return dir .. "/"
-			end
-			local parent = dir:match("^(.*)/[^/]+/$")
-			if not parent then break end
-			dir = parent .. "/"
-		end
-	end
-
-	return nil
+	-- The repo root is the parent of `scripts/`. Strip the trailing `scripts/` (with or without trailing slash).
+	local root = scripts_dir:gsub("scripts[\\/]?$", "")
+	root = root:gsub("\\", "/")
+	if root == "" then root = "./" end
+	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

scripts/elf_dwarf.lua

@@ -0,0 +1,514 @@
+--- elf_dwarf.lua — ELF32 + DWARF + atoms source-map utilities for the F'' track.
+---
+--- All ELF32 + DWARF-specific code lives here.
+---
+--- **What this module contains:**
+---   - **Format-constant tables** (the byte-offset / opcode / size encyclopedias for ELF32, DWARF4 aranges, DWARF5 rnglists, DWARF line-program, MIPS).
+---     Every constant carries a spec:` comment naming the spec section that defines it (convention established by F'').
+---   - **I/O helpers**: little-endian byte read/write, ELF32 section walker, nm symbol reader, source-map parser, native directory glob.
+---
+--- **Conventions:** tabs (1/level), EmmyLua annotations, no regex,
+--- Lua 5.3 compatible.
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- Native dependencies
+-- ════════════════════════════════════════════════════════════════════════════
+
+-- lfs is wired into package.cpath by `duffle_paths.lua` (vendored under
+-- `toolchain/lfs/lfs.dll`). Required here for native directory ops
+-- (replaces the ~56ms `dir /b` subprocess with ~2ms native).
+local lfs = require("lfs")
+
+local M = {}
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- Format-constant tables
+-- ════════════════════════════════════════════════════════════════════════════
+
+-- ----------------------------------------------------------------------------
+-- MIPS sizes
+-- ----------------------------------------------------------------------------
+
+--- spec: MIPS o32 ABI §"Register Usage" — 32-bit general-purpose registers
+M.MIPS_BYTES_PER_WORD = 0x04
+
+-- ----------------------------------------------------------------------------
+-- ELF32 (System V ABI gABI v1.2)
+-- ----------------------------------------------------------------------------
+--
+-- All offsets are 1-INDEXED (matching Lua string.sub convention), 
+-- expressed in hex so they map directly to the wire-format byte positions in the binary file. 
+-- To compute the 0-indexed file offset, subtract 1.
+--
+-- Example: e_shoff_offset = 0x21 means the 4-byte e_shoff field 
+-- starts at string.sub byte 0x21 (= 33 in 1-indexed), i.e. file offset 0x20 (= 32).
+
+--- spec: System V ABI gABI v1.2 §"ELF Header" (Table 1) + §"Section Header Table"
+M.ELF32 = {
+	magic_offset          = 0x01,         -- 4-byte magic "\127ELF" at file offset 0x00
+	magic                 = "\127ELF",
+	class_offset          = 0x05,         -- 1-byte; 1 = ELF32, 2 = ELF64
+	class_elf32           = 1,
+	endian_offset         = 0x06,         -- 1-byte; 1 = little-endian, 2 = big-endian
+	endian_little         = 1,
+	header_bytes          = 0x34,         -- spec: gABI v1.2 §"ELF Header" — ELF32 header is 52 bytes total
+	e_shoff_offset        = 0x21,         -- 4-byte LE; section-header table file offset
+	e_shentsize_offset    = 0x2F,         -- 2-byte LE; section-header entry size in bytes
+	e_shnum_offset        = 0x31,         -- 2-byte LE; number of section headers
+	e_shstrndx_offset     = 0x33,         -- 2-byte LE; index of section-name string table
+	sh_size_bytes         = 0x28,         -- spec: gABI v1.2 §"Section Header Table" — each entry is 40 bytes
+	sh_name_offset        = 0x01,         -- 4-byte LE; offset into .shstrtab
+	sh_type_offset        = 0x05,         -- 4-byte LE; section type (SHT_*)
+	sh_offset_offset      = 0x11,         -- 4-byte LE; section's file offset
+	sh_size_offset        = 0x15,         -- 4-byte LE; section's size in bytes
+	dw_dwarf32_terminator = 0xFFFFFFFF,   -- spec: DWARF4 spec §7.4 — 32-bit DWARF initial-length terminator
+}
+
+-- ----------------------------------------------------------------------------
+-- DWARF4 .debug_aranges (per DWARF5 spec §7.4 — Address Range Table)
+-- ----------------------------------------------------------------------------
+--
+-- All offsets are 1-INDEXED (matching Lua string.sub convention), in hex.
+
+--- spec: DWARF5 spec §7.4 (Address Range Table) — 32-bit DWARF form
+M.DWARF4_ARANGES = {
+	unit_length_offset = 0x01,    -- 4-byte LE; length of unit body (excludes these 4 bytes)
+	version_offset     = 0x05,    -- 2-byte LE; expected = 2
+	cu_offset_offset   = 0x07,    -- 4-byte LE; CU DIE offset in .debug_info
+	addr_size_offset   = 0x0B,    -- 1-byte;  expected = 4 (32-bit MIPS)
+	seg_size_offset    = 0x0C,    -- 1-byte;  expected = 0
+	entry_size         = 0x08,    -- 4-byte addr + 4-byte length (per §7.4)
+	terminator_size    = 0x08,    -- 8 zero bytes (per §7.4 end-of-list marker)
+	version_expected   = 2,
+	addr_size_expected = 4,
+	seg_size_expected  = 0,
+}
+
+-- ----------------------------------------------------------------------------
+-- DWARF5 .debug_rnglists (per DWARF5 spec §2.17 + §7.21)
+-- ----------------------------------------------------------------------------
+--
+-- All offsets are 1-INDEXED (matching Lua string.sub convention), in hex.
+
+--- spec: DWARF5 spec §2.17 + §7.21 (Range List Table) — 32-bit DWARF form
+M.DWARF5_RNGLISTS = {
+	unit_length_offset    = 0x01,    -- 4-byte LE
+	version_offset        = 0x05,    -- 2-byte LE; expected = 5
+	addr_size_offset      = 0x07,    -- 1-byte;  expected = 4
+	seg_size_offset       = 0x08,    -- 1-byte;  expected = 0
+	offset_count_offset   = 0x09,    -- 4-byte LE; expected = 0
+	first_entry_offset    = 0x0D,
+	end_of_list           = 0x00,    -- spec: DWARF5 §7.7 — DW_RLE_end_of_list byte value
+	start_length          = 0x07,    -- spec: DWARF5 §7.7 — DW_RLE_start_length byte value
+	version_expected      = 5,
+	addr_size_expected    = 4,
+	seg_size_expected     = 0,
+	offset_count_expected = 0,
+}
+
+-- ----------------------------------------------------------------------------
+-- DWARF line-program opcodes (per DWARF5 spec §6.2.5)
+-- ----------------------------------------------------------------------------
+--
+-- Opcode VALUES stay in decimal — they're identifiers (DW_LNS_copy = 1), not binary positions.
+-- Compare to the *_offset fields above which are hex.
+
+--- spec: DWARF5 spec §6.2.5 (Line Number Program Opcodes)
+M.DWARF_LINE_OPS = {
+	-- Standard opcodes (§6.2.5.2)
+	DW_LNS_extended     = 0,    -- spec: §6.2.5.2 — extended opcode marker byte
+	DW_LNS_copy         = 1,
+	DW_LNS_advance_pc   = 2,
+	DW_LNS_advance_line = 3,
+	DW_LNS_set_file     = 4,
+	-- Extended sub-opcodes (§6.2.5.3)
+	DW_LNE_end_sequence = 1,    -- spec: §6.2.5.3
+	DW_LNE_set_address  = 2,    -- spec: §6.2.5.3
+	-- Standard opcode header (§6.2.5.1)
+	-- opcode_base + line_range are 1-byte header fields; hex so they map
+	-- directly to their position in the line-program header byte sequence.
+	-- line_base stays signed decimal (=-5) since 0xFB obscures the spec semantics.
+	opcode_base              = 0x0D,
+	line_base                = -5,
+	line_range               = 0x0E,
+	-- Extended opcode payload sizes (include the sub-opcode byte; §6.2.5.3)
+	-- Hex so they match the byte positions in the line-program wire format.
+	end_sequence_payload_size = 0x01,   -- size = sub_opcode only
+	set_address_payload_size  = 0x05,   -- size = sub_opcode(1) + addr(4)
+}
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- I/O helpers: little-endian byte read/write
+-- ════════════════════════════════════════════════════════════════════════════
+
+--- Read a 4-byte little-endian unsigned integer from `buf` at 1-indexed offset `off`.
+--- Equivalent to `string.unpack("<I4", buf, off)` but avoids the table-return shape + works under LuaJIT 2.1
+--- (which has partial `string.unpack` coverage).
+---
+--- **Convention:** offsets are 1-indexed (matching Lua `string.sub`).
+---
+--- **Byte weights** are written as `0x100`, `0x10000`, `0x1000000` (i.e.
+--- 2^8, 2^16, 2^24) so the LE byte positions are visually explicit:
+--- byte 0 contributes its value directly; byte 1 is shifted left by 8
+--- (= 0x100); byte 2 by 16 (= 0x10000); byte 3 by 24 (= 0x1000000).
+---
+--- @param buf string
+--- @param off integer  -- 1-indexed
+--- @return integer
+function M.read_u32_le(buf, off)
+	return buf:byte(off)
+		+ buf:byte(off + 0x01) * 0x00000100
+		+ buf:byte(off + 0x02) * 0x00010000
+		+ buf:byte(off + 0x03) * 0x01000000
+end
+
+--- Read a 2-byte little-endian unsigned integer from `buf` at 1-indexed offset `off`.
+--- (1-indexed convention; matches `M.read_u32_le`.)
+--- @param buf string
+--- @param off integer  -- 1-indexed
+--- @return integer
+function M.read_u16_le(buf, off)
+	return buf:byte(off) + buf:byte(off + 0x01) * 0x00000100
+end
+
+--- Return a 4-byte little-endian byte string for `value`.
+--- Caller concatenates with `..` if composing multi-word blobs.
+---
+--- **Byte weights** written as `0x100` etc. (see `M.read_u32_le` for rationale).
+--- @param value integer  -- 0 ≤ value ≤ 0xFFFFFFFF
+--- @return string
+function M.write_u32_le(value)
+	return string.char(
+		value                          % 0x00000100,
+		math.floor(value / 0x00000100) % 0x00000100,
+		math.floor(value / 0x00010000) % 0x00000100,
+		math.floor(value / 0x01000000) % 0x00000100)
+end
+
+--- Return a 2-byte little-endian byte string for `value`.
+--- @param value integer  -- 0 ≤ value ≤ 0xFFFF
+--- @return string
+function M.write_u16_le(value)
+	return string.char(value % 0x00000100, math.floor(value / 0x00000100) % 0x00000100)
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- I/O helpers: ELF32 / DWARF / symbols
+-- ════════════════════════════════════════════════════════════════════════════
+
+--- Read the named sections from a post-link ELF32 by walking the ELF32 section-header table directly
+--- (no subprocess; lfs only for the existence check). Returns `{[name] = bytes_or_empty_string, ...}`.
+---
+--- **Convention:** offsets from `M.ELF32` (1-indexed for string.sub).
+--- Every requested name has an entry in the returned dict; missing sections have an empty string (NOT nil)
+--- so callers can do `sections[".debug_x"] or ""` for the missing case.
+---
+--- **Cost:** one file open + one `f:seek` + one `f:read` per section header 
+--- (we walk all `e_shnum` headers regardless of how many names are requested, to find the .shstrtab first).
+--- For frequent callers, pass the union of all needed sections in one call.
+--  can add `.debug_info` + `.debug_loc` + `.debug_str_offsets` to the list without writing a 2nd ELF walker.
+--- @param elf_path Path
+--- @param section_names string[]  -- list of section names to read
+--- @return table<string, string>
+function M.read_elf_sections(elf_path, section_names)
+	-- Initialize result with all requested names set to "" so callers can do `sections[X] 
+	-- or ""` for missing sections without nil-checks.
+	local result = {}
+	for _, name in ipairs(section_names) do result[name] = "" end
+
+	-- O(1) lookup set.
+	local wanted = {}
+	for _, name in ipairs(section_names) do wanted[name] = true end
+
+	-- Existence check (lfs.attributes avoids an io.open-vs-fail race).
+	if lfs.attributes(elf_path, "mode") ~= "file" then
+		io.stderr:write(string.format("[elf_dwarf.read_elf_sections] ELF not found: %s\n", elf_path))
+		return result
+	end
+
+	local f = io.open(elf_path, "rb")
+	if not f then
+		io.stderr:write(string.format("[elf_dwarf.read_elf_sections] io.open failed: %s\n", elf_path))
+		return result
+	end
+
+	-- Read the ELF32 header.
+	local header = f:read(M.ELF32.header_bytes)
+	if not header or #header < M.ELF32.header_bytes then
+		io.stderr:write("[elf_dwarf.read_elf_sections] ELF too small for ELF32 header\n")
+		f:close()
+		return result
+	end
+
+	-- Sanity-check magic + class + endianness.
+	if header:sub(M.ELF32.magic_offset, M.ELF32.magic_offset + 0x03) ~= M.ELF32.magic then
+		io.stderr:write("[elf_dwarf.read_elf_sections] not an ELF file\n")
+		f:close()
+		return result
+	end
+	if header:byte(M.ELF32.class_offset) ~= M.ELF32.class_elf32 then
+		io.stderr:write(string.format("[elf_dwarf.read_elf_sections] not ELF32 (class=%d)\n", header:byte(M.ELF32.class_offset)))
+		f:close()
+		return result
+	end
+	if header:byte(M.ELF32.endian_offset) ~= M.ELF32.endian_little then
+		io.stderr:write("[elf_dwarf.read_elf_sections] not little-endian; unsupported\n")
+		f:close()
+		return result
+	end
+
+	-- Parse section-header table location + dimensions from the header.
+	local e_shoff     = M.read_u32_le(header, M.ELF32.e_shoff_offset)
+	local e_shentsize = M.read_u16_le(header, M.ELF32.e_shentsize_offset)
+	local e_shnum     = M.read_u16_le(header, M.ELF32.e_shnum_offset)
+	local e_shstrndx  = M.read_u16_le(header, M.ELF32.e_shstrndx_offset)
+
+	-- Read the section-header string table (.shstrtab) so we can resolve section names from their `sh_name` offsets.
+	f:seek("set", e_shoff + e_shstrndx * e_shentsize)
+	local strtab_hdr = f:read(e_shentsize)
+	if not strtab_hdr or #strtab_hdr < e_shentsize then
+		io.stderr:write("[elf_dwarf.read_elf_sections] could not read .shstrtab header\n")
+		f:close()
+		return result
+	end
+	local strtab_offset = M.read_u32_le(strtab_hdr, M.ELF32.sh_offset_offset)
+	local strtab_size   = M.read_u32_le(strtab_hdr, M.ELF32.sh_size_offset)
+	f:seek("set", strtab_offset)
+	local strtab = f:read(strtab_size) or ""
+
+	-- Walk all section headers; collect (offset, size) for the wanted names.
+	local function read_section_bytes(sh_offset, sh_size)
+		f:seek("set", sh_offset)
+		return f:read(sh_size) or ""
+	end
+
+	for sh_idx = 0, e_shnum - 1 do
+		f:seek("set", e_shoff + sh_idx * e_shentsize)
+		local sh = f:read(e_shentsize)
+		if not sh or #sh < e_shentsize then break end
+		local sh_name   = M.read_u32_le(sh, M.ELF32.sh_name_offset)
+		local sh_offset = M.read_u32_le(sh, M.ELF32.sh_offset_offset)
+		local sh_size   = M.read_u32_le(sh, M.ELF32.sh_size_offset)
+
+		-- Extract the name (null-terminated C string in strtab).
+		local name_end = strtab:find("\0", sh_name + 1, true) or (sh_name + 1)
+		local name     = strtab:sub(sh_name + 1, name_end - 1)
+		if wanted[name] then
+			result[name] = read_section_bytes(sh_offset, sh_size)
+		end
+	end
+
+	f:close()
+	return result
+end
+
+--- Read ELF symbol addresses by walking the `.symtab` + `.strtab` sections directly (no `nm` subprocess). 
+--- Returns a map `{name -> {addr, size_bytes}}` for every `code_<name>` symbol.
+---
+--- **Why direct parsing instead of `mipsel-none-elf-nm -S`?**
+--- The `nm` subprocess costs ~50ms per spawn on Windows (cmd.exe + mipsel-none-elf-nm.exe). Parsing `.symtab` ourselves is ~0ms.
+--- Same return shape, same `code_` prefix filter.
+---
+--- **Conventions:**
+--- - ELF32 symtab entry = 16 bytes (`st_name:4 + st_value:4 + st_size:4 + st_info:1 + st_other:1 + st_shndx:2`). 1-indexed for Lua string.sub.
+--- - We filter on STB_GLOBAL (high nibble of st_info = 1) to match `nm`'s default (external symbols only). STB_WEAK excluded.
+--- - We strip the `code_` prefix to match the previous `read_nm` output. 
+--- - `st_size > 0` filter excludes undefined/imported symbols.
+---
+--- @param elf_path Path
+--- @return table<string, {integer, integer}>
+function M.read_nm(elf_path)
+	local addrs = {}
+
+	-- Read .symtab + .strtab via the existing ELF walker (no subprocess).
+	local sections = M.read_elf_sections(elf_path, {".symtab", ".strtab"})
+	local symtab   = sections[".symtab"]
+	local strtab   = sections[".strtab"]
+	if not symtab or not strtab or #symtab == 0 or #strtab == 0 then
+		-- No symbol table (e.g. stripped ELF). Return empty.
+		return addrs
+	end
+
+	-- Iterate the 16-byte ELF32 symtab entries.
+	-- Each entry (1-indexed): st_name at 1, st_value at 5, st_size at 9,
+	-- st_info at 13, st_other at 14, st_shndx at 15.
+	local SYM_ENTRY_BYTES = 0x10
+	local SYM_ST_NAME     = 0x01
+	local SYM_ST_VALUE    = 0x05
+	local SYM_ST_SIZE     = 0x09
+	local SYM_ST_INFO     = 0x0D
+	local n_syms = #symtab / SYM_ENTRY_BYTES
+	for i = 0, n_syms - 1 do
+		local entry_off  = i * SYM_ENTRY_BYTES + 1     -- 1-indexed
+		local st_info    = symtab:byte(entry_off + SYM_ST_INFO - 1)
+		-- High nibble = binding (STB_LOCAL=0, STB_GLOBAL=1, STB_WEAK=2).
+		-- Use math.floor(/16) instead of bit.rshift for LuaJIT 2.1 compat
+		-- (LuaJIT's `>>` is 5.3+, but math.floor(x/16) works on all versions).
+		local binding    = math.floor(st_info / 16)
+		if binding == 0 or binding == 1 then            -- STB_LOCAL or STB_GLOBAL
+			local st_size   = M.read_u32_le(symtab, entry_off + SYM_ST_SIZE  - 1)
+			if st_size > 0 then
+				local st_name_off = M.read_u32_le(symtab, entry_off + SYM_ST_NAME  - 1)
+				-- Extract the name from .strtab (null-terminated C string).
+				local name_end = strtab:find("\0", st_name_off + 1, true) or (st_name_off + 1)
+				local name     = strtab:sub(st_name_off + 1, name_end - 1)
+				-- Filter: keep all symbol-table symbols (atoms emit their name as the bare `<name>` since the `code_` prefix was removed from the MipsAtom_ macro).
+				-- The atoms_source_map pass already filters out non-atom symbols via the source-map.txt cross-ref.
+				if name and #name > 0 then
+					local st_value = M.read_u32_le(symtab, entry_off + SYM_ST_VALUE - 1)
+					addrs[name] = { st_value, st_size }
+				end
+			end
+		end
+	end
+
+	return addrs
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- LEB128 encoders (Unsigned + Signed Little-Endian Base 128)
+-- ════════════════════════════════════════════════════════════════════════════
+--
+-- DWARF uses LEB128 to encode variable-length integers in its wire format (line-program opcodes, DW_AT values, etc.).
+-- Both encoders pack 7 bits of data per byte + 1 bit of "more bytes follow" signaling.
+--
+-- Per-byte layout:
+--
+--     bit:   7 6 5 4 3 2 1 0
+--           │ └───── 7-bit data ─────┘
+--           └─ continuation flag (LEB_CONT_BIT = 0x80)
+--
+-- For SLEB128 (signed), bit 6 of the 7-bit data is the sign bit that the
+-- decoder uses for sign extension:
+--     bit 6 = 0 → value is positive (or zero); zero-extend on decode
+--     bit 6 = 1 → value is negative;            one-extend on decode
+--
+-- The signed encoder must emit the MINIMUM number of bytes whose final 7-bit payload already has the correct sign bit set 
+-- (otherwise the decoder would round-trip to a different value).
+--
+-- Spec: DWARF5 §7.6 "Variable-Length Data" / Appendix C.
+
+-- Top bit of each LEB128 byte. Set if more bytes follow in the encoding.
+local LEB_CONT_BIT = 0x80
+
+-- Low 7 bits of each LEB128 byte. The actual data payload.
+local LEB_DATA_MASK = 0x7F
+
+-- Bit 6 of the 7-bit data (i.e. 0x40). For SLEB128: the sign-bit position used by the decoder for sign extension.
+-- Encoders MUST stop when the next byte would be redundant AND the sign bit in the last byte matches the value's sign.
+local SLEB_SIGN_BIT = 0x40
+
+--- ULEB128 (Unsigned Little-Endian Base 128) encoder. Returns the byte string for the non-negative integer `n`.
+---
+--- Algorithm:
+---   - Extract the low 7 bits of `n` (LEB_DATA_MASK = 0x7F).
+---   - Shift `n` right by 7 bits.
+---   - If more bytes remain, OR in the continuation flag (LEB_CONT_BIT).
+---   - Repeat until `n` is fully consumed.
+---
+--- @param n integer  -- non-negative
+--- @return string
+function M.uleb128(n)
+	assert(n >= 0, "uleb128 requires non-negative input")
+	local bytes = {}
+	repeat
+		local b = n % (LEB_DATA_MASK + 1)      -- extract low 7 bits
+		n = (n - b) / (LEB_DATA_MASK + 1)      -- shift right by 7 bits
+		if n > 0 then b = b + LEB_CONT_BIT end -- set continuation bit if more bytes follow
+		bytes[#bytes + 1] = string.char(b)
+	until n == 0
+	return table.concat(bytes)
+end
+
+--- SLEB128 (Signed Little-Endian Base 128) encoder. Returns the byte
+--- string for the integer `n` (may be negative).
+---
+--- Algorithm differs from ULEB128 by the termination condition: stop when
+--- the remaining bits can be inferred from the sign bit in the last byte's
+--- 7-bit data payload.
+---   - If `n == 0`  (no more value bits)   AND bit 6 of the data = 0 → positive terminator (sign bit says "zero-extend").
+---   - If `n == -1` (sign-extended all-1s) AND bit 6 of the data = 1 → negative terminator (sign bit says "one-extend").
+---
+--- Without these checks, the decoder would round-trip to a different value
+--- (e.g. encoding `0` as `0x80 0x00` decodes to `0` correctly but is 2 bytes long; the termination check picks the 1-byte `0x00` form).
+---
+--- @param n integer  -- any integer (negative allowed)
+--- @return string
+function M.sleb128(n)
+	local bytes = {}
+	local more = true
+	while more do
+		local b = n % (LEB_DATA_MASK + 1)               -- extract low 7 bits
+		n = (n - b) / (LEB_DATA_MASK + 1)               -- arithmetic shift right by 7
+		-- Termination: remaining value bits fit in the sign bit of the last byte.
+		if     n == 0  and b <  SLEB_SIGN_BIT then more = false end  -- positive terminator
+		if     n == -1 and b >= SLEB_SIGN_BIT then more = false end  -- negative terminator
+		if more then b = b + LEB_CONT_BIT end
+		bytes[#bytes + 1] = string.char(b)
+	end
+	return table.concat(bytes)
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- I/O helpers: atoms source-map + native directory glob
+-- ════════════════════════════════════════════════════════════════════════════
+
+--- Parse a FORMAT_VERSION <expected_version> `*.atoms.sourcemap.txt` file.
+--- Returns `{name -> {total = N, words = {{pos, line}, ...}}}`.
+--- Returns `{}` on format-version mismatch (and logs to stderr).
+---
+--- **Wire format** (emitted by `passes/atoms_source_map.lua`):
+--- ```
+--- # FORMAT_VERSION <n>
+--- ATOM <name> "<abs-source-path>" <total>
+--- WORD <n> LINE <line> TEXT <text...>
+--- ...
+--- ENDATOM
+--- ```
+---
+--- **Conventions:** the in-memory shape uses `{pos, line, text}`
+--- (`atoms_source_map.lua:142`); the `.txt` file uses `WORD <n>` so the parser maps `n` → `pos` field name.
+--- @param sm_path Path
+--- @param expected_version integer  -- expected FORMAT_VERSION line
+--- @return table<string, table>
+function M.parse_source_map_file(sm_path, expected_version)
+	local out = {}
+	local cur_name, cur_words = nil, {}
+	for raw in io.lines(sm_path) do
+		local line = raw
+		if line:match("^#") then
+			local ver = line:match("^# FORMAT_VERSION%s+(%d+)")
+			if ver and tonumber(ver) ~= expected_version then
+				io.stderr:write(string.format(
+					"[elf_dwarf.parse_source_map_file] source-map version mismatch (got %s, expected %d) in %s\n",
+					ver, expected_version, sm_path))
+				return {}
+			end
+			-- skip other comments
+		elseif line:sub(1, 4) == "ATOM" then
+			-- ATOM <name> "<abs-source-path>" <total>
+			local _, _, name = line:find("ATOM%s+(%S+)%s+\"[^\"]*\"%s+(%d+)")
+			if name then
+				cur_name  = name
+				cur_words = {}
+				out[name] = { total = 0, words = cur_words }
+			end
+		elseif line == "ENDATOM" then
+			-- Update the recorded total from the entries count
+			-- (matches the `lines[1] = lines[1]:gsub(" 0$", " " .. total)` patch in atoms_source_map.lua:170).
+			if cur_name and out[cur_name] then
+				out[cur_name].total = #cur_words
+			end
+			cur_name, cur_words = nil, {}
+		elseif line:sub(1, 4) == "WORD" and cur_name then
+			-- WORD <n>  LINE <line>  TEXT <text...>
+			local _, n, _, src_line = line:find("WORD%s+(%d+)%s+LINE%s+(%d+)")
+			if n and src_line then
+				cur_words[#cur_words + 1] = { pos = tonumber(n), line = tonumber(src_line) }
+			end
+		end
+	end
+	return out
+end
+
+return M

scripts/gdb/gdb_tape_atoms.gdb

@@ -0,0 +1,119 @@
+# scripts/gdb/gdb_tape_atoms.gdb
+#
+# Wrapper for the tape-atom step-debug helpers. The 9 user commands are defined
+# here as STUBS (degraded-state messages). The real implementations + the
+# per-atom data tables are emitted by `passes/atoms_source_map.lua` (post-link
+# invocation: `ps1_meta.lua --atoms-source-map --gdb-runtime --elf <elf>`) into
+# `build/gen/gdb_tape_atoms_runtime.gdb`. Sourcing that file RE-DEFINES the
+# commands with real implementations.
+#
+# If `build/gen/gdb_tape_atoms_runtime.gdb` is missing or stale, the stubs
+# remain (E1: no source map). The user just needs to re-run `build_psyq.ps1`
+# to regenerate. No exceptions; no crashes.
+#
+# Why a wrapper + separate runtime file?
+# - The runtime file is auto-generated per-build; not in git.
+# - The wrapper is checked into git; always works.
+# - This split keeps the script trivial and the data plumbing out of git.
+#
+# Compatible with every gdb build (no Python, no Tcl, no Guile required) —
+# pure gdb command scripting + `set $var = val` + `define ... end`.
+#
+# Generated by track gdb_tape_atom_debugging_20260711 — see
+# C:\projects\Pikuma\ps1-ai\docs\gdb_tape_atom_debugging.md for the manual.
+
+# ── Stub commands (defined here so they're always present, even if the
+#    runtime file is missing). The runtime file overrides these if sourced. ──
+
+define tape_atoms
+  echo "[gdb_tape_atoms] STUB: runtime file build/gen/gdb_tape_atoms_runtime.gdb not found."
+  echo "[gdb_tape_atoms] STUB: run .\\build_psyq.ps1 to regenerate, then re-source this file."
+end
+document tape_atoms
+  List every tape atom symbol in the loaded ELF (code_<name>) with its .rodata address and word count.
+  STUB state: runtime file not sourced. Run build_psyq.ps1 to regenerate.
+end
+
+define break_atom
+  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+end
+document break_atom
+  Set a breakpoint at the start of tape atom <name>. STUB state.
+end
+
+define step_atom
+  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+end
+document step_atom
+  Resume execution until the next atom boundary. STUB state.
+end
+
+define next_atom
+  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+end
+document next_atom
+  Alias for step_atom. STUB state.
+end
+
+define where_in_atom
+  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+end
+document where_in_atom
+  Report current atom name, .rodata addr, word offset, and source line (if known). STUB state.
+end
+
+define stepi_inside_atom
+  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+end
+document stepi_inside_atom
+  One MIPS-instruction step, then where_in_atom. STUB state.
+end
+
+define show_c2
+  printf "C2[ 0]   0x%08x\n", $c2_data[0]
+  printf "C2[ 7]   0x%08x  [otz]\n", $c2_data[7]
+  printf "C2[12]   0x%08x  [sxy0]\n", $c2_data[12]
+  printf "C2[13]   0x%08x  [sxy1]\n", $c2_data[13]
+  printf "C2[14]   0x%08x  [sxy2]\n", $c2_data[14]
+  printf "C2[24]   0x%08x  [mac0]\n", $c2_data[24]
+  printf "...\n"
+  echo "(STUB state: only 7 representative regs shown. Run build_psyq.ps1 for full dump.)"
+end
+document show_c2
+  Pretty-print all 32 C2 data registers as hex + named alias. STUB state (7 reg subset).
+end
+
+define show_c2ctl
+  printf "C2CTL[ 0]  0x%08x\n", $c2_control[0]
+  printf "...\n"
+  echo "(STUB state: only 1 reg shown. Run build_psyq.ps1 for full dump.)"
+end
+document show_c2ctl
+  Pretty-print all 32 C2 control registers. STUB state (1 reg subset).
+end
+
+define wave_ctx
+  printf "$t4 = R_FaceCursor     0x%08x\n", $t4
+  printf "$t5 = R_VertBase       0x%08x\n", $t5
+  printf "$t6 = R_OtBase         0x%08x\n", $t6
+  printf "$t7 = R_PrimCursor     0x%08x\n", $t7
+end
+document wave_ctx
+  Pretty-print the 4 wave-context GPRs ($t4..$t7). (wave_ctx works in stub state too.)
+end
+
+
+# ── Source the runtime file (re-defines commands with real impls + data). ──
+
+# Try to source from project-root-relative path first (the typical case).
+# If the user is in a different CWD, the source will fail and stubs remain.
+# The runtime file path is computed relative to the ELF's source map convention
+# (build/gen/gdb_tape_atoms_runtime.gdb).
+echo [gdb_tape_atoms] Wrapper loaded. Sourcing runtime file...
+# Suppress the "Redefine command" prompts that would otherwise appear when the
+# runtime file overrides the 9 stub commands defined above. The runtime's
+# `define` blocks are intended to overwrite — there's no ambiguity to confirm.
+set confirm off
+source build/gen/gdb_tape_atoms_runtime.gdb
+set confirm on
+echo [gdb_tape_atoms] Runtime sourced successfully (9 commands now have real implementations).

scripts/launch_pcsx_debug.ps1

@@ -0,0 +1,94 @@
+# scripts/launch_pcsx_debug.ps1
+#
+# One-shot launcher for debug sessions: starts pcsx-redux with the .ps-exe
+# loaded, the gdb stub enabled, AND the pcsx_debug_helper Lua plugin loaded
+# so external CLI tools (gdb's `shell` command, etc.)
+# can read GTE state via http://localhost:8080/api/v1/lua/gte
+# (the gdb stub doesn't expose COP2 at all).
+#
+# usage:
+#   .\scripts\launch_pcsx_debug.ps1
+#   .\scripts\launch_pcsx_debug.ps1 -ExePath build\hello_gte.ps-exe
+#   .\scripts\launch_pcsx_debug.ps1 -HelperZip scripts\pcsx_debug_helper.zip
+#
+# After launch:
+#   - gdb: target remote localhost:3333
+#   - web: curl http://localhost:8080/api/v1/lua/gte
+#
+# Companion: scripts/debug_psyq.ps1 (bare launch — no .ps-exe, no helper).
+
+[CmdletBinding()]
+param(
+    [string]$PcsxPath = (Join-Path $PSScriptRoot '..\toolchain\pcsx-redux\vsprojects\x64\Release\pcsx-redux.exe'),
+    [string]$ExePath  = (Join-Path $PSScriptRoot '..\build\hello_gte.ps-exe'),
+    [string]$HelperZip = (Join-Path $PSScriptRoot 'pcsx_debug_helper.zip'),
+    [int]   $GdbPort  = 3333,
+    [int]   $WebPort  = 8080
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ── Pre-checks ──
+foreach ($p in @($PcsxPath, $ExePath, $HelperZip)) {
+    if (-not (Test-Path $p)) {
+        Write-Error "Missing: $p"
+        exit 1
+    }
+}
+
+# Kill any existing pcsx-redux so the archive file isn't locked.
+Get-Process pcsx-redux -ErrorAction SilentlyContinue | Stop-Process -Force
+Start-Sleep -Seconds 2
+
+# ── Launch ──
+$absExe  = [System.IO.Path]::GetFullPath($ExePath)
+$absZip  = [System.IO.Path]::GetFullPath($HelperZip)
+
+$args = @(
+    '-gdb', '-run'
+    '-loadexe', "`"$absExe`""
+    '-archive', "`"$absZip`""
+)
+
+Write-Host "Launching pcsx-redux..." -ForegroundColor Cyan
+Write-Host "  ps-exe    : $absExe"
+Write-Host "  helper zip: $absZip"
+Write-Host "  gdb       : localhost:$GdbPort"
+Write-Host "  web       : localhost:$WebPort/api/v1/lua/gte"
+Write-Host ""
+
+Start-Process -FilePath $PcsxPath -ArgumentList $args | Out-Null
+
+# ── Wait for both endpoints to come up ──
+$deadline = (Get-Date).AddSeconds(15)
+while ((Get-Date) -lt $deadline) {
+    $gdbUp = $false
+    $webUp = $false
+    try {
+        $tcp = New-Object System.Net.Sockets.TcpClient
+        $tcp.BeginConnect('localhost', $GdbPort, $null, $null) | Out-Null
+        Start-Sleep -Milliseconds 100
+        $gdbUp = $tcp.Connected
+        $tcp.Close()
+    } catch { $gdbUp = $false }
+    try {
+        $r = Invoke-WebRequest -Uri "http://localhost:$WebPort/" -UseBasicParsing -TimeoutSec 1 -ErrorAction SilentlyContinue
+        $webUp = $r.StatusCode -ne 0
+    } catch { $webUp = $false }
+    if ($gdbUp -and $webUp) { break }
+    Start-Sleep -Milliseconds 500
+}
+
+# ── Smoke-test the gte handler ──
+try {
+    $r = Invoke-WebRequest -Uri "http://localhost:$WebPort/api/v1/lua/gte" -UseBasicParsing -TimeoutSec 5
+    $firstLine = ([System.Text.Encoding]::UTF8.GetString($r.Content) -split "`n")[0]
+    Write-Host "GTE handler OK: $firstLine" -ForegroundColor Green
+} catch {
+    Write-Warning "GTE handler NOT responding: $_"
+    Write-Host "Check the pcsx-redux Lua Console for debug cli messages." -ForegroundColor Yellow
+}
+
+Write-Host ""
+Write-Host "pcsx-redux running. PIDs:" -ForegroundColor Cyan
+Get-Process pcsx-redux | Select-Object Id, ProcessName | Format-Table

scripts/passes/annotation.lua

@@ -3,16 +3,13 @@
 --- 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) { ... };`)
 ---
---- Source scanning: done ONCE upstream by `duffle.scan_source()` (ps1_meta.lua pre-scans each
---- source and stashes the result in `src.scan`). This pass is pure: read from the scan, run
---- checks, emit findings. No source re-walking.
+--- Source scanning: done ONCE upstream by `duffle.scan_source()` (ps1_meta.lua pre-scans each source and stashes the result in `src.scan`). 
 ---
 --- 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`
 ---
---- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible
+--- **Conventions**: tabs (1/level), EmmyLua annotations, no regex, Lua 5.3 compatible
 
 -- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
@@ -21,13 +18,12 @@
 -- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
 -- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
 local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
-local write_file          = duffle.write_file
-local ensure_dir          = duffle.ensure_dir
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local write_file     = duffle.write_file
+local ensure_dir     = duffle.ensure_dir
 
 -- Domain tables (single source of truth in duffle.lua).
 local WAVE_CONTEXT_REGS = duffle.WAVE_CONTEXT_REGS
-local TAPE_ATOM_MACROS  = duffle.TAPE_ATOM_MACROS
 
 local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 
@@ -68,11 +64,22 @@ local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 --- @field binds   string|nil    -- Binds_X name if any
 --- @field reads   string[]      -- R_* names (read targets)
 --- @field writes  string[]      -- R_* names (write targets)
+--- @field errors  string[]|nil  -- parse-time errors from scan_source (atom_info body malformed)
 
 --- @class Finding
 --- @field line integer  -- source line (or 0 for pass-level)
 --- @field msg  string   -- finding message
 
+--- @class Findings
+--- @field errors   Finding[]
+--- @field warnings Finding[]
+--- @field info     Finding[]
+
+--- @class PipeCtx
+--- @field atom_index   table<string, AtomAnnotation>  -- name -> AtomAnnotation (only kind=="atom")
+--- @field binds_index  table<string, BindsStruct>     -- name -> BindsStruct
+--- @field annot_counts table<string, integer>          -- name -> annotation count (for unique_annotation check)
+
 --- @class AnnotatedResult
 --- @field atoms    AtomEntry[]
 --- @field annots   AtomAnnotation[]
@@ -82,6 +89,154 @@ local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 --- @field warnings Finding[]
 --- @field info     Finding[]
 
+-- ════════════════════════════════════════════════════════════════════════════
+-- Per-check functions (the CHECK_RULES table's payload)
+-- ════════════════════════════════════════════════════════════════════════════
+--
+-- Each check has a uniform `append_to_findings` shape (errors[] / warnings[] / info[]).
+-- The dispatcher in `validate()` decides which findings list each check writes to — by convention,
+-- "existence" checks (declaration must exist, struct must exist) write errors[]; "shape" checks
+-- (writes/reads must be wave-context) write warnings[]. The `macro_word_drift` check writes
+-- both errors[] (missing/mismatch) and info[] (match).
+
+--- Check: every annotated atom must have a matching MipsAtom_(name) declaration.
+--- @param a AtomAnnotation
+--- @param pipe_ctx PipeCtx
+--- @param findings Findings
+local function check_atom_decl_exists(a, pipe_ctx, findings)
+	if not pipe_ctx.atom_index[a.name] then
+		findings.errors[#findings.errors + 1] = {
+			line = a.line,
+			msg  = string.format("annotation for '%s' has no matching MipsAtom_(%s) { ... }", a.name, a.name),
+		}
+	end
+end
+
+--- Check: every atom may have AT MOST ONE annotation.
+--- Post-loop: needs full-corpus `annot_counts` from pipe_ctx.
+--- @param pipe_ctx PipeCtx
+--- @param findings Findings
+local function check_unique_annotation(pipe_ctx, findings)
+	for name, n in pairs(pipe_ctx.annot_counts) do
+		if n > 1 then
+			findings.errors[#findings.errors + 1] = {
+				line = pipe_ctx.atom_index[name] and pipe_ctx.atom_index[name].line or 0,
+				msg  = string.format("MipsAtom_(%s) has %d annotations (expected at most 1)", name, n),
+			}
+		end
+	end
+end
+
+--- Check: BIND atoms must reference a real Binds_* struct.
+--- 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.
+--- @param a AtomAnnotation
+--- @param pipe_ctx PipeCtx
+--- @param findings Findings
+local function check_binds_struct_exists(a, pipe_ctx, findings)
+	if not a.binds then return end
+	if pipe_ctx.binds_index[a.binds] then return end
+	findings.warnings[#findings.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),
+	}
+end
+
+--- Check: Binds_* struct fields must correspond to known wave-context registers.
+--- Also checks that all `atom_writes(...)` entries are wave-context registers.
+--- @param a AtomAnnotation
+--- @param pipe_ctx PipeCtx
+--- @param findings Findings
+local function check_binds_field_wave_context(a, pipe_ctx, findings)
+	if not (a.binds and pipe_ctx.binds_index[a.binds]) then return end
+	local bs = pipe_ctx.binds_index[a.binds]
+
+	for _, f in ipairs(bs.fields) do
+		local candidate = "R_" .. f.name
+		if not is_wave_context_reg(candidate) then
+			findings.warnings[#findings.warnings + 1] = {
+				line = bs.line,
+				msg  = string.format("%s field '%s' doesn't match a known wave-context register (candidate '%s')", a.binds, f.name, candidate),
+			}
+		end
+	end
+
+	for _, w in ipairs(a.writes) do
+		if not is_wave_context_reg(w) then
+			findings.warnings[#findings.warnings + 1] = {
+				line = a.line,
+				msg  = string.format("%s writes '%s' which is not a known wave-context register", a.name, w),
+			}
+		end
+	end
+end
+
+--- Check: atom_reads(...) entries should be wave-context registers (or R_TapePtr for rbind).
+--- @param a AtomAnnotation
+--- @param pipe_ctx PipeCtx
+--- @param findings Findings
+local function check_reads_wave_context(a, pipe_ctx, findings)
+	for _, r in ipairs(a.reads) do
+		if not is_wave_context_reg(r) and r ~= "R_TapePtr" then
+			findings.warnings[#findings.warnings + 1] = {
+				line = a.line,
+				msg  = string.format("atom '%s' reads '%s' which is not a known wave-context register", a.name, r),
+			}
+		end
+	end
+end
+
+--- Check: TAPE_WORDS(mac_X, N) ↔ WORD_COUNT(mac_X, N) drift.
+--- Three outcomes: missing (error), mismatch (error), match (info).
+--- @param m MacroEntry
+--- @param wc table<string, integer>  -- the shared word-count table (from ctx.shared.word_counts)
+--- @param findings Findings
+local function check_macro_word_drift(m, wc, findings)
+	local declared = wc[m.name]
+	if not declared then
+		findings.errors[#findings.errors + 1] = {
+			line = m.line,
+			msg  = string.format("TAPE_WORDS(%s, %d) but '%s' is not in metadata.h", m.name, m.words, m.name),
+		}
+		return
+	end
+	if declared ~= m.words then
+		findings.errors[#findings.errors + 1] = {
+			line = m.line,
+			msg  = string.format("DRIFT: TAPE_WORDS(%s, %d) but metadata.h declares WORD_COUNT(%s, %d)", m.name, m.words, m.name, declared),
+		}
+		return
+	end
+	findings.info[#findings.info + 1] = {
+		line = m.line,
+		msg  = string.format("OK: %s = %d words", m.name, m.words),
+	}
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- CHECK_RULES — data-driven check dispatch (the plex pattern)
+-- ════════════════════════════════════════════════════════════════════════════
+--
+-- Each rule entry picks one of three "shapes" of dispatch:
+--   per_annot(annot, pipe_ctx, findings) — runs once per AtomAnnotation
+--   post(pipe_ctx, findings)             — runs once after all per_annot calls complete (full-corpus aggregation)
+--   per_macro(macro, wc, findings)       — runs once per TAPE_WORDS / _Pragma macro declaration
+--
+-- Adding a new check = 1 row here + 1 function above. The `validate()` dispatch loop never needs editing.
+
+local CHECK_RULES = {
+	{ name = "atom_decl_exists",         per_annot = check_atom_decl_exists         },
+	{ name = "binds_struct_exists",      per_annot = check_binds_struct_exists      },
+	{ name = "binds_field_wave_context", per_annot = check_binds_field_wave_context },
+	{ name = "reads_wave_context",       per_annot = check_reads_wave_context       },
+	{ name = "unique_annotation",        post      = check_unique_annotation        },
+	{ name = "macro_word_drift",         per_macro = check_macro_word_drift         },
+}
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- Validation
 -- ════════════════════════════════════════════════════════════════════════════
@@ -115,138 +270,65 @@ local function validate(ctx, src)
 			binds  = info.binds,
 			reads  = info.reads or {},
 			writes = info.writes or {},
-			errors = {},
+			errors = info.errors,
 		}
 	end
 
-	-- Index atoms by name for lookup.
-	local atom_index = {}
-	for _, a in ipairs(atoms) do atom_index[a.name] = a end
-
-	-- Index binds by name for lookup.
-	local binds_index = {}
-	for _, b in ipairs(scan.binds) do binds_index[b.name] = b end
-
-	local errors   = {}
-	local warnings = {}
-	local info     = {}
-
-	-- 1. Every annotated atom must exist as a real MipsAtom_ declaration.
-	for _, a in ipairs(annots) do
-		if not atom_index[a.name] then
-			errors[#errors + 1] = {
-				line = a.line,
-				msg  = string.format("annotation for '%s' has no matching MipsAtom_(%s) { ... }", a.name, a.name),
-			}
+	-- Build pipe_ctx (Fleury: expose structure). Pre-compute everything the per-check functions need.
+	-- Single source of truth for atom / binds / annotation-count lookups.
+	local pipe_ctx = {
+		atom_index   = {},
+		binds_index  = {},
+		annot_counts = {},
+	}
+	for _, a in ipairs(atoms)      do pipe_ctx.atom_index [a.name] = a end
+	for _, b in ipairs(scan.binds) do pipe_ctx.binds_index[b.name] = b end
+	for _, a in ipairs(annots)     do
+		if a.name then
+			pipe_ctx.annot_counts[a.name] = (pipe_ctx.annot_counts[a.name] or 0) + 1
 		end
+	end
+
+	-- Findings live in a single struct with three lists (errors / warnings / info).
+	-- Each check writes to the list appropriate for its severity.
+	local findings = { errors = {}, warnings = {}, info = {} }
+
+	-- Propagate parse-time errors from scan_source's atom_info parsing.
+	-- These are errors found in the atom_info(...) body itself (e.g., malformed args).
+	-- They are pre-existing in the scan payload — we just lift them into our findings list.
+	for _, a in ipairs(annots) do
 		if a.errors then
 			for _, msg in ipairs(a.errors) do
-				errors[#errors + 1] = {line = a.line, msg = string.format("'%s': %s", a.name, msg)}
-			end
-		end
-	end
-
-	-- 2. Every atom may have AT MOST ONE annotation (no duplicates).
-	-- (Atoms with ZERO annotations are valid in the new minimal shape.)
-	local count_per_atom = {}
-	for _, a in ipairs(annots) do
-		if a.name then
-			count_per_atom[a.name] = (count_per_atom[a.name] or 0) + 1
-		end
-	end
-	for name, n in pairs(count_per_atom) do
-		if n > 1 then
-			errors[#errors + 1] = {
-				line = atom_index[name] and atom_index[name].line or 0,
-				msg  = string.format("MipsAtom_(%s) has %d annotations (expected at most 1)", name, n),
-			}
-		end
-	end
-
-	-- 3. (Phase validity check DROPPED. Phases were removed from the annotation DSL.)
-
-	-- 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.
-				warnings[#warnings + 1] = {
+				findings.errors[#findings.errors + 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),
+					msg  = string.format("'%s': %s", a.name, msg),
 				}
 			end
 		end
 	end
 
-	-- 5. BIND writes must be wave-context registers that match Binds_ fields.
+	-- THE per-annotation pipeline. ONE loop. CHECK_RULES dispatches per_annot rules.
 	for _, a in ipairs(annots) do
-		if a.binds and binds_index[a.binds] then
-			local bs = binds_index[a.binds]
-
-			for _, f in ipairs(bs.fields) do
-				local candidate = "R_" .. f.name
-				if not is_wave_context_reg(candidate) then
-					warnings[#warnings + 1] = {
-						line = bs.line,
-						msg  = string.format("%s field '%s' doesn't match a known wave-context register (candidate '%s')", a.binds, f.name, candidate),
-					}
-				end
-			end
-
-			for _, w in ipairs(a.writes) do
-				if not is_wave_context_reg(w) then
-					warnings[#warnings + 1] = {
-						line = a.line,
-						msg  = string.format("%s writes '%s' which is not a known wave-context register", a.name, w),
-					}
-				end
-			end
+		for _, rule in ipairs(CHECK_RULES) do
+			if rule.per_annot then rule.per_annot(a, pipe_ctx, findings) end
 		end
 	end
 
-	-- 6. INFO reads should be wave-context registers (or R_TapePtr for rbind).
-	for _, a in ipairs(annots) do
-		for _, r in ipairs(a.reads) do
-			if not is_wave_context_reg(r) and r ~= "R_TapePtr" then
-				warnings[#warnings + 1] = {
-					line = a.line,
-					msg  = string.format("atom '%s' reads '%s' which is not a known wave-context register", a.name, r),
-				}
-			end
-		end
+	-- Post-loop rules (one-shot checks that need full-corpus aggregation in pipe_ctx).
+	for _, rule in ipairs(CHECK_RULES) do
+		if rule.post then rule.post(pipe_ctx, findings) end
 	end
 
-	-- 7. TAPE_WORDS(mac_X, N) ↔ WORD_COUNT(mac_X, N) drift.
-	--    Three outcomes: missing (error), mismatch (error), match (info).
-	local function check_macro_drift(m, declared)
-		if not declared then
-			errors[#errors + 1] = {
-				line = m.line,
-				msg  = string.format("TAPE_WORDS(%s, %d) but '%s' is not in metadata.h", m.name, m.words, m.name),
-			}
-			return
-		end
-		if declared ~= m.words then
-			errors[#errors + 1] = {
-				line = m.line,
-				msg  = string.format("DRIFT: TAPE_WORDS(%s, %d) but metadata.h declares WORD_COUNT(%s, %d)", m.name, m.words, m.name, declared),
-			}
-			return
-		end
-		info[#info + 1] = {
-			line = m.line,
-			msg  = string.format("OK: %s = %d words", m.name, m.words),
-		}
-	end
+	-- Per-macro rules (TAPE_WORDS vs WORD_COUNT drift).
+	local wc = ctx.shared.word_counts
 	for _, m in ipairs(scan.macros) do
-		check_macro_drift(m, ctx.shared.word_counts[m.name])
+		for _, rule in ipairs(CHECK_RULES) do
+			if rule.per_macro then rule.per_macro(m, wc, findings) end
+		end
 	end
 
-	-- 8. Information summary.
-	info[#info + 1] = {
+	-- Information summary (always emitted).
+	findings.info[#findings.info + 1] = {
 		line = 0,
 		msg  = string.format("scanned: %d atom(s), %d annotation(s), %d macro-word-decl(s), %d binds struct(s)",
 			#atoms, #annots, #scan.macros, #scan.binds),
@@ -257,9 +339,9 @@ local function validate(ctx, src)
 		annots   = annots,
 		macros   = scan.macros,
 		binds    = scan.binds,
-		errors   = errors,
-		warnings = warnings,
-		info     = info,
+		errors   = findings.errors,
+		warnings = findings.warnings,
+		info     = findings.info,
 	}
 end
 
@@ -300,7 +382,7 @@ end
 
 --- Stash aggregated per-module results for the report pass to consume.
 local function emit_module_annotations_stub(ctx, dir, dir_basename, atoms_count)
-	ctx.flags         = ctx.flags or {}
+	ctx.flags                = ctx.flags                or {}
 	ctx.flags._annot_results = ctx.flags._annot_results or {}
 	ctx.flags._annot_results[#ctx.flags._annot_results + 1] = {
 		dir          = dir,
@@ -339,20 +421,20 @@ function M.run(ctx)
 		local dir_errors   = {}
 		local dir_warnings = {}
 		-- Per-source validate() results, cached for the report pass (it reads from this instead of re-validating each source).
-		ctx.flags                       = ctx.flags or {}
+		ctx.flags                       = ctx.flags                       or {}
 		ctx.flags._annot_source_results = ctx.flags._annot_source_results or {}
 		for _, src in ipairs(dir_sources) do
-			local result = validate(ctx, src)
+			local result  = validate(ctx, src)
 			result.source = src.path                                  -- tag for downstream rendering
 			ctx.flags._annot_source_results[src.path] = result          -- stash so report.lua reads from cache instead of re-running validate()
 			dir_atoms = dir_atoms + #result.atoms
 			for _, e in ipairs(result.errors) do
 				dir_errors[#dir_errors + 1] = { line = e.line, msg = e.msg, source = src.path }
-				errors[#errors + 1] = { line = e.line, msg = e.msg }
+				errors    [#errors     + 1] = { line = e.line, msg = e.msg }
 			end
 			for _, w in ipairs(result.warnings) do
 				dir_warnings[#dir_warnings + 1] = { line = w.line, msg = w.msg }
-				warnings[#warnings + 1] = { line = w.line, msg = w.msg }
+				warnings    [#warnings     + 1] = { line = w.line, msg = w.msg }
 			end
 		end
 

scripts/passes/atoms_source_map.lua

@@ -0,0 +1,586 @@
+--- passes/atoms_source_map.lua — Per-.word source-line map emitter for tape atoms.
+---
+--- Reads the pre-scanned SourceScan payload (produced once upstream by `duffle.scan_source`)
+--- for `MipsAtom_(name)` (kind="atom"), `MipsAtomComp_` / `MipsAtomComp_Proc_` (kind="comp_*"),
+--- and `MipsCode code_<name>` (kind="raw_atom") declarations. 
+--- Walks each atom's pre-tokenized body (`{{tok=string, rel=integer}, ...}` from `duffle.tokenize_body`), 
+--- counts per-token word contributions via `ctx.shared.word_counts`, and emits one
+--- `WORD N LINE L TEXT T` line per `.word` to `<out_root>/<basename>.atoms.sourcemap.txt`.
+---
+--- **Two output forms** (per the workspace's per-emission-form pattern from
+--- `guide_metaprogram_ssdl.md`):
+---   1. **Canonical text form** — `<out_root>/<basename>.atoms.sourcemap.txt`.
+---      Always emitted. Format-version-tagged for forward-compat. 
+---      Lives in `<out_root>/` (build/gen) NOT `<source_dir>/gen/`. This file is a **build report**, not a compile artifact. 
+---      Matches the convention used by `annotation.lua` (`<out_root>/<basename>.errors.h`) + `static_analysis.lua` (`<out_root>/<basename>.static_analysis.txt`).
+---      Compile artifacts (`*.macs.h`, `*.offsets.h`) stay in `<source_dir>/gen/`.
+---   2. **gdb-runtime form** — `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`
+---      (pure gdb command script; addresses pre-computed via `nm`; the 9 user commands defined as `define ... end` blocks).
+---      Emitted ONLY when `ctx.flags.gdb_runtime` is true AND `ctx.flags.elf_path` points to an existing ELF.
+---      The gdb runtime form lets `gdb-multiarch --without-python` users (the common case on Windows MinGW builds) 
+---      load the source-map data via `source <path>` — no Python/Tcl/Guile required.
+---
+--- **Output format** (canonical text form):
+---   ```
+---   # FORMAT_VERSION 1
+---   # auto-generated by ps1_meta.lua (passes/atoms_source_map.lua) — DO NOT EDIT
+---   ATOM <name> "<abs-source-path>" <total_words>
+---   WORD 0  LINE 49  TEXT load_half_u(R_T0, R_FaceCursor, 0 * S_(S2)),
+---   WORD 1  LINE 49  TEXT load_half_u(R_T0, R_FaceCursor, 0 * S_(S2)),
+---   ... (one WORD line per .word emitted by the atom body) ...
+---   ENDATOM
+---   ATOM <next-name> "<abs-source-path>" <total_words>
+---   ...
+---   ENDATOM
+---   ```
+---
+--- Marker calls (`atom_label(...)`, `atom_offset(...)`) emit 0 `.word`s. 
+--- They share the same walking convention as `passes/offsets.lua :: scan_atom_body`: 
+--- markers do NOT advance the word-offset counter, but if a marker is bundled on the same token with a
+--- trailing instruction (e.g. `atom_label(foo) load_half_u(...)`), 
+--- the trailing instruction's word count is added. This matches `offsets.lua :: count_marker_rest`.
+---
+--- **Conventions:** tabs (1/level), EmmyLua annotations, no regex,
+--- Lua 5.3 compatible.
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- Module-scope requires + package.path setup
+-- ════════════════════════════════════════════════════════════════════════════
+
+-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works
+-- both standalone + when require'd). `duffle_paths.lua` sets package.path then
+-- returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
+local duffle           = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local elf_dwarf        = require("elf_dwarf")
+local word_count_eval  = require("word_count_eval")
+local count_token_words = word_count_eval.count_token_words
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- Constants
+-- ════════════════════════════════════════════════════════════════════════════
+
+-- Format version emitted as the first line. Bump + add a migration test if the
+-- format changes; the gdb runtime loader rejects mismatches (E2).
+local FORMAT_VERSION = 1
+
+-- Marker-call identifiers (mirrors offsets.lua:33-34).
+local LABEL_MARKER  = "atom_label"
+local OFFSET_MARKER = "atom_offset"
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- Type declarations
+-- ════════════════════════════════════════════════════════════════════════════
+
+--- @class AtomSourceMapCtx
+--- @field sources            table[]    -- SourceScan payload per source (from `ctx.sources`)
+--- @field shared             table      -- `ctx.shared`
+--- @field shared.word_counts table      -- macro name -> word count (populated by word-counts + components passes)
+--- @field out_root           string     -- output root (e.g. "build/gen")
+--- @field dry_run            boolean    -- if true, compute but don't write
+--- @field flags              table      -- `ctx.flags`; reads `flags.gdb_runtime` + `flags.elf_path`
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- Helpers
+-- ════════════════════════════════════════════════════════════════════════════
+
+--- True iff the leading identifier of `tok` is a marker call (`atom_label` / `atom_offset`).
+--- Mirrors `passes/offsets.lua :: is_marker_token` (which is file-local there).
+--- @param tok string
+--- @return boolean
+local function is_marker_token(tok)
+	local leading = duffle.read_ident(tok, 1)
+	return leading == LABEL_MARKER or leading == OFFSET_MARKER
+end
+
+--- Count words contributed by the non-marker portion of `tok` (after the marker's closing `)`).
+--- Mirrors offsets.lua:182 `count_marker_rest`. 
+--- Returns 0 if there's no trailing content after the marker call.
+--- @param tok string
+--- @param wc table
+--- @return integer
+local function count_marker_rest(tok, wc)
+	local marker_end = duffle.find_marker_call_end(tok)
+	if not marker_end or marker_end >= #tok then return 0 end
+	local rest = duffle.trim(tok:sub(marker_end))
+	if rest == "" then return 0 end
+	return count_token_words(rest, wc)
+end
+
+--- Compute per-word entries for an atom. 
+--- Shared between the canonical text form (per-source `.atoms.sourcemap.txt`) 
+--- and the gdb-runtime form (`gdb_tape_atoms_runtime.gdb`).
+---
+--- Returns a list of `{pos, line, text}` entries + the total word count.
+--- Markers contribute 0 entries (the marker call emits 0 `.word`s).
+--- @param atom table   -- one entry of scan.atoms / scan.raw_atoms
+--- @param src  table   -- SourceFile (has .scan with .line_of(), .path)
+--- @param wc   table   -- shared.word_counts
+--- @return table[], integer
+local function compute_word_entries(atom, src, wc)
+	local entries = {}
+	local pos     = 0
+	for _, t in ipairs(atom.body_tokens) do
+		local tok = t.tok
+		local rel = t.rel
+
+		local words
+		if is_marker_token(tok) then
+			words = count_marker_rest(tok, wc)
+		else
+			words = count_token_words(tok, wc)
+		end
+
+		if words > 0 then
+			-- Source line for THIS token = line containing byte offset `atom.body_off + rel`.
+			-- `src.scan.line_of(...)` is O(log N) via LineIndex.
+			local line = src.scan.line_of(atom.body_off + rel)
+			-- Flatten newlines + tabs in TEXT to spaces so each WORD entry fits on
+			-- one physical line. The gdb Python parser (or our pure-gdb parser)
+			-- does line-based splits; multi-line TEXT would break it.
+			local text = duffle.trim(tok):gsub("[\t\r\n]+", " ")
+			for _ = 1, words do
+				entries[#entries + 1] = { pos = pos, line = line, text = text }
+				pos = pos + 1
+			end
+		end
+	end
+	return entries, pos
+end
+
+--- Render one atom's stanza for the canonical text form
+--- (ATOM header line, N WORD lines, ENDATOM marker). Returns (lines, total_words).
+--- @param src    table
+--- @param atom   table
+--- @param wc     table
+--- @return string[], integer
+local function emit_atom_stanza(src, atom, wc)
+	local lines              = {}
+	local rel_path           = src.path:gsub("\\", "/")
+	local entries, total     = compute_word_entries(atom, src, wc)
+
+	-- ATOM header line with placeholder total (patched after we know it).
+	lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
+
+	for _, we in ipairs(entries) do
+		lines[#lines + 1] = string.format("WORD %d  LINE %d  TEXT %s",
+			we.pos, we.line, we.text)
+	end
+
+	-- Patch the placeholder total in the ATOM header line.
+	lines[1] = lines[1]:gsub(" 0$", " " .. tostring(total))
+	lines[#lines + 1] = "ENDATOM"
+	return lines, total
+end
+
+--- Render the full source map file content for one source (one .atoms.sourcemap.txt per source).
+--- Mirrors offsets.lua's `project_atoms` shape: scan.atoms + scan.raw_atoms, no kind filter.
+--- @param src table
+--- @param wc table
+--- @return string
+local function render_source_map(src, wc)
+	local lines = {}
+	lines[#lines + 1] = "# FORMAT_VERSION " .. FORMAT_VERSION
+	lines[#lines + 1] = "# auto-generated by ps1_meta.lua (passes/atoms_source_map.lua) — DO NOT EDIT"
+
+	for _, atom in ipairs(src.scan.atoms or {}) do
+		local stanza = emit_atom_stanza(src, atom, wc)
+		for _, line in ipairs(stanza) do
+			lines[#lines + 1] = line
+		end
+	end
+	for _, atom in ipairs(src.scan.raw_atoms or {}) do
+		local stanza = emit_atom_stanza(src, atom, wc)
+		for _, line in ipairs(stanza) do
+			lines[#lines + 1] = line
+		end
+	end
+
+	return table.concat(lines, "\n") .. "\n"
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- gdb-runtime emission (post-link, addresses via nm)
+-- ════════════════════════════════════════════════════════════════════════════
+
+--- Escape a string for embedding in a gdb `set $var = "..."` literal.
+--- gdb uses C-style escaping; we escape `\` and `"` (newlines were flattened earlier).
+--- @param s string
+--- @return string
+local function gdb_escape(s)
+	return (s:gsub("\\", "\\\\"):gsub('"', '\\"'))
+end
+
+--- Build the list of atoms with addresses + word entries.
+--- Shared helper for the gdb-runtime file emission.
+--- @param ctx PassCtx
+--- @return table[] -- list of {idx, name, src_path, file_base, addr, size_bytes, words, entries}
+local function build_atom_table(ctx)
+	local wc = (ctx.shared and ctx.shared.word_counts) or {}
+	local addrs = elf_dwarf.read_nm(ctx.flags.elf_path)
+
+	local matched = {}
+	for _, src in ipairs(ctx.sources) do
+		if src.scan then
+			local file_base = src.path:match("([^/\\]+)$") or src.path
+			for _, atom in ipairs(src.scan.atoms or {}) do
+				if atom.kind == nil or atom.kind == "atom" then
+					local name    = atom.raw_name or atom.name
+					local info    = addrs[name]
+					if info then
+						local entries, total = compute_word_entries(atom, src, wc)
+						matched[#matched + 1] = {
+							name       = name,
+							src_path   = src.path,
+							file_base  = file_base,
+							addr       = info[1],
+							size_bytes = info[2],
+							words      = total,
+							entries    = entries,
+						}
+					end
+				end
+			end
+			for _, atom in ipairs(src.scan.raw_atoms or {}) do
+				local name = atom.name
+				local info = addrs[name]
+				if info then
+					local entries, total = compute_word_entries(atom, src, wc)
+					matched[#matched + 1] = {
+						name       = name,
+						src_path   = src.path,
+						file_base  = file_base,
+						addr       = info[1],
+						size_bytes = info[2],
+						words      = total,
+						entries    = entries,
+					}
+				end
+			end
+		end
+	end
+
+	-- Deterministic order: sort by address (matches `nm` output ordering).
+	table.sort(matched, function(a, b) return a.addr < b.addr end)
+	for i, a in ipairs(matched) do
+		a.idx = i - 1
+	end
+	return matched
+end
+
+--- Append the 9 gdb command definitions to `lines`. Pure gdb scripting no Python, no Tcl, no Guile required. 
+--- **Fully hardcoded per-atom** because gdb doesn't do nested `$` substitution in var names
+--- `$__atom_name_$__i` inside a `while` loop is treated as one literal identifier, not a concat.
+---
+--- Each command is a static sequence of `printf` / `tbreak` / `if ... end` blocks.
+--- The Lua pass emits N atoms' worth of lines — no runtime iteration. 
+--- With 7 atoms + ~200 word entries, the runtime file is ~2000 lines, all auto-generated, no human edit ever.
+--- @param lines   table  -- output line buffer (mutated in place)
+--- @param matched table  -- list of atom records from `build_atom_table`
+local function append_gdb_commands(lines, matched)
+	-- ── tape_atoms ──
+	-- Hardcoded one printf per atom. No loop.
+	lines[#lines + 1] = "define tape_atoms"
+	for _, a in ipairs(matched) do
+		-- gdb 12.1 quirk: literals in printf args require an attached target.
+		-- Use the per-atom convenience vars set above as printf args.
+		lines[#lines + 1] = string.format(
+			'  printf "  code_%%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
+			a.idx, a.idx, a.idx)
+	end
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document tape_atoms"
+	lines[#lines + 1] = "  List every tape atom symbol in the loaded ELF (code_<name>) with .rodata addr + word count."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	-- ── break_atom (generic) + per-atom break_atom_X ──
+	lines[#lines + 1] = "define break_atom"
+	lines[#lines + 1] = '  echo "Usage: break_atom_<exact_name>  (pick from the list below)"'
+	for _, a in ipairs(matched) do
+		lines[#lines + 1] = string.format(
+			'  printf "  break_atom_%%-32s\\n", $__atom_name_%d', a.idx)
+	end
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document break_atom"
+	lines[#lines + 1] = "  Generic help: lists the per-atom break_atom_<name> commands."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	for _, a in ipairs(matched) do
+		lines[#lines + 1] = string.format("define break_atom_%s", a.name)
+		lines[#lines + 1] = string.format("  break *$__atom_addr_%d", a.idx)
+		lines[#lines + 1] = string.format(
+			'  printf "  Breakpoint set at code_%s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
+		lines[#lines + 1] = "end"
+		lines[#lines + 1] = string.format("document break_atom_%s", a.name)
+		lines[#lines + 1] = string.format("  Set a breakpoint at code_%s.", a.name)
+		lines[#lines + 1] = "end"
+		lines[#lines + 1] = ""
+	end
+
+	-- ── step_atom / next_atom ──
+	-- Hardcoded one tbreak per atom. No loop.
+	lines[#lines + 1] = "define step_atom"
+	for _, a in ipairs(matched) do
+		lines[#lines + 1] = string.format("  tbreak *$__atom_addr_%d", a.idx)
+	end
+	lines[#lines + 1] = "  continue"
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document step_atom"
+	lines[#lines + 1] = "  Set one-shot BPs at every atom + continue. Stops at the next atom boundary."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	lines[#lines + 1] = "define next_atom"
+	lines[#lines + 1] = "  step_atom"
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document next_atom"
+	lines[#lines + 1] = "  Alias for step_atom."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	-- ── where_in_atom ──
+	-- Hardcoded one outer-if per atom; inside, one inner-if per WORD entry.
+	lines[#lines + 1] = "define where_in_atom"
+	lines[#lines + 1] = "  set $__pc = (unsigned int)$pc"
+	lines[#lines + 1] = "  set $__matched = 0"
+	for _, a in ipairs(matched) do
+		-- Precompute end_addr (gdb 12.1's expression evaluator chokes on `addr + words*4`).
+		lines[#lines + 1] = string.format(
+			"  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
+		lines[#lines + 1] = string.format(
+			"  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
+		lines[#lines + 1] = string.format(
+			'    printf "atom:    code_%%s\\n", $__atom_name_%d', a.idx)
+		lines[#lines + 1] = '    printf "addr:    0x%08x\\n", $__pc'
+		lines[#lines + 1] = string.format(
+			"    set $__word = ($__pc - $__atom_addr_%d) / 4", a.idx)
+		lines[#lines + 1] = string.format(
+			'    printf "word:    %%d/%%d\\n", $__word, $__atom_words_%d', a.idx)
+		-- One inner-if per WORD entry. Each word's line + text hardcoded.
+		for _, we in ipairs(a.entries) do
+			lines[#lines + 1] = string.format(
+				"    if $__word == %d", we.pos)
+			-- Escape TEXT for printf format string.
+			local escaped_text = we.text:gsub("%%", "%%%%"):gsub('"', '\\"')
+			lines[#lines + 1] = string.format(
+				'      printf "source:  %%s:%%d  %%s\\n", $__atom_file_%d, %d, "%s"',
+				a.idx, we.line, escaped_text)
+			lines[#lines + 1] = "    end"
+		end
+		-- Fallback for words beyond the source map (shouldn't happen if nm matches).
+		local max_word = 0
+		if #a.entries > 0 then max_word = a.entries[#a.entries].pos end
+		lines[#lines + 1] = string.format(
+			'    if $__word > %d', max_word)
+		lines[#lines + 1] = '      printf "source:  (no source-map entry for word %%d; map may be stale)\\n", $__word'
+		lines[#lines + 1] = "    end"
+		lines[#lines + 1] = "    set $__matched = 1"
+		lines[#lines + 1] = "  end"
+	end
+	lines[#lines + 1] = "  if !$__matched"
+	lines[#lines + 1] = '    echo PC is not inside any known atom (in .text or unmapped region).'
+	lines[#lines + 1] = "  end"
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document where_in_atom"
+	lines[#lines + 1] = "  Report current atom name, .rodata addr, word offset, and source line."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	-- ── stepi_inside_atom ──
+	-- Hardcoded one if-containment-check per atom (no loop).
+	-- Precompute end_addr in Lua so we don't ask gdb to evaluate `addr + words*4`
+	-- inside the if condition (gdb 12.1's expression evaluator chokes on the
+	-- `*` and emits a misleading 'function malloc' error in some gdb builds).
+	lines[#lines + 1] = "define stepi_inside_atom"
+	lines[#lines + 1] = "  set $__in_atom = 0"
+	lines[#lines + 1] = "  set $__did_step = 0"
+	lines[#lines + 1] = "  set $__pc = (unsigned int)$pc"
+	for _, a in ipairs(matched) do
+		-- Precompute end_addr in the convenience var (single expression gdb handles).
+		lines[#lines + 1] = string.format(
+			"  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
+		lines[#lines + 1] = string.format(
+			"  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
+		lines[#lines + 1] = "    set $__in_atom = 1"
+		lines[#lines + 1] = "    stepi"
+		lines[#lines + 1] = "    set $__did_step = 1"
+		lines[#lines + 1] = "  end"
+	end
+	lines[#lines + 1] = "  if !$__did_step"
+	lines[#lines + 1] = '    echo [gdb_tape_atoms] stepi_inside_atom: PC is not inside any atom; refusing to step.'
+	lines[#lines + 1] = "  end"
+	lines[#lines + 1] = "  where_in_atom"
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document stepi_inside_atom"
+	lines[#lines + 1] = "  One MIPS-instruction step, then where_in_atom. The step-and-see-source-line workflow."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	-- ── show_c2 ──
+	-- GTE data regs (COP2). pcsx-redux's gdb stub doesn't expose COP2 (only
+	-- 72 regs: 32 GPR + COP0 + FPR).
+	--   curl http://localhost:8080/api/v1/lua/gte
+	-- We keep the command definition as a stub that points the user at the plugin.
+	lines[#lines + 1] = "define show_c2"
+	lines[#lines + 1] = '  echo "[gdb_tape_atoms] show_c2: gdb stub does not expose COP2 in this build."'
+	lines[#lines + 1] = '  echo "[gdb_tape_atoms] Use scripts/pcsx_debug_helper.zip + curl http://localhost:8080/api/v1/lua/gte"'
+	lines[#lines + 1] = '  echo "[gdb_tape_atoms] (or pcsx-redux Debug > Registers window for a native view)"'
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document show_c2"
+	lines[#lines + 1] = "  Stub. The gdb stub in this pcsx-redux build does not expose COP2 regs."
+	lines[#lines + 1] = "  For GTE data + control state, use the pcsx_debug_helper Lua plugin or the"
+	lines[#lines + 1] = "  pcsx-redux Debug > Registers window."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	-- ── show_c2ctl ──
+	lines[#lines + 1] = "define show_c2ctl"
+	lines[#lines + 1] = '  echo "[gdb_tape_atoms] show_c2ctl: see show_c2 for the same workaround."'
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document show_c2ctl"
+	lines[#lines + 1] = "  Stub. Same workaround as show_c2."
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = ""
+
+	-- ── wave_ctx ──
+	lines[#lines + 1] = "define wave_ctx"
+	lines[#lines + 1] = '  printf "$t4 = R_FaceCursor     0x%08x\\n", $t4'
+	lines[#lines + 1] = '  printf "$t5 = R_VertBase       0x%08x\\n", $t5'
+	lines[#lines + 1] = '  printf "$t6 = R_OtBase         0x%08x\\n", $t6'
+	lines[#lines + 1] = '  printf "$t7 = R_PrimCursor     0x%08x\\n", $t7'
+	lines[#lines + 1] = "end"
+	lines[#lines + 1] = "document wave_ctx"
+	lines[#lines + 1] = "  Pretty-print the 4 wave-context GPRs ($t4=R_FaceCursor, $t5=R_VertBase, $t6=R_OtBase, $t7=R_PrimCursor). Requires target attached."
+	lines[#lines + 1] = "end"
+end
+
+--- Emit the gdb-runtime file (post-link). Pure gdb scripting — no Python.
+--- Reads ELF addresses via `mipsel-none-elf-nm -S`, embeds them in `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`
+--- so gdb loads the data via `set $var = ...` + `define ... end` blocks at source-time.
+--- @param ctx PassCtx
+local function emit_gdb_runtime(ctx)
+	if not (ctx.flags and ctx.flags.gdb_runtime) then return end
+	local elf_path = ctx.flags.elf_path
+	if not elf_path or elf_path == "" then
+		io.stderr:write("[atoms_source_map] --gdb-runtime requires --elf <elf>\n")
+		return
+	end
+	if lfs.attributes(elf_path, "mode") ~= "file" then
+		io.stderr:write(string.format(
+			"[atoms_source_map] --gdb-runtime: ELF not found at %s\n", elf_path))
+		return
+	end
+
+	local matched = build_atom_table(ctx)
+	if #matched == 0 then
+		io.stderr:write("[atoms_source_map] --gdb-runtime: no atoms matched against nm symbols (stale scan?).\n")
+		return
+	end
+
+	local lines = {}
+	lines[#lines + 1] = "# Auto-generated by ps1_meta.lua (passes/atoms_source_map.lua)"
+	lines[#lines + 1] = "# DO NOT EDIT — re-run ps1_meta.lua --atoms-source-map --gdb-runtime to regenerate"
+	lines[#lines + 1] = "# Sourced by scripts/gdb/gdb_tape_atoms.gdb (the wrapper)."
+	lines[#lines + 1] = "# Pure gdb scripting — no Python, no Tcl, no Guile required."
+	lines[#lines + 1] = "# Commands are FULLY HARDCODED per-atom because gdb doesn't do nested"
+	lines[#lines + 1] = "# `$` substitution in var names (`$foo_$i` is one literal identifier)."
+	lines[#lines + 1] = "# Per-atom convenience vars ($__atom_name_<i> etc.) are set so gdb's"
+	lines[#lines + 1] = "# `printf` has valid expression args (gdb 12.1 quirks: literals in"
+	lines[#lines + 1] = "# printf args require an attached target; convenience-var args do not)."
+	lines[#lines + 1] = string.format("# %d atoms from ELF: %s", #matched, elf_path)
+	lines[#lines + 1] = ""
+
+	-- Format version + count + ELF path (the latter is referenced by the load-line).
+	lines[#lines + 1] = "set $__atom_format_version = " .. FORMAT_VERSION
+	lines[#lines + 1] = string.format("set $__atom_count = %d", #matched)
+	lines[#lines + 1] = string.format('set $__elf_path = "%s"', gdb_escape(elf_path))
+	lines[#lines + 1] = ""
+
+	-- Per-atom convenience vars (used as printf args; literals aren't accepted
+	-- without an attached target on gdb 12.1).
+	for _, a in ipairs(matched) do
+		lines[#lines + 1] = string.format('set $__atom_name_%d = "%s"', a.idx, gdb_escape(a.name))
+		lines[#lines + 1] = string.format("set $__atom_addr_%d = 0x%x", a.idx, a.addr)
+		lines[#lines + 1] = string.format("set $__atom_words_%d = %d", a.idx, a.words)
+		lines[#lines + 1] = string.format('set $__atom_file_%d = "%s"', a.idx, gdb_escape(a.file_base))
+	end
+	lines[#lines + 1] = ""
+
+	-- The 9 commands (each `define ... end` overrides the wrapper's stub).
+	lines[#lines + 1] = "# ── 9 user commands (overrides wrapper stubs) ──"
+	append_gdb_commands(lines, matched)
+	lines[#lines + 1] = ""
+
+	-- Confirmation line for the source operator.
+	lines[#lines + 1] = 'printf "[gdb_tape_atoms] runtime loaded %d atoms from %s\\n", $__atom_count, $__elf_path'
+
+	local out_path = ctx.out_root .. "/gdb_tape_atoms_runtime.gdb"
+	if not ctx.dry_run then
+		duffle.ensure_dir(duffle.dirname(out_path))
+		duffle.write_file_lf(out_path, table.concat(lines, "\n") .. "\n")
+	end
+	io.stderr:write(string.format(
+		"[atoms_source_map] wrote %s (%d atoms)\n", out_path, #matched))
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- M — module exports
+-- ════════════════════════════════════════════════════════════════════════════
+
+local M = {}
+
+--- Pass entry: emit one `<out_root>/<basename>.atoms.sourcemap.txt` per source file
+--- that contains at least one `MipsAtom_(name)` / `MipsCode code_<name>` declaration.
+--- Optionally also emit `<ctx.out_root>/gdb_tape_atoms_runtime.gdb` when
+--- `ctx.flags.gdb_runtime` is true.
+--- @param ctx PassCtx
+--- @return PassResult
+function M.run(ctx)
+	local outputs  = {}
+	local errors   = {}
+	local warnings = {}
+
+	-- word-counts + components passes must have populated shared.word_counts.
+	-- If absent, the orchestrator wired the deps wrong — fail loud.
+	local wc = (ctx.shared and ctx.shared.word_counts) or {}
+	if not wc or not next(wc) then
+		warnings[#warnings + 1] = {
+			line = 0,
+			msg  = "atoms_source_map: ctx.shared.word_counts is empty; the word-counts + components passes may not have populated it. Check the PASSES dep edges.",
+		}
+	end
+
+	-- Always emit the canonical text form (per-source).
+	for _, src in ipairs(ctx.sources) do
+		if src.scan then
+			local n_atoms     = src.scan.atoms and #src.scan.atoms or 0
+			local n_raw_atoms = src.scan.raw_atoms and #src.scan.raw_atoms or 0
+			if n_atoms + n_raw_atoms > 0 then
+				local basename = duffle.basename_no_ext(src.path)
+				-- Build report, NOT compile artifact: live in <out_root> alongside the other reports
+				-- (annotation.lua's *.errors.h, static_analysis.lua's *.static_analysis.txt, gdb_tape_atoms_runtime.gdb).
+				-- The per-source <source_dir>/gen/ is reserved for headers actually #included by C.
+				local out_path = ctx.out_root .. "/" .. basename .. ".atoms.sourcemap.txt"
+				local content  = render_source_map(src, wc)
+
+				if not ctx.dry_run then
+					duffle.ensure_dir(duffle.dirname(out_path))
+					duffle.write_file_lf(out_path, content)
+				end
+
+				outputs[#outputs + 1] = { kind = "report", path = out_path }
+			end
+		end
+	end
+
+	-- Optionally emit the gdb-runtime form (post-link, one file per build).
+	if ctx.flags and ctx.flags.gdb_runtime then
+		emit_gdb_runtime(ctx)
+	end
+
+	return { outputs = outputs, errors = errors, warnings = warnings }
+end
+
+return M

scripts/passes/components.lua

@@ -30,8 +30,8 @@
 -- both standalone and when require'd from the orchestrator.
 -- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
 -- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local _bootstrap_dir  = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
+local duffle          = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 local word_count_eval = require("word_count_eval")
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -107,13 +107,14 @@ local M = {}
 -- @param before_pos integer
 -- @return integer|nil
 local function find_last_name_open_paren(source, name, before_pos)
-	local search     = source:sub(1, before_pos)
 	local name_open  = name .. "("
 	local last_idx   = nil
 	local scan_pos   = 1
 	while true do
-		local found = search:find(name_open, scan_pos, true)  -- plain (no regex)
-		if not found then break end
+		-- Pass `before_pos + 1` so string.find only returns positions < before_pos + 1
+		-- (string.find's 4th arg `plain` is true; we use the 3rd arg `init` for the upper bound).
+		local found = source:find(name_open, scan_pos, true)
+		if not found or found >= before_pos then break end
 		last_idx = found
 		scan_pos = found + #name_open
 	end
@@ -126,15 +127,15 @@ end
 --- 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
---- with possible qualifiers between).
+--- We then verify the preceding context ends with `MipsAtom` 
+--- (the function-decl keyword with possible qualifiers between).
 ---
 --- @param source string
 --- @param name string
 --- @param before_pos integer
 --- @return string|nil
 local function find_function_args_for(source, name, before_pos)
-	local last_idx = find_last_name_open_paren(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).
@@ -224,7 +225,7 @@ end
 -- 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)
+	local  open_at = find_block_comment_open(source, close_end_pos)
 	if not open_at then return nil end
 	local block_start = extend_left_over_indent(source, open_at)
 	return source:sub(block_start, close_end_pos), block_start
@@ -255,18 +256,18 @@ local function preceding_comment_block(source, pos)
 	local pieces   = {}
 	while true do
 		local non_ws = skip_ws_backward(source, scan_pos)
-		if non_ws == 0 then break end
+		if    non_ws == 0 then break end
 
 		local is_block_close = non_ws >= 2 and source:sub(non_ws - 1, non_ws) == "*/"
 		local is_line_end    = source:sub(non_ws, non_ws) == "\n" or source:sub(non_ws, non_ws) == "\r"
 
 		if is_block_close then
-			local block_text, new_scan_pos = capture_block_comment(source, non_ws)
+			local  block_text, new_scan_pos = capture_block_comment(source, non_ws)
 			if not block_text then break end
 			table.insert(pieces, 1, block_text)
 			scan_pos = new_scan_pos
 		elseif is_line_end then
-			local line_text, new_scan_pos = capture_line_comment(source, non_ws)
+			local  line_text, new_scan_pos = capture_line_comment(source, non_ws)
 			if not line_text then break end
 			table.insert(pieces, 1, line_text)
 			scan_pos = new_scan_pos
@@ -282,8 +283,8 @@ end
 -- Argument-name extraction
 -- ════════════════════════════════════════════════════════════════════════════
 
--- 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).
+-- 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
 -- @return integer
@@ -322,9 +323,6 @@ end
 ---   `"U4 off, U4 code, U1 r, U1 g, U1 b"`  ->  `{"off", "code", "r", "g", "b"}`
 ---   `"U4 *ptr"`                            ->  `{"ptr"}`
 ---   `""`                                   ->  nil
----
---- No regex — uses `duffle.is_alnum` + plain string ops.
----
 --- @param args_str string|nil
 --- @return string[]|nil
 local function extract_arg_names(args_str)
@@ -334,9 +332,9 @@ local function extract_arg_names(args_str)
 	for _, tok in ipairs(tokens) do
 		local trimmed = duffle.trim(tok)
 		if trimmed ~= "" then
-			local ident_end = trim_trailer_back(trimmed, #trimmed)
+			local ident_end   = trim_trailer_back(trimmed, #trimmed)
 			local ident_start = trim_ident_back(trimmed, ident_end) + 1
-			local name = trimmed:sub(ident_start, ident_end)
+			local name        = trimmed:sub(ident_start, ident_end)
 			if name ~= "" then names[#names + 1] = name end
 		end
 	end
@@ -379,7 +377,6 @@ 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.
 --
@@ -403,8 +400,8 @@ local function convert_line_comments_to_block(s)
 			while eol <= len and result:byte(eol) ~= BYTE_NEWLINE do
 				eol = eol + 1
 			end
-			local before   = result:sub(1, pos - 1)
-			local comment  = result:sub(pos + 2, eol - 1)  -- skip the `//`
+			local before  = result:sub(1, pos - 1)
+			local comment = result:sub(pos + 2, eol - 1)  -- skip the `//`
 			local after
 			if eol <= len and result:byte(eol) == BYTE_NEWLINE then
 				after = " */" .. result:sub(eol)  -- keep the newline
@@ -422,8 +419,9 @@ 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)
@@ -476,8 +474,7 @@ end
 --- Compute word counts for every component in `components` in a single pass.
 --- The name-lookup table + memoization cache are built ONCE (per source) instead of per-component,
 --- so the cache survives across siblings and a component's recursive `mac_Y(...)` references hit memoized values
---- instead of re-walking the body. Previously each call rebuilt both tables (O(N) tables per call → O(N^2)).
----
+--- instead of re-walking the body.
 --- Cycle detection (A -> B -> A) is preserved via the in-progress `-1` sentinel in `cache`.
 ---
 --- @param components Component[]
@@ -530,7 +527,7 @@ end
 --- @return string
 local function signature_from_args(args_str)
 	local arg_names = extract_arg_names(args_str)
-	if arg_names and #arg_names > 0 then
+	if    arg_names and #arg_names > 0 then
 		return table.concat(arg_names, ", ")
 	end
 	return "..."
@@ -540,7 +537,7 @@ end
 --- The last 2 chars are always that pair.
 local function strip_trailing_continuation(lines)
 	local last = lines[#lines]
-	if last:sub(-2) == " \\" then
+	if    last:sub(-2) == " \\" then
 		lines[#lines] = last:sub(1, -3)
 	end
 end
@@ -627,14 +624,13 @@ end
 -- @return string  -- the output directory
 -- @return string  -- the full output path
 local function compute_macs_h_path(src)
-	local out_dir  = src.dir .. "/" .. GEN_SUBDIR
-	local out_path = out_dir .. "/" .. duffle.basename_no_ext(src.dir) .. ".macs.h"
+	local  out_dir  = src.dir .. "/" .. GEN_SUBDIR
+	local  out_path = out_dir .. "/" .. duffle.basename_no_ext(src.dir) .. ".macs.h"
 	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.
 ---
 --- @param ctx PassCtx
@@ -644,7 +640,6 @@ end
 --- @return string|nil  -- path to the written file (nil if no components)
 local function emit_component_macros_h(ctx, src, components, counts)
 	if #components == 0 then return nil end
-
 	local out_dir, out_path = compute_macs_h_path(src)
 	local lines             = header_boilerplate(src)
 
@@ -655,7 +650,6 @@ local function emit_component_macros_h(ctx, src, components, counts)
 	end
 
 	local content = table.concat(lines, "\n") .. "\n"
-
 	if ctx.dry_run then
 		print(string.format("  -> %s (dry-run)", out_path))
 		return out_path

scripts/passes/offsets.lua

@@ -132,6 +132,14 @@ local function record_offset_marker(branches, args, at_pos)
 	end
 end
 
+-- MARKER_TO_HANDLER — data-driven marker dispatch (the plex pattern).
+-- Maps the marker ident to its recorder function. Each handler takes (out_table, args, at_pos).
+-- Adding a new marker type = 1 row + 1 recorder function.
+local MARKER_TO_HANDLER = {
+	[LABEL_MARKER]  = record_label_marker,
+	[OFFSET_MARKER] = record_offset_marker,
+}
+
 --- 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
@@ -146,13 +154,13 @@ local function scan_for_atom_markers(token, at_pos, labels, branches)
 		local ch = token:sub(pos, pos)
 		if duffle.is_alpha(ch) then
 			local ident, after = duffle.read_ident(token, pos)
-			if ident == LABEL_MARKER then
+			local handler = MARKER_TO_HANDLER[ident]
+			if handler then
 				local args, after_paren = extract_ident_args(token, after)
-				record_label_marker(labels, args, at_pos)
-				pos = after_paren or after
-			elseif ident == OFFSET_MARKER then
-				local args, after_paren = extract_ident_args(token, after)
-				record_offset_marker(branches, args, at_pos)
+				-- Marker found — dispatch to its recorder. markers share labels and branches as
+				-- out-tables; the recorder picks which one(s) to write to based on its semantics.
+				-- (record_label_marker writes to labels; record_offset_marker writes to branches.)
+				handler(ident == LABEL_MARKER and labels or branches, args, at_pos)
 				pos = after_paren or after
 			else
 				pos = after

scripts/passes/report.lua

@@ -261,6 +261,28 @@ local function render_module_warnings_section(add, results, total_warnings)
 	add("")
 end
 
+-- ════════════════════════════════════════════════════════════════════════════
+-- SECTION_RENDERERS — data-driven section dispatch (the plex pattern)
+-- ════════════════════════════════════════════════════════════════════════════
+--
+-- Each entry maps a section to its (header, render_fn). The render_fn signature:
+--   render_fn(add, results, totals)
+--     add    -- the `add(line)` closure from the surrounding report renderer
+--     results -- AnnotationResult[] (per-source results)
+--     totals -- {atoms, annots, binds, macros, errors, warnings} counts
+--
+-- Sections that need to render "(none)" vs iterate use totals.errors / totals.warnings;
+-- other sections ignore the totals arg.
+-- Adding a new section = 1 row here + 1 render_<thing>_section function.
+local SECTION_RENDERERS = {
+	{ header = SECTION_HEADER_ATOMS,    render = render_module_atoms_section     },
+	{ header = SECTION_HEADER_ANNOTS,   render = render_module_annots_section    },
+	{ header = SECTION_HEADER_BINDS,    render = render_module_binds_section     },
+	{ header = SECTION_HEADER_MACROS,   render = render_module_macros_section    },
+	{ header = SECTION_HEADER_ERRORS,   render = function(add, results, totals) return render_module_errors_section(add, results, totals.errors)   end },
+	{ header = SECTION_HEADER_WARNINGS, render = function(add, results, totals) return render_module_warnings_section(add, results, totals.warnings) end },
+}
+
 --- Render the per-MODULE annotation report (one `<dir_basename>.annotations.txt`).
 --- @param dir string                  -- module directory path
 --- @param sources SourceFile[]        -- sources in this module
@@ -282,12 +304,22 @@ local function render_module_report(dir, sources, results)
 		total_atoms, total_annots, total_binds, total_macros))
 	add("")
 
-	render_module_atoms_section(add, results)
-	render_module_annots_section(add, results)
-	render_module_binds_section(add, results)
-	render_module_macros_section(add, results)
-	render_module_errors_section(add, results, total_errors)
-	render_module_warnings_section(add, results, total_warnings)
+	-- Bundle the totals so the section renderers don't need separate parameter lists.
+	-- Errors/warnings sections need their total count to decide "(none)" vs iterate.
+	-- Sections without totals (atoms/annots/binds/macros) ignore this arg.
+	local totals = {
+		atoms    = total_atoms,  annots = total_annots,  binds  = total_binds,
+		macros   = total_macros, errors = total_errors,  warnings = total_warnings,
+	}
+
+	-- THE per-section dispatch. ONE loop over SECTION_RENDERERS. Each renderer writes its
+	-- header + content via the `add` closure (pre-bound above).
+	-- Adding a new section = 1 row here + 1 render_<thing>_section function.
+	for _, section in ipairs(SECTION_RENDERERS) do
+		add(section.header)
+		section.render(add, results, totals)
+		add("")
+	end
 
 	return table.concat(lines, "\n") .. "\n"
 end
@@ -347,7 +379,8 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- (internal) Pull per-source validate() results from the annotation pass's stash.
--- The annotation pass runs first in the dep chain and caches results in `ctx.flags._annot_source_results`; we read from there instead of re-validating each source.
+-- The annotation pass runs first in the dep chain and caches results in `ctx.flags._annot_source_results`;
+-- we read from there instead of re-validating each source.
 -- Returns the list of module results + the flat list of all results (for the project-wide summary).
 -- @param ctx PassCtx
 -- @param dir_sources SourceFile[]

scripts/passes/scan_source.lua

@@ -1,6 +1,6 @@
 --- passes/scan_source.lua — Source pre-scan pass (the "mega entity" pass).
 ---
---- Single source-walk pass that produces the fat `SourceScan` payload consumed by all downstream passes. Walks each `ctx.sources` entry once, 
+--- Single source-walk pass that produces the fat `SourceScan` payload consumed by all downstream passes. Walks each `ctx.sources` entry once,
 --- extracting every construct type the metaprograms need:
 ---
 ---   MipsAtom_              (kind = "atom", with optional atom_info inner)
@@ -14,8 +14,7 @@
 --- This is the first pass in the dep graph (no deps).
 --- Every other pass that reads source structure depends on this one — see `ps1_meta.lua :: PASSES`.
 ---
---- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
---- Lua 5.3 compatible.
+--- **Conventions**: tabs (1/level), EmmyLua annotations, no regex, Lua 5.3 compatible
 
 -- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
@@ -35,7 +34,7 @@ local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 --- @field raw_atoms  AtomEntry[]     -- MipsCode code_<name> { body } (offsets pass only)
 --- @field binds      BindsEntry[]    -- typedef Struct_(Binds_X) { fields } (fields pre-parsed)
 --- @field atom_infos AtomInfoEntry[] -- MipsAtom_(name) atom_info(...) (sub-calls pre-parsed)
---- @field macros     MacroEntry[]    -- #pragma mac_X tape_atom words=N  +  _Pragma("...")
+--- @field macros     MacroEntry[]    -- #pragma mac_X tape_atom words=N  +   _Pragma("...")
 --- @field line_of    fun(pos: integer): integer  -- shared LineIndex closure
 
 --- @class SourceFile
@@ -74,7 +73,7 @@ local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 --- @field comment    string|nil     -- populated by components pass (backward lookup)
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Local helpers
+-- Local helpers (shared by per-form parsers)
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- C qualifier keywords that may precede a MipsAtom_ / MipsCode declaration.
@@ -86,6 +85,22 @@ local QUALIFIER_KEYWORDS = {
 	["internal"] = true, ["LP_"]   = true, ["global"]   = true, ["gkknown"] = true,
 }
 
+-- "ac_" prefix length on component names (e.g., `MipsAtomComp_(ac_X, ...)`). The components pass strips
+-- this prefix to derive the macro name (e.g., `mac_X`). Single source of truth — was duplicated in two
+-- branches of the pre-refactor scan_source.
+local AC_PREFIX     = "ac_"
+local AC_PREFIX_LEN = 3
+
+-- Strip the "ac_" prefix from a component name. Returns the input unchanged if it doesn't start with the prefix.
+-- @param raw_name string
+-- @return string
+local function strip_ac_prefix(raw_name)
+	if #raw_name > AC_PREFIX_LEN and raw_name:sub(1, AC_PREFIX_LEN) == AC_PREFIX then
+		return raw_name:sub(AC_PREFIX_LEN + 1)
+	end
+	return raw_name
+end
+
 -- Parse the U4 fields from a Binds_X body. Returns (fields, byte_count).
 local function scan_binds_fields(body)
 	local fields   = {}
@@ -101,7 +116,7 @@ local function scan_binds_fields(body)
 			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
+				byte_off = byte_off + 0x04    -- U4 field = 4 bytes (= 1 .word)
 			end
 			body_pos = field_end or (type_end + 1)
 		else
@@ -147,13 +162,13 @@ local function scan_atom_info_subcalls(info_inner)
 			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)
+				binds   = duffle.trim(sub_inner)
 				sub_pos = sub_after2
 			else
 				sub_pos = sub_open + 1
 			end
 		elseif sub_ident == "atom_reads" or sub_ident == "atom_writes" then
-			local kind = sub_ident
+			local kind     = sub_ident
 			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)
@@ -181,6 +196,262 @@ local function scan_skip_qualifiers(source, pos)
 	end
 end
 
+-- ════════════════════════════════════════════════════════════════════════════
+-- Per-form parsers (the DECL_PARSERS table's payload)
+-- ════════════════════════════════════════════════════════════════════════════
+--
+-- Each parser has the uniform signature:
+--   parser(source, pos, ident_end, line_of, out) -> new_pos
+-- where:
+--   source    -- the full source text
+--   pos       -- position of the construct's leading ident (e.g., `M` of `MipsAtom_`)
+--   ident_end -- position past the leading ident (where the `(` should be)
+--   line_of   -- closure over LineIndex(source) for 1-based line lookups
+--   out       -- the SourceScan out table (mutated in place: out.atoms / out.raw_atoms / out.binds / out.atom_infos / out.macros)
+--   returns   -- new position after the construct
+--
+-- All parsers read source-as-written via the duffle primitives (skip_ws_and_cmt / read_parens / read_braces / read_balanced).
+-- No regex per the no_regex constraint; no hand-rolled depth tracking (the MipsAtomComp_Proc_ brace matcher
+-- now uses duffle.read_braces instead of bespoke byte-dispatch).
+--
+-- Adding a new construct = 1 row in DECL_PARSERS + 1 parser function. The scan_source() loop never needs editing.
+
+--- Parse: `MipsAtom_(<name>) [atom_info(<binds>, <reads>, <writes>)] { <body> }`
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_mips_atom(source, pos, ident_end, line_of, out)
+	local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
+	if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
+	local inner, after_paren = duffle.read_parens(source, open_paren)
+
+	local raw_name = duffle.read_ident(inner, 1)
+
+	-- Lookahead for atom_info(...) between `)` and `{`. Captures sub-calls; updates brace search start.
+	local brace_search_pos = after_paren
+	local lookahead        = duffle.skip_ws_and_cmt(source, after_paren)
+	local look_ident, look_end = duffle.read_ident(source, lookahead)
+	if look_ident == "atom_info" then
+		local info_open = duffle.skip_ws_and_cmt(source, look_end)
+		if source:sub(info_open, info_open) == "(" then
+			local info_inner, info_after = duffle.read_parens(source, info_open)
+			local ai_binds, ai_reads, ai_writes = scan_atom_info_subcalls(info_inner)
+			out.atom_infos[#out.atom_infos + 1] = {
+				atom_name = raw_name or "?", binds = ai_binds,
+				reads     = ai_reads or {}, writes = ai_writes or {},
+				info_line = line_of(lookahead),
+			}
+			brace_search_pos = info_after
+		end
+	end
+
+	local brace = duffle.scan_to_char(source, "{", brace_search_pos)
+	if not brace then return open_paren + 1 end
+
+	local body, after_brace = duffle.read_braces(source, brace)
+	if raw_name and raw_name ~= "" then
+		out.atoms[#out.atoms + 1] = {
+			line        = line_of(pos), name = raw_name, body = body, body_off = brace + 1,
+			kind        = "atom", raw_name = raw_name,
+			ident_pos   = pos, after_paren = after_paren,
+		}
+	end
+
+	return after_brace
+end
+
+--- Parse: `MipsAtomComp_(<name>) { <body> }`
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_mips_atom_comp(source, pos, ident_end, line_of, out)
+	local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
+	if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
+	local inner, after_paren = duffle.read_parens(source, open_paren)
+
+	local raw_name = duffle.read_ident(inner, 1)
+	if not raw_name then return open_paren + 1 end
+
+	local brace = duffle.scan_to_char(source, "{", after_paren)
+	if not brace then return open_paren + 1 end
+
+	local body, after_brace = duffle.read_braces(source, brace)
+
+	out.atoms[#out.atoms + 1] = {
+		line        = line_of(pos), name = strip_ac_prefix(raw_name), body = body, body_off = brace + 1,
+		kind        = "comp_bare", raw_name = raw_name,
+		ident_pos   = pos, after_paren = after_paren,
+	}
+
+	return after_brace
+end
+
+--- Parse: `MipsAtomComp_Proc_(<name>, { <body> })` — body is inside the LAST `{` in args.
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
+	local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
+	if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
+	local inner, after_paren = duffle.read_parens(source, open_paren)
+
+	-- Find the LAST `{` in inner (the body brace, not any potential embedded braces in expressions).
+	local last_brace_pos = nil
+	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_brace_pos then return after_paren end
+
+	-- Use duffle.read_braces to find the matching close brace.
+	-- Replaces the pre-refactor hand-rolled depth tracker (~25 LOC of `if c == 123 then depth = depth + 1 ...`).
+	-- If close_pos is past the end of inner, the brace didn't match (malformed input); skip.
+	local body, close_pos = duffle.read_braces(inner, last_brace_pos)
+	if close_pos > #inner + 1 then return after_paren end
+
+	local raw_name = inner:match("^%s*([%w_]+)") or "?"
+	-- Position of body[1] in source = open_paren + 1 (start of inner) + last_brace_pos + 1 (past '{').
+	local body_off = open_paren + 2 + last_brace_pos
+
+	out.atoms[#out.atoms + 1] = {
+		line        = line_of(pos), name = strip_ac_prefix(raw_name), body = body, body_off = body_off,
+		kind        = "comp_proc", raw_name = raw_name,
+		ident_pos   = pos, after_paren = after_paren,
+	}
+
+	return after_paren
+end
+
+--- Parse: `MipsCode code_<name> { <body> }` (raw atom form — offsets pass only).
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_mips_code(source, pos, ident_end, line_of, out)
+	local next_pos = duffle.skip_ws_and_cmt(source, ident_end)
+	local next_ident, next_after = duffle.read_ident(source, next_pos)
+	if not next_ident or #next_ident <= 5 or next_ident:sub(1, 5) ~= "code_" then
+		return ident_end
+	end
+
+	local atom_name = next_ident:sub(6)
+	local brace_pos = duffle.scan_to_char(source, "{", next_after)
+	if not brace_pos then return ident_end end
+
+	local body, after_brace = duffle.read_braces(source, brace_pos)
+	out.raw_atoms[#out.raw_atoms + 1] = {
+		line      = line_of(pos), name = atom_name, body = body, body_off = brace_pos + 1,
+		kind      = "raw_atom", raw_name = atom_name,
+	}
+
+	return after_brace
+end
+
+--- Parse: `typedef Struct_(<name>) { <fields> }` — only emits when name starts with `Binds_`.
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_typedef_binds(source, pos, ident_end, line_of, out)
+	local after_typedef = duffle.skip_ws_and_cmt(source, ident_end)
+	local id2, id2_end = duffle.read_ident(source, after_typedef)
+	if id2 ~= "Struct_" then return ident_end end
+
+	local open_paren = duffle.skip_ws_and_cmt(source, id2_end)
+	if source:sub(open_paren, open_paren) ~= "(" then return id2_end end
+
+	local inner, after_paren = duffle.read_parens(source, open_paren)
+	local name = duffle.trim(inner)
+
+	local brace = duffle.scan_to_char(source, "{", after_paren)
+	if not brace then return open_paren + 1 end
+
+	local body, after_brace = duffle.read_braces(source, brace)
+	if name:sub(1, 6) == "Binds_" then
+		local fields, byte_off = scan_binds_fields(body)
+		out.binds[#out.binds + 1] = { line = line_of(pos), name = name, fields = fields, bytes = byte_off }
+	end
+
+	return after_brace
+end
+
+--- Parse: `_Pragma("mac_X tape_atom words=N")` (operator form).
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_pragma_macro(source, pos, ident_end, line_of, out)
+	local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
+	if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
+
+	local str, str_end = duffle.read_parens(source, open_paren)
+	str = duffle.trim(str)
+	if str:sub(1, 1) ~= '"' or str:sub(-1) ~= '"' then return str_end end
+
+	local inner = str:sub(2, -2)
+	local space = duffle.find_byte(inner, 32, 1)
+	if not space then return str_end end
+
+	local name = inner:sub(1, space - 1)
+	local rest = inner:sub(space + 1)
+	local eq = duffle.find_byte(rest, 61, 1)
+	if not eq then return str_end end
+
+	local key = duffle.trim(rest:sub(1, eq - 1))
+	local val = duffle.trim(rest:sub(eq + 1))
+	if key == "tape_atom words" or key == "words" then
+		out.macros[#out.macros + 1] = { line = line_of(pos), name = name, words = tonumber(val) or 0 }
+	end
+
+	return str_end
+end
+
+--- Parse: `pragma` ident (no-op — directive form `#pragma` is handled by `skip_preprocessor_line` upstream).
+--- If we reach this parser it means the directive skip didn't fire, which can happen for non-#-prefixed pragma.
+--- Just advance past the ident.
+--- @param source string
+--- @param pos integer
+--- @param ident_end integer
+--- @param line_of fun(pos: integer): integer
+--- @param out SourceScan
+--- @return integer
+local function parse_pragma_dummy(source, pos, ident_end, line_of, out)
+	return ident_end
+end
+
+-- ════════════════════════════════════════════════════════════════════════════
+-- DECL_PARSERS — data-driven construct dispatch (the plex pattern)
+-- ════════════════════════════════════════════════════════════════════════════
+--
+-- Each entry maps a leading ident to its parser function. The main scan_source() loop is one line of dispatch:
+--   local parser = DECL_PARSERS[ident]; if parser then pos = parser(...) end
+--
+-- Adding a new construct = 1 row here + 1 parser function above.
+
+local DECL_PARSERS = {
+	MipsAtom_          = parse_mips_atom,
+	MipsAtomComp_      = parse_mips_atom_comp,
+	MipsAtomComp_Proc_ = parse_mips_atom_comp_proc,
+	MipsCode           = parse_mips_code,
+	typedef            = parse_typedef_binds,
+	_Pragma            = parse_pragma_macro,
+	pragma             = parse_pragma_dummy,
+}
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- The single source walker
 -- ════════════════════════════════════════════════════════════════════════════
@@ -191,13 +462,16 @@ end
 --- @return table  -- SourceScan { atoms, raw_atoms, binds, atom_infos, macros, line_of }
 local function scan_source(source)
 	local line_of = duffle.LineIndex(source)
-	local atoms       = {}
-	local raw_atoms   = {}
-	local binds       = {}
-	local atom_infos  = {}
-	local macros      = {}
-	local pos         = 1
-	local src_len     = #source
+	local out     = {
+		atoms      = {},
+		raw_atoms  = {},
+		binds      = {},
+		atom_infos = {},
+		macros     = {},
+		line_of    = line_of,
+	}
+	local pos     = 1
+	local src_len = #source
 
 	while pos <= src_len do
 		pos = duffle.skip_ws_and_cmt(source, pos)
@@ -206,250 +480,29 @@ local function scan_source(source)
 		-- Skip preprocessor directives (#define / #include / #pragma / etc).
 		-- _Pragma is an operator (not a directive) — it doesn't start with #.
 		local pp_pos = duffle.skip_preprocessor_line(source, pos)
-		if pp_pos then pos = pp_pos; goto continue end
-
-		-- Skip C qualifiers (static, const, etc.) that may precede a declaration.
-		pos = scan_skip_qualifiers(source, pos)
-		if pos > src_len then break end
-
-		local ident, ident_end = duffle.read_ident(source, pos)
-		-- scan: <ident>
-		if not ident then pos = pos + 1; goto continue end
-
-		-- ── MipsAtom_ / MipsAtomComp_ / MipsAtomComp_Proc_ ──
-		if ident == "MipsAtom_" or ident == "MipsAtomComp_" or ident == "MipsAtomComp_Proc_" then
-			local is_atom = ident == "MipsAtom_"
-			local is_comp = ident == "MipsAtomComp_"
-			local is_proc = ident == "MipsAtomComp_Proc_"
-			local kind = is_atom and "atom" or (is_comp and "comp_bare" or "comp_proc")
-			local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
-			if source:sub(open_paren, open_paren) ~= "(" then pos = open_paren + 1; goto continue end
-
-			local inner, after_paren = duffle.read_parens(source, open_paren)
-			-- scan: <ident>(<args>)
-
-			if is_proc then
-				-- MipsAtomComp_Proc_(name, { body }) — body is inside the LAST { } in args.
-				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 last_brace_pos then
-					local depth = 1
-					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; inner_pos = inner_pos + 1
-						elseif c == 125 then depth = depth - 1; if depth == 0 then break end; inner_pos = inner_pos + 1
-						elseif c == 40 then local _, a = duffle.read_parens(inner, inner_pos); inner_pos = a
-						elseif c == 91 then local _, a = duffle.read_brackets(inner, inner_pos); inner_pos = a
-						elseif c == 34 or c == 39 then inner_pos = duffle.skip_str_or_cmt(inner, inner_pos) + 1
-						else inner_pos = inner_pos + 1 end
-					end
-					if depth == 0 then
-						-- scan: <ident>(<name>, { <body> })
-						local name_match = inner:match("^%s*([%w_]+)")
-						local raw_name = name_match or "?"
-						-- Strip "ac_" prefix for component names (components pass convention).
-						local name = raw_name
-						if #raw_name > 3 and raw_name:sub(1, 3) == "ac_" then
-							name = raw_name:sub(4)
-						end
-						local body = inner:sub(last_brace_pos + 1, inner_pos - 1)
-						local body_off = open_paren + 1 + last_brace_pos
-						atoms[#atoms + 1] = {
-							line = line_of(pos), name = name, body = body, body_off = body_off + 1,
-							kind = kind, raw_name = raw_name,
-							ident_pos = pos, after_paren = after_paren,
-							args = nil, comment = nil,
-						}
-					end
-				end
-				pos = after_paren
-			else
-				-- MipsAtom_(name) { body }  OR  MipsAtomComp_(name) { body }
-				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 raw_name = inner:sub(name_start, name_end - 1)
-				-- scan: <ident>(<name>)
-				if raw_name ~= "" then
-					local brace = duffle.scan_to_char(source, "{", after_paren)
-					-- scan: <ident>(<name>) {
-					if brace then
-						local body, after_brace = duffle.read_braces(source, brace)
-						-- scan: <ident>(<name>) { <body> }
-						-- Strip "ac_" prefix for component names (components pass convention).
-						local disp_name = raw_name
-						if is_comp and #raw_name > 3 and raw_name:sub(1, 3) == "ac_" then
-							disp_name = raw_name:sub(4)
-						end
-						atoms[#atoms + 1] = {
-							line = line_of(pos), name = disp_name, body = body, body_off = brace + 1,
-							kind = kind, raw_name = raw_name,
-							ident_pos = pos, after_paren = after_paren,
-							args = nil, comment = nil,
-						}
-						pos = after_brace
+		if pp_pos then
+			pos = pp_pos
+		else
+			-- Skip C qualifiers (static, const, etc.) that may precede a declaration.
+			pos = scan_skip_qualifiers(source, pos)
+			if pos <= src_len then
+				local ident, ident_end = duffle.read_ident(source, pos)
+				if ident then
+					local parser = DECL_PARSERS[ident]
+					if parser then
+						pos = parser(source, pos, ident_end, line_of, out)
 					else
-						pos = open_paren + 1
+						-- Unrecognized ident — advance past it.
+						pos = ident_end
 					end
 				else
-					pos = open_paren + 1
+					pos = pos + 1
 				end
 			end
-
-			-- For MipsAtom_ entries: check if atom_info(...) follows.
-			if is_atom then
-				local lookahead = duffle.skip_ws_and_cmt(source, after_paren)
-				local look_ident, look_end = duffle.read_ident(source, lookahead)
-				-- scan: MipsAtom_(<name>) <look_ident>
-				if look_ident == "atom_info" then
-					local info_open = duffle.skip_ws_and_cmt(source, look_end)
-					if source:sub(info_open, info_open) == "(" then
-						local info_inner, info_after = duffle.read_parens(source, info_open)
-						-- scan: MipsAtom_(<name>) atom_info(<binds>, <reads>, <writes>)
-						-- Find the atom name from the just-parsed atom entry (last one added).
-						local last_atom = atoms[#atoms]
-						local atom_name = last_atom and last_atom.raw_name or "?"
-						local ai_binds, ai_reads, ai_writes = scan_atom_info_subcalls(info_inner)
-						atom_infos[#atom_infos + 1] = {
-							atom_name = atom_name, binds = ai_binds,
-							reads = ai_reads or {}, writes = ai_writes or {},
-							info_line = line_of(lookahead),
-						}
-						-- Don't advance pos past info_after — the body { ... } still needs to be skipped
-						-- by the brace scan below. But if there's no body (forward decl), advance.
-						local body_brace = duffle.scan_to_char(source, "{", info_after)
-						if body_brace then
-							local _, after_body = duffle.read_braces(source, body_brace)
-							pos = after_body
-						else
-							pos = info_after
-						end
-					end
-				end
-			end
-			goto continue
 		end
-
-		-- ── MipsCode code_<name> { body } (raw atom form — offsets pass only) ──
-		if ident == "MipsCode" then
-			local next_pos = duffle.skip_ws_and_cmt(source, ident_end)
-			local next_ident, next_after = duffle.read_ident(source, next_pos)
-			-- scan: MipsCode <next_ident>
-			if next_ident and #next_ident > 5 and next_ident:sub(1, 5) == "code_" then
-				local atom_name = next_ident:sub(6)
-				-- scan: MipsCode code_<name>
-				local brace_pos = duffle.scan_to_char(source, "{", next_after)
-				-- scan: MipsCode code_<name> {
-				if brace_pos then
-					local body, after_brace = duffle.read_braces(source, brace_pos)
-					-- scan: MipsCode code_<name> { <body> }
-					raw_atoms[#raw_atoms + 1] = {
-						line = line_of(pos), name = atom_name, body = body, body_off = brace_pos + 1,
-						kind = "raw_atom", raw_name = atom_name,
-					}
-					pos = after_brace
-					goto continue
-				end
-			end
-			pos = ident_end
-			goto continue
-		end
-
-		-- ── typedef Struct_(Binds_X) { fields } ──
-		if ident == "typedef" then
-			local after_typedef = duffle.skip_ws_and_cmt(source, ident_end)
-			local id2, id2_end = duffle.read_ident(source, after_typedef)
-			-- scan: typedef <id2>
-			if id2 == "Struct_" then
-				local open_paren = duffle.skip_ws_and_cmt(source, id2_end)
-				if source:sub(open_paren, open_paren) == "(" then
-					local inner, after_paren = duffle.read_parens(source, open_paren)
-					-- scan: typedef Struct_(<name>)
-					local name = duffle.trim(inner)
-					local brace = duffle.scan_to_char(source, "{", after_paren)
-					-- scan: typedef Struct_(<name>) {
-					if brace then
-						local body, after_brace = duffle.read_braces(source, brace)
-						-- scan: typedef Struct_(<name>) { <fields> }
-						if name:sub(1, 6) == "Binds_" then
-							local fields, byte_off = scan_binds_fields(body)
-							binds[#binds + 1] = { line = line_of(pos), name = name, fields = fields, bytes = byte_off }
-						end
-						pos = after_brace
-						goto continue
-					end
-					pos = open_paren + 1
-					goto continue
-				end
-				pos = id2_end or (after_typedef + 1)
-				goto continue
-			end
-			pos = ident_end
-			goto continue
-		end
-
-		-- ── _Pragma("mac_X tape_atom words=N") (operator form) ──
-		if ident == "_Pragma" then
-			local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
-			if source:sub(open_paren, open_paren) == "(" then
-				local str, str_end = duffle.read_parens(source, open_paren)
-				-- scan: _Pragma(<string>)
-				str = duffle.trim(str)
-				if str:sub(1, 1) == '"' and str:sub(-1) == '"' then
-					local inner = str:sub(2, -2)
-					local space = duffle.find_byte(inner, 32, 1)
-					if space then
-						local name = inner:sub(1, space - 1)
-						local rest = inner:sub(space + 1)
-						local eq = duffle.find_byte(rest, 61, 1)
-						if eq then
-							local key = duffle.trim(rest:sub(1, eq - 1))
-							local val = duffle.trim(rest:sub(eq + 1))
-							if key == "tape_atom words" or key == "words" then
-								macros[#macros + 1] = { line = line_of(pos), name = name, words = tonumber(val) or 0 }
-							end
-						end
-					end
-				end
-				pos = str_end
-				goto continue
-			end
-			pos = open_paren + 1
-			goto continue
-		end
-
-		-- ── #pragma mac_X tape_atom words=N (directive form) ──
-		-- (preprocessor skip above handles # lines, but pragma is an ident here
-		--  only if it appeared without a leading # — which happens when the
-		--  preprocessor skip didn't fire because the # was on a previous line.
-		--  The annotation pass handles this via its own skip_preprocessor_line,
-		--  but scan_source handles it here by checking the ident.)
-		if ident == "pragma" then
-			-- This shouldn't normally fire — #pragma lines are skipped by
-			-- skip_preprocessor_line above. If we get here, it's a _Pragma
-			-- variant or a non-#-prefixed pragma. Just advance.
-			pos = ident_end
-			goto continue
-		end
-
-		-- ── Unrecognized ident — advance past it ──
-		pos = ident_end
-
-		::continue::
 	end
 
-	return {
-		atoms      = atoms,
-		raw_atoms  = raw_atoms,
-		binds      = binds,
-		atom_infos = atom_infos,
-		macros     = macros,
-		line_of    = line_of,
-	}
+	return out
 end
 
 -- ════════════════════════════════════════════════════════════════════════════

scripts/passes/static_analysis.lua

@@ -14,7 +14,7 @@
 ---   `["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 `lua.md` in the ps1-ai styleguides.
+--- **Conventions**: tabs (1/level), EmmyLua annotations, no regex, Lua 5.3 compatible.
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
@@ -114,25 +114,6 @@ local OUTPUT_EXTENSION = ".static_analysis.txt"
 --- @field findings   Finding[]   -- findings for this atom
 --- @field total_cycles integer   -- sum of token cycle costs
 
--- ════════════════════════════════════════════════════════════════════════════
--- Source scanning — delegated to duffle.scan_source (ps1_meta.lua pre-scans)
--- ════════════════════════════════════════════════════════════════════════════
---
--- The orchestrator calls duffle.scan_source once per source and stashes the fat SourceScan in src.scan.
--- validate() below reads from src.scan — no source walking in this pass.
-
--- ════════════════════════════════════════════════════════════════════════════
--- Body tokenizer (top-level comma splitter + per-token classification)
--- ════════════════════════════════════════════════════════════════════════════
-
---- Build a map: `body_relative_char_offset` -> `body_relative_line`.
---- Used by the checks to convert per-token offsets in the body to lina numbers relative to the start of `body`. 
---- The atom's source-line of the body-start is added by the caller.
----
--- NOTE: `tokenize_body` and `build_body_line_index` moved to `duffle.lua` as shared
--- memoized utilities (`duffle.tokenize_body`, `duffle.build_body_line_index`).
--- The local copies were deleted; all callers now use the duffle versions.
-
 -- ════════════════════════════════════════════════════════════════════════════
 -- classify_tokens — per-token classification (the plex's pre-computed data layer)
 -- ════════════════════════════════════════════════════════════════════════════
@@ -156,16 +137,30 @@ local OUTPUT_EXTENSION = ".static_analysis.txt"
 -- Checks that need "how many nops before token i" use `tok_class.nop_prefix` instead of walking backwards.
 
 --- @class TokClass
---- @field ident        string          -- leading identifier
---- @field nop_words    integer         -- 0/1/2
---- @field nop_prefix   integer         -- consecutive nop words before this token
---- @field is_yield     boolean
---- @field is_atom_label boolean
---- @field label_name   string|nil      -- for atom_label(name)
---- @field is_branch    boolean
---- @field branch_label string|false|nil -- for branch_*(..., atom_offset(F, label))
---- @field is_load_word boolean
---- @field is_store_word boolean
+--- @field ident              string          -- leading identifier
+--- @field nop_words          integer         -- 0/1/2
+--- @field nop_prefix         integer         -- consecutive nop words before this token
+--- @field is_yield           boolean
+--- @field is_atom_label      boolean
+--- @field label_name         string|nil      -- for atom_label(name)
+--- @field is_branch          boolean
+--- @field branch_label       string|false|nil -- for branch_*(..., atom_offset(F, label))
+--- @field is_load_word       boolean
+--- @field is_store_word      boolean
+--- @field mac_format_shape   string|nil      -- "f3" / "g4" etc. for mac_format_X_color; nil otherwise
+--- @field is_gte_store       boolean         -- ident matches `mac_gte_store_<shape>`
+--- @field is_ot_tag          boolean         -- ident matches `mac_insert_ot_tag_<shape>`
+--- @field writes_r_prim_cursor boolean       -- store_word targeting R_PrimCursor
+--- @field reads_r_tape_ptr   boolean         -- any token referencing R_TapePtr
+--- @field o_arg1             string|nil      -- first arg of O_(<a>, <b>) captures; nil for non-O_ tokens
+--- @field o_arg2             string|nil      -- second arg of O_(<a>, <b>) captures
+--- @field s_arg1             string|nil      -- arg of S_(<a>) captures; nil for non-S_ tokens
+
+-- Patterns for O_(<arg1>, <arg2>) and S_(<arg>) captures. UNANCHORED — the substring can appear
+-- anywhere in the token (e.g., `load_word(R_T0, R_TapePtr, O_(Binds_X, field))` matches at position ~24).
+-- The binds_name match is deferred to check_abi_handoff (which compares tc.o_arg1 == atom.info.binds).
+local O_PATTERN = "O_%(([%w_]+),%s*([%w_]+)%s*%)"
+local S_PATTERN = "S_%(([%w_]+)%s*%)"
 
 local function classify_tokens(tokens)
 	local n       = #tokens
@@ -186,6 +181,16 @@ local function classify_tokens(tokens)
 		local is_load_word  = ident == "load_word"
 		local is_store_word = ident == "store_word"
 
+		-- Per-check pre-computes (R3 lift). Each pre-compute eliminates one per-token regex/string-find
+		-- call from check_abi_handoff / check_gpu_portstore_shape.
+		local mac_format_shape   = nil
+		local is_gte_store        = false
+		local is_ot_tag           = false
+		local writes_r_prim_cursor = false
+		local reads_r_tape_ptr   = false
+		local o_arg1, o_arg2      = nil, nil
+		local s_arg1              = nil
+
 		if ident == "atom_label" then
 			is_atom_label = true
 			label_name    = tok:match("^atom_label%s*%(%s*([%w_]+)%s*%)")
@@ -194,17 +199,40 @@ local function classify_tokens(tokens)
 			branch_label = tok:match("atom_offset%s*%([^,]+,%s*([%w_]+)%s*%)") or false
 		end
 
+		-- mac_format_X_color / mac_gte_store_<shape> / mac_insert_ot_tag_<shape> (used by check_gpu_portstore_shape).
+		local shape = ident:match("^mac_format_([%w_]+)_color$")
+		if shape then mac_format_shape = shape end
+		if ident:match("^mac_gte_store_[%w_]+$")  then is_gte_store = true end
+		if ident:match("^mac_insert_ot_tag_[%w_]+$") then is_ot_tag    = true end
+
+		-- O_(<arg1>, <arg2>) / S_(<arg>) captures (used by check_abi_handoff).
+		-- Cheap pattern match — anchored, fails fast on non-matching tokens.
+		o_arg1, o_arg2 = tok:match(O_PATTERN)
+		if not o_arg1 then s_arg1 = tok:match(S_PATTERN) end
+
+		-- R_TapePtr + R_PrimCursor references (used by check_abi_handoff / check_gpu_portstore_shape).
+		if tok:find("R_TapePtr", 1, true) then reads_r_tape_ptr = true end
+		if is_store_word and tok:find("R_PrimCursor", 1, true) then writes_r_prim_cursor = true end
+
 		tc[tok_idx] = {
-			ident         = ident,
-			nop_words     = nop_words,
-			nop_prefix    = nop_run,
-			is_yield      = is_yield,
-			is_atom_label = is_atom_label,
-			label_name    = label_name,
-			is_branch     = is_branch,
-			branch_label  = branch_label,
-			is_load_word  = is_load_word,
-			is_store_word = is_store_word,
+			ident                = ident,
+			nop_words            = nop_words,
+			nop_prefix           = nop_run,
+			is_yield             = is_yield,
+			is_atom_label        = is_atom_label,
+			label_name           = label_name,
+			is_branch            = is_branch,
+			branch_label         = branch_label,
+			is_load_word         = is_load_word,
+			is_store_word        = is_store_word,
+			mac_format_shape     = mac_format_shape,
+			is_gte_store         = is_gte_store,
+			is_ot_tag            = is_ot_tag,
+			writes_r_prim_cursor = writes_r_prim_cursor,
+			reads_r_tape_ptr     = reads_r_tape_ptr,
+			o_arg1               = o_arg1,
+			o_arg2               = o_arg2,
+			s_arg1               = s_arg1,
 		}
 		-- Advance the nop run for the NEXT token.
 		if nop_words > 0 then
@@ -406,29 +434,28 @@ local function check_abi_handoff(atom, pipe_ctx, findings)
 	local tc             = atom.paths.tok_class
 	local found_field_set = {}
 	local found_advance   = false
-	local bind_re         = "O_%(" .. binds_name .. ",%s*([%w_]+)%s*%)"
-	for tok_idx, t in ipairs(tokens) do
-		local tok = t.tok
-		if tc[tok_idx].is_load_word 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_set[field] = true
-				else
-					local body_line = atom.line + line_in_body[t.rel]
-					findings[#findings + 1] = {
-						atom  = atom.name, line = body_line,
-						check = "abi_handoff", kind = "error",
-						msg   = string.format("%s at line %d has load_word(R_TapePtr, O_(%s, <non-ident>)); expected O_(%s, <field>)",
-							atom.name, body_line, binds_name, binds_name),
-					}
-				end
+
+	-- Reads from tc_entry fields pre-computed by classify_tokens (R3 lift). Eliminates 3 per-token
+	-- string-find/match calls (R_TapePtr + O_(binds_name,...) + bind_re) → 3 O(1) field reads.
+	for tok_idx = 1, #tokens do
+		local tc_entry = tc[tok_idx]
+		-- scan: load_word(R_*, R_TapePtr, O_(<Binds_X>, <field>))
+		if tc_entry.is_load_word and tc_entry.reads_r_tape_ptr and tc_entry.o_arg1 == binds_name then
+			local field = tc_entry.o_arg2
+			if field then
+				found_field_set[field] = true
+			else
+				local body_line = atom.line + line_in_body[tokens[tok_idx].rel]
+				findings[#findings + 1] = {
+					atom  = atom.name, line = body_line,
+					check = "abi_handoff", kind = "error",
+					msg   = string.format("%s at line %d has load_word(R_TapePtr, O_(%s, <non-ident>)); expected O_(%s, <field>)",
+						atom.name, body_line, binds_name, binds_name),
+				}
 			end
 		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>))
+		-- scan: add_ui_self(R_TapePtr, S_(<Binds_X>))
+		if tc_entry.reads_r_tape_ptr and tc_entry.s_arg1 == binds_name then
 			found_advance = true
 		end
 	end
@@ -449,7 +476,7 @@ local function check_abi_handoff(atom, pipe_ctx, findings)
 			atom  = atom.name, line = atom.line,
 			check = "abi_handoff", kind = "error",
 			msg   = string.format("%s at line %d binds %s but never advances R_TapePtr by S_(%s) (= %d bytes / %d words)",
-				atom.name, atom.line, binds_name, binds_name, binds.bytes, binds.bytes / 4),
+				atom.name, atom.line, binds_name, binds_name, binds.bytes, binds.bytes / 0x04),
 		}
 	end
 end
@@ -468,7 +495,6 @@ end
 ---   - Atoms containing a `mac_<name>(...)` call whose name is not in duffle.GP0_MACRO_CONTRIB emit a "new macro; update duffle.GP0_MACRO_CONTRIB" advisory.
 ---
 --- Applies only to `kind = "atom"` (baked atoms). Components don't emit full primitives.
---- Stage 2: signature uniformized to `(atom, pipe_ctx, findings)` — pipe_ctx is ignored here.
 local function check_gpu_portstore_shape(atom, pipe_ctx, findings)
 	if atom.kind ~= "atom" then return end
 	local tokens = atom.paths.tokens
@@ -479,31 +505,30 @@ local function check_gpu_portstore_shape(atom, pipe_ctx, findings)
 	local contrib = 0
 	local saw_format = false
 	local saw_prim_write = false
-	for tok_idx, t in ipairs(tokens) do
-		local tok = t.tok
-		local ident = tc[tok_idx].ident
-		-- Match `mac_format_<shape>_color(...)` and strip `_color`
-		-- to get the bare shape suffix (f3 / g4 / etc).
-		local shape = ident:match("^mac_format_([%w_]+)_color$")
+
+	-- Reads from tc_entry fields pre-computed by classify_tokens (R3 lift). Eliminates 4 per-token
+	-- string matches (mac_format_X_color + mac_gte_store_<shape> + mac_insert_ot_tag_<shape> + R_PrimCursor)
+	for tok_idx = 1, #tokens do
+		local tc_entry = tc[tok_idx]
+		local shape = tc_entry.mac_format_shape
 		if shape and duffle.GP0_CMD_BY_SHAPE[shape] then
 			if not cmd_byte then
 				cmd_byte = duffle.GP0_CMD_BY_SHAPE[shape]
-				cmd_line = atom.line + line_in_body[t.rel]
+				cmd_line = atom.line + line_in_body[tokens[tok_idx].rel]
 			end
 			saw_format = true
-			local contrib_key = "mac_format_" .. shape .. "_color"
-			local n = duffle.GP0_MACRO_CONTRIB[contrib_key]
+			local n = duffle.GP0_MACRO_CONTRIB["mac_format_" .. shape .. "_color"]
 			if    n then contrib = contrib + n end
 		end
-		if ident:match("^mac_gte_store_[%w_]+$") then
-			local n = duffle.GP0_MACRO_CONTRIB[ident]
+		if tc_entry.is_gte_store then
+			local n = duffle.GP0_MACRO_CONTRIB[tc_entry.ident]
 			if    n then contrib = contrib + n end
 		end
-		if ident:match("^mac_insert_ot_tag_[%w_]+$") then
-			local n = duffle.GP0_MACRO_CONTRIB[ident]
+		if tc_entry.is_ot_tag then
+			local n = duffle.GP0_MACRO_CONTRIB[tc_entry.ident]
 			if    n then contrib = contrib + n end
 		end
-		if tc[tok_idx].is_store_word and tok:find("R_PrimCursor", 1, true) then
+		if tc_entry.writes_r_prim_cursor then
 			saw_prim_write = true
 		end
 	end
@@ -536,10 +561,6 @@ end
 -- Check #5: per-atom cycle budget (uses analyze_atom_paths's unknown_macros)
 -- ════════════════════════════════════════════════════════════════════════════
 
--- NOTE: `token_cycles`, `find_atom_labels`, `find_branch_targets` were removed
--- when `classify_tokens` (the pre-computed per-token classification) replaced them.
--- The classification lives on `atom.paths.tok_class`; analyze_atom_paths reads it.
-
 --- Walk all paths through an atom body and return per-path cycle sums.
 --- Builds a tiny CFG: each token has a "next" pointer; branches have two (fall-through + taken).
 --- The BD-slot nop after a branch is absorbed into the branch's cost (MIPS-accurate: BD slot always runs), 

scripts/passes/word_count_eval.lua

@@ -28,17 +28,13 @@ local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Windows separator chars — used to convert `dir` output (which uses `\`) into POSIX paths (which our scripts expect).
+-- Windows separator char — used by `fname:match` to recognize `.macs.h` files.
 local PATH_SEP_BACKSLASH = "\\"
-local PATH_SEP_FORWARD   = "/"
 
--- Fallback glob command (subprocess). Used when `lfs` (LuaFileSystem) is not available.
--- Scoped to `code\` to avoid walking `.git/`, `toolchain/`, `build/`, etc.
-local DIR_GLOB_CMD = 'dir /b /s "%s\\code\\%s" 2>nul'
-
--- Try to load lfs (LuaFileSystem). If available, scan_dir uses native directory enumeration (~2ms)
--- instead of spawning `dir /b /s` as a subprocess (~56ms). Built by update_deps.ps1 into toolchain/lfs/lfs.dll.
-local lfs = pcall(require, "lfs") and require("lfs") or nil
+-- Required native extension: lfs (LuaFileSystem). Built by `update_deps.ps1` to
+-- `toolchain/lfs/lfs.dll` and wired into package.cpath by `scripts/duffle_paths.lua`.
+-- If lfs is missing, `require` throws — fail loud per the build-tool convention.
+local lfs = require("lfs")
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
@@ -106,26 +102,20 @@ 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.
 ---
 --- 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.
+--- Native walk via lfs.attributes + lfs.dir: ~2ms vs ~56ms for the prior `dir /b /s` subprocess.
 ---
 --- @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.
+-- Cache the scan_dir result per (dir, suffix) in package.loaded.
 -- 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__"
 
 --- Scan `code/` for files matching `suffix` (e.g. `*.macs.h`).
---- Uses `lfs` (LuaFileSystem) when available — native directory enumeration at ~2ms.
---- Falls back to `dir /b /s` subprocess (~56ms) when `lfs` is not compiled.
+--- Native directory enumeration via lfs (~2ms). Zero subprocess spawns.
 ---
 --- @param dir string        -- project root directory
 --- @param suffix string     -- file pattern, e.g. "*.macs.h"
@@ -137,33 +127,20 @@ function M.scan_dir(dir, suffix)
 	if    cache and cache[key] then return cache[key] end
 
 	local results = {}
-
-	if lfs then
-		-- Native walk: list code/<module>/gen/ for matching files. Zero subprocess spawns.
-		local code_dir = dir .. "/code"
-		if lfs.attributes(code_dir, "mode") == "directory" then
-			for mod_name in lfs.dir(code_dir) do
-				if mod_name ~= "." and mod_name ~= ".." then
-					local gen_path = code_dir .. "/" .. mod_name .. "/gen"
-					if lfs.attributes(gen_path, "mode") == "directory" then
-						for fname in lfs.dir(gen_path) do
-							if fname:match("%.macs%.h$") then
-								results[#results + 1] = gen_path .. "/" .. fname
-							end
+	local code_dir = dir .. "/code"
+	if lfs.attributes(code_dir, "mode") == "directory" then
+		for mod_name in lfs.dir(code_dir) do
+			if mod_name ~= "." and mod_name ~= ".." then
+				local gen_path = code_dir .. "/" .. mod_name .. "/gen"
+				if lfs.attributes(gen_path, "mode") == "directory" then
+					for fname in lfs.dir(gen_path) do
+						if fname:match("%.macs%.h$") then
+							results[#results + 1] = gen_path .. "/" .. fname
 						end
 					end
 				end
 			end
 		end
-	else
-		-- Fallback: single `dir /b /s` subprocess scoped to code\.
-		local pipe = io.popen(DIR_GLOB_CMD:format(dir, suffix))
-		if pipe then
-			for raw_line in pipe:lines() do
-				results[#results + 1] = raw_line:gsub(PATH_SEP_BACKSLASH, PATH_SEP_FORWARD)
-			end
-			pipe:close()
-		end
 	end
 
 	-- Cache the result (including empty results).

scripts/pcsx_debug_helper/autoexec.lua

@@ -0,0 +1,55 @@
+-- autoexec.lua - pcsx_debug_helper plugin entry point.
+-- Packaged in scripts/pcsx_debug_helper.zip. Loaded by pcsx-redux via
+-- the -archive CLI flag (see scripts/launch_pcsx_debug.ps1).
+--
+-- Registers two web handlers for external CLI tools:
+--   /api/v1/lua/gte - full GTE state (32 data + 32 control regs + PC)
+--   /api/v1/lua/gp  - GP state summary (screenshot endpoint + VRAM endpoint refs)
+--
+-- The GTE handler reads COP2 regs via PCSX.getRegisters().CP2D/CP2C. The
+-- pcsx-redux gdb stub doesn't expose COP2, so this is the only way for
+-- external tools to see GTE state.
+--
+-- The GP handler is a thin pointer: pcsx-redux's Lua API exposes only PCSX.GPU.takeScreenShot()
+-- (no GPUSTAT, no GP0/GP1 command log, no display state). For richer GP state, the existing web endpoints are the practical path:
+--   /api/v1/state/still      - PNG screenshot
+--   /api/v1/gpu/vram/raw     - VRAM raw bytes (1MB)
+--
+-- Companion: scripts/gdb/gdb_tape_atoms.gdb (covers GPRs + atom-aware stepping).
+
+local function register_handlers()
+    if not PCSX.WebServer then PCSX.WebServer = {} end
+    if not PCSX.WebServer.Handlers then PCSX.WebServer.Handlers = {} end
+
+    -- ── GTE state ──
+    PCSX.WebServer.Handlers.gte = function(req)
+        local r = PCSX.getRegisters()
+        local out = { "pc=0x" .. string.format("%x", r.pc) }
+        for i = 0, 31 do
+            out[#out + 1] = string.format("D[%d]=0x%08x C[%d]=0x%08x",
+                i, r.CP2D.r[i], i, r.CP2C.r[i])
+        end
+        return table.concat(out, "\n")
+    end
+
+		-- ── GP state (pointer to existing endpoints) ──
+		-- pcsx-redux's Lua GPU API exposes only takeScreenShot(); no GPUSTAT / GP0 / GP1 command log / display state.
+		-- We point to the existing web endpoints that DO expose those (when the emulator is actually rendering. Paused-at-BP frames won't have a fresh frame).
+    PCSX.WebServer.Handlers.gp = function(req)
+        local out = {
+            "gpu_screenshot_png=http://localhost:8080/api/v1/state/still",
+            "vram_raw=http://localhost:8080/api/v1/gpu/vram/raw (1MB VRAM)",
+            "gpustat=NOT_AVAILABLE_VIA_LUA",
+            "gp_command_log=NOT_AVAILABLE_VIA_LUA (use pcsx-redux Debug > GPU Logger)",
+            "hint_run_emulator_unpaused_for_screenshot",
+        }
+        return table.concat(out, "\n")
+    end
+end
+
+local ok, err = pcall(register_handlers)
+if ok then
+    print("[pcsx_debug_helper] handlers registered: gte, gp")
+else
+    print("[pcsx_debug_helper] registration failed: " .. tostring(err))
+end

scripts/ps1_meta.lua

@@ -148,6 +148,28 @@ local PASSES = {
 		desc   = "[FUTURE] GTE pipeline-fill, mac_yield uniformity, etc.",
 		out    = { { kind = "report", path_template = "<out_root>/<basename>.static_analysis.txt" } },
 	},
+	["atoms-source-map"] = {
+		module = "passes.atoms_source_map",
+		kind   = "header-output",
+		deps   = {"word-counts", "components"},
+		desc   = "Emit gen/<basename>.atoms.sourcemap.txt (per-.word C source line map for gdb debugging)",
+		out    = { { kind = "header", path_template = "<source_dir>/gen/<basename>.atoms.sourcemap.txt" } },
+	},
+	["dwarf-injection"] = {
+		module = "passes.dwarf_injection",
+		kind   = "shared",
+		deps   = {"scan-source", "atoms-source-map"},
+		desc   = "Inject per-atom .debug_line + .debug_aranges (F') + per-atom .debug_info subprogram + per-wave-context-reg .debug_info variables (G') into the ELF (post-link; writes 7 section .bin blobs for objcopy splice). (rbind composite) reads ctx.sources[i].scan to find atom_bind(Binds_X) atoms + their Binds_X struct fields; emits per-Binds_X DW_TAG_structure_type DIEs + per-rbind-atom DW_TAG_variable 'bind_args' DIEs with piece-chain DW_OP_bregN/DW_OP_piece location expressions.",
+		out    = {
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_line.bin"     },
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_aranges.bin"  },
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_rnglists.bin" },
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_abbrev.bin"   },
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_info.bin"     },
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_str.bin"      },
+			{ kind = "report", path_template = "<out_root>/<basename>.dwarf_loc.bin"      },
+		},
+	},
 	report = {
 		module = "passes.report",
 		kind   = "report",
@@ -167,19 +189,21 @@ local PASS_KIND_STOP_ON_ERROR = {
 
 -- Closed set of CLI flags -> pass names.
 local PASS_FLAG_TO_NAME = {
-	["--word-counts"]     = "word-counts",
-	["--components"]      = "components",
-	["--validate"]        = "annotation",
-	["--offsets"]         = "offsets",
-	["--static-analysis"] = "static-analysis",
-	["--report"]          = "report",
-	["--scan-source"]     = "scan-source",
-	["--all"]             = ALL_PASSES_SENTINEL,
+	["--word-counts"]       = "word-counts",
+	["--components"]        = "components",
+	["--validate"]          = "annotation",
+	["--offsets"]           = "offsets",
+	["--static-analysis"]   = "static-analysis",
+	["--atoms-source-map"]  = "atoms-source-map",
+	["--dwarf-injection"]   = "dwarf-injection",
+	["--report"]            = "report",
+	["--scan-source"]       = "scan-source",
+	["--all"]               = ALL_PASSES_SENTINEL,
 }
 
 local ALL_PASS_NAMES = {
 	"scan-source", "word-counts", "components", "annotation",
-	"offsets", "static-analysis", "report",
+	"offsets", "static-analysis", "atoms-source-map", "dwarf-injection", "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.
@@ -191,8 +215,8 @@ local function request_all_passes(args)
 end
 
 -- 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.
+-- 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 = {}
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -212,6 +236,8 @@ PASS_FLAGS (pick one or more, or use --all):
   --components          Generate <module>/gen/<basename>.macs.h
   --validate            Run atom annotation DSL validation
   --offsets             Generate <module>/gen/<basename>.offsets.h
+  --atoms-source-map    Generate <basename>.atoms.sourcemap.txt per source
+  --dwarf-injection     Inject per-atom .debug_line + .debug_aranges (post-link, requires --elf)
   --static-analysis     [FUTURE] GTE pipeline-fill, mac_yield uniformity
   --report              Render per-project summary
   --all                 Equivalent to all 6 flags above (default)
@@ -221,6 +247,9 @@ COMMON_FLAGS:
   --metadata PATH       Path to metadata.h (required)
   --out-root DIR        Output root for reports (default: build/gen)
   --project-root DIR    Project root for .macs.h scan (default: dirname(metadata))
+  --gdb-runtime         Also emit <out_root>/gdb_tape_atoms_runtime.gdb (post-link, requires --elf)
+  --dwarf-injection     Opt in to DWARF injection (writes <basename>.dwarf_*.bin blobs for objcopy splice; requires --elf)
+  --elf PATH            Path to linked .elf (for --gdb-runtime / --dwarf-injection)
   --dry-run             Print dep order + ASCII graph; exit 0 without running
   --verbose             Print per-pass debug output
   --help                Show this help and exit
@@ -253,6 +282,20 @@ FLAG_HANDLERS["--metadata"]     = function(args, argv, arg_idx) args.metadata
 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
 
+-- Per-pass stash flags. Read by `passes/atoms_source_map.lua` to opt into the
+-- post-link gdb-runtime emission. Same shape as the existing per-flag handlers:
+-- mutates `args.flags` (which propagates into `ctx.flags`).
+FLAG_HANDLERS["--gdb-runtime"]  = function(args) args.flags                       = args.flags or {}; args.flags.gdb_runtime = true end
+FLAG_HANDLERS["--elf"]          = function(args, argv, arg_idx) args.flags       = args.flags or {}; args.flags.elf_path  = argv[arg_idx + 1]; return arg_idx + 1 end
+-- F' track: enable DWARF injection (default OFF; opt-in via .vscode/launch.json or ps1_meta CLI).
+FLAG_HANDLERS["--dwarf-injection"] = function(args)
+	args.flags = args.flags or {}
+	args.flags.dwarf_injection = true
+	args.requested_set[#args.requested_set + 1] = "dwarf-injection"
+end
+
+-- G' (atom locals) is now consolidated into --dwarf-injection; no separate flag.
+
 -- 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]
@@ -344,9 +387,8 @@ local function build_ctx(args)
 			dir = dir:sub(1, -2)
 		end
 
-		-- src.scan is populated by the "scan-source" pass (the first pass in the
-		-- dep graph). build_ctx just opens + reads the files; the scan itself
-		-- happens in the pass module, not inline in the orchestrator.
+		-- src.scan is populated by the "scan-source" pass (the first pass in the dep graph).
+		-- build_ctx just opens + reads the files; the scan itself happens in the pass module, not inline in the orchestrator.
 		sources[#sources + 1] = {
 			path     = path,
 			text     = text,
@@ -368,7 +410,7 @@ local function build_ctx(args)
 		upstream      = {},
 		out_root      = args.out_root,
 		project_root  = args.project_root,
-		flags         = {},
+		flags         = args.flags or {},
 		dry_run       = args.dry_run,
 		verbose       = args.verbose,
 	}
@@ -486,9 +528,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 emspty 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
@@ -565,8 +607,8 @@ local function render_dep_graph(passes, requested, closed)
 	add("   |<base>.macs.h |   |<base>.errors |   |<base>.offsets|   |<base>.static  |")
 	add("   |   (header)   |   |  .h          |   |  .h          |   |  _analysis    |")
 	add("   +------+-------+   |  +annot.txt  |   |  (header)    |   |  .txt         |")
-	add("          |           +------+-------+   +--------------+   +------+--------+")
-	add("          v                v                                       v")
+	add("          |           +--+-----------+   +--------------+   +------+--------+")
+	add("          v              v                                         v")
 	add("   +------+----------------+  +------+-------+                     |")
 	add("   |offsets|static-analysis|  |report|       |<--------------------+")
 	add("   |       |               |  +------+-------+")