buzzing brain.

some more review before bed.
Preparing for camera transformation chapter.
2026-08-05 15:18:49 +00:00 · 2026-08-05 02:48:05 -04:00 · 2026-08-05 02:00:41 -04:00 · 2026-08-05 01:21:25 -04:00 · 2026-08-05 01:08:01 -04:00 · 2026-08-04 23:34:00 -04:00
65 changed files with 15773 additions and 5526 deletions
@@ -17,3 +17,6 @@ toolchain/PSn00bSDK
 .vscode/settings.json
 toolchain/lfs
 toolchain/lpeg
 scratch
 toolchain/libpsn00b
@@ -24,7 +24,7 @@
 			"osx": {
 				"gdbpath": "gdb"
 			},
-			"executable": "${workspaceRoot}/build/hello_psyq.elf",
+			"executable": "${workspaceRoot}/build/hello_gte.elf",
 			"setupCommands": [
 				{ "text": "set mi-async off" },
 				{ "text": "set remotetimeout 0" },
@@ -33,7 +33,7 @@
 			],
 			"autorun": [
 				"monitor reset shellhalt",
-				"load hello_psyq.elf",
+				"load hello_gte.elf",
 				"source scripts/gdb/gdb_tape_atoms.gdb",
 				"tbreak main",
 				"continue"
@@ -59,40 +59,6 @@
 			"osx": {
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_gpu.elf",
 			"setupCommands": [
 				{ "text": "set mi-async off" },
 				{ "text": "set remotetimeout 0" },
 				{ "text": "set logging file build/gen/hello_gte.gdb.log" },
 				{ "text": "set logging redirect on" }
 			],
 			"autorun": [
 				"monitor reset shellhalt",
 				"load hello_gpu.elf",
 				"tbreak main",
 				"continue"
 			]
 		},
 		{
 			"name": "Debug: Hello GTE Psy-Q!",
 			"type": "gdb",
 			"request": "attach",
 			"target": "localhost:3333",
 			"remote": true,
 			"cwd": "${workspaceRoot}/build",
 			"valuesFormatting": "parseText",
 			"registerLimit": "1-32",
 			"frameFilters": false,
 			"showDevDebugOutput": false,
 			"printCalls": false,
 			"stopAtConnect": true,
 			"gdbpath": "gdb-multiarch",
 			"windows": {
 				"gdbpath": "gdb-multiarch.exe"
 			},
 			"osx": {
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_gte.elf",
 			"setupCommands": [
 				{ "text": "set mi-async off" },
@@ -108,7 +74,7 @@
 			]
 		},
 		{
-			"name": "Debug: Hello GTE Psy-Q! (atoms debug — DWARF-injected)",
+			"name": "Debug: Hello GTE!",
 			"type": "gdb",
 			"request": "attach",
 			"target": "localhost:3333",
@@ -141,6 +107,76 @@
 				"tbreak main",
 				"continue"
 			]
 		},
 		{
 			"name": "Debug: Hello Joypad!",
 			"type": "gdb",
 			"request": "attach",
 			"target": "localhost:3333",
 			"remote": true,
 			"cwd": "${workspaceRoot}",
 			"valuesFormatting": "parseText",
 			"registerLimit": "1-32",
 			"frameFilters": false,
 			"showDevDebugOutput": false,
 			"printCalls": false,
 			"stopAtConnect": true,
 			"gdbpath": "gdb-multiarch",
 			"windows": {
 				"gdbpath": "gdb-multiarch.exe"
 			},
 			"osx": {
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_joypad.dwarf-injected.elf",
 			"setupCommands": [
 				{ "text": "set mi-async off" },
 				{ "text": "set remotetimeout 0" },
 				{ "text": "set logging file build/gen/hello_joypad.gdb.log" },
 				{ "text": "set logging redirect on" }
 			],
 			"autorun": [
 				"monitor reset shellhalt",
 				"load build/hello_joypad.dwarf-injected.elf",
 				"source scripts/gdb/gdb_tape_atoms.gdb",
 				"tbreak main",
 				"continue"
 			]
 		},
 		{
 			"name": "Debug: Hello Camera!",
 			"type": "gdb",
 			"request": "attach",
 			"target": "localhost:3333",
 			"remote": true,
 			"cwd": "${workspaceRoot}",
 			"valuesFormatting": "parseText",
 			"registerLimit": "1-32",
 			"frameFilters": false,
 			"showDevDebugOutput": false,
 			"printCalls": false,
 			"stopAtConnect": true,
 			"gdbpath": "gdb-multiarch",
 			"windows": {
 				"gdbpath": "gdb-multiarch.exe"
 			},
 			"osx": {
 				"gdbpath": "gdb"
 			},
 			"executable": "${workspaceRoot}/build/hello_camera.dwarf-injected.elf",
 			"setupCommands": [
 				{ "text": "set mi-async off" },
 				{ "text": "set remotetimeout 0" },
 				{ "text": "set logging file build/gen/hello_camera.gdb.log" },
 				{ "text": "set logging redirect on" }
 			],
 			"autorun": [
 				"monitor reset shellhalt",
 				"load build/hello_camera.dwarf-injected.elf",
 				"source scripts/gdb/gdb_tape_atoms.gdb",
 				"tbreak main",
 				"continue"
 			]
 		}
 	]
 }
@@ -1,201 +0,0 @@
 /*
 * atom_dsl.h
 * ============================================================================
 *
 * ATOM DSL: Annotation layer for tape atoms (lottes_tape.h).
 *
 *   WHAT THIS HEADER IS
 *   -------------------
 *   The metaprogram (scripts/passes/annotation.lua) reads source-as-written
 *   and validates:
 *     - atom_info(...) shape: up to three sub-calls (atom_bind(Binds_X),
 *       atom_reads(...), atom_writes(...)) in any order. All optional.
 *       (No phase token for now; phases may be reintroduced later.)
 *     - rbind atoms (atom_info(..., atom_bind(Binds_X), ...)) reference a
 *       real Binds_* struct declaration.
 *     - wave-context positions only reference the canonical 4-register
 *       set: R_PrimCursor / R_FaceCursor / R_VertBase / R_OtBase.
 *     - atom word-counts in word_counts.metadata.h agree with the body's
 *       actual .word count.
 *
 *   WHY A PURE MACRO (atom_info, atom_bind, atom_reads, atom_writes, atom_label)
 *   -----------------------------------------------------------------
 *   Each of these expands to a C comment or to nothing. The C preprocessor
 *   strips them to whitespace. The metaprogram reads the literal token from
 *   source-as-written, NOT from the preprocessed output. This means:
 *     - the C compiler does no work for them (no __attribute__, no
 *       _Pragma, no asm side-effects)
 *     - they can never silently drift from the metaprogram's view
 *       (the metaprogram re-reads the source on every build)
 *     - the annotation is invisible to the linker, debugger, and IDE
 *
 * ============================================================================
 *
 *  Usage:
 *      MipsAtom_(cube_tri) atom_info(
 *         atom_reads (R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *       , atom_writes(R_PrimCursor, R_FaceCursor)
 *      ){
 *          atom_label(culling),
 *          // ... atom body ...
 *          atom_offset(culling, bounds_chk)         // branch target, validated
 *          // ... atom body ...
 *          atom_label(bounds_chk),
 *      };
 *
 *
 *  Data Binding pattern -- atom_bind as a sub-call of atom_info
 *
 *      // Wave-context register layout (declarative):
 *      typedef Struct_(Binds_TrackFaceBatch) { 
 * 					U4 PrimCursor; 
 * 					U4 FaceCursor;
 *          U4 VertBase;
 * 					U4 OtBase;
 *      };
 *      MipsAtom_(rbind_track_face_batch) atom_info(
 *         atom_bind(Binds_TrackFaceBatch)
 *       , atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *      ){ ... };
 *
 *  Annotation rules
 *  ----------------
 *      1. atom_info(...) is OPTIONAL. Most atoms have no annotation.
 *         Atoms without atom_info are silently skipped by the metaprogram.
 *
 *      2. If present, atom_info takes up to three sub-calls, all
 *         order-independent within the arg list:
 *           - atom_bind(Binds_X) (optional; only for rbind atoms)
 *           - atom_reads(...) (optional; wave-context registers)
 *           - atom_writes(...) (optional; wave-context registers)
 *
 *      3. atom_bind(Binds_X) pins the ABI-struct shape -- the metaprogram
 *         cross-references Binds_X against the
 *         `typedef struct Binds_X { ... } Binds_X;` declaration.
 *
 *      4. atom_reads(...) and atom_writes(...) args are wave-context
 *         registers: R_PrimCursor / R_FaceCursor / R_VertBase / R_OtBase.
 *         Closed set. GTE / SP / DMA / I/O state is declared in source
 *         comments, not in atom_reads/atom_writes.
 *
 *      5. atom_label(name) is an anchor -- the macro is empty in C; the
 *         metaprogram records the marker at the current pos for offset
 *         calculation.
 *
 *      6. atom_offset(F, T) is resolved by gen/atom_offsets.h, generated
 *         from the atom_label markers.
 */
 #ifdef INTELLISENSE_DIRECTIVES
 #pragma once
 // #include <stdint.h>
 #endif
 /* ============================================================================
 * WAVE-CONTEXT REGISTERS -- canonical register set for the tape wave model.
 *
 *   R_PrimCursor  output pointer into the prim arena (next OT entry to write)
 *   R_FaceCursor  input pointer into the face array (next face to consume)
 *   R_VertBase    base pointer into the vertex arena (this wave's vertices)
 *   R_OtBase      base pointer into the ordering table (this wave's OT slot)
 *
 * Closed set. If your atom needs to touch GTE / SP / DMA / other side state,
 * declare it at the source level as you normally would -- but DO NOT put
 * those registers in atom_reads/atom_writes.
 *
 * ============================================================================*/
 /* ============================================================================
 * atom_reads(...) / atom_writes(...) -- wave-context register list
 *
 *   atom_reads(R_PrimCursor, R_FaceCursor)
 *         ->  (R_PrimCursor, R_FaceCursor)   // comma-evaluated, discarded
 *
 * The macro produces a comma-evaluated expression that the C compiler
 * silently discards (it sits in an unused arg position -- the result is
 * never bound). The Lua tool pattern-matches the "atom_reads(...)" /
 * "atom_writes(...)" token to extract the list.
 *
 * You can have at most one atom_reads(...) and at most one atom_writes(...)
 * in an atom_info(...) call. To declare multiple disjoint sets (rare), just
 * declare the union -- the metaprogram doesn't track which reads need which
 * writes at this granularity.
 *
 * ============================================================================*/
 #define atom_reads(...)  (__VA_ARGS__)
 #define atom_writes(...) (__VA_ARGS__)
 /* ============================================================================
 * ATOM ANNOTATION MACROS
 *
 *   atom_info -- single unified annotation. OPTIONAL. Most atoms have none.
 *
 *      MipsAtom_(cube_tri) atom_info(
 *         atom_reads (R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *       , atom_writes(R_PrimCursor, R_FaceCursor)
 *      ){ ... };
 *
 *   Shape (sub-args order-independent; all optional):
 *     - atom_bind(Binds_X):  at most one; pins the ABI-struct shape
 *     - atom_reads(...):     at most one; comma-list of wave-context registers
 *     - atom_writes(...):    at most one; comma-list of wave-context registers
 *
 *   No phase token for now. The metaprogram doesn't check ordering across
 *   atoms -- phases (init / bind / setup / work / commit / terminate) will
 *   be reintroduced when ordering checks are added.
 *
 *   The macro expands to a C comment (or to nothing). The C compiler does
 *   no work. The metaprogram reads the source-as-written directly.
 *
 * ============================================================================*/
 #define atom_info(...)  /* atom_info(__VA_ARGS__) */
 /* ----------------------------------------------------------------------------
 * atom_bind(Binds_X) -- rbind sub-call of atom_info
 *
 *   MipsAtom_(rbind_cube_tri) atom_info(
 *         atom_bind(Binds_CubeTri)
 *       , atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *   ){ ... };
 *
 * The Binds_X MUST be a typedef'd type (declared via
 * `typedef struct Binds_X { ... } Binds_X;` somewhere in the source).
 * The Lua tool cross-references this. Missing struct = error.
 *
 * atom_bind is a SUB-CALL of atom_info, not a standalone annotation macro.
 *
 * The macro expands to a C comment. The metaprogram reads source-as-written.
 * ----------------------------------------------------------------------------*/
 #define atom_bind(binds_struct)  /* atom_bind(binds_struct) */
 /* ============================================================================
 * atom_label / atom_offset — branch target machinery
 *
 *   atom_label(culling)                      ← nothing in C; anchor only
 *   ... body ...
 *   atom_label(bounds_chk)                   ← another anchor
 *
 *   atom_offset(culling, bounds_chk)         ← resolved by gen/.offsets.h
 *
 * The metaprogram generates gen/atom_offsets.h with one
 *   #define atom_offset__culling__bounds_chk  ((target - branch_pos - 1))
 * per atom_offset(F, T) call. The preprocessor then expands your call to
 * the right immediate value.
 *
 * If gen/atom_offsets.h is stale (or atom_label(name) is undefined),
 * `atom_offset__F__T` becomes an undefined macro and the C build fails.
 * This catches:
 *   - typo in atom_label (no anchor → metaprogram doesn't emit the macro)
 *   - .offsets.h not regenerated after body edits
 *   - body edit that broke the offset math (recompile + retest picks it up
 *     in CPU emulator)
 *
 * ============================================================================*/
 #define atom_offset(F, T) atom_offset_ ## F ## _ ## T
 /* atom_label is a pure annotation for the metaprogram's offset calculations.
 * The macro expands to a C comment, so the C preprocessor strips it to
 * whitespace — NO instruction word is emitted in the asm. The metaprogram
 * still recognises the literal `atom_label(name)` token in source and
 * records the marker at the current pos. */
 #define atom_label(name) /* atom_label anchor: name */
@@ -0,0 +1,159 @@
 /*
 * dsl.atom.h
 * ============================================================================
 *
 * ATOM DSL: Annotation layer for tape atoms (lottes_tape.h).
 * The metaprogram (scripts/passes/annotation.lua) reads source-as-written and validates:
 *   - atom_info(...) shape: up to three sub-calls (atom_bind(Binds_X), atom_reads(...), atom_writes(...)) in any order and are optional.
 *   - rbind atoms (atom_info(..., atom_bind(Binds_X), ...)) reference a real Binds_* struct declaration.
 *   - atom word-counts in word_counts.metadata.h match the body's actual .word count.
 *
 * Pure macro anntation.
 * ---------------
 * Don't want to constraint the macro usage to some attribute placment constraint, etc, don't want ot dela with the compiler.
 * atom_info, atom_bind, atom_reads, atom_writes, atom_label, atom_dbg_skip each expand to a C comment or to nothing
 * (C preprocessor strips them to whitespace).
 *
 * ============================================================================
 *  Usage:
 *      MipsAtom_(cube_tri) atom_info(
 *         atom_reads (R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *       , atom_writes(R_PrimCursor, R_FaceCursor)
 *      ){
 *          atom_label(culling),
 *          // ... atom body ...
 *          atom_offset(culling, bounds_chk)         // branch target, validated
 *          // ... atom body ...
 *          atom_label(bounds_chk),
 *      };
 *
 *
 *  Data Binding pattern -- atom_bind as a sub-call of atom_info
 *
 *      // Wave-context register layout (declarative):
 *      typedef Struct_(Binds_TrackFaceBatch) { 
 * 					U4 PrimCursor; 
 * 					U4 FaceCursor;
 *          U4 VertBase;
 * 					U4 OtBase;
 *      };
 *      MipsAtom_(rbind_track_face_batch) atom_info(
 *         atom_bind(Binds_TrackFaceBatch)
 *       , atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *      ){ ... };
 *
 *  Annotation rules
 *  ----------------
 *      1. atom_info(...) is OPTIONAL. Atoms without atom_info are silently skipped by the metaprogram.
 *      2. If present, atom_info takes up to three sub-calls, all order-independent within the arg list:
 *           - atom_bind(Binds_X)
 *           - atom_reads(...)
 *           - atom_writes(...)
 *      3. atom_bind(Binds_X): metaprogram cross-references Binds_X against the `typedef struct Binds_X { ... } Binds_X;` declaration.
 *      4. atom_reads(...) and atom_writes(...): Used to to check if registers are used correctly in macros: R_PrimCursor / R_FaceCursor / R_VertBase / R_OtBase.
 *      5. atom_label(name: Utilize with atom_offset as a target location.
 *      6. atom_offset(F, T): Resolved by gen/atom_offsets.h, generated from the atom_label markers. Calculated during the offset pass of the lua  metaprogram.
 */
 #ifdef INTELLISENSE_DIRECTIVES
 #pragma once
 #endif
 /* ============================================================================
 * atom_reads(...) / atom_writes(...)
 *
 * Used during the static analysis pass of the metaprogram to do
 * ============================================================================*/
 #define atom_reads(...)  (__VA_ARGS__)
 #define atom_writes(...) (__VA_ARGS__)
 /* ----------------------------------------------------------------------------
 * 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.
 * ----------------------------------------------------------------------------*/
 #define atom_reg /* atom_reg: opt the preceding enum entry into the DWARF registry */
 /* ============================================================================
 *   atom_info :
 *      MipsAtom_(cube_tri) atom_info(
 *         atom_reads (R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *       , atom_writes(R_PrimCursor, R_FaceCursor)
 *      ){ ... };
 * 
 *  - atom_bind(Binds_X): metaprogram cross-references Binds_X against the `typedef struct Binds_X { ... } Binds_X;` declaration.
 *  - atom_reads(...):    comma-list of registers
 *  - atom_writes(...):   comma-list of registers
 * ============================================================================*/
 #define atom_info(...)  /* atom_info(__VA_ARGS__) */
 /* ----------------------------------------------------------------------------
 * DEBUG SOURCE-STEP MARKER
 *
 * Place `atom_dbg_skip` (BARE) before a MipsAtom_, MipsAtomComp_, or MipsAtomComp_Proc_.
 * The following declaration kind determines whether the marker selects a whole atom or a component inline view.
 * The source scanner associates the marker with that declaration; placement diagnostics are handled by the annotation pass.
 *
 * Example:
 *     atom_dbg_skip MipsAtom_(tape_exit) { jump_reg(rret_addr), nop };
 *     atom_dbg_skip MipsAtomComp_(ac_yield) { ... };
 *     atom_dbg_skip MipsAtomComp_Proc_(ac_format_f3_color, { ... });
 * ----------------------------------------------------------------------------*/
 #define atom_dbg_skip /* atom_dbg_skip: skip the following atom or component source view */
 /* ----------------------------------------------------------------------------
 * Typed-view annotations (Registry for DWARF RR_<R_X> chain resolution)
 *   atom_type(<T>) -- overloaded:
 *      (a) enum-site default: `R_Foo = R_Tn, atom_reg atom_type(T)` 
 *      Sets the per-alias default typed view in the register_alias_registry.
 *      Consumed by the DWARF chain step (e) when no per-atom atom_ctx / atom_phase / atom_type callsite provides a stronger resolution.
 *      (b) callsite override: `atom_reads(R_Foo atom_type(T), ...)` Overrides the per-alias default for THIS atom only.
 *      Last-write-wins per R_Name; conflict -> error.
 *   atom_ctx(<atom_name>) -- atom-info sub-call:
 *       Propagate another atom's atom.rbind.fields (its Binds_* typed fields) into THIS atom's typed-view resolution.
 *       The named atom must be an rbind atom (have `atom_bind(Binds_X)` in its `atom_info`).
 *       Used as the escape hatch when atom_phase is not the natural correlation.
 *   atom_phase(<label>) -- atom-info sub-call: 
 *       Free-form C-identifier label for grouping atoms.
 *       Within a phase, the FIRST atom in source-order that owns its own atom.rbind provides 
 *       the Binds_* field types used by all other atoms in the same phase.
 *       The preferred correlation mechanism; atom_ctx is the escape hatch for non-natural cases.
 *
 * All three expand to C comments
 * (the bare-token convention matching `atom_reg` and `atom_dbg_skip`).
 * The Lua scanner reads the bare tokens in source-as-written; the C preprocessor strips them.
 * ----------------------------------------------------------------------------*/
 #define atom_type(T)        /* atom_type: associate <T> with the preceding enum entry (enum site) or this register (atom-info site) */
 #define atom_ctx(atom_name) /* atom_ctx: propagate <atom_name>'s Binds_* field types into this atom's typed views */
 #define atom_phase(label)   /* atom_phase: tag this atom with <label> for grouped typed-view resolution */
 /* ----------------------------------------------------------------------------
 * atom_bind(Binds_X) -- rbind sub-call of atom_info
 *
 *   MipsAtom_(rbind_cube_tri) atom_info(
 *         atom_bind(Binds_CubeTri)
 *       , atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 *   ){ ... };
 *
 * The Binds_X MUST be a typedef'd type (declared via `typedef struct Binds_X { ... } Binds_X;` somewhere in the source).
 * ----------------------------------------------------------------------------*/
 #define atom_bind(binds_struct)  /* atom_bind(binds_struct) */
 /* ============================================================================
 * atom_label / atom_offset — branch target machinery
 *
 *   atom_label(culling)                      ← nothing in C; anchor only
 *   ... body ...
 *   atom_label(bounds_chk)                   ← another anchor
 *
 *   atom_offset(culling, bounds_chk)         ← resolved by gen/offsets.h
 *
 * The metaprogram generates gen/offsets.h with one #define with the offset value per atom_offset(F, T) call.
 * The preprocessor then expands the call to the right immediate value.
 *
 * If gen/offsets.h is stale (or atom_label(name) is undefined), `atom_offset_F_T` becomes an undefined macro and the C build fails.
 * ============================================================================*/
 #define atom_offset(F, T) atom_offset_ ## F ## _ ## T
 // atom_label is a pure annotation for the metaprogram's offset calculations.
 #define atom_label(name) /* atom_label anchor: name */
@@ -43,7 +43,9 @@
 #define R_    restrict 
 #define V_    volatile 
-// Fictional, used for intiution.
+
 #pragma region Fictional //, used for intiution
 #define EUB_  restrict // Execute Unit Bound:    Data is siloed in the ALU Register File. The Load/Store Unit is bypassed. (Route to Execution Unit.  Keep in registers)
 #define ISO_  restrict // Isolated Provenance:   Alternative to Exu_. Guarantees electrical memory isolation, 
                       //                        unlocking the compiler’s ability to safely pack data across multiple parallel SIMD lanes (vectorization).
@@ -67,7 +69,8 @@
 #define latch_load_anchor(ptr)       //__atomic_load_n(ptr, ooo_anchor_)
 #define latch_store_drain(ptr, val)  //__atomic_store_n(ptr, val, ooo_drain_)
 #define pulse_xchg_weld(ptr, val)    //__atomic_exchange_n(ptr, val, ooo_weld_)
-//end of: Fictional.
+
 #pragma endreigon Fictional
 // R_ (restrict) establishes an "Eigen" or "Proprius" mapping.
@@ -135,16 +138,17 @@ enum { false = 0, true  = 1, true_overflow, };
 typedef void Proc_(VoidFn) (void);
-#define kilo(n)         (C_(U4, n) << 10)
+#define kilo(n)                (C_(U4, n) << 10)
-#define mega(n)         (C_(U4, n) << 20)
+#define mega(n)                (C_(U4, n) << 20)
-#define giga(n)         (C_(U4, n) << 30)
+#define giga(n)                (C_(U4, n) << 30)
-#define tera(n)         (C_(U4, n) << 40)
+#define tera(n)                (C_(U4, n) << 40)
-#define null             C_(U4,    0)
+
-#define nullptr          C_(void*, 0)
+#define null                    C_(U4,    0)
-#define O_(type, field) (C_(U4, & C_(type*,0)->field))
+#define nullptr                 C_(void*, 0)
- 
+#define O_(type, field)         C_(U4, & C_(type*,0)->field)
-#define OT_(field)       O_(typeof_ptr(& field), filed))
+#define OA_(type, member, idx)  C_(U4, & C_(type*,0)->member[idx])
-#define S_(data)         C_(U4, sizeof(data))
+#define OT_(field)              O_(typeof_ptr(& field), filed))
 #define S_(data)                C_(U4, sizeof(data))
 #define sop_1(op,a,b) C_(U1, s1_(a) op s1_(b))
 #define sop_2(op,a,b) C_(U2, s2_(a) op s2_(b))
@@ -218,3 +222,6 @@ IA_ void assert(U8 cond) { if(cond){return;} else{debug_trap(); ms_exit_process(
 #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")
@@ -50,17 +50,13 @@
 #define asm_words(...) m_expand(glue(GCC_ASM_INL_, GCC_ASM_COUNT_ARGS(__VA_ARGS__))(__VA_ARGS__))
 // Very nasty macro expansion. See the Cruft pragma region after all the DSL defines
-/* reg_str(n) — Stringify an integer register id into the GCC asm
+/* reg_str(n) — Stringify an integer register id into the GCC asm string form (e.g. 12 → "$12").
- * string form (e.g. 12 → "$12"). Use this anywhere GCC's parser
+ * Use this anywhere GCC's parser expects a literal string identifying a register: clobber lists,
- * expects a literal string identifying a register: clobber lists,
+ * asm templates, etc. The two-level macro is the standard preprocessor idiom for forcing one level of expansion before stringify —
- * asm templates, etc. The two-level macro is the standard preprocessor
+ * without it, `#n` would stringify the macro name `R_T4` to `"R_T4"` instead of expanding `R_T4` to its value first.
 * idiom for forcing one level of expansion before stringify — without
 * it, `#n` would stringify the macro name `R_T4` to `"R_T4"` instead
 * of expanding `R_T4` to its value first.
 *
- * For declaring a register variable bound to a specific GPR, use the
+ * For declaring a register variable bound to a specific GPR, use the `rgcc(n)` bundle from gcc_asm.h instead —
- * `rgcc(n)` bundle from gcc_asm.h instead — it adds the `__asm__()`
+ * it adds the `__asm__()` qualifier around the string.
 * qualifier around the string.
 *
 *   register V3_S2* p0 __asm__(reg_str(R_T4)) = ...;        // verbose
 *   register V3_S2* p0 rgcc(R_T4) = ...;                    // bundled
@@ -85,21 +81,19 @@
 *  - The string "$12" is derived from it via reg_str, so they cannot drift apart.
 *  - Spelling `__asm__(reg_str(R_T4_Code))` at every call site is noise.
 *
- *  tmpl defined in dsl.h (the token-paste glue). 
+ *  tmpl defined in dsl.h (token-paste glue). 
 *  rgcc define here (gcc_asm.h) because the `__asm__` keyword is GCC-specific. 
- *  Anyone porting to a different compiler's asm dialect overrides rgcc, 
+ *  Anyone porting to a different compiler's asm dialect overrides rgcc,
 *  and the integer→string derivation in rlit can be retargeted in one place.
 *
 *  For clobber lists and asm-template strings, use the bare `rlit(R_T4_Code)`.
 * ------------------------------------------------------------------------ */
 #define rgcc(n) __asm__(rlit(n))
-/* rgcc_ref(n) — GCC operand-reference form "%N". Not currently used
+/* rgcc_ref(n) — GCC operand-reference form "%N". Not currently used by the placeholder-pun macros
- * by the placeholder-pun macros (the .word bodies are fully baked
+ * (the .word bodies are fully baked at compile time and have no runtime operand references),
- * at compile time and have no runtime operand references), but kept
+ * but kept here for completeness in case a future asm template needs to refer to a runtime input by position.
- * here for completeness in case a future asm template needs to refer
+ * Mirror of rgcc but produces "%N" instead of "$N". */
 * to a runtime input by position. Mirror of rgcc but produces "%N"
 * instead of "$N". */
 #define rgcc_ref_(n)   "%" #n
 #define rgcc_ref(n)    rgcc_ref_(n)
@@ -147,11 +141,9 @@
    9,  8,  7,  6,  5,  4,  3,  2,  1,  0))
 /* --- 2. String Concatenation Helpers --- *
- * NOTE: we use `%0`, `%1`, ... not `%c0`, `%c1`, ... because GCC's
+ * NOTE: we use `%0`, `%1`, ... not `%c0`, `%c1`, ... because GCC's asm-parser rejects `%cN` in this position with "invalid use of '%c'".
- * asm-parser rejects `%cN` in this position with "invalid use of '%c'".
+ * The `%cN` form is for printing *character* constants; for arbitrary integer immediates (the only kind `"i"(...)` produces),
- * The `%cN` form is for printing *character* constants; for arbitrary
+ * the plain `%N` form is the right one. Both expand to the bare immediate.
 * integer immediates (the only kind `"i"(...)` produces), the plain
 * `%N` form is the right one. Both expand to the bare immediate.
 */
 #define GCC_ASM_W1                  "%0"
 #define GCC_ASM_W2   GCC_ASM_W1   ", %1"
@@ -1,126 +0,0 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #pragma once
 #endif
 // Auto-generated by ps1_meta.lua — DO NOT EDIT
 // Source: C:\projects\Pikuma\ps1\code\duffle\lottes_tape.h
 // Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)
 #ifndef WORD_COUNT
 #define WORD_COUNT(name, count)  enum { words_##name = (count) };
 #endif
 #define mac_yield(...) \
 	load_word(R_AtomJmp, R_TapePtr, 0) \
 ,	add_ui_self(         R_TapePtr, S_(MipsCode)) \
 ,	jump_reg( R_AtomJmp) \
 ,	nop
 WORD_COUNT(mac_yield, 4)
 /* Words: 3; Loads 3 S2 indices from the face array */
 #define mac_load_tri_indices(...) \
 	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))
 WORD_COUNT(mac_load_tri_indices, 3)
 /* Words: 18; Translates indices to vertex addresses and pushes them to GTE  */
 #define mac_gte_load_tri_verts(...) \
 	shift_lleft(R_AT, R_T0, v3s2_byteoff) \
 ,	add_u_self(R_AT, R_VertBase) \
 ,	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_T1, v3s2_byteoff) \
 ,	add_u_self(R_AT, R_VertBase) \
 ,	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_T2, v3s2_byteoff) \
 ,	add_u_self(R_AT, R_VertBase) \
 ,	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)
 WORD_COUNT(mac_gte_load_tri_verts, 18)
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
 * Hardcoded for Poly_F3 (5 words). For Poly_G4, use ac_insert_ot_tag_g4. */
 #define mac_insert_ot_tag_f3(...) \
 	shift_lleft( R_T1, R_T1, S_(U4)/2)                        /* T1 = otz * S_(U4) (otz arg is implicit R_T1) */ \
 ,	add_u_self(  R_T1, R_OtBase)                              /* T1 = & OrderingTable[OTZ] */ \
 ,	load_word(   R_AT, R_T1,         O_(PolyTag,code))        /* AT = old_ot_head */ \
 ,	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits) /* V0 = (5 - 1) << 24 = 4 << 24 */ \
 ,	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits))    /* Strip upper 8 bits (length from prev cell) → keep only low 24 */ \
 ,	or_u(        R_AT, R_AT, R_V0)                            /* Merge length */ \
 ,	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code))        /* prim->tag = packed(prim_length, old_addr) */ \
 ,	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits))    /* AT = (prim_length << 24) | old_addr */ \
 ,	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)) \
 ,	store_word(  R_AT, R_T1,         O_(PolyTag,code))        /* OrderingTable[OTZ] = PrimCursor */
 WORD_COUNT(mac_insert_ot_tag_f3, 11)
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
 * Hardcoded for Poly_G4 (9 words). For Poly_F3, use ac_insert_ot_tag_f3. */
 #define mac_insert_ot_tag_g4(...) \
 	shift_lleft( R_T1, R_T1, S_(U4)/2)                        /* T1 = otz * S_(U4) (otz arg is implicit R_T1) */ \
 ,	add_u_self(  R_T1, R_OtBase)                              /* T1 = & OrderingTable[OTZ] */ \
 ,	load_word(   R_AT, R_T1,         O_(PolyTag,code))        /* AT = old_ot_head */ \
 ,	load_upper_i(R_V0, (S_(Poly_G4)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits) /* V0 = (9 - 1) << 24 = 8 << 24 */ \
 ,	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits))    /* Strip upper 8 bits (length from prev cell) → keep only low 24 */ \
 ,	or_u(        R_AT, R_AT, R_V0)                            /* Merge length */ \
 ,	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code))        /* prim->tag = packed(prim_length, old_addr) */ \
 ,	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits))    /* AT = (prim_length << 24) | old_addr */ \
 ,	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)) \
 ,	store_word(  R_AT, R_T1,         O_(PolyTag,code))        /* OrderingTable[OTZ] = PrimCursor */
 WORD_COUNT(mac_insert_ot_tag_g4, 11)
 #define mac_pack_color_word(off, cmd, r, g, b) \
 	load_upper_i(R_AT, (cmd) << 8  | (b)) \
 ,	or_i_self(   R_AT, ((g)   << 8) | (r)) \
 ,	store_word(  R_AT, R_PrimCursor, (off))
 WORD_COUNT(mac_pack_color_word, 3)
 #define mac_format_f3_color(r, g, b) \
 	mac_pack_color_word(O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b)
 WORD_COUNT(mac_format_f3_color, 3)
 /* 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). */
 #define mac_gte_store_f3_post_rtpt(...) \
 	gte_sw(C2_SXY0, R_PrimCursor, O_(Poly_F3,p0)) \
 ,	gte_sw(C2_SXY1, R_PrimCursor, O_(Poly_F3,p1)) \
 ,	gte_sw(C2_SXY2, R_PrimCursor, O_(Poly_F3,p2))
 WORD_COUNT(mac_gte_store_f3_post_rtpt, 3)
 #define mac_format_g4_color(r0, g0, b0, r1, g1, b1, r2, g2, b2, r3, g3, b3) \
 	mac_pack_color_word(O_(Poly_G4,c0), gp0_cmd_poly_g4, r0,g0,b0) \
 ,	mac_pack_color_word(O_(Poly_G4,c1), 0,               r1,g1,b1) \
 ,	mac_pack_color_word(O_(Poly_G4,c2), 0,               r2,g2,b2) \
 ,	mac_pack_color_word(O_(Poly_G4,c3), 0,               r3,g3,b3)
 WORD_COUNT(mac_format_g4_color, 12)
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices of the
 * G4 triangle portion to p0/p1/p2.
 * 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).
 * The macro name declares the pipeline position; check #6 (GTE state-
 * machine validation) verifies the call site matches the declaration. */
 #define mac_gte_store_g4_p012_post_rtpt_pre_rtps(...) \
 	gte_sw(C2_SXY0, R_PrimCursor, O_(Poly_G4,p0)) \
 ,	gte_sw(C2_SXY1, R_PrimCursor, O_(Poly_G4,p1)) \
 ,	gte_sw(C2_SXY2, R_PrimCursor, O_(Poly_G4,p2))
 WORD_COUNT(mac_gte_store_g4_p012_post_rtpt_pre_rtps, 3)
 /* Words: 1; Stores the V3 screen coord to the G4's p3 slot.
 * 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 — DO NOT read SXY0 here, that's the bug this name
 * prevents).
 */
 #define mac_gte_store_g4_p3_post_rtps(...) \
 	gte_sw(C2_SXY2, R_PrimCursor, O_(Poly_G4,p3))
 WORD_COUNT(mac_gte_store_g4_p3_post_rtps, 1)
@@ -1,9 +0,0 @@
 // Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT
 // Source: C:\projects\Pikuma\ps1\code\duffle\lottes_tape.h
 #pragma once
 #pragma region lottes_tape
 #pragma endregion lottes_tape
@@ -0,0 +1,184 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #pragma once
 #endif
 // Auto-generated by ps1_meta.lua — DO NOT EDIT
 // Directory: C:\projects\Pikuma\ps1\code\duffle/
 //   source: C:\projects\Pikuma\ps1\code\duffle\word_count.metadata.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\dsl.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\memory.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\math.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\gcc_asm.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\gp.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\gte.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\dsl.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\lottes_tape.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.c
 //   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
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.atom.c
 // Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)
 #ifndef WORD_COUNT
 #define WORD_COUNT(name, count)  enum { words_##name = (count) };
 #endif
 /* atom_dbg_skip */
 /* ---------------------------------------------------------------------------
 *  MACRO ATOM Components (Reusable Assembly Components)
 *  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) \
 ,	add_ui_self(         R_TapePtr, S_(MipsCode)) \
 ,	jump_reg( R_AtomJmp) \
 ,	nop
 WORD_COUNT(mac_yield, 4)
 /* atom_dbg_skip */
 #define mac_yield_load(...) \
 	load_word(R_AtomJmp, R_TapePtr, 0)
 WORD_COUNT(mac_yield_load, 1)
 /* atom_dbg_skip */
 #define mac_yield_tail(...) \
 	add_ui_self(R_TapePtr, S_(MipsCode)) \
 ,	jump_reg(  R_AtomJmp) \
 ,	nop
 WORD_COUNT(mac_yield_tail, 3)
 /* atom_dbg_skip */
 #define mac_load_v2s2(rs_x, rs_y, r_base, offset) \
 	load_half( rs_x, r_base, O_(V3_S2,x)) \
 ,	load_half( rs_y, r_base, O_(V3_S2,y))
 WORD_COUNT(mac_load_v2s2, 2)
 /* atom_dbg_skip */
 #define mac_store_v2s2(rt_x, rt_y, base, offset) \
 	store_half(rt_x, base, offset + O_(V2_S2,x)) \
 ,	store_half(rt_y, base, offset + O_(V2_S2,y))
 WORD_COUNT(mac_store_v2s2, 2)
 /* 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)) \
 ,	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))
 WORD_COUNT(mac_store_rects2, 4)
 /* 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)) \
 ,	load_half_u(r_i1, r_face_cusor, 1 * S_(S2)) \
 ,	load_half_u(r_i2, r_face_cusor, 2 * S_(S2))
 WORD_COUNT(mac_load_tri_indices, 3)
 /* atom_dbg_skip */
 #define mac_gte_store_f3(r_primitive_cursor) \
 	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))
 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) \
 ,	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)
 WORD_COUNT(mac_gte_load_tri_verts, 18)
 /* atom_dbg_skip */
 #define mac_gte_store_g4_p012(r_primitive_cursor) \
 	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))
 WORD_COUNT(mac_gte_store_g4_p012, 3)
 /* atom_dbg_skip */
 #define mac_gte_store_g4_p3(r_primitive_cursor) \
 	gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p3))
 WORD_COUNT(mac_gte_store_g4_p3, 1)
 #define mac_gcmd_push(cmd, reg_transfer, reg_base, port) \
 	load_upper_i(reg_transfer, cmd >> 16) \
 ,	or_i_self(   reg_transfer, cmd & 0xFFFF) \
 ,	store_word(  reg_transfer, reg_base, port)
 WORD_COUNT(mac_gcmd_push, 3)
 /* atom_dbg_skip */
 #define mac_store_rgb8(rr, rg, rb, base, offset) \
 	store_byte(rr, base, offset + O_(RGB8,r)) \
 ,	store_byte(rg, base, offset + O_(RGB8,g)) \
 ,	store_byte(rb, base, offset + O_(RGB8,b))
 WORD_COUNT(mac_store_rgb8, 3)
 /* atom_dbg_skip */
 #define mac_pack_color_word(r_base, off, cmd, r, g, b) \
 	load_upper_i(R_AT, (cmd) << 8  | (b)) \
 ,	or_i_self(   R_AT, ((g)  << 8) | (r)) \
 ,	store_word(  R_AT, r_base, (off))
 WORD_COUNT(mac_pack_color_word, 3)
 /* atom_dbg_skip */
 #define mac_format_f3_color(r_base, r, g, b) \
 	mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b)
 WORD_COUNT(mac_format_f3_color, 3)
 #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) \
 ,	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c2), 0,               r2,g2,b2) \
 ,	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c3), 0,               r3,g3,b3)
 WORD_COUNT(mac_format_g4_color, 12)
 #define mac_insert_ot_tag_f3(r_ot_base, r_prim_cursor) \
 	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 */ \
 ,	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits) /* V0 = (5 - 1) << 24 = 4 << 24 */ \
 ,	mask_upper(  R_AT, R_AT,          S_(PolyTag_len_bits))   /* Strip upper 8 bits (length from prev cell) → keep only low 24 */ \
 ,	or_u(        R_AT, R_AT, R_V0)                            /* Merge length */ \
 ,	store_word(  R_AT, r_prim_cursor, O_(PolyTag,code))       /* prim->tag = packed(prim_length, old_addr) */ \
 ,	shift_lleft( R_AT, r_prim_cursor, S_(PolyTag_len_bits))   /* AT = (prim_length << 24) | old_addr */ \
 ,	shift_lright(R_AT, R_AT,          S_(PolyTag_len_bits)) \
 ,	store_word(  R_AT, R_T1,          O_(PolyTag,code))       /* OrderingTable[OTZ] = PrimCursor */
 WORD_COUNT(mac_insert_ot_tag_f3, 11)
 #define mac_insert_ot_tag_g4(r_ot_base, r_prim_cursor) \
 	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 */ \
 ,	load_upper_i(R_V0, (S_(Poly_G4)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits) /* V0 = (9 - 1) << 24 = 8 << 24 */ \
 ,	mask_upper(  R_AT, R_AT,          S_(PolyTag_len_bits))    /* Strip upper 8 bits (length from prev cell) → keep only low 24 */ \
 ,	or_u(        R_AT, R_AT, R_V0)                             /* Merge length */ \
 ,	store_word(  R_AT, r_prim_cursor, O_(PolyTag,code))        /* prim->tag = packed(prim_length, old_addr) */ \
 ,	shift_lleft( R_AT, r_prim_cursor, S_(PolyTag_len_bits))    /* AT = (prim_length << 24) | old_addr */ \
 ,	shift_lright(R_AT, R_AT,          S_(PolyTag_len_bits)) \
 ,	store_word(  R_AT, R_T1,          O_(PolyTag,code))        /* OrderingTable[OTZ] = PrimCursor */
 WORD_COUNT(mac_insert_ot_tag_g4, 11)
@@ -0,0 +1,53 @@
 // Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT
 // Directory: C:\projects\Pikuma\ps1\code\duffle\
 //   source: C:\projects\Pikuma\ps1\code\duffle\word_count.metadata.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\dsl.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\memory.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\math.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\gcc_asm.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\gp.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\gte.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\dsl.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\lottes_tape.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.c
 //   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
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.atom.c
 #pragma once
 #pragma region duffle
 // --- atom: pad_bios_snapshot (78 words) ---
 #define _atom_offset_snap_root_skip_disconnected      8
 #define _atom_offset_disconnected_snap_end            61
 #define _atom_offset_case_2_id_dispatch               8
 #define _atom_offset_pending_snap_end                 51
 #define _atom_offset_id_dispatch_try_analog_stick     11
 #define _atom_offset_id_dispatch_snap_end             38
 #define _atom_offset_try_analog_stick_try_analog_pad  12
 #define _atom_offset_analog_stick_snap_end            24
 #define _atom_offset_try_analog_pad_try_unsupported   11
 #define _atom_offset_analog_pad_snap_end              10
 enum {
    atom_offset_snap_root_skip_disconnected = _atom_offset_snap_root_skip_disconnected,
    atom_offset_disconnected_snap_end = _atom_offset_disconnected_snap_end,
    atom_offset_case_2_id_dispatch = _atom_offset_case_2_id_dispatch,
    atom_offset_pending_snap_end = _atom_offset_pending_snap_end,
    atom_offset_id_dispatch_try_analog_stick = _atom_offset_id_dispatch_try_analog_stick,
    atom_offset_id_dispatch_snap_end = _atom_offset_id_dispatch_snap_end,
    atom_offset_try_analog_stick_try_analog_pad = _atom_offset_try_analog_stick_try_analog_pad,
    atom_offset_analog_stick_snap_end = _atom_offset_analog_stick_snap_end,
    atom_offset_try_analog_pad_try_unsupported = _atom_offset_try_analog_pad_try_unsupported,
    atom_offset_analog_pad_snap_end = _atom_offset_analog_pad_snap_end,
 };
 #pragma endregion duffle
@@ -0,0 +1,82 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	include "dsl.h"
 #	include "gp.h"
 #	include "lottes_tape.h"
 #endif
 ATOM_FILE_DEBUGGER_LINE_MARKER(gp_atom_c);
 #pragma region MACs (Mips Atom Components)
 FI_ Slice_MipsCode ac_gcmd_push(U4 cmd, U4 reg_transfer, U4 reg_base, U2 port)
 MipsAtomComp_Proc_(ac_gcmd_push, {
 	load_upper_i(reg_transfer, cmd >> 16),
 	or_i_self(   reg_transfer, cmd & 0xFFFF),
 	store_word(  reg_transfer, reg_base, port),
 })
 FI_ Slice_MipsCode ac_store_rgb8(U1 rr, U1 rg, U1 rb, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_rgb8, {
 	store_byte(rr, base, offset + O_(RGB8,r)),
 	store_byte(rg, base, offset + O_(RGB8,g)),
 	store_byte(rb, base, offset + O_(RGB8,b)),	
 })
 /* Words: 3; Emits one (cmd|color) word to R_PrimCursor at the given
 * byte offset. Internal helper used by the *_format_*_color macros. */
 FI_ Slice_MipsCode ac_pack_color_word(U4 r_base, U4 off, U4 cmd, U1 r, U1 g, U1 b)
 atom_dbg_skip MipsAtomComp_Proc_(ac_pack_color_word, {
 	load_upper_i(R_AT, (cmd) << 8  | (b)),
 	or_i_self(   R_AT, ((g)  << 8) | (r)),
 	store_word(  R_AT, r_base, (off)),
 })
 /* Words: 3; Emits the F3 command+color word (cmd byte | BLUE | GREEN | RED)
 * Args: _r, _g, _b are 8-bit RGB byte values (not raw 16-bit fields). */
 FI_ Slice_MipsCode ac_format_f3_color(U4 r_base, U1 r, U1 g, U1 b)
 atom_dbg_skip MipsAtomComp_Proc_(ac_format_f3_color, { mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b) })
 /* Words: 12; Emits the four (code|color) words of a Poly_G4.
 * Args: rN,gN,bN are 8-bit RGB byte values for each of the 4 vertices. */
 FI_ Slice_MipsCode ac_format_g4_color(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, {
 	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),
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c3), 0,               r3,g3,b3),
 })
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
 * Hardcoded for Poly_F3 (5 words). For Poly_G4, use ac_insert_ot_tag_g4. */
 I_ Slice_MipsCode ac_insert_ot_tag_f3(U4 r_ot_base, U4 r_prim_cursor) MipsAtomComp_Proc_(ac_insert_ot_tag_f3, {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, r_ot_base),                             // T1 = & OrderingTable[OTZ]
 	load_word(   R_AT, R_T1,          O_(PolyTag,code)),       // AT = old_ot_head
 	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits), // V0 = (5 - 1) << 24 = 4 << 24
 	mask_upper(  R_AT, R_AT,          S_(PolyTag_len_bits)),   // Strip upper 8 bits (length from prev cell) → keep only low 24
 	or_u(        R_AT, R_AT, R_V0),                            // Merge length
 	store_word(  R_AT, r_prim_cursor, O_(PolyTag,code)),       // prim->tag = packed(prim_length, old_addr)
 	shift_lleft( R_AT, r_prim_cursor, S_(PolyTag_len_bits)),   // AT = (prim_length << 24) | old_addr
 	shift_lright(R_AT, R_AT,          S_(PolyTag_len_bits)),
 	store_word(  R_AT, R_T1,          O_(PolyTag,code)),       // OrderingTable[OTZ] = PrimCursor
 })
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
 * Hardcoded for Poly_G4 (9 words). For Poly_F3, use ac_insert_ot_tag_f3. */
 I_ Slice_MipsCode ac_insert_ot_tag_g4(U4 r_ot_base, U4 r_prim_cursor) MipsAtomComp_Proc_(ac_insert_ot_tag_g4, {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                         // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, r_ot_base),                              // T1 = & OrderingTable[OTZ]
 	load_word(   R_AT, R_T1,          O_(PolyTag,code)),        // AT = old_ot_head
 	load_upper_i(R_V0, (S_(Poly_G4)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits), // V0 = (9 - 1) << 24 = 8 << 24
 	mask_upper(  R_AT, R_AT,          S_(PolyTag_len_bits)),    // Strip upper 8 bits (length from prev cell) → keep only low 24
 	or_u(        R_AT, R_AT, R_V0),                             // Merge length
 	store_word(  R_AT, r_prim_cursor, O_(PolyTag,code)),        // prim->tag = packed(prim_length, old_addr)
 	shift_lleft( R_AT, r_prim_cursor, S_(PolyTag_len_bits)),    // AT = (prim_length << 24) | old_addr
 	shift_lright(R_AT, R_AT,          S_(PolyTag_len_bits)),
 	store_word(  R_AT, R_T1,          O_(PolyTag,code)),        // OrderingTable[OTZ] = PrimCursor
 })
 #pragma endregion MACs (Mips Atom Components)
@@ -1,7 +1,6 @@
 /* ============================================================================
 *  duffle DSL Suffix Conventions
 *  ============================================================================
 *
 *  Every mnemonic in this header follows the same suffix grammar:
 *
 *  Primitive commands: gp0_cmd_poly_f3 = 0x20    (byte opcode)
@@ -26,8 +25,7 @@
 *    0. Opcode IDs             gp0_cmd_poly_f3 = 0x20
 *
 *  Vendor mnemonics (gte_mtc2, gte_mfc2, etc.) are NOT in this header.
- *  They live in the opt-in `gp_vendor_sym.h` for users who prefer the
+ *  They live in the opt-in `gp_vendor_sym.h` for users who prefer the PSYQ-style names.
 *  PSYQ-style names.
 * ============================================================================ */
 #ifdef INTELLISENSE_DIRECTIVES
@@ -41,29 +39,28 @@
 /* ============================================================================
 *  Hardware MMIO Addresses
 *  ============================================================================
- *
+ *  PSX GPU has two 32-bit ports in the I/O register region at KSEG2 0x1F800000+.
- *  PSX GPU has two 32-bit ports in the I/O register region at KSEG2
+ *  GP0 (offset 0x10) is the data port (commands + params).
 *  0x1F800000+. GP0 (offset 0x10) is the data port (commands + params).
 *  GP1 (offset 0x14) is the control port (status, ctrl writes).
 * ============================================================================ */
 /* IO base address (KSEG2 0x1F800000+ for the I/O register region).
- * The 16-bit upper half `IO_BASE_ADDR_HI16` is the form used by
+ * The 16-bit upper half `IO_BASE_ADDR_HI16` is the form used by tape-side macros that pin a register
- * tape-side macros that pin a register to hold the IO base and access
+ * to hold the IO base and access ports via offsets:
- * ports via offsets — `lui $reg, 0x1F80` (1 word) then `sw $data, GPIO_PORT*_OFFSET($reg)` (1 word). 
+ *   `lui $reg, 0x1F80` (1 word) then `sw $data, GPIO_PORT*_OFFSET($reg)` (1 word). 
 * Mirrors the `IO_BASE_ADDR equ 0x1F80` + `gpio_port0 equ 0x1810` pattern from graphics_hello/gp.s. */
 enum {
-    IO_BASE_ADDR      = 0x1F800000,  /* full 32-bit I/O region base */
+	IO_BASE_ADDR      = 0x1F800000,  /* full 32-bit I/O region base */
-    IO_BASE_ADDR_HI16 = 0x1F80,      /* fits in a single `lui $reg, 0x1F80` */
+	IO_BASE_ADDR_HI16 = 0x1F80,      /* fits in a single `lui $reg, 0x1F80` */
-    /* Offsets from IO_BASE_ADDR to each port. Used by tape-side macros
+	/* Offsets from IO_BASE_ADDR to each port. Used by tape-side macros
-     * that pin a register to IO_BASE_ADDR and access ports via offsets:
+		* that pin a register to IO_BASE_ADDR and access ports via offsets:
-     *   sw $data, GPIO_PORT0_OFFSET($io_base)   ; write GP0
+		*   sw $data, GPIO_PORT0_OFFSET($io_base)   ; write GP0
-     *   sw $data, GPIO_PORT1_OFFSET($io_base)   ; write GP1 */
+		*   sw $data, GPIO_PORT1_OFFSET($io_base)   ; write GP1 */
-    GPIO_PORT0_OFFSET = 0x1810,
+	GPIO_PORT0_OFFSET = 0x1810,
-    GPIO_PORT1_OFFSET = 0x1814,
+	GPIO_PORT1_OFFSET = 0x1814,
-    HW_GP0_ADDR = (IO_BASE_ADDR_HI16 << 16) | GPIO_PORT0_OFFSET,
+	HW_GP0_ADDR = (IO_BASE_ADDR_HI16 << 16) | GPIO_PORT0_OFFSET,
-    HW_GP1_ADDR = (IO_BASE_ADDR_HI16 << 16) | GPIO_PORT1_OFFSET,
+	HW_GP1_ADDR = (IO_BASE_ADDR_HI16 << 16) | GPIO_PORT1_OFFSET,
 };
 #define HW_GP0 C_(U4 V_*, HW_GP0_ADDR)
@@ -75,77 +72,71 @@ enum {
 /* ============================================================================
 *  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.
- *  The layer-1 bitfield-layout constants live in the same enum block
+ *  NO macro body past this point uses a raw shift or raw mask.
 *  so the encoder can reference them by name. 
 *  NO macro body past this point uses a raw shift or raw mask. 
 *  Every shift/width/mask is named here, named once. 
 *  Mirrors the OPCODE_SHIFT / RS_SHIFT / REG_MASK convention from mips.h.
 * ============================================================================ */
 enum {
-    gp0_cmd_Nop             = 0x00,
+	gp0_cmd_Nop             = 0x00,
-    /* Cache management */
+	/* Cache management */
-    gp0_cmd_ClearCache      = 0x01,
+	gp0_cmd_ClearCache      = 0x01,
-    gp0_cmd_FillVram        = 0x02,
+	gp0_cmd_FillVram        = 0x02,
-    gp0_cmd_CopyVram        = 0x80,
+	gp0_cmd_CopyVram        = 0x80,
-    gp0_cmd_CopyVramChained = 0x81,
+	gp0_cmd_CopyVramChained = 0x81,
-    gp0_cmd_ReadVram        = 0xC0,
+	gp0_cmd_ReadVram        = 0xC0,
-    /* Polygons */
+	/* Polygons */
-    gp0_cmd_poly_f3         = 0x20,  /* Flat Triangle           */
+	gp0_cmd_poly_f3         = 0x20,  /* Flat Triangle           */
-    gp0_cmd_poly_ft3        = 0x24,  /* Flat Textured Triangle  */
+	gp0_cmd_poly_ft3        = 0x24,  /* Flat Textured Triangle  */
-    gp0_cmd_poly_g3         = 0x30,  /* Gouraud Triangle        */
+	gp0_cmd_poly_g3         = 0x30,  /* Gouraud Triangle        */
-    gp0_cmd_poly_gt3        = 0x34,  /* Gouraud Textured Tri    */
+	gp0_cmd_poly_gt3        = 0x34,  /* Gouraud Textured Tri    */
-    gp0_cmd_poly_f4         = 0x28,  /* Flat Quad               */
+	gp0_cmd_poly_f4         = 0x28,  /* Flat Quad               */
-    gp0_cmd_poly_ft4        = 0x2C,  /* Flat Textured Quad      */
+	gp0_cmd_poly_ft4        = 0x2C,  /* Flat Textured Quad      */
-    gp0_cmd_poly_g4         = 0x38,  /* Gouraud Quad            */
+	gp0_cmd_poly_g4         = 0x38,  /* Gouraud Quad            */
-    gp0_cmd_poly_gt4        = 0x3C,  /* Gouraud Textured Quad   */
+	gp0_cmd_poly_gt4        = 0x3C,  /* Gouraud Textured Quad   */
-    /* Lines */
+	/* Lines */
-    gp0_cmd_line_f2         = 0x40,
+	gp0_cmd_line_f2         = 0x40,
-    gp0_cmd_line_g2         = 0x50,
+	gp0_cmd_line_g2         = 0x50,
-    /* Sprites + Tiles + Rects */
+	/* Sprites + Tiles + Rects */
-    gp0_cmd_sprt_1          = 0x64,
+	gp0_cmd_sprt_1          = 0x64,
-    gp0_cmd_sprt_8          = 0x74,
+	gp0_cmd_sprt_8          = 0x74,
-    gp0_cmd_sprt_16         = 0x7C,
+	gp0_cmd_sprt_16         = 0x7C,
-    gp0_cmd_tile_1          = 0x60,
+	gp0_cmd_tile_1          = 0x60,
-    gp0_cmd_tile_8          = 0x68,
+	gp0_cmd_tile_8          = 0x68,
-    gp0_cmd_tile_16         = 0x70,
+	gp0_cmd_tile_16         = 0x70,
-    /* State setters (not drawing primitives; set render context). */
+	/* State setters (not drawing primitives; set render context). */
-    gp0_cmd_DrawModeSetting      = 0xE1,  /* TPage / draw-mode (semi-trans, dither, etc.) */
+	gp0_cmd_DrawModeSetting      = 0xE1,  /* TPage / draw-mode (semi-trans, dither, etc.) */
-    gp0_cmd_SetTextureWindow     = 0xE2,
+	gp0_cmd_SetTextureWindow     = 0xE2,
-    gp0_cmd_SetDrawArea_TopLeft  = 0xE3,
+	gp0_cmd_SetDrawArea_TopLeft  = 0xE3,
-    gp0_cmd_SetDrawArea_BotRight = 0xE4,
+	gp0_cmd_SetDrawArea_BotRight = 0xE4,
-    gp0_cmd_SetDrawOffset        = 0xE5,
+	gp0_cmd_SetDrawOffset        = 0xE5,
-    gp0_cmd_SetMaskBit           = 0xE6,
+	gp0_cmd_SetMaskBit           = 0xE6,
-    /* bitfield shifts / widths / masks ----
+	/* bitfield shifts / widths / masks ----
-     * Generic GP0/GP1 command byte (upper 8 bits of every word sent to either port). */
+		* Generic GP0/GP1 command byte (upper 8 bits of every word sent to either port). */
-    gp0_cmd_shift = 24,
+	gp0_cmd_shift = 24,
-    gp0_cmd_width =  8,
+	gp0_cmd_width =  8,
-    gp0_cmd_mask  = 0xFF,
+	gp0_cmd_mask  = 0xFF,
-    /* Color word layout (lives in Poly_F3.color, Poly_G4.c0..c3, etc.):
+	/* Color word layout (lives in Poly_F3.color, Poly_G4.c0..c3, etc.):
-     *   bits 31..24 = command byte
+		*   bits 31..24 = command byte
-     *   bits 23..16 = BLUE
+		*   bits 23..16 = BLUE
-     *   bits 15..08 = GREEN
+		*   bits 15..08 = GREEN
-     *   bits 07..00 = RED     (PSX GPU is BGR, NOT RGB) */
+		*   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_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_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_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_red_shift   =  0, gp0_color_red_width   = 8, gp0_color_red_mask   = 0xFF,
 };
 /* ============================================================================
 *  Layer 1.5 (per-field encoders) + Layer 2 (composite) + Layer 3 (semantic GP0 word builders)
 *  ============================================================================
- *
+ *  Layer 1.5 encoders take one field's value, mask it to its own width, and shift it to its own position. 
 *  Layer 1.5 encoders take one field's value, mask it to its own width,
 *  and shift it to its own position. 
 *  Mirrors `enc_op` / `enc_rs` / `enc_rt` in mips.h and `enc_gte_sf` / `enc_gte_mx` in gte.h. 
 *  Layer-2 composite encoders OR the per-field encoders together; layer-3 semantic macros delegate to the composites.
 *  No raw shifts or magic numbers in any macro body below this point.
@@ -178,73 +169,73 @@ enum {
 #define gp0_word_poly_gt4(r,g,b) enc_color_word(gp0_cmd_poly_gt4, (r),(g),(b))
 /* Cache management — bare-cmd words (no color/range payload). */
-#define gp0_word_clear_cache() enc_gp0_cmd_word(gp0_cmd_ClearCache)
+#define gp0_word_clear_cache()       enc_gp0_cmd_word(gp0_cmd_ClearCache)
-#define gp0_word_fill_vram()   enc_gp0_cmd_word(gp0_cmd_FillVram)
+#define gp0_word_fill_vram()         enc_gp0_cmd_word(gp0_cmd_FillVram)
-#define gp0_word_copy_vram()   enc_gp0_cmd_word(gp0_cmd_CopyVram)
+#define gp0_word_copy_vram()         enc_gp0_cmd_word(gp0_cmd_CopyVram)
-#define gp0_word_read_vram()   enc_gp0_cmd_word(gp0_cmd_ReadVram)
+#define gp0_word_read_vram()         enc_gp0_cmd_word(gp0_cmd_ReadVram)
 /* NOP — bare-cmd word (no effect; used as DR_ENV padding). */
 #define gp0_word_nop()               enc_gp0_cmd_word(gp0_cmd_Nop)
 /* ============================================================================
 *  GP1 command byte constants + Layer 1 (display-mode + range + draw-area bitfield shifts)
 *  ============================================================================
- *
+ *  GP1 status bits are read from HW_GP1;
- *  GP1 status bits are read from HW_GP1; ctrl writes use GP1 commands
+ *  ctrl writes use GP1 commands packed into 32-bit words 
- *  packed into 32-bit words (cmd byte in the upper 8 bits via
+ *  (cmd byte in the upper 8 bits via `enc_gp0_cmd(cmd)`).
 *  `enc_gp0_cmd(cmd)` — never a raw shift).
 * ============================================================================ */
 enum {
-    gp1_cmd_Reset                  = 0x00,
+	gp1_cmd_Reset                  = 0x00,
-    gp1_cmd_ResetCmdBuffer         = 0x01,
+	gp1_cmd_ResetCmdBuffer         = 0x01,
-    gp1_cmd_AcknowledgeIRQ         = 0x02,
+	gp1_cmd_AcknowledgeIRQ         = 0x02,
-    gp1_cmd_DisplayEnable          = 0x03,
+	gp1_cmd_DisplayEnable          = 0x03,
-    gp1_cmd_DMADirection           = 0x04,
+	gp1_cmd_DMADirection           = 0x04,
-    gp1_cmd_StartDisplayArea       = 0x05,
+	gp1_cmd_StartDisplayArea       = 0x05,
-    gp1_cmd_HorizontalDisplayRange = 0x06,
+	gp1_cmd_HorizontalDisplayRange = 0x06,
-    gp1_cmd_VerticalDisplayRange   = 0x07,
+	gp1_cmd_VerticalDisplayRange   = 0x07,
-    gp1_cmd_DisplayMode            = 0x08,
+	gp1_cmd_DisplayMode            = 0x08,
-    /* Note: GP1 only has commands 0x00..0x08. 
+	/* Note: GP1 only has commands 0x00..0x08. 
-		 * The state-setter commands (SetTextureWindow, * SetDrawArea*, 
+		* The state-setter commands (SetTextureWindow, * SetDrawArea*, SetDrawOffset, SetMaskBit) 
-		 * SetDrawOffset, SetMaskBit) live in the GP0 enum as * 0xE1..0xE6. 
+		* live in the GP0 enum as * 0xE1..0xE6.
-		 * DrawArea word builders are below as GP0s * macros 
+		* DrawArea word builders are below as GP0s * macros (since they emit GP0 commands). */
 		 * (since they emit GP0 commands). */
-    /* ---- Display-mode payload flags (per PSX-SPX §"GP1 Display Mode").
+	/* ---- Display-mode payload flags (per PSX-SPX §"GP1 Display Mode").
-     * Bit positions match the encoder shifts below; values are the
+		* Bit positions match the encoder shifts below; values are the *payload* bits only (cmd byte is OR'd in by enc_gp1_disp_mode_word). */
-     * *payload* bits only (the cmd byte is OR'd in by enc_gp1_disp_mode_word). */
+	gp1_disp_HRes_256   = 0x0,
-    gp1_disp_HRes_256   = 0x0,
+	gp1_disp_HRes_320   = 0x1,
-    gp1_disp_HRes_320   = 0x1,
+	gp1_disp_HRes_512   = 0x2,
-    gp1_disp_HRes_512   = 0x2,
+	gp1_disp_HRes_640   = 0x3,
-    gp1_disp_HRes_640   = 0x3,
+	gp1_disp_VRes_240   = 0x0,
-    gp1_disp_VRes_240   = 0x0,
+	gp1_disp_VRes_480   = 0x1,
-    gp1_disp_VRes_480   = 0x1,
+	gp1_disp_Color15    = 0x0,
-    gp1_disp_Color15    = 0x0,
+	gp1_disp_Color24    = 0x1,
-    gp1_disp_Color24    = 0x1,
+	gp1_disp_VInterlace = 0x1,
    gp1_disp_VInterlace = 0x1,
-    /* ---- Layer 1: GP1 display-mode + range + draw-area shifts/masks ---- */
+	/* ---- 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_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_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_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,
+	gp1_disp_interlace_shift =  5, gp1_disp_interlace_width = 1, gp1_disp_interlace_mask = 0x1,
-    /* GP1 horizontal display range: bits 0..11 = X2, bits 12..23 = X1 */
+	/* 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_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_x2_shift =  0, gp1_hrange_x2_width = 12, gp1_hrange_x2_mask = 0xFFF,
-    /* GP1 vertical display range: bits 0..9 = Y2, bits 10..19 = Y1 */
+	/* 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_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_y2_shift =  0, gp1_vrange_y2_width = 10, gp1_vrange_y2_mask = 0x3FF,
-    /* GP1 draw area (top-left or bottom-right): bits 0..9 = X, bits 10..19 = Y
+	/* 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) */
+		* (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_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,
+	gp1_draw_y_shift = 10, gp1_draw_y_width = 10, gp1_draw_y_mask = 0x3FF,
 };
 /* ---- 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_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_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_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_interlace(i) (((i) & gp1_disp_interlace_mask) << gp1_disp_interlace_shift)
 #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)
@@ -259,12 +250,16 @@ enum {
 #define enc_gp1_vrange_word(y1, y2)        (enc_gp0_cmd(gp1_cmd_VerticalDisplayRange)   | enc_gp1_vrange_y1(y1) | enc_gp1_vrange_y2(y2))
 /* ---- Layer 2: GP0 state-setter composite encoders ----
- * GP0(0xE3) SetDrawArea top-left and GP0(0xE4) SetDrawArea bottom-right
+ * GP0(0xE3) SetDrawArea top-left and GP0(0xE4) SetDrawArea bottom-right both use the same X/Y 10-bit signed payload as GP1 DisplayRange. */
 * both use the same X/Y 10-bit signed payload as GP1 DisplayRange. */
 #define enc_gp0_draw_area_tl_word(x, y)    (enc_gp0_cmd(gp0_cmd_SetDrawArea_TopLeft)  | enc_gp1_draw_x(x) | enc_gp1_draw_y(y))
 #define enc_gp0_draw_area_br_word(x, y)    (enc_gp0_cmd(gp0_cmd_SetDrawArea_BotRight) | enc_gp1_draw_x(x) | enc_gp1_draw_y(y))
 /* ---- Layer 3: GP1 semantic word builders ---- */
 #define gp1_word_Reset()             enc_gp0_cmd_word(gp1_cmd_Reset)
 #define gp1_word_ResetCmdBuffer()    enc_gp0_cmd_word(gp1_cmd_ResetCmdBuffer)
 #define gp1_word_AcknowledgeIRQ()    enc_gp0_cmd_word(gp1_cmd_AcknowledgeIRQ)
 #define gp1_word_StartDisplayArea()  enc_gp0_cmd_word(gp1_cmd_StartDisplayArea)
 #define gp1_word_display_enable(on)                         (enc_gp0_cmd(gp1_cmd_DisplayEnable) | ((on) & 1))
 #define gp1_word_display_disable()                          gp1_word_display_enable(0)
 #define gp1_word_display_mode_320x240_15bit_ntsc            enc_gp1_disp_mode_word(gp1_disp_HRes_320, gp1_disp_VRes_240, gp1_disp_Color15, 0)
@@ -282,7 +277,6 @@ enum {
 /* ============================================================================
 *  Pre-baked GPU state words
 *  ============================================================================
 *
 *  Common command words for boot-time GPU init and standard display configurations.
 * ============================================================================ */
@@ -290,31 +284,36 @@ enum {
 #define gp1_word_display_enabled   enc_gp0_cmd_word(gp1_cmd_DisplayEnable)
 #define gp1_word_display_disabled (enc_gp0_cmd_word(gp1_cmd_DisplayEnable) | 1)
 #define gp1_word_DisplayOn()       gp1_word_display_enable(0)
 #define gp1_word_DisplayOff()      gp1_word_display_enable(1)
 /* ---- DMA direction (2-bit payload on DMADirection cmd 0x04) ---- */
 enum {
-    gp1_dma_dir_Off            = 0,
+	gp1_dma_dir_Off            = 0,
-    gp1_dma_dir_FIFO           = 1,
+	gp1_dma_dir_FIFO           = 1,
-    gp1_dma_dir_CPU_to_GPU     = 2,
+	gp1_dma_dir_CPU_to_GPU     = 2,
-    gp1_dma_dir_GPUREAD_to_CPU = 3,
+	gp1_dma_dir_GPUREAD_to_CPU = 3,
 };
 #define gp1_word_dma_direction(dir) (enc_gp0_cmd(gp1_cmd_DMADirection) | ((dir) & 0x3))
 #define gp1_word_dma_to_gpu()       gp1_word_dma_direction(gp1_dma_dir_CPU_to_GPU)
 #define gp1_word_dma_read_cpu()     gp1_word_dma_direction(gp1_dma_dir_GPUREAD_to_CPU)
 /* ---- Standard display ranges (NTSC + PAL pre-baked) ---- */
 /* Horizontal range values are in video clock units (8 units/pixel); vertical range values are scanline numbers. */
 enum {
-    /* NTSC horizontal range: X1=608, X2=3168 */
+	/* NTSC horizontal range: X1=608, X2=3168 */
-    gp1_hrange_NTSC_x1 = 0x260,
+	gp1_hrange_NTSC_x1 = 0x260,
-    gp1_hrange_NTSC_x2 = 0xC60,
+	gp1_hrange_NTSC_x2 = 0xC60,
-    /* PAL horizontal range (same as NTSC for most CRTs) */
+	/* PAL horizontal range (same as NTSC for most CRTs) */
-    gp1_hrange_PAL_x1  = 0x260,
+	gp1_hrange_PAL_x1  = 0x260,
-    gp1_hrange_PAL_x2  = 0xC60,
+	gp1_hrange_PAL_x2  = 0xC60,
-    /* NTSC vertical range: Y1=24, Y2=264 */
+	/* NTSC vertical range: Y1=24, Y2=264 */
-    gp1_vrange_NTSC_y1 = 24,
+	gp1_vrange_NTSC_y1 = 24,
-    gp1_vrange_NTSC_y2 = 264,
+	gp1_vrange_NTSC_y2 = 264,
-    /* PAL vertical range: Y1=24, Y2=504 */
+	/* PAL vertical range: Y1=24, Y2=504 */
-    gp1_vrange_PAL_y1  = 24,
+	gp1_vrange_PAL_y1  = 24,
-    gp1_vrange_PAL_y2  = 504,
+	gp1_vrange_PAL_y2  = 504,
 };
 #define gp1_word_horizontal_range_ntsc enc_gp1_hrange_word(gp1_hrange_NTSC_x1, gp1_hrange_NTSC_x2)
@@ -325,14 +324,49 @@ enum {
 /* ---- Draw-mode setting (TPage / draw-area allowance) ---- */
 /* The "drawing enabled" word is the standard post-init state. */
 enum {
-    gp0_DrawMode_DrawToDispBit = 10,
+	/* Per psx-spx, the standard 0xE1 layout has dfe at bit 10. But libpsyx's PutDrawEnv
 	 * uses bit 19 (in the "unused" 14-23 range) for dfe in the DR_ENV code[0] — and the
 	 * PSX hardware honors bit 19 in the DR_ENV context (not bit 10). So we need a
 	 * separate bit definition for the DR_ENV-specific DrawMode. */
 	gp0_DrawMode_DrawToDispBit         = 10,   // standard psx-spx bit 10 (dfe)
 	gp0_DrawMode_DR_ENV_DrawToDispBit  = 19,   // libpsyx DR_ENV code[0] (dfe in DR_ENV context)
 	gp0_DrawMode_DR_ENV_isbgBit        = 19,   // libpsyx uses bit 19 for isbg too
 };
 #define gp0_word_draw_mode_drawing_allowed (enc_gp0_cmd(gp0_cmd_DrawModeSetting) | (1 << gp0_DrawMode_DrawToDispBit))
-/* ---- DrawArea pre-baked at origin (0,0) and full screen (320x240) ---- */
+/* DR_ENV-specific DrawMode variants (libpsyx SetDrawEnv layout).
 * The DR_ENV is a 16-word packet emitted at boot by gp_screen_init's ac_put_draw_env_demo
 * atom component. Within the DR_ENV, the 0xE1 command is reused in three different bit
 * configurations:
 *   code[0] = `gp0_word_draw_mode_drawing_allowed` (dfe=1; standard post-init state)
 *   code[6] = `gp0_word_dr_env_bg_color_cmd(isbg, r, g, b)` (initial-bg-color path)
 *   code[7] = `gp0_word_dr_env_draw_mode(isbg)` (isbg-flag path)
 * Bits 0-23 of the 0xE1 word are the payload; bits 24-31 are the cmd byte (0xE1). */
 #define gp0_word_dr_env_bg_color_cmd(isbg, r, g, b) (enc_gp0_cmd(gp0_cmd_DrawModeSetting) | (1 << gp0_DrawMode_DrawToDispBit) | ((isbg) ? gp0_dr_env_isbg_bit : 0) | enc_gp0_color_r(r) | enc_gp0_color_g(g) | enc_gp0_color_b(b))
 #define gp0_word_dr_env_draw_mode(isbg)             (enc_gp0_cmd(gp0_cmd_DrawModeSetting) | (1 << gp0_DrawMode_DrawToDispBit) | ((isbg) ? gp0_dr_env_isbg_bit : 0))
 /* State-setter bare-cmd words (no immediate payload; the GPU uses the current state machine already programmed). */
 #define gp0_word_set_texture_window() enc_gp0_cmd_word(gp0_cmd_SetTextureWindow)
 #define gp0_word_set_draw_offset()    enc_gp0_cmd_word(gp0_cmd_SetDrawOffset)
 #define gp0_word_set_mask_bit()       enc_gp0_cmd_word(gp0_cmd_SetMaskBit)
 /* DR_ENV code[5] Mask (0xE6 cmd + isbg bit). The isbg bit is set so the GPU knows the auto-clear path is active (paired with code[6] + code[7]). */
 #define gp0_word_dr_env_mask() (gp0_word_set_mask_bit() | gp0_dr_env_isbg_bit)
 /* DR_ENV pre-baked constants (libpsyx PutDrawEnv layout).
 * DR_ENV is a 16-word packet: tag = (length << 24) | addr, where length = 15 (15 code words follow) and addr = 0 (chain to nothing). */
 enum {
 	PolyTag_len_bits  =  8,
 	PolyTag_addr_bits = 24,
 	gp0_dr_env_tag      = (15 << 24) | 0x00FFFFFF,
 	gp0_dr_env_isbg_bit = (1 << gp0_DrawMode_DR_ENV_isbgBit),
 };
 /* ---- DrawArea at origin (0,0) and full screen (320x240) ---- */
 #define gp0_word_draw_area_top_left_origin      enc_gp0_draw_area_tl_word(0, 0)
-#define gp0_word_draw_area_bottom_right_320x240 enc_gp0_draw_area_br_word(320, 240)
+#define gp0_word_draw_area_bottom_right_320x240 enc_gp0_draw_area_br_word(319, 239)
-#define gp0_word_draw_area_bottom_right_640x480 enc_gp0_draw_area_br_word(640, 480)
+#define gp0_word_draw_area_bottom_right_640x480 enc_gp0_draw_area_br_word(639, 479)
 #pragma endregion GPU Ports & Commands
@@ -343,9 +377,9 @@ enum {
 *  Read from HW_GP1; the lower bits are DMA-block-size (variable-width).
 * ============================================================================ */
 enum {
-    gp1_Status_BitReady          = 31,
+	gp1_Status_BitReady          = 31,
-    gp1_Status_BitSendingDMA     = 25,
+	gp1_Status_BitSendingDMA     = 25,
-    gp1_Status_DMABlockSizeShift =  0,
+	gp1_Status_DMABlockSizeShift =  0,
 };
 #define gp1_status_is_ready()       ((HW_GP1[0] >> gp1_Status_BitReady)      & 1)
@@ -356,7 +390,6 @@ enum {
 /* ============================================================================
 *  Primitive structs (8 polygon variants + tag)
 *  ============================================================================
 *
 *  Each struct follows the GPU-documented memory layout for the corresponding primitive command. 
 *  The PolyTag is the OT-link header; the rest of the struct is the primitive's body.
 *
@@ -372,10 +405,10 @@ typedef Struct_(RGB8) { B1 r; B1 g; B1 b; };
 #define rgb8(r,g,b) ((RGB8){r,g,b})
 /* ---------- PolyTag (the OT-link header; 1 word) ---------- */
-enum {
+// enum {
-    PolyTag_len_bits  =  8,
+// 	PolyTag_len_bits  =  8,
-    PolyTag_addr_bits = 24,
+// 	PolyTag_addr_bits = 24,
-};
+// };
 typedef Struct_(PolyTag) {
 	union {
 		U4 code;
@@ -390,104 +423,104 @@ typedef Struct_(PolyTag) {
 * 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
+/* `set_code` is no longer in the new PolyTag design — the code byte lives in the primitive body
- *  in the primitive body (e.g. `((Poly_F3*)(p))->code`), not in the tag.
+ * (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, 
+ *  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)
 /* ---------- Poly_F3 (Flat Triangle; 5 words) ---------- */
 typedef Struct_(Poly_F3) {
-    U4   tag;
+	U4   tag;
-    RGB8 color;
+	RGB8 color;
-    B1   code;
+	B1   code;
-    union {
+	union {
-        struct { V2_S2 p0; V2_S2 p1; V2_S2 p2; };
+		struct { V2_S2 p0; V2_S2 p1; V2_S2 p2; };
-        A3_V2_S2 points;
+		A3_V2_S2 points;
-    };
+	};
 };
 /* ---------- Poly_F4 (Flat Quad; 6 words) ---------- */
 typedef Struct_(Poly_F4) {
-    U4   tag;
+	U4   tag;
-    RGB8 color;
+	RGB8 color;
-    B1   code;
+	B1   code;
-    union {
+	union {
-        struct { V2_S2 p0; V2_S2 p1; V2_S2 p2; V2_S2 p3; };
+		struct { V2_S2 p0; V2_S2 p1; V2_S2 p2; V2_S2 p3; };
-        A4_V2_S2 points;
+		A4_V2_S2 points;
-    };
+	};
 };
 /* ---------- Poly_G3 (Gouraud Triangle; 7 words) ---------- */
 typedef Struct_(Poly_G3) {
-    U4    tag; RGB8 c0; B1 code;
+	U4    tag; RGB8 c0; B1 code;
-    V2_S2 p0;  RGB8 c1; B1 pad1;
+	V2_S2 p0;  RGB8 c1; B1 pad1;
-    V2_S2 p1;  RGB8 c2; B1 pad2;
+	V2_S2 p1;  RGB8 c2; B1 pad2;
-    V2_S2 p2;
+	V2_S2 p2;
 };
 /* ---------- Poly_G4 (Gouraud Quad; 9 words) ---------- */
 typedef Struct_(Poly_G4) {
-    U4    tag; RGB8 c0; B1 code;
+	U4    tag; RGB8 c0; B1 code;
-    V2_S2 p0;  RGB8 c1; B1 pad1;
+	V2_S2 p0;  RGB8 c1; B1 pad1;
-    V2_S2 p1;  RGB8 c2; B1 pad2;
+	V2_S2 p1;  RGB8 c2; B1 pad2;
-    V2_S2 p2;  RGB8 c3; B1 pad3;
+	V2_S2 p2;  RGB8 c3; B1 pad3;
-    V2_S2 p3;
+	V2_S2 p3;
 };
 /* ---------- Poly_FT3 (Flat Textured Triangle; placeholder layout) ---------- */
 /* TODO(Ed): verify the textured-variant layout against PSX-SPX when needed. */
 typedef Struct_(Poly_FT3) {
-    U4   tag;
+	U4   tag;
-    RGB8 color;
+	RGB8 color;
-    B1   code;
+	B1   code;
-    U4   tpage;
+	U4   tpage;
-    U4   clut;
+	U4   clut;
-    V2_S2 p0; U1 u0; U1 v0;
+	V2_S2 p0; U1 u0; U1 v0;
-    V2_S2 p1; U1 u1; U1 v1;
+	V2_S2 p1; U1 u1; U1 v1;
-    V2_S2 p2; U1 u2; U1 v2;
+	V2_S2 p2; U1 u2; U1 v2;
 };
 /* ---------- Poly_FT4 (Flat Textured Quad) ---------- */
 typedef Struct_(Poly_FT4) {
-    U4   tag;
+	U4   tag;
-    RGB8 color;
+	RGB8 color;
-    B1   code;
+	B1   code;
-    U4   tpage;
+	U4   tpage;
-    U4   clut;
+	U4   clut;
-    V2_S2 p0; U1 u0; U1 v0;
+	V2_S2 p0; U1 u0; U1 v0;
-    V2_S2 p1; U1 u1; U1 v1;
+	V2_S2 p1; U1 u1; U1 v1;
-    V2_S2 p2; U1 u2; U1 v2;
+	V2_S2 p2; U1 u2; U1 v2;
-    V2_S2 p3; U1 u3; U1 v3;
+	V2_S2 p3; U1 u3; U1 v3;
 };
 /* ---------- Poly_GT3 (Gouraud Textured Triangle) ---------- */
 typedef Struct_(Poly_GT3) {
-    U4    tag; RGB8 c0; B1 code;
+	U4    tag; RGB8 c0; B1 code;
-    V2_S2 p0;  RGB8 c1; B1 pad1;
+	V2_S2 p0;  RGB8 c1; B1 pad1;
-    V2_S2 p1;  RGB8 c2; B1 pad2;
+	V2_S2 p1;  RGB8 c2; B1 pad2;
-    V2_S2 p2;
+	V2_S2 p2;
-    U4    tpage;
+	U4    tpage;
-    U4    clut;
+	U4    clut;
-    V2_S2 tp0; U1 u0; U1 v0;
+	V2_S2 tp0; U1 u0; U1 v0;
-    V2_S2 tp1; U1 u1; U1 v1;
+	V2_S2 tp1; U1 u1; U1 v1;
-    V2_S2 tp2; U1 u2; U1 v2;
+	V2_S2 tp2; U1 u2; U1 v2;
 };
 /* ---------- Poly_GT4 (Gouraud Textured Quad) ---------- */
 typedef Struct_(Poly_GT4) {
-    U4    tag; RGB8 c0; B1 code;
+	U4    tag; RGB8 c0; B1 code;
-    V2_S2 p0;  RGB8 c1; B1 pad1;
+	V2_S2 p0;  RGB8 c1; B1 pad1;
-    V2_S2 p1;  RGB8 c2; B1 pad2;
+	V2_S2 p1;  RGB8 c2; B1 pad2;
-    V2_S2 p2;  RGB8 c3; B1 pad3;
+	V2_S2 p2;  RGB8 c3; B1 pad3;
-    V2_S2 p3;
+	V2_S2 p3;
-    U4    tpage;
+	U4    tpage;
-    U4    clut;
+	U4    clut;
-    V2_S2 tp0; U1 u0; U1 v0;
+	V2_S2 tp0; U1 u0; U1 v0;
-    V2_S2 tp1; U1 u1; U1 v1;
+	V2_S2 tp1; U1 u1; U1 v1;
-    V2_S2 tp2; U1 u2; U1 v2;
+	V2_S2 tp2; U1 u2; U1 v2;
-    V2_S2 tp3; U1 u3; U1 v3;
+	V2_S2 tp3; U1 u3; U1 v3;
 };
 /* ---------- Primitive setters (C-level) ----------
@@ -511,7 +544,6 @@ typedef Struct_(Poly_GT4) {
 /* ============================================================================
 *  Texture Page (TPage) bit layout
 *  ============================================================================
 *
 *  The TPage data word sent via GP0(0x2X) has:
 *    bits  0..3   = texture page X    (4 bits, 64-px units, 0..16)
 *    bit   4      = texture page Y    (1 bit,  64-px units, 0/1)
@@ -523,26 +555,29 @@ typedef Struct_(Poly_GT4) {
 *    bits 12..31  = reserved (zero)
 * ============================================================================ */
 enum {
-    /* ---- Layer 1: TPage bitfield shifts / widths / masks ---- */
+	/* ---- Layer 1: TPage bitfield shifts / widths / masks ---- */
-    gp0_tpage_x_shift            =  0, gp0_tpage_x_width            =  4, gp0_tpage_x_mask            = 0xF,
+	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_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_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_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_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_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,
+	gp0_tpage_tex_disable_shift  = 11, gp0_tpage_tex_disable_width  =  1, gp0_tpage_tex_disable_mask  = 0x1,
-    /* TPage color-depth payload values (NOT bit positions — these go in
+	/* 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_shift). */
-    gp0_tpage_color_4bpp  = 0x0,
+	gp0_tpage_color_4bpp  = 0x0,
-    gp0_tpage_color_8bpp  = 0x1,
+	gp0_tpage_color_8bpp  = 0x1,
-    gp0_tpage_color_16bpp = 0x2,
+	gp0_tpage_color_16bpp = 0x2,
-    /* TPage semi-transparency mode payload values (NOT bit positions). */
+	/* Default TPage value libpsyx's SetDefDrawEnv writes (matches the `li v1, 10; sh v1, 20(v0)` sequence at C11_only.elf:0x8001273C). */
-    gp0_tpage_semi_trans_none  = 0x0,
+	gp0_tpage_default    = 10,
-    gp0_tpage_semi_trans_alpha = 0x1,
+
-    gp0_tpage_semi_trans_add   = 0x2,
+	/* TPage semi-transparency mode payload values (NOT bit positions). */
-    gp0_tpage_semi_trans_sub   = 0x3,
+	gp0_tpage_semi_trans_none  = 0x0,
 	gp0_tpage_semi_trans_alpha = 0x1,
 	gp0_tpage_semi_trans_add   = 0x2,
 	gp0_tpage_semi_trans_sub   = 0x3,
 };
 /* ---- Layer 1.5: TPage per-field encoders. Mirrors enc_gte_sf/mx/v in gte.h. ---- */
@@ -556,26 +591,25 @@ enum {
 /* ---- 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) \
-    (enc_gp0_tpage_x(x)                       \
+	 (enc_gp0_tpage_x(x)                       \
-   | enc_gp0_tpage_y(y)                       \
+	| enc_gp0_tpage_y(y)                       \
-   | enc_gp0_tpage_semi_trans(semi_trans)     \
+	| enc_gp0_tpage_semi_trans(semi_trans)     \
-   | enc_gp0_tpage_color_depth(color_depth)   \
+	| enc_gp0_tpage_color_depth(color_depth)   \
-   | enc_gp0_tpage_dither(dither)             \
+	| enc_gp0_tpage_dither(dither)             \
-   | enc_gp0_tpage_draw_to_disp(draw_to_disp) \
+	| enc_gp0_tpage_draw_to_disp(draw_to_disp) \
-   | enc_gp0_tpage_tex_disable(tex_disable))
+	| enc_gp0_tpage_tex_disable(tex_disable))
 typedef Struct_(TexturePage) { U4 raw; };
 /* ---- Layer 3: TPage semantic word builder ---- */
 #define gp0_word_tpage(x, y, semi_trans, color_depth, dither, draw_to_disp, tex_disable) \
-    enc_gp0_tpage_word((x), (y), (semi_trans), (color_depth), (dither), (draw_to_disp), (tex_disable))
+	enc_gp0_tpage_word((x), (y), (semi_trans), (color_depth), (dither), (draw_to_disp), (tex_disable))
 #pragma endregion TPage
 #pragma region CLUT
 /* ============================================================================
 *  CLUT (Color Look-Up Table) semantics
 *  ============================================================================
 * 
 *  CLUT is loaded into VRAM by sending a GP0 command whose payload is:
 *    bits  0..5   = Y in 16-px units (palette row)
 *    bits  6..14  = X in 16-px units (palette column)
@@ -583,12 +617,12 @@ 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 ---- */
+	/* ---- Layer 1: CLUT bitfield shifts / widths / masks ---- */
-    gp0_clut_y_shift = 0, gp0_clut_y_width = 6, gp0_clut_y_mask = 0x3F,
+	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,
+	gp0_clut_x_shift = 6, gp0_clut_x_width = 9, gp0_clut_x_mask = 0x1FF,
-    /* CLUT-load cmd-byte variants — the upper byte of the GP0 word. */
+	/* CLUT-load cmd-byte variants — the upper byte of the GP0 word. */
-    gp0_clut_cmd_Load4bpp = 0x20,
+	gp0_clut_cmd_Load4bpp = 0x20,
-    gp0_clut_cmd_Load8bpp = 0x25,
+	gp0_clut_cmd_Load8bpp = 0x25,
 };
 /* ---- Layer 1.5: CLUT per-field encoders ---- */
@@ -608,7 +642,6 @@ enum {
 /* ============================================================================
 *  TIM file format constants and headers
 *  ============================================================================
 *
 *  TIM (Sony .TIM texture image) file structure:
 *    +0x00  U4 file_id (always 0x10 = TIM magic)
 *    +0x04  U4 version (always 0x00 for v1)
@@ -626,31 +659,30 @@ enum {
 *         +0x06 U2 px_height
 *         +0x08 ... pixel data
 *
- *  Future?: add `tim_load_to_vram(tim_ptr, vram_addr)` that
+ *  Future?: add `tim_load_to_vram(tim_ptr, vram_addr)` that emits the necessary GP0 commands.
- *  emits the necessary GP0 commands. Stoppped for now at the
+ *  Stoppped for now at the struct + enum level.
 *  struct + enum level.
 * ============================================================================ */
 enum {
-    tim_file_id_magic = 0x10,
+	tim_file_id_magic = 0x10,
-    tim_type_4bpp     = 0x00,
+	tim_type_4bpp     = 0x00,
-    tim_type_8bpp     = 0x01,
+	tim_type_8bpp     = 0x01,
-    tim_type_16bpp    = 0x02,
+	tim_type_16bpp    = 0x02,
-    tim_type_32bpp    = 0x03,
+	tim_type_32bpp    = 0x03,
-    tim_type_mixed    = 0x04,
+	tim_type_mixed    = 0x04,
-    tim_flag_has_clut = 0x08,
+	tim_flag_has_clut = 0x08,
 };
 typedef Struct_(TIM_Header) {
-    U4 file_id;       /* always 0x10 = "TIM" magic */
+	U4 file_id;       /* always 0x10 = "TIM" magic */
-    U4 version;       /* ignored; always 0 */
+	U4 version;       /* ignored; always 0 */
-    U4 flags;         /* bits 0..2 = type, bit 3 = has_clut */
+	U4 flags;         /* bits 0..2 = type, bit 3 = has_clut */
 };
 typedef Struct_(TIM_SectionHeader) {
-    U4 section_length;  /* bytes in this section including this header */
+	U4 section_length;  /* bytes in this section including this header */
-    U2 org_x;           /* origin in VRAM */
+	U2 org_x;           /* origin in VRAM */
-    U2 org_y;
+	U2 org_y;
-    U2 width;           /* width in pixels */
+	U2 width;           /* width in pixels */
-    U2 height;          /* height in pixels */
+	U2 height;          /* height in pixels */
 };
 #pragma endregion TIM File Format
@@ -659,35 +691,24 @@ typedef Struct_(TIM_SectionHeader) {
 *  Tape-side GPU operations (NOT in this header)
 *  ============================================================================
 *
- *  No `mac_gp0_send` or related macros live in gp.h. Rationale: the
+ *  No `mac_gp0_send` or related macros live in gp.h.
- *  Lottes tape model uses OT-DMA for primitive submission, so atom bodies
+ *  Rationale: the Lottes tape model uses OT-DMA for primitive submission, so atom bodies write to main RAM (the OT/primitive buffer)
- *  write to main RAM (the OT/primitive buffer) and to GTE state — never
+ *  and to GTE state — never directly to the GPU ports at 0x1F801810 / 0x1F801814.
- *  directly to the GPU ports at 0x1F801810 / 0x1F801814. See
+ *  See `mac_format_f3_color`, `mac_insert_ot_tag`, `mac_gte_store_f3` in lottes_tape.h for the patterns atom bodies actually use.
 *  `mac_format_f3_color`, `mac_insert_ot_tag`, `mac_gte_store_f3` in
 *  lottes_tape.h for the patterns atom bodies actually use.
 *
- *  If a feature need arises requires tape-side GPU port writes (e.g. DMA-kick to
+ *  If a feature need arises requires tape-side GPU port writes 
- *  start GPU consumption of the OT, VBlank sync via GP1 status poll),
+ *  (e.g. DMA-kick to start GPU consumption of the OT, VBlank sync via GP1 status poll),
- *  the right home is `lottes_tape.h` alongside the rest of the `mac_*`
+ *  the right home is `lottes_tape.h` alongside the rest of the `mac_*` family:
- *  family — the encoder infrastructure is already in place:
+ *    1. The caller pins a register to hold the IO base, e.g. register U4 r_io rgcc(R_T4) = IO_BASE_ADDR;
 *       The compiler emits `lui R_T4, IO_BASE_ADDR_HI16` outside the atom body (in the C prologue before tape_run).
 *    2. The atom body uses `store_word(R_data, R_T4, GPIO_PORT0_OFFSET)` to write to GP0, and `store_word(R_data, R_T4, GPIO_PORT1_OFFSET)`
 *       to write to GP1. Both are preprocessor-encodable because R_T4 is a fixed register and the GPIO_PORT*_OFFSET constants
 *       fit in the `sw`'s 16-bit signed offset field. No placeholder-pun, no asm constraints, no hidden register choice.
 *       Same pattern as the old graphics_hello/hello_gp_routines.s `reg_io_offset`/`gcmd_push` convention.
 *
- *    1. The caller pins a register to hold the IO base, e.g.
+ *  This mirrors the existing tape-side wave-context discipline: 
- *         register U4 r_io rgcc(R_T4) = IO_BASE_ADDR;
+ *  the caller binds the IO-base register via `rgcc()`, the macro assumes the binding is in effect,
- *       The compiler emits `lui R_T4, IO_BASE_ADDR_HI16` outside the
+ *  and the encoding falls out at preprocessor time. 
- *       atom body (in the C prologue before tape_run).
+ *  No additional GPU-domain macro layer required.
 *
 *    2. The atom body uses `store_word(R_data, R_T4, GPIO_PORT0_OFFSET)`
 *       to write to GP0, and `store_word(R_data, R_T4, GPIO_PORT1_OFFSET)`
 *       to write to GP1. Both are preprocessor-encodable because R_T4 is
 *       a fixed register and the GPIO_PORT*_OFFSET constants fit in the
 *       `sw`'s 16-bit signed offset field. No placeholder-pun, no asm
 *       constraints, no hidden register choice. Same pattern as the
 *       old graphics_hello/hello_gp_routines.s `reg_io_offset`/`gcmd_push`
 *       convention.
 *
 *  This mirrors the existing tape-side wave-context discipline: the
 *  caller binds the IO-base register via `rgcc()`, the macro assumes
 *  the binding is in effect, and the encoding falls out at preprocessor
 *  time. No additional GPU-domain macro layer required.
 * ============================================================================ */
 #pragma endregion Tape-Side Macros
@@ -2,10 +2,8 @@
 *  duffle DSL — GPU Vendor Mnemonics (opt-in)
 *  ============================================================================
 *
- *  Provides the PSYQ-style CamelCase aliases for the canonical duffle GPU
+ *  Provides the PSYQ-style CamelCase aliases for the duffle GPU primitive setters and OT operations.
- *  primitive setters and OT operations. The duffle snake_case names are
+ *  The duffle snake_case names are primary; this header is for users who prefer the PSYQ SDK function names from the legacy C API.
 *  primary; this header is for users who prefer the PSYQ SDK function
 *  names from the legacy C API.
 *
 *  USAGE:   #include "duffle/gp_vendor_sym.h"   // after gp.h
 *
@@ -23,15 +21,11 @@
 *    OT operations:
 *      AddPrim(ot, p)  -> orderingtbl_add_primitive(ot, p)
 *
- *  The gp0_cmd_* / gp1_cmd_* byte constants are already short and
+ *  The gp0_cmd_* / gp1_cmd_* byte constants are already short and descriptive; no vendor alias is provided for them.
 *  descriptive; no vendor alias is provided for them.
 *
 *  The vendor mnemonics are NOT registered with the duffle word-count
 *  metadata (word_counts.metadata.h). They expand to the duffle canonical
 *  macros which DO have word-count entries (the ones emitted by
 *  mac_format_f3_color / mac_gte_store_f3 / etc.). Verification: V13
 *  (objdump byte-identical) holds.
 *
 *  The vendor mnemonics are NOT registered with the duffle word-count metadata (word_counts.metadata.h).
 *  They expand to the duffle macros which DO have word-count entries
 *  (the ones emitted by mac_format_f3_color / mac_gte_store_f3 / etc.). Verification: V13 (objdump byte-identical) holds.
 * ============================================================================ */
 #ifdef INTELLISENSE_DIRECTIVES
@@ -0,0 +1,76 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	include "gen/macs.h"
 #	include "gen/offsets.h"
 #	include "gte.h"
 #	include "gp.h"
 #	include "lottes_tape.h"	
 #endif
 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(U4 r_face_cusor, U4 r_i0, U4 r_i1, U4 r_i2) atom_dbg_skip MipsAtomComp_Proc_(ac_load_tri_indices, {
 	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)),
 })
 /* 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(U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_f3, {
 	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(U4 r_vert_base, U4 r_v0, U4 r_v1, U4 r_v2) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_load_tri_verts, {
 	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),
 })
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices of the
 * G4 triangle portion to p0/p1/p2.
 * 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(U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_g4_p012, {
 	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)),
 })
 /* Words: 1; Stores the V3 screen coord to the G4's p3 slot.
 * 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(U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_g4_p3, { gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p3)) })
 #pragma endregion MACs (Mips Atom Components)
 #pragma region Bsked Atoms
 typedef Struct_(Binds_SetGteWorld) {
 	M3_S2* transform;
 };
 internal MipsAtom_(set_gte_world) atom_info(
 		atom_bind(Binds_SetGteWorld)
 	,	atom_reads(R_TapePtr)
 ){
 	/* Pop matrix address from tape into R_T3 ($11) */
 	load_word(R_T3, R_TapePtr, O_(Binds_SetGteWorld,transform)),
 	add_ui_self(    R_TapePtr, S_(Binds_SetGteWorld)),
 	/* 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),
 	mac_yield()
 };
 #pragma endregion Baked Atoms
@@ -17,9 +17,8 @@
 *            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
+ *  Vendor mnemonics (gte_mtc2, gte_mfc2, gte_lwc2, gte_swc2, etc.) are NOT in this header.
- *  NOT in this header. They live in the opt-in `gte_vendor_sym.h` for
+ *  They are in the opt-in `gte_vendor_sym.h` for users who prefer the textbook MIPS assembly mnemonics.
 *  users who prefer the textbook MIPS assembly mnemonics.
 * ============================================================================ */
 #ifdef INTELLISENSE_DIRECTIVES
@@ -34,20 +33,16 @@
 *  gte.h — Geometry Transformation Engine (COP2) for the PS1
 * ============================================================================
 *
- *  Hand-rolled DSL for emitting GTE/MIPS instruction words as raw `.word`
+ *  Hand-rolled DSL for emitting GTE/MIPS instruction words as raw `.word` constants from C.
- *  constants from C. No GCC inline-assembly string syntax in the code body.
+ *  No GCC inline-assembly string syntax in the code body.
 *
 *  STYLE NOTES
 *  -----------
- *  - Per-field encoders are named `enc_gte_<field>(value)` and each one
+ *  - Per-field encoders are named `enc_gte_<field>(value)` and each one self-masks its argument before shifting.
- *    self-masks its argument before shifting. Mirrors the `enc_op / enc_rs
+ *    Mirrors the `enc_op / enc_rs / enc_rt / ...` family in mips.h.
- *    / enc_rt / ...` family in mips.h.
+ *  - The composite `enc_gte_cmdw(sf, mx, v, cv, lm, cmd)` is a flat OR of the per-field encoders, plus the COP2/CO base.
- *  - The composite `enc_gte_cmdw(sf, mx, v, cv, lm, cmd)` is a flat OR of
+ *  - Pre-baked shortcuts (`gte_cmd_rtpt`, `gte_cmd_rtps`, …) are defined for the common cases so call sites read like assembly source.
- *    the per-field encoders, plus the COP2/CO base.
+ *  - All register/field values are enums (not `#define`s) so they show up in debugger symbol tables and IDE autocomplete.
 *  - Pre-baked shortcuts (`gte_cmd_rtpt`, `gte_cmd_rtps`, …) are defined
 *    for the common cases so call sites read like assembly source.
 *  - All register/field values are enums (not `#define`s) so they show up
 *    in debugger symbol tables and IDE autocomplete.
 *
 *  SEE ALSO
 *  --------
@@ -58,8 +53,7 @@
 /* --- GTE Data Registers (Coprocessor 2) ---
 * Preprocessor-visible integer ids for the COP2 data register file.
- * Each enum value is bound to a parallel `_Code` `#define` so the
+ * Each enum value is bound to a parallel `_Code` `#define` so the preprocessor can stringify the integer (for `reg_str`/`rgcc` paths).
 * preprocessor can stringify the integer (for `reg_str`/`rgcc` paths).
 * Same pattern as the GPR `_Code` set in mips.h. */
 #define C2_VXY0_Code  0
 #define C2_VZ0_Code   1
@@ -192,10 +186,8 @@ enum {
 /* --- GTE Control Register Indices (for ctc2/cfc2) ---
 * Preprocessor-visible integer ids for the COP2 control register file.
- * Each enum value is bound to a parallel `_Code` `#define` so the
+ * Each enum value is bound to a parallel `_Code` `#define` so the preprocessor can stringify the integer (for `reg_str`/`rgcc` paths).
- * preprocessor can stringify the integer (for `reg_str`/`rgcc` paths).
+ * Same pattern as the GPR `_Code` set in mips.h. Note: indices 21-23 are reserved/unused on real hardware, so there's a gap. */
 * Same pattern as the GPR `_Code` set in mips.h. Note: indices 21-23
 * are reserved/unused on real hardware, so there's a gap. */
 #define gte_cr_RT11_Code  0
 #define gte_cr_RT12_Code  1  /* packed with RT13 in bits 16..31 */
 #define gte_cr_RT13_Code  2  /* packed with RT22 in bits 16..31 */
@@ -223,8 +215,9 @@ enum {
 #define gte_cr_RFC_Code  27
 #define gte_cr_GFC_Code  28
 #define gte_cr_BFC_Code  29
-#define gte_cr_OFX_Code  30
+#define gte_cr_OFX_Code  24
-#define gte_cr_OFY_Code  31
+#define gte_cr_OFY_Code  25
 #define gte_cr_H_Code    26
 enum {
 	gte_cr_RT11 = gte_cr_RT11_Code, gte_cr_RT12 = gte_cr_RT12_Code, gte_cr_RT13 = gte_cr_RT13_Code,
@@ -246,21 +239,16 @@ enum { _C2_OPS_ = 0
 /* COP2 transfer sub-opcodes (5-bit field in the `rs` slot of enc_gte_tx).
 *
- * Spans the 2x2 {From, To} × {Data, Control} register classes that the
+ * Spans the 2x2 {From, To} × {Data, Control} register classes that the GTE exposes:
 * GTE exposes:
 *
 *   bit 1 (0x02): register class — 0 = data,  1 = control
 *   bit 2 (0x04): direction      — 0 = read,  1 = write
 *
- * The values 0x00 (sub_mfc2) and 0x04 (sub_mtc2) are the same 5-bit
+ * The values 0x00 (sub_mfc2) and 0x04 (sub_mtc2) are the same 5-bit numbers as the general MIPS `cop_mf` / `cop_mt` defined in mips.h
- * numbers as the general MIPS `cop_mf` / `cop_mt` defined in mips.h
+ * (which target the data register file on any coprocessor).
- * (which target the data register file on any coprocessor). They are
+ * They are re-aliased here so the four-way table reads like the spec mnemonics (MFC2 / CFC2 / MTC2 / CTC2)
- * re-aliased here so the four-way table reads like the spec mnemonics
+ * and so the encoding lives next to its only consumer (this header).
 * (MFC2 / CFC2 / MTC2 / CTC2) and so the encoding lives next to its
 * only consumer (this header).
 *
- * Vendor mnemonic aliases (gte_mfc2 / gte_mtc2 / gte_cfc2 / gte_ctc2)
+ * Vendor mnemonic aliases (gte_mfc2 / gte_mtc2 / gte_cfc2 / gte_ctc2) live in gte_vendor_sym.h. */
 * live in gte_vendor_sym.h. */
 enum { _C2_TX_SUBS_ = 0
 	, sub_mfc2 = 0x00 /* MFC2: Move From Coprocessor 2 data   reg */
 	, sub_cfc2 = 0x02 /* CFC2: Copy From Coprocessor 2 ctrl   reg */
@@ -270,11 +258,11 @@ enum { _C2_TX_SUBS_ = 0
 /* COP2 (GTE) Transfer Format: mfc2 / cfc2 / mtc2 / ctc2 rt, rd
 * Layout: [op_cop2:6][sub:5][rt:5][rd:5][0:11]
- *   - sub: one of sub_mfc2 / sub_cfc2 / sub_mtc2 / sub_ctc2
+ *  - sub: one of sub_mfc2 / sub_cfc2 / sub_mtc2 / sub_ctc2
- *   - rt:  GPR source/dest
+ *  - rt:  GPR source/dest
- *   - rd:  COP2 register index (0..31):
+ *  - rd:  COP2 register index (0..31):
- *            data class → C2_VXY0_Code..C2_LZCR_Code (gte_in_v0_xy..gte_math_accum2 aliases)
+ *    data class → C2_VXY0_Code..C2_LZCR_Code (gte_in_v0_xy..gte_math_accum2 aliases)
- *            ctrl class → gte_cr_RT11_Code..gte_cr_OFY_Code */
+ *    ctrl class → gte_cr_RT11_Code..gte_cr_OFY_Code */
 #define enc_gte_tx(sub, rt, rd) (enc_op(op_cop2) | enc_rs(sub) | enc_rt(rt) | enc_rd(rd))
@@ -314,8 +302,8 @@ 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
+ * For the typical user-facing vector-level load (xy + z as two instructions),
- * instructions), use the higher-level `gte_load_vN` macros below. */
+ * 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)
@@ -323,13 +311,12 @@ enum { _C2_TX_SUBS_ = 0
 * Opcode is always MIPS_OP_COP2, RS is always 1 (CO).
 * The lower 25 bits are the GTE-specific command payload.
 *
- * The granular `enc_gte_<field>(x)` macros below mirror the `enc_op`/`enc_rs`
+ * The granular `enc_gte_<field>(x)` macros below mirror the `enc_op`/`enc_rs` pattern in mips.h:
- * pattern in mips.h: each one self-masks and shifts its own field, so a
+ * Each one self-masks and shifts its own field, so a caller can build up a GTE command piece by piece
- * caller can build up a GTE command piece by piece (handy for state-driven
+ * (handy for state-driven MVMVA emitters that vary one field at a time).
 * MVMVA emitters that vary one field at a time).
 *
- * `ENC_GTE_CMD` is the all-in-one convenience for emitting a full command
+ * `ENC_GTE_CMD` is the all-in-one convenience for emitting a full command word in one go.
- * word in one go. It just ORs the per-field encoders together. */
+ * It just ORs the per-field encoders together. */
 #define gte_cmd_base (enc_op(op_cop2) | (1 << 25))
 /* Per-field encoders. Each one does (value & mask) << shift on its own. */
@@ -353,41 +340,35 @@ enum { _C2_TX_SUBS_ = 0
 /* GTE command words for the common cases.
 *
- * These are pure compile-time integer constants — the C compiler
+ * These are pure compile-time integer constants — the C compiler constant-folds them into `.word` directives in .rodata.
- * constant-folds them into `.word` directives in .rodata. Use them
+ * Use them inside `asm_inline(...)` blocks (see `gte_rtpt` below for the idiom).
 * inside `asm_inline(...)` blocks (see `gte_rtpt` below for the
 * canonical idiom).
 *
 * Decomposition (per the `enc_gte_<field>` definitions above):
 *   gte_cmdw_<name> = gte_cmd_base | enc_gte_cmd(<cmd>)
- * The SF/MX/V/CV/LM fields are all zero in the common cases (standard
+ * The SF / MX / V / CV / LM fields are all zero in the common cases 
- * rotation-matrix, no scaling factor, V0 vector, translation vector,
+ * (standard rotation-matrix, no scaling factor, V0 vector, translation vector, no clamp),
- * no clamp), so the only varying bits are the `cmd` field.
+ * so the only varying bits are the `cmd` field.
 *
- * Naming follows the file's convention: `gte_cmd_*` is the raw
+ * Naming convention:
- * 6-bit `cmd` field id, `gte_cmdw_*` is the fully-encoded 32-bit
+ * - `gte_cmd_*` : Raw 6-bit `cmd` field id 
- * instruction word ready to drop into a `.word` directive.
+ * - `gte_cmdw_* : 32-bit instruction word ready to drop into a `.word` directive.
 *
 * --------------------------------------------------------------------------
 *  PsyQ-compatibility note (RTPS/RTPT):
- *  The original Sony PsyQ `inline_n.h` ships RTPT as `cop2 0x0280030` and
+ *  The original Sony PsyQ `inline_n.h` ships RTPT as `cop2 0x0280030` and RTPS as `cop2 0x0180001`.
- *  RTPS as `cop2 0x0180001`. Both have `0x20` set in the upper-reserved
+ *  Both have `0x20` set in the upper-reserved region (bit 21) AND `sf=1` (bit 19) — i.e. the "no division" flag.
- *  region (bit 21) AND `sf=1` (bit 19) — i.e. the "no division" flag.
+ *  Per psx-spec these bits are reserved/must-be-zero,
- *  Per psx-spec these bits are reserved/must-be-zero, but the real GTE
+ *  but the real GTE hardware and PCSX-Redux's GTE model both IGNORE them on these two commands
- *  hardware and PCSX-Redux's GTE model both IGNORE them on these two
+ *  (the perspective divide happens regardless of `sf`).
 *  commands (the perspective divide happens regardless of `sf`).
 *
- *  If we emit a strictly-spec-compliant word (`sf=0`, reserved bits
+ *  If we emit a strictly-spec-compliant word (`sf=0`, reserved bits clear),
- *  clear), PCSX-Redux's GTE checks those bits more strictly than the
+ *  PCSX-Redux's GTE checks those bits more strictly than the silicon does and RTPT silently no-ops — 
- *  silicon does and RTPT silently no-ops — the floor's screen
+ *  the floor's screen coordinates come out as raw projection-of-rotation (Z never divided),
- *  coordinates come out as raw projection-of-rotation (Z never
+ *  `nclip` ends up wrong, and the triangle is culled.
 *  divided), `nclip` ends up wrong, and the triangle is culled.
 *
- *  So for RTPS and RTPT we OR-in the `0x28` "PsyQ compat" pattern to
+ *  So for RTPS and RTPT we OR-in the `0x28` "PsyQ compat" pattern to match the working bit pattern everyone has shipped for 25 years.
- *  match the working bit pattern everyone has shipped for 25 years.
+ *  NCLIP / OP / MVMVA stay spec-clean — their reserved bits really are zero in the original PsyQ source.
 *  NCLIP/OP/MVMVA stay spec-clean — their reserved bits really are
 *  zero in the original PsyQ source.
 * --------------------------------------------------------------------------
 */
 #define gte_cmdw_psyq_compat  (1u << 21 | enc_gte_sf(gte_sf_integer))
@@ -420,20 +401,16 @@ enum { _C2_TX_SUBS_ = 0
 /**
 * @brief Loads a single SVECTOR to GTE vector register V0
 *
 * @details Loads values from an SVECTOR struct to GTE data registers C2_VXY0
 * (XY at offset 0) and C2_VZ0 (Z at offset 4) using `lwc2`.
 *
- * Uses string-style GCC inline asm with `%0` substitution because the
+ * Uses string-style GCC inline asm with `%0` substitution because the base register `r0` is a runtime GPR chosen by the compiler.
- * base register `r0` is a runtime GPR chosen by the compiler — it cannot
+ * It cannot be encoded into a static `.word` constant.
 * be encoded into a static `.word` constant.
 *
- * Usage:
+ * Usage: asm_gte_load_v0(svector_ptr);
 *   asm_gte_load_v0(svector_ptr);
 */
 /* lwc2 encoding helpers parameterized on the base GPR.
 *
 * gte_lw_v0_xy(base)  → lwc2 $0,  0(base)   ; C2_VXY0
 * gte_lw_v0_z(base)   → lwc2 $1,  4(base)   ; C2_VZ0
 * gte_lw_v1_xy(base)  → lwc2 $2,  0(base)   ; C2_VXY1
@@ -442,8 +419,7 @@ enum { _C2_TX_SUBS_ = 0
 * gte_lw_v2_z(base)   → lwc2 $5,  4(base)   ; C2_VZ2
 *
 * `base` is the GPR number to bake into the .word constant's `rs` field.
- * These are pure compile-time integers; the C compiler constant-folds
+ * These are pure compile-time integers; the C compiler constant-folds them into .word directives. */
 * them into .word directives. */
 enum {
 	GTE_Z_Offset = 4
@@ -458,26 +434,21 @@ enum {
 /* gte_load_vN(r_ptr, base) — placeholder-punned lwc2 loaders
 *
- * Emits `.word` constants encoding `lwc2 $N, off(<base>)` for the chosen
+ * Emits `.word` constants encoding `lwc2 $N, off(<base>)` for the chosen GTE vector register, where `<base>` is the GPR number you pass in
 * GTE vector register, where `<base>` is the GPR number you pass in
 * (typically one of R_T4..R_T9 for the standard "3-pointer" pattern).
 *
 * The caller MUST bind `r_ptr` to that same GPR via a register variable:
 *     register V3_S2* p_in_12 __asm__("$12") = my_ptr;
 *     gte_load_v0(p_in_12, R_T4);   // R_T4 = 12, base is $12
 *
- * Then `"r"(r_ptr)` inside the asm binds to $12 (the only register
+ * Then `"r"(r_ptr)` inside the asm binds to $12 (the only register `p_in_12` can live in),
- * `p_in_12` can live in), which is exactly the register the .word
+ * which is exactly the register the .word constants expect.
- * constants expect. A `"$12"` clobber would conflict with the
+ * A `"$12"` clobber would conflict with the register-variable binding ("asm specifier for variable conflicts with asm clobber list"), so we omit it.
- * register-variable binding ("asm specifier for variable conflicts
+ * The other ABI-clobbers ($2/$8/$9/$31) stay because the GTE instructions don't touch caller-saved GPRs but the kernel does treat them as volatile.
 * with asm clobber list"), so we omit it. The other ABI-clobbers
 * ($2/$8/$9/$31) stay because the GTE instructions don't touch
 * caller-saved GPRs but the kernel does treat them as volatile.
 *
 * WHICH REGISTER TO PICK
 * ----------------------
- * Any caller-saved GPR is safe. Recommended default for an RTPT-style
+ * Any caller-saved GPR is safe. Recommended default for an RTPT-style 3-pointer pipeline:
 * 3-pointer pipeline:
 *   gte_load_v0(p0, R_T4);  // $12
 *   gte_load_v1(p1, R_T5);  // $13
 *   gte_load_v2(p2, R_T6);  // $14
@@ -490,8 +461,7 @@ enum {
 *   clobbers section   : "$2", "$8", ..., "memory"      (from asm_clobber)
 *   3 colons total, GCC-legal. No string-syntax mnemonics in the .word body.
 *
- * The `asm_clobber(...)` helper from gcc_asm.h prepends the colon that
+ * The `asm_clobber(...)` helper from gcc_asm.h prepends the colon that starts the clobbers section. */
 * starts the clobbers section. */
 #define gte_load_v0(r_ptr, base) asm volatile(       \
 	asm_words( gte_lw_v0_xy(base), gte_lw_v0_z(base) ) \
 	asm_rpins,   r_use(r_ptr)                          \
@@ -510,12 +480,10 @@ enum {
 	asm_clobber: rlit(R_V0), rlit(R_T0), rlit(R_T1), rlit(R_RA), clb_mem_drain \
 )
-/* gte_load_v0v1v2(p0, p1, p2, b0, b1, b2) — the canonical prelude to gte_cmd_rtpt.
+/* 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")
@@ -534,29 +502,20 @@ enum {
 /**
 * @brief Rotate, Translate and Perspective Triple (23 cycles)
- *
+ * @details Performs rotation, translation and perspective calculation of three vertices at once.
- * @details Performs rotation, translation and perspective calculation of three
+ * The equation performed is the same as gte_rtps() only repeated three times for each vertex.
- * vertices at once. The equation performed is the same as gte_rtps() only
+ * The result of the first vertex is stored in GTE data register C2_SXY0, the second vector in C2_SXY1 then C2_SXY2.
 * repeated three times for each vertex. The result of the first vertex is
 * stored in GTE data register C2_SXY0, the second vector in C2_SXY1 then
 * C2_SXY2.
 *
 * Encoder-style emission (no inline-asm strings in the code body):
- *   1. Two `nop` words fill the COP2 pipeline latency — the GTE
+ *   1. Two `nop` words fill the COP2 pipeline latency — the GTE takes ~8 cycles per perspective divide, 
- *      takes ~8 cycles per perspective divide, and the nops let any
+ *      and the nops let any preceding lwc2/swc2 retire before RTPT starts reading its inputs from V0/V1/V2.
- *      preceding lwc2/swc2 retire before RTPT starts reading its
+ *   2. The RTPT command word itself is `gte_cmdw_rtpt` (see the pre-baked encoders above) — 
- *      inputs from V0/V1/V2.
+ *      `0x0280030` decoded as `op_cop2` | CO(1) | cmd=RTPT, with all SF/MX/V/CV/LM fields zero
- *   2. The RTPT command word itself is `gte_cmdw_rtpt` (see the
+ *      (standard rotation, no scaling, V0 vector, translation vector, no clamp).
 *      pre-baked encoders above) — `0x0280030` decoded as
 *      `op_cop2` | CO(1) | cmd=RTPT, with all SF/MX/V/CV/LM fields
 *      zero (standard rotation, no scaling, V0 vector, translation
 *      vector, no clamp).
 *
- * Clobbers the caller-saved GPRs via `clbr_volatile_gprs` (per the kernel
+ * Clobbers the caller-saved GPRs via `clbr_volatile_gprs` (per the kernel ABI)
- * ABI) plus the standard "memory" barrier. Does not clobber any COP2
+ * plus the standard "memory" barrier. Does not clobber any COP2 data/control register — 
- * data/control register — those have to be saved by the caller if
+ * those have to be saved by the caller if they need to survive across the call (RTPT writes SXY0..2, SZ0..3, OTZ, MAC0..3, IR0..3, etc.).
 * they need to survive across the call (RTPT writes SXY0..2, SZ0..3,
 * OTZ, MAC0..3, IR0..3, etc.).
 */
 #define gte_rtpt()                        \
 	asm volatile(                           \
@@ -572,32 +531,24 @@ enum {
 /**
 * @brief Normal clipping (8 cycles)
- *
+ * @details Computes the sign of three screen coordinates (C2_SXY0-2) used for backface culling.
- * @details Computes the sign of three screen coordinates (C2_SXY0-2) used for
+ * If the value of C2_MAC0 is negative, the coordinates are inverted and thus the triangle is back facing.
 * backface culling. If the value of C2_MAC0 is negative, the coordinates are
 * inverted and thus the triangle is back facing.
 *
 * The following equation is performed when executing this GTE command:
 *
 *     MAC0 = SX0*SY1 + SX1*SY2 + SX2*SY0 - SX0*SY2 - SX1*SY0 - SX2*SY1
 *
 * Encoder-style emission (no inline-asm strings in the code body):
- *   1. Two `nop` words fill the COP2 pipeline latency - the GTE
+ *   1. Two `nop` words fill the COP2 pipeline latency
- *      pipeline takes a few cycles per op, and the nops let any
+ *      - the GTE pipeline takes a few cycles per op, and the nops let any preceding
- *      preceding lwc2/swc2/RTPT retire before NCLIP starts reading
+ *      lwc2/swc2/RTPT retire before NCLIP starts reading its inputs from SXY0/SXY1/SXY2.
- *      its inputs from SXY0/SXY1/SXY2.
+ *   2. The NCLIP command word itself is `gte_cmdw_nclip` (see the pre-baked encoders above)
- *   2. The NCLIP command word itself is `gte_cmdw_nclip` (see the
+ *      - `0x01400006` decoded as  `op_cop2` | CO(1) | cmd=NCLIP, with all SF/MX/V/CV/LM fields zero.
- *      pre-baked encoders above) - `0x01400006` decoded as
+ *      NCLIP is spec-clean in the original PsyQ source (unlike RTPS/RTPT which carry the `gte_cmdw_psyq_compat` quirk),
- *      `op_cop2` | CO(1) | cmd=NCLIP, with all SF/MX/V/CV/LM fields
+ *      so `gte_cmdw_nclip` does NOT OR in any reserved bits.
 *      zero. NCLIP is spec-clean in the original PsyQ source
 *      (unlike RTPS/RTPT which carry the `gte_cmdw_psyq_compat`
 *      quirk), so `gte_cmdw_nclip` does NOT OR in any reserved bits.
 *
- * Clobbers the caller-saved GPRs via `clbr_volatile_gprs` (per the kernel
+ * Clobbers the caller-saved GPRs via `clbr_volatile_gprs` (per the kernel ABI) plus the standard "memory" barrier.
- * ABI) plus the standard "memory" barrier. Does not clobber any COP2
+ * Does not clobber any COP2 data/control register.
- * data/control register - those have to be saved by the caller if
+ * Those have to be saved by the caller if they need to survive across the call (NCLIP writes MAC0 only;
- * they need to survive across the call (NCLIP writes MAC0 only; it
+ * it is purely a sign-of-double-product computation on SXY0..2).
 * is purely a sign-of-double-product computation on SXY0..2).
 */
 #define gte_nclip()                       \
 	asm volatile(                           \
@@ -623,13 +574,10 @@ enum {
 		"cop2 0x0158002D;")
 /* asm_gte_matrix_set_rotation(r0)
 * Loads the 3x3 rotation matrix at `r0` into the GTE's rotation-matrix control registers (RT11..RT22, indices 0..4) via ctc2.
 *
- * Loads the 3x3 rotation matrix at `r0` into the GTE's rotation-matrix
+ * Memory layout at r0: five contiguous 32-bit words (offsets 0..16), each holding two packed 16-bit matrix elements.
- * control registers (RT11..RT22, indices 0..4) via ctc2.
+ * The first 1.5 rows of a standard PSX SDK MATRIX struct (where each row is laid out as
 *
 * 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] | ...).
 *
 * Generated MIPS (mirrors the source macro):
@@ -644,27 +592,22 @@ enum {
 *   ctc2 $13,  $3         ; → C2_RT21
 *   ctc2 $14,  $4         ; → C2_RT22
 *
- * Same contract as gte_load_v0: caller MUST bind `r0` to $12 via a
+ * Same contract as gte_load_v0: caller MUST bind `r0` to $12 via a register variable (`rgcc(R_T4)`) for the `lw $12, off(...)`
- * register variable (`rgcc(R_T4)`) for the `lw $12, off(...)`
+ * instructions to read from the right base. The `"r"(r0)` constraint alone doesn't force a specific GPR — it just lets GCC pick one.
- * instructions to read from the right base. The `"r"(r0)` constraint
+ * The .word constants here bake R_T4/R_T5/R_T6 into the `rs` field of each lw, so the lw instructions will 
- * alone doesn't force a specific GPR — it just lets GCC pick one.
+ * only do the right thing if $12 / $13 / $14 hold the matrix base at runtime.
 * The .word constants here bake R_T4/R_T5/R_T6 into the `rs` field
 * of each lw, so the lw instructions will only do the right thing
 * if $12/$13/$14 hold the matrix base at runtime.
 *
 *   M3_S2* m = ...;
 *   register M3_S2* m_in_12 rgcc(R_T4) = m;
 *   asm_gte_matrix_set_rotation(m_in_12);
 *
- * We clobber $12/$13/$14 (the ones we use as scratch inside the
+ * We clobber $12/$13/$14 (the ones we use as scratch inside the inline asm)
- * inline asm) plus the system clobbers; we don't clobber `r0` because
+ * plus the system clobbers; we don't clobber `r0` because the `rgcc` binding already says "this variable lives in $12".
 * the `rgcc` binding already says "this variable lives in $12".
 *
- * WARNING: Incomplete by design. The source macro only writes RT11..RT22
+ * WARNING: Incomplete by design. The source macro only writes RT11..RT22 (5 of 9 rotation elements);
- * (5 of 9 rotation elements); RT23 and the entire RT3x row are left
+ * RT23 and the entire RT3x row are left untouched.
- * untouched. Real libpsn00b SetRotMatrix writes all 9. Use only when the
+ * Real libpsn00b SetRotMatrix writes all 9. Use only when the GTE's remaining rotation entries are already correct,
- * GTE's remaining rotation entries are already correct, or you will
+ * or you will get stale-RT2x/RT3x artifacts in RTPS/RTPT/MVMVA output.
 * get stale-RT2x/RT3x artifacts in RTPS/RTPT/MVMVA output.
 */
 #define asm_gte_matrix_set_rotation(r0) \
 	asm volatile(                         \
@@ -2,10 +2,8 @@
 *  duffle DSL — GTE Vendor Mnemonics (opt-in)
 *  ============================================================================
 *
- *  Provides the textbook MIPS assembly mnemonics for the GTE/COP2
+ *  Provides the textbook MIPS assembly mnemonics for the GTE/COP2 instructions as thin aliases to the duffle macros in gte.h.
- *  instructions as thin aliases to the canonical duffle macros in gte.h.
+ *  The duffle names are primary; this header is for users who prefer the textbook mnemonics.
 *  The duffle names are primary; this header is for users who prefer
 *  the textbook mnemonics.
 *
 *  USAGE:   #include "duffle/gte_vendor_sym.h"   // after gte.h
 *
@@ -1,102 +1,208 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #	include "gen/macs.h"
 #	include "gen/offsets.h"
 #	include "dsl.h"
 #	include "gcc_asm.h"
 # include "mips.h"
 # include "gte.h"
 # include "memory.h"
-#	include "atom_dsl.h"
+#	include "dsl.atom.h"
 #	include "gen/duffle.macs.h"
 #	include "gen/duffle.offsets.h"
 #endif
-typedef U4 const MipsCode;
+#pragma region Tape Drive
-typedef Slice_(MipsCode);
+/* -----------------------------------------------------------------------------
-typedef Slice_MipsCode MipsAtom;
+ *  TAPE DRIVE ABI
 * -----------------------------------------------------------------------------
 * Note(Ed): One of the main purposes of this codebase is to help me
 * learn this, as such the information below may be entirely realized 
 * or finalized conceptually.
 * -----------------------------------------------------------------------------
 * This ABI and its associated legos were directly inspired by researching
 * the work of Timothy Lottes and Onat Türkçüoğlu; along with many others.
 * It's the simplest bootstrap of a a directly executed chain of assemby
 * arrays (Atoms) that terminate with a yield sequence to the next atom.
 * These eventually lead to a terminal atom for the tape which is defined
 * below as "tape_exit".
 * 
 * This behaves as one of the simplest runtime harnesses ontop of a 
 * host-enviornment's execution engine to author and compose programs with.
 * From here various conventions can be further applied.
 * To make things easier to understand it may be better to focus on what this
 * ABI does not have. It does not have have any branching within the tape but
 * relative branches between atoms. Branching nearly is always downstream.
 * Stack usage is non-existent. Push/Pop, FIFO, or Arena/Bump data structures
 * are used by atoms explicitly. In it's current form withe C11 macro dsl,
 * the user also has to do manual register allocation per atom.
 * 
 * One of the remarkable things about utilizing this abi is its essentially
 * interopable with CPUs, GPUs, FPGA, or, basically anything
 * from the 5th generation consoles and onward.
 * The ABI directly reflects how all computational hardware must be architected
 * in order to execute digital logic effectively on current era tech.
 * On the PS1 we don't have access to a few features like multi-threading,
 * speculative execution, or L3 cache; but, we can set the foundation for legoing
 * whats required baseline wise for eventually expanding the harness and core atoms
 * to take those newer hardware features into account. For example, you can easily
 * expand this to support wave-based execution model on a PS2 or PS3.
 * Not having a stack or automatic register allocation means the user can't ignore
 * excessive argument shuffle across workload or waves and thier phases.
 * Crossing ABI boundaries to other runtimes that do has an obviouss penalties.
 * 
 * Learning data-oreinted code becomes a natural progression. Your not fighting
 * a stack-based procedural paradigm that wants to argument shuffle on the stack
 * by lack of constraints on how the user may "call" a procedure. The user doesn't
 * have to hammer down "rules" or patterns to know how to massage the compiler
 * to get the asesmbly into its natural form. The form is obvious, and once
 * the user gets to author their compoonents it becomes a game of tetris.
 * 
 * Another feature is this ABI is very compatible with bootstrapping and developing
 * simple toolchains built off of bit-packed annotated command streams the user can
 * directly author, maintatain, and immediately execute. That being a color forth.
 * This can make the tetris less of a chore with some helpful policy generation for
 * allocation of registers, helping to choose resuable components, designing DSL on
 * the fly, etc.
 * -----------------------------------------------------------------------------
 * TODO(Ed): We ned pretty ascii diagrams and proper guides, articles, etc.
 * -----------------------------------------------------------------------------
 * For now this thing is just functioning and I'm abusing C11 + a lua metaprogram
 * to help establish a hybrid toolchain to ideate on a traditional text-based
 * authoring UX for this paradigm.
 * If pcsx-redux gets me viable hot-reload and persistent data storage beyond
 * save-states (just copying ram to filesystem). I can author a color forth to
 * mess around with, with an editor in-emulator or on the actual machine itself.
 * Assembly is tedius, but I think this codebase most likely has some of the most,
 * ergonomic you can come across..
 * */
 /* 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 */
 /* Stringification codes for the GCC inline assembler clobber lists. */
 #define R_AtomJmp_Code R_T8_Code
 #define R_TapePtr_Code R_T9_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.
 // 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
 };
 typedef U4 const MipsCode; // Underlying type to mips asm words.
 typedef Slice_(MipsCode);
 typedef U4 const MipsAtom; // Underlying type to an array of mips asm words that must terminate with an ac_yield.
 #define MipsAtom_(sym) MipsCode sym [] align_(4) =
 // Bare form: file-scope declaration with hardcoded body.
 // Used for components with no args (e.g., ac_load_tri_indices) or identifier-args (hardcoded register names).
 //   MipsAtomComp_(ac_X) { body }
 // expands to:
 //   MipsCode ac_X[] align_(4) = { body };
 #define MipsAtomComp_(sym) MipsCode sym [] align_(4) =
 // Function form: function-body block that returns a MipsAtom slice.
 // Used for components with value-args (e.g., ac_format_f3_color).
-//   FI_ MipsAtom ac_X(args) MipsAtomComp_Proc_(ac_X, { body })
+//   FI_ Slice_MipsCode ac_X(args) MipsAtomComp_Proc_(ac_X, { body })
 // expands to:
-//   FI_ MipsAtom ac_X(args) { MipsCode ac_X[] align_(4) = { body }; return slice_from_array(MipsCode, ac_X); }
+//   FI_ Slice_MipsCode ac_X(args) { MipsCode ac_X[] align_(4) = { body }; return slice_from_array(MipsCode, ac_X); }
 #define MipsAtomComp_Proc_(sym, ...) { MipsCode sym [] align_(4) = __VA_ARGS__; return slice_from_array(MipsCode, sym); }
-// Auto-generated component macros (<module>/gen/<dir>/<dir>.macs.h) are included manually by the unity build.
+/* Line-table anchor: gcc only adds a file to the .debug_line file table when the
   file contains line-numbered content. Files containing only:
     - `MipsAtomComp_` static-array declarations, or
     - `MipsAtomComp_Proc_` (force-inline) function bodies whose line info gets
       attributed to the call site at the include point are otherwise omitted from the file table,
 			 which breaks the DWARF injection when it tries to resolve atom-component provenance paths.
-/* Register aliases */
+   Place `ATOM_FILE_LINE_MARKER();` once at file scope in any `.atom.c` that defines atoms.
-enum {
+	 The macro expands to a file-scope `internal U4 const` declaration keeps the file in the line table.
-	R_AtomJmp    = R_T9,
+	 The constant is in `.rodata` and unreferenced; the linker may eliminate it.
-	R_TapePtr    = R_T8,  /* The Instruction Stream Pointer */
+	 The two-level concat + `__LINE__` suffix makes the identifier unique per call site
-	R_InCursor   = R_T4,  /* Input data cursor */
+	 (the identifier embeds the source line, so duplicates across `#include`d files don't collide). */
 #define ATOM_FILE_DEBUGGER_LINE_MARKER(file_name) internal U4 const tmpl(atom_file_debugger_line_marker,file_name) = 0
-	R_PrimCursor = R_T7,  /* VRAM output cursor (primitive buffer) */
+ typedef Slice_(MipsAtom); typedef Slice_MipsAtom Tape;
 	R_FaceCursor = R_T4,  /* Input data cursor (indices/faces) */
 	R_VertBase   = R_T5,  /* Base address of the vertex array */
 	R_OtBase     = R_T6,  /* Base address of the Ordering Table */
 /* Stringification codes for the GCC inline assembler clobber lists */
 #define R_TapePtr_Code     R_T8_Code
 #define R_InCursor_Code    R_T4_Code
 #define R_PrimCursor_Code  R_T7_Code
 #define R_FaceCursor_Code  R_T4_Code
 #define R_VertBase_Code    R_T5_Code
 #define R_OtBase_Code      R_T6_Code
 };
 #pragma region Tape Drive
 /* ---------------------------------------------------------------------------
 *  TAPE DRIVE ABI & REGISTER ALIASES (the enum moved earlier; see below)
 * ---------------------------------------------------------------------------*/
 /* The 'Exit' Atom */
-MipsAtom_(tape_exit) { jump_reg(rret_addr), nop };
+atom_dbg_skip MipsAtom_(tape_exit) { jump_reg(rret_addr), nop };
-/* Generalized Tape Engine Runner */
+// TODO(Ed): When we have a substantial workload/throughput, profile each of these to see impact at ABI boundaries.
-FI_ void tape_run(Slice_U4 tape) { register U4* tp rgcc(R_TapePtr) = tape.ptr; asm volatile(
+
 /* Tape Runner (Default) */
 FI_ void tape_run(Tape tape) { register U4* tape_ptr rgcc(R_TapePtr) = u4_r(tape.ptr); asm volatile(
 	asm_words(
-			add_ui(     R_SP, R_SP, -MipsStackAlignment) /* Allocate stack space */
+		  load_word(  R_AtomJmp, R_TapePtr, 0) /* Bootstrap the first jump */
-		, store_word( R_RA, R_SP,           0)         /* Safely backup $ra to the stack */
+		, add_ui_self(R_TapePtr, S_(MipsAtom)) /* Advance tape */
-		, load_word(  R_AtomJmp, R_TapePtr, 0)         /* Bootstrap the first jump */
+		, call_reg(   R_AtomJmp)               /* jalr $t9 */
-		, add_ui_self(R_TapePtr, S_(MipsCode))         /* Advance tape */
+		, nop                                  /* Branch delay slot */
 		, call_reg(   R_AtomJmp)                       /* jalr $t9 */
 		, nop                                          /* Branch delay slot */
 		, load_word(  R_RA, R_SP, 0)                   /* Restore $ra from stack */
 		, add_ui_self(R_SP, MipsStackAlignment)        /* Deallocate stack space */
 	)
-	asm_rpins, r_use(tp)
+	asm_rpins, r_use(tape_ptr)
 	asm_clobber: 
-			rlit(R_AT)
+		rlit(R_AT),
-		, rlit(R_V0), rlit(R_V1)
+		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_T0), rlit(R_T1), rlit(R_T2), rlit(R_T3), rlit(R_T4),
-		/* Tell GCC the tape engine owns and destroys the workspace registers */
+		rlit(R_T5), rlit(R_T6), rlit(R_T7), rlit(R_T8),
-		, rlit(R_PrimCursor), rlit(R_FaceCursor), rlit(R_VertBase), rlit(R_OtBase)
+		clb_mem_drain 
 		, rlit(R_T9)
 		, clb_mem_drain 
 ); }
 /* 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 
 ); }
 // Procedural authoring of tapes:
 typedef Relative_(FArena) Struct_(TapeBuilder) { U4 ptr; U4 capacity; U4 used; };
 FI_ void        tb_init(TapeBuilder* tb, FArena* arena) { tb->ptr = arena->start; tb->used = 0; }
 FI_ TapeBuilder tb_make_old(             FArena* arena) { return (TapeBuilder){ arena->start, 0 }; }
 FI_ TapeBuilder tb_make(Slice mem) { return (TapeBuilder){ mem.ptr, mem.len, 0 }; }
 #define tb_emit_(tb, atom) tb_emit(tb, atom)
 FI_ void tb_emit(TapeBuilder* tb, MipsCode* atom) { u4_r(tb->ptr)[tb->used] = u4_(atom); ++ tb->used; }
 FI_ void tb_data(TapeBuilder* tb, U4        data) { u4_r(tb->ptr)[tb->used] = u4_(data); ++ tb->used; }
 #define tb_emit_(atom)        tb_emit(& tb, atom)
 #define tb_data_(field, data) tb_data(& tb, u4_(data))
-FI_ Slice_U4 tb_end  (TapeBuilder* tb) { tb_emit(tb,tape_exit); return (Slice_U4){ C_(U4*,tb->ptr), tb->used }; }
+FI_ Tape tb_end  (TapeBuilder* tb) { tb_emit(tb,tape_exit); return (Tape){ C_(U4*,tb->ptr), tb->used }; }
-FI_ Slice_U4 tb_slice(TapeBuilder  tb) {                             return (Slice_U4){ C_(U4*,tb.ptr),  tb.used }; }
+FI_ Tape tb_slice(TapeBuilder  tb) {                        return (Tape){ C_(U4*,tb.ptr),  tb.used }; }
-#define tb_scope(tb) for(U4 tbs_once=0;tbs_once==0;++tbs_once,tb_emit(tb,tape_exit))
+#define tb_scope(tb)     for(U4 tbs_once=0;tbs_once==0;++tbs_once,tb_emit(tb,tape_exit))
 FI_ void tb_scope_run_end(TapeBuilder* tb) { tb_emit(tb,tape_exit); tape_run(tb_slice(tb[0])); }
 #define tb_scope_run(tb) for(U4 tbs_once=0;tbs_once==0;++tbs_once,tb_scope_run_end(tb))
 #pragma endregion Tape Drive
 #pragma region Macro Mips Atom Components
@@ -105,121 +211,31 @@ FI_ Slice_U4 tb_slice(TapeBuilder  tb) {                             return (Sli
 *  These do NOT yield. They are expanded inline inside Tape Atoms.
 * ---------------------------------------------------------------------------*/
-// The 'Yield' sequence for Tape Atoms (mac_yield). 
+// The 'Yield' sequence for Tape Atoms (mac_yield).
-MipsAtomComp_(ac_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),
 	add_ui_self(         R_TapePtr, S_(MipsCode)),
-	jump_reg( R_AtomJmp),
+	jump_reg( R_AtomJmp), nop,
 	nop,
 };
-/* Words: 3; Loads 3 S2 indices from the face array */
+atom_dbg_skip MipsAtomComp_(ac_yield_load) {
-MipsAtomComp_(ac_load_tri_indices) {
+	load_word(R_AtomJmp, R_TapePtr, 0),
 	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)),
 };
-/* Words: 18; Translates indices to vertex addresses and pushes them to GTE  */
+atom_dbg_skip MipsAtomComp_(ac_yield_tail) {
-MipsAtomComp_(ac_gte_load_tri_verts) {
+	add_ui_self(R_TapePtr, S_(MipsCode)),
-	shift_lleft(R_AT, R_T0, v3s2_byteoff), add_u_self(R_AT, R_VertBase), 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),
+	jump_reg(  R_AtomJmp), nop,
 	shift_lleft(R_AT, R_T1, v3s2_byteoff), add_u_self(R_AT, R_VertBase), 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_T2, v3s2_byteoff), add_u_self(R_AT, R_VertBase), 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),
 };
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
 * Hardcoded for Poly_F3 (5 words). For Poly_G4, use ac_insert_ot_tag_g4. */
 MipsAtomComp_(ac_insert_ot_tag_f3) {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, R_OtBase),                              // T1 = & OrderingTable[OTZ]
 	load_word(   R_AT, R_T1,         O_(PolyTag,code)),        // AT = old_ot_head
 	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits), // V0 = (5 - 1) << 24 = 4 << 24
 	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits)),    // Strip upper 8 bits (length from prev cell) → keep only low 24
 	or_u(        R_AT, R_AT, R_V0),                            // Merge length
 	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code)),        // prim->tag = packed(prim_length, old_addr)
 	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits)),    // AT = (prim_length << 24) | old_addr
 	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)),
 	store_word(  R_AT, R_T1,         O_(PolyTag,code)),        // OrderingTable[OTZ] = PrimCursor
 };
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list.
 * Hardcoded for Poly_G4 (9 words). For Poly_F3, use ac_insert_ot_tag_f3. */
 MipsAtomComp_(ac_insert_ot_tag_g4) {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, R_OtBase),                              // T1 = & OrderingTable[OTZ]
 	load_word(   R_AT, R_T1,         O_(PolyTag,code)),        // AT = old_ot_head
 	load_upper_i(R_V0, (S_(Poly_G4)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits), // V0 = (9 - 1) << 24 = 8 << 24
 	mask_upper(  R_AT, R_AT,         S_(PolyTag_len_bits)),    // Strip upper 8 bits (length from prev cell) → keep only low 24
 	or_u(        R_AT, R_AT, R_V0),                            // Merge length
 	store_word(  R_AT, R_PrimCursor, O_(PolyTag,code)),        // prim->tag = packed(prim_length, old_addr)
 	shift_lleft( R_AT, R_PrimCursor, S_(PolyTag_len_bits)),    // AT = (prim_length << 24) | old_addr
 	shift_lright(R_AT, R_AT,         S_(PolyTag_len_bits)),
 	store_word(  R_AT, R_T1,         O_(PolyTag,code)),        // OrderingTable[OTZ] = PrimCursor
 };
 /* Words: 3; Emits one (cmd|color) word to R_PrimCursor at the given
 * byte offset. Internal helper used by the *_format_*_color macros. */
 FI_ MipsAtom ac_pack_color_word(U4 off, U4 cmd, U1 r, U1 g, U1 b)
 MipsAtomComp_Proc_(ac_pack_color_word, {
 	load_upper_i(R_AT, (cmd) << 8  | (b)),
 	or_i_self(   R_AT, ((g)   << 8) | (r)),
 	store_word(  R_AT, R_PrimCursor, (off)),
 })
 /* Words: 3; Emits the F3 command+color word (cmd byte | BLUE | GREEN | RED)
 * Args: _r, _g, _b are 8-bit RGB byte values (not raw 16-bit fields).
 * Migrated from hello_gte_tape.c; takes RGB form per the Phase 3 convention. */
 FI_ MipsAtom ac_format_f3_color(U1 r, U1 g, U1 b)
 MipsAtomComp_Proc_(ac_format_f3_color, { mac_pack_color_word(O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b) })
 /* 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). */
 MipsAtomComp_(ac_gte_store_f3_post_rtpt) {
 	gte_sw(C2_SXY0, R_PrimCursor, O_(Poly_F3,p0)),
 	gte_sw(C2_SXY1, R_PrimCursor, O_(Poly_F3,p1)),
 	gte_sw(C2_SXY2, R_PrimCursor, O_(Poly_F3,p2)),
 };
 /* Words: 12; Emits the four (code|color) words of a Poly_G4.
 * Args: rN,gN,bN are 8-bit RGB byte values for each of the 4 vertices. */
 FI_ MipsAtom ac_format_g4_color(
 	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, {
 	mac_pack_color_word(O_(Poly_G4,c0), gp0_cmd_poly_g4, r0,g0,b0),
 	mac_pack_color_word(O_(Poly_G4,c1), 0,               r1,g1,b1),
 	mac_pack_color_word(O_(Poly_G4,c2), 0,               r2,g2,b2),
 	mac_pack_color_word(O_(Poly_G4,c3), 0,               r3,g3,b3),
 })
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices of the
 * G4 triangle portion to p0/p1/p2.
 * 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).
 * The macro name declares the pipeline position; check #6 (GTE state-
 * machine validation) verifies the call site matches the declaration. */
 MipsAtomComp_(ac_gte_store_g4_p012_post_rtpt_pre_rtps) {
 	gte_sw(C2_SXY0, R_PrimCursor, O_(Poly_G4,p0)),
 	gte_sw(C2_SXY1, R_PrimCursor, O_(Poly_G4,p1)),
 	gte_sw(C2_SXY2, R_PrimCursor, O_(Poly_G4,p2)),
 };
 /* Words: 1; Stores the V3 screen coord to the G4's p3 slot.
 * 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 — DO NOT read SXY0 here, that's the bug this name
 * prevents).
 */
 MipsAtomComp_(ac_gte_store_g4_p3_post_rtps) { gte_sw(C2_SXY2, R_PrimCursor, O_(Poly_G4,p3)) };
 #pragma endregion Macro Atom Components
 #pragma region Mips Atom Builder
-// This allows for runtime procedural authoring of mips atoms.
+// This helps with runtime procedural authoring of mips atoms.
 typedef Struct_(FMipsAtom512) { U4 data[512]; U4 used; };
@@ -241,123 +257,10 @@ FI_ void atombuilder_end(MipsAtomBuilder_R ab) {
 	mem_bump(ab->start, ab->capacity, & ab->used, S_(ac_yield));
 }
-#define mipsatom_from_builder(ab) (MipsAtom){ab.start, ab.used}
+#define mipsatom_from_builder(ab) (Slice_MipsCode){ab.start, ab.used}
 #pragma endregion Mips Atom Builder
 #pragma region Baked Mips Atoms
 // These atoms are resolved at compile time and are (usually) statically linked readonly data.
 enum {
 	bios_flushcache = 0x44,
 	bios_table_addr = 0xA0,
 };
 /* Flushes the Instruction Cache (PSX A-function 0x44 via BIOS stub at 0xA0).
 * Sequence (per MIPS ABI; arguments in arg registers, RA pushed to stack):
 *   1. sp -= 8;  sw $ra, 4($sp)        ; save RA
 *   2. $a0 = bios_flushcache (arg0)
 *   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
 */
 internal MipsAtom_(mips_flush_icache) {
 	add_ui(rstack_ptr, rstack_ptr, -MipsStackAlignment), // sp -= 8
 	store_word(rret_addr, rstack_ptr, S_(U4)),           // sw  $ra,   4($sp) 
 	add_ui(rret_0, rdiscard, bios_flushcache),           // addiu $a0, $0, 0x44 
 	add_ui(rtmp_0, rdiscard, bios_table_addr),           // addiu $t0, $0, 0xA0 
 	jump_link(rtmp_0, rret_addr),                        // jalr  $t0, $ra 
 	nop,                                                 // BD slot 
 	load_word(rret_addr, rstack_ptr, S_(U4)),            // lw   $ra, 4($sp) 
 	jump_reg(rret_addr),                                 // jr   $ra 
 	add_ui(rstack_ptr, rstack_ptr, MipsStackAlignment),  // sp += 8 (BD) 
 	mac_yield(),
 };
 typedef Struct_(Binds_SetGteWorld) {
 	M3_S2* transform;
 };
 internal MipsAtom_(set_gte_world) atom_info(
 		atom_bind(Binds_SetGteWorld)
 	,	atom_reads(R_TapePtr)
 ){
 	/* Pop matrix address from tape into R_T3 ($11) */
 	load_word(R_T3, R_TapePtr, O_(Binds_SetGteWorld,transform)),
 	add_ui_self(    R_TapePtr, S_(Binds_SetGteWorld)),
 	/* 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),
 	mac_yield()
 };
 /* DIAGNOSTIC 1: Pure tape loop test */
 internal MipsAtom_(diag_yield) { mac_yield() };
 // TODO(Ed): Reduce magic numbers/offsets
 /* DIAGNOSTIC 2: Pure memory test (No GTE). Draws a fixed cyan triangle. */
 internal MipsAtom_(diag_color) {
 	store_word(  R_0, R_T7, 0), 
 	load_upper_i(R_AT, gp0_cmd_poly_f3 << 8 | 0xFF), /* High: MipsCode Poly_F3(0x20) + Color B:FF */
 	or_i_self(   R_AT, 0xFF00),                      /* Low:  Color G:FF, R:00 (Cyan) */
 	store_word(  R_AT, R_T7, 4),
 	/* Fake coordinates - Swapped winding order to prevent GPU culling! */
 	load_upper_i(R_AT, 0x0010), or_i_self(R_AT, 0x0010), store_word(R_AT, R_T7, 8),  /* (16, 16) */
 	load_upper_i(R_AT, 0x0050), or_i_self(R_AT, 0x0010), store_word(R_AT, R_T7, 12), /* (80, 16) */
 	load_upper_i(R_AT, 0x0010), or_i_self(R_AT, 0x0050), store_word(R_AT, R_T7, 16), /* (16, 80) */
 	add_ui(          R_T1, R_0,  10),
 	shift_lleft_self(R_T1,       S_(U4)/2), 
 	add_u_self(      R_T1,       R_T6),         
 	load_word(   R_AT, R_T1, 0),        
 	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits),
 	store_word(  R_AT, R_T7, 0),       
 	shift_lleft(R_AT, R_T7, S_(PolyTag_len_bits)), shift_lright(R_AT, R_AT, S_(PolyTag_len_bits)),         
 	or_u_self(  R_AT, R_V0),          
 	store_word( R_AT, R_T1, 0),       
 	add_ui(R_T7, R_T7, 20),          
 	mac_yield()
 };
 // TODO(Ed): Reduce magic numbers/offsets
 /* DIAGNOSTIC 3: Pure GTE test (No Memory Writes) */
 internal MipsAtom_(diag_gte) {
 	/* Load 3 indices */
 	load_half_u(R_T0, R_T4, 0),
 	load_half_u(R_T1, R_T4, 2),
 	load_half_u(R_T2, R_T4, 4),
 	/* Load Vertices into GTE */
 	shift_lleft( R_AT, R_T0, 3), add_u(    R_AT, R_AT, R_T5),
 	load_word(R_V0, R_AT, 0), load_word(R_V1, R_AT, 4),
 	gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
 	shift_lleft( R_AT, R_T1, 3), add_u(R_AT, R_AT, R_T5),
 	load_word(R_V0, R_AT, 0), load_word(R_V1, R_AT, 4),
 	gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
 	shift_lleft(R_AT, R_T2, 3), add_u(R_AT, R_AT, R_T5),
 	load_word(R_V0, R_AT, 0), load_word(R_V1, R_AT, 4),
 	gte_mv_to_data_r(R_V0, C2_VXY2), gte_mv_to_data_r(R_V1, C2_VZ2),
 	/* Run Math */
 	nop2, gte_cmdw_rtpt,
 	nop2, gte_cmdw_nclip,
 	nop2,
 	/* Advance Face Cursor and Yield */
 	add_ui(R_T4, R_T4, 8),
 	mac_yield()
 };
 #pragma endregion Baked Mips Atoms
@@ -0,0 +1,29 @@
 #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_v2s2(U4 rs_x, U4 rs_y, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_load_v2s2, {
 	load_half( rs_x, r_base, O_(V3_S2,x)),
 	load_half( rs_y, r_base, O_(V3_S2,y)),
 })
 FI_ Slice_MipsCode ac_store_v2s2(U4 rt_x, U4 rt_y, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_v2s2, {
 	store_half(rt_x, base, offset + O_(V2_S2,x)),
 	store_half(rt_y, base, offset + O_(V2_S2,y)),
 })
 FI_ Slice_MipsCode ac_store_rects2(U4 rt_x, U4 rt_y, U4 rt_width, U4 rt_height, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_rects2, {
 	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)
@@ -11,6 +11,7 @@ enum {
 	v3s2_byteoff = 3, // log2(8), used with shift_left_logical op for index via byte offset.
 };
 typedef Array_(U1, 2);
 typedef Array_(U4, 2);
 typedef Array_(S2, 2);
 typedef Array_(S2, 3);
@@ -22,6 +23,7 @@ typedef S2 A3x3_S2[3][3];
 typedef Struct_(Extent2_S2) { S2 width; S2 height; };
 typedef Struct_(Extent2_S4) { S4 width; S4 height; };
 typedef Struct_(V2_U1)      { U1 x; U1 y; };
 typedef Struct_(V2_S2)      { S2 x; S2 y; };
 typedef Struct_(V2_S4)      { S4 x; S4 y; };
 typedef Struct_(V3_S2)      { S2 x; S2 y; S2 z; S2 pad; };
@@ -32,11 +34,12 @@ typedef Struct_(V4_S4)      { S4 x; S4 y; S4 z; S4 w; };
 typedef Struct_(R2_S2)      { V2_S2 p0; V2_S2 p1; };
 typedef Struct_(R2_S4)      { V2_S4 p0; V2_S4 p1; };
-typedef Struct_(Rect_S2) { S2 x; S2 y; S2 width; S2 height; };
+typedef Struct_(Rect_S2)    { S2 x; S2 y; S2 width; S2 height; };
-typedef Struct_(Rect_S4) { S4 x; S4 y; S4 width; S4 height; };
+typedef Struct_(Rect_S4)    { S4 x; S4 y; S4 width; S4 height; };
-typedef Struct_(M3_S2) { A3x3_S2 m; A3_S4 t; };
+typedef Struct_(M3_S2)      { A3x3_S2 m; A3_S4 t; };
 typedef Array_(V2_S2, 2);
 typedef Array_(V2_S2, 3);
 typedef Array_(V2_S2, 4);
@@ -58,10 +61,5 @@ FI_ void add_a3s4_fp(A3_S4_R out_a, A3_S4 b) {
 	(out_a[0])[2] += b[2] >> 1;
 }
-FI_ void add_v3s4(V3_S4_R out_a, V3_S4 b) { 
+FI_ void add_v3s4   (V3_S4_R out_a, V3_S4 b) {  add_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_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_fp(V3_S4_R out_a, V3_S4 b) { 
 	add_a3s4_fp(pcast(A3_S4_R, out_a), pcast(A3_S4, b)); 
 }
@@ -67,8 +67,8 @@ typedef Slice_(B1);
 #define slice_end(slice)   ((slice).ptr + (slice).len)
 #define S_slice(s)         ((s).len * S_((s).ptr[0]))
-#define slice_ut(ptr,len)  slice_ut_(u4_(ptr), u4_(len))
+#define slice_ut(ptr,len)  slice_ut_(u4_(ptr),     u4_(len))
-#define slice_ut_arr(a)    slice_ut_(u4_(a),   S_(a))
+#define slice_ut_arr(a)    slice_ut_(u4_(a),       S_(a))
 #define slice_to_ut(s)     slice_ut_(u4_((s).ptr), S_slice(s))
 #define slice_iter(container, iter)     (T_((container).ptr) iter = (container).ptr; iter != slice_end(container); ++ iter)
@@ -103,7 +103,7 @@ FI_ void farena_init(FArena_R arena, Slice mem) {  assert(arena != nullptr);
 	arena->used     = 0;
 }
 FI_ FArena farena_make(Slice mem) { FArena a; farena_init(& a, mem); return a; }
-I_ Slice   farena_push(FArena_R arena, U4 amount, Opt_farena o) {
+I_  Slice  farena_push(FArena_R arena, U4 amount, Opt_farena o) {
 	if (amount == 0) { return (Slice){}; }
 	U4 desired   = amount * (o.type_width == 0 ? 1 : o.type_width);
 	U4 to_commit = align_pow2(desired, o.alignment ?  o.alignment : MEM_ALIGNMENT_DEFAULT);
@@ -0,0 +1,38 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	include "gen/macs.h"
 #	include "gen/offsets.h"
 #	include "lottes_tape.h"
 #endif
 ATOM_FILE_DEBUGGER_LINE_MARKER(mips_atom_c);
 #pragma region Baked Atoms
 enum {
 	bios_flushcache = 0x44,
 	bios_table_addr = 0xA0,
 };
 /* Flushes the Instruction Cache (PSX A-function 0x44 via BIOS stub at 0xA0).
 * Sequence (per MIPS ABI; arguments in arg registers, RA pushed to stack):
 *   1. sp -= 8;  sw $ra, 4($sp)        ; save RA
 *   2. $a0 = bios_flushcache (arg0)
 *   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
 */
 internal MipsAtom_(mips_flush_icache) {
 	add_ui(rstack_ptr, rstack_ptr, -MipsStackAlignment), // sp -= 8
 	store_word(rret_addr, rstack_ptr, S_(U4)),           // sw  $ra,   4($sp) 
 	add_ui(rret_0, rdiscard, bios_flushcache),           // addiu $a0, $0, 0x44 
 	add_ui(rtmp_0, rdiscard, bios_table_addr),           // addiu $t0, $0, 0xA0 
 	jump_link(rtmp_0, rret_addr), nop,                   // jalr  $t0, $ra, BD slot
 	load_word(rret_addr, rstack_ptr, S_(U4)),            // lw   $ra, 4($sp) 
 	jump_reg(rret_addr),                                 // jr   $ra 
 	add_ui(rstack_ptr, rstack_ptr, MipsStackAlignment),  // sp += 8 (BD) 
 	mac_yield(),
 };
 #pragma endregion Baked Atoms
@@ -1,38 +1,28 @@
 /* ============================================================================
 *  duffle DSL Suffix Conventions
 *  ============================================================================
 *
 *  Every mnemonic in this header follows the same suffix grammar:
- *
+ *    _i: Immediate value (16-bit constant operand). 
- *    _i        Immediate value (16-bit constant operand). Combine with
+ *        Combine with _u or _s (single-letter modifier + type combined): add_ui, add_si.
- *              _u or _s (single-letter modifier + type combined): add_ui,
+ *        Examples: add_ui, add_si, and_i, or_i, xor_i, load_upper_i. and_i is sign-agnostic (andi zero-extends).
- *              add_si. Examples: add_ui, add_si, and_i, or_i, xor_i,
+ *        load_upper_i is a unique verb; _i is the immediate marker, not a modifier+type combination.
- *              load_upper_i. and_i is sign-agnostic (andi zero-extends).
+ *    _u: Unsigned (no-overflow, no-sign-extension).
- *              load_upper_i is a unique verb; _i is the immediate marker,
+ *        R-type arithmetic examples: add_u, sub_u, mult_u, div_u. I-type (combined with _i): add_ui.
- *              not a modifier+type combination.
+ *    _s: Signed (overflow-traps, sign-extends). 
- *
+ *        R-type: add_s, sub_s, mult_s, div_s, set_lt_s. I-type (combined with _i): add_si.
 *    _u        Unsigned (no-overflow, no-sign-extension). R-type
 *              arithmetic examples: add_u, sub_u, mult_u, div_u. I-type
 *              (combined with _i): add_ui.
 *
 *    _s        Signed (overflow-traps, sign-extends). R-type: add_s,
 *              sub_s, mult_s, div_s, set_lt_s. I-type (combined with _i):
 *              add_si.
 *
 *  --- Shift family (R-type): verb-modifier-direction ---
- *    The shift macros use `shift_<modifier><direction>`. Modifier is
+ *    The shift macros use `shift_<modifier><direction>`.
- *    the single letter `l` (logical) or `a` (arithmetic). Direction
+ *    Modifier is the single letter `l` (logical) or `a` (arithmetic).
- *    is the word `left` or `right`. Combined: `_lleft`, `_lright`,
+ *    Direction is the word `left` or `right`. Combined: `_lleft`, `_lright`, `_aright`.
- *    `_aright`. Examples: shift_lleft( rd, rt, shamt) (= sll)
+ *    Examples: shift_lleft( rd, rt, shamt) (= sll)
- *                         shift_lright(rd, rt, shamt) (= srl)
+ *              shift_lright(rd, rt, shamt) (= srl)
- *                         shift_aright(rd, rt, shamt) (= sra)
+ *              shift_aright(rd, rt, shamt) (= sra)
- *    (no `_aleft`; MIPS has no `sla` — arithmetic-left is bit-identical
+ *    (no `_aleft`; MIPS has no `sla` — arithmetic-left is bit-identical to logical-left, so use shift_lleft for that case)
 *    to logical-left, so use shift_lleft for that case)
 *
 *  --- Jump/Call family ---
- *    Simple jumps keep the original short names: jump (j), jump_reg
+ *    Simple jumps keep the original short names: jump (j), jump_reg (jr), jump_link (jalr rs, rd).
- *    (jr), jump_link (jalr rs, rd). The jump-and-link-to variants
+ *    The jump-and-link-to variants (jal, jalr rs with default $ra) get the `call_` verb instead:
 *    (jal, jalr rs with default $ra) get the `call_` verb instead:
 *    call_addr (jal), call_reg (jalr rs, default $ra).
 *    Examples: jump(off)         (= j)
 *              jump_reg(rs)      (= jr)
@@ -40,32 +30,22 @@
 *              call_reg(rs)      (= jalr rs, default $ra)
 *              call_addr(off)    (= jal)
 *
- *    _r        Register marker — used only when the register type needs
+ *    _r: Register marker — used only when the register type needs disambiguation (e.g., GTE data register vs control register).
- *              disambiguation (e.g., GTE data register vs control
+ *        NOT used in plain R-type arithmetic (the R-type is implicit). Examples: gte_mv_to_data_r, gte_mv_to_ctrl_r.
- *              register). NOT used in plain R-type arithmetic (the
+ *    _self:     Destination equals one source operand.
- *              R-type is implicit). Examples: gte_mv_to_data_r,
+ *               Examples: add_ui_self (I-type, to self), add_u_self (R-type, to self).
- *              gte_mv_to_ctrl_r.
+ *    _mv_to_:   Direction: data flows into X.
 *               Example: gte_mv_to_data_r, gte_mv_to_ctrl_r.
 *    _mv_from_: Direction: data flows out of X.
 *               Example: gte_mv_from_data_r, gte_mv_from_ctrl_r.
 *    _str:      String-form — emits inline-asm string instead of `.word`.
 *               Example: gte_rtpt_asm_str.
 *    _2w / _1w: Word count of the emitted sequence.
 *               Example: load_imm_2w.
 *
- *    _self     Destination equals one source operand.
+ *    _cop2: RESERVED — DO NOT USE in macro names. The `gte_` namespace prefix already implies coprocessor 2. Use `c2` only in:
- *              Examples: add_ui_self (I-type, to self),
+ *      (a) integer opcode enums (op_lwc2 = 0x32, op_swc2 = 0x3A)
- *                        add_u_self (R-type, to self).
+ *      (b) vendor-mnemonic macro aliases (gte_mtc2, gte_mfc2)
 *
 *    _mv_to_   Direction: data flows into X.
 *              Example: gte_mv_to_data_r, gte_mv_to_ctrl_r.
 *
 *    _mv_from_ Direction: data flows out of X.
 *              Example: gte_mv_from_data_r, gte_mv_from_ctrl_r.
 *
 *    _str      String-form — emits inline-asm string instead of `.word`.
 *              Example: gte_rtpt_asm_str.
 *
 *    _2w / _1w Word count of the emitted sequence.
 *              Example: load_imm_2w.
 *
 *    _cop2     RESERVED — DO NOT USE in macro names. The `gte_` namespace
 *              prefix already implies coprocessor 2. Use `c2` only in:
 *                (a) integer opcode enums (op_lwc2 = 0x32, op_swc2 = 0x3A)
 *                (b) vendor-mnemonic macro aliases (gte_mtc2, gte_mfc2)
 *
 *  Primitive commands: gp0_cmd_poly_f3 = 0x20 (byte opcode)
 *  Packed 32-bit cmd:  gp0_word_poly_f3(r, g, b) (32-bit, shifted)
@@ -80,9 +60,8 @@
 *            gte_lw_v0_xy(base) (gte + lw + v0 + xy)
 *            load_upper_i       (load-upper + immediate, unique verb)
 *
- *  Vendor mnemonics (sll, srl, sra, jr, j, jal, jalr) are NOT in this
+ *  Vendor mnemonics (sll, srl, sra, jr, j, jal, jalr) are NOT in this header.
- *  header. They live in the opt-in `mips_vendor_sym.h` for users who
+ *  They live in the opt-in `mips_vendor_sym.h` for users who prefer the textbook MIPS assembly mnemonics.
 *  prefer the textbook MIPS assembly mnemonics.
 * ============================================================================ */
 #ifdef INTELLISENSE_DIRECTIVES
@@ -98,19 +77,17 @@ enum {
 /* ============================================================================
 *  REGISTER INTEGER IDS (preprocessor-visible)
 * ============================================================================
- *  Every R_* enum below has a parallel R_*_Code `#define` so that the
+ *  Every R_* enum below has a parallel R_*_Code `#define` so that the preprocessor can stringify the integer
- *  preprocessor can stringify the integer (e.g. for asm clobber lists and
+ *  (e.g. for asm clobber lists and register-variable declarations via `rgcc(R_X)`).
- *  register-variable declarations via `rgcc(R_X)`). The enum value is
+ *  The enum value is bound to the `#define` so the two forms cannot drift apart.
 *  bound to the `#define` so the two forms cannot drift apart.
 *
- *  Only registers that get stringified need a `_Code` form; the rest are
+ *  Only registers that get stringified need a `_Code` form; the rest are plain enum values.
- *  plain enum values. If you need to add a new one, follow the pattern:
+ *  If you need to add a new one, follow the pattern:
 *      #define R_T7_Code 15
- *      R_T7 = R_T7_Code,        // in the enum
+ *      R_T7 = R_T7_Code,     // in the enum
 *
- *  User code should always reference the enum form (`R_T4`) at arithmetic
+ *  User code should always reference the enum form (`R_T4`) at arithmetic sites and let
- *  sites and let `rlit(R_T4_Code)` / `rgcc(R_T4)` handle the stringify
+ *  `rlit(R_T4_Code)` / `rgcc(R_T4)` handle the stringify cases — never write the bare number `12`.
 *  cases — never write the bare number `12`.
 * ============================================================================ */
 #define R_0_Code    0
 #define R_AT_Code   1
@@ -225,7 +202,6 @@ enum {
 	/* 2F: N/A */
 	// , op_lwc0
 	// , op_load_addr  = op_la
 	// , op_load_imm   = op_li
 	, op_jump       = op_j
@@ -327,15 +303,15 @@ enum { _BitOffsets = 0
 * Argument order matches the MIPS assembly syntax:
 *   dest-first, then source operands, then immediate last.
 *
- *   load_word(rt, base, off)   → lw   rt, off(base)
+ *   load_word(rt, base, off)    → lw   rt, off(base)
- *   store_word(rt, base, off)  → sw   rt, off(base)
+ *   store_word(rt, base, off)   → sw   rt, off(base)
- *   add_ui(rt, rs, imm)        → addiu rt, rs, imm
+ *   add_ui(rt, rs, imm)         → addiu rt, rs, imm
- *   shift_lleft(rd, rt, shamt)   → sll   rd, rt, shamt
+ *   shift_lleft(rd, rt, shamt)  → sll   rd, rt, shamt
- *   shift_lright(rd, rt, shamt)  → srl   rd, rt, shamt
+ *   shift_lright(rd, rt, shamt) → srl   rd, rt, shamt
- *   shift_aright(rd, rt, shamt)  → sra   rd, rt, shamt
+ *   shift_aright(rd, rt, shamt) → sra   rd, rt, shamt
- *   jump_reg(rs)               → jr    rs
+ *   jump_reg(rs)                → jr    rs
- *   jump_link(rs, rd)          → jalr  rs        (link in rd, default $ra)
+ *   jump_link(rs, rd)           → jalr  rs        (link in rd, default $ra)
- *   nop                        → sll   $0, $0, 0
+ *   nop                         → sll   $0, $0, 0
 */
 #define load_word(rt, base, off)   enc_i(op_lw,    (base), (rt), (off))
 #define load_byte(rt, base, off)   enc_i(op_lb,    (base), (rt), (off))
@@ -360,10 +336,10 @@ enum { _BitOffsets = 0
 /* Logic Opcodes */
-#define and_u(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_and)
+#define and_u(rd, rs, rt)        enc_r(op_special, (rs), (rt), (rd), 0, fc_and)
-#define or_u(rd, rs, rt)           enc_r(op_special, (rs), (rt), (rd), 0, fc_or)
+#define or_u(rd, rs, rt)         enc_r(op_special, (rs), (rt), (rd), 0, fc_or)
-#define xor_u(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_xor)
+#define xor_u(rd, rs, rt)        enc_r(op_special, (rs), (rt), (rd), 0, fc_xor)
-#define nor_u(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_nor)
+#define nor_u(rd, rs, rt)        enc_r(op_special, (rs), (rt), (rd), 0, fc_nor)
 #define or_u_self(rd_rs, rt)       enc_r(op_special, (rd_rs), (rt), (rd_rs), 0, fc_or)
@@ -386,10 +362,28 @@ enum { _BitOffsets = 0
 /* call_reg rs — jump-and-link to register-held address; link in $ra. */
 #define call_reg(rs)               jump_link((rs), R_RA)
-/* j target — absolute jump within the current 256MB region. */
+/* j target — absolute jump within the current 256MB region.
 * WARNING: `jump(off)` CANNOT BE USED for within-atom jumps in the current pipeline.
 * The MIPS j opcode encodes `(target_addr >> 2)` in its 26-bit immediate field; an  ABSOLUTE byte address, not a relative word offset.
 * The metaprogram computes `off` as a relative word offset (`target_word_idx - branch_word_idx - 1`), which the assembler/linker does NOT resolve.
 *
 * `jump(off)` is only safe when the BUILD PIPELINE owns the absolute position of the emitted code — i.e. when: s
 *   - the build emits a symbol-relative `.word` expression that the linker resolvess via `R_MIPS_26`, OR
 *   - the code is hand-assembled with explicit absolute targets, OR a custom post-build patcher resolves the 26-bit field.
 */
 #define jump(off)                  enc_i(op_j,     R_0, R_0, (off))
-/* call_addr off — jump-and-link to immediate address. */
+/* 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))
 /* call_addr off — jump-and-link to immediate address.
 *
 * Same WARNING as `jump(off)` above: the jal opcode also encodes an absolute 26-bit target.
 * For within-atom calls, the current pipeline has no equivalent always-taken call-and-link idiom.
 * Workaround: `branch_link` (always-taken branch + explicit `la $ra, next_word_addr; jr $ra`), or just use `call_reg($tmp)` after loading the target into a register.
 */
 #define call_addr(off)             enc_i(op_jal,   R_0, R_0, (off))
 /* --- Store family (mirrors the load family) --- */
@@ -404,12 +398,9 @@ enum { _BitOffsets = 0
 * mult_s / mult_u → mult / multu   (writes HI/LO; result in LO)
 * div_s / div_u   → div / divu     (LO = quot, HI = rem)
 *
- * NOTE: dsl.h defines `add_s`/`sub_s`/`mut_s`/`gt_s`/etc. as
+ * NOTE: dsl.h defines `add_s`/`sub_s`/`mut_s`/`gt_s`/etc. as _Generic-based signed integer-arithmetic helpers for U1/U2/U4.
- * _Generic-based signed integer-arithmetic helpers for U1/U2/U4. Those
+ * Those live in a different conceptual layer (generic arithmetic on DSL types) and would collide with the instruction encoders here.
- * live in a different conceptual layer (generic arithmetic on DSL
+ * The `#undef` below lets the gas-style names below win; if a file needs both, the dsl.h versions can be reached via their long forms
 * types) and would collide with the instruction encoders here. The
 * `#undef` below lets the gas-style names below win; if a file needs
 * both, the dsl.h versions can be reached via their long forms
 * (e.g. `def_signed_op`-style or the underlying `add_s1/s2/s4`). */
 #undef add_s
 #undef sub_s
@@ -441,7 +432,7 @@ enum { _BitOffsets = 0
 #define mov_to_low(rs)             enc_r(op_special, (rs), R_0, R_0, 0, fc_mtlo)
 /* --- Atomic branches (no pseudos like bgt/bge; compose with slt_* + branch_ne) ---
- * branch_equal  rs, rt, off → beq   rs, rt, off
+ * branch_equal   rs, rt, off → beq   rs, rt, off
 * branch_ne      rs, rt, off → bne   rs, rt, off
 * branch_lt_zero rs, off     → bltz  rs, off
 * branch_gt_zero rs, off     → bgtz  rs, off
@@ -463,7 +454,7 @@ enum { _BitOffsets = 0
 /* --- Shift-amount alias (matches the gas convention `\p3 = shamt`) --- */
 #define shift_amount(rd, rt, n)     shift_lleft(rd, rt, n)
-/* nop — canonical sll $0, $0, 0 */
+/* nop — sll $0, $0, 0 */
 #define nop  shift_lleft(rdiscard, rdiscard, 0)
 #define nop2 nop, nop
@@ -471,23 +462,16 @@ enum { _BitOffsets = 0
 #define load_imm_1w_s0(rt, imm) add_si((rt)), R_0, (imm))
 /* load_imm_2w — unconditional 2-word `li` form: `lui` + (ori | addi).
- *
+ * Granular companion to `load_imm`: skips the compile-time range checks and always emits 2 .words. Use this when:
 * Granular companion to `load_imm`: skips the compile-time range checks
 * and always emits 2 .words. Use this when:
 *   - you know `imm` is > 0xFFFF (otherwise you're wasting a word), OR
- *   - `imm` is not a compile-time constant and you want predictable
+ *   - `imm` is not a compile-time constant and you want predictable 2-word emission without the `__builtin_constant_p` branches.
 *     2-word emission without the `__builtin_constant_p` branches.
 *
 * The lo16 strategy is still chosen at expansion time on the lo half:
- *   lo16 in 0x0000..0x7FFF  →  addi (sign-ext is harmless, the lui
+ *   lo16 in 0x0000..0x7FFF  →  addi (sign-ext is harmless, the lui already cleared bits 15..0)
- *                              already cleared bits 15..0)
+ *   lo16 in 0x8000..0xFFFF  →  ori  (zero-extends to preserve the intended bit pattern)
 *   lo16 in 0x8000..0xFFFF  →  ori  (zero-extends to preserve the
 *                              intended bit pattern)
 *
- * For situations where you need to bypass even this choice (e.g. to
+ * For situations where you need to bypass even this choice (e.g. to force a specific encoding for a known discontiguous high/low pair),
 * force a specific encoding for a known discontiguous high/low pair),
 * see `load_imm_2w_ori_forced` and `load_imm_2w_addi_forced` below.
 *
 * Statement-level (not expression-level): emits its own `asm volatile(...)`.
 */
 #define load_imm_2w(rt, imm) do {                         \
@@ -518,9 +502,8 @@ enum { _BitOffsets = 0
 } while (0)
 /* load_imm_2w_addi_forced — force the `lui` + `addi` form regardless of lo16 sign.
- * Use when you know sign-extension is fine (e.g. lo16 is treated as
+ * Use when you know sign-extension is fine (e.g. lo16 is treated as signed downstream) 
- * signed downstream) and you want a smaller effective instruction
+ * and you want a smaller effective instruction (the assembler/MIPS hardware will sign-extend the imm16). */
 * (the assembler/MIPS hardware will sign-extend the imm16). */
 #define load_imm_2w_addi_forced(rt, imm) do {   \
 	/*U4 _li2a_imm_ = (U4)(imm);*/                \
 	asm volatile(asm_words(                       \
@@ -532,23 +515,17 @@ enum { _BitOffsets = 0
 /* load_imm rt, imm — true `li` semantics (assembler `li` pseudo)
 *
- * Dispatches at compile time on the immediate's range, picking the
+ * Dispatches at compile time on the immediate's range, picking the smallest single-instruction form when possible:
- * smallest single-instruction form when possible:
+ *   imm in 0       .. 0x7FFF     →  addi  rt, $0, imm   (1 word)
- *
+ *   imm in 0x8000  .. 0xFFFF     →  ori   rt, $0, imm   (1 word; sign-bit must be zeroed)
- *   imm in   0 ..  0x7FFF  →  addi  rt, $0, imm   (1 word)
+ *   imm in 0x10000 .. 0xFFFFFFFF →  lui + (ori | addi)  (2 words)
 *   imm in 0x8000 .. 0xFFFF →  ori   rt, $0, imm   (1 word; sign-bit must be zeroed)
 *   imm in  0x10000 ..  0xFFFFFFFF  →  lui + (ori | addi)  (2 words)
 *
 * Statement-level (not expression-level): the macro emits its own
 * `asm volatile(...)` block with 1 or 2 .word constants. Callers can
 * group multiple `load_imm` calls in a single volatile by using the
 * lower-level encoders directly:
 *
 * Statement-level (not expression-level): the macro emits its own `asm volatile(...)` block with 1 or 2 .word constants.
 * Callers can group multiple `load_imm` calls in a single volatile by using the lower-level encoders directly:
 *      load_imm(R_T4, 0x12345678);          // emits 2 .words
 *
- * Falls back to a 2-word form if `imm` is not a compile-time constant,
+ * Falls back to a 2-word form if `imm` is not a compile-time constant, but that path is unusual
- * but that path is unusual (load_imm is most useful with literal
+ * (load_imm is most useful with literal addresses and magic numbers). */
 * addresses and magic numbers). */
 #define load_imm(rt, imm) do {                                     \
 	if (cexpr_(imm) && ((imm) <= 0x7FFFU)) {                         \
 		/* Small positive: addi rt, $0, imm */                         \
@@ -588,9 +565,8 @@ enum { _BitOffsets = 0
 /* Standard clobber list for pure-MIPS asm volatile blocks: caller-saved
- * GPRs that the kernel treats as volatile (v0/v1/t0/t1/ra) plus the
+ * GPRs that the kernel treats as volatile (v0/v1/t0/t1/ra) plus the "memory" barrier.
- * "memory" barrier. The register ids are passed through `rlit` so
+ * The register ids are passed through `rlit` so the R_*_Code `#define`s are stringified into "$N" at expansion time. */
 * the R_*_Code `#define`s are stringified into "$N" at expansion time. */
 #define clbr_volatile_gprs rlit(R_V0), rlit(R_T0), rlit(R_T1), rlit(R_RA), clb_mem_drain
 #define asm_mips_flush_icache() asm volatile( asm_words( \
@@ -2,9 +2,8 @@
 *  duffle DSL — MIPS Vendor Mnemonics (opt-in)
 *  ============================================================================
 *
- *  Provides the textbook MIPS assembly mnemonics as thin aliases to the
+ *  Provides the textbook MIPS assembly mnemonics as thin aliases to the duffle macros in mips.h.
- *  canonical duffle macros in mips.h. The duffle names are primary; this
+ *  The duffle names are primary; this header is for users who prefer the textbook mnemonics.
 *  header is for users who prefer the textbook mnemonics.
 *
 *  USAGE:   #include "duffle/mips_vendor_sym.h"   // after mips.h
 *
@@ -0,0 +1,184 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #		include "gen/macs.h"
 #		include "gen/offsets.h"
 #	include "mips.h"
 #	include "dsl.atom.h"
 #	include "lottes_tape.h"
 #	include "pad.h"
 #endif
 ATOM_FILE_DEBUGGER_LINE_MARKER(pad_atom_c);
 #pragma region Baked Atoms
 /* ----- pad_bios_snapshot -----
 * Per-frame snapshot of one BIOS pad buffer into PadState.
 * Decoder (branch ladder on raw[0] status + raw[1] id):
 *   1. raw[0] == 0xFF         -> Disconnected (buttons=0, axes=0x80)
 *   2. raw[0]==0 && raw[1]==0 -> Pending      (buttons=0, axes=0x80)
 *   3. raw[1] == 0x41         -> Digital      (buttons normalized; axes=0x80)
 *   4. raw[1] == 0x53         -> AnalogStick  (buttons normalized; axes from raw[4..7])
 *   5. raw[1] in 0x7x         -> AnalogPad    (buttons normalized; axes from raw[4..7])
 *   6. else                   -> Unsupported  (buttons=0, axes=0x80)
 *
 * Buttons normalization: byte_swap16((~raw_buttons) & 0xFFFF).
 *   raw_buttons    = load_half_u(raw, 2) = raw[2] | (raw[3] << 8).
 *   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)
 */
 enum {
 	R_PadRaw    = R_T0 atom_reg atom_type(U1),
 	R_PadState  = R_T1 atom_reg,
 	R_RawStatus = R_T2 atom_reg,
 	R_RawId     = R_T3 atom_reg,
 };
 typedef Struct_(Binds_PadBiosSnapshot) {
    PadBiosRaw* raw;
    PadState*   state;
 };
 internal MipsAtom_(pad_bios_snapshot) atom_info(atom_bind(Binds_PadBiosSnapshot)
 , atom_reads( R_PadRaw, R_PadState, R_RawStatus, R_RawId, R_T4, R_T5, R_TapePtr)
 , atom_writes(R_PadRaw, R_PadState, R_RawStatus, R_RawId, R_T4, R_T5, R_TapePtr)
 ) {
 	/* === Bind consumption: T0 = raw, T1 = state, advance R_TapePtr by 8. */
 	load_word(R_PadRaw,   R_TapePtr, O_(Binds_PadBiosSnapshot,raw)),
 	load_word(R_PadState, R_TapePtr, O_(Binds_PadBiosSnapshot,state)),
 	add_ui_self(          R_TapePtr, S_(Binds_PadBiosSnapshot)),
 	/* === Read raw[0] (status) + raw[1] (id) */
 	load_byte_u(R_RawStatus, R_PadRaw, 0),
 	load_byte_u(R_RawId,     R_PadRaw, 1),
 atom_label(snap_root) /* === Case 1: Disconnected (status == 0xFF). */
 	add_ui(R_T4, R_0, 0xFF), branch_ne(R_RawStatus, R_T4, atom_offset(snap_root, skip_disconnected)),
 	/* BD-slot: pre-compute PadStatus_Disconnected. Branch reads R_T4=0xFF in EX before this WB completes.
 	 * If branch NOT taken (fall through to pending/id_dispatch), R_T4 is overwritten by the next case body's add_ui — harmless. */
 atom_label(disconnected) /* === Disconnected body. */
 	/* R_T4 = PadStatus_Disconnected from snap_root BD-slot. */
 	store_word(R_T4, R_PadState, O_(PadState,status)),
 	store_half(R_0,  R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	load_upper_i(R_T4, 0x8080), or_i_self(R_T4, 0x8080),
 	store_word(  R_T4,    R_PadState, O_(PadState,left_x)),
 	store_byte(  R_RawId, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(disconnected, snap_end)),
 		/* BD-slot: load next atom's entry point (replaces the nop).
 		 * The unconditional branch always jumps to snap_end, where mac_yield_tail()
 		 * transfers control to R_AtomJmp without re-loading it. */
 		mac_yield_load(),
 atom_label(skip_disconnected)
 	/* === Case 2: Pending (status == 0 && id == 0)
 	 * Combined check: if (status | id) != 0 then skip to id_dispatch.
 	 * Falls through to the Pending case only when both are zero. */
 	or_u_self(R_RawStatus, R_RawId), branch_ne(R_RawStatus, R_0, atom_offset(case_2, id_dispatch)),
 	/* BD-slot: pre-compute PadStatus_Pending. Branch reads R_RawStatus in EX before this WB completes.
 	 * If branch NOT taken (fall through to id_dispatch), R_T4 is overwritten by the digital/analog body add_ui — harmless. */
 atom_label(pending) /* === Pending body */
 	/* R_T4 = PadStatus_Pending from case_2 BD-slot. */
 	store_word(R_T4, R_PadState, O_(PadState,status)),
 	store_half(R_0,  R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	load_upper_i(R_T4, 0x8080), or_i_self(R_T4, 0x8080),
 	store_word(  R_T4,    R_PadState, O_(PadState,left_x)),
 	store_byte(  R_RawId, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(pending, snap_end)),
 		mac_yield_load(),
 atom_label(id_dispatch) /* === Case 3-6: ID dispatch */
 	add_ui(R_T4, R_0, 0x41), branch_ne(R_RawId, R_T4, atom_offset(id_dispatch, try_analog_stick)),
 	/* BD-slot: pre-compute PadStatus_Digital. Branch reads R_RawId in EX before this WB completes.
 	 * If branch NOT taken (fall through to try_analog_stick), R_T4 is overwritten by the analog body add_ui. */
 	/* === Digital body (status, buttons normalize, axes=0x80, id, branch. */
 	/* R_T4 = PadStatus_Digital from id_dispatch BD-slot. */
 	store_word( R_T4, R_PadState, O_(PadState,status)),
 	load_half_u(R_T4, R_PadRaw,   2 * S_(U1)),
 	/* Fill R_T4's load-delay slot with the 0x80808080 axes constant into R_T5
 	 * (R_T5 is dead on this path; it's only consumed at the analog_pad range check). */
 	load_upper_i(R_T5, 0x8080), or_i_self(R_T5, 0x8080),
 	nor_u(      R_T4, R_T4, R_0), /* raw_buttons is already in host bit order; no swap needed */
 	store_half( R_T4, R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	store_word(  R_T5, R_PadState, O_(PadState,left_x)),
 	add_ui(      R_T4, R_0, 0x41),
 	store_byte(  R_T4, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(id_dispatch, snap_end)),
 		mac_yield_load(),
 atom_label(try_analog_stick) /* === Case 4: AnalogStick (id == 0x53)*/
 	add_ui(R_T4, R_0, 0x53), branch_ne(R_RawId, R_T4, atom_offset(try_analog_stick, try_analog_pad)),
 	/* BD-slot: pre-compute PadStatus_AnalogStick. Branch reads R_RawId in EX before this WB completes.
 	 * If branch NOT taken (fall through to try_analog_pad), R_T4 is overwritten by the analog_pad body add_ui. */
 atom_label(analog_stick) /* === AnalogStick body
 	* Axes are loaded as two halfwords: raw[6..7] → left_xy (sh at offset 8), raw[4..5] → right_xy (sh at offset 10).
 	* R_T5 holds left_xy / id-value in turn (it's dead on this path — only consumed at the analog_pad range check). */
 	/* R_T4 = PadStatus_AnalogStick from try_analog_stick BD-slot. */
 	store_word(  R_T4, R_PadState, O_(PadState,status)),
 	load_half_u( R_T4, R_PadRaw,   2 * S_(U1)),           /* R_T4 = raw_buttons */
 	load_half_u( R_T5, R_PadRaw,   6 * S_(U1)),           /* R_T5 = left_xy; fills R_T4's load-delay slot (doesn't read R_T4) */
 	nor_u(       R_T4, R_T4, R_0),                        /* R_T4 = ~raw_buttons */
 	store_half(  R_T4, R_PadState, O_(PadState,buttons)),
 	load_half_u( R_T4, R_PadRaw,   4 * S_(U1)),           /* R_T4 = right_xy; fills R_T5's load-delay slot */
 	store_half(  R_T5, R_PadState, O_(PadState,left_x)),  /* R_T5 settled, store left_xy */
 	store_half(  R_T4, R_PadState, O_(PadState,right_x)),
 	add_ui(      R_T5, R_0, 0x53),                        /* R_T5 = id value (clobbers left_xy, already stored) */
 	store_byte(  R_T5, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(analog_stick, snap_end)),
 		mac_yield_load(),
 atom_label(try_analog_pad) /* === Case 5-6: AnalogPad (id & 0xF0 == 0x70) */
 	and_i(    R_T4, R_RawId, 0xF0),
 	add_ui(   R_T5, R_0,     0x70),
 	branch_ne(R_T4, R_T5, atom_offset(try_analog_pad, try_unsupported)),
 	/* BD-slot: pre-compute PadStatus_AnalogPad. Branch reads R_T4 in EX before this WB completes.
 	 * If branch NOT taken (fall through to try_unsupported), R_T4 is overwritten by the unsupported body add_ui. */
 atom_label(analog_pad) /* === AnalogPad body
 	* Same shape as AnalogStick with AnalogPad status. R_T5 holds left_xy (it's dead on this path). */
 	/* R_T4 = PadStatus_AnalogPad from try_analog_pad BD-slot. */
 	store_word( R_T4, R_PadState, O_(PadState,status)),
 	load_half_u(R_T4, R_PadRaw,   2 * S_(U1)),           /* R_T4 = raw_buttons */
 	load_half_u(R_T5, R_PadRaw,   6 * S_(U1)),           /* R_T5 = left_xy; fills R_T4's load-delay slot */
 	nor_u(      R_T4, R_T4, R_0),                        /* R_T4 = ~raw_buttons */
 	store_half( R_T4, R_PadState, O_(PadState,buttons)),
 	load_half_u(R_T4, R_PadRaw,   4 * S_(U1)),           /* R_T4 = right_xy; fills R_T5's load-delay slot */
 	store_half( R_T5, R_PadState, O_(PadState,left_x)),  /* R_T5 settled, store left_xy */
 	store_half( R_T4, R_PadState, O_(PadState,right_x)),
 	store_byte( R_RawId, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(analog_pad, snap_end)),
 		mac_yield_load(),
 atom_label(try_unsupported) /* === Case 7: Unsupported — fall through from the AnalogPad range-check miss. */
 	add_ui(    R_T4, R_0, PadStatus_Unsupported),
 	store_word(R_T4, R_PadState, O_(PadState,status)),
 	store_half(R_0,  R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	load_upper_i(R_T4, 0x8080), or_i_self(R_T4, 0x8080),
 	store_word(  R_T4, R_PadState, O_(PadState,left_x)),
 	add_ui(      R_T4, R_0, 0xFF),                      /* 0xFF sentinel: "unknown id" */
 	store_byte(  R_T4, R_PadState, O_(PadState,id)),
 	/* Fall through to snap_end. */
 atom_label(no_jump_fallthrough)
 	mac_yield_load(),
 atom_label(snap_end)
 	/* NOT mac_yield() — R_AtomJmp was already loaded in the BD-slot of the case-exit branch. */
 	mac_yield_tail(),
 };
 #pragma endregion Baked Atoms
@@ -0,0 +1,73 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #	include "dsl.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; the active-low-to-active-high inversion is applied bit-by-bit. */
 enum {
 	Bit_(Pad_Select,  0),
 	Bit_(Pad_L3,      1),
 	Bit_(Pad_R3,      2),
 	Bit_(Pad_Start,   3),
 	Bit_(Pad_Up,      4),
 	Bit_(Pad_Right,   5),
 	Bit_(Pad_Down,    6),
 	Bit_(Pad_Left,    7),
 	Bit_(Pad_L2,      8),
 	Bit_(Pad_R2,      9),
 	Bit_(Pad_L1,     10),
 	Bit_(Pad_R1,     11),
 	Bit_(Pad_Triangle, 12),
 	Bit_(Pad_Circle,  13),
 	Bit_(Pad_Cross,   14),
 	Bit_(Pad_Square,  15),
 };
 enum {
 	PadId_Offset = 4,
 	Pad0 = 0 << PadId_Offset,
 	Pad1 = 1 << PadId_Offset,
 };
 #define pad0_(btn_id) (btn_id << Pad0)
 #define pad1_(btn_id) (btn_id << Pad1)
 /* ============================================================
 * BIOS pad-buffer subsystem: docs/psx-spx/docs/kernelbios.md (B(12h) + B(13h))
 * ============================================================ */
 enum {
 	PAD_BIOS_RAW_SIZE = 0x22,
 };
 typedef Struct_(PadBiosRaw) {
 	U1 bytes[PAD_BIOS_RAW_SIZE];
 };
 typedef Enum_(U4, PadStatus) {
 	PadStatus_Disconnected,
 	PadStatus_Digital,
 	PadStatus_AnalogStick,
 	PadStatus_AnalogPad,
 	PadStatus_Unsupported,
 	PadStatus_Pending,
 	PadStatus_Invalid,
 };
 /* PadState — per-port normalized runtime state.
 * Field order is chosen so that the 4 axes (left_x, left_y, right_x, right_y)
 * form a contiguous 4-byte block at offset 8, allowing a single `store_word` to clear-or-write all 4 axes in one MIPS instruction.
 * The struct size stays 12 bytes (unchanged from the prior order,
 * which left the C compiler to insert 1 byte of trailing pad to reach the 4-byte struct alignment). */
 typedef Struct_(PadState) {
 	PadStatus status;  /* offset 0,  size 4 (U4) */
 	U2        buttons; /* offset 4,  size 2 */
 	U1        id;      /* offset 6,  size 1 */
 	U1        pad;     /* offset 7,  size 1 — explicit pad to align the axes block */
 	U1        left_x;  /* offset 8,  size 1 — store_word target (4-byte aligned) */
 	U1        left_y;  /* offset 9,  size 1 */
 	U1        right_x; /* offset 10, size 1 */
 	U1        right_y; /* offset 11, size 1 */
 };
@@ -0,0 +1,7 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	include "gen/macs.h"
 #	include "gen/offsets.h"
 #	include "psyq.h"
 #endif
 ATOM_FILE_DEBUGGER_LINE_MARKER(pysq_atom_c);
@@ -0,0 +1,103 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #	include "dsl.h"
 #	include "math.h"
 #	include "gp.h"
 #endif
 typedef Struct_(DrawEnv_Packed) { U4 tag; U4 code[15]; };
 typedef Struct_(DrawEnv) {
 	Rect_S2 clip_area;
 	V2_S2   drawing_offset[2];
 	Rect_S2 texture_window;
 	S2      texture_page;
 	B1      flag_dither;
 	B1      flag_draw_on_display;
 	B1      enable_auto_clear;
 	RGB8    initial_bg_color;
 	DrawEnv_Packed dr_env; // reserved
 };
 typedef Struct_(DisplayEnv) {
 	Rect_S2 display_area;
 	Rect_S2 screen;
 	B1      vinterlace;
 	B1      color24;
 	B1      pad0;
 	B1      pad1;
 };
 typedef Array_(DrawEnv,    2);
 typedef Array_(DisplayEnv, 2);
 typedef Struct_(DoubleBuffer) {
 	A2_DrawEnv    draw;
 	A2_DisplayEnv display;
 };
 DisplayEnv* displayenv_init(DisplayEnv* env, S4 x, S4 y, S4 w, S4 h) asm("SetDefDispEnv");
 DrawEnv*    drawenv_init   (DrawEnv*    env, S4 x, S4 y, S4 w, S4 h) asm("SetDefDrawEnv");
 DisplayEnv* displayenv_put(DisplayEnv* env) asm("PutDispEnv");
 DrawEnv*    drawenv_put   (DrawEnv*    env) asm("PutDrawEnv");
 U4   geom_init(void)             asm("InitGeom");
 void geom_set_offset(U4 x, U4 y) asm("SetGeomOffset");
 void geom_set_screen(U4 h)       asm("SetGeomScreen");
 U4* orderingtbl_clear_reverse(U4* ot, U4 len) asm("ClearOTagR");
 U4 reset_graph(U4 mode)           asm("ResetGraph");
 void set_display_enabled(U4 mask) asm("SetDispMask");
 U4 draw_sync(U4 mode) asm("DrawSync");
 U4 vsync(U4 mode)     asm("VSync");
 void draw_orderingtbl(U4* buf) asm("DrawOTag");
 typedef Struct_(Tile) {
 	U4      tag;
 	RGB8    color;
 	B1      code;
 	Rect_S2 rect;
 };
 /*
 	Linear Algebra
 */
 M3_S2* m3s2_rotation   (V3_S2* vec, M3_S2* mat) asm("RotMatrix");
 M3_S2* m3s2_translation(M3_S2* mat, V3_S4* vec) asm("TransMatrix");
 M3_S2* m3s2_scale      (M3_S2* mat, V3_S4* vec) asm("ScaleMatrix");
 // Rotation, Translation, Perspective
 S4 rtp_v3s2_raw(V3_S2* vec, S4* xy, S4* pp, S4* flag) asm("RotTransPers");
 FI_ S4 rtp_v3s2(V3_S2* vec, V2_S2* xy, A2_S2* pp, S4* flag) { return rtp_v3s2_raw(vec, C_(S4*R_, & xy->x), C_(S4*R_, pp), r_(flag)); }
 S4 rtp_avg_nclip_a3_v3s2_raw(V3_S2* v0, V3_S2* v1, V3_S2* v2, S4* xy1, S4* xy2, S4* xy3, S4* pp, S4* otz, S4* flag) asm("RotAverageNclip3");
 FI_  S4 rtp_avg_nclip_a3_v3s2(
 	V3_S2* v0,  V3_S2* v1,  V3_S2* v2, 
 	V2_S2* xy0, V2_S2* xy1, V2_S2* xy2, 
 	A2_S2* pp, S4* otz, S4* flag
 ){
 	return rtp_avg_nclip_a3_v3s2_raw(
 		v0, v1, v2, 
 		C_(S4*R_, xy0), C_(S4*R_, xy1), C_(S4*R_, xy2),
 		C_(S4*R_, pp),  C_(S4*R_, otz), C_(S4*R_, flag)
 	);
 }
 S4 rtp_avg_nclip_a4_v3s2_raw(V3_S2* v0, V3_S2* v1, V3_S2* v2, V3_S2* v3, S4* xy1, S4* xy2, S4* xy3, S4* xy4, S4* pp, S4* otz, S4* flag) asm("RotAverageNclip4");
 FI_ S4 rtp_avg_nclip_a4_v3s2(
 	V3_S2* v0,  V3_S2* v1,  V3_S2* v2,  V3_S2* v3,
 	V2_S2* xy0, V2_S2* xy1, V2_S2* xy2, V2_S2* xy3,
 	A2_S2* pp,  S4* otz,    S4* flag
 ){
 	return rtp_avg_nclip_a4_v3s2_raw(
 		v0, v1, v2, v3,
 		C_(S4*R_, xy0), C_(S4*R_, xy1), C_(S4*R_, xy2), C_(S4*R_, xy3),
 		C_(S4*R_, pp),  C_(S4*R_, otz), C_(S4*R_, flag)
 	);
 }
 void gte_matrix_set_rotation   (M3_S2* mat) asm("SetRotMatrix");
 void gte_matrix_set_translation(M3_S2* mat) asm("SetTransMatrix");
@@ -5,11 +5,10 @@
 // Format: WORD_COUNT(MACRO_NAME, COUNT)
 // One line per macro that appears in your atom sources.
 //
-// This file is encoding-macros-only. The auto-generated component
+// This file is encoding-macros-only. 
-// macros (mac_X) live in duffle/gen/<dir>.macs.h (included separately
+// The auto-generated component macros (mac_X) live in the source directory's own gen/macs.h (per-directory aggregation; included separately by the unity build).
-// by the unity build). The unity build should include THIS file and
+// The unity build should include THIS file and the .macs.h file in the same TU, with both wrapped 
-// the .macs.h file in the same TU, with both wrapped (or the
+// (or the include guard order handled) to avoid WORD_COUNT redeclaration.
 // include guard order handled) to avoid WORD_COUNT redeclaration.
 //
 // To regenerate: hand-count the instructions in each macro definition.
 // (You'll only need to do this once per macro — they don't change often.)
@@ -23,6 +22,7 @@ WORD_COUNT(call_reg,                         1)
 WORD_COUNT(call_addr,                        1)
 WORD_COUNT(branch_le_zero,                   1)
 WORD_COUNT(branch_equal,                     1)
 WORD_COUNT(branch_ne,                        1)
 WORD_COUNT(add_ui,                           1)
 WORD_COUNT(set_lt_u,                         1)
 WORD_COUNT(set_lt_s,                         1)
@@ -30,7 +30,9 @@ WORD_COUNT(set_lt_si,                        1)
 WORD_COUNT(set_lt_ui,                        1)
 WORD_COUNT(load_word,                        1)
 WORD_COUNT(load_half_u,                      1)
 WORD_COUNT(load_byte_u,                      1)
 WORD_COUNT(store_word,                       1)
 WORD_COUNT(store_byte,                       1)
 WORD_COUNT(add_ui_self,                      1)
 WORD_COUNT(add_u_self,                       1)
 WORD_COUNT(add_u,                            1)
@@ -38,6 +40,7 @@ WORD_COUNT(or_i,                             1)
 WORD_COUNT(or_i_self,                        1)
 WORD_COUNT(or_u,                             1)
 WORD_COUNT(or_u_self,                        1)
 WORD_COUNT(nor_u,                            1)
 WORD_COUNT(shift_lleft,                      1)
 WORD_COUNT(shift_lleft_self,                 1)
 WORD_COUNT(shift_lright,                     1)
@@ -1,161 +0,0 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	include "duffle/gen/duffle.macs.h"
 #	include "duffle/gen/duffle.offsets.h"
 #	include "duffle/atom_dsl.h"
 #	include "duffle/lottes_tape.h"
 #	include "duffle/word_count.metadata.h"
 #	include "gen/gte_hello.offsets.h"
 #	include "hello_gte.h"
 #endif
 #pragma region MACs (Mips Atom components)
 #pragma endregion MACs
 #pragma region Baked Atoms
 typedef Struct_(Binds_CubeTri) {
 	U4     PrimCursor;
 	V4_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri)
 ,	atom_reads(R_TapePtr)
 ,	atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
 /* ============================================================================
 *  cube_g4_face — Draw one cube face (Gouraud-shaded quad) via the GTE tape pipeline
 * ============================================================================
 *  Reads 4 indices from R_FaceCur (V4_S2 = 8 bytes), loads 4 vertices into
 *  the GTE, runs the PsyQ RotAverageNclip4 sequence, and renders a Poly_G4.
 */
 internal
 MipsAtom_(cube_g4_face) atom_info(
 		atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase),
 		atom_writes(R_PrimCursor, R_FaceCursor)
 ){
 	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)),
 	mac_gte_load_tri_verts(R_T0, R_T1, R_T2),
 	nop2, gte_cmdw_rotate_translate_perspective_triple,
 	nop2, gte_cmdw_nclip,
 	nop2,  gte_mv_from_data_r(R_T0, C2_MAC0),
 	nop,
 	branch_le_zero(R_T0, atom_offset(cull, cube_g4_face_exit)), nop,
 	store_word(R_0, R_PrimCursor, O_(Poly_G4, tag)),
 	mac_format_g4_color(
 		/* c0 magenta */ 0xFF, 0x00, 0xFF,
 		/* c1 yellow  */ 0xFF, 0xFF, 0x00,
 		/* c2 cyan    */ 0x00, 0xFF, 0xFF,
 		/* c3 green   */ 0x00, 0xFF, 0x00),
 	mac_gte_store_g4_p012_post_rtpt_pre_rtps(),
 	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)),
 	gte_mv_to_data_r(R_V0, C2_VXY0),       gte_mv_to_data_r(R_V1, C2_VZ0),
 	nop2, gte_cmdw_rotate_translate_perspective_single,
 	mac_gte_store_g4_p3_post_rtps(),
 	nop2, gte_cmdw_avg_sort_z4,
 	nop2, gte_mv_from_data_r(R_T1, C2_OTZ),
 	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,
 	mac_insert_ot_tag_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()
 };
 typedef Struct_(Binds_FloorTri) {
 	U4     PrimCursor;
 	V3_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal
 MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri)
 	, atom_reads(R_TapePtr)
 	, atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_FloorTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 internal
 MipsAtom_(floor_f3_face) atom_info(
 	, atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 	, atom_writes(R_PrimCursor, R_FaceCursor)
 ) {
 	mac_load_tri_indices(  R_T0, R_T1, R_T2),
 	mac_gte_load_tri_verts(R_T0, R_T1, R_T2),
 	nop2, gte_cmdw_rotate_translate_perspective_triple,
 	nop2, gte_cmdw_nclip,
 	/* Culling (Branch forward if Backface) */
 	nop2, gte_mv_from_data_r(R_T0, C2_MAC0),
 	nop,
 	branch_le_zero(R_T0, atom_offset(culling, floor_f3_face_exit)), nop,
 	/* Format Primitive */
 	mac_format_f3_color(0xFF, 0xFF, 0xFF),  // RGB-form (R=FF, G=FF, B=FF = white)
 	mac_gte_store_f3_post_rtpt(),
 	/* Calculate Depth */
 	nop2, gte_avg_sort_z3,
 	nop2, gte_mv_from_data_r(R_T1, C2_OTZ),
 	/* 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,
 	/* Insert into Ordering Table Linked List */
 	mac_insert_ot_tag_f3(),
 	add_ui_self(R_PrimCursor, S_(Poly_F3)), /* Advance Prim Cursor (5 words) */
 		// Note(Ed): No bounds checking, should be checked before atom runs.
 /* Advance Input Cursor & Yield (Both branch targets land here) */
 atom_label(floor_f3_face_exit)
 	add_ui_self(R_FaceCursor, S_(S2) * 4),  /* Advance Face Cursor (4 * S2 = 8 bytes) */
 	mac_yield()
 };
 typedef Struct_(Binds_SyncPrimitiveArena) { U4 used; U4 cursor; };
 internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitiveArena)
 	, atom_reads( R_TapePtr, R_PrimCursor)
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
 	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor
 	store_word(R_T0, R_AT, 0),            // R_AT[0] = R_T0
 	mac_yield()
 };
 #pragma endregion Baked Atoms
@@ -0,0 +1,41 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #pragma once
 #endif
 // Auto-generated by ps1_meta.lua — DO NOT EDIT
 // Directory: C:\projects\Pikuma\ps1\code\hello_camera/
 //   source: C:\projects\Pikuma\ps1\code\hello_camera\hello_camera.c
 //   source: C:\projects\Pikuma\ps1\code\hello_camera\hello_camera.h
 //   source: C:\projects\Pikuma\ps1\code\hello_camera\hello_camera.atom.c
 // Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)
 #ifndef WORD_COUNT
 #define WORD_COUNT(name, count)  enum { words_##name = (count) };
 #endif
 #define mac_put_disp_env(reg_transfer, reg_base, port) \
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_set_mask_bit(),                 reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port)
 WORD_COUNT(mac_put_disp_env, 5)
 #define mac_put_draw_env(reg_transfer, reg_base, port) \
 	mac_gcmd_push(gp0_dr_env_tag,                            reg_transfer, reg_base, port) /* tag (length=15 << 24, addr=0) — packet header for the DR_ENV sequence. The GPU needs this to recognize the next 15 words as a DR_ENV packet and trigger the isbg auto-clear. */ \
 ,	mac_gcmd_push(gp0_word_draw_mode_drawing_allowed,        reg_transfer, reg_base, port) /* code[0]  DrawMode (dfe=1, dtd=0, tpage=0) */ \
 ,	mac_gcmd_push(gp0_word_set_texture_window(),             reg_transfer, reg_base, port) /* code[1]  TextureWindow (tw=(0,0)) */ \
 ,	mac_gcmd_push(enc_gp0_draw_area_tl_word(0, ScreenRes_Y), reg_transfer, reg_base, port) /* code[2]  DrawArea top-left (clip.x=0, clip.y=ScreenRes_Y=240) */ \
 ,	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240,   reg_transfer, reg_base, port) /* code[3]  DrawArea bottom-right (clip.x+w=320, clip.y+h=480) */ \
 ,	mac_gcmd_push(gp0_word_set_draw_offset(),               reg_transfer, reg_base, port) /* code[4]  DrawOffset (ofs=(0,0)) — bare-cmd word; the GPU uses the current state machine. */ \
 ,	mac_gcmd_push(gp0_word_dr_env_mask(),                   reg_transfer, reg_base, port) /* code[5]  Mask (dtd=0, dfe=1, isbg=1) — 0xE6 cmd + isbg bit. */ \
 ,	mac_gcmd_push(gp0_word_dr_env_bg_color_cmd(1, 7, 7, 7), reg_transfer, reg_base, port) /* code[6]  Initial-bg-color + auto-clear (isbg=1, r=7, g=7, b=7). */ \
 ,	mac_gcmd_push(gp0_word_dr_env_draw_mode(1),             reg_transfer, reg_base, port) /* code[7]  Re-assert DrawMode with isbg=1 (isbg-flag set; the 0xE1 cmd byte plus isbg only). */	/* code[8..10]  Padding (NOP — GPU discards; the DR_ENV requires 16 words total). */ \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port)	/* code[11..12]  TextureWindow bottom-right (tw.x+tw.w=0, tw.y+tw.h=0) — libpsyx emits twice. */ \
 ,	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port)	/* code[13..14]  Padding (NOP) — completes the 16-word packet. */ \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port)
 WORD_COUNT(mac_put_draw_env, 16)
@@ -0,0 +1,50 @@
 // Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT
 // Directory: C:\projects\Pikuma\ps1\code\hello_camera\
 //   source: C:\projects\Pikuma\ps1\code\hello_camera\hello_camera.c
 //   source: C:\projects\Pikuma\ps1\code\hello_camera\hello_camera.h
 //   source: C:\projects\Pikuma\ps1\code\hello_camera\hello_camera.atom.c
 #pragma once
 #pragma region hello_camera
 // --- atom: pad_apply_input (60 words) ---
 #define _atom_offset_dpad_left_exit_dpad_left         6
 #define _atom_offset_dpad_right_exit_dpad_right       6
 #define _atom_offset_dead_zone_low_check_dead_low_active  8
 #define _atom_offset_dead_zone_high_check_dead_high_active  15
 #define _atom_offset_dead_zone_skip_exit_stick        24
 #define _atom_offset_end_low_exit_stick               12
 enum {
    atom_offset_dpad_left_exit_dpad_left = _atom_offset_dpad_left_exit_dpad_left,
    atom_offset_dpad_right_exit_dpad_right = _atom_offset_dpad_right_exit_dpad_right,
    atom_offset_dead_zone_low_check_dead_low_active = _atom_offset_dead_zone_low_check_dead_low_active,
    atom_offset_dead_zone_high_check_dead_high_active = _atom_offset_dead_zone_high_check_dead_high_active,
    atom_offset_dead_zone_skip_exit_stick = _atom_offset_dead_zone_skip_exit_stick,
    atom_offset_end_low_exit_stick = _atom_offset_end_low_exit_stick,
 };
 // --- atom: cube_g4_face (76 words) ---
 #define _atom_offset_cull_cube_g4_face_exit           41
 #define _atom_offset_bounds_chk_cube_g4_face_exit     24
 enum {
    atom_offset_cull_cube_g4_face_exit = _atom_offset_cull_cube_g4_face_exit,
    atom_offset_bounds_chk_cube_g4_face_exit = _atom_offset_bounds_chk_cube_g4_face_exit,
 };
 // --- atom: floor_f3_face (58 words) ---
 #define _atom_offset_culling_floor_f3_face_exit       25
 #define _atom_offset_bounds_chk_floor_f3_face_exit    16
 enum {
    atom_offset_culling_floor_f3_face_exit = _atom_offset_culling_floor_f3_face_exit,
    atom_offset_bounds_chk_floor_f3_face_exit = _atom_offset_bounds_chk_floor_f3_face_exit,
 };
 #pragma endregion hello_camera
@@ -0,0 +1,468 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #		include "duffle/gen/macs.h"
 #		include "duffle/gen/offsets.h"
 #	include "duffle/dsl.atom.h"
 #	include "duffle/lottes_tape.h"
 #	include "duffle/mips.h"
 #	include "duffle/gte.h"
 #	include "duffle/gp.h"
 #	include "duffle/pad.h"
 #	include "duffle/word_count.metadata.h"
 #	include "duffle/psyq.h"
 #	include "duffle/math.atom.c"
 #	include "duffle/mips.atom.c"
 #	include "duffle/gte.atom.c"
 #	include "duffle/gp.atom.c"
 #	include "duffle/psyq.atom.c"
 #		include "gen/offsets.h"
 #		include "gen/macs.h"
 #	include "hello_camera.h"
 #endif
 ATOM_FILE_DEBUGGER_LINE_MARKER(hello_joypad_atom_c);
 #pragma region MACs (Mips Atom components)
 FI_ Slice_MipsCode ac_put_disp_env(U4 reg_transfer, U4 reg_base, U2 port)
 MipsAtomComp_Proc_(ac_put_disp_env, {
 	// 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),
 	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_set_mask_bit(),                 reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port),
 })
 FI_ Slice_MipsCode ac_put_draw_env(U4 reg_transfer, U4 reg_base, U2 port)
 MipsAtomComp_Proc_(ac_put_draw_env, {
 	/*
 	* ORIGIN: each code word corresponds to the EXACT value libpsyx's PutDrawEnv function would compute for the same DrawEnv settings.
 	* References:
 	*   - libpsyx source: `toolchain/psyq-4_7/lib/libgpu.a` (binary, function `PutDrawEnv`)
 	*   - PSX-SPX doc:     https://problemkaputt.de/psx-spx.htm#gputdrawingcommands
 	*   - PSYQ SDK:        `setdrawenv` / `makelongdr_env` source
 	*   - NOCASH PSX spec: §"GP0(E1h) Draw Mode setting" through §"DR_ENV"
 	*
 	* The 16-word format is documented in the PSYQ SDK manual and on NOCASH's PSX-spec.txt. The libpsyx reference is at:
 	*   ./toolchain/psyq-4_7/lib/libgpu.a
 	*   (binary; the PutDrawEnv implementation builds the 16-word DR_ENV from the user's DRAWENV struct and emits it via GP0 GPU commands.)
 	*
 	* Word indices (libpsyx PutDrawEnv / SetDrawEnv order):
 	*   tag      = (length << 24) | addr                — 16-word packet (1 tag + 15 code)
 	*   code[0]  = DrawMode (dfe=1, dtd=0, tpage=0)     — must come first per libpsyx
 	*   code[1]  = TextureWindow (tw=(0,0))             — bare-cmd word; GPU uses current state
 	*   code[2]  = DrawArea top-left (clip.x=0, clip.y=240)
 	*   code[3]  = DrawArea bottom-right (clip.x+w=320, clip.y+h=480)
 	*   code[4]  = DrawOffset (ofs=(0,0))               — bare-cmd word
 	*   code[5]  = Mask (dtd=0, dfe=1, isbg=1)          — 0xE6 cmd + isbg bit
 	*   code[6]  = Initial-bg-color (isbg=1, r=7, g=7, b=7)
 	*   code[7]  = DrawMode (isbg=1, tpage=0)           — re-asserts DrawMode with isbg
 	*   code[8..10]  = padding (NOP)                    — 3 words to fill the packet
 	*   code[11..12] = TextureWindow bottom-right       — defaults to (0,0,0,0)
 	*   code[13..14] = padding (NOP)                    — completes the 16-word packet
 	*/
 	mac_gcmd_push(gp0_dr_env_tag,                            reg_transfer, reg_base, port), /* tag (length=15 << 24, addr=0) — packet header for the DR_ENV sequence. The GPU needs this to recognize the next 15 words as a DR_ENV packet and trigger the isbg auto-clear. */
 	mac_gcmd_push(gp0_word_draw_mode_drawing_allowed,        reg_transfer, reg_base, port), /* code[0]  DrawMode (dfe=1, dtd=0, tpage=0) */
 	mac_gcmd_push(gp0_word_set_texture_window(),             reg_transfer, reg_base, port), /* code[1]  TextureWindow (tw=(0,0)) */
 	mac_gcmd_push(enc_gp0_draw_area_tl_word(0, ScreenRes_Y), reg_transfer, reg_base, port), /* code[2]  DrawArea top-left (clip.x=0, clip.y=ScreenRes_Y=240) */
 	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240,   reg_transfer, reg_base, port), /* code[3]  DrawArea bottom-right (clip.x+w=320, clip.y+h=480) */
 	mac_gcmd_push(gp0_word_set_draw_offset(),               reg_transfer, reg_base, port), /* code[4]  DrawOffset (ofs=(0,0)) — bare-cmd word; the GPU uses the current state machine. */
 	mac_gcmd_push(gp0_word_dr_env_mask(),                   reg_transfer, reg_base, port), /* code[5]  Mask (dtd=0, dfe=1, isbg=1) — 0xE6 cmd + isbg bit. */
 	mac_gcmd_push(gp0_word_dr_env_bg_color_cmd(1, 7, 7, 7), reg_transfer, reg_base, port), /* code[6]  Initial-bg-color + auto-clear (isbg=1, r=7, g=7, b=7). */
 	mac_gcmd_push(gp0_word_dr_env_draw_mode(1),             reg_transfer, reg_base, port), /* code[7]  Re-assert DrawMode with isbg=1 (isbg-flag set; the 0xE1 cmd byte plus isbg only). */
 	/* code[8..10]  Padding (NOP — GPU discards; the DR_ENV requires 16 words total). */
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	/* code[11..12]  TextureWindow bottom-right (tw.x+tw.w=0, tw.y+tw.h=0) — libpsyx emits twice. */
 	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port),
 	/* code[13..14]  Padding (NOP) — completes the 16-word packet. */
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 })
 #pragma endregion MACs
 #pragma region Baked Atoms
 enum {
 	R_ScreenX   = R_T5 atom_reg atom_type(U2),
 	R_ScreenY   = R_T6 atom_reg atom_type(U2),
 	R_ScreenBuf = R_T7 atom_reg, /* Caller-pinned: & smem.screen_buf */
 #define R_ScreenBuf_Code R_T7_Code
 };
 //screen_env_init. Mirrors the libpsyx's SetDefDispEnv + SetDefDrawEnv + the manual enable_auto_clear / initial_bg_color writes.
 internal MipsAtom_(screen_env_init) atom_info(atom_phase(screen_init)
 ,	atom_reads(R_T0, R_ScreenX, R_ScreenY, R_ScreenBuf)
 , atom_writes(R_T0, R_ScreenX, R_ScreenY)
 ) {
 	/* 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)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,display_area) + OA_(DoubleBuffer,display,0)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,screen)       + OA_(DoubleBuffer,display,0)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,vinterlace)   + OA_(DoubleBuffer,display,0)),
 	/* display[1] = (0, 240, 320, 240); rest of struct zeroed. */
 	mac_store_rects2(R_0, R_ScreenY, R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DisplayEnv,display_area) + OA_(DoubleBuffer,display,1)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,screen)     + OA_(DoubleBuffer,display,1)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,vinterlace) + OA_(DoubleBuffer,display,1)),
 	mac_store_rects2(R_0, R_ScreenY, R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DrawEnv,clip_area)         + OA_(DoubleBuffer,draw,0)), /* draw[0].clip_area = (0, 240, 320, 240). C11's SetDefDrawEnv writes clip.y = y_arg. */
 	mac_store_v2s2(  R_0, R_ScreenY,                       R_ScreenBuf, O_(DrawEnv,drawing_offset[0]) + OA_(DoubleBuffer,draw,0)), /* draw[0].drawing_offset[0] = (0, 240); C11 passes y_arg as ofs. */
 	mac_store_v2s2(R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DrawEnv,clip_area.width) + OA_(DoubleBuffer,draw,1)),
 	/* draw[0].texture_window = (0, 0, 0, 0); two word-zeroes cover the full 8-byte tw field. */
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.x)     + OA_(DoubleBuffer,draw,0)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.width) + OA_(DoubleBuffer,draw,0)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,drawing_offset[0].x)  + OA_(DoubleBuffer,draw,1)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.x)     + OA_(DoubleBuffer,draw,1)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.width) + OA_(DoubleBuffer,draw,1)),
 	/* draw[0].texture_page = 10 (gp0_tpage_default). C11 SetDefDrawEnv at C11_only.elf:0x8001273C writes the same 0x0A. . */
 	add_ui(R_T0, R_0, gp0_tpage_default), 
 	store_half(R_T0, R_ScreenBuf, O_(DrawEnv,texture_page) + OA_(DoubleBuffer,draw,0)),
 	store_half(R_T0, R_ScreenBuf, O_(DrawEnv,texture_page) + OA_(DoubleBuffer,draw,1)),
 	/* draw[0] control bytes: flag_dither=1, flag_draw_on_display=1 (the dfe bit per psx-spx; libpsyx sets it via `SetDefDrawEnv`'s conditional at C11_only.elf:0x80012728), enable_auto_clear=1. Each byte is named;
 	 * the previous `store_word(R_0, ..., +20)` overwrote all four with zero. */
 	add_ui(R_T0, R_0, 1),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_dither)          + OA_(DoubleBuffer,draw,0)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_draw_on_display) + OA_(DoubleBuffer,draw,0)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,enable_auto_clear)    + OA_(DoubleBuffer,draw,0)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_dither)          + OA_(DoubleBuffer,draw,1)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_draw_on_display) + OA_(DoubleBuffer,draw,1)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,enable_auto_clear)    + OA_(DoubleBuffer,draw,1)),
 	/* draw[0].initial_bg_color = (r=7, g=7, b=7). */
 	add_ui(R_T0, R_0, 7), 
 	mac_store_rgb8(R_T0,R_T0,R_T0, R_ScreenBuf, O_(DrawEnv,initial_bg_color) + OA_(DoubleBuffer,draw,0)),
 	mac_store_rgb8(R_T0,R_T0,R_T0, R_ScreenBuf, O_(DrawEnv,initial_bg_color) + OA_(DoubleBuffer,draw,1)),
 	mac_yield(),
 };
 enum {
 	R_IO_BaseAddr = R_T4 atom_reg, /* Caller-pinned: IO_BASE_ADDR = 0x1F800000 */
 #define R_IO_BaseAddr_Code R_T4_Code
 };
 internal MipsAtom_(gp_screen_init) atom_info(atom_phase(screen_init), atom_reads(R_IO_BaseAddr)) {
 	store_word(R_0, R_IO_BaseAddr, GPIO_PORT1_OFFSET),                                   /* GP1(00h) Reset */
 	mac_gcmd_push(gp1_word_ResetCmdBuffer(),   R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(01h) ClearFIFO */
 	mac_gcmd_push(gp1_word_AcknowledgeIRQ(),   R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(02h) AckIRQ */
 	mac_gcmd_push(gp1_word_DisplayOn(),        R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(03h) Display ON */
 	mac_gcmd_push(gp1_word_dma_to_gpu(),       R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(04h) DMADirection=2 (CPU→GPU). libpsyx's per-frame PutDrawEnv/DrawOTag use DMA2; without this the DMA queue never drains. */
 	mac_gcmd_push(gp1_word_StartDisplayArea(), R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(05h) StartDisplayArea (X=0, Y=0) */
 	/* GP1: DisplayMode + Display Ranges */
 	mac_gcmd_push(gp1_word_display_mode_320x240_15bit_ntsc, R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	mac_gcmd_push(gp1_word_horizontal_range_ntsc,           R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	mac_gcmd_push(gp1_word_vertical_range_ntsc,             R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	/* GTE: SetGeomOffset (OFX, OFY) — ScreenRes_CenterX, ScreenRes_CenterY. */
 	load_upper_i(R_T5, ScreenRes_CenterX), gte_mv_to_ctrl_r(R_T5, gte_cr_OFX_Code),
 	load_upper_i(R_T5, ScreenRes_CenterY), gte_mv_to_ctrl_r(R_T5, gte_cr_OFY_Code),
 	/* GTE: SetGeomScreen (H) — CR26 (per PSX-SPX / libpsyx), value is the raw projection-plane distance, NOT shifted. */
 	add_ui(R_T5, R_0, ScreenZ), gte_mv_to_ctrl_r(R_T5, gte_cr_H_Code),
 	/* GP1: DisplayEnable — bit 0 = 0 (Display ON). */
 	mac_gcmd_push(gp1_word_DisplayOn(), R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	mac_yield(),
 };
 /* ----- pad_apply_input -----
 * Reads pad[0].buttons + pad[0].left_x; 
 * Applies the input-semantics deltas to cube_rot.y + floor_rot.y:
 *   - D-pad Left:  cube_rot.y += 30, floor_rot.y += 5
 *   - D-pad Right: cube_rot.y -= 30, floor_rot.y -= 5
 *   - Analog stick X (dead zone 0x70..0x90):
 *       cube delta  = (0x80 - left_x) >> 2  (range approx -32..+32)
 *       floor delta = (0x80 - left_x) >> 5  (range approx -4..+4)
 *   - D-pad + analog deltas add when used together.
 *
 * Convention:
 *   pad_state = 0 means no buttons active. 
 *   The fail-safe zero-button value flows through unchanged, so a disconnected/fresh pad produces no rotation.
 *   The branch_le_zero pattern below matches the existing pad_input_demo convention (atom body lines 248/257).
 *
 * Signed-delta trick:
 * load_byte_u zero-extends left_x to 32 bits; sub_u from 0x80 wraps to a SIGNED two's-complement value in the negative range;
 * shift_aright (sra) then correctly sign-extends the shift for both positive (left_x < 0x80) and negative (left_x > 0x80) cases.
 * Digital pads publish left_x = 0x80 → delta = 0 → no rotation, so the analog step is naturally a no-op for digital controllers.
 */
 typedef Struct_(Binds_PadApplyInput) {
    PadState* state;
    V3_S2*    cube_rot;
    V3_S2*    floor_rot;
 };
 enum {
 	R_PadStateT5 = R_T5 atom_reg,
 	R_CubeRot    = R_T1 atom_reg,
 	R_FloorRot   = R_T2 atom_reg,
 };
 internal MipsAtom_(pad_apply_input) atom_info(atom_bind(Binds_PadApplyInput)
 , atom_reads(R_T0, R_CubeRot, R_FloorRot, R_T3, R_T4, R_PadStateT5, R_TapePtr)
 , atom_writes(     R_CubeRot, R_FloorRot)
 ) {
 	/* Pop Binds from tape (state, cube_rot, floor_rot) */
 	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)),
 	/* Load pad[0].buttons into R_T0. */
 	load_word(R_T0, R_PadStateT5, O_(PadState,buttons)), 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, pad0_(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 */
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, 30),
 		add_si(    R_T3, R_T3, 5),
 		store_half(R_T4, R_CubeRot,  O_(V3_S2,y)),
 		store_half(R_T3, R_FloorRot, O_(V3_S2,y)),
 	atom_label(exit_dpad_left)
 	/* D-pad Right: cube_rot.y -= 30, floor_rot.y -= 5. */
 	and_i(R_T3, R_T0, pad0_(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 */
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, -30),
 		add_si(    R_T3, R_T3, -5),
 		store_half(R_T4, R_CubeRot,  O_(V3_S2,y)),
 		store_half(R_T3, R_FloorRot, O_(V3_S2,y)),
 	atom_label(exit_dpad_right)
 	/* 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)),
 	/* 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. */
 	add_ui(R_T4, R_0, 0x70), set_lt_u(R_T4, R_T3, R_T4), branch_ne(R_T4, R_0, atom_offset(dead_zone_low_check, dead_low_active)),
 	add_ui(R_T4, R_0, 0x80), /* BD-slot: pre-load 0x80 for dead_low_active */
 atom_label(dead_check_upper)
 	/* left_x >= 0x70 → check upper bound. */
 	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left_x)), /* reload */
 	add_ui(     R_T4, R_0, 0x90),
 	/* 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)),
 	add_ui(  R_T4, R_0, 0x80), /* BD-slot: pre-load 0x80 for dead_high_active */
 	jump_rel(atom_offset(dead_zone_skip, exit_stick)),
 		mac_yield_load(),
 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`).
 	 * The earlier `load_byte_u(R_T3, ...)` reload was redundant and introduced a load-use hazard on the next `sub_u`.
 	 * R_T4 = 0x80 from the BD-slot of `dead_zone_low_check`'s branch_ne. */
 	sub_u( R_T3, R_T4, R_T3), /* R_T3 = 0x80 - left_x */
 	/* delta = 0x80 - left_x (positive). */
 	/* R_T4 = cube_delta */
 	shift_aright(R_T4, R_T3, 2),
 	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)),
 	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)),
 	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(),
 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`).
 	 * The earlier `load_byte_u(R_T3, ...)` reload was redundant and introduced a load-use hazard on the next `sub_u`.
 	 * R_T4 = 0x80 from the BD-slot of `dead_zone_high_check`'s branch_ne. */
 	sub_u( R_T3, R_T4, R_T3),
 	/* 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,
 	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)),
 	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(),
 atom_label(exit_stick)
 	/* NOT mac_yield() — R_AtomJmp was already loaded in the BD-slot of the dead-zone/exit branch. */
 	mac_yield_tail(),
 };
 enum {
 	R_PrimCursor = R_T7 atom_reg atom_type(U4*),    /* VRAM output cursor (primitive buffer) */
 	R_FaceCursor = R_T4 atom_reg atom_type(V4_S2*), /* Cube face-index cursor (V4_S2*); floor context switches to V3_S2* via atom_phase */
 	R_VertBase   = R_T5 atom_reg atom_type(V3_S2*), /* Base address of the vertex array */
 	R_OtBase     = R_T6 atom_reg atom_type(U4*),    /* Base address of the Ordering Table */
 #define R_PrimCursor_Code  R_T7_Code
 #define R_FaceCursor_Code  R_T4_Code
 #define R_VertBase_Code    R_T5_Code
 #define R_OtBase_Code      R_T6_Code
 };
 typedef Struct_(Binds_CubeTri) {
 	U4     PrimCursor;
 	V4_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_phase(cube_g4)
 ,	atom_reads(R_TapePtr)
 ,	atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase, R_TapePtr)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
 // cube_g4_face — Draw one cube face (Gouraud-shaded quad) via the GTE tape pipeline
 internal
 MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 		atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase),
 		atom_writes(R_PrimCursor, R_FaceCursor)
 ){
 	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)),
 	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
 	gte_cmdw_nclip,
 	gte_mv_from_data_r(R_T0, C2_MAC0), nop,
 	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, only on the body path. */
 		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)),
 		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),
 		gte_cmdw_rotate_translate_perspective_single,
 		mac_gte_store_g4_p3(R_PrimCursor),
 		gte_cmdw_avg_sort_z4,
 		gte_mv_from_data_r(R_T1, C2_OTZ),
 		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,
 			mac_insert_ot_tag_g4(R_OtBase, R_PrimCursor),
 			mac_format_g4_color(R_PrimCursor,
 				/* c0 magenta */ 0xFF, 0x00, 0xFF,
 				/* c1 yellow  */ 0xFF, 0xFF, 0x00,
 				/* c2 cyan    */ 0x00, 0xFF, 0xFF,
 				/* c3 green   */ 0x00, 0xFF, 0x00),
 		// end: branch(bounds_chk)
 // end: branch(cull)
 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()
 };
 typedef Struct_(Binds_FloorTri) {
 	U4     PrimCursor;
 	V3_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal
 MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri), atom_phase(floor_f3)
 	, atom_reads(R_TapePtr)
 	, atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase, R_TapePtr)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_FloorTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 // atom_dbg_skip
 internal
 MipsAtom_(floor_f3_face) atom_info(atom_phase(floor_f3)
 	, atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 	, 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
 	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. 
 		/* Format Primitive */
 		mac_gte_store_f3(R_PrimCursor),
 		/* Calculate Depth */
 		gte_avg_sort_z3,
 		gte_mv_from_data_r(R_T1, C2_OTZ),
 		/* Bounds Check OTZ < 2048 (Branch forward to skip insertion) */
 		add_ui(      R_AT, R_0,  OrderingTbl_Len),
 		set_lt_u(    R_AT, R_T1, R_AT),
 		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, floor_f3_face_exit)), nop,
 			mac_format_f3_color(R_PrimCursor, 0xFF, 0xFF, 0xFF),  // RGB-form (R=FF, G=FF, B=FF = white)
 			mac_insert_ot_tag_f3(R_OtBase, R_PrimCursor),         /* Insert into Ordering Table Linked List */
 			add_ui_self(R_PrimCursor, S_(Poly_F3)), /* Advance Prim Cursor (5 words) */
 				// Note(Ed): No bounds checking, should be checked before atom runs.
 		// end: branch(bounds_chk)
 	// end: branch(culling)
 /* 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()
 };
 typedef Struct_(Binds_SyncPrimitiveArena) { U4 used; U4 cursor; };
 internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitiveArena)
 	, atom_reads( R_TapePtr, R_PrimCursor)
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
 	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor
 	store_word(R_T0, R_AT, 0),            // R_AT[0] = R_T0
 	mac_yield()
 };
 #pragma endregion Baked Atoms
@@ -0,0 +1,336 @@
 #pragma region Vendors
 #include <stdio.h>
 #include <stdlib.h>
 #include <assert.h>
 // #include "libgpu.h"
 // #include "libetc.h"
 // #include "libgte.h"
 #pragma endregion Vendors
 #pragma region Duffle Headers
 #	include "duffle/gen/macs.h"
 #	include "duffle/gen/offsets.h"
 #include "duffle/word_count.metadata.h"
 #include "duffle/dsl.h"
 #include "duffle/memory.h"
 #include "duffle/math.h"
 #include "duffle/gcc_asm.h"
 #include "duffle/mips.h"
 #include "duffle/gp.h"
 #include "duffle/gte.h"
 #include "duffle/pad.h"
 #include "duffle/dsl.atom.h"
 #include "duffle/lottes_tape.h"
 #include "duffle/psyq.h"
 #pragma endregion Duffle Headers
 #pragma region Duffle TUs
 #include "duffle/math.atom.c"
 #include "duffle/mips.atom.c"
 #include "duffle/gte.atom.c"
 #include "duffle/gp.atom.c"
 #include "duffle/pad.atom.c"
 #include "duffle/psyq.atom.c"
 #pragma endregion Duffle TUs
 #pragma region Hello Camera Headers
 #	include "gen/macs.h"
 #	include "gen/offsets.h"
 #include "hello_camera.h"
 #pragma endregion Hello Camera Headers
 #pragma region Hello Joypad TUs
 #include "hello_camera.atom.c"
 #pragma endregion Hello Joypad TUs
 enum { 
 	Scratchpad_Len = 1024, 
 	MemTape_Len    = 512,
 };
 typedef Struct_(SMemory) {
 	PrimitiveArena          primitives;
 	A2_OrderingTable_Buffer ordering_tbl;
 	DoubleBuffer            screen_buf;
 	S4                      active_buf_id;
 	U4 MemTape[MemTape_Len];
 	M3_S2 tform_world;
 	Ent_Cube  cube;
 	Ent_Floor floor;
 	PadBiosRaw pad_raw[2];
 	PadState   pad[2];
 	U4_V scratchpad; // d-cache
 };
 global SMemory smem;
 extern SMemory smem;
 I_ B1* prim__alloc(U4 type_width, Str8 type_name) {
 	gknown PrimitiveArena* pa  = & smem.primitives;
 	gknown B1*             buf = (B1*) r_(smem.primitives.buf)[smem.active_buf_id];
 	assert(pa->used + type_width < PrimitiveBuff_Len);
 	B1* next  = buf + pa->used;
 	pa->used += type_width;
 	return next;
 }
 #define prim_alloc(type) (type*)prim__alloc(S_(type), slit( stringify(type)))
 /* Uses ONE 8-byte frame allocated via the compiler's standard prologue.
 * The 4 wasted-arg words for B(12h) InitPAD2 live at [SP+0..15] but are not explicitly allocated.
 * The compiler handles the MIPS O32 "wasted stack" convention for us by treating the B-call as a 4-arg call.
 *
 * The buffer pointers are passed as arguments so the compiler keeps them in callee-saved registers;
 * The B(12h) asm volatile block does NOT clobber those registers (it clobbers only the volatile GPRs + the B-table arg registers explicitly).
 * The C-level writes after the call re-load the pointers from their callee-saved homes.
 *
 * The clobber list for both B-calls names the full BIOS destroy set documented in kernelbios.md:167-174 (R1..R15, R24..R25, R31, HI/LO).
 * The kernel-ABI "volatile GPRs" subset is clb_system; the rest of the destroy set is enumerated explicitly here. */
 NI_ void pad_bios_init_start(PadBiosRaw* raw0, PadBiosRaw* raw1)
 {
 	/* Pin raw0 + raw1 to $a0 + $a1 via rgcc; the B(12h) call uses these directly.
 	 * The `(void)` casts mark them as unread after the call so the compiler doesn't need to move them back. */
 	register PadBiosRaw* p0 rgcc(R_A0) = raw0;
 	register PadBiosRaw* p1 rgcc(R_A1) = raw1;
 	(void)p0; (void)p1;
 	// TODO(Ed): Properly annotate the raw values in the inline asm instructions.
 	// Use enums.
 	/* B(12h) InitPAD2(raw0, 0x22, raw1, 0x22)
 	 *   $a0 = raw0 (rgcc-bound; survives the sequence below)
 	 *   $a1 = raw1 (preserved into $a2 before $a1 is overwritten)
 	 *   $a2 = raw1 (moved from $a1; survives $a1's overwrite)
 	 *   $a3 = 0x22 (immediate)
 	 *   $t1 = 0x12 (function number)
 	 *   $t2 = 0xB0 (BIOS B-table address) */
 	asm volatile(
 		asm_words(
 			or_u(    rarg_2, rarg_1, rdiscard), /* $a2 = $a1 = raw1 */
 			add_ui(  rarg_1, rdiscard, 0x22),   /* $a1 = 0x22 */
 			add_ui(  rarg_3, rdiscard, 0x22),   /* $a3 = 0x22 */
 			add_ui(  rtmp_1, rdiscard, 0x12),   /* $t1 = 0x12 */
 			add_ui(  rtmp_2, rdiscard, 0xB0),   /* $t2 = 0xB0 */
 			call_reg(rtmp_2),                   /* jalr $t2, $ra */
 			nop                                 /* BD slot */
 		)
 		asm_rpins, r_use(p0), r_use(p1)
 		asm_clobber: 
 			rlit(R_AT), 
 			rlit(R_V0), rlit(R_V1), 
 			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_T9),
 			rlit(R_RA),
 			clb_mem_drain
 	);
 	/* The C-level writes re-load the pointers via the parameter names and write 0xFF to each 
 	 * buffer's status byte to mark the initial-state hazard documented in kernelbios.md:1621-1624. */
 	u1_v(raw0)[0] = 0xFF;
 	u1_v(raw1)[0] = 0xFF;
 	/* B(13h) StartPAD2() — no args. The BIOS preserves $sp. */
 	asm volatile(
 		asm_words(
 			add_ui(  rtmp_1, rdiscard, 0x13), /* $t1 = 0x13 */
 			add_ui(  rtmp_2, rdiscard, 0xB0), /* $t2 = 0xB0 (re-load) */
 			call_reg(rtmp_2),                 /* jalr $t2, $ra */
 			nop                               /* BD slot */
 		)
 		asm_clobber:
 			rlit(R_AT),
 			rlit(R_V0), rlit(R_V1),
 			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_T9),
 			rlit(R_RA),
 			clb_mem_drain
 	);
 }
 GCC_OPTIMIZATION_DISABLE
 void update(PrimitiveArena* pa, U4* ordering_buf) 
 {
 	TapeBuilder tb = tb_make(slice_ut_arr(smem.MemTape));
 	if (1) // Pad Input
 	{
 		tb.used = 0; tb_scope_run(& tb) {
 			/* BIOS-owned polling: per-frame snapshot of both ports. */
 			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]);
 			/* Per-frame rotation apply: consume pad[0].buttons + pad[0].left_x */
 			tb_emit_(pad_apply_input);
 				tb_data_(state,     & smem.pad[0]);
 				tb_data_(cube_rot,  & smem.cube.rot);
 				tb_data_(floor_rot, & smem.floor.rot);
 		}
 	}
 	orderingtbl_clear_reverse(ordering_buf, OrderingTbl_Len);
 	// Update the position based on acceleration and velocity
 	gknown V3_S4_R pos = & smem.cube.pos;
 	gknown V3_S4_R vel = & smem.cube.vel;
 	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;
 	// Prep
 	S4 nclip = 0;
 	S4 orderingtbl_z = 0;
 	A2_S2 p;    //???
 	S4 flag; //????
 	// Draw cube
 	if (1)
 	{
 		m3s2_rotation   (& smem.cube.rot,    & smem.tform_world);
 		m3s2_translation(& smem.tform_world, & smem.cube.pos);
 		m3s2_scale      (& smem.tform_world, & smem.cube.scale);
 		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;
 		tb.used = 0; tb_scope(& tb) {
 			tb_emit(& tb, rbind_cube_g4_face);
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.cube.faces));
 				tb_data(& tb, u4_(smem.cube.verts));
 				tb_data(& tb, u4_(ordering_buf));
 			for (U4 i = 0; i < Cube_num_faces; i++) {
 				// Two triangles per quad face: (x,y,z) and (x,z,w)
 				tb_emit(& tb, cube_g4_face);
 			}
 			tb_emit(& tb, sync_primitive_arena);
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
 		tape_run(tb_slice(tb));
 		// smem.cube.rot.y += 30;
 	}
 	// Draw floor
 	if (1)
 	{
 		m3s2_rotation   (& smem.floor.rot,   & smem.tform_world);
 		m3s2_translation(& smem.tform_world, & smem.floor.pos);
 		m3s2_scale      (& smem.tform_world, & smem.floor.scale);
 		U4 prim_base   = u4_(pa->buf[smem.active_buf_id]);
 		U4 prim_cursor = prim_base + pa->used;
 		// TODO(Ed): We should do a bounds check beforehand to confirm pa can hold all tris?
 		// The tape atoms in-flight should not need to care.
 		// Prepare the tape. (Push protocol to tape)
 		tb.used = 0; tb_scope(& tb) {
 			tb_emit(& tb, set_gte_world);
 				tb_data(& tb, u4_(& smem.tform_world));
 			tb_emit(& tb, rbind_floor_f3_face);
 			// TODO(Ed): Just use a single context struct ref
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.floor.faces));
 				tb_data(& tb, u4_(smem.floor.verts));
 				tb_data(& tb, u4_(ordering_buf));
 			for (U4 i = 0; i < Floor_num_faces; i++) {
 				tb_emit(& tb, floor_f3_face);
 			}
 			// After floor_f3_face iterations complete, the primitive arena's used counter needs updating.
 			tb_emit(& tb, sync_primitive_arena);
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
 		tape_run(tb_slice(tb));// Fire off the tape.
 		// C-side state (pa->used) has already been updated by the tape!
 		// smem.floor.rot.y += 5;
 	}
 }
 GCC_OPTIMIZATION_ENABLE
 void render(void) {
 }
 void gp_display_frame(DoubleBuffer* screen_buf, S4* active_buf_id, U4* ordering_buf, PrimitiveArena* pa) {
 	draw_sync(0);
 	vsync(0);
 	displayenv_put(& r_(screen_buf->display)[active_buf_id[0] ]);
 	drawenv_put   (& r_(screen_buf->draw)   [active_buf_id[0] ]);
 	{
 		draw_orderingtbl(ordering_buf + OrderingTbl_Len - 1);
 		pa->used = 0;
 	}
 	active_buf_id[0] = ! active_buf_id[0]; // Swap current buffer
 }
 GCC_OPTIMIZATION_DISABLE
 int main(void)
 {
 	smem = (SMemory){0};
 	smem.scratchpad = C_(U4_V, 0x1F800000);
 	// smem.primitives.used = 0;
 	// smem.active_buf_id   = 0;
 	/*Persistent Entity Setup*/{
 		ent_cube128_init(& smem.cube.verts, & smem.cube.faces); {
 			Ent_Cube* cube = & smem.cube;
 			cube->rot    = v3s2(0, 0, 0);
 			cube->scale  = v3s4_fp_one();
 			cube->accel  = v3s4(0, 1, 0);
 			cube->pos    = v3s4(0, -400, 1800);
 		}
 		ent_floor_init(& smem.floor.verts, & smem.floor.faces); {
 			Ent_Floor* floor = & smem.floor;
 			floor->rot   = v3s2(0, 0, 0);
 			floor->pos   = v3s4(0, 450, 1800);
 			floor->scale = v3s4_fp_one();
 		}
 	}
 	TapeBuilder tb = tb_make(slice_ut_arr(smem.MemTape)); {
 		reset_graph(0);
 		/* Direct BIOS: poll both ports during VBlank. */
 		pad_bios_init_start(& smem.pad_raw[0], & smem.pad_raw[1]);
 		/* Pinned registers for the GPU init atom. */
 		register U4*           io_base_addr rgcc(R_IO_BaseAddr) = u4_r(IO_BASE_ADDR);
 		register DoubleBuffer* screen_buf   rgcc(R_ScreenBuf)   = & smem.screen_buf;
 		tb.used = 0; tb_scope_run(& tb) {
 			tb_emit(& tb, screen_env_init);
 			tb_emit(& tb, gp_screen_init);
 		}
 	}
 	while (1) {
 		gknown S4* active_buf_id  = & smem.active_buf_id;
 		gknown U4* ordering_buf   = r_(smem.ordering_tbl)[active_buf_id[0]];
 		gknown PrimitiveArena* pa = & smem.primitives;
 		update(pa, ordering_buf);
 		render();
 		gp_display_frame(& smem.screen_buf, active_buf_id, ordering_buf, pa);
 	};
 	return 0;
 }
 GCC_OPTIMIZATION_ENABLE
@@ -0,0 +1,102 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #	include "duffle/dsl.h"
 #	include "duffle/math.h"
 #	include "duffle/gp.h"
 #	include "duffle/pad.h"
 #endif
 enum {
 	// PrimitiveBuff_Len = 4096,
 	// OrderingTbl_Len   = 2048,
 	PrimitiveBuff_Len = 131072,
 	OrderingTbl_Len   = 8192,
 };
 enum {
 	ScreenRes_X = 320,
 	ScreenRes_Y = 240,
 	ScreenZ     = 320,
 	ScreenRes_CenterX = (ScreenRes_X >> 1),
 	ScreenRes_CenterY = (ScreenRes_Y >> 1),
 };
 enum {
 	fp_one = (1 << 12),
 };
 #define v3s4_fp_one() v3s4(fp_one, fp_one, fp_one)
 typedef U4 OrderingTable_Buffer[OrderingTbl_Len];
 typedef Array_(OrderingTable_Buffer, 2);
 typedef B1 PrimitiveBuffer[PrimitiveBuff_Len];
 typedef Array_(PrimitiveBuffer, 2);
 typedef Struct_(PrimitiveArena) {
 	A2_PrimitiveBuffer buf;
 	U4                 used;
 };
 #define Cube_num_verts 8
 typedef Array_(V3_S2, Cube_num_verts);
 #define Cube_num_faces 6
 typedef Array_(V4_S2, Cube_num_faces);
 I_ void ent_cube128_init(A8_V3_S2* verts, A6_V4_S2* faces) {
 	LP_ A8_V3_S2 baked_verts = (A8_V3_S2) {
 		{ -128, -128, -128 },
 		{  128, -128, -128 },
 		{  128, -128,  128 },
 		{ -128, -128,  128 },
 		{ -128,  128, -128 },
 		{  128,  128, -128 },
 		{  128,  128,  128 },
 		{ -128,  128,  128 }
 	};
 	LP_ A6_V4_S2 baked_faces = (A6_V4_S2) {
 		{ 3, 2, 0, 1 },
 		{ 0, 1, 4, 5 },
 		{ 4, 5, 7, 6 },
 		{ 1, 2, 5, 6 },
 		{ 2, 3, 6, 7 },
 		{ 3, 0, 7, 4 },
 	};
 	mem_copy(u4_(verts), u4_(& baked_verts), S_(A8_V3_S2) );
 	mem_copy(u4_(faces), u4_(& baked_faces), S_(A6_V4_S2) );
 	return;
 }
 typedef Struct_(Ent_Cube) {
 	V3_S4 accel;
 	V3_S4 vel;
 	V3_S4 pos;
 	V3_S4 scale;
 	V3_S2 rot;
 	A8_V3_S2 verts;
 	A6_V4_S2 faces;
 };
 #define Floor_num_verts 4
 typedef Array_(V3_S2, Floor_num_verts);
 #define Floor_num_faces 2
 typedef Array_(V3_S2, Floor_num_faces);
 I_ void ent_floor_init(A4_V3_S2* verts, A2_V3_S2* faces) {
 	LP_ A4_V3_S2 baked_verts = (A4_V3_S2) {
 		{ -900, 0, -900 },
 		{ -900, 0,  900 },
 		{  900, 0, -900 },
 		{  900, 0,  900 },
 	};
 	LP_ A2_V3_S2 baked_faces = (A2_V3_S2) {
 		{ 0, 1, 2 },
 		{ 1, 3, 2 },
 	};
 	mem_copy(u4_(verts), u4_(& baked_verts), S_(A4_V3_S2));
 	mem_copy(u4_(faces), u4_(& baked_faces), S_(A2_V3_S2));
 };
 typedef Struct_(Ent_Floor) {
 	V3_S4 accel;
 	V3_S4 pos;
 	V3_S4 scale;
 	V3_S2 rot;
 	A4_V3_S2 verts;
 	A2_V3_S2 faces;
 };
@@ -5,20 +5,20 @@
 #pragma region hello_gte_tape
-// --- atom: cube_g4_face (87 words) ---
+// --- atom: cube_g4_face (77 words) ---
-#define _atom_offset_cull_cube_g4_face_exit           48
+#define _atom_offset_cull_cube_g4_face_exit           42
-#define _atom_offset_bounds_chk_cube_g4_face_exit     12
+#define _atom_offset_bounds_chk_cube_g4_face_exit     24
 enum {
    atom_offset_cull_cube_g4_face_exit = _atom_offset_cull_cube_g4_face_exit,
    atom_offset_bounds_chk_cube_g4_face_exit = _atom_offset_bounds_chk_cube_g4_face_exit,
 };
-// --- atom: floor_f3_face (66 words) ---
+// --- atom: floor_f3_face (58 words) ---
-#define _atom_offset_culling_floor_f3_face_exit       29
+#define _atom_offset_culling_floor_f3_face_exit       25
-#define _atom_offset_bounds_chk_floor_f3_face_exit    13
+#define _atom_offset_bounds_chk_floor_f3_face_exit    16
 enum {
    atom_offset_culling_floor_f3_face_exit = _atom_offset_culling_floor_f3_face_exit,
@@ -0,0 +1,29 @@
 // Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT
 // Source: C:\projects\Pikuma\ps1\code\hello_gte\hello_gte.tape.c
 #pragma once
 #pragma region hello_gte.tape
 // --- atom: cube_g4_face (77 words) ---
 #define _atom_offset_cull_cube_g4_face_exit           42
 #define _atom_offset_bounds_chk_cube_g4_face_exit     24
 enum {
    atom_offset_cull_cube_g4_face_exit = _atom_offset_cull_cube_g4_face_exit,
    atom_offset_bounds_chk_cube_g4_face_exit = _atom_offset_bounds_chk_cube_g4_face_exit,
 };
 // --- atom: floor_f3_face (58 words) ---
 #define _atom_offset_culling_floor_f3_face_exit       25
 #define _atom_offset_bounds_chk_floor_f3_face_exit    16
 enum {
    atom_offset_culling_floor_f3_face_exit = _atom_offset_culling_floor_f3_face_exit,
    atom_offset_bounds_chk_floor_f3_face_exit = _atom_offset_bounds_chk_floor_f3_face_exit,
 };
 #pragma endregion hello_gte.tape
@@ -1,6 +1,6 @@
-#include "stdio.h"
+#include <stdio.h>
 #include <stdlib.h>
-#include "assert.h"
+#include <assert.h>
 // #include "libgpu.h"
 // #include "libetc.h"
 // #include "libgte.h"
@@ -14,16 +14,16 @@
 #include "duffle/gp.h"
 #include "duffle/gte.h"
-#	include "duffle/gen/duffle.macs.h"
+#	include "duffle/gen/macs.h"
-#	include "duffle/gen/duffle.offsets.h"
+#	include "duffle/gen/offsets.h"
 #include "duffle/atom_dsl.h"
 #include "duffle/lottes_tape.h"
 #include "duffle/word_count.metadata.h"
-#	include "gen/gte_hello.offsets.h"
+#	include "gen/offsets.h"
 #include "hello_gte.h"
-#include "hello_gte_tape.c"
+#include "hello_gte.tape.c"
 typedef U4 OrderingTable_Buffer[OrderingTbl_Len];
 typedef Array_(OrderingTable_Buffer, 2);
@@ -99,8 +99,13 @@ typedef Struct_(Ent_Floor) {
 	A2_V3_S2 faces;
 };
-enum { scratchpad_size = 1024, };
+enum { 
 	Scratchpad_Len = 1024, 
 	MemTape_Len    = 512,
 };
 typedef Struct_(SMemory) {
 	U4 MemTape[MemTape_Len];
 	DoubleBuffer            screen_buf;
 	A2_OrderingTable_Buffer ordering_tbl;
 	PrimitiveArena          primitives;
@@ -117,7 +122,7 @@ global SMemory smem;
 extern SMemory smem;
 // TODO(Ed):
-FI_ U4* spad_warm(MipsAtom atom) {
+FI_ U4* spad_warm(Slice_MipsCode atom) {
 	return nullptr;
 }
@@ -182,6 +187,7 @@ void gp_display_frame(DoubleBuffer* screen_buf, S4* active_buf_id, U4* ordering_
 void render(void) {
 }
 GCC_OPTIMIZATION_DISABLE
 void update(PrimitiveArena* pa, U4* ordering_buf) 
 {
 	orderingtbl_clear_reverse(ordering_buf, OrderingTbl_Len);
@@ -207,6 +213,8 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 	A2_S2 p;    //???
 	S4 flag; //????
 	TapeBuilder tb = tb_make(slice_ut_arr(smem.MemTape));
 	// Draw Cube
 	if (0)
 	{
@@ -259,8 +267,7 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		U4 prim_base   = u4_(pa->buf[smem.active_buf_id]);
 		U4 prim_cursor = prim_base + pa->used;
-		LP_ U4 mem_temp_tape[512]; FArena tape_arena; farena_init(& tape_arena, slice_ut_arr(mem_temp_tape));
+		tb.used = 0; tb_scope(& tb) {
 		TapeBuilder tb = tb_make_old(&tape_arena); tb_scope(& tb) {
 			tb_emit(& tb, rbind_cube_g4_face);
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.cube.faces));
@@ -344,12 +351,11 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		U4 prim_base   = u4_(pa->buf[smem.active_buf_id]);
 		U4 prim_cursor = prim_base + pa->used;
-		// TODO(Ed): We should do a bounds check beforehand to confirm pa can hold all tris.
+		// TODO(Ed): We should do a bounds check beforehand to confirm pa can hold all tris?
 		// The tape atoms in-flight should not need to care.
 		// Prepare the tape. (Push protocol to tape)
-		LP_ U4 mem_temp_tape[512];
+		tb.used = 0; tb_scope(& tb) {
 		TapeBuilder tb = tb_make(slice_ut_arr(mem_temp_tape)); tb_scope(& tb) {
 			tb_emit(& tb, set_gte_world);
 				tb_data(& tb, u4_(& smem.tform_world));
@@ -367,25 +373,18 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
 		tape_run(tb_slice(tb));// Fire off the tape.
 		// C-side state (pa->used) has already been updated by the tape!
 		smem.floor.rot.y += 5;
 	}
 	// --- TAPE DIAGNOSTICS ---
-	if (1)
+	if (0)
 	{
 		LP_ U4 mem_temp_tape[512]; FArena tape_arena; farena_init(& tape_arena, slice_ut_arr(mem_temp_tape));
 		TapeBuilder tb = tb_make_old(& tape_arena); tb_scope(& tb) {
 			// Skip set_gte_world atom for diagnostics to isolate the triangle loop
 			for (U4 i = 0; i < Floor_num_faces; i++) {
 				// =======================================================
 				// SWAP EMIT TO TEST DIFFERENT PARTS OF THE PIPELINE:
 				// =======================================================
 				// 1. code_diag_yield -> Tests Tape Engine jump logic
 				// 2. code_diag_color -> Tests OT and Prim Arena memory
 				// 3. code_diag_gte   -> Tests Vertex arrays and GTE Math
 				// tb_emit(& tb, code_diag_yield);
 				// tb_emit(& tb, code_diag_color);
 				// tb_emit(& tb, code_diag_gte); 
@@ -394,9 +393,9 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		B1* prim_cursor = (B1*)r_(pa->buf)[smem.active_buf_id] + pa->used;
 		tape_run(tb_slice(tb));
 		pa->used = (U4)prim_cursor - (U4)r_(pa->buf)[smem.active_buf_id];
 		smem.floor.rot.y += 5;
 	}
 }
 GCC_OPTIMIZATION_ENABLE
 int main(void)
 {
@@ -0,0 +1,218 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	include "duffle/gen/macs.h"
 #	include "duffle/gen/offsets.h"
 #	include "duffle/atom_dsl.h"
 #	include "duffle/lottes_tape.h"
 #	include "duffle/word_count.metadata.h"
 #	include "gen/offsets.h"
 #	include "hello_gte.h"
 #endif
 #pragma region MACs (Mips Atom components)
 #pragma endregion MACs
 #pragma region Baked Atoms
 /* DIAGNOSTIC 1: Pure tape loop test */
 internal MipsAtom_(diag_yield) { mac_yield() };
 /* DIAGNOSTIC 2: Pure memory test (No GTE). Draws a fixed cyan triangle. */
 internal MipsAtom_(diag_color) {
 	store_word(  R_0, R_T7, 0), 
 	load_upper_i(R_AT, gp0_cmd_poly_f3 << 8 | 0xFF), /* High: MipsCode Poly_F3(0x20) + Color B:FF */
 	or_i_self(   R_AT, 0xFF00),                      /* Low:  Color G:FF, R:00 (Cyan) */
 	store_word(  R_AT, R_T7, 4),
 	/* Fake coordinates - Swapped winding order to prevent GPU culling! */
 	load_upper_i(R_AT, 0x0010), or_i_self(R_AT, 0x0010), store_word(R_AT, R_T7, 8),  /* (16, 16) */
 	load_upper_i(R_AT, 0x0050), or_i_self(R_AT, 0x0010), store_word(R_AT, R_T7, 12), /* (80, 16) */
 	load_upper_i(R_AT, 0x0010), or_i_self(R_AT, 0x0050), store_word(R_AT, R_T7, 16), /* (16, 80) */
 	add_ui(          R_T1, R_0,  10),
 	shift_lleft_self(R_T1,       S_(U4)/2), 
 	add_u_self(      R_T1,       R_T6),         
 	load_word(   R_AT, R_T1, 0),        
 	load_upper_i(R_V0, (S_(Poly_F3)/S_(U4) - S_(PolyTag)/S_(U4)) << PolyTag_len_bits),
 	store_word(  R_AT, R_T7, 0),       
 	shift_lleft(R_AT, R_T7, S_(PolyTag_len_bits)), shift_lright(R_AT, R_AT, S_(PolyTag_len_bits)),         
 	or_u_self(  R_AT, R_V0),          
 	store_word( R_AT, R_T1, 0),       
 	add_ui(R_T7, R_T7, 20),          
 	mac_yield()
 };
 /* DIAGNOSTIC 3: Pure GTE test (No Memory Writes) */
 internal MipsAtom_(diag_gte) {
 	/* Load 3 indices */
 	load_half_u(R_T0, R_T4, 0),
 	load_half_u(R_T1, R_T4, 2),
 	load_half_u(R_T2, R_T4, 4),
 	/* Load Vertices into GTE */
 	shift_lleft( R_AT, R_T0, 3), add_u(    R_AT, R_AT, R_T5),
 	load_word(R_V0, R_AT, 0), load_word(R_V1, R_AT, 4),
 	gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
 	shift_lleft( R_AT, R_T1, 3), add_u(R_AT, R_AT, R_T5),
 	load_word(R_V0, R_AT, 0), load_word(R_V1, R_AT, 4),
 	gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
 	shift_lleft(R_AT, R_T2, 3), add_u(R_AT, R_AT, R_T5),
 	load_word(R_V0, R_AT, 0), load_word(R_V1, R_AT, 4),
 	gte_mv_to_data_r(R_V0, C2_VXY2), gte_mv_to_data_r(R_V1, C2_VZ2),
 	/* Run Math */
 	nop2, gte_cmdw_rtpt,
 	nop2, gte_cmdw_nclip,
 	nop2,
 	/* Advance Face Cursor and Yield */
 	add_ui(R_T4, R_T4, 8),
 	mac_yield()
 };
 typedef Struct_(Binds_CubeTri) {
 	U4     PrimCursor;
 	V4_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_phase(cube_g4)
 ,	atom_reads(R_TapePtr)
 ,	atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
 // cube_g4_face — Draw one cube face (Gouraud-shaded quad) via the GTE tape pipeline
 internal
 MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 		atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase),
 		atom_writes(R_PrimCursor, R_FaceCursor)
 ){
 	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)),
 	mac_gte_load_tri_verts(R_T0, R_T1, R_T2),
 	nop2, gte_cmdw_rotate_translate_perspective_triple, // required cpu -> gte delay slot
 	gte_cmdw_nclip,
 	gte_mv_from_data_r(R_T0, C2_MAC0), nop,
 	branch_le_zero(R_T0, atom_offset(cull, cube_g4_face_exit)), nop,
 		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)),
 		gte_mv_to_data_r(R_V0, C2_VXY0),       gte_mv_to_data_r(R_V1, C2_VZ0),
 		mac_gte_store_g4_p012(),
 		gte_cmdw_rotate_translate_perspective_single,
 		mac_gte_store_g4_p3(),
 		gte_cmdw_avg_sort_z4,
 		gte_mv_from_data_r(R_T1, C2_OTZ),
 		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,
 			mac_insert_ot_tag_g4(),
 			mac_format_g4_color(
 				/* c0 magenta */ 0xFF, 0x00, 0xFF,
 				/* c1 yellow  */ 0xFF, 0xFF, 0x00,
 				/* c2 cyan    */ 0x00, 0xFF, 0xFF,
 				/* c3 green   */ 0x00, 0xFF, 0x00),
 		// end: branch(bounds_chk)
 // end: branch(cull)
 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()
 };
 typedef Struct_(Binds_FloorTri) {
 	U4     PrimCursor;
 	V3_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal
 MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri), atom_phase(floor_f3)
 	, atom_reads(R_TapePtr)
 	, atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_FloorTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 // atom_dbg_skip
 internal
 MipsAtom_(floor_f3_face) atom_info(atom_phase(floor_f3)
 	, atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 	, atom_writes(R_PrimCursor, R_FaceCursor)
 ) {
 	mac_load_tri_indices(  R_T0, R_T1, R_T2),
 	mac_gte_load_tri_verts(R_T0, R_T1, R_T2),
 	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. 
 		/* Format Primitive */
 		mac_gte_store_f3(),
 		/* Calculate Depth */
 		gte_avg_sort_z3,
 		gte_mv_from_data_r(R_T1, C2_OTZ),
 		/* Bounds Check OTZ < OrderingTbl_Len (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,
 			mac_format_f3_color(0xFF, 0xFF, 0xFF),  // RGB-form (R=FF, G=FF, B=FF = white)
 			mac_insert_ot_tag_f3(),                 /* Insert into Ordering Table Linked List */
 			add_ui_self(R_PrimCursor, S_(Poly_F3)), /* Advance Prim Cursor (5 words) */
 				// Note(Ed): No bounds checking, should be checked before atom runs.
 		// end: branch(bounds_chk)
 // end: branch(culling)
 /* 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()
 };
 typedef Struct_(Binds_SyncPrimitiveArena) { U4 used; U4 cursor; };
 internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitiveArena)
 	, atom_reads( R_TapePtr, R_PrimCursor)
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
 	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor
 	store_word(R_T0, R_AT, 0),            // R_AT[0] = R_T0
 	mac_yield()
 };
 #pragma endregion Baked Atoms
@@ -0,0 +1,41 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #pragma once
 #endif
 // Auto-generated by ps1_meta.lua — DO NOT EDIT
 // Directory: C:\projects\Pikuma\ps1\code\hello_joypad/
 //   source: C:\projects\Pikuma\ps1\code\hello_joypad\hello_joypad.c
 //   source: C:\projects\Pikuma\ps1\code\hello_joypad\hello_joypad.h
 //   source: C:\projects\Pikuma\ps1\code\hello_joypad\hello_joypad.atom.c
 // Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)
 #ifndef WORD_COUNT
 #define WORD_COUNT(name, count)  enum { words_##name = (count) };
 #endif
 #define mac_put_disp_env(reg_transfer, reg_base, port) \
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_set_mask_bit(),                 reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port)
 WORD_COUNT(mac_put_disp_env, 5)
 #define mac_put_draw_env(reg_transfer, reg_base, port) \
 	mac_gcmd_push(gp0_dr_env_tag,                            reg_transfer, reg_base, port) /* tag (length=15 << 24, addr=0) — packet header for the DR_ENV sequence. The GPU needs this to recognize the next 15 words as a DR_ENV packet and trigger the isbg auto-clear. */ \
 ,	mac_gcmd_push(gp0_word_draw_mode_drawing_allowed,        reg_transfer, reg_base, port) /* code[0]  DrawMode (dfe=1, dtd=0, tpage=0) */ \
 ,	mac_gcmd_push(gp0_word_set_texture_window(),             reg_transfer, reg_base, port) /* code[1]  TextureWindow (tw=(0,0)) */ \
 ,	mac_gcmd_push(enc_gp0_draw_area_tl_word(0, ScreenRes_Y), reg_transfer, reg_base, port) /* code[2]  DrawArea top-left (clip.x=0, clip.y=ScreenRes_Y=240) */ \
 ,	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240,   reg_transfer, reg_base, port) /* code[3]  DrawArea bottom-right (clip.x+w=320, clip.y+h=480) */ \
 ,	mac_gcmd_push(gp0_word_set_draw_offset(),               reg_transfer, reg_base, port) /* code[4]  DrawOffset (ofs=(0,0)) — bare-cmd word; the GPU uses the current state machine. */ \
 ,	mac_gcmd_push(gp0_word_dr_env_mask(),                   reg_transfer, reg_base, port) /* code[5]  Mask (dtd=0, dfe=1, isbg=1) — 0xE6 cmd + isbg bit. */ \
 ,	mac_gcmd_push(gp0_word_dr_env_bg_color_cmd(1, 7, 7, 7), reg_transfer, reg_base, port) /* code[6]  Initial-bg-color + auto-clear (isbg=1, r=7, g=7, b=7). */ \
 ,	mac_gcmd_push(gp0_word_dr_env_draw_mode(1),             reg_transfer, reg_base, port) /* code[7]  Re-assert DrawMode with isbg=1 (isbg-flag set; the 0xE1 cmd byte plus isbg only). */	/* code[8..10]  Padding (NOP — GPU discards; the DR_ENV requires 16 words total). */ \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port)	/* code[11..12]  TextureWindow bottom-right (tw.x+tw.w=0, tw.y+tw.h=0) — libpsyx emits twice. */ \
 ,	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port)	/* code[13..14]  Padding (NOP) — completes the 16-word packet. */ \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port) \
 ,	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port)
 WORD_COUNT(mac_put_draw_env, 16)
@@ -0,0 +1,76 @@
 // Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT
 // Directory: C:\projects\Pikuma\ps1\code\hello_joypad\
 //   source: C:\projects\Pikuma\ps1\code\hello_joypad\hello_joypad.c
 //   source: C:\projects\Pikuma\ps1\code\hello_joypad\hello_joypad.h
 //   source: C:\projects\Pikuma\ps1\code\hello_joypad\hello_joypad.atom.c
 #pragma once
 #pragma region hello_joypad
 // --- atom: cube_g4_face (76 words) ---
 #define _atom_offset_cull_cube_g4_face_exit           41
 #define _atom_offset_bounds_chk_cube_g4_face_exit     24
 enum {
    atom_offset_cull_cube_g4_face_exit = _atom_offset_cull_cube_g4_face_exit,
    atom_offset_bounds_chk_cube_g4_face_exit = _atom_offset_bounds_chk_cube_g4_face_exit,
 };
 // --- atom: floor_f3_face (58 words) ---
 #define _atom_offset_culling_floor_f3_face_exit       25
 #define _atom_offset_bounds_chk_floor_f3_face_exit    16
 enum {
    atom_offset_culling_floor_f3_face_exit = _atom_offset_culling_floor_f3_face_exit,
    atom_offset_bounds_chk_floor_f3_face_exit = _atom_offset_bounds_chk_floor_f3_face_exit,
 };
 // --- atom: pad_bios_snapshot (78 words) ---
 #define _atom_offset_snap_root_skip_disconnected      8
 #define _atom_offset_disconnected_snap_end            61
 #define _atom_offset_case_2_id_dispatch               8
 #define _atom_offset_pending_snap_end                 51
 #define _atom_offset_id_dispatch_try_analog_stick     11
 #define _atom_offset_id_dispatch_snap_end             38
 #define _atom_offset_try_analog_stick_try_analog_pad  12
 #define _atom_offset_analog_stick_snap_end            24
 #define _atom_offset_try_analog_pad_try_unsupported   11
 #define _atom_offset_analog_pad_snap_end              10
 enum {
    atom_offset_snap_root_skip_disconnected = _atom_offset_snap_root_skip_disconnected,
    atom_offset_disconnected_snap_end = _atom_offset_disconnected_snap_end,
    atom_offset_case_2_id_dispatch = _atom_offset_case_2_id_dispatch,
    atom_offset_pending_snap_end = _atom_offset_pending_snap_end,
    atom_offset_id_dispatch_try_analog_stick = _atom_offset_id_dispatch_try_analog_stick,
    atom_offset_id_dispatch_snap_end = _atom_offset_id_dispatch_snap_end,
    atom_offset_try_analog_stick_try_analog_pad = _atom_offset_try_analog_stick_try_analog_pad,
    atom_offset_analog_stick_snap_end = _atom_offset_analog_stick_snap_end,
    atom_offset_try_analog_pad_try_unsupported = _atom_offset_try_analog_pad_try_unsupported,
    atom_offset_analog_pad_snap_end = _atom_offset_analog_pad_snap_end,
 };
 // --- atom: pad_apply_input (60 words) ---
 #define _atom_offset_dpad_left_exit_dpad_left         6
 #define _atom_offset_dpad_right_exit_dpad_right       6
 #define _atom_offset_dead_zone_low_check_dead_low_active  8
 #define _atom_offset_dead_zone_high_check_dead_high_active  15
 #define _atom_offset_dead_zone_skip_exit_stick        24
 #define _atom_offset_end_low_exit_stick               12
 enum {
    atom_offset_dpad_left_exit_dpad_left = _atom_offset_dpad_left_exit_dpad_left,
    atom_offset_dpad_right_exit_dpad_right = _atom_offset_dpad_right_exit_dpad_right,
    atom_offset_dead_zone_low_check_dead_low_active = _atom_offset_dead_zone_low_check_dead_low_active,
    atom_offset_dead_zone_high_check_dead_high_active = _atom_offset_dead_zone_high_check_dead_high_active,
    atom_offset_dead_zone_skip_exit_stick = _atom_offset_dead_zone_skip_exit_stick,
    atom_offset_end_low_exit_stick = _atom_offset_end_low_exit_stick,
 };
 #pragma endregion hello_joypad
@@ -0,0 +1,638 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #		include "duffle/gen/macs.h"
 #		include "duffle/gen/offsets.h"
 #	include "duffle/dsl.atom.h"
 #	include "duffle/lottes_tape.h"
 #	include "duffle/mips.h"
 #	include "duffle/gte.h"
 #	include "duffle/gp.h"
 #	include "duffle/pad.h"
 #	include "duffle/word_count.metadata.h"
 #	include "duffle/psyq.h"
 #	include "duffle/math.atom.c"
 #	include "duffle/mips.atom.c"
 #	include "duffle/gte.atom.c"
 #	include "duffle/gp.atom.c"
 #	include "duffle/psyq.atom.c"
 #		include "gen/offsets.h"
 #		include "gen/macs.h"
 #	include "hello_joypad.h"
 #endif
 ATOM_FILE_DEBUGGER_LINE_MARKER(hello_joypad_atom_c);
 #pragma region MACs (Mips Atom components)
 FI_ Slice_MipsCode ac_put_disp_env(U4 reg_transfer, U4 reg_base, U2 port)
 MipsAtomComp_Proc_(ac_put_disp_env, {
 	// 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),
 	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_set_mask_bit(),                 reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240, reg_transfer, reg_base, port),
 })
 FI_ Slice_MipsCode ac_put_draw_env(U4 reg_transfer, U4 reg_base, U2 port)
 MipsAtomComp_Proc_(ac_put_draw_env, {
 	/*
 	* ORIGIN: each code word corresponds to the EXACT value libpsyx's PutDrawEnv function would compute for the same DrawEnv settings.
 	* References:
 	*   - libpsyx source: `toolchain/psyq-4_7/lib/libgpu.a` (binary, function `PutDrawEnv`)
 	*   - PSX-SPX doc:     https://problemkaputt.de/psx-spx.htm#gputdrawingcommands
 	*   - PSYQ SDK:        `setdrawenv` / `makelongdr_env` source
 	*   - NOCASH PSX spec: §"GP0(E1h) Draw Mode setting" through §"DR_ENV"
 	*
 	* The 16-word format is documented in the PSYQ SDK manual and on NOCASH's PSX-spec.txt. The libpsyx reference is at:
 	*   ./toolchain/psyq-4_7/lib/libgpu.a
 	*   (binary; the PutDrawEnv implementation builds the 16-word DR_ENV from the user's DRAWENV struct and emits it via GP0 GPU commands.)
 	*
 	* Word indices (libpsyx PutDrawEnv / SetDrawEnv order):
 	*   tag      = (length << 24) | addr                — 16-word packet (1 tag + 15 code)
 	*   code[0]  = DrawMode (dfe=1, dtd=0, tpage=0)     — must come first per libpsyx
 	*   code[1]  = TextureWindow (tw=(0,0))             — bare-cmd word; GPU uses current state
 	*   code[2]  = DrawArea top-left (clip.x=0, clip.y=240)
 	*   code[3]  = DrawArea bottom-right (clip.x+w=320, clip.y+h=480)
 	*   code[4]  = DrawOffset (ofs=(0,0))               — bare-cmd word
 	*   code[5]  = Mask (dtd=0, dfe=1, isbg=1)          — 0xE6 cmd + isbg bit
 	*   code[6]  = Initial-bg-color (isbg=1, r=7, g=7, b=7)
 	*   code[7]  = DrawMode (isbg=1, tpage=0)           — re-asserts DrawMode with isbg
 	*   code[8..10]  = padding (NOP)                    — 3 words to fill the packet
 	*   code[11..12] = TextureWindow bottom-right       — defaults to (0,0,0,0)
 	*   code[13..14] = padding (NOP)                    — completes the 16-word packet
 	*/
 	mac_gcmd_push(gp0_dr_env_tag,                            reg_transfer, reg_base, port), /* tag (length=15 << 24, addr=0) — packet header for the DR_ENV sequence. The GPU needs this to recognize the next 15 words as a DR_ENV packet and trigger the isbg auto-clear. */
 	mac_gcmd_push(gp0_word_draw_mode_drawing_allowed,        reg_transfer, reg_base, port), /* code[0]  DrawMode (dfe=1, dtd=0, tpage=0) */
 	mac_gcmd_push(gp0_word_set_texture_window(),             reg_transfer, reg_base, port), /* code[1]  TextureWindow (tw=(0,0)) */
 	mac_gcmd_push(enc_gp0_draw_area_tl_word(0, ScreenRes_Y), reg_transfer, reg_base, port), /* code[2]  DrawArea top-left (clip.x=0, clip.y=ScreenRes_Y=240) */
 	mac_gcmd_push(gp0_word_draw_area_bottom_right_320x240,   reg_transfer, reg_base, port), /* code[3]  DrawArea bottom-right (clip.x+w=320, clip.y+h=480) */
 	mac_gcmd_push(gp0_word_set_draw_offset(),               reg_transfer, reg_base, port), /* code[4]  DrawOffset (ofs=(0,0)) — bare-cmd word; the GPU uses the current state machine. */
 	mac_gcmd_push(gp0_word_dr_env_mask(),                   reg_transfer, reg_base, port), /* code[5]  Mask (dtd=0, dfe=1, isbg=1) — 0xE6 cmd + isbg bit. */
 	mac_gcmd_push(gp0_word_dr_env_bg_color_cmd(1, 7, 7, 7), reg_transfer, reg_base, port), /* code[6]  Initial-bg-color + auto-clear (isbg=1, r=7, g=7, b=7). */
 	mac_gcmd_push(gp0_word_dr_env_draw_mode(1),             reg_transfer, reg_base, port), /* code[7]  Re-assert DrawMode with isbg=1 (isbg-flag set; the 0xE1 cmd byte plus isbg only). */
 	/* code[8..10]  Padding (NOP — GPU discards; the DR_ENV requires 16 words total). */
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	/* code[11..12]  TextureWindow bottom-right (tw.x+tw.w=0, tw.y+tw.h=0) — libpsyx emits twice. */
 	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_set_texture_window(), reg_transfer, reg_base, port),
 	/* code[13..14]  Padding (NOP) — completes the 16-word packet. */
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 	mac_gcmd_push(gp0_word_nop(), reg_transfer, reg_base, port),
 })
 #pragma endregion MACs
 #pragma region Baked Atoms
 enum {
 	R_ScreenX   = R_T5 atom_reg atom_type(U2),
 	R_ScreenY   = R_T6 atom_reg atom_type(U2),
 	R_ScreenBuf = R_T7 atom_reg, /* Caller-pinned: & smem.screen_buf */
 #define R_ScreenBuf_Code R_T7_Code
 };
 //screen_env_init. Mirrors the libpsyx's SetDefDispEnv + SetDefDrawEnv + the manual enable_auto_clear / initial_bg_color writes.
 internal MipsAtom_(screen_env_init) atom_info(atom_phase(screen_init)
 ,	atom_reads(R_T0, R_ScreenX, R_ScreenY, R_ScreenBuf)
 , atom_writes(R_T0, R_ScreenX, R_ScreenY)
 ) {
 	/* 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)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,display_area) + OA_(DoubleBuffer,display,0)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,screen)       + OA_(DoubleBuffer,display,0)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,vinterlace)   + OA_(DoubleBuffer,display,0)),
 	/* display[1] = (0, 240, 320, 240); rest of struct zeroed. */
 	mac_store_rects2(R_0, R_ScreenY, R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DisplayEnv,display_area) + OA_(DoubleBuffer,display,1)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,screen)     + OA_(DoubleBuffer,display,1)),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,vinterlace) + OA_(DoubleBuffer,display,1)),
 	mac_store_rects2(R_0, R_ScreenY, R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DrawEnv,clip_area)         + OA_(DoubleBuffer,draw,0)), /* draw[0].clip_area = (0, 240, 320, 240). C11's SetDefDrawEnv writes clip.y = y_arg. */
 	mac_store_v2s2(  R_0, R_ScreenY,                       R_ScreenBuf, O_(DrawEnv,drawing_offset[0]) + OA_(DoubleBuffer,draw,0)), /* draw[0].drawing_offset[0] = (0, 240); C11 passes y_arg as ofs. */
 	mac_store_v2s2(R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DrawEnv,clip_area.width) + OA_(DoubleBuffer,draw,1)),
 	/* draw[0].texture_window = (0, 0, 0, 0); two word-zeroes cover the full 8-byte tw field. */
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.x)     + OA_(DoubleBuffer,draw,0)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.width) + OA_(DoubleBuffer,draw,0)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,drawing_offset[0].x)  + OA_(DoubleBuffer,draw,1)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.x)     + OA_(DoubleBuffer,draw,1)),
 	store_word(R_0, R_ScreenBuf, O_(DrawEnv,texture_window.width) + OA_(DoubleBuffer,draw,1)),
 	/* draw[0].texture_page = 10 (gp0_tpage_default). C11 SetDefDrawEnv at C11_only.elf:0x8001273C writes the same 0x0A. . */
 	add_ui(R_T0, R_0, gp0_tpage_default), 
 	store_half(R_T0, R_ScreenBuf, O_(DrawEnv,texture_page) + OA_(DoubleBuffer,draw,0)),
 	store_half(R_T0, R_ScreenBuf, O_(DrawEnv,texture_page) + OA_(DoubleBuffer,draw,1)),
 	/* draw[0] control bytes: flag_dither=1, flag_draw_on_display=1 (the dfe bit per psx-spx; libpsyx sets it via `SetDefDrawEnv`'s conditional at C11_only.elf:0x80012728), enable_auto_clear=1. Each byte is named;
 	 * the previous `store_word(R_0, ..., +20)` overwrote all four with zero. */
 	add_ui(R_T0, R_0, 1),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_dither)          + OA_(DoubleBuffer,draw,0)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_draw_on_display) + OA_(DoubleBuffer,draw,0)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,enable_auto_clear)    + OA_(DoubleBuffer,draw,0)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_dither)          + OA_(DoubleBuffer,draw,1)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,flag_draw_on_display) + OA_(DoubleBuffer,draw,1)),
 	store_byte(R_T0, R_ScreenBuf, O_(DrawEnv,enable_auto_clear)    + OA_(DoubleBuffer,draw,1)),
 	/* draw[0].initial_bg_color = (r=7, g=7, b=7). */
 	add_ui(R_T0, R_0, 7), 
 	mac_store_rgb8(R_T0,R_T0,R_T0, R_ScreenBuf, O_(DrawEnv,initial_bg_color) + OA_(DoubleBuffer,draw,0)),
 	mac_store_rgb8(R_T0,R_T0,R_T0, R_ScreenBuf, O_(DrawEnv,initial_bg_color) + OA_(DoubleBuffer,draw,1)),
 	mac_yield(),
 };
 enum {
 	R_IO_BaseAddr = R_T4 atom_reg, /* Caller-pinned: IO_BASE_ADDR = 0x1F800000 */
 #define R_IO_BaseAddr_Code R_T4_Code
 };
 internal MipsAtom_(gp_screen_init) atom_info(atom_phase(screen_init), atom_reads(R_IO_BaseAddr)) {
 	store_word(R_0, R_IO_BaseAddr, GPIO_PORT1_OFFSET),                                   /* GP1(00h) Reset */
 	mac_gcmd_push(gp1_word_ResetCmdBuffer(),   R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(01h) ClearFIFO */
 	mac_gcmd_push(gp1_word_AcknowledgeIRQ(),   R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(02h) AckIRQ */
 	mac_gcmd_push(gp1_word_DisplayOn(),        R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(03h) Display ON */
 	mac_gcmd_push(gp1_word_dma_to_gpu(),       R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(04h) DMADirection=2 (CPU→GPU). libpsyx's per-frame PutDrawEnv/DrawOTag use DMA2; without this the DMA queue never drains. */
 	mac_gcmd_push(gp1_word_StartDisplayArea(), R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),  /* GP1(05h) StartDisplayArea (X=0, Y=0) */
 	/* GP1: DisplayMode + Display Ranges */
 	mac_gcmd_push(gp1_word_display_mode_320x240_15bit_ntsc, R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	mac_gcmd_push(gp1_word_horizontal_range_ntsc,           R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	mac_gcmd_push(gp1_word_vertical_range_ntsc,             R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	/* GTE: SetGeomOffset (OFX, OFY) — ScreenRes_CenterX, ScreenRes_CenterY. */
 	load_upper_i(R_T5, ScreenRes_CenterX), gte_mv_to_ctrl_r(R_T5, gte_cr_OFX_Code),
 	load_upper_i(R_T5, ScreenRes_CenterY), gte_mv_to_ctrl_r(R_T5, gte_cr_OFY_Code),
 	/* GTE: SetGeomScreen (H) — CR26 (per PSX-SPX / libpsyx), value is the raw projection-plane distance, NOT shifted. */
 	add_ui(R_T5, R_0, ScreenZ), gte_mv_to_ctrl_r(R_T5, gte_cr_H_Code),
 	/* GP1: DisplayEnable — bit 0 = 0 (Display ON). */
 	mac_gcmd_push(gp1_word_DisplayOn(), R_T5, R_IO_BaseAddr, GPIO_PORT1_OFFSET),
 	mac_yield(),
 };
 enum {
 	R_PrimCursor = R_T7 atom_reg atom_type(U4*),    /* VRAM output cursor (primitive buffer) */
 	R_FaceCursor = R_T4 atom_reg atom_type(V4_S2*), /* Cube face-index cursor (V4_S2*); floor context switches to V3_S2* via atom_phase */
 	R_VertBase   = R_T5 atom_reg atom_type(V3_S2*), /* Base address of the vertex array */
 	R_OtBase     = R_T6 atom_reg atom_type(U4*),    /* Base address of the Ordering Table */
 #define R_PrimCursor_Code  R_T7_Code
 #define R_FaceCursor_Code  R_T4_Code
 #define R_VertBase_Code    R_T5_Code
 #define R_OtBase_Code      R_T6_Code
 };
 typedef Struct_(Binds_CubeTri) {
 	U4     PrimCursor;
 	V4_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_phase(cube_g4)
 ,	atom_reads(R_TapePtr)
 ,	atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase, R_TapePtr)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
 // cube_g4_face — Draw one cube face (Gouraud-shaded quad) via the GTE tape pipeline
 internal
 MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 		atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase),
 		atom_writes(R_PrimCursor, R_FaceCursor)
 ){
 	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)),
 	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
 	gte_cmdw_nclip,
 	gte_mv_from_data_r(R_T0, C2_MAC0), nop,
 	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, only on the body path. */
 		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)),
 		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),
 		gte_cmdw_rotate_translate_perspective_single,
 		mac_gte_store_g4_p3(R_PrimCursor),
 		gte_cmdw_avg_sort_z4,
 		gte_mv_from_data_r(R_T1, C2_OTZ),
 		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,
 			mac_insert_ot_tag_g4(R_OtBase, R_PrimCursor),
 			mac_format_g4_color(R_PrimCursor,
 				/* c0 magenta */ 0xFF, 0x00, 0xFF,
 				/* c1 yellow  */ 0xFF, 0xFF, 0x00,
 				/* c2 cyan    */ 0x00, 0xFF, 0xFF,
 				/* c3 green   */ 0x00, 0xFF, 0x00),
 		// end: branch(bounds_chk)
 // end: branch(cull)
 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()
 };
 typedef Struct_(Binds_FloorTri) {
 	U4     PrimCursor;
 	V3_S2* FaceCursor;
 	V3_S2* VertBase;
 	U4*    OtBase;
 };
 internal
 MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri), atom_phase(floor_f3)
 	, atom_reads(R_TapePtr)
 	, atom_writes(R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase, R_TapePtr)
 ){
 	/* Pop 4 arguments from the tape directly into the workspace registers */
 	load_word(R_PrimCursor, R_TapePtr, O_(Binds_FloorTri,PrimCursor)),
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
 	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 // atom_dbg_skip
 internal
 MipsAtom_(floor_f3_face) atom_info(atom_phase(floor_f3)
 	, atom_reads( R_PrimCursor, R_FaceCursor, R_VertBase, R_OtBase)
 	, 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
 	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. 
 		/* Format Primitive */
 		mac_gte_store_f3(R_PrimCursor),
 		/* Calculate Depth */
 		gte_avg_sort_z3,
 		gte_mv_from_data_r(R_T1, C2_OTZ),
 		/* Bounds Check OTZ < 2048 (Branch forward to skip insertion) */
 		add_ui(      R_AT, R_0,  OrderingTbl_Len),
 		set_lt_u(    R_AT, R_T1, R_AT),
 		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, floor_f3_face_exit)), nop,
 			mac_format_f3_color(R_PrimCursor, 0xFF, 0xFF, 0xFF),  // RGB-form (R=FF, G=FF, B=FF = white)
 			mac_insert_ot_tag_f3(R_OtBase, R_PrimCursor),         /* Insert into Ordering Table Linked List */
 			add_ui_self(R_PrimCursor, S_(Poly_F3)), /* Advance Prim Cursor (5 words) */
 				// Note(Ed): No bounds checking, should be checked before atom runs.
 		// end: branch(bounds_chk)
 	// end: branch(culling)
 /* 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()
 };
 typedef Struct_(Binds_SyncPrimitiveArena) { U4 used; U4 cursor; };
 internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitiveArena)
 	, atom_reads( R_TapePtr, R_PrimCursor)
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
 	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor
 	store_word(R_T0, R_AT, 0),            // R_AT[0] = R_T0
 	mac_yield()
 };
 /* ----- pad_bios_snapshot -----
 * Per-frame snapshot of one BIOS pad buffer into PadState.
 * Decoder (branch ladder on raw[0] status + raw[1] id):
 *   1. raw[0] == 0xFF         -> Disconnected (buttons=0, axes=0x80)
 *   2. raw[0]==0 && raw[1]==0 -> Pending      (buttons=0, axes=0x80)
 *   3. raw[1] == 0x41         -> Digital      (buttons normalized; axes=0x80)
 *   4. raw[1] == 0x53         -> AnalogStick  (buttons normalized; axes from raw[4..7])
 *   5. raw[1] in 0x7x         -> AnalogPad    (buttons normalized; axes from raw[4..7])
 *   6. else                   -> Unsupported  (buttons=0, axes=0x80)
 *
 * Buttons normalization: byte_swap16((~raw_buttons) & 0xFFFF).
 *   raw_buttons    = load_half_u(raw, 2) = raw[2] | (raw[3] << 8).
 *   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)
 */
 enum {
 	R_PadRaw    = R_T0 atom_reg atom_type(U1),
 	R_PadState  = R_T1 atom_reg,
 	R_RawStatus = R_T2 atom_reg,
 	R_RawId     = R_T3 atom_reg,
 };
 typedef Struct_(Binds_PadBiosSnapshot) {
    PadBiosRaw* raw;
    PadState*   state;
 };
 internal MipsAtom_(pad_bios_snapshot) atom_info(atom_bind(Binds_PadBiosSnapshot)
 , atom_reads( R_PadRaw, R_PadState, R_RawStatus, R_RawId, R_T4, R_T5, R_TapePtr)
 , atom_writes(R_PadRaw, R_PadState, R_RawStatus, R_RawId, R_T4, R_T5, R_TapePtr)
 ) {
 	/* === Bind consumption: T0 = raw, T1 = state, advance R_TapePtr by 8. */
 	load_word(R_PadRaw,   R_TapePtr, O_(Binds_PadBiosSnapshot,raw)),
 	load_word(R_PadState, R_TapePtr, O_(Binds_PadBiosSnapshot,state)),
 	add_ui_self(          R_TapePtr, S_(Binds_PadBiosSnapshot)),
 	/* === Read raw[0] (status) + raw[1] (id) */
 	load_byte_u(R_RawStatus, R_PadRaw, 0),
 	load_byte_u(R_RawId,     R_PadRaw, 1),
 atom_label(snap_root) /* === Case 1: Disconnected (status == 0xFF). */
 	add_ui(R_T4, R_0, 0xFF), branch_ne(R_RawStatus, R_T4, atom_offset(snap_root, skip_disconnected)),
 	/* BD-slot: pre-compute PadStatus_Disconnected. Branch reads R_T4=0xFF in EX before this WB completes.
 	 * If branch NOT taken (fall through to pending/id_dispatch), R_T4 is overwritten by the next case body's add_ui — harmless. */
 atom_label(disconnected) /* === Disconnected body. */
 	/* R_T4 = PadStatus_Disconnected from snap_root BD-slot. */
 	store_word(R_T4, R_PadState, O_(PadState,status)),
 	store_half(R_0,  R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	load_upper_i(R_T4, 0x8080), or_i_self(R_T4, 0x8080),
 	store_word(  R_T4,    R_PadState, O_(PadState,left_x)),
 	store_byte(  R_RawId, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(disconnected, snap_end)),
 		/* BD-slot: load next atom's entry point (replaces the nop).
 		 * The unconditional branch always jumps to snap_end, where mac_yield_tail()
 		 * transfers control to R_AtomJmp without re-loading it. */
 		mac_yield_load(),
 atom_label(skip_disconnected)
 	/* === Case 2: Pending (status == 0 && id == 0)
 	 * Combined check: if (status | id) != 0 then skip to id_dispatch.
 	 * Falls through to the Pending case only when both are zero. */
 	or_u_self(R_RawStatus, R_RawId), branch_ne(R_RawStatus, R_0, atom_offset(case_2, id_dispatch)),
 	/* BD-slot: pre-compute PadStatus_Pending. Branch reads R_RawStatus in EX before this WB completes.
 	 * If branch NOT taken (fall through to id_dispatch), R_T4 is overwritten by the digital/analog body add_ui — harmless. */
 atom_label(pending) /* === Pending body */
 	/* R_T4 = PadStatus_Pending from case_2 BD-slot. */
 	store_word(R_T4, R_PadState, O_(PadState,status)),
 	store_half(R_0,  R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	load_upper_i(R_T4, 0x8080), or_i_self(R_T4, 0x8080),
 	store_word(  R_T4,    R_PadState, O_(PadState,left_x)),
 	store_byte(  R_RawId, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(pending, snap_end)),
 		mac_yield_load(),
 atom_label(id_dispatch) /* === Case 3-6: ID dispatch */
 	add_ui(R_T4, R_0, 0x41), branch_ne(R_RawId, R_T4, atom_offset(id_dispatch, try_analog_stick)),
 	/* BD-slot: pre-compute PadStatus_Digital. Branch reads R_RawId in EX before this WB completes.
 	 * If branch NOT taken (fall through to try_analog_stick), R_T4 is overwritten by the analog body add_ui. */
 	/* === Digital body (status, buttons normalize, axes=0x80, id, branch. */
 	/* R_T4 = PadStatus_Digital from id_dispatch BD-slot. */
 	store_word( R_T4, R_PadState, O_(PadState,status)),
 	load_half_u(R_T4, R_PadRaw,   2 * S_(U1)),
 	/* Fill R_T4's load-delay slot with the 0x80808080 axes constant into R_T5
 	 * (R_T5 is dead on this path; it's only consumed at the analog_pad range check). */
 	load_upper_i(R_T5, 0x8080), or_i_self(R_T5, 0x8080),
 	nor_u(      R_T4, R_T4, R_0), /* raw_buttons is already in host bit order; no swap needed */
 	store_half( R_T4, R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	store_word(  R_T5, R_PadState, O_(PadState,left_x)),
 	add_ui(      R_T4, R_0, 0x41),
 	store_byte(  R_T4, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(id_dispatch, snap_end)),
 		mac_yield_load(),
 atom_label(try_analog_stick) /* === Case 4: AnalogStick (id == 0x53)*/
 	add_ui(R_T4, R_0, 0x53), branch_ne(R_RawId, R_T4, atom_offset(try_analog_stick, try_analog_pad)),
 	/* BD-slot: pre-compute PadStatus_AnalogStick. Branch reads R_RawId in EX before this WB completes.
 	 * If branch NOT taken (fall through to try_analog_pad), R_T4 is overwritten by the analog_pad body add_ui. */
 atom_label(analog_stick) /* === AnalogStick body
 	* Axes are loaded as two halfwords: raw[6..7] → left_xy (sh at offset 8), raw[4..5] → right_xy (sh at offset 10).
 	* R_T5 holds left_xy / id-value in turn (it's dead on this path — only consumed at the analog_pad range check). */
 	/* R_T4 = PadStatus_AnalogStick from try_analog_stick BD-slot. */
 	store_word(  R_T4, R_PadState, O_(PadState,status)),
 	load_half_u( R_T4, R_PadRaw,   2 * S_(U1)),           /* R_T4 = raw_buttons */
 	load_half_u( R_T5, R_PadRaw,   6 * S_(U1)),           /* R_T5 = left_xy; fills R_T4's load-delay slot (doesn't read R_T4) */
 	nor_u(       R_T4, R_T4, R_0),                        /* R_T4 = ~raw_buttons */
 	store_half(  R_T4, R_PadState, O_(PadState,buttons)),
 	load_half_u( R_T4, R_PadRaw,   4 * S_(U1)),           /* R_T4 = right_xy; fills R_T5's load-delay slot */
 	store_half(  R_T5, R_PadState, O_(PadState,left_x)),  /* R_T5 settled, store left_xy */
 	store_half(  R_T4, R_PadState, O_(PadState,right_x)),
 	add_ui(      R_T5, R_0, 0x53),                        /* R_T5 = id value (clobbers left_xy, already stored) */
 	store_byte(  R_T5, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(analog_stick, snap_end)),
 		mac_yield_load(),
 atom_label(try_analog_pad) /* === Case 5-6: AnalogPad (id & 0xF0 == 0x70) */
 	and_i(    R_T4, R_RawId, 0xF0),
 	add_ui(   R_T5, R_0,     0x70),
 	branch_ne(R_T4, R_T5, atom_offset(try_analog_pad, try_unsupported)),
 	/* BD-slot: pre-compute PadStatus_AnalogPad. Branch reads R_T4 in EX before this WB completes.
 	 * If branch NOT taken (fall through to try_unsupported), R_T4 is overwritten by the unsupported body add_ui. */
 atom_label(analog_pad) /* === AnalogPad body
 	* Same shape as AnalogStick with AnalogPad status. R_T5 holds left_xy (it's dead on this path). */
 	/* R_T4 = PadStatus_AnalogPad from try_analog_pad BD-slot. */
 	store_word( R_T4, R_PadState, O_(PadState,status)),
 	load_half_u(R_T4, R_PadRaw,   2 * S_(U1)),           /* R_T4 = raw_buttons */
 	load_half_u(R_T5, R_PadRaw,   6 * S_(U1)),           /* R_T5 = left_xy; fills R_T4's load-delay slot */
 	nor_u(      R_T4, R_T4, R_0),                        /* R_T4 = ~raw_buttons */
 	store_half( R_T4, R_PadState, O_(PadState,buttons)),
 	load_half_u(R_T4, R_PadRaw,   4 * S_(U1)),           /* R_T4 = right_xy; fills R_T5's load-delay slot */
 	store_half( R_T5, R_PadState, O_(PadState,left_x)),  /* R_T5 settled, store left_xy */
 	store_half( R_T4, R_PadState, O_(PadState,right_x)),
 	store_byte( R_RawId, R_PadState, O_(PadState,id)),
 	jump_rel(atom_offset(analog_pad, snap_end)),
 		mac_yield_load(),
 atom_label(try_unsupported) /* === Case 7: Unsupported — fall through from the AnalogPad range-check miss. */
 	add_ui(    R_T4, R_0, PadStatus_Unsupported),
 	store_word(R_T4, R_PadState, O_(PadState,status)),
 	store_half(R_0,  R_PadState, O_(PadState,buttons)),
 	/* axes = 0x80808080 (centered) — single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y). */
 	load_upper_i(R_T4, 0x8080), or_i_self(R_T4, 0x8080),
 	store_word(  R_T4, R_PadState, O_(PadState,left_x)),
 	add_ui(      R_T4, R_0, 0xFF),                      /* 0xFF sentinel: "unknown id" */
 	store_byte(  R_T4, R_PadState, O_(PadState,id)),
 	/* Fall through to snap_end. */
 atom_label(no_jump_fallthrough)
 	mac_yield_load(),
 atom_label(snap_end)
 	/* NOT mac_yield() — R_AtomJmp was already loaded in the BD-slot of the case-exit branch. */
 	mac_yield_tail(),
 };
 /* ----- pad_apply_input -----
 * Reads pad[0].buttons + pad[0].left_x; 
 * Applies the input-semantics deltas to cube_rot.y + floor_rot.y:
 *   - D-pad Left:  cube_rot.y += 30, floor_rot.y += 5
 *   - D-pad Right: cube_rot.y -= 30, floor_rot.y -= 5
 *   - Analog stick X (dead zone 0x70..0x90):
 *       cube delta  = (0x80 - left_x) >> 2  (range approx -32..+32)
 *       floor delta = (0x80 - left_x) >> 5  (range approx -4..+4)
 *   - D-pad + analog deltas add when used together.
 *
 * Convention:
 *   pad_state = 0 means no buttons active. 
 *   The fail-safe zero-button value flows through unchanged, so a disconnected/fresh pad produces no rotation.
 *   The branch_le_zero pattern below matches the existing pad_input_demo convention (atom body lines 248/257).
 *
 * Signed-delta trick:
 * load_byte_u zero-extends left_x to 32 bits; sub_u from 0x80 wraps to a SIGNED two's-complement value in the negative range;
 * shift_aright (sra) then correctly sign-extends the shift for both positive (left_x < 0x80) and negative (left_x > 0x80) cases.
 * Digital pads publish left_x = 0x80 → delta = 0 → no rotation, so the analog step is naturally a no-op for digital controllers.
 */
 typedef Struct_(Binds_PadApplyInput) {
    PadState* state;
    V3_S2*    cube_rot;
    V3_S2*    floor_rot;
 };
 enum {
 	R_PadStateT5 = R_T5 atom_reg,
 	R_CubeRot    = R_T1 atom_reg,
 	R_FloorRot   = R_T2 atom_reg,
 };
 internal MipsAtom_(pad_apply_input) atom_info(atom_bind(Binds_PadApplyInput)
 , atom_reads(R_T0, R_CubeRot, R_FloorRot, R_T3, R_T4, R_PadStateT5, R_TapePtr)
 , atom_writes(     R_CubeRot, R_FloorRot)
 ) {
 	/* Pop Binds from tape (state, cube_rot, floor_rot) */
 	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)),
 	/* Load pad[0].buttons into R_T0. */
 	load_word(R_T0, R_PadStateT5, O_(PadState,buttons)), 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, pad0_(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 */
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, 30),
 		add_si(    R_T3, R_T3, 5),
 		store_half(R_T4, R_CubeRot,  O_(V3_S2,y)),
 		store_half(R_T3, R_FloorRot, O_(V3_S2,y)),
 	atom_label(exit_dpad_left)
 	/* D-pad Right: cube_rot.y -= 30, floor_rot.y -= 5. */
 	and_i(R_T3, R_T0, pad0_(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 */
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, -30),
 		add_si(    R_T3, R_T3, -5),
 		store_half(R_T4, R_CubeRot,  O_(V3_S2,y)),
 		store_half(R_T3, R_FloorRot, O_(V3_S2,y)),
 	atom_label(exit_dpad_right)
 	/* 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)),
 	/* 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. */
 	add_ui(R_T4, R_0, 0x70), set_lt_u(R_T4, R_T3, R_T4), branch_ne(R_T4, R_0, atom_offset(dead_zone_low_check, dead_low_active)),
 	add_ui(R_T4, R_0, 0x80), /* BD-slot: pre-load 0x80 for dead_low_active */
 atom_label(dead_check_upper)
 	/* left_x >= 0x70 → check upper bound. */
 	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left_x)), /* reload */
 	add_ui(     R_T4, R_0, 0x90),
 	/* 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)),
 	add_ui(  R_T4, R_0, 0x80), /* BD-slot: pre-load 0x80 for dead_high_active */
 	jump_rel(atom_offset(dead_zone_skip, exit_stick)),
 		mac_yield_load(),
 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`).
 	 * The earlier `load_byte_u(R_T3, ...)` reload was redundant and introduced a load-use hazard on the next `sub_u`.
 	 * R_T4 = 0x80 from the BD-slot of `dead_zone_low_check`'s branch_ne. */
 	sub_u( R_T3, R_T4, R_T3), /* R_T3 = 0x80 - left_x */
 	/* delta = 0x80 - left_x (positive). */
 	/* R_T4 = cube_delta */
 	shift_aright(R_T4, R_T3, 2),
 	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)),
 	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)),
 	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(),
 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`).
 	 * The earlier `load_byte_u(R_T3, ...)` reload was redundant and introduced a load-use hazard on the next `sub_u`.
 	 * R_T4 = 0x80 from the BD-slot of `dead_zone_high_check`'s branch_ne. */
 	sub_u( R_T3, R_T4, R_T3),
 	/* 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,
 	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)),
 	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(),
 atom_label(exit_stick)
 	/* NOT mac_yield() — R_AtomJmp was already loaded in the BD-slot of the dead-zone/exit branch. */
 	mac_yield_tail(),
 };
 #pragma endregion Baked Atoms
@@ -0,0 +1,441 @@
 #pragma region Vendors
 #include <stdio.h>
 #include <stdlib.h>
 #include <assert.h>
 // #include "libgpu.h"
 // #include "libetc.h"
 // #include "libgte.h"
 #pragma endregion Vendors
 #pragma region Duffle Headers
 #	include "duffle/gen/macs.h"
 #	include "duffle/gen/offsets.h"
 #include "duffle/word_count.metadata.h"
 #include "duffle/dsl.h"
 #include "duffle/memory.h"
 #include "duffle/math.h"
 #include "duffle/gcc_asm.h"
 #include "duffle/mips.h"
 #include "duffle/gp.h"
 #include "duffle/gte.h"
 #include "duffle/pad.h"
 #include "duffle/dsl.atom.h"
 #include "duffle/lottes_tape.h"
 #include "duffle/psyq.h"
 #pragma endregion Duffle Headers
 #pragma region Duffle TUs
 #include "duffle/math.atom.c"
 #include "duffle/mips.atom.c"
 #include "duffle/gte.atom.c"
 #include "duffle/gp.atom.c"
 #include "duffle/psyq.atom.c"
 #pragma endregion Duffle TUs
 #pragma region Joypade Headers
 #	include "gen/macs.h"
 #	include "gen/offsets.h"
 #include "hello_joypad.h"
 #pragma region Joypad Headers
 #pragma region Hello Joypad TUs
 #include "hello_joypad.atom.c"
 #pragma endregion Hello Joypad TUs
 enum { 
 	Scratchpad_Len = 1024, 
 	MemTape_Len    = 512,
 };
 typedef Struct_(SMemory) {
 	PrimitiveArena          primitives;
 	A2_OrderingTable_Buffer ordering_tbl;
 	DoubleBuffer            screen_buf;
 	S4                      active_buf_id;
 	U4 MemTape[MemTape_Len];
 	M3_S2 tform_world;
 	Ent_Cube  cube;
 	Ent_Floor floor;
 	PadBiosRaw pad_raw[2];
 	PadState   pad[2];
 	U4_V scratchpad; // d-cache
 };
 global SMemory smem;
 extern SMemory smem;
 I_ B1* prim__alloc(U4 type_width, Str8 type_name) {
 	gknown PrimitiveArena* pa  = & smem.primitives;
 	gknown B1*             buf = (B1*) r_(smem.primitives.buf)[smem.active_buf_id];
 	assert(pa->used + type_width < PrimitiveBuff_Len);
 	B1* next  = buf + pa->used;
 	pa->used += type_width;
 	return next;
 }
 #define prim_alloc(type) (type*)prim__alloc(S_(type), slit( stringify(type)))
 /* Uses ONE 8-byte frame allocated via the compiler's standard prologue.
 * The 4 wasted-arg words for B(12h) InitPAD2 live at [SP+0..15] but are not explicitly allocated.
 * The compiler handles the MIPS O32 "wasted stack" convention for us by treating the B-call as a 4-arg call.
 *
 * The buffer pointers are passed as arguments so the compiler keeps them in callee-saved registers;
 * The B(12h) asm volatile block does NOT clobber those registers (it clobbers only the volatile GPRs + the B-table arg registers explicitly).
 * The C-level writes after the call re-load the pointers from their callee-saved homes.
 *
 * The clobber list for both B-calls names the full BIOS destroy set documented in kernelbios.md:167-174 (R1..R15, R24..R25, R31, HI/LO).
 * The kernel-ABI "volatile GPRs" subset is clb_system; the rest of the destroy set is enumerated explicitly here. */
 NI_ void pad_bios_init_start(PadBiosRaw* raw0, PadBiosRaw* raw1)
 {
 	/* Pin raw0 + raw1 to $a0 + $a1 via rgcc; the B(12h) call uses these directly.
 	 * The `(void)` casts mark them as unread after the call so the compiler doesn't need to move them back. */
 	register PadBiosRaw* p0 rgcc(R_A0) = raw0;
 	register PadBiosRaw* p1 rgcc(R_A1) = raw1;
 	(void)p0; (void)p1;
 	// TODO(Ed): Properly annotate the raw values in the inline asm instructions.
 	// Use enums.
 	/* B(12h) InitPAD2(raw0, 0x22, raw1, 0x22)
 	 *   $a0 = raw0 (rgcc-bound; survives the sequence below)
 	 *   $a1 = raw1 (preserved into $a2 before $a1 is overwritten)
 	 *   $a2 = raw1 (moved from $a1; survives $a1's overwrite)
 	 *   $a3 = 0x22 (immediate)
 	 *   $t1 = 0x12 (function number)
 	 *   $t2 = 0xB0 (BIOS B-table address) */
 	asm volatile(
 		asm_words(
 			or_u(    rarg_2, rarg_1, rdiscard), /* $a2 = $a1 = raw1 */
 			add_ui(  rarg_1, rdiscard, 0x22),   /* $a1 = 0x22 */
 			add_ui(  rarg_3, rdiscard, 0x22),   /* $a3 = 0x22 */
 			add_ui(  rtmp_1, rdiscard, 0x12),   /* $t1 = 0x12 */
 			add_ui(  rtmp_2, rdiscard, 0xB0),   /* $t2 = 0xB0 */
 			call_reg(rtmp_2),                   /* jalr $t2, $ra */
 			nop                                 /* BD slot */
 		)
 		asm_rpins, r_use(p0), r_use(p1)
 		asm_clobber: 
 			rlit(R_AT), 
 			rlit(R_V0), rlit(R_V1), 
 			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_T9),
 			rlit(R_RA),
 			clb_mem_drain
 	);
 	/* The C-level writes re-load the pointers via the parameter names and write 0xFF to each 
 	 * buffer's status byte to mark the initial-state hazard documented in kernelbios.md:1621-1624. */
 	u1_v(raw0)[0] = 0xFF;
 	u1_v(raw1)[0] = 0xFF;
 	/* B(13h) StartPAD2() — no args. The BIOS preserves $sp. */
 	asm volatile(
 		asm_words(
 			add_ui(  rtmp_1, rdiscard, 0x13), /* $t1 = 0x13 */
 			add_ui(  rtmp_2, rdiscard, 0xB0), /* $t2 = 0xB0 (re-load) */
 			call_reg(rtmp_2),                 /* jalr $t2, $ra */
 			nop                               /* BD slot */
 		)
 		asm_clobber:
 			rlit(R_AT),
 			rlit(R_V0), rlit(R_V1),
 			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_T9),
 			rlit(R_RA),
 			clb_mem_drain
 	);
 }
 GCC_OPTIMIZATION_DISABLE
 void update(PrimitiveArena* pa, U4* ordering_buf) 
 {
 	TapeBuilder tb = tb_make(slice_ut_arr(smem.MemTape));
 	if (0) // Pad Input (dead — kept for the source-as-written record; references the deleted `pad_state` field)
 	{
 		(void)Pad_Left; (void)Pad_Right; /* suppress unused-token warnings */
 		if (false) {
 			smem.cube.rot.y  += 30;
 			smem.floor.rot.y += 5;
 		}
 		if (false) {
 			smem.cube.rot.y  -= 30;
 			smem.floor.rot.y -= 5;
 		}
 	}
 	if (1) // Pad Input (Tape version)
 	{
 		tb.used = 0; tb_scope_run(& tb) {
 			/* BIOS-owned polling: per-frame snapshot of both ports. */
 			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]);
 			/* Per-frame rotation apply: consume pad[0].buttons + pad[0].left_x */
 			tb_emit_(pad_apply_input);
 				tb_data_(state,     & smem.pad[0]);
 				tb_data_(cube_rot,  & smem.cube.rot);
 				tb_data_(floor_rot, & smem.floor.rot);
 		}
 	}
 	orderingtbl_clear_reverse(ordering_buf, OrderingTbl_Len);
 	// Update the position based on acceleration and velocity
 	gknown V3_S4_R pos = & smem.cube.pos;
 	gknown V3_S4_R vel = & smem.cube.vel;
 	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;
 	// Prep
 	S4 nclip = 0;
 	S4 orderingtbl_z = 0;
 	A2_S2 p;    //???
 	S4 flag; //????
 	// Draw Cube
 	if (0)
 	{
 		m3s2_rotation   (& smem.cube.rot,    & smem.tform_world);
 		m3s2_translation(& smem.tform_world, & smem.cube.pos);
 		m3s2_scale      (& smem.tform_world, & smem.cube.scale);
 		// gte_matrix_set_rotation   (& smem.tform_world);
 		gte_matrix_set_translation(& smem.tform_world);
 		for (U4 face_id = 0; face_id < Cube_num_faces; face_id += 1)
 		{
 			Poly_G4* quad = prim_alloc(Poly_G4); set_poly_g4(quad);
 			quad->c0 = rgb8(255,   0, 255);
 			quad->c1 = rgb8(255, 255,   0);
 			quad->c2 = rgb8(  0, 255, 255);
 			quad->c3 = rgb8(  0, 255,   0);
 			V4_S2* face = & smem.cube.faces[face_id];
 			V3_S2* p0   = & smem.cube.verts[face->x];
 			V3_S2* p1   = & smem.cube.verts[face->y];
 			V3_S2* p2   = & smem.cube.verts[face->z];
 			V3_S2* p3   = & smem.cube.verts[face->w];
 			nclip = rtp_avg_nclip_a4_v3s2(
 				p0, p1, p2, p3,
 				& quad->p0, & quad->p1, & quad->p2, & quad->p3,
 				& p, & orderingtbl_z, & flag
 			);
 			if (nclip <= 0) {
 				continue;
 			}
 			if ((orderingtbl_z > 0) && (orderingtbl_z < OrderingTbl_Len)) {
 				orderingtbl_add_primitive(ordering_buf[orderingtbl_z], quad);
 			}
 		}
 		// smem.cube.rot.x +=  6;
 		// smem.cube.rot.y +=  8;
 		// smem.cube.rot.z += 12;
 		smem.cube.rot.y += 30;
 	}
 	// Draw cube (tape method) - two triangles per face
 	if (1)
 	{
 		m3s2_rotation   (& smem.cube.rot,    & smem.tform_world);
 		m3s2_translation(& smem.tform_world, & smem.cube.pos);
 		m3s2_scale      (& smem.tform_world, & smem.cube.scale);
 		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;
 		tb.used = 0; tb_scope(& tb) {
 			tb_emit(& tb, rbind_cube_g4_face);
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.cube.faces));
 				tb_data(& tb, u4_(smem.cube.verts));
 				tb_data(& tb, u4_(ordering_buf));
 			for (U4 i = 0; i < Cube_num_faces; i++) {
 				// Two triangles per quad face: (x,y,z) and (x,z,w)
 				tb_emit(& tb, cube_g4_face);
 			}
 			tb_emit(& tb, sync_primitive_arena);
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
 		tape_run(tb_slice(tb));
 		// smem.cube.rot.y += 30;
 	}
 	// Draw Floor
 	if (0)
 	{
 		m3s2_rotation   (& smem.floor.rot,   & smem.tform_world);
 		m3s2_translation(& smem.tform_world, & smem.floor.pos);
 		m3s2_scale      (& smem.tform_world, & smem.floor.scale);
 		gte_matrix_set_rotation   (& smem.tform_world);
 		gte_matrix_set_translation(& smem.tform_world);
 		for (U4 face_id = 0; face_id < Floor_num_faces; face_id += 1)
 		{
 			Poly_F3* tri = prim_alloc(Poly_F3); set_poly_f3(tri);
 			tri->color   = rgb8(255, 255, 255);
 			V3_S2* face = & smem.floor.faces[face_id];
 			register V3_S2* p0 rgcc(R_T4) = & smem.floor.verts[face->x];
 			register V3_S2* p1 rgcc(R_T5) = & smem.floor.verts[face->y];
 			register V3_S2* p2 rgcc(R_T6) = & smem.floor.verts[face->z];
 			gte_load_v0(p0, R_T4);
 			/*
 			asm volatile( ".word " "%0" ", %1" : : 
 				"i"(((op_lwc2 & OPCODE_MASK) << OPCODE_SHIFT) | ((R_T4 & REG_MASK) << RS_SHIFT) | ((gte_in_v0_xy & REG_MASK) << RT_SHIFT) | (0            & IMM_MASK)),
 				"i"(((op_lwc2 & OPCODE_MASK) << OPCODE_SHIFT) | ((R_T4 & REG_MASK) << RS_SHIFT) | ((gte_in_v0_z  & REG_MASK) << RT_SHIFT) | (GTE_Z_Offset & IMM_MASK)), 
 				"r"(p0) : 
 				"$2", "$8", "$9", "$31", "memory" 
 			);
 			*/
 			gte_load_v1(p1, R_T5);
 			gte_load_v2(p2, R_T6);
 			gte_rtpt();
 			gte_nclip();
 			gte_stotz(& nclip);
 			// nclip = rtp_avg_nclip_a3_v3s2(p0, p1, p2
 			// 	, & tri->p0, & tri->p1, & tri->p2
 			// 	, & p, & orderingtbl_z, & flag
 			// );
 			// if (nclip <= 0) {
 			// 	continue;
 			// }
 			if (nclip > 0 ) {
 				gte_stsxy3(& tri->p0, & tri->p1, & tri->p2);
 				gte_avsz3();
 				gte_stotz(& orderingtbl_z);
 				if ((orderingtbl_z > 0) && (orderingtbl_z < OrderingTbl_Len)) {
 					orderingtbl_add_primitive(ordering_buf[orderingtbl_z], tri);
 				}
 			}
 		}
 		smem.floor.rot.y += 5;
 	}
 	// Draw floor tape method
 	if (1)
 	{
 		m3s2_rotation   (& smem.floor.rot,   & smem.tform_world);
 		m3s2_translation(& smem.tform_world, & smem.floor.pos);
 		m3s2_scale      (& smem.tform_world, & smem.floor.scale);
 		U4 prim_base   = u4_(pa->buf[smem.active_buf_id]);
 		U4 prim_cursor = prim_base + pa->used;
 		// TODO(Ed): We should do a bounds check beforehand to confirm pa can hold all tris?
 		// The tape atoms in-flight should not need to care.
 		// Prepare the tape. (Push protocol to tape)
 		tb.used = 0; tb_scope(& tb) {
 			tb_emit(& tb, set_gte_world);
 				tb_data(& tb, u4_(& smem.tform_world));
 			tb_emit(& tb, rbind_floor_f3_face);
 			// TODO(Ed): Just use a single context struct ref
 				tb_data(& tb, prim_cursor);
 				tb_data(& tb, u4_(smem.floor.faces));
 				tb_data(& tb, u4_(smem.floor.verts));
 				tb_data(& tb, u4_(ordering_buf));
 			for (U4 i = 0; i < Floor_num_faces; i++) {
 				tb_emit(& tb, floor_f3_face);
 			}
 			// After floor_f3_face iterations complete, the primitive arena's used counter needs updating.
 			tb_emit(& tb, sync_primitive_arena);
 				tb_data(& tb, u4_(& pa->used));
 				tb_data(& tb, prim_base);
 		}
 		tape_run(tb_slice(tb));// Fire off the tape.
 		// C-side state (pa->used) has already been updated by the tape!
 		// smem.floor.rot.y += 5;
 	}
 }
 GCC_OPTIMIZATION_ENABLE
 void render(void) {
 }
 void gp_display_frame(DoubleBuffer* screen_buf, S4* active_buf_id, U4* ordering_buf, PrimitiveArena* pa) {
 	draw_sync(0);
 	vsync(0);
 	displayenv_put(& r_(screen_buf->display)[active_buf_id[0] ]);
 	drawenv_put   (& r_(screen_buf->draw)   [active_buf_id[0] ]);
 	{
 		draw_orderingtbl(ordering_buf + OrderingTbl_Len - 1);
 		pa->used = 0;
 	}
 	active_buf_id[0] = ! active_buf_id[0]; // Swap current buffer
 }
 GCC_OPTIMIZATION_DISABLE
 int main(void)
 {
 	smem = (SMemory){0};
 	smem.scratchpad = C_(U4_V, 0x1F800000);
 	// smem.primitives.used = 0;
 	// smem.active_buf_id   = 0;
 	/*Persistent Entity Setup*/{
 		ent_cube128_init(& smem.cube.verts, & smem.cube.faces); {
 			Ent_Cube* cube = & smem.cube;
 			cube->rot    = v3s2(0, 0, 0);
 			cube->scale  = v3s4_fp_one();
 			cube->accel  = v3s4(0, 1, 0);
 			cube->pos    = v3s4(0, -400, 1800);
 		}
 		ent_floor_init(& smem.floor.verts, & smem.floor.faces); {
 			Ent_Floor* floor = & smem.floor;
 			floor->rot   = v3s2(0, 0, 0);
 			floor->pos   = v3s4(0, 450, 1800);
 			floor->scale = v3s4_fp_one();
 		}
 	}
 	TapeBuilder tb = tb_make(slice_ut_arr(smem.MemTape)); {
 		reset_graph(0);
 		/* Direct BIOS: poll both ports during VBlank. */
 		pad_bios_init_start(& smem.pad_raw[0], & smem.pad_raw[1]);
 		/* Pinned registers for the GPU init atom. */
 		register U4*           io_base_addr rgcc(R_IO_BaseAddr) = u4_r(IO_BASE_ADDR);
 		register DoubleBuffer* screen_buf   rgcc(R_ScreenBuf)   = & smem.screen_buf;
 		tb.used = 0; tb_scope_run(& tb) {
 			tb_emit(& tb, screen_env_init);
 			tb_emit(& tb, gp_screen_init);
 		}
 	}
 	while (1) {
 		gknown S4* active_buf_id  = & smem.active_buf_id;
 		gknown U4* ordering_buf   = r_(smem.ordering_tbl)[active_buf_id[0]];
 		gknown PrimitiveArena* pa = & smem.primitives;
 		update(pa, ordering_buf);
 		render();
 		gp_display_frame(& smem.screen_buf, active_buf_id, ordering_buf, pa);
 	};
 	return 0;
 }
 GCC_OPTIMIZATION_ENABLE
@@ -0,0 +1,102 @@
 #ifdef INTELLISENSE_DIRECTIVES
 #	pragma once
 #	include "duffle/dsl.h"
 #	include "duffle/math.h"
 #	include "duffle/gp.h"
 #	include "duffle/pad.h"
 #endif
 enum {
 	// PrimitiveBuff_Len = 4096,
 	// OrderingTbl_Len   = 2048,
 	PrimitiveBuff_Len = 131072,
 	OrderingTbl_Len   = 8192,
 };
 enum {
 	ScreenRes_X = 320,
 	ScreenRes_Y = 240,
 	ScreenZ     = 320,
 	ScreenRes_CenterX = (ScreenRes_X >> 1),
 	ScreenRes_CenterY = (ScreenRes_Y >> 1),
 };
 enum {
 	fp_one = (1 << 12),
 };
 #define v3s4_fp_one() v3s4(fp_one, fp_one, fp_one)
 typedef U4 OrderingTable_Buffer[OrderingTbl_Len];
 typedef Array_(OrderingTable_Buffer, 2);
 typedef B1 PrimitiveBuffer[PrimitiveBuff_Len];
 typedef Array_(PrimitiveBuffer, 2);
 typedef Struct_(PrimitiveArena) {
 	A2_PrimitiveBuffer buf;
 	U4                 used;
 };
 #define Cube_num_verts 8
 typedef Array_(V3_S2, Cube_num_verts);
 #define Cube_num_faces 6
 typedef Array_(V4_S2, Cube_num_faces);
 I_ void ent_cube128_init(A8_V3_S2* verts, A6_V4_S2* faces) {
 	LP_ A8_V3_S2 baked_verts = (A8_V3_S2) {
 		{ -128, -128, -128 },
 		{  128, -128, -128 },
 		{  128, -128,  128 },
 		{ -128, -128,  128 },
 		{ -128,  128, -128 },
 		{  128,  128, -128 },
 		{  128,  128,  128 },
 		{ -128,  128,  128 }
 	};
 	LP_ A6_V4_S2 baked_faces = (A6_V4_S2) {
 		{ 3, 2, 0, 1 },
 		{ 0, 1, 4, 5 },
 		{ 4, 5, 7, 6 },
 		{ 1, 2, 5, 6 },
 		{ 2, 3, 6, 7 },
 		{ 3, 0, 7, 4 },
 	};
 	mem_copy(u4_(verts), u4_(& baked_verts), S_(A8_V3_S2) );
 	mem_copy(u4_(faces), u4_(& baked_faces), S_(A6_V4_S2) );
 	return;
 }
 typedef Struct_(Ent_Cube) {
 	V3_S4 accel;
 	V3_S4 vel;
 	V3_S4 pos;
 	V3_S4 scale;
 	V3_S2 rot;
 	A8_V3_S2 verts;
 	A6_V4_S2 faces;
 };
 #define Floor_num_verts 4
 typedef Array_(V3_S2, Floor_num_verts);
 #define Floor_num_faces 2
 typedef Array_(V3_S2, Floor_num_faces);
 I_ void ent_floor_init(A4_V3_S2* verts, A2_V3_S2* faces) {
 	LP_ A4_V3_S2 baked_verts = (A4_V3_S2) {
 		{ -900, 0, -900 },
 		{ -900, 0,  900 },
 		{  900, 0, -900 },
 		{  900, 0,  900 },
 	};
 	LP_ A2_V3_S2 baked_faces = (A2_V3_S2) {
 		{ 0, 1, 2 },
 		{ 1, 3, 2 },
 	};
 	mem_copy(u4_(verts), u4_(& baked_verts), S_(A4_V3_S2));
 	mem_copy(u4_(faces), u4_(& baked_faces), S_(A2_V3_S2));
 };
 typedef Struct_(Ent_Floor) {
 	V3_S4 accel;
 	V3_S4 pos;
 	V3_S4 scale;
 	V3_S2 rot;
 	A4_V3_S2 verts;
 	A2_V3_S2 faces;
 };
@@ -0,0 +1,659 @@
 #if 0 /* ac_pad_sio_write_pad_state — superseded by pad_bios_snapshot */
 /* ============================================================
 * raw_sio_pad_poll_20260802 — superseded by bios_pad_buffer_snapshot_20260803.
 * The doomed raw-SIO production atoms (ac_pad_sio_write_pad_state,
 * pad_sio_init, pad_sio_step, pad_sio_diag_pin, pad_sio_diag_byte_exchange)
 * reference symbols that were removed from code/duffle/pad.h during
 * Phase 1. Each is wrapped in a narrow `#if 0` so the C compile skips
 * the body while the source-as-written text stays in place for the
 * Phase 5.1 deletion pass. The wrap is removed (and the bodies are
 * deleted) by Phase 5.1 of this track.
 * ============================================================ */
 * Writes the per-port PadState in 5 instructions plus 4 store_word calls (status,
 * buttons, left_x/y/right_x/right_y packed, attempt). The provisional decode publishes
 * 0x0000FFFF buttons + centered axes on every path until response-byte decode lands.
 *
 * Args:
 *   status_val    - the PadSioStatus enum value to publish
 *   state_ptr_reg - the PadState* base (R_PadState at the call site)
 *   scratch_reg   - scratch register for the value being stored (e.g., R_T0)
 *
 * Emits 9 instructions (status/buttons/axes/attempt stores plus the
 * two-instruction zero-extended buttons load).
 */
 FI_ Slice_MipsCode ac_pad_sio_write_pad_state(U4 status_val, U4 state_ptr_reg, U4 scratch_reg)
 MipsAtomComp_Proc_(ac_pad_sio_write_pad_state, {
 	add_ui(scratch_reg, R_0, status_val),
 	store_word(scratch_reg, state_ptr_reg, O_(PadState,status)),
 	/* FIX 2026-08-02: buttons = 0x0000FFFF = "no buttons pressed" in
 	 * libetc convention. Build it with LUI + ORI so addiu does not
 	 * sign-extend 0xFFFF to 0xFFFFFFFF. */
 	load_upper_i(scratch_reg, 0x0000),
 	or_i(scratch_reg, scratch_reg, 0xFFFF),
 	store_word(scratch_reg, state_ptr_reg, O_(PadState,buttons)),
 	add_ui(scratch_reg, R_0, 0x80808080),
 	store_word(scratch_reg, state_ptr_reg, O_(PadState,left_x)),
 	add_ui(scratch_reg, R_0, 0),
 	store_word(scratch_reg, state_ptr_reg, O_(PadState,attempt))
 })
 #endif /* end ac_pad_sio_write_pad_state wrap */
 /* ----- pad_sio_init -----
 * Boot-time SIO0 init. Caller pins R_T6 = sio_base_addr0.
 * Issues SIO CTRL=0x0040 (reset), MODE=0x000D, BAUD=0x0088.
 * (Phase 2 fills the body.)
 */
 #if 0 /* pad_sio_init — superseded by pad_bios_init_start (Phase 1.3) */
 internal MipsAtom_(pad_sio_init) atom_info(atom_phase(pad_init)
 , atom_reads(R_T5, R_T6)
 , atom_writes(R_T5, R_T6)
 ) {
 	/* FIX 2026-08-02: explicitly load the KSEG1 base into R_T6 at the top of
 	 * the atom body. The rgcc(R_PadSioBase) binding in main() pins R_T6 = base
 	 * when main() runs, but $12 is caller-saved per the O32 ABI — when tape_run
 	 * is invoked, R_T6 is fair game. The atom body cannot rely on the value. */
 	load_upper_i(R_T6, pad_IO_KSEG1_BASE >> 16),   /* R_T6 high 16 = 0xBF80 */
 	or_i(R_T6, R_T6, pad_IO_KSEG1_BASE & 0xFFFF),   /* R_T6 = 0xBF800000 */
 	/* SIO CTRL = 0x0040 (reset) */
 	add_ui(R_T5, R_0, pad_SIO_CTRL_RESET),
 	store_half(R_T5, R_T6, pad_SIO_CTRL_OFFSET),
 	/* SIO MODE = 0x000D (MUL1, 8-bit, no parity, idle-high) */
 	add_ui(R_T5, R_0, pad_SIO_MODE_INIT),
 	store_half(R_T5, R_T6, pad_SIO_MODE_OFFSET),
 	/* SIO BAUD = 0x0088 (~250 kHz) */
 	add_ui(R_T5, R_0, pad_SIO_BAUD_INIT),
 	store_half(R_T5, R_T6, pad_SIO_BAUD_OFFSET),
 	mac_yield(),
 };
 #endif /* end pad_sio_init wrap */
 /* ----- pad_sio_step -----
 * Per-frame bounded raw-SIO transaction. Reads PadState pointers + SIO
 * base addresses from Binds_PadSioStep; writes per-port status +
 * buttons + axes into smem.pad[0..1].
 * Body shape (per spec §"Transaction model (per port, per pad_sio_step)"):
 *   port 0: CTRL=CLEANUP → settle → CTRL=port-select → settle → exchange 5
 *           bytes (addr + 0x42 0x00 0x00 0x00) → decode → write PadState[0]
 *           → CTRL=CLEANUP.
 *   port 1: swap scratch regs (sio_base_addr1 → R_PadSioBase, state1 →
 *           R_PadState) → mirror port 0 sequence.
 *
 * Bounded-loop semantics: every countdown is wrapped in
 *   add_ui_self(R_T1, -1) + branch_ne(R_T1, R_0, ...)
 * with a known maximum (pad_SIO_SETTLE_BEFORE_TX=1000, pad_SIO_SETTLE_AFTER_TX=2000,
 * pad_SIO_WAIT_BUDGET=4096). The static-analysis pass currently reports
 * has_loops = true; the follow-up metaprogram track that learns modeled-bounded
 * loops is out of scope here (per spec §"Risks").
 *
 * Scratch register strategy:
 *   R_PadStatus    = R_T4 — RESERVED for port-1 swap (holds state1)
 *   R_PadCountdown = R_T5 — RESERVED for port-1 swap (holds sio_base_addr1)
 *   R_T0           — byte-exchange value + STAT read (clobbered freely)
 *   R_T1           — countdown budget (clobbered freely)
 *   R_PadState     = R_T7 — PadState* (preserved for PadState writes)
 *   R_PadSioBase   = R_T6 — SIO base (preserved through the port)
 *
 * Response decode (Task 3.1 teaching scope):
 *   - status   = PadSioStatus_Digital (hardcoded)
 *   - buttons  = 0xFFFF (no buttons pressed in the provisional libetc
 *                         convention; full response-byte decode is follow-up)
 *   - axes     = 0x80808080 (centered: left_x=0x80, left_y=0x80,
 *                             right_x=0x80, right_y=0x80)
 *   - attempt  = 0
 *   - DualShock handshake (0x43 0x01 → 0x44 0x01 0x03 → 0x43 0x00) is
 *     follow-up scope; the hardcoded digital decode is a placeholder.
 *
 * Both ports raise /CS (CTRL = pad_SIO_CTRL_CLEANUP) before exit. Both ports
 * treat response timeout as PadSioStatus_Disconnected per the spec §"Failure
 * handling" + the canonical per-port timeout semantics.
 */
 #if 0 /* pad_sio_step — superseded by pad_bios_snapshot (Phase 2.1) */
 internal MipsAtom_(pad_sio_step) atom_info(atom_bind(Binds_PadSioStep)
 , atom_reads(R_TapePtr, R_PadSioBase, R_PadState, R_PadStatus, R_PadCountdown)
 , atom_writes(R_PadStatus, R_PadCountdown)
 ) {
 	/* FIX 2026-08-02: explicitly load KSEG1 base into R_PadSioBase (R_T6) at the
 	 * top. The rgcc() binding in main() does NOT survive the tape_run call
 	 * because R_T6 is caller-saved per the O32 ABI. The pad_sio_init atom
 	 * (also in the per-frame tape) reloads R_T6 separately. */
 	load_upper_i(R_PadSioBase, pad_IO_KSEG1_BASE >> 16),
 	or_i(R_PadSioBase, R_PadSioBase, pad_IO_KSEG1_BASE & 0xFFFF),
 	/* Pop Binds from tape (in Binds_PadSioStep declaration order) */
 	load_word(R_PadState,     R_TapePtr, O_(Binds_PadSioStep,state0)),
 	load_word(R_PadStatus,    R_TapePtr, O_(Binds_PadSioStep,state1)),    /* reserved for port-1 swap */
 	load_word(R_PadSioBase,   R_TapePtr, O_(Binds_PadSioStep,sio_base_addr0)),
 	load_word(R_PadCountdown, R_TapePtr, O_(Binds_PadSioStep,sio_base_addr1)),  /* reserved for port-1 swap */
 	add_ui_self(R_TapePtr, S_(Binds_PadSioStep)),
 	/* ============== PORT 0 TRANSACTION ============== */
 	/* Use R_T0 (byte value / STAT read) + R_T1 (countdown) as scratch.
 	 * R_PadStatus (state1) + R_PadCountdown (sio_base_addr1) are preserved
 	 * through the port-0 body and swapped into R_PadSioBase + R_PadState
 	 * at atom_offset(port1_start, ...) below. */
 	/* 1. Cleanup: CTRL = 0x0010 (raise /CS, clear stale status) */
 	add_ui(R_T0, R_0, pad_SIO_CTRL_CLEANUP),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	/* Bounded by pad_SIO_SETTLE_BEFORE_TX = 1000 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_SETTLE_BEFORE_TX),
 atom_label(settle_pre_port0)
 	nop,  /* BD slot */
 	add_ui_self(R_T1, -1),
 	branch_ne(R_T1, R_0, atom_offset(settle_pre_port0, settle_pre_port0)),
 	/* 2. Port-select: CTRL = 0x0003 (TX enable + DTR /CS) for port 0 */
 	add_ui(R_T0, R_0, pad_SIO_CTRL_TX_ENABLE),
 	or_i(R_T0, R_T0, pad_SIO_CTRL_DTR_CS),  /* set /CS line low */
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	/* Bounded by pad_SIO_SETTLE_AFTER_TX = 2000 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_SETTLE_AFTER_TX),
 atom_label(settle_post_port0)
 	nop,
 	add_ui_self(R_T1, -1),
 	branch_ne(R_T1, R_0, atom_offset(settle_post_port0, settle_post_port0)),
 	/* 3. Address byte (0x01) — send + RX-ready wait + read response + RX-drain confirmation */
 	add_ui(R_T0, R_0, pad_PROTO_ADDR),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack0_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack0_port0, ack0_received_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack0_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack0_port0, wait_ack0_port0)),
 	/* RX timeout → mark disconnected; skip to port 1 */
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ack0)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ack0, port1_start)),
 atom_label(ack0_received_port0)
 	/* Read open-bus response byte 0 — discard per docs/psx-spx §controllersandmemorycards.md */
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Confirm RX FIFO drained before sending byte 1. Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel0_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel0_port0, ack_released_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel0_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel0_port0, wait_ackrel0_port0)),
 	/* RX-drain timeout → disconnected; skip to port 1 */
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ackrel0)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ackrel0, port1_start)),
 atom_label(ack_released_port0)
 	/* === Byte 1 (port 0): send 0x42 (cmd read) + RX-ready wait + read response + RX-drain confirmation === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, pad_PROTO_CMD_READ),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack1_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack1_port0, ack1_received_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack1_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack1_port0, wait_ack1_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ack1)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ack1, port1_start)),
 atom_label(ack1_received_port0)
 	/* Read response ID byte — discarded for teaching scope (decode hardcoded). */
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* RX FIFO drain wait. Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel1_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel1_port0, ack_released1_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel1_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel1_port0, wait_ackrel1_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ackrel1)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ackrel1, port1_start)),
 atom_label(ack_released1_port0)
 	/* === Byte 2 (port 0): send 0x00 + RX-ready wait + read response + RX-drain confirmation === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, 0x00),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack2_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack2_port0, ack2_received_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack2_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack2_port0, wait_ack2_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ack2)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ack2, port1_start)),
 atom_label(ack2_received_port0)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel2_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel2_port0, ack_released2_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel2_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel2_port0, wait_ackrel2_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ackrel2)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ackrel2, port1_start)),
 atom_label(ack_released2_port0)
 	/* === Byte 3 (port 0): send 0x00 + RX-ready wait + read response + RX-drain confirmation === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, 0x00),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack3_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack3_port0, ack3_received_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack3_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack3_port0, wait_ack3_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ack3)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ack3, port1_start)),
 atom_label(ack3_received_port0)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel3_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel3_port0, ack_released3_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel3_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel3_port0, wait_ackrel3_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_ackrel3)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_ackrel3, port1_start)),
 atom_label(ack_released3_port0)
 	/* === Byte 4 (FINAL, port 0): send 0x00 + RX-not-empty wait + read final byte === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, 0x00),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_rx4_port0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_rx4_port0, rx4_received_port0)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_rx4_port0)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_rx4_port0, wait_rx4_port0)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port0_from_rx4)
 	branch_equal(R_0, R_0, atom_offset(skip_port0_from_rx4, port1_start)),
 atom_label(rx4_received_port0)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),  /* discard final byte */
 	/* === RESPONSE DECODE (hardcoded for teaching scope) ===
 	 * Per the plan §"Phase 3 task 3.1" + spec §"Architecture":
 	 *   - Full decode (buttons/axes from response bytes) is follow-up scope.
 	 *   - Teaching scope: hardcode digital poll response.
 	 *     status = PadSioStatus_Digital
 	 *     buttons = 0x0000FFFF (no buttons pressed — placeholder)
 	 *     axes = 0x80808080 (left_x=0x80, left_y=0x80, right_x=0x80, right_y=0x80)
 	 *     attempt = 0
 	 */
 atom_label(decode_port0)
 	mac_pad_sio_write_pad_state(PadSioStatus_Digital, R_PadState, R_T0),
 	/* /CS cleanup: raise /CS, clear stale status before exiting port 0. */
 	add_ui(R_T0, R_0, pad_SIO_CTRL_CLEANUP),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	/* ============== PORT 1 SETUP ============== */
 	/* Swap: R_PadCountdown holds sio_base_addr1; R_PadStatus holds state1. */
 atom_label(port1_start)
 	add_u(R_PadSioBase, R_0, R_PadCountdown),  /* sio_base_addr1 → R_PadSioBase */
 	add_u(R_PadState,   R_0, R_PadStatus),     /* state1 → R_PadState */
 	/* ============== PORT 1 TRANSACTION (mirror of port 0) ============== */
 	/* R_PadStatus + R_PadCountdown are no longer reserved (port 1 is the
 	 * last transaction); we still use R_T0/R_T1 as scratch to match port 0. */
 	/* 1. Cleanup: CTRL = 0x0010 (raise /CS, clear stale status) */
 	add_ui(R_T0, R_0, pad_SIO_CTRL_CLEANUP),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	/* Bounded by pad_SIO_SETTLE_BEFORE_TX = 1000 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_SETTLE_BEFORE_TX),
 atom_label(settle_pre_port1)
 	nop,
 	add_ui_self(R_T1, -1),
 	branch_ne(R_T1, R_0, atom_offset(settle_pre_port1, settle_pre_port1)),
 	/* 2. Port-select: CTRL = 0x0003 | (1 << 13) (port 1 select) */
 	add_ui(R_T0, R_0, pad_SIO_CTRL_TX_ENABLE),
 	or_i(R_T0, R_T0, pad_SIO_CTRL_DTR_CS),
 	or_i(R_T0, R_T0, 1 << 13),  /* port 1 select bit (CTRL bit 13 = port select) */
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	/* Bounded by pad_SIO_SETTLE_AFTER_TX = 2000 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_SETTLE_AFTER_TX),
 atom_label(settle_post_port1)
 	nop,
 	add_ui_self(R_T1, -1),
 	branch_ne(R_T1, R_0, atom_offset(settle_post_port1, settle_post_port1)),
 	/* 3. Address byte (0x01) — send + RX-ready wait + read response + RX-drain confirmation */
 	add_ui(R_T0, R_0, pad_PROTO_ADDR),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack0_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack0_port1, ack0_received_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack0_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack0_port1, wait_ack0_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ack0)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ack0, end_atom)),
 atom_label(ack0_received_port1)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel0_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel0_port1, ack_released_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel0_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel0_port1, wait_ackrel0_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ackrel0)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ackrel0, end_atom)),
 atom_label(ack_released_port1)
 	/* === Byte 1 (port 1): send 0x42 (cmd read) + RX-ready wait + read response + RX-drain confirmation === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, pad_PROTO_CMD_READ),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack1_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack1_port1, ack1_received_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack1_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack1_port1, wait_ack1_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ack1)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ack1, end_atom)),
 atom_label(ack1_received_port1)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel1_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel1_port1, ack_released1_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel1_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel1_port1, wait_ackrel1_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ackrel1)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ackrel1, end_atom)),
 atom_label(ack_released1_port1)
 	/* === Byte 2 (port 1): send 0x00 + RX-ready wait + read response + RX-drain confirmation === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, 0x00),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack2_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack2_port1, ack2_received_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack2_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack2_port1, wait_ack2_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ack2)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ack2, end_atom)),
 atom_label(ack2_received_port1)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel2_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel2_port1, ack_released2_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel2_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel2_port1, wait_ackrel2_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ackrel2)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ackrel2, end_atom)),
 atom_label(ack_released2_port1)
 	/* === Byte 3 (port 1): send 0x00 + RX-ready wait + read response + RX-drain confirmation === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, 0x00),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ack3_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_ack3_port1, ack3_received_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ack3_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ack3_port1, wait_ack3_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ack3)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ack3, end_atom)),
 atom_label(ack3_received_port1)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_ackrel3_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_equal(R_T0, R_0, atom_offset(wait_ackrel3_port1, ack_released3_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_ackrel3_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_ackrel3_port1, wait_ackrel3_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_ackrel3)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_ackrel3, end_atom)),
 atom_label(ack_released3_port1)
 	/* === Byte 4 (FINAL, port 1): send 0x00 + RX-not-empty wait + read final byte === */
 	/* Bounded by pad_SIO_WAIT_BUDGET = 4096 iterations. */
 	add_ui(R_T0, R_0, 0x00),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(wait_rx4_port1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(wait_rx4_port1, rx4_received_port1)),
 	add_ui_self(R_T1, -1),
 atom_label(continue_wait_rx4_port1)
 	branch_ne(R_T1, R_0, atom_offset(continue_wait_rx4_port1, wait_rx4_port1)),
 	mac_pad_sio_write_pad_state(PadSioStatus_Disconnected, R_PadState, R_T0),
 atom_label(skip_port1_from_rx4)
 	branch_equal(R_0, R_0, atom_offset(skip_port1_from_rx4, end_atom)),
 atom_label(rx4_received_port1)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),  /* discard final byte */
 	/* === RESPONSE DECODE (port 1) === */
 atom_label(decode_port1)
 	mac_pad_sio_write_pad_state(PadSioStatus_Digital, R_PadState, R_T0),
 	/* /CS cleanup: raise /CS, clear stale status before exiting port 1. */
 	add_ui(R_T0, R_0, pad_SIO_CTRL_CLEANUP),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 atom_label(end_atom)
 	mac_yield(),
 };
 #endif /* end pad_sio_step wrap */
 /* ----- pad_sio_diag_pin -----
 * Per-frame diagnostic counter. The caller binds R_DiagPinScratch to
 * scratch_for_atom_diag_pin for temporary gdb verification.
 */
 #if 0 /* pad_sio_diag_pin — superseded (raw-SIO phase removed) */
 internal MipsAtom_(pad_sio_diag_pin) atom_info(atom_phase(pad_init)
 , atom_reads(R_T0, R_T1, R_DiagPinScratch)
 , atom_writes(R_T0, R_T1, R_DiagPinScratch)
 ) {
 	/* FIX 2026-08-02: explicitly reload R_DiagPinScratch (R_T3 = $t3). Caller-saved
 	 * per O32 ABI; the rgcc binding in main() does not survive tape_run. */
 	load_upper_i(R_DiagPinScratch, 0x8001),
 	or_i(R_DiagPinScratch, R_DiagPinScratch, 0xC800),
 	/* High half = 0xD1A6; low half increments once per atom invocation. */
 	load_word(R_T1, R_DiagPinScratch, 0),
 	nop,
 	add_ui(R_T1, R_T1, 1),
 	and_i(R_T0, R_T1, 0xFFFF),
 	load_upper_i(R_T1, 0xD1A6),
 	or_i(R_T1, R_T1, 0),
 	or_u(R_T1, R_T1, R_T0),
 	store_word(R_T1, R_DiagPinScratch, 0),
 	mac_yield(),
 };
 #endif /* end pad_sio_diag_pin wrap */
 /* ----- pad_sio_diag_byte_exchange -----
 * Temporary two-byte wire probe: sends 0x01 and 0x42, then stores the
 * open-bus byte and response ID in scratch_for_atom_diag_pin.
 */
 #if 0 /* pad_sio_diag_byte_exchange — superseded (raw-SIO phase removed) */
 internal MipsAtom_(pad_sio_diag_byte_exchange) atom_info(atom_phase(pad_init)
 , atom_reads(R_T0, R_T1, R_T2, R_PadSioBase, R_DiagPinScratch)
 , atom_writes(R_T0, R_T1, R_T2, R_PadSioBase, R_DiagPinScratch)
 ) {
 	/* FIX 2026-08-02: explicitly reload R_DiagPinScratch (R_T3 = $t3). Caller-saved
 	 * per O32 ABI; the rgcc binding in main() does not survive tape_run. */
 	load_upper_i(R_DiagPinScratch, 0x8001),
 	or_i(R_DiagPinScratch, R_DiagPinScratch, 0xC800),
 	/* FIX 2026-08-02: explicitly load KSEG1 base into R_PadSioBase (R_T6) at the
 	 * top. The rgcc() binding in main() does NOT survive the tape_run call
 	 * because R_T6 is caller-saved per the O32 ABI. */
 	load_upper_i(R_PadSioBase, pad_IO_KSEG1_BASE >> 16),
 	or_i(R_PadSioBase, R_PadSioBase, pad_IO_KSEG1_BASE & 0xFFFF),
 	add_ui(R_T0, R_0, pad_SIO_CTRL_CLEANUP),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	add_ui(R_T0, R_0, pad_SIO_CTRL_TX_ENABLE),
 	or_i(R_T0, R_T0, pad_SIO_CTRL_DTR_CS),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	add_ui(R_T0, R_0, pad_PROTO_ADDR),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(diag_wait_ack0)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(diag_wait_ack0, diag_ack0_done)),
 	add_ui_self(R_T1, -1),
 	branch_ne(R_T1, R_0, atom_offset(diag_wait_ack0, diag_wait_ack0)),
 	add_ui(R_T0, R_0, 0xDEADAC01),
 	store_word(R_T0, R_DiagPinScratch, 0),
 	branch_equal(R_0, R_0, atom_offset(diag_timeout_ack0, diag_timeout)),
 atom_label(diag_ack0_done)
 	load_byte_u(R_T2, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T0, R_0, pad_PROTO_CMD_READ),
 	store_byte(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	add_ui(R_T1, R_0, pad_SIO_WAIT_BUDGET),
 atom_label(diag_wait_ack1)
 	load_half_u(R_T0, R_PadSioBase, pad_SIO_STAT_OFFSET),
 	nop,
 	and_i(R_T0, R_T0, pad_SIO_STAT_RX_NOT_EMPTY),
 	branch_ne(R_T0, R_0, atom_offset(diag_wait_ack1, diag_ack1_done)),
 	add_ui_self(R_T1, -1),
 	branch_ne(R_T1, R_0, atom_offset(diag_wait_ack1, diag_wait_ack1)),
 	add_ui(R_T0, R_0, 0xDEADAC02),
 	store_word(R_T0, R_DiagPinScratch, 0),
 	branch_equal(R_0, R_0, atom_offset(diag_timeout_ack1, diag_timeout)),
 atom_label(diag_ack1_done)
 	load_byte_u(R_T0, R_PadSioBase, pad_SIO_DATA_OFFSET),
 	nop,
 	shift_lleft(R_T0, R_T0, 8),
 	or_u(R_T2, R_T2, R_T0),
 	store_word(R_T2, R_DiagPinScratch, 0),
 atom_label(diag_success)
 	branch_equal(R_0, R_0, atom_offset(diag_success, diag_done)),
 	nop,
 atom_label(diag_timeout_ack0)
 	add_ui(R_T0, R_0, 0xDEADAC01),
 	store_word(R_T0, R_DiagPinScratch, 0),
 atom_label(diag_timeout_ack1)
 	add_ui(R_T0, R_0, 0xDEADAC02),
 	store_word(R_T0, R_DiagPinScratch, 0),
 atom_label(diag_timeout)
 	add_ui(R_T0, R_0, 0xDEADACFF),
 	store_word(R_T0, R_DiagPinScratch, 0),
 atom_label(diag_done)
 	add_ui(R_T0, R_0, pad_SIO_CTRL_CLEANUP),
 	store_half(R_T0, R_PadSioBase, pad_SIO_CTRL_OFFSET),
 	mac_yield(),
 };
 #endif /* end pad_sio_diag_byte_exchange wrap */
@@ -7,12 +7,12 @@ A rest from the usual.
 ## Dependencies
 I will be programming from a Windows 11 machine (may eventually try this on the Steam Deck...):
 ![system_info](./docs/assets/system_info.png)
 [armips](https://github.com/Kingcom/armips)
 * Supports doing bare-metal assembly for the ps1
 * `scoop install armips` or just clone and build..
 * Was used early in the course. Now I just use an macro asm dsl in C11.
 [luajit-2.1](https://github.com/LuaJIT/LuaJIT.git)
@@ -73,3 +73,9 @@ scoop install luajit
 ![hello_psyq!](./docs/assets/pcsx-redux_2025-08-05_23-01-19.png)
 ![cube!](./docs/assets/pcsx-redux_2025-10-11_03-04-01.png)
 ![cube and floor!](./docs/assets/pcsx-redux_2026-07-10_22-47-02.png)
 Win 11 machine:
 ![system_info](./docs/assets/system_info.png)
 Still haven't gotten around to trying this on linux...
@@ -81,19 +81,6 @@ $path_psyq          = join-path $path_toolchain  'psyq-4_7'
 $path_psyq_iwyu     = join-path $path_toolchain  'psyq_iwyu'
 $path_psyq_imyu_inc = join-path $path_psyq_iwyu  'include'
 function Get-SourceFiles { param([Parameter(Mandatory=$true)] [string[]]$paths, [Parameter(Mandatory=$true)] [string[]]$extensions)
 	$files = @()
 	foreach ($p in $paths) {
 		if (-not (test-path $p)) { continue }
 		foreach ($ext in $extensions) {
 			Get-ChildItem -Path $p -File -Recurse -Filter "*$ext" -ErrorAction SilentlyContinue | ForEach-Object {
 				$files += $_.FullName
 			}
 		}
 	}
 	return ($files | Sort-Object -Unique)
 }
 function assemble-unit { param(
 	[string]  $unit,
 	[string]  $link_module,
@@ -153,7 +140,7 @@ function compile-unit { param(
 		$f_arch_no_shared,
 		$f_arch_no_stack_prot
 	)
-	# $compile_args    += $f_std_c23
+	$compile_args    += $f_std_c11
 	$compile_args    += ($f_include + $path_psyq_imyu_inc)
 	$compile_args    += ($f_include + $path_nugget)
@@ -193,29 +180,18 @@ function link-modules { param([string[]]$link_modules, [string]  $elf, [string[]
 	$link_args += ($f_link_pass_through_prefix + $f_link_mapfile + $map)
 	$link_args += ($f_link_pass_through_prefix + $f_link_start_group)
 	# raw_sio_pad_poll_20260802 — Task 5.1c surgical library-list trim.
 	# The 16 removed entries (c2, card, cd, comb, ds, gs, gun, hmd, math,
 	# mcrd, mcx, press, sio, snd, spu, tap) had LOAD lines in the map but
 	# ZERO .o files pulled in — they were unused. The 5 kept libraries
 	# (api, c, etc, gpu, gte) are required by the C-side calls in
 	# hello_joypad.c (reset_graph, draw_sync, vsync, etc.).
 	$libraries = @(
 		"api",
 		"c",
 		"c2",
 		"card",
 		"cd",
 		"comb",
 		"ds",
 		"etc",
 		"gpu",
-		"gs",
+		"gte"
 		"gte",
 		"gun",
 		"hmd",
 		"math",
 		"mcrd",
 		"mcx",
 		"pad",
 		"press",
 		"sio",
 		"snd",
 		"spu",
 		"tap"
 	)
 	foreach ($lib in $libraries) {
 		$link_args += ($f_link_lib + $lib)
@@ -243,6 +219,119 @@ function make-binary { param([string]$elf, [string]$exe)
 	if ($LASTEXITCODE -ne 0) { Write-Error "Objcopy failed. Aborting."; exit 1 }
 }
 function ps1-meta { param(
 		[string]$unity_root,
 		[string[]]$sources,
 		[Parameter(Mandatory=$true)][string]$metadata,
 		[string]$out_root = (join-path $path_build 'gen'),
 		[string[]]$passes = @('--pre-link'),
 		[string[]]$extra_args = @()
 	)
 	# `--unity-root` and `--source` are
 	# mutually exclusive. Exactly one of `$unity_root` / `$sources` must
 	# be supplied; the other must be absent.
 	if ($null -ne $unity_root -and $unity_root -ne '') 
 	{
 		if ($null -ne $sources -and $sources.Count -gt 0) {
 			write-error 'ps1-meta: -unity_root and -sources are mutually exclusive'
 			exit 2
 		}
 	} 
 	elseif ($null -eq $sources -or $sources.Count -eq 0) {
 		write-error 'ps1-meta: either -unity_root <file> or -sources <file...> is required'
 		exit 2
 	}
 	$script = join-path $path_scripts 'ps1_meta.lua'
 	$input_summary = if ($null -ne $unity_root -and $unity_root -ne '') {
 		"unity=$unity_root"
 	}
 	else {
 		"$($sources.Count) source(s)"
 	}
 	write-host "ps1-meta  $input_summary, passes=$($passes -join ',')" ` -ForegroundColor Magenta
 	$arg_list = @($passes) + @('--metadata', $metadata) + @('--out-root', $out_root) + @($extra_args)
 	if ($null -ne $unity_root -and $unity_root -ne '') {
 		$arg_list += @('--unity-root', $unity_root)
 	}
 	else {
 		foreach ($s in $sources) { $arg_list += @('--source', $s) }
 	}
 	& luajit $script @arg_list
 	if ($LASTEXITCODE -ne 0) {
 		write-error "ps1-meta failed (exit $LASTEXITCODE). Aborting."
 		exit $LASTEXITCODE
 	}
 }
 function inject-dwarf { param(
 	[string]$elf,
 	[string]$path_gen
 )
 	$base_name               = [System.IO.Path]::GetFileNameWithoutExtension($elf)
 	$path_dwarf_line_bin     = join-path $path_gen  "$base_name.dwarf_line.bin"
 	$path_dwarf_aranges_bin  = join-path $path_gen  "$base_name.dwarf_aranges.bin"
 	$path_dwarf_rnglists_bin = join-path $path_gen  "$base_name.dwarf_rnglists.bin"
 	$path_dwarf_info_bin     = join-path $path_gen  "$base_name.dwarf_info.bin"
 	$path_dwarf_abbrev_bin   = join-path $path_gen  "$base_name.dwarf_abbrev.bin"
 	$path_dwarf_str_bin      = join-path $path_gen  "$base_name.dwarf_str.bin"
 	$path_dwarf_loc_bin      = join-path $path_gen  "$base_name.dwarf_loc.bin"
 	$path_dwarf_loclists_bin = join-path $path_gen  "$base_name.dwarf_loclists.bin"
 	$path_inject_elf         = join-path $path_build "$base_name.dwarf-injected.elf"
 	if (-not (Test-Path $path_dwarf_line_bin))     { return }
 	if (-not (Test-Path $path_dwarf_aranges_bin))  { return }
 	if (-not (Test-Path $path_dwarf_rnglists_bin)) { return }
 	Write-Host "[build] DWARF-injecting $elf -> $path_inject_elf"
 	Copy-Item -LiteralPath $elf -Destination $path_inject_elf -Force
 	# Objcopy call 1: 3x --update-section for the PC-mapping tables (line, aranges, rnglists).
 	$objcopy_args_dwarf_pc = @(
 		"--update-section=.debug_line=$path_dwarf_line_bin",
 		"--update-section=.debug_aranges=$path_dwarf_aranges_bin",
 		"--update-section=.debug_rnglists=$path_dwarf_rnglists_bin"
 	)
 	& $Objcopy @objcopy_args_dwarf_pc $path_inject_elf 2>&1 | Out-Null
 	if ($LASTEXITCODE -ne 0) {
 		Write-Warning "[build] objcopy dwarf-pc splice failed (exit $LASTEXITCODE); removing $path_inject_elf"
 		Remove-Item -LiteralPath $path_inject_elf -ErrorAction SilentlyContinue
 		return
 	}
 	# Objcopy call 2: 3x --update-section + 2x --add-section for the debug-data tables (info, abbrev, str, loc, loclists).
 	$objcopy_args_dwarf_info = @(
 		"--update-section=.debug_info=$path_dwarf_info_bin",
 		"--update-section=.debug_abbrev=$path_dwarf_abbrev_bin",
 		"--update-section=.debug_str=$path_dwarf_str_bin",
 		"--add-section=.debug_loc=$path_dwarf_loc_bin",
 		"--add-section=.debug_loclists=$path_dwarf_loclists_bin"
 	)
 	& $Objcopy @objcopy_args_dwarf_info $path_inject_elf 2>&1 | Out-Null
 	if ($LASTEXITCODE -ne 0) {
 		Write-Warning "[build] objcopy dwarf-info splice failed (exit $LASTEXITCODE); removing $path_inject_elf"
 		Remove-Item -LiteralPath $path_inject_elf -ErrorAction SilentlyContinue
 		return
 	}
 	# Baked atoms execute from RAM but are emitted as C data arrays, so their ELF sections lack SHF_EXECINSTR.
 	# GDB discards line rows for non-code sections. Mark only the debug-copy sections executable.
 	# The original ELF and PS-EXE remain byte/flag unchanged.
 	& $Objcopy `
 		--set-section-flags ".rodata=alloc,load,readonly,code,contents" `
 		--set-section-flags ".data=alloc,load,data,code,contents" `
 		$path_inject_elf 2>&1 | Out-Null
 	if ($LASTEXITCODE -ne 0) {
 		Write-Warning "[build] atom-section flag update failed (exit $LASTEXITCODE); removing $path_inject_elf"
 		Remove-Item -LiteralPath $path_inject_elf -ErrorAction SilentlyContinue
 	}
 	else {
 		Write-Host "[build] DWARF-injected ELF: $path_inject_elf"
 	}
 }
 # inject-dwarf
 function build-hello_psyqo {
 	$includes += @()
@@ -317,34 +406,16 @@ function build-graphis_hello {
 }
 # build-graphis_hello
-function ps1-meta { param(
+function build-hello_gte {
 		[Parameter(Mandatory=$true)][string[]]$sources,
 		[Parameter(Mandatory=$true)][string]$metadata,
 		[string]$out_root = (join-path $path_build 'gen'),
 		[string[]]$passes = @('--all'),
 		[string[]]$extra_args = @()
 	)
 	$script = join-path $path_scripts 'ps1_meta.lua'
 	write-host "ps1-meta  $($sources.Count) source(s), passes=$($passes -join ',')" ` -ForegroundColor Magenta
 	$arg_list = @($passes) + @('--metadata', $metadata) + @('--out-root', $out_root) + @($extra_args)
 	foreach ($s in $sources) { $arg_list += @('--source', $s) }
 	& luajit $script @arg_list
 	if ($LASTEXITCODE -ne 0) {
 		write-error "ps1-meta failed (exit $LASTEXITCODE). Aborting."
 		exit $LASTEXITCODE
 	}
 }
 function build-gte_hello {
 	$includes += @()
-	$path_module        = join-path $path_code   'gte_hello'
+	$path_module        = join-path $path_code   'hello_gte'
 	$path_duffle        = join-path $path_code   'duffle'
 	$path_atom_metadata = join-path $path_duffle 'word_count.metadata.h'
 	$path_build_gen     = join-path $path_build   'gen'
-	$source_dirs  = @($path_duffle, $path_module)
+	$src_c = join-path $path_module 'hello_gte.c'
-	$atom_sources = Get-SourceFiles -paths $source_dirs -extensions @('.h', '.c')
+	ps1-meta -unity_root $src_c -metadata $path_atom_metadata -out_root $path_build_gen
 	ps1-meta -sources $atom_sources -metadata $path_atom_metadata -out_root (join-path $path_build 'gen')
 	$assemble_args = @()
 	$assemble_args += $f_debug
@@ -360,7 +431,6 @@ function build-gte_hello {
 	# assemble-unit $src_asm $module_asm $includes $assemble_args
 	$src_c    = join-path $path_module 'hello_gte.c'
 	$module_c = join-path $path_build  'hello_gte_c.o'
 	$compile_args = @()
@@ -379,119 +449,120 @@ function build-gte_hello {
 	$link_args += $f_debug
 	# $link_args += $f_optimize_size
 	$link_modules = @(
-		$module_asm_crt, 
+		$module_asm_crt,
 		$module_c
 	)
 	link-modules $link_modules $elf $link_args
 	make-binary $elf $exe
-	# TODO(Ed): Do both -gdb-runtime and dwarf-injection passes in a single ps1-meta call.
+	# Post-link: gdb-runtime + dwarf-injection in a single Lua invocation (one luajit cold start).
 	ps1-meta -unity_root $src_c -metadata $path_atom_metadata -out_root $path_build_gen -passes @('--post-link') ` -extra_args @('--elf', $elf)
-	# Post-link: emit ONLY build/gen/gdb_tape_atoms_runtime.gdb.
+	inject-dwarf $elf $path_build_gen
 	# The per-source *.atoms.sourcemap.txt was already generated by the pre-link --all call,
 	# so we skip --atoms-source-map here to avoid re-doing the work. 
 	# The gdb-runtime emission requires --elf (for nm-based address lookup) so it MUST happen post-link.
 	ps1-meta -sources $atom_sources -metadata $path_atom_metadata `
 		-out_root (join-path $path_build 'gen') `
 		-passes @('--gdb-runtime') `
 		-extra_args @('--elf', $elf)
 	# F' + G' consolidated: --dwarf-injection now emits 7 .bin blobs 
 	# (.debug_line, .debug_aranges, .debug_rnglists, .debug_info, .debug_abbrev, .debug_str, .debug_loc) all in one pass.
 	ps1-meta -sources $atom_sources -metadata $path_atom_metadata `
 		-out_root (join-path $path_build 'gen') `
 		-passes @('--dwarf-injection') `
 		-extra_args @('--elf', $elf)
 	#TODO(Ed): Move the below into ps-1 meta pass to reduce syscall latency?
 	# F' track: post-link DWARF injection. The new Lua pass writes build/gen/<basename>.dwarf_*.bin blobs; 
 	# we splice them into a COPY of the ELF via objcopy --update-section (works fine from PowerShell).
 	# The un-injected $elf + $exe are unchanged (shipping binary).
 	$dwarfLineBin    = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_line.bin'
 	$dwarfArangesBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_aranges.bin'
 	$dwarfRnglistsBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_rnglists.bin'
 	$injectElf       = Join-Path $path_build 'hello_gte.dwarf-injected.elf'
 	if ((Test-Path $dwarfLineBin) -and (Test-Path $dwarfArangesBin) -and (Test-Path $dwarfRnglistsBin)) 
 	{
 		Write-Host "[build] DWARF-injecting $elf -> $injectElf"
 		Copy-Item -LiteralPath $elf -Destination $injectElf
 		& $Objcopy --update-section ".debug_line=$dwarfLineBin"    $injectElf
 		$last_exit_code_error = $LASTEXITCODE -ne 0
 		if ($last_exit_code_error) {
 			Write-Warning "[build] objcopy .debug_line update failed (exit $LASTEXITCODE); removing $injectElf"
 			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
 			return;
 		} 
 		& $Objcopy --update-section ".debug_aranges=$dwarfArangesBin" $injectElf
 		$last_exit_code_error = $LASTEXITCODE -ne 0
 		if ($LASTEXITCODE -ne 0) {
 			Write-Warning "[build] objcopy .debug_aranges update failed (exit $LASTEXITCODE); removing $injectElf"
 			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
 			return;
 		}
 		& $Objcopy --update-section ".debug_rnglists=$dwarfRnglistsBin" $injectElf
 		if ($LASTEXITCODE -ne 0) {
 			Write-Warning "[build] objcopy .debug_rnglists update failed (exit $LASTEXITCODE); removing $injectElf"
 			Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
 		} 
 		else 
 		{
 			# Baked atoms execute from RAM but are emitted as C data arrays, so their ELF sections lack SHF_EXECINSTR. 
 			# GDB discards line rows for non-code sections. 
 			# Mark only the debug-copy sections executable; the shipping ELF and PS-EXE remain byte/flag unchanged.
 			& $Objcopy `
 				--set-section-flags ".rodata=alloc,load,readonly,code,contents" `
 				--set-section-flags ".data=alloc,load,data,code,contents" `
 				$injectElf
 			if ($LASTEXITCODE -ne 0) {
 				Write-Warning "[build] objcopy atom-section flag update failed (exit $LASTEXITCODE); removing $injectElf"
 				Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
 			} else {
 				Write-Host "[build] DWARF-injected ELF: $injectElf"
 			}
 		}
 	}
 	# G' (atom locals) is now part of --dwarf-injection.
 	# The F' splice block above already covered .debug_line / .debug_aranges / .debug_rnglists;
 	# we extend the same Copy-Item + objcopy chain to splice the G' 4 sections
 	# (.debug_info, .debug_abbrev, .debug_str via --update-section; .debug_loc via --add-section since it doesn't exist in the source ELF).
 	$dwarfInfoBin   = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_info.bin'
 	$dwarfAbbrevBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_abbrev.bin'
 	$dwarfStrBin    = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_str.bin'
 	$dwarfLocBin    = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_loc.bin'
 	if ((Test-Path $dwarfInfoBin) -and (Test-Path $dwarfAbbrevBin) -and (Test-Path $dwarfStrBin) -and (Test-Path $dwarfLocBin)) 
 	{
 		Write-Host "[build] G' atom-locals: splicing .debug_info/.debug_abbrev/.debug_str/.debug_loc into $injectElf"
 		& $Objcopy --update-section ".debug_info=$dwarfInfoBin"     $injectElf
 		$last_exit_code_error = ($LASTEXITCODE -ne 0) 
 		if ($last_exit_code_error) {
 			Write-Warning "[build] objcopy .debug_info update failed (exit $LASTEXITCODE)"
 			return;
 		} 
 		& $Objcopy --update-section ".debug_abbrev=$dwarfAbbrevBin" $injectElf
 		if ($LASTEXITCODE -ne 0) {
 			Write-Warning "[build] objcopy .debug_abbrev update failed (exit $LASTEXITCODE)"
 			return;
 		} 
 		& $Objcopy --update-section ".debug_str=$dwarfStrBin"      $injectElf
 		if ($LASTEXITCODE -ne 0) {
 			Write-Warning "[build] objcopy .debug_str update failed (exit $LASTEXITCODE)"
 		} 
 		else 
 		{
 			# .debug_loc doesn't exist in the source ELF; --add-section creates it.
 			& $Objcopy --add-section ".debug_loc=$dwarfLocBin"     $injectElf
 			if ($LASTEXITCODE -ne 0) {
 				Write-Warning "[build] objcopy .debug_loc add-section failed (exit $LASTEXITCODE)"
 			} else {
 				Write-Host "[build] G' atom-locals-injected: $injectElf"
 			}
 		}
 	}
 }
-build-gte_hello
+# build-hello_gte
 function build-hello_joypad {
 	$includes += @()
 	$path_module        = join-path $path_code   'hello_joypad'
 	$path_duffle        = join-path $path_code   'duffle'
 	$path_atom_metadata = join-path $path_duffle 'word_count.metadata.h'
 	$path_build_gen     = join-path $path_build  'gen'
 	$src_c = join-path $path_module 'hello_joypad.c'
 	ps1-meta -unity_root $src_c -metadata $path_atom_metadata -out_root $path_build_gen
 	$assemble_args = @()
 	$assemble_args += $f_debug
 	$assemble_args += $f_optimize_none
 	$assemble_args += ($f_include + $path_code)
 	$src_asm_crt    = join-path $path_nugget_common 'crt0/crt0.s'
 	$module_asm_crt = join-path $path_build         'crt0.o'
 	assemble-unit $src_asm_crt $module_asm_crt $includes $assemble_args
 	$module_c = join-path $path_build  'hello_joypad_c.o'
 	$compile_args = @()
 	$compile_args += $f_debug
 	$compile_args += $f_optimize_none
 	# $compile_args += $f_optimize_intrinsics
 	# $compile_args += $f_optimize_size
 	# $compile_args += $f_optimize_debug
 	$compile_args += ($f_include + $path_code)
 	compile-unit $src_c $module_c $includes $compile_args
 	$elf = join-path $path_build 'hello_joypad.elf'
 	$exe = join-path $path_build 'hello_joypad.ps-exe'
 	$link_args = @()
 	$link_args += $f_debug
 	# $link_args += $f_optimize_size
 	$link_modules = @(
 		$module_asm_crt,
 		$module_c
 	)
 	link-modules $link_modules $elf $link_args
 	make-binary $elf $exe
 	# Post-link: gdb-runtime + dwarf-injection in a single Lua invocation (one luajit cold start).
 	ps1-meta -unity_root $src_c -metadata $path_atom_metadata -out_root $path_build_gen -passes @('--post-link') ` -extra_args @('--elf', $elf)
 	inject-dwarf $elf $path_build_gen
 }
 # build-hello_joypad
 function build-hello_camera {
 	$includes += @()
 	$path_module        = join-path $path_code   'hello_camera'
 	$path_duffle        = join-path $path_code   'duffle'
 	$path_atom_metadata = join-path $path_duffle 'word_count.metadata.h'
 	$path_build_gen     = join-path $path_build  'gen'
 	$src_c = join-path $path_module 'hello_camera.c'
 	ps1-meta -unity_root $src_c -metadata $path_atom_metadata -out_root $path_build_gen
 	$assemble_args = @()
 	$assemble_args += $f_debug
 	$assemble_args += $f_optimize_none
 	$assemble_args += ($f_include + $path_code)
 	$src_asm_crt    = join-path $path_nugget_common 'crt0/crt0.s'
 	$module_asm_crt = join-path $path_build         'crt0.o'
 	assemble-unit $src_asm_crt $module_asm_crt $includes $assemble_args
 	$module_c = join-path $path_build  'hello_camera_c.o'
 	$compile_args = @()
 	$compile_args += $f_debug
 	$compile_args += $f_optimize_none
 	# $compile_args += $f_optimize_intrinsics
 	# $compile_args += $f_optimize_size
 	# $compile_args += $f_optimize_debug
 	$compile_args += ($f_include + $path_code)
 	compile-unit $src_c $module_c $includes $compile_args
 	$elf = join-path $path_build 'hello_camera.elf'
 	$exe = join-path $path_build 'hello_camera.ps-exe'
 	$link_args = @()
 	$link_args += $f_debug
 	# $link_args += $f_optimize_size
 	$link_modules = @(
 		$module_asm_crt,
 		$module_c
 	)
 	link-modules $link_modules $elf $link_args
 	make-binary $elf $exe
 	# Post-link: gdb-runtime + dwarf-injection in a single Lua invocation (one luajit cold start).
 	ps1-meta -unity_root $src_c -metadata $path_atom_metadata -out_root $path_build_gen -passes @('--post-link') ` -extra_args @('--elf', $elf)
 	inject-dwarf $elf $path_build_gen
 }
 build-hello_camera
 # NO idea if this works yet...
 function Send-ToEmulator { param( [string]$exePath )
@@ -11,11 +11,10 @@
 ---   ```
 ---
 --- That small bootstrap: (a) locates this helper via `arg[0]` / `debug.getinfo`,
--- (b) loads it (which sets `package.path` + `package.cpath` via cached `git rev-parse`),
+--- (b) loads it (which sets `package.path` + `package.cpath`),
 --- (c) at the bottom calls `require("duffle")` (now resolvable since `package.path` was just set) and returns the duffle M.
 --- Net effect: the caller gets the duffle module in one statement; no separate `dofile(...)` + `require("duffle")` dance.
 ---
 --- Replaces the prior 2-line (entry) or 4-line (pass) pattern that had the call site do its own path resolution + duplicated setup.
 local M = {}
@@ -27,9 +26,6 @@ local CACHE_KEY = "__duffle_repo_root__"
 --- parent of the directory containing this script. We derive it directly from `debug.getinfo(1, "S").source`
 --- (returns `@<path>` for the currently-running chunk).
 ---
 --- Replaces the prior `io.popen("git rev-parse --show-toplevel")` approach, which cost ~100-180ms per
 --- LuaJIT process on Windows due to git's CLI startup. The path-derive approach costs <1ms.
 ---
 --- If `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
@@ -61,7 +57,12 @@ end
 function M.setup()
 	local repo_root = find_repo_root()
 	if not repo_root then
-		io.stderr:write("[duffle_paths] git rev-parse failed -- not in a git repo?\n")
+		-- 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
@@ -1,32 +1,18 @@
 # scripts/gdb/gdb_tape_atoms.gdb
 #
-# Wrapper for the tape-atom step-debug helpers. The 9 user commands are defined
+# Wrapper for the tape-atom step-debug helpers.
-# here as STUBS (degraded-state messages). The real implementations + the
+# The 9 user commands are defined here as STUBS (degraded-state messages). 
-# per-atom data tables are emitted by `passes/atoms_source_map.lua` (post-link
+# The real implementations + the per-atom data tables are emitted by `passes/atoms_source_map.lua` 
-# invocation: `ps1_meta.lua --atoms-source-map --gdb-runtime --elf <elf>`) into
+# (post-link invocation: `ps1_meta.lua --atoms-source-map --gdb-runtime --elf <elf>`) into `build/gdb_tape_atoms_runtime.gdb`.
-# `build/gen/gdb_tape_atoms_runtime.gdb`. Sourcing that file RE-DEFINES the
+# Sourcing that file RE-DEFINES the commands with real implementations.
 # commands with real implementations.
 #
-# If `build/gen/gdb_tape_atoms_runtime.gdb` is missing or stale, the stubs
+# If `build/gdb_tape_atoms_runtime.gdb` is missing or stale, the stubs remain (E1: no source map).
-# remain (E1: no source map). The user just needs to re-run `build_psyq.ps1`
+# The user just needs to re-run `build_psyq.ps1` to regenerate.
 # to regenerate. No exceptions; no crashes.
 #
 # Why a wrapper + separate runtime file?
 # - The runtime file is auto-generated per-build; not in git.
 # - The wrapper is checked into git; always works.
 # - This split keeps the script trivial and the data plumbing out of git.
 #
 # Compatible with every gdb build (no Python, no Tcl, no Guile required) —
 # pure gdb command scripting + `set $var = val` + `define ... end`.
 #
 # Generated by track gdb_tape_atom_debugging_20260711 — see
 # C:\projects\Pikuma\ps1-ai\docs\gdb_tape_atom_debugging.md for the manual.
-# ── Stub commands (defined here so they're always present, even if the
+# ?? Stub commands (defined here so they're always present, even if the runtime file is missing). The runtime file overrides these if sourced. ??
 #    runtime file is missing). The runtime file overrides these if sourced. ──
 define tape_atoms
-  echo "[gdb_tape_atoms] STUB: runtime file build/gen/gdb_tape_atoms_runtime.gdb not found."
+  echo "[gdb_tape_atoms] STUB: runtime file build/gdb_tape_atoms_runtime.gdb not found."
  echo "[gdb_tape_atoms] STUB: run .\\build_psyq.ps1 to regenerate, then re-source this file."
 end
 document tape_atoms
@@ -35,35 +21,35 @@ document tape_atoms
 end
 define break_atom
-  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+  echo "[gdb_tape_atoms] STUB: build/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
 end
 document break_atom
  Set a breakpoint at the start of tape atom <name>. STUB state.
 end
 define step_atom
-  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+  echo "[gdb_tape_atoms] STUB: build/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
 end
 document step_atom
  Resume execution until the next atom boundary. STUB state.
 end
 define next_atom
-  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+  echo "[gdb_tape_atoms] STUB: build/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
 end
 document next_atom
  Alias for step_atom. STUB state.
 end
 define where_in_atom
-  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+  echo "[gdb_tape_atoms] STUB: build/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
 end
 document where_in_atom
  Report current atom name, .rodata addr, word offset, and source line (if known). STUB state.
 end
 define stepi_inside_atom
-  echo "[gdb_tape_atoms] STUB: build/gen/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
+  echo "[gdb_tape_atoms] STUB: build/gdb_tape_atoms_runtime.gdb not sourced. Run build_psyq.ps1."
 end
 document stepi_inside_atom
  One MIPS-instruction step, then where_in_atom. STUB state.
@@ -77,7 +63,7 @@ define show_c2
  printf "C2[14]   0x%08x  [sxy2]\n", $c2_data[14]
  printf "C2[24]   0x%08x  [mac0]\n", $c2_data[24]
  printf "...\n"
-  echo "(STUB state: only 7 representative regs shown. Run build_psyq.ps1 for full dump.)"
+   echo "(STUB state: only 7 representative regs shown. Run build_psyq.ps1 for full dump.)"
 end
 document show_c2
  Pretty-print all 32 C2 data registers as hex + named alias. STUB state (7 reg subset).
@@ -103,17 +89,17 @@ document wave_ctx
 end
-# ── Source the runtime file (re-defines commands with real impls + data). ──
+# ?? Source the runtime file (re-defines commands with real impls + data). ??
 # Try to source from project-root-relative path first (the typical case).
 # If the user is in a different CWD, the source will fail and stubs remain.
-# The runtime file path is computed relative to the ELF's source map convention
+# The runtime file path is computed relative to the ELF's source map convention (build/gdb_tape_atoms_runtime.gdb).
 # (build/gen/gdb_tape_atoms_runtime.gdb).
 echo [gdb_tape_atoms] Wrapper loaded. Sourcing runtime file...
-# Suppress the "Redefine command" prompts that would otherwise appear when the
+# Suppress the "Redefine command" prompts that would otherwise appear when the runtime file overrides the 9 stub commands defined above.
-# runtime file overrides the 9 stub commands defined above. The runtime's
+# The runtime's `define` blocks are intended to overwrite ? there's no ambiguity to confirm.
 # `define` blocks are intended to overwrite — there's no ambiguity to confirm.
 set confirm off
-source build/gen/gdb_tape_atoms_runtime.gdb
+
 # Source the runtime file (re-defines commands with real impls + data).
 source build/gdb_tape_atoms_runtime.gdb
 set confirm on
-echo [gdb_tape_atoms] Runtime sourced successfully (9 commands now have real implementations).
+echo [gdb_tape_atoms] Runtime sourced successfully (9 commands now have real implementations).
@@ -1,42 +1,32 @@
 --- passes/annotation.lua — Atom-annotation DSL validator.
 ---
 --- Validates `MipsAtom_(name) atom_info(atom_bind(Binds_X), atom_reads(...), atom_writes(...)) { ... }` declarations in source files.
--- Also reads: `Binds_*` struct declarations (`typedef Struct_(Binds_X) { ... };`)
+--- Also reads `Binds_*` struct declarations (`typedef Struct_(Binds_X) { ... };`).
 ---
--- Source scanning: done ONCE upstream by `duffle.scan_source()` (ps1_meta.lua pre-scans each source and stashes the result in `src.scan`). 
+--- `duffle.scan_source()` scans each source once upstream; `ps1_meta.lua` stores that result in `src.scan`.
 ---
--- Writes:
+--- Ownership: the canonical `ctx.shared.corpus` supplies cross-source registries, while each `src.scan` supplies its source's declarations and bodies.
---   - `<ctx.out_root>/<dir_basename>.errors.h` — one per module, with `#error` directives on findings (the C compile will surface the error)
+--- A context without `ctx.shared.corpus` is rejected with an explicit canonical-corpus message.
 ---   - The annotations.txt report is rendered by `passes/report.lua` from the per-module results stashed in `ctx.flags._annot_results`
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex, Lua 5.3 compatible
-- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
+-- Bootstrap follows the entry scripts; `scripts/duffle_paths.lua` sets package.path and package.cpath. See `ps1_meta.lua` for the rationale.
-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
+-- `debug.getinfo(1, "S").source` locates this file for standalone and orchestrated runs, then `duffle_paths.lua` returns the loaded `duffle` module.
 -- 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 write_file     = duffle.write_file
 local ensure_dir     = duffle.ensure_dir
-- Domain tables (single source of truth in duffle.lua).
+-- The annotation pass reads the source-derived registries from scan_source:
-local WAVE_CONTEXT_REGS = duffle.WAVE_CONTEXT_REGS
+--   * pipe_ctx.register_alias_registry — for atom_dbg_reg_default(R_X, ...) and atom_reg_types(R_X, ...) member-identity checks
-
+--   * pipe_ctx.type_name_registry      — for atom_dbg_reg_default(<T>, ...) and atom_reg_types(<T>, ...) type-identity checks
 local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 --- @class SourceFile
--- @field path     string  -- absolute path to the source file
+--- @field path     string  -- Absolute path to the source file
--- @field text     string  -- the full source text
+--- @field text     string  -- Full source text
--- @field dir      string  -- the directory containing the source
+--- @field dir      string  -- Directory containing the source
--- @field basename string  -- filename without extension
+--- @field basename string  -- Filename without extension
--- @field scan     table   -- pre-scanned SourceScan payload (from duffle.scan_source)
+--- @field scan     table   -- Pre-scanned SourceScan payload (from duffle.scan_source)
 --- @class PassCtx
 --- @field sources            SourceFile[]
@@ -47,8 +37,6 @@ local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 --- @field project_root       string
 --- @field upstream           table<string, table>
 --- @field flags              table
 --- @field flags._annot_results table[]   -- stashed by annotation pass; consumed by report.lua
 --- @field dry_run            boolean
 --- @field verbose            boolean
 --- @class PassResult
@@ -57,18 +45,28 @@ local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 --- @field warnings table[]
 --- @class AtomAnnotation
--- @field line    integer       -- source line of the atom_info call
+--- @field line    integer       -- Source line of the atom_info call
--- @field macro   string        -- the macro name (always "atom_info" in the new shape)
+--- @field macro   string        -- Macro name (always "atom_info" in the new shape)
--- @field name    string        -- the atom name
+--- @field name    string        -- Atom name
--- @field kind    string        -- always "info"
+--- @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)
+--- @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 line integer -- Source line (or 0 for pass-level)
--- @field msg  string   -- finding message
+--- @field msg  string  -- Finding message
 --- @class Findings
 --- @field errors   Finding[]
@@ -76,9 +74,14 @@ local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 --- @field info     Finding[]
 --- @class PipeCtx
--- @field atom_index   table<string, AtomAnnotation>  -- name -> AtomAnnotation (only kind=="atom")
+--- @field atom_index     table<string, AtomAnnotation> -- Name -> AtomAnnotation (only kind=="atom")
--- @field binds_index  table<string, BindsStruct>     -- name -> BindsStruct
+--- @field binds_index    table<string, BindsStruct>    -- Name -> BindsStruct
--- @field annot_counts table<string, integer>          -- name -> annotation count (for unique_annotation check)
+--- @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) 
 --- @class AnnotatedResult
 --- @field atoms    AtomEntry[]
@@ -92,15 +95,11 @@ local function is_wave_context_reg(n) return WAVE_CONTEXT_REGS[n] ~= nil  end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Per-check functions (the CHECK_RULES table's payload)
 -- ════════════════════════════════════════════════════════════════════════════
--
+--- The dispatcher in `validate()` routes each result by convention: existence checks write errors[] and shape checks write warnings[].
-- Each check has a uniform `append_to_findings` shape (errors[] / warnings[] / info[]).
+--- `macro_word_drift` writes errors[] for missing or mismatched metadata and info[] for a match.
 -- The dispatcher in `validate()` decides which findings list each check writes to — by convention,
 -- "existence" checks (declaration must exist, struct must exist) write errors[]; "shape" checks
 -- (writes/reads must be wave-context) write warnings[]. The `macro_word_drift` check writes
 -- both errors[] (missing/mismatch) and info[] (match).
--- Check: every annotated atom must have a matching MipsAtom_(name) declaration.
+--- Check: Every annotated atom must have a matching MipsAtom_(name) declaration.
--- @param a AtomAnnotation
+--- @param a        AtomAnnotation
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
 local function check_atom_decl_exists(a, pipe_ctx, findings)
@@ -112,8 +111,8 @@ local function check_atom_decl_exists(a, pipe_ctx, findings)
 	end
 end
--- Check: every atom may have AT MOST ONE annotation.
+--- Check:     Every atom may have AT MOST ONE annotation.
--- Post-loop: needs full-corpus `annot_counts` from pipe_ctx.
+--- Post-loop: Needs full-corpus `annot_counts` from pipe_ctx.
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
 local function check_unique_annotation(pipe_ctx, findings)
@@ -128,15 +127,12 @@ local function check_unique_annotation(pipe_ctx, findings)
 end
 --- Check: BIND atoms must reference a real Binds_* struct.
--- Demoted from error to warning (2026-07-10): the same condition is now caught by passes/static_analysis.lua's
+--- 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.
--- check_abi_handoff() as an error. Emitting a warning here keeps the annotation pass from being stop-on-error
+--- @param a        AtomAnnotation
 --- for the common test-fixture case, while still surfacing the issue in the report.
 --- The static-analysis report remains the source of truth for build-stopping errors.
 --- @param a AtomAnnotation
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
 local function check_binds_struct_exists(a, pipe_ctx, findings)
-	if not a.binds then return end
+	if not a.binds                   then return end
 	if pipe_ctx.binds_index[a.binds] then return end
 	findings.warnings[#findings.warnings + 1] = {
 		line = a.line,
@@ -146,57 +142,13 @@ local function check_binds_struct_exists(a, pipe_ctx, findings)
 	}
 end
 --- Check: Binds_* struct fields must correspond to known wave-context registers.
 --- Also checks that all `atom_writes(...)` entries are wave-context registers.
 --- @param a AtomAnnotation
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
 local function check_binds_field_wave_context(a, pipe_ctx, findings)
 	if not (a.binds and pipe_ctx.binds_index[a.binds]) then return end
 	local bs = pipe_ctx.binds_index[a.binds]
 	for _, f in ipairs(bs.fields) do
 		local candidate = "R_" .. f.name
 		if not is_wave_context_reg(candidate) then
 			findings.warnings[#findings.warnings + 1] = {
 				line = bs.line,
 				msg  = string.format("%s field '%s' doesn't match a known wave-context register (candidate '%s')", a.binds, f.name, candidate),
 			}
 		end
 	end
 	for _, w in ipairs(a.writes) do
 		if not is_wave_context_reg(w) then
 			findings.warnings[#findings.warnings + 1] = {
 				line = a.line,
 				msg  = string.format("%s writes '%s' which is not a known wave-context register", a.name, w),
 			}
 		end
 	end
 end
 --- Check: atom_reads(...) entries should be wave-context registers (or R_TapePtr for rbind).
 --- @param a AtomAnnotation
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
 local function check_reads_wave_context(a, pipe_ctx, findings)
 	for _, r in ipairs(a.reads) do
 		if not is_wave_context_reg(r) and r ~= "R_TapePtr" then
 			findings.warnings[#findings.warnings + 1] = {
 				line = a.line,
 				msg  = string.format("atom '%s' reads '%s' which is not a known wave-context register", a.name, r),
 			}
 		end
 	end
 end
 --- Check: TAPE_WORDS(mac_X, N) ↔ WORD_COUNT(mac_X, N) drift.
 --- Three outcomes: missing (error), mismatch (error), match (info).
--- @param m MacroEntry
+--- @param m  MacroEntry
--- @param wc table<string, integer>  -- the shared word-count table (from ctx.shared.word_counts)
+--- @param wc table<string, integer> -- Shared word-count table (from ctx.shared.word_counts)
 --- @param findings Findings
 local function check_macro_word_drift(m, wc, findings)
-	local declared = wc[m.name]
+	local  declared = wc[m.name]
 	if not declared then
 		findings.errors[#findings.errors + 1] = {
 			line = m.line,
@@ -217,38 +169,309 @@ local function check_macro_word_drift(m, wc, findings)
 	}
 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 findings Findings
 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
 		if seen_first_line[occ.reg] == nil then
 			seen_first_line[occ.reg] = occ.source_line
 		else
 			findings.errors[#findings.errors + 1] = {
 				line = occ.source_line,
 				msg  = string.format(
 					"duplicate atom_dbg_reg_default for %q at line %d (first declared at line %d); one default per register",
 					occ.reg, occ.source_line, seen_first_line[occ.reg]),
 			}
 		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
 		if not reg_registry[reg] then
 			findings.errors[#findings.errors + 1] = {
 				line = def.source_line,
 				msg  = string.format(
 					"atom_dbg_reg_default at line %d references unknown register %q (not in register_alias_registry)",
 					def.source_line, reg),
 			}
 		end
 		if def.pointer_depth == nil or def.pointer_depth < 0 or def.pointer_depth > 1 then
 			findings.errors[#findings.errors + 1] = {
 				line = def.source_line,
 				msg  = string.format(
 					"atom_dbg_reg_default at line %d for %q has unsupported pointer depth %d (expected 0 or 1)",
 					def.source_line, reg, def.pointer_depth or -1),
 			}
 		end
 		if not def.type_name or not type_registry[def.type_name] then
 			findings.errors[#findings.errors + 1] = {
 				line = def.source_line,
 				msg  = string.format(
 					"atom_dbg_reg_default at line %d for %q uses unknown type %q (not in type_name_registry)",
 					def.source_line, reg, tostring(def.type_name)),
 			}
 		end
 	end
 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 findings Findings
 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
 		if ai.reg_type_overrides then
 			for reg, ov in pairs(ai.reg_type_overrides) do
 				if not reg_registry[reg] then
 					findings.errors[#findings.errors + 1] = {
 						line = ai.info_line,
 						msg  = string.format(
 							"atom '%s' has atom_reg_types for %q; compute-register types are restricted to opt-in aliases (%q not in register_alias_registry)",
 							ai.atom_name, reg, reg),
 					}
 				end
 				if not ov.type_name or not type_registry[ov.type_name] then
 					findings.errors[#findings.errors + 1] = {
 						line = ai.info_line,
 						msg  = string.format(
 							"atom '%s' atom_reg_types for %q uses unknown compute type %q (not in type_name_registry)",
 							ai.atom_name, reg, tostring(ov.type_name)),
 					}
 				end
 			end
 		end
 	end
 end
 --- Check: atom_view(Binds_X) entries reference a Binds_* struct with at least one field.
 --- @param _src     SourceFile
 --- @param pipe_ctx PipeCtx
 --- @param findings Findings
 local function check_atom_view_layout(_src, pipe_ctx, findings)
 	for atom_name, view in pairs(pipe_ctx.atom_views or {}) do
 		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]
 			if not bs then
 				findings.errors[#findings.errors + 1] = {
 					line = view.info_line,
 					msg  = string.format(
 						"atom '%s' has atom_view(%s) but no Struct_(%s) { ... } declaration was found",
 						atom_name, view.binds_name, view.binds_name),
 				}
 			elseif not bs.fields or #bs.fields == 0 then
 				findings.errors[#findings.errors + 1] = {
 					line = bs.line,
 					msg  = string.format(
 						"atom '%s' has atom_view(%s) but that struct declares zero typed fields",
 						atom_name, view.binds_name),
 				}
 			end
 		end
 	end
 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 findings Findings
 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
 			seen[f.name] = (seen[f.name] or 0) + 1
 		end
 		for name, count in pairs(seen) do
 			if count > 1 then
 				findings.errors[#findings.errors + 1] = {
 					line = bs.line,
 					msg  = string.format(
 						"%s has duplicate field name %q (count %d); the typed-view contract requires unique field names",
 						bs.name, name, count),
 				}
 			end
 		end
 	end
 end
 -- Check: Debug-skip markers must satisfy shape + placement constraints.
 --- Walks the priority list once; each marker produces at most one error, so one source defect yields one finding.
 --- Priority order (first defect wins):
 ---   1. marker_kind ~= "atom_dbg_skip" -> legacy/renamed spelling (use `atom_dbg_skip`)
 ---   2. marker_kind == "atom_dbg_skip" AND has_parens -> parenthesized form (the marker is bare-only)
 ---   3. args  ~= ""                 -> takes no arguments
 ---   4. superseded_by_marker_line   -> duplicate marker (cite superseding line)
 ---   5. pending + no target_kind    -> dangling (no following declaration)
 ---   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 findings Findings
 local function check_skip_marker(marker, _pipe_ctx, findings)
 	local kind = marker.marker_kind
 	local line = marker.marker_line
 	-- 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
 		findings.errors[#findings.errors + 1] = {
 			line = line,
 			msg  = string.format("%s marker at line %d must be bare; the parenthesized form is no longer accepted (use `atom_dbg_skip MipsAtom_(name) { ... }`)",
 				kind, line),
 		}
 		return
 	end
 	if marker.args ~= nil and marker.args ~= "" then
 		findings.errors[#findings.errors + 1] = {
 			line = line,
 			msg  = string.format("%s marker at line %d takes no arguments; found %q", kind, line, marker.args),
 		}
 		return
 	end
 	if marker.superseded_by_marker_line then
 		findings.errors[#findings.errors + 1] = {
 			line = line,
 			msg  = string.format("duplicate %s marker at line %d; superseded by another %s marker at line %d"
 				, kind, line, kind, marker.superseded_by_marker_line),
 		}
 		return
 	end
 	if marker.pending and not marker.target_kind then
 		findings.errors[#findings.errors + 1] = {
 			line = line,
 			msg  = string.format("dangling %s marker at line %d: no following MipsAtom_/MipsAtomComp_/MipsAtomComp_Proc_ declaration"
 				, kind, line),
 		}
 		return
 	end
 	if marker.target_kind
 		and marker.target_kind ~= "atom"
 		and marker.target_kind ~= "comp_bare"
 		and marker.target_kind ~= "comp_proc" then
 		findings.errors[#findings.errors + 1] = {
 			line = line,
 			msg  = string.format("%s marker at line %d must precede MipsAtom_, MipsAtomComp_, or MipsAtomComp_Proc_; found an unrelated declaration"
 				, kind, line),
 		}
 	end
 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 findings Findings
 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
 		if ai.reg_type_overrides then
 			for reg, _ in pairs(ai.reg_type_overrides) do
 				if not reg_registry[reg] then
 					findings.warnings[#findings.warnings + 1] = {
 						line = 0,
 						msg  = "wave-context removed; opt in via #define atom_reg in mips.h "
 							.. "(every R_<alias> that should be visible to the annotation pass "
 							.. "must be enum-declared with the bare atom_reg marker)",
 					}
 					return
 				end
 			end
 		end
 	end
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- CHECK_RULES — data-driven check dispatch (the plex pattern)
 -- ════════════════════════════════════════════════════════════════════════════
 --
-- Each rule entry picks one of three "shapes" of dispatch:
+-- Each rule entry picks one of four "shapes" of dispatch:
--   per_annot(annot, pipe_ctx, findings) — runs once per AtomAnnotation
+--   per_annot(annot, pipe_ctx, findings)        -- runs once per AtomAnnotation
--   post(pipe_ctx, findings)             — runs once after all per_annot calls complete (full-corpus aggregation)
+--   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_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 = {
-	{ name = "atom_decl_exists",         per_annot = check_atom_decl_exists         },
+	{ name = "atom_decl_exists",          per_annot       = check_atom_decl_exists          },
-	{ name = "binds_struct_exists",      per_annot = check_binds_struct_exists      },
+	{ name = "binds_struct_exists",       per_annot       = check_binds_struct_exists       },
-	{ name = "binds_field_wave_context", per_annot = check_binds_field_wave_context },
+	{ name = "unique_annotation",         post            = check_unique_annotation         },
-	{ name = "reads_wave_context",       per_annot = check_reads_wave_context       },
+	{ name = "macro_word_drift",          per_macro       = check_macro_word_drift          },
-	{ name = "unique_annotation",        post      = check_unique_annotation        },
+	{ name = "skip_marker_validation",    per_skip_marker = check_skip_marker               },
-	{ name = "macro_word_drift",         per_macro = check_macro_word_drift         },
+	{ name = "semantic_reg_defaults",     per_source      = check_semantic_reg_defaults     },
 	{ name = "atom_reg_types",            per_source      = check_atom_reg_types            },
 	{ name = "atom_view_layout",          per_source      = check_atom_view_layout          },
 	{ name = "binds_no_duplicate_fields", per_source      = check_binds_no_duplicate_fields },
 	{ name = "wave_context_migration",    per_source      = check_wave_context_migration    },
 }
 -- ════════════════════════════════════════════════════════════════════════════
 -- Validation
 -- ════════════════════════════════════════════════════════════════════════════
--
+-- Pure check: Read from src.scan, run validations, emit findings. The scan was done once upstream.
 -- Pure check: read from src.scan, run validations, emit findings.
 -- No source walking; no parsing. The scan was done once upstream.
--- Validate one source against its pre-scanned SourceScan payload.
+--- 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
--- @param src SourceFile
+--- @return PipeCtx
 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
 		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 {},
 	}
 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.
 --- @return AnnotatedResult
-local function validate(ctx, src)
+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.
@@ -274,28 +497,32 @@ local function validate(ctx, src)
 		}
 	end
-	-- Build pipe_ctx (Fleury: expose structure). Pre-compute everything the per-check functions need.
+	-- 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`.
-	-- Single source of truth for atom / binds / annotation-count lookups.
+	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 pipe_ctx = {
-		atom_index   = {},
+		atom_index               = {},
-		binds_index  = {},
+		binds_index              = {},
-		annot_counts = {},
+		annot_counts             = corpus_pipe_ctx.annot_counts,
 		types                    = scan.types or {},
 		type_occurrences         = scan.type_occurrences or {},
 		atom_views               = scan.atom_views or {},
 		seen_defaults            = seen_defaults,
 		atom_infos_list          = atom_infos_list,
 		binds_list               = scan.binds or {},
 		-- See the module ownership contract; these shared lookup tables come from 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
 	for _, a in ipairs(annots)     do
 		if a.name then
 			pipe_ctx.annot_counts[a.name] = (pipe_ctx.annot_counts[a.name] or 0) + 1
 		end
 	end
 	-- Findings live in a single struct with three lists (errors / warnings / info).
 	-- Each check writes to the list appropriate for its severity.
 	local findings = { errors = {}, warnings = {}, info = {} }
-	-- Propagate parse-time errors from scan_source's atom_info parsing.
+	-- Lift parse-time errors already recorded in scan_source's atom_info payload into this pass's findings list.
 	-- These are errors found in the atom_info(...) body itself (e.g., malformed args).
 	-- They are pre-existing in the scan payload — we just lift them into our findings list.
 	for _, a in ipairs(annots) do
 		if a.errors then
 			for _, msg in ipairs(a.errors) do
@@ -319,19 +546,34 @@ local function validate(ctx, src)
 		if rule.post then rule.post(pipe_ctx, findings) end
 	end
 	-- 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
 	end
 	-- Per-macro rules (TAPE_WORDS vs WORD_COUNT drift).
-	local wc = ctx.shared.word_counts
+	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
 	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
 	-- 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)",
+		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, #annots, #scan.macros, #scan.binds),
 	}
 	return {
@@ -345,52 +587,6 @@ local function validate(ctx, src)
 	}
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Per-DIRECTORY (per-module) output: errors.h + annotations.txt
 -- ════════════════════════════════════════════════════════════════════════════
 --- Render `<dir_basename>.errors.h` with `#error` directives for every error found across all sources in the directory.
 --- Empty directories (no errors, no atoms) produce no file.
 local function emit_module_errors_h(ctx, dir_basename, atoms_count, errors, sources)
 	if ctx.dry_run then return nil end
 	if atoms_count == 0 and #errors == 0 then
 		return nil
 	end
 	local out_path = ctx.out_root .. "/" .. dir_basename .. ".errors.h"
 	local lines    = {
 		"// Auto-generated by ps1_meta.lua (passes/annotation.lua) — DO NOT EDIT",
 		string.format("// Module: %s   Sources: %d", dir_basename, #sources),
 		"#pragma once",
 		"",
 	}
 	if #errors == 0 then
 		lines[#lines + 1] = "// annotation pass OK"
 	else
 		for _, e in ipairs(errors) do
 			local src_tag = ""
 			if e.source then
 				local src_name = e.source:match("([^/\\]+)$") or e.source
 				src_tag = src_name .. ": "
 			end
 			lines[#lines + 1] = string.format('#error "%s%s (line %d)"', src_tag, e.msg, e.line)
 		end
 	end
 	ensure_dir(ctx.out_root)
 	write_file(out_path, table.concat(lines, "\n") .. "\n")
 	return out_path
 end
 --- Stash aggregated per-module results for the report pass to consume.
 local function emit_module_annotations_stub(ctx, dir, dir_basename, atoms_count)
 	ctx.flags                = ctx.flags                or {}
 	ctx.flags._annot_results = ctx.flags._annot_results or {}
 	ctx.flags._annot_results[#ctx.flags._annot_results + 1] = {
 		dir          = dir,
 		dir_basename = dir_basename,
 		atoms_count  = atoms_count,
 	}
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- M.run — orchestrator entry
 -- ════════════════════════════════════════════════════════════════════════════
@@ -409,24 +605,22 @@ function M.run(ctx)
 	local errors   = {}
 	local warnings = {}
-	-- Per-DIRECTORY (per-module) aggregation. Group sources by `src.dir`,
+	-- Build the shared pipe_ctx once for this run; every validate() call sees the same cross-source registries.
-	-- validate every source in the dir, then emit ONE errors.h per dir.
+	-- The corpus owns the canonical cross-source registries; per-source scans retain body / declaration ownership.
-	-- `ctx.by_dir` is pre-computed in build_ctx (shared across all passes).
+	local corpus_pipe_ctx = build_corpus_pipe_ctx(ctx)
-	local by_dir = ctx.by_dir or duffle.group_sources_by_dir(ctx.sources)
+	local corpus = ctx.shared.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 {}
 	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 = {}
 		-- Per-source validate() results, cached for the report pass (it reads from this instead of re-validating each source).
 		ctx.flags                       = ctx.flags                       or {}
 		ctx.flags._annot_source_results = ctx.flags._annot_source_results or {}
 		for _, src in ipairs(dir_sources) do
-			local result  = validate(ctx, src)
+			local result  = validate(ctx, src, corpus_pipe_ctx)
-			result.source = src.path                                  -- tag for downstream rendering
+			result.source = src.path                           -- tag for downstream rendering
 			ctx.flags._annot_source_results[src.path] = result          -- stash so report.lua reads from cache instead of re-running validate()
 			dir_atoms = dir_atoms + #result.atoms
 			for _, e in ipairs(result.errors) do
 				dir_errors[#dir_errors + 1] = { line = e.line, msg = e.msg, source = src.path }
@@ -437,13 +631,6 @@ function M.run(ctx)
 				warnings    [#warnings     + 1] = { line = w.line, msg = w.msg }
 			end
 		end
 		local err_path = emit_module_errors_h(ctx, dir_basename, dir_atoms, dir_errors, dir_sources)
 		if err_path then
 			table.insert(outputs, { errors_h = err_path })
 		end
 		emit_module_annotations_stub(ctx, dir, dir_basename, dir_atoms)
 	end
 	return { outputs = outputs, errors = errors, warnings = warnings }
@@ -1,26 +1,21 @@
 --- passes/atoms_source_map.lua — Per-.word source-line map emitter for tape atoms.
 ---
--- Reads the pre-scanned SourceScan payload (produced once upstream by `duffle.scan_source`)
+--- Writer: this pass, given `atom.paths` (the per-atom mutable surface owned by `emission_model`). Readers:
--- for `MipsAtom_(name)` (kind="atom"), `MipsAtomComp_` / `MipsAtomComp_Proc_` (kind="comp_*"),
+--- `passes/dwarf_injection.lua` (synthesizes DW_TAG_inlined_subroutine + per-word line program rows) and 
--- and `MipsCode code_<name>` (kind="raw_atom") declarations. 
+--- the gdb-runtime wrapper at `scripts/gdb/gdb_tape_atoms.gdb` (loads the source map via `source <path>`).
 --- Walks each atom's pre-tokenized body (`{{tok=string, rel=integer}, ...}` from `duffle.tokenize_body`), 
 --- counts per-token word contributions via `ctx.shared.word_counts`, and emits one
 --- `WORD N LINE L TEXT T` line per `.word` to `<out_root>/<basename>.atoms.sourcemap.txt`.
 ---
--- **Two output forms** (per the workspace's per-emission-form pattern from
+--- Inputs from `atom.paths`: the ordered `items` stream, dense `word_events`, `invocations` views. Outputs: 
--- `guide_metaprogram_ssdl.md`):
+---  one `WORD N LINE L TEXT T` line per emitted `.word`, plus the per-word provenance form that DWARF synthesis consumes.
---   1. **Canonical text form** — `<out_root>/<basename>.atoms.sourcemap.txt`.
+---
---      Always emitted. Format-version-tagged for forward-compat. 
+--- Two output forms:
---      Lives in `<out_root>/` (build/gen) NOT `<source_dir>/gen/`. This file is a **build report**, not a compile artifact. 
+---   1. Markdown form: Handled by `passes/report.lua` (writes `<module>.atoms.md`).
---      Matches the convention used by `annotation.lua` (`<out_root>/<basename>.errors.h`) + `static_analysis.lua` (`<out_root>/<basename>.static_analysis.txt`).
+---      The render functions `render_source_map` + `render_provenance` are exported for `report.lua` to call directly.
 ---      Compile artifacts (`*.macs.h`, `*.offsets.h`) stay in `<source_dir>/gen/`.
---   2. **gdb-runtime form** — `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`
+---   2. `gdb_tape_atoms_runtime.gdb`: Post-link opt-in (`ctx.flags.gdb_runtime`),
---      (pure gdb command script; addresses pre-computed via `nm`; the 9 user commands defined as `define ... end` blocks).
+---      so the gdb wrapper script + the generated runtime script share the same canonical location.
---      Emitted ONLY when `ctx.flags.gdb_runtime` is true AND `ctx.flags.elf_path` points to an existing ELF.
+---      Triggered by `--post-link` or `--gdb-runtime`.
 ---      The gdb runtime form lets `gdb-multiarch --without-python` users (the common case on Windows MinGW builds) 
 ---      load the source-map data via `source <path>` — no Python/Tcl/Guile required.
 ---
--- **Output format** (canonical text form):
+--- Output forma (sourcemap.txt form):
 ---   ```
 ---   # FORMAT_VERSION 1
 ---   # auto-generated by ps1_meta.lua (passes/atoms_source_map.lua) — DO NOT EDIT
@@ -33,167 +28,169 @@
 ---   ...
 ---   ENDATOM
 ---   ```
---
+--- Marker records are zero-width in `atom.paths.items`, so they emit no WORD rows in the dense word view.
 --- Marker calls (`atom_label(...)`, `atom_offset(...)`) emit 0 `.word`s. 
 --- They share the same walking convention as `passes/offsets.lua :: scan_atom_body`: 
 --- markers do NOT advance the word-offset counter, but if a marker is bundled on the same token with a
 --- trailing instruction (e.g. `atom_label(foo) load_half_u(...)`), 
 --- the trailing instruction's word count is added. This matches `offsets.lua :: count_marker_rest`.
 ---
 --- **Conventions:** tabs (1/level), EmmyLua annotations, no regex,
 --- Lua 5.3 compatible.
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works
+-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` 
-- both standalone + when require'd). `duffle_paths.lua` sets package.path then
+-- (works both standalone + when require'd). `duffle_paths.lua` sets package.path then returns `require("duffle")` 
-- returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
+-- 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 duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
-local elf_dwarf        = require("elf_dwarf")
+local elf_dwarf      = require("elf_dwarf")
 local word_count_eval  = require("word_count_eval")
 local count_token_words = word_count_eval.count_token_words
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
-- Format version emitted as the first line. Bump + add a migration test if the
+-- Format version emitted as the first line. Bump + add a migration test if the format changes; 
-- format changes; the gdb runtime loader rejects mismatches (E2).
+-- the gdb runtime loader rejects mismatches (E2).
 local FORMAT_VERSION = 1
 -- Marker-call identifiers (mirrors offsets.lua:33-34).
 local LABEL_MARKER  = "atom_label"
 local OFFSET_MARKER = "atom_offset"
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 --- @class AtomSourceMapCtx
--- @field sources            table[]    -- SourceScan payload per source (from `ctx.sources`)
+--- @field shared             table   -- `ctx.shared`
--- @field shared             table      -- `ctx.shared`
+--- @field shared.corpus      table   -- source-order registry; single writer is build_ctx
--- @field shared.word_counts table      -- macro name -> word count (populated by word-counts + components passes)
+--- @field shared.word_counts table
--- @field out_root           string     -- output root (e.g. "build/gen")
+--- @field out_root           string  -- output root (e.g. "build/gen")
--- @field dry_run            boolean    -- if true, compute but don't write
+--- @field flags              table   -- `ctx.flags`; reads `flags.gdb_runtime` + `flags.elf_path`
 --- @field flags              table      -- `ctx.flags`; reads `flags.gdb_runtime` + `flags.elf_path`
 -- ════════════════════════════════════════════════════════════════════════════
-- Helpers
+-- Atom-path renderers
 -- ════════════════════════════════════════════════════════════════════════════
--- True iff the leading identifier of `tok` is a marker call (`atom_label` / `atom_offset`).
+--- Join word boundaries (from `items`) to per-word call text + source lines (from `word_events`).
--- Mirrors `passes/offsets.lua :: is_marker_token` (which is file-local there).
+--- @param atom table
 --- @param tok string
 --- @return boolean
 local function is_marker_token(tok)
 	local leading = duffle.read_ident(tok, 1)
 	return leading == LABEL_MARKER or leading == OFFSET_MARKER
 end
 --- Count words contributed by the non-marker portion of `tok` (after the marker's closing `)`).
 --- Mirrors offsets.lua:182 `count_marker_rest`. 
 --- Returns 0 if there's no trailing content after the marker call.
 --- @param tok string
 --- @param wc table
 --- @return integer
 local function count_marker_rest(tok, wc)
 	local marker_end = duffle.find_marker_call_end(tok)
 	if not marker_end or marker_end >= #tok then return 0 end
 	local rest = duffle.trim(tok:sub(marker_end))
 	if rest == "" then return 0 end
 	return count_token_words(rest, wc)
 end
 --- Compute per-word entries for an atom. 
 --- Shared between the canonical text form (per-source `.atoms.sourcemap.txt`) 
 --- and the gdb-runtime form (`gdb_tape_atoms_runtime.gdb`).
 ---
 --- Returns a list of `{pos, line, text}` entries + the total word count.
 --- Markers contribute 0 entries (the marker call emits 0 `.word`s).
 --- @param atom table   -- one entry of scan.atoms / scan.raw_atoms
 --- @param src  table   -- SourceFile (has .scan with .line_of(), .path)
 --- @param wc   table   -- shared.word_counts
 --- @return table[], integer
-local function compute_word_entries(atom, src, wc)
+local 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
 		if item.kind == "word" then word_items[#word_items + 1] = item end
 	end
 	local entries = {}
-	local pos     = 0
+	for index, event in ipairs(events) do
-	for _, t in ipairs(atom.body_tokens) do
+		local item = word_items[index] or {}
-		local tok = t.tok
+		entries[#entries + 1] = {
-		local rel = t.rel
+			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,
 			invocation = (event.outermost_invocation_id
 				and paths.invocations
 				and paths.invocations[event.outermost_invocation_id]) or nil,
 		}
 	end
 	return entries, #events
 end
-		local words
+--- Render one atom's provenance stanza. Format 1 line shapes:
-		if is_marker_token(tok) then
+---   `WORD N  CALL <src-path>:<src-line>  MACRO <name> "<def-path>:<def-line>" BODY <line>` (component invocation)
-			words = count_marker_rest(tok, wc)
+---   `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
 local function emit_provenance_stanza(src, atom, wc)
 	local lines          = {}
 	local rel_path       = src.path:gsub("\\\\", "/")
 	local entries, total = canonical_word_entries(atom)
 	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]
 		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)
 		else
-			words = count_token_words(tok, wc)
+			lines[#lines + 1] = string.format("WORD %d  CALL %s:%d  RAW", entry.pos, rel_path, entry.line)
 		end
 		if words > 0 then
 			-- Source line for THIS token = line containing byte offset `atom.body_off + rel`.
 			-- `src.scan.line_of(...)` is O(log N) via LineIndex.
 			local line = src.scan.line_of(atom.body_off + rel)
 			-- Flatten newlines + tabs in TEXT to spaces so each WORD entry fits on
 			-- one physical line. The gdb Python parser (or our pure-gdb parser)
 			-- does line-based splits; multi-line TEXT would break it.
 			local text = duffle.trim(tok):gsub("[\t\r\n]+", " ")
 			for _ = 1, words do
 				entries[#entries + 1] = { pos = pos, line = line, text = text }
 				pos = pos + 1
 			end
 		end
 	end
-	return entries, pos
+
 	lines[1]          = lines[1]:gsub(" 0$", " " .. tostring(total))
 	lines[#lines + 1] = "ENDATOM"
 	return lines, total
 end
--- Render one atom's stanza for the canonical text form
+--- Render the full provenance file content for one source.
--- (ATOM header line, N WORD lines, ENDATOM marker). Returns (lines, total_words).
+--- @param src table
 --- @param wc  table
 --- @return string
 local function render_provenance(src, wc)
 	local lines = {}
 	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"
 	lines[#lines + 1] = "# file:line) and, when the word was emitted by a `mac_X(...)` component invocation,"
 	lines[#lines + 1] = "# the component's definition file:line + the per-word BODY line. Used by"
 	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."
 	local function append(atom)
 		local stanza = emit_provenance_stanza(src, atom, wc)
 		for _, line in ipairs(stanza) do lines[#lines + 1] = line end
 	end
 	for _, atom in ipairs(src.scan.atoms or {}) do
 		if atom.paths then append(atom) end
 	end
 	for _, atom in ipairs(src.scan.raw_atoms or {}) do
 		if atom.paths then append(atom) end
 	end
 	return table.concat(lines, "\n") .. "\n"
 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
-local function emit_atom_stanza(src, atom, wc)
+local function emit_atom_stanza(src, atom)
-	local lines              = {}
+	local lines          = {}
-	local rel_path           = src.path:gsub("\\", "/")
+	local rel_path       = src.path:gsub("\\\\", "/")
-	local entries, total     = compute_word_entries(atom, src, wc)
+	local entries, total = canonical_word_entries(atom)
 	-- ATOM header line with placeholder total (patched after we know it).
 	lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
-
+	for _, entry in ipairs(entries) do
 	for _, we in ipairs(entries) do
 		lines[#lines + 1] = string.format("WORD %d  LINE %d  TEXT %s",
-			we.pos, we.line, we.text)
+			entry.pos, entry.line, entry.text)
 	end
 	-- Patch the placeholder total in the ATOM header line.
 	lines[1] = lines[1]:gsub(" 0$", " " .. tostring(total))
 	lines[#lines + 1] = "ENDATOM"
 	return lines, total
 end
--- Render the full source map file content for one source (one .atoms.sourcemap.txt per source).
+--- Render the full source map file content for one source (one .atoms.sourcemap.txt per source). Mirrors offsets.lua's
--- Mirrors offsets.lua's `project_atoms` shape: scan.atoms + scan.raw_atoms, no kind filter.
+--- `project_atoms` shape: scan.atoms + scan.raw_atoms, no kind filter.
 --- @param src table
--- @param wc table
+--- @param wc  table
 --- @return string
-local function render_source_map(src, wc)
+local function render_source_map(src)
-	local lines = {}
+	local lines       = {}
 	lines[#lines + 1] = "# FORMAT_VERSION " .. FORMAT_VERSION
 	lines[#lines + 1] = "# auto-generated by ps1_meta.lua (passes/atoms_source_map.lua) — DO NOT EDIT"
 	local function append(atom)
 		local stanza = emit_atom_stanza(src, atom)
 		for _, line in ipairs(stanza) do lines[#lines + 1] = line end
 	end
 	for _, atom in ipairs(src.scan.atoms or {}) do
-		local stanza = emit_atom_stanza(src, atom, wc)
+		if atom.paths then append(atom) end
 		for _, line in ipairs(stanza) do
 			lines[#lines + 1] = line
 		end
 	end
 	for _, atom in ipairs(src.scan.raw_atoms or {}) do
-		local stanza = emit_atom_stanza(src, atom, wc)
+		if atom.paths then append(atom) end
 		for _, line in ipairs(stanza) do
 			lines[#lines + 1] = line
 		end
 	end
 	return table.concat(lines, "\n") .. "\n"
@@ -211,70 +208,49 @@ local function gdb_escape(s)
 	return (s:gsub("\\", "\\\\"):gsub('"', '\\"'))
 end
--- Build the list of atoms with addresses + word entries.
+--- Build the list of atoms with addresses + word entries. Shared helper for the gdb-runtime file emission.
 --- Shared helper for the gdb-runtime file emission.
 --- @param ctx PassCtx
 --- @return table[] -- list of {idx, name, src_path, file_base, addr, size_bytes, words, entries}
 local function build_atom_table(ctx)
-	local wc = (ctx.shared and ctx.shared.word_counts) or {}
+	local addrs   = elf_dwarf.read_nm(ctx.flags.elf_path)
-	local addrs = elf_dwarf.read_nm(ctx.flags.elf_path)
+	local corpus  = ctx.shared and ctx.shared.corpus
 	local matched = {}
-	for _, src in ipairs(ctx.sources) do
+
-		if src.scan then
+	for _, src in ipairs(corpus.source_order or {}) do
-			local file_base = src.path:match("([^/\\]+)$") or src.path
+		local file_base = src.path:match("([^/\\\\]+)$") or src.path
-			for _, atom in ipairs(src.scan.atoms or {}) do
+		local function append(atom)
-				if atom.kind == nil or atom.kind == "atom" then
+			if not atom.paths then return end
-					local name    = atom.raw_name or atom.name
+			local  name = atom.raw_name or atom.name
-					local info    = addrs[name]
+			local  info = addrs[name]
-					if info then
+			if not info then return end
-						local entries, total = compute_word_entries(atom, src, wc)
+			local entries, total = canonical_word_entries(atom)
-						matched[#matched + 1] = {
+			matched[#matched + 1] = {
-							name       = name,
+				name       = name,
-							src_path   = src.path,
+				src_path   = src.path,
-							file_base  = file_base,
+				file_base  = file_base,
-							addr       = info[1],
+				addr       = info[1],
-							size_bytes = info[2],
+				size_bytes = info[2],
-							words      = total,
+				words      = total,
-							entries    = entries,
+				entries    = entries,
-						}
+			}
 					end
 				end
 			end
 			for _, atom in ipairs(src.scan.raw_atoms or {}) do
 				local name = atom.name
 				local info = addrs[name]
 				if info then
 					local entries, total = compute_word_entries(atom, src, wc)
 					matched[#matched + 1] = {
 						name       = name,
 						src_path   = src.path,
 						file_base  = file_base,
 						addr       = info[1],
 						size_bytes = info[2],
 						words      = total,
 						entries    = entries,
 					}
 				end
 			end
 		end
 		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
 	end
 	-- Deterministic order: sort by address (matches `nm` output ordering).
 	table.sort(matched, function(a, b) return a.addr < b.addr end)
-	for i, a in ipairs(matched) do
+	for i, a in ipairs(matched) do a.idx = i - 1 end
 		a.idx = i - 1
 	end
 	return matched
 end
--- Append the 9 gdb command definitions to `lines`. Pure gdb scripting no Python, no Tcl, no Guile required. 
+--- Append the 9 gdb command definitions to `lines`. Pure gdb scripting — addresses come from `nm`,
--- **Fully hardcoded per-atom** because gdb doesn't do nested `$` substitution in var names
+--- the convenience vars set in `emit_gdb_runtime` provide printf args, and 
--- `$__atom_name_$__i` inside a `while` loop is treated as one literal identifier, not a concat.
+--- each command is a static sequence of `printf` / `tbreak` / `if ... end` blocks.
 --- The Lua pass emits N atoms' worth of lines; runtime iteration is gdb's job.
 ---
--- Each command is a static sequence of `printf` / `tbreak` / `if ... end` blocks.
+--- Why hardcoded per-atom: gdb's `$` substitution doesn't concat inside var names — `$__atom_name_$__i` in a `while`
--- The Lua pass emits N atoms' worth of lines — no runtime iteration. 
+--- loop resolves to one literal identifier, not `name_i`. Compile-time emission is the only path.
 --- With 7 atoms + ~200 word entries, the runtime file is ~2000 lines, all auto-generated, no human edit ever.
 --- @param lines   table  -- output line buffer (mutated in place)
 --- @param matched table  -- list of atom records from `build_atom_table`
 local function append_gdb_commands(lines, matched)
@@ -284,8 +260,7 @@ local function append_gdb_commands(lines, matched)
 	for _, a in ipairs(matched) do
 		-- gdb 12.1 quirk: literals in printf args require an attached target.
 		-- Use the per-atom convenience vars set above as printf args.
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format('  printf "  code_%%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
 			'  printf "  code_%%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
 			a.idx, a.idx, a.idx)
 	end
 	lines[#lines + 1] = "end"
@@ -298,8 +273,7 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "define break_atom"
 	lines[#lines + 1] = '  echo "Usage: break_atom_<exact_name>  (pick from the list below)"'
 	for _, a in ipairs(matched) do
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format('  printf "  break_atom_%%-32s\\n", $__atom_name_%d', a.idx)
 			'  printf "  break_atom_%%-32s\\n", $__atom_name_%d', a.idx)
 	end
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = "document break_atom"
@@ -310,8 +284,7 @@ local function append_gdb_commands(lines, matched)
 	for _, a in ipairs(matched) do
 		lines[#lines + 1] = string.format("define break_atom_%s", a.name)
 		lines[#lines + 1] = string.format("  break *$__atom_addr_%d", a.idx)
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format('  printf "  Breakpoint set at code_%s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
 			'  printf "  Breakpoint set at code_%s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
 		lines[#lines + 1] = "end"
 		lines[#lines + 1] = string.format("document break_atom_%s", a.name)
 		lines[#lines + 1] = string.format("  Set a breakpoint at code_%s.", a.name)
@@ -347,33 +320,24 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "  set $__matched = 0"
 	for _, a in ipairs(matched) do
 		-- Precompute end_addr (gdb 12.1's expression evaluator chokes on `addr + words*4`).
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format("  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
-			"  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(
+		lines[#lines + 1] = string.format('    printf "atom:    code_%%s\\n", $__atom_name_%d', a.idx)
 			"  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
 		lines[#lines + 1] = string.format(
 			'    printf "atom:    code_%%s\\n", $__atom_name_%d', a.idx)
 		lines[#lines + 1] = '    printf "addr:    0x%08x\\n", $__pc'
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format("    set $__word = ($__pc - $__atom_addr_%d) / 4", a.idx)
-			"    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)
 		lines[#lines + 1] = string.format(
 			'    printf "word:    %%d/%%d\\n", $__word, $__atom_words_%d', a.idx)
 		-- One inner-if per WORD entry. Each word's line + text hardcoded.
 		for _, we in ipairs(a.entries) do
-			lines[#lines + 1] = string.format(
+			lines[#lines + 1] = string.format("    if $__word == %d", we.pos)
 				"    if $__word == %d", we.pos)
 			-- Escape TEXT for printf format string.
 			local escaped_text = we.text:gsub("%%", "%%%%"):gsub('"', '\\"')
-			lines[#lines + 1] = string.format(
+			lines[#lines + 1] = string.format('      printf "source:  %%s:%%d  %%s\\n", $__atom_file_%d, %d, "%s"', a.idx, we.line, escaped_text)
 				'      printf "source:  %%s:%%d  %%s\\n", $__atom_file_%d, %d, "%s"',
 				a.idx, we.line, escaped_text)
 			lines[#lines + 1] = "    end"
 		end
 		-- Fallback for words beyond the source map (shouldn't happen if nm matches).
 		local max_word = 0
 		if #a.entries > 0 then max_word = a.entries[#a.entries].pos end
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format('    if $__word > %d', max_word)
 			'    if $__word > %d', max_word)
 		lines[#lines + 1] = '      printf "source:  (no source-map entry for word %%d; map may be stale)\\n", $__word'
 		lines[#lines + 1] = "    end"
 		lines[#lines + 1] = "    set $__matched = 1"
@@ -390,19 +354,16 @@ local function append_gdb_commands(lines, matched)
 	-- ── stepi_inside_atom ──
 	-- Hardcoded one if-containment-check per atom (no loop).
-	-- Precompute end_addr in Lua so we don't ask gdb to evaluate `addr + words*4`
+	-- Precompute end_addr in Lua so we don't ask gdb to evaluate `addr + words*4` inside the if condition
-	-- inside the if condition (gdb 12.1's expression evaluator chokes on the
+	-- (gdb 12.1's expression evaluator chokes on the `*` and emits a misleading 'function malloc' error in some gdb builds).
 	-- `*` and emits a misleading 'function malloc' error in some gdb builds).
 	lines[#lines + 1] = "define stepi_inside_atom"
 	lines[#lines + 1] = "  set $__in_atom = 0"
 	lines[#lines + 1] = "  set $__did_step = 0"
 	lines[#lines + 1] = "  set $__pc = (unsigned int)$pc"
 	for _, a in ipairs(matched) do
 		-- Precompute end_addr in the convenience var (single expression gdb handles).
-		lines[#lines + 1] = string.format(
+		lines[#lines + 1] = string.format("  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
-			"  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(
 			"  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
 		lines[#lines + 1] = "    set $__in_atom = 1"
 		lines[#lines + 1] = "    stepi"
 		lines[#lines + 1] = "    set $__did_step = 1"
@@ -418,32 +379,6 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = ""
 	-- ── show_c2 ──
 	-- GTE data regs (COP2). pcsx-redux's gdb stub doesn't expose COP2 (only
 	-- 72 regs: 32 GPR + COP0 + FPR).
 	--   curl http://localhost:8080/api/v1/lua/gte
 	-- We keep the command definition as a stub that points the user at the plugin.
 	lines[#lines + 1] = "define show_c2"
 	lines[#lines + 1] = '  echo "[gdb_tape_atoms] show_c2: gdb stub does not expose COP2 in this build."'
 	lines[#lines + 1] = '  echo "[gdb_tape_atoms] Use scripts/pcsx_debug_helper.zip + curl http://localhost:8080/api/v1/lua/gte"'
 	lines[#lines + 1] = '  echo "[gdb_tape_atoms] (or pcsx-redux Debug > Registers window for a native view)"'
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = "document show_c2"
 	lines[#lines + 1] = "  Stub. The gdb stub in this pcsx-redux build does not expose COP2 regs."
 	lines[#lines + 1] = "  For GTE data + control state, use the pcsx_debug_helper Lua plugin or the"
 	lines[#lines + 1] = "  pcsx-redux Debug > Registers window."
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = ""
 	-- ── show_c2ctl ──
 	lines[#lines + 1] = "define show_c2ctl"
 	lines[#lines + 1] = '  echo "[gdb_tape_atoms] show_c2ctl: see show_c2 for the same workaround."'
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = "document show_c2ctl"
 	lines[#lines + 1] = "  Stub. Same workaround as show_c2."
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = ""
 	-- ── wave_ctx ──
 	lines[#lines + 1] = "define wave_ctx"
 	lines[#lines + 1] = '  printf "$t4 = R_FaceCursor     0x%08x\\n", $t4'
@@ -456,13 +391,12 @@ local function append_gdb_commands(lines, matched)
 	lines[#lines + 1] = "end"
 end
--- Emit the gdb-runtime file (post-link). Pure gdb scripting — no Python.
+--- Emit the gdb-runtime file (post-link). Pure gdb scripting — addresses come from `mipsel-none-elf-nm -S`, get embedded
--- Reads ELF addresses via `mipsel-none-elf-nm -S`, embeds them in `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`
+--- in `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`, and load via `set $var = ...` + `define ... end` blocks at gdb source-time.
 --- so gdb loads the data via `set $var = ...` + `define ... end` blocks at source-time.
 --- @param ctx PassCtx
 local function emit_gdb_runtime(ctx)
 	if not (ctx.flags and ctx.flags.gdb_runtime) then return end
-	local elf_path = ctx.flags.elf_path
+	local  elf_path = ctx.flags.elf_path
 	if not elf_path or elf_path == "" then
 		io.stderr:write("[atoms_source_map] --gdb-runtime requires --elf <elf>\n")
 		return
@@ -516,13 +450,25 @@ 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 = ctx.out_root .. "/gdb_tape_atoms_runtime.gdb"
+	local out_path
-	if not ctx.dry_run then
+	-- 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`
-		duffle.ensure_dir(duffle.dirname(out_path))
+	-- (any equivalent spelling — relative, absolute backslash, absolute forward-slash, trailing-separator variants).
-		duffle.write_file_lf(out_path, table.concat(lines, "\n") .. "\n")
+	-- This puts the gdb runtime alongside the ELF at `build/` rather than under the report subdir.
 	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"
 	end
-	io.stderr:write(string.format(
+	if ends_with_gen_dir(ctx.out_root) then
-		"[atoms_source_map] wrote %s (%d atoms)\n", out_path, #matched))
+		-- 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[/\\]?$", "")
 		out_path = parent .. "/gdb_tape_atoms_runtime.gdb"
 	else
 		out_path = ctx.out_root .. "/gdb_tape_atoms_runtime.gdb"
 	end
 	duffle.ensure_dir(duffle.dirname(out_path))
 	duffle.write_file_lf(out_path, table.concat(lines, "\n") .. "\n")
 	-- io.stderr:write(string.format("[atoms_source_map] wrote %s (%d atoms)\n", out_path, #matched))
 end
 -- ════════════════════════════════════════════════════════════════════════════
@@ -531,10 +477,62 @@ end
 local M = {}
--- Pass entry: emit one `<out_root>/<basename>.atoms.sourcemap.txt` per source file
+-- Expose the pure render functions so `report.lua` and the focused tests can call them directly without triggering the file-emit path.
--- that contains at least one `MipsAtom_(name)` / `MipsCode code_<name>` declaration.
+M.render_source_map = render_source_map
--- Optionally also emit `<ctx.out_root>/gdb_tape_atoms_runtime.gdb` when
+M.render_provenance = render_provenance
--- `ctx.flags.gdb_runtime` is true.
+
 --- Render ONE atom's sourcemap stanza.
 --- @param atom table   -- atom record (must have `atom.paths` populated)
 --- @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 = {}
 	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",
 			entry.pos, entry.line, entry.text)
 	end
 	lines[#lines + 1] = "ENDATOM"
 	return table.concat(lines, "\n") .. "\n"
 end
 --- Render ONE atom's provenance stanza — no per-file format header, no enumeration of other atoms.
 ---
 --- `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
 --- @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 = {}
 	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]
 		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)
 		else
 			lines[#lines + 1] = string.format(
 				"WORD %d  CALL %s:%d  RAW", entry.pos, rel_path, entry.line)
 		end
 	end
 	return table.concat(lines, "\n") .. "\n"
 end
 --- Pass entry. For each source that declares at least one `MipsAtom_(name)` / `MipsCode code_<name>`,
 --- 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)
@@ -542,38 +540,22 @@ function M.run(ctx)
 	local errors   = {}
 	local warnings = {}
-	-- word-counts + components passes must have populated shared.word_counts.
+	local corpus = ctx.shared and ctx.shared.corpus
-	-- If absent, the orchestrator wired the deps wrong — fail loud.
+	if type(corpus) ~= "table" or type(corpus.source_order) ~= "table" then
-	local wc = (ctx.shared and ctx.shared.word_counts) or {}
+		error("atoms_source_map.run requires ctx.shared.corpus.source_order (canonical corpus).", 0)
-	if not wc or not next(wc) then
+	end
 	-- Word counts come from `corpus.word_counts` (populated by word_count_eval + components passes).
 	local wc = corpus.word_counts or {}
 	if not next(wc) then
 		warnings[#warnings + 1] = {
 			line = 0,
-			msg  = "atoms_source_map: ctx.shared.word_counts is empty; the word-counts + components passes may not have populated it. Check the PASSES dep edges.",
+			msg  = "atoms_source_map: corpus.word_counts is empty; the word-counts + components passes may not have populated it. Check the PASSES dep edges.",
 		}
 	end
-	-- Always emit the canonical text form (per-source).
+	-- atoms.sourcemap.txt + atoms.provenance.txt content moved to report.lua via `<module>.atoms.md` markdown file.
-	for _, src in ipairs(ctx.sources) do
+	-- This pass emits only the post-link gdb_runtime artifact (see emit_gdb_runtime below).
 		if src.scan then
 			local n_atoms     = src.scan.atoms and #src.scan.atoms or 0
 			local n_raw_atoms = src.scan.raw_atoms and #src.scan.raw_atoms or 0
 			if n_atoms + n_raw_atoms > 0 then
 				local basename = duffle.basename_no_ext(src.path)
 				-- Build report, NOT compile artifact: live in <out_root> alongside the other reports
 				-- (annotation.lua's *.errors.h, static_analysis.lua's *.static_analysis.txt, gdb_tape_atoms_runtime.gdb).
 				-- The per-source <source_dir>/gen/ is reserved for headers actually #included by C.
 				local out_path = ctx.out_root .. "/" .. basename .. ".atoms.sourcemap.txt"
 				local content  = render_source_map(src, wc)
 				if not ctx.dry_run then
 					duffle.ensure_dir(duffle.dirname(out_path))
 					duffle.write_file_lf(out_path, content)
 				end
 				outputs[#outputs + 1] = { kind = "report", path = out_path }
 			end
 		end
 	end
 	-- Optionally emit the gdb-runtime form (post-link, one file per build).
 	if ctx.flags and ctx.flags.gdb_runtime then
@@ -1,24 +1,14 @@
 --- passes/components.lua — Component-macro header generator.
 ---
--- Reads the pre-scanned SourceScan payload (produced once upstream by `duffle.scan_source`)
+--- Ownership: `corpus.word_counts`, `corpus.components`, and `corpus.component_body_index`.
--- for `MipsAtomComp_(ac_X)` and `MipsAtomComp_Proc_(ac_X, { body })` declarations, then does
+--- Scanner owns `declaration_comment` and `debug_skip` on each declaration record; this pass projects both forward.
 --- per-source backward lookups for the function-args string (from the preceding `FI_ MipsAtom ac_X(...)`
 --- function declaration) and the preceding comment block (for LSP/IntelliSense signature docs).
 ---
--- Emits a per-directory `<dir_basename>.macs.h` containing one `#define mac_X(sig) \` macro per component
+--- Reads the pre-scanned SourceScan payload from `duffle.scan_source` for `MipsAtomComp_(ac_X)` and `MipsAtomComp_Proc_(ac_X, { body })` declarations,
--- + `WORD_COUNT(mac_X, N)` entries for downstream offset computation.
+--- then resolves the function-args string from the preceding `FI_ Slice_MipsCode ac_X(...)` declaration via a backward walk.
 ---
--- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
+--- Emits one `gen/macs.h` per *immediate source directory* with `#define mac_X(sig) \` macros plus `WORD_COUNT(mac_X, N)` entries for downstream offset computation.
--- Lua 5.3 compatible.
+--- All sources inside the same directory contribute to the same file (per-directory aggregation).
-
+--- The directory itself is the namespace, so the filename does not repeat the module name.
 --- @class Component
 --- @field name    string
 --- @field body    string
 --- @field args    string|nil
 --- @field line    integer
 --- @field comment string|nil
 --- @class M
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
@@ -26,13 +16,11 @@
 -- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
 -- 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 word_count_eval = require("word_count_eval")
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
@@ -40,55 +28,56 @@ local word_count_eval = require("word_count_eval")
 -- Atom component declaration identifiers.
 local ATOM_COMP_PROC  = "MipsAtomComp_Proc_"
-local MIPS_ATOM       = "MipsAtom"  -- prefix on the function declaration that wraps an AtomComp_Proc_
+local MIPS_ATOM       = "Slice_MipsCode"  -- prefix on the function declaration that wraps an AtomComp_Proc_
 -- Component-name prefixes.
-local AC_PREFIX       = "ac_"        -- arg to MipsAtomComp_(ac_X); the X is the atom name
+local AC_PREFIX       = "ac_"  -- arg to MipsAtomComp_(ac_X); the X is the atom name
 local AC_PREFIX_LEN   = 3
-local MAC_PREFIX      = "mac_"       -- prefix on generated macros; the rest is the atom name
+local MAC_PREFIX      = "mac_" -- prefix on generated macros; the rest is the atom name
 local MAC_PREFIX_LEN  = 4
 -- ASCII byte values used in tokenization.
 local BYTE_NEWLINE    = 10
 local BYTE_SLASH      = 47
-- Source dir basename used as the output `.macs.h` filename.
+-- Output gen subdirectory + filename (per-directory aggregation; the directory name is the namespace).
 local GEN_SUBDIR      = "gen"
 local MACS_FILENAME   = "macs.h"
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
 -- ════════════════════════════════════════════════════════════════════════════
 --- @class SourceFile
--- @field path     string  -- absolute path to the source file
+--- @field path     string  -- Absolute path to the source file
--- @field text     string  -- the full source text
+--- @field text     string  -- Full source text
--- @field dir      string  -- the directory containing the source
+--- @field dir      string  -- Directory containing the source
--- @field basename string  -- filename without extension
+--- @field basename string  -- Filename without extension
--- @field scan     table   -- pre-scanned SourceScan payload (from duffle.scan_source)
+--- @field scan     table   -- Pre-scanned SourceScan payload (from duffle.scan_source)
 --- @class PassCtx
--- @field sources            SourceFile[]           -- all source files in the build
+--- @field sources            SourceFile[]           -- All source files in the build
--- @field metadata_path      string                 -- path to word_count.metadata.h
+--- @field metadata_path      string                 -- Path to word_count.metadata.h
--- @field shared             table                  -- cross-pass shared state
+--- @field shared             table                  -- Cross-pass shared state
--- @field shared.word_counts table<string, integer> -- populated by word-counts + components
+--- @field out_root           string                 -- Output root (e.g. "build/gen")
--- @field out_root           string                 -- output root (e.g. "build/gen")
+--- @field project_root       string                 -- Project root (e.g. "code/")
--- @field project_root       string                 -- project root (e.g. "code/")
+--- @field upstream           table<string, table>   -- Per-pass upstream outputs
 --- @field upstream           table<string, table>   -- per-pass upstream outputs
 --- @field flags              table                  -- CLI flags
--- @field dry_run            boolean                -- if true, compute but don't write
+--- @field verbose            boolean                -- Log diagnostic info
 --- @field verbose            boolean                -- log diagnostic info
 --- @class PassResult
 --- @field outputs  table[]  -- {kind=, path=} entries describing emit files
--- @field errors   table[]  -- {line=, msg=} entries; build-stops
+--- @field errors   table[]  -- {line=, msg=}  entries; build-stops
--- @field warnings table[]  -- {line=, msg=} entries; build-succeeds
+--- @field warnings table[]  -- {line=, msg=}  entries; build-succeeds
 --- @class Component
--- @field name    string        -- atom name (without `ac_` prefix)
+--- @field name       string     -- Atom name (without `ac_` prefix)
--- @field body    string        -- brace-delimited body (without the braces)
+--- @field body       string     -- Brace-delimited body (without the braces)
--- @field args    string|nil    -- function-args string (function form only)
+--- @field args       string|nil -- Function-args string (function form only)
--- @field line    integer       -- source line of the declaration
+--- @field line       integer    -- Source line of the declaration
--- @field comment string|nil    -- preceding `/* */` or `//` comment block (signature doc)
+--- @field comment    string|nil -- Scanner-owned `declaration_comment`; the components pass reads it from the scanner record
 --- @field kind       string     -- "comp_bare" | "comp_proc"
 --- @field debug_skip boolean    -- Mirror of `a.debug_skip` (scanner-owned); true iff a bare `atom_dbg_skip` marker immediately preceded the declaration
 -- ════════════════════════════════════════════════════════════════════════════
 -- Local helpers (file I/O + path normalization)
@@ -97,16 +86,28 @@ local GEN_SUBDIR      = "gen"
 local M = {}
 -- ════════════════════════════════════════════════════════════════════════════
-- Function-args extraction (precedes MipsAtomComp_Proc_ invocations)
+-- Back-walk helpers (composed into the entry point below: find_function_args_for)
 --
 -- Only the function-args lookup for proc components occurs here.
 -- The preceding-comment walk occur in `scan_source.lua` — `a.declaration_comment` carries the resolved comment,
 -- so this file reads it forward rather than re-walking the source.
 -- ════════════════════════════════════════════════════════════════════════════
-- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
+--- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
-- Returns the position of the open paren, or nil if not found.
+--- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
-- @param source string
+---
-- @param name string
+--- Convention: function form is
-- @param before_pos integer
+---   `FI_ Slice_MipsCode ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
-- @return integer|nil
+--- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
-local function find_last_name_open_paren(source, name, before_pos)
+--- We then verify the preceding context ends with `Slice_MipsCode`
 --- (the function-decl keyword with possible qualifiers between).
 ---
 --- @param source     string
 --- @param name       string
 --- @param before_pos integer
 --- @return string|nil
 local function find_function_args_for(source, name, before_pos)
 	-- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
 	local name_open  = name .. "("
 	local last_idx   = nil
 	local scan_pos   = 1
@@ -118,24 +119,6 @@ local function find_last_name_open_paren(source, name, before_pos)
 		last_idx = found
 		scan_pos = found + #name_open
 	end
 	return last_idx
 end
 --- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
 --- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
 ---
 --- Convention: function form is
 ---   `FI_ MipsAtom ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
 --- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
 --- We then verify the preceding context ends with `MipsAtom` 
 --- (the function-decl keyword with possible qualifiers between).
 ---
 --- @param source string
 --- @param name string
 --- @param before_pos integer
 --- @return string|nil
 local function find_function_args_for(source, name, before_pos)
 	local  last_idx = find_last_name_open_paren(source, name, before_pos)
 	if not last_idx then return nil end
 	-- Verify the preceding context ends with "MipsAtom" (with possible qualifiers between).
@@ -154,171 +137,10 @@ local function find_function_args_for(source, name, before_pos)
 	return inner
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Preceding-comment-block extraction
 -- ════════════════════════════════════════════════════════════════════════════
 -- Skip whitespace (space/tab/newline/CR) backward from `pos`, returning the position of the first non-whitespace char.
 -- @param source string
 -- @param pos integer
 -- @return integer
 local function skip_ws_backward(source, pos)
 	local back = pos - 1
 	while back > 0 do
 		local ch = source:sub(back, back)
 		if ch == " " or ch == "\t" or ch == "\n" or ch == "\r" then
 			back = back - 1
 		else
 			break
 		end
 	end
 	return back
 end
 -- Find the opening `/*` for a block comment whose `*/` ends at `close_pos`.
 -- Returns the position of `/`, or nil if not found.
 -- @param source string
 -- @param close_pos integer  -- position of the closing `*` of `*/`
 -- @return integer|nil
 local function find_block_comment_open(source, close_pos)
 	local prefix  = source:sub(1, close_pos - 1)
 	local open_at = nil
 	for scan = #prefix - 1, 1, -1 do
 		if prefix:sub(scan, scan + 1) == "/*" then
 			open_at = scan
 			break
 		end
 	end
 	return open_at
 end
 -- Walk back from `open_at` over leading spaces + tabs to include the indentation before the `/*` in the captured comment.
 -- @param source string
 -- @param open_at integer
 -- @return integer
 local function extend_left_over_indent(source, open_at)
 	local start = open_at
 	while start > 1 do
 		local ch = source:sub(start - 1, start - 1)
 		if ch == " " or ch == "\t" then
 			start = start - 1
 		else
 			break
 		end
 	end
 	return start
 end
 -- Walk back from `line_end` to the start of the source line (the most recent `\n` or position 1).
 -- @param source string
 -- @param line_end integer
 -- @return integer
 local function find_line_start(source, line_end)
 	local start = line_end
 	while start > 1 and source:sub(start - 1, start - 1) ~= "\n" do
 		start = start - 1
 	end
 	return start
 end
 -- (internal) Capture one `/* ... */` block comment whose closing `*/`
 -- ends at `close_end_pos`. Returns (block_text, new_scan_pos) where `new_scan_pos`
 -- is where to continue scanning for more comments, or nil if no block comment was found.
 local function capture_block_comment(source, close_end_pos)
 	local  open_at = find_block_comment_open(source, close_end_pos)
 	if not open_at then return nil end
 	local block_start = extend_left_over_indent(source, open_at)
 	return source:sub(block_start, close_end_pos), block_start
 end
 -- (internal) Capture one `// ...` line comment ending at `line_end_pos`.
 -- Returns (comment_text, new_scan_pos) or nil if the line is not a `//` comment.
 local function capture_line_comment(source, line_end_pos)
 	local line_start = find_line_start(source, line_end_pos)
 	local line       = source:sub(line_start, line_end_pos)
 	if line:sub(1, 2) == "//" then
 		return line, line_start - 1
 	end
 	return nil
 end
 --- Find the contiguous comment block immediately preceding `pos` in `source`.
 --- Returns the comment text (with the `/* */` or `//` markers preserved) or an empty string if no comment is adjacent.
 ---
 --- Used to copy signature comments from the source declaration (`MipsAtomComp_` / `MipsAtomComp_Proc_` / function decl)
 --- over to the generated `mac_X` macro, so LSP/IntelliSense displays the args doc.
 ---
 --- @param source string
 --- @param pos integer
 --- @return string
 local function preceding_comment_block(source, pos)
 	local scan_pos = pos
 	local pieces   = {}
 	while true do
 		local non_ws = skip_ws_backward(source, scan_pos)
 		if    non_ws == 0 then break end
 		local is_block_close = non_ws >= 2 and source:sub(non_ws - 1, non_ws) == "*/"
 		local is_line_end    = source:sub(non_ws, non_ws) == "\n" or source:sub(non_ws, non_ws) == "\r"
 		if is_block_close then
 			local  block_text, new_scan_pos = capture_block_comment(source, non_ws)
 			if not block_text then break end
 			table.insert(pieces, 1, block_text)
 			scan_pos = new_scan_pos
 		elseif is_line_end then
 			local  line_text, new_scan_pos = capture_line_comment(source, non_ws)
 			if not line_text then break end
 			table.insert(pieces, 1, line_text)
 			scan_pos = new_scan_pos
 		else
 			break
 		end
 	end
 	if #pieces == 0 then return "" end
 	return table.concat(pieces, "\n")
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Argument-name extraction
 -- ════════════════════════════════════════════════════════════════════════════
 -- Walk `trimmed` backward from `pos` over trailing whitespace / asterisks / brackets, 
 -- returning the position of the first non-trailer character (i.e. the end of the identifier).
 -- @param trimmed string
 -- @param pos integer
 -- @return integer
 local function trim_trailer_back(trimmed, pos)
 	local back = pos
 	while back > 0 do
 		local ch = trimmed:sub(back, back)
 		if ch == " " or ch == "\t" or ch == "*" or ch == "]" or ch == "[" then
 			back = back - 1
 		else
 			break
 		end
 	end
 	return back
 end
 -- Walk `trimmed` backward from `pos` over identifier chars (alnum + `_`),
 -- returning the position just before the identifier starts.
 -- @param trimmed string
 -- @param pos integer
 -- @return integer
 local function trim_ident_back(trimmed, pos)
 	local back = pos
 	while back > 0 do
 		local ch = trimmed:sub(back, back)
 		if duffle.is_alnum(ch) or ch == "_" then
 			back = back - 1
 		else
 			break
 		end
 	end
 	return back
 end
 --- Extract just the parameter NAMES from a function-args string (stripping type annotations). E.g.,
 ---   `"U4 off, U4 code, U1 r, U1 g, U1 b"`  ->  `{"off", "code", "r", "g", "b"}`
 ---   `"U4 *ptr"`                            ->  `{"ptr"}`
@@ -332,9 +154,28 @@ local function extract_arg_names(args_str)
 	for _, tok in ipairs(tokens) do
 		local trimmed = duffle.trim(tok)
 		if trimmed ~= "" then
-			local ident_end   = trim_trailer_back(trimmed, #trimmed)
+			-- Find the identifier at the end: walk back over trailers (whitespace + `*` + `[]`),
-			local ident_start = trim_ident_back(trimmed, ident_end) + 1
+			-- then walk back over the identifier chars (alnum + `_`).
-			local name        = trimmed:sub(ident_start, ident_end)
+			local ident_end = #trimmed
 			while ident_end > 0 do
 				local ch = trimmed:sub(ident_end, ident_end)
 				if ch == " " or ch == "\t" or ch == "*" or ch == "]" or ch == "[" then
 					ident_end = ident_end - 1
 				else
 					break
 				end
 			end
 			local ident_start = ident_end
 			while ident_start > 0 do
 				local ch = trimmed:sub(ident_start, ident_start)
 				if duffle.is_alnum_byte(string.byte(ch)) or ch == "_" then
 					ident_start = ident_start - 1
 				else
 					break
 				end
 			end
 			ident_start = ident_start + 1
 			local name = trimmed:sub(ident_start, ident_end)
 			if name ~= "" then names[#names + 1] = name end
 		end
 	end
@@ -346,26 +187,34 @@ end
 -- Component projection (read from pre-scanned SourceScan)
 -- ════════════════════════════════════════════════════════════════════════════
-- Project pre-scanned MipsAtomComp_ / MipsAtomComp_Proc_ entries into Component shape.
+--- Project pre-scanned MipsAtomComp_ / MipsAtomComp_Proc_ entries into Component shape.
-- Does per-source backward lookups for args (preceding function decl) and comment (preceding comment block).
+--- Reads the scanner-owned `declaration_comment` (resolved by scan_source.lua, skipping backward across an associated bare `atom_dbg_skip` marker when present).
-- Carries `body_tokens` forward from scan-source so word_count_rec reads from the precomputed table
+--- Per-source backward lookups remain in place only for the function `args` of proc components.
-- instead of calling duffle.tokenize_body again.
+--- That lookup is unique to components.lua and stays separate from the declaration-comment walk.
-- @param source string  -- the full source text (needed for backward lookups)
+--- Carries `body_tokens` forward from scan-source so word_count_rec reads from the precomputed table instead of calling duffle.tokenize_body again.
-- @param scan  table   -- SourceScan from duffle.scan_source
+--- Carries the scanner-owned `debug_skip` flag forward so the generated projection can emit `/* atom_dbg_skip */`
-- @return Component[]
+--- before the authored comment and so `update_canonical_components` can mirror the same field onto `corpus.components[name]`.
 --- @param source string  -- the full source text (needed for backward lookups)
 --- @param scan   table   -- SourceScan from duffle.scan_source
 --- @return Component[]
 local function project_components(source, scan)
 	local out = {}
 	for _, a in ipairs(scan.atoms) do
 		if a.kind == "comp_bare" or a.kind == "comp_proc" then
-			local args    = find_function_args_for(source, a.raw_name, a.ident_pos)
+			local args = find_function_args_for(source, a.raw_name, a.ident_pos)
-			local comment = preceding_comment_block(source, a.ident_pos)
+			-- Comment ownership: scan_source.lua stamps `declaration_comment` on the record by walking backward past any associated bare marker.
 			-- The pass reads `declaration_comment` directly.
 			local comment = a.declaration_comment or ""
 			out[#out + 1] = {
 				line        = a.line,
 				name        = a.name,
 				body        = a.body,
 				body_off    = a.body_off,
 				body_tokens = a.body_tokens,
 				args        = args,
 				comment     = comment,
 				kind        = a.kind,  -- "comp_bare" | "comp_proc"; provenance emitter reads this.
 				debug_skip  = a.debug_skip == true,
 			}
 		end
 	end
@@ -382,7 +231,6 @@ end
 --
 -- Skips `//` sequences that are inside string or character literals
 -- (a rough heuristic — sufficient for component bodies which don't have those constructs).
 --
 --- @param s string
 --- @return string
 local function convert_line_comments_to_block(s)
@@ -419,11 +267,11 @@ end
 -- Word-count computation (memoized recursive lookup)
 -- ════════════════════════════════════════════════════════════════════════════
-- Strip the `mac_` prefix from a component-call ident so we can look it up against the components-by-name table. 
+--- Strip the `mac_` prefix from a component-call ident so we can look it up against the components-by-name table. 
-- Returns the ident unchanged if it doesn't start with the prefix 
+--- Returns the ident unchanged if it doesn't start with the prefix 
-- (so a non-component ident like `mask_upper` falls through to the wc-table branch).
+--- (so a non-component ident like `mask_upper` falls through to the wc-table branch).
-- @param ident string|nil
+--- @param ident string|nil
-- @return string|nil
+--- @return string|nil
 local function strip_mac_prefix(ident)
 	if not ident then return nil end
 	if ident:sub(1, MAC_PREFIX_LEN) == MAC_PREFIX then
@@ -432,13 +280,13 @@ local function strip_mac_prefix(ident)
 	return ident
 end
-- (internal) Recursive word-count lookup. `cache` is the memoization table shared across all components
+--- (internal) Recursive word-count lookup. `cache` is the memoization table shared across all components
-- in a single source's `count_all_components` pass; the in-progress -1 sentinel detects cycles (A -> B -> A).
+--- in a single source's `count_all_components` pass; the in-progress -1 sentinel detects cycles (A -> B -> A).
-- @param name string -- the component name (without `mac_`)
+--- @param name         string -- the component name (without `mac_`)
-- @param comp_by_name table<string, Component>
+--- @param comp_by_name table<string, Component>
-- @param wc table<string, integer>
+--- @param wc           table<string, integer>
-- @param cache table<string, integer>
+--- @param cache        table<string, integer>
-- @return integer
+--- @return integer
 local function word_count_rec(name, comp_by_name, wc, cache)
 	if cache[name] ~= nil then return cache[name] end
 	cache[name] = -1  -- mark in-progress (cycle detection)
@@ -451,7 +299,7 @@ local function word_count_rec(name, comp_by_name, wc, cache)
 			local trimmed = t.tok
 			if trimmed ~= "" then
 				local lookup = strip_mac_prefix(duffle.read_ident(trimmed, 1))
-				if lookup and comp_by_name[lookup] then
+				if    lookup and comp_by_name[lookup] then
 					-- It's a `mac_X(...)` call. Recurse.
 					n = n + word_count_rec(lookup, comp_by_name, wc, cache)
 				elseif lookup and wc and wc[lookup] then
@@ -473,12 +321,11 @@ end
 --- Compute word counts for every component in `components` in a single pass.
 --- The name-lookup table + memoization cache are built ONCE (per source) instead of per-component,
--- so the cache survives across siblings and a component's recursive `mac_Y(...)` references hit memoized values
+--- so the cache survives across siblings and a component's recursive `mac_Y(...)` 
--- instead of re-walking the body.
+--- references hit memoized values instead of re-walking the body.
 --- Cycle detection (A -> B -> A) is preserved via the in-progress `-1` sentinel in `cache`.
 ---
 --- @param components Component[]
--- @param wc table<string, integer>
+--- @param wc         table<string, integer>
 --- @return table<string, integer>  -- map of component name (without `mac_`) -> word count
 local function count_all_components(components, wc)
 	local comp_by_name = {}
@@ -491,6 +338,116 @@ local function count_all_components(components, wc)
 	return counts
 end
 -- ═══════════════════════════════════════════
 -- Per-component metadata derivation (replaces the hardcoded `M.GP0_MACRO_CONTRIB` + `M.INSTRUCTION_LATENCY[mac_*]` tables that previously lived in `duffle.lua`).
 --
 -- Each `MipsAtomComp_(ac_X) { body }` definition in `code/duffle/lottes_tape.h` is the canonical source.
 -- The `mac_X(...)` macros are GENERATED from these definitions by `emit_component_macros_h` for tape-side composition;
 -- the metaprogram must NEVER walk the generated variants to derive metadata.
 -- Always walk the original `MipsAtomComp_` body via `cc.body_tokens`.
 -- ═══════════════════════════════════════════
 --- (internal) Recursive cycle-cost derivation. Sum `latency[ident]` per emitted instruction in the component body,
 --- recursing through nested `mac_*` calls (so `mac_format_g4_color`'s cost = 4 × `mac_pack_color_word`'s cost).
 --- Special rule: `mac_yield`'s cost = 0 (per `lottes_tape.h:125-130` "the runtime cost lands in the next atom's prologue").
 --- @param name         string  -- component bare name (e.g. "yield", "pack_color_word")
 --- @param comp_by_name table<string, Component>
 --- @param latency      table<string, integer>
 --- @param cache        table<string, integer>  -- shared memoization; `-1` sentinel detects cycles
 --- @return integer
 local function cycle_cost_rec(name, comp_by_name, latency, cache)
 	if cache[name] ~= nil then return cache[name] end
 	cache[name] = -1
 	local cc = comp_by_name[name]
 	local n
 	if cc then
 		if name == "yield" then
 			-- mac_yield's cost is 0 by convention (the runtime cost lands in the next atom's prologue).
 			n = 0
 		else
 			n = 0
 			local tokens = cc.body_tokens
 			for _, t in ipairs(tokens) do
 				local trimmed = t.tok
 				if trimmed ~= "" then
 					local ident = duffle.read_ident(trimmed, 1)
 					if ident and ident:sub(1, MAC_PREFIX_LEN) == MAC_PREFIX then
 						-- Nested `mac_X(...)` call: recurse.
 						local nested = ident:sub(MAC_PREFIX_LEN + 1)
 						n = n + cycle_cost_rec(nested, comp_by_name, latency, cache)
 					else
 						-- Leaf instruction or pseudo-macro. Look up in INSTRUCTION_LATENCY; default 1.
 						n = n + (latency[ident] or 1)
 					end
 				end
 			end
 		end
 	else
 		n = 1
 	end
 	cache[name] = n
 	return n
 end
 --- (internal) Recursive GP0 prim-buffer contribution. Count `store_word` / `store_half` / `store_byte` 
 --- calls in the component body that target `R_PrimCursor` (these are the
 --- RAM-side prim-buffer words the macro contributes), recursing through nested `mac_*` calls.
 --- Only `R_PrimCursor`-targeting stores count. Stores targeting other registers (e.g. `R_OtBase`, heap pointers) are not prim-buffer contributions.
 --- @param name         string
 --- @param comp_by_name table<string, Component>
 --- @param cache        table<string, integer>
 --- @return integer
 local function gp0_contrib_rec(name, comp_by_name, cache)
 	if cache[name] ~= nil then return cache[name] end
 	cache[name] = -1
 	local cc = comp_by_name[name]
 	local n
 	if cc then
 		n = 0
 		local tokens = cc.body_tokens
 		for _, t in ipairs(tokens) do
 			local trimmed = t.tok
 			if    trimmed ~= "" then
 				local ident = duffle.read_ident(trimmed, 1)
 				if    ident and ident:sub(1, MAC_PREFIX_LEN) == MAC_PREFIX then
 					-- Nested `mac_X(...)` call: recurse.
 					local nested = ident:sub(MAC_PREFIX_LEN + 1)
 					n = n + gp0_contrib_rec(nested, comp_by_name, cache)
 				elseif ident == "store_word" or ident == "store_half" or ident == "store_byte" then
 					if trimmed:find("R_PrimCursor", 1, true) then
 						n = n + 1
 					end
 				end
 			end
 		end
 	else
 		n = 0
 	end
 	cache[name] = n
 	return n
 end
 --- Compute `cycle_cost` + `gp0_contrib` for every component in `components` in a single pass.
 --- Memoization cache is built ONCE (per source) and shared across both helpers so that
 --- a nested `mac_Y` reference inside a `mac_X` body computes its values once.
 --- @param components Component[]
 --- @param latency    table<string, integer>
 --- @return table<string, {cycle_cost=integer, gp0_contrib=integer}>
 local function compute_components_metadata(components, latency)
 	local comp_by_name = {}
 	for _, cc in ipairs(components) do comp_by_name[cc.name] = cc end
 	local cc_cache  = {}
 	local gc_cache  = {}
 	local out       = {}
 	for _, c in ipairs(components) do
 		out[c.name] = {
 			cycle_cost = cycle_cost_rec(c.name, comp_by_name, latency, cc_cache),
 			gp0_contrib = gp0_contrib_rec(c.name, comp_by_name, gc_cache),
 		}
 	end
 	return out
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Per-component emit logic
 -- ════════════════════════════════════════════════════════════════════════════
@@ -500,8 +457,8 @@ end
 --- @param s string
 --- @return string[]
 local function split_comment_lines(s)
-	local out  = {}
+	local out   = {}
-	local pos  = 1
+	local pos   = 1
 	local s_len = #s
 	while pos <= s_len do
 		local nl = s:find("\n", pos, true)
@@ -515,13 +472,6 @@ local function split_comment_lines(s)
 	return out
 end
 --- Split an atom body by top-level commas; drop empty tokens.
 --- @param body string
 --- @return string[]
 local function tokens_from_body(body)
 	return duffle.tokenize_body_simple(body)
 end
 --- Determine the macro signature: function-args list (function form) or variadic-ignored (bare form).
 --- @param args_str string|nil
 --- @return string
@@ -558,23 +508,34 @@ end
 --- Build the list of lines for one component
 --- (signature comment, `#define mac_X(...)` line with backslash-continued tokens, then `WORD_COUNT(mac_X, N)` entry).
--- @param c Component
+--- For skipped components, a `/* atom_dbg_skip */` marker comment is emitted immediately before the authored comment block.
 --- The marker is a single line, the comment comes next, and the `#define` line follows. The `debug_skip` stamp is scanner-owned
 --- (`a.debug_skip == true` on the declaration record); the components pass projects it directly.
 --- @param c          Component
 --- @param components Component[]
--- @param wc table<string, integer>
+--- @param wc         table<string, integer>
 --- @return string[]  -- list of lines for this component
 local function build_component_lines(c, counts)
 	local lines = {}
 	-- Marker comment: emitted once for every skipped component.
 	-- The marker is scanner-owned (declared by `atom_dbg_skip` immediately before the declaration in the source);
 	-- the components pass projects `c.debug_skip` and emits the marker as a generated comment.
 	if c.debug_skip then
 		lines[#lines + 1] = "/* atom_dbg_skip */"
 	end
 	if c.comment and c.comment ~= "" then
 		for _, line in ipairs(split_comment_lines(c.comment)) do
 			lines[#lines + 1] = line
 		end
 	end
-	local tokens = tokens_from_body(c.body)
+	local tokens = duffle.split_top_level_commas(c.body)
-	local sig    = signature_from_args(c.args)
+	for i = 1, #tokens do tokens[i] = duffle.trim(tokens[i]) end
 	local sig = signature_from_args(c.args)
 	-- Direct lookup against the per-source precomputed `counts` table (built once by count_all_components).
-	local n      = counts[c.name]
+	local n   = counts[c.name]
 	if n > 0 then
 		emit_macro_body(lines, c, sig, tokens)
@@ -591,11 +552,17 @@ end
 -- Per-source emit logic
 -- ════════════════════════════════════════════════════════════════════════════
-- Build the boilerplate header lines (the `#ifdef INTELLISENSE_DIRECTIVES` block,
+--- Build the boilerplate header lines (the `#ifdef INTELLISENSE_DIRECTIVES` block,
-- the `// Auto-generated` comment, the `// Source:` line, and the self-contained `WORD_COUNT` macro definition).
+--- the `// Auto-generated` comment, the `// Source:` line, and the self-contained `WORD_COUNT` macro definition).
-- @param src SourceFile
+--- @param dir     string       -- the absolute source directory
-- @return string[]
+--- @param sources SourceFile[] -- sources contributing to this directory (for the header comment)
-local function header_boilerplate(src)
+--- @return string[]
 local function header_boilerplate(dir, sources)
 	local source_lines = { "// Directory: " .. duffle.to_absolute_path(dir) .. "/" }
 	for _, src in ipairs(sources) do
 		source_lines[#source_lines + 1] = "//   source: " .. duffle.to_absolute_path(src.path)
 	end
 	local source_blob = table.concat(source_lines, "\n")
 	return {
 		-- #pragma once wrapped in #ifdef INTELLISENSE_DIRECTIVES, matching the convention in lottes_tape.h.
 		-- The build does manual unity includes (the user controls include order), so the pragma is only active for IDE/tooling.
@@ -603,12 +570,12 @@ local function header_boilerplate(src)
 		"#pragma once",
 		"#endif",
 		"// Auto-generated by ps1_meta.lua — DO NOT EDIT",
-		"// Source: " .. duffle.to_absolute_path(src.path),
+		source_blob,
 		"// Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)",
 		"",
 		-- Self-contained: define WORD_COUNT if not already defined.
-		-- We use the same definition here so the auto-generated entries below expand to compile-time constants whether
+		-- We use the same definition here so the auto-generated entries below expand
-		-- the metadata file is included first or not.
+		-- to compile-time constants whether the metadata file is included first or not.
 		"#ifndef WORD_COUNT",
 		"#define WORD_COUNT(name, count)  enum { words_##name = (count) };",
 		"#endif",
@@ -616,32 +583,30 @@ local function header_boilerplate(src)
 	}
 end
-- Compute the output path for one source's `.macs.h` file.
+--- Compute the per-directory output path for `.macs.h`.
-- The pre-rework convention uses the *directory* basename
+---  e.g. any source in `code/duffle/` produces `code/duffle/gen/macs.h` regardless of source filename.
-- (not the source file basename) — e.g. `code/duffle/lottes_tape.h` produces `code/duffle/gen/duffle.macs.h`.
+--- The directory name is the namespace; the filename does not repeat it.
-- This matches what the C codebase #includes.
+--- @param dir string  -- the absolute source directory
-- @param src SourceFile
+--- @return string  -- the output directory
-- @return string  -- the output directory
+--- @return string  -- the full output path
-- @return string  -- the full output path
+local function compute_macs_h_path(dir)
-local function compute_macs_h_path(src)
+	local  out_dir  = dir .. "/" .. GEN_SUBDIR
-	local  out_dir  = src.dir .. "/" .. GEN_SUBDIR
+	local  out_path = out_dir .. "/" .. MACS_FILENAME
 	local  out_path = out_dir .. "/" .. duffle.basename_no_ext(src.dir) .. ".macs.h"
 	return out_dir, out_path
 end
--- Emit a per-source `.macs.h` header with the `mac_X` macros + `WORD_COUNT` entries. 
+--- Emit a per-directory `.macs.h` header with the aggregated `mac_X` macros + `WORD_COUNT` entries.
 --- Writes in BINARY mode so LF line endings are preserved (the git blob is LF; Windows text-mode would emit CRLF and break the byte-identical diff).
--- Honors `ctx.dry_run`: prints the intended path but does not write the file.
+--- @param ctx        PassCtx
---
+--- @param dir        string                  -- the absolute source directory
--- @param ctx PassCtx
+--- @param sources    SourceFile[]            -- sources contributing to this directory (for the header comment)
--- @param src SourceFile
+--- @param components Component[]             -- aggregated components from all sources in this directory
--- @param components Component[]
+--- @param counts     table<string, integer>  -- precomputed word counts (from count_all_components)
 --- @param counts table<string, integer>  -- precomputed word counts (from count_all_components)
 --- @return string|nil  -- path to the written file (nil if no components)
-local function emit_component_macros_h(ctx, src, components, counts)
+local function emit_component_macros_h(ctx, dir, sources, components, counts)
 	if #components == 0 then return nil end
-	local out_dir, out_path = compute_macs_h_path(src)
+	local out_dir, out_path = compute_macs_h_path(dir)
-	local lines             = header_boilerplate(src)
+	local lines             = header_boilerplate(dir, sources)
 	for _, c in ipairs(components) do
 		for _, l in ipairs(build_component_lines(c, counts)) do
@@ -650,11 +615,6 @@ local function emit_component_macros_h(ctx, src, components, counts)
 	end
 	local content = table.concat(lines, "\n") .. "\n"
 	if ctx.dry_run then
 		print(string.format("  -> %s (dry-run)", out_path))
 		return out_path
 	end
 	duffle.ensure_dir(out_dir)
 	duffle.write_file_lf(out_path, content)
 	print(string.format("  -> %s", out_path))
@@ -665,15 +625,94 @@ end
 -- Pass entry
 -- ════════════════════════════════════════════════════════════════════════════
-- (internal) Extend `ctx.shared.word_counts` with this source's component macros
+--- (internal) Extend `corpus.word_counts` with this source's component macros so offsets sees them without re-reading the file.
-- so offsets sees them without re-reading the file.
+--- First declaration wins: a later caller's count is dropped (the existing entry from the first source is preserved).
-- @param ctx PassCtx
+--- @param corpus     table  -- the corpus
-- @param components Component[]
+--- @param components Component[]
-- @param counts table<string, integer>  -- precomputed word counts (from count_all_components)
+--- @param counts     table<string, integer>  -- precomputed word counts (from count_all_components)
-local function update_shared_word_counts(ctx, components, counts)
+local function update_canonical_word_counts(corpus, components, counts)
-	local wc = ctx.shared.word_counts
+	local wc = corpus.word_counts
 	for _, c in ipairs(components) do
-		wc["mac_" .. c.name] = counts[c.name]
+		local key = "mac_" .. c.name
 		if wc[key] == nil then
 			wc[key] = counts[c.name]
 		end
 	end
 end
 --- @class ComponentDef
 --- @field name       string  -- bare name (without ac_/mac_ prefix)
 --- @field line       integer -- definition source line (line of `MipsAtomComp_(ac_X)` / `MipsAtomComp_Proc_(ac_X, ...)`)
 --- @field path       string  -- absolute source path of the definition
 --- @field kind       string  -- "comp_bare" | "comp_proc"
 --- @field debug_skip boolean -- mirror of the scanner-owned `a.debug_skip`; consumers read this directly
 --- (internal) Populate `corpus.components` with this source's components-by-name map.
 --- First declaration wins; later declarations of the same bare name are dropped and recorded as a collision via `corpus.collisions` (kind = "component").
 --- The pass does NOT write to `ctx.shared.components`.
 --- No parallel skip map is built here; consumers that need the per-component skip state read `corpus.components[name].debug_skip` directly.
 --- The `cycle_cost` + `gp0_contrib` fields are populated from `metadata[c.name]` (computed by `compute_components_metadata` against the original `MipsAtomComp_` body).
 --- @param corpus     table   -- the corpus
 --- @param src        SourceFile
 --- @param components Component[]
 --- @param metadata    table<string, {cycle_cost=integer, gp0_contrib=integer}>
 local function update_canonical_components(corpus, src, components, metadata)
 	local rel_path = src.path:gsub("\\", "/")
 	for _, c in ipairs(components) do
 		-- Keyed by bare name (e.g. `yield`, `load_tri_indices`).
 		-- The atoms_source_map pass looks up components by bare name from the corpus;
 		-- `mac_` prefix lives at the call-site identifier and is stripped before lookup.
 		local m = metadata and metadata[c.name] or nil
 		if corpus.components[c.name] == nil then
 			corpus.components[c.name] = {
 				name        = c.name,
 				line        = c.line,
 				path        = rel_path,
 				kind        = c.kind or "comp_bare",
 				debug_skip  = c.debug_skip == true,
 				cycle_cost  = m and m.cycle_cost  or nil,
 				gp0_contrib = m and m.gp0_contrib or nil,
 			}
 		else
 			-- A second declaration of the same bare name: record a typed collision so static-analysis + the report can surface it.
 			-- Identical-shape declarations (same path + line) reuse the first-wins entry without a collision record.
 			local existing = corpus.components[c.name]
 			if existing.path ~= rel_path or existing.line ~= c.line then
 				local kind       = c.kind or "comp_bare"
 				local first_kind = existing.kind or "comp_bare"
 				corpus.collisions[#corpus.collisions + 1] = {
 					kind              = "component",
 					name              = c.name,
 					first_site        = { path = existing.path, line = existing.line },
 					conflicting_site  = { path = rel_path,       line = c.line },
 					first_shape       = "kind=" .. first_kind,
 					conflicting_shape = "kind=" .. kind,
 				}
 			end
 		end
 	end
 end
 --- (internal) Populate `corpus.component_body_index` with this source's body index entries.
 --- First declaration wins; later declarations are dropped (no separate collision record: the components collision is already surfaced by `update_canonical_components`).
 --- The pass writes to `corpus.component_body_index` only (the corpus owns this projection).
 --- @param corpus     table  -- the corpus
 --- @param src        SourceFile
 --- @param components Component[]
 --- @param scan       table  -- the SourceScan payload (for line_of)
 local function update_canonical_component_body_index(corpus, src, components, scan)
 	local line_of = scan and scan.line_of
 	for _, c in ipairs(components) do
 		if corpus.component_body_index[c.name] == nil then
 			corpus.component_body_index[c.name] = {
 				body_tokens = c.body_tokens,
 				body_off    = c.body_off,
 				line_of     = line_of,
 				source      = src.path,
 				declaration = c.line,
 				kind        = c.kind,
 			}
 		end
 	end
 end
@@ -684,16 +723,59 @@ function M.run(ctx)
 	local errors   = {}
 	local warnings = {}
-	for _, src in ipairs(ctx.sources) do
+	-- Corpus ownership gate.
-		-- project_components reads from src.scan + does backward lookups on src.text
+	local corpus = ctx.shared and ctx.shared.corpus
-		local components = project_components(src.text, src.scan)
+	if type(corpus) ~= "table" then
-		if #components > 0 then
+		error("components.run requires ctx.shared.corpus.", 0)
-			-- Compute word counts for ALL components once (was: rebuilt per call inside the helpers).
+	end
-			local counts = count_all_components(components, ctx.shared.word_counts)
+	if type(corpus.source_order) ~= "table" then
-			local macs_path = emit_component_macros_h(ctx, src, components, counts)
+		error("components.run requires ctx.shared.corpus.source_order.", 0)
 	end
 	if type(corpus.word_counts) ~= "table" then
 		error("components.run requires ctx.shared.corpus.word_counts; "
 			.. "word_count_eval.run must run before components.run "
 			.. "(see PASSES deps).", 0)
 	end
 	-- Projection ownership:
 	--   * `corpus.word_counts["mac_"..name]` — current component count
 	--   * `corpus.components[name]`         — bare-name component definition
 	--   * `corpus.component_body_index[name]` — body / line_of / source index
 	-- The pass writes to the corpus only; consumers read from the corpus directly.
 	-- Per-directory aggregation: every source in the same directory contributes to one `gen/macs.h`.
 	-- The directory itself is the namespace. `corpus.sources_by_dir` preserves source-order within each bucket (matches `corpus.source_order`).
 	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
 		-- Aggregate components from every source in this directory.
 		-- `project_components` returns nil for sources with no `MipsAtomComp_` declarations; we skip those.
 		local aggregated_components = {}
 		local metadata_per_source   = {}
 		for _, src in ipairs(sources) do
 			local per_source = project_components(src.text, src.scan) or {}
 			for _, c in ipairs(per_source) do
 				aggregated_components[#aggregated_components + 1] = c
 			end
 			if #per_source > 0 then
 				metadata_per_source[src] = compute_components_metadata(per_source, duffle.INSTRUCTION_LATENCY)
 			end
 		end
 		if #aggregated_components > 0 then
 			-- Compute word counts across the aggregated set. `corpus.word_counts` carries the
 			-- same-source + prior-directory entries so the recursive lookup sees both.
 			local counts    = count_all_components(aggregated_components, corpus.word_counts)
 			local macs_path = emit_component_macros_h(ctx, dir, sources, aggregated_components, counts)
 			if macs_path then
 				outputs[#outputs + 1] = { macs_h = macs_path }
-				update_shared_word_counts(ctx, components, counts)
+				-- Populate the projections AFTER disk emission (byte-identical `.macs.h` contract).
 				update_canonical_word_counts(corpus, aggregated_components, counts)
 				for _, src in ipairs(sources) do
 					local per_source = project_components(src.text, src.scan) or {}
 					if #per_source > 0 then
 						update_canonical_components(corpus, src, per_source, metadata_per_source[src])
 						update_canonical_component_body_index(corpus, src, per_source, src.scan)
 					end
 				end
 			end
 		end
 	end
@@ -0,0 +1,237 @@
 --- 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)`.
 --- 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.
 ---
 --- Source-order discipline:
 ---   * `corpus.source_order` sets the source-record order.
 ---   * Within each source, the pass visits `src.scan.atoms` and `src.scan.raw_atoms` in declaration order.
 ---
 --- Per-atom projection fields on `atom.paths`:
 ---   `tokens`, `line_in_body`, `items`, `word_events`, `markers`, `invocations`, `errors`, `warnings`.
 ---   The construction walk appends `items` and derives each dense view from that ordered stream.
 ---
 --- Component expansion and construction validation:
 ---   * known `mac_X(...)` calls recursively expand component bodies;
 ---   * invocation records retain monotonic IDs, parent IDs, immediate call text, and the immutable outermost root call text;
 ---   * invocation construction stamps `debug_skip` from `corpus.components[name].debug_skip` at the construction site (no second pass, no source parse, no parallel lookup);
 ---   * component cycles close balanced invocation boundaries and emit a `cycle` construction error at the recursive edge;
 ---   * declared-vs-measured component word counts emit `count_mismatch` construction errors; opaque uncounted macros emit warnings.
 ---
 --- `passes.scan_source` strips its private `_code_macros` / `_code_macro_bodies` tables before this pass runs.
 local M = {}
 -- ─────────────────────────────────────────────────────────────────────────
 -- 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")
 -- ─────────────────────────────────────────────────────────────────────────
 -- Helpers
 -- ─────────────────────────────────────────────────────────────────────────
 -- Convert the recursive walk's body-relative line numbers into physical source lines once.
 -- The walker builds `line_of` from `body_text` and stamps body-relative line numbers (1..N) into `item.line` and `invocation.call_line`.
 -- This function converts those values to physical source lines at the close site with the forwarded source `line_of` closure.
 -- `call_line` discipline:
 --   * 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.
 --
 -- 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.
 local function stamp_root_provenance(projection, atom_record, src, corpus)
 	local root_line_of   = src.scan and src.scan.line_of
 	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"
 		, "emission_model: atom_record.body_off (byte offset of the body's first byte in source) is required to derive `root_body_line`. The scanner must populate body_off for every atom record.")
 	-- `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      = {}
 	for _, item in ipairs(projection.items) do
 		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.
 	local function body_line_for(event, item)
 		local ids = event.invocation_ids or {}
 		-- 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]
 			if inner_inv then
 				local component = component_index[inner_inv.component_name]
 				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
 				end
 			end
 		end
 		-- RAW root-body word: item.line is body-text's 1-based line number (the first content line is line 2 because line 1 is the trailing `\n` after `{`).
 		-- Convert body-text-relative → physical using `root_body_line + (item.line - 1)`.
 		return (root_body_line or 0) + (item.line or 1) - 1
 	end
 	-- 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
 		if inv.call_path == nil or inv.call_path == "" then
 			inv.call_path = root_path
 		end
 	end
 	-- 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
 		if inv.parent_id == 0 then
 			inv.call_line = (root_body_line or 0) + (inv.call_line or 1) - 1
 		end
 	end
 	-- 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]
 			if    it and it.kind == "word" then
 				local fake_event = { invocation_ids = { inv.id } }
 				bls[#bls + 1]    = body_line_for(fake_event, it) or 0
 			end
 		end
 		inv.body_lines = bls
 	end
 	-- 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)
 		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]
 		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
 		end
 		we.call_line = call_line
 		if we.def_path  == nil or we.def_path  == "" then we.def_path  = src.path         or "" end
 		if we.def_line  == nil or we.def_line  == 0  then we.def_line  = atom_record.line or 0  end
 		if we.call_path == nil or we.call_path == "" then we.call_path = src.path         or "" end
 	end
 end
 -- Project one atom record into `atom.paths`.
 -- Mutates the atom record in-place and returns the projection (for pass-level error/warning accumulation).
 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 {}
 	-- 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 = {
 		tokens       = atom_record.body_tokens or {},
 		line_in_body = duffle.build_body_line_index(body),
 		items        = proj.items,
 		word_events  = proj.word_events,
 		markers      = proj.markers,
 		invocations  = proj.invocations,
 		errors       = proj.errors,
 		warnings     = proj.warnings,
 	}
 	stamp_root_provenance(proj, atom_record, src, corpus)
 	atom_record.paths = paths
 	return proj
 end
 -- ─────────────────────────────────────────────────────────────────────────
 -- Run the emission-model pass.
 -- ─────────────────────────────────────────────────────────────────────────
 --- @param ctx PassCtx  -- { shared = { corpus = ... }, out_root, ... }
 --- @return PassResult
 function M.run(ctx)
 	local outputs  = {}
 	local errors   = {}
 	local warnings = {}
 	local corpus = ctx and ctx.shared and ctx.shared.corpus
 	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 | raw_atom | comp_bare | comp_proc.
 	local function process_atom(atom, src)
 		if not (atom and atom.body) then return end
 		local kind = atom.kind
 		if kind ~= "atom" 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.
 			errors[#errors + 1] = {
 				kind   = e.kind,
 				line   = e.line,
 				msg    = e.msg,
 				source = e.source or src.path,
 			}
 		end
 		for _, w in ipairs(proj.warnings) do
 			warnings[#warnings + 1] = {
 				kind = w.kind,
 				line = w.line,
 				msg  = w.msg,
 			}
 		end
 	end
 	-- Walk `corpus.source_order`; within each source, visit atoms followed by raw_atoms.
 	-- Recognized kinds (atom | 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
 			process_atom(atom, src)
 		end
 		for _, atom in ipairs(scan.raw_atoms or {}) do
 			process_atom(atom, src)
 		end
 	end
 	return {
 		outputs  = outputs,
 		errors   = errors,
 		warnings = warnings,
 	}
 end
 return M
@@ -3,12 +3,11 @@
 --- 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
 --- from each `atom_offset(F, T)` marker to its target `atom_label(T)` declaration, and emits
--- `<dir_basename>.offsets.h` with one `#define _atom_offset_F_T = N` per branch.
+--- `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.
 ---
 --- The offset is `target_word - branch_word - 1` (the standard MIPS branch-immediate encoding: branch_offset = relative_pc_in_words - 1).
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
 --- Lua 5.3 compatible.
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
@@ -16,23 +15,16 @@
 -- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
 -- 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 duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 local word_count_eval = require("word_count_eval")
 local count_token_words = word_count_eval.count_token_words
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 -- Marker-call identifiers inside atom bodies.
 local LABEL_MARKER    = "atom_label"
 local OFFSET_MARKER   = "atom_offset"
 -- Offset macro/enum naming prefixes (the emitted header uses these).
 local OFFSET_MACRO_PREFIX = "_atom_offset_"
 local OFFSET_ENUM_PREFIX  = "atom_offset_"
@@ -45,231 +37,141 @@ local OFFSET_MACRO_COL = 44
 -- ════════════════════════════════════════════════════════════════════════════
 --- @class SourceFile
--- @field path     string  -- absolute path to the source file
+--- @field path     string  -- Absolute path to the source file
--- @field text     string  -- the full source text
+--- @field text     string  -- Full source text
--- @field dir      string  -- the directory containing the source
+--- @field dir      string  -- Directory containing the source
--- @field basename string  -- filename without extension
+--- @field basename string  -- Filename without extension
--- @field scan     table   -- pre-scanned SourceScan payload (from duffle.scan_source)
+--- @field scan     table   -- Pre-scanned SourceScan payload (from duffle.scan_source)
 --- @class PassCtx
--- @field sources            SourceFile[]           -- all source files in the build
+--- @field shared             table -- Cross-pass shared state
--- @field metadata_path      string                 -- path to word_count.metadata.h
+--- @field shared.corpus      table -- Corpus projection
--- @field shared             table                  -- cross-pass shared state
+--- @field shared.word_counts table
--- @field shared.word_counts table                  -- macro name -> word count
+--- @field out_root           string -- Output root (e.g. "build/gen")
 --- @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 dry_run            boolean                -- if true, compute but don't write
 --- @field verbose            boolean                -- log diagnostic info
 --- @class PassResult
 --- @field outputs  table[]  -- {kind=, path=} entries describing emit files
--- @field errors   table[]  -- {line=, msg=} entries; build-stops
+--- @field errors   table[]  -- {line=, msg=}  entries; build-stops
--- @field warnings table[]  -- {line=, msg=} entries; build-succeeds
+--- @field warnings table[]  -- {line=, msg=}  entries; build-succeeds
 --- @class BranchOffset
--- @field tag    string   -- the marker tag (e.g. "F" in `atom_offset(F, T)`)
+--- @field tag               string      -- Marker tag (e.g. "F" in `atom_offset(F, T)`)
--- @field target string   -- the target label name (e.g. "T" in `atom_offset(F, T)`)
+--- @field target            string      -- Target label name (e.g. "T" in `atom_offset(F, T)`)
--- @field pos    integer  -- the branch's word position within the atom body
+--- @field branch_word       integer     -- Branch word position within the atom body
--- @field offset integer  -- computed `target_word - branch_word - 1`
+--- @field offset            integer     -- Computed per consuming instruction (see `compute_offsets`)
 --- @field consuming_encoder string|nil  -- Instruction consuming the offset (e.g. "branch_le_zero", "jump", "call_addr")
 --- @field consuming_arg_pos integer|nil -- 1-based arg position within the consuming instruction's arg list
 --- @class AtomData
--- @field name        string         -- atom name
+--- @field name        string         -- Atom name
--- @field total_words integer        -- total word count of the atom body
+--- @field total_words integer        -- Total word count of the atom body
--- @field offsets     BranchOffset[] -- per-branch offset list
+--- @field offsets     BranchOffset[] -- Per-branch offset list
 -- ════════════════════════════════════════════════════════════════════════════
-- Per-token marker-call helpers (atom_label / atom_offset inside bodies)
+-- Canonical marker projection
 -- ════════════════════════════════════════════════════════════════════════════
-- Extract comma-separated identifier args from a parenthesized group after a function-like macro call.
+-- MARKER_PROJECTORS is the marker-kind data table.
-- Returns (args, after_paren) where `after_paren` is the position just past the closing `)`, or nil if `token` did not start with `(`.
+-- The emission-model pass already records marker word positions + consuming-instruction context;
-- @param token string
+-- this pass only projects those records into the label/branch lookup shape needed by offset computation.
-- @param after_ident integer
+local MARKER_PROJECTORS = {
-- @return string[], integer|nil
+	label = function(state, marker)
-local function extract_ident_args(token, after_ident)
+		state.labels[marker.name] = marker.word_index
-	local arg_start = duffle.skip_ws_and_cmt(token, after_ident)
+	end,
-	if token:sub(arg_start, arg_start) ~= "(" then return {}, nil end
+	offset = function(state, marker)
-	local inner, after_paren = duffle.read_parens(token, arg_start)
+		state.branches[#state.branches + 1] = {
-	-- scan: <marker>(<args>)
+			tag                = marker.name,
-
+			target             = marker.target,
-	local args      = {}
+			branch_word        = marker.word_index,
-	local pos       = 1
+			consuming_encoder  = marker.consuming_encoder,
-	local inner_len = #inner
+			consuming_arg_pos  = marker.consuming_arg_pos,
-	while pos <= inner_len do
+		}
-		pos = duffle.skip_ws_and_cmt(inner, pos)
+	end,
 		if pos > inner_len then break end
 		local ident, after = duffle.read_ident(inner, pos)
 		if ident and ident ~= "" then
 			table.insert(args, ident)
 			pos = after
 		else
 			pos = pos + 1
 		end
 		pos = duffle.skip_ws_and_cmt(inner, pos)
 		if pos <= inner_len and inner:sub(pos, pos) == "," then pos = pos + 1 end
 	end
 	return args, after_paren
 end
 -- (internal) Record a `atom_label(name)` marker — `at_pos` is the branch-free word position within the atom body.
 -- @param labels table<string, integer>
 -- @param args string[]
 -- @param at_pos integer
 local function record_label_marker(labels, args, at_pos)
 	if #args >= 1 then labels[args[1]] = at_pos end
 end
 -- (internal) Record a `atom_offset(tag, target)` marker.
 -- @param branches table[]  -- list of {pos=, target=, tag=}
 -- @param args string[]
 -- @param at_pos integer
 local function record_offset_marker(branches, args, at_pos)
 	if #args >= 2 then
 		table.insert(branches, { pos = at_pos, target = args[2], tag = args[1] })
 	end
 end
 -- MARKER_TO_HANDLER — data-driven marker dispatch (the plex pattern).
 -- Maps the marker ident to its recorder function. Each handler takes (out_table, args, at_pos).
 -- Adding a new marker type = 1 row + 1 recorder function.
 local MARKER_TO_HANDLER = {
 	[LABEL_MARKER]  = record_label_marker,
 	[OFFSET_MARKER] = record_offset_marker,
 }
--- Scan a single token for atom_label/atom_offset markers, walking through balanced groups transparently (so nested calls are found).
+--- Project canonical marker records into the two lookup tables used by the offset renderer.
--- @param token string
+--- No source text, body text, or body token is inspected.
--- @param at_pos integer    -- the branch-free word position of this token in the body
+--- @param markers table[] -- atom.paths.markers
--- @param labels table<string, integer>
+--- @return table<string, integer>, table[]
--- @param branches table[]
+local function project_markers(markers)
-local function scan_for_atom_markers(token, at_pos, labels, branches)
+	local state = { labels = {}, branches = {} }
-	local pos     = 1
+	for _, marker in ipairs(markers or {}) do
-	local tok_len = #token
+		local project = MARKER_PROJECTORS[marker.kind]
-	while pos <= tok_len do
+		if    project then project(state, marker) end
 		pos = duffle.skip_ws_and_cmt(token, pos)
 		if pos > tok_len then break end
 		local ch = token:sub(pos, pos)
 		if duffle.is_alpha(ch) then
 			local ident, after = duffle.read_ident(token, pos)
 			local handler = MARKER_TO_HANDLER[ident]
 			if handler then
 				local args, after_paren = extract_ident_args(token, after)
 				-- Marker found — dispatch to its recorder. markers share labels and branches as
 				-- out-tables; the recorder picks which one(s) to write to based on its semantics.
 				-- (record_label_marker writes to labels; record_offset_marker writes to branches.)
 				handler(ident == LABEL_MARKER and labels or branches, args, at_pos)
 				pos = after_paren or after
 			else
 				pos = after
 			end
 		else
 			local nx = duffle.skip_str_or_cmt(token, pos)
 			pos = (nx > pos) and nx or (pos + 1)
 		end
 	end
-end
+	return state.labels, state.branches
 -- (internal) Count words emitted by the rest of `tok` after a marker call
 -- (the marker call itself emits 0 words, but the source pattern may bundle the marker with the next instruction on the same line,
 -- separated by no top-level comma).
 -- Returns the word count contributed by that rest.
 -- @param tok string
 -- @param word_counts table
 -- @return integer
 local function count_marker_rest(tok, word_counts)
 	-- duffle.find_marker_call_end returns the position PAST the closing `)` of the marker call
 	-- (or nil if `tok` isn't a marker call). Canonical impl in duffle.lua is faster than the
 	-- file-local copy that used to live here (byte-indexed, no `tok:sub` per char).
 	local marker_end = duffle.find_marker_call_end(tok)
 	if not marker_end or marker_end >= #tok then return 0 end
 	local rest = duffle.trim(tok:sub(marker_end))
 	if rest == "" then return 0 end
 	return count_token_words(rest, word_counts)
 end
 -- (internal) Is this token a marker call (`atom_label` or `atom_offset`)?
 -- @param tok string
 -- @return boolean
 local function is_marker_token(tok)
 	local leading_ident = duffle.read_ident(tok, 1)
 	return leading_ident == LABEL_MARKER or leading_ident == OFFSET_MARKER
 end
 --- Scan an atom body for labels + branches, count total words.
 --- Returns (labels, branches, total_words).
 --- @param body string
 --- @param word_counts table
 --- @return table<string, integer>, table[], integer
 -- scan_atom_body: walk pre-tokenized body for atom_label/atom_offset markers + word counts.
 -- Uses `atom.body_tokens` from the SourceScan payload (pre-tokenized by scan-source pass).
 -- @param body_tokens table[]  -- {{tok=string, rel=integer}, ...} from duffle.tokenize_body
 -- @param word_counts table
 -- @return table, table, integer  -- labels, branches, total_words
 local function scan_atom_body(body_tokens, word_counts)
 	local pos      = 0
 	local labels   = {}
 	local branches = {}
 	for _, t in ipairs(body_tokens) do
 		local tok = t.tok
 		if is_marker_token(tok) then
 			-- Marker call: record at the current pos, do NOT advance pos.
 			scan_for_atom_markers(tok, pos, labels, branches)
 			pos = pos + count_marker_rest(tok, word_counts)
 		else
 			local words = count_token_words(tok, word_counts)
 			scan_for_atom_markers(tok, pos, labels, branches)
 			pos = pos + words
 		end
 	end
 	return labels, branches, pos
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Offset computation + header generation
 -- ════════════════════════════════════════════════════════════════════════════
-- Compute branch offsets as `target_word - branch_word - 1`
+--- Compute branch offsets per consuming instruction.
-- (the standard MIPS branch-immediate encoding).
+--- Disposition table:
-- @param labels table<string, integer>
+---   `branch_*`           -> relative offset: `target_word - branch_word - 1` (MIPS branch-immediate encoding).
-- @param branches table[]
+---   `jump` / `call_addr` -> same value as `branch_*` (a relative word offset). 
-- @return BranchOffset[]
+---     The duffle headers' `enc_i` macro truncates the value to the immediate-field width (16 bits for branches, 26 bits for jumps).
 ---     For tape-atom bodies within a single module, this works for `j`/`jal` because the linker's symbol resolution produces the correct 26-bit absolute target via standard `j` relocations.
 ---     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.
 --- @param labels   table<string, integer>
 --- @param branches table[]
 --- @return BranchOffset[]
 local function compute_offsets(labels, branches)
 	local results = {}
 	for _, br in ipairs(branches) do
 		local target = labels[br.target]
 		if not target then
-			error("Branch target '" .. br.target .. "' has no atom_label (at word " .. br.pos .. ")")
+			error("Branch target '" .. br.target .. "' has no atom_label (at word " .. br.branch_word .. ")")
 		end
-		results[#results + 1] = { target = br.target, tag = br.tag, offset = target - br.pos - 1 }
+		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.
 		-- 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,
 			consuming_encoder  = br.consuming_encoder,
 			consuming_arg_pos  = br.consuming_arg_pos,
 		}
 	end
 	return results
 end
-- Right-pad `s` with spaces to width `w`. If `s` is already `w` or wider, no padding is added.
+--- Right-pad `s` with spaces to width `w`. If `s` is already `w` or wider, no padding is added.
-- @param s string
+--- @param s string
-- @param w integer
+--- @param w integer
-- @return string
+--- @return string
 local function pad_right(s, w)
 	return s .. string.rep(" ", math.max(0, w - #s))
 end
-- (internal) Build a constant-table entry `{macro_name, enum_name, value}` from a BranchOffset.
+--- (internal) Build a constant-table entry `{macro_name, enum_name, value}` from a BranchOffset.
-- @param r BranchOffset
+--- @param bo BranchOffset
-- @return table
+--- @return table
-local function make_offset_const(r)
+local function make_offset_const(bo)
 	return {
-		macro_name = OFFSET_MACRO_PREFIX .. r.tag .. "_" .. r.target,
+		macro_name = OFFSET_MACRO_PREFIX .. bo.tag .. "_" .. bo.target,
-		enum_name  = OFFSET_ENUM_PREFIX  .. r.tag .. "_" .. r.target,
+		enum_name  = OFFSET_ENUM_PREFIX  .. bo.tag .. "_" .. bo.target,
-		value      = r.offset,
+		value      = bo.offset,
 	}
 end
-- (internal) Emit one atom's offset constants + enum into the lines buffer.
+--- (internal) Emit one atom's offset constants + enum into the lines buffer.
-- @param add fun(s: string)
+--- @param add  fun(s: string)
-- @param atom AtomData
+--- @param atom AtomData
 local function emit_atom_offsets(add, atom)
 	if #atom.offsets == 0 then return end
 	add("// --- atom: " .. atom.name .. " (" .. atom.total_words .. " words) ---")
@@ -290,84 +192,73 @@ local function emit_atom_offsets(add, atom)
 	add("")
 end
-- Generate the per-source .offsets.h header.
+--- Generate the per-directory .offsets.h header.
-- @param source_path string
+--- @param dir          string     -- the absolute source directory
-- @param atoms_data AtomData[]
+--- @param sources      table[]    -- sources contributing to this directory (for the header comment)
-- @return string
+--- @param atoms_data   AtomData[]
-local function generate_header(source_path, atoms_data)
+--- @return string
-	local basename = duffle.basename_no_ext(source_path)
+local function generate_header(dir, sources, atoms_data)
 	local dir_basename = duffle.basename_no_ext(dir)
 	local lines = {}
 	local function add(s) lines[#lines + 1] = s end
 	add("// Auto-generated by ps1_meta.lua (passes/offsets.lua) — DO NOT EDIT")
-	add("// Source: " .. source_path)
+	add("// Directory: " .. dir:gsub("/", "\\") .. "\\")
 	for _, src in ipairs(sources) do
 		add("//   source: " .. src.path:gsub("/", "\\"))
 	end
 	add("#pragma once")
 	add("")
-	add("#pragma region " .. basename)
+	add("#pragma region " .. dir_basename)
 	add("")
 	add("")
 	for _, atom in ipairs(atoms_data) do
 		emit_atom_offsets(add, atom)
 	end
-	add("#pragma endregion " .. basename)
+	add("#pragma endregion " .. dir_basename)
 	add("")
 	return table.concat(lines, "\n") .. "\n"
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- M — module exports
 -- ════════════════════════════════════════════════════════════════════════════
 local M = {}
-- Project the pre-scanned SourceScan entries into the {name, body, body_tokens} shape this pass needs.
+--- (internal) Aggregate atoms from every source in one directory, render the per-directory `offsets.h`.
-- MipsAtom_ entries have kind="atom"; MipsCode code_<name> entries have kind="raw_atom".
+--- Returns the offsets_h path if a header was written, or nil.
-- `body_tokens` is set by scan-source on every `scan.atoms[i]` / `scan.raw_atoms[i]`; we carry it forward
+--- @param ctx     PassCtx
-- so `scan_atom_body` reads from the precomputed table directly (no per-atom tokenize_body fallback).
+--- @param dir     string       -- the absolute source directory
-- @param scan table  -- SourceScan from duffle.scan_source
+--- @param sources SourceFile[] -- sources in this directory
-- @return table[]  -- list of {name=, body=, body_tokens=}
+--- @return string|nil  -- the offsets_h path
-local function project_atoms(scan)
+local function process_directory(ctx, dir, sources)
 	local out = {}
 	for _, a in ipairs(scan.atoms) do
 		out[#out + 1] = { name = a.raw_name, body = a.body, body_tokens = a.body_tokens }
 	end
 	for _, a in ipairs(scan.raw_atoms) do
 		out[#out + 1] = { name = a.name, body = a.body, body_tokens = a.body_tokens }
 	end
 	return out
 end
 -- (internal) Process one source: project atoms from scan, scan bodies, write header.
 -- Returns the offsets_h path if a header was written, or nil.
 -- @param ctx PassCtx
 -- @param src SourceFile
 -- @return string|nil  -- the offsets_h path
 local function process_source(ctx, src)
 	local atoms = project_atoms(src.scan)
 	if #atoms == 0 then return nil end
 	local atoms_data = {}
-	for _, atom in ipairs(atoms) do
+
-		local labels, branches, total = scan_atom_body(atom.body_tokens, ctx.shared.word_counts)
+	local function append_atom(atom)
 		local  paths = atom and atom.paths
 		if not paths then return end
 		local labels, branches = project_markers(paths.markers)
 		atoms_data[#atoms_data + 1] = {
-			name        = atom.name,
+			name        = atom.raw_name or atom.name,
-			total_words = total,
+			total_words = #(paths.word_events or {}),
 			offsets     = compute_offsets(labels, branches),
 		}
 	end
-	local out_path = src.dir .. "/gen/" .. duffle.basename_no_ext(src.dir) .. ".offsets.h"
+	for _, src in ipairs(sources) do
-	if not ctx.dry_run then
+		local scan = src.scan or {}
-		duffle.ensure_dir(duffle.dirname(out_path))
+		for _, atom in ipairs(scan.atoms or {}) do append_atom(atom) end
-		duffle.write_file(out_path, generate_header(src.path, atoms_data))
+		for _, atom in ipairs(scan.raw_atoms or {}) do append_atom(atom) end
 	end
 	if #atoms_data == 0 then return nil end
 	local out_path = dir .. "/gen/offsets.h"
 	duffle.ensure_dir(duffle.dirname(out_path))
 	duffle.write_file(out_path, generate_header(dir, sources, atoms_data))
 	return out_path
 end
 --- Run the offsets pass.
--- For each source, emits a per-module `<dir_basename>.offsets.h` containing `#define _atom_offset_F_T = N` constants 
+--- For each canonical source-directory, emits a per-directory `gen/offsets.h`
--- for every `atom_offset(F, T)` reference in the source's atoms.
+--- containing constants for every marker recorded in atom.paths across every source in that directory.
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
@@ -375,8 +266,18 @@ function M.run(ctx)
 	local errors   = {}
 	local warnings = {}
-	for _, src in ipairs(ctx.sources) do
+	local corpus = ctx.shared and ctx.shared.corpus
-		local out_path = process_source(ctx, src)
+	if type(corpus) ~= "table" then
 		error("offsets.run requires ctx.shared.corpus", 0)
 	end
 	if type(corpus.source_order) ~= "table" then
 		error("offsets.run requires ctx.shared.corpus.source_order.", 0)
 	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)
 		if out_path then
 			outputs[#outputs + 1] = { offsets_h = out_path }
 		end
@@ -1,30 +1,34 @@
--- passes/report.lua — Per-MODULE annotation report renderer +
+--- passes/report.lua — Per-MODULE annotation report renderer + project-wide summary writer.
 --- project-wide summary writer.
 ---
 --- Two output files per build:
 ---   - `build/gen/<dir_basename>.annotations.txt` — one per source-directory containing atoms; aggregates across all sources in the directory.
 ---   - `build/gen/annotation_validation.txt` — the project summary.
 ---
--- The annotation pass stashes per-MODULE summary entries in `ctx.flags._annot_results` (set by `passes/annotation.lua`). 
+--- The annotation pass emits `errors.h` files per module and the canonical `corpus.sources_by_dir` projection groups sources by directory.
--- This pass re-validates each source via `annotation.validate()` to get the detailed per-source results needed for the report. 
+--- This pass iterates the dir projection directly and re-validates each source via `annotation.validate()` to get the detailed per-source results.
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
 --- Lua 5.3 compatible.
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 -- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
-- Note: this boilerplate is duplicated in 6 other entry scripts; a Phase-6 extraction target (`duffle.setup_package_path()`).
+-- Bootstrap: See `ps1_meta.lua` for the rationale.
-- Bootstrap: see `ps1_meta.lua` for the rationale.
+-- Bootstrap: Load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
-- 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.
-- Uses `debug.getinfo` to find this file's own directory, so it works
+-- Bootstrap: Load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
 -- 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 duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 -- Load the annotation pass so we can re-validate each source against the canonical corpus projection.
 -- The annotation pass exposes `M.validate`, which returns the per-source AnnotationResult (atoms / annots / macros / binds / errors / warnings)
 -- that the report pass renders into the per-module `<dir_basename>.annotations.txt` output.
 local annotation = dofile(_bootstrap_dir .. "annotation.lua")
 -- Load atoms_source_map for the `render_source_map` / `render_provenance` module functions (used by `render_module_atoms_md` to produce `<module>.atoms.md` without re-walking source tokens).
 -- The pass itself emits no per-source files anymore; we only consume the two pure renderers here.
 -- Defined BEFORE the renderer functions below so their upvalues resolve to this local (not the global `atoms_source_map`, which is nil).
 local atoms_source_map = dofile(_bootstrap_dir .. "atoms_source_map.lua")
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
@@ -32,7 +36,7 @@ local duffle        = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 -- Section separators used in the rendered text reports.
 -- The thin rules are hand-tuned to align with the per-section content width; do not change without also checking the section renderers below.
-local RULE_THICK = "========================================================"
+local RULE_THICK               = "========================================================"
 local SECTION_HEADER_ATOMS     = "── Atoms ────────────────────────────────────────────────"
 local SECTION_HEADER_ANNOTS    = "── Annotations ──────────────────────────────────────────"
 local SECTION_HEADER_BINDS     = "── Binds_* structs ──────────────────────────────────────"
@@ -40,8 +44,7 @@ local SECTION_HEADER_MACROS    = "── Macro word-count declarations ───
 local SECTION_HEADER_ERRORS    = "── Errors ──────────────────────────────────────────────"
 local SECTION_HEADER_WARNINGS  = "── Warnings ────────────────────────────────────────────"
-- Lua pattern that captures the basename (last path segment) of a
+-- Lua pattern that captures the basename (last path segment) of a forward- or back-slash separated path.
 -- forward- or back-slash separated path.
 local BASENAME_PATTERN = "([^/\\]+)$"
 -- Debug flag name — set to truthy in `_G` to enable verbose logging.
@@ -55,422 +58,542 @@ local PASS_NAME = "report"
 -- ════════════════════════════════════════════════════════════════════════════
 --- @class SourceFile
--- @field path     string  -- absolute path to the source file
+--- @field path     string  -- Absolute path to the source file
--- @field text     string  -- the full source text
+--- @field text     string  -- Full source text
--- @field dir      string  -- the directory containing the source
+--- @field dir      string  -- Directory containing the source
--- @field basename string  -- filename without extension
+--- @field basename string  -- Filename without extension
 --- @class PassCtx
--- @field sources            SourceFile[]            -- all source files in the build
+--- @field sources            SourceFile[]         -- All source files in the build
--- @field metadata_path      string                  -- path to word_count.metadata.h
+--- @field metadata_path      string               -- Path to word_count.metadata.h
--- @field shared             table                   -- cross-pass shared state
+--- @field shared             table                -- Cross-pass shared state
--- @field out_root           string                  -- output root (e.g. "build/gen")
+--- @field out_root           string               -- Output root (e.g. "build/gen")
--- @field project_root       string                  -- project root (e.g. "code/")
+--- @field project_root       string               -- Project root (e.g. "code/")
--- @field upstream           table<string, table>    -- per-pass upstream outputs
+--- @field upstream           table<string, table> -- Per-pass upstream outputs
--- @field flags              table                   -- CLI flags + per-pass stash
+--- @field flags              table                -- CLI flags + per-pass stash
--- @field flags._annot_results ModuleEntry[]         -- stashed by annotation pass
+--- @field verbose            boolean              -- If true, log diagnostic info
 --- @field dry_run            boolean                 -- if true, compute but don't write
 --- @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 errors   table[]  -- {line=, msg=}  entries; build-stops
--- @field warnings table[]  -- {line=, msg=} entries; build-succeeds
+--- @field warnings table[]  -- {line=, msg=}  entries; build-succeeds
 -- Shapes produced by `passes/annotation.lua`'s `M.validate()`.
 --- @class AtomEntry
--- @field name string   -- atom name (e.g. "cube_g4_face")
+--- @field name string   -- Atom name (e.g. "cube_g4_face")
--- @field line integer  -- source line of the atom declaration
+--- @field line integer  -- Source line of the atom declaration
 --- @class AnnotEntry
--- @field line    integer  -- source line
+--- @field line    integer     -- Source line
--- @field macro   string   -- the macro name (e.g. "atom_reads")
+--- @field macro   string      -- Macro name (e.g. "atom_reads")
--- @field name    string   -- the atom name (if a `name(...)` was given)
+--- @field name    string      -- Atom name (if a `name(...)` was given)
--- @field kind    string   -- "atom_info" | "atom_bind" | ...
+--- @field kind    string      -- "atom_info" | "atom_bind" | ...
 --- @field binds   string|nil  -- Binds_X name if any
 --- @field reads   string[]    -- R_* names (read targets)
 --- @field writes  string[]    -- R_* names (write targets)
--- @field error   string|nil  -- error message if annotation was malformed
+--- @field error   string|nil  -- Error message if annotation was malformed
 --- @class BindsField
--- @field name   string   -- field name
+--- @field name   string   -- Field name
--- @field offset integer  -- byte offset within the Binds_X struct
+--- @field offset integer  -- Byte offset within the Binds_X struct
 --- @class BindsStruct
--- @field name   string         -- struct name (e.g. "Binds_Floor")
+--- @field name   string         -- Struct name (e.g. "Binds_Floor")
--- @field line   integer        -- source line of the typedef
+--- @field line   integer        -- Source line of the typedef
--- @field bytes  integer        -- total byte size
+--- @field bytes  integer        -- Total byte size
--- @field fields BindsField[]   -- the field list
+--- @field fields BindsField[]   -- The field list
 --- @class MacroEntry
--- @field name  string   -- macro name (e.g. "WORD_COUNT(my_macro, 4)")
+--- @field name  string   -- Macro name (e.g. "WORD_COUNT(my_macro, 4)")
--- @field line  integer  -- source line
+--- @field line  integer  -- Source line
--- @field words integer  -- declared word count
+--- @field words integer  -- Declared word count
 --- @class Finding
--- @field line integer  -- source line
+--- @field line integer  -- Source line
--- @field msg  string   -- finding message
+--- @field msg  string   -- Finding message
 --- @class AnnotationResult
--- @field source   string         -- set by this pass; original source path
+--- @field source   string         -- Set by this pass; original source path
--- @field atoms    AtomEntry[]    -- atom declarations in this source
+--- @field atoms    AtomEntry[]    -- Atom declarations in this source
--- @field annots   AnnotEntry[]   -- annotation entries
+--- @field annots   AnnotEntry[]   -- Annotation entries
--- @field macros   MacroEntry[]   -- macro word-count declarations
+--- @field macros   MacroEntry[]   -- Macro word-count declarations
 --- @field binds    BindsStruct[]  -- Binds_* struct declarations
--- @field errors   Finding[]      -- errors from validation
+--- @field errors   Finding[]      -- Errors from validation
--- @field warnings Finding[]      -- warnings from validation
+--- @field warnings Finding[]      -- Warnings from validation
--- @field info     table          -- info summary (not rendered here)
+--- @field info     table          -- Info summary (not rendered here)
 --- @class ModuleEntry
--- @field dir          string   -- absolute directory path
+--- @field dir          string   -- Absolute directory path
--- @field dir_basename string   -- basename (e.g. "duffle", "gte_hello")
+--- @field dir_basename string   -- Basename (e.g. "duffle", "gte_hello")
--- @field atoms_count  integer  -- pre-counted atoms for filtering
+--- @field atoms_count  integer  -- Pre-counted atoms for filtering
 --- @class ModuleReport
--- @field dir       string             -- module directory
+--- @field dir       string             -- Module directory
--- @field sources   SourceFile[]       -- sources in this module
+--- @field sources   SourceFile[]       -- Sources in this module
--- @field results   AnnotationResult[] -- per-source validate() results
+--- @field results   AnnotationResult[] -- Per-source validate() results
 --- @class ProjectReport
--- @field results AnnotationResult[]  -- all per-source results
+--- @field results AnnotationResult[]  -- All per-source results
 -- ════════════════════════════════════════════════════════════════════════════
 -- Per-MODULE annotation report (aggregated across all sources in a dir)
 -- ════════════════════════════════════════════════════════════════════════════
-- Extract the basename (last path segment) of a forward- or back-slash separated path. Returns the input unchanged if no separator is found.
+--- Extract the basename (last path segment) of a forward- or back-slash separated path. Returns the input unchanged if no separator is found.
-- @param path string
+--- @param path string
-- @return string
+--- @return string
 local function source_basename(path)
 	return path:match(BASENAME_PATTERN) or path
 end
-- (internal) Format a single annotation entry as one rendered line.
+-- ════════════════════════════════════════════════════════════════════════════
-- @param a AnnotEntry
+-- Markdown renderers (consolidated-report-files refactor, 2026-07-26)
-- @param src_name string
+-- ════════════════════════════════════════════════════════════════════════════
-- @return string
+
-local function format_annot_line(a, src_name)
+--- Render the thin project-wide summary (`build/atom_meta_report.summary.md`).
-	if a.error then
+--- @param all_results { 
-		return string.format("  ✗ line %d  %s  [ERROR: %s]  [%s]", a.line, a.macro or "?", a.error, src_name)
+--- 	module:string,
 --- 	atoms:integer, 
 --- 	annots:integer, 
 --- 	binds:integer,
 ---		macros:integer,   
 ---		findings:integer,
 ---		errors:integer,
 --- 	warnings:integer,
 --- 	info:integer }[]
 --- @return string
 local function render_project_summary(all_results)
 	local lines = {
 		"# Project summary",
 		"> Auto-generated by ps1_meta.lua (passes/report.lua).",
 		"",
 		"| module | atoms | annots | binds | macros | findings | errors | warnings | info |",
 		"|--------|-------|--------|-------|--------|----------|--------|----------|------|",
 	}
 	local totals = { atoms = 0, annots = 0, binds = 0, macros = 0, findings = 0, errors = 0, warnings = 0, info = 0 }
 	for _, e in ipairs(all_results) do
 		lines[#lines + 1] = string.format("| %s | %d | %d | %d | %d | %d | %d | %d | %d |"
 			, e.module, e.atoms, e.annots, e.binds, e.macros, e.findings, e.errors, e.warnings, e.info)
 		totals.atoms    = totals.atoms    + e.atoms
 		totals.annots   = totals.annots   + e.annots
 		totals.binds    = totals.binds    + e.binds
 		totals.macros   = totals.macros   + e.macros
 		totals.findings = totals.findings + e.findings
 		totals.errors   = totals.errors   + e.errors
 		totals.warnings = totals.warnings + e.warnings
 		totals.info     = totals.info     + e.info
 	end
-	local line = string.format("  ●  line %d  %s  [%s]", a.line, a.name, src_name)
+	lines[#lines + 1] = string.format("| **TOTAL** | %d | %d | %d | %d | %d | %d | %d | %d |"
-	if a.binds               then line = line .. "  binds=" .. a.binds end
+		, totals.atoms, totals.annots, totals.binds, totals.macros, totals.findings, totals.errors, totals.warnings, totals.info)
-	if #a.reads > 0          then line = line .. "  reads={" .. table.concat(a.reads, ",") .. "}" end
+	return table.concat(lines, "\n") .. "\n"
 	if #a.writes > 0         then line = line .. "  writes={" .. table.concat(a.writes, ",") .. "}" end
 	return line
 end
-- (internal) Tally totals across all results in a module.
+--- Render the per-module verbose source-map markdown (`build/<module>.atoms.md`).
-- @param results AnnotationResult[]
+--- Per-source sub-section, per-atom stanza with sourcemap + provenance rows.
-- @return integer, integer, integer, integer, integer, integer
+--- Pulls sourcemap + provenance from `atoms_source_map` (no second source walk).
-local function tally_module_totals(results)
+--- @param dir         string
-	local total_atoms, total_annots, total_binds, total_macros = 0, 0, 0, 0
+--- @param dir_sources SourceFile[]
-	local total_errors, total_warnings = 0, 0
+--- @param wc          table<string, integer>
-	for _, r in ipairs(results) do
+--- @return string
-		total_atoms    = total_atoms    + #r.atoms
+local function render_module_atoms_md(dir, dir_sources, wc)
-		total_annots   = total_annots   + #r.annots
+	local dir_basename = source_basename(dir)
-		total_binds    = total_binds    + #r.binds
+	local lines        = {
-		total_macros   = total_macros   + #r.macros
+		"# " .. dir_basename .. " — atoms (verbose source map)",
-		total_errors   = total_errors   + #r.errors
+		"> Per-word call-site + provenance. Auto-generated.",
-		total_warnings = total_warnings + #r.warnings
+		"",
 	}
 	for _, src in ipairs(dir_sources) do
 		local src_name = source_basename(src.path)
 		lines[#lines + 1] = "## " .. src_name
 		lines[#lines + 1] = ""
 		-- For each atom with a projection, render its sourcemap + provenance.
 		local atoms_list = {}
 		for _, atom in ipairs((src.scan or {}).atoms or {}) do
 			if atom.paths then atoms_list[#atoms_list + 1] = atom end
 		end
 		for _, atom in ipairs((src.scan or {}).raw_atoms or {}) do
 			if atom.paths then atoms_list[#atoms_list + 1] = atom end
 		end
 		if #atoms_list == 0 then
 			lines[#lines + 1] = "_(no atom projections)_"
 			lines[#lines + 1] = ""
 		else
 			-- Per-source forward-slash path (same one `emit_atom_stanza` / `emit_provenance_stanza` would derive;
 			-- computed once per `## <source>` heading and reused by each atom's `WORD N CALL ...` field).
 			local rel_path = src.path:gsub("\\\\", "/")
 			for _, atom in ipairs(atoms_list) do
 				lines[#lines + 1] = string.format(
 					"### atom: %s (line %d, %d words)",
 					atom.name, atom.line or 0, #(atom.paths.items or {}))
 				lines[#lines + 1] = ""
 				lines[#lines + 1] = "**Sourcemap** — per-word call site:"
 				lines[#lines + 1] = "```"
 				-- Per-atom invariant: call the per-atom renderers, NOT the per-source ones.
 				-- The per-source renderers enumerate every atom in `src`;
 				-- calling them in a per-atom loop would repeat the whole source under every `### atom:` heading.
 				lines[#lines + 1] = atoms_source_map.render_atom_source_map(atom):gsub("\n+$", "")
 				lines[#lines + 1] = "```"
 				lines[#lines + 1] = ""
 				lines[#lines + 1] = "**Provenance** — per-word definition + body:"
 				lines[#lines + 1] = "```"
 				lines[#lines + 1] = atoms_source_map.render_atom_provenance(atom, wc, rel_path):gsub("\n+$", "")
 				lines[#lines + 1] = "```"
 				lines[#lines + 1] = ""
 			end
 		end
 	end
-	return total_atoms, total_annots, total_binds, total_macros, total_errors, total_warnings
+	return table.concat(lines, "\n") .. "\n"
 end
-- (internal) Section renderer: per-source atom declarations.
+--- Render the consolidated per-module markdown (`build/<module>.atom_meta_report.md`).
-local function render_module_atoms_section(add, results)
+--- Aggregates annotation + static-analysis content across all sources in `dir`.
-	add(SECTION_HEADER_ATOMS)
+--- Annotations come from re-running `annotation.validate()` per source (the existing pattern);
-	for _, r in ipairs(results) do
+--- static-analysis comes from `corpus.static_analysis_results[dir_basename]` (populated by `static_analysis.lua` — no second corpus_pipe_ctx build).
 --- @param dir           string
 --- @param dir_sources   SourceFile[]
 --- @param annot_results AnnotationResult[]
 --- @param sa_results    table -- corpus.static_analysis_results[dir_basename]
 --- @return string
 local function render_module_meta_report(dir, dir_sources, annot_results, sa_results)
 	local dir_basename = source_basename(dir)
 	local lines        = {
 		"# " .. dir_basename .. " — atom meta report",
 		"> Auto-generated by ps1_meta.lua (passes/report.lua). Do not edit.",
 		"",
 	}
 	local function add(s) lines[#lines + 1] = s end
 	-- Module summary table.
 	local n_atoms        = 0
 	local n_annot        = 0
 	local n_binds        = 0
 	local n_macros       = 0
 	local n_bare, n_proc = 0, 0
 	for _, r in ipairs(annot_results) do
 		n_atoms  = n_atoms  + #r.atoms
 		n_annot  = n_annot  + #r.annots
 		n_binds  = n_binds  + #r.binds
 		n_macros = n_macros + #r.macros
 	end
 	for _, a in ipairs(sa_results.atoms or {}) do
 		if     a.kind == "comp_bare" then n_bare = n_bare + 1
 		elseif a.kind == "comp_proc" then n_proc = n_proc + 1
 		end
 	end
 	add("## Module summary"); add("")
 	add("| metric | value |"); add("|--------|-------|")
 	add(string.format("| sources | %d |", #dir_sources))
 	add(string.format("| atoms | %d (atoms: %d, comp_bare: %d, comp_proc: %d) |",
 		#(sa_results.atoms or {}),
 		#(sa_results.atoms or {}) - n_bare - n_proc, n_bare, n_proc))
 	add(string.format("| annotations | %d |", n_annot))
 	add(string.format("| binds structs | %d |", n_binds))
 	add(string.format("| macro decls | %d |", n_macros))
 	add(string.format("| findings | %d (errors: %d, warnings: %d, info: %d) |",
 		#(sa_results.findings or {}),
 		#(sa_results.errors   or {}),
 		#(sa_results.warnings or {}),
 		#(sa_results.info     or {})))
 	add("")
 	-- Sources
 	add("## Sources"); add("")
 	for _, s in ipairs(dir_sources) do add("- `" .. s.path .. "`") end
 	add("")
 	-- Atoms (annotation)
 	add("## Atoms"); add("")
 	add("| kind | name | source | line |"); add("|------|------|--------|------|")
 	for _, r in ipairs(annot_results) do
 		local src_name = source_basename(r.source)
 		for _, a in ipairs(r.atoms) do
-			add(string.format("  MipsAtom_(%s)   line %d   [%s]", a.name, a.line, src_name))
+			add(string.format("| atom | %s | %s | %d |", a.name, src_name, a.line))
 		end
 	end
 	add("")
 end
-- (internal) Section renderer: per-source annotation entries.
+	-- Annotations
-local function render_module_annots_section(add, results)
+	add("## Annotations"); add("")
-	add(SECTION_HEADER_ANNOTS)
+	if #annot_results == 0 then
-	for _, r in ipairs(results) do
+		add("_(none)_")
 		local src_name = source_basename(r.source)
 		for _, a in ipairs(r.annots) do
 			add(format_annot_line(a, src_name))
 		end
 	end
 	add("")
 end
 -- (internal) Section renderer: per-source Binds_* struct declarations.
 local function render_module_binds_section(add, results)
 	add(SECTION_HEADER_BINDS)
 	for _, r in ipairs(results) do
 		local src_name = source_basename(r.source)
 		for _, b in ipairs(r.binds) do
 			add(string.format("  %s   line %d   %d bytes   [%s]", b.name, b.line, b.bytes, src_name))
 			for _, f in ipairs(b.fields) do
 				add(string.format("    +%2d: %s", f.offset, f.name))
 			end
 		end
 	end
 	add("")
 end
 -- (internal) Section renderer: per-source macro word-count declarations.
 local function render_module_macros_section(add, results)
 	add(SECTION_HEADER_MACROS)
 	for _, r in ipairs(results) do
 		local src_name = source_basename(r.source)
 		for _, m in ipairs(r.macros) do
 			add(string.format("  %s  line %d  words=%d  [%s]", m.name, m.line, m.words, src_name))
 		end
 	end
 	add("")
 end
 -- (internal) Section renderer: per-source errors (one-line + "(none)" if empty).
 local function render_module_errors_section(add, results, total_errors)
 	add(SECTION_HEADER_ERRORS)
 	if total_errors == 0 then
 		add("  (none)")
 	else
-		for _, r in ipairs(results) do
+		add("| source | line | name | binds | reads | writes |")
 		add("|--------|------|------|-------|-------|--------|")
 		for _, r in ipairs(annot_results) do
 			local src_name = source_basename(r.source)
-			for _, e in ipairs(r.errors) do
+			for _, a in ipairs(r.annots) do
-				add(string.format("  ✗ line %d  %s  [%s]", e.line, e.msg, src_name))
+				local binds  = a.binds  or "—"
 				local reads  = (#a.reads  > 0 and table.concat(a.reads,  ",")) or "—"
 				local writes = (#a.writes > 0 and table.concat(a.writes, ",")) or "—"
 				add(string.format("| %s | %d | %s | %s | %s | %s |"
 					, src_name, a.line, a.name, binds, reads, writes))
 			end
 		end
 	end
 	add("")
 end
-- (internal) Section renderer: per-source warnings (one-line + "(none)" if empty).
+	-- Binds_* structs
-local function render_module_warnings_section(add, results, total_warnings)
+	add("## Binds_* structs"); add("")
-	add(SECTION_HEADER_WARNINGS)
+	if #annot_results == 0 then
-	if total_warnings == 0 then
+		add("_(none)_")
 		add("  (none)")
 	else
-		for _, r in ipairs(results) do
+		for _, r in ipairs(annot_results) do
 			local src_name = source_basename(r.source)
-			for _, w in ipairs(r.warnings) do
+			for _, b in ipairs(r.binds) do
-				add(string.format("  ⚠ line %d  %s  [%s]", w.line, w.msg, src_name))
+				add(string.format("### %s (%s:%d, %d bytes)",
 					b.name, src_name, b.line, b.bytes))
 				for _, f in ipairs(b.fields) do
 					add(string.format("- `+%d %s`", f.offset, f.name))
 				end
 				add("")
 			end
 		end
 	end
 	-- Macro decls
 	add("## Macro word-count declarations"); add("")
 	if #annot_results == 0 then
 		add("_(none)_")
 	else
 		add("| source | line | macro declaration |")
 		add("|--------|------|-------------------|")
 		for _, r in ipairs(annot_results) do
 			local src_name = source_basename(r.source)
 			for _, m in ipairs(r.macros) do
 				add(string.format("| %s | %d | %s |",
 					src_name, m.line, m.name))
 			end
 		end
 	end
 	add("")
 	-- Findings by atom (static-analysis)
 	add("## Static analysis — findings by atom"); add("")
 	local by_atom = {}
 	for _, f in ipairs(sa_results.findings or {}) do
 		by_atom[f.atom] = by_atom[f.atom] or {}
 		by_atom[f.atom][#by_atom[f.atom] + 1] = f
 	end
 	if next(by_atom) == nil then
 		add("_(no findings)_")
 	else
 		for _, a in ipairs(sa_results.atoms or {}) do
 			local fs = by_atom[a.name]
 			if fs then
 				add(string.format("### %s", a.name))
 				for _, f in ipairs(fs) do
 					add(string.format("- `[%s] %s`", f.check, f.msg))
 				end
 				add("")
 			end
 		end
 	end
 	-- Errors / Warnings / Info
 	local function add_findings(label, entries)
 		add(string.format("## %s", label))
 		if #entries == 0 then
 			add("_(none)_")
 		else
 			for _, e in ipairs(entries) do
 				add(string.format("- line %d  %s", e.line, e.msg))
 			end
 		end
 		add("")
 	end
 	add_findings("Errors",   sa_results.errors   or {})
 	add_findings("Warnings", sa_results.warnings or {})
 	add_findings("Info",     sa_results.info     or {})
 	-- Per-atom cycle counts (path-aware)
 	add("## Per-atom cycle counts (path-aware, best case, no stalls)"); add("")
 	add("| atom | source | min | max | branches | paths | notes |")
 	add("|------|--------|-----|-----|----------|-------|-------|")
 	local sorted = {}
 	for _, a in ipairs(sa_results.atoms or {}) do sorted[#sorted + 1] = a end
 	table.sort(sorted, function(x, y)
 		return ((x.paths or {}).cycles_max or 0) > ((y.paths or {}).cycles_max or 0)
 	end)
 	for _, a in ipairs(sorted) do
 		local p        = a.paths or {}
 		local src_name = a.source_path and source_basename(a.source_path) or ""
 		local notes    = ""
 		if p.has_loops then notes = notes .. " [loop!]" end
 		if p.unknown_macros and #p.unknown_macros > 0 then
 			notes = notes .. " [unknown: " .. table.concat(p.unknown_macros, ", ") .. "]"
 		end
 		add(string.format("| %s | %s | %d | %d | %d | %d | %s |",
 			a.name, src_name,
 			p.cycles_min or 0, p.cycles_max or 0,
 			p.branches   or 0, p.paths      or 0, notes))
 	end
 	add("")
 	-- Per-source scan summary
 	add("## Per-source scan summary"); add("")
 	for _, src in ipairs(dir_sources) do
 		local src_atoms = {}
 		for _, a in ipairs(sa_results.atoms or {}) do
 			if a.source_path == src.path then src_atoms[#src_atoms + 1] = a end
 		end
 		if #src_atoms > 0 then
 			local mn, mx = math.huge, -1
 			for _, a in ipairs(src_atoms) do
 				local p = a.paths or {}
 				if (p.cycles_min or 0) < mn then mn = p.cycles_min or 0 end
 				if (p.cycles_max or 0) > mx then mx = p.cycles_max or 0 end
 			end
 			local path_str
 			if mx > 0 then
 				path_str = string.format("  cycles=%d..%d", mn, mx)
 			else
 				path_str = string.format("  %d cycles", mn)
 			end
 			add(string.format("- `%s` — %d atom%s%s",
 				src.basename, #src_atoms,
 				#src_atoms == 1 and "" or "s", path_str))
 		end
 	end
 	add("")
 	return table.concat(lines, "\n") .. "\n"
 end
 -- ════════════════════════════════════════════════════════════════════════════
-- SECTION_RENDERERS — data-driven section dispatch (the plex pattern)
+-- REPORT_RENDERERS — data-driven report dispatch (one row per file kind)
 -- ════════════════════════════════════════════════════════════════════════════
--
+-- `once = true` means render once at the project level (not per-module).
-- Each entry maps a section to its (header, render_fn). The render_fn signature:
+-- `basename(dir_basename)` yields the file's basename for that kind.
--   render_fn(add, results, totals)
+-- `gather(ctx, dir, dir_sources [, all_modules])` returns the rendered string.
--     add    -- the `add(line)` closure from the surrounding report renderer
+local REPORT_RENDERERS = {
--     results -- AnnotationResult[] (per-source results)
+	{
--     totals -- {atoms, annots, binds, macros, errors, warnings} counts
+		name     = "atom_meta_report",
--
+		ext      = "md",
-- Sections that need to render "(none)" vs iterate use totals.errors / totals.warnings;
+		basename = function(dir_basename) return dir_basename .. ".atom_meta_report" end,
-- other sections ignore the totals arg.
+		once     = false,
-- Adding a new section = 1 row here + 1 render_<thing>_section function.
+		gather   = function(ctx, dir, dir_sources)
-local SECTION_RENDERERS = {
+			-- Annotations: re-run `annotation.validate()` per source (the existing pattern).
-	{ header = SECTION_HEADER_ATOMS,    render = render_module_atoms_section     },
+			local annot_results = {}
-	{ header = SECTION_HEADER_ANNOTS,   render = render_module_annots_section    },
+			for _, src in ipairs(dir_sources) do
-	{ header = SECTION_HEADER_BINDS,    render = render_module_binds_section     },
+				if src.scan then
-	{ header = SECTION_HEADER_MACROS,   render = render_module_macros_section    },
+					local r = annotation.validate(ctx, src, nil)
-	{ header = SECTION_HEADER_ERRORS,   render = function(add, results, totals) return render_module_errors_section(add, results, totals.errors)   end },
+					r.source = src.path
-	{ header = SECTION_HEADER_WARNINGS, render = function(add, results, totals) return render_module_warnings_section(add, results, totals.warnings) end },
+					annot_results[#annot_results + 1] = r
 				end
 			end
 			-- Static-analysis: read stashed projection (no re-validate).
 			local dir_basename = dir:match("([^/\\]+)$") or dir
 			local sa_results   = (ctx.shared.corpus.static_analysis_results or {})[dir_basename] or {}
 			return render_module_meta_report(dir, dir_sources, annot_results, sa_results)
 		end,
 	},
 	{
 		name     = "atoms",
 		ext      = "md",
 		basename = function(dir_basename) return dir_basename .. ".atoms" end,
 		once     = false,
 		gather   = function(ctx, dir, dir_sources)
 			return render_module_atoms_md(dir, dir_sources,
 				ctx.shared.corpus.word_counts or {})
 		end,
 	},
 	{
 		name     = "summary",
 		ext      = "md",
 		basename = function(_dir_basename) return "atom_meta_report.summary" end,
 		once     = true,
 		gather   = function(_ctx, _dir, _dir_sources, all_modules)
 			return render_project_summary(all_modules)
 		end,
 	},
 }
 --- Render the per-MODULE annotation report (one `<dir_basename>.annotations.txt`).
 --- @param dir string                  -- module directory path
 --- @param sources SourceFile[]        -- sources in this module
 --- @param results AnnotationResult[]  -- per-source validate() results
 --- @return string                     -- the rendered report text
 local function render_module_report(dir, sources, results)
 	local lines = {}
 	local function add(s) lines[#lines + 1] = s end
 	add(RULE_THICK)
 	add("ANNOTATION PASS — module " .. source_basename(dir))
 	add(RULE_THICK)
 	add(string.format("Sources: %d", #sources))
 	for _, s in ipairs(sources) do add("  " .. s.path) end
 	add("")
 	local total_atoms, total_annots, total_binds, total_macros, total_errors, total_warnings = tally_module_totals(results)
 	add(string.format("Atoms: %d   Annotations: %d   Binds structs: %d   Macro decls: %d",
 		total_atoms, total_annots, total_binds, total_macros))
 	add("")
 	-- Bundle the totals so the section renderers don't need separate parameter lists.
 	-- Errors/warnings sections need their total count to decide "(none)" vs iterate.
 	-- Sections without totals (atoms/annots/binds/macros) ignore this arg.
 	local totals = {
 		atoms    = total_atoms,  annots = total_annots,  binds  = total_binds,
 		macros   = total_macros, errors = total_errors,  warnings = total_warnings,
 	}
 	-- THE per-section dispatch. ONE loop over SECTION_RENDERERS. Each renderer writes its
 	-- header + content via the `add` closure (pre-bound above).
 	-- Adding a new section = 1 row here + 1 render_<thing>_section function.
 	for _, section in ipairs(SECTION_RENDERERS) do
 		add(section.header)
 		section.render(add, results, totals)
 		add("")
 	end
 	return table.concat(lines, "\n") .. "\n"
 end
 -- ════════════════════════════════════════════════════════════════════════════
-- Per-project summary
+-- M — public pass surface
 -- ════════════════════════════════════════════════════════════════════════════
 --- Render the per-project summary (`build/gen/annotation_validation.txt`).
 --- Aggregates totals across all sources; lists per-source error counts if any source has errors.
 --- @param all_results AnnotationResult[]
 --- @return string
 local function render_project_report(all_results)
 	local lines = {}
 	local function add(s) lines[#lines + 1] = s end
 	local total_atoms, total_annots, total_macros, total_binds = 0, 0, 0, 0
 	local total_errors, total_warnings = 0, 0
 	for _, r in ipairs(all_results) do
 		total_atoms    = total_atoms    + #r.atoms
 		total_annots   = total_annots   + #r.annots
 		total_macros   = total_macros   + #r.macros
 		total_binds    = total_binds    + #r.binds
 		total_errors   = total_errors   + #r.errors
 		total_warnings = total_warnings + #r.warnings
 	end
 	add(RULE_THICK)
 	add("ANNOTATION VALIDATION — project summary")
 	add(RULE_THICK)
 	add("")
 	add(string.format("Atoms:        %d", total_atoms))
 	add(string.format("Annotations:  %d", total_annots))
 	add(string.format("Macros:       %d", total_macros))
 	add(string.format("Binds:        %d", total_binds))
 	add("")
 	add(string.format("Errors:       %d", total_errors))
 	add(string.format("Warnings:     %d", total_warnings))
 	add("")
 	if total_errors > 0 then
 		add("Per-source error counts:")
 		for _, r in ipairs(all_results) do
 			if #r.errors > 0 then
 				local src_name = source_basename(r.source)
 				add(string.format("  %s : %d error(s)", src_name, #r.errors))
 			end
 		end
 		add("")
 	end
 	return table.concat(lines, "\n") .. "\n"
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- Orchestration helpers
 -- ════════════════════════════════════════════════════════════════════════════
 -- (internal) Pull per-source validate() results from the annotation pass's stash.
 -- The annotation pass runs first in the dep chain and caches results in `ctx.flags._annot_source_results`;
 -- we read from there instead of re-validating each source.
 -- Returns the list of module results + the flat list of all results (for the project-wide summary).
 -- @param ctx PassCtx
 -- @param dir_sources SourceFile[]
 -- @return AnnotationResult[], AnnotationResult[]
 local function lookup_module_results(ctx, dir_sources)
 	local src_cache      = (ctx.flags and ctx.flags._annot_source_results) or {}
 	local module_results = {}
 	local all_results    = {}
 	for _, src in ipairs(dir_sources) do
 		local result = src_cache[src.path]
 		if result then
 			result.source = src.path                                    -- defensive (annotation tags it too; this guards against cache misses from earlier iterations)
 			module_results[#module_results + 1] = result
 			all_results[#all_results + 1] = result
 		end
 	end
 	return module_results, all_results
 end
 -- (internal) Does this module's results contain anything worth emitting?
 -- @param module_results AnnotationResult[]
 -- @return boolean
 local function module_has_content(module_results)
 	for _, r in ipairs(module_results) do
 		if #r.atoms  > 0 or #r.annots > 0 or #r.binds    > 0
 		or #r.macros > 0 or #r.errors > 0 or #r.warnings > 0 then
 			return true
 		end
 	end
 	return false
 end
 -- (internal) Log a debug message if `_G[DEBUG_FLAG]` is truthy.
 -- @param fmt string
 local function debug_log(fmt, ...)
 	if _G[DEBUG_FLAG] then
 		io.stderr:write(string.format("[%s] " .. fmt, PASS_NAME, ...))
 	end
 end
 -- ════════════════════════════════════════════════════════════════════════════
 -- M — module exports
 -- ════════════════════════════════════════════════════════════════════════════
 local M = {}
--- Run the report pass. 
+--- Run the report pass. Emits 1 `atom_meta_report.summary.md` per build + 2 `atom_meta_report.md` + 2 `atoms.md` files per module (duffle + gte_hello).
--- Renders one `<dir_basename>.annotations.txt` per source-directory that has content, plus the project-wide `annotation_validation.txt` summary.
+--- Reads `corpus.static_analysis_results` (added in Phase 1) to populate per-module findings without re-running validate().
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
-	local outputs  = {}
+	local outputs = {}
-	local errors   = {}
+	local corpus  = ctx.shared and ctx.shared.corpus
-	local warnings = {}
+	local by_dir  = (corpus and corpus.sources_by_dir) or {}
-	local module_entries = (ctx.flags and ctx.flags._annot_results) or {}
+	-- `out_path_root`: when the conventional `out_root` is `build/gen` (any spelling — relative, absolute, separator variants).
-	local by_dir         = ctx.by_dir or duffle.group_sources_by_dir(ctx.sources)
+	-- Write the md files to `build/` (parent of `gen/`) instead of nested under `gen/`.
 	-- Mirrors the `gdb_tape_atoms_runtime.gdb` relocation.
 	local function ends_with_gen(p)
 		return type(p) == "string" and (p:match("[/\\]gen[/\\]?$") ~= nil
 			or p == "build/gen" or p == "build\\gen")
 	end
 	local out_root_effective = ends_with_gen(ctx.out_root)
 		and ctx.out_root:gsub("[/\\]gen[/\\]?$", "")
 		or ctx.out_root
-	if not ctx.dry_run then duffle.ensure_dir(ctx.out_root) end
+	duffle.ensure_dir(out_root_effective)
-	local all_results_for_summary = {}
+	-- Aggregator for the project-wide `once = true` summary renderer.
-	for _, entry in ipairs(module_entries) do
+	local all_modules = {}
 		debug_log("entry: dir=%s basename=%s atoms_count=%d dir_sources=%d\n", entry.dir, entry.dir_basename, entry.atoms_count, #(by_dir[entry.dir] or {}))
-		if entry.atoms_count > 0 or #(by_dir[entry.dir] or {}) > 0 then
+	for dir, dir_sources in pairs(by_dir) do
-			local dir_sources                 = by_dir[entry.dir] or {}
+		local dir_basename = dir:match("([^/\\]+)$") or dir
-			local module_results, all_results = lookup_module_results(ctx, dir_sources)
+
-			for _, r in ipairs(all_results) do
+		-- Per-renderer dispatch for the per-module renderers (once = false).
-				all_results_for_summary[#all_results_for_summary + 1] = r
+		for _, renderer in ipairs(REPORT_RENDERERS) do
 			if not renderer.once then
 				local body     = renderer.gather(ctx, dir, dir_sources)
 				local out_path = out_root_effective .. "/" .. renderer.basename(dir_basename) .. "." .. renderer.ext
 				duffle.write_file(out_path, body)
 				outputs[#outputs + 1] = { kind = renderer.name, path = out_path }
 			end
 		end
-			if module_has_content(module_results) then
+		-- For the summary, compute per-module totals once (re-validating annotations per source — same pattern as the meta_report renderer).
-				local out_path = ctx.out_root .. "/" .. entry.dir_basename .. ".annotations.txt"
+		local annot_results = {}
-				if not ctx.dry_run then
+		for _, src in ipairs(dir_sources) do
-					duffle.write_file(out_path, render_module_report(entry.dir, dir_sources, module_results))
+			if src.scan then
-				end
+				local r = annotation.validate(ctx, src, nil)
-				outputs[#outputs + 1] = { annotations_txt = out_path }
+				r.source = src.path
-			else
+				annot_results[#annot_results + 1] = r
 				debug_log("  -> no content; skipping\n")
 			end
 		end
 		local n_annot, n_binds, n_macros = 0, 0, 0
 		for _, r in ipairs(annot_results) do
 			n_annot  = n_annot  + #r.annots
 			n_binds  = n_binds  + #r.binds
 			n_macros = n_macros + #r.macros
 		end
 		local sa_results = (corpus.static_analysis_results or {})[dir_basename] or {}
 		all_modules[#all_modules + 1] = {
 			module   = dir_basename,
 			atoms    = #(sa_results.atoms or {}),
 			annots   = n_annot,
 			binds    = n_binds,
 			macros   = n_macros,
 			findings = #(sa_results.findings or {}),
 			errors   = #(sa_results.errors   or {}),
 			warnings = #(sa_results.warnings or {}),
 			info     = #(sa_results.info     or {}),
 		}
 	end
 	-- Project-wide renderer (once = true): write the summary file.
 	for _, renderer in ipairs(REPORT_RENDERERS) do
 		if renderer.once then
 			local body     = renderer.gather(ctx, nil, nil, all_modules)
 			local out_path = out_root_effective .. "/" .. renderer.basename("") .. "." .. renderer.ext
 			duffle.write_file(out_path, body)
 			outputs[#outputs + 1] = { kind = renderer.name, path = out_path }
 		end
 	end
-	if not ctx.dry_run and #all_results_for_summary > 0 then
+	return { outputs = outputs, errors = {}, warnings = {} }
 		local summary_path = ctx.out_root .. "/annotation_validation.txt"
 		duffle.write_file(summary_path, render_project_report(all_results_for_summary))
 		outputs[#outputs + 1] = { summary_txt = summary_path }
 	end
 	return { outputs = outputs, errors = errors, warnings = warnings }
 end
 return M
@@ -1,11 +1,17 @@
 --- word_count_eval.lua — Word-counting logic for the tape-atom metaprogram pipeline.
 ---
--- Three responsibilities:
+--- Two responsibilities:
---   1. **Public utilities** (used by `passes/components.lua`, `passes/offsets.lua`, `passes/annotation.lua`):
+---   1. **Public utility** `M.count_token_words(token, wc)`: Used by `passes/offsets.lua`, `passes/annotation.lua`, and other passes.
---        - `M.count_token_words(token, wc)` — words emitted by one token
+---   2. **Pass entry** `M.run(ctx)`: Loads the authored `word_count.metadata.h` into `ctx.shared.corpus.word_counts` for downstream passes.
---        - `M.scan_dir(dir, suffix)` — glob walk for *.macs.h
+---      The generated `.macs.h` files are OUTPUT artifacts and are NOT inputs to this pass;
---   2. **Pass entry** `M.run(ctx)` — loads metadata.h + *.macs.h into `ctx.shared.word_counts` for downstream passes.
+---      Current component counts are owned by `passes/components.lua` (which populates `corpus.word_counts` and `corpus.component_body_index`
---   3. **Internal helpers** for the body scanner.
+---      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).
 ---   * No `.macs.h` recursive discovery (no `scan_dir`, no scan cache, no `_invalidate_scan_cache`).
 ---
 --- **Conventions**: tabs (1/level), EmmyLua annotations, no regex,
 --- Lua 5.3 compatible.
@@ -14,27 +20,11 @@
 -- Module-scope requires + package.path setup
 -- ════════════════════════════════════════════════════════════════════════════
 -- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
 -- Note: this boilerplate is duplicated in 6 other entry scripts; a Phase-6 extraction target (`duffle.setup_package_path()`).
 -- Bootstrap: see `ps1_meta.lua` for the rationale.
 -- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
 -- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
 -- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
 -- 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 duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 -- ════════════════════════════════════════════════════════════════════════════
 -- Constants
 -- ════════════════════════════════════════════════════════════════════════════
 -- Windows separator char — used by `fname:match` to recognize `.macs.h` files.
 local PATH_SEP_BACKSLASH = "\\"
 -- Required native extension: lfs (LuaFileSystem). Built by `update_deps.ps1` to
 -- `toolchain/lfs/lfs.dll` and wired into package.cpath by `scripts/duffle_paths.lua`.
 -- If lfs is missing, `require` throws — fail loud per the build-tool convention.
 local lfs = require("lfs")
 -- ════════════════════════════════════════════════════════════════════════════
 -- Type declarations
@@ -53,12 +43,12 @@ local lfs = require("lfs")
 --- @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.word_counts WordCounts    -- populated by this pass
+--- @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 dry_run            boolean       -- if true, compute but don't write
 --- @field verbose            boolean       -- if true, log diagnostic info
 --- @class PassResult
@@ -80,9 +70,8 @@ local M = {}
 --- For most tokens (regular MIPS instructions) this returns 1.
 --- For `mac_X(...)` calls, this returns the resolved word count from `wc` (recursively if needed). For `nop2` etc., returns wc[name].
 --- For unknown macros, returns 1 and (optionally) warns.
---
+--- @param token string     -- a single token from split_top_level_commas
--- @param token string        -- a single token from split_top_level_commas
+--- @param wc    WordCounts -- the shared word-count table
 --- @param wc WordCounts       -- the shared word-count table
 --- @return integer
 function M.count_token_words(token, wc)
 	local s = duffle.trim(token)
@@ -97,93 +86,42 @@ function M.count_token_words(token, wc)
 	return 1
 end
 -- ┌────────────────────────────────────────────────────────────────────┐
 -- │ Shared utility: scan_dir                                           │
 -- └────────────────────────────────────────────────────────────────────┘
 --- Recursively scan a directory for files matching a glob suffix.
 ---
 --- The `.macs.h` files produced by the components pass always live at `<project_root>/<module>/gen/`.
 --- Native walk via lfs.attributes + lfs.dir: ~2ms vs ~56ms for the prior `dir /b /s` subprocess.
 ---
 --- @param dir string        -- directory to scan (absolute or relative)
 --- @param suffix string     -- file pattern, e.g. "*.macs.h"
 --- @return string[]
 -- Cache the scan_dir result per (dir, suffix) in package.loaded.
 -- The cache persists for the lifetime of the Lua process (cleared when ps1_meta.lua exits).
 -- If a build removes/creates .macs.h files mid-process, the caller can invalidate by calling `M._invalidate_scan_cache()`.
 local SCAN_CACHE_KEY = "__word_count_eval_scan_cache__"
 --- Scan `code/` for files matching `suffix` (e.g. `*.macs.h`).
 --- Native directory enumeration via lfs (~2ms). Zero subprocess spawns.
 ---
 --- @param dir string        -- project root directory
 --- @param suffix string     -- file pattern, e.g. "*.macs.h"
 --- @return string[]
 function M.scan_dir(dir, suffix)
 	local key = dir .. "\0" .. suffix
 	local cache = package.loaded[SCAN_CACHE_KEY]
 	if    cache and cache[key] then return cache[key] end
 	local results = {}
 	local code_dir = dir .. "/code"
 	if lfs.attributes(code_dir, "mode") == "directory" then
 		for mod_name in lfs.dir(code_dir) do
 			if mod_name ~= "." and mod_name ~= ".." then
 				local gen_path = code_dir .. "/" .. mod_name .. "/gen"
 				if lfs.attributes(gen_path, "mode") == "directory" then
 					for fname in lfs.dir(gen_path) do
 						if fname:match("%.macs%.h$") then
 							results[#results + 1] = gen_path .. "/" .. fname
 						end
 					end
 				end
 			end
 		end
 	end
 	-- Cache the result (including empty results).
 	cache      = cache or {}
 	cache[key] = results
 	package.loaded[SCAN_CACHE_KEY] = cache
 	return results
 end
 --- Invalidate the scan cache (call after creating new .macs.h files in the same Lua process — usually not needed).
 function M._invalidate_scan_cache() package.loaded[SCAN_CACHE_KEY] = nil end
 -- ┌────────────────────────────────────────────────────────────────────┐
 -- │ Pass entry: M.run(ctx) — "word-counts" pass                        │
 -- └────────────────────────────────────────────────────────────────────┘
--- Load metadata.h + scan for existing *.macs.h files into ctx.shared.word_counts.
+--- Load the authored `word_count.metadata.h` into `ctx.shared.corpus.word_counts`.
--- Loading the .macs.h files is idempotent: entries from later (current-build) .macs.h files override metadata.h entries of the same name.
+--- Generated `.macs.h` files are OUTPUT artifacts and are NOT scanned as inputs.
 --- Current component counts are computed and inserted by `passes/components.lua`
 --- after the components pass iterates `corpus.source_order` and writes each source-directory's `gen/macs.h` file.
 ---
 --- Contract:
 ---   * `ctx.shared.corpus` MUST exist (canonical corpus ownership).
 ---   * `ctx.metadata_path` MUST be a readable file path to the authored `word_count.metadata.h`.
 ---   * The pass assigns exactly one table to `corpus.word_counts`.
 ---     Consumers read the corpus-owned table directly.
 ---     Consumers must read `corpus.word_counts` directly.
 --- @param ctx PassCtx
 --- @return PassResult
 function M.run(ctx)
-	local wc = {}
+	-- 1. Canonical-corpus ownership gate.
-
+	local corpus = ctx.shared and ctx.shared.corpus
-	-- 1. Load metadata.h (the encoding-macro source of truth).
+	if type(corpus) ~= "table" then
-	local meta_counts = duffle.load_word_counts(ctx.metadata_path)
+		error("word_count_eval.run requires ctx.shared.corpus (canonical corpus). The fixture must install the corpus before running this pass.", 0)
 	for name, count in pairs(meta_counts) do wc[name] = count end
 	-- 2. Scan project_root recursively for *.macs.h files (component-macro source).
 	local macs_files = M.scan_dir(ctx.project_root, "*.macs.h")
 	for _, macs_path in ipairs(macs_files) do
 		local ok, mc = pcall(duffle.load_word_counts, macs_path)
 		if not ok then
 			io.stderr:write(string.format("[word_count_eval] parse error in '%s': %s\n", macs_path, tostring(mc)))
 		elseif type(mc) ~= "table" then
 			io.stderr:write(string.format("[word_count_eval] '%s' did not return a table (got %s)\n", macs_path, type(mc)))
 		else
 			for name, count in pairs(mc) do wc[name] = count end
 		end
 	end
-	ctx.shared.word_counts = wc
+	-- 2. metadata_path gate.
 	if type(ctx.metadata_path) ~= "string" or ctx.metadata_path == "" then
 		error("word_count_eval.run requires ctx.metadata_path (path to the authored word_count.metadata.h).", 0)
 	end
 	-- 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)
 	-- 4. Assign the count table. ONE assignment, no copy. The assignment creates no secondary alias.
 	corpus.word_counts = wc
 	return { outputs = {}, errors = {}, warnings = {} }
 end
@@ -1,17 +1,15 @@
 -- autoexec.lua - pcsx_debug_helper plugin entry point.
-- Packaged in scripts/pcsx_debug_helper.zip. Loaded by pcsx-redux via
+-- Packaged in scripts/pcsx_debug_helper.zip. Loaded by pcsx-redux via the -archive CLI flag (see scripts/launch_pcsx_debug.ps1).
 -- the -archive CLI flag (see scripts/launch_pcsx_debug.ps1).
 --
 -- Registers two web handlers for external CLI tools:
 --   /api/v1/lua/gte - full GTE state (32 data + 32 control regs + PC)
 --   /api/v1/lua/gp  - GP state summary (screenshot endpoint + VRAM endpoint refs)
 --
-- The GTE handler reads COP2 regs via PCSX.getRegisters().CP2D/CP2C. The
+-- The GTE handler reads COP2 regs via PCSX.getRegisters().CP2D/CP2C.
-- pcsx-redux gdb stub doesn't expose COP2, so this is the only way for
+-- The pcsx-redux gdb stub doesn't expose COP2, so this is the only way for external tools to see GTE state.
 -- external tools to see GTE state.
 --
-- The GP handler is a thin pointer: pcsx-redux's Lua API exposes only PCSX.GPU.takeScreenShot()
+-- The GP handler is a thin pointer: 
-- (no GPUSTAT, no GP0/GP1 command log, no display state). For richer GP state, the existing web endpoints are the practical path:
+-- pcsx-redux's Lua API exposes only PCSX.GPU.takeScreenShot() (no GPUSTAT, no GP0/GP1 command log, no display state). For richer GP state, the existing web endpoints are the practical path:
 --   /api/v1/state/still      - PNG screenshot
 --   /api/v1/gpu/vram/raw     - VRAM raw bytes (1MB)
 --
@@ -48,8 +46,6 @@ local function register_handlers()
 end
 local ok, err = pcall(register_handlers)
-if ok then
+if ok then print("[pcsx_debug_helper] handlers registered: gte, gp")
-    print("[pcsx_debug_helper] handlers registered: gte, gp")
+else       print("[pcsx_debug_helper] registration failed: " .. tostring(err))
 else
    print("[pcsx_debug_helper] registration failed: " .. tostring(err))
 end
@@ -39,13 +39,7 @@ pop-location
 # ════════════════════════════════════════════════════════════════════════════
 # PCSX-Redux — built via MSBuild (VS2022)
 #
 # Requires: Visual Studio 2022 with the C++ desktop workload.
 # The .vcxproj files target platform toolset v145, but VS2022 ships v143;
 # we pass /p:PlatformToolset=v143 to retarget at build time (no file edits).
 # NuGet packages (glfw, luajit.native, libFFmpeg-lite, x64sentry) are
 # restored automatically by MSBuild on first build.
 #
 # Output: toolchain\pcsx-redux\vsprojects\x64\Debug\pcsx-redux.exe
 # ════════════════════════════════════════════════════════════════════════════
@@ -62,11 +56,10 @@ if (-not $msbuild_exe) {
 }
 $path_pcsx_sln = join-path $path_pcsx_redux 'vsprojects\pcsx-redux.sln'
-&	$msbuild_exe $path_pcsx_sln /p:Configuration=Release /p:Platform=x64 /p:PlatformToolset=v143 /m /v:minimal
+& $msbuild_exe $path_pcsx_sln /p:Configuration=Release /p:Platform=x64 /p:PlatformToolset=v143 /m /v:minimal
 # Locate luajit via scoop. `luajit.exe` is on PATH via scoop's shim;
-# we use `scoop prefix` to find the install root for the include dir
+# we use `scoop prefix` to find the install root for the include dir (needed to compile lpeg against luajit's headers).
 # (needed to compile lpeg against luajit's headers).
 # If scoop or luajit is missing, fail fast with an actionable message.
 $luajit_prefix = & scoop prefix luajit 2>$null
 if (-not $luajit_prefix -or -not (Test-Path (Join-Path $luajit_prefix 'bin/luajit.exe'))) {
@@ -77,8 +70,8 @@ if (-not $luajit_prefix -or -not (Test-Path (Join-Path $luajit_prefix 'bin/luaji
 # Discover the luajit include dir by globbing `include/luajit-*`.
 # This avoids hardcoding a specific version (e.g. `luajit-2.1`).
 $luajit_include_root = Join-Path $luajit_prefix 'include'
-$lua_inc_dir = Get-ChildItem -Path $luajit_include_root -Directory -Filter 'luajit-*' -ErrorAction SilentlyContinue |
+$lua_inc_dir         = Get-ChildItem -Path $luajit_include_root -Directory -Filter 'luajit-*' -ErrorAction SilentlyContinue |
-	Select-Object -First 1 -ExpandProperty FullName
+Select-Object -First 1 -ExpandProperty FullName
 if (-not $lua_inc_dir) {
 	write-error "No 'luajit-*' include dir found under '$luajit_include_root'. The scoop luajit install may be broken."
 	exit 1
@@ -87,7 +80,6 @@ if (-not $lua_inc_dir) {
 # Generate lpeg.dll by compiling the 6 source files directly.
 # `gcc` is on PATH (scoop's shim puts it there).
 # The source files: lpcap.c lpcode.c lpcset.c lpprint.c lptree.c lpvm.c
 # (per the lpeg makefile — no `make.lua` template generator in this version).
 # Link against luajit's import library (`libluajit-5.1.a`) for the Lua C API symbols (lua_*, luaL_*).
 $luajit_lib_dir = Join-Path $luajit_prefix 'lib'
 $lpeg_sources = @('lpcap.c', 'lpcode.c', 'lpcset.c', 'lpprint.c', 'lptree.c', 'lpvm.c')
@@ -98,31 +90,24 @@ $lpeg_compile_args = @(
 	'-o', 'lpeg.dll'
 ) + $lpeg_sources + @('-lluajit-5.1')
 push-location $path_lpeg
-&	gcc @lpeg_compile_args
+& gcc @lpeg_compile_args
 pop-location
 # ════════════════════════════════════════════════════════════════════════════
 # lfs (LuaFileSystem) — compiled from pcsx-redux's vendored luafilesystem source.
 # Used by word_count_eval.lua :: scan_dir for native directory enumeration (~2ms)
 # instead of spawning `dir /b /s` as a subprocess (~56ms).
 # Source: toolchain/pcsx-redux/third_party/luafilesystem/src/lfs.c
 # Output: toolchain/lfs/lfs.dll
 # ════════════════════════════════════════════════════════════════════════════
 $path_lfs = join-path $path_toolchain 'lfs'
 verify-path $path_lfs
-$lfs_src = join-path $path_pcsx_redux 'third_party\luafilesystem\src\lfs.c'
+$lfs_src        = join-path $path_pcsx_redux 'third_party\luafilesystem\src\lfs.c'
-$lfs_dll = join-path $path_lfs 'lfs.dll'
+$lfs_dll        = join-path $path_lfs 'lfs.dll'
 $lfs_dll_import = join-path $luajit_lib_dir 'libluajit-5.1.dll.a'
 & gcc -O2 -shared "-I$lua_inc_dir" -o $lfs_dll $lfs_src $lfs_dll_import
 # ════════════════════════════════════════════════════════════════════════════
 # OpenBIOS — built from the PCSX-Redux source tree via make + mipsel-none-elf
 #
 # OpenBIOS is an open-source PS1 BIOS implementation (no retail BIOS dump needed). 
 # It builds with the MIPS cross-toolchain (`mipsel-none-elf-gcc`, on PATH via the `mips` toolchain installer) 
 # + `make` (on PATH via scoop).
 #
 # Output: toolchain\pcsx-redux\src\mips\openbios\openbios.bin
 # ════════════════════════════════════════════════════════════════════════════
Author	SHA1	Message	Date
ed	01f7ceba7c	buzzing brain.	2026-08-05 02:48:05 -04:00
ed	6f2eff920d	some more review before bed.	2026-08-05 02:00:41 -04:00
ed	f25765a7b7	Preparing for camera transformation chapter.	2026-08-05 01:21:25 -04:00
ed	2757aa4330	Fix bug with pad input processing (needed mac_yield load fallthrough case)	2026-08-05 01:08:01 -04:00
ed	748b58c5c5	Codebase overhaul. Metaprogram proofread (part 2). Starting to get serious. Need to rewrite the ps1 lua metaprogram sometime soonish. Getting too bloated... need to consolidate code paths. In this push codebase structure is starting to get a bit more realized. Decided todo now to match Pikuma's linking module files vods beginning to reorganize its codebase as well. Atoms & atom components are not in their on *.atom.c files. (Not calling it tape.c as I don't really bake tapes like that outside of the unity c file so far...) The lua metaprogram has had additional features added to it yet again to avoid hardcoding module handling and supporting multiple atom files per-module. Either after the camera or cd-rom section I'll be most likely pausing to fully refactor the metaprogram. Possibly as a full re-write to get the loc minimal.	2026-08-04 23:34:00 -04:00
ed	6441dbc23e	Proof-reading lua metaprogram (part 1)	2026-08-04 19:32:43 -04:00
ed	57fdb9e037	improvmenets to delay slot modeling (lua metaprogram)	2026-08-04 18:27:00 -04:00
ed	b5953a723b	add ac_yield_load and ac_yield_tail for delay slot optimization opportunities.	2026-08-04 17:25:02 -04:00
ed	888ffce859	Finished: Pikuma Linking multiple files (not applying to codebase only watched)	2026-08-04 16:49:02 -04:00
ed	7289e7c89c	Added jump_rel (can't use abs jump with asm dsl). Fixes + improvements to ps1 asm meta passes.	2026-08-04 16:01:01 -04:00
ed	54a5bb9a31	starting to optimize	2026-08-04 12:59:51 -04:00
ed	e0f4ac873d	spamming load delay slots for now as a fix...	2026-08-04 09:07:53 -04:00
ed	f17fa9165e	wip: input was working... messed it up (bios snapshot reads)	2026-08-04 00:50:12 -04:00
ed	8282f8e902	overkill sio cruft, not keeping.	2026-08-03 10:12:06 -04:00
ed	9eb696ece8	drafting	2026-08-02 21:58:57 -04:00
ed	858e57f293	preparing to overhaul input handling	2026-08-02 17:49:24 -04:00
ed	afcd9b86f0	Gaining clarity on tape abi.. screen_init atoms done. Time to finish rest of joypad course vods...	2026-08-02 15:19:52 -04:00
ed	43cd4e0344	WIP: working towards minimizing C-ABI & PsyQ CRT usage	2026-08-01 23:11:10 -04:00
ed	09dde54030	Finished(Controller Input): Reading Joypad State	2026-07-31 15:15:51 -04:00
ed	315e1b2c5e	Fix(lua atom tape dsl): Bad-hardcode for source file line-table mapping in dwarf injection pass.	2026-07-31 14:28:50 -04:00
ed	02658d3609	Prepare for hello joypad!	2026-07-28 00:35:02 -04:00
ed	dbc459b7e0	gte_hello -> hello_gte. gte is done, moving on to controller!	2026-07-28 00:17:23 -04:00
ed	a704341fc6	Testing out the metaprogram with some optimization, need to remove some hardcoding later..	2026-07-27 23:35:03 -04:00
ed	7421b32fd7	redundant nop reduction	2026-07-27 22:49:41 -04:00
ed	e2eb74be19	Remove gte component result contracts (was a bad bodge in, for a later directive thats TODO)	2026-07-27 22:49:26 -04:00
ed	338f1fe46e	Better reports from dsl metaprogram	2026-07-27 10:06:23 -04:00
ed	27a9038e0d	req c11,	2026-07-26 17:36:46 -04:00
ed	8c8d2e54aa	remove cruft	2026-07-26 14:40:57 -04:00
ed	80a35aa23a	WIP: Better step debug on atom components, better db_skip annotation, lots of curation passes on lua. Still don't have this thing in its final state for the curse but its close.	2026-07-26 13:55:47 -04:00
ed	f247d56c32	Debug vis ergonomics	2026-07-25 13:19:35 -04:00
ed	590ff1e2ec	Curation pass: reduce nested conditional branching in some defnitions.	2026-07-25 13:00:36 -04:00
ed	653e18ee28	remove code related to dry run and dep graph rendering (ps1 meta)	2026-07-25 11:59:41 -04:00
ed	ebb876fe89	report.lua: Remove redudnant section formatting/header	2026-07-25 11:25:12 -04:00
ed	1b40b16c0e	Review pass.	2026-07-25 11:20:53 -04:00
ed	9ffd6592bc	Better static analysis for C0 <-> C2 data race hazards.	2026-07-25 04:09:48 -04:00
ed	d56adab38f	branch delay slot better support. Still reviewing. Need to see if gte is handled properly.	2026-07-23 18:35:02 -04:00
ed	08af73d0d2	Lua Metaprogram: Improvements to static analysis + others.	2026-07-23 10:18:30 -04:00
ed	67d54debfa	offset corections (dwarf)	2026-07-22 18:00:09 -04:00
ed	3c25306070	fixes	2026-07-22 09:47:01 -04:00
ed	c3cf05950e	good enough for now	2026-07-21 22:29:22 -04:00
ed	f6b4d9895e	Adjustments to offset convention (don't want 1s based addresssing to mess with the spec defined encoding)	2026-07-21 20:52:13 -04:00
ed	e70361b548	curation: first pass	2026-07-21 19:20:30 -04:00
ed	ed3eb45b1d	Fixes atom component gdb stepping. New phase/ctx annotations for atoms. Attempt at type views on registers (gdb pretty print failures). Needs heavy curation and problably simplicication.	2026-07-18 10:29:04 -04:00
ed	d7770b6e1d	review pass on c code.	2026-07-15 08:56:37 -04:00
ed	137549b1c8	First pass review	2026-07-14 22:55:16 -04:00
ed	7d5b13aadb	TODO: need to review snapshot	2026-07-14 12:16:00 -04:00