offset corections (dwarf)

scripts/build_psyq.ps1

@@ -321,7 +321,7 @@ 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 = @('--pre-link'),
 		[string[]]$extra_args = @()
 	)
 	$script = join-path $path_scripts 'ps1_meta.lua'
@@ -379,123 +379,78 @@ function build-gte_hello {
 	$link_args += $f_debug
 	# $link_args += $f_optimize_size
 	$link_modules = @(
-		$module_asm_crt, 
+		$module_asm_crt,
 		$module_c
 	)
 	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.
+	# Post-link: gdb-runtime + dwarf-injection in a single Lua invocation (one luajit cold start).
 	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') `
+		-passes @('--post-link') `
 		-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)) 
+	# F' + G' splice: collapse 9 objcopy subprocess invocations into 3.
+	# - 1 call: 3x --update-section for F' (line / aranges / rnglists)
+	# - 1 call: 3x --update-section for G' (info / abbrev / str)
+	# - 1 call: 2x --add-section for G' (loc / loclists — these don't exist in the source ELF)
+	# - 1 call: 1x --set-section-flags (.rodata / .data enable code flag)
+	# = 4 objcopy calls (was 9; saved 5 spawns).
+	$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"
-			}
-		}
-	}
+		Copy-Item -LiteralPath $elf -Destination $injectElf -Force
 
-	# 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'
-	$dwarfLoclistsBin  = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_loclists.bin'
-	if ((Test-Path $dwarfInfoBin) -and (Test-Path $dwarfAbbrevBin) -and (Test-Path $dwarfStrBin) -and (Test-Path $dwarfLocBin) -and (Test-Path $dwarfLoclistsBin))
-	{
-		Write-Host "[build] G' atom-locals: splicing .debug_info/.debug_abbrev/.debug_str/.debug_loc/.debug_loclists 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)"
+		# Single objcopy call: 3x --update-section for F' (line, aranges, rnglists).
+		$f_args = @(
+			"--update-section=.debug_line=$dwarfLineBin",
+			"--update-section=.debug_aranges=$dwarfArangesBin",
+			"--update-section=.debug_rnglists=$dwarfRnglistsBin"
+		)
+		& $Objcopy @f_args $injectElf 2>&1 | Out-Null
+		if ($LASTEXITCODE -ne 0) {
+			Write-Warning "[build] objcopy F' splice failed (exit $LASTEXITCODE); removing $injectElf"
+			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
 			return;
 		}
-		& $Objcopy --update-section ".debug_abbrev=$dwarfAbbrevBin" $injectElf
+
+		# G' 5-section splice: 3 update-section (info / abbrev / str) + 2 add-section (loc / loclists).
+		$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'
+		$dwarfLoclistsBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_loclists.bin'
+		$g_args = @(
+			"--update-section=.debug_info=$dwarfInfoBin",
+			"--update-section=.debug_abbrev=$dwarfAbbrevBin",
+			"--update-section=.debug_str=$dwarfStrBin",
+			"--add-section=.debug_loc=$dwarfLocBin",
+			"--add-section=.debug_loclists=$dwarfLoclistsBin"
+		)
+		& $Objcopy @g_args $injectElf 2>&1 | Out-Null
 		if ($LASTEXITCODE -ne 0) {
-			Write-Warning "[build] objcopy .debug_abbrev update failed (exit $LASTEXITCODE)"
+			Write-Warning "[build] objcopy G' splice failed (exit $LASTEXITCODE); removing $injectElf"
+			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
 			return;
 		}
-		& $Objcopy --update-section ".debug_str=$dwarfStrBin"      $injectElf
+
+		# 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 2>&1 | Out-Null
 		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 
-			{
-				# .debug_loclists doesn't exist in the source ELF; --add-section creates it.
-				& $Objcopy --add-section ".debug_loclists=$dwarfLoclistsBin" $injectElf
-				if ($LASTEXITCODE -ne 0) {
-					Write-Warning "[build] objcopy .debug_loclists add-section failed (exit $LASTEXITCODE)"
-				} else {
-					Write-Host "[build] G' atom-locals-injected: $injectElf"
-				}
-			}
+			Write-Warning "[build] atom-section flag update failed (exit $LASTEXITCODE); removing $injectElf"
+			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
+		} else {
+			Write-Host "[build] DWARF-injected ELF: $injectElf"
 		}
 	}
 }

scripts/duffle.lua

@@ -9,7 +9,6 @@
 ---   - **Word-count loader** (`load_word_counts` for `WORD_COUNT(...)` metadata files).
 ---   - **Line lookup** (`LineIndex` returns an O(log N) `line_of(pos)` closure for source-mapping).
 ---   - **Domain tables** (`TAPE_ATOM_MACROS`, `GTE_PIPELINE_LATENCY`, `GP0_CMD_SIZE`, `GP0_CMD_BY_SHAPE`, `GP0_MACRO_CONTRIB`, `INSTRUCTION_LATENCY`).
----   - **Process-bootstrap helper** (`setup_package_path`replaces the 8-line `arg[0]`-resolution boilerplate duplicated across 7 entry scripts)
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex.
 
@@ -137,10 +136,8 @@ 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.
+-- Byte-based versions (accept a single-byte INTEGER).
+-- Used in all hot loops because they avoid the string allocation per s:sub(pos, pos) call.
 
 -- Whitespace characters per C locale.
 function M.is_space_byte(b) return b == BYTE_SPACE or b == BYTE_TAB or b == BYTE_NEWLINE or b == BYTE_CR or b == BYTE_VT  or b == BYTE_FF end
@@ -231,6 +228,9 @@ end
 -- Section 3: I/O primitives
 -- ════════════════════════════════════════════════════════════════════════════
 
+-- File contents intentionally use io.open below. LuaFileSystem handles path
+-- metadata, directory iteration, the current directory, and mkdir; it does not
+-- expose file-content read/write streams.
 function M.read_file(path)
 	local  f = io.open(path, "r")
 	if not f then error("Cannot open " .. path) end
@@ -249,7 +249,7 @@ end
 -- @param path string
 -- @param content string
 function M.write_file_lf(path, content)
-	local f = io.open(path, "wb")
+	local  f = io.open(path, "wb")
 	if not f then error("Cannot write " .. path) end
 	f:write(content); f:close()
 end
@@ -274,8 +274,7 @@ end
 -- Normalizes forward slashes to backslashes on Windows.
 -- Used for byte-identical emit: the // Source: comment line uses the absolute path.
 --
--- 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.
+-- The CWD is memoized on first call.
 -- @param path string
 -- @return string
 local _absolute_path_cache = {}
@@ -288,11 +287,10 @@ function M.to_absolute_path(path)
 		_absolute_path_cache[path] = result
 		return result
 	end
-	-- lfs.currentdir() is ~0ms vs io.popen("cd") at ~50ms per call on Windows.
-	local cwd = lfs.currentdir()
+	local  cwd = lfs.currentdir()
 	if not cwd then _absolute_path_cache[path] = path; return path end
 	cwd = cwd:gsub("/", "\\")
-	local tail = (path:gsub("/", "\\"))
+	local tail   = (path:gsub("/", "\\"))
 	local result = cwd .. "\\" .. tail
 	_absolute_path_cache[path] = result
 	return result
@@ -396,15 +394,11 @@ function M.scan_to_char(s, target, start)
 	local target_byte = target:byte()
 	local pos = start
 	while pos <= #s do
-		local c = s:byte(pos)
-		if      c == target_byte then return pos end
-		-- scan: ... <target found> | <skipping to target>
-		if      c == BYTE_OPEN_PAREN  then local _, a = M.read_balanced(s, "(", ")", pos); pos = a
-			-- scan: ... ( <balanced> ) ...
-		elseif  c == BYTE_OPEN_BRACE  then local _, a = M.read_balanced(s, "{", "}", pos); pos = a
-			-- scan: ... { <balanced> } ...
-		elseif  c == BYTE_OPEN_BRACK  then local _, a = M.read_balanced(s, "[", "]", pos); pos = a
-			-- scan: ... [ <balanced> ] ...
+		local   c = s:byte(pos)
+		if      c == target_byte      then return pos end                                          -- scan: ... <target found> | <skipping to target>
+		if      c == BYTE_OPEN_PAREN  then local _, a = M.read_balanced(s, "(", ")", pos); pos = a -- scan: ... ( <balanced> ) ...
+		elseif  c == BYTE_OPEN_BRACE  then local _, a = M.read_balanced(s, "{", "}", pos); pos = a -- scan: ... { <balanced> } ...
+		elseif  c == BYTE_OPEN_BRACK  then local _, a = M.read_balanced(s, "[", "]", pos); pos = a -- scan: ... [ <balanced> ] ...
 		else
 			local nx = M.skip_str_or_cmt(s, pos)
 			pos      = (nx > pos) and nx or (pos + 1)
@@ -520,12 +514,11 @@ function M.split_top_level_commas(body)
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Section 4b: tokenize_body + build_body_line_index (shared, memoized)
+-- Section 4: tokenize_body + build_body_line_index (shared, memoized)
 -- ════════════════════════════════════════════════════════════════════════════
 
-local _tokenize_body_cache        = {}
-local _tokenize_body_simple_cache = {}
-local _body_line_index_cache      = {}
+local _tokenize_body_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`.
@@ -535,12 +528,12 @@ local _body_line_index_cache      = {}
 function M.tokenize_body(body)
 	if _tokenize_body_cache[body] ~= nil then return _tokenize_body_cache[body] end
 	local out = {}
-	local len     = #body
-	local rel     = 1
+	local len = #body
+	local rel = 1
 	while rel <= len do
 		local ws_end = M.skip_ws_and_cmt(body, rel)
 		if ws_end > rel then rel = ws_end end
-		if rel > len then break end
+		if rel    > len then break end
 
 		local scan = rel
 		while scan <= len do
@@ -575,21 +568,6 @@ function M.tokenize_body(body)
 	return out
 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
-
 --- Build a line-index: count `\n` chars from offset 1 up to the offset; that count + 1 is the line number (1-based).
 --- Memoized on the body string.
 --- @param body string
@@ -597,7 +575,7 @@ end
 function M.build_body_line_index(body)
 	if _body_line_index_cache[body] ~= nil then return _body_line_index_cache[body] end
 	local index = {}
-	local len = #body
+	local len   = #body
 	local newline_count = 0
 	for pos = 1, len do
 		if pos > 1 then
@@ -619,7 +597,7 @@ end
 --- @param tok string
 --- @return integer|nil
 function M.find_marker_call_end(tok)
-	local ident, after = M.read_ident(tok, 1)
+	local  ident, after = M.read_ident(tok, 1)
 	if not ident then return nil end
 	if ident ~= "atom_label" and ident ~= "atom_offset" then return nil end
 	local paren_pos = M.skip_ws_and_cmt(tok, after)
@@ -628,6 +606,41 @@ function M.find_marker_call_end(tok)
 	return close
 end
 
+--- True iff `tok` is an atom-label or atom-offset marker call.
+--- Sibling helper to M.find_marker_call_end; uses the same string constants.
+--- @param tok string
+--- @return boolean
+function M.is_marker_token(tok)
+	local  leading = M.read_ident(tok, 1)
+	return leading == "atom_label" or leading == "atom_offset"
+end
+
+--- Count words contributed by the non-marker portion of `tok` (after the marker's closing `)`).
+--- Returns 0 if `tok` isn't a marker call or has no trailing content.
+---
+--- `count_token_words_fn` is injected by the caller rather than imported here because the
+--- dependency arrow already points the other way: `passes/offsets.lua` and
+--- `passes/atoms_source_map.lua` both `require("word_count_eval")` and pass its
+--- `count_token_words` as the 3rd argument to this function, while `word_count_eval`
+--- itself loads `duffle` via `duffle_paths.lua` (see `passes/word_count_eval.lua` near
+--- the top of the file) and calls `duffle.trim` / `duffle.read_ident` /
+--- `duffle.skip_ws_and_cmt` from `M.count_token_words`. Importing `word_count_eval`
+--- from this module would reverse that direction and form a recursive require cycle.
+--- The callback keeps the marker-syntax helpers (`find_marker_call_end`,
+--- `is_marker_token`, this function) shared in `duffle` without making the foundational
+--- utility depend on a pass module.
+--- @param tok string
+--- @param word_counts table
+--- @param count_token_words_fn fun(tok: string, wc: table): integer
+--- @return integer
+function M.count_marker_rest(tok, word_counts, count_token_words_fn)
+	local marker_end = M.find_marker_call_end(tok)
+	if not marker_end or marker_end >= #tok then return 0 end
+	local rest = M.trim(tok:sub(marker_end))
+	if rest == "" then return 0 end
+	return count_token_words_fn(rest, word_counts)
+end
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- Section 5: load_word_counts
 -- ════════════════════════════════════════════════════════════════════════════
@@ -703,13 +716,12 @@ M.TAPE_ATOM_MACROS = {
 -- The check (`scripts/passes/static_analysis.lua :: check_gte_pipeline_fill`) walks each atom body,
 -- counts the consecutive nop words before every `gte_cmdw_*` invocation, and reports a finding if the count is below this minimum.
 --
--- PRE-FILL vs POST-FILL: this table models PRE-cmdw nops (retiring preceding C2 writes),
--- NOT the post-cmdw input-latch window. 
+-- PRE-FILL vs POST-FILL: this table models PRE-cmdw nops (retiring preceding C2 writes).
 -- The PSX-SPX pipeline timings doc (`docs/psx-spx/docs/gtepipelinetimings.md`) measures a DIFFERENT number:
 -- the smallest N nops between `cop2` and `mtc2` to a specific input register at which the write no longer affects the output.
 -- For nearly all instructions, inputs latch in the first 0-4 cycles — the GTE snapshots its input register file early and works
---  from internal pipeline storage afterward. The documented total cycle count is NOT the "do not touch inputs" window;
--- the actual read window is much shorter.
+--  from internal pipeline storage afterward. 
+-- The documented total cycle count is NOT the "do not touch inputs" window; the actual read window is much shorter.
 --
 -- The `gte_rtpt()` / `gte_nclip()` wrapper macros in gte.h emit the pre-cmd nops internally (asm_words(nop, nop, ...)),
 -- but THOSE WRAPPERS ARE NOT USED INSIDE ATOM BODIES in this codebase.
@@ -934,7 +946,7 @@ M.INSTRUCTION_LATENCY = {
 	["gte_nclip"]                                    = 8,   -- alias for nclip
 	["gte_avsz3"]                                    = 5,
 	["gte_avsz4"]                                    = 6,
-	-- Legacy single-cycle store helpers (gte_stotz, gte_stsxy3 are 1 cycle)
+	-- Single-cycle store helpers (gte_stotz, gte_stsxy3 are 1 cycle)
 	["gte_stotz"]           = 1,
 	["gte_stsxy3"]          = 1,
 	-- High-level GTE helpers (gte_load_v0/v1/v2 do multiple lwc2s)

scripts/elf_dwarf.lua

@@ -1,10 +1,9 @@
---- elf_dwarf.lua — ELF32 + DWARF + atoms source-map utilities for the F'' track.
----
+--- elf_dwarf.lua — ELF32 + DWARF + atoms source-map utilities.
 --- 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'').
+---     Every constant carries a spec:` comment naming the spec section that defines it.
 ---   - **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,
@@ -14,8 +13,7 @@
 -- 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).
+-- lfs is wired into package.cpath by `duffle_paths.lua` (vendored under `toolchain/lfs/lfs.dll`). 
 local lfs = require("lfs")
 
 local M = {}
@@ -26,17 +24,17 @@ local M = {}
 -- (DWARF5 §7.5.5 "Tag Encodings" + Table 7.1; gcc emits these exact values for the DWARF3-extension and DWARF5 line units.)
 
 M.DW_TAG = {
-	compile_unit        = 0x11,
-	subprogram          = 0x2E,
-	variable            = 0x34,
-	structure_type      = 0x13,
-	member              = 0x0D,
-	base_type           = 0x24,
-	typedef             = 0x2A,
-	pointer_type        = 0x0F,
-	const_type          = 0x26,
-	volatile_type       = 0x27,
-	inlined_subroutine  = 0x1D,
+	compile_unit       = 0x11,
+	subprogram         = 0x2E,
+	variable           = 0x34,
+	structure_type     = 0x13,
+	member             = 0x0D,
+	base_type          = 0x24,
+	typedef            = 0x2A,
+	pointer_type       = 0x0F,
+	const_type         = 0x26,
+	volatile_type      = 0x27,
+	inlined_subroutine = 0x1D,
 	-- We index the canonical gcc-emitted tags. Anything else falls through.
 }
 
@@ -102,49 +100,51 @@ local DW_FORM_implicit_const = 0x21
 --- 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).
+--- **Wire-offset contract:** format offsets, fixed-width reader offsets, LEB/parser cursors,
+--- and section-relative values are zero-based wire offsets. Only Lua string APIs receive
+--- a `+ 1` conversion at their boundary (`byte`, `sub`, and `find`).
+---
+--- ELF/DWARF field offsets are expressed in hex so they map directly to the
+--- zero-based byte positions in the binary file.
+
 
 --- 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_offset          = 0x00,         -- 4-byte magic "\127ELF" at file offset 0x00
 	magic                 = "\127ELF",
-	class_offset          = 0x05,         -- 1-byte; 1 = ELF32, 2 = ELF64
+	class_offset          = 0x04,         -- 1-byte; 1 = ELF32, 2 = ELF64
 	class_elf32           = 1,
-	endian_offset         = 0x06,         -- 1-byte; 1 = little-endian, 2 = big-endian
+	endian_offset         = 0x05,         -- 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
+	e_shoff_offset        = 0x20,         -- 4-byte LE; section-header table file offset
+	e_shentsize_offset    = 0x2E,         -- 2-byte LE; section-header entry size in bytes
+	e_shnum_offset        = 0x30,         -- 2-byte LE; number of section headers
+	e_shstrndx_offset     = 0x32,         -- 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
+	sh_name_offset        = 0x00,         -- 4-byte LE; offset into .shstrtab
+	sh_type_offset        = 0x04,         -- 4-byte LE; section type (SHT_*)
+	sh_offset_offset      = 0x10,         -- 4-byte LE; section's file offset
+	sh_size_offset        = 0x14,         -- 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.
+-- All offsets are zero-based wire offsets.
 
 --- 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
+	unit_length_offset = 0x00,    -- 4-byte LE; length of unit body (excludes these 4 bytes)
+	version_offset     = 0x04,    -- 2-byte LE; expected = 2
+	cu_offset_offset   = 0x06,    -- 4-byte LE; CU DIE offset in .debug_info
+	addr_size_offset   = 0x0A,    -- 1-byte;  expected = 4 (32-bit MIPS)
+	seg_size_offset    = 0x0B,    -- 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,
@@ -155,16 +155,16 @@ M.DWARF4_ARANGES = {
 -- ----------------------------------------------------------------------------
 -- DWARF5 .debug_rnglists (per DWARF5 spec §2.17 + §7.21)
 -- ----------------------------------------------------------------------------
--- All offsets are 1-INDEXED (matching Lua string.sub convention), in hex.
+-- All offsets are zero-based wire offsets.
 
 --- 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,
+	unit_length_offset    = 0x00,    -- 4-byte LE
+	version_offset        = 0x04,    -- 2-byte LE; expected = 5
+	addr_size_offset      = 0x06,    -- 1-byte;  expected = 4
+	seg_size_offset       = 0x07,    -- 1-byte;  expected = 0
+	offset_count_offset   = 0x08,    -- 4-byte LE; expected = 0
+	first_entry_offset    = 0x0C,
 	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,
@@ -208,35 +208,37 @@ M.DWARF_LINE_OPS = {
 -- 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
+--- Read a 4-byte little-endian unsigned integer from `buf` at zero-based wire offset `off`.
+--- Equivalent to `string.unpack("<I4", buf, off + 1)` 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`).
+--- **Convention:** `off` is a zero-based wire offset; `+ 1` is applied only at the `string.byte` boundary.
 ---
 --- **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
+--- @param off integer  -- zero-based wire offset
 --- @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
+	local byte_off = off + 1
+	return buf:byte(byte_off)
+		+ buf:byte(byte_off + 0x01) * 0x00000100
+		+ buf:byte(byte_off + 0x02) * 0x00010000
+		+ buf:byte(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`.)
+--- Read a 2-byte little-endian unsigned integer from `buf` at zero-based wire offset `off`.
+--- (`off` is zero-based; `+ 1` is applied only at the `string.byte` boundary.)
 --- @param buf string
---- @param off integer  -- 1-indexed
+--- @param off integer  -- zero-based wire offset
 --- @return integer
 function M.read_u16_le(buf, off)
-	return buf:byte(off) + buf:byte(off + 0x01) * 0x00000100
+	local byte_off = off + 1
+	return buf:byte(byte_off) + buf:byte(byte_off + 0x01) * 0x00000100
 end
 
--- Pure-Lua 5.3 LEB128 readers (no `bit` library). `2^shift` arithmetic matches the existing F' parser.
+-- Pure-Lua 5.3 LEB128 readers (no `bit` library). `2^shift` arithmetic matches the existing parser.
 -- Offsets are 0-based; returns (value, next_pos).
 -- Track A Task 10: promoted from `local function` to M.* exports so passes/dwarf_injection.lua
 -- can import them as file-scope locals per the 2nd-caller lift precedent
@@ -359,23 +361,23 @@ end
 -- The caller decides whether to interpret that as a section offset.
 local function read_form_value(buf, str_buf, pos, form)
 	if form == M.DW_FORM.addr then
-		return M.read_u32_le(buf, pos + 1), pos + 4
+		return M.read_u32_le(buf, pos), pos + 4
 	elseif form == M.DW_FORM.string then
 		local s = read_c_string_at(buf, pos)
 		return s, pos + #s + 1
 	elseif form == M.DW_FORM.strp then
 		-- DW_FORM_strp: 4-byte offset into .debug_str.
-		local strp_off = M.read_u32_le(buf, pos + 1)
+		local strp_off = M.read_u32_le(buf, pos)
 		return read_c_string_at(str_buf, strp_off), pos + 4
 	elseif form == M.DW_FORM.udata then return M.read_uleb128_at(buf, pos)
 	elseif form == M.DW_FORM.data1 then return buf:byte(pos + 1), pos + 1
-	elseif form == M.DW_FORM.data2 then return M.read_u16_le(buf, pos + 1), pos + 2
-	elseif form == M.DW_FORM.data4 then return M.read_u32_le(buf, pos + 1), pos + 4
-	elseif form == M.DW_FORM.ref4  then return M.read_u32_le(buf, pos + 1), pos + 4
+	elseif form == M.DW_FORM.data2 then return M.read_u16_le(buf, pos), pos + 2
+	elseif form == M.DW_FORM.data4 then return M.read_u32_le(buf, pos), pos + 4
+	elseif form == M.DW_FORM.ref4  then return M.read_u32_le(buf, pos), pos + 4
 	elseif form == M.DW_FORM.sec_offset then
 		-- DW_FORM_sec_offset: 4-byte offset (size depends on DWARF version;
 		-- on DWARF5 32-bit it's always 4 bytes).
-		return M.read_u32_le(buf, pos + 1), pos + 4
+		return M.read_u32_le(buf, pos), pos + 4
 	elseif form == M.DW_FORM.flag_present then
 		return 1, pos
 	elseif form == M.DW_FORM.exprloc then
@@ -387,331 +389,97 @@ local function read_form_value(buf, str_buf, pos, form)
 		-- The constant is declared in the abbrev; no value bytes in the DIE.
 		return nil, pos
 	elseif form == M.DW_FORM.ref_sig8 then
-		return M.read_u32_le(buf, pos + 1), pos + 8
+		-- DW_FORM_ref_sig8 (DWARF5 §7.4.2): an 8-byte value identifying a type
+		-- by signature. The low 4 bytes (LE) are the type signature (content hash);
+		-- the high 4 bytes (LE) are a CU-relative offset into the matching type unit.
+		-- Consumers use the low 4 to look up the type unit (see M.find_type_unit_by_signature)
+		-- then the high 4 to resolve the specific type within it.
+		-- Return the low 4 as the primary value to preserve the (value, next_pos) shape;
+		-- the high 4 is exposed via M.read_ref_sig8 (which returns both halves).
+		local _, _, next_pos = M.read_ref_sig8(buf, pos)
+		return M.read_u32_le(buf, pos), next_pos
 	else
 		return nil, pos
 	end
 end
 
--- Index the .debug_info + .debug_abbrev sections of an existing ELF and collect one entry per "interesting" type DIE in the FIRST compilation unit. 
--- The index supports typed-views:
---   index = {
---     by_name = { ["V4_S2"]      = {kind="structure_type", die_offset, byte_size, fields={...}},
---                 ["U4"]         = {kind="base_type",      die_offset, byte_size, encoding="unsigned"},
---                 ["MipsCode"]   = {kind="typedef",        die_offset, target_kind=..., target_die_offset=...} },
---     by_offset = { [die_offset] = {kind, name, ...} },     -- reverse lookup
---   }
---
--- @param info string             -- .debug_info section bytes
--- @param abbrev string           -- .debug_abbrev section bytes
--- @param str_buf string          -- .debug_str section bytes (for DW_FORM_strp name resolution)
--- @param abbrev_offset integer   -- 0-based offset of the main CU's abbrev table
--- @param cu_start integer|nil    -- 0-based offset of the main CU (caller-known)
--- @return table|nil, string|nil  -- (index, error)
-function M.index_main_cu_types(info, abbrev, str_buf, abbrev_offset, cu_start)
-	if not info or #info < 12 or not abbrev or not abbrev_offset then return nil, "missing input" end
-	str_buf = str_buf or ""
-	-- Index the main table at abbrev_offset. 
-	-- The F' pass writes a trailing 0 byte after the main table; the G' pass may append additional codes (100-108) + a 0 terminator.
-	-- The walker may encounter a code that wasn't in the main table but exists later in the same .debug_abbrev;
-	-- on the first miss, walk the rest of the section to add any new abbrevs we encounter.
-	local  abbrev_decls, err = parse_abbrev_table(abbrev, abbrev_offset)
-	if not abbrev_decls then return nil, err end
-	local  abbrev_by_code = {}
-	for _, d in ipairs(abbrev_decls) do abbrev_by_code[d.code] = d end
-
-	-- Resolve cu_start + cu_end_excl.
-	local cu_end_excl
-	if cu_start then
-		local ul = M.read_u32_le(info, cu_start + 1)
-		if    ul == 0xFFFFFFFF then return nil, "DWARF64 not supported" end
-		cu_end_excl = cu_start + 4 + ul
-	else
-		local pos = 0
-		cu_start = nil
-		while pos < #info do
-			local ul = M.read_u32_le(info, pos + 1)
-			if    ul == 0xFFFFFFFF then break end
-			local unit_end = pos + 4 + ul
-			if    unit_end > #info then break end
-			local unit_abbrev = M.read_u32_le(info, pos + 9)
-			if    unit_abbrev == abbrev_offset then
-				cu_start    = pos
-				cu_end_excl = unit_end
-				break
-			end
-			pos = unit_end
-		end
-		if not cu_start then return nil, "no CU matches abbrev_offset" end
-	end
-
-	-- Walk the CU's DIE tree at 0-based offset cu_start + 12.
-	-- Emit a flat list of type-bearing DEIs; recursion handles nested children 
-	-- (members inside structure_type, types inside subprograms, etc.).
-	-- A non-type DIE's subtree is SKIPPED by walking until the matching null.
-	local by_name    = {}
-	local by_offset  = {}
-	local pos_cursor = cu_start + 12
-	-- Root DIE is the compile_unit; skip past it.
-	if pos_cursor >= cu_end_excl then return nil, "no DIE bytes" end
-	local root_decl_code
-	root_decl_code, pos_cursor = M.read_uleb128_at(info, pos_cursor)
-	if not root_decl_code then return nil, "truncated root DIE code" end
-	local  root_decl = abbrev_by_code[root_decl_code]
-	if not root_decl then return nil, "unknown root DIE abbrev" end
-	-- Skip root DIE attributes.
-	for     _, attr in ipairs(root_decl.attrs) do
-		local _, ne = read_form_value(info, str_buf, pos_cursor, attr.form)
-		if not ne then return nil, "truncated root attr" end
-		pos_cursor = ne
-	end
-	-- If root has no children, return an empty index.
-	if not root_decl.has_children or root_decl.has_children == 0 then
-		return { by_name = by_name, by_offset = by_offset }
-	end
-
-	-- Helper: skip a subtree rooted at the current DIE (pos_cursor is positioned at the first child).
-	-- Walks down and right until the matching null terminator is consumed.
-	-- Returns the new pos_cursor. 
-	-- For DIE trees that contain only the closed type + member shapes, the depth never exceeds 2 (type DIE -> member DIE -> null).
-	local function skip_subtree(pos)
-		local depth = 1
-		while pos < cu_end_excl and depth > 0 do
-			local code = info:byte(pos + 1)
-			pos = pos + 1
-			if code == 0 then
-				depth = depth - 1
-			else
-				local d = abbrev_by_code[code]
-				if d and d.has_children ~= 0 then
-					depth = depth + 1
-				end
-			end
-		end
-		return pos
-	end
-
-	-- Pre-declare n_visited so the closure helpers can read it.
-	local n_visited = 0
-
-	-- Helper: read one DIE's attributes. 
-	-- Returns (name, byte_size, encoding, type_ref, new_pos_cursor) on success; (nil, error_string) on truncation.
-	local function read_die_attributes(decl, pos)
-		local die_name       = nil
-		local die_byte_size  = nil
-		local die_encoding   = nil
-		local die_type_ref   = nil
-		for ai, attr in ipairs(decl.attrs) do
-			local before  = pos
-			local val, ne = read_form_value(info, str_buf, pos, attr.form)
-			if not ne then
-				return nil, "truncated DIE attr"
-			end
-			pos = ne
-			if attr.name == M.DW_AT.name then
-				die_name = val
-			elseif attr.name == M.DW_AT.byte_size and (decl.tag == M.DW_TAG.base_type or decl.tag == M.DW_TAG.structure_type) then
-				die_byte_size = val
-			elseif attr.name == M.DW_AT.encoding and decl.tag == M.DW_TAG.base_type then
-				die_encoding = val
-			elseif attr.name == M.DW_AT.type then
-				die_type_ref = val
-			end
-		end
-		return die_name, die_byte_size, die_encoding, die_type_ref, pos
-	end
-
-	-- Helper: read structure_type members. Returns (member_fields, new_pos).
-	local function read_member_fields(decl, pos)
-		local fields = {}
-		while pos < cu_end_excl do
-			local mcode = info:byte(pos + 1)
-			if mcode == 0 then
-				pos = pos + 1
-				break
-			end
-			local mdecl = abbrev_by_code[mcode]
-			if not mdecl then return nil, "unknown member abbrev" end
-			pos = pos + 1
-			local mname, mtype_ref, moffset
-			for _, a in ipairs(mdecl.attrs) do
-				local v, ne = read_form_value(info, str_buf, pos, a.form)
-				if not ne then return nil, "truncated member attr" end
-				pos = ne
-				if     a.name == M.DW_AT.name                 then mname     = v
-				elseif a.name == M.DW_AT.type                 then mtype_ref = v
-				elseif a.name == M.DW_AT.data_member_location then moffset   = v end
-			end
-			fields[#fields + 1] = { name = mname, type_offset = mtype_ref, offset = moffset }
-		end
-		return fields, pos
-	end
-
-	-- Top-level walker: iterate siblings.
-	-- For each DIE, decide whether to record (if type), descend (if structure_type with members), or skip its subtree.
-	while pos_cursor < cu_end_excl do
-		local code = info:byte(pos_cursor + 1)
-		if    code == 0 then pos_cursor = pos_cursor + 1; break end
-		local decl = abbrev_by_code[code]
-		if not decl then
-			-- Lazily scan the rest of the section for the missing code.
-			-- The G' pass appends new abbrevs (100-108) after the main table's terminator.
-			-- On the first miss, walk the rest of the section.
-			local scan_pos = 0
-			while scan_pos < #abbrev do
-				if abbrev:byte(scan_pos + 1) == 0 then
-					scan_pos = scan_pos + 1
-					goto continue
-				end
-				local  new_table, e3 = parse_abbrev_table(abbrev, scan_pos)
-				if not new_table then
-					scan_pos = scan_pos + 1
-					goto continue
-				end
-				for _, d in ipairs(new_table) do
-					if not abbrev_by_code[d.code] then
-						abbrev_by_code[d.code] = d
-					end
-				end
-				-- Find the terminator (0 byte) of this table.
-				local  term = M.find_abbrev_table_end(abbrev, scan_pos)
-				if not term then break end
-				scan_pos = term + 1
-				::continue::
-			end
-			decl = abbrev_by_code[code]
-			if not decl then
-				return nil, string.format("unknown abbrev %d at offset 0x%x", code, pos_cursor)
-			end
-		end
-		local die_offset = pos_cursor
-		pos_cursor = pos_cursor + 1
-		local read_result = { read_die_attributes(decl, pos_cursor) }
-		if   #read_result == 2 then
-			return nil, read_result[2]
-		end
-		local die_name, die_byte_size, die_encoding, die_type_ref, pos_after_attrs
-		= read_result[1], read_result[2], read_result[3], read_result[4], read_result[5]
-		n_visited = n_visited + 1
-		local is_type = (
-		     decl.tag == M.DW_TAG.base_type
-			or decl.tag == M.DW_TAG.structure_type
-			or decl.tag == M.DW_TAG.typedef
-			or decl.tag == M.DW_TAG.pointer_type
-			or decl.tag == M.DW_TAG.const_type)
-
-		local member_fields = nil
-		pos_cursor = pos_after_attrs
-		if decl.tag == M.DW_TAG.structure_type and decl.has_children ~= 0 then
-			local  f, np = read_member_fields(decl, pos_cursor)
-			if not f then return nil, np end
-			member_fields = f
-			pos_cursor    = np
-		elseif decl.has_children ~= 0 then
-			-- Skip the subtree (e.g., DW_TAG_subprogram, DW_TAG_variable, etc.).
-			pos_cursor = skip_subtree(pos_cursor)
-		end
-
-		if is_type and die_name then
-			local kind
-			if     decl.tag == M.DW_TAG.base_type      then kind = "base_type"
-			elseif decl.tag == M.DW_TAG.structure_type then kind = "structure_type"
-			elseif decl.tag == M.DW_TAG.typedef        then kind = "typedef"
-			elseif decl.tag == M.DW_TAG.pointer_type   then kind = "pointer_type"
-			elseif decl.tag == M.DW_TAG.const_type     then kind = "const_type" end
-			local entry = {
-				kind       = kind,
-				name       = die_name,
-				die_offset = die_offset,
-				byte_size  = die_byte_size,
-				encoding   = die_encoding,
-				type_ref   = die_type_ref,
-				fields     = member_fields,
-			}
-			by_name[die_name]     = entry
-			by_offset[die_offset] = entry
-		end
-	end
-	return { by_name = by_name, by_offset = by_offset }
+--- Read a `DW_FORM_ref_sig8` value at 0-based offset `pos` from `buf`.
+--- Returns the low 4 bytes (LE) as `low`, the high 4 bytes (LE) as `high`, and
+--- the cursor position after the 8-byte value as `next_pos`.
+--- Callers that need the full type-unit + type-offset pair
+--- (e.g. to resolve a type identifier embedded as a signature)
+--- should use this directly rather than going through `read_form_value`,
+--- which only exposes the low 4 bytes to preserve its existing (value, next_pos) return shape.
+--- @param buf string
+--- @param pos integer  -- zero-based wire offset
+--- @return integer  -- low 4 bytes (LE), the type signature
+--- @return integer  -- high 4 bytes (LE), the offset within the matching type unit
+--- @return integer  -- cursor after the 8-byte value
+function M.read_ref_sig8(buf, pos)
+	return M.read_u32_le(buf, pos), M.read_u32_le(buf, pos + 4), pos + 8
 end
 
--- Resolve a chain of pointer + const + typedef + structure_type down to a canonical struct or base type.
--- The returned entry has kind, name, byte_size, and (for structure_type) fields with {name, offset, type_name, pointer_depth}.
--- Returns nil if the chain cannot be resolved (e.g., missing DIE).
--- @param index table          -- M.index_main_cu_types result
--- @param start_offset integer -- CU-relative DW_FORM_ref4 offset of the start
--- @param max_depth integer    -- cycle protection
--- @return table|nil           -- {kind, name, byte_size, fields?, pointer_depth}
-function M.resolve_type_chain(index, start_offset, max_depth)
-	max_depth = max_depth or 16
-	if not index or not start_offset then return nil end
-	local chain      = {}
-	local cur_offset = start_offset
-	local depth      = 0
-	while cur_offset and depth < max_depth do
-		local entry = index.by_offset[cur_offset]
-		if not entry then return nil end
-		chain[#chain + 1] = entry
-		if     entry.kind == "pointer_type" then cur_offset = entry.type_ref
-		elseif entry.kind == "const_type"   then cur_offset = entry.type_ref
-		elseif entry.kind == "typedef"      then cur_offset = entry.type_ref
-		else
-			break
+-- DWARF5 §7.5.6 (Type Entries).
+-- Walk all units in `info` and return the 0-based offset of the first unit
+-- whose `DW_AT_type_signature` (8-byte value at the end of the unit header) equals `target_sig`.
+-- The signature is interpreted as two 32-bit halves (low/high) per the read_ref_sig8 contract;
+-- we match both halves (i.e. the 8-byte value as a whole). Returns nil if no matching unit exists.
+--
+-- Unit header layout (from pos 0):
+--   unit_length(4) + version(2) + unit_type(1) + address_size(1) + debug_abbrev_offset(4)
+--   -- followed by type_unit_specific fields:
+--   type_signature(8) + type_offset(4)
+-- The type_signature is at byte offset 8 of the body (right after debug_abbrev_offset).
+-- @param info string  -- the .debug_info section bytes
+-- @param target_sig_lo integer  -- low 4 bytes (LE) of the desired signature
+-- @param target_sig_hi integer  -- high 4 bytes (LE) of the desired signature
+-- @return integer|nil, integer|nil  -- unit offset, type_offset within the unit
+function M.find_type_unit_by_signature(info, target_sig_lo, target_sig_hi)
+	local pos = 0
+	local section_len = #info
+	while pos + 4 < section_len do
+		local unit_length = M.read_u32_le(info, pos)
+		if unit_length == 0xFFFFFFFF then
+			return nil, nil  -- DWARF64 not supported
 		end
-		depth = depth + 1
-	end
-	-- Compute pointer_depth = number of pointer/const wrappers.
-	local pointer_depth = 0
-	for _, e in ipairs(chain) do
-		if e.kind == "pointer_type" then pointer_depth = pointer_depth + 1 end
-	end
-	-- The last entry is the "naked" type.
-	local naked = chain[#chain]
-	if not naked then return nil end
-	-- If the last entry is a structure_type, resolve each field's type name
-	-- + pointer depth too (for `bind_args` shape expansion).
-	if naked.kind == "structure_type" and naked.fields then
-		local fields = {}
-		for _, f in ipairs(naked.fields) do
-			local field_entry = f.type_offset and index.by_offset[f.type_offset] or nil
-			local field_chain = {}
-			local d = 0
-			local co = f.type_offset
-			while co and d < 16 do
-				local e2 = index.by_offset[co]
-				if not e2 then break end
-				field_chain[#field_chain + 1] = e2
-				if e2.kind == "pointer_type" or e2.kind == "const_type" or e2.kind == "typedef" then
-					co = e2.type_ref
-				else
-					break
+		-- unit_length is the body size, NOT including the 4-byte unit_length field itself.
+		local body_start = pos + 4
+		local body_end   = body_start + unit_length
+		if body_end > section_len then
+			return nil, nil  -- malformed
+		end
+		-- Per DWARF5 §7.5.6, the type_unit (DW_UT_type = 0x02) body layout is:
+		--   0:  version (2)
+		--   2:  unit_type (1) -- DW_UT_type = 0x02
+		--   3:  address_size (1)
+		--   4:  debug_abbrev_offset (4)
+		--   8:  type_signature (8)
+		--   16: type_offset (4)
+		--   20: <children>
+		if body_end - body_start >= 20 then
+			-- read_ref_sig8 / write_u32_le / etc. are 1-indexed (string:byte);
+			-- pos / body_start / body_end are 0-based wire offsets, so the
+			-- 1-indexed byte at 0-based wire offset X is string:byte(X + 1).
+			-- Per DWARF5 §7.5.6, the type_unit body is laid out as:
+			--   byte 0-1: version (2)
+			--   byte 2:   unit_type (1) -- DW_UT_type = 0x02
+			--   byte 3:   address_size (1)
+			--   byte 4-7: debug_abbrev_offset (4)
+			--   byte 8-15: type_signature (8)
+			--   byte 16-19: type_offset (4)
+			local unit_type = info:byte(body_start + 2 + 1)  -- 0-based +2 = unit_type in 1-indexed
+			if unit_type == 0x02 then  -- DW_UT_type
+				local sig_lo, sig_hi, _ = M.read_ref_sig8(info, body_start + 8)  -- 0-based +8 = type_signature in 1-indexed
+				if sig_lo == target_sig_lo and sig_hi == target_sig_hi then
+					local type_offset = M.read_u32_le(info, body_start + 16)  -- 0-based +16 = type_offset in 1-indexed
+					return pos, type_offset
 				end
-				d = d + 1
 			end
-			local fpd = 0
-			for _, x in ipairs(field_chain) do if x.kind == "pointer_type" then fpd = fpd + 1 end end
-			fields[#fields + 1] = {
-				name          = f.name,
-				offset        = f.offset,
-				type_name     = (field_chain[#field_chain] and field_chain[#field_chain].name) or "?",
-				pointer_depth = fpd,
-			}
 		end
-		return {
-			kind          = "structure_type",
-			name          = naked.name,
-			byte_size     = naked.byte_size,
-			fields        = fields,
-			pointer_depth = pointer_depth,
-		}
+		-- Advance to the next unit (the 4-byte unit_length + the body).
+		pos = body_end
 	end
-	return {
-		kind          = naked.kind,
-		name          = naked.name,
-		byte_size     = naked.byte_size,
-		encoding      = naked.encoding,
-		pointer_depth = pointer_depth,
-	}
+	return nil, nil
 end
 
 --- Return a 4-byte little-endian byte string for `value`.
@@ -741,7 +509,7 @@ end
 --- 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).
+--- **Convention:** ELF/DWARF offsets are zero-based wire offsets. Direct Lua string APIs add `+ 1` at the boundary.
 --- 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.
 ---
@@ -783,17 +551,17 @@ function M.read_elf_sections(elf_path, section_names)
 	end
 
 	-- Sanity-check magic + class + endianness.
-	if header:sub(M.ELF32.magic_offset, M.ELF32.magic_offset + 0x03) ~= M.ELF32.magic then
+	if header:sub(M.ELF32.magic_offset + 1, M.ELF32.magic_offset + 0x04) ~= 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)))
+	if header:byte(M.ELF32.class_offset + 1) ~= 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 + 1)))
 		f:close()
 		return result
 	end
-	if header:byte(M.ELF32.endian_offset) ~= M.ELF32.endian_little then
+	if header:byte(M.ELF32.endian_offset + 1) ~= M.ELF32.endian_little then
 		io.stderr:write("[elf_dwarf.read_elf_sections] not little-endian; unsupported\n")
 		f:close()
 		return result
@@ -847,12 +615,9 @@ 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.
+--- - ELF32 symtab entry = 16 bytes (`st_name:4 + st_value:4 + st_size:4 + st_info:1 + st_other:1 + st_shndx:2`); offsets within each entry are zero-based wire offsets.
+--- - Direct Lua `string.byte`/`string.sub`/`string.find` boundaries receive `+ 1`.
 --- - 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.
@@ -871,31 +636,31 @@ function M.read_nm(elf_path)
 	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.
+	-- Each entry (zero-based): st_name at 0, st_value at 4, st_size at 8, st_info at 12, st_other at 13, st_shndx at 14.
 	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 SYM_ST_NAME     = 0x00
+	local SYM_ST_VALUE    = 0x04
+	local SYM_ST_SIZE     = 0x08
+	local SYM_ST_INFO     = 0x0C
 	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)
+		local entry_off  = i * SYM_ENTRY_BYTES
+		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)
+			local st_size   = M.read_u32_le(symtab, entry_off + SYM_ST_SIZE)
 			if st_size > 0 then
-				local st_name_off = M.read_u32_le(symtab, entry_off + SYM_ST_NAME  - 1)
+				local st_name_off = M.read_u32_le(symtab, entry_off + SYM_ST_NAME)
 				-- 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)
+					local st_value = M.read_u32_le(symtab, entry_off + SYM_ST_VALUE)
 					addrs[name] = { st_value, st_size }
 				end
 			end
@@ -963,9 +728,8 @@ function M.uleb128(n)
 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.
+--- 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").
 ---
@@ -988,10 +752,96 @@ function M.sleb128(n)
 	return table.concat(bytes)
 end
 
+--- ULEB128 byte-length: number of bytes the encoder M.uleb128 would produce for `n`.
+--- Used by callers that need to size a buffer before encoding (e.g. compute_loclists_offsets
+--- needs the encoded length of an `uleb128(4)` for a `DW_OP_piece + uleb128(U4_BYTE_SIZE)` tail).
+--- @param n integer  -- non-negative
+--- @return integer  -- 1..5 for n in [0, 2^32)
+function M.uleb128_size(n)
+	assert(n >= 0, "uleb128_size requires non-negative input")
+	if n == 0 then return 1 end
+	local bytes = 1
+	while n >= 0x80 do
+		n = (n - (n % (LEB_DATA_MASK + 1))) / (LEB_DATA_MASK + 1)  -- arithmetic shift right by 7
+		bytes = bytes + 1
+	end
+	return bytes
+end
+
+--- SLEB128 byte-length: number of bytes the encoder M.sleb128 would produce for `n`.
+--- Used by callers that need to size a buffer before encoding.
+--- (e.g. compute_loclists_offsets needs the encoded length of an `sleb128(field.offset)` in a tape piece).
+--- Handles the signed DWARF5 termination: positive terminator if (n == 0) and bit 6 of last byte is unset;
+--- negative terminator if (n == -1) and bit 6 of last byte is set.
+--- @param n integer  -- any integer (negative allowed)
+--- @return integer
+function M.sleb128_size(n)
+	local more = true
+	local bytes = 0
+	local v = n
+	while more do
+		local b = v % (LEB_DATA_MASK + 1) -- extract low 7 bits
+		v = (v - b) / (LEB_DATA_MASK + 1) -- arithmetic shift right by 7
+		if     v == 0  and b <  SLEB_SIGN_BIT then more = false end  -- positive terminator
+		if     v == -1 and b >= SLEB_SIGN_BIT then more = false end  -- negative terminator
+		if more then b = b + LEB_CONT_BIT end
+		bytes = bytes + 1
+	end
+	return bytes
+end
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- I/O helpers: atoms source-map + native directory glob
 -- ════════════════════════════════════════════════════════════════════════════
 
+--- Parse a FORMAT_VERSION <expected_version> atoms-meta file (sourcemap or provenance).
+--- Shared by M.parse_source_map_file + M.parse_provenance_file.
+--- The two callers differ only in how they parse WORD lines; that's `extract_word(line)`.
+--- Returns the standard `{name -> {total, words}}` shape.
+--- Returns `{}` on format-version mismatch (and logs to stderr).
+--- @param path             string
+--- @param expected_version integer
+--- @param extract_word     fun(line: string): table|nil  -- caller-supplied per-line parser
+--- @return table<string, table>
+function M.parse_atom_records(path, expected_version, extract_word)
+	local out = {}
+	local cur_name, cur_words = nil, {}
+	for raw in io.lines(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_atom_records] version mismatch (got %s, expected %d) in %s\n",
+					ver, expected_version, 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
+			local field = extract_word(line)
+			if field then
+				cur_words[#cur_words + 1] = field
+			end
+		end
+	end
+	return out
+end
+
 --- 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).
@@ -1011,43 +861,12 @@ end
 --- @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
+	return M.parse_atom_records(sm_path, expected_version, function(line)
+		local _, n, _, src_line = line:find("WORD%s+(%d+)%s+LINE%s+(%d+)")
+		if n and src_line then
+			return { pos = tonumber(n), line = tonumber(src_line) }
 		end
-	end
-	return out
+	end)
 end
 
 --- Parse a FORMAT_VERSION <expected_version> `*.atoms.provenance.txt` file.
@@ -1072,64 +891,35 @@ end
 --- @param expected_version integer  -- expected FORMAT_VERSION line
 --- @return table<string, table>
 function M.parse_provenance_file(prov_path, expected_version)
-	local out = {}
-	local cur_name, cur_words = nil, {}
-	for raw in io.lines(prov_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_provenance_file] provenance version mismatch (got %s, expected %d) in %s\n",
-					ver, expected_version, prov_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
-			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
-			-- Two accepted shapes:
-			--   WORD <n>  CALL <call-file>:<call-line>  RAW
-			--   WORD <n>  CALL <call-file>:<call-line>  MACRO <comp_name> "<comp-file>:<comp-line>"
-			local pos, call_file, call_line, comp_name, comp_file, comp_line =
-				line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+MACRO%s+(%S+)%s+"([^"]*):(%d+)"')
-			if pos then
-				cur_words[#cur_words + 1] = {
-					pos       = tonumber(pos),
-					call_file = call_file,
-					call_line = tonumber(call_line),
-					comp_name = comp_name,
-					comp_file = comp_file,
-					comp_line = tonumber(comp_line),
-				}
-			else
-				-- RAW row.
-				local raw_pos, raw_file, raw_line = line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+RAW')
-				if raw_pos then
-					cur_words[#cur_words + 1] = {
-						pos       = tonumber(raw_pos),
-						call_file = raw_file,
-						call_line = tonumber(raw_line),
-						comp_name = nil,
-						comp_file = nil,
-						comp_line = nil,
-					}
-				end
-			end
+	return M.parse_atom_records(prov_path, expected_version, function(line)
+		-- Two accepted shapes:
+		--   WORD <n>  CALL <call-file>:<call-line>  RAW
+		--   WORD <n>  CALL <call-file>:<call-line>  MACRO <comp_name> "<comp-file>:<comp-line>"
+		local pos, call_file, call_line, comp_name, comp_file, comp_line =
+			line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+MACRO%s+(%S+)%s+"([^"]*):(%d+)"')
+		if pos then
+			return {
+				pos       = tonumber(pos),
+				call_file = call_file,
+				call_line = tonumber(call_line),
+				comp_name = comp_name,
+				comp_file = comp_file,
+				comp_line = tonumber(comp_line),
+			}
 		end
-	end
-	return out
+		-- RAW row.
+		local raw_pos, raw_file, raw_line = line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+RAW')
+		if raw_pos then
+			return {
+				pos       = tonumber(raw_pos),
+				call_file = raw_file,
+				call_line = tonumber(raw_line),
+				comp_name = nil,
+				comp_file = nil,
+				comp_line = nil,
+			}
+		end
+	end)
 end
 
 return M

scripts/passes/annotation.lua

@@ -148,7 +148,7 @@ end
 --- @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 not a.binds                   then return end
 	if pipe_ctx.binds_index[a.binds] then return end
 	findings.warnings[#findings.warnings + 1] = {
 		line = a.line,
@@ -164,7 +164,7 @@ end
 --- @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]
+	local  declared = wc[m.name]
 	if not declared then
 		findings.errors[#findings.errors + 1] = {
 			line = m.line,
@@ -392,8 +392,7 @@ end
 --- Any source referencing an R_X that's NOT in the registry will trip the new check; a single pass-level info entry
 --- (emitted only when at least one such rejection lands in this source) tells users where to look.
 ---
---- Track A Task 13 added the proper `enum_alias_membership` per_source rule;
---- this is the stop-gap until users migrate off raw C-ABI register names.
+--- This check is a stop-gap until users migrate off raw C-ABI register names.
 --- @param _src SourceFile
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
@@ -409,7 +408,7 @@ local function check_wave_context_migration(_src, pipe_ctx, findings)
 						line = 0,
 						msg  = "wave-context removed; opt in via #define atom_reg in mips.h "
 							.. "(every R_<alias> that should be visible to the annotation pass "
-							.. "must be enum-declared with the bare atom_reg marker; see Track A Task 21)",
+							.. "must be enum-declared with the bare atom_reg marker)",
 					}
 					return
 				end

scripts/passes/atoms_source_map.lua

@@ -36,9 +36,8 @@
 ---
 --- 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`.
+--- 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.
@@ -84,68 +83,6 @@ local OFFSET_MARKER = "atom_offset"
 -- 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 and the gdb-runtime form.
----
---- 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
-
 -- ════════════════════════════════════════════════════════════════════════════
 -- Provenance emission
 -- ════════════════════════════════════════════════════════════════════════════
@@ -155,7 +92,7 @@ local MAC_PREFIX     = "mac_"
 local MAC_PREFIX_LEN = 4
 
 --- Strip the `mac_` prefix from a token's leading identifier.
---- Returns nil if the identifier doesn't start with `mac_` 
+--- Returns nil if the identifier doesn't start with `mac_`
 --- (so non-component tokens like `load_half_u`, `nop2`, `gte_cmdw_*` fall through cleanly).
 --- @param tok string
 --- @return string|nil
@@ -168,25 +105,48 @@ local function strip_mac_prefix_from_token(tok)
 	return nil
 end
 
---- Compute per-word provenance entries for an atom. Mirrors `compute_word_entries` but additionally classifies each emitted `.word` as either:
----   - `RAW`     — emitted by a direct instruction token (no component provenance)
----   - `MACRO X` — emitted by a `mac_X(...)` component invocation, with the component's definition file:line resolved from `ctx.shared.components`.
----
---- Returns a list of `{pos, line, text, comp_name, comp_line, comp_path, body_line}` entries + the total word count.
---- `comp_name` is nil for RAW rows. `body_line` is the line of THIS specific word in the macro body (component source file, not the caller's source);
---- it differs from `comp_line` (= the macro signature line) for every body word whose macro-body token is on a different physical line.
---- `body_line` is `nil` for RAW rows and for component words whose component declaration could not be indexed (older pass combinations / external macros).
----
---- The per-word body-line lookup mirrors `passes/dwarf_injection.lua :: compute_invocation_body_lines`:
---- walk the component's pre-tokenized body in lockstep with `count_token_words` and attribute the source line via `src.scan.line_of(...)` to each emitted `.word`.
---- Atom labels (`atom_label(...)`) emit 0 `.word`s and are skipped to stay aligned with the macro-side word-counting contract.
---- @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
---- @param comp table  -- shared.components map: bare_name -> {name=, line=, path=, kind=}
---- @param comp_body_index table  -- per-source component body index: bare_name -> {body_off, body_tokens, line_of}
+--- Fetch the per-word body lines for a `mac_X(...)` invocation.
+--- Walks the component's pre-tokenized body in lockstep with `count_token_words` and attributes each emitted `.word`
+--- to a source line via `idx.line_of(...)`. 
+--- Atom labels (`atom_label(...)`) emit 0 `.word`s and are skipped.
+--- @param bare string|nil          -- the bare component name (e.g. `gte_load_tri_verts`)
+--- @param comp_body_index table
+--- @param wc table
+--- @return table|nil                -- list of source lines, 1-based by word position
+local function fetch_body_lines(bare, comp_body_index, wc)
+	if not (bare and comp_body_index) then return nil end
+	local idx = comp_body_index[bare]
+	if not (idx and idx.body_tokens and idx.line_of) then return nil end
+	local lines = {}
+	for _, bt in ipairs(idx.body_tokens) do
+		local bt_tok = duffle.trim(bt.tok or "")
+		if bt_tok ~= "" then
+			local leading = duffle.read_ident(bt_tok, 1)
+			local bt_words
+			if leading == "atom_label" or leading == "atom_offset" then
+				bt_words = 0
+			else
+				bt_words = count_token_words(bt_tok, wc)
+			end
+			if bt_words > 0 then
+				local body_line = idx.line_of(idx.body_off + bt.rel)
+				for _ = 1, bt_words do lines[#lines + 1] = body_line end
+			end
+		end
+	end
+	return lines
+end
+
+--- Unified per-word entry walker. `mode` is "sourcemap" (3 fields) or "provenance" (8 fields including component + body-line lookup).
+--- Returns (entries, total_words). Markers contribute 0 entries.
+--- @param atom table
+--- @param src  table
+--- @param wc   table
+--- @param mode string           -- "sourcemap" | "provenance"
+--- @param comp table|nil        -- shared.components map (provenance only)
+--- @param comp_body_index table|nil  -- per-source body index (provenance only)
 --- @return table[], integer
-local function compute_provenance_entries(atom, src, wc, comp, comp_body_index)
+local function compute_word_entries(atom, src, wc, mode, comp, comp_body_index)
 	local entries = {}
 	local pos     = 0
 	for _, t in ipairs(atom.body_tokens) do
@@ -194,70 +154,46 @@ local function compute_provenance_entries(atom, src, wc, comp, comp_body_index)
 		local rel = t.rel
 
 		local words
-		if is_marker_token(tok) then
-			words = count_marker_rest(tok, wc)
+		if duffle.is_marker_token(tok) then
+			words = duffle.count_marker_rest(tok, wc, count_token_words)
 		else
 			words = count_token_words(tok, wc)
 		end
 
-		-- Resolve component provenance for this token (if any).
-		local comp_name = nil
-		local comp_line = nil
-		local comp_path = nil
-		local comp_kind = nil
-		local bare      = strip_mac_prefix_from_token(tok)
-		if bare and comp and comp[bare] then
-			comp_name = bare
-			comp_line = comp[bare].line
-			comp_path = comp[bare].path
-			comp_kind = comp[bare].kind
-		end
-
-		-- Per-word body lines: lazily allocate from the indexed component body the first time we see a `mac_X(...)` call to a given component.
-		-- We allocate ONE full body_lines vector per (call) and consume it sequentially; 
-		-- if a single atom calls the same component more than once, each call refetches its own vector. 
-		-- (Today no atom calls the same `mac_X(...)` twice, but the refetch keeps the semantics correct even if that changes.)
-		local body_lines = nil
-		local function fetch_body_lines()
-			if not (bare and comp_body_index) then return nil end
-			local idx = comp_body_index[bare]
-			if not (idx and idx.body_tokens and idx.line_of) then return nil end
-			local lines = {}
-			for _, bt in ipairs(idx.body_tokens) do
-				local bt_tok = duffle.trim(bt.tok or "")
-				if bt_tok ~= "" then
-					local leading = duffle.read_ident(bt_tok, 1)
-					local bt_words
-					if leading == "atom_label" or leading == "atom_offset" then
-						bt_words = 0
-					else
-						bt_words = count_token_words(bt_tok, wc)
-					end
-					if bt_words > 0 then
-						local body_line = idx.line_of(idx.body_off + bt.rel)
-						for _ = 1, bt_words do lines[#lines + 1] = body_line end
-					end
-				end
+		-- Provenance-only: resolve component + body_lines (one fetch per token).
+		local comp_name, comp_line, comp_path, comp_kind
+		local body_lines
+		if mode == "provenance" then
+			local bare = strip_mac_prefix_from_token(tok)
+			if bare and comp and comp[bare] then
+				comp_name = bare
+				comp_line = comp[bare].line
+				comp_path = comp[bare].path
+				comp_kind = comp[bare].kind
 			end
-			return lines
+			if comp_name then body_lines = fetch_body_lines(bare, comp_body_index, wc) end
 		end
 
 		if words > 0 then
 			local line = src.scan.line_of(atom.body_off + rel)
 			local text = duffle.trim(tok):gsub("[\t\r\n]+", " ")
-			-- Fetch body_lines ONCE per token (one mac_X(...) call exhausts N body words).
-			if comp_name then body_lines = fetch_body_lines() end
 			for i = 1, words do
-				entries[#entries + 1] = {
-					pos       = pos,
-					line      = line,
-					text      = text,
-					comp_name = comp_name,
-					comp_line = comp_line,
-					comp_path = comp_path,
-					comp_kind = comp_kind,
-					body_line = body_lines and body_lines[i],
-				}
+				local entry
+				if mode == "provenance" then
+					entry = {
+						pos       = pos,
+						line      = line,
+						text      = text,
+						comp_name = comp_name,
+						comp_line = comp_line,
+						comp_path = comp_path,
+						comp_kind = comp_kind,
+						body_line = body_lines and body_lines[i],
+					}
+				else  -- "sourcemap" (default)
+					entry = { pos = pos, line = line, text = text }
+				end
+				entries[#entries + 1] = entry
 				pos = pos + 1
 			end
 		end
@@ -282,7 +218,7 @@ end
 local function emit_provenance_stanza(src, atom, wc, comp, comp_body_index)
 	local lines    = {}
 	local rel_path = src.path:gsub("\\", "/")
-	local entries, total = compute_provenance_entries(atom, src, wc, comp, comp_body_index)
+	local entries, total = compute_word_entries(atom, src, wc, "provenance", comp, comp_body_index)
 
 	-- 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)
@@ -465,7 +401,6 @@ end
 ---
 --- 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)
@@ -595,8 +530,7 @@ local function append_gdb_commands(lines, matched)
 	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).
+	-- 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"
@@ -713,8 +647,9 @@ local M = {}
 --- but invoked from many source files (every atom body that calls `mac_X(...)`).
 --- The body_offset + body_tokens + line_of live with the declaration source, so a per-source index would miss invocations from other sources.
 ---
---- The cross-source index is keyed by the bare component name (`gte_load_tri_verts`, NOT `ac_gte_load_tri_verts`) — `strip_mac_prefix_from_token` strips the `mac_` prefix
---- from call-site identifiers and yields that exact bare name; matching it here keeps the lookup aligned with the `ctx.shared.components` map's keying convention.
+--- The cross-source index is keyed by the bare component name (`gte_load_tri_verts`, NOT `ac_gte_load_tri_verts`)
+--- `strip_mac_prefix_from_token` strips the `mac_` prefix from call-site identifiers and yields that exact bare name;
+--- matching it here keeps the lookup aligned with the `ctx.shared.components` map's keying convention.
 --- First declaration wins (subsequent redeclarations would collide; today's sources declare each component exactly once).
 --- @param ctx PassCtx
 --- @return table<string, table>  -- {[comp_name] = {body_off, body_tokens, line_of}}

scripts/passes/components.lua

@@ -96,16 +96,24 @@ local GEN_SUBDIR      = "gen"
 local M = {}
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Function-args extraction (precedes MipsAtomComp_Proc_ invocations)
+-- Back-walk helpers (composed into the 2 entry points below: find_function_args_for + preceding_comment_block)
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
--- Returns the position of the open paren, or nil if not found.
--- @param source string
--- @param name string
--- @param before_pos integer
--- @return integer|nil
-local function find_last_name_open_paren(source, name, before_pos)
+--- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
+--- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
+---
+--- Convention: function form is
+---   `FI_ MipsAtom ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
+--- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
+--- We then verify the preceding context ends with `MipsAtom`
+--- (the function-decl keyword 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)
+	-- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
 	local name_open  = name .. "("
 	local last_idx   = nil
 	local scan_pos   = 1
@@ -117,24 +125,6 @@ local function find_last_name_open_paren(source, name, before_pos)
 		last_idx = found
 		scan_pos = found + #name_open
 	end
-	return last_idx
-end
-
---- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
---- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
----
---- 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).
----
---- @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)
 	if not last_idx then return nil end
 
 	-- Verify the preceding context ends with "MipsAtom" (with possible qualifiers between).
@@ -153,100 +143,11 @@ local function find_function_args_for(source, name, before_pos)
 	return inner
 end
 
--- ════════════════════════════════════════════════════════════════════════════
--- Preceding-comment-block extraction
--- ════════════════════════════════════════════════════════════════════════════
-
--- Skip whitespace (space/tab/newline/CR) backward from `pos`, returning the position of the first non-whitespace char.
--- @param source string
--- @param pos integer
--- @return integer
-local function skip_ws_backward(source, pos)
-	local back = pos - 1
-	while back > 0 do
-		local ch = source:sub(back, back)
-		if ch == " " or ch == "\t" or ch == "\n" or ch == "\r" then
-			back = back - 1
-		else
-			break
-		end
-	end
-	return back
-end
-
--- Find the opening `/*` for a block comment whose `*/` ends at `close_pos`.
--- Returns the position of `/`, or nil if not found.
--- @param source string
--- @param close_pos integer  -- position of the closing `*` of `*/`
--- @return integer|nil
-local function find_block_comment_open(source, close_pos)
-	local prefix  = source:sub(1, close_pos - 1)
-	local open_at = nil
-	for scan = #prefix - 1, 1, -1 do
-		if prefix:sub(scan, scan + 1) == "/*" then
-			open_at = scan
-			break
-		end
-	end
-	return open_at
-end
-
--- Walk back from `open_at` over leading spaces + tabs to include the indentation before the `/*` in the captured comment.
--- @param source string
--- @param open_at integer
--- @return integer
-local function extend_left_over_indent(source, open_at)
-	local start = open_at
-	while start > 1 do
-		local ch = source:sub(start - 1, start - 1)
-		if ch == " " or ch == "\t" then
-			start = start - 1
-		else
-			break
-		end
-	end
-	return start
-end
-
--- Walk back from `line_end` to the start of the source line (the most recent `\n` or position 1).
--- @param source string
--- @param line_end integer
--- @return integer
-local function find_line_start(source, line_end)
-	local start = line_end
-	while start > 1 and source:sub(start - 1, start - 1) ~= "\n" do
-		start = start - 1
-	end
-	return start
-end
-
--- (internal) Capture one `/* ... */` block comment whose closing `*/`
--- ends at `close_end_pos`. Returns (block_text, new_scan_pos) where `new_scan_pos`
--- is where to continue scanning for more comments, or nil if no block comment was found.
-local function capture_block_comment(source, close_end_pos)
-	local  open_at = find_block_comment_open(source, close_end_pos)
-	if not open_at then return nil end
-	local block_start = extend_left_over_indent(source, open_at)
-	return source:sub(block_start, close_end_pos), block_start
-end
-
--- (internal) Capture one `// ...` line comment ending at `line_end_pos`.
--- Returns (comment_text, new_scan_pos) or nil if the line is not a `//` comment.
-local function capture_line_comment(source, line_end_pos)
-	local line_start = find_line_start(source, line_end_pos)
-	local line       = source:sub(line_start, line_end_pos)
-	if line:sub(1, 2) == "//" then
-		return line, line_start - 1
-	end
-	return nil
-end
-
 --- Find the contiguous comment block immediately preceding `pos` in `source`.
 --- Returns the comment text (with the `/* */` or `//` markers preserved) or an empty string if no comment is adjacent.
 ---
 --- Used to copy signature comments from the source declaration (`MipsAtomComp_` / `MipsAtomComp_Proc_` / function decl)
 --- over to the generated `mac_X` macro, so LSP/IntelliSense displays the args doc.
----
 --- @param source string
 --- @param pos integer
 --- @return string
@@ -254,22 +155,59 @@ local function preceding_comment_block(source, pos)
 	local scan_pos = pos
 	local pieces   = {}
 	while true do
-		local non_ws = skip_ws_backward(source, scan_pos)
-		if    non_ws == 0 then break end
+		-- Skip whitespace (space/tab/newline/CR) backward from `scan_pos`,
+		-- returning the position of the first non-whitespace char.
+		local non_ws = scan_pos - 1
+		while non_ws > 0 do
+			local ch = source:sub(non_ws, non_ws)
+			if ch == " " or ch == "\t" or ch == "\n" or ch == "\r" then
+				non_ws = non_ws - 1
+			else
+				break
+			end
+		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)
-			if not block_text then break end
-			table.insert(pieces, 1, block_text)
-			scan_pos = new_scan_pos
+			-- Find the opening `/*` for a block comment whose `*/` ends at `non_ws`.
+			-- Walk back from `non_ws` over `/*` candidates.
+			local prefix  = source:sub(1, non_ws - 1)
+			local open_at = nil
+			for scan = #prefix - 1, 1, -1 do
+				if prefix:sub(scan, scan + 1) == "/*" then
+					open_at = scan
+					break
+				end
+			end
+			if not open_at then break end
+			-- Walk back from `open_at` over leading spaces + tabs to include the indentation before the `/*`.
+			local block_start = open_at
+			while block_start > 1 do
+				local ch = source:sub(block_start - 1, block_start - 1)
+				if ch == " " or ch == "\t" then
+					block_start = block_start - 1
+				else
+					break
+				end
+			end
+			table.insert(pieces, 1, source:sub(block_start, non_ws))
+			scan_pos = block_start
 		elseif is_line_end then
-			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
+			-- Walk back from `non_ws` to the start of the source line (the most recent `\n` or position 1).
+			local line_start = non_ws
+			while line_start > 1 and source:sub(line_start - 1, line_start - 1) ~= "\n" do
+				line_start = line_start - 1
+			end
+			local line = source:sub(line_start, non_ws)
+			if line:sub(1, 2) == "//" then
+				table.insert(pieces, 1, line)
+				scan_pos = line_start - 1
+			else
+				break
+			end
 		else
 			break
 		end
@@ -282,42 +220,6 @@ 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).
--- @param trimmed string
--- @param pos integer
--- @return integer
-local function trim_trailer_back(trimmed, pos)
-	local back = pos
-	while back > 0 do
-		local ch = trimmed:sub(back, back)
-		if ch == " " or ch == "\t" or ch == "*" or ch == "]" or ch == "[" then
-			back = back - 1
-		else
-			break
-		end
-	end
-	return back
-end
-
--- Walk `trimmed` backward from `pos` over identifier chars (alnum + `_`),
--- returning the position just before the identifier starts.
--- @param trimmed string
--- @param pos integer
--- @return integer
-local function trim_ident_back(trimmed, pos)
-	local back = pos
-	while back > 0 do
-		local ch = trimmed:sub(back, back)
-		if duffle.is_alnum(ch) or ch == "_" then
-			back = back - 1
-		else
-			break
-		end
-	end
-	return back
-end
-
 --- Extract just the parameter NAMES from a function-args string (stripping type annotations). E.g.,
 ---   `"U4 off, U4 code, U1 r, U1 g, U1 b"`  ->  `{"off", "code", "r", "g", "b"}`
 ---   `"U4 *ptr"`                            ->  `{"ptr"}`
@@ -331,9 +233,29 @@ 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_start = trim_ident_back(trimmed, ident_end) + 1
-			local name        = trimmed:sub(ident_start, ident_end)
+			-- Find the identifier at the end: walk back over trailers (whitespace + `*` + `[]`),
+			-- then walk back over the identifier chars (alnum + `_`).
+			-- Plex: inlined the 2 single-caller helpers (no 2-caller rule met).
+			local ident_end = #trimmed
+			while ident_end > 0 do
+				local ch = trimmed:sub(ident_end, ident_end)
+				if ch == " " or ch == "\t" or ch == "*" or ch == "]" or ch == "[" then
+					ident_end = ident_end - 1
+				else
+					break
+				end
+			end
+			local ident_start = ident_end
+			while ident_start > 0 do
+				local ch = trimmed:sub(ident_start, ident_start)
+				if duffle.is_alnum(ch) or ch == "_" then
+					ident_start = ident_start - 1
+				else
+					break
+				end
+			end
+			ident_start = ident_start + 1
+			local name = trimmed:sub(ident_start, ident_end)
 			if name ~= "" then names[#names + 1] = name end
 		end
 	end
@@ -513,13 +435,6 @@ local function split_comment_lines(s)
 	return out
 end
 
---- Split an atom body by top-level commas; drop empty tokens.
---- @param body string
---- @return string[]
-local function tokens_from_body(body)
-	return duffle.tokenize_body_simple(body)
-end
-
 --- Determine the macro signature: function-args list (function form) or variadic-ignored (bare form).
 --- @param args_str string|nil
 --- @return string
@@ -569,7 +484,8 @@ local function build_component_lines(c, counts)
 		end
 	end
 
-	local tokens = tokens_from_body(c.body)
+	local tokens = duffle.split_top_level_commas(c.body)
+	for i = 1, #tokens do tokens[i] = duffle.trim(tokens[i]) end
 	local sig    = signature_from_args(c.args)
 	-- Direct lookup against the per-source precomputed `counts` table (built once by count_all_components).
 	local n      = counts[c.name]
@@ -605,7 +521,7 @@ local function header_boilerplate(src)
 		"// Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)",
 		"",
 		-- Self-contained: define WORD_COUNT if not already defined.
-		-- We use the same definition here so the auto-generated entries below expand 
+		-- We use the same definition here so the auto-generated entries below expand
 		-- to compile-time constants whether the metadata file is included first or not.
 		"#ifndef WORD_COUNT",
 		"#define WORD_COUNT(name, count)  enum { words_##name = (count) };",
@@ -616,7 +532,7 @@ end
 
 -- Compute the output path for one source's `.macs.h` file.
 -- The pre-rework convention uses the *directory* basename
--- (not the source file basename) — e.g. `code/duffle/lottes_tape.h` produces `code/duffle/gen/duffle.macs.h`.
+-- (not the source file basename) e.g. `code/duffle/lottes_tape.h` produces `code/duffle/gen/duffle.macs.h`.
 -- This matches what the C codebase #includes.
 -- @param src SourceFile
 -- @return string  -- the output directory

scripts/passes/offsets.lua

@@ -172,32 +172,6 @@ local function scan_for_atom_markers(token, at_pos, labels, branches)
 	end
 end
 
--- (internal) Count words emitted by the rest of `tok` after a marker call
--- (the marker call itself emits 0 words, but the source pattern may bundle the marker with the next instruction on the same line,
--- separated by no top-level comma).
--- Returns the word count contributed by that rest.
--- @param tok string
--- @param word_counts table
--- @return integer
-local function count_marker_rest(tok, word_counts)
-	-- duffle.find_marker_call_end returns the position PAST the closing `)` of the marker call
-	-- (or nil if `tok` isn't a marker call). Canonical impl in duffle.lua is faster than the
-	-- file-local copy that used to live here (byte-indexed, no `tok:sub` per char).
-	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, word_counts)
-end
-
--- (internal) Is this token a marker call (`atom_label` or `atom_offset`)?
--- @param tok string
--- @return boolean
-local function is_marker_token(tok)
-	local leading_ident = duffle.read_ident(tok, 1)
-	return leading_ident == LABEL_MARKER or leading_ident == OFFSET_MARKER
-end
-
 --- Scan an atom body for labels + branches, count total words.
 --- Returns (labels, branches, total_words).
 --- @param body string
@@ -214,10 +188,10 @@ local function scan_atom_body(body_tokens, word_counts)
 	local branches = {}
 	for _, t in ipairs(body_tokens) do
 		local tok = t.tok
-		if is_marker_token(tok) then
+		if duffle.is_marker_token(tok) then
 			-- Marker call: record at the current pos, do NOT advance pos.
 			scan_for_atom_markers(tok, pos, labels, branches)
-			pos = pos + count_marker_rest(tok, word_counts)
+			pos = pos + duffle.count_marker_rest(tok, word_counts, count_token_words)
 		else
 			local words = count_token_words(tok, word_counts)
 			scan_for_atom_markers(tok, pos, labels, branches)

scripts/passes/report.lua

@@ -16,7 +16,6 @@
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
--- Note: this boilerplate is duplicated in 6 other entry scripts; extraction target (`duffle.setup_package_path()`).
 -- Bootstrap: see `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
 -- Uses `debug.getinfo` to find this file's own directory, so it works

scripts/passes/scan_source.lua

@@ -19,9 +19,8 @@
 
 -- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
--- Uses `debug.getinfo` to find this file's own directory, so it works
--- both standalone and when require'd from the orchestrator.
--- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
+-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
+-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when required).
 -- 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")
@@ -172,6 +171,26 @@ local function push_skip_over_marker(out, marker)
 	markers[#markers + 1] = marker
 end
 
+-- Try to read `(...)` parens after `ident_end`.
+-- Returns (inner, after_paren, open_paren) on success, or (nil, fallback_pos) if no parens.
+-- `fallback_pos` defaults to `open_paren + 1` (the common "advance by 1" no-parens case).
+local function read_parens_after(source, ident_end, fallback)
+	local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
+	if source:sub(open_paren, open_paren) ~= "(" then return nil, fallback or open_paren + 1 end
+	local inner, after_paren = duffle.read_parens(source, open_paren)
+	return inner, after_paren, open_paren
+end
+
+-- Find the opening `{` of a body block and read its contents.
+-- Returns (body, after_brace, body_off) on success, or (nil, fallback_pos) on no brace.
+-- `fallback_pos` defaults to `after_paren + 1` (the common "advance by 1" case).
+local function find_body_braces(source, after_paren, fallback)
+	local brace = duffle.scan_to_char(source, "{", after_paren)
+	if not brace then return nil, fallback or (after_paren + 1) end
+	local body, after_brace = duffle.read_braces(source, brace)
+	return body, after_brace, brace + 1
+end
+
 -- Attach the pending marker to the next declaration. 
 -- The declaration form disambiguates whole atoms from components;
 -- unsupported declarations retain placement evidence for annotation.lua and populate neither lookup table.
@@ -202,30 +221,25 @@ local function associate_skip_over_marker(out, target_name, target_raw_name, tar
 	end
 end
 
--- Read a top-level comma-delimited argument list. Mirrors split_top_level_commas in shape;
--- kept inline so scan_source can remain dependency-free.
-local function read_top_level_args(text, pos)
-	local args = {}
-	pos = duffle.skip_ws_and_cmt(text, pos)
-	while pos <= #text do
-		local buf, level = {}, 0
-		while pos <= #text do
-			local c = text:sub(pos, pos)
-			if c == "(" or c == "[" or c == "{" then level = level + 1
-			elseif c == ")" or c == "]" or c == "}" then
-				if level == 0 then break end
-				level = level - 1
-			elseif c == "," and level == 0 then break end
-			buf[#buf + 1] = c
-			pos = pos + 1
-		end
-		local arg = duffle.trim(table.concat(buf))
-		if arg ~= "" then args[#args + 1] = arg end
-		if pos > #text then break end
-		if text:sub(pos, pos) == "," then pos = pos + 1; pos = duffle.skip_ws_and_cmt(text, pos) end
-		if not text:sub(pos, pos) or text:sub(pos, pos) == ")" then break end
-	end
-	return args
+-- Register a parsed atom entry in `out.atoms` and link its skip-over marker.
+-- Captures the shared 8-field shape used by MipsAtom_, MipsAtomComp_, MipsAtomComp_Proc_.
+local function register_atom(out, kind, declaration_line, name, body, body_off, raw_name, pos, after_paren)
+	out.atoms[#out.atoms + 1] = {
+		line      = declaration_line, name = name, body = body, body_off = body_off,
+		kind      = kind, raw_name = raw_name,
+		ident_pos = pos, after_paren = after_paren,
+	}
+	associate_skip_over_marker(out, name, raw_name, kind, declaration_line, pos)
+end
+
+-- Register a parsed raw-atom entry in `out.raw_atoms` and link its skip-over marker.
+-- Captures the 5-field shape used by MipsCode (the raw-atom form; offsets pass only).
+local function register_raw_atom(out, declaration_line, name, body, body_off, raw_name, pos, marker_kind)
+	out.raw_atoms[#out.raw_atoms + 1] = {
+		line = declaration_line, name = name, body = body, body_off = body_off,
+		kind = "raw_atom", raw_name = raw_name,
+	}
+	associate_skip_over_marker(out, name, raw_name, marker_kind, declaration_line, pos)
 end
 
 -- Parse a `Type*` chain (zero or more `*` separated by optional whitespace) followed by the type ident.
@@ -256,15 +270,14 @@ local BUILTIN_BYTE_SIZES = {
 	["S1"]                  = 1,
 	["S2"]                  = 2,
 	["S4"]                  = 4,
-	-- GCC __UINT*_TYPE__ family (used by the duffle TSet_ convention). TODO(Ed): Do we really need these, they shouldn't be directly used...
+	-- GCC __UINT*/__INT*_TYPE__ family (used by the duffle TSet_ convention in dsl.h).
+	-- MIPS32 has no 64-bit types; __UINT64_TYPE__/__INT64_TYPE__ are excluded.
 	["__UINT8_TYPE__"]      = 1,
 	["__UINT16_TYPE__"]     = 2,
 	["__UINT32_TYPE__"]     = 4,
-	["__UINT64_TYPE__"]     = 8,
 	["__INT8_TYPE__"]       = 1,
 	["__INT16_TYPE__"]      = 2,
 	["__INT32_TYPE__"]      = 4,
-	["__INT64_TYPE__"]      = 8,
 }
 
 -- Pointer fields collapse to 4 bytes on MIPS32 (PS1).
@@ -273,128 +286,87 @@ local POINTER_BYTE_SIZE = 4
 -- Maximum chain depth when resolving typedef / TSet_ chains (cycle guard).
 local TYPE_CHAIN_MAX_DEPTH = 8
 
--- Parse the `<type> <field>;` declarations from a Struct_ body.
--- Returns the raw fields array with `{name, type_name, pointer_depth}` only (NO offset / byte_size).
--- The propagation pass `resolve_struct_field_sizes` walks each struct's fields AFTER type resolution and populates offset + byte_size in place.
--- Returns (fields). The aggregate byte_count is computed in the propagation pass (it depends on whether every field's type resolved).
-local function parse_struct_body_fields(body)
+-- Walk a `Struct_` / `Enum_` body, calling `build_field(first, first_end, after_first)` for each entry.
+-- The builder returns either:
+--   - (record, new_pos)  -- append record to fields; advance body_pos to new_pos
+--   - (nil, new_pos)     -- skip this entry; advance body_pos to new_pos
+-- After each entry, the walker skips a single trailing `,` or `;`.
+-- The 2 body-field parsers in this file (struct + enum) share this body-walk loop.
+-- @param body string
+--- @param build_field fun(first: string, first_end: integer, after_first: integer): (table|nil, integer)
+--- @return table[]
+local function walk_body_fields(body, build_field)
 	local fields   = {}
 	local body_pos = 1
 	local body_len = #body
 	while body_pos <= body_len do
 		body_pos = duffle.skip_ws_and_cmt(body, body_pos)
 		if body_pos > body_len then break end
-		local type_ident, type_end = duffle.read_ident(body, body_pos)
-		if not type_ident then
+		local first, first_end = duffle.read_ident(body, body_pos)
+		if not first then
 			body_pos = body_pos + 1
 		else
-			-- Parse the trailing `*` chain to derive pointer_depth.
-			local depth  = 0
-			local cursor = duffle.skip_ws_and_cmt(body, type_end)
-			while cursor <= body_len and body:sub(cursor, cursor) == "*" do
-				depth  = depth + 1
-				cursor = cursor + 1
-				cursor = duffle.skip_ws_and_cmt(body, cursor)
-			end
-
-			-- Read the field ident immediately after the type chain.
-			local field_ident, field_end = duffle.read_ident(body, cursor)
-			if not field_ident then
-				body_pos = type_end + 1
-			else
-				fields[#fields + 1] = {
-					name          = field_ident,
-					type_name     = type_ident,
-					pointer_depth = depth,
-					-- offset + byte_size filled by resolve_struct_field_sizes
-					offset        = nil,
-					byte_size     = nil,
-				}
-				body_pos = field_end
+			local after_first = duffle.skip_ws_and_cmt(body, first_end)
+			local result, new_pos = build_field(first, first_end, after_first)
+			if result then fields[#fields + 1] = result end
+			body_pos = new_pos or first_end
+			-- Skip a single trailing `,` or `;`.
+			if body_pos <= body_len and (body:sub(body_pos, body_pos) == "," or body:sub(body_pos, body_pos) == ";") then
+				body_pos = body_pos + 1
 			end
 		end
 	end
 	return fields
 end
 
+-- Parse the `<type> <field>;` declarations from a Struct_ body.
+-- Returns the raw fields array with `{name, type_name, pointer_depth}` only (NO offset / byte_size).
+-- The propagation pass `resolve_struct_field_sizes` walks each struct's fields AFTER type resolution and populates offset + byte_size in place.
+-- Returns (fields). The aggregate byte_count is computed in the propagation pass (it depends on whether every field's type resolved).
+local function parse_struct_body_fields(body)
+	return walk_body_fields(body, function(type_name, type_end, after_type)
+		-- Parse the trailing `*` chain to derive pointer_depth.
+		local depth, cursor = 0, after_type
+		while cursor <= #body and body:sub(cursor, cursor) == "*" do
+			depth  = depth + 1
+			cursor = cursor + 1
+			cursor = duffle.skip_ws_and_cmt(body, cursor)
+		end
+		-- Read the field ident immediately after the type chain.
+		local field_ident, field_end = duffle.read_ident(body, cursor)
+		if not field_ident then return nil, type_end + 1 end
+		return {
+			name          = field_ident,
+			type_name     = type_name,
+			pointer_depth = depth,
+			-- offset + byte_size filled by resolve_struct_field_sizes
+			offset        = nil,
+			byte_size     = nil,
+		}, field_end
+	end)
+end
+
 -- Parse the `Enum_(<underlying>, <name>) { <body> }` body for entries.
--- Captures one field per named enumerator with the shape { name, value } value is the integer literal parsed from the source.
--- Returns the fields array (may be empty for `enum { }` shapes).
--- Self-contained integer parser (no upvalue on parse_enum_int_literal which lives further down in the file).
+-- Captures one field per named enumerator with the shape { name, value }.
+-- The value is the integer literal parsed from the source via the canonical `parse_enum_int_literal`.
 local function parse_enum_body_fields(body)
-	local fields   = {}
-	local body_pos = 1
-	local body_len = #body
-	while body_pos <= body_len do
-		body_pos = duffle.skip_ws_and_cmt(body, body_pos)
-		if body_pos > body_len then break end
-		local entry_name, name_end = duffle.read_ident(body, body_pos)
-		if not entry_name then
-			body_pos = body_pos + 1
-		else
-			local after_name = duffle.skip_ws_and_cmt(body, name_end)
-			local value
-			if body:sub(after_name, after_name) == "=" then
-				local val_pos = duffle.skip_ws_and_cmt(body, after_name + 1)
-				-- Self-contained integer literal parse (decimal, negative, hex).
-				-- Mirrors parse_enum_int_literal for the subset of shapes that appear in `typedef Enum_(...)` bodies.
-				local sign = 1
-				local p    = val_pos
-				if p <= body_len and body:sub(p, p) == "-" then
-					sign = -1
-					p    = p + 1
-				end
-				local start_digit = p
-				-- Hex form `0xNN` / `0XNN`.
-				local hex_value
-				if p + 1 <= body_len and body:sub(p, p) == "0"
-					and (body:sub(p + 1, p + 1) == "x"
-						or body:sub(p + 1, p + 1) == "X") then
-					p = p + 2
-					hex_value = 0
-					local any_hex = false
-					while p <= body_len do
-						local c = body:byte(p)
-						local d
-						if     c >= 0x30 and c <= 0x39 then d = c - 0x30
-						elseif c >= 0x61 and c <= 0x66 then d = c - 0x61 + 10
-						elseif c >= 0x41 and c <= 0x46 then d = c - 0x41 + 10
-						else break end
-						hex_value = hex_value * 16 + d
-						p         = p + 1
-						any_hex   = true
-					end
-					if any_hex then value = sign * hex_value end
-				elseif start_digit <= body_len and body:sub(start_digit, start_digit):match("[%d]") then
-					-- Decimal form.
-					local dec_value = 0
-					local any_digit = false
-					while p <= body_len do
-						local c = body:byte(p)
-						if c < 0x30 or c > 0x39 then break end
-						dec_value = dec_value * 10 + (c - 0x30)
-						p         = p + 1
-						any_digit = true
-					end
-					if any_digit then value = sign * dec_value end
-				end
-				if value ~= nil then
-					body_pos = p
-				else
-					body_pos = after_name + 1
-				end
+	return walk_body_fields(body, function(entry_name, name_end, after_name)
+		local value
+		local new_pos
+		if body:sub(after_name, after_name) == "=" then
+			local val_pos = duffle.skip_ws_and_cmt(body, after_name + 1)
+			local v, end_pos = parse_enum_int_literal(body, val_pos)
+			if v ~= nil then
+				value   = v
+				new_pos = end_pos
 			else
-				body_pos = name_end
+				new_pos = after_name + 1
 			end
-			fields[#fields + 1] = { name = entry_name, value = value }
+		else
+			new_pos = name_end
 		end
-		-- Skip past any trailing comma.
-		body_pos = duffle.skip_ws_and_cmt(body, body_pos)
-		if body_pos <= body_len and body:sub(body_pos, body_pos) == "," then
-			body_pos = body_pos + 1
-		end
-	end
-	return fields
+		return { name = entry_name, value = value }, new_pos
+	end)
 end
 
 -- Resolve a typedef chain's `byte_size` via repeated underlying_type walks.
@@ -445,7 +417,7 @@ local function propagate_type_sizes(out)
 	local reg = out.type_name_registry
 	if not reg then return end
 
-	-- Phase 1: seed builtin primitives (U1/U2/U4/S1/S2/S4 + __UINT*_TYPE__ family).
+	-- Seed builtin primitives (U1/U2/U4/S1/S2/S4 + __UINT*_TYPE__ family).
 	for name, size in pairs(BUILTIN_BYTE_SIZES) do
 		if reg[name] and reg[name].byte_size == nil then
 			reg[name].byte_size = size
@@ -559,9 +531,6 @@ end
 -- parens like `V4_S2*()`), the function still returns the leading reg_name but sets `malformed_flag = true` and `override_entry = nil`
 -- so the caller can silently drop the override while keeping the register in the reads/writes list
 -- (per the parser-safety contract — "malformed atom_type MUST NOT create any override").
---
--- The legacy `atom_rtype(...)` spelling is accepted as a transparent alias so test fixtures
--- authored against the pre-Track-A grammar continue to parse. Canonical: `atom_type`.
 local function parse_atom_info_reg_entry(entry)
 	local pos = 1
 	pos = duffle.skip_ws_and_cmt(entry, pos)
@@ -573,9 +542,8 @@ local function parse_atom_info_reg_entry(entry)
 	if pos > #entry then return reg_name, nil, false end
 
 	-- Adjacent ident must be a bare `atom_type` (word-bounded both sides).
-	-- `atom_rtype` is the legacy alias; matches silently.
 	local next_ident, next_end = duffle.read_ident(entry, pos)
-	if not next_ident or (next_ident ~= "atom_type" and next_ident ~= "atom_rtype") then
+	if not next_ident or next_ident ~= "atom_type" then
 		return reg_name, nil, false
 	end
 	-- Left word-boundary: `_atom_type` should NOT match `atom_type`.
@@ -620,15 +588,91 @@ end
 -- Returns (binds, reads, writes, view_binds, reg_overrides, ctx_atom_name, phase_label).
 -- `view_binds` is the Binds_X ident from `atom_view(Binds_X)`.
 -- `reg_overrides` is a {reg_name = {reg, type_name, pointer_depth, source_line}}
--- table populated from BOTH `atom_reg_types(R_X, <type>)` (legacy) and `atom_type(...)` sub-entries inside `atom_reads(...)` / `atom_writes(...)`.
+-- table populated from `atom_reg_types(R_X, <type>)` and `atom_type(...)` sub-entries inside `atom_reads(...)` / `atom_writes(...)`.
 -- `ctx_atom_name` is the rbind atom ident from `atom_ctx(<atom_name>)` (singular; last-write-wins).
 -- `phase_label` is the user-authored C-ident label from `atom_phase(<label>)` (singular; last-write-wins).
 -- `info_line` is the 1-based line of the enclosing `atom_info(...)` call;
 -- It is recorded as `source_line` on every override entry so downstream passes can locate the declaration.
 local function scan_atom_info_subcalls(info_inner, info_line)
-	local binds, reads, writes = nil, nil, nil
-	local view_binds, reg_overrides = nil, nil
+	local binds, reads, writes       = nil, nil, nil
+	local view_binds, reg_overrides  = nil, nil
 	local ctx_atom_name, phase_label = nil, nil
+
+	-- Per-subcall handler table. Each handler takes (sub_inner, info_line) and mutates the outer locals above.
+	-- atom_reads/atom_writes share a handler (same shape; just different output target).
+	local function rw_handler(sub_inner, info_line, kind)
+		-- The reads/writes arrays contain ONLY register idents;
+		-- the `atom_type(...)` sub-entry (when present and well-formed) is recorded as a per-atom reg_type_override.
+		local entries = duffle.split_top_level_commas(sub_inner)
+		local regs     = {}
+		for _, entry in ipairs(entries) do
+			local reg_name, override, malformed = parse_atom_info_reg_entry(entry)
+			if reg_name then
+				regs[#regs + 1] = reg_name
+				if override then
+					reg_overrides = reg_overrides or {}
+					reg_overrides[reg_name] = {
+						reg           = reg_name,
+						type_name     = override.type_name,
+						pointer_depth = override.pointer_depth,
+						source_line   = info_line,
+					}
+				end
+				-- malformed = silent: plain register still recorded; no override.
+			end
+		end
+		if kind == "atom_reads" then reads = regs else writes = regs end
+	end
+	local function ident_handler(sub_inner, info_line, out_name)
+		-- Validates the arg is a single C identifier (no commas / parens / whitespace).
+		-- Silently reject malformed args; the DWARF chain treats the field as un-set.
+		local name = duffle.read_ident(sub_inner, 1)
+		if name then
+			local after_id = duffle.skip_ws_and_cmt(sub_inner, 1 + #name)
+			if after_id > #sub_inner then
+				if     out_name == "ctx_atom_name" then ctx_atom_name = name
+				elseif out_name == "phase_label"   then phase_label   = name end
+			end
+		end
+	end
+	local function reg_types_handler(sub_inner, info_line)
+		local args = duffle.split_top_level_commas(sub_inner)
+		if not args[1] then return end
+		reg_overrides = reg_overrides or {}
+		local reg_name = duffle.trim(args[1])
+		local type_name, depth = nil, 0
+		if args[2] then
+			local parsed_name, parsed_depth = parse_type_chain(args[2], 1)
+			if parsed_name then
+				type_name, depth = parsed_name, parsed_depth
+			else
+				type_name, depth = duffle.trim(args[2]), 0
+			end
+		end
+		reg_overrides[reg_name] = {
+			reg           = reg_name,
+			type_name     = type_name,
+			pointer_depth = depth,
+			source_line   = info_line,
+		}
+	end
+	local SUBCALL_HANDLERS = {
+		-- scan: atom_bind(<Binds_X>)
+		atom_bind       = function(sub_inner)            binds = duffle.trim(sub_inner) end,
+		-- scan: atom_reads(<R_X [atom_type(<T>)], ...>)
+		atom_reads      = function(sub_inner, info_line) rw_handler(sub_inner, info_line, "atom_reads") end,
+		-- scan: atom_writes(<R_X [atom_type(<T>)], ...>)
+		atom_writes     = function(sub_inner, info_line) rw_handler(sub_inner, info_line, "atom_writes") end,
+		-- scan: atom_view(<Binds_X>)
+		atom_view       = function(sub_inner)            view_binds = duffle.trim(sub_inner) end,
+		-- scan: atom_reg_types(<R_X>, <T>)
+		atom_reg_types  = reg_types_handler,
+		-- scan: atom_ctx(<atom_name>)
+		atom_ctx        = function(sub_inner, info_line) ident_handler(sub_inner, info_line, "ctx_atom_name") end,
+		-- scan: atom_phase(<label>)
+		atom_phase      = function(sub_inner, info_line) ident_handler(sub_inner, info_line, "phase_label")   end,
+	}
+
 	local sub_pos = 1
 	while sub_pos <= #info_inner do
 		sub_pos = duffle.skip_ws_and_cmt(info_inner, sub_pos)
@@ -636,118 +680,16 @@ local function scan_atom_info_subcalls(info_inner, info_line)
 		local sub_ident, sub_end = duffle.read_ident(info_inner, sub_pos)
 		if not sub_ident then
 			sub_pos = sub_pos + 1
-		elseif sub_ident == "atom_bind" then
-			local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
-			if info_inner:sub(sub_open, sub_open) == "(" then
-				local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
-				-- scan: atom_bind(<Binds_X>)
-				binds   = duffle.trim(sub_inner)
-				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 sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
-			if info_inner:sub(sub_open, sub_open) == "(" then
-				local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
-				-- scan: atom_reads(<R_X [atom_type(<T>)], ...>)  OR atom_writes(<R_X [atom_type(<T>)], ...>)
-				-- The reads/writes arrays contain ONLY register idents;
-				-- the `atom_type(...)` sub-entry (when present and well-formed) is recorded as a per-atom reg_type_override.
-				local entries = read_top_level_args(sub_inner, 1)
-				local regs     = {}
-				for _, entry in ipairs(entries) do
-					local reg_name, override, malformed = parse_atom_info_reg_entry(entry)
-					if reg_name then
-						regs[#regs + 1] = reg_name
-						if override then
-							reg_overrides = reg_overrides or {}
-							reg_overrides[reg_name] = {
-								reg           = reg_name,
-								type_name     = override.type_name,
-								pointer_depth = override.pointer_depth,
-								source_line   = info_line,
-							}
-						end
-						-- malformed = silent: plain register still recorded; no override.
-					end
-				end
-				if kind == "atom_reads" then reads = regs else writes = regs end
-				sub_pos = sub_after2
-			else
-				sub_pos = sub_open + 1
-			end
-		elseif sub_ident == "atom_view" then
-			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)
-				view_binds = duffle.trim(sub_inner)
-				sub_pos    = sub_after2
-			else
-				sub_pos = sub_open + 1
-			end
-		elseif sub_ident == "atom_reg_types" then
-			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)
-				local args = read_top_level_args(sub_inner, 1)
-				if args[1] then
-					reg_overrides = reg_overrides or {}
-					local reg_name = duffle.trim(args[1])
-					local type_name, depth = nil, 0
-					if args[2] then
-						local parsed_name, parsed_depth = parse_type_chain(args[2], 1)
-						if parsed_name then
-							type_name, depth = parsed_name, parsed_depth
-						else
-							type_name, depth = duffle.trim(args[2]), 0
-						end
-					end
-					reg_overrides[reg_name] = {
-						reg           = reg_name,
-						type_name     = type_name,
-						pointer_depth = depth,
-						source_line   = info_line,
-					}
-				end
-				sub_pos = sub_after2
-			else
-				sub_pos = sub_open + 1
-			end
-		elseif sub_ident == "atom_ctx" then
-			-- scan: atom_ctx(<atom_name>)
-			-- The argument must be a single C identifier (no commas, no parens, no whitespace inside).
-			-- Anything else is silently rejected (no `ctx_atom_name` is set) so the DWARF chain falls through.
-			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)
-				local name = duffle.read_ident(sub_inner, 1)
-				if name then
-					local after_id = duffle.skip_ws_and_cmt(sub_inner, 1 + #name)
-					if after_id > #sub_inner then ctx_atom_name = name end
-				end
-				sub_pos = sub_after2
-			else
-				sub_pos = sub_open + 1
-			end
-		elseif sub_ident == "atom_phase" then
-			-- scan: atom_phase(<label>)
-			-- The argument is a free-form C identifier label (atomic single ident; no commas / parens / whitespace inside).
-			-- Silently reject malformed args; the DWARF chain treats the atom as un-grouped.
-			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)
-				local name = duffle.read_ident(sub_inner, 1)
-				if name then
-					local after_id = duffle.skip_ws_and_cmt(sub_inner, 1 + #name)
-					if after_id > #sub_inner then phase_label = name end
-				end
-				sub_pos = sub_after2
-			else
-				sub_pos = sub_open + 1
-			end
 		else
-			sub_pos = sub_end
+			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)
+				local handler = SUBCALL_HANDLERS[sub_ident]
+				if handler then handler(sub_inner, info_line) end
+				sub_pos = sub_after2
+			else
+				sub_pos = sub_open + 1
+			end
 		end
 	end
 	return binds, reads, writes, view_binds, reg_overrides, ctx_atom_name, phase_label
@@ -767,7 +709,7 @@ end
 -- Track A helpers: enum / atom_reg / R_*_Code parsing
 -- ════════════════════════════════════════════════════════════════════════════
 --
--- The Track A parser walks `enum { <body> }` declarations and emits one AliasEntry per R_* entry whose value is followed by a bare `atom_reg` token.
+-- The parser walks `enum { <body> }` declarations and emits one AliasEntry per R_* entry whose value is followed by a bare `atom_reg` token.
 -- Value resolution handles decimal/negative/hex literals and `R_*_Code` symbol references; 
 -- symbol references resolve via the cross-source `_code_macros` registry built in two passes by `M.run`.
 
@@ -1027,7 +969,7 @@ local function parse_enum_atom_type_default(body, pos)
 	if pos > #body then return nil, 0, pos end
 	-- Bare `atom_type` word with word-bounding on both sides.
 	local ident, ident_end = duffle.read_ident(body, pos)
-	if ident ~= "atom_type" and ident ~= "atom_rtype" then return nil, 0, pos end
+	if ident ~= "atom_type" then return nil, 0, pos end
 	if pos > 1 then
 		local prev = body:byte(pos - 1)
 		if duffle.is_alnum_byte(prev) then return nil, 0, pos end
@@ -1075,17 +1017,19 @@ end
 -- Adding a new construct = 1 row in DECL_PARSERS + 1 parser function. The scan_source() loop never needs editing.
 
 --- Parse an empty debug-skip marker and retain its raw placement evidence.
+--- The marker_kind is the source ident itself (e.g. `atom_dbg_skip_over`).
+--- The dispatch table maps each ident to this same function;
+--- the marker_kind is derived from the source so future idents route through the same row.
 --- @param source string
 --- @param pos integer
 --- @param ident_end integer
 --- @param line_of fun(pos: integer): integer
 --- @param out SourceScan
---- @param marker_kind string
 --- @return integer
-local function parse_skip_over_marker(source, pos, ident_end, line_of, out, marker_kind)
+local function parse_skip_over_marker(source, pos, ident_end, line_of, out)
 	local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
 	local marker = {
-		marker_kind  = marker_kind,
+		marker_kind  = source:sub(pos, ident_end - 1),
 		marker_line  = line_of(pos),
 		marker_pos   = pos,
 		after_paren  = ident_end,
@@ -1102,17 +1046,12 @@ local function parse_skip_over_marker(source, pos, ident_end, line_of, out, mark
 	return marker.after_paren
 end
 
-local function parse_atom_dbg_skip_over(source, pos, ident_end, line_of, out)
-	return parse_skip_over_marker(source, pos, ident_end, line_of, out, "atom_dbg_skip_over")
-end
-
 -- Parse `atom_dbg_reg_default(R_X, <type>...)`;
 -- the second argument may be a `Type` or `Type*`/`Type**` chain. Records in `out.types[R_X]`.
 local function parse_atom_dbg_reg_default(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 args = read_top_level_args(inner, 1)
+	local inner, after_paren = read_parens_after(source, ident_end)
+	if not inner then return after_paren end
+	local args = duffle.split_top_level_commas(inner)
 	if #args < 1 then
 		-- Annotation pass surfaces this; we still consume the marker.
 		return after_paren
@@ -1144,9 +1083,8 @@ end
 --- @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 inner, after_paren, open_paren = read_parens_after(source, ident_end)
+	if not inner then return after_paren end
 
 	local raw_name = duffle.read_ident(inner, 1)
 
@@ -1198,18 +1136,10 @@ local function parse_mips_atom(source, pos, ident_end, line_of, out)
 		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)
+	local body, after_brace, body_off = find_body_braces(source, brace_search_pos, open_paren + 1)
+	if not body then return after_brace end
 	if raw_name and raw_name ~= "" then
-		local declaration_line = line_of(pos)
-		out.atoms[#out.atoms + 1] = {
-			line        = declaration_line, name = raw_name, body = body, body_off = brace + 1,
-			kind        = "atom", raw_name = raw_name,
-			ident_pos   = pos, after_paren = after_paren,
-		}
-		associate_skip_over_marker(out, raw_name, raw_name, "atom", declaration_line, pos)
+		register_atom(out, "atom", line_of(pos), raw_name, body, body_off, raw_name, pos, after_paren)
 	end
 
 	return after_brace
@@ -1223,26 +1153,16 @@ end
 --- @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 inner, after_paren, open_paren = read_parens_after(source, ident_end)
+	if not inner then return after_paren end
 
 	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)
-	local name              = strip_ac_prefix(raw_name)
-	local declaration_line  = line_of(pos)
-
-	out.atoms[#out.atoms + 1] = {
-		line        = declaration_line, name = name, body = body, body_off = brace + 1,
-		kind        = "comp_bare", raw_name = raw_name,
-		ident_pos   = pos, after_paren = after_paren,
-	}
-	associate_skip_over_marker(out, name, raw_name, "comp_bare", declaration_line, pos)
+	local body, after_brace, body_off = find_body_braces(source, after_paren, open_paren + 1)
+	if not body then return after_brace end
+	local name = strip_ac_prefix(raw_name)
+	register_atom(out, "comp_bare", line_of(pos), name, body, body_off, raw_name, pos, after_paren)
 
 	return after_brace
 end
@@ -1255,9 +1175,8 @@ end
 --- @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)
+	local inner, after_paren, open_paren = read_parens_after(source, ident_end)
+	if not inner then return after_paren end
 
 	-- Find the LAST `{` in inner (the body brace, not any potential embedded braces in expressions).
 	local last_brace_pos = nil
@@ -1274,16 +1193,10 @@ local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
 
 	local raw_name = inner:match("^%s*([%w_]+)") or "?"
 	local name = strip_ac_prefix(raw_name)
-	local declaration_line = line_of(pos)
 	-- 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      = declaration_line, name = name, body = body, body_off = body_off,
-		kind      = "comp_proc", raw_name = raw_name,
-		ident_pos = pos, after_paren = after_paren,
-	}
-	associate_skip_over_marker(out, name, raw_name, "comp_proc", declaration_line, pos)
+	register_atom(out, "comp_proc", line_of(pos), name, body, body_off, raw_name, pos, after_paren)
 
 	return after_paren
 end
@@ -1303,16 +1216,9 @@ local function parse_mips_code(source, pos, ident_end, line_of, out)
 	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)
-	local declaration_line = line_of(pos)
-	out.raw_atoms[#out.raw_atoms + 1] = {
-		line = declaration_line, name = atom_name, body = body, body_off = brace_pos + 1,
-		kind = "raw_atom", raw_name = atom_name,
-	}
-	associate_skip_over_marker(out, atom_name, next_ident, "unrelated", declaration_line, pos)
+	local body, after_brace, body_off = find_body_braces(source, next_after, ident_end)
+	if not body then return after_brace end
+	register_raw_atom(out, line_of(pos), atom_name, body, body_off, atom_name, pos, "unrelated")
 
 	return after_brace
 end
@@ -1425,16 +1331,12 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
 
 	-- ── Shape 1: `typedef Struct_(<name>) { <body> } <alias>;` ────────────
 	if id2 == "Struct_" then
-		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 inner, after_paren, open_paren = read_parens_after(source, id2_end, id2_end)
+		if not inner then return id2_end end
 		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)
+		local body, after_brace = find_body_braces(source, after_paren, open_paren + 1)
+		if not body then return after_brace end
 		register_struct_type(body, name, pos, line_of, out)
 		associate_skip_over_marker(out, name, name, "unrelated", line_of(pos), pos)
 		return after_brace
@@ -1442,20 +1344,16 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
 
 	-- ── Shape 2: `typedef Enum_(<underlying>, <name>) { <body> } <alias>;`
 	if id2 == "Enum_" then
-		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 inner, after_paren, open_paren = read_parens_after(source, id2_end, id2_end)
+		if not inner then return id2_end end
 		-- Split `inner` on the first top-level comma into (<underlying>, <name>).
-		local args = read_top_level_args(inner, 1)
+		local args = duffle.split_top_level_commas(inner)
 		if   #args < 2 then return after_paren end
 		local underlying = duffle.trim(args[1])
 		local name       = duffle.trim(args[2])
 
-		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)
+		local body, after_brace = find_body_braces(source, after_paren, open_paren + 1)
+		if not body then return after_brace end
 		register_enum_type(underlying, name, body, pos, line_of, out)
 		associate_skip_over_marker(out, name, name, "unrelated", line_of(pos), pos)
 		return after_brace
@@ -1470,9 +1368,8 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
 
 	-- Shape 4: `typedef <type> TSet_(<name>);`
 	if id3 == "TSet_" then
-		local open_paren = duffle.skip_ws_and_cmt(source, id3_end)
-		if source:sub(open_paren, open_paren) ~= "(" then return id3_end end
-		local tset_inner, tset_after = duffle.read_parens(source, open_paren)
+		local tset_inner, tset_after = read_parens_after(source, id3_end, id3_end)
+		if not tset_inner then return id3_end end
 		local tset_name = duffle.trim(tset_inner)
 		register_typedef_alias(id2, tset_name, pos, line_of, out)
 		associate_skip_over_marker(out, tset_name, tset_name, "unrelated", line_of(pos), pos)
@@ -1493,10 +1390,8 @@ end
 --- @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)
+	local str, str_end = read_parens_after(source, ident_end)
+	if not str then return str_end end
 	str = duffle.trim(str)
 	if str:sub(1, 1) ~= '"' or str:sub(-1) ~= '"' then return str_end end
 
@@ -1561,12 +1456,11 @@ local function parse_enum_value(body, pos, out)
 	return nil, pos
 end
 
--- Walk one enum entry: read value, check for bare `atom_reg`,
--- and (if both are present and the name starts with `R_`) write an AliasEntry into `out.register_alias_registry`.
+-- Walk one enum entry: read value, check for bare `atom_reg`, and
+-- (if both are present and the name starts with `R_`) write an AliasEntry into `out.register_alias_registry`.
 -- If `atom_reg` is followed by an adjacent `atom_type(<T>)`, the parsed T is stored on the AliasEntry
 -- as `default_type` (type_name + pointer_depth). Silent if `atom_type(...)` is malformed.
--- Returns the new byte position within `body` (advanced past `atom_type(...)` if well-formed, past `atom_reg` alone,
--- or past the value if neither was present).
+-- Returns the new byte position within `body` (advanced past `atom_type(...)` if well-formed, past `atom_reg` alone, or past the value if neither was present).
 local function parse_enum_entry(source, body, body_offset, line_of, out, entry_name, name_body_pos, value_start)
 	-- value_start is within `body`, just past the `=`.
 	local after_ws = duffle.skip_ws_and_cmt(body, value_start)
@@ -1662,11 +1556,9 @@ local function parse_enum(source, pos, ident_end, line_of, out)
 	end
 
 	-- Find the opening brace of the enum body.
-	local  brace_pos = duffle.scan_to_char(source, "{", after_ident)
-	if not brace_pos then return ident_end end
-
-	local body, after_brace = duffle.read_braces(source, brace_pos)
-	parse_enum_body(source, body, brace_pos + 1, line_of, out)
+	local body, after_brace, body_off = find_body_braces(source, after_ident, ident_end)
+	if not body then return after_brace end
+	parse_enum_body(source, body, body_off, line_of, out)
 
 	return after_brace
 end
@@ -1674,7 +1566,6 @@ 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
 --
@@ -1684,7 +1575,7 @@ local DECL_PARSERS = {
 	MipsAtom_                  = parse_mips_atom,
 	MipsAtomComp_              = parse_mips_atom_comp,
 	MipsAtomComp_Proc_         = parse_mips_atom_comp_proc,
-	atom_dbg_skip_over         = parse_atom_dbg_skip_over,
+	atom_dbg_skip_over         = parse_skip_over_marker,
 	atom_dbg_reg_default       = parse_atom_dbg_reg_default,
 	MipsCode                   = parse_mips_code,
 	typedef                    = parse_typedef_binds,
@@ -1813,7 +1704,7 @@ local M = {}
 --- Walk each source once and attach the fat SourceScan payload to `src.scan`.
 --- No output files; this is a pure in-memory pre-processing pass.
 ---
---- Track A: runs in 3 phases.
+--- Runs in 3 phases.
 ---   Pass 1a: `scan_source_pre_pass` over every source, populating the cross-source `ctx.shared._code_macros` AND `ctx.shared._code_macro_bodies` registries.
 ---             The bodies table holds the raw post-`=` text of every `#define R_*_Code` line (cross-source) so the chain walker can fall back when a 
 ---             sdefining `#define` lives in a different source than the chain call site.

scripts/passes/static_analysis.lua

@@ -11,8 +11,8 @@
 ---     5. **per-atom cycle budget** — sum each atom body's instruction latencies (per `duffle.INSTRUCTION_LATENCY`); report total.
 ---   Per-source rules (registry-driven, added 2026-07-16):
 ---     6. **enum_alias_membership** — every `R_X` referenced from `atom_dbg_reg_default`, `atom_reg_types`,
----        `atom_rtype(...)`, `atom_reads`, or `atom_writes` must be in `scan.register_alias_registry`. Missing -> warning.
----     7. **atom_rtype_consistency** — every `reg_type_overrides[R_X].type_name` must resolve in `scan.type_name_registry`. Missing -> error.
+---        `atom_type(...)`, `atom_reads`, or `atom_writes` must be in `scan.register_alias_registry`. Missing -> warning.
+---     7. **atom_type_consistency** — every `reg_type_overrides[R_X].type_name` must resolve in `scan.type_name_registry`. Missing -> error.
 ---     8. **binds_no_substruct_deref** — every `load_word(R_A, R_B, O_(Type, Field))` and `store_word(...)` in every atom body
 ---        must reference a leaf scalar (pointer-to-struct counts as leaf; nested struct members do NOT). Missing -> warning (build continues).
 ---     9. **reads_writes_alias_membership** — distinct check name duplicating #6's reads/writes coverage so the report can
@@ -92,8 +92,7 @@ local OUTPUT_EXTENSION = ".static_analysis.txt"
 --- @field errors   table[]
 --- @field warnings table[]
 
---- @alias AtomName    string  -- lower_snake_case atom name
---- @alias MacroName   string  -- lower_snake_case macro identifier
+--- @alias AtomName    string  -- lower_snake_case atom nameMacroName   string  -- lower_snake_case macro identifier
 --- @alias CheckName   string  -- "gte_pipeline_fill" | "mac_yield_uniformity" | "abi_handoff" | "gpu_port_store_shape" | "per_atom_cycle_budget"
 
 --- @class AtomBody
@@ -709,7 +708,6 @@ local function analyze_atom_paths(atom)
 	-- Mutate the pre-allocated `atom.paths` slot in place (caller owns the table).
 	-- Mega-struct move: a single source of truth for all per-atom path-analysis data,
 	-- instead of returning a fresh table that would just get copied onto 5 atom fields.
-	-- If a caller ever DIDN'T pre-allocate (legacy code path), fall back to a fresh slot.
 	local p = atom.paths or {}
 	p.cycles_min     = cycles_min
 	p.cycles_max     = cycles_max
@@ -742,10 +740,10 @@ local function check_per_atom_cycle_budget(atom, pipe_ctx, findings)
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Check #6: enum_alias_membership (Track A Task 13)
+-- Check #6: enum_alias_membership
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Every R_X referenced from a debug-visible surface — atom_dbg_reg_default, atom_reg_types, atom_rtype sub-entries, atom_reads, atom_writes;
+-- Every R_X referenced from a debug-visible surface — atom_dbg_reg_default, atom_reg_types, atom_type sub-entries, atom_reads, atom_writes;
 -- MUST be present in `pipe_ctx.register_alias_registry`.
 -- The registry is the source-derived answer to "is this R_X a real, opt-in alias?"
 -- (populated by scan_source's `parse_enum_aliases` from `enum { R_X = N atom_reg }` declarations).
@@ -777,7 +775,7 @@ local function check_enum_alias_membership(_src, pipe_ctx, findings)
 		end
 	end
 
-	-- (b) atom_reg_types(R_X, T) + (c) atom_rtype(R_X, T) sub-entries both populate `ai.reg_type_overrides` (Track A Task 5 merge).
+	-- (b) atom_reg_types(R_X, T) + (c) atom_type(R_X, T) sub-entries both populate `ai.reg_type_overrides`.
 	--     (d) atom_reads(R_X) + (e) atom_writes(R_X) populate the reads/writes arrays.
 	--     All four are checked against the same registry; the per-rule dispatch iterates `ai` once and covers all three locations
 	--     so we don't re-walk atom_infos for each sub-check.
@@ -823,17 +821,16 @@ local function check_enum_alias_membership(_src, pipe_ctx, findings)
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Check #7: atom_type_consistency (Track A Task 13; legacy alias atom_rtype_consistency)
+-- Check #7: atom_type_consistency
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- Every `reg_type_overrides[R_X].type_name` (populated by BOTH `atom_reg_types(R_X, <type>)`
--- and `atom_type(R_X, <type>)` sub-entries inside atom_reads/atom_writes — legacy `atom_rtype` is
--- accepted as a transparent alias) MUST resolve to a `type_name_registry` entry.
+-- and `atom_type(R_X, <type>)` sub-entries inside atom_reads/atom_writes) MUST resolve to a `type_name_registry` entry.
 -- The registry is the source-derived answer to "is this type name declared in this translation unit?"
 -- (populated by `typedef Struct_(...)`, `typedef Enum_(...)`, `typedef ... TSet_(...)` declarations).
 -- Missing type names are errors (the build stops) so the user adds the typedef before re-running.
 -- Per-source rule.
-local function check_atom_rtype_consistency(_src, pipe_ctx, findings)
+local function check_atom_type_consistency(_src, pipe_ctx, findings)
 	local type_registry = pipe_ctx.type_name_registry or {}
 	for _, ai in ipairs(pipe_ctx.atom_infos_list or {}) do
 		local info_line = ai.info_line or 0
@@ -843,7 +840,7 @@ local function check_atom_rtype_consistency(_src, pipe_ctx, findings)
 				if not ov.type_name or not type_registry[ov.type_name] then
 					findings[#findings + 1] = {
 						atom  = atom_name, line = info_line,
-						check = "atom_rtype_consistency", kind = "error",
+						check = "atom_type_consistency", kind = "error",
 						msg   = string.format(
 							"atom '%s' at line %d reg_type_overrides[%q] uses unknown type %q (not in type_name_registry)",
 							atom_name, info_line, reg, tostring(ov.type_name)),
@@ -855,7 +852,7 @@ local function check_atom_rtype_consistency(_src, pipe_ctx, findings)
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Check #8: binds_no_substruct_deref (Track A Task 13)
+-- Check #8: binds_no_substruct_deref
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- For every `load_word(R_A, R_B, O_(<Type>, <Field>))` and matching `store_word(...)` call in every atom body,
@@ -945,7 +942,7 @@ local function check_binds_no_substruct_deref(_src, pipe_ctx, findings)
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
--- Check #9: reads_writes_alias_membership (Track A Task 13)
+-- Check #9: reads_writes_alias_membership
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- For every `atom_reads(R_X)` and `atom_writes(R_X)` entry in every `atom_infos` entry, the `R_X` MUST be present in `pipe_ctx.register_alias_registry`.
@@ -1005,7 +1002,7 @@ local CHECK_RULES = {
 	{ name = "gpu_portstore_shape",          per_atom   = check_gpu_portstore_shape          },
 	{ name = "per_atom_cycle_budget",        per_atom   = check_per_atom_cycle_budget        },
 	{ name = "enum_alias_membership",        per_source = check_enum_alias_membership        },
-	{ name = "atom_rtype_consistency",       per_source = check_atom_rtype_consistency       },
+	{ name = "atom_type_consistency",        per_source = check_atom_type_consistency        },
 	{ name = "binds_no_substruct_deref",     per_source = check_binds_no_substruct_deref     },
 	{ name = "reads_writes_alias_membership",per_source = check_reads_writes_alias_membership},
 }

scripts/passes/word_count_eval.lua

@@ -15,7 +15,6 @@
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
--- Note: this boilerplate is duplicated in 6 other entry scripts; extraction target (`duffle.setup_package_path()`).
 -- Bootstrap: see `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
 -- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
@@ -28,9 +27,6 @@ local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Windows separator char — used by `fname:match` to recognize `.macs.h` files.
-local PATH_SEP_BACKSLASH = "\\"
-
 -- 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.

scripts/ps1_meta.lua

@@ -17,10 +17,25 @@
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 
--- Bootstrap: load `duffle_paths.lua` via `arg[0]` (this script's own path).
--- That single statement: (a) sets `package.path` + `package.cpath` (via cached `git rev-parse`),
--- (b) at the bottom returns `require("duffle")`. So the dofile's return value is the duffle module.
-local duffle = dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
+-- Bootstrap: load `duffle_paths.lua` via this script's own path.
+-- Use `arg[0]` when this file is the entry script (`arg[0]` ends in
+-- "ps1_meta.lua"); fall back to `debug.getinfo(1, "S").source` when this
+-- file is being dofile()'d or require()'d (in which case `arg[0]` is the
+-- *caller's* path, not ours).
+--
+-- That single statement: (a) sets `package.path` + `package.cpath`
+-- (via cached `git rev-parse`), (b) at the bottom returns `require("duffle")`.
+-- So the dofile's return value is the duffle module.
+local _is_entry_script = arg and arg[0] and arg[0]:match("ps1_meta%.lua$") ~= nil
+local _bootstrap_src
+if _is_entry_script then
+	_bootstrap_src = arg[0]
+else
+	-- debug.getinfo(1, "S").source returns "@<path>" for the current chunk;
+	-- strip the leading "@" so the directory match works in both cases.
+	_bootstrap_src = debug.getinfo(1, "S").source:sub(2)
+end
+local duffle = dofile((_bootstrap_src:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
@@ -49,6 +64,8 @@ local PASS_FLAG_DISPATCH_KEY   = "__pass__"
 --- @field module string       -- module name passed to require()
 --- @field kind   string       -- "shared" | "header-output" | "validation" | "report"
 --- @field deps   string[]     -- names of upstream passes
+--- @field groups string[]?    -- OPTIONAL build-phase groups this pass is a root of
+---                             -- (e.g. { "pre-link" }, { "post-link" }); absent ⇒ dependency-only
 --- @field desc   string       -- human description (used by --help + ASCII graph)
 --- @field out    PassOutput[] -- output paths (used by --dry-run + report)
 
@@ -100,18 +117,26 @@ local PASS_FLAG_DISPATCH_KEY   = "__pass__"
 -- PASSES table (data, not code) — the orchestrator's dep graph
 -- ════════════════════════════════════════════════════════════════════════════
 
+-- Build-phase groups: each PASSES row may declare membership in one or more
+-- named groups via `groups = { ... }`. The CLI flags --pre-link and
+-- --post-link request the *roots* of their group; topo_sort then closes
+-- transitive dependencies from those roots, and dispatch_passes runs every
+-- pass in the resulting closure without phase-filtering.
+--
+-- A row without a `groups` entry is dependency-only: it runs only when a
+-- transitive dep requests it, but it remains directly requestable through
+-- its explicit CLI flag (e.g. --atoms-source-map, --scan-source).
+
 local PASSES = {
 	["scan-source"] = {
 		module = "passes.scan_source",
-		kind   = "shared",
-		deps   = {},
+		kind   = "shared", deps = {},
 		desc   = "Walk each source once; produce the fat SourceScan payload for downstream passes",
 		out    = {},
 	},
 	["word-counts"] = {
 		module = "passes.word_count_eval",
-		kind   = "shared",
-		deps   = {},
+		kind   = "shared", deps = {},
 		desc   = "Build the shared metadata table (metadata.h + .macs.h)",
 		out    = {},
 	},
@@ -136,6 +161,7 @@ local PASSES = {
 		module = "passes.offsets",
 		kind   = "header-output",
 		deps   = {"scan-source", "word-counts", "components"},
+		groups = { "pre-link" },
 		desc   = "Compute branch offsets for atom_label / atom_offset",
 		out    = { { kind = "header", path_template = "<source_dir>/gen/<basename>.offsets.h" } },
 	},
@@ -143,7 +169,7 @@ local PASSES = {
 		module = "passes.static_analysis",
 		kind   = "validation",
 		deps   = {"scan-source", "word-counts", "components"},
-		desc   = "[FUTURE] GTE pipeline-fill, mac_yield uniformity, etc.",
+		desc   = "Static analysis: GTE pipeline-fill, mac_yield uniformity, ABI handoff, GPU port-store shape, per-atom cycle budget, type consistency",
 		out    = { { kind = "report", path_template = "<out_root>/<basename>.static_analysis.txt" } },
 	},
 	["atoms-source-map"] = {
@@ -160,6 +186,7 @@ local PASSES = {
 		module = "passes.dwarf_injection",
 		kind   = "shared",
 		deps   = {"scan-source", "atoms-source-map"},
+		groups = { "post-link" },
 		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 plus one deterministic .gdbinit sidecar). (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"     },
@@ -176,11 +203,56 @@ local PASSES = {
 		module = "passes.report",
 		kind   = "report",
 		deps   = {"annotation", "static-analysis"},
+		groups = { "pre-link" },
 		desc   = "Render the per-project summary",
 		out    = { { kind = "report", path_template = "<out_root>/annotation_validation.txt" } },
 	},
 }
 
+-- ────────────────────────────────────────────────────────────────────────────
+-- Phase-root selection: derive the sorted set of roots belonging to a named
+-- build-phase group, then append them to `args.requested_set`. topo_sort
+-- closes the transitive deps from there; dispatch_passes runs every resolved
+-- pass without phase-filtering.
+-- ────────────────────────────────────────────────────────────────────────────
+
+--- @param group_name string  -- the build-phase group ("pre-link" | "post-link")
+--- @return string[]          -- sorted root pass names belonging to that group
+local function roots_for_group(group_name)
+	local names = {}
+	for name, pass in pairs(PASSES) do
+		if pass.groups then
+			for _, g in ipairs(pass.groups) do
+				if g == group_name then
+					names[#names + 1] = name
+					break
+				end
+			end
+		end
+	end
+	table.sort(names)
+	return names
+end
+
+--- Append every root belonging to `group_name` to `args.requested_set`.
+--- Errors loudly if no PASSES row declares the group, so a typo'd or
+--- future-removed group name cannot silently fall through to pre-link
+--- (or any other default) and dispatch nothing.
+--- @param args ParsedArgs
+--- @param group_name string
+local function request_roots_for_group(args, group_name)
+	local roots = roots_for_group(group_name)
+	if #roots == 0 then
+		error(string.format(
+			"ps1_meta: build-phase group %q has zero roots in PASSES; "
+			.. "check PASSES rows for a `groups = { %q }` field",
+			group_name, group_name))
+	end
+	for _, name in ipairs(roots) do
+		args.requested_set[#args.requested_set + 1] = name
+	end
+end
+
 -- Pass-kind taxonomy: which kinds stop the build on errors?
 local PASS_KIND_STOP_ON_ERROR = {
 	["shared"]        = false,
@@ -190,6 +262,13 @@ local PASS_KIND_STOP_ON_ERROR = {
 }
 
 -- Closed set of CLI flags -> pass names.
+-- Per-pass flags (e.g. --word-counts) live here; phase flags (--pre-link,
+-- --post-link, --all) live in FLAG_HANDLERS because they own side effects
+-- or invoke group-derivation logic. --dwarf-injection is *also* a per-pass
+-- opt-in flag, but its selection + opt-in state are both owned by the
+-- explicit FLAG_HANDLERS entry below (it sets args.flags.dwarf_injection
+-- and appends "dwarf-injection" to requested_set), so it is intentionally
+-- absent from this table.
 local PASS_FLAG_TO_NAME = {
 	["--word-counts"]       = "word-counts",
 	["--components"]        = "components",
@@ -197,35 +276,27 @@ local PASS_FLAG_TO_NAME = {
 	["--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",
-	"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.
+--- Append every pass name to args.requested_set. Names are derived from
+--- PASSES (no parallel name list); used by --all and by any caller that
+--- wants the full closure.
 --- @param args ParsedArgs
 local function request_all_passes(args)
-	for _, n in ipairs(ALL_PASS_NAMES) do
+	local names = {}
+	for name in pairs(PASSES) do names[#names + 1] = name end
+	table.sort(names)
+	for _, n in ipairs(names) do
 		args.requested_set[#args.requested_set + 1] = n
 	end
 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.
+-- 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 = {}
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -240,16 +311,28 @@ ps1_meta.lua - Tape-atom metaprogram orchestrator
 USAGE:
   ps1_meta.lua [PASS_FLAGS] [COMMON_FLAGS]
 
-PASS_FLAGS (pick one or more, or use --all):
-  --word-counts         Load metadata.h + scan for existing .macs.h
-  --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)
+PASS_FLAGS:
+  Pick a phase or one-or-more individual passes:
+    --pre-link            [phase; default] Run the pre-link group + transitive deps.
+                         The root set is data-driven from each PASSES row's
+                         `groups` field; no parallel name list is maintained.
+    --post-link           [phase] Run the post-link group + transitive deps.
+                         Requires --elf. Sets --gdb-runtime and --dwarf-injection
+                         opt-in flags as well.
+    --all                 Select every row of the PASSES table. Pass-local opt-in
+                         guards remain active, so --dwarf-injection still requires
+                         --elf and --gdb-runtime still requires a runtime emission.
+  Or pick any subset:
+    --scan-source         Scan sources into the fat SourceScan payload
+    --word-counts         Load metadata.h + scan for existing .macs.h
+    --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     [opt-in] Select the post-link dwarf-injection pass + set the
+                         opt-in flag. Requires --elf.
+    --static-analysis     Static analysis: GTE pipeline-fill, mac_yield, ABI handoff, cycle budget
+    --report              Render per-project summary
 
 COMMON_FLAGS:
   --source FILE         Source file to process (repeatable)
@@ -257,7 +340,6 @@ COMMON_FLAGS:
   --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
@@ -269,7 +351,9 @@ EXIT CODES:
   2  Metaprogram internal error
 
 EXAMPLE:
-  ps1_meta.lua --all --metadata metadata.h --source code/foo.c --source code/bar.c
+  ps1_meta.lua --pre-link  --metadata metadata.h --source code/foo.c --source code/bar.c
+  ps1_meta.lua --post-link --metadata metadata.h --source code/foo.c --source code/bar.c --elf build/hello_gte.elf
+  ps1_meta.lua --all       --metadata metadata.h --source code/foo.c --source code/bar.c
 ]])
 end
 
@@ -292,16 +376,35 @@ FLAG_HANDLERS["--out-root"]     = function(args, argv, arg_idx) args.out_root
 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).
+-- 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
+-- Enable DWARF injection (default OFF). Opts in to the post-link pass and
+-- sets the flag in one shot — the explicit handler below owns both
+-- selection and opt-in state, so --dwarf-injection is intentionally absent
+-- from PASS_FLAG_TO_NAME.
 FLAG_HANDLERS["--dwarf-injection"] = function(args)
-	args.flags = args.flags or {}
+	args.flags                 = args.flags or {}
 	args.flags.dwarf_injection = true
 	args.requested_set[#args.requested_set + 1] = "dwarf-injection"
 end
+-- Build-phase flags: --pre-link and --post-link request the roots of their
+-- declared groups (see roots_for_group). topo_sort closes transitive deps
+-- from those roots; dispatch_passes runs every pass in the resolved
+-- closure without phase-filtering.
+FLAG_HANDLERS["--pre-link"] = function(args)
+	request_roots_for_group(args, "pre-link")
+end
+-- Batch post-link phase: gdb-runtime + dwarf-injection in one luajit cold
+-- start. Sets the same opt-in flags as --gdb-runtime + --dwarf-injection
+-- and selects the post-link build-phase group.
+-- --elf is required; parse_args enforces it after all flags are parsed.
+FLAG_HANDLERS["--post-link"]      = function(args)
+	args.flags = args.flags or {}
+	args.flags.gdb_runtime     = true
+	args.flags.dwarf_injection = true
+	request_roots_for_group(args, "post-link")
+end
 
 -- G' (atom locals) is now consolidated into --dwarf-injection; no separate flag.
 
@@ -345,8 +448,10 @@ local function parse_args(argv)
 		pos = pos + 1
 	end
 
-	-- Default: --all if no explicit pass flags.
-	if #args.requested_set == 0 then request_all_passes(args) end
+	-- Default: --pre-link if no explicit pass flags were given. The first
+	-- invocation of a build is always pre-link, so this avoids silently
+	-- also invoking post-link work in builds without an ELF artifact.
+	if #args.requested_set == 0 then request_roots_for_group(args, "pre-link") end
 
 	-- Defaults: project_root = dirname(metadata).
 	if args.metadata and not args.project_root then
@@ -366,6 +471,20 @@ local function parse_args(argv)
 		os.exit(EXIT_INTERNAL_ERROR)
 	end
 
+	-- Post-link opt-ins (--gdb-runtime, --dwarf-injection) write output that
+	-- depends on the linked ELF. Without --elf the metaprogram can't satisfy
+	-- those requests, so refuse loud and early. This covers the explicit
+	-- --post-link batch, --dwarf-injection by itself, and --gdb-runtime by
+	-- itself.
+	local flags      = args.flags or {}
+	local elf_path   = flags.elf_path
+	local has_elf    = type(elf_path) == "string" and #elf_path > 0
+	local post_links = flags.gdb_runtime or flags.dwarf_injection
+	if post_links and not has_elf then
+		io.stderr:write("ps1_meta: --elf PATH is required for post-link output\n")
+		os.exit(EXIT_INTERNAL_ERROR)
+	end
+
 	return args
 end
 
@@ -380,6 +499,8 @@ end
 local function build_ctx(args)
 	local sources = {}
 	for _, path in ipairs(args.sources) do
+		-- lfs handles path metadata and directories, not file-content streams.
+		-- Keep this io.open local so this entry point preserves its tailored diagnostic and exit path below.
 		local  f = io.open(path, "r")
 		if not f then
 			io.stderr:write("ps1_meta: cannot open --source " .. path .. "\n")
@@ -427,11 +548,17 @@ end
 -- Topological sort (Kahn's algorithm + cycle detection)
 -- ════════════════════════════════════════════════════════════════════════════
 
---- Compute the dep-closure of `requested_set`: include every pass name transitively required by the requested set.
+--- Topologically sort the requested pass set, augmented with all transitive deps.
+--- Detects cycles and errors out with details.
 --- @param passes table<string, PassDescriptor>
 --- @param requested_set string[]
---- @return table<string, boolean>  -- set of pass names needed (including transitive deps)
-local function dep_closure(passes, requested_set)
+--- @return string[]  -- execution order
+---
+--- Implementation note: the 4 algorithm phases (dep-closure, in-degree, ready-queue, sort) are inlined as 3 small blocks within this function. 
+--- Each was a 1-caller helper; the 2-caller rule doesn't apply, so inlining produces a single readable function
+--- (plex: small patterns → shared, but only when shared; here they're not).
+local function topo_sort(passes, requested_set)
+	-- Phase 1: dep-closure. Include every pass name transitively required by `requested_set`.
 	local needed = {}
 	for _, name in ipairs(requested_set) do needed[name] = true end
 	local changed = true
@@ -450,23 +577,8 @@ local function dep_closure(passes, requested_set)
 			end
 		end
 	end
-	return needed
-end
 
---- Count entries in a hash table (Lua's `#t` doesn't work for hash tables).
---- @param t table
---- @return integer
-local function count_entries(t)
-	local n = 0
-	for _ in pairs(t) do n = n + 1 end
-	return n
-end
-
---- Compute in-degrees for the Kahn sort: for each pass in `needed`, the number of its deps that are also in `needed`.
---- @param passes table<string, PassDescriptor>
---- @param needed table<string, boolean>
---- @return table<string, integer>
-local function compute_in_degrees(passes, needed)
+	-- Phase 2: in-degrees for Kahn's algorithm. For each pass in `needed`, the number of its deps that are also in `needed`.
 	local in_degree = {}
 	for name, _ in pairs(needed) do in_degree[name] = 0 end
 	for name, _ in pairs(needed) do
@@ -476,65 +588,41 @@ local function compute_in_degrees(passes, needed)
 			end
 		end
 	end
-	return in_degree
-end
 
---- Seed the Kahn ready queue with passes whose in-degree is 0, sorted alphabetically for deterministic execution order.
--- @param in_degree table<string, integer>
---- @return string[]
-local function seed_ready_queue(in_degree)
+	-- Phase 3: seed the ready queue with passes whose in-degree is 0, sorted alphabetically for deterministic order.
 	local ready = {}
 	for name, deg in pairs(in_degree) do
 		if deg == 0 then ready[#ready + 1] = name end
 	end
 	table.sort(ready)
-	return ready
-end
 
--- (internal) Pop the next ready pass, decrement the in-degree of every remaining pass that depended on it
--- (inserting newly-zero-degree passes back into the ready queue), and append to `order`. Keeps `ready` sorted.
--- @param passes table<string, PassDescriptor>
--- @param needed table<string, boolean>
--- @param in_degree table<string, integer>
--- @param ready string[]
--- @param order string[]
-local function process_next_ready(passes, needed, in_degree, ready, order)
-	local just_finished = table.remove(ready, 1)
-	order[#order + 1] = just_finished
-	for name, _ in pairs(needed) do
-		if name ~= just_finished then
-			for _, dep in ipairs(passes[name].deps) do
-				if dep == just_finished then
-					in_degree[name] = in_degree[name] - 1
-					if in_degree[name] == 0 then
-						ready[#ready + 1] = name
-						table.sort(ready)
+	-- Phase 4: drain the ready queue. For each popped pass, decrement the in-degree of every remaining pass that depended on it.
+	-- Newly-zero-degree passes are inserted back into the ready queue (kept sorted).
+	local order = {}
+	while #ready > 0 do
+		local just_finished = table.remove(ready, 1)
+		order[#order + 1] = just_finished
+		for name, _ in pairs(needed) do
+			if name ~= just_finished then
+				for _, dep in ipairs(passes[name].deps) do
+					if dep == just_finished then
+						in_degree[name] = in_degree[name] - 1
+						if in_degree[name] == 0 then
+							ready[#ready + 1] = name
+							table.sort(ready)
+						end
 					end
 				end
 			end
 		end
 	end
-end
 
---- Topologically sort the requested pass set, augmented with all transitive deps.
---- Detects cycles and errors out with details.
---- @param passes table<string, PassDescriptor>
---- @param requested_set string[]
---- @return string[]  -- execution order
-local function topo_sort(passes, requested_set)
-	local needed    = dep_closure(passes, requested_set)
-	local in_degree = compute_in_degrees(passes, needed)
-	local ready     = seed_ready_queue(in_degree)
-
-	local order = {}
-	while #ready > 0 do
-		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
+	-- 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
+	-- Without this check, a fully-closed cycle (e.g. A -> B -> A) would silently return an empty order list, leaving the orchestrator to dispatch nothing.
+	local needed_count = 0
+	for _ in pairs(needed) do needed_count = needed_count + 1 end  -- count hash entries; Lua's #t doesn't work
+	if #order ~= needed_count then
 		for name, deg in pairs(in_degree) do
 			if deg > 0 then
 				error("dependency cycle detected involving pass '" .. name .. "'")
@@ -552,16 +640,15 @@ end
 --- Render the dep graph as ASCII art. Output width capped at 78 columns.
 --- Falls back to the simpler "Resolved dependency order" list only if graph width exceeds terminal width.
 --- @param passes table<string, PassDescriptor>
---- @param requested string[]  -- originally-requested passes (subset of closed)
 --- @param closed string[]     -- dep-closed execution order
 --- @return string
-local function render_dep_graph(passes, requested, closed)
+local function render_dep_graph(passes, closed)
 	local lines = {}
 	local function add(s) lines[#lines + 1] = s end
 
 	add("[ps1_meta] Resolved dependency order (closed under deps):")
 	for pass_idx, name in ipairs(closed) do
-		local p = passes[name]
+		local p        = passes[name]
 		local deps_str = (#p.deps == 0) and "(no deps)" or
 			"(deps: " .. table.concat(p.deps, ", ") .. ")"
 		add(string.format("  %d. %-22s %-45s [%s]",
@@ -570,51 +657,204 @@ local function render_dep_graph(passes, requested, closed)
 	add("")
 
 	-- Data-driven ASCII graph built from the actual PASSES table.
-	-- Shows the source -> scan_source -> pass chain. Each pass is shown once; edges are "feeds into" arrows based on deps.
+	-- Kahn layers determine the row of each box; each pass becomes a 4-row
+	-- box (top border, name, kind+output-count, bottom border). Boxes in
+	-- the same layer are rendered side-by-side; layers are connected by a
+	-- 'v' marker row whose 'v' chars are centered under each box, indicating
+	-- the downward 'feeds into' direction.
+	--
+	-- Layout invariants enforced here:
+	--   * MAX_GRAPH_WIDTH = 78 cols: no emitted line exceeds this. The
+	--     "simplest" way to stay under the budget is to limit each sub-row
+	--     to MAX_BOXES_PER_ROW = 3 boxes; for the canonical 9-row PASSES
+	--     table the largest layer has 3 boxes, so no wrap engages today.
+	--     If a future layer grows past 3 boxes, the layer is split into
+	--     adjacent sub-rows (each ending in its own 'v'-marker row).
+	--   * No silent truncation: per-layer box width is computed from the
+	--     layer's widest content (max(name length, kind-suffix length))
+	--     plus a 1-char leading + 1-char trailing padding + 2 wall chars.
+	--     Long names widen the box; they are NEVER truncated.
+	--   * Collision-safety: every PASSES row has a unique name, kind, and
+	--     out-list, so two distinct passes cannot produce visually identical
+	--     boxes.
 	add("[ps1_meta] Pass graph (read top-to-bottom; edges = 'feeds into'):")
 	add("")
 
-	-- Compute which passes feed which other passes (reverse of deps).
-	local feeds = {}  -- feeds[X] = list of passes that X feeds into
-	for _, name in ipairs(closed) do feeds[name] = {} end
-	for name, p in pairs(passes) do
-		for _, dep in ipairs(p.deps) do
-			if feeds[dep] then feeds[dep][#feeds[dep] + 1] = name end
+	-- Compute Kahn layer per pass: layer L = max(deps' layer) + 1, layer 0
+	-- for deps-less passes. Repeated sweeps until every pass in `closed` is
+	-- assigned (handles forward refs that resolve on the second pass).
+	local pass_layer, max_layer = {}, 0
+	local sorted_closed = {}
+	for _, name in ipairs(closed) do sorted_closed[#sorted_closed + 1] = name end
+	table.sort(sorted_closed)
+	local function assign_layers()
+		local assigned_count = 0
+		for _, name in ipairs(sorted_closed) do
+			if pass_layer[name] == nil then
+				local p = passes[name]
+				local max_dep, ready = -1, true
+				for _, dep in ipairs(p.deps) do
+					if pass_layer[dep] == nil then ready = false; break end
+					if pass_layer[dep] > max_dep then max_dep = pass_layer[dep] end
+				end
+				if ready then
+					pass_layer[name] = max_dep + 1
+					if pass_layer[name] > max_layer then max_layer = pass_layer[name] end
+					assigned_count = assigned_count + 1
+				end
+			end
+		end
+		return assigned_count
+	end
+	while assign_layers() > 0 do end
+	-- Defensive invariant: any unresolved pass is a bug. topo_sort already
+	-- errors on cycles before this point, so reaching here means a logic
+	-- error in the renderer (or a synthetic call that bypassed topo_sort).
+	-- Surface the failure loudly with the offending names; never silently
+	-- place unresolved passes at layer 0 (which would corrupt the graph).
+	local unresolved = {}
+	for _, name in ipairs(sorted_closed) do
+		if pass_layer[name] == nil then unresolved[#unresolved + 1] = name end
+	end
+	if #unresolved > 0 then
+		error("render_dep_graph: unresolved Kahn layer for pass(es): "
+			.. table.concat(unresolved, ", ")
+			.. "; topo_sort should have caught this earlier")
+	end
+
+	-- Bucket passes by layer; sort each bucket alphabetically for stability.
+	local layers = {}
+	for i = 0, max_layer do layers[i] = {} end
+	for _, name in ipairs(sorted_closed) do
+		layers[pass_layer[name]][#layers[pass_layer[name]] + 1] = name
+	end
+	for i = 0, max_layer do table.sort(layers[i]) end
+
+	-- Layout constants. Boxes in the same layer share the same width
+	-- (computed as the layer's widest content + padding + walls).
+	local MAX_GRAPH_WIDTH   = 78
+	local MAX_BOXES_PER_ROW = 3
+	local GAP               = 3
+
+	local function pad_right(s, width)
+		if #s >= width then return s:sub(1, width) end
+		return s .. string.rep(" ", width - #s)
+	end
+
+	-- Compute the box width (in chars, including both walls) for a layer.
+	-- The interior is the wider of (a) the longest pass name + 1 leading
+	-- space and (b) the longest "<kind> <N>" suffix + 1 leading space.
+	-- Then add 2 for the wall chars.
+	--
+	-- Why +1 (not +2): the +1 formula means the layer's max-content row
+	-- has 0 padding before the right wall (the `|` is immediately after
+	-- the content). This is the collision-safe widening policy the task
+	-- requires — long names widen the box and never get trailing padding.
+	-- Shorter passes in the same layer get trailing padding to fill the
+	-- interior to the layer's uniform width; they never get truncated.
+	local function box_w_for_layer(bucket)
+		local max_content = 0
+		for _, name in ipairs(bucket) do
+			local p        = passes[name]
+			local out_n    = #(p.out or {})
+			local kind_suf = string.format("%s %d>", p.kind, out_n)
+			if #name     > max_content then max_content = #name     end
+			if #kind_suf > max_content then max_content = #kind_suf end
+		end
+		-- Interior = 1 leading space + max_content + 0 trailing (the
+		-- trailing `|` IS the right boundary); walls = 2.
+		return max_content + 3
+	end
+
+	-- Render one pass as a 4-row box at the given box_w. The interior is
+	-- always padded to fit exactly; no string is ever truncated.
+	local function render_box(name, box_w)
+		local p        = passes[name]
+		local out_n    = #(p.out or {})
+		local kind_suf = string.format("%s %d>", p.kind, out_n)
+		local interior = box_w - 2
+		local border   = "+" .. string.rep("-", interior) .. "+"
+		return {
+			border,
+			"|" .. pad_right(" " .. name,     interior) .. "|",
+			"|" .. pad_right(" " .. kind_suf, interior) .. "|",
+			border,
+		}
+	end
+
+	-- Join a single row (1..4) across all boxes in a sub-row, with GAP
+	-- spaces between adjacent boxes.
+	local function join_row(box_rows, row_idx)
+		local parts = {}
+		for i, b in ipairs(box_rows) do
+			parts[#parts + 1] = b[row_idx]
+			if i < #box_rows then parts[#parts + 1] = string.rep(" ", GAP) end
+		end
+		return table.concat(parts)
+	end
+
+	-- 'v' marker row beneath a sub-row: one 'v' centered under each box.
+	local function v_marker_row(box_rows)
+		local total = 0
+		local centers = {}
+		for i, b in ipairs(box_rows) do
+			local w = #b[1]  -- box width = length of the top border row
+			local center = total + math.floor(w / 2)
+			centers[#centers + 1] = center
+			total = total + w + GAP
+		end
+		-- total now includes a trailing GAP we don't want; trim it.
+		total = total - GAP
+		local s = string.rep(" ", total)
+		for _, c in ipairs(centers) do
+			s = s:sub(1, c) .. "v" .. s:sub(c + 2)
+		end
+		return s
+	end
+
+	-- Render a single sub-row (a contiguous chunk of a layer's bucket).
+	-- Emits the 4 box rows + an empty line + the 'v' marker row + an
+	-- empty line, EXCEPT the very last sub-row of the very last layer
+	-- omits the trailing 'v' marker (nothing flows below it).
+	local function render_subrow(bucket_chunk, is_last_subrow, is_last_layer)
+		local box_w = box_w_for_layer(bucket_chunk)
+		local boxes = {}
+		for _, name in ipairs(bucket_chunk) do boxes[#boxes + 1] = render_box(name, box_w) end
+		add(join_row(boxes, 1))  -- top borders
+		add(join_row(boxes, 2))  -- names
+		add(join_row(boxes, 3))  -- kind + output-count
+		add(join_row(boxes, 4))  -- bottom borders
+		-- 'v' marker row beneath this sub-row connects downward to the
+		-- next sub-row of the same layer (if any) OR to the next layer.
+		-- Skip the trailing 'v' only on the very last sub-row of the
+		-- final layer, where nothing flows below it.
+		if not is_last_subrow or not is_last_layer then
+			add("")
+			add(v_marker_row(boxes))
+			add("")
 		end
 	end
 
-	-- Layout: source -> scan_source -> word-counts -> {components, annotation, offsets, static-analysis} -> report
-	-- Outputs are listed under each pass.
-	local outputs_for = function(name)
-		local p = passes[name]
-		if not p or not p.out or #p.out == 0 then return "" end
-		local outs = {}
-		for _, o in ipairs(p.out) do outs[#outs + 1] = o.path_template end
-		return table.concat(outs, ", ")
+	for layer_idx = 0, max_layer do
+		local bucket   = layers[layer_idx]
+		local is_last  = (layer_idx == max_layer)
+		-- Split the layer into sub-rows of at most MAX_BOXES_PER_ROW boxes.
+		-- With a 20-char box width (the canonical case: name "static-analysis"
+		-- is 15 chars, suffix "header-output 2>" is 16 chars) and GAP=3,
+		-- 3 boxes per sub-row = 3*20 + 2*3 = 66 cols + a 'v' row of 66 cols;
+		-- well within MAX_GRAPH_WIDTH. A 4th box would push to 4*20 + 3*3 = 89,
+		-- which is why MAX_BOXES_PER_ROW = 3 (wrap when >3).
+		local chunk_size = math.min(MAX_BOXES_PER_ROW, #bucket)
+		if chunk_size < 1 then chunk_size = 1 end
+		for chunk_start = 1, #bucket, chunk_size do
+			local chunk_end = math.min(chunk_start + chunk_size - 1, #bucket)
+			local chunk = {}
+			for i = chunk_start, chunk_end do chunk[#chunk + 1] = bucket[i] end
+			local is_last_subrow = (chunk_end == #bucket)
+			render_subrow(chunk, is_last_subrow, is_last)
+		end
 	end
 
-	add("   +-----------+   +-------------------+    +-----------------+")
-	add("   |  source   |-->|  scan_source      |--->|   word-counts   |")
-	add("   |  files    |   | (scan_source.lua) |    |   (load)        |")
-	add("   +-----------+   +-------------------+    +-----------------+")
-	add("                          (single walk)         |")
-	add("                                                |")
-	add("        +-------------------+-------------------+-----------+")
-	add("        v                   v                   v           v")
-	add("   +--------------+   +--------------+   +--------------+   +---------------+")
-	add("   | components   |   | annotation   |   |   offsets    |   |static-analysis|")
-	add("   +--------------+   +--------------+   +--------------+   +---------------+")
-	add("   |<src>/gen/    |   |build/gen/    |   |<src>/gen/    |   |build/gen/     |")
-	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("   |offsets|static-analysis|  |report|       |<--------------------+")
-	add("   |       |               |  +------+-------+")
-	add("   +-------+---------------+")
-
 	return table.concat(lines, "\n") .. "\n"
 end
 
@@ -663,6 +903,7 @@ local function dispatch_passes(ctx, order)
 	local had_errors = false
 	for _, pass_name in ipairs(order) do
 		local pass   = PASSES[pass_name]
+		io.stderr:write(string.format("[ps1_meta] %-22s running\n", pass_name))
 		local mod    = require(pass.module)
 		local result = mod.run(ctx)
 
@@ -686,7 +927,7 @@ local function main(argv)
 
 		-- --dry-run: print dep order + ASCII graph, exit OK.
 		if args.dry_run then
-			io.write(render_dep_graph(PASSES, requested, closed))
+			io.write(render_dep_graph(PASSES, closed))
 			os.exit(EXIT_OK)
 		end
 
@@ -702,4 +943,20 @@ local function main(argv)
 	os.exit(EXIT_OK)
 end
 
-main({...})
+-- Module export for in-process consumers (tests that dofile this script).
+-- The closure above, `render_dep_graph`, and the canonical `PASSES` table
+-- are exposed so a test can render the graph for synthetic PASSES tables
+-- without spawning a subprocess. The conditional `main(...)` call below
+-- only fires when this file is invoked as the entry script (arg[0] ends
+-- in "ps1_meta.lua"); in dofile() mode (test's arg[0] does not match),
+-- main() is skipped and the chunk returns `_M` to the caller.
+local _M = {
+	render_dep_graph = render_dep_graph,
+	PASSES           = PASSES,
+}
+
+if arg and arg[0] and arg[0]:match("ps1_meta%.lua$") then
+	main({...})
+end
+
+return _M