some more review. not working still.

scripts/duffle.lua

@@ -217,7 +217,7 @@ local function parse_path_root(input)
 		if not server_end or server_end == server_start then
 			error("UNC path requires //server/share: " .. input, 3)
 		end
-		local server = input:sub(server_start, server_end - 1)
+		local server      = input:sub(server_start, server_end - 1)
 		local share_start = server_end + 1
 		while input:sub(share_start, share_start) == "/" do
 			share_start = share_start + 1
@@ -515,8 +515,7 @@ local function splice_c_lines(source)
 		local splice_len = nil
 		if byte == BYTE_BACKSLASH and source:byte(pos + 1) == BYTE_NEWLINE then
 			splice_len = 2
-		elseif byte == BYTE_BACKSLASH and source:byte(pos + 1) == BYTE_CR
-			and source:byte(pos + 2) == BYTE_NEWLINE then
+		elseif byte == BYTE_BACKSLASH and source:byte(pos + 1) == BYTE_CR and source:byte(pos + 2) == BYTE_NEWLINE then
 			splice_len = 3
 		end
 
@@ -2095,7 +2094,8 @@ local E_MAC_PREFIX_LEN = 4
 ---   * Unknown `mac_X` (not in `component_index`): fall back to `word_counts[ident]` if present; otherwise emit one opaque event so the cycle budget accounts for the word.
 ---   * Marker Tokens (`atom_label(...)` / `atom_offset(...)`): Zero events (they are pure metaprogram hints).
 ---
---- Cycle protection: a per-expansion `visiting` set tracks components currently on the expansion stack; a re-entry produces a deterministic `{kind = "cycle", ...}` error and aborts that branch (does NOT hang, does NOT recurse).
+--- Cycle protection: a per-expansion `visiting` set tracks components currently on the expansion stack;
+--- a re-entry produces a deterministic `{kind = "cycle", ...}` error and aborts that branch (does NOT hang, does NOT recurse).
 ---
 --- Pure: reads `body_entry` / `component_index` / `word_counts`. Memoization is the caller's responsibility.
 --- Callers wanting `word_events` / `word_event_errors` precomputed for many atoms should memoize them per atom.

scripts/duffle_paths.lua

@@ -47,15 +47,14 @@ local function find_repo_root()
 	return root
 end
 
---- Set `package.path` (for `require("duffle")` + `require("passes.X")`) and
---- `package.cpath` (for `lpeg.dll`).
+--- Set `package.path` (for `require("duffle")` + `require("passes.X")`) and `package.cpath` (for `lpeg.dll`).
 ---
 --- This script does NOT touch the OS environment: no `os.setenv`, no `os.putenv`, no `$PATH` mods. 
 --- It just sets `package.path` and `package.cpath` (the standard Lua way to register module search dirs). 
 --- lpeg is built by `update_deps.ps1` to `toolchain/lpeg/`, 
 --- which we wire into `package.cpath` here (so `require("lpeg")` from `duffle.lua` resolves without any global state).
 function M.setup()
-	local repo_root = find_repo_root()
+	local  repo_root = find_repo_root()
 	if not repo_root then
 		-- Unreachable in practice: find_repo_root() derives the repo root from this script's
 		-- own source path via debug.getinfo(1, "S").source (no subprocess, no git CLI, <1ms).

scripts/passes/auto_reg.lua

@@ -144,10 +144,10 @@ local function build_user_pins(corpus)
 end
 
 -- Find every physical GPR referenced in the atom body, via EITHER:
---   (a) a hardcoded physical GPR ident (R_T\d+|R_V\d+|R_A\d+|R_S\d+) — the existing regex;
---   (b) an alias ident (R_<Alias>) resolved via alias_to_gpr back to its physical GPR ident.
--- Returns { [physical_gpr_ident] = count }. The clash-detection and source-pool-exclusion logic
--- only needs the presence of each GPR (boolean test), but keeping the count preserves the
+--   (a) A hardcoded physical GPR ident (R_T\d+|R_V\d+|R_A\d+|R_S\d+) — the existing regex;
+--   (b) An alias ident (R_<Alias>) resolved via alias_to_gpr back to its physical GPR ident.
+-- Returns { [physical_gpr_ident] = count }. Clash-detection and source-pool-exclusion logic
+-- only needs the presence of each GPR (boolean test), but keeping count preserves the
 -- original find_hardcoded_rn shape so callers can switch without churn.
 -- The alias pattern is sorted lexicographically to keep the regex deterministic.
 local function find_used_gprs(body_text, alias_to_gpr)

scripts/passes/components.lua

@@ -3,9 +3,12 @@
 --- Ownership: `corpus.word_counts`, `corpus.components`, and `corpus.component_body_index`.
 --- Scanner owns `declaration_comment` and `debug_skip` on each declaration record; this pass projects both forward.
 ---
---- Reads the pre-scanned SourceScan payload from `duffle.scan_source` for `MipsAtomComp_(ac_X)`, `MipsAtomComp_Proc_(ac_X, { body })`, and `MipsAtom_Proc_(X, ab, { body })` declarations,
+--- Reads the pre-scanned SourceScan payload from `duffle.scan_source` for `MipsAtomComp_(ac_X)` and `MipsAtomComp_Proc_(ac_X, { body })` declarations (kind="comp_bare" / "comp_proc"),
 --- then resolves the function-args string from the preceding `FI_ Slice_MipsCode ac_X(...)` declaration via a backward walk.
 ---
+--- `MipsAtom_Proc_(X, ab, { body })` declarations (kind="atom_proc") are ATOMS, not components, and are deliberately excluded —
+--- atoms get emitted via `tb_emit(tb, code_<name>)` linker symbols, not inlined as `mac_*` macros.
+---
 --- 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.
 --- 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.
@@ -76,7 +79,7 @@ local MACS_FILENAME   = "macs.h"
 --- @field args       string|nil -- Function-args string (function form only)
 --- @field line       integer    -- Source line of the declaration
 --- @field comment    string|nil -- Scanner-owned `declaration_comment`; the components pass reads it from the scanner record
---- @field kind       string     -- "comp_bare" | "comp_proc" | "atom_proc"
+--- @field kind       string     -- "comp_bare" | "comp_proc"  (atom_proc is NOT a component — see `project_components`)
 --- @field debug_skip boolean    -- Mirror of `a.debug_skip` (scanner-owned); true iff a bare `atom_dbg_skip` marker immediately preceded the declaration
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -200,16 +203,17 @@ end
 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" or a.kind == "atom_proc" then
-			-- `MipsAtom_Proc_` atoms have no `FI_ Slice_MipsCode ac_X(...)` function-decl prelude
-			-- (the macro sits inside a wrapping `I_ void <proc_name>(...)` body), so the function-args
-			-- lookup is meaningless; signature defaults to `...` (variadic-ignored).
-			-- The `mac_<name>` alias expansion discards the `ab` (atom-builder) arg the same way
-			-- `MipsAtomComp_Proc_` components do.
-			local args = nil
-			if a.kind ~= "atom_proc" then
-				args = find_function_args_for(source, a.raw_name, a.ident_pos)
-			end
+		-- Only `MipsAtomComp_(ac_X)` (kind="comp_bare") and `MipsAtomComp_Proc_(ac_X, ...)` (kind="comp_proc")
+		-- are COMPONENTS — they get inlined via `mac_<name>` aliases inside atom bodies.
+		-- `MipsAtom_Proc_` (kind="atom_proc") is an ATOM (ends with `mac_yield()`); it gets emitted via
+		-- `tb_emit(tb, code_<name>)` (linker symbol), NOT inlined as a macro. Including `atom_proc` here
+		-- would incorrectly emit `mac_<name>` aliases for atoms, polluting `gen/macs.h`.
+		-- See `docs/duffle_dsl_primer.md` §"mac_* aliases" for the contract.
+		if a.kind == "comp_bare" or a.kind == "comp_proc" then
+			-- Function-args lookup is meaningful for `MipsAtomComp_Proc_` components
+			-- (the macro sits inside `FI_ Slice_MipsCode ac_X(...)`); the alias expansion
+			-- discards the `ab` (atom-builder) arg the same way both forms do.
+			local args = find_function_args_for(source, a.raw_name, 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 ""
@@ -221,7 +225,7 @@ local function project_components(source, scan)
 				body_tokens = a.body_tokens,
 				args        = args,
 				comment     = comment,
-				kind        = a.kind,  -- "comp_bare" | "comp_proc" | "atom_proc"; provenance emitter reads this.
+				kind        = a.kind,  -- "comp_bare" | "comp_proc"; provenance emitter reads this.
 				debug_skip  = a.debug_skip == true,
 			}
 		end
@@ -400,8 +404,7 @@ local function cycle_cost_rec(name, comp_by_name, latency, cache)
 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.
+--- 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>
@@ -484,10 +487,9 @@ end
 
 --- Determine the macro signature: function-args list (function form) or variadic-ignored (bare form).
 --- For `MipsAtomComp_Proc_` components, the leading `ab` (atom-builder) arg is dropped:
---- the generated `mac_<name>` macros are inline-expansion aliases for baked atoms; their bodies
---- don't reference `ab` (the builder is only consumed by the procedural `atombuilder_unroll` line
---- that `MipsAtomComp_Proc_` appends after the body). Inline callers therefore don't need to thread
---- a builder context.
+--- the generated `mac_<name>` macros are inline-expansion aliases for baked atoms; their bodies don't reference `ab`
+--- (the builder is only consumed by the procedural `atombuilder_unroll` line that `MipsAtomComp_Proc_` appends after the body).
+--- Inline callers therefore don't need to thread a builder context.
 --- @param args_str string|nil
 --- @return string
 local function signature_from_args(args_str)
@@ -544,7 +546,7 @@ local function build_component_lines(c, counts)
 
 	-- 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.
+	-- This 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
@@ -578,8 +580,8 @@ end
 
 --- Build the boilerplate header lines (the `#ifdef INTELLISENSE_DIRECTIVES` block,
 --- the `// Auto-generated` comment, the `// Source:` line, and the self-contained `WORD_COUNT` macro definition).
---- @param dir     string       -- the absolute source directory
---- @param sources SourceFile[] -- sources contributing to this directory (for the header comment)
+--- @param dir     string       -- Absolute source directory
+--- @param sources SourceFile[] -- Sources contributing to this directory (for the header comment)
 --- @return string[]
 local function header_boilerplate(dir, sources)
 	local source_lines = { "// Directory: " .. duffle.to_absolute_path(dir) .. "/" }
@@ -610,9 +612,9 @@ end
 --- Compute the per-directory output path for `.macs.h`.
 ---  e.g. any source in `code/duffle/` produces `code/duffle/gen/macs.h` regardless of source filename.
 --- The directory name is the namespace; the filename does not repeat it.
---- @param dir string  -- the absolute source directory
---- @return string  -- the output directory
---- @return string  -- the full output path
+--- @param dir string  -- Absolute source directory
+--- @return string  -- Output directory
+--- @return string  -- Full output path
 local function compute_macs_h_path(dir)
 	local  out_dir  = dir .. "/" .. GEN_SUBDIR
 	local  out_path = out_dir .. "/" .. MACS_FILENAME
@@ -622,11 +624,11 @@ end
 --- 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).
 --- @param ctx        PassCtx
---- @param dir        string                  -- the absolute source directory
---- @param sources    SourceFile[]            -- sources contributing to this directory (for the header comment)
---- @param components Component[]             -- aggregated components from all sources in this directory
---- @param counts     table<string, integer>  -- precomputed word counts (from count_all_components)
---- @return string|nil  -- path to the written file (nil if no components)
+--- @param dir        string                  -- Absolute source directory
+--- @param sources    SourceFile[]            -- Sources contributing to this directory (for the header comment)
+--- @param components Component[]             -- Aggregated components from all sources in this directory
+--- @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, dir, sources, components, counts)
 	if #components == 0 then return nil end
 	local out_dir, out_path = compute_macs_h_path(dir)
@@ -665,11 +667,11 @@ local function update_canonical_word_counts(corpus, components, counts)
 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" | "atom_proc"
---- @field debug_skip boolean -- mirror of the scanner-owned `a.debug_skip`; consumers read this directly
+--- @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"  (atom_proc is NOT a component)
+--- @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").

scripts/passes/dwarf_injection.lua

@@ -703,9 +703,9 @@ end
 ---     `{comp_name, call_file, call_line, comp_file, comp_line, start_pos, end_pos, body_lines, debug_skip}`. `body_lines[k]`
 ---     is the k-th word's source line within the component body.
 ---
---- @param corpus table -- the corpus from `ctx.shared.corpus`
+--- @param corpus table -- From `ctx.shared.corpus`
 --- @param addrs  table -- ELF symbols keyed by atom name from `elf_dwarf.read_nm`
---- @return table[]  -- list of {name, addr, size_bytes, words, entries, invocations, debug_skip?}
+--- @return table[]  -- List of {name, addr, size_bytes, words, entries, invocations, debug_skip?}
 local function build_atom_table(corpus, addrs)
 	-- Cross-ref: keep only atoms present in BOTH the nm symbol table AND `corpus.atoms_by_name`. Output is sorted by ascending addr.
 	local atoms_by_name = corpus.atoms_by_name or {}
@@ -834,10 +834,10 @@ end
 --- This is intentional: silently falling back to a hardcoded GPR would mask the missing opt-in.
 ---
 --- Pre-tokenized: `body_tokens` is the scan-source pass's pre-split list of top-level statements (each entry is a single `load_*` call or other statement).
---- @param body_tokens table[]  -- the atom's pre-tokenized body statements (from atom.body_tokens)
---- @param binds_name  string   -- expected Binds_X name (skip pairs with mismatching binds)
---- @param registries  table    -- merged registries from collect_per_source_registries
---- @return table[]             -- list of {reg = <MIPS index>, field = <field name>}
+--- @param body_tokens table[]  -- The atom's pre-tokenized body statements (from atom.body_tokens)
+--- @param binds_name  string   -- Expected Binds_X name (skip pairs with mismatching binds)
+--- @param registries  table    -- Merged registries from collect_per_source_registries
+--- @return table[]             -- List of {reg = <MIPS index>, field = <field name>}
 local function parse_body_load_pairs(body_tokens, binds_name, registries)
 	local pairs = {}
 	local reg_index_by_name = (registries and registries.register_alias_registry) or {}
@@ -880,9 +880,9 @@ end
 --- The piece chain uses (DW_OP_regN, DW_OP_piece, ULEB128(field_size)).
 ---
 --- Binds fields come from `scan.binds`; the per-source `scan.binds[i].fields` already carries the typed-field record after the scan-source generalization.
---- @param corpus     table   -- the corpus from `ctx.shared.corpus`
---- @param atom_table table[] -- the cross-ref'd atom table from build_atom_table
---- @param registries table   -- merged registries from collect_per_source_registries
+--- @param corpus     table   -- From `ctx.shared.corpus`
+--- @param atom_table table[] -- Cross-ref'd atom table from build_atom_table
+--- @param registries table   -- Merged registries from collect_per_source_registries
 --- @return table, table      -- (rbind_atoms, rbind_structs)
 local function parse_rbind_atoms(corpus, atom_table, registries)
 	registries = registries or {}
@@ -944,7 +944,7 @@ local function parse_rbind_atoms(corpus, atom_table, registries)
 						binds     = ai.binds,
 						fields    = struct.fields, -- {name, offset} from scan.binds
 						bytes     = struct.bytes,
-						regs      = pairs,         -- ordered list of {reg, field}
+						regs      = pairs,         -- Ordered list of {reg, field}
 						info_line = ai.info_line,
 					}
 					table.insert(struct.atom_names, atom_name)
@@ -1036,13 +1036,13 @@ local function build_dwarf_aranges_section(existing, atom_table)
 	-- We bump the unit's length field accordingly.
 	--
 	-- Unit structure (DWARF4 §7.21):
-	--   unit_length (4)
-	--   version (2)
+	--   unit_length       (4)
+	--   version           (2)
 	--   debug_info_offset (4)  -- CU DIE offset in .debug_info
-	--   address_size (1)
-	--   segment_size (1)
-	--   entries... (4-byte addr + 4-byte length)
-	--   terminator (8 bytes: addr=0, length=0)
+	--   address_size      (1)
+	--   segment_size      (1)
+	--   entries...        (4-byte addr + 4-byte length)
+	--   terminator        (8 bytes: addr=0, length=0)
 
 	-- Walk all units and emit each one (preserving existing structure).
 	-- For the LAST unit, replace the terminator with my entries + new term.
@@ -1780,7 +1780,8 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
 	emit(uleb128(ABBREV_TYPED_VIEW_POINTER))  -- DW_TAG_pointer_type (abbrev 110; NOT 9; void chain target)
 	emit(elf_dwarf.write_u32_le(ref4_of(void_chain_offset)))  -- 4-byte ref4: points at the void base_type's tag byte
 	-- type_chain_offsets["void|1"] is what step (f) of the per-RR_<R_Name> chain looks up.
-	type_chain_offsets["void|1"] = void_chain_offset  -- both the base_type offset and the pointer_type are emitted consecutively; the OUTERMOST is the pointer_type. The variable's DW_AT_type must reference the pointer_type, not the base_type. Patch below.
+	type_chain_offsets["void|1"] = void_chain_offset  -- both the base_type offset and the pointer_type are emitted consecutively; the OUTERMOST is the pointer_type.
+	-- The variable's DW_AT_type must reference the pointer_type, not the base_type. Patch below.
 	-- Capture the pointer_type's offset (the last-thing-emitted DIE start) and overwrite the lookup.
 	-- The pointer_type was emitted as: uleb(9) (1 byte) + 4-byte ref4 = 5 bytes. Its tag byte is at void_chain_offset + 8 (the base_type's 8 bytes: 1 tag + 5 name + 1 byte_size + 1 encoding).
 	local ptr_void_offset = void_chain_offset + 8

scripts/passes/offsets.lua

@@ -4,9 +4,17 @@
 --- 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
 --- `gen/offsets.h` with one `#define _atom_offset_F_T = N` per branch.
+---
 --- Per-directory aggregation: every source in the same directory contributes to the same `gen/offsets.h`.
 --- The directory itself is the namespace; the filename does not repeat the module name.
 ---
+--- (Task 12.16 note: atom-namespaced enum names — e.g., `atom_offset__normalize_v3s4__srav_path__aligned_done` —
+--- were considered to prevent cross-atom label collisions, but the C-side `atom_offset(F, T)` macro in
+--- `code/duffle/dsl.atom.h` doesn't know the current atom_name at expansion time, so any namespacing
+--- on the metaprogram side breaks the C build. Reverted. The C-side would need a per-atom
+--- `CURRENT_ATOM` #define (set by `MipsAtom_`/`MipsAtom_Proc_` macros) plus an updated `atom_offset`
+--- macro that uses it. That's a coordinated refactor — deferred to a future track.)
+---
 --- The offset is `target_word - branch_word - 1` (the standard MIPS branch-immediate encoding: branch_offset = relative_pc_in_words - 1).
 
 -- ════════════════════════════════════════════════════════════════════════════

scripts/passes/static_analysis.lua

@@ -39,8 +39,8 @@
 --- `── Info` section renders finding-level info between `── Warnings` and the per-atom cycle counts.
 ---
 --- The structural handshake checks (`mac_yield_uniformity`, `hazard_nop_use`, `control_transfer_delay_slot_use`) skip atoms/components with `debug_skip == true`.
---- The `atom_dbg_skip` marker designates runtime-helper declarations whose structure is fixed by the tape runtime (e.g. `tape_exit`, `ac_yield`).
---- Flagging them as "missing mac_yield" or "BD slot is redundant" is signal noise, not a logic failure. 
+--- `atom_dbg_skip` marker designates runtime-helper declarations whose structure is fixed by the tape runtime (e.g. `tape_exit`, `ac_yield`).
+--- Flagging them as "missing mac_yield" or "BD slot is redundant".
 --- Other checks (transfer_hazards, gpu_portstore_shape, abi_handoff, enum_alias_membership, …) still apply to debug_skip declarations because real hazards / typos can still surface in them.
 ---
 --- The orchestrator (`ps1_meta.lua`) wires this module in via the PASSES table:
@@ -452,7 +452,7 @@ local function is_cop2_consumer_of(consumer_event, destination, producer_rel)
 end
 
 -- True iff `consumer_event` reads the GPR operand at any position the destination register occupies.
--- The read-position lookup consults `duffle.OPERAND_READ_POSITIONS` for the consumer's encoder and walks each `args[pos]` to find an operand-equal match.
+-- read_pos lookup consults `duffle.OPERAND_READ_POSITIONS` for the consumer's encoder and walks each `args[pos]` to find an operand-equal match.
 local function is_gpr_consumer_of(consumer_event, destination)
 	local consumer_token = consumer_event.encoder or consumer_event.ident
 	local read_pos       = duffle.OPERAND_READ_POSITIONS or {}