Last adjustments for metaprogram, hitting a intermission checkpoint to do docs, writeups, and other research distillations.

not sure what the standalone repo is going to be yet, but it will be relatively permissive since this is prototype/educational setup

.vscode/cozy-and-windy/README.md

@@ -0,0 +1,26 @@
+# Cozy and Windy
+
+Editor theme ported from the Rider scheme of the same name.
+
+It colors the editor surface, C/C++ syntax, and tape-atom DSL keywords
+emitted by `local.tape-atom-syntax`. It does not change workbench chrome.
+
+## Install
+
+```powershell
+cd C:\projects\Pikuma\ps1\.vscode\cozy-and-windy
+npm run package
+code --install-extension .\cozy-and-windy-0.1.0.vsix --force
+```
+
+Reload the window. Select **Cozy and Windy** as the color theme, or set
+`workbench.colorTheme` to `Cozy and Windy` in the PS1 workspace settings.
+
+Keep `local.tape-atom-syntax` installed. This theme colors those token
+types; it does not classify them.
+
+## Inspect
+
+Open `hello_camera.atom.c` and run **Developer: Inspect Editor Tokens and Scopes**
+on `MipsAtom_`, an atom name, `atom_info`, `R_PrimCursor`, a `gte_*` call,
+and a `mac_*` call.

.vscode/cozy-and-windy/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "cozy-and-windy",
+	"displayName": "Cozy and Windy",
+	"description": "Editor theme ported from the Rider Cozy and Windy scheme. Colors C/C++ and tape-atom DSL keywords.",
+	"publisher": "local",
+	"version": "0.1.0",
+	"engines": {
+		"vscode": "^1.80.0"
+	},
+	"categories": [
+		"Themes"
+	],
+	"scripts": {
+		"package": "npx --yes @vscode/vsce@3.6.1 package --allow-missing-repository --skip-license --out cozy-and-windy-0.1.0.vsix"
+	},
+	"contributes": {
+		"themes": [
+			{
+				"label": "Cozy and Windy",
+				"uiTheme": "vs-dark",
+				"path": "./themes/cozy-and-windy-color-theme.json"
+			}
+		]
+	}
+}

.vscode/cozy-and-windy/themes/cozy-and-windy-color-theme.json

@@ -0,0 +1,132 @@
+{
+	"name": "Cozy and Windy",
+	"type": "dark",
+	"semanticHighlighting": true,
+	"colors": {
+		// 121212
+		// 111212
+		// 211f1e
+		// 191817
+		"editor.background": "#191817",
+		"editor.foreground": "#dfc6ba",
+		"editor.lineHighlightBackground": "#1c1c1c",
+		"editor.selectionBackground": "#164371",
+		"editor.selectionForeground": "#c8c8c8",
+		"editorLineNumber.foreground": "#43c3c3",
+		"editorLineNumber.activeForeground": "#00fff4",
+		"editorIndentGuide.background1": "#181818",
+		"editorIndentGuide.activeBackground1": "#202020",
+		"editorRuler.foreground": "#505050",
+		"editorGutter.background": "#211f1e",
+		"editorBracketMatch.background": "#3b514d",
+		"editor.foldBackground": "#0c0c0c6a",
+		"editor.wordHighlightBackground": "#211f1e4d",
+		"editor.wordHighlightStrongBackground": "#303030",
+		"editorCursor.foreground": "#00fff4",
+		"editorWhitespace.foreground": "#181818",
+		// "editorLineHighlightBorder": "#1c1c1c",
+		"editorWidget.background": "#211f1e",
+		"editorSuggestWidget.background": "#2c334b",
+		"editorHoverWidget.background": "#2c334b"
+	},
+	"semanticTokenColors": {
+		"comment": { "foreground": "#868686", "fontStyle": "italic" },
+		"keyword": { "foreground": "#d8bd5b" },
+		"string": { "foreground": "#d46a54" },
+		"number": { "foreground": "#b5cea8" },
+		"operator": { "foreground": "#be8e78" },
+		"class": { "foreground": "#54a4d6" },
+		"struct": { "foreground": "#54a4d6" },
+		"enum": { "foreground": "#54a4d6" },
+		"type": { "foreground": "#54a4d6" },
+		"interface": { "foreground": "#7984ab" },
+		"function": { "foreground": "#cccab5" },
+		// "function": { "foreground": "#6090a9" },
+		"method": { "foreground": "#6090a9" },
+		"variable": { "foreground": "#bc966c" },
+		"parameter": { "foreground": "#ce8365" },
+		"property": { "foreground": "#acb8c8" },
+		"*.static": { "foreground": "#9e95c6" },
+		"macro": { "foreground": "#5ea852" },
+		"namespace": { "foreground": "#8e8e8e" },
+		"typeParameter": { "foreground": "#b8d7a3" },
+		"enumMember": { "foreground": "#a373b0" },
+		"label": { "foreground": "#c8c8c8", "fontStyle": "bold" },
+		"tapeAtomKeyword": { "foreground": "#d8bd5b", "fontStyle": "bold" },
+		"tapeAtomName": { "foreground": "#b1b7d6", "fontStyle": "bold" },
+		"tapeComponentKeyword": { "foreground": "#d68a36", "fontStyle": "bold" },
+		"tapeComponentName": { "foreground": "#b1b7d6", "fontStyle": "bold" },
+		"tapeAnnotation": { "foreground": "#d8bd5b" },
+		"tapeBindType": { "foreground": "#54a4d6" },
+		"tapePhase": { "foreground": "#b8d7a3", "fontStyle": "italic" },
+		"tapeLabel": { "foreground": "#959595", "fontStyle": "bold" },
+		// "tapeCpuInstruction": { "foreground": "#6d9aa0" },
+		// "tapeCpuInstruction": { "foreground": "#cf7539" },
+		// "tapeCpuInstruction": { "foreground": "#d16b3a" },
+		"tapeCpuInstruction": { "foreground": "#d5895a" },
+		"tapeGteInstruction": { "foreground": "#988bcb" },
+		"tapeGpuInstruction": { "foreground": "#bf7dac" },
+		"tapeComponentInstruction": { "foreground": "#8baa5d" },
+		// "tapeGprRegister": { "foreground": "#92d4d9" },
+		"tapeGprRegister": { "foreground": "#a2bfa8" },
+		"tapeCop2Register": { "foreground": "#945cd9" },
+		"tapeDuffleType": { "foreground": "#54a4d6" },
+		"tapeAttribute": { "foreground": "#73a07c" },
+		"tapeGprRegister.tapeRead": { "foreground": "#5bb8b0", "fontStyle": "italic" },
+		"tapeGprRegister.tapeWrite": { "foreground": "#2d8f8c", "fontStyle": "bold" },
+		"tapeCop2Register.tapeRead": { "foreground": "#b08ae0", "fontStyle": "italic" },
+		"tapeCop2Register.tapeWrite": { "foreground": "#7b3ec4", "fontStyle": "bold" },
+		// "*.tapeAuto": { },
+		"tapeControlFlow": { "foreground": "#63d169", "fontStyle": "bold" },
+		"tapeDelaySlot": { "foreground": "#ff5647" }
+	},
+	"tokenColors": [
+		{ "scope": ["comment", "comment.block", "comment.line", "comment.block.documentation"], "settings": { "foreground": "#868686", "fontStyle": "italic" } },
+		{ "scope": ["keyword", "keyword.control", "keyword.other"], "settings": { "foreground": "#d8bd5b" } },
+		{ "scope": ["string", "string.quoted"], "settings": { "foreground": "#d46a54" } },
+		{ "scope": ["string.quoted.other"], "settings": { "foreground": "#d69d85" } },
+		{ "scope": ["constant.numeric"], "settings": { "foreground": "#b5cea8" } },
+		{ "scope": ["punctuation", "keyword.operator"], "settings": { "foreground": "#be8e78" } },
+		{ "scope": ["keyword.operator.overload"], "settings": { "foreground": "#b87e76" } },
+		{ "scope": ["entity.name.type", "entity.name.type.class", "entity.name.type.struct", "entity.name.type.enum"], "settings": { "foreground": "#54a4d6" } },
+		{ "scope": ["entity.name.type.interface"], "settings": { "foreground": "#7984ab" } },
+		{ "scope": ["entity.name.function"], "settings": { "foreground": "#cccab5" } },
+		{ "scope": ["entity.name.function.member"], "settings": { "foreground": "#6090a9" } },
+		{ "scope": ["variable.other.local"], "settings": { "foreground": "#bc966c" } },
+		{ "scope": ["variable.parameter"], "settings": { "foreground": "#ce8365" } },
+		{ "scope": ["variable.other.property"], "settings": { "foreground": "#acb8c8" } },
+		{ "scope": ["variable.other.constant"], "settings": { "foreground": "#9e95c6" } },
+		{ "scope": ["variable.other.global", "variable.other.defaultLibrary"], "settings": { "foreground": "#bf7dac" } },
+		{ "scope": ["support.type", "support.function"], "settings": { "foreground": "#8baa5d" } },
+		{ "scope": ["meta.preprocessor"], "settings": { "foreground": "#5ea852" } },
+		// { "scope": ["variable.parameter.preprocessor"], "settings": { "foreground": "#636363" } },
+		{ "scope": ["variable.parameter.preprocessor"], "settings": { "foreground": "#bc966c" } },
+		{ "scope": ["keyword.control.directive"], "settings": { "foreground": "#d68a36" } },
+		{ "scope": ["entity.name.namespace"], "settings": { "foreground": "#8e8e8e" } },
+		{ "scope": ["entity.name.type.parameter"], "settings": { "foreground": "#b8d7a3" } },
+		{ "scope": ["variable.other.enummember"], "settings": { "foreground": "#a373b0" } },
+		{ "scope": ["entity.name.type.concept"], "settings": { "foreground": "#76ff7d" } },
+		{ "scope": ["entity.name.type.dependent"], "settings": { "foreground": "#448b5a", "fontStyle": "bold" } },
+		{ "scope": ["entity.name.label"], "settings": { "foreground": "#c8c8c8", "fontStyle": "bold" } },
+		{ "scope": ["invalid"], "settings": { "foreground": "#ff5647" } },
+		{ "scope": ["keyword.codetag.todo"], "settings": { "foreground": "#c10000", "fontStyle": "bold italic" } },
+		{ "scope": ["keyword.control.duffle.atom"], "settings": { "foreground": "#d8bd5b", "fontStyle": "bold" } },
+		{ "scope": ["entity.name.function.duffle.atom"], "settings": { "foreground": "#cccab5", "fontStyle": "bold" } },
+		{ "scope": ["keyword.control.duffle.component"], "settings": { "foreground": "#d68a36", "fontStyle": "bold" } },
+		{ "scope": ["entity.name.function.duffle.component"], "settings": { "foreground": "#6090a9", "fontStyle": "bold" } },
+		{ "scope": ["support.function.duffle.annotation"], "settings": { "foreground": "#d8bd5b" } },
+		{ "scope": ["entity.name.type.duffle.bind"], "settings": { "foreground": "#54a4d6" } },
+		{ "scope": ["entity.name.tag.duffle.phase"], "settings": { "foreground": "#b8d7a3", "fontStyle": "italic" } },
+		{ "scope": ["entity.name.label.duffle.atom"], "settings": { "foreground": "#c8c8c8", "fontStyle": "bold" } },
+		{ "scope": ["support.function.duffle.cpu"], "settings": { "foreground": "#6d9aa0" } },
+		{ "scope": ["support.function.duffle.gte"], "settings": { "foreground": "#988bcb" } },
+		{ "scope": ["support.function.duffle.gpu"], "settings": { "foreground": "#bf7dac" } },
+		{ "scope": ["support.function.duffle.component"], "settings": { "foreground": "#8baa5d" } },
+		{ "scope": ["keyword.control.duffle.branch"], "settings": { "foreground": "#76ff7d", "fontStyle": "bold" } },
+		{ "scope": ["keyword.operator.duffle.delayslot"], "settings": { "foreground": "#ff5647" } },
+		{ "scope": ["variable.other.constant.duffle.gpr"], "settings": { "foreground": "#3fa8a6" } },
+		{ "scope": ["variable.other.constant.duffle.cop2"], "settings": { "foreground": "#945cd9" } },
+		{ "scope": ["storage.type.duffle.type"], "settings": { "foreground": "#54a4d6" } },
+		{ "scope": ["storage.modifier.duffle.attr"], "settings": { "foreground": "#73a07c" } }
+	]
+}

.vscode/install_extensions.ps1

@@ -0,0 +1,43 @@
+# Package and install the local VS Code Insiders extensions under .vscode/.
+# Usage:
+#   .\install_extensions.ps1
+#   .\install_extensions.ps1 -SkipPackage
+
+param([switch] $SkipPackage)
+
+$path_vscode   = $PSScriptRoot
+$code_insiders = "C:\apps\Microsoft VS Code Insiders\bin\code-insiders.cmd"
+if (-not (test-path -literalpath $code_insiders)) {
+	$found = get-command code-insiders -erroraction silentlycontinue
+	if ($found) { $code_insiders = $found.source }
+}
+
+if (-not (test-path -literalpath $code_insiders)) { throw "code-insiders not found. Install VS Code Insiders or add it to PATH." }
+
+$extensions = @(
+	(join-path $path_vscode "tape-atom-syntax"),
+	(join-path $path_vscode "cozy-and-windy")
+)
+
+foreach ($extension in $extensions) {
+	$package_json = join-path $extension "package.json"
+	if (-not (test-path -literalpath $package_json)) { throw "missing $package_json" }
+
+	$manifest = get-content -literalpath $package_json -raw | convertfrom-json
+	$vsix     = join-path $extension ("{0}-{1}.vsix" -f $manifest.name, $manifest.version)
+
+	if (-not $SkipPackage) {
+		if (-not $manifest.scripts.package) { throw "$package_json has no scripts.package" }
+		write-host "packaging $($manifest.displayName) ($($manifest.name)@$($manifest.version))"
+		& npm --prefix $extension run package
+		if ($LASTEXITCODE -ne 0) { throw "npm run package failed for $extension" }
+	}
+
+	if (-not (test-path -literalpath $vsix)) { throw "missing $vsix" }
+
+	write-host "installing $vsix"
+	& $code_insiders --install-extension $vsix --force
+	if ($LASTEXITCODE -ne 0) { throw "install failed for $vsix" }
+}
+
+write-host "done. reload the Insiders window (Developer: Reload Window)."

.vscode/tape-atom-syntax/classifier.js

@@ -0,0 +1,222 @@
+"use strict";
+
+const { nearestCall } = require("./lexer");
+const { mergeIndexes, scanSource } = require("./source-index");
+
+const TOKEN_TYPES = [
+	"tapeAtomKeyword",
+	"tapeAtomName",
+	"tapeComponentKeyword",
+	"tapeComponentName",
+	"tapeAnnotation",
+	"tapeBindType",
+	"tapePhase",
+	"tapeLabel",
+	"tapeCpuInstruction",
+	"tapeControlFlow",
+	"tapeGteInstruction",
+	"tapeGpuInstruction",
+	"tapeComponentInstruction",
+	"tapeDelaySlot",
+	"tapeGprRegister",
+	"tapeCop2Register",
+	"tapeDuffleType",
+	"tapeAttribute",
+	"keyword",
+	"macro",
+];
+
+const TOKEN_MODIFIERS = ["declaration", "tapeRead", "tapeWrite", "tapeAuto"];
+const TOKEN_TYPE_INDEX = new Map(TOKEN_TYPES.map((name, index) => [name, index]));
+const TOKEN_MODIFIER_INDEX = new Map(TOKEN_MODIFIERS.map((name, index) => [name, index]));
+
+const ATOM_KEYWORDS = new Set(["MipsAtom_", "MipsAtom_Proc_"]);
+const COMPONENT_KEYWORDS = new Set(["MipsAtomComp_", "MipsAtomComp_Proc_"]);
+const ANNOTATIONS = new Set([
+	"atom_info", "atom_bind", "atom_reads", "atom_writes", "atom_label",
+	"atom_offset", "atom_reg", "atom_type", "atom_ctx", "atom_phase",
+	"atom_auto_reg", "phase_auto_reg", "atom_dbg_skip",
+]);
+
+const DSL_KEYWORDS = new Set([
+	"FI_", "I_", "NI_", "Relative_", "Struct_", "Enum_", "Union_", "Array_",
+	"Slice_", "TypeR_", "TypeV_", "align_", "internal", "local_persist", "global",
+	"RO_", "LP_", "gknown", "expect_", "cexpr_",
+	"asm", "asm_words", "asm_rpins", "asm_clobber",
+	"O_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "tr_", "tv_",
+	"rgcc", "r_use", "r_set", "r_mod", "r_imm", "r_mem",
+	"u1_", "u2_", "u4_", "u8_", "s1_", "s2_", "s4_", "s8_",
+	"u1_r", "u2_r", "u4_r", "u8_r", "u1_v", "u2_v", "u4_v", "u8_v",
+]);
+
+const DELAY_SLOT_KEYWORDS = new Set(["LdSlot_", "BdSlot_", "DmaSlot_", "GteDelay_"]);
+
+const CONTROL_FLOW_PREFIXES = /^(?:branch_|jump_|call_)/;
+
+const ROLE_TO_TYPE = {
+	atomName: "tapeAtomName",
+	componentName: "tapeComponentName",
+	bindType: "tapeBindType",
+	duffleType: "tapeDuffleType",
+	gprRegister: "tapeGprRegister",
+	cop2Register: "tapeCop2Register",
+};
+
+function registerType(name, index) {
+	const kind = index.registers.get(name);
+	if (kind === "gpr" || /^R_[A-Za-z0-9_]+$/.test(name)) return "tapeGprRegister";
+	if (kind === "cop2" || /^(?:C2_|gte_cr_)[A-Za-z0-9_]+$/.test(name)) return "tapeCop2Register";
+	return null;
+}
+
+function instructionType(name, index) {
+	const domain = index.macros.get(name);
+	if (domain === "control") return "tapeControlFlow";
+	if (domain === "cpu") return "tapeCpuInstruction";
+	if (domain === "gte") return "tapeGteInstruction";
+	if (domain === "gpu") return "tapeGpuInstruction";
+	if (domain === "component") {
+		if (/^mac_gte_/.test(name)) return "tapeGteInstruction";
+		if (/^mac_gp/.test(name)) return "tapeGpuInstruction";
+		if (/^mac_/.test(name)) return "tapeComponentInstruction";
+		return "macro";
+	}
+	if (domain === "utility") return "macro";
+	if (/^gte_(?!cr_)/.test(name)) return "tapeGteInstruction";
+	if (/^gp[01]_/.test(name)) return "tapeGpuInstruction";
+	if (/^mac_gte_/.test(name)) return "tapeGteInstruction";
+	if (/^mac_gp/.test(name)) return "tapeGpuInstruction";
+	if (/^mac_/.test(name)) return "tapeComponentInstruction";
+	return null;
+}
+
+function modifierMask(modifiers) {
+	let mask = 0;
+	for (const modifier of modifiers) {
+		const index = TOKEN_MODIFIER_INDEX.get(modifier);
+		if (index !== undefined) mask |= (1 << index);
+	}
+	return mask;
+}
+
+function isRegUseAccess(tokens, tokenIndex) {
+	const prev = tokens[tokenIndex - 1];
+	if (!prev || prev.text !== ".") return false;
+	const prevPrev = tokens[tokenIndex - 2];
+	if (!prevPrev || prevPrev.kind !== "identifier") return false;
+	const next = tokens[tokenIndex + 1];
+	if (next && next.text === ".") return false;
+	if (prevPrev.text === "r") return true;
+	const prev3 = tokens[tokenIndex - 3];
+	const prev4 = tokens[tokenIndex - 4];
+	if (prev3 && prev3.text === "." && prev4 && prev4.kind === "identifier" && prev4.text === "r") return true;
+	return false;
+}
+
+function classifyDocument(source, filePath, workspaceIndex, shouldCancel = () => false) {
+	const scanned = scanSource(source, filePath);
+	const index = mergeIndexes(workspaceIndex, scanned.index);
+	const spans = [];
+
+	for (let tokenIndex = 0; tokenIndex < scanned.tokens.length; tokenIndex += 1) {
+		if (shouldCancel()) break;
+		const token = scanned.tokens[tokenIndex];
+		if (token.kind !== "identifier") continue;
+
+		let type = null;
+		let modifiers = [];
+		const declaration = scanned.declarations.get(token.start);
+		const context = nearestCall(scanned.contexts, tokenIndex);
+
+		if (declaration) {
+			type = ROLE_TO_TYPE[declaration.role] || null;
+			modifiers = declaration.modifiers.slice();
+		} else if (ATOM_KEYWORDS.has(token.text)) {
+			type = "tapeAtomKeyword";
+		} else if (COMPONENT_KEYWORDS.has(token.text)) {
+			type = "keyword";
+		} else if (ANNOTATIONS.has(token.text)) {
+			type = "tapeAnnotation";
+		} else if (context && context.callee === "atom_bind" && context.argIndex === 0) {
+			type = "tapeBindType";
+		} else if (context && context.callee === "atom_phase" && context.argIndex === 0) {
+			type = "tapePhase";
+			modifiers = ["declaration"];
+		} else if (context && context.callee === "atom_ctx" && context.argIndex === 0) {
+			type = "tapeAtomName";
+		} else if (context && context.callee === "atom_label" && context.argIndex === 0) {
+			type = "tapeLabel";
+			modifiers = ["declaration"];
+		} else if (context && context.callee === "atom_offset" && context.argIndex <= 1) {
+			type = "tapeLabel";
+		} else if (context && context.callee === "atom_reads") {
+			type = registerType(token.text, index);
+			if (type) modifiers = ["tapeRead"];
+		} else if (context && context.callee === "atom_writes") {
+			type = registerType(token.text, index);
+			if (type) modifiers = ["tapeWrite"];
+		} else if (context && context.callee === "atom_auto_reg") {
+			if (context.argIndex === 0) type = "tapeAtomName";
+			if (context.argIndex === 1) {
+				type = "tapeGprRegister";
+				modifiers = ["declaration", "tapeAuto"];
+			}
+		} else if (context && context.callee === "phase_auto_reg") {
+			if (context.argIndex === 0) type = "tapePhase";
+			if (context.argIndex === 1) {
+				type = "tapeGprRegister";
+				modifiers = ["declaration", "tapeAuto"];
+			}
+		}
+
+		if (!type && index.bindTypes.has(token.text)) type = "tapeBindType";
+		if (!type && DSL_KEYWORDS.has(token.text)) type = "keyword";
+		if (!type && index.types.has(token.text)) type = "tapeDuffleType";
+		if (!type && index.attributes.has(token.text)) type = "tapeAttribute";
+		if (!type) type = registerType(token.text, index);
+		if (!type && DELAY_SLOT_KEYWORDS.has(token.text)) type = "tapeDelaySlot";
+		if (!type) {
+			const domain = index.macros.get(token.text);
+			if (domain === "control" || (domain && CONTROL_FLOW_PREFIXES.test(token.text))) {
+				type = "tapeControlFlow";
+			}
+		}
+		if (!type && isRegUseAccess(scanned.tokens, tokenIndex)) type = "tapeGprRegister";
+		if (!type) type = instructionType(token.text, index);
+		if (!type && /^(?:Slice_|A[0-9]+_)/.test(token.text)) type = "tapeDuffleType";
+		if (!type && /_[RV]$/.test(token.text)) type = "tapeDuffleType";
+		if (!type && index.atoms.has(token.text)) type = "tapeAtomName";
+		if (!type && index.components.has(token.text)) type = "tapeComponentName";
+		if (!type && index.phases.has(token.text)) type = "tapePhase";
+		if (!type && index.labels.has(token.text)) type = "tapeLabel";
+		if (!type) continue;
+
+		spans.push({
+			text: token.text,
+			type,
+			typeIndex: TOKEN_TYPE_INDEX.get(type),
+			modifiers,
+			modifierMask: modifierMask(modifiers),
+			start: token.start,
+			length: token.end - token.start,
+			line: token.line,
+			character: token.character,
+		});
+	}
+
+	spans.sort((left, right) => left.start - right.start || left.length - right.length);
+	const nonOverlapping = [];
+	for (const span of spans) {
+		const previous = nonOverlapping[nonOverlapping.length - 1];
+		if (!previous || previous.start + previous.length <= span.start) nonOverlapping.push(span);
+	}
+
+	return { spans: nonOverlapping, errors: scanned.errors };
+}
+
+module.exports = {
+	TOKEN_MODIFIERS,
+	TOKEN_TYPES,
+	classifyDocument,
+	modifierMask,
+};

.vscode/tape-atom-syntax/extension.js

@@ -0,0 +1,111 @@
+"use strict";
+
+const vscode = require("vscode");
+const { TOKEN_MODIFIERS, TOKEN_TYPES, classifyDocument } = require("./classifier");
+const { createIndex, mergeIndexes, scanSource } = require("./source-index");
+
+const SOURCE_GLOB = "**/*.{c,h,cc,cpp,cxx,hh,hpp,hxx}";
+const EXCLUDE_GLOB = "**/{gen,build,.slop_cache,toolchain,node_modules}/**";
+const EXCLUDED_SEGMENTS = new Set(["gen", "build", ".slop_cache", "toolchain", "node_modules"]);
+
+function isExcluded(uri) {
+	const segments = uri.fsPath.replaceAll("\\", "/").split("/");
+	return segments.some((segment) => EXCLUDED_SEGMENTS.has(segment));
+}
+
+function formatError(filePath, error) {
+	return `${filePath}:${error.offset}: ${error.kind}`;
+}
+
+async function activate(context) {
+	const output = vscode.window.createOutputChannel("Tape Atom DSL");
+	const emitter = new vscode.EventEmitter();
+	const legend = new vscode.SemanticTokensLegend(TOKEN_TYPES, TOKEN_MODIFIERS);
+	let workspaceIndex = createIndex();
+	let rebuildGeneration = 0;
+	let debounceHandle = null;
+
+	async function rebuildIndex() {
+		const generation = ++rebuildGeneration;
+		const files = await vscode.workspace.findFiles(SOURCE_GLOB, EXCLUDE_GLOB);
+		let nextIndex = createIndex();
+
+		for (const uri of files) {
+			if (generation !== rebuildGeneration) return;
+			if (isExcluded(uri)) continue;
+			try {
+				const bytes = await vscode.workspace.fs.readFile(uri);
+				const source = Buffer.from(bytes).toString("utf8");
+				const result = scanSource(source, uri.fsPath);
+				nextIndex = mergeIndexes(nextIndex, result.index);
+				for (const error of result.errors) output.appendLine(formatError(uri.fsPath, error));
+			} catch (error) {
+				output.appendLine(`${uri.fsPath}: ${error.stack || error.message || error}`);
+			}
+		}
+
+		if (generation !== rebuildGeneration) return;
+		workspaceIndex = nextIndex;
+		emitter.fire();
+	}
+
+	function scheduleRebuild(uri) {
+		if (uri && isExcluded(uri)) return;
+		if (debounceHandle !== null) clearTimeout(debounceHandle);
+		debounceHandle = setTimeout(() => {
+			debounceHandle = null;
+			rebuildIndex().catch((error) => output.appendLine(error.stack || String(error)));
+		}, 100);
+	}
+
+	const provider = {
+		onDidChangeSemanticTokens: emitter.event,
+		provideDocumentSemanticTokens(document, cancellationToken) {
+			try {
+				const result = classifyDocument(
+					document.getText(),
+					document.uri.fsPath,
+					workspaceIndex,
+					() => cancellationToken.isCancellationRequested
+				);
+				const builder = new vscode.SemanticTokensBuilder(legend);
+				for (const span of result.spans) {
+					if (cancellationToken.isCancellationRequested) break;
+					builder.push(span.line, span.character, span.length, span.typeIndex, span.modifierMask);
+				}
+				for (const error of result.errors) {
+					output.appendLine(formatError(document.uri.fsPath || document.uri.toString(), error));
+				}
+				return builder.build();
+			} catch (error) {
+				output.appendLine(`${document.uri}: ${error.stack || error.message || error}`);
+				return new vscode.SemanticTokensBuilder(legend).build();
+			}
+		},
+	};
+
+	const selector = [
+		{ language: "c", scheme: "file" },
+		{ language: "c", scheme: "untitled" },
+		{ language: "cpp", scheme: "file" },
+		{ language: "cpp", scheme: "untitled" },
+	];
+	const watcher = vscode.workspace.createFileSystemWatcher(SOURCE_GLOB);
+
+	context.subscriptions.push(
+		output,
+		emitter,
+		watcher,
+		watcher.onDidCreate(scheduleRebuild),
+		watcher.onDidChange(scheduleRebuild),
+		watcher.onDidDelete(scheduleRebuild),
+		vscode.languages.registerDocumentSemanticTokensProvider(selector, provider, legend),
+		{ dispose() { if (debounceHandle !== null) clearTimeout(debounceHandle); } }
+	);
+
+	await rebuildIndex();
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

.vscode/tape-atom-syntax/lexer.js

@@ -0,0 +1,186 @@
+"use strict";
+
+function isIdentifierStart(code) {
+	return code === 95 ||
+		(code >= 65 && code <= 90) ||
+		(code >= 97 && code <= 122);
+}
+
+function isIdentifierContinue(code) {
+	return isIdentifierStart(code) || (code >= 48 && code <= 57);
+}
+
+function lex(source) {
+	if (typeof source !== "string") throw new TypeError("source must be a string");
+
+	const tokens = [];
+	const errors = [];
+	let offset = 0;
+	let line = 0;
+	let character = 0;
+
+	function advance() {
+		if (source[offset] === "\r" && source[offset + 1] === "\n") {
+			offset += 2;
+			line += 1;
+			character = 0;
+			return;
+		}
+		if (source[offset] === "\n") {
+			offset += 1;
+			line += 1;
+			character = 0;
+			return;
+		}
+		offset += 1;
+		character += 1;
+	}
+
+	function pushToken(kind, start, startLine, startCharacter) {
+		tokens.push({
+			kind,
+			text: source.slice(start, offset),
+			start,
+			end: offset,
+			line: startLine,
+			character: startCharacter,
+		});
+	}
+
+	while (offset < source.length) {
+		const ch = source[offset];
+
+		if (/\s/.test(ch)) {
+			advance();
+			continue;
+		}
+
+		if (ch === "/" && source[offset + 1] === "/") {
+			while (offset < source.length && source[offset] !== "\r" && source[offset] !== "\n") advance();
+			continue;
+		}
+
+		if (ch === "/" && source[offset + 1] === "*") {
+			const start = offset;
+			advance();
+			advance();
+			let closed = false;
+			while (offset < source.length) {
+				if (source[offset] === "*" && source[offset + 1] === "/") {
+					advance();
+					advance();
+					closed = true;
+					break;
+				}
+				advance();
+			}
+			if (!closed) errors.push({ kind: "unterminated-block-comment", offset: start });
+			continue;
+		}
+
+		if (ch === "\"" || ch === "'") {
+			const quote = ch;
+			const start = offset;
+			advance();
+			let closed = false;
+			while (offset < source.length) {
+				if (source[offset] === "\\") {
+					advance();
+					if (offset < source.length) advance();
+					continue;
+				}
+				if (source[offset] === quote) {
+					advance();
+					closed = true;
+					break;
+				}
+				if (source[offset] === "\n" || source[offset] === "\r") break;
+				advance();
+			}
+			if (!closed) errors.push({ kind: "unterminated-literal", offset: start });
+			continue;
+		}
+
+		const code = source.charCodeAt(offset);
+		if (isIdentifierStart(code)) {
+			const start = offset;
+			const startLine = line;
+			const startCharacter = character;
+			advance();
+			while (offset < source.length && isIdentifierContinue(source.charCodeAt(offset))) advance();
+			pushToken("identifier", start, startLine, startCharacter);
+			continue;
+		}
+
+		const start = offset;
+		const startLine = line;
+		const startCharacter = character;
+		advance();
+		pushToken("punctuation", start, startLine, startCharacter);
+	}
+
+	return { tokens, errors };
+}
+
+function buildCallContexts(tokens) {
+	const contexts = Array.from({ length: tokens.length }, () => []);
+	const calls = [];
+	const errors = [];
+	const stack = [];
+
+	for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex += 1) {
+		const token = tokens[tokenIndex];
+
+		if (token.text === ")") {
+			if (stack.length === 0) {
+				errors.push({ kind: "unmatched-close-paren", offset: token.start });
+			} else {
+				const frame = stack.pop();
+				if (frame.callee !== null) calls.push({ ...frame, closeTokenIndex: tokenIndex });
+			}
+		}
+
+		contexts[tokenIndex] = stack
+			.filter((frame) => frame.callee !== null)
+			.map((frame) => ({
+				callee: frame.callee,
+				calleeTokenIndex: frame.calleeTokenIndex,
+				openTokenIndex: frame.openTokenIndex,
+				argIndex: frame.argIndex,
+			}));
+
+		if (token.text === "(") {
+			const previous = tokens[tokenIndex - 1];
+			const hasCallee = previous && previous.kind === "identifier";
+			stack.push({
+				callee: hasCallee ? previous.text : null,
+				calleeTokenIndex: hasCallee ? tokenIndex - 1 : -1,
+				openTokenIndex: tokenIndex,
+				argIndex: 0,
+			});
+			continue;
+		}
+
+		if (token.text === "," && stack.length > 0) {
+			const frame = stack[stack.length - 1];
+			if (frame.callee !== null) frame.argIndex += 1;
+		}
+	}
+
+	for (const frame of stack) {
+		errors.push({ kind: "unmatched-open-paren", offset: tokens[frame.openTokenIndex].start });
+	}
+
+	return { contexts, calls, errors };
+}
+
+function nearestCall(contexts, tokenIndex, callee) {
+	const entries = contexts[tokenIndex] || [];
+	for (let contextIndex = entries.length - 1; contextIndex >= 0; contextIndex -= 1) {
+		const entry = entries[contextIndex];
+		if (callee === undefined || entry.callee === callee) return entry;
+	}
+	return null;
+}
+
+module.exports = { buildCallContexts, lex, nearestCall };

.vscode/tape-atom-syntax/package.json

@@ -0,0 +1,85 @@
+{
+	"name": "atomasm-psx",
+	"displayName": "AtomAsm-PSX",
+	"description": "Semantic highlighting for the PS1 Tape/Atom MIPS macro DSL",
+	"publisher": "local",
+	"version": "0.3.0",
+	"engines": { "vscode": "^1.80.0" },
+	"categories": ["Programming Languages"],
+	"activationEvents": ["onLanguage:c", "onLanguage:cpp"],
+	"main": "./extension.js",
+	"files": [
+		"classifier.js",
+		"extension.js",
+		"lexer.js",
+		"source-index.js",
+		"syntaxes/tape_atom.tmLanguage.json"
+	],
+	"scripts": {
+		"test": "node --test test/*.test.js",
+		"package": "npx --yes @vscode/vsce@3.6.1 package --allow-missing-repository --skip-license --out atomasm-psx-0.3.0.vsix"
+	},
+	"contributes": {
+		"semanticTokenTypes": [
+			{ "id": "tapeAtomKeyword", "superType": "keyword", "description": "Tape atom declaration keyword" },
+			{ "id": "tapeAtomName", "superType": "function", "description": "Tape atom name" },
+			{ "id": "tapeComponentKeyword", "superType": "keyword", "description": "Tape atom component declaration keyword" },
+			{ "id": "tapeComponentName", "superType": "function", "description": "Tape atom component name" },
+			{ "id": "tapeAnnotation", "superType": "macro", "description": "Tape atom annotation" },
+			{ "id": "tapeBindType", "superType": "type", "description": "Tape bind structure type" },
+			{ "id": "tapePhase", "superType": "label", "description": "Tape atom phase" },
+			{ "id": "tapeLabel", "superType": "label", "description": "Tape atom branch label" },
+			{ "id": "tapeCpuInstruction", "superType": "macro", "description": "MIPS CPU instruction emitter" },
+			{ "id": "tapeControlFlow", "superType": "keyword", "description": "MIPS branch or jump instruction" },
+			{ "id": "tapeGteInstruction", "superType": "macro", "description": "GTE instruction emitter" },
+			{ "id": "tapeGpuInstruction", "superType": "macro", "description": "GPU command emitter" },
+			{ "id": "tapeComponentInstruction", "superType": "macro", "description": "Tape atom component invocation" },
+			{ "id": "tapeDelaySlot", "superType": "keyword", "description": "Load or branch delay slot annotation" },
+			{ "id": "tapeGprRegister", "superType": "variable", "description": "MIPS GPR alias" },
+			{ "id": "tapeCop2Register", "superType": "variable", "description": "COP2 data or control register alias" },
+			{ "id": "tapeDuffleType", "superType": "type", "description": "Duffle type or type constructor" },
+			{ "id": "tapeAttribute", "superType": "keyword", "description": "Duffle linkage or storage attribute" },
+			{ "id": "keyword", "description": "Standard keyword (DSL built-in macros)" },
+			{ "id": "macro", "description": "Standard macro (utility #define with no instruction domain)" }
+		],
+		"semanticTokenModifiers": [
+			{ "id": "tapeRead", "description": "Register declared in atom_reads" },
+			{ "id": "tapeWrite", "description": "Register declared in atom_writes" },
+			{ "id": "tapeAuto", "description": "Auto-allocated register" }
+		],
+		"semanticTokenScopes": [
+			{
+				"language": "c",
+				"scopes": {
+					"tapeAtomKeyword": ["keyword.control.duffle.atom"],
+					"tapeAtomName": ["entity.name.function.duffle.atom"],
+					"tapeComponentKeyword": ["keyword.control.duffle.component"],
+					"tapeComponentName": ["entity.name.function.duffle.component"],
+					"tapeAnnotation": ["support.function.duffle.annotation"],
+					"tapeBindType": ["entity.name.type.duffle.bind"],
+					"tapePhase": ["entity.name.tag.duffle.phase"],
+					"tapeLabel": ["entity.name.label.duffle.atom"],
+					"tapeCpuInstruction": ["support.function.duffle.cpu"],
+					"tapeControlFlow": ["keyword.control.duffle.branch"],
+					"tapeGteInstruction": ["support.function.duffle.gte"],
+					"tapeGpuInstruction": ["support.function.duffle.gpu"],
+					"tapeComponentInstruction": ["support.function.duffle.component"],
+					"tapeDelaySlot": ["keyword.operator.duffle.delayslot"],
+					"tapeGprRegister": ["variable.other.constant.duffle.gpr"],
+					"tapeCop2Register": ["variable.other.constant.duffle.cop2"],
+					"tapeDuffleType": ["storage.type.duffle.type"],
+					"tapeAttribute": ["storage.modifier.duffle.attr"],
+				"keyword": ["keyword"],
+				"macro": ["entity.name.function.preprocessor"]
+				}
+			}
+		],
+		"grammars": [
+			{
+				"scopeName": "tape_atom.injection",
+				"path": "./syntaxes/tape_atom.tmLanguage.json",
+				"injectTo": ["source.c", "source.cpp"]
+			}
+		]
+	}
+}

.vscode/tape-atom-syntax/source-index.js

@@ -0,0 +1,341 @@
+"use strict";
+
+const path = require("node:path");
+const { buildCallContexts, lex, nearestCall } = require("./lexer");
+
+const BASE_TYPES = [
+	"B1", "B2", "B4", "B8", "F4", "F8", "S1", "S2", "S4", "S8",
+	"U1", "U2", "U4", "U8", "MipsAtom", "MipsCode", "Reg",
+];
+
+const C_BUILTINS = new Set([
+	"void", "type", "char", "short", "int", "long", "float", "double",
+	"unsigned", "signed", "bool", "size_t", "uint8_t", "uint16_t", "uint32_t",
+	"int8_t", "int16_t", "int32_t",
+]);
+
+const BASE_ATTRIBUTES = [
+	"FI_", "I_", "NI_", "Relative_", "Struct_", "Enum_", "Union_", "Array_",
+	"Slice_", "TypeR_", "TypeV_", "align_", "internal", "local_persist", "global",
+	"RO_", "LP_", "gknown", "expect_", "cexpr_",
+	"asm", "asm_words", "asm_rpins", "asm_clobber",
+	"O_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "tr_", "tv_",
+	"rgcc", "r_use", "r_set", "r_mod", "r_imm", "r_mem",
+	"u1_", "u2_", "u4_", "u8_", "s1_", "s2_", "s4_", "s8_",
+	"u1_r", "u2_r", "u4_r", "u8_r", "u1_v", "u2_v", "u4_v", "u8_v",
+];
+
+function createIndex() {
+	return {
+		atoms: new Set(),
+		components: new Set(),
+		componentAliases: new Set(),
+		macros: new Map(),
+		registers: new Map(),
+		bindTypes: new Set(),
+		types: new Set(BASE_TYPES),
+		phases: new Set(),
+		labels: new Set(),
+		attributes: new Set(BASE_ATTRIBUTES),
+		componentCallees: new Map(),
+	};
+}
+
+function cloneIndex(source) {
+	const result = createIndex();
+	for (const key of ["atoms", "components", "componentAliases", "bindTypes", "types", "phases", "labels", "attributes"]) {
+		for (const value of source[key]) result[key].add(value);
+	}
+	for (const [name, domain] of source.macros) result.macros.set(name, domain);
+	for (const [name, domain] of source.registers) result.registers.set(name, domain);
+	for (const [name, callees] of source.componentCallees) result.componentCallees.set(name, callees.slice());
+	return result;
+}
+
+function mergeIndexes(...sources) {
+	const result = createIndex();
+	for (const source of sources) {
+		if (!source) continue;
+		for (const key of ["atoms", "components", "componentAliases", "bindTypes", "types", "phases", "labels", "attributes"]) {
+			for (const value of source[key]) result[key].add(value);
+		}
+		for (const [name, domain] of source.macros) {
+			const existing = result.macros.get(name);
+			if (!existing || domainRank(domain) >= domainRank(existing)) result.macros.set(name, domain);
+		}
+		for (const [name, domain] of source.registers) result.registers.set(name, domain);
+		for (const [name, callees] of source.componentCallees) {
+			const existing = result.componentCallees.get(name) || [];
+			result.componentCallees.set(name, existing.concat(callees));
+		}
+	}
+	return resolveComponentDomains(result);
+}
+
+function domainFromPath(filePath) {
+	const base = path.basename(filePath.replaceAll("\\", "/")).toLowerCase();
+	if (base === "mips.h") return "cpu";
+	if (base === "gte.h") return "gte";
+	if (base === "gp.h") return "gpu";
+	return null;
+}
+
+function prefixDomain(name) {
+	if (/^(?:branch_|jump_|call_)/.test(name)) return "control";
+	if (/^gte_(?!cr_)/.test(name) || name.startsWith("mac_gte_") || name.startsWith("ac_gte_")) return "gte";
+	if (/^gp[01]_/.test(name) || name.startsWith("mac_gp_") || name.startsWith("ac_gp_")) return "gpu";
+	return null;
+}
+
+function collectBraceIdentifiers(tokens, openBraceIndex) {
+	const names = [];
+	let depth = 0;
+	for (let tokenIndex = openBraceIndex; tokenIndex < tokens.length; tokenIndex += 1) {
+		if (tokens[tokenIndex].text === "{") depth += 1;
+		if (tokens[tokenIndex].text === "}") {
+			depth -= 1;
+			if (depth === 0) break;
+		}
+		if (tokens[tokenIndex].kind === "identifier") names.push(tokens[tokenIndex].text);
+	}
+	return names;
+}
+
+function resolveComponentDomains(index) {
+	const hardwareRank = { cpu: 1, gpu: 2, gte: 3, control: 4 };
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const [alias, callees] of index.componentCallees) {
+			let best = index.macros.get(alias) || "component";
+			let bestRank = hardwareRank[best] || 0;
+			for (const callee of callees) {
+				const domain = prefixDomain(callee) || index.macros.get(callee);
+				const rank = hardwareRank[domain] || 0;
+				if (rank > bestRank) {
+					best = domain;
+					bestRank = rank;
+				}
+			}
+			if (bestRank > 0 && index.macros.get(alias) !== best) {
+				index.macros.set(alias, best);
+				changed = true;
+			}
+		}
+	}
+	return index;
+}
+
+function domainRank(domain) {
+	if (domain === "control") return 4;
+	if (domain === "cpu" || domain === "gte" || domain === "gpu") return 3;
+	if (domain === "component") return 2;
+	return 1;
+}
+
+function registerKind(name) {
+	if (/^R_[A-Za-z0-9_]+$/.test(name)) return "gpr";
+	if (/^(?:C2_|gte_cr_)[A-Za-z0-9_]+$/.test(name)) return "cop2";
+	return null;
+}
+
+function componentAlias(name) {
+	return name.startsWith("ac_") ? `mac_${name.slice(3)}` : null;
+}
+
+function findFunctionNameBefore(tokens, calleeTokenIndex) {
+	let closeIndex = calleeTokenIndex - 1;
+	while (closeIndex >= 0 && tokens[closeIndex].kind === "identifier" && tokens[closeIndex].text === "atom_dbg_skip") {
+		closeIndex -= 1;
+	}
+	if (!tokens[closeIndex] || tokens[closeIndex].text !== ")") return null;
+
+	let depth = 1;
+	for (let tokenIndex = closeIndex - 1; tokenIndex >= 0; tokenIndex -= 1) {
+		if (tokens[tokenIndex].text === ")") depth += 1;
+		if (tokens[tokenIndex].text === "(") depth -= 1;
+		if (depth !== 0) continue;
+		const name = tokens[tokenIndex - 1];
+		return name && name.kind === "identifier" ? name : null;
+	}
+	return null;
+}
+
+function scanSource(source, filePath) {
+	const lexical = lex(source);
+	const balanced = buildCallContexts(lexical.tokens);
+	const tokens = lexical.tokens;
+	const contexts = balanced.contexts;
+	const index = createIndex();
+	const declarations = new Map();
+	const domain = domainFromPath(filePath);
+
+	function mark(token, role, modifiers = ["declaration"]) {
+		declarations.set(token.start, { role, modifiers });
+	}
+
+	function addComponent(token) {
+		index.components.add(token.text);
+		mark(token, "componentName");
+		const alias = componentAlias(token.text);
+		if (alias) {
+			index.componentAliases.add(alias);
+			index.macros.set(alias, prefixDomain(alias) || prefixDomain(token.text) || "component");
+		}
+	}
+
+	function bindComponentCallees(alias, callees) {
+		if (!alias) return;
+		index.componentAliases.add(alias);
+		index.componentCallees.set(alias, callees);
+		if (!index.macros.has(alias)) index.macros.set(alias, "component");
+	}
+
+	for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex += 1) {
+		const token = tokens[tokenIndex];
+		if (token.kind !== "identifier") continue;
+
+		const kind = registerKind(token.text);
+		if (kind) {
+			index.registers.set(token.text, kind);
+			if (tokens[tokenIndex + 1] && tokens[tokenIndex + 1].text === "=") {
+				mark(token, kind === "gpr" ? "gprRegister" : "cop2Register");
+			}
+		}
+
+		const context = nearestCall(contexts, tokenIndex);
+		if (context && context.argIndex === 0) {
+			if (context.callee === "MipsAtom_") {
+				index.atoms.add(token.text);
+				mark(token, "atomName");
+			}
+			if (context.callee === "MipsAtomComp_") addComponent(token);
+			if (context.callee === "atom_bind") index.bindTypes.add(token.text);
+			if (context.callee === "atom_phase" || context.callee === "phase_auto_reg") index.phases.add(token.text);
+			if (context.callee === "atom_label" || context.callee === "atom_offset") index.labels.add(token.text);
+		}
+
+		const isWrappedType = context && (
+			((context.callee === "Struct_" || context.callee === "Union_") && context.argIndex === 0) ||
+			(context.callee === "Enum_" && context.argIndex === 1)
+		);
+		if (isWrappedType) {
+			index.types.add(token.text);
+			mark(token, token.text.startsWith("Binds_") ? "bindType" : "duffleType");
+			if (token.text.startsWith("Binds_")) index.bindTypes.add(token.text);
+		}
+
+		if (context && context.callee === "atom_offset" && context.argIndex === 1) index.labels.add(token.text);
+
+		if (context && context.callee === "atom_auto_reg") {
+			if (context.argIndex === 0) index.atoms.add(token.text);
+			if (context.argIndex === 1) {
+				index.registers.set(token.text, "gpr");
+				mark(token, "gprRegister", ["declaration", "tapeAuto"]);
+			}
+		}
+
+		if (context && context.callee === "phase_auto_reg" && context.argIndex === 1) {
+			index.registers.set(token.text, "gpr");
+			mark(token, "gprRegister", ["declaration", "tapeAuto"]);
+		}
+
+		if (token.text === "define" && tokens[tokenIndex - 1] && tokens[tokenIndex - 1].text === "#") {
+			const name = tokens[tokenIndex + 1];
+			if (name && name.kind === "identifier" && name.line === token.line) {
+				if (/^(?:RegUse_|Struct_|Enum_|Union_|TypeR_|TypeV_|Relative_|Binds_)/.test(name.text)) {
+					index.types.add(name.text);
+				} else if (/^(?:ac_|mac_)/.test(name.text)) {
+					const alias = name.text.startsWith("ac_") ? componentAlias(name.text) : name.text;
+					const rest = [];
+					for (let restIndex = tokenIndex + 2; restIndex < tokens.length && tokens[restIndex].line === name.line; restIndex += 1) {
+						if (tokens[restIndex].kind === "identifier") rest.push(tokens[restIndex].text);
+					}
+					if (alias) {
+						index.componentAliases.add(alias);
+						index.macros.set(alias, prefixDomain(alias) || "component");
+						if (rest.length) index.componentCallees.set(alias, rest);
+					}
+				} else {
+					index.macros.set(name.text, domain || "utility");
+				}
+			}
+		}
+
+		if (token.text === "typedef") {
+			let endIndex = tokenIndex + 1;
+			let hasBrace = false;
+			let lastIdentifier = null;
+			while (endIndex < tokens.length && tokens[endIndex].text !== ";") {
+				if (tokens[endIndex].text === "{") hasBrace = true;
+				if (tokens[endIndex].kind === "identifier" && !C_BUILTINS.has(tokens[endIndex].text)) lastIdentifier = tokens[endIndex];
+				endIndex += 1;
+			}
+			if (!hasBrace && lastIdentifier && !C_BUILTINS.has(lastIdentifier.text)) {
+				index.types.add(lastIdentifier.text);
+				mark(lastIdentifier, "duffleType");
+			}
+		}
+
+		if (token.text === "MipsAtom_Proc_") {
+			const functionName = findFunctionNameBefore(tokens, tokenIndex);
+			if (functionName) {
+				const atomName = functionName.text.endsWith("_proc")
+					? functionName.text.slice(0, -5)
+					: functionName.text;
+				index.atoms.add(atomName);
+				index.atoms.add(functionName.text);
+				mark(functionName, "atomName");
+			}
+		}
+
+		if (token.text === "MipsAtomComp_Proc_") {
+			const functionName = findFunctionNameBefore(tokens, tokenIndex);
+			if (functionName) addComponent(functionName);
+		}
+	}
+
+	for (const call of balanced.calls) {
+		if (call.callee === "MipsAtomComp_") {
+			const name = tokens[call.openTokenIndex + 1];
+			const brace = tokens[call.closeTokenIndex + 1];
+			if (name && name.kind === "identifier" && brace && brace.text === "{") {
+				bindComponentCallees(componentAlias(name.text), collectBraceIdentifiers(tokens, call.closeTokenIndex + 1));
+			}
+		}
+		if (call.callee === "MipsAtomComp_Proc_") {
+			const functionName = findFunctionNameBefore(tokens, call.calleeTokenIndex);
+			let braceIndex = -1;
+			for (let tokenIndex = call.openTokenIndex + 1; tokenIndex < call.closeTokenIndex; tokenIndex += 1) {
+				if (tokens[tokenIndex].text === "{") {
+					braceIndex = tokenIndex;
+					break;
+				}
+			}
+			if (functionName && braceIndex >= 0) {
+				bindComponentCallees(componentAlias(functionName.text), collectBraceIdentifiers(tokens, braceIndex));
+			}
+		}
+		if (!domain) continue;
+		const name = tokens[call.calleeTokenIndex];
+		const after = tokens[call.closeTokenIndex + 1];
+		if (!name || !after || after.text !== "{") continue;
+		if (/^(?:gp0_|gp1_|gte_|mac_)/.test(name.text)) index.macros.set(name.text, domain);
+	}
+
+	return {
+		index: resolveComponentDomains(cloneIndex(index)),
+		declarations,
+		tokens,
+		contexts,
+		errors: [...lexical.errors, ...balanced.errors],
+	};
+}
+
+module.exports = {
+	createIndex,
+	domainFromPath,
+	mergeIndexes,
+	resolveComponentDomains,
+	scanSource,
+};

.vscode/tape-atom-syntax/syntaxes/tape_atom.tmLanguage.json

@@ -0,0 +1,71 @@
+{
+	"scopeName": "tape_atom.injection",
+	"injectionSelector": "L:source.c -comment -string, L:source.cpp -comment -string",
+	"patterns": [
+		{ "include": "#atom-declarations" },
+		{ "include": "#component-declarations" },
+		{ "include": "#annotation-arguments" },
+		{ "include": "#annotations" },
+		{ "include": "#delay-slots" },
+		{ "include": "#types" },
+		{ "include": "#attributes" }
+	],
+	"repository": {
+		"atom-declarations": {
+			"patterns": [
+				{
+					"match": "\\b(MipsAtom_)\\s*\\(\\s*([A-Za-z_][A-Za-z0-9_]*)",
+					"captures": {
+						"1": { "name": "keyword.control.duffle.atom" },
+						"2": { "name": "entity.name.function.duffle.atom" }
+					}
+				},
+				{ "match": "\\bMipsAtom_Proc_\\b", "name": "keyword.control.duffle.atom" },
+				{ "match": "\\b[A-Za-z_][A-Za-z0-9_]*_proc\\b", "name": "entity.name.function.duffle.atom" }
+			]
+		},
+		"component-declarations": {
+			"patterns": [
+				{
+					"match": "\\b(MipsAtomComp_)\\s*\\(\\s*(ac_[A-Za-z0-9_]*)",
+					"captures": {
+						"1": { "name": "keyword" },
+						"2": { "name": "entity.name.function.duffle.component" }
+					}
+				},
+				{ "match": "\\bMipsAtomComp_Proc_\\b", "name": "keyword" }
+			]
+		},
+		"annotation-arguments": {
+			"patterns": [
+				{
+					"match": "\\b(atom_offset)\\s*\\(\\s*([A-Za-z_][A-Za-z0-9_]*)\\s*,\\s*([A-Za-z_][A-Za-z0-9_]*)",
+					"captures": {
+						"1": { "name": "support.function.duffle.annotation" },
+						"2": { "name": "entity.name.label.duffle.atom" },
+						"3": { "name": "entity.name.label.duffle.atom" }
+					}
+				},
+				{ "match": "(?<=\\batom_bind\\()\\s*Binds_[A-Za-z0-9_]+", "name": "entity.name.type.duffle.bind" },
+				{ "match": "(?<=\\batom_phase\\()\\s*[A-Za-z_][A-Za-z0-9_]*", "name": "entity.name.tag.duffle.phase" },
+				{ "match": "(?<=\\batom_label\\()\\s*[A-Za-z_][A-Za-z0-9_]*", "name": "entity.name.label.duffle.atom" }
+			]
+		},
+		"annotations": {
+			"match": "\\b(atom_info|atom_bind|atom_reads|atom_writes|atom_label|atom_offset|atom_reg|atom_type|atom_ctx|atom_phase|atom_auto_reg|phase_auto_reg|atom_dbg_skip)\\b",
+			"name": "support.function.duffle.annotation"
+		},
+		"delay-slots": {
+			"match": "\\b(LdSlot_|BdSlot_|DmaSlot_|GteDelay_)\\b",
+			"name": "keyword.operator.duffle.delayslot"
+		},
+		"types": {
+			"match": "\\b(?:Binds_[A-Za-z0-9_]+|RegUse_[A-Za-z0-9_]+)\\b",
+			"name": "storage.type.duffle.type"
+		},
+		"attributes": {
+			"match": "\\b(?:FI_|I_|NI_|Relative_|Struct_|Enum_|Union_|Array_|Slice_|TypeR_|TypeV_|align_|internal|local_persist|global|RO_|LP_|gknown|expect_|cexpr_|asm|asm_words|asm_rpins|asm_clobber|O_|S_|C_|T_|tmpl|glue|r_|v_|tr_|tv_|rgcc|r_use|r_set|r_mod|r_imm|r_mem|u[1248]_|u[1248]_r|u[1248]_v|s[1248]_)\\b",
+			"name": "keyword"
+		}
+	}
+}

.vscode/tape-atom-syntax/test/classifier.test.js

@@ -0,0 +1,128 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { classifyDocument } = require("../classifier");
+const { createIndex } = require("../source-index");
+
+function byText(result, text) {
+	return result.spans.filter((span) => span.text === text);
+}
+
+test("classifyDocument distinguishes declaration, annotation, phase, bind, and label roles", () => {
+	const source = [
+		"typedef Struct_(Binds_CubeTri) { U4 PrimCursor; };",
+		"MipsAtom_(cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_phase(cube_g4),",
+		"\tatom_reads(R_PrimCursor), atom_writes(R_FaceCursor)) {",
+		"\tbranch_le_zero(R_T0, atom_offset(cull, exit)),",
+		"\tatom_label(exit)",
+		"};",
+	].join("\n");
+
+	const result = classifyDocument(source, "C:/x/code/hello_camera/hello_camera.atom.c", createIndex());
+
+	assert.equal(byText(result, "MipsAtom_")[0].type, "tapeAtomKeyword");
+	assert.deepEqual(byText(result, "cube_g4_face")[0].modifiers, ["declaration"]);
+	assert.equal(byText(result, "atom_bind")[0].type, "tapeAnnotation");
+	assert.equal(byText(result, "Binds_CubeTri").at(-1).type, "tapeBindType");
+	assert.equal(byText(result, "cube_g4")[0].type, "tapePhase");
+	assert.deepEqual(byText(result, "cube_g4")[0].modifiers, ["declaration"]);
+	assert.equal(byText(result, "cull")[0].type, "tapeLabel");
+	assert.equal(byText(result, "exit").every((span) => span.type === "tapeLabel"), true);
+});
+
+test("classifyDocument applies read and write modifiers to GPRs", () => {
+	const source = "atom_info(atom_reads(R_PrimCursor), atom_writes(R_FaceCursor))";
+	const result = classifyDocument(source, "C:/x/code/test.atom.c", createIndex());
+
+	assert.deepEqual(byText(result, "R_PrimCursor")[0].modifiers, ["tapeRead"]);
+	assert.deepEqual(byText(result, "R_FaceCursor")[0].modifiers, ["tapeWrite"]);
+});
+
+test("classifyDocument separates CPU, GTE, GPU, and component domains", () => {
+	const workspace = createIndex();
+	workspace.macros.set("load_word", "cpu");
+	workspace.macros.set("gte_cmdw_rtpt", "gte");
+	workspace.macros.set("gp1_word_DisplayOn", "gpu");
+	workspace.macros.set("mac_yield", "control");
+	workspace.componentAliases.add("mac_yield");
+
+	const source = "load_word(R_T0, R_T1, 0), gte_cmdw_rtpt, gp1_word_DisplayOn(), mac_yield(), C2_MAC0, gte_cr_OFX_Code";
+	const result = classifyDocument(source, "C:/x/code/test.c", workspace);
+
+	assert.equal(byText(result, "load_word")[0].type, "tapeCpuInstruction");
+	assert.equal(byText(result, "gte_cmdw_rtpt")[0].type, "tapeGteInstruction");
+	assert.equal(byText(result, "gp1_word_DisplayOn")[0].type, "tapeGpuInstruction");
+	assert.equal(byText(result, "mac_yield")[0].type, "tapeControlFlow");
+	assert.equal(byText(result, "C2_MAC0")[0].type, "tapeCop2Register");
+	assert.equal(byText(result, "gte_cr_OFX_Code")[0].type, "tapeCop2Register");
+});
+
+test("component invocations keep the domain resolved from their emitted instructions", () => {
+	const workspace = createIndex();
+	workspace.macros.set("mac_load_word_imm", "cpu");
+	workspace.macros.set("mac_gcmd_push", "gpu");
+	workspace.macros.set("mac_gte_store_f3", "gte");
+	workspace.macros.set("mac_load_v3s4", "cpu");
+
+	const source = "mac_load_word_imm(dst, imm), mac_gcmd_push(cmd), mac_gte_store_f3(cursor), mac_load_v3s4()";
+	const result = classifyDocument(source, "C:/x/code/hello_camera/hello_camera.atom.c", workspace);
+
+	assert.equal(byText(result, "mac_load_word_imm")[0].type, "tapeCpuInstruction");
+	assert.equal(byText(result, "mac_gcmd_push")[0].type, "tapeGpuInstruction");
+	assert.equal(byText(result, "mac_gte_store_f3")[0].type, "tapeGteInstruction");
+	assert.equal(byText(result, "mac_load_v3s4")[0].type, "tapeCpuInstruction");
+});
+
+test("utility macros without a hardware domain use the standard macro token", () => {
+	const workspace = createIndex();
+	workspace.macros.set("load_word", "cpu");
+	workspace.macros.set("assert", "utility");
+	workspace.macros.set("stringify", "utility");
+	workspace.macros.set("u4_hi", "utility");
+
+	const source = "load_word(R_T0, R_T1, 0), assert(ok), stringify(name), u4_hi(imm)";
+	const result = classifyDocument(source, "C:/x/code/hello_camera/hello_camera.c", workspace);
+
+	assert.equal(byText(result, "load_word")[0].type, "tapeCpuInstruction");
+	assert.equal(byText(result, "assert")[0].type, "macro");
+	assert.equal(byText(result, "stringify")[0].type, "macro");
+	assert.equal(byText(result, "u4_hi")[0].type, "macro");
+});
+
+test("document-local declarations override an empty workspace index", () => {
+	const source = [
+		"MipsAtomComp_(ac_new_component) { nop };",
+		"MipsAtomComp_Proc_(ab, { nop })",
+		"mac_new_component(),",
+	].join("\n");
+	const result = classifyDocument(source, "C:/x/code/duffle/math.atom.c", createIndex());
+
+	assert.equal(byText(result, "MipsAtomComp_")[0].type, "keyword");
+	assert.equal(byText(result, "MipsAtomComp_Proc_")[0].type, "keyword");
+	assert.equal(byText(result, "ac_new_component")[0].type, "tapeComponentName");
+	assert.equal(byText(result, "mac_new_component")[0].type, "tapeComponentInstruction");
+});
+
+test("delay slot markers share the tapeDelaySlot token", () => {
+	const source = "LdSlot_ nop, BdSlot_ nop, DmaSlot_ nop2, GteDelay_ nop";
+	const result = classifyDocument(source, "C:/x/code/duffle/gte.atom.c", createIndex());
+
+	assert.equal(byText(result, "LdSlot_")[0].type, "tapeDelaySlot");
+	assert.equal(byText(result, "BdSlot_")[0].type, "tapeDelaySlot");
+	assert.equal(byText(result, "DmaSlot_")[0].type, "tapeDelaySlot");
+	assert.equal(byText(result, "GteDelay_")[0].type, "tapeDelaySlot");
+});
+
+test("classifier returns ordered non-overlapping spans and partial malformed output", () => {
+	const source = "atom_reads(R_A /* broken";
+	const result = classifyDocument(source, "C:/x/code/test.atom.c", createIndex());
+
+	assert.equal(result.errors.some((error) => error.kind === "unterminated-block-comment"), true);
+	for (let spanIndex = 1; spanIndex < result.spans.length; spanIndex += 1) {
+		const previous = result.spans[spanIndex - 1];
+		const current = result.spans[spanIndex];
+		assert.equal(previous.start + previous.length <= current.start, true);
+	}
+});

.vscode/tape-atom-syntax/test/contract.test.js

@@ -0,0 +1,88 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+const { TOKEN_MODIFIERS, TOKEN_TYPES } = require("../classifier");
+
+const ROOT = path.resolve(__dirname, "..");
+
+function readJson(filePath) {
+	const raw = fs.readFileSync(filePath, "utf8");
+	const stripped = raw.replace(/\/\/.*$/gm, "").replace(/,\s*([}\]])/g, "$1");
+	return JSON.parse(stripped);
+}
+
+function collectScopeNames(value, output = new Set()) {
+	if (Array.isArray(value)) {
+		for (const entry of value) collectScopeNames(entry, output);
+		return output;
+	}
+	if (!value || typeof value !== "object") return output;
+	if (typeof value.name === "string") output.add(value.name);
+	for (const child of Object.values(value)) collectScopeNames(child, output);
+	return output;
+}
+
+test("package semantic legend matches classifier exports", () => {
+	const packageJson = readJson(path.join(ROOT, "package.json"));
+	const contributedTypes = packageJson.contributes.semanticTokenTypes.map((entry) => entry.id);
+	const contributedModifiers = packageJson.contributes.semanticTokenModifiers.map((entry) => entry.id);
+
+	assert.equal(packageJson.version, "0.3.0");
+	assert.deepEqual(contributedTypes, TOKEN_TYPES);
+	assert.deepEqual(contributedModifiers, TOKEN_MODIFIERS.filter((name) => name !== "declaration"));
+});
+
+test("package includes runtime files only and acknowledges local-only metadata", () => {
+	const packageJson = readJson(path.join(ROOT, "package.json"));
+
+	assert.deepEqual(packageJson.files, [
+		"classifier.js",
+		"extension.js",
+		"lexer.js",
+		"source-index.js",
+		"syntaxes/tape_atom.tmLanguage.json",
+	]);
+	assert.equal(packageJson.scripts.package.includes("--allow-missing-repository"), true);
+	assert.equal(packageJson.scripts.package.includes("--skip-license"), true);
+});
+
+test("every semantic token has a scope mapping; DSL-specific tokens also have grammar scopes", () => {
+	const packageJson = readJson(path.join(ROOT, "package.json"));
+	const grammar = readJson(path.join(ROOT, "syntaxes", "tape_atom.tmLanguage.json"));
+	const mappings = packageJson.contributes.semanticTokenScopes[0].scopes;
+	const grammarScopes = collectScopeNames(grammar);
+
+	const grammarRequired = new Set([
+		"tapeAtomKeyword", "tapeAtomName", "tapeComponentName",
+		"tapeAnnotation", "tapeBindType", "tapePhase", "tapeLabel",
+		"tapeDelaySlot", "tapeDuffleType", "keyword",
+	]);
+
+	for (const tokenType of TOKEN_TYPES) {
+		assert.equal(Array.isArray(mappings[tokenType]), true, `missing scope mapping: ${tokenType}`);
+		if (grammarRequired.has(tokenType)) {
+			assert.equal(mappings[tokenType].some((scope) => grammarScopes.has(scope)), true, `grammar does not emit: ${tokenType}`);
+		}
+	}
+});
+
+test("TextMate offset labels stay scoped to atom_offset calls", () => {
+	const grammar = readJson(path.join(ROOT, "syntaxes", "tape_atom.tmLanguage.json"));
+	const serialized = JSON.stringify(grammar);
+	const offsetRule = grammar.repository["annotation-arguments"].patterns
+		.find((rule) => rule.match.includes("atom_offset"));
+
+	assert.equal(serialized.includes("(?<=,)"), false);
+	assert.equal(offsetRule.captures[1].name, "support.function.duffle.annotation");
+	assert.equal(offsetRule.captures[2].name, "entity.name.label.duffle.atom");
+	assert.equal(offsetRule.captures[3].name, "entity.name.label.duffle.atom");
+});
+
+test("workspace enables semantic highlighting", () => {
+	const settings = readJson(path.resolve(ROOT, "..", "settings.json"));
+	assert.equal(settings["editor.semanticHighlighting.enabled"], true);
+});

.vscode/tape-atom-syntax/test/lexer.test.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { buildCallContexts, lex, nearestCall } = require("../lexer");
+
+test("lex skips comments, strings, and character literals", () => {
+	const source = [
+		"MipsAtom_(visible)",
+		"// MipsAtom_(line_comment)",
+		"const char *s = \"atom_reads(R_Hidden)\";",
+		"char c = '\\''; /* gte_cmdw_hidden */",
+		"atom_reads(R_Visible)",
+	].join("\n");
+
+	const result = lex(source);
+	const identifiers = result.tokens
+		.filter((token) => token.kind === "identifier")
+		.map((token) => token.text);
+
+	assert.deepEqual(result.errors, []);
+	assert.equal(identifiers.includes("visible"), true);
+	assert.equal(identifiers.includes("R_Visible"), true);
+	assert.equal(identifiers.includes("line_comment"), false);
+	assert.equal(identifiers.includes("R_Hidden"), false);
+	assert.equal(identifiers.includes("gte_cmdw_hidden"), false);
+});
+
+test("lex reports unterminated block comments without returning comment tokens", () => {
+	const result = lex("R_Visible /* atom_reads(R_Hidden)");
+
+	assert.equal(result.tokens.some((token) => token.text === "R_Visible"), true);
+	assert.equal(result.tokens.some((token) => token.text === "R_Hidden"), false);
+	assert.deepEqual(result.errors.map((error) => error.kind), ["unterminated-block-comment"]);
+});
+
+test("line comments stop at CRLF boundaries", () => {
+	const result = lex("// atom_reads(R_Hidden)\r\natom_reads(R_Visible)\r\n");
+	const identifiers = result.tokens
+		.filter((token) => token.kind === "identifier")
+		.map((token) => token.text);
+
+	assert.equal(identifiers.includes("R_Hidden"), false);
+	assert.equal(identifiers.includes("R_Visible"), true);
+});
+
+test("balanced contexts retain multiline nesting and argument indexes", () => {
+	const source = [
+		"atom_info(",
+		"\tatom_phase(cube_g4),",
+		"\tatom_reads(R_A, nested(R_B, R_C)),",
+		"\tatom_writes(R_D)",
+		")",
+	].join("\n");
+	const lexical = lex(source);
+	const balanced = buildCallContexts(lexical.tokens);
+
+	const byText = new Map();
+	lexical.tokens.forEach((token, index) => {
+		if (token.kind === "identifier") byText.set(token.text, index);
+	});
+
+	assert.equal(nearestCall(balanced.contexts, byText.get("cube_g4")).callee, "atom_phase");
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_A")).callee, "atom_reads");
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_A")).argIndex, 0);
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_C")).callee, "nested");
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_D")).callee, "atom_writes");
+	assert.deepEqual(balanced.errors, []);
+});
+
+test("balanced contexts report unmatched parentheses", () => {
+	const lexical = lex("atom_reads(R_A");
+	const balanced = buildCallContexts(lexical.tokens);
+
+	assert.deepEqual(balanced.errors.map((error) => error.kind), ["unmatched-open-paren"]);
+});

.vscode/tape-atom-syntax/test/source-index.test.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+	createIndex,
+	domainFromPath,
+	mergeIndexes,
+	scanSource,
+} = require("../source-index");
+
+test("scanSource discovers current atom and component forms", () => {
+	const source = [
+		"MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4), atom_reads(R_PrimCursor)) { mac_yield() };",
+		"MipsAtomComp_(ac_load_pair) { load_word(R_T0, R_T1, 0) };",
+		"internal MipsAtom* normalize_proc(AtomArena_R aa) MipsAtom_Proc_(aa, { mac_yield() })",
+		"FI_ void ac_store_pair(MipsAtomBuilder_R ab) atom_dbg_skip MipsAtomComp_Proc_(ab, { store_word(R_T0, R_T1, 0) })",
+	].join("\n");
+
+	const result = scanSource(source, "C:/projects/Pikuma/ps1/code/duffle/mips.atom.c");
+
+	assert.equal(result.index.atoms.has("cube_g4_face"), true);
+	assert.equal(result.index.atoms.has("normalize"), true);
+	assert.equal(result.index.components.has("ac_load_pair"), true);
+	assert.equal(result.index.components.has("ac_store_pair"), true);
+	assert.equal(result.index.componentAliases.has("mac_load_pair"), true);
+	assert.equal(result.index.componentAliases.has("mac_store_pair"), true);
+	assert.equal(result.index.macros.get("mac_store_pair"), "component");
+	assert.equal(result.index.componentCallees.get("mac_store_pair").includes("store_word"), true);
+	assert.equal(result.index.phases.has("cube_g4"), true);
+	assert.equal(result.index.registers.get("R_PrimCursor"), "gpr");
+	assert.deepEqual(result.errors, []);
+});
+
+test("scanSource discovers binds, labels, registers, typedefs, and macro domains", () => {
+	const source = [
+		"typedef Struct_(Binds_CubeTri) { U4 PrimCursor; };",
+		"typedef Enum_(U4, PadStatus) { PadStatus_Ok };",
+		"typedef U4 const MipsCode;",
+		"enum { R_PrimCursor = R_T7 atom_reg, C2_Custom = 12, gte_cr_Custom = 13 };",
+		"#define load_word(rt, base, off) enc_i(rt, base, off)",
+		"atom_bind(Binds_CubeTri)",
+		"atom_label(exit)",
+		"atom_offset(entry, exit)",
+	].join("\n");
+
+	const result = scanSource(source, "C:/projects/Pikuma/ps1/code/duffle/mips.h");
+
+	assert.equal(result.index.bindTypes.has("Binds_CubeTri"), true);
+	assert.equal(result.index.types.has("PadStatus"), true);
+	assert.equal(result.index.types.has("MipsCode"), true);
+	assert.equal(result.index.registers.get("R_PrimCursor"), "gpr");
+	assert.equal(result.index.registers.get("C2_Custom"), "cop2");
+	assert.equal(result.index.registers.get("gte_cr_Custom"), "cop2");
+	assert.equal(result.index.macros.get("load_word"), "cpu");
+	assert.equal(result.index.labels.has("entry"), true);
+	assert.equal(result.index.labels.has("exit"), true);
+});
+
+test("domainFromPath uses the declaration file rather than parent directory names", () => {
+	assert.equal(domainFromPath("C:/x/code/hello_gte/hello_gte.atom.c"), null);
+	assert.equal(domainFromPath("C:/x/code/duffle/mips.h"), "cpu");
+	assert.equal(domainFromPath("C:/x/code/duffle/gte.h"), "gte");
+	assert.equal(domainFromPath("C:/x/code/duffle/gp.h"), "gpu");
+});
+
+test("component aliases inherit the domain of the instructions they emit", () => {
+	const headers = mergeIndexes(
+		scanSource("#define load_word(a,b,c) 1\n#define store_word(a,b,c) 1\n#define shift_aright_var(a,b,c) 1\n#define jump_reg(rd) 1\n", "C:/x/code/duffle/mips.h").index,
+		scanSource("#define gte_sw(rt, base, off) 1\n", "C:/x/code/duffle/gte.h").index
+	);
+	const math = scanSource(
+		[
+			"MipsAtomComp_(ac_load_v3s4) { load_word(R_T0, R_T1, 0) };",
+			"#define mac_load_p3s4 mac_load_v3s4",
+		].join("\n"),
+		"C:/x/code/duffle/math.atom.c"
+	);
+	const shift = scanSource(
+		"MipsAtomComp_(ac_shift_aright_var_v3_self) { shift_aright_var(R_T0, R_T0, R_T1) };",
+		"C:/x/code/duffle/gte.atom.c"
+	);
+	const gte = scanSource(
+		"MipsAtomComp_(ac_gte_store_f3) { gte_sw(C2_SXY0, R_T0, 0) };",
+		"C:/x/code/duffle/gte.atom.c"
+	);
+	const yieldAtom = scanSource(
+		"MipsAtomComp_(ac_yield) { load_word(R_AtomJmp, R_TapePtr, 0), jump_reg(R_AtomJmp), nop };",
+		"C:/x/code/duffle/lottes_tape.h"
+	);
+
+	const merged = mergeIndexes(headers, math.index, shift.index, gte.index, yieldAtom.index);
+	assert.equal(merged.macros.get("mac_load_v3s4"), "cpu");
+	assert.equal(merged.macros.get("mac_load_p3s4"), "cpu");
+	assert.equal(merged.macros.get("mac_shift_aright_var_v3_self"), "cpu");
+	assert.equal(merged.macros.get("mac_gte_store_f3"), "gte");
+	assert.equal(merged.macros.get("mac_yield"), "control");
+});
+
+test("scanSource tags utility header defines as utility, not a hardware domain", () => {
+	const source = [
+		"#define assert(cond) ((void)(cond))",
+		"#define stringify(name) #name",
+		"#define u4_hi(imm) ((imm) >> 16)",
+	].join("\n");
+	const result = scanSource(source, "C:/projects/Pikuma/ps1/code/duffle/dsl.h");
+
+	assert.equal(result.index.macros.get("assert"), "utility");
+	assert.equal(result.index.macros.get("stringify"), "utility");
+	assert.equal(result.index.macros.get("u4_hi"), "utility");
+});
+
+test("mergeIndexes prefers a hardware domain over a later utility define", () => {
+	const left = createIndex();
+	left.macros.set("sub_s", "utility");
+	const right = createIndex();
+	right.macros.set("sub_s", "cpu");
+
+	assert.equal(mergeIndexes(left, right).macros.get("sub_s"), "cpu");
+	assert.equal(mergeIndexes(right, left).macros.get("sub_s"), "cpu");
+});
+
+test("mergeIndexes preserves domain-specific aliases", () => {
+	const left = createIndex();
+	left.macros.set("load_word", "cpu");
+	const right = createIndex();
+	right.componentAliases.add("mac_gte_store");
+	right.macros.set("mac_gte_store", "gte");
+
+	const merged = mergeIndexes(left, right);
+	assert.equal(merged.macros.get("load_word"), "cpu");
+	assert.equal(merged.macros.get("mac_gte_store"), "gte");
+});

LICENSE

@@ -1,24 +1,17 @@
-This is free and unencumbered software released into the public domain.
+Copyright (C) 2026 Edward R. Gonzalez
 
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
 
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.

code/duffle/bios.h

@@ -1,6 +1,7 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #endif
+
 enum {
 	bios_init_pad_2  = 0x12,
 	bios_start_pad_2 = 0x13,

code/duffle/dsl.atom.h

@@ -70,8 +70,8 @@
 /* ----------------------------------------------------------------------------
  * atom_reg (per-enum opt-in marker for the DWARF register-alias registry)
  *
- * The bare `atom_reg` token adjacent to an enum entry in mips.h / lottes_tape.h flags that alias as debug-visible for scan_source's register_alias_registry.
- * The C preprocessor strips it to a comment so no runtime symbol is created; the Lua scanner reads the bare token.
+ * Bare `atom_reg` token adjacent to an enum entry that alias as debug-visible for scan_source's register_alias_registry.
+ * Lua scanner reads the bare token.
  * ----------------------------------------------------------------------------*/
 #define atom_reg /* atom_reg: opt the preceding enum entry into the DWARF registry */
 
@@ -160,6 +160,8 @@
  * ----------------------------------------------------------------------------*/
 #define atom_bind(binds_struct)  /* atom_bind(binds_struct) */
 
+#define Binds_(type) (tmpl(Binds,type)) // TODO(Ed): Do we want to use this?
+
 /* ============================================================================
  * atom_label / atom_offset — branch target machinery
  *

code/duffle/dsl.h

@@ -3,7 +3,7 @@
 #	include "assert.h"
 #endif
 
-#define offset_of(type, member)  cast(U8,__builtin_offsetof(type,member))
+#define offset_of(type, member)  cast(U8,__builtin_offsetof(type,member)) // Compiler builtin version of O_
 #define static_assert            _Static_assert
 #define typeof                   __typeof__
 #define typeof_ptr(ptr)          typeof((ptr)[0])
@@ -97,6 +97,7 @@
 #define Array_expand(type,len)         type Array_sym(type, len)[len]; typedef PtrSet_(Array_sym(type, len))
 #define Array_(type,len)               Array_expand(type,len)
 #define Bit_(id,b)                     id = (1 << b), tmpl(id,pos) = b
+#define Bitmask_(b)                    (1u << b)
 #define Enum_(underlying_type, symbol) underlying_type TSet_(symbol); enum   symbol
 #define Proc_(symbol)                  symbol
 #define Relative_(symbol)              // Does nothing but annotate that a symbol is associated with another.
@@ -139,16 +140,16 @@ enum { false = 0, true  = 1, true_overflow, };
 
 typedef void Proc_(VoidFn) (void);
 
-#define kilo(n)                (C_(U4, n) << 10)
-#define mega(n)                (C_(U4, n) << 20)
-#define giga(n)                (C_(U4, n) << 30)
-#define tera(n)                (C_(U4, n) << 40)
+#define Kilo_(n) (C_(U4, n) << 10)
+#define Mega_(n) (C_(U4, n) << 20)
+#define Giga_(n) (C_(U4, n) << 30)
+#define Tera_(n) (C_(U4, n) << 40)
 
 #define null             C_(U4,    0)
 #define nullptr          C_(void*, 0)
 #define O_(type, field)  C_(U4, & C_(type*,0)->field)
-#define OA_(type, member, idx)  C_(U4, & C_(type*,0)->member[idx])
-#define OT_(field)              O_(typeof_ptr(& field), filed))
+#define OA_(type, aexpr) C_(U4, & C_(type*,0) aexpr)
+#define OT_(field)       O_(typeof_ptr(& field), field))
 #define S_(data)         C_(U4, sizeof(data))
 
 #define sop_1(op,a,b) C_(U1, s1_(a) op s1_(b))
@@ -185,7 +186,7 @@ def_signed_ops(le, <=)
 #define alignas                             _Alignas
 #define alignof                             _Alignof
 #define byte_pad(amount, ...)               B1 glue(_PAD_, __VA_ARGS__) [amount]
-#define pcast(type, data)                   (C_(type*, & (data)) [0])
+#define C_ptr(type, data)                   (C_(type*, & (data)) [0])
 
 #define dbg_args(...)                      __VA_ARGS__
 
@@ -200,6 +201,8 @@ def_signed_ops(le, <=)
 #define defer_info(type,expr, ...) for(type       info= {__VA_ARGS__}; info.once!=1;++info.once,(expr))    // Defer with tracked state
 
 #define do_while(cond) for (U8 once=0; once!=1 || (cond); ++once)
+
+#define Jmp_nZero_(cond,label) if (cond) goto label;
 #pragma endregion Control Flow & Iteration
 
 #define span_iter(type, iter, m_begin, op, m_end) ( \
@@ -216,16 +219,16 @@ def_signed_ops(le, <=)
 typedef Span_(S4);
 typedef Span_(U4);
 
-#if 0
 #pragma region Debug
-#define debug_trap() __builtin_debugtrap()
+#define debug_trap() __builtin_trap()
 #if BUILD_DEBUG
-IA_ void assert(U8 cond) { if(cond){return;} else{debug_trap(); ms_exit_process(1);} }
+	#define assert(cond) if(cond == false){debug_trap();}
 #else
-#define assert(cond)
+#	ifndef assert
+#		include <assert.h>
+#	endif
 #endif
 #pragma endregion Debug
-#endif
 
 #define GCC_OPTIMIZATION_DISABLE _Pragma("GCC push_options") _Pragma("GCC optimize(\"O0\")")
 #define GCC_OPTIMIZATION_ENABLE  _Pragma("GCC pop_options")

code/duffle/gen/macs.h

@@ -17,7 +17,7 @@
 //   source: C:\projects\Pikuma\ps1\code\duffle\bios.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.c
-//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.c
+//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gte.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gp.atom.c
@@ -35,15 +35,12 @@
  *  These do NOT yield. They are expanded inline inside Tape Atoms.
  * ---------------------------------------------------------------------------*/
 // The 'Yield' sequence for Tape Atoms (mac_yield).
-//   - mac_yield() is the safe default for atom-endings: 4 words, BD-slot of jr is mandatory nop.
-//   - mac_yield_load() + mac_yield_tail():
-//     - unconditional branch: mac_yield_load fills the branch's BD-slot (replaces a nop);
-//     - mac_yield_tail runs at the branch target (does NOT re-load R_AtomJmp).
 #define mac_yield(...) \
 	load_word(R_AtomJmp, R_TapePtr, 0) \
+	LdSlot_ \
 ,	add_ui_self(         R_TapePtr, S_(MipsCode)) \
 ,	jump_reg( R_AtomJmp) \
-,	nop
+,	BdSlot_ nop
 WORD_COUNT(mac_yield, 4)
 
 /* atom_dbg_skip */
@@ -55,9 +52,20 @@ WORD_COUNT(mac_yield_load, 1)
 #define mac_yield_tail(...) \
 	add_ui_self(R_TapePtr, S_(MipsCode)) \
 ,	jump_reg( R_AtomJmp) \
-,	nop
+,	BdSlot_ nop
 WORD_COUNT(mac_yield_tail, 3)
 
+/* atom_dbg_skip */
+#define mac_load_half_v3(tx, ty, tz, base, offset) \
+	load_half(tx, base, offset + OA_(U2,[0])) \
+,	load_half(ty, base, offset + OA_(U2,[1])) \
+,	load_half(tz, base, offset + OA_(U2,[2]))
+WORD_COUNT(mac_load_half_v3, 3)
+
+#define mac_load_v3s2(transfer, base, offset) \
+	mac_load_half_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_load_v3s2, 3)
+
 /* atom_dbg_skip */
 #define mac_load_v2s2(rs_x, rs_y, r_base, offset) \
 	load_half(rs_x, r_base, offset + O_(V3_S2,x)) \
@@ -71,26 +79,75 @@ WORD_COUNT(mac_load_v2s2, 2)
 WORD_COUNT(mac_store_v2s2, 2)
 
 /* atom_dbg_skip */
-#define mac_load_v3s4(rs_x, rs_y, rs_z, r_base, offset) \
-	load_word( rs_x, r_base, offset + O_(V3_S4,x)) \
-,	load_word( rs_y, r_base, offset + O_(V3_S4,y)) \
-,	load_word( rs_z, r_base, offset + O_(V3_S4,z))
+#define mac_load_word_v3(tx, ty, tz, base, offset) \
+	load_word(tx, base, offset + OA_(U4,[0])) \
+,	load_word(ty, base, offset + OA_(U4,[1])) \
+,	load_word(tz, base, offset + OA_(U4,[2]))
+WORD_COUNT(mac_load_word_v3, 3)
+
+#define mac_load_v3s4(transfer, base, offset) \
+	mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
 WORD_COUNT(mac_load_v3s4, 3)
 
-/* atom_dbg_skip */
-#define mac_store_v3s4(rt_x, rt_y, rt_z, base, offset) \
-	store_word(rt_x, base, offset + O_(V3_S4,x)) \
-,	store_word(rt_y, base, offset + O_(V3_S4,y)) \
-,	store_word(rt_z, base, offset + O_(V3_S4,z))
-WORD_COUNT(mac_store_v3s4, 3)
+#define mac_load_p3s4(transfer, base, offset) \
+	mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_load_p3s4, 3)
 
 /* atom_dbg_skip */
-#define mac_sub_v3s4(rds_x, rds_y, rds_z, rt_x, rt_y, rt_z) \
-	sub_s(rds_x, rds_x, rt_x) \
-,	sub_s(rds_y, rds_y, rt_y) \
-,	sub_s(rds_z, rds_z, rt_z)
+#define mac_store_half_v3(tx, ty, tz, base, offset) \
+	store_half(tx, base, offset + OA_(U2,[0])) \
+,	store_half(ty, base, offset + OA_(U2,[1])) \
+,	store_half(tz, base, offset + OA_(U2,[2]))
+WORD_COUNT(mac_store_half_v3, 3)
+
+#define mac_store_v3s2(transfer, base, offset) \
+	mac_store_half_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_store_v3s2, 3)
+
+/* atom_dbg_skip */
+#define mac_store_word_v3(tx, ty, tz, base, offset) \
+	store_word(tx, base, offset + OA_(U4,[0])) \
+,	store_word(ty, base, offset + OA_(U4,[1])) \
+,	store_word(tz, base, offset + OA_(U4,[2]))
+WORD_COUNT(mac_store_word_v3, 3)
+
+#define mac_store_v3s4(transfer, base, offset) \
+	mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_store_v3s4, 3)
+
+#define mac_store_p3s4(transfer, base, offset) \
+	mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_store_p3s4, 3)
+
+/* atom_dbg_skip */
+#define mac_add_si_v3s4(rt_x, rt_y, rt_z, base, offset) \
+	add_si(rt_x, base, O_(V3_S4,x)) \
+,	add_si(rt_y, base, O_(V3_S4,y)) \
+,	add_si(rt_z, base, O_(V3_S4,z))
+WORD_COUNT(mac_add_si_v3s4, 3)
+
+/* atom_dbg_skip */
+#define mac_sub_s_v3(dx, dy, dz, sx, sy, sz, tx, ty, tz) \
+	sub_s(dx, sx, tx) \
+,	sub_s(dy, sy, ty) \
+,	sub_s(dz, sz, tz)
+WORD_COUNT(mac_sub_s_v3, 3)
+
+#define mac_sub_v3s4(d, s, t) \
+	mac_sub_s_v3(d.x, d.y, d.z, s.x, s.y, s.z, t.x, t.y, t.z)
 WORD_COUNT(mac_sub_v3s4, 3)
 
+/* atom_dbg_skip */
+#define mac_sub_s_v3_self(ds_x, ds_y, ds_z, tx, ty, tz) \
+	sub_s(ds_x, ds_x, tx) \
+,	sub_s(ds_y, ds_y, ty) \
+,	sub_s(ds_z, ds_z, tz)
+WORD_COUNT(mac_sub_s_v3_self, 3)
+
+#define mac_sub_v3s4_self(ds, t) \
+	mac_sub_s_v3_self(ds.x, ds.y, ds.z, t.x, t.y, t.z)
+WORD_COUNT(mac_sub_v3s4_self, 3)
+
 /* atom_dbg_skip */
 #define mac_store_rects2(rt_x, rt_y, rt_width, rt_height, base, offset) \
 	store_half(rt_x,      base, offset + O_(Rect_S2,x)) \
@@ -99,6 +156,39 @@ WORD_COUNT(mac_sub_v3s4, 3)
 ,	store_half(rt_height, base, offset + O_(Rect_S2,height))
 WORD_COUNT(mac_store_rects2, 4)
 
+/* atom_dbg_skip */
+#define mac_load_word_imm(dst, imm) \
+	load_upper_i(dst, u4_hi(imm)) \
+,	or_i_self(   dst, u4_lo(imm))
+WORD_COUNT(mac_load_word_imm, 2)
+
+#define mac_shift_aright_v3_self(dt_x, dt_y, dt_z, shift_amount) \
+	shift_aright(dt_x, dt_x, shift_amount) \
+,	shift_aright(dt_y, dt_y, shift_amount) \
+,	shift_aright(dt_z, dt_z, shift_amount)
+WORD_COUNT(mac_shift_aright_v3_self, 3)
+
+#define mac_shift_aright_v3s4_self(dt, shift) \
+	mac_shift_aright_v3_self(dt.x, dt.y, dt.z, shift)
+WORD_COUNT(mac_shift_aright_v3s4_self, 3)
+
+#define mac_shift_aright_var_v3(rd_v0, rd_v1, rd_v2, rs_v0, rs_v1, rs_v2, r_shift) \
+	shift_aright_var(rd_v0, rs_v0, r_shift) \
+,	shift_aright_var(rd_v1, rs_v1, r_shift) \
+,	shift_aright_var(rd_v2, rs_v2, r_shift)
+WORD_COUNT(mac_shift_aright_var_v3, 3)
+
+/* atom_dbg_skip */
+#define mac_shift_aright_var_v3_self(rds_v0, rds_v1, rds_v2, r_shift) \
+	shift_aright_var(rds_v0, rds_v0, r_shift) \
+,	shift_aright_var(rds_v1, rds_v1, r_shift) \
+,	shift_aright_var(rds_v2, rds_v2, r_shift)
+WORD_COUNT(mac_shift_aright_var_v3_self, 3)
+
+#define mac_shift_aright_var_v3s4_self(ds, shift) \
+	mac_shift_aright_var_v3_self(ds.x, ds.y, ds.z, shift)
+WORD_COUNT(mac_shift_aright_var_v3s4_self, 3)
+
 /* atom_dbg_skip */
 #define mac_load_tri_indices(r_face_cusor, r_i0, r_i1, r_i2) \
 	load_half_u(r_i0, r_face_cusor, 0 * S_(S2)) \
@@ -106,6 +196,30 @@ WORD_COUNT(mac_store_rects2, 4)
 ,	load_half_u(r_i2, r_face_cusor, 2 * S_(S2))
 WORD_COUNT(mac_load_tri_indices, 3)
 
+#define mac_gte_mv_to_cr_diag_v3s4(v) \
+	gte_mv_to_ctrl_r(v.y, gte_cr_RT13) \
+,	gte_mv_to_ctrl_r(v.z, gte_cr_RT22) \
+,	gte_mv_to_ctrl_r(v.x, gte_cr_RT11)
+WORD_COUNT(mac_gte_mv_to_cr_diag_v3s4, 3)
+
+#define mac_gte_ld_ir123_v3s4(v) \
+	gte_mv_to_data_r(v.x, C2_IR1) \
+,	gte_mv_to_data_r(v.y, C2_IR2) \
+,	gte_mv_to_data_r(v.z, C2_IR3)
+WORD_COUNT(mac_gte_ld_ir123_v3s4, 3)
+
+/* atom_dbg_skip */
+#define mac_gte_op_cross_v3s4(a, b) \
+	mac_gte_mv_to_cr_diag_v3s4(a) \
+	GteDelay_  /* RT diagonal: D1 = a.x, D2 = a.y, D3 = a.z */ \
+,	mac_gte_ld_ir123_v3s4(b) \
+	GteDelay_  /* IR: second operand (b.xyz) */ \
+,	gte_cmdw_cross                            /* OP: MAC1/2/3 = a × b (S12.20) */ \
+,	mac_gte_mv_from_mac123_v3s4(a) \
+	GteDelay_  /* Read MAC1/2/3 → a.xyz (overwrites source-A's load targets) */ \
+,	mac_shift_aright_v3s4_self(a, 12) /* Right-shift MAC by 12 (S12.20 → S12.0 OuterProduct12) */
+WORD_COUNT(mac_gte_op_cross_v3s4, 13)
+
 /* atom_dbg_skip */
 #define mac_gte_store_f3(r_primitive_cursor) \
 	gte_sw(C2_SXY0, r_primitive_cursor, O_(Poly_F3,p0)) \
@@ -114,24 +228,24 @@ WORD_COUNT(mac_load_tri_indices, 3)
 WORD_COUNT(mac_gte_store_f3, 3)
 
 /* atom_dbg_skip */
-#define mac_gte_load_tri_verts(r_vert_base, r_v0, r_v1, r_v2) \
-	shift_lleft(R_AT, r_v0, v3s2_byteoff) \
-,	add_u_self(R_AT, r_vert_base) \
+#define mac_gte_load_tri_verts(vbase, v0, v1, v2) \
+	shift_lleft(R_AT, v0, v3s2_byteoff) \
+,	add_u_self(R_AT, vbase) \
 ,	load_word(R_V0, R_AT, O_(V3_S2,x)) \
 ,	load_word(R_V1, R_AT, O_(V3_S2,z)) \
-,	gte_mv_to_data_r(R_V0, C2_VXY0) \
+,	LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY0) \
 ,	gte_mv_to_data_r(R_V1, C2_VZ0) \
-,	shift_lleft(R_AT, r_v1, v3s2_byteoff) \
-,	add_u_self(R_AT, r_vert_base) \
+,	shift_lleft(R_AT, v1, v3s2_byteoff) \
+,	add_u_self(R_AT, vbase) \
 ,	load_word(R_V0, R_AT, O_(V3_S2,x)) \
 ,	load_word(R_V1, R_AT, O_(V3_S2,z)) \
-,	gte_mv_to_data_r(R_V0, C2_VXY1) \
+,	LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY1) \
 ,	gte_mv_to_data_r(R_V1, C2_VZ1) \
-,	shift_lleft(R_AT, r_v2, v3s2_byteoff) \
-,	add_u_self(R_AT, r_vert_base) \
+,	shift_lleft(R_AT, v2, v3s2_byteoff) \
+,	add_u_self(R_AT, vbase) \
 ,	load_word(R_V0, R_AT, O_(V3_S2,x)) \
 ,	load_word(R_V1, R_AT, O_(V3_S2,z)) \
-,	gte_mv_to_data_r(R_V0, C2_VXY2) \
+,	LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY2) \
 ,	gte_mv_to_data_r(R_V1, C2_VZ2)
 WORD_COUNT(mac_gte_load_tri_verts, 18)
 
@@ -149,23 +263,28 @@ WORD_COUNT(mac_gte_store_g4_p3, 1)
 
 /* atom_dbg_skip */
 #define mac_gte_sqr_v3(r_sx, r_sy, r_sz, r_sq_x, r_sq_y, r_sq_z) \
-	gte_mv_to_data_r(r_sx, C2_IR1) \
-,	gte_mv_to_data_r(r_sy, C2_IR2) \
-,	gte_mv_to_data_r(r_sz, C2_IR3) \
-,	nop \
-,	gte_cmdw_sqr \
+	mac_gte_sqr_v3s4(r_sx, r_sy, r_sz, nop) \
 ,	gte_mv_from_data_r(r_sq_x, C2_MAC1) \
 ,	gte_mv_from_data_r(r_sq_y, C2_MAC2) \
 ,	gte_mv_from_data_r(r_sq_z, C2_MAC3)
 WORD_COUNT(mac_gte_sqr_v3, 8)
 
+/* atom_dbg_skip */
+#define mac_gte_sqr_v3s4(r_sx, r_sy, r_sz, delay_slot) \
+	gte_mv_to_data_r(r_sx, C2_IR1) \
+,	gte_mv_to_data_r(r_sy, C2_IR2) \
+,	gte_mv_to_data_r(r_sz, C2_IR3) \
+,	delay_slot \
+,	gte_cmdw_sqr
+WORD_COUNT(mac_gte_sqr_v3s4, 5)
+
 /* atom_dbg_skip */
 #define mac_gte_gpf_scale(r_sx, r_sy, r_sz, r_recip_est, r_shift, r_dx, r_dy, r_dz) \
 	gte_mv_to_data_r(r_recip_est, C2_IR0) \
 ,	gte_mv_to_data_r(r_sx,        C2_IR1) \
 ,	gte_mv_to_data_r(r_sy,        C2_IR2) \
 ,	gte_mv_to_data_r(r_sz,        C2_IR3) \
-,	nop2 /* retire IR0..IR3 → GPF input pre-fill (matches libgte 0x80016134..0x80016138) */ \
+,	GteDelay_ nop2 /* retire IR0..IR3 → GPF input pre-fill (matches libgte 0x80016134..0x80016138) */ \
 ,	gte_cmdw_gpf \
 ,	gte_mv_from_data_r(r_dx, C2_MAC1) \
 ,	gte_mv_from_data_r(r_dy, C2_MAC2) \
@@ -175,58 +294,50 @@ WORD_COUNT(mac_gte_sqr_v3, 8)
 ,	shift_aright_var(r_dz, r_dz, r_shift)
 WORD_COUNT(mac_gte_gpf_scale, 13)
 
-#define mac_apply_matrix_lv(r_mtx, r_vec, r_out, r_t0, r_t1, r_t2) \
-	load_word(  r_t0, r_mtx,  0) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT11) \
-,	load_word(  r_t0, r_mtx,  4) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT12) \
-,	load_word(  r_t0, r_mtx,  8) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT13) \
-,	load_word(  r_t0, r_mtx, 12) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT21) \
-,	load_half_u(r_t0, r_mtx, 16) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT22) \
-,	nop2	/* Load PACKED pos into V0 (libgte SVECTOR layout).
-	 * r_vec points to atom-0-staged packed data ((pos.y << 16) | pos.x at +0, pos.z at +4).
-	 * LWC2 base register MUST be the pointer r_vec, NOT the loaded value r_t0. */ \
-,	load_word(r_t0, r_vec, 0) \
-,	nop \
-,	gte_lw(C2_VXY0, r_vec, 0) \
-,	load_word(r_t0, r_vec, 4) \
-,	nop \
-,	gte_lw(C2_VZ0, r_vec, 4)	/* RTPS: cv=3 (no translation), sf=1 (no shift, integer), v=0 (V0 input),
-	 * mx=0 (rotation matrix). MAC = RT row · V0 + 0. RTPS also writes
-	 * SXY0/1/2 + SZ0..SZ3 (perspective division); ignored. */ \
-,	gte_cmdw_rtps_sf1	/* Read MAC1/2/3 → out. */ \
-,	gte_mv_from_data_r(r_t0, C2_MAC1) \
-,	gte_mv_from_data_r(r_t1, C2_MAC2) \
-,	gte_mv_from_data_r(r_t2, C2_MAC3) \
-,	nop \
-,	store_word(r_t0, r_out, 0) \
-,	store_word(r_t1, r_out, 4) \
-,	store_word(r_t2, r_out, 8)
-WORD_COUNT(mac_apply_matrix_lv, 31)
-
-#define mac_trans_matrix(r_mtx, r_off, r_t1) \
-	load_word(r_t1, r_off, O_(V3_S4,x)) \
-,	nop \
-,	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[0])) \
+#define mac_trans_mt3s3s4(r_mtx, r_off, r_t0, r_t1, r_t2) \
+	load_word( r_t0, r_off, O_(V3_S4,x)) \
 ,	load_word( r_t1, r_off, O_(V3_S4,y)) \
-,	nop \
+,	load_word( r_t2, r_off, O_(V3_S4,z)) \
+,	store_word(r_t0, r_mtx, O_(MT3_S2S4,t[0])) \
 ,	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[1])) \
-,	load_word(r_t1, r_off, O_(V3_S4,z)) \
-,	nop \
-,	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[2]))
-WORD_COUNT(mac_trans_matrix, 9)
+,	store_word(r_t2, r_mtx, O_(MT3_S2S4,t[2]))
+WORD_COUNT(mac_trans_mt3s3s4, 6)
 
+/* atom_dbg_skip */
+#define mac_lzcr_round_even_half_shift(r_shift, r_mag_sq, r_mag_sq_copy) \
+	and_i(r_shift, r_shift, gte_lzcr_even_mask) \
+,	or_u(r_mag_sq_copy, r_mag_sq, 0) \
+,	li_s(        r_mag_sq, 31) \
+,	sub_s(       r_mag_sq, r_mag_sq, r_shift) \
+,	shift_aright(r_mag_sq, r_mag_sq, 1)
+WORD_COUNT(mac_lzcr_round_even_half_shift, 5)
+
+#define mac_gte_general_purpose_interopolation(to_ir0, to_ir1, to_ir2, to_ir3, fr_mac1, fr_mac2, fr_mac3, nop_slot1, nop_slot2) \
+	gte_mv_to_data_r(to_ir0, C2_IR0) \
+,	gte_mv_to_data_r(to_ir1, C2_IR1) /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */ \
+,	gte_mv_to_data_r(to_ir2, C2_IR2) \
+,	gte_mv_to_data_r(to_ir3, C2_IR3) /* IR3 = src.z (reloaded) */ \
+,	GteDelay_ nop_slot1 \
+,	GteDelay_ nop_slot2 \
+,	gte_cmdw_gpf \
+,	gte_mv_from_data_r(fr_mac1, C2_MAC1) \
+,	gte_mv_from_data_r(fr_mac2, C2_MAC2) \
+,	gte_mv_from_data_r(fr_mac3, C2_MAC3)
+WORD_COUNT(mac_gte_general_purpose_interopolation, 10)
+
+#define mac_gte_mv_from_data_r_mac123(fr_mac1, fr_mac2, fr_mac3) \
+	gte_mv_from_data_r(fr_mac1, C2_MAC1) \
+,	gte_mv_from_data_r(fr_mac2, C2_MAC2) \
+,	gte_mv_from_data_r(fr_mac3, C2_MAC3)
+WORD_COUNT(mac_gte_mv_from_data_r_mac123, 3)
+
+#define mac_gte_mv_from_mac123_v3s4(v) \
+	mac_gte_mv_from_data_r_mac123(v.x, v.y, v.z)
+WORD_COUNT(mac_gte_mv_from_mac123_v3s4, 3)
+
+/* atom_dbg_skip */
 #define mac_gcmd_push(cmd, reg_transfer, reg_base, port) \
-	load_upper_i(reg_transfer, u4_hi(cmd)) \
-,	or_i_self(   reg_transfer, u4_lo(cmd))	/* load_upper_i(reg_transfer, cmd >> 16),	// or_i_self(   reg_transfer, cmd & 0xFFFF), */ \
+	mac_load_word_imm(reg_transfer, cmd) \
 ,	store_word(       reg_transfer, reg_base, port)
 WORD_COUNT(mac_gcmd_push, 3)
 
@@ -249,6 +360,7 @@ WORD_COUNT(mac_pack_color_word, 3)
 	mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b)
 WORD_COUNT(mac_format_f3_color, 3)
 
+/* atom_dbg_skip */
 #define mac_format_g4_color(r_prim_cursor, r0, g0, b0, r1, g1, b1, r2, g2, b2, r3, g3, b3) \
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c0), gp0_cmd_poly_g4, r0,g0,b0) \
 ,	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c1), 0,               r1,g1,b1) \
@@ -270,16 +382,16 @@ WORD_COUNT(mac_format_g4_color, 12)
 WORD_COUNT(mac_insert_ot_tag, 11)
 
 /* atom_dbg_skip */
-#define mac_pad_set_centered_axes(r_state, r_scratch) \
-	load_upper_i(r_scratch, (PadAxis_Centered_Word >> 16) & 0xFFFF) \
-,	or_i_self(   r_scratch,  PadAxis_Centered_Word        & 0xFFFF) \
-,	store_word(  r_scratch, r_state, O_(PadState,axes))
+#define mac_pad_set_centered_axes(state, scratch) \
+	load_upper_i(scratch, (PadAxis_Centered >> 16) & 0xFFFF) \
+,	or_i_self(   scratch,  PadAxis_Centered        & 0xFFFF) /* mac_load_word_imm(scratch, PadAxis_Centered), */ \
+,	store_word(  scratch, state, O_(PadState,axes))
 WORD_COUNT(mac_pad_set_centered_axes, 3)
 
 /* atom_dbg_skip */
-#define mac_pad_set_id_byte(r_state, r_id, id_value) \
+#define mac_pad_set_id_byte(state, r_id, id_value) \
 	add_ui(    r_id, R_0, id_value) \
-,	store_byte(r_id, r_state, O_(PadState,id))
+,	store_byte(r_id, state, O_(PadState,id))
 WORD_COUNT(mac_pad_set_id_byte, 2)
 
 /* atom_dbg_skip */

code/duffle/gen/offsets.h

@@ -14,7 +14,7 @@
 //   source: C:\projects\Pikuma\ps1\code\duffle\bios.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.c
-//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.c
+//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gte.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gp.atom.c
@@ -25,7 +25,15 @@
 #pragma region duffle
 
 
-// --- atom: normalize_v3s4 (66 words) ---
+// --- atom: example_atom_proc (10 words) ---
+
+#define _atom_offset_example_atom_proc_skip           2
+
+enum {
+    atom_offset_example_atom_proc_skip = _atom_offset_example_atom_proc_skip,
+};
+
+// --- atom: normalize_v3s4 (62 words) ---
 
 #define _atom_offset_aligned_done_srav_path           3
 #define _atom_offset_srav_path_aligned_done           4

code/duffle/gp.atom.c

@@ -9,36 +9,34 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(gp_atom_c);
 #pragma region MACs (Mips Atom Components)
 
 FI_ Slice_MipsCode ac_gcmd_push(AtomBuilder_R ab, U4 cmd, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_gcmd_push, ab, {
-	load_upper_i(reg_transfer, u4_hi(cmd)),
-	or_i_self(   reg_transfer, u4_lo(cmd)),
-	// load_upper_i(reg_transfer, cmd >> 16),
-	// or_i_self(   reg_transfer, cmd & 0xFFFF),
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	mac_load_word_imm(reg_transfer, cmd),
 	store_word(       reg_transfer, reg_base, port),
 })
 
-FI_ Slice_MipsCode ac_store_rgb8(AtomBuilder_R ab, U1 rr, U1 rg, U1 rb, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_rgb8, ab, {
+FI_ Slice_MipsCode ac_store_rgb8(AtomBuilder_R ab, U1 rr, U1 rg, U1 rb, U4 base, U4 offset) 
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	store_byte(rr, base, offset + O_(RGB8,r)),
 	store_byte(rg, base, offset + O_(RGB8,g)),
 	store_byte(rb, base, offset + O_(RGB8,b)),
 })
 
 FI_ Slice_MipsCode ac_pack_color_word(AtomBuilder_R ab, U4 r_base, U4 off, U4 cmd, U1 r, U1 g, U1 b)
-atom_dbg_skip MipsAtomComp_Proc_(ac_pack_color_word, ab, {
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	load_upper_i(R_AT, (cmd) << 8  | (b)),
 	or_i_self(   R_AT, ((g)  << 8) | (r)),
 	store_word(  R_AT, r_base, (off)),
 })
 
 FI_ Slice_MipsCode ac_format_f3_color(AtomBuilder_R ab, U4 r_base, U1 r, U1 g, U1 b)
-atom_dbg_skip MipsAtomComp_Proc_(ac_format_f3_color, ab, { mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b) })
+atom_dbg_skip MipsAtomComp_Proc_(ab, { mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b) })
 
 FI_ Slice_MipsCode ac_format_g4_color(AtomBuilder_R ab, U4 r_prim_cursor,
 	U1 r0, U1 g0, U1 b0,
   U1 r1, U1 g1, U1 b1,
   U1 r2, U1 g2, U1 b2,
   U1 r3, U1 g3, U1 b3)
-MipsAtomComp_Proc_(ac_format_g4_color, ab, {
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c0), gp0_cmd_poly_g4, r0,g0,b0),
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c1), 0,               r1,g1,b1),
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c2), 0,               r2,g2,b2),
@@ -46,7 +44,8 @@ MipsAtomComp_Proc_(ac_format_g4_color, ab, {
 })
 
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list. */
-I_ Slice_MipsCode ac_insert_ot_tag(AtomBuilder_R ab, U4 r_ot_base, U4 r_prim_cursor, U4 poly_size) MipsAtomComp_Proc_(ac_insert_ot_tag, ab, {
+// TODO(Ed): Expose R_T1 as a r_t0, r_V0 as r_t2
+I_ Slice_MipsCode ac_insert_ot_tag(AtomBuilder_R ab, Reg r_ot_base, Reg r_prim_cursor, U2 poly_size) MipsAtomComp_Proc_(ab, {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, r_ot_base),                             // T1 = & OrderingTable[OTZ]
 	load_word(   R_AT, R_T1,          O_(PolyTag,code)),       // AT = old_ot_head

code/duffle/gp.h

@@ -21,7 +21,7 @@
  *    4. Semantic encoders      gp0_word_poly_f3(r,g,b)
  *    3. Composite encoders     enc_color_word(cmd, r, g, b)
  *    2. Per-field encoders     enc_gp0_color_r(r), enc_gp0_color_g(g), ...
- *    1. Bitfield layout consts gp0_color_red_shift = 0, gp0_color_red_mask = 0xFF
+ *    1. Bitfield layout consts gp0_color_red_pos = 0, gp0_color_red_width = 8
  *    0. Opcode IDs             gp0_cmd_poly_f3 = 0x20
  *
  *  Vendor mnemonics (gte_mtc2, gte_mfc2, etc.) are NOT in this header.
@@ -68,13 +68,14 @@ enum {
 
 #define gp0_send(word) (HW_GP0[0] = (word))
 #define gp1_send(word) (HW_GP1[0] = (word))
+#define DmaSlot_ // Annotate an instruction as filling a CPU <-> Command DMA delay slot/s
 
 /* ============================================================================
  *  GP0 command byte constants + Layer 1 (GPU bitfield shifts)
  *  ============================================================================
  *  8-bit GP0 opcodes (the upper byte of a primitive's first word). These are the BYTE only.
  *  NO macro body past this point uses a raw shift or raw mask.
- *  Mirrors the OPCODE_SHIFT / RS_SHIFT / REG_MASK convention from mips.h.
+ *  Mirrors the OPCODE_POS / RS_POS convention from mips.h.
  * ============================================================================ */
 enum {
 	gp0_cmd_Nop             = 0x00,
@@ -116,21 +117,20 @@ enum {
 	gp0_cmd_SetDrawOffset        = 0xE5,
 	gp0_cmd_SetMaskBit           = 0xE6,
 
-	/* bitfield shifts / widths / masks ----
+	/* bitfield offset pos / widths ----
 		* Generic GP0/GP1 command byte (upper 8 bits of every word sent to either port). */
-	gp0_cmd_shift = 24,
+	gp0_cmd_pos   = 24,
 	gp0_cmd_width =  8,
-	gp0_cmd_mask  = 0xFF,
 
 	/* Color word layout (lives in Poly_F3.color, Poly_G4.c0..c3, etc.):
 		*   bits 31..24 = command byte
 		*   bits 23..16 = BLUE
 		*   bits 15..08 = GREEN
 		*   bits 07..00 = RED     (PSX GPU is BGR, NOT RGB) */
-	gp0_color_cmd_shift   = 24, gp0_color_cmd_width   = 8, gp0_color_cmd_mask   = 0xFF,
-	gp0_color_blue_shift  = 16, gp0_color_blue_width  = 8, gp0_color_blue_mask  = 0xFF,
-	gp0_color_green_shift =  8, gp0_color_green_width = 8, gp0_color_green_mask = 0xFF,
-	gp0_color_red_shift   =  0, gp0_color_red_width   = 8, gp0_color_red_mask   = 0xFF,
+	gp0_color_cmd_pos   = 24, gp0_color_cmd_width   = 8,
+	gp0_color_blue_pos  = 16, gp0_color_blue_width  = 8,
+	gp0_color_green_pos =  8, gp0_color_green_width = 8,
+	gp0_color_red_pos   =  0, gp0_color_red_width   = 8,
 };
 
 /* ============================================================================
@@ -143,12 +143,12 @@ enum {
  * ============================================================================ */
 
 /* ---- Layer 1.5: per-field encoders ---- */
-#define enc_gp0_cmd(cmd)       (((cmd) & gp0_cmd_mask)         << gp0_cmd_shift)
+#define enc_gp0_cmd(cmd)       ((cmd) << gp0_cmd_pos)
 
-#define enc_gp0_color_cmd(cmd) (((cmd) & gp0_color_cmd_mask)   << gp0_color_cmd_shift)
-#define enc_gp0_color_r(r)     (((r)   & gp0_color_red_mask)   << gp0_color_red_shift)
-#define enc_gp0_color_g(g)     (((g)   & gp0_color_green_mask) << gp0_color_green_shift)
-#define enc_gp0_color_b(b)     (((b)   & gp0_color_blue_mask)  << gp0_color_blue_shift)
+#define enc_gp0_color_cmd(cmd) ((cmd) << gp0_color_cmd_pos)
+#define enc_gp0_color_r(r)     ((r)   << gp0_color_red_pos)
+#define enc_gp0_color_g(g)     ((g)   << gp0_color_green_pos)
+#define enc_gp0_color_b(b)     ((b)   << gp0_color_blue_pos)
 
 /* ---- Layer 2: composite encoders ---- */
 #define enc_color_word(cmd, r, g, b) (enc_gp0_color_cmd(cmd) | enc_gp0_color_r(r) | enc_gp0_color_g(g) | enc_gp0_color_b(b))
@@ -211,38 +211,38 @@ enum {
 	gp1_disp_Color24    = 0x1,
 	gp1_disp_VInterlace = 0x1,
 
-	/* ---- Layer 1: GP1 display-mode + range + draw-area shifts/masks ---- */
-	gp1_disp_hres_shift      =  0, gp1_disp_hres_width      = 2, gp1_disp_hres_mask      = 0x3,
-	gp1_disp_vres_shift      =  2, gp1_disp_vres_width      = 1, gp1_disp_vres_mask      = 0x1,
-	gp1_disp_color_shift     =  4, gp1_disp_color_width     = 1, gp1_disp_color_mask     = 0x1,
-	gp1_disp_interlace_shift =  5, gp1_disp_interlace_width = 1, gp1_disp_interlace_mask = 0x1,
+	/* ---- Layer 1: GP1 display-mode + range + draw-area shifts/widths ---- */
+	gp1_disp_hres_pos      =  0, gp1_disp_hres_width      = 2,
+	gp1_disp_vres_pos      =  2, gp1_disp_vres_width      = 1,
+	gp1_disp_color_pos     =  4, gp1_disp_color_width     = 1,
+	gp1_disp_interlace_pos =  5, gp1_disp_interlace_width = 1,
 
 	/* GP1 horizontal display range: bits 0..11 = X2, bits 12..23 = X1 */
-	gp1_hrange_x1_shift = 12, gp1_hrange_x1_width = 12, gp1_hrange_x1_mask = 0xFFF,
-	gp1_hrange_x2_shift =  0, gp1_hrange_x2_width = 12, gp1_hrange_x2_mask = 0xFFF,
+	gp1_hrange_x1_pos = 12, gp1_hrange_x1_width = 12,
+	gp1_hrange_x2_pos =  0, gp1_hrange_x2_width = 12,
 
 	/* GP1 vertical display range: bits 0..9 = Y2, bits 10..19 = Y1 */
-	gp1_vrange_y1_shift = 10, gp1_vrange_y1_width = 10, gp1_vrange_y1_mask = 0x3FF,
-	gp1_vrange_y2_shift =  0, gp1_vrange_y2_width = 10, gp1_vrange_y2_mask = 0x3FF,
+	gp1_vrange_y1_pos = 10, gp1_vrange_y1_width = 10,
+	gp1_vrange_y2_pos =  0, gp1_vrange_y2_width = 10,
 
 	/* GP1 draw area (top-left or bottom-right): bits 0..9 = X, bits 10..19 = Y
-		* (10-bit signed — caller pre-signs and masks with the named mask) */
-	gp1_draw_x_shift =  0, gp1_draw_x_width = 10, gp1_draw_x_mask = 0x3FF,
-	gp1_draw_y_shift = 10, gp1_draw_y_width = 10, gp1_draw_y_mask = 0x3FF,
+		* (10-bit signed — caller pre-signs) */
+	gp1_draw_x_pos =  0, gp1_draw_x_width = 10,
+	gp1_draw_y_pos = 10, gp1_draw_y_width = 10,
 };
 
 /* ---- Layer 1.5: GP1 per-field encoders ---- */
-#define enc_gp1_disp_hres(h)      (((h) & gp1_disp_hres_mask)      << gp1_disp_hres_shift)
-#define enc_gp1_disp_vres(v)      (((v) & gp1_disp_vres_mask)      << gp1_disp_vres_shift)
-#define enc_gp1_disp_color(c)     (((c) & gp1_disp_color_mask)     << gp1_disp_color_shift)
-#define enc_gp1_disp_interlace(i) (((i) & gp1_disp_interlace_mask) << gp1_disp_interlace_shift)
+#define enc_gp1_disp_hres(h)      ((h) << gp1_disp_hres_pos)
+#define enc_gp1_disp_vres(v)      ((v) << gp1_disp_vres_pos)
+#define enc_gp1_disp_color(c)     ((c) << gp1_disp_color_pos)
+#define enc_gp1_disp_interlace(i) ((i) << gp1_disp_interlace_pos)
 
-#define enc_gp1_hrange_x1(x1) (((x1) & gp1_hrange_x1_mask) << gp1_hrange_x1_shift)
-#define enc_gp1_hrange_x2(x2) (((x2) & gp1_hrange_x2_mask) << gp1_hrange_x2_shift)
-#define enc_gp1_vrange_y1(y1) (((y1) & gp1_vrange_y1_mask) << gp1_vrange_y1_shift)
-#define enc_gp1_vrange_y2(y2) (((y2) & gp1_vrange_y2_mask) << gp1_vrange_y2_shift)
-#define enc_gp1_draw_x(x)     (((x)  & gp1_draw_x_mask)    << gp1_draw_x_shift)
-#define enc_gp1_draw_y(y)     (((y)  & gp1_draw_y_mask)    << gp1_draw_y_shift)
+#define enc_gp1_hrange_x1(x1) ((x1) << gp1_hrange_x1_pos)
+#define enc_gp1_hrange_x2(x2) ((x2) << gp1_hrange_x2_pos)
+#define enc_gp1_vrange_y1(y1) ((y1) << gp1_vrange_y1_pos)
+#define enc_gp1_vrange_y2(y2) ((y2) << gp1_vrange_y2_pos)
+#define enc_gp1_draw_x(x)     ((x)  << gp1_draw_x_pos)
+#define enc_gp1_draw_y(y)     ((y)  << gp1_draw_y_pos)
 
 /* ---- Layer 2: GP1 composite encoders ---- */
 #define enc_gp1_disp_mode_word(h, v, c, i) (enc_gp0_cmd(gp1_cmd_DisplayMode)            | enc_gp1_disp_hres(h)  | enc_gp1_disp_vres(v) | enc_gp1_disp_color(c) | enc_gp1_disp_interlace(i))
@@ -419,14 +419,11 @@ typedef Struct_(PolyTag) {
 	};
 };
 
-/* DSL cast convention: every cast uses `C_()`, every pointer qualifier is `R_` (restrict) or `V_` (volatile).
- * No raw C-style casts. RHS values are assumed to be `U4` — caller passes a `U4` directly. */
 #define set_len(tag,v)  (C_(PolyTag_R,tag)->len  = u4_(v))
 #define set_addr(tag,v) (C_(PolyTag_R,tag)->addr = u4_(v))
-/* `set_code` is no longer in the new PolyTag design — the code byte lives in the primitive body
+/* `set_code` is no longer in the new PolyTag design
  * (e.g. `((Poly_F3*)(p))->code`), not in the tag.
- *  Use the typed primitive structs (Poly_F3, Poly_G4, etc.) and the `set_poly_*` setters,
- *  which set both the tag's length and the code. */
+ *  Use the typed primitive structs (Poly_F3, Poly_G4, etc.) and the `set_poly_*` setters, which set both the tag's length and the code. */
 #define get_len(tag)  C_(U4,C_(PolyTag_R,tag)->len)
 #define get_addr(tag) C_(U4,C_(PolyTag_R,tag)->addr)
 
@@ -555,17 +552,17 @@ typedef Struct_(Poly_GT4) {
  *    bits 12..31  = reserved (zero)
  * ============================================================================ */
 enum {
-	/* ---- Layer 1: TPage bitfield shifts / widths / masks ---- */
-	gp0_tpage_x_shift            =  0, gp0_tpage_x_width            =  4, gp0_tpage_x_mask            = 0xF,
-	gp0_tpage_y_shift            =  4, gp0_tpage_y_width            =  1, gp0_tpage_y_mask            = 0x1,
-	gp0_tpage_semi_trans_shift   =  5, gp0_tpage_semi_trans_width   =  2, gp0_tpage_semi_trans_mask   = 0x3,
-	gp0_tpage_color_depth_shift  =  7, gp0_tpage_color_depth_width  =  2, gp0_tpage_color_depth_mask  = 0x3,
-	gp0_tpage_dither_shift       =  9, gp0_tpage_dither_width       =  1, gp0_tpage_dither_mask       = 0x1,
-	gp0_tpage_draw_to_disp_shift = 10, gp0_tpage_draw_to_disp_width =  1, gp0_tpage_draw_to_disp_mask = 0x1,
-	gp0_tpage_tex_disable_shift  = 11, gp0_tpage_tex_disable_width  =  1, gp0_tpage_tex_disable_mask  = 0x1,
+	/* ---- Layer 1: TPage bitfield shifts / widths ---- */
+	gp0_tpage_x_pos            =  0, gp0_tpage_x_width            =  4,
+	gp0_tpage_y_pos            =  4, gp0_tpage_y_width            =  1,
+	gp0_tpage_semi_trans_pos   =  5, gp0_tpage_semi_trans_width   =  2,
+	gp0_tpage_color_depth_pos  =  7, gp0_tpage_color_depth_width  =  2,
+	gp0_tpage_dither_pos       =  9, gp0_tpage_dither_width       =  1,
+	gp0_tpage_draw_to_disp_pos = 10, gp0_tpage_draw_to_disp_width =  1,
+	gp0_tpage_tex_disable_pos  = 11, gp0_tpage_tex_disable_width  =  1,
 
 	/* TPage color-depth payload values (NOT bit positions — these go in
-	 * the 2-bit field at gp0_tpage_color_depth_shift). */
+	 * the 2-bit field at gp0_tpage_color_depth_pos). */
 	gp0_tpage_color_4bpp  = 0x0,
 	gp0_tpage_color_8bpp  = 0x1,
 	gp0_tpage_color_16bpp = 0x2,
@@ -573,7 +570,7 @@ enum {
 	/* Default TPage value libpsyx's SetDefDrawEnv writes (matches the `li v1, 10; sh v1, 20(v0)` sequence at C11_only.elf:0x8001273C). */
 	gp0_tpage_default    = 10,
 
-	/* TPage semi-transparency mode payload values (NOT bit positions). */
+	/* TPage semi-transparency mode payload values. */
 	gp0_tpage_semi_trans_none  = 0x0,
 	gp0_tpage_semi_trans_alpha = 0x1,
 	gp0_tpage_semi_trans_add   = 0x2,
@@ -581,13 +578,13 @@ enum {
 };
 
 /* ---- Layer 1.5: TPage per-field encoders. Mirrors enc_gte_sf/mx/v in gte.h. ---- */
-#define enc_gp0_tpage_x(x)            (((x) & gp0_tpage_x_mask)            << gp0_tpage_x_shift)
-#define enc_gp0_tpage_y(y)            (((y) & gp0_tpage_y_mask)            << gp0_tpage_y_shift)
-#define enc_gp0_tpage_semi_trans(s)   (((s) & gp0_tpage_semi_trans_mask)   << gp0_tpage_semi_trans_shift)
-#define enc_gp0_tpage_color_depth(c)  (((c) & gp0_tpage_color_depth_mask)  << gp0_tpage_color_depth_shift)
-#define enc_gp0_tpage_dither(d)       (((d) & gp0_tpage_dither_mask)       << gp0_tpage_dither_shift)
-#define enc_gp0_tpage_draw_to_disp(d) (((d) & gp0_tpage_draw_to_disp_mask) << gp0_tpage_draw_to_disp_shift)
-#define enc_gp0_tpage_tex_disable(t)  (((t) & gp0_tpage_tex_disable_mask)  << gp0_tpage_tex_disable_shift)
+#define enc_gp0_tpage_x(x)            ((x) << gp0_tpage_x_pos)
+#define enc_gp0_tpage_y(y)            ((y) << gp0_tpage_y_pos)
+#define enc_gp0_tpage_semi_trans(s)   ((s) << gp0_tpage_semi_trans_pos)
+#define enc_gp0_tpage_color_depth(c)  ((c) << gp0_tpage_color_depth_pos)
+#define enc_gp0_tpage_dither(d)       ((d) << gp0_tpage_dither_pos)
+#define enc_gp0_tpage_draw_to_disp(d) ((d) << gp0_tpage_draw_to_disp_pos)
+#define enc_gp0_tpage_tex_disable(t)  ((t) << gp0_tpage_tex_disable_pos)
 
 /* ---- Layer 2: TPage composite encoder. Mirrors enc_gte_cmdw in gte.h ---- */
 #define enc_gp0_tpage_word(x, y, semi_trans, color_depth, dither, draw_to_disp, tex_disable) \
@@ -617,17 +614,17 @@ typedef Struct_(TexturePage) { U4 raw; };
  *    bits 24..31  = command byte — 0x20 (4bpp load) or 0x25 (8bpp load)
  * ============================================================================ */
 enum {
-	/* ---- Layer 1: CLUT bitfield shifts / widths / masks ---- */
-	gp0_clut_y_shift = 0, gp0_clut_y_width = 6, gp0_clut_y_mask = 0x3F,
-	gp0_clut_x_shift = 6, gp0_clut_x_width = 9, gp0_clut_x_mask = 0x1FF,
+	/* ---- Layer 1: CLUT bitfield shifts / widths ---- */
+	gp0_clut_y_pos = 0, gp0_clut_y_width = 6,
+	gp0_clut_x_pos = 6, gp0_clut_x_width = 9,
 	/* CLUT-load cmd-byte variants — the upper byte of the GP0 word. */
 	gp0_clut_cmd_Load4bpp = 0x20,
 	gp0_clut_cmd_Load8bpp = 0x25,
 };
 
 /* ---- Layer 1.5: CLUT per-field encoders ---- */
-#define enc_gp0_clut_x(x) (((x) & gp0_clut_x_mask) << gp0_clut_x_shift)
-#define enc_gp0_clut_y(y) (((y) & gp0_clut_y_mask) << gp0_clut_y_shift)
+#define enc_gp0_clut_x(x) ((x) << gp0_clut_x_pos)
+#define enc_gp0_clut_y(y) ((y) << gp0_clut_y_pos)
 
 /* ---- Layer 2: CLUT composite encoder ---- */
 #define enc_gp0_clut_word(cmd, x, y) (enc_gp0_cmd(cmd) | enc_gp0_clut_x(x) | enc_gp0_clut_y(y))

code/duffle/gte.atom.c

@@ -11,25 +11,62 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(gte_atom_c);
 #pragma region MACs (Mips Atom Components)
 
 /* Words: 3; Loads 3 S2 indices from the face array */
-FI_ Slice_MipsCode ac_load_tri_indices(AtomBuilder_R ab, U4 r_face_cusor, U4 r_i0, U4 r_i1, U4 r_i2) atom_dbg_skip MipsAtomComp_Proc_(ac_load_tri_indices, ab, {
+FI_ Slice_MipsCode ac_load_tri_indices(AtomBuilder_R ab, U4 r_face_cusor, U4 r_i0, U4 r_i1, U4 r_i2)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	load_half_u(r_i0, r_face_cusor, 0 * S_(S2)),
 	load_half_u(r_i1, r_face_cusor, 1 * S_(S2)),
 	load_half_u(r_i2, r_face_cusor, 2 * S_(S2)),
 })
 
+FI_ Slice_MipsCode ac_gte_mv_to_cr_diag_v3s4(AtomBuilder_R ab, Reg_(V3_S4) v) MipsAtomComp_Proc_(ab, {
+	gte_mv_to_ctrl_r(v.y, gte_cr_RT13),
+	gte_mv_to_ctrl_r(v.z, gte_cr_RT22),
+	gte_mv_to_ctrl_r(v.x, gte_cr_RT11),
+})
+
+FI_ Slice_MipsCode ac_gte_ld_ir123_v3s4(AtomBuilder_R ab, Reg_(V3_S4) v) MipsAtomComp_Proc_(ab, {
+	gte_mv_to_data_r(v.x, C2_IR1),
+	gte_mv_to_data_r(v.y, C2_IR2),
+	gte_mv_to_data_r(v.z, C2_IR3),
+})
+
+/* ─── GTE OP cross product (a × b → a) ───
+ * Sets up RT diagonal from a.xyz, IR1/2/3 from b.xyz, fires OP,
+ * reads MAC1/2/3, shifts right 12 (S12.20 → S12.0 OuterProduct12), writes back to a.xyz.
+ * Composes the three sub-primitives (RT-load, IR-load, OP, MAC-read, shift)
+ * into one component for use by atoms that need the cross product inline.
+ *
+ * Output gpr (a) aliases source-A gpr; MAC read clobbers source-A's load targets,
+ * but by that point the RT load is complete and source A is dead.
+ * Pipeline: clobbers IR1..3, MAC1..3, RT11..33.
+ *
+ * The CPU→COP2 transfer chains (3 ctc2, 3 mtc2) require a 2-slot retirement gap,
+ * and the MFC2→GPR chain (3 mfc2) requires a 1-slot retirement gap, before the GPR can be read.
+ * The hazard nops are inlined below — same convention as ac_gte_gpf_scale — so any atom body inlining this component inherits them.
+ *
+ * Words: 18 (3 ctc2 + 2 nop + 3 mtc2 + 2 nop + 1 op + 3 mfc2 + 1 nop + 3 sra).
+ */
+FI_ Slice_MipsCode ac_gte_op_cross_v3s4(AtomBuilder_R ab, Reg_(V3_S4) a, Reg_(V3_S4) b) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	mac_gte_mv_to_cr_diag_v3s4(a),  GteDelay_  /* RT diagonal: D1 = a.x, D2 = a.y, D3 = a.z */
+	mac_gte_ld_ir123_v3s4(b),       GteDelay_  /* IR: second operand (b.xyz) */
+	gte_cmdw_cross,                            /* OP: MAC1/2/3 = a × b (S12.20) */
+	mac_gte_mv_from_mac123_v3s4(a), GteDelay_  /* Read MAC1/2/3 → a.xyz (overwrites source-A's load targets) */
+	mac_shift_aright_v3s4_self(a, 12), /* Right-shift MAC by 12 (S12.20 → S12.0 OuterProduct12) */
+})
+
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices to the F3.
  * PIPELINE: post-RTPT (SXY0=v0.screen, SXY1=v1.screen, SXY2=v2.screen). */
-FI_ Slice_MipsCode ac_gte_store_f3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_f3, ab, {
+FI_ Slice_MipsCode ac_gte_store_f3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	gte_sw(C2_SXY0, r_primitive_cursor, O_(Poly_F3,p0)),
 	gte_sw(C2_SXY1, r_primitive_cursor, O_(Poly_F3,p1)),
 	gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_F3,p2)),
 })
 
 /* Words: 18; Translates indices to vertex addresses and pushes them to GTE  */
-I_ Slice_MipsCode ac_gte_load_tri_verts(AtomBuilder_R ab, U4 r_vert_base, U4 r_v0, U4 r_v1, U4 r_v2) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_load_tri_verts, ab, {
-	shift_lleft(R_AT, r_v0, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
-	shift_lleft(R_AT, r_v1, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
-	shift_lleft(R_AT, r_v2, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY2), gte_mv_to_data_r(R_V1, C2_VZ2),
+I_ Slice_MipsCode ac_gte_load_tri_verts(AtomBuilder_R ab, Reg vbase, Reg v0, Reg v1, Reg v2) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	shift_lleft(R_AT, v0, v3s2_byteoff), add_u_self(R_AT, vbase), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
+	shift_lleft(R_AT, v1, v3s2_byteoff), add_u_self(R_AT, vbase), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
+	shift_lleft(R_AT, v2, v3s2_byteoff), add_u_self(R_AT, vbase), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY2), gte_mv_to_data_r(R_V1, C2_VZ2),
 })
 
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices of the
@@ -37,7 +74,7 @@ I_ Slice_MipsCode ac_gte_load_tri_verts(AtomBuilder_R ab, U4 r_vert_base, U4 r_v
  * PIPELINE: post-RTPT, pre-RTPS (SXY0=v0.screen, SXY1=v1.screen, SXY2=v2.screen).
  * MUST be called BEFORE V3-RTPS, otherwise SXY0/1/2 get overwritten with v3
  * (RTPS writes only to SXY2, but to keep the three registers aligned with v0/v1/v2 you must store before RTPS). */
-FI_ Slice_MipsCode ac_gte_store_g4_p012(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_g4_p012, ab, {
+FI_ Slice_MipsCode ac_gte_store_g4_p012(AtomBuilder_R ab, Reg r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	gte_sw(C2_SXY0, r_primitive_cursor, O_(Poly_G4,p0)),
 	gte_sw(C2_SXY1, r_primitive_cursor, O_(Poly_G4,p1)),
 	gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p2)),
@@ -47,33 +84,41 @@ FI_ Slice_MipsCode ac_gte_store_g4_p012(AtomBuilder_R ab, U4 r_primitive_cursor)
  * PIPELINE: post-RTPS (SXY2 holds v3.screen because RTPS writes its single-vertex result to SXY2;
  * SXY0 still holds v0.screen from the earlier RTPT.
  */
-FI_ Slice_MipsCode ac_gte_store_g4_p3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_g4_p3, ab, { gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p3)) })
+FI_ Slice_MipsCode ac_gte_store_g4_p3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ab, { gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p3)) })
 
 /* ─── STAGE 1 of normalize: SQR + mfc2 MAC1/2/3 ───
- * Emits squared magnitude per component (in MAC1/2/3) into caller-provided scratch regs.
- * Stage 2 of normalize consumes these directly.
- * Words: 8.  Clobbers: IR1/2/3, MAC1/2/3.  Uses gte_cmdw_sqr (sf=0, lm=1). */
-FI_ Slice_MipsCode ac_gte_sqr_v3(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz, U4 r_sq_x, U4 r_sq_y, U4 r_sq_z) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_sqr_v3, ab, {
-	gte_mv_to_data_r(r_sx, C2_IR1),
-	gte_mv_to_data_r(r_sy, C2_IR2),
-	gte_mv_to_data_r(r_sz, C2_IR3),
-	nop, gte_cmdw_sqr,
+ * Emits squared magnitude per component (in MAC1/2/3) into caller-provided scratch regs. */
+FI_ Slice_MipsCode ac_gte_sqr_v3(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz, U4 r_sq_x, U4 r_sq_y, U4 r_sq_z) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	mac_gte_sqr_v3s4(r_sx, r_sy, r_sz, nop),
 	gte_mv_from_data_r(r_sq_x, C2_MAC1),
 	gte_mv_from_data_r(r_sq_y, C2_MAC2),
 	gte_mv_from_data_r(r_sq_z, C2_MAC3),
 })
 
+/* ─── SQR FIRE — mtc2 3 GPRs into IR1/IR2/IR3, then fire SQR. ─── */
+FI_ Slice_MipsCode ac_gte_sqr_v3s4(AtomBuilder_R ab, Reg r_sx, Reg r_sy, Reg r_sz, MipsCode delay_slot)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	gte_mv_to_data_r(r_sx, C2_IR1),
+	gte_mv_to_data_r(r_sy, C2_IR2),
+	gte_mv_to_data_r(r_sz, C2_IR3),
+	delay_slot, gte_cmdw_sqr,
+})
+
 /* ─── STAGE 4 of normalize: mtc2 IR0..3 + GPF + mfc2 MAC + srav finalize ───
  * Reusable standalone — given an IR0 = 1/|v| estimate (typically from a sqrtbl lookup) and a shift count 
  * (typically (31 - LZCR)/2), multiplies IR0*IR[i] via GPF and shifts right to produce the normalized output.
  * Used standalone for "scale vector by scalar".
  * Words: 11.  Clobbers: IR0..3, MAC1..3.  Uses gte_cmdw_gpf (sf=0, lm=0). */
-FI_ Slice_MipsCode ac_gte_gpf_scale(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz, U4 r_recip_est, U4 r_shift, U4 r_dx, U4 r_dy, U4 r_dz) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_gpf_scale, ab, {
+FI_ Slice_MipsCode ac_gte_gpf_scale(AtomBuilder_R ab, 
+	U4 r_sx, U4 r_sy, U4 r_sz, 
+	U4 r_recip_est, U4 r_shift, 
+	U4 r_dx, U4 r_dy, U4 r_dz)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	gte_mv_to_data_r(r_recip_est, C2_IR0),
 	gte_mv_to_data_r(r_sx,        C2_IR1),
 	gte_mv_to_data_r(r_sy,        C2_IR2),
 	gte_mv_to_data_r(r_sz,        C2_IR3),
-	nop2, /* retire IR0..IR3 → GPF input pre-fill (matches libgte 0x80016134..0x80016138) */
+	GteDelay_ nop2, /* retire IR0..IR3 → GPF input pre-fill (matches libgte 0x80016134..0x80016138) */
 	gte_cmdw_gpf,
 	gte_mv_from_data_r(r_dx, C2_MAC1),
 	gte_mv_from_data_r(r_dy, C2_MAC2),
@@ -83,89 +128,82 @@ FI_ Slice_MipsCode ac_gte_gpf_scale(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz,
 	shift_aright_var(r_dz, r_dz, r_shift),
 })
 
-/* ─── APPLY MATRIX LV (libgte ApplyMatrixLV port) ───
- * Atom component — auto-generates mac_apply_matrix_lv Mac composer macro.
- * Uses GTE RTPS (cv=1, sf=1, v=0) with lwc2-loaded V0/VZ0 inputs.
- * Per PSX-SPX `geometrytransformationenginegte.md` lines 416-418:
- *   IR1 = MAC1 = (TRX*1000h + RT11*VX0 + RT12*VY0 + RT13*VZ0) SAR (sf*12)
- *   IR2 = MAC2 = (TRY*1000h + RT21*VX0 + RT22*VY0 + RT23*VZ0) SAR (sf*12)
- *   IR3 = MAC3 = (TRZ*1000h + RT31*VX0 + RT32*VY0 + RT33*VZ0) SAR (sf*12)
- * RTPS uses the FULL row of the rotation matrix (not just diagonal like MVMVA with mx=0).
- * libgte's `gte_ApplyMatrix` calls `gte_rtv0()` = RTPS cv=1 v=0 mx=0.
- * Per `gte.h` line 405 the body sets cv=3 (BK, zero-initialized) so no TR contribution.
- *
- * Operands:
- *   r_mtx  : MT3_S2S4* (matrix pointer)
- *   r_vec  : U4 (pointer to PACKED V0 data — (pos.y << 16) | pos.x at +0, pos.z at +4)
- *   r_out  : V3_S4* (output pointer; MAC1/2/3 stored here)
- *   r_t0/1/2 : 3 GPR codes for matrix load + intermediate state
- * Words: ~26.  Clobbers: r_t0, r_t1, r_t2 (C2 $0..$4, VXY0/VZ0, MAC1/2/3, SXY0/1/2). */
-FI_ Slice_MipsCode ac_apply_matrix_lv(AtomBuilder_R ab
-	,	U4 r_mtx, U4 r_vec, U4 r_out
-	,	U4 r_t0,  U4 r_t1,  U4 r_t2
-) MipsAtomComp_Proc_(ac_apply_matrix_lv, ab, {
-	/* Load MATRIX rows into GTE RT11..RT33 (libgte convention: ctc2 to C2 $0..$4 in order).
-	 * load_half_u zero-extends the last word so RT33 = m[2][2] and TRX = 0. */
-	load_word(  r_t0, r_mtx,  0), nop, gte_mv_to_ctrl_r(r_t0, gte_cr_RT11),
-	load_word(  r_t0, r_mtx,  4), nop, gte_mv_to_ctrl_r(r_t0, gte_cr_RT12),
-	load_word(  r_t0, r_mtx,  8), nop, gte_mv_to_ctrl_r(r_t0, gte_cr_RT13),
-	load_word(  r_t0, r_mtx, 12), nop, gte_mv_to_ctrl_r(r_t0, gte_cr_RT21),
-	load_half_u(r_t0, r_mtx, 16), nop, gte_mv_to_ctrl_r(r_t0, gte_cr_RT22),
-	nop2,
-
-	/* Load PACKED pos into V0 (libgte SVECTOR layout).
-	 * r_vec points to atom-0-staged packed data ((pos.y << 16) | pos.x at +0, pos.z at +4).
-	 * LWC2 base register MUST be the pointer r_vec, NOT the loaded value r_t0. */
-	load_word(r_t0, r_vec, 0), nop,
-	gte_lw(C2_VXY0, r_vec, 0),
-	load_word(r_t0, r_vec, 4), nop,
-	gte_lw(C2_VZ0, r_vec, 4),
-
-	/* RTPS: cv=3 (no translation), sf=1 (no shift, integer), v=0 (V0 input),
-	 * mx=0 (rotation matrix). MAC = RT row · V0 + 0. RTPS also writes
-	 * SXY0/1/2 + SZ0..SZ3 (perspective division); ignored. */
-	gte_cmdw_rtps_sf1,
-
-	/* Read MAC1/2/3 → out. */
-	gte_mv_from_data_r(r_t0, C2_MAC1),
-	gte_mv_from_data_r(r_t1, C2_MAC2),
-	gte_mv_from_data_r(r_t2, C2_MAC3),
-	nop,
-	store_word(r_t0, r_out, 0),
-	store_word(r_t1, r_out, 4),
-	store_word(r_t2, r_out, 8),
-})
-
 /* ─── TRANS MATRIX (libgte TransMatrix port) ───
  * Atom component — auto-generates mac_trans_matrix Mac composer macro.
  * m->t = v (struct copy; libgte's TransMatrix at 0x8001a540 is just 3 store_words, no GTE, no add).
  * Uses 1 GPR (r_t1 = off value) per axis; per-axis load-delay-slot pattern.
  * Words: 9.  Clobbers: r_t1. */
-FI_ Slice_MipsCode ac_trans_matrix(AtomBuilder_R ab
+FI_ Slice_MipsCode ac_trans_mt3s3s4(AtomBuilder_R ab
 	,	U4 r_mtx, U4 r_off
-	,	U4 r_t1
-) MipsAtomComp_Proc_(ac_trans_matrix, ab, {
-	load_word(r_t1, r_off, O_(V3_S4,x)),
-	nop,
-	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[0])),
-
+	,	U4 r_t0, U4 r_t1, U4 r_t2
+) MipsAtomComp_Proc_(ab, {
+	load_word( r_t0, r_off, O_(V3_S4,x)),
 	load_word( r_t1, r_off, O_(V3_S4,y)),
-	nop,
+	load_word( r_t2, r_off, O_(V3_S4,z)),
+	store_word(r_t0, r_mtx, O_(MT3_S2S4,t[0])),
 	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[1])),
-
-	load_word(r_t1, r_off, O_(V3_S4,z)),
-	nop,
-	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[2])),
+	store_word(r_t2, r_mtx, O_(MT3_S2S4,t[2])),
 })
 
+/* ─── LZCR ROUND EVEN + HALF-SHIFT ───
+ * Takes the raw LZCR leading-zero/ones count (from mfc2 C2_LZCR, range 1..32 per PSX-SPX cop2r31) and the |v|² sum (in r_mag_sq from the MAC1+MAC2+MAC3 add).
+ * Produces:
+ *   r_shift        ← LZCR rounded down to even (clear bit 0)
+ *   r_mag_sq_copy  ← |v|² sum (moved out of r_mag_sq before it's overwritten)
+ *   r_mag_sq       ← (31 - even_LZCR) / 2 = the final srav/GPF shift amount
+ *
+ * Rounding to even ensures (31 - LZCR) is always odd, so the >> 1 division is consistent — no 0.5 loss.
+ * The caller branches on LZCR < 24 to decide left-shift vs right-shift of r_mag_sq_copy, then saves the shift count.
+ *
+ * Note: C2_LZCR (cop2r31) is a fixed read-only C2 data register — the caller must read it via mfc2 from C2_LZCR;
+ * there is no register choice at the hardware level. Only the GPR that holds the result is caller-determined. */
+FI_ Slice_MipsCode ac_lzcr_round_even_half_shift(AtomBuilder_R ab,
+	U4 r_shift,
+	U4 r_mag_sq,
+	U4 r_mag_sq_copy)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	and_i(r_shift, r_shift, gte_lzcr_even_mask),
+	or_u(r_mag_sq_copy, r_mag_sq, 0),
+	li_s(        r_mag_sq, 31),
+	sub_s(       r_mag_sq, r_mag_sq, r_shift),
+	shift_aright(r_mag_sq, r_mag_sq, 1),
+})
+
+FI_ Slice_MipsCode ac_gte_general_purpose_interopolation(AtomBuilder_R ab
+	, Reg to_ir0,  Reg to_ir1,  Reg to_ir2, Reg to_ir3
+	, Reg fr_mac1, Reg fr_mac2, Reg fr_mac3
+	, MipsCode nop_slot1, MipsCode nop_slot2)
+MipsAtomComp_Proc_(ab, {
+	gte_mv_to_data_r(to_ir0, C2_IR0),
+	gte_mv_to_data_r(to_ir1, C2_IR1), /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */
+	gte_mv_to_data_r(to_ir2, C2_IR2),
+	gte_mv_to_data_r(to_ir3, C2_IR3), /* IR3 = src.z (reloaded) */
+	GteDelay_ nop_slot1,
+	GteDelay_ nop_slot2,
+	gte_cmdw_gpf,
+	gte_mv_from_data_r(fr_mac1, C2_MAC1),
+	gte_mv_from_data_r(fr_mac2, C2_MAC2),
+	gte_mv_from_data_r(fr_mac3, C2_MAC3),
+})
+
+FI_ Slice_MipsCode ac_gte_mv_from_data_r_mac123(AtomBuilder_R ab
+	, Reg fr_mac1, Reg fr_mac2, Reg fr_mac3)
+MipsAtomComp_Proc_(ab, {
+	gte_mv_from_data_r(fr_mac1, C2_MAC1),
+	gte_mv_from_data_r(fr_mac2, C2_MAC2),
+	gte_mv_from_data_r(fr_mac3, C2_MAC3),
+})
+
+
+FI_ Slice_MipsCode ac_gte_mv_from_mac123_v3s4(AtomBuilder_R ab, Reg_(V3_S4) v) MipsAtomComp_ProcMap_(ab, mac_gte_mv_from_data_r_mac123(v.x, v.y, v.z))
+
 #pragma endregion MACs (Mips Atom Components)
 
 #pragma region Atom Procs
 
 /* ─── Local copy of PSYQ's sqrtbl (1/sqrt lookup table for VectorNormal). ───
  * Source: PSYQ 4.7 libgte sqrtbl at 0x800185B4 in hello_camera.elf.
- *   objdump -s --start-address=0x800185B4 --stop-address=0x800185F4 hello_camera.elf
- *   → 192 entries × 16-bit signed, in 1.12 fixed-point (max value 0x1000 = 1.0).
+ *   objdump -s --start-address=0x800185B4 --stop-address=0x800185F4 hello_camera.elf → 192 entries × 16-bit signed, in 1.12 fixed-point (max value 0x1000 = 1.0).
  *
  * Data is identical to the libgte original (byte-for-byte verified).
  * 
@@ -200,8 +238,9 @@ FI_ Slice_MipsCode ac_trans_matrix(AtomBuilder_R ab
  * and the load upper_halves of the table bracket the input range.
  * The later 64 entries (octaves 2-3) are the `srav` branch when the magnitude's top bit is well above bit 24.
  *
- * 192-entry table is reproduced verbatim from libgte (verified against libpsn00b/psxgte/vector.s:100-123 — 24 rows × 8 halfwords, last entry 0x0804). */
-internal RO_ S2  gte_normalize_sqr_tbl[192] align_(2) = {
+ * Reproduced verbatim from libgte (verified against libpsn00b/psxgte/vector.s:100-123 — 24 rows × 8 halfwords, last entry 0x0804).
+ * */
+internal S2 const gte_normalize_sqr_tbl[192] align_(2) = {
 	0x1000, 0x0fe0, 0x0fc1, 0x0fa3, 0x0f85, 0x0f68, 0x0f4c, 0x0f30,
 	0x0f15, 0x0efb, 0x0ee1, 0x0ec7, 0x0eae, 0x0e96, 0x0e7e, 0x0e66,
 	0x0e4f, 0x0e38, 0x0e22, 0x0e0c, 0x0df7, 0x0de2, 0x0dcd, 0x0db9,
@@ -228,130 +267,96 @@ internal RO_ S2  gte_normalize_sqr_tbl[192] align_(2) = {
 	0x0820, 0x081c, 0x0818, 0x0814, 0x0810, 0x080c, 0x0808, 0x0804,
 };
 
+typedef Struct_(Binds_normalize_v3s4) {
+	U2 src_offset;    /* offset of src V3_S4 within the BIOS scratchpad */
+	U2 dst_offset;    /* offset of dst V3_S4 within the BIOS scratchpad */
+};
+typedef Struct_(RegUse_normalize_v3s4) {
+	union { Reg_(V3_S4) res, src; };
+	union { Reg r0, src_ptr, mac2; };
+	union { Reg r1, dst_ptr; };
+	union { Reg r2, dst_offset, mac1, v_sqr_aligned; };
+	union { Reg r3, src_offset, btarget, shift_count, sqrtbl_index; };
+	union { Reg r4, mac3, v_sqr_sum, scale_exp, srav_shift; };
+	union { Reg r5, lzcr, inv_len; };
+};
 /* ─── Full normalize (all 4 stages inline) ───
- * Generic 4-stage GTE normalize (SQR → sum+LZCR → align+sqrtbl → GPF+srav).
- *
- * Parameterized by caller-provided scratch base + src/dst offsets.
- * The caller passes r_src_offset and r_dst_offset as compile-time constants
- * (typically derived from O_ macros in the caller's struct schema, e.g., `O_(CallerBundleScratch, fwd)`).
- *
- * This design lets any caller (with a scratch base + struct schema) use `normalize_v3s4_proc` 
- * without putting magic offsets in the C-side bundle helper — the offsets come from O_ macros at the call site.
- *
- * Body uses 9 GPRs (r_src_ptr..r_branch_tmp):
- *   r_src_ptr, r_dst_ptr : src/dst pointers (computed from r_scratch + caller offsets)
- *   r_tmp                : src.x PRESERVED across stages 1-2 (NOT clobbered by mfc2 MAC2) → fed to IR1 in stage 4
- *   r_mac1_scratch       : MAC1 result scratch (also holds aligned |v|² in stage 3)
- *   r_mac2_scratch       : MAC2 result scratch → result.x after stage 4 sra
- *   r_recip_est          : src.y PRESERVED across stages 1-2 → fed to IR2 in stage 4 → result.y
- *   r_lzcr               : |v|² sum (stage 2) → shift count (stage 3) → 1/|v| (stage 4 IR0)
- *   r_shift              : shift count SAVED in stage 3 → consumed by stage 4 srav
- *   r_branch_tmp         : src.z PRESERVED across stages 1-2 → fed to IR3 in stage 4 → result.z (also sqrtbl base addr)
- *
- * Atom_labels are srav_path / aligned_done 
- * (NOT namespaced — they're internal to this proc; 
- * the metaprogram's per-atom-name enum emission handles any collision across different atoms/files that share the same labels).
- *
- * Pool cost: 11 GPRs (well within the 9-10 caller-trash GPR budget when r_scratch is a wave-context carrier).
- *
- * Direct port of PSYQ libgte msc02.rel.text VectorNormal disassembly (0x800160a0..0x8001615c).
- * Words: ~59 (matches libgte 0x800160a0..0x8001615c at +/- 0-2 words for BD-slot reshuffling).
- * Sqrtbl: hardcoded to 0x800185B4 (libgte msc02.rel.data). Note: swapped to local.
- * Pipeline: clobbers IR0..3, MAC1..3, LZCS, LZCR.
- */
-/* MipsAtom_Proc_ wrapper: declares the static MipsCode[] body, then calls atombuilder_unroll(ab, ...) to copy the encoded instructions into the caller's MipsAtomBuilder arena.  */
-internal MipsAtom* normalize_v3s4_proc(AtomArena_R aa,	U4 r_scratch /* GPR code: scratch base carrier (e.g., R_T4 = R_ResolveScratch) */
-	,	U4 r_src_offset, U4 r_dst_offset     /* GPR codes: PARAMETERIZED offsets (caller passes O_ macros) */
-	,	U4 r_src_ptr, U4 r_dst_ptr, U4 r_tmp /* GPR codes: 3 scratch regs (src/dst computed + tmp) */
-	,	U4 r_mac1_scratch, U4 r_mac2_scratch /* GPR codes: 2 more: MAC1/MAC2 scratch */
-	,	U4 r_recip_est                       /* GPR code: |v|² sum + shift-input + sqrtbl[index] */
-	,	U4 r_lzcr, U4 r_shift                /* GPR codes: lzcr + final srav amount */
-	,	U4 r_branch_tmp                      /* GPR code: scratch (shift count, branch target, lookup addr) */
-)
-MipsAtom_Proc_(normalize_v3s4, aa, {
-	add_si(r_src_ptr, r_scratch, r_src_offset),     /* r_src_ptr = &src */
-	add_si(r_dst_ptr, r_scratch, r_dst_offset),     /* r_dst_ptr = &dst */
-	nop,
+ * Generic 4-stage GTE normalize (SQR → sum+LZCR → align+sqrtbl → GPF+srav). */
+internal MipsAtom* normalize_v3s4(AtomArena_R aa, RegUse_normalize_v3s4 r)
+MipsAtom_Proc_(aa, {
+	load_half(r.src_offset, R_TapePtr, O_(Binds_normalize_v3s4, src_offset)),
+	load_half(r.dst_offset, R_TapePtr, O_(Binds_normalize_v3s4, dst_offset)),
+	LdSlot_ add_u(r.src_ptr, R_ScratchBase, r.src_offset),
+	LdSlot_ add_u(r.dst_ptr, R_ScratchBase, r.dst_offset),
+	LdSlot_ add_ui_self(R_TapePtr, S_(Binds_normalize_v3s4)),
 
-	/* Load src.x/y/z from r_src_ptr (caller-determined address) into r_tmp/r_recip_est/r_branch_tmp.
-	 * r_tmp holds src.x throughout stages 1-2 — r_mac2_scratch is clobbered to MAC2 in stage 1.5 (line below). */
-	load_word(r_tmp,          r_src_ptr, O_(V3_S4,x)),
-	load_word(r_recip_est,    r_src_ptr, O_(V3_S4,y)),
-	load_word(r_branch_tmp,   r_src_ptr, O_(V3_S4,z)),
-	nop, /* load-delay */
+	mac_load_v3s4(r.src, r.src_ptr, 0),
 
 	/* Stage 1: mtc2 src → IR1/2/3, SQR fires. */
-	gte_mv_to_data_r(r_tmp,        C2_IR1),
-	gte_mv_to_data_r(r_recip_est,  C2_IR2),
-	gte_mv_to_data_r(r_branch_tmp, C2_IR3),
-	nop, gte_cmdw_sqr,
+	LdSlot_ mac_gte_sqr_v3s4(r.src.x, r.src.y, r.src.z, LdSlot_ nop),
 
-	/* Stage 2: mfc2 MAC1/2/3, sum, mtc2 LZCS. */
-	gte_mv_from_data_r(r_mac1_scratch, C2_MAC1),
-	gte_mv_from_data_r(r_mac2_scratch, C2_MAC2),
-	gte_mv_from_data_r(r_lzcr,         C2_MAC3),
-	nop,
-	add_u(r_lzcr, r_lzcr, r_mac2_scratch),
-	add_u(r_lzcr, r_lzcr, r_mac1_scratch),
-	gte_mv_to_data_r(r_lzcr, C2_LZCS),
-	nop2,
-	gte_mv_from_data_r(r_shift, C2_LZCR),
-	nop,
+	/* Stage 2: mfc2 MAC1/2/3, sum, mtc2 LZCS. src_ptr is dead; reuse as mac2. */
+	mac_gte_mv_from_data_r_mac123(r.mac1, r.mac2, r.mac3), LdSlot_ nop,
+	add_u_self(        r.v_sqr_sum, r.mac1),
+	add_u_self(        r.v_sqr_sum, r.mac2),
+	gte_mv_to_data_r(  r.v_sqr_sum, C2_LZCS), GteDelay_ nop2,
+	gte_mv_from_data_r(r.lzcr,      C2_LZCR), GteDelay_ nop,
 
-	/* Stage 3: compute srav amount (r_lzcr) + align |v|² to bit 24.
-	 * IMPORTANT: the sllv/srav below writes the aligned |v|² to r_mac1_scratch (NOT r_lzcr),
-	 * so r_lzcr retains the shift count all the way to the start of stage 4.
-	 */
-	and_i(   r_shift, r_shift, -2),
-	or_u(r_mac1_scratch, r_lzcr, 0),                            /* FIX B: save sum before clobbering r_lzcr with shift count */
-	li_s(    r_lzcr,           31),
-	sub_s(   r_lzcr, r_lzcr, r_shift),
-	shift_aright(r_lzcr, r_lzcr, 1),
-	/* r_branch_tmp = LZCR - 24 (overwrites r_branch_tmp; src.z no longer needed after SQR) */
-	add_si(  r_branch_tmp, r_shift, -24),
-	branch_lt_zero(r_branch_tmp, atom_offset(aligned_done, srav_path)), nop,    /* FIX A: bltz → srav_path (LZCR<24 path) */
-	jump_rel(atom_offset(srav_path, aligned_done)),                              /* FIX A: b → aligned_done (LZCR>=24 path) */
-	shift_lleft_var(r_mac1_scratch, r_mac1_scratch, r_branch_tmp),              /* FIX B: src=sum (r_mac1_scratch), dst=same */
+	/* Stage 3: even(LZCR), half-shift, align |v|² to bit 24. */
+	mac_lzcr_round_even_half_shift(r.lzcr, r.v_sqr_sum, r.v_sqr_aligned),
+	add_si(        r.btarget, r.lzcr, -24),
+	branch_lt_zero(r.btarget, atom_offset(aligned_done, srav_path)), BdSlot_ nop, /* bltz → srav_path (LZCR <  24 path) */
+		jump_rel(atom_offset(srav_path, aligned_done)),                             /* b → aligned_done (LZCR >= 24 path) */
+		BdSlot_ shift_lleft_var(r.v_sqr_aligned, r.v_sqr_aligned, r.btarget),
 		atom_label(srav_path)
-	li_s(    r_branch_tmp, 24),
-	sub_s(   r_branch_tmp, r_branch_tmp, r_shift),
-	shift_aright_var(r_mac1_scratch, r_mac1_scratch, r_branch_tmp),             /* FIX B: src=sum (r_mac1_scratch), dst=same */
+			li_s( r.shift_count, 24),
+			sub_s(r.shift_count, r.shift_count, r.lzcr),
+			shift_aright_var(r.v_sqr_aligned, r.v_sqr_aligned, r.shift_count),
 	atom_label(aligned_done)
-	/* Save the shift count to r_shift before the next 5 instructions overwrite r_lzcr
-	 * (the sqrtbl lookup loads 1/|v| into r_lzcr, which becomes IR0 in stage 4). */
-	or_u(r_shift, r_lzcr, 0),                                    /* r_shift ← shift count (preserved through stage 4) */
-	/* r_mac1_scratch holds |v|² aligned (top bit at bit 7). */
-	add_si(     r_mac1_scratch, r_mac1_scratch, -64),
-	shift_lleft(r_mac1_scratch, r_mac1_scratch, 1),
-	load_upper_i(r_branch_tmp, u4_hi(& gte_normalize_sqr_tbl)),
-	or_i_self(   r_branch_tmp, u4_lo(& gte_normalize_sqr_tbl)),
-	add_u(r_branch_tmp, r_branch_tmp, r_mac1_scratch),
-	load_half(r_lzcr,   r_branch_tmp, 0), nop,                  /* r_lzcr = sqrtbl[aligned-64] = 1/|v| (IR0 in stage 4) */
+		add_si(     r.v_sqr_aligned, r.v_sqr_aligned, -64),
+		shift_lleft(r.v_sqr_aligned, r.v_sqr_aligned, 1),
+		mac_load_word_imm(r.sqrtbl_index, & gte_normalize_sqr_tbl), add_u_self(r.sqrtbl_index, r.v_sqr_aligned),
+		load_half(r.inv_len, r.sqrtbl_index, 0),
+		LdSlot_ nop,
 
-	/* FIX bug C: r_branch_tmp held the sqrtbl base+index, NOT src.z. Reload src.z from scratch now that r_branch_tmp is free. */
-	load_word(r_branch_tmp, r_src_ptr, O_(V3_S4,z)), nop,        /* r_branch_tmp = src.z (for IR3 in stage 4) */
+	mac_gte_general_purpose_interopolation(r.inv_len,
+		r.src.x, r.src.y, r.src.z,
+		r.res.x, r.res.y, r.res.z,
+		GteDelay_ load_word(R_AtomJmp, R_TapePtr, 0), LdSlot_   // ac_yield: word 1
+		GteDelay_ add_ui_self(         R_TapePtr, S_(MipsCode)) // ac_yield: word 2
+	),
+	mac_shift_aright_var_v3s4_self(r.res, r.srav_shift),
+	mac_store_v3s4(r.res, r.dst_ptr, 0),
 
-	/* Stage 4: GPF + srav finalize (r_shift = shift count, r_lzcr = 1/|v|). */
-	gte_mv_to_data_r(r_lzcr,         C2_IR0),
-	gte_mv_to_data_r(r_tmp,          C2_IR1),                    /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */
-	gte_mv_to_data_r(r_recip_est,    C2_IR2),
-	gte_mv_to_data_r(r_branch_tmp,   C2_IR3),                    /* IR3 = src.z (reloaded) */
-	nop2, gte_cmdw_gpf,
-	gte_mv_from_data_r(r_mac2_scratch, C2_MAC1),
-	gte_mv_from_data_r(r_recip_est,    C2_MAC2),
-	gte_mv_from_data_r(r_branch_tmp,   C2_MAC3),
-	shift_aright_var(r_mac2_scratch, r_mac2_scratch, r_shift),   /* sra by r_shift = (31-LZCR)/2 (saved before sqrtbl lookup) */
-	shift_aright_var(r_recip_est,    r_recip_est,    r_shift),
-	shift_aright_var(r_branch_tmp,   r_branch_tmp,   r_shift),
+	jump_reg(R_AtomJmp), BdSlot_ nop // ac_yield: word 3-4
+})
 
-	/* Store result.x/y/z to r_dst_ptr (caller-determined dst address). */
-	store_word(r_mac2_scratch, r_dst_ptr, O_(V3_S4,x)),
-	store_word(r_recip_est,    r_dst_ptr, O_(V3_S4,y)),
-	store_word(r_branch_tmp,   r_dst_ptr, O_(V3_S4,z)),
+
+/* ─── GTE OP cross product (a × b → out) ───
+ * Generalized V3_S4 cross product via GTE OP (OuterProduct12 libpsyx convention).
+ * The >> 12 shift converts S12.20 → S12.0 OuterProduct12. */
+typedef Struct_(Binds_gte_cross_v3s4) { V3_S4* src_a; V3_S4* src_b; V3_S4* out; };
+typedef Struct_(RegUse_gte_cross_v3s4) {
+	Reg_(V3_S4) a;
+	Reg_(V3_S4) b;
+	union { Reg out, t0; } x;
+	union { Reg src_a, t1, rt11; } y;
+	union { Reg src_b, t2, rt22; } z;
+};
+internal MipsAtom* gte_cross_v3s4(AtomArena_R aa, RegUse_gte_cross_v3s4 r)
+atom_info(atom_bind(Binds_gte_cross_v3s4)) MipsAtom_Proc_(aa, {
+	load_word(r.y.src_a,  R_TapePtr, O_(Binds_gte_cross_v3s4,src_a)),
+	load_word(r.z.src_b,  R_TapePtr, O_(Binds_gte_cross_v3s4,src_b)),
+	load_word(r.x.out,    R_TapePtr, O_(Binds_gte_cross_v3s4,out)),
+	LdSlot_ add_ui_self(  R_TapePtr, S_(Binds_gte_cross_v3s4)),
+
+	mac_load_v3s4(r.a, r.y.src_a, 0), LdSlot_
+	mac_load_v3s4(r.b, r.z.src_b, 0), LdSlot_
+	mac_gte_op_cross_v3s4(r.a, r.b), /* RT diagonal + IR + OP + MAC read + shift */
+	mac_store_v3s4(r.a, r.x.out, 0),
 
 	mac_yield()
 })
-
 #pragma endregion Atom Procs
 
 #pragma region Baked Atoms
@@ -367,12 +372,22 @@ internal MipsAtom_(set_gte_mt3s2s4) atom_info(
 	load_word(R_T3, R_TapePtr, O_(Binds_SetGteMT3S2S4,transform)),
 	add_ui_self(    R_TapePtr, S_(Binds_SetGteMT3S2S4)),
 	/* Load 3x3 Rotation + 3x1 Translation from R_T3 into GTE CONTROL Regs (ctc2) */
-	load_word(R_T0, R_T3, 0),  load_word(R_T1, R_T3,  4),
-	gte_mv_to_ctrl_r(R_T0, gte_cr_RT11), gte_mv_to_ctrl_r(R_T1, gte_cr_RT12),
-	load_word(R_T0, R_T3, 8),  load_word(R_T1, R_T3, 12), load_word(R_T2, R_T3, 16),
-	gte_mv_to_ctrl_r(R_T0, gte_cr_RT13), gte_mv_to_ctrl_r(R_T1, gte_cr_RT21), gte_mv_to_ctrl_r(R_T2, gte_cr_RT22),
-	load_word(R_T0, R_T3, 20), load_word(R_T1, R_T3, 24), load_word(R_T2, R_T3, 28),
-	gte_mv_to_ctrl_r(R_T0, gte_cr_TRX),  gte_mv_to_ctrl_r(R_T1, gte_cr_TRY),  gte_mv_to_ctrl_r(R_T2, gte_cr_TRZ),
+	load_word(R_T0, R_T3, 0), 
+	load_word(R_T1, R_T3, 4), 
+	gte_mv_to_ctrl_r(R_T0, gte_cr_RT11),
+	gte_mv_to_ctrl_r(R_T1, gte_cr_RT12),
+	load_word(R_T0, R_T3,  8),
+	load_word(R_T1, R_T3, 12),
+	load_word(R_T2, R_T3, 16),
+	gte_mv_to_ctrl_r(R_T0, gte_cr_RT13),
+	gte_mv_to_ctrl_r(R_T1, gte_cr_RT21),
+	gte_mv_to_ctrl_r(R_T2, gte_cr_RT22),
+	load_word(R_T0, R_T3, 20),
+	load_word(R_T1, R_T3, 24),
+	load_word(R_T2, R_T3, 28),
+	gte_mv_to_ctrl_r(R_T0, gte_cr_TRX),
+	gte_mv_to_ctrl_r(R_T1, gte_cr_TRY),
+	gte_mv_to_ctrl_r(R_T2, gte_cr_TRZ),
 	mac_yield()
 };
 

code/duffle/gte.h

@@ -16,9 +16,6 @@
  *            gte_mv_to_data_r   (gte + mv + to + data + register)
  *            gte_lw_v0_xy(base) (gte + lw + v0 + xy)
  *            load_upper_i       (load-upper + immediate, unique verb)
- *
- *  Vendor mnemonics (gte_mtc2, gte_mfc2, gte_lwc2, gte_swc2, etc.) are NOT in this header.
- *  They are in the opt-in `gte_vendor_sym.h` for users who prefer the textbook MIPS assembly mnemonics.
  * ============================================================================ */
 
 #ifdef INTELLISENSE_DIRECTIVES
@@ -33,7 +30,7 @@
  *  gte.h — Geometry Transformation Engine (COP2) for the PS1
  * ============================================================================
  *
- *  Hand-rolled DSL for emitting GTE/MIPS instruction words as raw `.word` constants from C.
+ *  Hand-rolled DSL for emitting GTE/MIPS instruction words from C.
  *  No GCC inline-assembly string syntax in the code body.
  *
  *  STYLE NOTES
@@ -101,20 +98,20 @@ enum {
 
 /* Semantic Aliases for GTE Data Registers */
 enum {
-	gte_in_v0_xy     = C2_VXY0, /* Input Vector 0 (X, Y) */
-	gte_in_v0_z      = C2_VZ0,  /* Input Vector 0 (Z) */
-	gte_in_v1_xy     = C2_VXY1, /* Input Vector 1 (X, Y) */
-	gte_in_v1_z      = C2_VZ1,  /* Input Vector 1 (Z) */
-	gte_in_v2_xy     = C2_VXY2, /* Input Vector 2 (X, Y) */
-	gte_in_v2_z      = C2_VZ2,  /* Input Vector 2 (Z) */
-	gte_in_rgb       = C2_RGB,  /* Input Color (R, G, B, MipsCode) */
-	gte_out_scr_xy0  = C2_SXY0, /* Output Screen Coord 0 (X, Y) */
-	gte_out_scr_xy1  = C2_SXY1, /* Output Screen Coord 1 (X, Y) */
-	gte_out_scr_xy2  = C2_SXY2, /* Output Screen Coord 2 (X, Y) */
-	gte_out_depth    = C2_OTZ,  /* Output Ordering Table Z (Depth) */
-	gte_math_accum0  = C2_MAC0, /* Math Accumulator 0 */
-	gte_math_accum1  = C2_MAC1, /* Math Accumulator 1 */
-	gte_math_accum2  = C2_MAC2, /* Math Accumulator 2 */
+	C2_InV0_XY    = C2_VXY0, /* Input Vector 0 (X, Y) */
+	C2_InV0_Z     = C2_VZ0,  /* Input Vector 0 (Z) */
+	C2_InV1_XY    = C2_VXY1, /* Input Vector 1 (X, Y) */
+	C2_InV1_Z     = C2_VZ1,  /* Input Vector 1 (Z) */
+	C2_InV2_XY    = C2_VXY2, /* Input Vector 2 (X, Y) */
+	C2_InV2_Z     = C2_VZ2,  /* Input Vector 2 (Z) */
+	C2_In_RGB     = C2_RGB,  /* Input Color (R, G, B, MipsCode) */
+	C2_OutSrc_XY0 = C2_SXY0, /* Output Screen Coord 0 (X, Y) */
+	C2_OutSrc_XY1 = C2_SXY1, /* Output Screen Coord 1 (X, Y) */
+	C2_OutSrc_XY2 = C2_SXY2, /* Output Screen Coord 2 (X, Y) */
+	C2_OutDepth   = C2_OTZ,  /* Output Ordering Table Z (Depth) */
+	C2_MathAccu0  = C2_MAC0, /* Math Accumulator 0 */
+	C2_MathAccu1  = C2_MAC1, /* Math Accumulator 1 */
+	C2_MathAccu2  = C2_MAC2, /* Math Accumulator 2 */
 };
 
 /* --- GTE Command Semantics (The Bitfield Meanings) --- 
@@ -173,46 +170,40 @@ enum {
  *   +------------+--+-----+------+------+------+------+---+--------+----------+
  *                                    \_____ GTE_PAYLOAD _____/       \__ GTE_CMD __/
  *
- * Shifts/masks below are the *bit positions* and *bit widths* of each configurable field, used by the ENC_GTE_CMD encoder. 
- * Mirrors the OPCODE_SHIFT / RS_SHIFT convention used in mips.h.
+ * Offset position & masks below are the *bit positions* and *bit widths* of each configurable field, used by the ENC_GTE_CMD encoder. 
+ * Mirrors the OPCODE_POS / RS_POS convention used in mips.h.
  */
 
-	gte_shift_sf  = 19,  gte_width_sf  = 1,  gte_mask_sf  = 0x1,
-	gte_shift_mx  = 17,  gte_width_mx  = 2,  gte_mask_mx  = 0x3,
-	gte_shift_v   = 15,  gte_width_v   = 2,  gte_mask_v   = 0x3,
-	gte_shift_cv  = 13,  gte_width_cv  = 2,  gte_mask_cv = 0x3,
-	gte_shift_lm  = 10,  gte_width_lm  = 1,  gte_mask_lm  = 0x1,
-	gte_shift_cmd =  0,  gte_width_cmd = 6,  gte_mask_cmd = 0x3F,
+	gte_pos_sf  = 19,  gte_width_sf  = 1,
+	gte_pos_mx  = 17,  gte_width_mx  = 2,
+	gte_pos_v   = 15,  gte_width_v   = 2,
+	gte_pos_cv  = 13,  gte_width_cv  = 2,
+	gte_pos_lm  = 10,  gte_width_lm  = 1,
+	gte_pos_cmd =  0,  gte_width_cmd = 6,
 
 	/* Fake command number (bits 24-20) — IGNORED by the GTE hardware per PSX-SPX `geometrytransformationenginegte.md` line 48.
 	 * libgte's compiler emits non-zero values in this field as a disassembly signature. */
-	gte_shift_fake_cmd = 20,
+	gte_pos_fake_cmd   = 20,
 	gte_width_fake_cmd = 5,
-	gte_mask_fake_cmd  = 0x1F,
 };
 
 /* --- GTE Control Register Aliases (Pitfall 1) ---
- * Three pairs of aliases map to the SAME C2 control-register slot on real silicon:
+ * Three pairs of aliases map to the C2 control-register slot:
  *   C2[24] = gte_cr_RBK (background R)         | gte_cr_OFX (screen offset X)
  *   C2[25] = gte_cr_GBK (background G)         | gte_cr_OFY (screen offset Y)
  *   C2[26] = gte_cr_BBK (background B)         | gte_cr_H   (projection plane distance H)
- * Cross-alias writes inside one atom body, or across the wave-context boundary,
- * silently clobber each other. The metaprogram's check_gte_cr_alias_writes
- * (CHECK_RULES row) warns about each pair per source. See
- * docs/gte_reference.md §"Control-register alias table" for the silicon
- * rationale and the libgte outer-product convention.
+ * Cross-alias writes inside one atom body, or across the wave-context boundary, silently clobber each other.
+ * The metaprogram's check_gte_cr_alias_writes (CHECK_RULES row) warns about each pair per source.
+ * See psx-spx docs/gte_reference.md §"Control-register alias table" for the silicon rationale and the libgte outer-product convention.
  */
 
 /* --- RT-matrix packed-slot convention (Pitfall 4) ---
  * The silicon packs two 16-bit RT elements per 32-bit C2 slot:
  *   C2[2] = (RT22 << 16) | RT13       (gte_cr_RT13 writes the low  half, gte_cr_RT22 writes the high half)
  *   C2[4] = (RT33 << 16) | RT22       (gte_cr_RT22 writes the low  half — clobbers prior RT22 value if RT13 was also written)
- * OP and MVMVA read D1/D2/D3 from these packed slots. The libgte outer-product
- * convention (see ac_apply_matrix_lv at gte.atom.c:108-122) writes C2[2] then
- * C2[4] in sequence; the SECOND write's low half is RT22, not RT13. An agent
- * who writes gte_cr_RT13 then gte_cr_RT22 to the SAME source GPR clobbers the
- * RT13 value. See docs/gte_reference.md §"RT-matrix packed-slot convention"
- * for the canonical write pattern.
+ * OP and MVMVA read D1/D2/D3 from these packed slots.
+ * The libgte outer-product convention (see ac_apply_matrix_lv at gte.atom.c:108-122) writes C2[2] then C2[4] in sequence;
+ * the SECOND write's low half is RT22, not RT13. 
  */
 
 /* --- GTE Control Register Indices (for ctc2/cfc2) ---
@@ -301,8 +292,7 @@ enum { _C2_TX_SUBS_ = 0
 // #define gte_mv_from_data_r(rt, rd) enc_gte_tx(cop_mf, (rt), (rd)) /* Move GTE Control Register (rd) to GPR (rt) */
 
 /* GTE Data vs Control Register Transfers
- *
- * Each macro emits a single .word constant for one of MFC2/CFC2/MTC2/CTC2.
+ * Each macro emits a single instruction for one of MFC2/CFC2/MTC2/CTC2.
  *
  * `rd` is the C2 register index in the file the sub-opcode names:
  *   gte_mv_from_data_r / gte_mv_to_data_r  →  C2 data register file
@@ -317,14 +307,14 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_mv_from_ctrl_r(rt, rd) enc_gte_tx(sub_cfc2, (rt), (rd)) /* Copy From ctrl reg */
 #define gte_mv_to_data_r(rt, rd)   enc_gte_tx(sub_mtc2, (rt), (rd)) /* Move To   data reg */
 #define gte_mv_to_ctrl_r(rt, rd)   enc_gte_tx(sub_ctc2, (rt), (rd)) /* Copy To   ctrl reg */
+#define GteDelay_ // Annotate an instruction as filling a CPU <-> GTE DMA delay slot/s
 
 /* COP2 Data Load (lwc2): `lwc2 rt, off(rs)`
  * Layout: [op_lwc2:6][rs:5][rt:5][imm:16]
  *   - rs: GPR base address
  *   - rt: COP2 data register index (0..31)
  *   - imm: signed 16-bit offset
- * NOTE: When `rs` is a runtime register, the encoding cannot be pre-baked
- * into a .word — use the string-style `gte_load_v0` macro below instead. */
+ * NOTE: When `rs` is a runtime register, the encoding cannot be pre-baked into a .word — use the string-style `gte_load_v0` macro below instead. */
 #define enc_gte_lw(rt, base, off) enc_i(op_lwc2, (base), (rt), (off))
 /* Store Word */
 #define enc_gte_sw(rt, base, off) enc_i(op_swc2, (base), (rt), (off))
@@ -333,8 +323,7 @@ enum { _C2_TX_SUBS_ = 0
  * `swc2` is redundant when we're already inside the `gte_` namespace.
  *   gte_lw rt, base, off  →  lwc2 rt, off(base)
  *   gte_sw rt, base, off  →  swc2 rt, off(base)
- * For the typical user-facing vector-level load (xy + z as two instructions),
- * use the higher-level `gte_load_vN` macros below. */
+ * For the typical user-facing vector-level load (xy + z as two instructions), use the higher-level `gte_load_vN` macros below. */
 #define gte_lw(rt, base, off) enc_gte_lw(rt, base, off)
 #define gte_sw(rt, base, off) enc_gte_sw(rt, base, off)
 
@@ -351,13 +340,13 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_cmd_base (enc_op(op_cop2) | (1 << 25))
 
 /* Per-field encoders. Each one does (value & mask) << shift on its own. */
-#define enc_gte_sf(sf)          (((sf)  & gte_mask_sf      ) << gte_shift_sf )
-#define enc_gte_mx(mx)          (((mx)  & gte_mask_mx      ) << gte_shift_mx )
-#define enc_gte_v(v)            (((v)   & gte_mask_v       ) << gte_shift_v  )
-#define enc_gte_cv(cv)          (((cv)  & gte_mask_cv      ) << gte_shift_cv )
-#define enc_gte_lm(lm)          (((lm)  & gte_mask_lm      ) << gte_shift_lm )
-#define enc_gte_cmd(cmd)        (((cmd) & gte_mask_cmd     ) << gte_shift_cmd )
-#define enc_gte_fake_cmd(x)     (((x)   & gte_mask_fake_cmd) << gte_shift_fake_cmd)
+#define enc_gte_sf(sf)      ((sf)  << gte_pos_sf )
+#define enc_gte_mx(mx)      ((mx)  << gte_pos_mx )
+#define enc_gte_v(v)        ((v)   << gte_pos_v  )
+#define enc_gte_cv(cv)      ((cv)  << gte_pos_cv )
+#define enc_gte_lm(lm)      ((lm)  << gte_pos_lm )
+#define enc_gte_cmd(cmd)    ((cmd) << gte_pos_cmd )
+#define enc_gte_fake_cmd(x) ((x)   << gte_pos_fake_cmd)
 
 /* Composite: all six GTE fields + the COP2/CO base. */
 #define enc_gte_cmdw(sf, mx, v, cv, lm, cmd) ( \
@@ -409,10 +398,11 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_cmdw_rtpt   (gte_cmd_base | enc_gte_cmd(gte_cmd_rtpt ) | gte_cmdw_psyq_compat)
 #define gte_cmdw_nclip  (gte_cmd_base | enc_gte_cmd(gte_cmd_nclip))
 #define gte_cmdw_op     (gte_cmd_base | enc_gte_cmd(gte_cmd_op   ))
-#define gte_cmdw_outer_product gte_cmdw_op      /* "outer product" -- NOCASH/Sdk terminology */
-#define gte_cmdw_wedge         gte_cmdw_op      /* "wedge product"  -- geometric-algebra terminology.
-	* RGA(Lengyel): the GTE OP is a 3D signed-16-bit D x IR cross, not a generic RGA exterior product.
-	* The wedge alias is the 3D complement interpretation of the same 3 scalars (MAC1..MAC3). */
+#define gte_cmdw_outer_product gte_cmdw_op      /* "outer product" -- PSY-Q terminology */
+#define gte_cmdw_wedge         gte_cmdw_op      /* "wedge product"  -- geometric-algebra terminology. */
+#define gte_cmdw_cross         gte_cmdw_op      /* "cross product"  -- geometric-algebra terminology.
+	* RGA(Lengyel): The GTE OP is a 3D signed-16-bit D x IR cross, not a generic RGA exterior product.
+	* The wedge alias is a 3D complement interpretation of the same 3 scalars (MAC1..MAC3). */
 #define gte_cmdw_mvmva  (gte_cmd_base | enc_gte_cmd(gte_cmd_mvmva))
 
 /* MVMVA with sf=0 (no shift, full-integer), cv=3 (no translation), v=3 (IR vector input).
@@ -440,29 +430,17 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_cmdw_mvmva_pass1_c11  (gte_cmd_base | enc_gte_v(2) | enc_gte_mx(3) | enc_gte_cmd(gte_cmd_mvmva))
 #define gte_cmdw_mvmva_no_tr gte_cmdw_mvmva_ir
 
-/* MVMVA pass 2 — EXACT C11 ApplyMatrixLV command.
- * Command word: 0x4A49E012.
- * bits 31-26: 010010 = COP2
- * bit 25: 1 (CO set)
- * bits 24-20: 01001 = 9 (fake_cmd)
- * bit 19: 1 (sf=1)
- * bits 18-17: 00 (mx=0, RT matrix)
- * bits 16-15: 11 (v=3, IR)
- * bits 14-13: 11 (cv=3, no translation)
- * bits 5-0: 010010 = MVMVA
- * sf=1, mx=0, v=3, cv=3. Pass 2 reads RT matrix, IR input, >>12. */
-#define gte_cmdw_mvmva_c11_pass2_exact  0x4A49E012
-
-/* MVMVA pass 1 — C11's exact command: 0x4A41E012.
- * bit 25: 1, sf=0, mx=0, v=3, cv=3. Pass 1 reads RT matrix, IR input, no shift. */
-#define gte_cmdw_mvmva_c11_pass1_exact  0x4A41E012
+/* MVMVA pass 2 — C11 ApplyMatrixLV command.
+ * Decoded: op_cop2 | CO | fake_cmd=4 | sf=1 (>>12) | mx=0 (RT matrix) | v=3 (IR) | cv=3 (no translation) | lm=0 | cmd=MVMVA.
+ * Reads (RT row · IR) >> 12 into MAC1/2/3. Per-field composition (no opaque literal)
+ * keeps the bit layout visible at the call site + matches the libgte C-side byte-exact. */
+#define gte_cmdw_mvmva_c11_pass2  (gte_cmd_base | enc_gte_fake_cmd(4) | enc_gte_sf(1) | enc_gte_v(3) | enc_gte_mx(0) | enc_gte_cv(3) | enc_gte_cmd(gte_cmd_mvmva))
 
 /* MVMVA: sf=1 (>>12), mx=0 (RT matrix), v=0 (V0), cv=3 (no TR). */
 #define gte_cmdw_mvmva_sf1_mx0_v0_cv3  (gte_cmd_base | enc_gte_sf(1) | enc_gte_cv(3) | enc_gte_v(0) | enc_gte_mx(0) | enc_gte_cmd(gte_cmd_mvmva))
 
-/* RTPS with sf=1 (12-bit shift, no translation): matches the output of libgte's
- * ApplyMatrixLV when the GTE pipeline expects R*pos >> 12. The shift produces
- * values like (-270, 710, 1713) which match the C11 reference path. */
+/* RTPS with sf=1 (12-bit shift, no translation): matches the output of libgte's ApplyMatrixLV when the GTE pipeline expects R*pos >> 12. 
+ * The shift produces values like (-270, 710, 1713) which match the C11 reference path. */
 #define gte_cmdw_rtps_sf1   (gte_cmd_base | enc_gte_sf(1) | enc_gte_cv(3) | enc_gte_cmd(gte_cmd_rtps))
 
 /* SQR / GPF cosmetic-bits compat helpers.
@@ -495,6 +473,12 @@ enum { _C2_TX_SUBS_ = 0
  *   bits 24-20 = 0x19 (libgte "nonsense SDK command number" signature) */
 #define gte_cmdw_gpf   (gte_cmd_base | enc_gte_cmd(gte_cmd_gpf) | gte_cmdw_gpf_fake_sig)
 
+/* Mask to round LZCR (leading-zero/ones count, range 1..32 per PSX-SPX cop2r31) down to even.
+ * The normalize_v3s4 half-shift logic computes (31 - LZCR) >> 1; clearing bit 0 ensures the subtraction result is always odd, so the >> 1 division is consistent (no 0.5 loss). */
+enum {
+	gte_lzcr_even_mask = 0xFFFE, /* all bits except bit 0 */
+};
+
 #define gte_cmdw_rotate_translate_perspective_single gte_cmdw_rtps
 #define gte_cmdw_rotate_translate_perspective_triple gte_cmdw_rtpt
 /* RGA(Lengyel): RTPS/RTPT consume the matrix expansion of a rigid transformation (rotation matrix + translation vector) loaded into the RT/TR control registers.
@@ -597,8 +581,8 @@ enum {
 
 /* gte_load_v0v1v2(p0, p1, p2, b0, b1, b2) — prelude to gte_cmd_rtpt.
  *
- * Loads all three GTE input vectors (6 words) from three separate pointers, one per GTE vector register,
- * each loaded from its own base GPR. Caller must bind each `pN` to `bN` via a register variable.
+ * Loads all three GTE input vectors (6 words) from three separate pointers, one per GTE vector register, each loaded from its own base GPR.
+ * Caller must bind each `pN` to `bN` via a register variable.
  *   register V3_S2* p0 rgcc(R_T4) = verts[0].ptr;  // → __asm__("$12")
  *   register V3_S2* p1 rgcc(R_T5) = verts[1].ptr;  // → __asm__("$13")
  *   register V3_S2* p2 rgcc(R_T6) = verts[2].ptr;  // → __asm__("$14")
@@ -692,8 +676,7 @@ enum {
  * Loads the 3x3 rotation matrix at `r0` into the GTE's rotation-matrix control registers (RT11..RT22, indices 0..4) via ctc2.
  *
  * Memory layout at r0: five contiguous 32-bit words (offsets 0..16), each holding two packed 16-bit matrix elements.
- * The first 1.5 rows of a standard PSX SDK MATRIX struct (where each row is laid out as
- * [RT_xx, RT_xy] | [RT_xz, pad] | ...).
+ * The first 1.5 rows of a standard PSX SDK MATRIX struct (where each row is laid out as [RT_xx, RT_xy] | [RT_xz, pad] | ...).
  *
  * Generated MIPS (mirrors the source macro):
  *   lw   $12,  0( %0 )    ; word 0

code/duffle/lottes_tape.h

@@ -66,61 +66,81 @@
  * */
 /* Register Allocation Info */
 enum {
-	R_AtomJmp  = R_T8 atom_reg,  /* debug-visible; tape yield handshake scratch */
-	R_TapePtr  = R_T9 atom_reg,  /* The Instruction Stream Pointer */
+	R_ScratchBase = R_SP atom_reg, /* Scratchpad base address (host frame top) */
+	R_AtomJmp     = R_FP atom_reg, /* Next atom target (yield handshake scratch) */
+	R_TapePtr     = R_RA atom_reg, /* The Instruction Stream Pointer */
 /* Stringification codes for the GCC inline assembler clobber lists. */
-#define R_AtomJmp_Code R_T8_Code
-#define R_TapePtr_Code R_T9_Code
+#define R_ScratchBase_Code R_SP_Code
+#define R_AtomJmp_Code     R_FP_Code
+#define R_TapePtr_Code     R_RA_Code
 
 // R_InCursor = R_T4,
 // #define R_InCursor_Code    R_T4_Code
 
-// Reserved Registers (Callee-saved):
-// - R_T9: Holds the Tape Ptr which we need to increment
-//         If we hit a wall with register allocations we can clobber V0 & V1 (return values), defering as opt-in by user.
-// - R_RA: Not sure??
-// Needed by ac_yield but can be used as atom scratch:
-// - R_T8: Will be used as the atom jump register.
+// Reserved Registers (Callee-saved across the host ABI transition):
+// - R_SP: Holds the scratchpad base while tape code executes.
+// - R_FP: Holds the next atom target.
+// - R_RA: Holds the tape cursor.
+// All atom-body allocations must stay out of these.
+// Atom bodies may freely use R2-R25.
 
-// All allocatable registers for mips atoms:
-	R_TScratchVolatile = R_AT, // This one is reserved for psuedo instructions, but you can technically use it.
-	R_TScratch0  = R_T0,
-	R_TScratch1  = R_T1,
-	R_TScratch2  = R_T2,
-	R_TScratch3  = R_T3,
-	R_TScratch4  = R_T4,
-	R_TScratch5  = R_T5,
-	R_TScratch6  = R_T6,
-	R_TScratch7  = R_T7,
-	R_TScratch8 =  R_T8,
-	R_TScratch10 = R_V0, // Tend to be used with gte DMAs
-	R_TScratch11 = R_V1, // Tend to be used with gte DMAs
-	// Note(Ed): We can technically clobber these, but don't unless we hit a bottleneck.
-	// A 0-2
-	// S 0-7
+// All allocatable registers for atom bodies (R2-R25, 24 registers):
+
+	R_PsuedoVolatile = R_AT, // Assembler temporary; never allocate.
+
+	// Atom Allocation Pool
+	R_Atom0  = R_T0,
+	R_Atom1  = R_T1,
+	R_Atom2  = R_T2,
+	R_Atom3  = R_T3,
+	R_Atom4  = R_T4,
+	R_Atom5  = R_T5,
+	R_Atom6  = R_T6,
+	R_Atom7  = R_T7,
+	R_Atom8  = R_T8,
+	R_Atom9  = R_T9,
+	R_Atom10 = R_V0, // Tend to be used with gte moves
+	R_Atom11 = R_V1, // Tend to be used with gte moves
+	R_Atom12 = R_A0,
+	R_Atom13 = R_A1,
+	R_Atom14 = R_A2,
+	R_Atom15 = R_A3,
+	R_Atom16 = R_S0,
+	R_Atom17 = R_S1,
+	R_Atom18 = R_S2,
+	R_Atom19 = R_S3,
+	R_Atom20 = R_S4,
+	R_Atom21 = R_S5,
+	R_Atom22 = R_S6,
+	R_Atom23 = R_S7,
 };
 
 typedef U2 Reg; // Register parameter used with atom or atom component procedures
+#define Reg_(type) tmpl(Reg,type) // Just a way to template register allocations of C-struct types.
 
 typedef U4 const MipsCode; // Underlying type to mips asm words.
 typedef Slice_(MipsCode);
 
-typedef U4 const MipsAtom; 
+typedef U4 const MipsAtom; // Underlying type to a mips atom defnition 
 typedef Slice_(MipsAtom);
+
 // Sometimes a user will define a bundle of atoms that represent a procedure of work as:
 //   MipsAtom* <identifier>[...];
 // Unfortuantely if using slice_from_array it will make the slice's pointer: MipsAtom** so this enforce its defined as MipsAtom*
-// TODO(Ed): Alternatively we can make the MipsAtom an opaque pointer to the atom... so that the blow returns 'MipsAtom'.
+// TODO(Ed): Alternatively we can make the MipsAtom an opaque pointer to the atom... so that the proc returns 'MipsAtom'.
 #define atombundle_from_array(array) (Slice_MipsAtom){.ptr=array[0],.len=Array_len(array)}
 
 // Underlying type to an ptr to an array of mips asm words that must terminate with an ac_yield.
 #define MipsAtom_(sym) MipsCode sym [] align_(4) =
 
 // Used for atoms with value-args
-//   FI_ void ac_X(args) MipsAtomComp_Proc_(ac_X, { body })
+//   internal MipsAtom* X_proc(AtomArena_R aa, args) MipsAtom_Proc_(X, aa, { body })
 // expands to:
-//   FI_ void ac_X(args) { MipsCode ac_X[] align_(4) = { body }; return ac_X; }
-#define MipsAtom_Proc_(sym, aa, ...) { MipsCode sym [] align_(4) = __VA_ARGS__; return atomarena_push(aa, slice_from_array(MipsCode, sym)); }
+//   internal MipsAtom* X_proc(AtomArena_R aa, args) { MipsCode atom_comp_code[] align_(4) = { body }; return atomarena_push(aa, slice_from_array(MipsCode, atom_comp_code)); }
+// The atom name is derived by the Lua metaprogram from the preceding
+// `MipsAtom* X_proc(...)` declaration (backward walk from the macro site,
+// strips the `_proc` suffix).
+#define MipsAtom_Proc_(aa, ...) { MipsCode atom_comp_code[] align_(4) = __VA_ARGS__; return atomarena_push(aa, slice_from_array(MipsCode, atom_comp_code)); }
 
 // Used for components with no args (e.g., ac_load_tri_indices) or identifier-args (hardcoded register names).
 //   MipsAtomComp_(ac_X) { body }
@@ -129,68 +149,95 @@ typedef Slice_(MipsAtom);
 #define MipsAtomComp_(sym) MipsCode sym [] align_(4) =
 
 // Used for components with value-args (mandatory `ab` (atom-builder) arg).
-//   FI_ void ac_X(MipsAtomBuilder_R ab, args) MipsAtomComp_Proc_(ac_X, ab, { body })
+//   FI_ void ac_X(MipsAtomBuilder_R ab, args) MipsAtomComp_Proc_(ab, { body })
 // expands to:
 //   FI_ void ac_X(MipsAtomBuilder_R ab, args) {
-//       MipsCode ac_X[] align_(4) = { body };
-//       atombuilder_unroll(ab, slice_from_array(MipsCode, ac_X));
+//       MipsCode atom_comp_code[] align_(4) = { body };
+//       atombuilder_push(ab, slice_from_array(MipsCode, atom_comp_code));
 //   }
 // The body must NOT include mac_yield() (the parent atom yields).
-// Inline-only callers (the generated `mac_<name>` aliases) skip this arg via metaprogram filtering;
-// escape callers (ac_<name> invoked as a function) pass a long-lived builder.
-#define MipsAtomComp_Proc_(sym, ab, ...) { MipsCode sym [] align_(4) = __VA_ARGS__; atombuilder_push(ab, slice_from_array(MipsCode, sym)); }
+// The component name is derived by the Lua metaprogram from the preceding `FI_ Slice_MipsCode ac_X(...)` declaration (backward walk from the macro site).
+// Inline-only callers (the generated `mac_<name>` aliases) skip the `ab` arg via metaprogram filtering; escape callers (ac_<name> invoked as a function) pass a long-lived builder.
+#define MipsAtomComp_Proc_(ab, ...) { MipsCode atom_comp_code[] align_(4) = __VA_ARGS__; atombuilder_push(ab, slice_from_array(MipsCode, atom_comp_code)); }
+
+// Used for trivial mappings from one atom component proc to the command of a more baser (meant for type-mapping)
+#define MipsAtomComp_ProcMap_(ab, base_command) atom_dbg_skip MipsAtomComp_Proc_(ab, {base_command })
+
+// WIP: Atoms Assocated closely with each other to form a tape procedure. (Maybe also a phase in a procedure/pipeline?)
+
+#define AtomBundle_(name)              Struct_(tmpl(AtomBundle,name))
+#define AtomBundle_Len(name)           S_(tmpl(AtomBundle,name))/S_(MipsAtom*)
+#define AtomBundleEntry_(bundle,entry) tmpl(bundle,entry)
 
 /* Line-table anchor: gcc only adds a file to the .debug_line file table when the contains line-numbered content.
 	Files containing only atoms and atom components.
    Place `ATOM_FILE_LINE_MARKER();` once at file scope in any `.atom.c` that defines atoms.
-	 The macro expands to a file-scope `internal U4 const` declaration keeps the file in the line table.
-	 The constant is in `.rodata` and unreferenced; the linker may eliminate it.
-	 The two-level concat + `__LINE__` suffix makes the identifier unique per call site
-	 (the identifier embeds the source line, so duplicates across `#include`d files don't collide). */
+	 Macro expands to a file-scope `internal U4 const` declaration keeps the file in the line table.
+	 The constant is in `.rodata` so the linker may eliminate it. */
 #define ATOM_FILE_DEBUGGER_LINE_MARKER(file_name) internal U4 const tmpl(atom_file_debugger_line_marker,file_name) = 0
 
 typedef Slice_MipsAtom Tape;
 
-/* The 'Exit' Atom */
-atom_dbg_skip MipsAtom_(tape_exit) { jump_reg(R_RA), nop };
+typedef Struct_(TapeHostFrame) {
+	U4 s0;
+	U4 s1;
+	U4 s2;
+	U4 s3;
+	U4 s4;
+	U4 s5;
+	U4 s6;
+	U4 s7;
+	U4 fp;
+	U4 sp;
+	U4 ra;
+};
 
-// TODO(Ed): When we have a substantial workload/throughput, profile each of these to see impact at ABI boundaries.
+enum {
+	TapeHostFrame_Loc = Scratchpad_End - S_(TapeHostFrame),
+	TapeScratch_Len   = TapeHostFrame_Loc - Scratchpad_Loc,
+};
+static_assert(S_(TapeHostFrame) == 11 * S_(U4));
+static_assert(TapeHostFrame_Loc == 0x1F8003D4);
 
-/* Tape Runner (Default) */
-FI_ void tape_run(Tape tape) { register U4* tape_ptr rgcc(R_TapePtr) = u4_r(tape.ptr); asm volatile(
-	asm_words(
-		  load_word(  R_AtomJmp, R_TapePtr, 0) /* Bootstrap the first jump */
-		, add_ui_self(R_TapePtr, S_(MipsAtom)) /* Advance tape */
-		, call_reg(   R_AtomJmp)               /* jalr $t9 */
-		, nop                                  /* Branch delay slot */
-	)
-	asm_rpins, r_use(tape_ptr)
-	asm_clobber: 
-		rlit(R_AT),
-		rlit(R_V0), rlit(R_V1), // We clobber these for GTE ACs (that don't expose register selection, might expose them in the future...)
-		rlit(R_T0), rlit(R_T1), rlit(R_T2), rlit(R_T3), rlit(R_T4),
-		rlit(R_T5), rlit(R_T6), rlit(R_T7), rlit(R_T8),
-		clb_mem_drain 
-); }
+atom_dbg_skip MipsAtom_(tape_enter) {
+	mac_load_word_imm(R_V0, u4_(TapeHostFrame_Loc)),
+	store_word(R_S0, R_V0, O_(TapeHostFrame,s0)),
+	store_word(R_S1, R_V0, O_(TapeHostFrame,s1)),
+	store_word(R_S2, R_V0, O_(TapeHostFrame,s2)),
+	store_word(R_S3, R_V0, O_(TapeHostFrame,s3)),
+	store_word(R_S4, R_V0, O_(TapeHostFrame,s4)),
+	store_word(R_S5, R_V0, O_(TapeHostFrame,s5)),
+	store_word(R_S6, R_V0, O_(TapeHostFrame,s6)),
+	store_word(R_S7, R_V0, O_(TapeHostFrame,s7)),
+	store_word(R_FP, R_V0, O_(TapeHostFrame,fp)),
+	store_word(R_SP, R_V0, O_(TapeHostFrame,sp)),
+	store_word(R_RA, R_V0, O_(TapeHostFrame,ra)),
+	add_ui(R_TapePtr, R_A0, 0),
+	load_upper_i(R_ScratchBase, u4_hi(Scratchpad_Loc)),
+	load_word(R_AtomJmp, R_TapePtr, 0),
+	add_ui_self(         R_TapePtr, S_(MipsAtom)),
+	jump_reg(R_AtomJmp), BdSlot_ nop,
+};
 
-/* Tape Runner (Static and Arg Clobbers) */
-FI_ void tape_run_a02_s07(Tape tape) { register U4* tape_ptr rgcc(R_TapePtr) = u4_r(tape.ptr); asm volatile(
-	asm_words(
-		  load_word(  R_AtomJmp, R_TapePtr, 0) /* Bootstrap the first jump */
-		, add_ui_self(R_TapePtr, S_(MipsAtom)) /* Advance tape */
-		, call_reg(   R_AtomJmp)               /* jalr $t9 */
-		, nop                                  /* Branch delay slot */
-	)
-	asm_rpins, r_use(tape_ptr)
-	asm_clobber: 
-		rlit(R_AT),
-		rlit(R_V0), rlit(R_V1), rlit(R_A0), rlit(R_A1), rlit(R_A2),
-		rlit(R_T0), rlit(R_T1), rlit(R_T2), rlit(R_T3), rlit(R_T4),
-		rlit(R_T5), rlit(R_T6), rlit(R_T7), rlit(R_T8),
-		rlit(R_S0), rlit(R_S1), rlit(R_S2), rlit(R_S3), rlit(R_S4),
-		rlit(R_S5), rlit(R_S6), rlit(R_S7),
-		clb_mem_drain 
-); }
+atom_dbg_skip MipsAtom_(tape_exit) {
+	mac_load_word_imm(R_V0, u4_(TapeHostFrame_Loc)),
+	load_word(R_S0, R_V0, O_(TapeHostFrame,s0)),
+	load_word(R_S1, R_V0, O_(TapeHostFrame,s1)),
+	load_word(R_S2, R_V0, O_(TapeHostFrame,s2)),
+	load_word(R_S3, R_V0, O_(TapeHostFrame,s3)),
+	load_word(R_S4, R_V0, O_(TapeHostFrame,s4)),
+	load_word(R_S5, R_V0, O_(TapeHostFrame,s5)),
+	load_word(R_S6, R_V0, O_(TapeHostFrame,s6)),
+	load_word(R_S7, R_V0, O_(TapeHostFrame,s7)),
+	load_word(R_RA, R_V0, O_(TapeHostFrame,ra)),
+	load_word(R_FP, R_V0, O_(TapeHostFrame,fp)),
+	load_word(R_SP, R_V0, O_(TapeHostFrame,sp)),
+	jump_reg(R_RA), BdSlot_ nop,
+};
+
+typedef void Proc_(TapeEntryFn)(MipsAtom* tape_ptr);
+
+FI_ void tape_run(Tape tape) { C_(TapeEntryFn*, tape_enter)(tape.ptr); }
 
 // Procedural authoring of tapes:
 typedef Relative_(FArena) Struct_(TapeBuilder) { U4 ptr; U4 capacity; U4 used; };
@@ -201,9 +248,13 @@ FI_ TapeBuilder tb_make(Slice mem) { return (TapeBuilder){ u4_(mem.ptr), mem.len
 FI_ void tb_emit(TapeBuilder* tb, MipsAtom* atom) { u4_r(tb->ptr)[tb->used] = u4_(atom); ++ tb->used; }
 FI_ void tb_data(TapeBuilder* tb, U4        data) { u4_r(tb->ptr)[tb->used] = u4_(data); ++ tb->used; }
 #define tb_emit_(atom)        tb_emit(& tb, atom)
-#define tb_data_(field, data) tb_data(& tb, u4_(data))
 
-FI_ void tb_emit_bundle(TapeBuilder_R tb, Slice_MipsAtom atoms) { mem_copy(u4_(tb->ptr), u4_(atoms.ptr), S_slice(atoms)); tb->used += atoms.len; }
+FI_ void tb_bind(TapeBuilder* tb, Slice data) { mem_copy(tb->ptr + tb->used * S_(MipsCode), u4_(data.ptr), data.len); tb->used += data.len / S_(MipsCode); }
+#define tb_bind_(tb,type,...) tb_bind(tb, (Slice){ (B1*)(& (type){__VA_ARGS__}), S_(type) }); static_assert(S_(type) % S_(MipsCode) == 0)
+
+// NOTE(Ed): Wip still ideating convention. Possibly will never use a composite.
+#define tb_emit_wbind_(tb,atom,...)       tb_emit(tb,atom); tb_bind_(tb,tmpl(Binds,atom),__VA_ARGS__)
+#define tb_emit_wbind2_(tb,atom,type,...) tb_emit(tb,atom); tb_bind_(tb,type,__VA_ARGS__)
 
 FI_ Tape tb_end  (TapeBuilder* tb) { tb_emit(tb,tape_exit); return (Tape){ C_(U4*,tb->ptr), tb->used }; }
 FI_ Tape tb_slice(TapeBuilder  tb) {                        return (Tape){ C_(U4*,tb.ptr),  tb.used }; }
@@ -220,15 +271,11 @@ FI_ void tb_scope_run_end(TapeBuilder* tb) { tb_emit(tb,tape_exit); tape_run(tb_
  * ---------------------------------------------------------------------------*/
 
 // The 'Yield' sequence for Tape Atoms (mac_yield).
-//   - mac_yield() is the safe default for atom-endings: 4 words, BD-slot of jr is mandatory nop.
-//   - mac_yield_load() + mac_yield_tail():
-//     - unconditional branch: mac_yield_load fills the branch's BD-slot (replaces a nop);
-//     - mac_yield_tail runs at the branch target (does NOT re-load R_AtomJmp).
 
 atom_dbg_skip MipsAtomComp_(ac_yield) {
-	load_word(R_AtomJmp, R_TapePtr, 0),
+	load_word(R_AtomJmp, R_TapePtr, 0), LdSlot_
 	add_ui_self(         R_TapePtr, S_(MipsCode)),
-	jump_reg( R_AtomJmp), nop,
+	jump_reg( R_AtomJmp), BdSlot_ nop,
 };
 
 atom_dbg_skip MipsAtomComp_(ac_yield_load) {
@@ -237,16 +284,13 @@ atom_dbg_skip MipsAtomComp_(ac_yield_load) {
 
 atom_dbg_skip MipsAtomComp_(ac_yield_tail) {
 	add_ui_self(R_TapePtr, S_(MipsCode)),
-	jump_reg(  R_AtomJmp), nop,
+	jump_reg( R_AtomJmp), BdSlot_ nop,
 };
+
 #pragma endregion Macro Atom Components
 
 #pragma region Atom Builder
 // This helps with runtime procedural authoring of mips atoms.
-
-typedef Struct_(FMipsAtom512) { U4 data[512]; U4 used; };
-
-// FArena Related
 typedef Relative_(FArena) Struct_(AtomBuilder) { U4 start; U4 capacity; U4 used; };
 
 // Usual way to resolve an atom after the bulder is done.
@@ -267,7 +311,6 @@ FI_ void tb_emit_atombuilder(TapeBuilder_R tb, AtomBuilder_R ab) { tb_emit(tb, a
 
 #pragma region Atom Arena
 // Just a dedicated FArena that is meant to mem_copy and return atom definitions made with MipsAtom_Proc_
-
 typedef Relative_(FArena) Struct_(AtomArena) { U4 start; U4 capacity; U4 used; };
 
 #define atomarena_unused_start(ab) ((ab).start + (ab).used)
@@ -284,37 +327,126 @@ FI_ MipsAtom* atomarena_push(AtomArena_R aa, Slice_MipsCode code) {
 	return C_(MipsAtom*, dest);
 }
 FI_ void atomarena_reset(AtomArena_R aa) { aa->used = 0; }
-#pragma region Atom Arena
+#pragma endregion Atom Arena
 
 #pragma region RegFile (Register File Allocator)
 // A specialized allocator utilized to help the user track which registers are bound to values
 // that must be preserved for the arena's bounds.
+// TODO(Ed): Technically we can do this at comp-time with the metaprogram, but we may have namespace conflicts.
+// Unless we follow a convention for #define <Scope_Prefix> or something per register allocation boundary.
 
-enum {
-	RegFileArena_Len,
-};
-typedef Enum_(U4, RegFileEntry) {
-	// TODO(Ed): Define RF_Field, each field is maped by index + bit pos.
-	// the index is the upper portion of a U4 and the bit pos in the lower pos.
+/* ABI reserves that are never handed out by alloc.
+ * R_AT is the assembler temporary (per the MIPS O32 ABI). 
+ * R_K0/K1 are kernel reserves.
+ * R_GP stays the host global pointer.
+ * R_SP/R_FP/R_RA are tape runtime carriers between tape_enter and tape_exit. */
+U4 const regfile_abi_mask =
+	(1u << R_0)  | (1u << R_AT) |
+	(1u << R_K0) | (1u << R_K1) |
+	(1u << R_GP) | (1u << R_SP) |
+	(1u << R_FP) | (1u << R_RA);
 
-	regfileentry_todo_,
-	// TODO(Ed): Is there a trick we can do with the current register enums to 
-	// just resolve an entry automatically when doing a pin?
+internal Reg const regfile_alloc_order[] = {
+	R_V0, R_V1,
+	R_A0, R_A1, R_A2, R_A3,
+	R_T0, R_T1, R_T2, R_T3, R_T4, R_T5, R_T6, R_T7,
+	R_S0, R_S1, R_S2, R_S3, R_S4, R_S5, R_S6, R_S7,
+	R_T8, R_T9,
 };
+
 typedef Struct_(RegFile) {
-	U1 GPR[RegFileArena_Len];
-	U1 GTE[RegFileArena_Len];
-	U1 GP[RegFileArena_Len];
+	A2_U2 GPR;
+	A2_U2 GTE;
 };
-
-void regfile_pin(U4 register) {
-
-	assert(false);
+#define regfile(pin_mask) {.GPR={u4_lo(pin_mask), u4_hi(pin_mask)} }
+FI_ void regfile_init(RegFile_R rf) {
+	/* pack the 32-bit ABI mask into the two U2s */
+	rf->GPR[0] = u4_lo(regfile_abi_mask);
+	rf->GPR[1] = u4_hi(regfile_abi_mask);
+	rf->GTE[0] = rf->GTE[1] = 0;
 }
+FI_ RegFile regfile_make(void) { RegFile rf; regfile_init(& rf); return rf; }
 
+typedef Struct_(RegFile_RInfo) {
+	U2_R section;
+	U2   mask;
+	B2   occupied;
+};
+FI_ RegFile_RInfo regfile_rinfo(A2_U2 file, Reg r_id) {
+	U2   s_id     = r_id >> 4;
+	U2_R section  = & file[s_id];
+	U2   mask     = u2_(1u << (r_id & 15));
+	B2   occupied = (section[0] & mask) != 0;
+	return (RegFile_RInfo){section, mask, occupied};
+}
+FI_ Reg regfile__alloc_helper(A2_U2 file, Reg r_id) {
+	Reg result = 0; RegFile_RInfo info = regfile_rinfo(file, r_id);
+	if (info.occupied == false) {
+		info.section[0] |= info.mask;
+		result           = r_id;
+	}
+	return result; 
+}
+I_ Reg regfile_alloc(RegFile_R rf) {
+	Reg allocated = 0;
+	for index_iter(U4, r_id, R_V0, <, R_T9) {
+		allocated = regfile__alloc_helper(rf->GPR, r_id);
+		Jmp_nZero_(allocated,resolved);
+	}
+	assert(allocated != 0);
+resolved: return allocated;
+}
+FI_ Reg regfile_pin(RegFile_R rf, Reg r_id) {
+	RegFile_RInfo info = regfile_rinfo(rf->GPR, r_id);
+	assert(info.occupied == false);
+	info.section[0] |= info.mask;
+	return r_id;
+}
+FI_ void regfile_pin_mask(RegFile_R rf, U4 mask) {
+	B4 occupied = u4_r(rf->GPR)[0] & mask;
+	assert(occupied == false);
+	u4_r(rf->GPR)[0] |= mask;
+}
+FI_ void regfile_free_mask(RegFile_R rf, U4 mask) {
+	if (regfile_abi_mask & mask) return;
+	u4_r(rf->GPR)[0] &= ~mask;
+}
+FI_ void regfile_free_reg(RegFile_R rf, Reg r_id) {
+	/* never free the ABI set */
+	if (regfile_abi_mask & (1u << r_id)) return;
+	RegFile_RInfo info = regfile_rinfo(rf->GPR, r_id);
+	info.section[0] &= ~info.mask;
+}
+FI_ void regfile_reset(RegFile_R rf) {
+	rf->GPR[0] = u4_lo(regfile_abi_mask);
+	rf->GPR[1] = u4_hi(regfile_abi_mask);
+}
+FI_ void regfile_reset_to_mask(RegFile_R rf, U4 mask) {
+	rf->GPR[0] = u4_lo(mask);
+	rf->GPR[1] = u4_hi(mask);
+}
 #pragma endregion RegFileArena (Register File Allocator)
 
 #pragma region Mips Atom Procs
+/* RegUse structs are a convention to organize register allocations for a mips atom procedure.
+	Unlike the usual enum-based declarations, they provide a namespaced scope and have view types via union declarations. */
+#define RegUse_(proc_name) (tmpl(RegUse,proc_name))
+
+	typedef Struct_(RegUse_example_atom_proc) {
+		Reg const ro_register; // Scratch base carrier.
+		Reg usual_modifiable;
+		union { Reg view_1, view_2, view_3; } t1;
+	};
+	internal MipsAtom* example_atom_proc(AtomArena_R aa, U2 offset, RegUse_example_atom_proc r) 
+	MipsAtom_Proc_(aa, {
+		add_si(r.usual_modifiable, r.ro_register, offset),
+		or_u(r.t1.view_1, r.ro_register, 0),
+		branch_lt_zero(r.t1.view_1, atom_offset(example_atom_proc, skip)), BdSlot_ nop,
+		li_s(r.t1.view_2, 100),
+	atom_label(skip)
+		add_si(r.t1.view_3, r.usual_modifiable, 10),
+		mac_yield(),
+	})
 
 #pragma endregion Mips Atom Procs
 

code/duffle/math.atom.c

@@ -1,55 +0,0 @@
-#ifdef INTELLISENSE_DIRECTIVES
-#	include "gen/macs.h"
-#	include "gen/offsets.h"
-#	include "math.h"
-#	include "lottes_tape.h"
-#endif
-
-ATOM_FILE_DEBUGGER_LINE_MARKER(math_atom_c);
-
-#pragma region MACs (Mips Atom Component)
-
-// FI_ Slice_MipsCode ac_load_imm
-
-FI_ Slice_MipsCode ac_load_v2s2(AtomBuilder_R ab, U4 rs_x, U4 rs_y, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_load_v2s2, ab, {
-	load_half( rs_x, r_base, offset + O_(V3_S2,x)),
-	load_half( rs_y, r_base, offset + O_(V3_S2,y)),
-})
-
-FI_ Slice_MipsCode ac_store_v2s2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_v2s2, ab, {
-	store_half(rt_x, base, offset + O_(V2_S2,x)),
-	store_half(rt_y, base, offset + O_(V2_S2,y)),
-})
-
-FI_ Slice_MipsCode ac_load_v3s4(AtomBuilder_R ab, U4 rs_x, U4 rs_y, U4 rs_z, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_load_v3s4, ab, {
-	load_word( rs_x, r_base, offset + O_(V3_S4,x)),
-	load_word( rs_y, r_base, offset + O_(V3_S4,y)),
-	load_word( rs_z, r_base, offset + O_(V3_S4,z)),
-})
-// TODO(Ed): we could generate these mappings properly..
-#define ac_load_p3s4 ac_load_v3s4
-#define mac_load_p3s4 mac_load_v3s4
-
-FI_ Slice_MipsCode ac_store_v3s4(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 rt_z, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_v3s4, ab, {
-	store_word(rt_x, base, offset + O_(V3_S4,x)),
-	store_word(rt_y, base, offset + O_(V3_S4,y)),
-	store_word(rt_z, base, offset + O_(V3_S4,z)),
-})
-// TODO(Ed): we could generate these mappings properly..
-#define ac_store_p3s4 ac_store_v3s4
-#define mac_store_p3s4 mac_store_v3s4
-
-FI_ Slice_MipsCode ac_sub_v3s4(AtomBuilder_R ab, U4 rds_x, U4 rds_y, U4 rds_z, U4 rt_x,  U4 rt_y,  U4 rt_z) atom_dbg_skip MipsAtomComp_Proc_(ac_sub_v3s4, ab, {
-	sub_s(rds_x, rds_x, rt_x),
-	sub_s(rds_y, rds_y, rt_y),
-	sub_s(rds_z, rds_z, rt_z),
-})
-
-FI_ Slice_MipsCode ac_store_rects2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 rt_width, U4 rt_height, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_rects2, ab, {
-	store_half(rt_x,      base, offset + O_(Rect_S2,x)),
-	store_half(rt_y,      base, offset + O_(Rect_S2,y)),
-	store_half(rt_width,  base, offset + O_(Rect_S2,width)),
-	store_half(rt_height, base, offset + O_(Rect_S2,height)),
-})
-
-#pragma endregion MACs (Mips Atom Component)

code/duffle/math.atom.h

@@ -0,0 +1,96 @@
+#ifdef INTELLISENSE_DIRECTIVES
+#	include "gen/macs.h"
+#	include "gen/offsets.h"
+#	include "math.h"
+#	include "lottes_tape.h"
+#endif
+
+ATOM_FILE_DEBUGGER_LINE_MARKER(math_atom_c);
+
+#define v3s4_R_0() ((Reg_(V3_S4)){R_0,R_0,R_0})
+
+typedef Struct_(Reg_V3_S2) { Reg x, y, z; };
+typedef Struct_(Reg_V3_S4) { Reg x, y, z; }; // Register allocation of a V3_S4
+typedef Struct_(Reg_P3_S4) { Reg x, y, z; }; // Register allocation of a P3_S4
+
+#pragma region MACs (Mips Atom Component)
+
+FI_ Slice_MipsCode ac_load_half_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_half(tx, base, offset + OA_(U2,[0])),
+	load_half(ty, base, offset + OA_(U2,[1])),
+	load_half(tz, base, offset + OA_(U2,[2])),
+})
+
+FI_ Slice_MipsCode ac_load_v3s2(AtomBuilder_R ab, Reg_(V3_S2) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_load_half_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_load_v2s2(AtomBuilder_R ab, U4 rs_x, U4 rs_y, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_half(rs_x, r_base, offset + O_(V3_S2,x)),
+	load_half(rs_y, r_base, offset + O_(V3_S2,y)),
+})
+
+FI_ Slice_MipsCode ac_store_v2s2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_half(rt_x, base, offset + O_(V2_S2,x)),
+	store_half(rt_y, base, offset + O_(V2_S2,y)),
+})
+
+FI_ Slice_MipsCode ac_load_word_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_word(tx, base, offset + OA_(U4,[0])),
+	load_word(ty, base, offset + OA_(U4,[1])),
+	load_word(tz, base, offset + OA_(U4,[2])),
+})
+
+FI_ Slice_MipsCode ac_load_v3s4(AtomBuilder_R ab, Reg_(V3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+FI_ Slice_MipsCode ac_load_p3s4(AtomBuilder_R ab, Reg_(P3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_store_half_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_half(tx, base, offset + OA_(U2,[0])),
+	store_half(ty, base, offset + OA_(U2,[1])),
+	store_half(tz, base, offset + OA_(U2,[2])),
+})
+
+FI_ Slice_MipsCode ac_store_v3s2(AtomBuilder_R ab, Reg_(V3_S2) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_store_half_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_store_word_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_word(tx, base, offset + OA_(U4,[0])),
+	store_word(ty, base, offset + OA_(U4,[1])),
+	store_word(tz, base, offset + OA_(U4,[2])),
+})
+
+FI_ Slice_MipsCode ac_store_v3s4(AtomBuilder_R ab, Reg_(V3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+FI_ Slice_MipsCode ac_store_p3s4(AtomBuilder_R ab, Reg_(P3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_add_si_v3s4(AtomBuilder_R ab, Reg rt_x,  Reg rt_y,  Reg rt_z, Reg base, U2 offset)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	add_si(rt_x, base, O_(V3_S4,x)),
+	add_si(rt_y, base, O_(V3_S4,y)),
+	add_si(rt_z, base, O_(V3_S4,z)),
+})
+
+FI_ Slice_MipsCode ac_sub_s_v3(AtomBuilder_R ab
+	, Reg dx, Reg dy, Reg dz
+	, Reg sx, Reg sy, Reg sz
+	, Reg tx, Reg ty, Reg tz
+) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	sub_s(dx, sx, tx),
+	sub_s(dy, sy, ty),
+	sub_s(dz, sz, tz),
+})
+
+FI_ Slice_MipsCode ac_sub_v3s4(AtomBuilder_R ab, Reg_(V3_S4) d, Reg_(V3_S4) s, Reg_(V3_S4) t) MipsAtomComp_ProcMap_(ab, mac_sub_s_v3(d.x, d.y, d.z, s.x, s.y, s.z, t.x, t.y, t.z))
+
+FI_ Slice_MipsCode ac_sub_s_v3_self(AtomBuilder_R ab, Reg ds_x, Reg ds_y, Reg ds_z, Reg tx,  Reg ty,  Reg tz) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	sub_s(ds_x, ds_x, tx),
+	sub_s(ds_y, ds_y, ty),
+	sub_s(ds_z, ds_z, tz),
+})
+
+FI_ Slice_MipsCode ac_sub_v3s4_self(AtomBuilder_R ab, Reg_(V3_S4) ds, Reg_(V3_S4) t) MipsAtomComp_ProcMap_(ab, mac_sub_s_v3_self(ds.x, ds.y, ds.z, t.x, t.y, t.z))
+
+FI_ Slice_MipsCode ac_store_rects2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 rt_width, U4 rt_height, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_half(rt_x,      base, offset + O_(Rect_S2,x)),
+	store_half(rt_y,      base, offset + O_(Rect_S2,y)),
+	store_half(rt_width,  base, offset + O_(Rect_S2,width)),
+	store_half(rt_height, base, offset + O_(Rect_S2,height)),
+})
+
+#pragma endregion MACs (Mips Atom Component)

code/duffle/math.h

@@ -24,6 +24,7 @@ enum {
 };
 
 typedef Array_(U1, 2);
+typedef Array_(U2, 2);
 typedef Array_(U4, 2);
 typedef Array_(S2, 2);
 typedef Array_(S2, 3);
@@ -46,6 +47,9 @@ typedef Struct_(V4_S4)      { S4 x; S4 y; S4 z; S4 w; };
 // typedef Struct_(P3_S4)      { S4 x; S4 y; S4 z; S4 w1; }; // RGA(Lengyel): Affine point with implicit weight one. Storage alias of V3_S4. Use P3_S4 when the value is a point.
 typedef V3_S4 P3_S4;
 
+typedef Struct_(R1_U2) { U2 p0; U2 p1; };
+typedef Struct_(R1_S2) { S2 p0; S2 p1; };
+
 typedef Struct_(R2_S2)      { V2_S2 p0; V2_S2 p1; }; // Range-2 Signed 2-Byte (16-bit)
 typedef Struct_(R2_S4)      { V2_S4 p0; V2_S4 p1; }; // Range-2 Signed 4-Byte (32-bit)
 
@@ -64,6 +68,8 @@ typedef Array_(V2_S2, 2);
 typedef Array_(V2_S2, 3);
 typedef Array_(V2_S2, 4);
 
+#define r1u2(p0,p1) (R1_U2){p0,p1}
+
 enum {
 	fp_one = (1 << 12),
 };
@@ -106,10 +112,10 @@ FI_ void mul_a3s4(A3_S4_R out_a, A3_S4 b) {
 	(out_a[0])[2] *= b[2];
 }
 
-FI_ void add_v3s4   (V3_S4_R out_a, V3_S4 b) {  add_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
-FI_ void add_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  add_a3s4_fp(pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void add_v3s4   (V3_S4_R out_a, V3_S4 b) {  add_a3s4   (C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
+FI_ void add_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  add_a3s4_fp(C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
 
-FI_ void sub_v3s4   (V3_S4_R out_a, V3_S4 b) {  sub_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
-FI_ void sub_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  sub_a3s4_fp(pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void sub_v3s4   (V3_S4_R out_a, V3_S4 b) {  sub_a3s4   (C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
+FI_ void sub_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  sub_a3s4_fp(C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
 
-FI_ void mul_v3s4   (V3_S4_R out_a, V3_S4 b) {  mul_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void mul_v3s4   (V3_S4_R out_a, V3_S4 b) {  mul_a3s4   (C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }

code/duffle/memory.h

@@ -73,7 +73,7 @@ typedef Slice_(B1);
 
 #define slice_iter(container, iter)     (T_((container).ptr) iter = (container).ptr; iter != slice_end(container); ++ iter)
 #define slice_arg_from_array(type, ...) & (tmpl(Slice,type)) { .ptr = Array_decl(type,__VA_ARGS__), .len = Array_len( Array_decl(type,__VA_ARGS__)) }
-#define slice_from_array(type, array)     (tmpl(Slice,type)) { .ptr = array, .len = S_(array) / S_(type) }
+#define slice_from_array(type, array)     (tmpl(Slice,type)) { .ptr = array, .len = Array_len(array) }
 
 FI_ void slice_zero_(Slice s) { slice_assert(s); mem_zero(u4_(s.ptr), s.len); }
 #define  slice_zero(s)        slice_zero_(slice_to_ut(s))
@@ -131,3 +131,15 @@ FI_ U4 farena_unused_start(FArena arena) { return arena.start + arena.used; }
 #define farena_push_array(arena, type, amount, ...) (tmpl(Slice,type)){ C_(type*, farena_push((arena), (amount), opt_(farena, .type_width=S_(type), __VA_ARGS__)).ptr), (amount) }
 
 #pragma endregion FArena
+
+#pragma region BIOS Scratchpad
+/* BIOS scratchpad location. 1 KB at 0x1F800000.
+ * TapeHostFrame occupies the final 44 bytes while tape code executes.
+ * Atom scratch is bounded by the TapeHostFrame_Loc declaration in lottes_tape.h. */
+enum {
+	Scratchpad_Loc = 0x1F800000,
+	Scratchpad_Len = 0x400,                             /* 1 KB */
+	Scratchpad_End = Scratchpad_Loc + Scratchpad_Len,   /* 0x1F800400 */
+};
+#define C_scratch(type) C_(type, Scratchpad_Loc)
+#pragma endregion BIOS Scratchpad

code/duffle/mips.atom.c

@@ -2,11 +2,50 @@
 #		include "gen/macs.h"
 #		include "gen/offsets.h"
 #	include "bios.h"
+#	include "mips.h"
 #	include "lottes_tape.h"
 #endif
 
 ATOM_FILE_DEBUGGER_LINE_MARKER(mips_atom_c);
 
+#pragma region MACs (Mips Atom Components)
+
+FI_ Slice_MipsCode ac_load_word_imm(AtomBuilder_R ab, Reg dst, U4 imm)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_upper_i(dst, u4_hi(imm)),
+	or_i_self(   dst, u4_lo(imm)),
+})
+
+FI_ Slice_MipsCode ac_shift_aright_v3_self(AtomBuilder_R ab, Reg dt_x, Reg dt_y, Reg dt_z, U2 shift_amount)
+MipsAtomComp_Proc_( ab, {
+	shift_aright(dt_x, dt_x, shift_amount),
+	shift_aright(dt_y, dt_y, shift_amount),
+	shift_aright(dt_z, dt_z, shift_amount),	
+})
+
+FI_ Slice_MipsCode ac_shift_aright_v3s4_self(AtomBuilder_R ab, Reg_(V3_S4) dt, U2 shift) MipsAtomComp_ProcMap_(ab, mac_shift_aright_v3_self(dt.x, dt.y, dt.z, shift))
+
+FI_ Slice_MipsCode ac_shift_aright_var_v3(AtomBuilder_R ab
+	, Reg rd_v0, Reg rd_v1, Reg rd_v2
+	, Reg rs_v0, Reg rs_v1, Reg rs_v2
+	, Reg r_shift)
+MipsAtomComp_Proc_(ab, {
+	shift_aright_var(rd_v0, rs_v0, r_shift),
+	shift_aright_var(rd_v1, rs_v1, r_shift),
+	shift_aright_var(rd_v2, rs_v2, r_shift),
+})
+
+FI_ Slice_MipsCode ac_shift_aright_var_v3_self(AtomBuilder_R ab, Reg rds_v0, Reg rds_v1, Reg rds_v2, Reg r_shift) 
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	shift_aright_var(rds_v0, rds_v0, r_shift),
+	shift_aright_var(rds_v1, rds_v1, r_shift),
+	shift_aright_var(rds_v2, rds_v2, r_shift),
+})
+
+FI_ Slice_MipsCode ac_shift_aright_var_v3s4_self(AtomBuilder_R ab, Reg_(V3_S4) ds, Reg shift) MipsAtomComp_ProcMap_(ab, mac_shift_aright_var_v3_self(ds.x, ds.y, ds.z, shift))
+
+#pragma endregion MACs (Mips Atom Components)
+
 #pragma region Baked Atoms
 
 /* Flushes the Instruction Cache (PSX A-function 0x44 via BIOS stub at 0xA0).
@@ -16,9 +55,15 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(mips_atom_c);
  *   3. $t0 = bios_table_addr           ; t0 = &BIOS A-function table
  *   4. jalr $t0, $ra                   ; call BIOS(flushcache)
  *      nop                             ; branch delay slot
- *   5. lw $ra, 4($sp);  jr $ra         ; restore & return
- *   6. sp += 8
+ *   5. lw $ra, 4($sp)
+ *   6. sp += 8                         ; load-delay
+ *   7. jr $ra
+ *      nop                             ; BD
  */
+
+#if 0
+// Note: Can't do this without having a way to do C-Runtime frame call from Tape ABI.
+// Don't support this without adjusting scratchpad to save tape frame in some way.
 internal MipsAtom_(mips_flush_icache) {
 	add_ui(R_SP, R_SP, -MipsStackAlignment), // sp -= 8
 	store_word(R_RA, R_SP, S_(U4)),           // sw  $ra,   4($sp) 
@@ -26,9 +71,10 @@ internal MipsAtom_(mips_flush_icache) {
 	add_ui(R_T0, R_0, bios_table_addr),           // addiu $t0, $0, 0xA0 
 	jump_link(R_T0, R_RA), nop,                   // jalr  $t0, $ra, BD slot
 	load_word(R_RA, R_SP, S_(U4)),            // lw   $ra, 4($sp) 
-	jump_reg(R_RA),                                 // jr   $ra 
-	add_ui(R_SP, R_SP, MipsStackAlignment),  // sp += 8 (BD) 
-	mac_yield(),
+	add_ui(R_SP, R_SP, MipsStackAlignment),  // sp += 8 (load-delay)
+	jump_reg(R_RA), nop,                          // jr   $ra, BD slot
+	// mac_yield(),
 };
+#endif
 
 #pragma endregion Baked Atoms

code/duffle/mips.h

@@ -252,29 +252,29 @@ enum {
 enum { _BitOffsets = 0
 /* Bit Offsets for MIPS Instruction Fields */
 
-	, OPCODE_SHIFT = 26
-	, RS_SHIFT     = 21
-	, RT_SHIFT     = 16
-	, RD_SHIFT     = 11
-	, SHAMT_SHIFT  = 6  /* Shift Amount */
-	, FC_SHIFT     = 0
+	, OPCODE_POS = 26
+	, RS_POS     = 21
+	, RT_POS     = 16
+	, RD_POS     = 11
+	, SHAMT_POS  = 6  /* Shift Amount: Offset Position */
+	, FC_POS     = 0
 
-/* Bit Masks to prevent overflow into adjacent fields */
+/* IMM_MASK is the 16-bit two's-complement truncation for the immediate field.
+ * It is NOT a range guard — it is load-bearing for negative branch offsets
+ * (the metaprogram emits raw signed offsets; the mask truncates them to the
+ * 16-bit representation the hardware expects). The static analysis
+ * `immediate_field_width` check validates ranges at build time. */
 
-	, OPCODE_MASK  = 0x3F
-	, REG_MASK     = 0x1F
-	, SHAMT_MASK   = 0x1F /* Shift Amount */
-	, FC_MASK      = 0x3F
 	, IMM_MASK     = 0xFFFF
 };
 
-#define enc_op(op)       (((op)    & OPCODE_MASK) << OPCODE_SHIFT)
-#define enc_rs(rs)       (((rs)    & REG_MASK)    << RS_SHIFT)
-#define enc_rt(rt)       (((rt)    & REG_MASK)    << RT_SHIFT)
-#define enc_rd(rd)       (((rd)    & REG_MASK)    << RD_SHIFT)
-#define enc_shamt(shamt) (((shamt) & SHAMT_MASK)  << SHAMT_SHIFT)
-#define enc_fc(fc)       (((fc)    & FC_MASK)     << FC_SHIFT)
-#define enc_imm(imm)     (((imm)   & IMM_MASK))
+#define enc_op(op)       ((op)    << OPCODE_POS)
+#define enc_rs(rs)       ((rs)    << RS_POS)
+#define enc_rt(rt)       ((rt)    << RT_POS)
+#define enc_rd(rd)       ((rd)    << RD_POS)
+#define enc_shamt(shamt) ((shamt) << SHAMT_POS)
+#define enc_fc(fc)       ((fc)    << FC_POS)
+#define enc_imm(imm)     ((imm) & IMM_MASK)
 
 /* MIPS R-Type Instruction Format (Register-to-Register) */
 #define enc_r(op, rs, rt, rd, shamt, fc) (enc_op(op) | enc_rs(rs) | enc_rt(rt) | enc_rd(rd) | enc_shamt(shamt) | enc_fc(fc))
@@ -318,7 +318,10 @@ enum { _BitOffsets = 0
 #define load_half(rt, base, off)   enc_i(op_lh,    (base), (rt), (off))
 #define load_byte_u(rt, base, off) enc_i(op_lbu,   (base), (rt), (off))
 #define load_half_u(rt, base, off) enc_i(op_lhu,   (base), (rt), (off))
+#define LdSlot_
+
 #define store_word(rt, base, off)  enc_i(op_sw,    (base), (rt), (off))
+
 #define add_ui(rt, rs, imm)        enc_i(op_addiu, (rs),   (rt), (imm))
 #define and_i(rt, rs, imm)         enc_i(op_andi,  (rs),   (rt), (imm))
 // #define and_si                     and_i
@@ -379,6 +382,9 @@ enum { _BitOffsets = 0
  */
 #define jump(off)                  enc_i(op_j,     R_0, R_0, (off))
 
+// Annotate an instruction as filling a branch-delay slot.
+#define BdSlot_
+
 /* jump_rel off — unconditional relative jump (the within-atom-safe `jump`).
  * MIPS I R3000A has no "branch always" opcode. The idiom for an unconditional relative jump is `beq $0, $0, off`. */
 #define jump_rel(off)              branch_equal(R_0, R_0, (off))
@@ -411,6 +417,7 @@ enum { _BitOffsets = 0
 #define div_s(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_div)
 #define div_u(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_divu)
 
+// TODO(Ed): Change convention of 'self' to ds for (destination is source)?
 #define add_u_self(rd_rs, rt)      add_u(rd_rs, rd_rs, rt)
 
 /* --- Arithmetic I-type (immediate) --- */
@@ -458,6 +465,7 @@ enum { _BitOffsets = 0
 
 // li_s — load signed 16-bit immediate into GPR (addiu rt, $0, imm — sign-extends).
 #define li_s(rt, imm)       add_ui((rt), R_0, (imm))
+// #define load_imm_s(rt, imm) add_ui((rt), R_0, (imm))
 
 #define load_imm_1w(rt, imm)    add_ui((rt),  R_0, (imm))
 #define load_imm_1w_s0(rt, imm) add_si((rt)), R_0, (imm))
@@ -578,6 +586,7 @@ enum { _BitOffsets = 0
 	, jump_link(rtmp_0, rret_addr)              \
 	, nop                                       \
 	, load_word(rret_addr, rstack_ptr, 4)       \
-	, jump_reg(rret_addr)                       \
 	, add_ui(rstack_ptr, rstack_ptr, MipsStackAlignment) \
+	, jump_reg(rret_addr)                       \
+	, nop                                       \
 ) asm_clobber: clbr_volatile_gprs )

code/duffle/pad.atom.c

@@ -11,18 +11,18 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(pad_atom_c);
 
 #pragma region MACs (Mips Atom Components)
 
-FI_ Slice_MipsCode ac_pad_set_centered_axes(AtomBuilder_R ab, U4 r_state, U4 r_scratch) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_set_centered_axes, ab, {
-    load_upper_i(r_scratch, (PadAxis_Centered_Word >> 16) & 0xFFFF),
-    or_i_self(   r_scratch,  PadAxis_Centered_Word        & 0xFFFF),
-    store_word(  r_scratch, r_state, O_(PadState,axes)),
+FI_ Slice_MipsCode ac_pad_set_centered_axes(AtomBuilder_R ab, Reg state, Reg scratch) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+		load_upper_i(scratch, (PadAxis_Centered >> 16) & 0xFFFF),
+    or_i_self(   scratch,  PadAxis_Centered        & 0xFFFF), // mac_load_word_imm(scratch, PadAxis_Centered),
+    store_word(  scratch, state, O_(PadState,axes)),
 })
 
-FI_ Slice_MipsCode ac_pad_set_id_byte(AtomBuilder_R ab, U1 r_state, U1 r_id, U1 id_value) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_set_id_byte, ab, {
+FI_ Slice_MipsCode ac_pad_set_id_byte(AtomBuilder_R ab, Reg state, Reg r_id, U1 id_value) atom_dbg_skip MipsAtomComp_Proc_(ab, {
     add_ui(    r_id, R_0, id_value),
-    store_byte(r_id, r_state, O_(PadState,id)),
+    store_byte(r_id, state, O_(PadState,id)),
 })
 
-FI_ Slice_MipsCode ac_pad_set_status(AtomBuilder_R ab, U4 r_tmp, U1 r_state, U4 pad_status) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_set_status, ab, {
+FI_ Slice_MipsCode ac_pad_set_status(AtomBuilder_R ab, U4 r_tmp, U1 r_state, U4 pad_status) atom_dbg_skip MipsAtomComp_Proc_(ab, {
     add_ui(    r_tmp, R_0, pad_status),
     store_word(r_tmp, r_state, O_(PadState,status)),
 })
@@ -30,7 +30,7 @@ FI_ Slice_MipsCode ac_pad_set_status(AtomBuilder_R ab, U4 r_tmp, U1 r_state, U4
 /* Invert r_buttons (active-low → active-high) and store to PadState.buttons.
  * r_buttons must already be loaded (the caller is responsible for filling the load-delay slot of
  * the preceding load_half_u with an instruction that doesn't read r_buttons). */
-FI_ Slice_MipsCode ac_pad_store_inverted_buttons(AtomBuilder_R ab, U1 r_buttons, U1 r_pad_state) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_store_inverted_buttons, ab, {
+FI_ Slice_MipsCode ac_pad_store_inverted_buttons(AtomBuilder_R ab, U1 r_buttons, U1 r_pad_state) atom_dbg_skip MipsAtomComp_Proc_(ab, {
     nor_u(     r_buttons, r_buttons, R_0),
     store_half(r_buttons, r_pad_state, O_(PadState,buttons)),
 })
@@ -54,12 +54,12 @@ FI_ Slice_MipsCode ac_pad_store_inverted_buttons(AtomBuilder_R ab, U1 r_buttons,
  *   byte_swap16(x) = (x >> 8) | (x << 8); nor(x, R_0) = ~x. store_half truncates to 16 bits so the upper-16 mask is implicit in the store.
  *
  * Register use (atom-local; no wave-context touched):
- *   R_T0 = raw base      (kept throughout; axes loads read raw[4..7] from R_T0)
- *   R_T1 = state base    (kept throughout; all stores go through R_T1)
- *   R_T2 = raw[0] status (alive across the disc/pending/id dispatch, then dead)
- *   R_T3 = raw[1] id     (alive across the id dispatch, then dead)
- *   R_T4 = scratch       (shifts, compares, immediate loads, store values)
- *   R_T5 = scratch       (parallel lui+ori for the 0x80808080 axes constant + byte-swap target)
+ *   R_T0 = raw base      : Kept throughout; axes loads read raw[4..7] from R_T0.
+ *   R_T1 = state base    : Kept throughout; all stores go through R_T1.
+ *   R_T2 = raw[0] status : Alive across the disc/pending/id dispatch, then dead.
+ *   R_T3 = raw[1] id     : Alive across the id dispatch, then dead.
+ *   R_T4 = scratch       : Shifts, compares, immediate loads, store values.
+ *   R_T5 = scratch       : Parallel lui + ori for the 0x80808080 axes constant + byte-swap target.
  */
 enum {
 	R_PadRaw    = R_T0 atom_reg atom_type(U1),
@@ -124,7 +124,8 @@ atom_label(id_dispatch) /* === Case 3-6: ID dispatch */
 	 * R_T5 is then "dead" — only consumed at the analog_pad range check downstream. */
 	mac_pad_set_status(R_T4, R_PadState, PadStatus_Digital),
 	load_half_u(       R_T4, R_PadRaw, O_(PadBiosRaw, buttons)), /* R_T4 = raw_buttons; */
-	load_upper_i(R_T5, PadAxis_Centered_Hi), or_i_self(R_T5, PadAxis_Centered_Lo), /* fills the buttons-load's delay slot (doesn't read R_T4) */
+	mac_load_word_imm( R_T5, PadAxis_Centered), /* fills the buttons-load's delay slot (doesn't read R_T4) */
+	// load_upper_i(R_T5, PadAxis_Centered_Hi), or_i_self(R_T5, PadAxis_Centered_Lo), 
 	mac_pad_store_inverted_buttons(R_T4, R_PadState),            /* R_T4 settled: nor + sh writes ~raw_buttons to state.buttons */
 	store_word(R_T5,    R_PadState, O_(PadState, axes)),         /* single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y) */
 	mac_pad_set_id_byte(R_PadState, R_T4, PadRawId_Digital),

code/duffle/pad.c

@@ -36,7 +36,7 @@ NI_ void pad_bios_init_start(PadBiosRaw* raw0, PadBiosRaw* raw1)
 	 *   $t2 = 0xB0 (BIOS B-table address) */
 	asm volatile(
 		asm_words(
-			or_u(    R_A2, R_A0, R_0),                 /* $a2 = $a1 = raw1 */
+			or_u(    R_A2, R_A1, R_0),                 /* $a2 = $a1 = raw1 */
 			add_ui(  R_A1, R_0, bios_pad_buffer_size), /* $a1 = 0x22 */
 			add_ui(  R_A3, R_0, bios_pad_buffer_size), /* $a3 = 0x22 */
 			add_ui(  R_T1, R_0, bios_init_pad_2),      /* $t1 = 0x12 */

code/duffle/pad.h

@@ -4,10 +4,7 @@
 #	include "math.h"
 #endif
 
-/* PSX button bit positions — 1:1 with PSX-SPX docs at docs/psx-spx/docs/controllersandmemorycards.md:405-421.
- * Wire is active-low (0 = pressed).
- * The decoder atom computes buttons = (~raw_buttons) & 0xFFFF; 
- * active-low-to-active-high inversion is applied bit-by-bit. */
+// PSX button bit positions: PSX-SPX docs/psx-spx/docs/controllersandmemorycards.md:405-421.
 typedef Enum_(U2, PadBtns) {
 	Bit_(Pad_Select,    0),
 	Bit_(Pad_L3,        1),
@@ -62,11 +59,7 @@ typedef Enum_(U4, PadStatus) {
 	PadStatus_Invalid,
 };
 
-/* Distinct from the game-facing PadStatus enum: PadRawStatus_Ok and PadRawStatus_Timeout are raw BIOS values;
- * PadStatus_* are game-facing post-decode states. PadUnknownId_Sentinel is written by the decoder 
- * when the controller id does not match any known controller type.
- * PadAxisCentered_Word: Four-byte 0x80 pattern used to clear / center 
- * four byte axes at PadState.left_x through PadState.right_y. */
+// Distinct from the game-facing PadStatus enum: PadRawStatus_Ok and PadRawStatus_Timeout are raw BIOS values
 typedef Enum_(U1, PadRawStatus) {
 	PadRawStatus_Ok      = 0x00,
 	PadRawStatus_Timeout = 0xFF,
@@ -83,7 +76,7 @@ typedef Enum_(U1, PadUnknownId) {
 typedef Enum_(U4, PadAxisCentered) {
 	PadAxis_Centered_Hi = 0x8080,
 	PadAxis_Centered_Lo = 0x8080,
-	PadAxis_Centered_Word = 0x80808080U,
+	PadAxis_Centered    = 0x80808080U,
 };
 typedef Enum_(U1, PadDeadZone) {
 	PadDeadZone_LowBound  = 0x70,  /* left_x <  LowBound  → active;  delta = 0x80 - left_x > 0 (rightward pull) */

code/duffle/psyq.h

@@ -104,7 +104,7 @@ void gte_matrix_set_translation(MT3_S2S4* mat) asm("SetTransMatrix");
 
 // Einheit, Metrication to unit vector. "Normalization", not Orthogonal "Normal, Normalis". Directionalization.
 // RGA(Lengyel): Normalize the bulk of a zero-weight direction. This is not finite-point unitization (which forces w=1).
-S4 normalize_v3s4(V3_S4* v0, V3_S4* v1) asm("VectorNormal");
+S4 psy_normalize_v3s4(V3_S4* v0, V3_S4* v1) asm("VectorNormal");
 
 // RGA(Lengyel): Apply the matrix expansion of a rigid transformation.
 // Motor antiproduct is equivalent for unitized points; LA form is what GTE consumes.

code/duffle/word_count.metadata.h

@@ -55,6 +55,7 @@ WORD_COUNT(gte_mv_to_ctrl_r,                 1)
 WORD_COUNT(gte_sw,                           1)
 WORD_COUNT(gte_cmdw_rtpt,                    1)
 WORD_COUNT(gte_cmdw_nclip,                   1)
+WORD_COUNT(gte_cmdw_op,                      1)
 WORD_COUNT(gte_avg_sort_z3,                  1)
 WORD_COUNT(gte_cmdw_sqr,                     1)
 WORD_COUNT(gte_cmdw_gpf,                     1)

code/hello_camera/gen/offsets.h

@@ -26,7 +26,7 @@ enum {
     atom_offset_end_low_exit_stick = _atom_offset_end_low_exit_stick,
 };
 
-// --- atom: pad_input_cam (40 words) ---
+// --- atom: pad_input_cam (39 words) ---
 
 #define _atom_offset_left_x_exit_left_x               3
 #define _atom_offset_right_x_exit_right_x             3
@@ -44,7 +44,7 @@ enum {
     atom_offset_circle_z_exit_circle_z = _atom_offset_circle_z_exit_circle_z,
 };
 
-// --- atom: cube_g4_face (76 words) ---
+// --- atom: cube_g4_face (73 words) ---
 
 #define _atom_offset_cull_cube_g4_face_exit           41
 #define _atom_offset_bounds_chk_cube_g4_face_exit     24
@@ -54,7 +54,7 @@ enum {
     atom_offset_bounds_chk_cube_g4_face_exit = _atom_offset_bounds_chk_cube_g4_face_exit,
 };
 
-// --- atom: floor_f3_face (58 words) ---
+// --- atom: floor_f3_face (56 words) ---
 
 #define _atom_offset_culling_floor_f3_face_exit       25
 #define _atom_offset_bounds_chk_floor_f3_face_exit    16

code/hello_camera/hello_camera.atom.c

@@ -10,7 +10,7 @@
 #	include "duffle/pad.h"
 #	include "duffle/word_count.metadata.h"
 #	include "duffle/psyq.h"
-#	include "duffle/math.atom.c"
+#	include "duffle/math.atom.h"
 #	include "duffle/mips.atom.c"
 #	include "duffle/gte.atom.c"
 #	include "duffle/gp.atom.c"
@@ -26,7 +26,7 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(hello_joypad_atom_c);
 #pragma region MACs (Mips Atom components)
 
 FI_ Slice_MipsCode ac_put_disp_env(AtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_disp_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	// Emits 5 GP0 commands for buffer 0 (display_area = (0,0,320,240)).
 	// Sequence per libpsyx PutDispEnv: DrawArea TL → DrawArea BR → Mask → DrawArea TL → DrawArea BR
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port),
@@ -37,7 +37,7 @@ MipsAtomComp_Proc_(ac_put_disp_env, ab, {
 })
 
 I_ Slice_MipsCode ac_put_draw_env(AtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_draw_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	/*
 	* ORIGIN: each code word corresponds to the EXACT value libpsyx's PutDrawEnv function would compute for the same DrawEnv settings.
 	* References:
@@ -92,443 +92,138 @@ MipsAtomComp_Proc_(ac_put_draw_env, ab, {
 #pragma endregion MACs
 
 #pragma region Atom Procs
-// Modular Atoms
-
-enum {
-	// TODO(Ed): We can resolve scratch at anytime its fixed to a specific address.
-	R_ResolveScratch = R_T4 atom_reg atom_type(U4*),
-#define R_ResolveScratch_Code R_T4_Code
-};
-typedef Struct_(Binds_ResolveLookAt) {
-	MT3_S2S4* look_at;
-	P3_S4*    eye;
-	P3_S4*    target;
-	V3_S4*    up_in;
-};
-
-/* ─── ResolveLookAtScratch — offset schema for the resolve_look_at bundle's */
-typedef Struct_(ResolveLookAtScratch) {
-	V3_S4 fwd;       /* offset  +0  (16 bytes — 4 S4 fields incl. internal pad) */
-	V3_S4 uz;        /* offset +16 (16 bytes) */
-	V3_S4 right;     /* offset +32 (16 bytes) */
-	V3_S4 ux;        /* offset +48 (16 bytes) */
-	V3_S4 up;        /* offset +64 (16 bytes) */
-	V3_S4 uy;        /* offset +80 (16 bytes) */
-	P3_S4 eye;       /* offset +96 (16 bytes; storage alias of V3_S4) */
-	P3_S4 target;    /* offset +112 (16 bytes; storage alias of V3_S4) */
-	V3_S4 up_in;     /* offset +128 (16 bytes) */
-};
 
+#pragma region resolve_look_at
 /* ─── resolve_look_at bundle chain atoms ──────────────────────────── */
 
-typedef Struct_(Binds_ResolveLookAtSub) {
-	P3_S4* target;  /* U4 (C-side P3_S4* — read by atom 0 directly; NOT a scratchpad address) */
-	P3_S4* eye;     /* U4 (C-side P3_S4* — read by atom 0 directly; staged into scratchpad by atom 0) */
-	V3_S4* up_in;   /* U4 (C-side V3_S4* — read by atom 0 directly; staged into scratchpad by atom 0) */
-	ResolveLookAtScratch* scratchpad;
+typedef AtomBundle_(resolve_look_at) { MipsAtom
+	*input_and_sub,
+	*normalize_fwd_uz,
+	*cross_to_right,
+	*normalize_right_ux,
+	*cross_to_up,
+	*normalize_up_uy,
+	*populate_mt3s4s2;
 };
 
-/* Atom 0 in the bundle: input_and_sub. Stages C-side inputs into the scratchpad and computes fwd = target - eye.
- * Staging work:
- *   * Stage eye.x/y/z   → scratch (for atom 6's translation column)
- *   * Stage up_in.x/y/z → scratch (for atom 2's outer-product operand)
- *   * Compute fwd = target - eye, store fwd.x/y/z → scratch+0/+4/+8 (for atom 1)
- * GPR codes (assigned by resolve_look_at_init):
- *   r_target_ptr : R_T0
- *   r_eye_ptr    : R_T1
- *   r_up_in_ptr  : R_T2
- *   r_scratch    : R_T4 (R_ResolveScratch; wave-context carrier)
- *   r_tmp0       : R_T3 (stage eye/up_in + load eye.y)
- *   r_tmp1       : R_T5 (stage eye/up_in + load eye.z)
- *   r_tmp2       : R_T6 (stage eye/up_in + load target.x)
- *   r_tmp3       : R_T7 (stage eye/up_in + load target.y)
- *   R_AT         : hardcoded (load eye.y / eye.z / target.z)
- *   R_V0         : hardcoded (load eye.z / target.z)
- * Pool cost: 8 GPRs + R_T4 (carrier) + R_AT + R_V0 (hardcoded) = 11 GPRs.
- */
-internal MipsAtom* resolve_look_at__input_and_sub_proc(AtomArena_R aa,	
-			// TODO(Ed): We can resolve scratch at anytime its fixed to a specific address.
-			U4 r_scratch
-	,	U4 r_target_ptr,U4 r_eye_ptr, U4 r_up_in_ptr
-	,	U4 r_tmp0,      U4 r_tmp1,    U4 r_tmp2, U4 r_tmp3
-) MipsAtom_Proc_(resolve_look_at__input_and_sub, aa, {
-	load_word(r_target_ptr, R_TapePtr, O_(Binds_ResolveLookAtSub,target)),
-	load_word(r_eye_ptr,    R_TapePtr, O_(Binds_ResolveLookAtSub,eye)),
-	load_word(r_up_in_ptr,  R_TapePtr, O_(Binds_ResolveLookAtSub,up_in)),
-	load_word(r_scratch,    R_TapePtr, O_(Binds_ResolveLookAtSub,scratchpad)),
-	add_ui_self(            R_TapePtr, S_(Binds_ResolveLookAtSub)),
+typedef Struct_(ResolveLookAtScratch) {
+	V3_S4 fwd;
+	V3_S4 uz;
+	V3_S4 right;
+	V3_S4 ux;
+	V3_S4 up;
+	V3_S4 uy;
+	P3_S4 eye;
+	P3_S4 target;
+	V3_S4 up_in;
+};
+
+typedef Struct_(Binds_ResolveLookAtSub) {
+	P3_S4* target;
+	P3_S4* eye;
+	V3_S4* up_in;
+};
+typedef Struct_(RegUse_resolve_look_at_input_and_sub) {
+	Reg target_ptr;
+	Reg eye_ptr;
+	Reg up_in_ptr;
+	union { Reg_(V3_S4) r012, up_in,  eye; };
+	union { Reg_(V3_S4) r345, target, fwd; };
+};
+/* Atom 0 in the bundle: input_and_sub. Stages C-side inputs into the scratchpad and computes fwd = target - eye. */
+internal MipsAtom* AtomBundleEntry_(resolve_look_at,input_and_sub)(AtomArena_R aa, RegUse_resolve_look_at_input_and_sub r)
+atom_info(atom_bind(Binds_ResolveLookAtSub)) MipsAtom_Proc_(aa, {
+	load_word(r.target_ptr, R_TapePtr, O_(Binds_ResolveLookAtSub,target)),
+	load_word(r.eye_ptr,    R_TapePtr, O_(Binds_ResolveLookAtSub,eye)),
+	load_word(r.up_in_ptr,  R_TapePtr, O_(Binds_ResolveLookAtSub,up_in)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_ResolveLookAtSub)),
+
+	/* Stage up_in.x/y/z into the scratchpad. R_ScratchBase = R_SP = 0x1F800000. */
+	mac_load_v3s4( r.up_in, r.up_in_ptr, 0), LdSlot_
+	mac_store_v3s4(r.up_in, R_ScratchBase, O_(ResolveLookAtScratch,up_in)),
 
 	// Stage eye.x/y/z into the scratchpad (atom 6 reads these for the translation column).
-	mac_load_p3s4( r_tmp0, r_tmp1, r_tmp2, r_eye_ptr, 0),
-	mac_store_p3s4(r_tmp0, r_tmp1, r_tmp2, r_scratch, O_(ResolveLookAtScratch,eye)),
-
-	/* Stage up_in.x/y/z into the scratchpad. */
-	mac_load_p3s4( r_tmp0, r_tmp1, r_tmp2, r_up_in_ptr, 0),
-	mac_store_p3s4(r_tmp0, r_tmp1, r_tmp2, r_scratch, O_(ResolveLookAtScratch,up_in)),
+	mac_load_v3s4( r.eye, r.eye_ptr, 0), LdSlot_
+	mac_store_v3s4(r.eye, R_ScratchBase, O_(ResolveLookAtScratch,eye)),
 
 	/* Compute fwd = target - eye. */
-	mac_load_p3s4(r_tmp0, r_tmp1, r_tmp2, r_target_ptr, 0),
-	mac_load_p3s4(r_tmp3, R_AT, R_V0, r_eye_ptr, 0),
-	mac_sub_v3s4(
-		r_tmp0, r_tmp1, r_tmp2,
-		r_tmp3, R_AT,   R_V0),
-	mac_store_v3s4(r_tmp0, r_tmp1, r_tmp2, r_scratch, O_(ResolveLookAtScratch,fwd)),
+	mac_load_v3s4(    r.target, r.target_ptr, 0), LdSlot_
+	mac_sub_v3s4_self(r.fwd, r.eye),
+	mac_store_v3s4(   r.fwd, R_ScratchBase, O_(ResolveLookAtScratch,fwd)),
 
 	mac_yield()
 })
 
-/* Atom 2: cross uz × up_in → right. */
-internal MipsAtom* resolve_look_at__cross_uz_up_in_to_right_proc(AtomArena_R aa, U4 r_scratch
-	,	U4 r_a, U4 r_b, U4 r_c /* load a.x/y/z; result out.x/y/z */
-	,	U4 r_d                 /* load b.x */
-	,	U4 r_f, U4 r_g, U4 r_h /* r_f = &right (out ptr), r_g = &uz, r_h = &up_in */
-) MipsAtom_Proc_(resolve_look_at__cross_uz_up_in_to_right, aa, {
-	/* FIX: build packed RT22+RT33 with proper sign extension. */
-	add_si(r_g, r_scratch, O_(ResolveLookAtScratch,uz)),    /* r_g = &uz */
-	add_si(r_h, r_scratch, O_(ResolveLookAtScratch,up_in)), /* r_h = &up_in */
-	add_si(r_f, r_scratch, O_(ResolveLookAtScratch,right)), /* r_f = &right (out) */
-	nop,
-
-	/* Load a (uz).x/y/z into r_a/r_b/r_c. */
-	load_word(r_a, r_g, O_(V3_S4,x)),
-	load_word(r_b, r_g, O_(V3_S4,y)),
-	load_word(r_c, r_g, O_(V3_S4,z)),
-	nop,
-
-	/* Load b (up_in).x/y/z into r_d + R_AT/R_V0 (R_AT/R_V0 are hardcoded scratch). */
-	load_word(r_d,  r_h, O_(V3_S4,x)),
-	load_word(R_AT, r_h, O_(V3_S4,y)),
-	load_word(R_V0, r_h, O_(V3_S4,z)),
-	nop,
-
-	/* Save the two RT control-register slots OP will clobber. We reuse
-	 * r_g/r_h (scratch pointers, no longer needed) as the save targets. */
-	gte_mv_from_ctrl_r(r_g, gte_cr_RT11),    /* r_g = C2 r0 (RT11|RT12) */
-	gte_mv_from_ctrl_r(r_h, gte_cr_RT22),    /* r_h = C2 r4 (RT22|RT33) */
-
-	/* Load uz.x/uz.y/uz.z into COP2 control registers.
-	 * OP reads D1 = RT11 from $0.low, D2 = RT22 from $2.high, D3 = RT33 from $4.high.
-	 * RT22 is in BOTH $2.high AND $4.low (shared bit position). OP reads from $2.high.
-	 * So set RT22 via ctc2 r_b, $2 (sets $2.high = a.y.high = RT22, $2.low = a.y.low = RT13).
-	 * Then set RT33 via ctc2 r_c, $4 (sets $4.high = a.z.high = RT33, $4.low = a.z.low).
-	 * The $2 and $4 writes don't clobber each other (separate registers).
-	 * The 2nd ctc2 DOES clobber $4.low (becomes a.z.low, NOT a.y.high), but since OP
-	 * reads RT22 from $2.high (which the 2nd ctc2 doesn't touch), D2 is still a.y.high.
-	 * This is libpsyx's OuterProduct12 convention EXACTLY. */
-	gte_mv_to_ctrl_r(r_b, gte_cr_RT13),    /* $2 = r_b = a.y. RT13=a.y.low, RT22=a.y.high. */
-	gte_mv_to_ctrl_r(r_c, gte_cr_RT22),    /* $4 = r_c = a.z. RT22=a.z.low, RT33=a.z.high. */
-
-	/* Load uz into the RT diagonal. */
-	gte_mv_to_ctrl_r(r_a, gte_cr_RT11),   /* D1 = RT11 = uz.x (low 16 of $0, sign-extended by OP). */
-	nop2,                                 /* CTC2 retirement (CPU→COP2 2-slot delay) */
-
-	/* Load up_in into IR (the second operand for OP). */
-	gte_mv_to_data_r(r_d,  C2_IR1),       /* IR1 = up_in.x */
-	gte_mv_to_data_r(R_AT, C2_IR2),       /* IR2 = up_in.y */
-	gte_mv_to_data_r(R_V0, C2_IR3),       /* IR3 = up_in.z */
-	nop2,                                 /* MTC2 retirement (CPU→COP2 2-slot delay) */
-
-	gte_cmdw_outer_product, /* OP: MAC1/2/3 = uz × up_in
-		*   MAC1 = IR3*D2 - IR2*D3 = up_in.z*uz.y.high - up_in.y*uz.z.high
-		*   MAC2 = IR1*D3 - IR3*D1 = up_in.x*uz.z.high - up_in.z*uz.x
-		*   MAC3 = IR2*D1 - IR1*D2 = up_in.y*uz.x - up_in.x*uz.y.high
-		* For up_in = (0, -fp_one, 0):
-		*   MAC1 = 0 - (-fp_one)*uz.z.high = fp_one*uz.z.high
-		*   MAC2 = 0 - 0 = 0
-		*   MAC3 = (-fp_one)*uz.x - 0 = -fp_one*uz.x */
-
-	/* Restore the RT slots we clobbered. */
-	gte_mv_to_ctrl_r(r_g, gte_cr_RT11),   /* restore C2 r0 (RT11|RT12) */
-	gte_mv_to_ctrl_r(r_h, gte_cr_RT22),   /* restore C2 r4 (RT22|RT33) */
-
-	/* mfc2 MAC1/2/3 → r_a/r_b/r_c (out.x/y/z). */
-	gte_mv_from_data_r(r_a, C2_MAC1),
-	gte_mv_from_data_r(r_b, C2_MAC2),
-	gte_mv_from_data_r(r_c, C2_MAC3),
-	nop,  /* MFC2 retirement */
-
-	/* Right-shift MAC by 12 to convert from GTE's S12.20 fixed-point scale back to libpsyx OuterProduct12 convention (S12.0, fp_one=4096=1<<12).
-	 * Without this, MAC values (~16M for unit-vector cross products) overflow the GTE's 16-bit IR registers when atom 3 normalizes via mtc2. */
-	shift_aright(r_a, r_a, 12),
-	shift_aright(r_b, r_b, 12),
-	shift_aright(r_c, r_c, 12),
-
-	/* Store out.x/y/z to r_f (out ptr = scratch+32). */
-	store_word(r_a, r_f, O_(V3_S4,x)),
-	store_word(r_b, r_f, O_(V3_S4,y)),
-	store_word(r_c, r_f, O_(V3_S4,z)),
-
-	mac_yield()
-})
-
-/* Atom 4: cross uz × ux → up. */
-internal MipsAtom* resolve_look_at__cross_uz_ux_to_up_proc(AtomArena_R aa,	U4 r_scratch
-	,	U4 r_a, U4 r_b, U4 r_c /* load a.x/y/z; result out.x/y/z */
-	,	U4 r_d                 /* load b.x */
-	,	U4 r_f, U4 r_g, U4 r_h /* r_f = &up (out ptr), r_g = &uz, r_h = &ux */
-) MipsAtom_Proc_(resolve_look_at__cross_uz_ux_to_up, aa, {
-	/* Compute the three scratch pointers from r_scratch. */
-	add_si(r_g, r_scratch, O_(ResolveLookAtScratch,uz)), /* r_g = &uz */
-	add_si(r_h, r_scratch, O_(ResolveLookAtScratch,ux)), /* r_h = &ux */
-	add_si(r_f, r_scratch, O_(ResolveLookAtScratch,up)), /* r_f = &up (out) */
-	nop,
-
-	/* Load a (uz).x/y/z into r_a/r_b/r_c. */
-	load_word(r_a, r_g, O_(V3_S4,x)),
-	load_word(r_b, r_g, O_(V3_S4,y)),
-	load_word(r_c, r_g, O_(V3_S4,z)),
-	nop,
-
-	/* Load b (ux).x/y/z into r_d + R_AT/R_V0. */
-	load_word(r_d,  r_h, O_(V3_S4,x)),
-	load_word(R_AT, r_h, O_(V3_S4,y)),
-	load_word(R_V0, r_h, O_(V3_S4,z)),
-	nop,
-
-	/* OP reads D1/D2/D3 from RT11/RT22/RT33 ($0/$2/$4), not V0/V1/V2.
-	 * Mirror atom 1: cfc2 RT save, ctc2 RT diagonal from uz, mtc2 IR from ux,
-	 * ctc2 RT restore. */
-
-	/* Save the two RT control-register slots OP will clobber (reusing
-	 * r_g/r_h — they're no longer needed as scratch pointers). */
-	gte_mv_from_ctrl_r(r_g, gte_cr_RT11),    /* r_g = C2 $0 (RT11|RT12) */
-	gte_mv_from_ctrl_r(r_h, gte_cr_RT22),    /* r_h = C2 $4 (RT22|RT33) */
-
-	/* Load uz into the RT diagonal — same packing as atom 1.
-	 * OP reads D1 = RT11 from $0.low, D2 = RT22 from $2.high, D3 = RT33 from $4.high.
-	 * RT22 is shared between $2.high and $4.low — the ctc2 sequence to $2 then $4
-	 * sets RT22 to uz.y.high (via $2), then to uz.z.low (via $4). OP reads
-	 * RT22 from $2.high which the second ctc2 doesn't touch, so D2 stays uz.y.high.
-	 * (This is libpsyx OuterProduct12 convention EXACTLY.) */
-	gte_mv_to_ctrl_r(r_b, gte_cr_RT13),    /* $2 = uz.y. RT13=uz.y.low, RT22=uz.y.high. */
-	gte_mv_to_ctrl_r(r_c, gte_cr_RT22),    /* $4 = uz.z. RT22=uz.z.low, RT33=uz.z.high. */
-	gte_mv_to_ctrl_r(r_a, gte_cr_RT11),   /* $0 = uz.x. RT11=uz.x. */
-	nop2,                                 /* CTC2 retirement (CPU→COP2 2-slot delay) */
-
-	/* Load ux into the IR registers (the second operand for OP). */
-	gte_mv_to_data_r(r_d,  C2_IR1),       /* IR1 = ux.x */
-	gte_mv_to_data_r(R_AT, C2_IR2),       /* IR2 = ux.y */
-	gte_mv_to_data_r(R_V0, C2_IR3),       /* IR3 = ux.z */
-	nop2,                                 /* MTC2 retirement (CPU→COP2 2-slot delay) */
-
-	gte_cmdw_outer_product,
-
-	/* Restore the RT slots we clobbered. */
-	gte_mv_to_ctrl_r(r_g, gte_cr_RT11),   /* restore C2 $0 (RT11|RT12) */
-	gte_mv_to_ctrl_r(r_h, gte_cr_RT22),   /* restore C2 $4 (RT22|RT33) */
-
-	gte_mv_from_data_r(r_a, C2_MAC1),
-	gte_mv_from_data_r(r_b, C2_MAC2),
-	gte_mv_from_data_r(r_c, C2_MAC3),
-	nop,
-	/* Right-shift MAC by 12 to convert from GTE's S12.20 scale back to libpsyx
-	 * OuterProduct12 convention (S12.0, fp_one=4096). See atom 1 for rationale. */
-	shift_aright(r_a, r_a, 12),
-	shift_aright(r_b, r_b, 12),
-	shift_aright(r_c, r_c, 12),
-	store_word(r_a, r_f, O_(V3_S4,x)),
-	store_word(r_b, r_f, O_(V3_S4,y)),
-	store_word(r_c, r_f, O_(V3_S4,z)),
-
-	mac_yield()
-})
-
-typedef Struct_(Binds_ResolveLookAtPopAndTrans) {
-	U4 look_at;  /* U4 (MT3_S2S4* — destination matrix address) */
+typedef Struct_(Binds_ResolveLookAt_PopulateMT3S4S2) {
+	MT3_S2S4* look_at;  /* MT3_S2S4* — destination matrix address */
 };
-/* Atom 6 in the bundle: write look_at->m[][] from ux/uy/uz, then compute the translation column t[] = R * (-eye).
+typedef Struct_(RegUse_resolve_look_at_populate_mt3s4s2) {
+	Reg         look_at;
+	Reg         eye;            /* matrix_vector phase: load -eye */
+	Reg_(V3_S4) row;            /* populate phase: load ux/uy/uz */
+	union { Reg r0, ux, vx; }; /* populate addr → matrix_vector v_x */
+	union { Reg r1, uy, vy; }; /* populate uy   → matrix_vector v_y */
+	union { Reg r2, uz, vz; }; /* populate uz   → matrix_vector v_z */
+};
+/* write look_at->m[][] from ux/uy/uz as packed S2 (populate),
+ * ctc2 RT chain into C2[0..4] (matrix_vector), MVMVA RT*(-eye)>>12, store off
+ * directly to look_at->t[] (trans_matrix).
  *
- * GPR codes (assigned by resolve_look_at_init):
- *   r_look_at   : MT3_S2S4* (popped from tape; output matrix destination)
- *   r_pux       : pointer to ux   (offset O_(ResolveLookAtScratch,ux))
- *   r_puy       : pointer to uy   (offset O_(ResolveLookAtScratch,uy))
- *   r_puz       : pointer to uz   (offset O_(ResolveLookAtScratch,uz))
- *   r_peye      : pointer to eye  (offset O_(ResolveLookAtScratch,eye))
- *   r_tmp0/1/2  : atom-local scratch (load + MVMVA + store temps)
- *
- * 4 pointer regs (r_pux/r_puy/r_puz/r_peye) are DEDICATED — they hold the scratch addresses for the entire body.
- * They are computed in-body via `add_si(r_px, r_scratch, O_(ResolveLookAtScratch, field))` so no tape-data pointer is needed.
- *
- * Struct layout (per duffle/math.h):
- *   MT3_S2S4 { A3x3_S2 m; A3_S4 t; }  →  m[][] is S2 packed (9 × 2 = 18 bytes at offset 0) 
- *                                        t[0/1/2] is S4     (3 × 4 = 12 bytes at offset 18)
- *
- * Translation column: GTE MVMVA with the world rotation matrix pre-set
- * (helper emits set_gte_world before the bundle, per the bundle design).
- * MVMVA computes R * pos (with cv=0/mx=0/sf=0/v=0); MAC1/2/3 = R * (-eye).
- * Pool cost: r_look_at (1) + r_scratch (R_T4 carrier) + 4 ptr regs + 3 tmp regs = 9 GPRs.
- */
-internal MipsAtom* resolve_look_at__populate_proc(AtomArena_R aa
-	,	U4 r_look_at
-	,	U4 r_scratch
-	,	U4 r_pux, U4 r_puy, U4 r_puz
-	,	U4 r_tmp0, U4 r_tmp1, U4 r_tmp2
-) MipsAtom_Proc_(resolve_look_at__populate, aa, {
-	/* Pop look_at* (the matrix output) — advance R_TapePtr by 4 bytes. */
-	load_word(r_look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	add_ui_self(         R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
-
-	/* Compute the 3 scratch pointers in their dedicated GPRs (eye isn't needed by 6a — 6b reads it). */
-	add_si(r_pux, r_scratch, O_(ResolveLookAtScratch,ux)),  /* r_pux = &ux */
-	add_si(r_puy, r_scratch, O_(ResolveLookAtScratch,uy)),  /* r_puy = &uy */
-	add_si(r_puz, r_scratch, O_(ResolveLookAtScratch,uz)),  /* r_puz = &uz */
-	nop,
-
-	/* ── m[0] = (S2)ux ── */
-	load_word(r_tmp0, r_pux, O_(V3_S4,x)),
-	load_word(r_tmp1, r_pux, O_(V3_S4,y)),
-	load_word(r_tmp2, r_pux, O_(V3_S4,z)),
-	nop,
-	store_half(r_tmp0, r_look_at, O_(MT3_S2S4,m[0][0])),
-	store_half(r_tmp1, r_look_at, O_(MT3_S2S4,m[0][1])),
-	store_half(r_tmp2, r_look_at, O_(MT3_S2S4,m[0][2])),
-
-	/* ── m[1] = (S2)uy ── */
-	load_word(r_tmp0, r_puy, O_(V3_S4,x)),
-	load_word(r_tmp1, r_puy, O_(V3_S4,y)),
-	load_word(r_tmp2, r_puy, O_(V3_S4,z)),
-	nop,
-	store_half(r_tmp0, r_look_at, O_(MT3_S2S4,m[1][0])),
-	store_half(r_tmp1, r_look_at, O_(MT3_S2S4,m[1][1])),
-	store_half(r_tmp2, r_look_at, O_(MT3_S2S4,m[1][2])),
-
-	/* ── m[2] = (S2)uz ── */
-	load_word(r_tmp0, r_puz, O_(V3_S4,x)),
-	load_word(r_tmp1, r_puz, O_(V3_S4,y)),
-	load_word(r_tmp2, r_puz, O_(V3_S4,z)),
-	nop,
-	store_half(r_tmp0, r_look_at, O_(MT3_S2S4,m[2][0])),
-	store_half(r_tmp1, r_look_at, O_(MT3_S2S4,m[2][1])),
-	store_half(r_tmp2, r_look_at, O_(MT3_S2S4,m[2][2])),
-
-	/* Zero t[0..2] — atom 6c writes the final values here. */
-	store_word(R_0, r_look_at, O_(MT3_S2S4,t[0])),
-	store_word(R_0, r_look_at, O_(MT3_S2S4,t[1])),
-	store_word(R_0, r_look_at, O_(MT3_S2S4,t[2])),
-
-	mac_yield()
-})
-
-/* Atom 6b in the bundle: matrix-vector product off = R * (-eye) >> 12.
- * Uses RTPS with V0 loaded from scratch via lwc2. The RT matrix is
- * pre-loaded by atom 6a.5 (resolve_look_at__load_rt).
- * Stores off to scratch+96 (overwriting the packed pos).
- *
- * GPR codes (assigned by resolve_look_at_init):
- *   r_scratch : R_ResolveScratch (R_T4) — scratch base
- *   r_peye    : pointer to eye (slot +96, reused as off destination)
- *   r_tmp0/1/2: -eye + GTE transfer scratch
- *
- * Pool cost: r_scratch (carrier) + 1 ptr reg + 3 tmp regs = 5 GPRs.
- */
-internal MipsAtom* resolve_look_at__matrix_vector_proc(AtomArena_R aa
-	,	U4 r_scratch
-	,	U4 r_peye
-	,	U4 r_look_at
-	,	U4 r_tmp0, U4 r_tmp1, U4 r_tmp2
-) MipsAtom_Proc_(resolve_look_at__matrix_vector, aa, {
-	/* === EXACT C11 ApplyMatrixLV replication ===
-	 * The C11 does:
+ * C11 ApplyMatrixLV semantics (gte.atom.c ac_apply_matrix_lv; libgte reference):
  *   1. ctc2 RT matrix (5 ctc2s to C2[0..4])
-	 *   2. lw v.x/y/z from memory
-	 *   3. S15 decomposition (negu + sra 15 + negu + andi 0x7FFF + negu)
-	 *   4. mtc2 HIGH bits to IR1/2/3, nop, MVMVA pass1 (sf=0, mx=0, v=3, cv=3)
-	 *   5. mfc2 MACs
-	 *   6. mtc2 LOW bits to IR1/2/3, nop, MVMVA pass2 (sf=1, mx=0, v=3, cv=3)
-	 *   7. mfc2 MACs
-	 *   8. Combine: (pass1 << 3) + pass2
-	 *
-	 * For S16-fitting pos (|pos| < 32768), pos >> 15 = 0, so pass1 = 0.
-	 * The combine simplifies: result = 0 + pass2 = pass2.
-	 * So we skip the S15 decomposition and just do pass 2 directly.
-	 * We still use v=3 (IR input) and mx=0 (RT matrix) like the C11. */
-
-	/* Pop look_at* from tape. */
-	load_word(r_look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	add_ui_self(         R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
-
-	/* r_peye = &eye (slot +96, reused as off destination). */
-	add_si(r_peye, r_scratch, O_(ResolveLookAtScratch,eye)),
-	nop,
-
-	/* === Load RT matrix from look_at into C2[0..4] via ctc2 ===
-	 * Exact s  ame sequence as set_gte_mt3s2s4 / C11's ApplyMatrixLV. */
-	load_word(  r_tmp0, r_look_at,  0), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT11),
-	load_word(  r_tmp0, r_look_at,  4), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT12),
-	load_word(  r_tmp0, r_look_at,  8), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT13),
-	load_word(  r_tmp0, r_look_at, 12), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT21),
-	load_half_u(r_tmp0, r_look_at, 16), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT22),
-	nop2,  /* CTC2 retirement (2 slots × 5 ctc2s) */
-
-	/* Load pos = -eye after the matrix load releases r_tmp0. */
-	load_word(r_tmp0, r_peye, O_(P3_S4,x)),
-	load_word(r_tmp1, r_peye, O_(P3_S4,y)),
-	load_word(r_tmp2, r_peye, O_(P3_S4,z)),
-	nop,
-	sub_u(r_tmp0, R_0, r_tmp0),  /* pos.x = -eye.x */
-	sub_u(r_tmp1, R_0, r_tmp1),
-	sub_u(r_tmp2, R_0, r_tmp2),
-
-	/* === mtc2 pos (as S16) to IR1/2/3 ===
-	 * The GTE takes low 16 bits. pos fits in S16. For negative pos, the
-	 * 32-bit sign-extended value's low 16 bits = correct S16. */
-	/* Mask pos to 16 bits to be safe. For S16-fitting pos, pos & 0xFFFF
-	 * gives the correct S16 value (sign bit preserved). */
-	/* r_tmp0/1/2 already have pos values. */
-	gte_mv_to_data_r(r_tmp0, C2_IR1),
-	gte_mv_to_data_r(r_tmp1, C2_IR2),
-	gte_mv_to_data_r(r_tmp2, C2_IR3),
-	nop2,  /* MTC2 retirement (2 slots) */
-
-	/* === MVMVA pass 2 EXACT C11 command: 0x4A49E012 ===
-	 * sf=1, mx=0 (RT), v=3 (IR), cv=3. Reads RT × IR >> 12. */
-	gte_cmdw_mvmva_c11_pass2_exact,
-	nop,  /* GTE interlock */
-
-	/* === mfc2 MAC1/2/3 → r_tmp0/1/2 === */
-	gte_mv_from_data_r(r_tmp0, C2_MAC1),
-	gte_mv_from_data_r(r_tmp1, C2_MAC2),
-	gte_mv_from_data_r(r_tmp2, C2_MAC3),
-	nop,
-
-	/* === Store off → scratch+96 (overwriting pos) === */
-	store_word(r_tmp0, r_peye, O_(V3_S4,x)),
-	store_word(r_tmp1, r_peye, O_(V3_S4,y)),
-	store_word(r_tmp2, r_peye, O_(V3_S4,z)),
-
-	mac_yield()
-})
-
-/* Atom 6c in the bundle: copy scratch+96 (off, written by atom 6b) → look_at->t[].
- * Uses mac_trans_matrix component (m->t = v, libgte TransMatrix semantics = struct copy).
- *
- * GPR codes (assigned by resolve_look_at_init):
- *   r_look_at : MT3_S2S4* (popped from tape; output matrix destination)
- *   r_scratch : R_ResolveScratch (R_T4) — scratch base
- *   r_off_ptr : pointer to off (= &scratch.eye, reused slot)
- *   r_tmp0    : transfer reg for mac_trans_matrix
- *
- * Pool cost: r_look_at (1) + r_scratch (carrier) + r_off_ptr + 1 clobber = 4 GPRs.
+ *   2. lw -eye from memory
+ *   3. S15 decomposition (eliminated here — the fused body takes the >>12 path
+ *      directly via mtc2 IR + MVMVA pass2, matching the libgte canonical output)
+ *   4. mtc2 to IR1/2/3, nop2, MVMVA pass2 (sf=1, mx=0, v=3, cv=3)
+ *   5. mfc2 MACs → off
+ *   6. store off to look_at->t[] (skip scratch.eye intermediate)
  */
-I_ MipsAtom* resolve_look_at__trans_matrix_proc(AtomArena_R aa
-	,	U4 r_look_at
-	,	U4 r_scratch
-	,	U4 r_off_ptr
-	,	U4 r_tmp0
-) MipsAtom_Proc_(resolve_look_at__trans_matrix, aa, {
-	/* Pop look_at* from tape. */
-	load_word(r_look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	add_ui_self(         R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
+internal MipsAtom* AtomBundleEntry_(resolve_look_at,populate_mt3s4s2)(AtomArena_R aa, RegUse_resolve_look_at_populate_mt3s4s2 r)
+atom_info(atom_bind(Binds_ResolveLookAt_PopulateMT3S4S2)) MipsAtom_Proc_(aa, {
+	/* --- Tape pop: look_at pointer --- */
+	load_word(r.look_at, R_TapePtr, O_(Binds_ResolveLookAt_PopulateMT3S4S2,look_at)),
+	LdSlot_ add_ui_self( R_TapePtr, S_(Binds_ResolveLookAt_PopulateMT3S4S2)),
 
-	/* r_off_ptr = &off (= &scratch.eye since atom 6b overwrote eye with off). */
-	add_si(r_off_ptr, r_scratch, O_(ResolveLookAtScratch,eye)),
-	nop,
+	add_si(r.ux,  R_ScratchBase, O_(ResolveLookAtScratch, ux)), LdSlot_
+	add_si(r.uy,  R_ScratchBase, O_(ResolveLookAtScratch, uy)),
+	add_si(r.uz,  R_ScratchBase, O_(ResolveLookAtScratch, uz)),
+	add_si(r.eye, R_ScratchBase, O_(ResolveLookAtScratch, eye)),
 
-	/* Copy off → look_at.t[] (mac_trans_matrix: m->t = v). */
-	mac_trans_matrix(r_look_at, r_off_ptr, r_tmp0),
+	/* write look_at->m[][] from ux/uy/uz as packed S2 */
+	mac_load_v3s4(r.row, r.ux, 0), LdSlot_ mac_store_v3s2(r.row, r.look_at, O_(MT3_S2S4, m[0])),
+	mac_load_v3s4(r.row, r.uy, 0), LdSlot_ mac_store_v3s2(r.row, r.look_at, O_(MT3_S2S4, m[1])),
+	mac_load_v3s4(r.row, r.uz, 0), LdSlot_ mac_store_v3s2(r.row, r.look_at, O_(MT3_S2S4, m[2])),
 
-	mac_yield()
+	/* ctc2 RT chain + MVMVA RT * (-eye) >> 12 */
+	/*   C2[0] = (RT12<<16)|RT11  ← ctc2 RT11 from m[0][0..1]
+	 *   C2[1] = (RT21<<16)|RT13  ← ctc2 RT12 from m[0][2..3]
+	 *   C2[2] = (RT23<<16)|RT22  ← ctc2 RT13 from m[1][1..2]
+	 *   C2[3] = (RT32<<16)|RT31  ← ctc2 RT21 from m[2][0..1]
+	 *   C2[4] = (RT33<<16)|junk  ← ctc2 RT22 from m[2][2] (half) */
+	load_word(  r.vx, r.look_at, O_(MT3_S2S4, m[0][0])), /* RT11|RT12 */ LdSlot_
+	load_word(  r.vy, r.look_at, O_(MT3_S2S4, m[0][2])), /* RT13|RT21 */ LdSlot_ gte_mv_to_ctrl_r(r.vx, gte_cr_RT11),
+	load_word(  r.vz, r.look_at, O_(MT3_S2S4, m[1][1])), /* RT22|RT23 */ LdSlot_ gte_mv_to_ctrl_r(r.vy, gte_cr_RT12),
+	load_word(  r.vx, r.look_at, O_(MT3_S2S4, m[2][0])), /* RT31|RT32 */ LdSlot_ gte_mv_to_ctrl_r(r.vz, gte_cr_RT13),
+	load_half_u(r.vy, r.look_at, O_(MT3_S2S4, m[2][2])), /* RT33 */      LdSlot_ gte_mv_to_ctrl_r(r.vx, gte_cr_RT21),
+
+	GteDelay_ mac_load_word_v3(r.vx, r.vy, r.vz, r.eye, 0), LdSlot_ 
+	mac_sub_s_v3(r.vx, r.vy, r.vz, R_0, R_0, R_0, r.vx, r.vy, r.vz),
+
+	gte_mv_to_data_r(r.vx, C2_IR1),
+	gte_mv_to_data_r(r.vy, C2_IR2),
+	gte_mv_to_data_r(r.vz, C2_IR3),
+	GteDelay_ nop2,
+
+	/* MVMVA pass 2 — C11 ApplyMatrixLV command. sf=1, mx=0 (RT), v=3 (IR), cv=3. Reads RT × IR >> 12. */
+	gte_cmdw_mvmva_c11_pass2,                        GteDelay_ load_word(R_AtomJmp, R_TapePtr, 0),            // ac_yield: word 1
+	mac_gte_mv_from_data_r_mac123(r.vx, r.vy, r.vz), GteDelay_ add_ui_self(         R_TapePtr, S_(MipsCode)), // ac_yield: word 2
+
+	/* store off directly to look_at->t[] (skip scratch.eye intermediate) */
+	mac_store_word_v3(r.vx, r.vy, r.vz, r.look_at, O_(MT3_S2S4, t)),
+
+	jump_reg(R_AtomJmp), BdSlot_ nop, // ac_yield: word 3-4
 })
+#pragma endregion resolve_look_at
 
 #pragma endregion Atom Procs
 
@@ -547,7 +242,7 @@ internal MipsAtom_(screen_env_init) atom_info(atom_phase(screen_init)
 ) {
 	/* display[0] = (0, 0, 320, 240); rest of struct zeroed. */
 	add_ui(R_ScreenX, R_0, ScreenRes_X), add_ui(R_ScreenY, R_0, ScreenRes_Y),
-	mac_store_v2s2(R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DisplayEnv,display_area.width) + OA_(DoubleBuffer,display,0)),
+	mac_store_v2s2(R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DisplayEnv,display_area.width) + O_(DoubleBuffer,display[0])),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,display_area) + O_(DoubleBuffer,display[0])),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,screen)       + O_(DoubleBuffer,display[0])),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,vinterlace)   + O_(DoubleBuffer,display[0])),
@@ -593,23 +288,6 @@ internal MipsAtom_(screen_env_init) atom_info(atom_phase(screen_init)
 	mac_yield(),
 };
 
-/* gp_screen_init's GPR setup. Tests the mixed user-pinning + auto-reg pattern:
- *   - R_IO_BaseAddr = R_T4 (user-pinned via atom_reg; pre-existing)
- *   - R_GP1_Offset  = R_T2 (user-pinned via atom_reg; NEW -- for GPIO_PORT1_OFFSET)
- *   - R_ScreenX     = R_T5 (user-pinned via atom_reg; used as a transfer and GTE setup reg)
- *   - R_GpTmp       = auto-allocated by the lua pass and used for several GPU transfers;
- *                    the C preprocessor resolves it to the chosen free pool GPR.
- *
- * For gp_screen_init, the auto-reg pool exclusions are:
- *   user_pinned (from the corpus register_alias_registry) : R_T0..R_T7 (all 8 user-pinned across hello_camera.atom.c)
- *   body-parsed physical registers                         : aliases resolve through the registry;
- *                                                           the body uses R_ScreenX, not raw R_T5
- *   source_pool after both subtractions                   : {R_V0, R_V1} only
- *   R_GpTmp gets R_V0 (the first-fit choice). Its repeated GPU-transfer use proves that the
- *   auto-reg allocation is active while the R_ScreenX references prove the pinned alias is used.
- *   R_TapePtr (R_T9), R_AtomJmp (R_T8), R_AT are excluded from the POOL by construction in
- *   passes/auto_reg.lua -- see the "obvious exclusions" comment block at the top of that file.
- */
 enum {
 	R_IO_BaseAddr = R_T4 atom_reg, /* Caller-pinned: IO_BASE_ADDR = 0x1F800000 */
 	R_GP1_Offset  = R_T2 atom_reg, /* Caller-pinned: GPIO_PORT1_OFFSET = 0x10 */
@@ -660,15 +338,15 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 	load_word(R_PadStateT5, R_TapePtr, O_(Binds_PadApplyInput,state)),
 	load_word(R_CubeRot,    R_TapePtr, O_(Binds_PadApplyInput,cube_rot)),
 	load_word(R_FloorRot,   R_TapePtr, O_(Binds_PadApplyInput,floor_rot)),
-	add_ui_self(            R_TapePtr, S_(Binds_PadApplyInput)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_PadApplyInput)),
 
 	/* Load pad[0].buttons into R_T0. */
-	load_word(R_T0, R_PadStateT5, O_(PadState,buttons)), nop,
+	load_word(R_T0, R_PadStateT5, O_(PadState,buttons)), LdSlot_ nop,
 	// Note(Ed): Potential op with delay slot?
 
 	/* D-pad Left: cube_rot.y += 30, floor_rot.y += 5.  */
-	and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(dpad_left, exit_dpad_left)),
-		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)),   /* BD-slot */
+	and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(dpad_left, exit_dpad_left)), BdSlot_
+		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)), LdSlot_
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, 30),
 		add_si(    R_T3, R_T3, 5),
@@ -677,8 +355,8 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 	atom_label(exit_dpad_left)
 
 	/* D-pad Right: cube_rot.y -= 30, floor_rot.y -= 5. */
-	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(dpad_right, exit_dpad_right)),
-		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)),   /* BD-slot */
+	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(dpad_right, exit_dpad_right)), BdSlot_
+		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)), LdSlot_
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, -30),
 		add_si(    R_T3, R_T3, -5),
@@ -688,7 +366,7 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 
 	/* Analog left-stick X: dead zone 0x70..0x90.
 	 * Cube delta = (0x80 - left_x) >> 2; floor delta = (0x80 - left_x) >> 5. */
-	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)),
+	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)), LdSlot_ //?
 
 	/* Dead-zone check: skip analog if left_x in [0x70, 0x90] inclusive. Outside dead zone on LOW side: left_x < 0x70 (strictly).
 	 * set_lt_u(R_T4, R_T3, R_T4=0x70) → R_T4 = (left_x < 0x70) ? 1 : 0. */
@@ -697,14 +375,14 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 
 atom_label(dead_check_upper)
 	/* left_x >= 0x70 → check upper bound. */
-	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)), /* reload */
+	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)), /* reload */ LdSlot_ //? 
 	add_ui(     R_T4, R_0, PadDeadZone_HighBound),
 
 	/* R_T4 = (0x90 < left_x) ? 1 : 0 → (left_x > 0x90) ? 1 : 0 */
-	set_lt_u(R_T4, R_T4, R_T3), branch_ne(R_T4, R_0, atom_offset(dead_zone_high_check, dead_high_active)),
+	set_lt_u(R_T4, R_T4, R_T3), branch_ne(R_T4, R_0, atom_offset(dead_zone_high_check, dead_high_active)), BdSlot_
 	add_ui(  R_T4, R_0, PadDeadZone_Center), /* BD-slot: pre-load 0x80 for dead_high_active */
 	jump_rel(atom_offset(dead_zone_skip, exit_stick)),
-		mac_yield_load(),
+		BdSlot_ mac_yield_load(), LdSlot_
 
 atom_label(dead_low_active)
 	/* R_T3 = left_x (from line 632 lbu; not clobbered between dead_zone_low_check branch + its BD-slot `add_ui R_T4, 0x80`).
@@ -715,18 +393,18 @@ atom_label(dead_low_active)
 
 	/* R_T4 = cube_delta */
 	shift_aright(R_T4, R_T3, 2),
-	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), nop,
+	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), LdSlot_ nop,
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_CubeRot, O_(V3_S2,y)),
 	/* R_T4 = floor_delta — moved into the load-delay slot of the floor load below (fills the 1-instruction gap;
 	 * doesn't read R_T0; R_T4 settles by the subsequent add_u). */
-	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)),
+	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)), LdSlot_
 	shift_aright(R_T4, R_T3, 5),
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_FloorRot, O_(V3_S2,y)),
 
 	jump_rel(atom_offset(end_low, exit_stick)),
-		mac_yield_load(),
+		BdSlot_ mac_yield_load(), LdSlot_
 
 atom_label(dead_high_active)
 	/* R_T3 = left_x (from line 641 lbu in dead_check_upper; not clobbered between dead_zone_high_check branch + its BD-slot `add_ui R_T4, 0x80`).
@@ -736,18 +414,18 @@ atom_label(dead_high_active)
 	/* delta = 0x80 - left_x (signed negative). */
 
 	shift_aright(R_T4, R_T3, 2),                      /* R_T4 = cube_delta (signed) */
-	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), nop,
+	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), LdSlot_ nop,
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_CubeRot, O_(V3_S2,y)),
 
 	/* R_T4 = floor_delta (signed) — moved into the load-delay slot of the floor load below. */
-	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)),
+	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)), LdSlot_
 	shift_aright(R_T4, R_T3, 5),
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_FloorRot, O_(V3_S2,y)),
 
 atom_label(no_jump_fallthrough)
-	mac_yield_load(),
+	mac_yield_load(), LdSlot_
 
 atom_label(exit_stick)
 	/* NOT mac_yield() — R_AtomJmp was already loaded in the BD-slot of the dead-zone/exit branch. */
@@ -769,42 +447,45 @@ internal MipsAtom_(pad_input_cam) atom_info(atom_bind(Binds_PadInputCam)
 	/* Bind pop: state → R_CamPadState (R_T5), cam → R_Cam (R_T4), advance R_TapePtr by 8. */
 	load_word(R_CamPadState, R_TapePtr, O_(Binds_PadInputCam,state)),
 	load_word(R_Cam,         R_TapePtr, O_(Binds_PadInputCam,cam)),
-	add_ui_self(             R_TapePtr, S_(Binds_PadInputCam)),
+	LdSlot_ add_ui_self(     R_TapePtr, S_(Binds_PadInputCam)),
 
 	/* Load pad[0].buttons into R_T0; nop fills the load-delay slot. */
-	load_word(R_T0, R_CamPadState, O_(PadState,buttons)),
-	load_word(R_T1, R_Cam, O_(Camera,pos.x)), // BD-Slot.
+	load_word(R_T0, R_CamPadState, O_(PadState,buttons)), LdSlot_
+	load_word(R_T1, R_Cam, O_(Camera,pos.x)),
 
 	// D-pad Left → cam.pos.x -= 50.  and_i fulfills BD-slot for load on R_Cam.
-	and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(left_x, exit_left_x)), mac_yield_load(),
+	LdSlot_ and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(left_x, exit_left_x)), BdSlot_ nop,
 		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.x)), 
 	atom_label(exit_left_x)
+
 	/* D-pad Right → cam.pos.x += 50. Reuses R_T1 from Left. */
-	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(right_x, exit_right_x)), nop,
+	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(right_x, exit_right_x)), BdSlot_ nop,
 		add_si(R_T1, R_T1,  50), store_word(R_T1, R_Cam, O_(Camera,pos.x)),
 	atom_label(exit_right_x)
 
 	/* D-pad Up → cam.pos.y -= 50. Load pos.y BEFORE the andi. */
-	load_word(R_T1, R_Cam, O_(Camera,pos.y)),
-	and_i(R_T3, R_T0, Pad_Up), branch_le_zero(R_T3, atom_offset(up_y, exit_up_y)), nop,
+	load_word(R_T1, R_Cam, O_(Camera,pos.y)), LdSlot_ 
+	and_i(R_T3, R_T0, Pad_Up), branch_le_zero(R_T3, atom_offset(up_y, exit_up_y)), BdSlot_ nop,
 		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.y)),
 	atom_label(exit_up_y)
+
 	/* D-pad Down → cam.pos.y += 50. Reuses R_T1 from Up. */
-	and_i(R_T3, R_T0, Pad_Down), branch_le_zero(R_T3, atom_offset(down_y, exit_down_y)), nop,
+	and_i(R_T3, R_T0, Pad_Down), branch_le_zero(R_T3, atom_offset(down_y, exit_down_y)), BdSlot_ nop,
 		add_si(R_T1, R_T1,  50), store_word(R_T1, R_Cam, O_(Camera,pos.y)),
 	atom_label(exit_down_y)
 
 	/* D-pad Cross → cam.pos.z -= 50. Load pos.z BEFORE the andi. */
-	load_word(R_T1, R_Cam, O_(Camera,pos.z)),
-	and_i(R_T3, R_T0, Pad_Cross), branch_le_zero(R_T3, atom_offset(cross_z, exit_cross_z)), nop,
+	load_word(R_T1, R_Cam, O_(Camera,pos.z)), LdSlot_
+	and_i(R_T3, R_T0, Pad_Cross), branch_le_zero(R_T3, atom_offset(cross_z, exit_cross_z)), BdSlot_ load_word(R_AtomJmp, R_TapePtr, 0), LdSlot_ // ac_yield: word 1
 		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.z)),
 	atom_label(exit_cross_z)
+
 	/* D-pad Circle → cam.pos.z += 50. Reuses R_T1 from Cross. */
-	and_i(R_T3, R_T0, Pad_Circle), branch_le_zero(R_T3, atom_offset(circle_z, exit_circle_z)), nop,
+	and_i(R_T3, R_T0, Pad_Circle), branch_le_zero(R_T3, atom_offset(circle_z, exit_circle_z)), BdSlot_ add_ui_self(R_TapePtr, S_(MipsCode)), // ac_yield: word 2
 		add_si(R_T1, R_T1,  50), store_word(R_T1, R_Cam, O_(Camera,pos.z)),
 	atom_label(exit_circle_z)
 
-	mac_yield_tail(),
+	jump_reg(R_AtomJmp), BdSlot_ nop // ac_yield: word 3-4
 };
 
 enum {
@@ -832,7 +513,7 @@ internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
-	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
 
@@ -845,20 +526,22 @@ MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 	load_half_u(R_T0, R_FaceCursor, 0 * S_(S2)),
 	load_half_u(R_T1, R_FaceCursor, 1 * S_(S2)),
 	load_half_u(R_T2, R_FaceCursor, 2 * S_(S2)),
-	load_half_u(R_T3, R_FaceCursor, 3 * S_(S2)),
+	// load_half_u(R_T3, R_FaceCursor, 3 * S_(S2)),
 
-	mac_gte_load_tri_verts(R_VertBase, R_T0, R_T1, R_T2),
-	nop2, gte_cmdw_rotate_translate_perspective_triple, // required cpu -> gte delay slot
+	LdSlot_ mac_gte_load_tri_verts(R_VertBase, R_T0, R_T1, R_T2), 
+		GteDelay_ load_half_u(R_T3, R_FaceCursor, 3 * S_(S2)), LdSlot_
+		GteDelay_ load_word(R_AtomJmp, R_TapePtr, 0),          LdSlot_ //ac_yield: word 2,
+	gte_cmdw_rotate_translate_perspective_triple,
 	gte_cmdw_nclip,
 
-	gte_mv_from_data_r(R_T0, C2_MAC0), nop,
+	gte_mv_from_data_r(R_T0, C2_MAC0), GteDelay_ add_ui_self(R_TapePtr, S_(MipsCode)), // ac_yield: word 1
 	branch_le_zero(R_T0, atom_offset(cull, cube_g4_face_exit)),
 		/* BD-slot: Write the prim tag (R_0=0; overwrites the legacy tag word in the prim_buffer).
 		 * If branch IS taken (face culled), the body is skipped and this 0-tag is stranded —
 		 * harmless because the OT entry that points to this prim is created later. */
-		store_word(R_0, R_PrimCursor, O_(Poly_G4, tag)),
+		BdSlot_ store_word(R_0, R_PrimCursor, O_(Poly_G4, tag)),
 		shift_lleft(R_AT, R_T3, v3s2_byteoff), add_u(R_AT, R_AT, R_VertBase),
-		load_word(R_V0, R_AT, O_(V3_S2, x)),   load_word(R_V1, R_AT, O_(V3_S2, z)),
+		load_word(R_V0, R_AT, O_(V3_S2, x)),   load_word(R_V1, R_AT, O_(V3_S2, z)), LdSlot_
 		gte_mv_to_data_r(R_V0, C2_VXY0),       gte_mv_to_data_r(R_V1, C2_VZ0),
 
 		mac_gte_store_g4_p012(R_PrimCursor),
@@ -870,7 +553,7 @@ MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 		add_ui(      R_AT, R_0,  OrderingTbl_Len),
 		set_lt_u(    R_AT, R_T1, R_AT),
 
-		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, cube_g4_face_exit)), nop,
+		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, cube_g4_face_exit)), BdSlot_ nop,
 			mac_insert_ot_tag(R_OtBase, R_PrimCursor, S_(Poly_G4)),
 			mac_format_g4_color(R_PrimCursor,
 				/* c0 magenta */ 0xFF, 0x00, 0xFF,
@@ -883,7 +566,7 @@ MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 atom_label(cube_g4_face_exit)
 	add_ui_self(R_PrimCursor, S_(Poly_G4)),     /* 9 words = Poly_G4 */
 	add_ui_self(R_FaceCursor, S_(S2) * 4),      /* 4 × S2 = 8 bytes */
-	mac_yield()
+	jump_reg(R_AtomJmp), BdSlot_ nop      // ac_yield: word 3-4
 };
 
 typedef Struct_(Binds_FloorTri) {
@@ -902,7 +585,7 @@ MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri), atom_phase(f
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
-	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 
@@ -913,13 +596,13 @@ MipsAtom_(floor_f3_face) atom_info(atom_phase(floor_f3)
 	, atom_writes(R_PrimCursor, R_FaceCursor)
 ) {
 	mac_load_tri_indices(R_FaceCursor, R_T0, R_T1, R_T2),
-	mac_gte_load_tri_verts(R_VertBase,   R_T0, R_T1, R_T2),
-	nop2, gte_cmdw_rotate_translate_perspective_triple, // 2 nops retire the final cpu -> gte writes before RTPT
+	mac_gte_load_tri_verts(R_VertBase, R_T0, R_T1, R_T2), GteDelay_ nop2,
+	gte_cmdw_rotate_translate_perspective_triple, // 2 nops retire the final cpu -> gte writes before RTPT
 	gte_cmdw_nclip,
 
 	/* Culling (Branch forward if Backface) */
-	gte_mv_from_data_r(R_T0, C2_MAC0),
-	nop, branch_le_zero(R_T0, atom_offset(culling, floor_f3_face_exit)), nop, // required gte -> cpu load-delay slot.
+	gte_mv_from_data_r(R_T0, C2_MAC0), GteDelay_ load_word(R_AtomJmp, R_TapePtr, 0), // ac_yield: word 1
+	branch_le_zero(R_T0, atom_offset(culling, floor_f3_face_exit)), BdSlot_ add_ui_self(R_TapePtr, S_(MipsCode)),  // ac_yield: word 2
 		/* Format Primitive */
 		mac_gte_store_f3(R_PrimCursor),
 
@@ -929,7 +612,7 @@ MipsAtom_(floor_f3_face) atom_info(atom_phase(floor_f3)
 		/* Bounds Check OTZ < 2048 (Branch forward to skip insertion) */
 		add_ui(      R_AT, R_0,  OrderingTbl_Len),
 		set_lt_u(    R_AT, R_T1, R_AT),
-		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, floor_f3_face_exit)), nop,
+		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, floor_f3_face_exit)), BdSlot_ nop,
 			mac_format_f3_color(R_PrimCursor, 0xFF, 0xFF, 0xFF),  // RGB-form (R=FF, G=FF, B=FF = white)
 			mac_insert_ot_tag(R_OtBase, R_PrimCursor, S_(Poly_F3)),   /* Insert into Ordering Table Linked List */
 			add_ui_self(R_PrimCursor, S_(Poly_F3)), /* Advance Prim Cursor (5 words) */
@@ -940,7 +623,7 @@ MipsAtom_(floor_f3_face) atom_info(atom_phase(floor_f3)
 /* Advance Input Cursor & Yield (Both branch targets land here) */
 atom_label(floor_f3_face_exit)
 	add_ui_self(R_FaceCursor, S_(S2) * 4),  /* Advance Face Cursor (4 * S2 = 8 bytes) */
-	mac_yield()
+	jump_reg(R_AtomJmp), BdSlot_ nop // ac_yield: word 3-4
 };
 
 typedef Struct_(Binds_SyncPrimitiveArena) { U4 used; U4 cursor; };
@@ -949,7 +632,7 @@ internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitive
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
-	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
+	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)), LdSlot_
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor

code/hello_camera/hello_camera.c

@@ -1,7 +1,7 @@
 #pragma region Vendors
 #include <stdio.h>
 #include <stdlib.h>
-#include <assert.h>
+// #include <assert.h>
 // #include "libgpu.h"
 // #include "libetc.h"
 // #include "libgte.h"
@@ -32,7 +32,7 @@
 
 #pragma region Duffle TUs
 #include "duffle/pad.c"
-#include "duffle/math.atom.c"
+#include "duffle/math.atom.h"
 #include "duffle/mips.atom.c"
 #include "duffle/gte.atom.c"
 #include "duffle/gp.atom.c"
@@ -53,15 +53,13 @@
 #pragma endregion Hello Joypad TUs
 
 enum {
-	Scratchpad_Loc = 0x1F800000,
-};
-#define C_scratch(type) C_(type, Scratchpad_Loc)
-
-enum {
-	Scratchpad_Len           = 1024,
 	MemTape_Len              = 512,
+
 	ResolveLookAtArena_Words = 1024,
 	ResolveLookAtArena_Size  = ResolveLookAtArena_Words * S_(MipsCode),
+
+	CT_InitAtomMem_Words     = Kilo_(4),
+	CT_InitAtomMem_Size       = CT_InitAtomMem_Words * S_(MipsCode),
 };
 typedef Struct_(SMemory) {
 	PrimitiveArena          primitives;
@@ -82,11 +80,12 @@ typedef Struct_(SMemory) {
 	PadBiosRaw pad_raw[2];
 	PadState   pad[2];
 
-	// TODO(Ed): We don't need this we can just cast at any point an address to a desired view of scratchpad, we have the address.
-	U4_V scratchpad; // d-cache
+	U1 ct_init_atom_mem[CT_InitAtomMem_Size];
+	MipsAtom* normalize_v3s4;
+	MipsAtom* gte_cross_v3s4;
 
 	U1        resolve_look_at_mem[ResolveLookAtArena_Size];
-	MipsAtom* resolve_look_at_atom_addrs[10];
+	MipsAtom* resolve_look_at_bundle[AtomBundle_Len(resolve_look_at)];
 };
 global SMemory smem;
 extern SMemory smem;
@@ -112,10 +111,10 @@ I_ void resolve_look_at_c11(MT3_S2S4* look_at, P3_S4* eye, P3_S4* target, V3_S4*
 	V3_S4 pos, off;
 
 	forward = target[0]; sub_v3s4(& forward, eye[0]); // RGA(Lengyel): Affine point - point = zero-weight direction.
-	normalize_v3s4(& forward, & uz);                  // RGA(Lengyel): Normalize the direction bulk. Not finite-point unitization.
+	psy_normalize_v3s4(& forward, & uz);              // RGA(Lengyel): Normalize the direction bulk. Not finite-point unitization.
 
-	cross_v3s4(& uz,   up_in, & right); normalize_v3s4(& right, & ux); // RGA(Lengyel): Complement(Wedge(forward, up_in)) -> right axis.
-	cross_v3s4(& uz, & ux,    & up);    normalize_v3s4(& up,    & uy); // RGA(Lengyel): Complement(Wedge(forward, right)) -> up axis.
+	cross_v3s4(& uz,   up_in, & right); psy_normalize_v3s4(& right, & ux); // RGA(Lengyel): Complement(Wedge(forward, up_in)) -> right axis.
+	cross_v3s4(& uz, & ux,    & up);    psy_normalize_v3s4(& up,    & uy); // RGA(Lengyel): Complement(Wedge(forward, right)) -> up axis.
 
 	// RGA(Lengyel): matrix expansion of the world-to-camera rotation (basis rows).
 	look_at->m[0][0] = ux.x; look_at->m[0][1] = ux.y; look_at->m[0][2] = ux.z;
@@ -131,289 +130,114 @@ I_ void resolve_look_at_c11(MT3_S2S4* look_at, P3_S4* eye, P3_S4* target, V3_S4*
 }
 FI_ void camera_look_at_c11(Camera* c, P3_S4* target, V3_S4* up_in) { resolve_look_at_c11(& c->look_at, & c->pos, target, up_in); }
 
-/* Pre-build all 7 chain atoms of the resolve_look_at bundle into the static arena.
- * Called ONCE from main() before the frame loop.
- * After this returns, the smem.resolve_look_at_atom_addrs[] array contains valid MIPS atom pointers
- * for the frame-time bundle helper to emit via tb_emit(tb, captured_addr).
- *
- * 4 unique procs in hello_camera.atom.c (chain atoms 0, 2, 4, 6); atoms 1, 3, 5
- * share the GENERIC normalize_v3s4_proc from gte.atom.c (called 3x with different
- * O_(ResolveLookAtScratch,...) offsets):
- * 	0: resolve_look_at__input_and_sub_proc
- * 	1: normalize_v3s4_proc                  (fwd → uz; offsets 0, 16)
- * 	2: resolve_look_at__cross_uz_up_in_to_right_proc
- * 	3: normalize_v3s4_proc                  (right → ux; offsets 32, 48)
- * 	4: resolve_look_at__cross_uz_ux_to_up_proc
- * 	5: normalize_v3s4_proc                  (up → uy; offsets 64, 80)
- * 	6: resolve_look_at__populate_and_translate_proc
- *
- * Task 12.16 promotion: the bundle-specific resolve_look_at__chain_normalize_proc
- * has been promoted to the generic normalize_v3s4_proc (gte.atom.c), which now
- * takes r_scratch + r_src_offset + r_dst_offset as U4 parameters. The 3 callers
- * pass O_(ResolveLookAtScratch,...) macros as offset args. The metaprogram emits
- * one set of `atom_offset__normalize_v3s4__srav_path__aligned_done` defs
- * (namespaced by atom name) in duffle/gen/offsets.h, shared by all 3 callers.
- *
- * GPR pool per atom: 10 free GPRs (R_T0..R_T3 + R_T5..R_T7 + R_V0 + R_V1 + R_AT).
- * R_T4 is reserved as the wave-context carrier (R_ResolveScratch).
- */
-/* === EXPLICIT REGISTER ALLOCATION TRACKER ===
- * Every GPR used by every atom is tracked below. NO GPR is assigned to
- * two atoms at overlapping lifetimes. The tape runtime preserves R_T8/R_T9
- * (R_AtomJmp/R_TapePtr) and clobbers R_T0-R_T7, R_AT, R_V0, R_V1.
- * R_T4 is reserved as R_ResolveScratch (wave-context carrier).
- *
- * GPR pool: R_T0($8), R_T1($9), R_T2($10), R_T3($11), R_T5($13),
- *           R_T6($14), R_T7($15), R_V0($2), R_V1($3), R_AT($1)
- * Reserved: R_T4($12) = R_ResolveScratch
- * Tape: R_T8($24) = R_AtomJmp, R_T9($25) = R_TapePtr (preserved)
- *
- * === ATOM 0: input_and_sub (stages eye/up_in, computes fwd) ===
- * Pop tape → R_T0(target), R_T1(eye), R_T2(up_in).
- * Use R_T3,R_T5,R_T6,R_T7 as temps.
- * NO conflict with other atoms (each atom has independent lifetime).
- *
- * === ATOM 1: normalize fwd→uz ===
- * r_src_offset=0, r_dst_offset=16.
- * r_src_ptr=R_T0, r_dst_ptr=R_T1, r_tmp=R_T2 (preserved for stage 4).
- * r_mac1=R_T3, r_mac2=R_T5, r_recip=R_T6, r_lzcr=R_T7, r_shift=R_V0, r_branch=R_V1.
- *
- * === ATOM 2: cross uz×up_in→right ===
- * r_a=R_T0, r_b=R_T1, r_c=R_T2, r_d=R_T3, r_f(out)=R_T5, r_g=R_T6, r_h=R_T7.
- *
- * === ATOM 3: normalize right→ux ===
- * Same GPR pool as atom 1.
- *
- * === ATOM 4: cross uz×ux→up ===
- * r_a=R_T0, r_b=R_T1, r_c=R_T2, r_d=R_T3, r_f(out)=R_T5, r_g=R_T6, r_h=R_T7.
- *
- * === ATOM 5: normalize up→uy ===
- * Same GPR pool as atom 1.
- *
- * === ATOM 6a: populate (m[][] from ux/uy/uz, t[]=0) ===
- * r_look_at=R_T0 (pop tape), r_scratch=R_T4.
- * r_pux=R_T1, r_puy=R_T3, r_puz=R_T5.
- * r_tmp0=R_T2, r_tmp1=R_T6, r_tmp2=R_V0.
- *
- * === ATOM 6a.5: set_gte_mt3s2s4 (ctc2 RT matrix) ===
- * BAKED atom. Uses R_T3 internally (hardcoded in gte.atom.c).
- * NO conflict — different GPR pool, and the atom body hardcodes R_T3
- * as the matrix pointer. We DON'T need to assign R_T3 to atom 6a.5
- * because it's a baked atom with its own GPR usage.
- *
- * === ATOM 6b: matrix_vector (RT * (-eye) >> 12) ===
- * r_look_at=R_T0 (pop tape), r_scratch=R_T4.
- * r_peye=R_T1.
- * r_tmp0=R_T2, r_tmp1=R_T3, r_tmp2=R_T5.
- * Uses mac_apply_matrix_lv which internally uses these temps.
- *
- * === ATOM 6c: trans_matrix (off → look_at->t[]) ===
- * r_look_at=R_T0 (pop tape), r_scratch=R_T4.
- * r_off_ptr=R_T1.
- * r_tmp0=R_T2.
- *
- * === CONFLICT CHECK ===
- * All atoms use the same GPR pool R_T0-R_T3, R_T5-R_T7, R_V0-R_V1.
- * But atoms are SEQUENTIAL — each atom's lifetime is disjoint from
- * the next atom's lifetime. The tape yield handshake between atoms
- * preserves R_TapePtr (R_T9) and R_AtomJmp (R_T8).
- *
- * The GPR pool is SHARED across atoms (they run sequentially, not
- * concurrently). Each atom's build call assigns specific R_T* codes
- * for that atom's body. The same R_T* code can be reused across atoms
- * because the previous atom's body has already yielded.
- */
-internal void resolve_look_at_init(void) {
-	/* Wrap the static arena in a MipsAtomBuilder. */
+internal void compile_init_atoms(void) {
+	AtomArena ab = atomarena_make(slice_ut_arr(smem.ct_init_atom_mem));
+	RegFile   rf = regfile(regfile_abi_mask);
+#define ralloc() regfile_alloc(& rf)
+#define ralloc_v3() { ralloc(), ralloc(), ralloc() }
+
+	smem.gte_cross_v3s4 = gte_cross_v3s4(& ab,
+		RegUse_(gte_cross_v3s4) {
+			.a  = ralloc_v3(),
+			.b  = ralloc_v3(),
+			.x  = ralloc(),
+			.y  = ralloc(),
+			.z  = ralloc(),
+		});
+	regfile_reset(& rf);
+
+	smem.normalize_v3s4 = normalize_v3s4(& ab,
+		RegUse_(normalize_v3s4) {
+			.res = ralloc_v3(),
+			.r0     = ralloc(),
+			.r1     = ralloc(),
+			.r2     = ralloc(),
+			.r3     = ralloc(),
+			.r4     = ralloc(),
+			.r5     = ralloc(),
+		});
+	regfile_reset(& rf);
+
+	assert(ab.used <= CT_InitAtomMem_Size);
+#undef ralloc
+#undef ralloc_v3
+}
+
+internal void compile_resolve_look_at(void) {
+	AtomBundle_resolve_look_at_R bundle = C_(void*, smem.resolve_look_at_bundle);
 	AtomArena ab = atomarena_make(slice_ut_arr(smem.resolve_look_at_mem));
+	RegFile   rf = regfile(regfile_abi_mask);
+#define ralloc() regfile_alloc(& rf)
+#define ralloc_v3() { ralloc(), ralloc(), ralloc() }
+	bundle->input_and_sub = AtomBundleEntry_(resolve_look_at, input_and_sub)(& ab,
+		RegUse_(resolve_look_at_input_and_sub) {
+			.target_ptr = ralloc(),
+			.eye_ptr    = ralloc(),
+			.up_in_ptr  = ralloc(),
+			.up_in      = ralloc_v3(),
+			.r012       = ralloc_v3(),
+			.r345       = {ralloc(), R_AT, ralloc() },
+	});
+	regfile_reset(& rf);
 
-	/* === ATOM 0: input_and_sub === */
-	U4 const r_target_ptr = R_T0;  /* tape pop → target */
-	U4 const r_eye_ptr    = R_T1;  /* tape pop → eye */
-	U4 const r_up_in_ptr  = R_T2;  /* tape pop → up_in */
-	U4 const r_tmp0_0     = R_T3;
-	U4 const r_tmp1_0     = R_T5;
-	U4 const r_tmp2_0     = R_T6;
-	U4 const r_tmp3_0     = R_T7;
-	smem.resolve_look_at_atom_addrs[0] = resolve_look_at__input_and_sub_proc(& ab,
-		R_ResolveScratch,
-		r_target_ptr, r_eye_ptr, r_up_in_ptr,
-		r_tmp0_0, r_tmp1_0, r_tmp2_0, r_tmp3_0);
+	bundle->normalize_fwd_uz   = smem.normalize_v3s4;
+	bundle->cross_to_right     = smem.gte_cross_v3s4;
+	bundle->normalize_right_ux = smem.normalize_v3s4;
+	bundle->cross_to_up        = smem.gte_cross_v3s4;
+	bundle->normalize_up_uy    = smem.normalize_v3s4;
 
-	/* === ATOM 1: normalize fwd→uz === */
-	U4 const r_src_offset_1  = O_(ResolveLookAtScratch, fwd);
-	U4 const r_dst_offset_1  = O_(ResolveLookAtScratch, uz);
-	U4 const r_src_ptr_1     = R_T0;
-	U4 const r_dst_ptr_1     = R_T1;
-	U4 const r_tmp_1         = R_T2;
-	U4 const r_mac1_1        = R_T3;
-	U4 const r_mac2_1        = R_T5;
-	U4 const r_recip_1       = R_T6;
-	U4 const r_lzcr_1        = R_T7;
-	U4 const r_shift_1       = R_V0;
-	U4 const r_branch_1      = R_V1;
-	smem.resolve_look_at_atom_addrs[1] = normalize_v3s4_proc(& ab,
-		R_ResolveScratch,
-		r_src_offset_1, r_dst_offset_1,
-		r_src_ptr_1, r_dst_ptr_1, r_tmp_1,
-		r_mac1_1, r_mac2_1, r_recip_1, r_lzcr_1,
-		r_shift_1, r_branch_1);
+	bundle->populate_mt3s4s2 = AtomBundleEntry_(resolve_look_at,populate_mt3s4s2)(& ab,
+		RegUse_(resolve_look_at_populate_mt3s4s2){
+			.look_at = ralloc(),
+			.eye     = ralloc(),
+			.row     = ralloc_v3(),
+			.r0      = ralloc(),
+			.r1      = ralloc(),
+			.r2      = ralloc(),
+		});
 
-	/* === ATOM 2: cross uz×up_in→right === */
-	U4 const r_a_2 = R_T0;
-	U4 const r_b_2 = R_T1;
-	U4 const r_c_2 = R_T2;
-	U4 const r_d_2 = R_T3;
-	U4 const r_f_2 = R_T5;  /* out ptr (HARDCODED in body: scratch+32) */
-	U4 const r_g_2 = R_T6;  /* a ptr = scratch+16 */
-	U4 const r_h_2 = R_T7;  /* b ptr = scratch+128 */
-	smem.resolve_look_at_atom_addrs[2] = resolve_look_at__cross_uz_up_in_to_right_proc(& ab,
-		R_ResolveScratch,
-		r_a_2, r_b_2, r_c_2, r_d_2, r_f_2, r_g_2, r_h_2);
-
-	/* === ATOM 3: normalize right→ux === */
-	U4 const r_src_offset_3  = O_(ResolveLookAtScratch, right);
-	U4 const r_dst_offset_3  = O_(ResolveLookAtScratch, ux);
-	U4 const r_src_ptr_3     = R_T0;
-	U4 const r_dst_ptr_3     = R_T1;
-	U4 const r_tmp_3         = R_T2;
-	U4 const r_mac1_3        = R_T3;
-	U4 const r_mac2_3        = R_T5;
-	U4 const r_recip_3       = R_T6;
-	U4 const r_lzcr_3        = R_T7;
-	U4 const r_shift_3       = R_V0;
-	U4 const r_branch_3      = R_V1;
-	smem.resolve_look_at_atom_addrs[3] = normalize_v3s4_proc(& ab,
-		R_ResolveScratch,
-		r_src_offset_3, r_dst_offset_3,
-		r_src_ptr_3, r_dst_ptr_3, r_tmp_3,
-		r_mac1_3, r_mac2_3, r_recip_3, r_lzcr_3,
-		r_shift_3, r_branch_3);
-
-	/* === ATOM 4: cross uz×ux→up === */
-	U4 const r_a_4 = R_T0;
-	U4 const r_b_4 = R_T1;
-	U4 const r_c_4 = R_T2;
-	U4 const r_d_4 = R_T3;
-	U4 const r_f_4 = R_T5;  /* out ptr (HARDCODED: scratch+64) */
-	U4 const r_g_4 = R_T6;  /* a ptr = scratch+16 */
-	U4 const r_h_4 = R_T7;  /* b ptr = scratch+48 */
-	smem.resolve_look_at_atom_addrs[4] = resolve_look_at__cross_uz_ux_to_up_proc(& ab,
-		R_ResolveScratch,
-		r_a_4, r_b_4, r_c_4, r_d_4, r_f_4, r_g_4, r_h_4);
-
-	/* === ATOM 5: normalize up→uy === */
-	U4 const r_src_offset_5  = O_(ResolveLookAtScratch, up);
-	U4 const r_dst_offset_5  = O_(ResolveLookAtScratch, uy);
-	U4 const r_src_ptr_5     = R_T0;
-	U4 const r_dst_ptr_5     = R_T1;
-	U4 const r_tmp_5         = R_T2;
-	U4 const r_mac1_5        = R_T3;
-	U4 const r_mac2_5        = R_T5;
-	U4 const r_recip_5       = R_T6;
-	U4 const r_lzcr_5        = R_T7;
-	U4 const r_shift_5       = R_V0;
-	U4 const r_branch_5      = R_V1;
-	smem.resolve_look_at_atom_addrs[5] = normalize_v3s4_proc(& ab,
-		R_ResolveScratch,
-		r_src_offset_5, r_dst_offset_5,
-		r_src_ptr_5, r_dst_ptr_5, r_tmp_5,
-		r_mac1_5, r_mac2_5, r_recip_5, r_lzcr_5,
-		r_shift_5, r_branch_5);
-
-	/* === ATOM 6a: populate (m[][] from ux/uy/uz, t[]=0) === */
-	U4 const r_look_at_6a = R_T0;  /* tape pop → look_at* */
-	U4 const r_scratch_6a = R_ResolveScratch;
-	U4 const r_pux_6a      = R_T1;
-	U4 const r_puy_6a      = R_T3;
-	U4 const r_puz_6a      = R_T5;
-	U4 const r_tmp0_6a     = R_T2;
-	U4 const r_tmp1_6a     = R_T6;
-	U4 const r_tmp2_6a     = R_V0;
-	smem.resolve_look_at_atom_addrs[6] = resolve_look_at__populate_proc(& ab,
-		r_look_at_6a, r_scratch_6a,
-		r_pux_6a, r_puy_6a, r_puz_6a,
-		r_tmp0_6a, r_tmp1_6a, r_tmp2_6a);
-
-	/* === ATOM 6a.5: set_gte_mt3s2s4 (BAKED — ctc2 RT matrix) ===
-	 * This is a BAKED atom from gte.atom.c. Its body hardcodes R_T3 as
-	 * the matrix pointer (popped from tape). It does NOT need GPR
-	 * assignment from us — it has its own internal GPR usage.
-	 * We just take its address. */
-	smem.resolve_look_at_atom_addrs[7] = (MipsAtom*) & set_gte_mt3s2s4;
-
-	/* === ATOM 6b: matrix_vector (RT * (-eye) >> 12) ===
-	 * Uses mac_apply_matrix_lv component macro which internally uses
-	 * r_t0 for the RT matrix load + V0 load, then r_t0/r_t1/r_t2
-	 * for the mfc2/store. We pass our GPRs. */
-	U4 const r_scratch_6b = R_ResolveScratch;
-	U4 const r_peye_6b    = R_T1;  /* scratch+96 (packed V0 dst, then off dst) */
-	U4 const r_look_at_6b = R_T0;  /* tape pop → look_at* */
-	U4 const r_tmp0_6b    = R_T2;
-	U4 const r_tmp1_6b    = R_T3;
-	U4 const r_tmp2_6b    = R_T5;
-	smem.resolve_look_at_atom_addrs[8] = resolve_look_at__matrix_vector_proc(& ab,
-		r_scratch_6b, r_peye_6b, r_look_at_6b,
-		r_tmp0_6b, r_tmp1_6b, r_tmp2_6b);
-
-	/* === ATOM 6c: trans_matrix (off → look_at->t[]) === */
-	U4 const r_look_at_6c = R_T0;  /* tape pop → look_at* */
-	U4 const r_scratch_6c = R_ResolveScratch;
-	U4 const r_off_ptr_6c = R_T1;  /* &scratch.eye (= off dst) */
-	U4 const r_tmp0_6c    = R_T2;
-	smem.resolve_look_at_atom_addrs[9] = resolve_look_at__trans_matrix_proc(& ab,
-		r_look_at_6c, r_scratch_6c, r_off_ptr_6c, r_tmp0_6c);
-
-	/* Sanity check: arena didn't overflow. */
-	assert(ab.used <= ResolveLookAtArena_Size);
+	assert(ab.used <= ResolveLookAtArena_Size); // Sanity check: arena didn't overflow.
+#undef ralloc
 }
 
-/* Emit the resolve_look_at bundle into the tape. Called once per frame from update().
- * The 7 chain atoms are pre-built at init time (resolve_look_at_init) and referenced by address via smem.resolve_look_at_atom_addrs[].
- * Per-frame work: 7 tb_emit (atom pointer emissions) + 5 tb_data (C-side pointers for atom 0 + look_at for atom 6).
- *
- * Binds_ contract (the field-name labels are for human readability):
- *   Atom 0  input_and_sub              target(4) eye(4) up_in(4) scratch_base(4) = 4 words
- *   Atoms 1-5                           (no tape data — atom uses r_scratch + offset internally)
- *   Atom 6  populate_and_translate     look_at(4)                                = 1 word
- *                                       ----
- *                                       5 tb_data words total per frame.
- */
-I_ void resolve_look_at(
-		TapeBuilder_R tb
-	,	MT3_S2S4* look_at
-	,	P3_S4*    eye
-	,	P3_S4*    target
-	,	V3_S4*    up_in
-){
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[0]); {
-		tb_data(tb, u4_(target));
-		tb_data(tb, u4_(eye));
-		tb_data(tb, u4_(up_in));
-		tb_data(tb, u4_(smem.scratchpad));
+// Emit the resolve_look_at bundle into the tape. Called once per frame from update().
+I_ void resolve_look_at(TapeBuilder_R tb,	MT3_S2S4* look_at, P3_S4* eye, P3_S4* target,	V3_S4* up_in) {
+	/* Typed view of the scratchpad for field-address arithmetic. */
+	ResolveLookAtScratch*        sp     = C_scratch(ResolveLookAtScratch*);
+	AtomBundle_resolve_look_at_R bundle = C_(void*, smem.resolve_look_at_bundle);
+	tb_emit(tb, bundle->input_and_sub); tb_bind_(tb, Binds_ResolveLookAtSub, 
+		.target = target,
+		.eye    = eye,
+		.up_in  = up_in,
+	);
+	tb_emit(tb, bundle->normalize_fwd_uz); tb_bind_(tb, Binds_normalize_v3s4,
+		.src_offset = O_(ResolveLookAtScratch,fwd),
+		.dst_offset = O_(ResolveLookAtScratch,uz),
+	);
+	tb_emit(tb, bundle->cross_to_right); tb_bind_(tb, Binds_gte_cross_v3s4,
+		.src_a = & sp->uz,
+		.src_b = & sp->up_in,
+		.out   = & sp->right,
+	);
+	tb_emit(tb, bundle->normalize_right_ux); tb_bind_(tb, Binds_normalize_v3s4, 
+		.src_offset = O_(ResolveLookAtScratch,right),
+		.dst_offset = O_(ResolveLookAtScratch,ux),
+	);
+	tb_emit(tb, bundle->cross_to_up); tb_bind_(tb, Binds_gte_cross_v3s4, 
+		.src_a = & sp->uz,
+		.src_b = & sp->ux,
+		.out   = & sp->up,
+	);
+	tb_emit(tb, bundle->normalize_up_uy); tb_bind_(tb, Binds_normalize_v3s4,
+		.src_offset = O_(ResolveLookAtScratch,up),
+		.dst_offset = O_(ResolveLookAtScratch,uy),
+	);
+	tb_emit(tb, bundle->populate_mt3s4s2); tb_bind_(tb, Binds_ResolveLookAt_PopulateMT3S4S2, 
+		.look_at = look_at,
+	);
 }
+FI_ void camera_look_at(TapeBuilder_R tb, Camera* c, P3_S4* target, V3_S4* up_in) { resolve_look_at(tb, & c->look_at, & c->pos, target, up_in); }
 
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[1]); { }
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[2]); { }
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[3]); { }
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[4]); { }
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[5]); { }
-
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[6]); {
-		tb_data(tb, u4_(look_at));
-	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[7]); {
-		tb_data(tb, u4_(look_at));
-	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[8]); {
-		tb_data(tb, u4_(look_at));
-	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[9]); {
-		tb_data(tb, u4_(look_at));
-	}
-}
-
-GCC_OPTIMIZATION_DISABLE
 void update(PrimitiveArena* pa, U4* ordering_buf) 
 {
 	TapeBuilder tb = tb_make(slice_ut_arr(smem.MemTape));
@@ -423,15 +247,15 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		tb.used = 0; tb_scope_run(& tb) {
 			// Grab latest state from bios.
 			tb_emit_(pad_bios_snapshot);
-				tb_data_(raw,   & smem.pad_raw[0]);
-				tb_data_(state, & smem.pad[0]);
-			tb_emit_(pad_bios_snapshot);
-				tb_data_(raw,   & smem.pad_raw[1]);
-				tb_data_(state, & smem.pad[1]);
+				tb_data(& tb,   u4_(& smem.pad_raw[0]));
+				tb_data(& tb, u4_(& smem.pad[0]));
+			// tb_emit_(pad_bios_snapshot);
+			// 	tb_data_(raw,   & smem.pad_raw[1]);
+			// 	tb_data_(state, & smem.pad[1]);
 
 			tb_emit_(pad_input_cam);
-				tb_data_(state, & smem.pad[0]);
-				tb_data_(cam, & smem.cam);
+				tb_data(& tb, u4_(& smem.pad[0]));
+				tb_data(& tb, u4_(& smem.cam));
 
 			// tb_emit_(pad_input_cube_rotation);
 			// 	tb_data_(state,     & smem.pad[0]);
@@ -448,12 +272,6 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 	gknown V3_S4_R acc = & smem.cube.accel;
 	add_v3s4(vel, acc[0]);
 	add_v3s4_fp(pos, vel[0]);
-	// vel->x += acc->x;
-	// vel->y += acc->y;
-	// vel->z += acc->z;
-	// pos->x += vel->x;
-	// pos->y += vel->y;
-	// pos->z += vel->z;
 
 	if (pos->y + 150 > smem.floor.pos.y) vel->y *= -1;
 
@@ -470,7 +288,7 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 	if (use_c11_path == false)
 	{
 		tb.used = 0; tb_scope_run(& tb) {
-			resolve_look_at(& tb, & smem.cam.look_at, & smem.cam.pos, & smem.cube.pos, & v3s4(0, -fp_one, 0));
+			camera_look_at(& tb, & smem.cam, & smem.cube.pos, & v3s4(0, -fp_one, 0));
 		}
 	}
 
@@ -486,9 +304,6 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		gte_matrix_set_rotation   (& smem.tform_view);
 		gte_matrix_set_translation(& smem.tform_view);
 
-		// gte_matrix_set_rotation   (& smem.tform_world);
-		// gte_matrix_set_translation(& smem.tform_world);
-
 		U4 prim_base   = u4_(pa->buf[smem.active_buf_id]);
 		U4 prim_cursor = prim_base + pa->used;
 
@@ -508,7 +323,7 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
-		tape_run_a02_s07(tb_slice(tb));// Fire off the tape (bigger-clobber variant).
+		tape_run(tb_slice(tb));// Fire off the tape (bigger-clobber variant).
 
 		// smem.cube.rot.y += 30;
 	}
@@ -550,13 +365,12 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
-		tape_run_a02_s07(tb_slice(tb));// Fire off the tape (bigger-clobber variant).
+		tape_run(tb_slice(tb));// Fire off the tape (bigger-clobber variant).
 
 		// C-side state (pa->used) has already been updated by the tape!
 		// smem.floor.rot.y += 5;
 	}
 }
-GCC_OPTIMIZATION_ENABLE
 
 void render(void) {
 }
@@ -573,12 +387,9 @@ void gp_display_frame(DoubleBuffer* screen_buf, S4* active_buf_id, U4* ordering_
 	active_buf_id[0] = ! active_buf_id[0]; // Swap current buffer
 }
 
-GCC_OPTIMIZATION_DISABLE
 int main(void)
 {
 	smem = (SMemory){0};
-	// TODO(Ed): remove this field we don't need it in smem.
-	smem.scratchpad = C_(U4_V, Scratchpad_Loc);
 	// smem.primitives.used = 0;
 	// smem.active_buf_id   = 0;
 	smem.cam.pos = v3s4(500, -1000, -1500);
@@ -602,8 +413,8 @@ int main(void)
 		/* Direct BIOS: poll both ports during VBlank. */
 		pad_bios_init_start(& smem.pad_raw[0], & smem.pad_raw[1]);
 
-		/* Pre-build the resolve_look_at bundle atoms into the static arena. */
-		resolve_look_at_init();
+		compile_init_atoms();
+		compile_resolve_look_at();
 
 		/* Pinned registers for the GPU init atom. */
 		register U4*           io_base_addr rgcc(R_IO_BaseAddr) = u4_r(IO_BASE_ADDR);
@@ -623,5 +434,3 @@ int main(void)
 	};
 	return 0;
 }
-GCC_OPTIMIZATION_ENABLE
-

code/hello_joypad/hello_joypad.atom.c

@@ -25,7 +25,7 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(hello_joypad_atom_c);
 #pragma region MACs (Mips Atom components)
 
 FI_ Slice_MipsCode ac_put_disp_env(MipsAtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_disp_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	// Emits 5 GP0 commands for buffer 0 (display_area = (0,0,320,240)).
 	// Sequence per libpsyx PutDispEnv: DrawArea TL → DrawArea BR → Mask → DrawArea TL → DrawArea BR
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port),
@@ -36,7 +36,7 @@ MipsAtomComp_Proc_(ac_put_disp_env, ab, {
 })
 
 FI_ Slice_MipsCode ac_put_draw_env(MipsAtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_draw_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	/*
 	* ORIGIN: each code word corresponds to the EXACT value libpsyx's PutDrawEnv function would compute for the same DrawEnv settings.
 	* References:

scripts/build_psyq.ps1

@@ -532,6 +532,7 @@ function build-hello_camera {
 
 	$compile_args = @()
 	$compile_args += $f_debug
+	$compile_args += ($f_define + 'BUILD_DEBUG')
 	$compile_args += $f_optimize_none
 	# $compile_args += $f_optimize_intrinsics
 	# $compile_args += $f_optimize_size

scripts/duffle_isa.lua

@@ -0,0 +1,866 @@
+--- duffle_isa.lua — encoder / GTE / hardware tables.
+
+--- @class InstructionImm
+--- @field arg    integer
+--- @field signed boolean|nil
+--- @field width  integer
+
+--- @class InstructionValue
+--- @field dest      integer
+--- @field op        string
+--- @field sources   integer[]|nil
+--- @field immediate integer|nil
+--- @field source    integer|nil
+
+--- @class InstructionRow
+--- @field cycles        integer
+--- @field kind          string
+--- @field reads         integer[]|nil
+--- @field writes        integer[]|nil
+--- @field imm           InstructionImm[]|nil
+--- @field value         InstructionValue|nil
+--- @field delay_slot    boolean|nil
+--- @field suppress_arg1 table<string, string>|nil  -- bag: GPR ident -> reason
+
+--- @class TapeAtomMacroRow
+--- @field kind  string
+--- @field binds boolean
+
+--- @class GteCommandPort
+--- @field register string
+--- @field role     string
+
+--- @class GteCommandLatch
+--- @field register string
+--- @field required integer
+
+--- @class GteCommandRow
+--- @field aliases string[]
+--- @field cycles  integer
+--- @field inputs  string[]
+--- @field outputs GteCommandPort[]
+--- @field latch   GteCommandLatch[]
+
+--- @class GteCrAliasGroup
+--- @field [1] integer   -- C2 control-register slot
+--- @field [2] string[]  -- aliases that share that slot
+
+--- @class GtePackedSlotRelation
+--- @field slot   integer
+--- @field first  string
+--- @field second string
+
+--- @class HardwareRelationPort
+--- @field domain string
+--- @field arg    integer
+
+--- @class HardwareRelationVisibility
+--- @field kind     string
+--- @field required integer
+
+--- @class HardwareRelationEvidence
+--- @field confidence string
+--- @field source     string
+
+--- @class HardwareRelationRow
+--- @field id                string
+--- @field semantic          string
+--- @field consumer          string
+--- @field token             string
+--- @field direction         string
+--- @field reads             HardwareRelationPort
+--- @field writes            HardwareRelationPort
+--- @field visibility        HardwareRelationVisibility|nil
+--- @field evidence          HardwareRelationEvidence
+--- @field violation_kind    string
+--- @field destination_match string|nil
+--- @field fanout_to         string[]|nil
+--- @field required          integer|nil
+--- @field clear_on_consumer boolean|nil
+--- @field stage             boolean|nil
+--- @field cu2_transition    boolean|nil
+--- @field status_register   integer|nil
+
+--- @class Cu2TransitionPolicy
+--- @field status_register integer
+--- @field enable_bit      integer
+--- @field required        integer
+--- @field visibility_kind string
+--- @field evidence        HardwareRelationEvidence
+
+--- @class GprRole
+--- @field name     string
+--- @field pool     boolean
+--- @field optional boolean
+--- @field carrier  boolean
+
+--- @class DuffleIsa
+--- @field GPR_ROLE                    table<string, GprRole>
+--- @field TAPE_ATOM_MACROS            table<string, TapeAtomMacroRow>
+--- @field DELAY_MARKERS               table<string, boolean>
+--- @field INSTRUCTION                 table<string, InstructionRow>
+--- @field GTE_COMMAND                 table<string, GteCommandRow>
+--- @field ALIAS_TO_CANONICAL          table<string, string>
+--- @field instr                       fun(ident: string): InstructionRow|nil
+--- @field gte_canon                   fun(ident: string): string
+--- @field gte                         fun(ident: string): GteCommandRow|nil
+--- @field GTE_CR_ALIAS_GROUPS         GteCrAliasGroup[]
+--- @field GTE_PACKED_SLOT_RELATIONS   GtePackedSlotRelation[]
+--- @field OPERAND_READ_POSITIONS      table<string, integer[]>
+--- @field GP0_CMD_SIZE                table<integer, integer>
+--- @field GP0_CMD_BY_SHAPE            table<string, integer>
+--- @field UNKNOWN_INSTRUCTION_CYCLES  integer
+--- @field HARDWARE_RELATIONS          HardwareRelationRow[]
+--- @field CU2_TRANSITION_POLICY       Cu2TransitionPolicy
+
+local M = {} ---@type DuffleIsa
+
+-- Section 7: domain tables
+-- ════════════════════════════════════════════════════════════════════════════
+
+-- One GprRole row per name. Construction order is the auto_reg pool order,
+-- then R_AT, then the three carriers. Index by name into M.GPR_ROLE.
+--- @type table<string, GprRole>
+M.GPR_ROLE = {
+	{ name = "R_V0",          pool = true,  optional = true, carrier = false },
+	{ name = "R_V1",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T0",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T1",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T2",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T3",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T4",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T5",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T6",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T7",          pool = true,  optional = true, carrier = false },
+	{ name = "R_A0",          pool = true,  optional = true, carrier = false },
+	{ name = "R_A1",          pool = true,  optional = true, carrier = false },
+	{ name = "R_A2",          pool = true,  optional = true, carrier = false },
+	{ name = "R_A3",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S0",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S1",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S2",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S3",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S4",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S5",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S6",          pool = true,  optional = true, carrier = false },
+	{ name = "R_S7",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T8",          pool = true,  optional = true, carrier = false },
+	{ name = "R_T9",          pool = true,  optional = true, carrier = false },
+	{ name = "R_AT",          pool = false, optional = true, carrier = false },
+	{ name = "R_TapePtr",     pool = false, optional = true, carrier = true  },
+	{ name = "R_AtomJmp",     pool = false, optional = true, carrier = true  },
+	{ name = "R_ScratchBase", pool = false, optional = true, carrier = true  },
+}
+for _, row in ipairs(M.GPR_ROLE) do ---@type integer, GprRole
+	M.GPR_ROLE[row.name] = row
+end
+
+-- atom_info sub-calls: atom_bind, atom_reads, atom_writes, atom_view, atom_reg_types, atom_ctx, atom_phase.
+--- @type table<string, TapeAtomMacroRow>
+M.TAPE_ATOM_MACROS = {
+	["atom_info"] = { kind = "info", binds = false },
+}
+
+-- Empty C macros that prefix the next encoder. Zero words.
+-- BdSlot_ nop is one nop word. The marker is not the BD instruction.
+--- @type table<string, boolean>  -- bag: marker prefix -> true
+M.DELAY_MARKERS = {
+	["GteDelay_"] = true,
+	["LdSlot_"]   = true,
+	["BdSlot_"]   = true,
+	["DmaSlot_"]  = true,
+}
+
+-- One row per encoder. Read through duffle.instr.
+--- @type table<string, InstructionRow>
+M.INSTRUCTION = {
+	["BdSlot_"]            = { cycles = 0,  kind = "marker", },
+	["LdSlot_"]            = { cycles = 0,  kind = "marker", },
+	["add_s"]              = { cycles = 1,  kind = "alu", },
+	["add_si"]             = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm = { { arg = 3, signed = true, width  = 16, },}, },
+	["add_u"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["add_u_self"]         = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 },                                                       value = { dest = 1, op = "add_u", sources = { 1, 2 }, }, },
+	["add_ui"]             = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm   = { { arg = 3, signed = true, width = 16, }, }, value = { dest = 1, immediate = 3, op = "add_ui", source = 2, }, },
+	["add_ui_self"]        = { cycles = 1,  kind = "alu",        reads = { 1 },    writes = { 1 }, imm   = { { arg = 2, signed = true, width = 16, }, }, value = { dest = 1, immediate = 2, op = "add_ui", source = 1, },  },
+	["and"]                = { cycles = 1,  kind = "alu", },
+	["and_i"]              = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm   = { { arg = 3, width = 16, }, },                value = { dest = 1, immediate = 3, op = "and_i", source = 2, }, },
+	["and_u"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["atom_bind"]          = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["atom_info"]          = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["atom_label"]         = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["atom_offset"]        = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["atom_reads"]         = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["atom_writes"]        = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["branch_equal"]       = { cycles = 2,  kind = "branch",     reads = { 1, 2 }, writes = {}, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["branch_ge_zero"]     = { cycles = 2,  kind = "branch",     reads = { 1 },    writes = {}, imm = { { arg = 2, signed = true, width = 16, }, }, },
+	["branch_gt_zero"]     = { cycles = 2,  kind = "branch",     reads = { 1 },    writes = {}, imm = { { arg = 2, signed = true, width = 16, }, }, },
+	["branch_le_zero"]     = { cycles = 2,  kind = "branch",     reads = { 1 },    writes = {}, imm = { { arg = 2, signed = true, width = 16, }, }, },
+	["branch_lt_zero"]     = { cycles = 2,  kind = "branch",     reads = { 1 },    writes = {}, imm = { { arg = 2, signed = true, width = 16, }, }, },
+	["branch_ne"]          = { cycles = 2,  kind = "branch",     reads = { 1, 2 }, writes = {}, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["call_addr"]          = { cycles = 2,  kind = "call",       reads = {},       writes = { 1 }, },
+	["call_reg"]           = { cycles = 2,  kind = "call",       reads = { 1 },    writes = { 2 }, },
+	["div_s"]              = { cycles = 35, kind = "alu",        reads = { 1, 2 }, writes = {}, },
+	["div_u"]              = { cycles = 35, kind = "alu",        reads = { 1, 2 }, writes = {}, },
+	["gte_load_v0"]        = { cycles = 2,  kind = "cop2_xfer",  reads = { 2 },    writes = {}, },
+	["gte_load_v0v1v2"]    = { cycles = 6,  kind = "cop2_xfer",  reads = { 2 },    writes = {}, },
+	["gte_load_v1"]        = { cycles = 2,  kind = "cop2_xfer",  reads = { 2 },    writes = {}, },
+	["gte_load_v2"]        = { cycles = 2,  kind = "cop2_xfer",  reads = { 2 },    writes = {}, },
+	["gte_lw"]             = { cycles = 1,  kind = "load",       reads = { 2 },    writes = {}, },
+	["gte_lwc2"]           = { cycles = 1,  kind = "load", },
+	["gte_mv_from_ctrl_r"] = { cycles = 1,  kind = "cop2_xfer",  reads = {},       writes = { 1 }, },
+	["gte_mv_from_data_r"] = { cycles = 1,  kind = "cop2_xfer",  reads = {},       writes = { 1 }, },
+	["gte_mv_to_ctrl_r"]   = { cycles = 1,  kind = "cop2_xfer",  reads = { 1 },    writes = {}, },
+	["gte_mv_to_data_r"]   = { cycles = 1,  kind = "cop2_xfer",  reads = { 1 },    writes = {}, },
+	["gte_stotz"]          = { cycles = 1,  kind = "cop2_xfer",  reads = {},       writes = {}, },
+	["gte_stsxy3"]         = { cycles = 1,  kind = "cop2_xfer",  reads = {},       writes = {}, },
+	["gte_sw"]             = { cycles = 1,  kind = "store",      reads = { 2 },    writes = {}, },
+	["gte_swc2"]           = { cycles = 1,  kind = "store", },
+	["jump"]               = { cycles = 2,  kind = "jump",       reads = {},       writes = {}, },
+	["jump_link"]          = { cycles = 2,  kind = "call",       reads = { 1 },    writes = { 2 }, },
+	["jump_reg"]           = { cycles = 2,  kind = "jump",       reads = { 1 },    writes = {}, suppress_arg1 = { R_AtomJmp = "fixed mac_yield handshake", }, },
+	["jump_rel"]           = { cycles = 2,  kind = "branch", delay_slot = true, },
+	["li_s"]               = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, value = { dest = 1, immediate = 3, op = "add_ui", source = 2, }, },
+	["load_byte"]          = { cycles = 1,  kind = "load",       reads = { 2 },    writes = { 1 }, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["load_byte_u"]        = { cycles = 1,  kind = "load",       reads = { 2 },    writes = { 1 }, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["load_half"]          = { cycles = 1,  kind = "load",       reads = { 2 },    writes = { 1 }, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["load_half_u"]        = { cycles = 1,  kind = "load",       reads = { 2 },    writes = { 1 }, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["load_imm"]           = { cycles = 2,  kind = "alu",        reads = {},       writes = { 1 }, },
+	["load_ui"]            = { cycles = 1,  kind = "alu",        reads = {},       writes = { 1 }, },
+	["load_upper_i"]       = { cycles = 1,  kind = "alu",        reads = {},       writes = { 1 }, imm = { { arg = 2, width = 16, }, }, value = { dest = 1, immediate = 2, op = "load_upper_i", }, },
+	["load_word"]          = { cycles = 1,  kind = "load",       reads = { 2 },    writes = { 1 }, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["mac_yield"]          = { cycles = 0,  kind = "marker",     reads = {},       writes = {}, },
+	["mask_upper"]         = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, },
+	["mov_from_high"]      = { cycles = 2,  kind = "alu",        reads = {},       writes = { 1 }, },
+	["mov_from_low"]       = { cycles = 2,  kind = "alu",        reads = {},       writes = { 1 }, },
+	["mov_to_high"]        = { cycles = 1,  kind = "alu",        reads = { 1 },    writes = {}, },
+	["mov_to_low"]         = { cycles = 1,  kind = "alu",        reads = { 1 },    writes = {}, },
+	["mult_s"]             = { cycles = 12, kind = "alu",        reads = { 1, 2 }, writes = {}, },
+	["mult_u"]             = { cycles = 12, kind = "alu",        reads = { 1, 2 }, writes = {}, },
+	["nop"]                = { cycles = 1,  kind = "nop",        reads = {},       writes = {}, },
+	["nop2"]               = { cycles = 2,  kind = "nop",        reads = {},       writes = {}, },
+	["nor_u"]              = { cycles = 1,  kind = "alu", },
+	["or_i"]               = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm = { { arg = 3, width = 16, }, }, value = { dest = 1, immediate = 3, op = "or_i", source = 2, }, },
+	["or_i_self"]          = { cycles = 1,  kind = "alu",        reads = { 1 },    writes = { 1 }, imm = { { arg = 2, width = 16, }, }, value = { dest = 1, immediate = 2, op = "or_i", source = 1, }, },
+	["or_u"]               = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["or_u_self"]          = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, value = { dest = 1, op = "or", sources = { 1, 2 }, }, },
+	["set_lt_s"]           = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["set_lt_si"]          = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, },
+	["set_lt_u"]           = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["set_lt_ui"]          = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, },
+	["shift_aright"]       = { cycles = 1,  kind = "alu",        reads = { 2 },    writes = { 1 }, imm = { { arg = 3, width = 5, }, }, },
+	["shift_aright_var"]   = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, imm = { { arg = 3, width = 5, }, }, },
+	["shift_lleft"]        = { cycles = 1,  kind = "alu",        reads = { 2 },    writes = { 1 }, imm = { { arg = 3, width = 5, }, }, },
+	["shift_lleft_self"]   = { cycles = 1,  kind = "alu",        reads = { 1 },    writes = { 1 }, imm = { { arg = 2, width = 5, }, }, value = { dest = 1, immediate = 2, op = "shift_lleft", source = 1, }, },
+	["shift_lleft_var"]    = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["shift_lright"]       = { cycles = 1,  kind = "alu",        reads = { 2 },    writes = { 1 }, imm = { { arg = 3, width = 5, }, }, },
+	["slt_s"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["slt_si"]             = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["slt_u"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["slt_ui"]             = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm = { { arg = 3, signed = true, width = 16,}, }, },
+	["store_byte"]         = { cycles = 1,  kind = "store",      reads = { 1, 2 }, writes = {},    imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["store_half"]         = { cycles = 1,  kind = "store",      reads = { 1, 2 }, writes = {},    imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["store_word"]         = { cycles = 1,  kind = "store",      reads = { 1, 2 }, writes = {},    imm = { { arg = 3, signed = true, width = 16, }, }, },
+	["sub_s"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["sub_u"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+	["sys_mov_from_cop0"]  = { cycles = 1,  kind = "cop0_xfer",  reads = {},       writes = { 1 }, },
+	["sys_mov_to_cop0"]    = { cycles = 1,  kind = "cop0_xfer",  reads = { 1 },    writes = {}, },
+	["xor_i"]              = { cycles = 1,  kind = "alu",        reads = { 1, 2 }, writes = { 1 }, imm = { { arg = 3, width = 16, }, }, value = { dest = 1, immediate = 3, op = "xor_i", source = 2, }, },
+	["xor_u"]              = { cycles = 1,  kind = "alu",        reads = { 2, 3 }, writes = { 1 }, },
+}
+
+-- One row per GTE command. Alias cycle numbers live here, not on INSTRUCTION.
+--- @type table<string, GteCommandRow>
+M.GTE_COMMAND = {
+	["gte_cmdw_avsz3"] = {
+		aliases = { "gte_avg_sort_z3", "gte_avsz3", "gte_cmdw_avg_sort_z3" },
+		cycles  = 5,
+		inputs  = { "C2_SZ0", "C2_SZ1", "C2_SZ2", "C2_SZ3", "gte_cr_ZSF3" },
+		outputs = {
+			{ register = "C2_OTZ", role = "otz", },
+		},
+		latch = {
+			{ register = "C2_OTZ", required = 4, },
+		},
+	},
+	["gte_cmdw_avsz4"] = {
+		aliases = { "gte_avg_sort_z4", "gte_avsz4", "gte_cmdw_avg_sort_z4" },
+		cycles  = 6,
+		inputs  = { "C2_SZ0", "C2_SZ1", "C2_SZ2", "C2_SZ3", "gte_cr_ZSF4" },
+		outputs = {
+			{ register = "C2_OTZ", role = "otz", },
+		},
+		latch = {
+			{ register = "C2_OTZ", required = 4, },
+		},
+	},
+	["gte_cmdw_gpf"] = {
+		aliases = {},
+		cycles = 5,
+		inputs = { "C2_IR0", "C2_IR1", "C2_IR2", "C2_IR3" },
+		outputs = {
+			{ register = "C2_MAC1", role = "mac_result", },
+			{ register = "C2_MAC2", role = "mac_result", },
+			{ register = "C2_MAC3", role = "mac_result", },
+			{ register = "C2_IR1", role = "latest_color", },
+			{ register = "C2_IR2", role = "latest_color", },
+			{ register = "C2_IR3", role = "latest_color", },
+		},
+		latch = {
+			{ register = "C2_MAC1", required = 4, },
+			{ register = "C2_MAC2", required = 4, },
+			{ register = "C2_MAC3", required = 4, },
+			{ register = "C2_IR1",  required = 4, },
+			{ register = "C2_IR2",  required = 4, },
+			{ register = "C2_IR3",  required = 4, },
+		},
+	},
+	["gte_cmdw_mvmva"] = {
+		aliases = {},
+		cycles = 8,
+		inputs = { 
+			"C2_VXY0", "C2_VZ0",
+			"C2_VXY1", "C2_VZ1",
+			"C2_VXY2", "C2_VZ2",
+			"C2_IR1", "C2_IR2", "C2_IR3",
+			"gte_cr_RT11", "gte_cr_RT12", "gte_cr_RT13",
+			"gte_cr_RT21", "gte_cr_RT22", "gte_cr_RT23",
+			"gte_cr_RT31", "gte_cr_RT32", "gte_cr_RT33",
+			"gte_cr_TRX", "gte_cr_TRY", "gte_cr_TRZ"
+		},
+		outputs = {
+			{ register = "C2_IR1", role = "latest_color", },
+			{ register = "C2_IR2", role = "latest_color", },
+			{ register = "C2_IR3", role = "latest_color", },
+		},
+		latch = {
+			{ register = "C2_IR1", required = 4, },
+			{ register = "C2_IR2", required = 4, },
+			{ register = "C2_IR3", required = 4, },
+		},
+	},
+	["gte_cmdw_nclip"] = {
+		aliases = { "gte_nclip" },
+		cycles  = 8,
+		inputs  = { "C2_SXY0", "C2_SXY1", "C2_SXY2" },
+		outputs = {
+			{ register = "C2_SZ3", role = "mac_result", },
+		},
+		latch = {
+			{ register = "C2_SZ3", required = 4, },
+		},
+	},
+	["gte_cmdw_op"] = {
+		aliases = { "gte_cmdw_outer_product", "gte_cmdw_wedge" },
+		cycles  = 6,
+		inputs  = {},
+		outputs = {
+			{ register = "C2_IR1", role = "latest_color", },
+			{ register = "C2_IR2", role = "latest_color", },
+			{ register = "C2_IR3", role = "latest_color", },
+		},
+		latch = {
+			{ register = "C2_IR1", required = 4, },
+			{ register = "C2_IR2", required = 4, },
+			{ register = "C2_IR3", required = 4, },
+		},
+	},
+	["gte_cmdw_rtps"] = {
+		aliases = { "gte_cmdw_rotate_translate_perspective_single", "gte_rtps" },
+		cycles = 15,
+		inputs = { 
+			"C2_VXY0", "C2_VZ0",
+			"C2_VXY1", "C2_VZ1",
+			"C2_VXY2", "C2_VZ2",
+			"C2_RGB", "C2_OTZ",
+			"C2_IR0", "C2_IR1", "C2_IR2", "C2_IR3",
+			"C2_SZ0", "C2_SZ1", "C2_SZ2", "C2_SZ3",
+			"gte_cr_RT11", "gte_cr_RT12", "gte_cr_RT13",
+			"gte_cr_RT21", "gte_cr_RT22", "gte_cr_RT23",
+			"gte_cr_RT31", "gte_cr_RT32", "gte_cr_RT33",
+			"gte_cr_TRX", "gte_cr_TRY", "gte_cr_TRZ",
+			"gte_cr_OFX", "gte_cr_OFY",
+			"gte_cr_H",
+			"gte_cr_DQA", "gte_cr_DQB" 
+		},
+		outputs = {
+			{ register = "C2_SXY2", role = "latest_screen_xy", },
+			{ register = "C2_SZ2",  role = "latest_screen_z", },
+			{ register = "C2_OTZ",  role = "otz", },
+			{ register = "C2_IR0",  role = "latest_color", },
+		},
+		latch = {
+			{ register = "C2_SXY2", required = 4, },
+			{ register = "C2_SZ2",  required = 4, },
+			{ register = "C2_OTZ",  required = 4, },
+			{ register = "C2_IR0",  required = 4, },
+		},
+	},
+	["gte_cmdw_rtpt"] = {
+		aliases = { "gte_cmdw_rotate_translate_perspective_triple", "gte_rtpt" },
+		cycles = 23,
+		inputs = { 
+			"C2_VXY0", "C2_VZ0",
+			"C2_VXY1", "C2_VZ1",
+			"C2_VXY2", "C2_VZ2",
+			"C2_RGB",  "C2_OTZ",
+			"C2_IR0",  "C2_IR1", "C2_IR2", "C2_IR3",
+			"C2_SZ0",  "C2_SZ1", "C2_SZ2", "C2_SZ3",
+			"gte_cr_RT11", "gte_cr_RT12", "gte_cr_RT13",
+			"gte_cr_RT21", "gte_cr_RT22", "gte_cr_RT23",
+			"gte_cr_RT31", "gte_cr_RT32", "gte_cr_RT33",
+			"gte_cr_TRX",  "gte_cr_TRY",  "gte_cr_TRZ",
+			"gte_cr_OFX",  "gte_cr_OFY",
+			"gte_cr_H",
+			"gte_cr_DQA", "gte_cr_DQB"
+		},
+		outputs = {
+			{ register = "C2_SXY0", role = "screen_xy[0]", },
+			{ register = "C2_SXY1", role = "screen_xy[1]", },
+			{ register = "C2_SXY2", role = "latest_screen_xy", },
+			{ register = "C2_SZ3",  role = "latest_screen_z", },
+			{ register = "C2_OTZ",  role = "otz", },
+		},
+		latch = {
+			{ register = "C2_SXY0", required = 4, },
+			{ register = "C2_SXY1", required = 4, },
+			{ register = "C2_SXY2", required = 4, },
+			{ register = "C2_SZ3",  required = 4, },
+			{ register = "C2_OTZ",  required = 4, },
+		},
+	},
+	["gte_cmdw_sqr"] = {
+		aliases = {},
+		cycles  = 5,
+		inputs  = { "C2_IR1", "C2_IR2", "C2_IR3" },
+		outputs = {
+			{ register = "C2_MAC1", role = "mac_result", },
+			{ register = "C2_MAC2", role = "mac_result", },
+			{ register = "C2_MAC3", role = "mac_result", },
+			{ register = "C2_IR1",  role = "latest_color", },
+			{ register = "C2_IR2",  role = "latest_color", },
+			{ register = "C2_IR3",  role = "latest_color", },
+		},
+		latch = {
+			{ register = "C2_MAC1", required = 4, },
+			{ register = "C2_MAC2", required = 4, },
+			{ register = "C2_MAC3", required = 4, },
+			{ register = "C2_IR1",  required = 4, },
+			{ register = "C2_IR2",  required = 4, },
+			{ register = "C2_IR3",  required = 4, },
+		},
+	},
+}
+
+--- @param ident string
+--- @return InstructionRow|nil
+function M.instr    (ident) return M.INSTRUCTION            [ident]          end
+--- @param ident string
+--- @return string
+function M.gte_canon(ident) return M.ALIAS_TO_CANONICAL     [ident] or ident end
+--- @param ident string
+--- @return GteCommandRow|nil
+function M.gte      (ident) return M.GTE_COMMAND[M.gte_canon(ident)]         end
+
+--- @return nil
+local function build_alias_map()
+	--- @type table<string, string>  -- bag: alias or canon -> canon
+	M.ALIAS_TO_CANONICAL = {}
+	for canon, row in pairs(M.GTE_COMMAND) do ---@type string, GteCommandRow
+		M.ALIAS_TO_CANONICAL[canon] = canon
+		for _, alias in ipairs(row.aliases or {}) do ---@type integer, string
+			M.ALIAS_TO_CANONICAL[alias] = canon
+		end
+	end
+end
+build_alias_map()
+
+
+--- GTE control-register alias groups.
+--- Aliases within a group write to the same C2 control-register slot (the HW double-maps some C2 slots across multiple PSX SDK / libgte conventions).
+--- Aliases across groups write to distinct C2 slots.
+---
+--- Cross-alias writes inside one atom body, or across the wave-context boundary, silently clobber each other.
+--- The `check_gte_cr_alias_writes` check warns about each pair per source. See `docs/gte_reference.md` §"Control-register alias table"
+--- for the HW rationale and the libgte outer-product convention.
+--- @type GteCrAliasGroup[]
+M.GTE_CR_ALIAS_GROUPS = {
+	{ 24, { "gte_cr_RBK", "gte_cr_OFX" } },   -- background R vs screen offset X
+	{ 25, { "gte_cr_GBK", "gte_cr_OFY" } },   -- background G vs screen offset Y
+	{ 26, { "gte_cr_BBK", "gte_cr_H"   } },   -- background B vs projection plane distance H
+}
+
+-- Packed RT slots named by the gte.h packed-slot comment. First must be written before second.
+--- @type GtePackedSlotRelation[]
+M.GTE_PACKED_SLOT_RELATIONS = {
+	{ slot = 2, first = "gte_cr_RT13", second = "gte_cr_RT22" },
+}
+
+-- Operand-class table for the COP2->GPR load-delay check.
+-- Maps each emitting-token ident to the set of GPR operand positions it reads.
+-- Covers the current encoder vocabulary (`code/duffle/mips.h` + `code/duffle/gte.h`); add rows here as new encoders land.
+--
+-- Semantics:
+--   * A "GPR operand position" is the textual slot in the macro's argument list, 1-based; e.g. `load_word(rt, base, off)` has positional operands 1 (rt), 2 (base), 3 (off).
+--     The table reads operands 1 + 2 + 3 to find what GPRs the macro touches.
+--   * The check tracks one entry per destination GPR per MFC2 / CFC2 event.
+--     A subsequent event counts as a "use" iff any of its read operand positions reference that destination GPR's ident (e.g. `R_T0`).
+--   * Branch delay slots are out of scope (MIPS control-flow; tracked separately).
+--- @type table<string, integer[]>  -- bag: encoder ident -> GPR operand positions
+M.OPERAND_READ_POSITIONS = {
+	-- CPU ALU with one or two GPR operands. Reads every GPR operand.
+	["add_ui"]                 = {1, 2},
+	["li_s"]                   = {1, 2},  -- rt (write), imm16 (immediate)
+	["add_ui_self"]            = {1},
+	["add_si"]                 = {1, 2},
+	["add_u"]                  = {1, 2, 3},
+	["add_u_self"]             = {1, 2},
+	["sub_s"]                  = {1, 2, 3},
+	["sub_u"]                  = {1, 2, 3},
+	["and_i"]                  = {1, 2},
+	["and"]                    = {1, 2, 3},
+	["or_i"]                   = {1, 2},
+	["or_i_self"]              = {1},
+	["or"]                     = {1, 2, 3},
+	["or_self"]                = {1, 2},
+	["xor_i"]                  = {1, 2},
+	["xor"]                    = {1, 2, 3},
+	["slt_s"]                  = {1, 2, 3},
+	["slt_u"]                  = {1, 2, 3},
+	["slt_si"]                 = {1, 2},
+	["slt_ui"]                 = {1, 2},
+	["mult_s"]                 = {1, 2},
+	["mult_u"]                 = {1, 2},
+	["div_s"]                  = {1, 2},
+	["div_u"]                  = {1, 2},
+	-- Shifts: shift_lleft(rd, rt, shamt); the rt operand is the value, rd is dest.
+	["shift_lleft"]            = {1, 2},
+	["shift_lright"]           = {1, 2},
+	["shift_aright"]           = {1, 2},
+	["shift_lleft_self"]       = {1},
+	-- Loads: load_word(rt, base, off); the rt operand is the destination (it's written, not read) and base + off are non-GPR operands.
+	-- The check treats the rt operand as a write, so the read-positions table for `load_*` is empty.
+	["load_word"]              = {},
+	["load_half_u"]            = {},
+	["load_byte_u"]            = {},
+	["load_half"]              = {},
+	["load_byte"]              = {},
+	["load_upper_i"]           = {},
+	["load_ui"]                = {},
+	-- Stores write to memory; base + rt operands are non-read for load-delay purposes.
+	["store_word"]             = {},
+	["store_half"]             = {},
+	["store_byte"]             = {},
+	-- Branches read rs (+ rt for beq/bne). The branch delay slot is out of scope.
+	["branch_equal"]           = {1, 2},
+	["branch_ne"]              = {1, 2},
+	["branch_le_zero"]         = {1},
+	["branch_lt_zero"]         = {1},
+	["branch_ge_zero"]         = {1},
+	["branch_gt_zero"]         = {1},
+	-- Jumps / link: jr / jalr read rs only (the target). RD is the destination link.
+	["jump_reg"]               = {1},
+	["jump_link"]              = {1},
+	["call_reg"]               = {1},
+	["call_addr"]              = {},
+	["jump"]                   = {},
+	-- mask_upper is a 2-word macro: shift_lleft then shift_lright. The first reads rt.
+	["mask_upper"]             = {1, 2},
+	-- move from/to HI/LO.
+	["mov_from_high"]          = {},
+	["mov_from_low"]           = {},
+	["mov_to_high"]            = {1},
+	["mov_to_low"]             = {1},
+	-- GTE transfers / loads / stores / commands: the relevant table values live in the check itself.
+	-- `gte_mv_to_*` writes its rt operand; `gte_mv_from_*` writes its rt operand; `gte_*` commands are atomic-from-the-CPU-POV
+	-- once they issue (the CPU holds until the command completes, so load-delay violations don't surface here).
+	["gte_mv_from_data_r"]     = {},
+	["gte_mv_from_ctrl_r"]     = {},
+	["gte_mv_to_data_r"]       = {},
+	["gte_mv_to_ctrl_r"]       = {},
+	["gte_lw"]                 = {},
+	["gte_sw"]                 = {},
+	["shift_lleft_var"]        = {1, 2, 3},  -- rd, rt, rs (variable shift amount)
+	["shift_aright_var"]       = {1, 2, 3},
+}
+
+-- GP0 packet sizes (total words including the 1-word tag) per GP0 cmd byte.
+-- Per PSX-SPX `docs/psx-spx/docs/graphicsprocessingunitgpu.md` §"GPU Render Polygon Commands":
+--   Each polygon command's word count = 1 (tag/cmd) + per-vertex (vertex + optional color + optional UV).
+--   F3:  cmd + 3 vertices = 4 words; +1 tag = 5
+--   F4:  cmd + 4 vertices = 5 words; +1 tag = 6
+--   G3:  cmd + 3×(color + vertex) = 6 words; +1 tag = 7
+--   G4:  cmd + 4×(color + vertex) = 8 words; +1 tag = 9
+--   FT3: cmd + tpage + clut + 3×(vertex + UV) = 7 words; +1 tag = 8
+--   FT4: cmd + tpage + clut + 4×(vertex + UV) = 9 words; +1 tag = 10
+--   GT3: cmd + tpage + clut + 3×(color + vertex + UV) = 9 words; +1 tag = 10
+--   GT4: cmd + tpage + clut + 4×(color + vertex + UV) = 12 words; +1 tag = 13
+--
+-- Cross-checked against code/duffle/gp.h struct sizes + the set_poly_* macros
+-- (which encode "len" = "words after tag"):
+--   set_poly_f3(p)   -> set_len(p, 4)   ->  5 total GP0 0x20
+--   set_poly_ft3(p)  -> set_len(p, 7)   ->  8 total GP0 0x24
+--   set_poly_f4(p)   -> set_len(p, 5)   ->  6 total GP0 0x28
+--   set_poly_ft4(p)  -> set_len(p, 9)   -> 10 total GP0 0x2C
+--   set_poly_g3(p)   -> set_len(p, 6)   ->  7 total GP0 0x30
+--   set_poly_gt3(p)  -> set_len(p, 9)   -> 10 total GP0 0x34
+--   set_poly_g4(p)   -> set_len(p, 8)   ->  9 total GP0 0x38
+--   set_poly_gt4(p)  -> set_len(p, 12)  -> 13 total GP0 0x3C
+--- @type table<integer, integer>  -- bag: GP0 cmd byte -> word count
+M.GP0_CMD_SIZE = {
+	[0x20] =  5,  -- Poly_F3
+	[0x24] =  8,  -- Poly_FT3
+	[0x28] =  6,  -- Poly_F4
+	[0x2C] = 10,  -- Poly_FT4
+	[0x30] =  7,  -- Poly_G3
+	[0x34] = 10,  -- Poly_GT3
+	[0x38] =  9,  -- Poly_G4
+	[0x3C] = 13,  -- Poly_GT4
+}
+
+-- Shape suffix (after `ac_format_` / `mac_format_` prefix) -> GP0 cmd byte.
+-- Lets the static-analysis check derive the cmd byte from a macro name like `mac_format_g4_color` -> `g4` -> 0x38 -> 9 expected words.
+--- @type table<string, integer>  -- bag: shape suffix -> GP0 cmd byte
+M.GP0_CMD_BY_SHAPE = {
+	["f3"]  = 0x20, ["ft3"] = 0x24,
+	["f4"]  = 0x28, ["ft4"] = 0x2C,
+	["g3"]  = 0x30, ["gt3"] = 0x34,
+	["g4"]  = 0x38, ["gt4"] = 0x3C,
+}
+
+--- @type integer
+M.UNKNOWN_INSTRUCTION_CYCLES = 1
+
+-- Hardware-relation policy table.
+--
+-- The forward walker in `passes/static_analysis.lua::analyze_hardware_relations` reads every emitted word_event, matches its `encoder` against `row.token`, and:
+--   * stages the event as a producer in `atom.paths.forward_state`; or
+--   * matches it as a consumer against pending producers and records a hazard on `atom.paths.hazards` when the gap is below `visibility.required`.
+--
+-- Each row is the contract for one CPU-to-coprocessor transfer semantic (the coprocessor-to-CPU path mirrors the same shape).
+-- The `reads` / `writes` sub-tables carry the argument positions the analyzer inspects:
+--   * `writes.arg` is the destination operand (the producer's effect); the analyzer stages this register as a pending producer.
+--   * `reads` (when present) lists the operand positions the same token reads back from hardware; for MTC2 / CTC2 the producer reads the GPR source it is loading from.
+--     The `fanout_to` field (MTC2-IRGB row only) tells the consumer-match logic which downstream COP2 registers are transitively updated by the write.
+--
+-- Visibility semantics:
+--   * `kind = "post_producer_words"` means the consumer observes the producer's effect after `required` independent emitted words that are
+--     strictly between the producer and the consumer. The producer's own emitted slot is implicit (it counts as the slot of issue, not toward `required`) 
+--     per the PSX-SPX rule: "Store delays are counted in numbers of clock cycles (not in numbers of opcodes).
+--     For 3 cycle delay, one must usually insert 3 cached opcodes (or one uncached opcode)."
+--   * `required` is the minimum count of intervening emitted words between producer and consumer.
+--     `required = 0` permits the consumer on the very next slot; `required < 0` would place the consumer on the same slot as the producer
+--     and is reserved for future "self-retires" relations.
+--
+-- Evidence:
+--   * `evidence.confidence` is one of `"exact"`, `"conservative"`, `"unknown"`. The severity comes from `violation_kind`;
+--     A hardware measurement that the vendor caveats may still classify as `"conservative"` even when the underlying timing is numerically known.
+--   * `evidence.source` is the upstream reference (file + line range) the row is sourced from. New rows must carry this citation.
+--
+-- Consumers:
+--   * passes/static_analysis.lua::analyze_hardware_relations          (forward walker).
+--   * passes/static_analysis.lua::transfer_hazards CHECK_RULES reader (renders hazards onto `findings`).
+-- This table is consumed by the hardware-relation analyzer and hazard renderer.
+--- @type HardwareRelationRow[]
+M.HARDWARE_RELATIONS = {
+	-- CPU → COP2 data register (MTC2). The ordinary default is 2 cached words between producer and consumer (cpuspecifications.md:407-419).
+	{
+		id             = "mtc2_gpr_visibility",
+		semantic       = "MTC2",
+		consumer       = "cop2_input",
+		token          = "gte_mv_to_data_r",
+		direction      = "gpr_to_cop2_data",
+		reads          = { domain = "gpr",       arg = 1 },
+		writes         = { domain = "cop2.data", arg = 2 },
+		visibility     = { kind = "post_producer_words", required = 2 },
+		evidence       = {
+			confidence = "exact",
+			source     = "cpuspecifications.md:407-419",
+		},
+		violation_kind = "error",
+	},
+	-- CPU → COP2 data register when the destination is C2_IRGB (data 28).
+	-- C2_IRGB drives the IR1/IR2/IR3 color-conversion fan-out, which extends the propagation delay to 3 cached words.
+	-- `destination_match = "C2_IRGB"` is the row's filter; the analyzer consults this when the producer's destination operand equals "C2_IRGB".
+	-- C2_ORGB (data 29) is read-only and is never classified as a writable fan-out destination.
+	{
+		id              = "mtc2_irgb_visibility",
+		semantic        = "MTC2",
+		consumer        = "cop2_input",
+		token           = "gte_mv_to_data_r",
+		direction       = "gpr_to_cop2_data",
+		reads           = { domain = "gpr",       arg = 1 },
+		writes          = { domain = "cop2.data", arg = 2 },
+		destination_match = "C2_IRGB",
+		fanout_to       = { "C2_IR1", "C2_IR2", "C2_IR3" },
+		visibility      = { kind = "post_producer_words", required = 3 },
+		evidence        = {
+			confidence = "exact",
+			source     = "cpuspecifications.md:407-419",
+		},
+		violation_kind  = "error",
+	},
+	-- CPU → COP2 control register (CTC2). Ordinary minimum 2;
+	-- no IRGB-style fan-out exists for control registers (per spec §3.6: only C2_IRGB has the 3-cycle fan-out on the data side).
+	{
+		id             = "ctc2_gpr_visibility",
+		semantic       = "CTC2",
+		consumer       = "cop2_input",
+		token          = "gte_mv_to_ctrl_r",
+		direction      = "gpr_to_cop2_control",
+		reads          = { domain = "gpr",        arg = 1 },
+		writes         = { domain = "cop2.ctrl",  arg = 2 },
+		visibility     = { kind = "post_producer_words", required = 2 },
+		evidence       = {
+			confidence = "exact",
+			source     = "cpuspecifications.md:407-419",
+		},
+		violation_kind = "error",
+	},
+	-- COP2 data → GPR (MFC2). One cached slot between the transfer and the first GPR consumer;
+	-- the GPR is not updated until the instruction AFTER the MFC2 completes (geometrytransformationenginegte.md:29-32).
+	{
+		id             = "mfc2_gpr_visibility",
+		semantic       = "MFC2",
+		consumer       = "gpr_read",
+		token          = "gte_mv_from_data_r",
+		direction      = "cop2_data_to_gpr",
+		reads          = { domain = "cop2.data",  arg = 2 },
+		writes         = { domain = "gpr",        arg = 1 },
+		visibility     = { kind = "post_producer_words", required = 1 },
+		evidence       = {
+			confidence = "exact",
+			source     = "geometrytransformationenginegte.md:29-32",
+		},
+		violation_kind = "error",
+	},
+	-- COP2 control → GPR (CFC2). Same delay as MFC2 (cpuspecifications.md treats the two load-from-COP2 paths symmetrically).
+	{
+		id             = "cfc2_gpr_visibility",
+		semantic       = "CFC2",
+		consumer       = "gpr_read",
+		token          = "gte_mv_from_ctrl_r",
+		direction      = "cop2_control_to_gpr",
+		reads          = { domain = "cop2.ctrl",  arg = 2 },
+		writes         = { domain = "gpr",        arg = 1 },
+		visibility     = { kind = "post_producer_words", required = 1 },
+		evidence       = {
+			confidence = "exact",
+			source     = "cpuspecifications.md:382-419",
+		},
+		violation_kind = "error",
+	},
+	-- COP0 control → GPR (MFC0).
+	-- One cached slot; the analyzer treats `sys_mov_from_cop0(rt, 12)` (the SR/CU2 transfer) as the same shape as the COP2 load-delay path.
+	-- The semantic-level SR/CU2 transition models the load delay;
+	-- SR.CU2 bounded-value propagation is modeled separately).
+	{
+		id             = "mfc0_gpr_visibility",
+		semantic       = "MFC0",
+		consumer       = "gpr_read",
+		token          = "sys_mov_from_cop0",
+		direction      = "cop0_control_to_gpr",
+		reads          = { domain = "cop0.ctrl",  arg = 2 },
+		writes         = { domain = "gpr",        arg = 1 },
+		visibility     = { kind = "post_producer_words", required = 1 },
+		evidence       = {
+			confidence = "exact",
+			source     = "cpuspecifications.md:171-178",
+		},
+		violation_kind = "error",
+	},
+	-- Memory -> COP2 data register (LWC2).
+	-- The memory-side timing is not measured by the vendored GTE latch experiment, so this relation has no numeric retirement threshold.
+	-- The LWC2 destination has TWO retirement regimes (per PSX-SPX):
+	--   * GTE-command consumer (`gte_cmdw_*`): the GTE pipeline LATCHES the LWC2 result, so a `gte_cmdw_*`
+	--     in the very next slot uses the latched value. Gap = 0 is allowed. (Per `docs/psx-spx/docs/gtepipelinetimings.md:271-274`.)
+	--   * Any other consumer: standard MIPS load delay applies. Gap = 1 required. (Per `docs/psx-spx/docs/cpuspecifications.md:407-419`.)
+	-- Two separate relations so the walker can dispatch by consumer type and emit different severities
+	-- (the GTE-command path is `info` because the latch is intentional; the non-GTE-consumer path is `error` because the missing nop is a real bug).
+	{
+		id             = "lwc2_to_gte_command",
+		semantic       = "LWC2_to_GTE",
+		consumer       = "cop2_input",
+		token          = "gte_lw",
+		direction      = "memory_to_cop2_data",
+		reads          = { domain = "memory",    arg = 2 },
+		writes         = { domain = "cop2.data", arg = 1 },
+		required       = 0,  -- GTE-command consumer: gap = 0 OK (latched).
+		evidence       = {
+			confidence = "measured",
+			source     = "gtepipelinetimings.md:271-274",
+		},
+		violation_kind = "info",
+		clear_on_consumer = true,
+	},
+	{
+		id             = "lwc2_to_other_consumer",
+		semantic       = "LWC2_to_other",
+		consumer       = "cop2_input",
+		token          = "gte_lw",
+		direction      = "memory_to_cop2_data",
+		reads          = { domain = "memory",    arg = 2 },
+		writes         = { domain = "cop2.data", arg = 1 },
+		required       = 1,  -- Non-GTE-consumer: standard MIPS load delay.
+		evidence       = {
+			confidence = "inferred",
+			source     = "cpuspecifications.md:407-419",
+		},
+		violation_kind = "error",
+		clear_on_consumer = true,
+	},
+	-- COP2 data register -> memory (SWC2). A read of C2 state, not a CPU-to-COP2 write.
+	-- The policy row stays in for direction/provenance; staging it as a later command-input producer is suppressed.
+	{
+		id             = "swc2_memory_write",
+		semantic       = "SWC2",
+		consumer       = "gpr_read",
+		token          = "gte_sw",
+		direction      = "cop2_data_to_memory",
+		reads          = { domain = "cop2.data", arg = 1 },
+		writes         = { domain = "memory",    arg = 2 },
+		visibility     = { kind = "none", required = 0 },
+		evidence       = {
+			confidence = "exact",
+			source     = "cpuspecifications.md:79",
+		},
+		violation_kind = "info",
+		stage          = false,
+	},
+	-- MTC0 Status/SR.CU2. The ordinary COP0 store has no general store-delay relation;
+	-- this row feeds the dedicated CU2 transition logic in the same forward walk and is therefore not staged in `pending`.
+	{
+		id             = "mtc0_cu2_visibility",
+		semantic       = "MTC0",
+		consumer       = "gpr_read",
+		token          = "sys_mov_to_cop0",
+		direction      = "gpr_to_cop0_status",
+		reads          = { domain = "gpr",          arg = 1 },
+		writes         = { domain = "cop0.status",  arg = 2 },
+		status_register = 12,
+		visibility     = { kind = "post_producer_words", required = 2 },
+		evidence       = {
+			confidence = "conservative",
+			source     = "cpuspecifications.md:543,625-628",
+		},
+		violation_kind = "warning",
+		stage          = false,
+		cu2_transition = true,
+	},
+ }
+
+-- Bounded Status/SR.CU2 transition policy.
+-- The value lattice and the transition consumer both read this immutable row; no second value pass is permitted.
+-- The source says the enable/disable transition takes "2 clock cycles or so", so the boundary is conservative rather than exact.
+--- @type Cu2TransitionPolicy
+M.CU2_TRANSITION_POLICY = {
+	status_register = 12,
+	enable_bit      = 0x40000000,
+	required        = 2,
+	visibility_kind = "post_producer_words",
+	evidence        = {
+		confidence = "conservative",
+		source     = "cpuspecifications.md:543,625-628",
+	},
+}
+
+return M

scripts/duffle_paths.lua

@@ -16,30 +16,31 @@
 --- Net effect: the caller gets the duffle module in one statement; no separate `dofile(...)` + `require("duffle")` dance.
 ---
 
-local M = {}
+--- @class DufflePaths
+--- @field setup fun(): nil
+
+local M = {} ---@type DufflePaths
 
 -- Cache key for the repo root. Stored in `package.loaded` (process-global) so all 8 entry scripts + passes scripts share one resolution.
-local CACHE_KEY = "__duffle_repo_root__"
+local CACHE_KEY = "__duffle_repo_root__" ---@type string
 
 --- Resolve the repo root from this script's own path. Zero shell spawn.
---- `duffle_paths.lua` always lives at `<repo>/scripts/duffle_paths.lua`, so the repo root is the
---- parent of the directory containing this script. We derive it directly from `debug.getinfo(1, "S").source`
---- (returns `@<path>` for the currently-running chunk).
+--- `duffle_paths.lua` always lives at `<repo>/scripts/duffle_paths.lua`, so the repo root is the parent of the directory containing this script.
+--- We derive it directly from `debug.getinfo(1, "S").source` (returns `@<path>` for the currently-running chunk).
 ---
---- If `debug.getinfo` can't parse this script's path (shouldn't happen — dofile always populates source),
---- return nil and let `M.setup()` fail loud.
+--- If `debug.getinfo` can't parse this script's path (shouldn't happen — dofile always populates source), return nil and let `M.setup()` fail loud.
 --- @return string|nil
 local function find_repo_root()
 	if package.loaded[CACHE_KEY] then return package.loaded[CACHE_KEY] end
 
-	local source = debug.getinfo(1, "S").source
+	local source = debug.getinfo(1, "S").source ---@type string
 	-- Strip the leading `@` (Lua's dofile marker) and the trailing `/duffle_paths.lua` filename.
 	-- What remains is the directory containing this script, i.e. `<repo>/scripts/`.
-	local scripts_dir = source and source:match("^@?(.*)[/\\]duffle_paths%.lua$")
+	local scripts_dir = source and source:match("^@?(.*)[/\\]duffle_paths%.lua$") ---@type string|nil
 	if not scripts_dir then return nil end
 
 	-- The repo root is the parent of `scripts/`. Strip the trailing `scripts/` (with or without trailing slash).
-	local root = scripts_dir:gsub("scripts[\\/]?$", "")
+	local root = scripts_dir:gsub("scripts[\\/]?$", "") ---@type string
 	root = root:gsub("\\", "/")
 	if root == "" then root = "./" end
 	if not root:match("/$") then root = root .. "/" end
@@ -51,22 +52,19 @@ end
 ---
 --- This script does NOT touch the OS environment: no `os.setenv`, no `os.putenv`, no `$PATH` mods. 
 --- It just sets `package.path` and `package.cpath` (the standard Lua way to register module search dirs). 
---- lpeg is built by `update_deps.ps1` to `toolchain/lpeg/`, 
---- which we wire into `package.cpath` here (so `require("lpeg")` from `duffle.lua` resolves without any global state).
+--- lpeg is built by `update_deps.ps1` to `toolchain/lpeg/`, which we wire into `package.cpath` here (so `require("lpeg")` from `duffle.lua` resolves without any global state).
+--- @return nil
 function M.setup()
-	local  repo_root = find_repo_root()
+	local  repo_root = find_repo_root() ---@type string|nil
 	if not repo_root then
-		-- Unreachable in practice: find_repo_root() derives the repo root from this script's
-		-- own source path via debug.getinfo(1, "S").source (no subprocess, no git CLI, <1ms).
-		-- A nil return means the source path did not match the expected
-		-- <repo>/scripts/duffle_paths.lua layout — a packaging bug, not a "missing git repo"
-		-- condition. os.exit(2) is retained so a real failure surfaces loud rather than
-		-- silently producing an unconfigured module table.
+		-- Unreachable in practice: find_repo_root() derives the repo root from this script's own source path via debug.getinfo(1, "S").source (no subprocess, no git CLI, <1ms).
+		-- A nil return means the source path did not match the expected <repo>/scripts/duffle_paths.lua layout — a packaging bug, not a "missing git repo" condition.
+		-- os.exit(2) is retained so a real failure surfaces loud rather than silently producing an unconfigured module table.
 		os.exit(2)
 	end
 
-	local scripts_dir = repo_root .. "scripts/"
-	local passes_dir  = repo_root .. "scripts/passes/"
+	local scripts_dir = repo_root .. "scripts/"        ---@type string
+	local passes_dir  = repo_root .. "scripts/passes/" ---@type string
 	package.path = scripts_dir .. "?.lua;"
 		.. scripts_dir .. "?/init.lua;"
 		.. passes_dir  .. "?.lua;"
@@ -76,8 +74,8 @@ function M.setup()
 	-- lpeg: built by `update_deps.ps1` to `toolchain/lpeg/lpeg.dll`.
 	-- lfs: compiled from pcsx-redux's vendored luafilesystem source to `toolchain/lfs/lfs.dll`.
 	-- Wire both directories into cpath so `require("lpeg")` and `require("lfs")` resolve.
-	local lpeg_dir = repo_root .. "toolchain/lpeg/"
-	local lfs_dir  = repo_root .. "toolchain/lfs/"
+	local lpeg_dir = repo_root .. "toolchain/lpeg/" ---@type string
+	local lfs_dir  = repo_root .. "toolchain/lfs/"  ---@type string
 	package.cpath = lpeg_dir .. "?.dll;"
 		.. lfs_dir  .. "?.dll;"
 		.. package.cpath
@@ -86,6 +84,6 @@ end
 -- Run the setup as a side effect.
 M.setup()
 
--- Now that package.path includes scripts/, `require("duffle")` resolves. Return the duffle module
--- so callers can do `local duffle = dofile(...duffle_paths.lua)` in one line.
+-- Now that package.path includes scripts/, `require("duffle")` resolves.
+-- Return the duffle module so callers can do `local duffle = dofile(...duffle_paths.lua)` in one line.
 return require("duffle")

scripts/elf32.lua

@@ -22,7 +22,94 @@
 -- spec: System V ABI gABI v1.2 §"ELF Header" (Table 1) + §"Section Header Table"
 -- spec: System V ABI gABI v1.2 §"Symbol Table" (Elf32_Sym layout)
 
-local M = {}
+--- @class Elf32Adapter
+--- @field read_u8_at  fun(off: integer): integer|nil
+--- @field read_u16_at fun(off: integer): integer|nil
+--- @field read_u32_at fun(off: integer): integer|nil
+--- @field read_size   fun(): integer
+
+--- @class Elf32Header
+--- @field e_entry     integer
+--- @field e_shoff     integer
+--- @field e_shentsize integer
+--- @field e_shnum     integer
+--- @field e_shstrndx  integer
+--- @field error       string|nil
+
+--- @class Elf32Section
+--- @field sh_name   integer
+--- @field sh_type   integer
+--- @field sh_flags  integer
+--- @field sh_addr   integer
+--- @field sh_offset integer
+--- @field sh_size   integer
+--- @field sh_link   integer
+--- @field name      string
+
+--- @class Elf32Sym
+--- @field value integer
+--- @field size  integer
+--- @field info  integer
+--- @field shndx integer
+
+--- @class Elf32HeaderLayout
+--- @field magic_offset       integer
+--- @field magic              string
+--- @field class_offset       integer
+--- @field endian_offset      integer
+--- @field header_bytes       integer
+--- @field e_entry_offset     integer
+--- @field e_shoff_offset     integer
+--- @field e_shentsize_offset integer
+--- @field e_shnum_offset     integer
+--- @field e_shstrndx_offset  integer
+
+--- @class Elf32SectionLayout
+--- @field sh_name_offset   integer
+--- @field sh_type_offset   integer
+--- @field sh_flags_offset  integer
+--- @field sh_addr_offset   integer
+--- @field sh_offset_offset integer
+--- @field sh_size_offset   integer
+--- @field sh_link_offset   integer
+--- @field sh_entsize_bytes integer
+
+--- @class Elf32SymLayout
+--- @field st_name         integer
+--- @field st_value        integer
+--- @field st_size         integer
+--- @field st_info         integer
+--- @field sym_entry_bytes integer
+
+--- @class Elf32Mod
+--- @field ELFCLASS32             integer
+--- @field ELFDATA2LSB            integer
+--- @field EM_MIPS                integer
+--- @field SHT_SYMTAB             integer
+--- @field SHT_STRTAB             integer
+--- @field SHT_NOBITS             integer
+--- @field SHF_WRITE              integer
+--- @field SHF_ALLOC              integer
+--- @field SHF_EXECINSTR          integer
+--- @field ELF32_HEADER           Elf32HeaderLayout
+--- @field ELF32_SECTION          Elf32SectionLayout
+--- @field ELF32_SYM              Elf32SymLayout
+--- @field dw_dwarf32_terminator  integer
+--- @field read_u32               fun(adapter: Elf32Adapter, off: integer): integer|nil
+--- @field read_u16               fun(adapter: Elf32Adapter, off: integer): integer|nil
+--- @field read_u8                fun(adapter: Elf32Adapter, off: integer): integer|nil
+--- @field size                   fun(adapter: Elf32Adapter): integer
+--- @field read_u32_le            fun(buf: string, off: integer): integer
+--- @field read_u16_le            fun(buf: string, off: integer): integer
+--- @field validate_adapter       fun(adapter: any): boolean, string|nil
+--- @field get_str                fun(strtab: string, off: integer): string|nil
+--- @field parse_elf32_headers    fun(adapter: Elf32Adapter): Elf32Header|nil, string|nil
+--- @field walk_sections          fun(adapter: Elf32Adapter, hdr: Elf32Header): Elf32Section[]|nil, string|nil
+--- @field read_section_bytes     fun(adapter: Elf32Adapter, section: Elf32Section): string|nil
+--- @field read_named_section     fun(adapter: Elf32Adapter, sections: Elf32Section[], name: string): string|nil, string|nil
+--- @field collect_symbols        fun(adapter: Elf32Adapter, sections: Elf32Section[]): table<string, Elf32Sym>|nil, string|nil
+
+local M = {} ---@type Elf32Mod
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Little-endian readers (bit-weighted accumulator, math.floor only)
@@ -39,7 +126,7 @@ local M = {}
 --- **Call form:** explicit-pass. The reader receives `adapter` as the first positional argument and the offset as the second; no `self` is passed.
 --- Test fixtures declare `function(offset) ... end` and the parsers call them via dot syntax `adapter.read_u8_at(off)`.
 --- The colon form `adapter:read_u8_at(off)` would prepend the adapter table as `offset` and break the contract.
---- @param adapter table
+--- @param adapter Elf32Adapter
 --- @param off     integer  -- zero-based wire offset
 --- @return integer|nil
 function M.read_u32(adapter, off)
@@ -50,7 +137,7 @@ function M.read_u32(adapter, off)
 end
 
 --- Read a 2-byte little-endian unsigned integer from `adapter` at zero-based wire offset `off`.
---- @param adapter table
+--- @param adapter Elf32Adapter
 --- @param off integer  -- zero-based wire offset
 --- @return integer|nil
 function M.read_u16(adapter, off)
@@ -59,7 +146,7 @@ function M.read_u16(adapter, off)
 end
 
 --- Read a 1-byte unsigned integer from `adapter` at zero-based wire offset `off`.
---- @param adapter table
+--- @param adapter Elf32Adapter
 --- @param off integer  -- zero-based wire offset
 --- @return integer|nil
 function M.read_u8(adapter, off)
@@ -67,7 +154,7 @@ function M.read_u8(adapter, off)
 end
 
 --- Total adapter byte length.
---- @param adapter table
+--- @param adapter Elf32Adapter
 --- @return integer
 function M.size(adapter)
 	return adapter.read_size()
@@ -76,8 +163,11 @@ end
 --- Forwarders kept for backward compat with scripts/elf_dwarf.lua.
 --- The metaprogram side keeps `read_u32_le` / `read_u16_le`;
 --- both layers now use the same byte-level helpers under the hood.
+--- @param buf string
+--- @param off integer
+--- @return integer
 function M.read_u32_le(buf, off)
-	local byte_off = off + 1
+	local byte_off = off + 1 ---@type integer
 	return buf:byte(byte_off)
 		+ buf:byte(byte_off + 0x01) * 0x00000100
 		+ buf:byte(byte_off + 0x02) * 0x00010000
@@ -89,7 +179,7 @@ end
 --- @param off integer  -- zero-based wire offset
 --- @return integer
 function M.read_u16_le(buf, off)
-	local byte_off = off + 1
+	local byte_off = off + 1 ---@type integer
 	return buf:byte(byte_off) + buf:byte(byte_off + 0x01) * 0x00000100
 end
 
@@ -116,6 +206,7 @@ M.SHF_EXECINSTR = 0x4 -- spec: gABI v1.2 §"Section Attributes" — executable
 -- ELF32 header layout (System V ABI gABI v1.2 §"ELF Header" Table 1)
 -- ---------------------------------------------------------------------------
 -- All offsets are zero-based wire offsets. The header is 52 bytes total (header_bytes = 0x34 = 52).
+--- @type Elf32HeaderLayout
 M.ELF32_HEADER = {
 	magic_offset         = 0x00,  -- 4 bytes; expected "\127ELF"
 	magic                = "\127ELF",
@@ -134,6 +225,7 @@ M.ELF32_HEADER = {
 -- ---------------------------------------------------------------------------
 -- Each entry is 40 bytes (sh_entsize_bytes = 0x28 = 40);
 -- zero-based, field offsets relative to the start of the entry.
+--- @type Elf32SectionLayout
 M.ELF32_SECTION = {
 	sh_name_offset    = 0x00,  -- 4-byte LE; offset into .shstrtab
 	sh_type_offset    = 0x04,  -- 4-byte LE; section type (SHT_*)
@@ -150,6 +242,7 @@ M.ELF32_SECTION = {
 -- ---------------------------------------------------------------------------
 -- Each entry is 16 bytes (sym_entry_bytes = 0x10 = 16);
 -- zero-based, field offsets relative to the start of the entry.
+--- @type Elf32SymLayout
 M.ELF32_SYM = {
 	st_name          = 0x00,  -- 4-byte LE; offset into the linked string table
 	st_value         = 0x04,  -- 4-byte LE; symbol value (address / absolute)
@@ -190,7 +283,7 @@ end
 --- @return string|nil
 function M.get_str(strtab, off)
 	if off < 0 or off >= #strtab then return nil end
-	local  end_pos = strtab:find("\0", off + 1, true)
+	local  end_pos = strtab:find("\0", off + 1, true) ---@type integer|nil
 	if not end_pos then return nil end
 	return strtab:sub(off + 1, end_pos - 1)
 end
@@ -205,39 +298,39 @@ end
 --- On failure returns nil + a stable error code:
 ---   bad_magic, unsupported_elf_class, unsupported_elf_data, truncated_header
 --- The header's machine field is NOT validated here — callers (e.g. the helper's prime path) decide whether to require EM_MIPS before symbol reads.
---- @param adapter table
---- @return table|nil, string|nil
+--- @param adapter Elf32Adapter
+--- @return Elf32Header|nil, string|nil
 function M.parse_elf32_headers(adapter)
-	local  ok, err = M.validate_adapter(adapter)
+	local  ok, err = M.validate_adapter(adapter) ---@type boolean, string|nil
 	if not ok then return nil, err end
 
 	-- 4-byte magic: 0x7F 'E' 'L' 'F'.
 	-- The byte readers take the adapter explicitly.
 	-- The production `Support.File` adapter is wrapped by the caller to drop its implicit `self` so the parser shape is flat pass-style.
-	local b1 = M.read_u8(adapter, 0)
-	local b2 = M.read_u8(adapter, 1)
-	local b3 = M.read_u8(adapter, 2)
-	local b4 = M.read_u8(adapter, 3)
+	local b1 = M.read_u8(adapter, 0) ---@type integer|nil
+	local b2 = M.read_u8(adapter, 1) ---@type integer|nil
+	local b3 = M.read_u8(adapter, 2) ---@type integer|nil
+	local b4 = M.read_u8(adapter, 3) ---@type integer|nil
 	if not (b1 and b2 and b3 and b4)
 		or not (b1 == 0x7f and b2 == 0x45 and b3 == 0x4c and b4 == 0x46) then
 		return nil, "bad_magic"
 	end
 
-	local class = M.read_u8(adapter, M.ELF32_HEADER.class_offset)
+	local class = M.read_u8(adapter, M.ELF32_HEADER.class_offset) ---@type integer|nil
 	if    class ~= M.ELFCLASS32 then
 		return nil, "unsupported_elf_class"
 	end
 
-	local data = M.read_u8(adapter, M.ELF32_HEADER.endian_offset)
+	local data = M.read_u8(adapter, M.ELF32_HEADER.endian_offset) ---@type integer|nil
 	if    data ~= M.ELFDATA2LSB then
 		return nil, "unsupported_elf_data"
 	end
 
-	local e_entry     = M.read_u32(adapter, M.ELF32_HEADER.e_entry_offset)
-	local e_shoff     = M.read_u32(adapter, M.ELF32_HEADER.e_shoff_offset)
-	local e_shentsize = M.read_u16(adapter, M.ELF32_HEADER.e_shentsize_offset)
-	local e_shnum     = M.read_u16(adapter, M.ELF32_HEADER.e_shnum_offset)
-	local e_shstrndx  = M.read_u16(adapter, M.ELF32_HEADER.e_shstrndx_offset)
+	local e_entry     = M.read_u32(adapter, M.ELF32_HEADER.e_entry_offset)     ---@type integer|nil
+	local e_shoff     = M.read_u32(adapter, M.ELF32_HEADER.e_shoff_offset)     ---@type integer|nil
+	local e_shentsize = M.read_u16(adapter, M.ELF32_HEADER.e_shentsize_offset) ---@type integer|nil
+	local e_shnum     = M.read_u16(adapter, M.ELF32_HEADER.e_shnum_offset)     ---@type integer|nil
+	local e_shstrndx  = M.read_u16(adapter, M.ELF32_HEADER.e_shstrndx_offset)  ---@type integer|nil
 	if not (e_entry and e_shoff and e_shentsize and e_shnum and e_shstrndx) then
 		return nil, "truncated_header"
 	end
@@ -254,11 +347,11 @@ end
 
 --- Read one section-header entry from `adapter` at `sh_off`.
 --- Returns a table with the wire fields plus a (yet-unresolved) `name` field.
---- @param adapter table
+--- @param adapter Elf32Adapter
 --- @param sh_off  integer
---- @return table|nil, string|nil  -- entry, error
+--- @return Elf32Section|nil, string|nil
 local function read_section_entry(adapter, sh_off)
-	local entry = {
+	local entry = { ---@type Elf32Section
 		sh_name   = M.read_u32(adapter, sh_off + M.ELF32_SECTION.sh_name_offset),
 		sh_type   = M.read_u32(adapter, sh_off + M.ELF32_SECTION.sh_type_offset),
 		sh_flags  = M.read_u32(adapter, sh_off + M.ELF32_SECTION.sh_flags_offset),
@@ -279,22 +372,22 @@ end
 --- (the section at logical index 0 is at array position 1, etc.).
 --- Each entry has the wire fields plus a resolved `name` derived from `.shstrtab`.
 --- Returns nil + a stable error code on failure: truncated_section_headers, missing_shstrtab, truncated_strtab
---- @param adapter table
---- @param hdr     table  -- the table returned by parse_elf32_headers
---- @return table|nil, string|nil
+--- @param adapter Elf32Adapter
+--- @param hdr     Elf32Header
+--- @return Elf32Section[]|nil, string|nil
 function M.walk_sections(adapter, hdr)
 	if not hdr or hdr.error then return nil, hdr and hdr.error or "truncated_section_headers" end
 
-	local file_size = M.size(adapter)
+	local file_size = M.size(adapter) ---@type integer
 	if hdr.e_shoff + hdr.e_shnum * hdr.e_shentsize > file_size then
 		return nil, "truncated_section_headers"
 	end
 
 	-- Read every section header first; we need .shstrtab to resolve names.
-	local sections = {}
-	for i = 0, hdr.e_shnum - 1 do
-		local sh_off = hdr.e_shoff + i * hdr.e_shentsize
-		local entry, err = read_section_entry(adapter, sh_off)
+	local sections = {} ---@type Elf32Section[]
+	for i = 0, hdr.e_shnum - 1 do ---@type integer
+		local sh_off = hdr.e_shoff + i * hdr.e_shentsize ---@type integer
+		local entry, err = read_section_entry(adapter, sh_off) ---@type Elf32Section|nil, string|nil
 		if not entry then return nil, err end
 		sections[i + 1] = entry
 	end
@@ -303,17 +396,17 @@ function M.walk_sections(adapter, hdr)
 		return nil, "missing_shstrtab"
 	end
 
-	local  shstrtab = sections[hdr.e_shstrndx + 1]
+	local  shstrtab = sections[hdr.e_shstrndx + 1] ---@type Elf32Section|nil
 	if not shstrtab or shstrtab.sh_type ~= M.SHT_STRTAB then
 		return nil, "missing_shstrtab"
 	end
 	if shstrtab.sh_offset + shstrtab.sh_size > file_size then
 		return nil, "truncated_section_headers"
 	end
-	local  shstrtab_bytes = M.read_section_bytes(adapter, shstrtab)
+	local  shstrtab_bytes = M.read_section_bytes(adapter, shstrtab) ---@type string|nil
 	if not shstrtab_bytes then return nil, "truncated_section_headers" end
 
-	for _, s in ipairs(sections) do
+	for _, s in ipairs(sections) do ---@type integer, Elf32Section
 		s.name = M.get_str(shstrtab_bytes, s.sh_name) or ""
 	end
 
@@ -322,15 +415,15 @@ end
 
 --- Read the bytes of one section. Returns a string, or nil if the adapter returns nil for any byte (out-of-bounds).
 --- The caller is responsible fors sizing the buffer (the section's sh_offset + sh_size must fit in adapter.size).
---- @param adapter table
---- @param section table  -- one entry from walk_sections
+--- @param adapter Elf32Adapter
+--- @param section Elf32Section
 --- @return string|nil
 function M.read_section_bytes(adapter, section)
-	local size = section.sh_size
+	local size = section.sh_size ---@type integer
 	if    size == 0 then return "" end
-	local out = {}
-	for i = 0, size - 1 do
-		local b = M.read_u8(adapter, section.sh_offset + i)
+	local out = {} ---@type string[]
+	for i = 0, size - 1 do ---@type integer
+		local b = M.read_u8(adapter, section.sh_offset + i) ---@type integer|nil
 		if    b == nil then return nil end
 		out[#out + 1] = string.char(b)
 	end
@@ -339,15 +432,15 @@ end
 
 --- Convenience: walk sections, then look up the named section, then read its bytes.
 --- Returns nil + a stable error code if the section is absent or out-of-bounds.
---- @param adapter  table
---- @param sections table  -- 1-based array from walk_sections
+--- @param adapter  Elf32Adapter
+--- @param sections Elf32Section[]
 --- @param name     string
 --- @return string|nil, string|nil
 function M.read_named_section(adapter, sections, name)
 	if not sections then return nil, "missing_section" end
-	for _, s in ipairs(sections) do
+	for _, s in ipairs(sections) do ---@type integer, Elf32Section
 		if   s.name == name then
-			local bytes = M.read_section_bytes(adapter, s)
+			local bytes = M.read_section_bytes(adapter, s) ---@type string|nil
 			if not bytes then return nil, "truncated_section_data" end
 			return bytes, nil
 		end
@@ -359,47 +452,47 @@ end
 --- Each stored entry is `{ value = st_value, size = st_size, info = st_info, shndx = st_shndx }`.
 --- Both STB_LOCAL and STB_GLOBAL symbols are included; the live ELF stores `smem` as a local symbol.
 --- Returns nil + a stable error code on failure: missing_symtab_strtab, truncated_section_headers
---- @param adapter  table
---- @param sections table
---- @return table|nil, string|nil
+--- @param adapter  Elf32Adapter
+--- @param sections Elf32Section[]
+--- @return table<string, Elf32Sym>|nil, string|nil
 function M.collect_symbols(adapter, sections)
 	if not sections then return nil, "missing_sections" end
-	local symbols = {}
-	local file_size = M.size(adapter)
-	for _, s in ipairs(sections) do
+	local symbols   = {}              ---@type table<string, Elf32Sym>  -- bag: symbol name -> Elf32Sym
+	local file_size = M.size(adapter) ---@type integer
+	for _, s in ipairs(sections) do ---@type integer, Elf32Section
 		if s.sh_type == M.SHT_SYMTAB then
-			local  strtab = sections[s.sh_link + 1]
+			local  strtab = sections[s.sh_link + 1] ---@type Elf32Section|nil
 			if not strtab or strtab.sh_type ~= M.SHT_STRTAB then
 				return nil, "missing_symtab_strtab"
 			end
 			if strtab.sh_offset + strtab.sh_size > file_size then
 				return nil, "truncated_section_headers"
 			end
-			local  strtab_bytes = M.read_section_bytes(adapter, strtab)
+			local  strtab_bytes = M.read_section_bytes(adapter, strtab) ---@type string|nil
 			if not strtab_bytes then return nil, "truncated_section_headers" end
 			if s.sh_offset + s.sh_size > file_size then
 				return nil, "truncated_section_headers"
 			end
-			local  symtab_bytes = M.read_section_bytes(adapter, s)
+			local  symtab_bytes = M.read_section_bytes(adapter, s) ---@type string|nil
 			if not symtab_bytes then return nil, "truncated_section_headers" end
-			local n = #symtab_bytes / M.ELF32_SYM.sym_entry_bytes
-			for j = 0, n - 1 do
-				local e = s.sh_offset + j * M.ELF32_SYM.sym_entry_bytes
-				local st_name  = M.read_u32(adapter, e + M.ELF32_SYM.st_name)
+			local n = #symtab_bytes / M.ELF32_SYM.sym_entry_bytes ---@type number
+			for j = 0, n - 1 do ---@type integer
+				local e        = s.sh_offset + j * M.ELF32_SYM.sym_entry_bytes ---@type integer
+				local st_name  = M.read_u32(adapter, e + M.ELF32_SYM.st_name)  ---@type integer|nil
 				if    st_name then
-					local st_value = M.read_u32(adapter, e + M.ELF32_SYM.st_value)
-					local st_size  = M.read_u32(adapter, e + M.ELF32_SYM.st_size)
-					local st_info  = M.read_u8(adapter, e + M.ELF32_SYM.st_info)
+					local st_value = M.read_u32(adapter, e + M.ELF32_SYM.st_value) ---@type integer|nil
+					local st_size  = M.read_u32(adapter, e + M.ELF32_SYM.st_size)  ---@type integer|nil
+					local st_info  = M.read_u8(adapter, e + M.ELF32_SYM.st_info)   ---@type integer|nil
 					-- st_shndx is at offset 14 (2 bytes) — derived from the layout
 					-- the metaprogram reads too. Inline the read to keep the
 					-- adapter as the only I/O surface.
-					local b1 = M.read_u8(adapter, e + 14)
-					local b2 = M.read_u8(adapter, e + 15)
+					local b1 = M.read_u8(adapter, e + 14) ---@type integer|nil
+					local b2 = M.read_u8(adapter, e + 15) ---@type integer|nil
 					if not (b1 and b2) then
 						return nil, "truncated_section_headers"
 					end
-					local st_shndx = b1 + b2 * 0x100
-					local name = M.get_str(strtab_bytes, st_name) or ""
+					local st_shndx = b1 + b2 * 0x100 ---@type integer
+					local name = M.get_str(strtab_bytes, st_name) or "" ---@type string
 					if    name ~= "" then
 						symbols[name] = {
 							value = st_value,

scripts/gdb/gdb_tape_atoms.gdb

@@ -16,7 +16,7 @@ define tape_atoms
   echo "[gdb_tape_atoms] STUB: run .\\build_psyq.ps1 to regenerate, then re-source this file."
 end
 document tape_atoms
-  List every tape atom symbol in the loaded ELF (code_<name>) with its .rodata address and word count.
+  List every tape atom symbol in the loaded ELF with its .rodata address and word count.
   STUB state: runtime file not sourced. Run build_psyq.ps1 to regenerate.
 end
 

scripts/launch_pcsx_debug.ps1

@@ -1,10 +1,9 @@
 # scripts/launch_pcsx_debug.ps1
 #
-# One-shot launcher for debug sessions: starts pcsx-redux with the .ps-exe
-# loaded, the gdb stub enabled, AND the pcsx_debug_helper Lua plugin loaded
-# so external CLI tools (gdb's `shell` command, etc.)
-# can read GTE state via http://localhost:8080/api/v1/lua/gte
-# (the gdb stub doesn't expose COP2 at all).
+# One-shot launcher for debug sessions:
+# Starts pcsx-redux with the .ps-exe loaded, the gdb stub enabled, 
+# AND the pcsx_debug_helper Lua plugin loaded so external CLI tools (gdb's `shell` command, etc.)
+# can read GTE state via http://localhost:8080/api/v1/lua/gte (the gdb stub doesn't expose COP2 at all).
 #
 # usage:
 #   .\scripts\launch_pcsx_debug.ps1
@@ -84,7 +83,8 @@ try {
     $r = Invoke-WebRequest -Uri "http://localhost:$WebPort/api/v1/lua/gte" -UseBasicParsing -TimeoutSec 5
     $firstLine = ([System.Text.Encoding]::UTF8.GetString($r.Content) -split "`n")[0]
     Write-Host "GTE handler OK: $firstLine" -ForegroundColor Green
-} catch {
+}
+catch {
     Write-Warning "GTE handler NOT responding: $_"
     Write-Host "Check the pcsx-redux Lua Console for debug cli messages." -ForegroundColor Yellow
 }

scripts/passes/annotation.lua

@@ -10,8 +10,8 @@
 
 -- Bootstrap follows the entry scripts; `scripts/duffle_paths.lua` sets package.path and package.cpath. See `ps1_meta.lua` for the rationale.
 -- `debug.getinfo(1, "S").source` locates this file for standalone and orchestrated runs, then `duffle_paths.lua` returns the loaded `duffle` module.
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")            ---@type DuffleExport
 
 -- The annotation pass reads the source-derived registries from scan_source:
 --   * pipe_ctx.register_alias_registry — for atom_dbg_reg_default(R_X, ...) and atom_reg_types(R_X, ...) member-identity checks
@@ -21,76 +21,40 @@ local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 
---- @class SourceFile
---- @field path     string  -- Absolute path to the source file
---- @field text     string  -- Full source text
---- @field dir      string  -- Directory containing the source
---- @field basename string  -- Filename without extension
---- @field scan     table   -- Pre-scanned SourceScan payload (from duffle.scan_source)
+-- SourceFile, PassCtx, PassResult, PassShared, Corpus, Finding: see ps1_meta.lua
+-- SourceScan, AtomEntry, AtomInfoEntry, BindsEntry, RegTypeDefault, AtomViewEntry: see scan_source.lua
 
---- @class PassCtx
---- @field sources            SourceFile[]
---- @field metadata_path      string
---- @field shared             table
---- @field shared.word_counts table<string, integer>
---- @field out_root           string
---- @field project_root       string
---- @field upstream           table<string, table>
---- @field flags              table
---- @field verbose            boolean
-
---- @class PassResult
---- @field outputs  table[]
---- @field errors   table[]
---- @field warnings table[]
-
---- @class AtomAnnotation
---- @field line    integer       -- Source line of the atom_info call
---- @field macro   string        -- Macro name (always "atom_info" in the new shape)
---- @field name    string        -- Atom name
---- @field kind    string        -- Always "info"
---- @field binds   string|nil    -- Binds_X name if any
---- @field reads   string[]      -- R_* names (read targets)
---- @field writes  string[]      -- R_* names (write targets)
---- @field errors  string[]|nil  -- Parse-time errors from scan_source (atom_info body malformed)
-
---- @class DebugSkipMarker  -- Sub-shape of scan_source.lua's @class DebugSkipMarker
---- @field marker_kind    string                 -- Exact marker ident read from source. Only "atom_dbg_skip" (bare) is positive.
---- @field marker_line    integer
---- @field args           string|nil             -- Trimmed text inside the parens (nil when has_parens is false)
---- @field has_parens     boolean
---- @field is_bare        boolean                -- true iff marker_kind == "atom_dbg_skip" AND has_parens == false (the only positive form)
---- @field pending        boolean                -- true while awaiting the following declaration
---- @field superseded_by_marker_line integer|nil -- Set on a marker that was bumped out of the pending slot
---- @field target_kind    string|nil             -- "atom" | "comp_bare" | "comp_proc" | "unrelated" once observed
-
---- @class Finding
---- @field line integer -- Source line (or 0 for pass-level)
---- @field msg  string  -- Finding message
+--- @class RegTypeOccurrence
+--- @field reg         string
+--- @field type_name   string
+--- @field source_line integer
 
 --- @class Findings
 --- @field errors   Finding[]
 --- @field warnings Finding[]
 --- @field info     Finding[]
 
---- @class PipeCtx
---- @field atom_index     table<string, AtomAnnotation> -- Name -> AtomAnnotation (only kind=="atom")
---- @field binds_index    table<string, BindsStruct>    -- Name -> BindsStruct
---- @field annot_counts   table<string, integer>        -- Name -> annotation count (for unique_annotation check)
---- @field types          table<string, RegTypeDefault> -- From scan_source
---- @field atom_views     table<string, AtomViewEntry>  -- From scan_source
---- @field seen_defaults  table<string, integer>        -- Duplicate atom_dbg_reg_default detection
---- @field seen_field     table<string, integer>        -- Binds_* -> count of fields (set/checked by check_binds_no_duplicate_fields)
---- @field _scan          SourceScan                    -- Full scan payload (typed-view sub-calls live here) 
+-- PassScratch: see ps1_meta.lua
 
 --- @class AnnotatedResult
 --- @field atoms    AtomEntry[]
---- @field annots   AtomAnnotation[]
+--- @field annots   AtomInfoEntry[]
 --- @field macros   MacroEntry[]
 --- @field binds    BindsEntry[]
 --- @field errors   Finding[]
 --- @field warnings Finding[]
 --- @field info     Finding[]
+--- @field source   string|nil
+
+--- @class CheckRule
+--- @field per_annot (fun(item: AtomInfoEntry, pipe_ctx: PassScratch, findings: Findings): nil)|nil
+
+--- @class SourceScan
+--- @field type_occurrences RegTypeOccurrence[]|nil
+
+--- @class AnnotationPass
+--- @field validate fun(ctx: PassCtx, src: SourceFile, corpus_pipe_ctx: PassScratch|nil): AnnotatedResult
+--- @field run      fun(ctx: PassCtx): PassResult
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Per-check functions (the CHECK_RULES table's payload)
@@ -99,24 +63,27 @@ local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 --- `macro_word_drift` writes errors[] for missing or mismatched metadata and info[] for a match.
 
 --- Check: Every annotated atom must have a matching MipsAtom_(name) declaration.
---- @param a        AtomAnnotation
---- @param pipe_ctx PipeCtx
+--- @param info     AtomInfoEntry
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
-local function check_atom_decl_exists(a, pipe_ctx, findings)
-	if not pipe_ctx.atom_index[a.name] then
+--- @return nil
+local function check_atom_decl_exists(info, pipe_ctx, findings)
+	if not pipe_ctx.atom_index[info.atom_name] then
 		findings.errors[#findings.errors + 1] = {
-			line = a.line,
-			msg  = string.format("annotation for '%s' has no matching MipsAtom_(%s) { ... }", a.name, a.name),
+			line = info.info_line,
+			msg  = string.format("annotation for '%s' has no matching MipsAtom_(%s) { ... }", info.atom_name, info.atom_name),
 		}
 	end
 end
 
 --- Check:     Every atom may have AT MOST ONE annotation.
 --- Post-loop: Needs full-corpus `annot_counts` from pipe_ctx.
---- @param pipe_ctx PipeCtx
+--- @param _item    AtomInfoEntry|nil
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
-local function check_unique_annotation(pipe_ctx, findings)
-	for name, n in pairs(pipe_ctx.annot_counts) do
+--- @return nil
+local function check_unique_annotation(_item, pipe_ctx, findings)
+	for name, n in pairs(pipe_ctx.annot_counts) do ---@type string, integer
 		if n > 1 then
 			findings.errors[#findings.errors + 1] = {
 				line = pipe_ctx.atom_index[name] and pipe_ctx.atom_index[name].line or 0,
@@ -128,27 +95,30 @@ end
 
 --- Check: BIND atoms must reference a real Binds_* struct.
 --- I keep this as a warning so the annotation pass can report the common test-fixture case; `check_abi_handoff` in static analysis supplies the build-stopping error.
---- @param a        AtomAnnotation
---- @param pipe_ctx PipeCtx
+--- @param info     AtomInfoEntry
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
-local function check_binds_struct_exists(a, pipe_ctx, findings)
-	if not a.binds                   then return end
-	if pipe_ctx.binds_index[a.binds] then return end
+--- @return nil
+local function check_binds_struct_exists(info, pipe_ctx, findings)
+	if not info.binds                   then return end
+	if pipe_ctx.binds_index[info.binds] then return end
 	findings.warnings[#findings.warnings + 1] = {
-		line = a.line,
+		line = info.info_line,
 		msg  = string.format("'%s' binds '%s' but no Struct_(%s) { ... } " 
 			.. "declaration found (also flagged as an error by check_abi_handoff in the static-analysis pass)"
-			, a.name, a.binds, a.binds),
+			, info.atom_name, info.binds, info.binds),
 	}
 end
 
 --- Check: TAPE_WORDS(mac_X, N) ↔ WORD_COUNT(mac_X, N) drift.
 --- Three outcomes: missing (error), mismatch (error), match (info).
 --- @param m        MacroEntry
---- @param wc table<string, integer> -- Shared word-count table (from ctx.shared.word_counts)
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
-local function check_macro_word_drift(m, wc, findings)
-	local  declared = wc[m.name]
+--- @return nil
+local function check_macro_word_drift(m, pipe_ctx, findings)
+	local wc = (pipe_ctx and pipe_ctx.word_counts) or {} ---@type WordCounts
+	local  declared = wc[m.name]                         ---@type integer|nil
 	if not declared then
 		findings.errors[#findings.errors + 1] = {
 			line = m.line,
@@ -172,12 +142,13 @@ end
 --- Check: atom_dbg_reg_default(R_X, <type>) targets an alias in `pipe_ctx.register_alias_registry` and a type in `pipe_ctx.type_name_registry`.
 --- Pointer depth remains bounded to 0 or 1, and duplicate defaults remain errors.
 --- @param _src     SourceFile -- unused (kept for the per_source shape)
---- @param pipe_ctx PipeCtx
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
+--- @return nil
 local function check_semantic_reg_defaults(_src, pipe_ctx, findings)
 	-- Detect duplicate defaults using the ordered occurrence list (the out.types hash only retains the last declaration).
-	local seen_first_line = {}
-	for _, occ in ipairs(pipe_ctx.type_occurrences or {}) do
+	local seen_first_line = {}                               ---@type table<string, integer>  -- bag: register ident -> first source line
+	for _, occ in ipairs(pipe_ctx.type_occurrences or {}) do ---@type integer, RegTypeOccurrence
 		if seen_first_line[occ.reg] == nil then
 			seen_first_line[occ.reg] = occ.source_line
 		else
@@ -189,9 +160,9 @@ local function check_semantic_reg_defaults(_src, pipe_ctx, findings)
 			}
 		end
 	end
-	local reg_registry  = pipe_ctx.register_alias_registry or {}
-	local type_registry = pipe_ctx.type_name_registry      or {}
-	for reg, def in pairs(pipe_ctx.types or {}) do
+	local reg_registry  = pipe_ctx.register_alias_registry or {} ---@type table<string, AliasEntry>
+	local type_registry = pipe_ctx.type_name_registry      or {} ---@type table<string, TypeNameEntry>
+	for reg, def in pairs(pipe_ctx.types or {}) do               ---@type string, RegTypeDefault
 		if not reg_registry[reg] then
 			findings.errors[#findings.errors + 1] = {
 				line = def.source_line,
@@ -222,14 +193,15 @@ end
 --- Check: atom_reg_types(R_X, <type>) entries target an alias in `pipe_ctx.register_alias_registry` and a type in `pipe_ctx.type_name_registry`.
 --- A bare `atom_reg` marker opts the `R_<n>` alias into GPR identity; references to R_T0..R_T3 require the same explicit marker.
 --- @param _src     SourceFile
---- @param pipe_ctx PipeCtx
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
+--- @return nil
 local function check_atom_reg_types(_src, pipe_ctx, findings)
-	local reg_registry  = pipe_ctx.register_alias_registry or {}
-	local type_registry = pipe_ctx.type_name_registry      or {}
-	for _, ai in ipairs(pipe_ctx.atom_infos_list or {}) do
+	local reg_registry  = pipe_ctx.register_alias_registry or {} ---@type table<string, AliasEntry>
+	local type_registry = pipe_ctx.type_name_registry      or {} ---@type table<string, TypeNameEntry>
+	for _, ai in ipairs(pipe_ctx.atom_infos_list or {}) do       ---@type integer, AtomInfoEntry
 		if ai.reg_type_overrides then
-			for reg, ov in pairs(ai.reg_type_overrides) do
+			for reg, ov in pairs(ai.reg_type_overrides) do ---@type string, RegTypeOverride
 				if not reg_registry[reg] then
 					findings.errors[#findings.errors + 1] = {
 						line = ai.info_line,
@@ -253,14 +225,15 @@ end
 
 --- Check: atom_view(Binds_X) entries reference a Binds_* struct with at least one field.
 --- @param _src     SourceFile
---- @param pipe_ctx PipeCtx
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
+--- @return nil
 local function check_atom_view_layout(_src, pipe_ctx, findings)
-	for atom_name, view in pairs(pipe_ctx.atom_views or {}) do
+	for atom_name, view in pairs(pipe_ctx.atom_views or {}) do ---@type string, AtomViewEntry
 		if not view.binds_name then
 			-- The atom had atom_reg_types but no atom_view; no layout check needed.
 		else
-			local bs = pipe_ctx.binds_index[view.binds_name]
+			local bs = pipe_ctx.binds_index[view.binds_name] ---@type BindsEntry|nil
 			if not bs then
 				findings.errors[#findings.errors + 1] = {
 					line = view.info_line,
@@ -282,15 +255,16 @@ end
 
 --- Check: Binds_* structs require unique field names because atom_view uses those names for typed-field lookup in gdb.
 --- @param _src     SourceFile
---- @param pipe_ctx PipeCtx
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
+--- @return nil
 local function check_binds_no_duplicate_fields(_src, pipe_ctx, findings)
-	for _, bs in ipairs(pipe_ctx.binds_list or {}) do
-		local seen = {}
-		for _, f in ipairs(bs.fields or {}) do
+	for _, bs in ipairs(pipe_ctx.binds_list or {}) do ---@type integer, BindsEntry
+		local seen = {}                        ---@type table<string, integer>  -- bag: field name -> occurrence count
+		for _, f in ipairs(bs.fields or {}) do ---@type integer, TypeField
 			seen[f.name] = (seen[f.name] or 0) + 1
 		end
-		for name, count in pairs(seen) do
+		for name, count in pairs(seen) do ---@type string, integer
 			if count > 1 then
 				findings.errors[#findings.errors + 1] = {
 					line = bs.line,
@@ -314,11 +288,12 @@ end
 ---   6. unsupported target_kind     -> marker precedes an unrelated declaration
 --- Valid markers stamp `debug_skip` on whole-atom, bare-component, and proc-component declaration records in scan_source.lua.
 --- @param marker    DebugSkipMarker
---- @param _pipe_ctx PipeCtx     -- Unused; kept for consistency with per_annot // TODO(Ed): Remove?
+--- @param _pipe_ctx PassScratch     -- Unused; kept for consistency with per_annot
 --- @param findings  Findings
+--- @return nil
 local function check_skip_marker(marker, _pipe_ctx, findings)
-	local kind = marker.marker_kind
-	local line = marker.marker_line
+	local kind = marker.marker_kind ---@type string
+	local line = marker.marker_line ---@type integer
 	-- Left `scan.debug_skip_markers` with production records for `atom_dbg_skip` only; other identifiers take the walker's unrelated branch.
 
 	if marker.has_parens then
@@ -371,15 +346,16 @@ end
 --- Warn when a source references an unregistered alias.
 --- When a source uses an unregistered R_X, this check emits one pass-level info entry for that source and directs C-ABI register names to explicit alias registration.
 --- @param _src     SourceFile
---- @param pipe_ctx PipeCtx
+--- @param pipe_ctx PassScratch
 --- @param findings Findings
+--- @return nil
 local function check_wave_context_migration(_src, pipe_ctx, findings)
 	if not (pipe_ctx.types and next(pipe_ctx.types)) then return end
 	if not (pipe_ctx.atom_infos_list) then return end
-	local reg_registry = pipe_ctx.register_alias_registry or {}
-	for _, ai in ipairs(pipe_ctx.atom_infos_list) do
+	local reg_registry = pipe_ctx.register_alias_registry or {} ---@type table<string, AliasEntry>
+	for _, ai in ipairs(pipe_ctx.atom_infos_list) do            ---@type integer, AtomInfoEntry
 		if ai.reg_type_overrides then
-			for reg, _ in pairs(ai.reg_type_overrides) do
+			for reg, _ in pairs(ai.reg_type_overrides) do ---@type string, RegTypeOverride
 				if not reg_registry[reg] then
 					findings.warnings[#findings.warnings + 1] = {
 						line = 0,
@@ -399,14 +375,14 @@ end
 -- ════════════════════════════════════════════════════════════════════════════
 --
 -- Each rule entry picks one of four "shapes" of dispatch:
---   per_annot(annot, pipe_ctx, findings)        -- runs once per AtomAnnotation
+--   per_annot(info, pipe_ctx, findings)         -- runs once per scan.atom_infos row
 --   post(pipe_ctx, findings)                    -- runs once after all per_annot calls complete (full-corpus aggregation)
 --   per_macro(macro, wc, findings)              -- runs once per TAPE_WORDS / _Pragma macro declaration
 --   per_skip_marker(marker, pipe_ctx, findings) -- runs once per src.scan.debug_skip_markers entry
 --
 -- Adding a new check = 1 row here + 1 function above. The `validate()` dispatch loop never needs editing.
 
-local CHECK_RULES = {
+local CHECK_RULES = { ---@type CheckRule[]
 	{ name = "atom_decl_exists",          per_annot       = check_atom_decl_exists          },
 	{ name = "binds_struct_exists",       per_annot       = check_binds_struct_exists       },
 	{ name = "unique_annotation",         post            = check_unique_annotation         },
@@ -427,81 +403,35 @@ local CHECK_RULES = {
 --- Builds one pass-wide pipe_ctx from the merged `corpus.*` registries and source-ordered `corpus.atom_infos`; per-source declarations and bodies remain in `src.scan`.
 --- The module ownership contract above requires callers to construct `ctx.shared.corpus` through `build_ctx`; the error message below enforces that gate.
 --- @param ctx PassCtx
---- @return PipeCtx
+--- @return PassScratch
 local function build_corpus_pipe_ctx(ctx)
-	local corpus = ctx.shared and ctx.shared.corpus
-	if not corpus then
-		error("annotation requires ctx.shared.corpus "
-			.. "(the canonical corpus is the source of truth; "
-			.. "no per-source fallback is supported)", 0)
-	end
-
-	-- `corpus.atom_infos` preserves source order and duplicates; I precompute counts here for `check_unique_annotation` and the per-source checks.
-	local annot_counts = {}
-	for _, info in ipairs(corpus.atom_infos or {}) do
+	local view         = duffle.corpus_view(ctx) ---@type PassScratch
+	local annot_counts = {}                      ---@type table<string, integer>  -- bag: atom name -> annotation count
+	for _, info in ipairs(view.atom_infos) do    ---@type integer, AtomInfoEntry
 		if info and info.atom_name then
 			annot_counts[info.atom_name] = (annot_counts[info.atom_name] or 0) + 1
 		end
 	end
-
-	-- Every consumer of these fields observes mutations via the canonical corpus without independently mutable registry construction.
-	return {
-		-- Cross-source lookup tables from corpus.
-		register_alias_registry  = corpus.register_alias_registry or {},
-		type_name_registry       = corpus.type_name_registry      or {},
-		atom_views               = corpus.atom_views              or {},
-		atom_ctxs                = corpus.atom_ctxs               or {},
-		atom_phases              = corpus.atom_phases             or {},
-		binds_by_name            = corpus.binds_by_name           or {},
-		atoms_by_name            = corpus.atoms_by_name           or {},
-		-- Corpus-wide ordered list of atom_info records (source-order + duplicates).
-		atom_infos_list          = corpus.atom_infos              or {},
-		-- Corpus-wide annotation count aggregation (post-rule consumes this).
-		annot_counts             = annot_counts,
-		-- Corpus-wide collisions (recorded by scan_source.merge_corpus_registries).
-		collisions               = corpus.collisions              or {},
-		-- `check_macro_word_drift` reads `corpus.word_counts`, populated by word_count_eval.run.
-		word_counts              = corpus.word_counts or {},
-	}
+	view.annot_counts    = annot_counts
+	view.atom_infos_list = view.atom_infos
+	view.word_counts     = ctx.shared.corpus.word_counts or {}
+	return view
 end
 
 --- Validate one source against its pre-scanned SourceScan payload + the corpus-wide pipe_ctx.
 --- @param ctx             PassCtx
 --- @param src             SourceFile
---- @param corpus_pipe_ctx PipeCtx|nil  -- Built once per pass from corpus registries; nil builds the same projection here.
+--- @param corpus_pipe_ctx PassScratch|nil  -- Built once per pass from corpus registries; nil builds the same projection here.
 --- @return AnnotatedResult
 local function validate(ctx, src, corpus_pipe_ctx)
 	corpus_pipe_ctx = corpus_pipe_ctx or build_corpus_pipe_ctx(ctx)
-	local scan = src.scan
-
-	-- Project the pre-scanned atoms to the AtomEntry shape this pass needs.
-	local atoms = {}
-	for _, a in ipairs(scan.atoms) do
-		if a.kind == "atom" then
-			atoms[#atoms + 1] = { line = a.line, name = a.raw_name }
-		end
-	end
-
-	-- Project the pre-scanned atom_infos to AtomAnnotation shape.
-	local annots = {}
-	for _, info in ipairs(scan.atom_infos) do
-		annots[#annots + 1] = {
-			line   = info.info_line,
-			macro  = "atom_info",
-			name   = info.atom_name,
-			kind   = "info",
-			binds  = info.binds,
-			reads  = info.reads or {},
-			writes = info.writes or {},
-			errors = info.errors,
-		}
-	end
+	local scan = src.scan ---@type SourceScan
 
 	-- Build a per-source pipe_ctx: shared lookups come from `corpus_pipe_ctx`, while declarations, bodies, types, views, defaults, and occurrences come from `src.scan`.
-	local seen_defaults   = {}; for reg, _ in pairs (scan.types      or {}) do seen_defaults[reg] = (seen_defaults[reg] or 0) + 1 end
-	local atom_infos_list = {}; for _, ai  in ipairs(scan.atom_infos or {}) do atom_infos_list[#atom_infos_list + 1] = ai         end
+	local seen_defaults   = {}; for reg, _ in pairs (scan.types      or {}) do seen_defaults[reg] = (seen_defaults[reg] or 0) + 1 end ---@type table<string, integer>  -- bag: register ident -> occurrence count
+	local atom_infos_list = {}; for _, ai  in ipairs(scan.atom_infos or {}) do atom_infos_list[#atom_infos_list + 1] = ai         end ---@type AtomInfoEntry[]
 
-	local pipe_ctx = {
+	local pipe_ctx = { ---@type PassScratch
 		atom_index               = {},
 		binds_index              = {},
 		annot_counts             = corpus_pipe_ctx.annot_counts,
@@ -515,70 +445,66 @@ local function validate(ctx, src, corpus_pipe_ctx)
 		register_alias_registry  = corpus_pipe_ctx.register_alias_registry,
 		type_name_registry       = corpus_pipe_ctx.type_name_registry,
 	}
-	for _, a in ipairs(atoms)      do pipe_ctx.atom_index [a.name] = a end
-	for _, b in ipairs(scan.binds) do pipe_ctx.binds_index[b.name] = b end
+	local atoms = {}                  ---@type AtomEntry[]
+	for _, a in ipairs(scan.atoms) do ---@type integer, AtomEntry
+		if a.kind == "atom" or a.kind == "atom_proc" then
+			atoms[#atoms + 1] = a
+			pipe_ctx.atom_index[a.raw_name or a.name] = a
+		end
+	end
+	for _, b in ipairs(scan.binds) do pipe_ctx.binds_index[b.name] = b end ---@type integer, BindsEntry
 
 	-- Findings live in a single struct with three lists (errors / warnings / info).
 	-- Each check writes to the list appropriate for its severity.
-	local findings = { errors = {}, warnings = {}, info = {} }
+	local findings = { errors = {}, warnings = {}, info = {} } ---@type Findings
 
 	-- Lift parse-time errors already recorded in scan_source's atom_info payload into this pass's findings list.
-	for _, a in ipairs(annots) do
-		if a.errors then
-			for _, msg in ipairs(a.errors) do
+	for _, info in ipairs(scan.atom_infos) do ---@type integer, AtomInfoEntry
+		if info.errors then
+			for _, msg in ipairs(info.errors) do ---@type integer, string
 				findings.errors[#findings.errors + 1] = {
-					line = a.line,
-					msg  = string.format("'%s': %s", a.name, msg),
+					line = info.info_line,
+					msg  = string.format("'%s': %s", info.atom_name, msg),
 				}
 			end
 		end
 	end
 
 	-- THE per-annotation pipeline. ONE loop. CHECK_RULES dispatches per_annot rules.
-	for _, a in ipairs(annots) do
-		for _, rule in ipairs(CHECK_RULES) do
-			if rule.per_annot then rule.per_annot(a, pipe_ctx, findings) end
-		end
+	for _, info in ipairs(scan.atom_infos) do ---@type integer, AtomInfoEntry
+		duffle.run_check_rules(CHECK_RULES, "per_annot", info, pipe_ctx, findings)
 	end
 
 	-- Post-loop rules (one-shot checks that need full-corpus aggregation in pipe_ctx).
-	for _, rule in ipairs(CHECK_RULES) do
-		if rule.post then rule.post(pipe_ctx, findings) end
-	end
+	duffle.run_check_rules(CHECK_RULES, "post", nil, pipe_ctx, findings)
 
 	-- scan_source records each marker in scan.debug_skip_markers; this loop validates each record independently and emits at most one error per marker.
 	-- Valid markers stamp `debug_skip = true` on the following atom or component declaration, which downstream consumers read directly.
-	local skip_markers = scan.debug_skip_markers or {}
-	for _, marker in ipairs(skip_markers) do
-		for _, rule in ipairs(CHECK_RULES) do
-			if rule.per_skip_marker then rule.per_skip_marker(marker, pipe_ctx, findings) end
-		end
+	local skip_markers = scan.debug_skip_markers or {} ---@type DebugSkipMarker[]
+	for _, marker in ipairs(skip_markers) do           ---@type integer, DebugSkipMarker
+		duffle.run_check_rules(CHECK_RULES, "per_skip_marker", marker, pipe_ctx, findings)
 	end
 
 	-- Per-macro rules (TAPE_WORDS vs WORD_COUNT drift).
-	local wc = corpus_pipe_ctx.word_counts
-	for _, m in ipairs(scan.macros) do
-		for _, rule in ipairs(CHECK_RULES) do
-			if rule.per_macro then rule.per_macro(m, wc, findings) end
-		end
+	pipe_ctx.word_counts = corpus_pipe_ctx.word_counts
+	for _, m in ipairs(scan.macros) do ---@type integer, MacroEntry
+		duffle.run_check_rules(CHECK_RULES, "per_macro", m, pipe_ctx, findings)
 	end
 
 	-- Per-source rules (reg defaults, atom_view layout, compute-register type overrides, Binds_* field uniqueness).
 	-- Each per_source rule sees the full scan payload via pipe_ctx.
-	for _, rule in ipairs(CHECK_RULES) do
-		if rule.per_source then rule.per_source(src, pipe_ctx, findings) end
-	end
+	duffle.run_check_rules(CHECK_RULES, "per_source", src, pipe_ctx, findings)
 
 	-- Information summary (always emitted).
 	findings.info[#findings.info + 1] = {
 		line = 0,
 		msg  = string.format("scanned: %d atom(s), %d annotation(s), %d macro-word-decl(s), %d binds struct(s)"
-			, #atoms, #annots, #scan.macros, #scan.binds),
+			, #atoms, #scan.atom_infos, #scan.macros, #scan.binds),
 	}
 
 	return {
 		atoms    = atoms,
-		annots   = annots,
+		annots   = scan.atom_infos,
 		macros   = scan.macros,
 		binds    = scan.binds,
 		errors   = findings.errors,
@@ -591,9 +517,7 @@ end
 -- M.run — orchestrator entry
 -- ════════════════════════════════════════════════════════════════════════════
 
---- @class M
-
-local M = {}
+local M = {} ---@type AnnotationPass
 
 -- Expose `validate` for downstream passes (e.g. report.lua) that need to re-render the per-source results into a per-MODULE report.
 M.validate = validate
@@ -601,32 +525,32 @@ M.validate = validate
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
-	local outputs  = {}
-	local errors   = {}
-	local warnings = {}
+	local outputs  = {} ---@type PassOutputEntry[]
+	local errors   = {} ---@type Finding[]
+	local warnings = {} ---@type Finding[]
 
 	-- Build the shared pipe_ctx once for this run; every validate() call sees the same cross-source registries.
 	-- The corpus owns the canonical cross-source registries; per-source scans retain body / declaration ownership.
-	local corpus_pipe_ctx = build_corpus_pipe_ctx(ctx)
-	local corpus = ctx.shared.corpus
+	local corpus_pipe_ctx = build_corpus_pipe_ctx(ctx) ---@type PassScratch
+	local corpus          = ctx.shared.corpus          ---@type Corpus
 
 	-- Group `corpus.sources_by_dir` by module, validate every source in each bucket, and emit one errors.h per directory.
-	local by_dir = (corpus and corpus.sources_by_dir) or {}
+	local by_dir = (corpus and corpus.sources_by_dir) or {} ---@type table<string, SourceFile[]>
 
-	for dir, dir_sources in pairs(by_dir) do
-		local dir_basename = dir:match("([^/\\]+)$") or dir
-		local dir_atoms    = 0
-		local dir_errors   = {}
-		local dir_warnings = {}
-		for _, src in ipairs(dir_sources) do
-			local result  = validate(ctx, src, corpus_pipe_ctx)
+	for dir, dir_sources in pairs(by_dir) do ---@type string, SourceFile[]
+		local dir_basename = dir:match("([^/\\]+)$") or dir ---@type string
+		local dir_atoms    = 0                              ---@type integer
+		local dir_errors   = {}                             ---@type Finding[]
+		local dir_warnings = {}                             ---@type Finding[]
+		for _, src in ipairs(dir_sources) do                ---@type integer, SourceFile
+			local result  = validate(ctx, src, corpus_pipe_ctx) ---@type AnnotatedResult
 			result.source = src.path                           -- tag for downstream rendering
 			dir_atoms = dir_atoms + #result.atoms
-			for _, e in ipairs(result.errors) do
+			for _, e in ipairs(result.errors) do ---@type integer, Finding
 				dir_errors[#dir_errors + 1] = { line = e.line, msg = e.msg, source = src.path }
 				errors    [#errors     + 1] = { line = e.line, msg = e.msg }
 			end
-			for _, w in ipairs(result.warnings) do
+			for _, w in ipairs(result.warnings) do ---@type integer, Finding
 				dir_warnings[#dir_warnings + 1] = { line = w.line, msg = w.msg }
 				warnings    [#warnings     + 1] = { line = w.line, msg = w.msg }
 			end

scripts/passes/atoms_source_map.lua

@@ -37,9 +37,9 @@
 -- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` 
 -- (works both standalone + when require'd). `duffle_paths.lua` sets package.path then returns `require("duffle")` 
 -- at the bottom, so the dofile value IS the duffle module.
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
-local elf_dwarf      = require("elf_dwarf")
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")            ---@type DuffleExport
+local elf_dwarf      = require("elf_dwarf")                                       ---@type ElfDwarfMod
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
@@ -47,42 +47,78 @@ local elf_dwarf      = require("elf_dwarf")
 
 -- Format version emitted as the first line. Bump + add a migration test if the format changes; 
 -- the gdb runtime loader rejects mismatches (E2).
-local FORMAT_VERSION = 1
+local FORMAT_VERSION = 1 ---@type integer
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- @class AtomSourceMapCtx
---- @field shared             table   -- `ctx.shared`
---- @field shared.corpus      table   -- source-order registry; single writer is build_ctx
---- @field shared.word_counts table
---- @field out_root           string  -- output root (e.g. "build/gen")
---- @field flags              table   -- `ctx.flags`; reads `flags.gdb_runtime` + `flags.elf_path`
+--- @field shared        PassShared
+--- @field out_root      string
+--- @field flags         PassFlags
+--- @field project_root  string|nil
+
+--- @class WordMapEntry
+--- @field pos        integer
+--- @field line       integer
+--- @field text       string
+--- @field body_line  integer
+--- @field gpr_keys   string[]|nil
+--- @field invocation InvocationRecord|nil
+
+--- @class NmAddr
+--- @field [1] integer  -- st_value
+--- @field [2] integer  -- st_size
+
+--- @class GdbAtomRecord
+--- @field idx        integer|nil
+--- @field name       string
+--- @field src_path   string
+--- @field file_base  string
+--- @field addr       integer
+--- @field size_bytes integer
+--- @field words      integer
+--- @field entries    WordMapEntry[]
+
+--- @class ElfDwarfMod
+--- @field read_nm fun(elf_path: Path): table<string, NmAddr>
+
+--- @class AtomSourceMapPass
+--- @field render_source_map      fun(src: SourceFile): string
+--- @field render_provenance      fun(src: SourceFile, wc: WordCounts): string
+--- @field render_atom_source_map fun(atom: AtomEntry): string
+--- @field render_atom_provenance fun(atom: AtomEntry, wc: WordCounts, rel_path: string): string
+--- @field run                    fun(ctx: PassCtx): PassResult
+
+--- @class AtomEntry
+--- @field paths AtomPaths|nil
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Atom-path renderers
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- Join word boundaries (from `items`) to per-word call text + source lines (from `word_events`).
---- @param atom table
---- @return table[], integer
+--- @param atom AtomEntry
+--- @return WordMapEntry[]
+--- @return integer
 local function canonical_word_entries(atom)
-	local paths      = atom.paths or {}
-	local events     = paths.word_events or {}
-	local word_items = {}
-	for _, item in ipairs(paths.items or {}) do
+	local paths      = atom.paths or {}         ---@type AtomPaths
+	local events     = paths.word_events or {}  ---@type WordEvent[]
+	local word_items = {}                       ---@type EmissionItem[]
+	for _, item in ipairs(paths.items or {}) do ---@type integer, EmissionItem
 		if item.kind == "word" then word_items[#word_items + 1] = item end
 	end
 
-	local entries = {}
-	for index, event in ipairs(events) do
-		local item = word_items[index] or {}
+	local entries = {}                    ---@type WordMapEntry[]
+	for index, event in ipairs(events) do ---@type integer, WordEvent
+		local item = word_items[index] or {} ---@type EmissionItem
 		entries[#entries + 1] = {
 			pos        = event.i or (index - 1),
 			line       = event.call_line or item.line or 0,
 			text       = event.call_text or item.call_text or "",
 			body_line  = event.body_line or item.body_line or item.line or 0,
+			gpr_keys   = event.gpr_keys,
 			invocation = (event.outermost_invocation_id
 				and paths.invocations
 				and paths.invocations[event.outermost_invocation_id]) or nil,
@@ -96,19 +132,20 @@ end
 ---   `WORD N  CALL <src-path>:<src-line>  RAW` (raw `.word` outside any mac_* component)
 --- Component identity comes from the outermost invocation record; the count-table lookup confirms the component was declared in `corpus.word_counts` 
 --- (populated by word_count_eval + components passes).
---- @param src  table
---- @param atom table
---- @param wc   table -- identity alias of corpus.word_counts
---- @return string[], integer
+--- @param src  SourceFile
+--- @param atom AtomEntry
+--- @param wc   WordCounts
+--- @return string[]
+--- @return integer
 local function emit_provenance_stanza(src, atom, wc)
-	local lines          = {}
-	local rel_path       = src.path:gsub("\\\\", "/")
-	local entries, total = canonical_word_entries(atom)
+	local lines          = {}                           ---@type string[]
+	local rel_path       = src.path:gsub("\\\\", "/")   ---@type string
+	local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
 	lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
 
-	for _, entry in ipairs(entries) do
-		local inv         = entry.invocation
-		local macro_count = inv and wc["mac_" .. inv.component_name]
+	for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
+		local inv         = entry.invocation                         ---@type InvocationRecord|nil
+		local macro_count = inv and wc["mac_" .. inv.component_name] ---@type integer|nil
 		if inv and macro_count ~= nil then
 			lines[#lines + 1] = string.format('WORD %d  CALL %s:%d  MACRO %s "%s:%d" BODY %d'
 				, entry.pos, rel_path, entry.line, inv.component_name
@@ -124,11 +161,11 @@ local function emit_provenance_stanza(src, atom, wc)
 end
 
 --- Render the full provenance file content for one source.
---- @param src table
---- @param wc  table
+--- @param src SourceFile
+--- @param wc  WordCounts
 --- @return string
 local function render_provenance(src, wc)
-	local lines = {}
+	local lines = {} ---@type string[]
 	lines[#lines + 1] = "# FORMAT_VERSION 1"
 	lines[#lines + 1] = "# auto-generated by ps1_meta.lua (passes/atoms_source_map.lua) — DO NOT EDIT"
 	lines[#lines + 1] = "# Per-.word provenance: maps each emitted .word to its call site (atom body"
@@ -137,14 +174,16 @@ local function render_provenance(src, wc)
 	lines[#lines + 1] = "# dwarf_injection to synthesize DW_TAG_inlined_subroutine instances + per-word"
 	lines[#lines + 1] = "# line program rows for native source-level step into component bodies."
 
+	--- @param atom AtomEntry
+	--- @return nil
 	local function append(atom)
-		local stanza = emit_provenance_stanza(src, atom, wc)
-		for _, line in ipairs(stanza) do lines[#lines + 1] = line end
+		local stanza = emit_provenance_stanza(src, atom, wc)          ---@type string[]
+		for _, line in ipairs(stanza) do lines[#lines + 1] = line end ---@type integer, string
 	end
-	for _, atom in ipairs(src.scan.atoms or {}) do
+	for _, atom in ipairs(src.scan.atoms or {}) do ---@type integer, AtomEntry
 		if atom.paths then append(atom) end
 	end
-	for _, atom in ipairs(src.scan.raw_atoms or {}) do
+	for _, atom in ipairs(src.scan.raw_atoms or {}) do ---@type integer, AtomEntry
 		if atom.paths then append(atom) end
 	end
 
@@ -153,17 +192,17 @@ end
 
 --- Render one atom's stanza for the sourcemap.txt form (ATOM header line, N WORD lines, ENDATOM marker).
 --- Returns (lines, total_words).
---- @param src    table
---- @param atom   table
---- @param wc     table
---- @return string[], integer
+--- @param src  SourceFile
+--- @param atom AtomEntry
+--- @return string[]
+--- @return integer
 local function emit_atom_stanza(src, atom)
-	local lines          = {}
-	local rel_path       = src.path:gsub("\\\\", "/")
-	local entries, total = canonical_word_entries(atom)
+	local lines          = {}                           ---@type string[]
+	local rel_path       = src.path:gsub("\\\\", "/")   ---@type string
+	local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
 
 	lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
-	for _, entry in ipairs(entries) do
+	for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
 		lines[#lines + 1] = string.format("WORD %d  LINE %d  TEXT %s",
 			entry.pos, entry.line, entry.text)
 	end
@@ -174,22 +213,23 @@ end
 
 --- Render the full source map file content for one source (one .atoms.sourcemap.txt per source). Mirrors offsets.lua's
 --- `project_atoms` shape: scan.atoms + scan.raw_atoms, no kind filter.
---- @param src table
---- @param wc  table
+--- @param src SourceFile
 --- @return string
 local function render_source_map(src)
-	local lines       = {}
+	local lines       = {} ---@type string[]
 	lines[#lines + 1] = "# FORMAT_VERSION " .. FORMAT_VERSION
 	lines[#lines + 1] = "# auto-generated by ps1_meta.lua (passes/atoms_source_map.lua) — DO NOT EDIT"
 
+	--- @param atom AtomEntry
+	--- @return nil
 	local function append(atom)
-		local stanza = emit_atom_stanza(src, atom)
-		for _, line in ipairs(stanza) do lines[#lines + 1] = line end
+		local stanza = emit_atom_stanza(src, atom)                    ---@type string[]
+		for _, line in ipairs(stanza) do lines[#lines + 1] = line end ---@type integer, string
 	end
-	for _, atom in ipairs(src.scan.atoms or {}) do
+	for _, atom in ipairs(src.scan.atoms or {}) do ---@type integer, AtomEntry
 		if atom.paths then append(atom) end
 	end
-	for _, atom in ipairs(src.scan.raw_atoms or {}) do
+	for _, atom in ipairs(src.scan.raw_atoms or {}) do ---@type integer, AtomEntry
 		if atom.paths then append(atom) end
 	end
 
@@ -210,20 +250,22 @@ end
 
 --- Build the list of atoms with addresses + word entries. Shared helper for the gdb-runtime file emission.
 --- @param ctx PassCtx
---- @return table[] -- list of {idx, name, src_path, file_base, addr, size_bytes, words, entries}
+--- @return GdbAtomRecord[]
 local function build_atom_table(ctx)
-	local addrs   = elf_dwarf.read_nm(ctx.flags.elf_path)
-	local corpus  = ctx.shared and ctx.shared.corpus
-	local matched = {}
+	local addrs   = elf_dwarf.read_nm(ctx.flags.elf_path) ---@type table<string, NmAddr>
+	local corpus  = ctx.shared and ctx.shared.corpus      ---@type Corpus|nil
+	local matched = {}                                    ---@type GdbAtomRecord[]
 
-	for _, src in ipairs(corpus.source_order or {}) do
-		local file_base = src.path:match("([^/\\\\]+)$") or src.path
+	for _, src in ipairs(corpus.source_order or {}) do ---@type integer, SourceFile
+		local file_base = src.path:match("([^/\\\\]+)$") or src.path ---@type string
+		--- @param atom AtomEntry
+		--- @return nil
 		local function append(atom)
 			if not atom.paths then return end
-			local  name = atom.raw_name or atom.name
-			local  info = addrs[name]
+			local  name = atom.raw_name or atom.name ---@type string
+			local  info = addrs[name]                ---@type NmAddr|nil
 			if not info then return end
-			local entries, total = canonical_word_entries(atom)
+			local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
 			matched[#matched + 1] = {
 				name       = name,
 				src_path   = src.path,
@@ -234,13 +276,16 @@ local function build_atom_table(ctx)
 				entries    = entries,
 			}
 		end
-		for _, atom in ipairs((src.scan or {}).atoms or {}) do append(atom) end
-		for _, atom in ipairs((src.scan or {}).raw_atoms or {}) do append(atom) end
+		for _, atom in ipairs((src.scan or {}).atoms or {}) do append(atom) end     ---@type integer, AtomEntry
+		for _, atom in ipairs((src.scan or {}).raw_atoms or {}) do append(atom) end ---@type integer, AtomEntry
 	end
 
 	-- Deterministic order: sort by address (matches `nm` output ordering).
+	--- @param a GdbAtomRecord
+	--- @param b GdbAtomRecord
+	--- @return boolean
 	table.sort(matched, function(a, b) return a.addr < b.addr end)
-	for i, a in ipairs(matched) do a.idx = i - 1 end
+	for i, a in ipairs(matched) do a.idx = i - 1 end ---@type integer, GdbAtomRecord
 	return matched
 end
 
@@ -251,28 +296,29 @@ end
 ---
 --- Why hardcoded per-atom: gdb's `$` substitution doesn't concat inside var names — `$__atom_name_$__i` in a `while`
 --- loop resolves to one literal identifier, not `name_i`. Compile-time emission is the only path.
---- @param lines   table  -- output line buffer (mutated in place)
---- @param matched table  -- list of atom records from `build_atom_table`
+--- @param lines   string[]
+--- @param matched GdbAtomRecord[]
+--- @return nil
 local function append_gdb_commands(lines, matched)
 	-- ── tape_atoms ──
 	-- Hardcoded one printf per atom. No loop.
 	lines[#lines + 1] = "define tape_atoms"
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		-- gdb 12.1 quirk: literals in printf args require an attached target.
 		-- Use the per-atom convenience vars set above as printf args.
-		lines[#lines + 1] = string.format('  printf "  code_%%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
+		lines[#lines + 1] = string.format('  printf "  %%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
 			a.idx, a.idx, a.idx)
 	end
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = "document tape_atoms"
-	lines[#lines + 1] = "  List every tape atom symbol in the loaded ELF (code_<name>) with .rodata addr + word count."
+	lines[#lines + 1] = "  List every tape atom symbol in the loaded ELF with .rodata addr + word count."
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = ""
 
 	-- ── break_atom (generic) + per-atom break_atom_X ──
 	lines[#lines + 1] = "define break_atom"
 	lines[#lines + 1] = '  echo "Usage: break_atom_<exact_name>  (pick from the list below)"'
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		lines[#lines + 1] = string.format('  printf "  break_atom_%%-32s\\n", $__atom_name_%d', a.idx)
 	end
 	lines[#lines + 1] = "end"
@@ -281,13 +327,13 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = ""
 
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		lines[#lines + 1] = string.format("define break_atom_%s", a.name)
 		lines[#lines + 1] = string.format("  break *$__atom_addr_%d", a.idx)
-		lines[#lines + 1] = string.format('  printf "  Breakpoint set at code_%s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
+		lines[#lines + 1] = string.format('  printf "  Breakpoint set at %s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
 		lines[#lines + 1] = "end"
 		lines[#lines + 1] = string.format("document break_atom_%s", a.name)
-		lines[#lines + 1] = string.format("  Set a breakpoint at code_%s.", a.name)
+		lines[#lines + 1] = string.format("  Set a breakpoint at %s.", a.name)
 		lines[#lines + 1] = "end"
 		lines[#lines + 1] = ""
 	end
@@ -295,7 +341,7 @@ local function append_gdb_commands(lines, matched)
 	-- ── step_atom / next_atom ──
 	-- Hardcoded one tbreak per atom. No loop.
 	lines[#lines + 1] = "define step_atom"
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		lines[#lines + 1] = string.format("  tbreak *$__atom_addr_%d", a.idx)
 	end
 	lines[#lines + 1] = "  continue"
@@ -318,24 +364,24 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "define where_in_atom"
 	lines[#lines + 1] = "  set $__pc = (unsigned int)$pc"
 	lines[#lines + 1] = "  set $__matched = 0"
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		-- Precompute end_addr (gdb 12.1's expression evaluator chokes on `addr + words*4`).
 		lines[#lines + 1] = string.format("  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
 		lines[#lines + 1] = string.format("  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
-		lines[#lines + 1] = string.format('    printf "atom:    code_%%s\\n", $__atom_name_%d', a.idx)
+		lines[#lines + 1] = string.format('    printf "atom:    %%s\\n", $__atom_name_%d', a.idx)
 		lines[#lines + 1] = '    printf "addr:    0x%08x\\n", $__pc'
 		lines[#lines + 1] = string.format("    set $__word = ($__pc - $__atom_addr_%d) / 4", a.idx)
 		lines[#lines + 1] = string.format('    printf "word:    %%d/%%d\\n", $__word, $__atom_words_%d', a.idx)
 		-- One inner-if per WORD entry. Each word's line + text hardcoded.
-		for _, we in ipairs(a.entries) do
+		for _, we in ipairs(a.entries) do ---@type integer, WordMapEntry
 			lines[#lines + 1] = string.format("    if $__word == %d", we.pos)
 			-- Escape TEXT for printf format string.
-			local escaped_text = we.text:gsub("%%", "%%%%"):gsub('"', '\\"')
+			local escaped_text = we.text:gsub("%%", "%%%%"):gsub('"', '\\"') ---@type string
 			lines[#lines + 1] = string.format('      printf "source:  %%s:%%d  %%s\\n", $__atom_file_%d, %d, "%s"', a.idx, we.line, escaped_text)
 			lines[#lines + 1] = "    end"
 		end
 		-- Fallback for words beyond the source map (shouldn't happen if nm matches).
-		local max_word = 0
+		local max_word = 0 ---@type integer
 		if #a.entries > 0 then max_word = a.entries[#a.entries].pos end
 		lines[#lines + 1] = string.format('    if $__word > %d', max_word)
 		lines[#lines + 1] = '      printf "source:  (no source-map entry for word %%d; map may be stale)\\n", $__word'
@@ -360,7 +406,7 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "  set $__in_atom = 0"
 	lines[#lines + 1] = "  set $__did_step = 0"
 	lines[#lines + 1] = "  set $__pc = (unsigned int)$pc"
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		-- Precompute end_addr in the convenience var (single expression gdb handles).
 		lines[#lines + 1] = string.format("  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
 		lines[#lines + 1] = string.format("  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
@@ -394,9 +440,10 @@ end
 --- Emit the gdb-runtime file (post-link). Pure gdb scripting — addresses come from `mipsel-none-elf-nm -S`, get embedded
 --- in `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`, and load via `set $var = ...` + `define ... end` blocks at gdb source-time.
 --- @param ctx PassCtx
+--- @return nil
 local function emit_gdb_runtime(ctx)
 	if not (ctx.flags and ctx.flags.gdb_runtime) then return end
-	local  elf_path = ctx.flags.elf_path
+	local  elf_path = ctx.flags.elf_path ---@type string|nil
 	if not elf_path or elf_path == "" then
 		io.stderr:write("[atoms_source_map] --gdb-runtime requires --elf <elf>\n")
 		return
@@ -407,13 +454,13 @@ local function emit_gdb_runtime(ctx)
 		return
 	end
 
-	local matched = build_atom_table(ctx)
+	local matched = build_atom_table(ctx) ---@type GdbAtomRecord[]
 	if #matched == 0 then
 		io.stderr:write("[atoms_source_map] --gdb-runtime: no atoms matched against nm symbols (stale scan?).\n")
 		return
 	end
 
-	local lines = {}
+	local lines = {} ---@type string[]
 	lines[#lines + 1] = "# Auto-generated by ps1_meta.lua (passes/atoms_source_map.lua)"
 	lines[#lines + 1] = "# DO NOT EDIT — re-run ps1_meta.lua --atoms-source-map --gdb-runtime to regenerate"
 	lines[#lines + 1] = "# Sourced by scripts/gdb/gdb_tape_atoms.gdb (the wrapper)."
@@ -434,7 +481,7 @@ local function emit_gdb_runtime(ctx)
 
 	-- Per-atom convenience vars (used as printf args; literals aren't accepted
 	-- without an attached target on gdb 12.1).
-	for _, a in ipairs(matched) do
+	for _, a in ipairs(matched) do ---@type integer, GdbAtomRecord
 		lines[#lines + 1] = string.format('set $__atom_name_%d = "%s"', a.idx, gdb_escape(a.name))
 		lines[#lines + 1] = string.format("set $__atom_addr_%d = 0x%x", a.idx, a.addr)
 		lines[#lines + 1] = string.format("set $__atom_words_%d = %d", a.idx, a.words)
@@ -450,10 +497,12 @@ local function emit_gdb_runtime(ctx)
 	-- Confirmation line for the source operator.
 	lines[#lines + 1] = 'printf "[gdb_tape_atoms] runtime loaded %d atoms from %s\\n", $__atom_count, $__elf_path'
 
-	local out_path
+	local out_path ---@type string
 	-- Move out of `<out_root>/gdb_tape_atoms_runtime.gdb` to `<out_root>/../gdb_tape_atoms_runtime.gdb` when the conventional `<out_root>` is `<build>/gen`
 	-- (any equivalent spelling — relative, absolute backslash, absolute forward-slash, trailing-separator variants).
 	-- This puts the gdb runtime alongside the ELF at `build/` rather than under the report subdir.
+	--- @param p string
+	--- @return boolean
 	local function ends_with_gen_dir(p)
 		if type(p) ~= "string" then return false end
 		return p:match("[/\\]gen[/\\]?$") ~= nil or p == "build/gen" or p == "build\\gen"
@@ -461,7 +510,7 @@ local function emit_gdb_runtime(ctx)
 	if ends_with_gen_dir(ctx.out_root) then
 		-- Strip the trailing `/gen` segment, then write the runtime script under `build/`.
 		-- e.g. "C:/projects/Pikuma/ps1/build/gen" -> "C:/projects/Pikuma/ps1/build".
-		local parent = ctx.out_root:gsub("[/\\]gen[/\\]?$", "")
+		local parent = ctx.out_root:gsub("[/\\]gen[/\\]?$", "") ---@type string
 		out_path = parent .. "/gdb_tape_atoms_runtime.gdb"
 	else
 		out_path = ctx.out_root .. "/gdb_tape_atoms_runtime.gdb"
@@ -475,24 +524,35 @@ end
 -- M — module exports
 -- ════════════════════════════════════════════════════════════════════════════
 
-local M = {}
+local M = {} ---@type AtomSourceMapPass
 
 -- Expose the pure render functions so `report.lua` and the focused tests can call them directly without triggering the file-emit path.
 M.render_source_map = render_source_map
 M.render_provenance = render_provenance
 
 --- Render ONE atom's sourcemap stanza.
---- @param atom table   -- atom record (must have `atom.paths` populated)
+--- @param atom AtomEntry
 --- @return string
 function M.render_atom_source_map(atom)
 	assert(type(atom) == "table", "render_atom_source_map: atom must be a table")
 	assert(type(atom.paths) == "table", "render_atom_source_map: atom.paths must be a table")
-	local entries, total = canonical_word_entries(atom)
-	local lines = {}
+	local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
+	local lines = {}                                    ---@type string[]
 	lines[#lines + 1] = string.format("ATOM %s  %d", (atom.raw_name or atom.name), total)
-	for _, entry in ipairs(entries) do
-		lines[#lines + 1] = string.format("WORD %d  LINE %d  TEXT %s",
+	for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
+		local word_line = string.format("WORD %d  LINE %d  TEXT %s", ---@type string
 			entry.pos, entry.line, entry.text)
+		local keys = {}    ---@type string[]
+		for pos = 1, 16 do ---@type integer
+			local k = entry.gpr_keys and entry.gpr_keys[pos] ---@type string|nil
+			if type(k) == "string" and k:sub(1, 7) == "reguse:" then
+				keys[#keys + 1] = k
+			end
+		end
+		if #keys > 0 then
+			word_line = word_line .. "  KEYS " .. table.concat(keys, ",")
+		end
+		lines[#lines + 1] = word_line
 	end
 	lines[#lines + 1] = "ENDATOM"
 	return table.concat(lines, "\n") .. "\n"
@@ -502,25 +562,23 @@ end
 ---
 --- `rel_path` is the source path (forward-slashes) embedded in every `CALL` line.
 --- The .md caller (report.lua) is expected to derive this once per `## <source>` heading and pass it down for each atom in that source.
---- @param atom      table   -- atom record (must have `atom.paths` populated)
---- @param wc        table   -- identity alias of `corpus.word_counts`
---- @param rel_path  string  -- source path (forward-slashes) for `CALL` fields
+--- @param atom     AtomEntry
+--- @param wc       WordCounts
+--- @param rel_path string
 --- @return string
 function M.render_atom_provenance(atom, wc, rel_path)
 	assert(type(atom)       == "table", "render_atom_provenance:  atom must be a table")
 	assert(type(atom.paths) == "table", "render_atom_provenance:  atom.paths must be a table")
 	assert(type(rel_path)   == "string", "render_atom_provenance: rel_path must be a string")
-	local entries, total = canonical_word_entries(atom)
-	local lines = {}
+	local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
+	local lines = {}                                    ---@type string[]
 	lines[#lines + 1] = string.format("ATOM %s  %d", (atom.raw_name or atom.name), total)
-	for _, entry in ipairs(entries) do
-		local inv = entry.invocation
-		local macro_count = inv and wc and wc["mac_" .. inv.component_name]
+	for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
+		local inv         = entry.invocation                                ---@type InvocationRecord|nil
+		local macro_count = inv and wc and wc["mac_" .. inv.component_name] ---@type integer|nil
 		if inv and macro_count ~= nil then
-			lines[#lines + 1] = string.format(
-				'WORD %d  CALL %s:%d  MACRO %s "%s:%d" BODY %d',
-				entry.pos, rel_path, entry.line, inv.component_name,
-				inv.def_path or "", inv.def_line or 0, entry.body_line)
+			lines[#lines + 1] = string.format('WORD %d  CALL %s:%d  MACRO %s "%s:%d" BODY %d'
+				, entry.pos, rel_path, entry.line, inv.component_name, inv.def_path or "", inv.def_line or 0, entry.body_line)
 		else
 			lines[#lines + 1] = string.format(
 				"WORD %d  CALL %s:%d  RAW", entry.pos, rel_path, entry.line)
@@ -529,24 +587,24 @@ function M.render_atom_provenance(atom, wc, rel_path)
 	return table.concat(lines, "\n") .. "\n"
 end
 
---- Pass entry. For each source that declares at least one `MipsAtom_(name)` / `MipsCode code_<name>`,
+--- Pass entry. For each source that declares at least one tape atom,
 --- emit two files in `<out_root>/`: `<basename>.atoms.sourcemap.txt` (per-word call-site map) and `<basename>.atoms.provenance.txt`
 --- (per-word definition + body line, resolved via the outermost `mac_X(...)` invocation).
 --- When `ctx.flags.gdb_runtime` is true and `ctx.flags.elf_path` exists, also emit the post-link gdb script `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`.
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
-	local outputs  = {}
-	local errors   = {}
-	local warnings = {}
+	local outputs  = {} ---@type PassOutputEntry[]
+	local errors   = {} ---@type Finding[]
+	local warnings = {} ---@type Finding[]
 
-	local corpus = ctx.shared and ctx.shared.corpus
+	local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
 	if type(corpus) ~= "table" or type(corpus.source_order) ~= "table" then
 		error("atoms_source_map.run requires ctx.shared.corpus.source_order (canonical corpus).", 0)
 	end
 
 	-- Word counts come from `corpus.word_counts` (populated by word_count_eval + components passes).
-	local wc = corpus.word_counts or {}
+	local wc = corpus.word_counts or {} ---@type WordCounts
 	if not next(wc) then
 		warnings[#warnings + 1] = {
 			line = 0,

scripts/passes/auto_reg.lua

@@ -9,8 +9,7 @@
 --- These GPRs are unavailable to EVERY atom's source pool.
 --- Carriers are preserved across atoms by context discipline and must never be reallocated.
 --- Per-atom body parsing also catches alias references (R_<Alias>) and hardcoded R_Tn references,
---- so the user can write either `R_T4` or `R_ResolveScratch` in an atom body and the pass will
---- exclude R_T4 from that atom's pool.
+--- so the user can write either `R_T4` or `R_ResolveScratch` in an atom body and the pass will exclude R_T4 from that atom's pool.
 ---
 --- Conflict detection: If the user hardcodes `R_Tn` in an atom body that shares a phase with an auto-reg that picked `R_Tn`,
 --- emit `phase_register_clash` as an info finding (no build stop).
@@ -19,97 +18,97 @@
 --- Pool exhaustion: If a phase declares more `R_<Sym>` mappings than the 10-register pool can hold,
 --- emit `phase_register_pool_exhausted` as a build-stopping error.
 
---- @class AutoRegResult
---- @field outputs  table[]  -- {kind=, path=} entries
---- @field errors   table[]  -- {line=, msg=}  entries (build-stops)
---- @field warnings table[]  -- {line=, msg=}  entries (build-continues)
+--- @alias GprIdent string
 
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+--- @class GprAllocMap
+--- @field [string] GprIdent  -- bag: auto-reg symbol -> physical GPR
+
+--- @class AutoRegOutput
+--- @field auto_reg_h string
+
+--- @class AutoRegResult
+--- @field outputs  AutoRegOutput[]
+--- @field errors   Finding[]
+--- @field warnings Finding[]
+
+--- @class AutoRegPass
+--- @field run  fun(ctx: PassCtx): AutoRegResult
+--- @field POOL GprIdent[]
+
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")            ---@type DuffleExport
+local isa            = require("duffle_isa")                                      ---@type DuffleIsa
 
 --- ════════════════════════════════════════════════════════════════════════════
---- THE GPR ALLOCATION POOL — what is allocatable, and (more importantly) WHY
+--- THE GPR ALLOCATION POOL — what's allocatable, and (more importantly) WHY
 --- ════════════════════════════════════════════════════════════════════════════
 ---
 --- The auto-reg pass picks physical GPRs for `atom_auto_reg(...)` / `phase_auto_reg(...)` markers.
---- It allocates from a FIXED 10-register pool.
---- This comment block makes the inclusion AND exclusion criteria obvious so a reader doesn't have 
---- to grep lottes_tape.h + mips.h to understand the design.
----
---- ── WHAT'S IN THE POOL (10 GPRs, all caller-trash per the O32 ABI) ────────
----     R_T0..R_T7  (GPR codes 8..15), R_V0..R_V1 (GPR codes 2..3)  
----      The workhorse of every atom body. The uesr should be aware of atom allocation across atoms they chain. 
----      If they have a collision it means either they didn't saturate the register file optimally for a phase,
----      or the may have made the workload to large for the run.
----
---- ── WHAT'S NOT IN THE POOL — and WHY (the "obvious exclusions") ────────────
----   R_T9  (GPR code 25)  — R_TapePtr, the tape instruction stream pointer.
----     Owned by the tape runtime (in tape_run / tape_run_a02_s07).
----     `rgcc(R_TapePtr)` register-variable ties the C compiler's view to $t9 across the whole tape_run.
----     The auto-reg pass MUST NOT clobber this; doing so would desync the C-side tape pointer from the
----     hardware pointer and crash on the next tape_run.
----
----   R_T8  (GPR code 24)  — R_AtomJmp, the atom-jump register used by the 4-word yield handshake.
----     Every `mac_yield()` / `mac_yield_tail` does `load_word R_AtomJmp, R_TapePtr, 0` then
----     `jump_reg R_AtomJmp`. The auto-reg pass MUST NOT clobber this either, or the atom dispatcher breaks.
----     Owned by the tape runtime, same family as R_TapePtr.
----
----   R_AT  (GPR code 1)   — Assembler temporary. Reserved by the MIPS O32 ABI for pseudoinstruction expansion
----     (lottes_tape.h:86, mips.h:93). The ISA's psuedo instructions use it as a scratch temporary.
----
----   R_A0..A3 (codes 4..7)   — Function arguments. Used in tape_run_a02_s07, see below.
----   R_S0..S7 (codes 16..23) — Callee-saved. Preserved across C-ABI calls by convention.
----     The `tape_run_a02_s07` variant clobbers them deliberately, but the default `tape_run` does NOT.
----     Kept out of POOL to preserve the conservative default.
----     Add them in a separate "big clobber" pool if/when needed.
----
----   R_K0/K1       (codes 26..27) — Kernel / interrupt handler reserves. Never touched by user code; OS-internal.
----   R_GP/SP/FP/RA (codes 28..31) — Stack frame + return-address. Owned by the C compiler; never allocatable.
+--- The 24-register pool covers R2-R25 (the user/atom allocatable surface):
+---   R_T0..R_T7, R_V0..R_V1, R_A0..A3, R_S0..S7, R_T8..T9.
+--- Excluded (and never added to the pool):
 ---   R_0          (code 0)   — Hardwired zero. Cannot be written.
+---   R_AT         (code 1)   — Assembler temporary. Reserved by the MIPS O32 ABI.
+---   R_A0..A3                — Explicitly omitted above even though their integer codes map to POOL entries;
+---                             the pool-construction loop below only references the POOL string literals, never the integer codes, so they are NOT auto-allocated by default.
+---                             (A0-A3 become available when the user adds them to POOL or hardcodes an R_A0 reference in the atom body.)
+---   R_K0/K1       (codes 26-27) — Kernel / interrupt handler reserves. Never touched by user code.
+---   R_GP/SP/FP/RA (codes 28-31) — R_SP/R_FP/R_RA are tape-runtime carriers between tape_enter and tape_exit; R_GP stays the host global pointer.
 ---
-local POOL = {
-    "R_T0", "R_T1", "R_T2", "R_T3",
-    "R_T4", "R_T5", "R_T6", "R_T7",
-    "R_V0", "R_V1",
-}
+local POOL = {} ---@type GprIdent[]
+for _, row in ipairs(isa.GPR_ROLE) do ---@type integer, GprRole
+	if row.pool then
+		POOL[#POOL + 1] = row.name
+	end
+end
 
 -- Map from integer MIPS GPR code (the `code` field on AliasEntry) to the physical GPR ident in POOL.
 -- The standard MIPS O32 ABI register numbering matches mips.h's R_*_Code #defines (mips.h).
 -- Only the POOL entries matter for auto_reg — non-pool aliases
 -- (R_AT=1, R_A0..A3=4..7, R_T8=24, R_T9=25, R_K0/K1=26..27, R_GP/SP/FP/RA=28..31) 
 -- are deliberately omitted — see the comment block above for the WHY of each exclusion.
-local INT_CODE_TO_POOL_GPR = {
+local INT_CODE_TO_POOL_GPR = { ---@type table<integer, GprIdent>  -- bag: MIPS GPR code -> POOL ident
 	[2]  = "R_V0", [3]  = "R_V1",
+	[4]  = "R_A0", [5]  = "R_A1", [6]  = "R_A2", [7]  = "R_A3",
 	[8]  = "R_T0", [9]  = "R_T1", [10] = "R_T2", [11] = "R_T3",
 	[12] = "R_T4", [13] = "R_T5", [14] = "R_T6", [15] = "R_T7",
+	[16] = "R_S0", [17] = "R_S1", [18] = "R_S2", [19] = "R_S3",
+	[20] = "R_S4", [21] = "R_S5", [22] = "R_S6", [23] = "R_S7",
+	[24] = "R_T8", [25] = "R_T9",
 }
 
 -- Stable sort for deterministic allocation order.
+--- @param tbl table<string, string>  -- bag: key set only; values unused
+--- @return string[]
 local function stable_sort_keys(tbl)
-    local keys = {}
-    for k in pairs(tbl) do keys[#keys + 1] = k end
+	local keys = {}                                ---@type string[]
+	for k in pairs(tbl) do keys[#keys + 1] = k end ---@type string
 	table.sort(keys)
 	return keys
 end
 
 -- Allocate one phase's auto-reg mappings.
 -- Returns (allocated_map, errors). On pool exhaustion, errors is populated and the function halts.
+--- @param phase_label string
+--- @param decls table<string, string>  -- bag: auto-reg symbol -> decl payload
+--- @return GprAllocMap
+--- @return Finding[]
 local function allocate_phase(phase_label, decls)
 	-- Deep-copy POOL into a fresh sequence table. The original `table.unpack and table.unpack(POOL) or { unpack(POOL) }`
 	-- idiom wraps the unpacked values in a single inner table under LuaJIT 5.1 (`table.unpack` is nil; the `or` returns one value),
 	-- which corrupts the pool into `{ {R_T0, R_T1, ...} }` — making `table.remove(pool, 1)` return the inner table on iteration.
-    local pool   = {}
-    for i = 1, #POOL do pool[i] = POOL[i] end
-    local result = {}
-    local errors = {}
-    for _, sym in ipairs(stable_sort_keys(decls)) do
-        local next_gpr = table.remove(pool, 1)
+	local pool   = {}                                ---@type GprIdent[]
+	for i = 1, #POOL do pool[i] = POOL[i] end        ---@type integer
+	local result = {}                                ---@type GprAllocMap
+	local errors = {}                                ---@type Finding[]
+	for _, sym in ipairs(stable_sort_keys(decls)) do ---@type integer, string
+		local next_gpr = table.remove(pool, 1) ---@type GprIdent|nil
 		if not next_gpr then
 			errors[#errors + 1] = {
 				line = 0,
 				msg  = string.format("phase_register_pool_exhausted: "
 					.. "phase '%s' requested symbol '%s' but the pool has no remaining registers "
-									.. "(max 10 per phase: R_T0..R_T7 + R_V0..R_V1). Split the phase or use hardcoded GPRs."
+					.. "(max 24 per phase: R_T0..R_T7 + R_V0..R_V1 + R_A0..R_A3 + R_S0..R_S7 + R_T8..R_T9). Split the phase or use hardcoded GPRs."
 					, phase_label, sym),
 			}
 			return result, errors
@@ -127,13 +126,16 @@ end
 -- Each entry's `code` is the integer MIPS GPR number (0..31); INT_CODE_TO_POOL_GPR translates it back to the physical GPR ident.
 -- Aliases whose `code` points to a non-POOL GPR (e.g. R_S0, R_T8, R_K1) are ignored — 
 -- they don't affect the auto_reg pool, and they're already excluded from POOL above.
+--- @param corpus Corpus
+--- @return table<GprIdent, boolean>
+--- @return table<string, GprIdent>
 local function build_user_pins(corpus)
-    local user_pinned  = {}
-    local alias_to_gpr = {}
+	local user_pinned  = {} ---@type table<GprIdent, boolean>  -- bag: pinned physical GPR -> true
+	local alias_to_gpr = {} ---@type table<string, GprIdent>  -- bag: alias ident -> physical GPR
 	if not corpus.register_alias_registry then return user_pinned, alias_to_gpr end
-    for alias_name, alias_entry in pairs(corpus.register_alias_registry) do
+	for alias_name, alias_entry in pairs(corpus.register_alias_registry) do ---@type string, AliasEntry
 		if alias_entry.has_atom_reg and alias_entry.code then
-            local gpr = INT_CODE_TO_POOL_GPR[alias_entry.code]
+			local gpr = INT_CODE_TO_POOL_GPR[alias_entry.code] ---@type GprIdent|nil
 			if gpr then
 				user_pinned[gpr]         = true
 				alias_to_gpr[alias_name] = gpr
@@ -143,30 +145,33 @@ local function build_user_pins(corpus)
 	return user_pinned, alias_to_gpr
 end
 
--- Find every physical GPR referenced in the atom body, via EITHER:
---   (a) A hardcoded physical GPR ident (R_T\d+|R_V\d+|R_A\d+|R_S\d+) — the existing regex;
---   (b) An alias ident (R_<Alias>) resolved via alias_to_gpr back to its physical GPR ident.
--- Returns { [physical_gpr_ident] = count }. Clash-detection and source-pool-exclusion logic
--- only needs the presence of each GPR (boolean test), but keeping count preserves the
--- original find_hardcoded_rn shape so callers can switch without churn.
--- The alias pattern is sorted lexicographically to keep the regex deterministic.
+--- Find every physical GPR referenced in the atom body, via EITHER:
+---   (a) A hardcoded physical GPR ident (R_T\d+|R_V\d+|R_A\d+|R_S\d+) — the existing regex;
+---   (b) An alias ident (R_<Alias>) resolved via alias_to_gpr back to its physical GPR ident.
+--- Returns { [physical_gpr_ident] = count }.
+--- Clash-detection and source-pool-exclusion logic only needs the presence of each GPR (boolean test), 
+--- but keeping count preserves the original find_hardcoded_rn shape so callers can switch without churn.
+--- The alias pattern is sorted lexicographically to keep the regex deterministic.
+--- @param body_text string
+--- @param alias_to_gpr table<string, GprIdent>  -- bag: alias ident -> physical GPR
+--- @return table<GprIdent, integer>
 local function find_used_gprs(body_text, alias_to_gpr)
-    local found = {}
+	local found = {} ---@type table<GprIdent, integer>  -- bag: physical GPR -> hit count
 	-- (a) Hardcoded physical GPRs (R_T0..R_T7, R_V0..R_V1, R_A0..R_A3, R_S0..R_S7).
-    for gpr in body_text:gmatch("(R_T%d+|R_V%d+|R_A%d+|R_S%d+)") do
+	for gpr in body_text:gmatch("(R_T%d+|R_V%d+|R_A%d+|R_S%d+)") do ---@type GprIdent
 		found[gpr] = (found[gpr] or 0) + 1
 	end
 	-- (b) Alias references (R_<Alias>) resolved to physical GPRs via the registry.
 	--      Sorted by name so the regex is byte-stable across runs.
 	if alias_to_gpr and next(alias_to_gpr) then
-        local aliases = {}
-        for alias_name in pairs(alias_to_gpr) do
+		local aliases = {}                       ---@type string[]
+		for alias_name in pairs(alias_to_gpr) do ---@type string
 			aliases[#aliases + 1] = alias_name
 		end
 		table.sort(aliases)
-        local pattern = "(" .. table.concat(aliases, "|") .. ")"
-        for alias_name in body_text:gmatch(pattern) do
-            local gpr = alias_to_gpr[alias_name]
+		local pattern = "(" .. table.concat(aliases, "|") .. ")" ---@type string
+		for alias_name in body_text:gmatch(pattern) do           ---@type string
+			local gpr = alias_to_gpr[alias_name] ---@type GprIdent|nil
 			if gpr and not found[gpr] then
 				found[gpr] = 1
 			end
@@ -176,26 +181,31 @@ local function find_used_gprs(body_text, alias_to_gpr)
 end
 
 -- Emit one gen/auto_reg.h header per directory.
+--- @param out_dir string
+--- @param dir string
+--- @param sources SourceFile[]
+--- @param mappings GprAllocMap
+--- @return string|nil
 local function emit_auto_reg_h(out_dir, dir, sources, mappings)
 	if not mappings or next(mappings) == nil then return end
-    local out_path = out_dir .. "/" .. "auto_reg.h"
+	local out_path = out_dir .. "/" .. "auto_reg.h" ---@type string
 	duffle.ensure_dir(out_dir)
-    local lines = {
+	local lines = { ---@type string[]
 		"#ifdef INTELLISENSE_DIRECTIVES",
 		"#pragma once",
 		"#endif",
 		"// Auto-generated by ps1_meta.lua (passes/auto_reg.lua) — DO NOT EDIT",
 		"// Directory: " .. dir:gsub("/", "\\"),
 	}
-    for _, src in ipairs(sources) do
+	for _, src in ipairs(sources) do ---@type integer, SourceFile
 		lines[#lines + 1] = "//   source: " .. src.path
 	end
 	lines[#lines + 1] = "// Per-phase register allocations resolved by the lua pass."
 	lines[#lines + 1] = "// R_<Sym>_Code = <chosen GPR's _Code constant> for every marker in this directory."
 	lines[#lines + 1] = ""
-    for _, sym in ipairs(stable_sort_keys(mappings)) do
-        local gpr         = mappings[sym]
-        local gpr_code    = gpr .. "_Code"
+	for _, sym in ipairs(stable_sort_keys(mappings)) do ---@type integer, string
+		local gpr         = mappings[sym]  ---@type GprIdent
+		local gpr_code    = gpr .. "_Code" ---@type string
 		lines[#lines + 1] = "#define " .. sym .. "_Code " .. gpr_code
 	end
 	lines[#lines + 1] = ""
@@ -208,16 +218,16 @@ end
 -- Pass entry
 -- ════════════════════════════════════════════════════════════════════════════
 
-local M = {}
+local M = {} ---@type AutoRegPass
 
 --- @param ctx PassCtx
 --- @return AutoRegResult
 function M.run(ctx)
-    local outputs  = {}
-    local errors   = {}
-    local warnings = {}
+	local outputs  = {} ---@type AutoRegOutput[]
+	local errors   = {} ---@type Finding[]
+	local warnings = {} ---@type Finding[]
 
-    local corpus = ctx.shared and ctx.shared.corpus
+	local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
 	if type(corpus) ~= "table" then
 		error("auto_reg.run requires ctx.shared.corpus", 0)
 	end
@@ -227,17 +237,17 @@ function M.run(ctx)
 	--  MUST NOT be allocated to any auto-reg marker — they're preserved across atoms by the wave-context discipline.
 	--  The corpus's register_alias_registry is the source of truth for these opt-in pins.
 	--  Body references to those aliases (via alias_to_gpr) are also excluded on a per-atom basis in step 2 below.
-    local user_pinned, alias_to_gpr = build_user_pins(corpus)
+	local user_pinned, alias_to_gpr = build_user_pins(corpus) ---@type table<GprIdent, boolean>, table<string, GprIdent>
 
 	-- 1. Allocate phase pools first (phase declarations take precedence over per-atom declarations).
-    local phase_allocations = {}
-    for phase_label, decls in pairs(corpus.phase_auto_regs or {}) do
-        local mapping, errs = allocate_phase(phase_label, decls)
-        for sym, gpr in pairs(mapping) do
+	local phase_allocations = {}                                     ---@type table<string, GprAllocMap>  -- bag: phase_label -> alloc map
+	for phase_label, decls in pairs(corpus.phase_auto_regs or {}) do ---@type string, table<string, string>
+		local mapping, errs = allocate_phase(phase_label, decls) ---@type GprAllocMap, Finding[]
+		for sym, gpr in pairs(mapping) do                        ---@type string, GprIdent
 			phase_allocations[phase_label]      = phase_allocations[phase_label] or {}
 			phase_allocations[phase_label][sym] = gpr
 		end
-        for _, e in ipairs(errs) do
+		for _, e in ipairs(errs) do ---@type integer, Finding
 			errors[#errors + 1] = e
 		end
 	end
@@ -246,16 +256,16 @@ function M.run(ctx)
 	-- Otherwise, allocate a private pool for the atom.
 	-- The phase membership is in `corpus.atom_phases[phase_label].atoms` (an array of atom names declared via `atom_phase(<phase>)`
 	-- in the atom's `atom_info` line). Build a reverse map `atom_name -> phase_label` so the lookup is O(1) per atom scope.
-    local atom_name_to_phase = {}
-    for phase_label, entry in pairs(corpus.atom_phases or {}) do
-        for _, atom_name in ipairs(entry.atoms or {}) do
+	local atom_name_to_phase = {}                                ---@type table<AtomName, string>  -- bag: atom name -> phase label
+	for phase_label, entry in pairs(corpus.atom_phases or {}) do ---@type string, AtomPhaseGroup
+		for _, atom_name in ipairs(entry.atoms or {}) do ---@type integer, AtomName
 			atom_name_to_phase[atom_name] = phase_label
 		end
 	end
 
-    local atom_allocations = {}
-    for atom_scope, decls in pairs(corpus.atom_auto_regs or {}) do
-        local phase_label = atom_name_to_phase[atom_scope]
+	local atom_allocations = {}                                    ---@type table<AtomName, GprAllocMap>  -- bag: atom scope -> alloc map
+	for atom_scope, decls in pairs(corpus.atom_auto_regs or {}) do ---@type AtomName, table<string, string>
+		local phase_label = atom_name_to_phase[atom_scope] ---@type string|nil
 		-- Build the atom's source pool: start with the full POOL, subtract:
 		--   (a) every GPR already committed (phase allocations + prior atom allocations)
 		--   (b) every USER-PINNED GPR (wave-context carriers + file-scope pinned aliases)
@@ -265,27 +275,26 @@ function M.run(ctx)
 		-- the original `source_pool = phase_allocations[phase_label]` form used the phase
 		-- allocation MAP as a pool, but that map has no array part, so `table.remove(source_pool, 1)`
 		-- returned nil and every atom-with-phase marker errored with `phase_register_pool_exhausted`.
-        local used = {}
-        for _, m in pairs(phase_allocations) do for _, gpr in pairs(m) do used[gpr] = true end end
-        for _, m in pairs(atom_allocations)  do for _, gpr in pairs(m) do used[gpr] = true end end
+		local used = {}                                                                            ---@type table<GprIdent, boolean>  -- bag: committed or body-referenced GPR -> true
+		for _, m in pairs(phase_allocations) do for _, gpr in pairs(m) do used[gpr] = true end end ---@type integer, GprAllocMap
+		for _, m in pairs(atom_allocations)  do for _, gpr in pairs(m) do used[gpr] = true end end ---@type integer, GprAllocMap
 		-- (c) Body references — scan the atom body for hardcoded + alias-resolved GPRs.
 		--     Folded into `used` so the source_pool exclusion is a single check.
-        local atom = corpus.atoms_by_name and corpus.atoms_by_name[atom_scope]
+		local atom = corpus.atoms_by_name and corpus.atoms_by_name[atom_scope] ---@type AtomEntry|nil
 		if atom and atom.body then
-            local body_used = find_used_gprs(atom.body, alias_to_gpr)
-            for gpr in pairs(body_used) do used[gpr] = true end
+			local body_used = find_used_gprs(atom.body, alias_to_gpr) ---@type table<GprIdent, integer>
+			for gpr in pairs(body_used) do used[gpr] = true end       ---@type GprIdent
 		end
-        local source_pool = {}
-        for _, gpr in ipairs(POOL) do
-            -- Exclude (a) prior commitments, (b) USER-PINNED GPRs (wave-context carriers
-            -- declared via atom_reg + _Code defs, preserved across atoms globally).
+		local source_pool = {}        ---@type GprIdent[]
+		for _, gpr in ipairs(POOL) do ---@type integer, GprIdent
+			-- Exclude (a) prior commitments, (b) USER-PINNED GPRs (wave-context carriers declared via atom_reg + _Code defs, preserved across atoms globally).
 			if not used[gpr] and not user_pinned[gpr] then
 				source_pool[#source_pool + 1] = gpr
 			end
 		end
-        local result = {}
-        for _, sym in ipairs(stable_sort_keys(decls)) do
-            local next_gpr = table.remove(source_pool, 1)
+		local result = {}                                ---@type GprAllocMap
+		for _, sym in ipairs(stable_sort_keys(decls)) do ---@type integer, string
+			local next_gpr = table.remove(source_pool, 1) ---@type GprIdent|nil
 			if not next_gpr then
 				errors[#errors + 1] = {
 					line = 0,
@@ -307,11 +316,11 @@ function M.run(ctx)
 	-- This warning is kept as a defensive safety net for cases the body scanner might miss
 	-- (e.g. macros that expand to register references the scanner cannot resolve).
 	-- For each resolved (scope, sym) -> R_Tn mapping, scan the atom body source for used GPRs.
-    for atom_scope, decls in pairs(atom_allocations) do
-        local atom = corpus.atoms_by_name and corpus.atoms_by_name[atom_scope]
+	for atom_scope, decls in pairs(atom_allocations) do ---@type AtomName, GprAllocMap
+		local atom = corpus.atoms_by_name and corpus.atoms_by_name[atom_scope] ---@type AtomEntry|nil
 		if    atom and atom.body then
-            local used_in_body = find_used_gprs(atom.body, alias_to_gpr)
-            for sym, allocated_gpr in pairs(decls) do
+			local used_in_body = find_used_gprs(atom.body, alias_to_gpr) ---@type table<GprIdent, integer>
+			for sym, allocated_gpr in pairs(decls) do                    ---@type string, GprIdent
 				if used_in_body[allocated_gpr] and used_in_body[allocated_gpr] > 0 then
 					warnings[#warnings + 1] = {
 						line  = atom.line or 0,
@@ -326,30 +335,32 @@ function M.run(ctx)
 
 	-- 4. Emit per-directory gen/auto_reg.h.
 	-- For each source directory that has atom_auto_regs or phase_auto_regs entries, emit one header.
-    local sources_by_dir = corpus.sources_by_dir or {}
-    for dir, sources in pairs(sources_by_dir) do
-        local per_dir_mappings = {}
-        for _, src in ipairs(sources) do
+	local sources_by_dir = corpus.sources_by_dir or {} ---@type table<string, SourceFile[]>
+	for dir, sources in pairs(sources_by_dir) do       ---@type string, SourceFile[]
+		local per_dir_mappings = {}      ---@type GprAllocMap
+		for _, src in ipairs(sources) do ---@type integer, SourceFile
 			-- Collect every (sym -> gpr) entry that originated from a source in this directory.
 			-- `src.scan.atom_auto_regs` is keyed by ATOM SCOPE NAME; `pairs(t)` iterates KEYS so `scope_name` here is the scope ident (e.g. "cube_g4_face").
 			-- The previous `for _, scan_atom_auto` form silently assigned the VALUE (a `{sym = sym}` table) to the variable,
 			-- which made `atom_allocations[scan_atom_auto]` a table-indexed lookup that never resolved.
-            for scope_name in pairs(src.scan and src.scan.atom_auto_regs or {}) do
-                for sym, gpr in pairs(atom_allocations[scope_name] or {}) do
+			for scope_name in pairs(src.scan and src.scan.atom_auto_regs or {}) do ---@type string
+				for sym, gpr in pairs(atom_allocations[scope_name] or {}) do ---@type string, GprIdent
 					per_dir_mappings[sym] = gpr
 				end
 			end
-            for scope_name in pairs(src.scan and src.scan.phase_auto_regs or {}) do
-                for sym, gpr in pairs(phase_allocations[scope_name] or {}) do
+			for scope_name in pairs(src.scan and src.scan.phase_auto_regs or {}) do ---@type string
+				for sym, gpr in pairs(phase_allocations[scope_name] or {}) do ---@type string, GprIdent
 					per_dir_mappings[sym] = gpr
 				end
 			end
 		end
-        local out_dir  = dir .. "/gen"
-        local out_path = emit_auto_reg_h(out_dir, dir, sources, per_dir_mappings)
+		local out_dir  = dir .. "/gen"                                            ---@type string
+		local out_path = emit_auto_reg_h(out_dir, dir, sources, per_dir_mappings) ---@type string|nil
 		if out_path then outputs[#outputs + 1] = { auto_reg_h = out_path } end
 	end
 	return { outputs = outputs, errors = errors, warnings = warnings }
 end
 
+M.POOL = POOL
+
 return M

scripts/passes/emission_model.lua

@@ -1,13 +1,13 @@
 --- passes/emission_model.lua: Per-atom emission projection.
 ---
 --- The `emission-model` pass owns `atom.paths`, the canonical per-atom mutable surface for atoms and raw atoms with bodies in `ctx.shared.corpus.source_order`.
---- For each atom, the pass invokes `duffle.project_emission(body_text, component_index, word_counts, components)`.
+--- For each atom, the pass invokes `duffle.project_emission(body_text, components, word_counts, components)`.
 --- It stores the ordered `items` stream plus the dense `word_events` / `markers` / `invocations` views on `atom.paths`.
 ---
 --- Public boundary:
 ---   * `M.run(ctx)` is the only entry point.
 ---   * The pass returns `{outputs = {}, errors = ..., warnings = ...}`.
----     Pass kind = `validation` → `PASS_KIND_STOP_ON_ERROR.validation` preserves the existing build-stopping policy.
+---     Pass kind = `validation`. Findings record on the result; the orchestrator does not exit non-zero.
 ---
 --- Source-order discipline:
 ---   * `corpus.source_order` sets the source-record order.
@@ -26,13 +26,94 @@
 ---
 --- `passes.scan_source` strips its private `_code_macros` / `_code_macro_bodies` tables before this pass runs.
 
-local M = {}
+--- @class BodyToken
+--- @field tok string
+--- @field rel integer
+
+--- @class EmissionItem
+--- @field kind                    string
+--- @field encoder                 string|nil
+--- @field args                    string[]|nil
+--- @field i                       integer|nil
+--- @field word_count              integer|nil
+--- @field line                    integer|nil
+--- @field call_text               string|nil
+--- @field root_call_text          string|nil
+--- @field invocation_ids          integer[]|nil
+--- @field outermost_invocation_id integer|nil
+--- @field gpr_keys                string[]|nil
+--- @field ident                   string|nil
+--- @field isa_kind                string|nil
+--- @field nop_words               integer|nil
+--- @field is_yield                boolean|nil
+--- @field is_load                 boolean|nil
+--- @field is_branch               boolean|nil
+--- @field is_unconditional_jump   boolean|nil
+--- @field is_terminal_jump        boolean|nil
+--- @field gp0_shape               string|nil
+--- @field name                    string|nil
+--- @field target                  string|nil
+--- @field word_index              integer|nil
+--- @field consuming_encoder       string|nil
+--- @field consuming_arg_pos       integer|nil
+--- @field invocation_id           integer|nil
+
+--- @class WordEvent
+--- @field i                       integer
+--- @field encoder                 string
+--- @field args                    string[]
+--- @field def_path                string
+--- @field def_line                integer
+--- @field call_text               string|nil
+--- @field root_call_text          string|nil
+--- @field invocation_ids          integer[]
+--- @field outermost_invocation_id integer
+--- @field word_count              integer
+--- @field gpr_keys                string[]|nil
+--- @field ident                   string
+--- @field kind                    string
+--- @field nop_words               integer
+--- @field is_yield                boolean
+--- @field is_load                 boolean
+--- @field is_branch               boolean
+--- @field is_unconditional_jump   boolean
+--- @field is_terminal_jump        boolean
+--- @field gp0_shape               string|nil
+--- @field body_line               integer|nil
+--- @field call_line               integer|nil
+--- @field call_path               string|nil
+
+--- @class EmissionMarker
+--- @field kind              string
+--- @field name              string
+--- @field line              integer
+--- @field word_index        integer
+--- @field target            string|nil
+--- @field consuming_encoder string|nil
+--- @field consuming_arg_pos integer|nil
+
+-- Finding: see ps1_meta.lua
+
+--- @class AtomPaths
+--- @field tokens       BodyToken[]
+--- @field line_in_body table<integer, integer>  -- bag: body byte offset -> 1-based line
+--- @field items        EmissionItem[]
+--- @field word_events  WordEvent[]
+--- @field markers      EmissionMarker[]
+--- @field invocations  InvocationRecord[]
+--- @field errors       Finding[]
+--- @field warnings     Finding[]
+
+--- @class EmissionModelPass
+--- @field run fun(ctx: PassCtx): PassResult
+
+local M = {} ---@type EmissionModelPass
 
 -- ─────────────────────────────────────────────────────────────────────────
 -- Bootstrap: load `duffle_paths.lua` via debug.getinfo so the module works standalone (run as `luajit passes/emission_model.lua`) and when require'd from the orchestrator.
 -- ─────────────────────────────────────────────────────────────────────────
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")            ---@type DuffleExport
 
 -- ─────────────────────────────────────────────────────────────────────────
 -- Helpers
@@ -45,12 +126,17 @@ local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 --   * ROOT invocations (`inv.parent_id == 0`) receive body-relative `call_line` values directly from `M.LineIndex(body_text)` in the walker.
 --     The source `line_of` closure supplies physical lines at the close site, so this function converts each root value exactly once.
 --   * INNER invocations (`inv.parent_id ~= 0`) receive physical `call_line` values directly from the COMPONENT's `line_of` in the walker.
---     Recursive descent forwards that closure through `corpus.component_body_index[name].line_of`; those values arrive physical and remain unchanged.
+--     Recursive descent forwards that closure through `corpus.components[name].line_of`; those values arrive physical and remain unchanged.
 --
 -- After this function, every `inv.call_line` is physical. DWARF and provenance output read it directly.
 -- The word-event loop forwards the already-physical `outer_inv.call_line` into `we.call_line` for words inside an invocation.
+--- @param projection EmissionProjection
+--- @param atom_record AtomEntry
+--- @param src SourceFile
+--- @param corpus Corpus
+--- @return nil
 local function stamp_root_provenance(projection, atom_record, src, corpus)
-	local root_line_of   = src.scan and src.scan.line_of
+	local root_line_of   = src.scan and src.scan.line_of ---@type (fun(pos: integer): integer)|nil
 	assert(type(root_line_of) == "function"
 		, "emission_model: src.scan.line_of is required (canonical LineIndex closure over the source text) to stamp physical provenance")
 	assert(type(atom_record.body_off) == "number"
@@ -58,26 +144,29 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
 	-- `root_body_line` is the physical source line of the ATOM HEADER byte containing the opening `{`; that byte is one byte BEFORE `atom_record.body_off`.
 	-- The walker assigns line 2 to the body's first content line because line 1 is the trailing `\n` after `{`. Body-text line k therefore maps to `root_body_line + (k - 1)`.
 	-- `body_off - 1` points at the opening `{`, whose line index identifies the header line. `body_off` points after `{` and would shift every word row forward by one line.
-	local root_body_line  = root_line_of(atom_record.body_off - 1) or atom_record.line or 0
-	local component_index = corpus.component_body_index or {}
-	local word_items      = {}
+	local root_body_line  = root_line_of(atom_record.body_off - 1) or atom_record.line or 0 ---@type integer
+	local components = corpus.components or {}                                              ---@type table<string, Component>
+	local word_items      = {}                                                              ---@type EmissionItem[]
 
-	for _, item in ipairs(projection.items) do
+	for _, item in ipairs(projection.items) do ---@type integer, EmissionItem
 		if item.kind == "word" then word_items[#word_items + 1] = item end
 	end
 
 	-- Resolve one word's physical body line, where the byte containing that word appears in source.
 	--   * Component expansions carry `invocation_ids`; the component's full-file `line_of` leaves `item.line` physical.
 	--   * Raw tokens in the root atom body carry an empty `invocation_ids` list and a body-relative `item.line`; convert them here.
+	--- @param event WordEvent
+	--- @param item EmissionItem
+	--- @return integer
 	local function body_line_for(event, item)
-		local ids = event.invocation_ids or {}
+		local ids = event.invocation_ids or {} ---@type integer[]
 		-- The innermost open invocation identifies which line index the walker used.
 		-- A component `line_of` makes `item.line` physical; the atom's `body_text` line index makes it body-relative.
 		if ids and #ids > 0 then
-			local inner_id  = ids[#ids]
-			local inner_inv = inner_id and projection.invocations[inner_id]
+			local inner_id  = ids[#ids]                                     ---@type integer
+			local inner_inv = inner_id and projection.invocations[inner_id] ---@type InvocationRecord|nil
 			if inner_inv then
-				local component = component_index[inner_inv.component_name]
+				local component = components[inner_inv.component_name] ---@type Component|nil
 				if component and component.line_of then
 					-- Walker used `comp.line_of`, which is the source's physical LineIndex. item.line is already physical.
 					return item.line or 0
@@ -92,8 +181,8 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
 	-- Stamp the root source path onto invocation records whose `call_path` the walker left empty.
 	-- The walker passes `body_entry.source` to `emit_invoke_begin`; `M.project_emission` creates the root `body_entry` with source `""`, leaving its `call_path` empty.
 	-- This stamp gives every invocation a physical `call_path` matching `passes/atoms_source_map.lua`'s in-memory provenance projection.
-	local root_path = src.path or ""
-	for _, inv in ipairs(projection.invocations) do
+	local root_path = src.path or ""                ---@type string
+	for _, inv in ipairs(projection.invocations) do ---@type integer, InvocationRecord
 		if inv.call_path == nil or inv.call_path == "" then
 			inv.call_path = root_path
 		end
@@ -102,7 +191,7 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
 	-- Normalize `inv.call_line` to a physical source line.
 	--   * ROOT  invocations (`parent_id == 0`) carry body-relative `call_line` values from `M.LineIndex(body_text)`; convert them once with `root_body_line`.
 	--   * INNER invocations (`parent_id ~= 0`) carry physical `call_line` values from the component's `line_of`; retain them unchanged.
-	for _, inv in ipairs(projection.invocations) do
+	for _, inv in ipairs(projection.invocations) do ---@type integer, InvocationRecord
 		if inv.parent_id == 0 then
 			inv.call_line = (root_body_line or 0) + (inv.call_line or 1) - 1
 		end
@@ -111,14 +200,14 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
 	-- Build `body_lines` for each invocation.
 	-- `atoms_source_map` and `dwarf_injection` read `inv.body_lines[k]` directly from the invocation record created here.
 	-- Component words already carry physical `item.line` values from the walker's COMPONENT line index, so `body_line_for` returns them unchanged.
-	for _, inv in ipairs(projection.invocations) do
-		local sw  = inv.start_word
-		local ew  = inv.end_word
-		local bls = {}
-		for i = sw, ew do
-			local it = projection.items and projection.items[i]
+	for _, inv in ipairs(projection.invocations) do ---@type integer, InvocationRecord
+		local sw  = inv.start_word ---@type integer
+		local ew  = inv.end_word   ---@type integer
+		local bls = {}             ---@type integer[]
+		for i = sw, ew do          ---@type integer
+			local it = projection.items and projection.items[i] ---@type EmissionItem|nil
 			if    it and it.kind == "word" then
-				local fake_event = { invocation_ids = { inv.id } }
+				local fake_event = { invocation_ids = { inv.id } } ---@type WordEvent
 				bls[#bls + 1]    = body_line_for(fake_event, it) or 0
 			end
 		end
@@ -128,15 +217,15 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
 	-- Resolve each `word_event`'s physical `body_line` and `call_line`.
 	-- For words inside an invocation, `we.call_line` identifies the OUTER atom source line containing the `mac_X(...)` token that triggered expansion.
 	-- The root-invocation conversion above makes every `inv.call_line` physical; forward it directly and use each raw word's `body_line` as the fallback.
-	for index, we in ipairs(projection.word_events) do
-		local item      = word_items[index] or {}
-		local body_line = body_line_for(we, item)
+	for index, we in ipairs(projection.word_events) do ---@type integer, WordEvent
+		local item      = word_items[index] or {} ---@type EmissionItem
+		local body_line = body_line_for(we, item) ---@type integer
 		item.line    = body_line
 		we.body_line = body_line
 
-		local call_line = body_line
-		local outer_id  = we.outermost_invocation_id or 0
-		local outer_inv = projection.invocations[outer_id]
+		local call_line = body_line                        ---@type integer
+		local outer_id  = we.outermost_invocation_id or 0  ---@type integer
+		local outer_inv = projection.invocations[outer_id] ---@type InvocationRecord|nil
 		if outer_inv then
 			-- `outer_inv.call_line` is physical after the conversion loop above, so use it directly.
 			call_line = outer_inv.call_line
@@ -151,13 +240,46 @@ end
 
 -- Project one atom record into `atom.paths`.
 -- Mutates the atom record in-place and returns the projection (for pass-level error/warning accumulation).
+--- @param atom_record AtomEntry
+--- @param src SourceFile
+--- @param corpus Corpus
+--- @return EmissionProjection
 local function project_atom(atom_record, src, corpus)
-	local body  = atom_record.body or ""
-	local wc    = corpus.word_counts or {}
-	local cbi   = corpus.component_body_index or {}
+	local body  = atom_record.body or ""            ---@type string
+	local wc    = corpus.word_counts or {}          ---@type WordCounts
+	local comps = corpus.components or {}           ---@type table<string, Component>
+	local schema = nil                              ---@type RegUseSchema|nil
+	if atom_record.reg_use_schema_name then
+		schema = corpus.reg_use_schemas and corpus.reg_use_schemas[atom_record.reg_use_schema_name]
+	end
 	-- That construction site stamps `invocation.debug_skip` while appending each record to `proj.invocations`.
-	local proj  = duffle.project_emission(body, cbi, wc, corpus.components)
-	local paths = {
+	local proj  = duffle.project_emission(body, comps, wc, comps, { ---@type EmissionProjection
+		reg_use_schema = schema,
+		reg_use_param  = atom_record.reg_use_param_name,
+		atom_name      = atom_record.name,
+		schema_name    = atom_record.reg_use_schema_name,
+	})
+	if atom_record.reg_use_schema_name and not schema then
+		proj.errors[#proj.errors + 1] = {
+			kind        = "error",
+			check       = "reguse_missing_schema",
+			msg         = string.format("RegUse schema %q is missing", atom_record.reg_use_schema_name),
+			schema_name = atom_record.reg_use_schema_name,
+		}
+	end
+	for _, err in ipairs(corpus.reg_use_errors or {}) do ---@type integer, RegUseError
+		if err.schema_name == atom_record.reg_use_schema_name then
+			proj.errors[#proj.errors + 1] = {
+				kind        = "error",
+				check       = err.kind,
+				line        = err.line or err.source_line or 0,
+				msg         = err.msg or "",
+				source      = err.source or err.source_file,
+				schema_name = err.schema_name,
+			}
+		end
+	end
+	local paths = { ---@type AtomPaths
 		tokens       = atom_record.body_tokens or {},
 		line_in_body = duffle.build_body_line_index(body),
 		items        = proj.items,
@@ -179,35 +301,42 @@ end
 --- @param ctx PassCtx  -- { shared = { corpus = ... }, out_root, ... }
 --- @return PassResult
 function M.run(ctx)
-	local outputs  = {}
-	local errors   = {}
-	local warnings = {}
+	local outputs  = {} ---@type PassOutputEntry[]
+	local errors   = {} ---@type Finding[]
+	local warnings = {} ---@type Finding[]
 
-	local corpus = ctx and ctx.shared and ctx.shared.corpus
+	local corpus = ctx and ctx.shared and ctx.shared.corpus ---@type Corpus|nil
 	if type(corpus)              ~= "table" then error("emission_model: ctx.shared.corpus is required (canonical projection)", 0) end
 	if type(corpus.source_order) ~= "table" then error("emission_model: ctx.shared.corpus.source_order is required", 0) end
 
 	-- Project once, collect errors + warnings for one atom.
 	-- Kind must be one of: atom | atom_proc | raw_atom | comp_bare | comp_proc.
+	--- @param atom AtomEntry
+	--- @param src SourceFile
+	--- @return nil
 	local function process_atom(atom, src)
 		if not (atom and atom.body) then return end
-		local kind = atom.kind
+		local kind = atom.kind ---@type string
 		if kind ~= "atom" and kind ~= "atom_proc" and kind ~= "raw_atom" and kind ~= "comp_bare" and kind ~= "comp_proc" then
 			return
 		end
-		local proj = project_atom(atom, src, corpus)
-		for _, e in ipairs(proj.errors) do
-			-- Preserve `kind` (cycle / count_mismatch / unbalanced) so readers dispatch on the diagnostic class and leave the message string as display text.
+		local proj = project_atom(atom, src, corpus) ---@type EmissionProjection
+		for _, e in ipairs(proj.errors) do           ---@type integer, Finding
+			-- Finding.kind is severity. Finding.check holds the diagnostic code
+			-- (cycle / count_mismatch / unbalanced / reguse_*).
 			errors[#errors + 1] = {
-				kind   = e.kind,
+				kind        = "error",
+				check       = e.check,
 				line        = e.line,
 				msg         = e.msg,
 				source      = e.source or src.path,
+				schema_name = e.schema_name,
 			}
 		end
-		for _, w in ipairs(proj.warnings) do
+		for _, w in ipairs(proj.warnings) do ---@type integer, Finding
 			warnings[#warnings + 1] = {
-				kind = w.kind,
+				kind  = "warning",
+				check = w.check,
 				line  = w.line,
 				msg   = w.msg,
 			}
@@ -217,12 +346,12 @@ function M.run(ctx)
 	-- Walk `corpus.source_order`; within each source, visit atoms followed by raw_atoms.
 	-- Recognized kinds (atom | atom_proc | raw_atom | comp_bare | comp_proc) each receive the atom.paths projection via duffle.project_emission.
 	-- Components are macros inlined into atom bodies; focused tests and isolated component analyses consume atom.paths directly.
-	for _, src in ipairs(corpus.source_order) do
-		local scan = src.scan or {}
-		for _, atom in ipairs(scan.atoms or {}) do
+	for _, src in ipairs(corpus.source_order) do ---@type integer, SourceFile
+		local scan = src.scan or {}                ---@type SourceScan
+		for _, atom in ipairs(scan.atoms or {}) do ---@type integer, AtomEntry
 			process_atom(atom, src)
 		end
-		for _, atom in ipairs(scan.raw_atoms or {}) do
+		for _, atom in ipairs(scan.raw_atoms or {}) do ---@type integer, AtomEntry
 			process_atom(atom, src)
 		end
 	end

scripts/passes/offsets.lua

@@ -1,20 +1,14 @@
 --- passes/offsets.lua — Branch-offset generator.
 ---
 --- Reads the pre-scanned SourceScan payload (produced once upstream by `duffle.scan_source`)
---- for `MipsAtom_(name)` and `MipsCode code_<name>` declarations, computes the word offset
+--- for `MipsAtom_(name)` and leftover `MipsCode code_*` declarations, computes the word offset
+--- (ELF symbol is the C ident; raw `code_*` is leftover, not the atom rule)
 --- from each `atom_offset(F, T)` marker to its target `atom_label(T)` declaration, and emits
 --- `gen/offsets.h` with one `#define _atom_offset_F_T = N` per branch.
 ---
 --- Per-directory aggregation: every source in the same directory contributes to the same `gen/offsets.h`.
 --- The directory itself is the namespace; the filename does not repeat the module name.
 ---
---- (Task 12.16 note: atom-namespaced enum names — e.g., `atom_offset__normalize_v3s4__srav_path__aligned_done` —
---- were considered to prevent cross-atom label collisions, but the C-side `atom_offset(F, T)` macro in
---- `code/duffle/dsl.atom.h` doesn't know the current atom_name at expansion time, so any namespacing
---- on the metaprogram side breaks the C build. Reverted. The C-side would need a per-atom
---- `CURRENT_ATOM` #define (set by `MipsAtom_`/`MipsAtom_Proc_` macros) plus an updated `atom_offset`
---- macro that uses it. That's a coordinated refactor — deferred to a future track.)
----
 --- The offset is `target_word - branch_word - 1` (the standard MIPS branch-immediate encoding: branch_offset = relative_pc_in_words - 1).
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -26,41 +20,25 @@
 -- 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).
 -- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")            ---@type DuffleExport
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- Offset macro/enum naming prefixes (the emitted header uses these).
-local OFFSET_MACRO_PREFIX = "_atom_offset_"
-local OFFSET_ENUM_PREFIX  = "atom_offset_"
+local OFFSET_MACRO_PREFIX = "_atom_offset_" ---@type string
+local OFFSET_ENUM_PREFIX  = "atom_offset_"  ---@type string
 
 -- Column width for the `#define _atom_offset_F_T = N` alignment.
-local OFFSET_MACRO_COL = 44
+local OFFSET_MACRO_COL = 44 ---@type integer
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 
---- @class SourceFile
---- @field path     string  -- Absolute path to the source file
---- @field text     string  -- Full source text
---- @field dir      string  -- Directory containing the source
---- @field basename string  -- Filename without extension
---- @field scan     table   -- Pre-scanned SourceScan payload (from duffle.scan_source)
-
---- @class PassCtx
---- @field shared             table -- Cross-pass shared state
---- @field shared.corpus      table -- Corpus projection
---- @field shared.word_counts table
---- @field out_root           string -- Output root (e.g. "build/gen")
-
---- @class PassResult
---- @field outputs  table[]  -- {kind=, path=} entries describing emit files
---- @field errors   table[]  -- {line=, msg=}  entries; build-stops
---- @field warnings table[]  -- {line=, msg=}  entries; build-succeeds
+-- SourceFile, PassCtx, PassResult: see ps1_meta.lua
 
 --- @class BranchOffset
 --- @field tag               string      -- Marker tag (e.g. "F" in `atom_offset(F, T)`)
@@ -75,6 +53,32 @@ local OFFSET_MACRO_COL = 44
 --- @field total_words integer        -- Total word count of the atom body
 --- @field offsets     BranchOffset[] -- Per-branch offset list
 
+--- @class OffsetBranch
+--- @field tag               string
+--- @field target            string
+--- @field branch_word       integer
+--- @field consuming_encoder string|nil
+--- @field consuming_arg_pos integer|nil
+--- @field line              integer|nil
+
+--- @class MarkerProjectState
+--- @field labels   table<string, integer>  -- bag: label name -> word index
+--- @field branches OffsetBranch[]
+
+--- @class OffsetConst
+--- @field macro_name string
+--- @field enum_name  string
+--- @field value      integer
+
+--- @class OffsetOutput
+--- @field offsets_h string
+
+--- @class OffsetsPass
+--- @field run fun(ctx: PassCtx): PassResult
+
+--- @class AtomEntry
+--- @field paths AtomPaths|nil
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- Canonical marker projection
 -- ════════════════════════════════════════════════════════════════════════════
@@ -82,10 +86,16 @@ local OFFSET_MACRO_COL = 44
 -- MARKER_PROJECTORS is the marker-kind data table.
 -- The emission-model pass already records marker word positions + consuming-instruction context;
 -- this pass only projects those records into the label/branch lookup shape needed by offset computation.
-local MARKER_PROJECTORS = {
+local MARKER_PROJECTORS = { ---@type table<string, fun(state: MarkerProjectState, marker: EmissionMarker): nil>
+	--- @param state MarkerProjectState
+	--- @param marker EmissionMarker
+	--- @return nil
 	label = function(state, marker)
 		state.labels[marker.name] = marker.word_index
 	end,
+	--- @param state MarkerProjectState
+	--- @param marker EmissionMarker
+	--- @return nil
 	offset = function(state, marker)
 		state.branches[#state.branches + 1] = {
 			tag                = marker.name,
@@ -99,12 +109,13 @@ local MARKER_PROJECTORS = {
 
 --- Project canonical marker records into the two lookup tables used by the offset renderer.
 --- No source text, body text, or body token is inspected.
---- @param markers table[] -- atom.paths.markers
---- @return table<string, integer>, table[]
+--- @param markers EmissionMarker[]
+--- @return table<string, integer>
+--- @return OffsetBranch[]
 local function project_markers(markers)
-	local state = { labels = {}, branches = {} }
-	for _, marker in ipairs(markers or {}) do
-		local project = MARKER_PROJECTORS[marker.kind]
+	local state = { labels = {}, branches = {} } ---@type MarkerProjectState
+	for _, marker in ipairs(markers or {}) do    ---@type integer, EmissionMarker
+		local project = MARKER_PROJECTORS[marker.kind] ---@type (fun(state: MarkerProjectState, marker: EmissionMarker): nil)|nil
 		if    project then project(state, marker) end
 	end
 	return state.labels, state.branches
@@ -123,38 +134,47 @@ end
 ---     For cross-module `j`/`jal` (atom body in one module, target in another), the linker emits a `R_MIPS_26` relocation against the lower 26 bits; the upper 4 bits come from the PC of the delay slot following the `j`.
 ---     The metaprogram doesn't know either at compile time, so the emitted value is the relative word offset that the duffle `enc_i` macro places in the immediate field; the toolchain handles the rest.
 ---   `jump_reg` / `call_reg` / `jump_link` -> ERROR. Register-form jumps have no offset field; `atom_offset` is invalid.
----
---- Top-level `atom_offset(F, T)` markers (where the marker is the entire token — `consuming_encoder` == nil) default to `branch_*` behavior (relative offset).
---- This preserves backward compatibility for any top-level marker that may exist outside a control-transfer instruction.
+---   missing `consuming_encoder` -> ERROR. A lone top-level `atom_offset` is not a branch.
 --- @param labels   table<string, integer>
---- @param branches table[]
+--- @param branches OffsetBranch[]
+--- @param errors   Finding[]
 --- @return BranchOffset[]
-local function compute_offsets(labels, branches)
-	local results = {}
-	for _, br in ipairs(branches) do
-		local target = labels[br.target]
+local function compute_offsets(labels, branches, errors)
+	local results = {}               ---@type BranchOffset[]
+	for _, br in ipairs(branches) do ---@type integer, OffsetBranch
+		local target = labels[br.target] ---@type integer|nil
 		if not target then
-			error("Branch target '" .. br.target .. "' has no atom_label (at word " .. br.branch_word .. ")")
-		end
-		local consuming = br.consuming_encoder
-		local offset
-		if consuming == "jump_reg" or consuming == "call_reg" or consuming == "jump_link" then
-			-- Register-form jumps have no offset field. `atom_offset` cannot be used here.
-			error("atom_offset cannot be used with " .. consuming
-				.. " (register-form jumps have no offset field); at word " .. br.branch_word)
-		end
-		-- All other consuming instructions (including `branch_*`, `jump`, `call_addr`, and nil for top-level markers) use the same relative offset value.
+			errors[#errors + 1] = {
+				line = br.line or 0,
+				msg  = "Branch target '" .. br.target .. "' has no atom_label (at word " .. br.branch_word .. ")",
+			}
+		else
+			local consuming = br.consuming_encoder ---@type string|nil
+			if consuming == nil or consuming == "" then
+				errors[#errors + 1] = {
+					line = br.line or 0,
+					msg  = "atom_offset requires a consuming encoder (branch_*, jump, call_addr); top-level atom_offset is invalid; at word " .. br.branch_word,
+				}
+			elseif consuming == "jump_reg" or consuming == "call_reg" or consuming == "jump_link" then
+				errors[#errors + 1] = {
+					line = br.line or 0,
+					msg  = "atom_offset cannot be used with " .. consuming
+						.. " (register-form jumps have no offset field); at word " .. br.branch_word,
+				}
+			else
+				-- Consuming instructions with an offset field (`branch_*`, `jump`, `call_addr`) use the same relative offset value.
 				-- The MIPS encoding differs per opcode but the duffle `enc_i` macro handles the truncation to the immediate-field width.
-		offset = target - br.branch_word - 1
 				results[#results + 1] = {
 					target             = br.target,
 					tag                = br.tag,
 					branch_word        = br.branch_word,
-			offset             = offset,
+					offset             = target - br.branch_word - 1,
 					consuming_encoder  = br.consuming_encoder,
 					consuming_arg_pos  = br.consuming_arg_pos,
 				}
 			end
+		end
+	end
 	return results
 end
 
@@ -168,7 +188,7 @@ end
 
 --- (internal) Build a constant-table entry `{macro_name, enum_name, value}` from a BranchOffset.
 --- @param bo BranchOffset
---- @return table
+--- @return OffsetConst
 local function make_offset_const(bo)
 	return {
 		macro_name = OFFSET_MACRO_PREFIX .. bo.tag .. "_" .. bo.target,
@@ -180,20 +200,21 @@ end
 --- (internal) Emit one atom's offset constants + enum into the lines buffer.
 --- @param add  fun(s: string)
 --- @param atom AtomData
+--- @return nil
 local function emit_atom_offsets(add, atom)
 	if #atom.offsets == 0 then return end
 	add("// --- atom: " .. atom.name .. " (" .. atom.total_words .. " words) ---")
 	add("")
-	local consts = {}
-	for _, r in ipairs(atom.offsets) do
+	local consts = {}                   ---@type OffsetConst[]
+	for _, r in ipairs(atom.offsets) do ---@type integer, BranchOffset
 		consts[#consts + 1] = make_offset_const(r)
 	end
-	for _, c in ipairs(consts) do
+	for _, c in ipairs(consts) do ---@type integer, OffsetConst
 		add("#define " .. pad_right(c.macro_name, OFFSET_MACRO_COL) .. "  " .. c.value)
 	end
 	add("")
 	add("enum {")
-	for _, c in ipairs(consts) do
+	for _, c in ipairs(consts) do ---@type integer, OffsetConst
 		add("    " .. c.enum_name .. " = " .. c.macro_name .. ",")
 	end
 	add("};")
@@ -201,19 +222,21 @@ local function emit_atom_offsets(add, atom)
 end
 
 --- Generate the per-directory .offsets.h header.
---- @param dir          string     -- the absolute source directory
---- @param sources      table[]    -- sources contributing to this directory (for the header comment)
+--- @param dir        string
+--- @param sources    SourceFile[]
 --- @param atoms_data AtomData[]
 --- @return string
 local function generate_header(dir, sources, atoms_data)
-	local dir_basename = duffle.basename_no_ext(dir)
+	local dir_basename = duffle.basename_no_ext(dir) ---@type string
 
-	local lines = {}
+	local lines = {} ---@type string[]
+	--- @param s string
+	--- @return nil
 	local function add(s) lines[#lines + 1] = s end
 
 	add("// Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT")
 	add("// Directory: " .. dir:gsub("/", "\\") .. "\\")
-	for _, src in ipairs(sources) do
+	for _, src in ipairs(sources) do ---@type integer, SourceFile
 		add("//   source: " .. src.path:gsub("/", "\\"))
 	end
 	add("#pragma once")
@@ -221,7 +244,7 @@ local function generate_header(dir, sources, atoms_data)
 	add("#pragma region " .. dir_basename)
 	add("")
 	add("")
-	for _, atom in ipairs(atoms_data) do
+	for _, atom in ipairs(atoms_data) do ---@type integer, AtomData
 		emit_atom_offsets(add, atom)
 	end
 	add("#pragma endregion " .. dir_basename)
@@ -229,36 +252,39 @@ local function generate_header(dir, sources, atoms_data)
 	return table.concat(lines, "\n") .. "\n"
 end
 
-local M = {}
+local M = {} ---@type OffsetsPass
 
 --- (internal) Aggregate atoms from every source in one directory, render the per-directory `offsets.h`.
 --- Returns the offsets_h path if a header was written, or nil.
 --- @param ctx     PassCtx
---- @param dir     string       -- the absolute source directory
---- @param sources SourceFile[] -- sources in this directory
---- @return string|nil  -- the offsets_h path
-local function process_directory(ctx, dir, sources)
-	local atoms_data = {}
+--- @param dir     string
+--- @param sources SourceFile[]
+--- @param errors  Finding[]
+--- @return string|nil
+local function process_directory(ctx, dir, sources, errors)
+	local atoms_data = {} ---@type AtomData[]
 
+	--- @param atom AtomEntry
+	--- @return nil
 	local function append_atom(atom)
-		local  paths = atom and atom.paths
+		local  paths = atom and atom.paths ---@type AtomPaths|nil
 		if not paths then return end
-		local labels, branches = project_markers(paths.markers)
+		local labels, branches = project_markers(paths.markers) ---@type table<string, integer>, OffsetBranch[]
 		atoms_data[#atoms_data + 1] = {
 			name        = atom.raw_name or atom.name,
 			total_words = #(paths.word_events or {}),
-			offsets     = compute_offsets(labels, branches),
+			offsets     = compute_offsets(labels, branches, errors),
 		}
 	end
 
-	for _, src in ipairs(sources) do
-		local scan = src.scan or {}
-		for _, atom in ipairs(scan.atoms or {}) do append_atom(atom) end
-		for _, atom in ipairs(scan.raw_atoms or {}) do append_atom(atom) end
+	for _, src in ipairs(sources) do ---@type integer, SourceFile
+		local scan = src.scan or {}                                          ---@type SourceScan
+		for _, atom in ipairs(scan.atoms or {}) do append_atom(atom) end     ---@type integer, AtomEntry
+		for _, atom in ipairs(scan.raw_atoms or {}) do append_atom(atom) end ---@type integer, AtomEntry
 	end
 	if #atoms_data == 0 then return nil end
 
-	local out_path = dir .. "/gen/offsets.h"
+	local out_path = dir .. "/gen/offsets.h" ---@type string
 	duffle.ensure_dir(duffle.dirname(out_path))
 	duffle.write_file(out_path, generate_header(dir, sources, atoms_data))
 	return out_path
@@ -270,11 +296,11 @@ end
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
-	local outputs  = {}
-	local errors   = {}
-	local warnings = {}
+	local outputs  = {} ---@type OffsetOutput[]
+	local errors   = {} ---@type Finding[]
+	local warnings = {} ---@type Finding[]
 
-	local corpus = ctx.shared and ctx.shared.corpus
+	local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
 	if type(corpus) ~= "table" then
 		error("offsets.run requires ctx.shared.corpus", 0)
 	end
@@ -283,9 +309,9 @@ function M.run(ctx)
 	end
 
 	-- Per-directory aggregation: every source in the same directory contributes to one `gen/offsets.h`.
-	local sources_by_dir = corpus.sources_by_dir or duffle.group_sources_by_dir(corpus.source_order)
-	for dir, sources in pairs(sources_by_dir) do
-		local out_path = process_directory(ctx, dir, sources)
+	local sources_by_dir = corpus.sources_by_dir or duffle.group_sources_by_dir(corpus.source_order) ---@type table<string, SourceFile[]>
+	for dir, sources in pairs(sources_by_dir) do                                                     ---@type string, SourceFile[]
+		local out_path = process_directory(ctx, dir, sources, errors) ---@type string|nil
 		if out_path then
 			outputs[#outputs + 1] = { offsets_h = out_path }
 		end

scripts/passes/word_count_eval.lua

@@ -4,13 +4,13 @@
 ---   1. **Public utility** `M.count_token_words(token, wc)`: Used by `passes/offsets.lua`, `passes/annotation.lua`, and other passes.
 ---   2. **Pass entry** `M.run(ctx)`: Loads the authored `word_count.metadata.h` into `ctx.shared.corpus.word_counts` for downstream passes.
 ---      The generated `.macs.h` files are OUTPUT artifacts and are NOT inputs to this pass;
----      Current component counts are owned by `passes/components.lua` (which populates `corpus.word_counts` and `corpus.component_body_index`
+---      Current component counts are owned by `passes/components.lua` (which populates `corpus.word_counts` and `corpus.components`
 ---      AFTER computing each current count from the just-built body + `corpus.word_counts`).
 ---
 --- **Canonical contract**:
 ---   * `ctx.shared.corpus.word_counts` is the count table.
 ---   * `corpus.word_counts` is the sole count table. Consumers read `corpus.word_counts` directly.
----   * `ctx.shared.components` and `ctx.shared.component_body_index` are NOT created by this pass (projections only).
+---   * `ctx.shared.components` is NOT created by this pass (projections only).
 ---   * No `.macs.h` recursive discovery (no `scan_dir`, no scan cache, no `_invalidate_scan_cache`).
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
@@ -23,44 +23,28 @@
 -- 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.
 -- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
-local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
-local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
+local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
+local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")            ---@type DuffleExport
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- @class WordCounts
---- @field [string] integer  -- macro name -> word count
+--- @field [string] integer  -- bag: macro name -> word count
 
---- @class SourceFile
---- @field path     string  -- absolute path to the source file
---- @field text     string  -- the full source text
---- @field dir      string  -- the directory containing the source
---- @field basename string  -- filename without extension
+--- @class WordCountEval
+--- @field count_token_words fun(token: string, wc: WordCounts): integer
+--- @field run               fun(ctx: PassCtx): PassResult
 
---- @class PassCtx
---- @field sources            SourceFile[]  -- all source files in the build
---- @field metadata_path      string        -- path to word_count.metadata.h
---- @field shared             table         -- cross-pass shared state
---- @field shared.corpus      table         -- canonical corpus (required)
---- @field shared.corpus.word_counts WordCounts -- canonical count table (populated by this pass)
---- @field out_root           string        -- output root (e.g. "build/gen")
---- @field project_root       string        -- project root (e.g. "code/")
---- @field upstream           table<string, table>  -- per-pass upstream outputs
---- @field flags              table         -- CLI flags
---- @field verbose            boolean       -- if true, log diagnostic info
-
---- @class PassResult
---- @field outputs  table[]  -- {kind=, path=} entries describing emit files
---- @field errors   table[]  -- {line=, msg=} entries; build-stops
---- @field warnings table[]  -- {line=, msg=} entries; build-succeeds
+-- SourceFile, PassCtx, PassResult: see ps1_meta.lua
+-- DuffleExport: see duffle.lua (facade returned by duffle_paths.lua)
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module exports
 -- ════════════════════════════════════════════════════════════════════════════
 
-local M = {}
+local M = {} ---@type WordCountEval
 
 -- ┌────────────────────────────────────────────────────────────────────┐
 -- │ Shared utility: count_token_words                                  │
@@ -74,12 +58,12 @@ local M = {}
 --- @param wc    WordCounts -- the shared word-count table
 --- @return integer
 function M.count_token_words(token, wc)
-	local s = duffle.trim(token)
+	local s = duffle.trim(token) ---@type string
 	if    s == "" then return 0 end
-	local name, after = duffle.read_ident(s, 1)
+	local name, after = duffle.read_ident(s, 1) ---@type string|nil, integer
 	if not name then return 1 end
 	if wc[name] then return wc[name] end
-	local paren_pos = duffle.skip_ws_and_cmt(s, after)
+	local paren_pos = duffle.skip_ws_and_cmt(s, after) ---@type integer
 	if s:sub(paren_pos, paren_pos) == "(" then
 		io.stderr:write("  warning: unknown macro '" .. name .. "', assuming 1 word\n")
 	end
@@ -105,7 +89,7 @@ end
 --- @return PassResult
 function M.run(ctx)
 	-- 1. Canonical-corpus ownership gate.
-	local corpus = ctx.shared and ctx.shared.corpus
+	local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
 	if type(corpus) ~= "table" then
 		error("word_count_eval.run requires ctx.shared.corpus (canonical corpus). The fixture must install the corpus before running this pass.", 0)
 	end
@@ -117,7 +101,7 @@ function M.run(ctx)
 
 	-- 3. Load authored metadata. Generated .macs.h files are NOT scanned
 	--    (the pass computes their counts from the just-built bodies after disk emission; see passes/components.lua).
-	local wc = duffle.load_word_counts(ctx.metadata_path)
+	local wc = duffle.load_word_counts(ctx.metadata_path) ---@type WordCounts
 
 	-- 4. Assign the count table. ONE assignment, no copy. The assignment creates no secondary alias.
 	corpus.word_counts = wc

scripts/ps1_meta.lua

@@ -19,8 +19,8 @@
 -- 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).
 -- That single statement: (a) sets `package.path` + `package.cpath`, (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
+local _is_entry_script = arg and arg[0] and arg[0]:match("ps1_meta%.lua$") ~= nil ---@type boolean
+local _bootstrap_src                                                              ---@type string
 if _is_entry_script then
 	_bootstrap_src = arg[0]
 else
@@ -28,26 +28,26 @@ else
 	-- 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")
+local duffle = dofile((_bootstrap_src:match("(.*[/\\])") or "./") .. "duffle_paths.lua") ---@type DuffleExport
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 
 -- Exit codes (per the --help text and the post-build summary convention).
-local EXIT_OK                  = 0
-local EXIT_VALIDATION_ERRORS   = 1
-local EXIT_INTERNAL_ERROR      = 2
+local EXIT_OK                  = 0 ---@type integer
+local EXIT_VALIDATION_ERRORS   = 1 ---@type integer
+local EXIT_INTERNAL_ERROR      = 2 ---@type integer
 
 -- Default --out-root value if not provided.
-local DEFAULT_OUT_ROOT         = "build/gen"
+local DEFAULT_OUT_ROOT         = "build/gen" ---@type string
 
 -- Sentinel for "all passes" in `PASS_FLAG_TO_NAME`. Distinguishes `--all` from the per-pass flags (which map to individual pass names).
-local ALL_PASSES_SENTINEL      = "__all__"
+local ALL_PASSES_SENTINEL      = "__all__" ---@type string
 
 -- Sentinel key for the pass-flag dispatcher in `FLAG_HANDLERS`. 
 -- The actual pass names are looked up via `PASS_FLAG_TO_NAME`, not direct dispatch, so this key never matches a real flag.
-local PASS_FLAG_DISPATCH_KEY   = "__pass__"
+local PASS_FLAG_DISPATCH_KEY   = "__pass__" ---@type string
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
@@ -60,29 +60,98 @@ local PASS_FLAG_DISPATCH_KEY   = "__pass__"
 --- @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
 
---- @class SourceFile
---- @field path     string  -- Absolute path to the source file
---- @field text     string  -- Full source text
---- @field dir      string  -- Directory containing the source
---- @field basename string  -- Filename without extension
+--- @class Corpus
+--- @field unity_root              string|nil
+--- @field project_root            string
+--- @field code_root               string
+--- @field source_order            SourceFile[]
+--- @field sources_by_path         table<Path, SourceFile>
+--- @field sources_by_dir          table<string, SourceFile[]>
+--- @field atoms_by_name           table<AtomName, AtomEntry>
+--- @field binds_by_name           table<string, BindsEntry>
+--- @field atom_infos              AtomInfoEntry[]
+--- @field register_alias_registry table<string, AliasEntry>
+--- @field type_name_registry      table<string, TypeNameEntry>
+--- @field atom_views              table<AtomName, AtomViewEntry>
+--- @field atom_ctxs               table<AtomName, AtomCtxEntry>
+--- @field atom_phases             table<string, AtomPhaseGroup>
+--- @field word_counts             WordCounts
+--- @field components              table<string, Component>
+--- @field atom_bundles            table<string, AtomBundle>|nil
+--- @field tape_emits              TapeEmit[]|nil
+--- @field collisions              CorpusCollision[]
+--- @field resolver                SourceResolver
+--- @field component_atom_infos    AtomInfoEntry[]|nil
+--- @field atom_auto_regs          table<AtomName, table<string, string>>|nil
+--- @field phase_auto_regs         table<string, table<string, string>>|nil
+--- @field reg_use_schemas         table<string, RegUseSchema>|nil
+--- @field reg_use_errors          RegUseError[]|nil
+--- @field static_analysis_results table<string, AtomAnalysis>|nil
+--- @field tape_chains             table<string, TapeChain>|nil
+
+--- @class PassShared
+--- @field corpus Corpus
+
+--- @class PassFlags
+--- @field gdb_runtime     boolean|nil
+--- @field dwarf_injection boolean|nil
+--- @field elf_path        string|nil
 
 --- @class PassCtx
 --- @field metadata_path string                 -- Path to word_count.metadata.h
---- @field shared             table                  -- Cross-pass shared state
---- @field shared.corpus      table                  -- Authored-source/project projection
+--- @field shared        PassShared             -- Cross-pass shared state
 --- @field out_root      string                 -- Output root (e.g. "build/gen")
 --- @field project_root  string                 -- PS1 repository root
---- @field flags              table                  -- CLI flags + per-pass stash
+--- @field flags         PassFlags              -- CLI flags + per-pass stash
 --- @field verbose       boolean                -- If true, log diagnostic info
 
+--- CheckName: see static_analysis.lua. AtomName: see duffle.lua.
 --- @class Finding
---- @field line integer  -- Source line (or 0 for pass-level)
---- @field msg  string   -- Finding message
+--- @field line         integer
+--- @field msg          string
+--- @field kind         string|nil     -- error | warning | info
+--- @field atom         AtomName|nil
+--- @field check        CheckName|nil
+--- @field source       string|nil     -- optional; emit/reguse path
+--- @field schema_name  string|nil     -- optional; emit/reguse
+
+--- @class PassScratch
+--- @field corpus                   Corpus|nil
+--- @field info_by_atom             table<string, AtomInfoEntry>|nil
+--- @field binds_index              table<string, BindsEntry>|nil
+--- @field atom_index               table<string, AtomEntry>|nil
+--- @field annot_counts             table<string, integer>|nil  -- bag
+--- @field types                    table<string, RegTypeDefault>|nil
+--- @field atom_views               table<string, AtomViewEntry>|nil
+--- @field seen_defaults            table<string, integer>|nil  -- bag
+--- @field seen_field               table<string, integer>|nil  -- bag
+--- @field _scan                    SourceScan|nil
+--- @field word_counts              WordCounts|nil
+--- @field register_alias_registry  table<string, AliasEntry>|nil
+--- @field type_name_registry       table<string, TypeNameEntry>|nil
+--- @field type_occurrences         RegTypeOccurrence[]|nil
+--- @field atom_infos_list          AtomInfoEntry[]|nil
+--- @field binds_list               BindsEntry[]|nil
+--- @field unknown_seen             table<string, integer>|nil  -- bag
+--- @field atoms                    AtomEntry[]|nil
+--- @field components_by_name       table<string, Component>|nil
+--- @field atoms_by_name            table<string, AtomEntry>|nil
+--- @field tape_chains              table<string, string[]>|nil
+--- @field source_order             SourceFile[]|nil
+--- @field component_atom_infos     AtomInfoEntry[]|nil
+--- @field atom_infos_all           AtomInfoEntry[]|nil
+--- @field gte_cr_alias_groups      GteCrAliasGroup[]|nil
+--- @field line_for_word_event      (fun(ev: WordEvent): integer)|nil
+
+--- @class PassOutputEntry
+--- @field kind string
+--- @field path string
 
 --- @class PassResult
---- @field outputs  PassOutputEntry[] -- Emitted file paths
+--- @field outputs  PassOutputEntry[]
 --- @field errors   Finding[]         -- Build-stops (per-pass kind policy)
 --- @field warnings Finding[]         -- Informational
+--- @field info     Finding[]|nil     -- static_analysis only
 
 --- @class ParsedArgs
 --- @field requested_set string[]       -- Pass names to run (explicit --all expanded)
@@ -92,6 +161,18 @@ local PASS_FLAG_DISPATCH_KEY   = "__pass__"
 --- @field out_root      string         -- --out-root value (default "build/gen")
 --- @field project_root  string         -- PS1 repository root (derived from metadata by default)
 --- @field verbose       boolean        -- If true, log diagnostic info
+--- @field flags         PassFlags|nil  -- Per-pass stash; copied onto PassCtx.flags
+
+--- @alias FlagHandler fun(args: ParsedArgs, argv: string[]|nil, arg_idx: integer|nil): integer|nil
+
+--- @class PassModule
+--- @field run fun(ctx: PassCtx): PassResult
+
+--- @class Ps1MetaMod
+--- @field PASSES                  table<string, PassDescriptor>
+--- @field PASS_KIND_STOP_ON_ERROR table<string, boolean>
+--- @field parse_args              fun(argv: string[]): ParsedArgs
+--- @field build_ctx               fun(args: ParsedArgs): PassCtx
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- PASSES Table
@@ -104,7 +185,7 @@ local PASS_FLAG_DISPATCH_KEY   = "__pass__"
 -- 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 = {
+local PASSES = { ---@type table<string, PassDescriptor>
 	["scan-source"] = {
 		module = "passes.scan_source",
 		kind   = "shared", deps = {},
@@ -142,8 +223,7 @@ local PASSES = {
 	},
 	["static-analysis"] = {
 		module = "passes.static_analysis",
-		-- "diagnostic" — every `error`/`warning` finding is written to the report file;
-		-- The orchestrator does NOT exit non-zero on these findings (see PASS_KIND_STOP_ON_ERROR).
+		-- "diagnostic" — every `error`/`warning` finding is written to the report file.
 		-- Report severity is independent from process exit policy.
 		kind   = "diagnostic",
 		deps   = {"scan-source", "word-counts", "components", "emission-model"},
@@ -175,10 +255,10 @@ local PASSES = {
 --- @param group_name string  -- 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
+	local names = {}                   ---@type string[]
+	for name, pass in pairs(PASSES) do ---@type string, PassDescriptor
 		if pass.groups then
-			for _, g in ipairs(pass.groups) do
+			for _, g in ipairs(pass.groups) do ---@type integer, string
 				if g == group_name then
 					names[#names + 1] = name
 					break
@@ -195,27 +275,25 @@ end
 --- cannot silently fall through to pre-link (or any other default) and dispatch nothing.
 --- @param args       ParsedArgs
 --- @param group_name string
+--- @return nil
 local function request_roots_for_group(args, group_name)
-	local roots = roots_for_group(group_name)
+	local roots = roots_for_group(group_name) ---@type string[]
 	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
+	for _, name in ipairs(roots) do ---@type integer, string
 		args.requested_set[#args.requested_set + 1] = name
 	end
 end
 
--- Pass-kind taxonomy: Which kinds stop the build on errors?
---
+-- Pass-kind taxonomy: findings always print. No pass kind stops the build.
 -- Report severity is independent from process exit policy.
--- A "diagnostic" pass still writes every `error`/`warning` finding into its report file,
--- but `report_validation_errors` returns early for non-stopping kinds, so nothing is printed to stderr and the orchestrator does not exit non-zero.
--- Adding a new pass kind requires listing it here explicitly; An unknown kind must not silently fall back to "true".
-local PASS_KIND_STOP_ON_ERROR = {
+-- Adding a new pass kind requires listing it here explicitly; an unknown kind must not silently fall back to "true".
+local PASS_KIND_STOP_ON_ERROR = { ---@type table<string, boolean>  -- bag: pass kind -> stop-on-error
 	["shared"]        = false,
-	["header-output"] = true,
-	["validation"]    = true,
+	["header-output"] = false,
+	["validation"]    = false,
 	["diagnostic"]    = false,
 	["report"]        = false,
 }
@@ -224,7 +302,7 @@ local PASS_KIND_STOP_ON_ERROR = {
 -- Per-pass flags (e.g. --word-counts); phase flags (--pre-link, --post-link, --all) are within 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 = {
+local PASS_FLAG_TO_NAME = { ---@type table<string, string>  -- bag: CLI flag -> pass name or ALL_PASSES_SENTINEL
 	["--word-counts"]       = "word-counts",
 	["--components"]        = "components",
 	["--validate"]          = "annotation",
@@ -239,24 +317,26 @@ local PASS_FLAG_TO_NAME = {
 --- 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
+--- @return nil
 local function request_all_passes(args)
-	local names = {}
-	for name in pairs(PASSES) do names[#names + 1] = name end
+	local names = {}                                          ---@type string[]
+	for name in pairs(PASSES) do names[#names + 1] = name end ---@type string
 	table.sort(names)
-	for _, n in ipairs(names) do
+	for _, n in ipairs(names) do ---@type integer, string
 		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). 
-local FLAG_HANDLERS = {}
+local FLAG_HANDLERS = {} ---@type table<string, FlagHandler>
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- CLI parsing
 -- ════════════════════════════════════════════════════════════════════════════
 
 --- Print the CLI usage to stdout and exit 0.
+--- @return nil
 local function print_help()
 	io.write([[
 ps1_meta.lua - Tape-atom metaprogram orchestrator
@@ -295,8 +375,7 @@ COMMON_FLAGS:
   --help                Show this help and exit
 
 EXIT CODES:
-  0  All requested passes succeeded
-  1  Validation errors found
+  0  Ran. Findings print on stderr and in the report; they do not fail the process.
   2  Metaprogram internal error
 
 EXAMPLES:
@@ -306,7 +385,7 @@ EXAMPLES:
 ]])
 end
 
-local FLAG_VALUE_NAMES = {
+local FLAG_VALUE_NAMES = { ---@type table<string, string>  -- bag: flag -> value metavar
 	["--source"]       = "FILE",
 	["--unity-root"]   = "FILE",
 	["--metadata"]     = "PATH",
@@ -315,9 +394,14 @@ local FLAG_VALUE_NAMES = {
 	["--elf"]          = "PATH",
 }
 
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @param flag    string
+--- @return string
+--- @return integer
 local function require_flag_value(argv, arg_idx, flag)
-	local value      = argv[arg_idx + 1]
-	local next_known = type(value) == "string"
+	local value      = argv[arg_idx + 1]       ---@type string|nil
+	local next_known = type(value) == "string" ---@type boolean
 		and (FLAG_HANDLERS[value] ~= nil or PASS_FLAG_TO_NAME[value] ~= nil)
 	if value == nil or next_known then
 		io.stderr:write("ps1_meta: " .. flag .. " requires " .. FLAG_VALUE_NAMES[flag] .. "\n")
@@ -331,49 +415,81 @@ end
 -- Populated AFTER print_help so the --help handler can reference it as an upvalue (Lua resolves locals at closure-call time, 
 -- but if the closure is defined before the local, it falls back to _G). 
 
+--- @param args ParsedArgs
+--- @return nil
 FLAG_HANDLERS["--help"]    = function(args) print_help(); os.exit(0) end
+--- @param args ParsedArgs
+--- @return nil
 FLAG_HANDLERS["--verbose"] = function(args) args.verbose = true      end
 
+--- @param args    ParsedArgs
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @return integer
 FLAG_HANDLERS["--source"] = function(args, argv, arg_idx)
-	local value, value_idx = require_flag_value(argv, arg_idx, "--source")
+	local value, value_idx = require_flag_value(argv, arg_idx, "--source") ---@type string, integer
 	args.sources[#args.sources + 1] = value
 	return value_idx
 end
+--- @param args    ParsedArgs
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @return integer
 FLAG_HANDLERS["--unity-root"] = function(args, argv, arg_idx)
-	local value, value_idx = require_flag_value(argv, arg_idx, "--unity-root")
+	local value, value_idx = require_flag_value(argv, arg_idx, "--unity-root") ---@type string, integer
 	args.unity_root = value
 	return value_idx
 end
+--- @param args    ParsedArgs
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @return integer
 FLAG_HANDLERS["--metadata"] = function(args, argv, arg_idx)
-	local value, value_idx = require_flag_value(argv, arg_idx, "--metadata")
+	local value, value_idx = require_flag_value(argv, arg_idx, "--metadata") ---@type string, integer
 	args.metadata = value
 	return value_idx
 end
+--- @param args    ParsedArgs
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @return integer
 FLAG_HANDLERS["--out-root"] = function(args, argv, arg_idx)
-	local value, value_idx = require_flag_value(argv, arg_idx, "--out-root")
+	local value, value_idx = require_flag_value(argv, arg_idx, "--out-root") ---@type string, integer
 	args.out_root = value
 	return value_idx
 end
+--- @param args    ParsedArgs
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @return integer
 FLAG_HANDLERS["--project-root"] = function(args, argv, arg_idx)
-	local value, value_idx = require_flag_value(argv, arg_idx, "--project-root")
+	local value, value_idx = require_flag_value(argv, arg_idx, "--project-root") ---@type string, integer
 	args.project_root = value
 	return value_idx
 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`).
+--- @param args ParsedArgs
+--- @return nil
 FLAG_HANDLERS["--gdb-runtime"] = function(args)
 	args.flags = args.flags or {}
 	args.flags.gdb_runtime = true
 end
+--- @param args    ParsedArgs
+--- @param argv    string[]
+--- @param arg_idx integer
+--- @return integer
 FLAG_HANDLERS["--elf"] = function(args, argv, arg_idx)
-	local value, value_idx = require_flag_value(argv, arg_idx, "--elf")
+	local value, value_idx = require_flag_value(argv, arg_idx, "--elf") ---@type string, integer
 	args.flags = args.flags or {}
 	args.flags.elf_path = value
 	return value_idx
 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.
+--- @param args ParsedArgs
+--- @return nil
 FLAG_HANDLERS["--dwarf-injection"] = function(args)
 	args.flags                 = args.flags or {}
 	args.flags.dwarf_injection = true
@@ -381,12 +497,16 @@ FLAG_HANDLERS["--dwarf-injection"] = function(args)
 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.
+--- @param args ParsedArgs
+--- @return nil
 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.
+--- @param args ParsedArgs
+--- @return nil
 FLAG_HANDLERS["--post-link"]      = function(args)
 	args.flags = args.flags or {}
 	args.flags.gdb_runtime     = true
@@ -397,8 +517,11 @@ end
 -- `--dwarf-injection` also emits atom-local debug data.
 
 -- Pass-flag handler. Reads the closed-set table, expands --all, appends to requested_set.
+--- @param args ParsedArgs
+--- @param a    string
+--- @return nil
 FLAG_HANDLERS[PASS_FLAG_DISPATCH_KEY] = function(args, a)
-	local name = PASS_FLAG_TO_NAME[a]
+	local name = PASS_FLAG_TO_NAME[a] ---@type string|nil
 	if name == ALL_PASSES_SENTINEL then
 		request_all_passes(args)
 		return
@@ -410,7 +533,7 @@ end
 --- @param argv string[]
 --- @return ParsedArgs
 local function parse_args(argv)
-	local args = {
+	local args = { ---@type ParsedArgs
 		requested_set = {},
 		sources       = {},
 		unity_root    = nil,
@@ -420,10 +543,10 @@ local function parse_args(argv)
 		verbose       = false,
 	}
 
-	local pos = 1
+	local pos = 1 ---@type integer
 	while pos <= #argv do
-		local a       = argv[pos]
-		local handler = FLAG_HANDLERS[a]
+		local a       = argv[pos]        ---@type string
+		local handler = FLAG_HANDLERS[a] ---@type FlagHandler|nil
 		if handler then
 			pos = handler(args, argv, pos) or pos
 		elseif PASS_FLAG_TO_NAME[a] then
@@ -448,14 +571,14 @@ local function parse_args(argv)
 	-- `<repo>/code/duffle/word_count.metadata.h` is the canonical metadata location. 
 	-- `project_root` names `<repo>`; the resolver derives `<project_root>/code` separately.
 	if not args.project_root then
-		local metadata_dir = duffle.dirname(duffle.normalize_path(args.metadata))
-		local code_root    = duffle.dirname(metadata_dir)
+		local metadata_dir = duffle.dirname(duffle.normalize_path(args.metadata)) ---@type string
+		local code_root    = duffle.dirname(metadata_dir)                         ---@type string
 		args.project_root  = duffle.dirname(code_root)
 	else
 		args.project_root = duffle.normalize_path(args.project_root)
 	end
 
-	local has_unity = type(args.unity_root) == "string" and args.unity_root ~= ""
+	local has_unity = type(args.unity_root) == "string" and args.unity_root ~= "" ---@type boolean
 	if has_unity and #args.sources > 0 then
 		io.stderr:write("ps1_meta: --unity-root FILE and --source FILE are mutually exclusive\n")
 		os.exit(EXIT_INTERNAL_ERROR)
@@ -468,10 +591,10 @@ local function parse_args(argv)
 	-- 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
+	local flags      = args.flags or {}                             ---@type PassFlags
+	local elf_path   = flags.elf_path                               ---@type string|nil
+	local has_elf    = type(elf_path) == "string" and #elf_path > 0 ---@type boolean
+	local post_links = flags.gdb_runtime or flags.dwarf_injection   ---@type boolean
 	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)
@@ -490,9 +613,9 @@ end
 --- @param args ParsedArgs
 --- @return PassCtx
 local function build_ctx(args)
-	local normalized_project_root  = duffle.normalize_path(args.project_root)
-	local project_root             = normalized_project_root
-	local project_root_is_absolute = normalized_project_root:match("^%a:/")
+	local normalized_project_root  = duffle.normalize_path(args.project_root) ---@type string
+	local project_root             = normalized_project_root                  ---@type string
+	local project_root_is_absolute = normalized_project_root:match("^%a:/")   ---@type boolean
 		or normalized_project_root:sub(1, 2) == "//"
 		or normalized_project_root:sub(1, 1) == "/"
 	if not project_root_is_absolute then
@@ -503,9 +626,9 @@ local function build_ctx(args)
 		-- Do not route POSIX/UNC/drive-absolute paths through to_absolute_path.
 		duffle.canonical_path_key(project_root)
 	end
-	local resolution
+	local resolution ---@type Corpus
 	if args.unity_root then
-		local ok_resolve, resolved = pcall(duffle.resolve_source_corpus, {
+		local ok_resolve, resolved = pcall(duffle.resolve_source_corpus, { ---@type boolean, Corpus|string
 			unity_root   = args.unity_root,
 			project_root = project_root,
 		})
@@ -515,59 +638,18 @@ local function build_ctx(args)
 		end
 		resolution = resolved
 	else
-		local source_order    = {}
-		local sources_by_path = {}
-		local resolver = {
-			resolved = {},
-			skipped  = {},
-			shadowed = {},
-		}
-		for _, input_path in ipairs(args.sources) do
-			local path = duffle.normalize_path(input_path)
-			local key_ok, key_or_error = pcall(duffle.canonical_path_key, path)
-			if not key_ok then
-				error("ps1_meta: invalid --source " .. input_path .. ": " .. tostring(key_or_error), 0)
-			end
-			local file = io.open(path, "r")
-			if not file then
-				io.stderr:write("ps1_meta: cannot open --source " .. input_path .. "\n")
+		local ok_exact, exact = pcall(duffle.resolve_exact_sources, { ---@type boolean, Corpus|string
+			sources      = args.sources,
+			project_root = project_root,
+		})
+		if not ok_exact then
+			io.stderr:write("ps1_meta: cannot resolve --source: " .. tostring(exact) .. "\n")
 			os.exit(EXIT_INTERNAL_ERROR)
 		end
-			local text = file:read("*a")
-			file:close()
-
-			local source = {
-				path     = path,
-				text     = text,
-				dir      = duffle.dirname(path),
-				basename = duffle.basename_no_ext(path),
-			}
-			source_order[#source_order + 1] = source
-			local key = key_or_error
-			if not sources_by_path[key] then sources_by_path[key] = source end
-			resolver.resolved[#resolver.resolved + 1] = {
-				include_path  = path,
-				include_text  = nil,
-				root_source   = nil,
-				root_line     = nil,
-				candidate_a   = path,
-				candidate_b   = nil,
-				selected_path = path,
-				disposition   = "exact",
-			}
-		end
-		resolution = {
-			unity_root      = nil,
-			project_root    = project_root,
-			code_root       = duffle.normalize_path(project_root .. "/code"),
-			source_order    = source_order,
-			sources_by_path = sources_by_path,
-			sources_by_dir  = duffle.group_sources_by_dir(source_order),
-			resolver        = resolver,
-		}
+		resolution = exact
 	end
 
-	local corpus = {
+	local corpus = { ---@type Corpus
 		unity_root              = resolution.unity_root,
 		project_root            = resolution.project_root,
 		code_root               = resolution.code_root,
@@ -584,11 +666,12 @@ local function build_ctx(args)
 		atom_phases             = {},
 		word_counts             = {},
 		components              = {},
-		component_body_index    = {},
+		atom_bundles            = {},
+		tape_emits              = {},
 		collisions              = {},
 		resolver                = resolution.resolver,
 	}
-	local ctx = {
+	local ctx = { ---@type PassCtx
 		metadata_path = args.metadata,
 		shared        = { corpus = corpus },
 		out_root      = args.out_root,
@@ -617,15 +700,15 @@ end
 --- Keeping these blocks local makes the topological sort self-contained.
 local function topo_sort(passes, requested_set)
 	-- Dependency closure: include every pass transitively required by `requested_set`.
-	local needed = {}
-	for _, name in ipairs(requested_set) do needed[name] = true end
-	local changed = true
+	local needed = {}                                               ---@type table<string, boolean>  -- bag: pass name -> needed
+	for _, name in ipairs(requested_set) do needed[name] = true end ---@type integer, string
+	local changed = true                                            ---@type boolean
 	while changed do
 		changed = false
-		for name, _ in pairs(needed) do
-			local pass = passes[name]
+		for name, _ in pairs(needed) do ---@type string, boolean
+			local pass = passes[name] ---@type PassDescriptor
 			if not pass then error("unknown pass '" .. name .. "' requested") end
-			for _, dep in ipairs(pass.deps) do
+			for _, dep in ipairs(pass.deps) do ---@type integer, string
 				if not needed[dep] then
 					needed[dep] = true
 					changed = true
@@ -635,10 +718,10 @@ local function topo_sort(passes, requested_set)
 	end
 
 	-- In-degree calculation: count each needed pass's needed dependencies.
-	local in_degree = {}
-	for name, _ in pairs(needed) do in_degree[name] = 0 end
-	for name, _ in pairs(needed) do
-		for _, dep in ipairs(passes[name].deps) do
+	local in_degree = {}                                    ---@type table<string, integer>  -- bag: pass name -> in-degree
+	for name, _ in pairs(needed) do in_degree[name] = 0 end ---@type string, boolean
+	for name, _ in pairs(needed) do                         ---@type string, boolean
+		for _, dep in ipairs(passes[name].deps) do ---@type integer, string
 			if needed[dep] then
 				in_degree[name] = in_degree[name] + 1
 			end
@@ -646,21 +729,21 @@ local function topo_sort(passes, requested_set)
 	end
 
 	-- Ready-queue seeding: add zero-in-degree passes in deterministic order.
-	local ready = {}
-	for name, deg in pairs(in_degree) do
+	local ready = {}                     ---@type string[]
+	for name, deg in pairs(in_degree) do ---@type string, integer
 		if deg == 0 then ready[#ready + 1] = name end
 	end
 	table.sort(ready)
 
 	-- Ready-queue drain: decrement dependents when each pass is emitted.
 	-- Newly-zero-degree passes are inserted back into the ready queue (kept sorted).
-	local order = {}
+	local order = {} ---@type string[]
 	while #ready > 0 do
-		local just_finished = table.remove(ready, 1)
+		local just_finished = table.remove(ready, 1) ---@type string
 		order[#order + 1] = just_finished
-		for name, _ in pairs(needed) do
+		for name, _ in pairs(needed) do ---@type string, boolean
 			if name ~= just_finished then
-				for _, dep in ipairs(passes[name].deps) do
+				for _, dep in ipairs(passes[name].deps) do ---@type integer, string
 					if dep == just_finished then
 						in_degree[name] = in_degree[name] - 1
 						if in_degree[name] == 0 then
@@ -676,10 +759,10 @@ local function topo_sort(passes, requested_set)
 	-- Cycle detection: if `order` doesn't include all needed passes, some are stuck with in_degree > 0
 	-- (the cycle closed on itself before Kahn could process them).
 	-- Without this check, a fully-closed cycle (e.g. A -> B -> A) would silently return an empty order list, leaving the orchestrator to dispatch nothing.
-	local needed_count = 0
-	for _ in pairs(needed) do needed_count = needed_count + 1 end  -- count hash entries; Lua's #t doesn't work
+	local needed_count = 0                                        ---@type integer
+	for _ in pairs(needed) do needed_count = needed_count + 1 end ---@type string -- count hash entries; Lua's #t doesn't work
 	if #order ~= needed_count then
-		for name, deg in pairs(in_degree) do
+		for name, deg in pairs(in_degree) do ---@type string, integer
 			if deg > 0 then
 				error("dependency cycle detected involving pass '" .. name .. "'")
 			end
@@ -693,19 +776,19 @@ end
 -- Main Orchestrator
 -- ════════════════════════════════════════════════════════════════════════════
 
---- (internal) If the pass's kind is in PASS_KIND_STOP_ON_ERROR and it reported errors, write each error to stderr.
---- Returns true if any validation errors were reported.
+--- (internal) Write every pass error to stderr.
+--- Returns true only when the pass kind still stops the build.
 --- @param pass_name string
 --- @param pass      PassDescriptor
 --- @param result    PassResult
 --- @return boolean
 local function report_validation_errors(pass_name, pass, result)
-	local   has_errors = result.errors and #result.errors > 0
-	if not (has_errors and PASS_KIND_STOP_ON_ERROR[pass.kind]) then return false end
-	for _, e in ipairs(result.errors) do
+	local has_errors = result.errors and #result.errors > 0 ---@type boolean
+	if not has_errors then return false end
+	for _, e in ipairs(result.errors) do ---@type integer, Finding
 		io.stderr:write(string.format("[%s] line %d: %s\n", pass_name, e.line or 0, e.msg or ""))
 	end
-	return true
+	return PASS_KIND_STOP_ON_ERROR[pass.kind] == true
 end
 
 --- (internal) Run each pass in `order` in topological sequence.
@@ -713,11 +796,11 @@ end
 --- @param order string[]
 --- @return boolean  -- true if any validation errors were reported
 local function dispatch_passes(ctx, order)
-	local had_errors = false
-	for _, pass_name in ipairs(order) do
-		local pass   = PASSES[pass_name]
-		local mod    = require(pass.module)
-		local result = mod.run(ctx)
+	local had_errors = false             ---@type boolean
+	for _, pass_name in ipairs(order) do ---@type integer, string
+		local pass   = PASSES[pass_name]    ---@type PassDescriptor
+		local mod    = require(pass.module) ---@type PassModule
+		local result = mod.run(ctx)         ---@type PassResult
 		if report_validation_errors(pass_name, pass, result) then
 			had_errors = true
 		end
@@ -727,16 +810,16 @@ end
 
 --- Main entry point. Runs the requested passes in dep-topological order.
 --- @param argv string[]
+--- @return nil
 local function main(argv)
-	local ok, err = pcall(function()
-		local args = parse_args(argv)
-		local ctx  = build_ctx(args)
+	local ok, err = pcall(function() ---@type boolean, string|nil
+		local args = parse_args(argv) ---@type ParsedArgs
+		local ctx  = build_ctx(args)  ---@type PassCtx
 		
-		local requested = args.requested_set
-		local closed    = topo_sort(PASSES, requested)
+		local requested = args.requested_set           ---@type string[]
+		local closed    = topo_sort(PASSES, requested) ---@type string[]
 
-		local had_errors = dispatch_passes(ctx, closed)
-		if had_errors then os.exit(EXIT_VALIDATION_ERRORS) end
+		dispatch_passes(ctx, closed)
 	end)
 
 	if not ok then
@@ -750,7 +833,7 @@ end
 -- Module export for in-process consumers (tests that dofile this script).
 -- 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 = {
+local _M = { ---@type Ps1MetaMod
 	PASSES                   = PASSES,
 	PASS_KIND_STOP_ON_ERROR  = PASS_KIND_STOP_ON_ERROR,
 	parse_args               = parse_args,

scripts/update_deps.ps1

@@ -91,11 +91,9 @@ if (-not (Test-Path -LiteralPath $path_pcsx_packages)) {
     New-Item -ItemType Directory -Path $path_pcsx_packages -Force | Out-Null
 }
 
-# Download anything missing. Skip the package entirely if its dir already has
-# any contents (the legacy packages.config style means the targets file
-# location varies per package — `luajit.native` puts it at build/native/,
-# `glfw` puts it elsewhere — so we can't probe a specific path; just check
-# whether the dir is non-empty).
+# Download anything missing.
+# Skip the package entirely if its dir already has any contents (the legacy packages.config style means the targets file location varies per package 
+# — `luajit.native` puts it at build/native/, `glfw` puts it elsewhere — so we can't probe a specific path; just check whether the dir is non-empty).
 Add-Type -AssemblyName System.IO.Compression.FileSystem
 foreach ($pkg in $required_packages.Values) {
     $pkgDir = Join-Path $path_pcsx_packages ('{0}.{1}' -f $pkg.id, $pkg.version)
@@ -122,24 +120,18 @@ foreach ($pkg in $required_packages.Values) {
     }
 }
 
-# ════════════════════════════════════════════════════════════════════════════
-# isoffi.lua size guard — `core.vcxproj` #includes src/core/isoffi.lua into
-# luaiso.cc via the `-- lualoader, R"EOF(...)EOF"` trick. The raw string
-# literal between R"EOF(-- and -- )EOF" must stay under ~16,379 bytes or
-# MSVC (19.44) fails with C2026 (its actual raw-string limit is 16,384,
-# minus 5 bytes for the `-- lualoader, ` prefix). If the upstream file
-# grows past that, trim it: remove license header, trailing whitespace,
-# blank separators, inline comments, and shrink 4-space indent to 2-space.
+# ════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+# isoffi.lua size guard — `core.vcxproj` #includes src/core/isoffi.lua into luaiso.cc via the `-- lualoader, R"EOF(...)EOF"` trick.
+# The raw string literal between R"EOF(-- and -- )EOF" must stay under ~16,379 bytes or MSVC (19.44) fails with C2026 (its actual raw-string limit is 16,384, minus 5 bytes for the `-- lualoader, ` prefix).
+# If the upstream file grows past that, trim it: remove license header, trailing whitespace, blank separators, inline comments, and shrink 4-space indent to 2-space.
 # Idempotent — only writes when the raw string exceeds the limit.
-# ════════════════════════════════════════════════════════════════════════════
+# ════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
 $path_isoffi = join-path $path_pcsx_redux 'src\core\isoffi.lua'
 if (Test-Path -LiteralPath $path_isoffi) {
     $content = Get-Content -LiteralPath $path_isoffi -Raw -Encoding utf8
     $startMarker = $content.IndexOf('R"EOF(--')
     $endMarker   = $content.IndexOf('-- )EOF"')
-    $literalLen  = if ($startMarker -ge 0 -and $endMarker -gt $startMarker) {
-        $endMarker - ($startMarker + 8)
-    } else { -1 }
+    $literalLen  = if ($startMarker -ge 0 -and $endMarker -gt $startMarker) { $endMarker - ($startMarker + 8) } else { -1 }
     # Effective MSVC raw-string limit for the lualoader prefix is 16379 bytes.
     if ($literalLen -gt 16379) {
         Write-Host "isoffi.lua raw string is $literalLen bytes (>16379); trimming for MSVC C2026 limit."
@@ -168,8 +160,7 @@ if (Test-Path -LiteralPath $path_isoffi) {
             $newLines += $line
         }
         ($newLines -join "`n") | Out-File -LiteralPath $path_isoffi -Encoding utf8 -NoNewline
-        $newLen = ((Get-Content -LiteralPath $path_isoffi -Raw -Encoding utf8) `
-            -replace '.*R"EOF\(--', '' -replace '-- \)EOF".*', '').Length
+        $newLen = ((Get-Content -LiteralPath $path_isoffi -Raw -Encoding utf8) -replace '.*R"EOF\(--', '' -replace '-- \)EOF".*', '').Length
         Write-Host "isoffi.lua trimmed: $literalLen -> $newLen bytes of raw string content."
     }
 }
@@ -231,13 +222,11 @@ $lfs_dll_import = join-path $luajit_lib_dir 'libluajit-5.1.dll.a'
 
 $path_openbios = join-path $path_pcsx_redux 'src\mips\openbios'
 
-# Wipe stale *.dep files across src\mips. These cache absolute paths to the
-# GCC headers directory; if the toolchain was upgraded (e.g. v14.2.0 → v16.1.0)
+# Wipe stale *.dep files across src\mips.
+# These cache absolute paths to the GCC headers directory; if the toolchain was upgraded (e.g. v14.2.0 → v16.1.0)
 # Make reads the stale paths and aborts with "no rule to make target .../stddef.h".
-# `make clean` in openbios only clears its own dir — subdirs like
-# common/crt0/, modplayer/, and shell/ keep their stale .dep files. Easier to
-# just delete the lot before each build than to teach every Makefile about
-# deepclean recursion.
+# `make clean` in openbios only clears its own dir — subdirs like common/crt0/, modplayer/, and shell/ keep their stale .dep files.
+# Easier to just delete the lot before each build than to teach every Makefile about deepclean recursion.
 Get-ChildItem -Path (join-path $path_pcsx_redux 'src\mips') -Recurse -Filter '*.dep' -ErrorAction SilentlyContinue |
     ForEach-Object { Remove-Item -LiteralPath $_.FullName -Force }