posts-article minor changes

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

@@ -30,7 +30,7 @@
 		"editorHoverWidget.background": "#2c334b"
 	},
 	"semanticTokenColors": {
-		"comment": { "foreground": "#868686", "fontStyle": "italic" },
+		"comment": { "foreground": "#868686", }, //"fontStyle": "italic" },
 		"keyword": { "foreground": "#d8bd5b" },
 		"string": { "foreground": "#d46a54" },
 		"number": { "foreground": "#b5cea8" },
@@ -81,7 +81,7 @@
 		"tapeDelaySlot": { "foreground": "#ff5647" }
 	},
 	"tokenColors": [
-		{ "scope": ["comment", "comment.block", "comment.line", "comment.block.documentation"], "settings": { "foreground": "#868686", "fontStyle": "italic" } },
+		{ "scope": ["comment", "comment.block", "comment.line", "comment.block.documentation"], "settings": { "foreground": "#868686", } }, //"fontStyle": "italic" } },
 		{ "scope": ["keyword", "keyword.control", "keyword.other"], "settings": { "foreground": "#d8bd5b" } },
 		{ "scope": ["string", "string.quoted"], "settings": { "foreground": "#d46a54" } },
 		{ "scope": ["string.quoted.other"], "settings": { "foreground": "#d69d85" } },

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

@@ -33,23 +33,59 @@ const TOKEN_MODIFIER_INDEX = new Map(TOKEN_MODIFIERS.map((name, index) => [name,
 const ATOM_KEYWORDS = new Set(["MipsAtom_", "MipsAtom_Proc_"]);
 const COMPONENT_KEYWORDS = new Set(["MipsAtomComp_", "MipsAtomComp_Proc_"]);
 const ANNOTATIONS = new Set([
-	"atom_info", "atom_bind", "atom_reads", "atom_writes", "atom_label",
+	"atom_info",
-	"atom_offset", "atom_reg", "atom_type", "atom_ctx", "atom_phase",
+	"atom_bind",
-	"atom_auto_reg", "phase_auto_reg", "atom_dbg_skip",
+	"atom_reads",
+	"atom_writes",
+	"atom_label",
+	"atom_offset",
+	"atom_reg",
+	"atom_type",
+	"atom_ctx",
+	"atom_phase",
+	"atom_auto_reg", 
+	"phase_auto_reg", 
+	"atom_dbg_skip",
 ]);
 
 const DSL_KEYWORDS = new Set([
-	"FI_", "I_", "NI_", "Relative_", "Struct_", "Enum_", "Union_", "Array_",
+	"enum", "struct", "union",
-	"Slice_", "TypeR_", "TypeV_", "align_", "internal", "local_persist", "global",
+	"offset_of", "static_assert", "typeof", "typeof_ptr", "typeof_same",
-	"RO_", "LP_", "gknown", "expect_", "cexpr_",
+	"glue", "tmpl",
+	"A_", "FI_", "I_", "NI_", 
+	"Array_", "Enum_", "Proc_", "Relative_", "Struct_", "Union_", "Slice_", 
+
+	// "TypeR_", "TypeV_",
+
+	"align_", 
+	"internal", "local_persist", "global",
+
+	"RO_", "LP_", 
+	"gknown", "expect_", "cexpr_",
+
+	"O_", "OA_", "S_", "C_", "T_", "T_same", "R_", "V_",
+	"r_", "v_", "rt_", "vt_",
+
 	"asm", "asm_words", "asm_rpins", "asm_clobber",
-	"O_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "rt_", "vt_",
 	"rgcc", "r_use", "r_set", "r_mod", "r_imm", "r_mem",
-	"u1_", "u2_", "u4_", "u8_", "s1_", "s2_", "s4_", "s8_",
+	
-	"u1_r", "u2_r", "u4_r", "u8_r", "u1_v", "u2_v", "u4_v", "u8_v",
+	"b1_", "b2_", "b4_", "b8_", 
+	"u1_", "u2_", "u4_", "u8_", 
+	"s1_", "s2_", "s4_", "s8_",
+	"b1_r", "b2_r", "b4_r", "b8_r", 
+	"b1_v", "b2_v", "b4_v", "b8_v", 
+	"u1_r", "u2_r", "u4_r", "u8_r", 
+	"u1_v", "u2_v", "u4_v", "u8_v",
+
+	"u4_lo", "u4_hi",
 ]);
 
-const DELAY_SLOT_KEYWORDS = new Set(["LdSlot_", "BdSlot_", "DmaSlot_", "GteDelay_"]);
+const DELAY_SLOT_KEYWORDS = new Set([
+	"LdSlot_",
+	"BdSlot_",
+	"DmaSlot_",
+	"GteDelay_"
+]);
 
 const CONTROL_FLOW_PREFIXES = /^(?:branch_|jump_|call_)/;
 
@@ -100,10 +136,8 @@ function modifierMask(modifiers) {
 }
 
 function isRegUseAccess(tokens, tokenIndex) {
-	const prev = tokens[tokenIndex - 1];
+	const prev     = tokens[tokenIndex - 1]; if (!prev || prev.text !== ".") return false;
-	if (!prev || prev.text !== ".") return false;
+	const prevPrev = tokens[tokenIndex - 2]; if (!prevPrev || prevPrev.kind !== "identifier") return false;
-	const prevPrev = tokens[tokenIndex - 2];
-	if (!prevPrev || prevPrev.kind !== "identifier") return false;
 	const next     = tokens[tokenIndex + 1];
 	if (next && next.text === ".") return false;
 	if (prevPrev.text     === "r") return true;
@@ -120,8 +154,7 @@ function classifyDocument(source, filePath, workspaceIndex, shouldCancel = () =>
 
 	for (let tokenIndex = 0; tokenIndex < scanned.tokens.length; tokenIndex += 1) {
 		if (shouldCancel()) break;
-		const token = scanned.tokens[tokenIndex];
+		const token = scanned.tokens[tokenIndex]; if (token.kind !== "identifier") continue;
-		if (token.kind !== "identifier") continue;
 
 		let type          = null;
 		let modifiers     = [];
@@ -131,37 +164,49 @@ function classifyDocument(source, filePath, workspaceIndex, shouldCancel = () =>
 		if (declaration) {
 			type      = ROLE_TO_TYPE[declaration.role] || null;
 			modifiers = declaration.modifiers.slice();
-		} else if (ATOM_KEYWORDS.has(token.text)) {
+		} 
+		else if (ATOM_KEYWORDS.has(token.text)) {
 			type = "tapeAtomKeyword";
-		} else if (COMPONENT_KEYWORDS.has(token.text)) {
+		} 
+		else if (COMPONENT_KEYWORDS.has(token.text)) {
 			type = "keyword";
-		} else if (ANNOTATIONS.has(token.text)) {
+		} 
+		else if (ANNOTATIONS.has(token.text)) {
 			type = "tapeAnnotation";
-		} else if (context && context.callee === "atom_bind" && context.argIndex === 0) {
+		} 
+		else if (context && context.callee === "atom_bind" && context.argIndex === 0) {
 			type = "tapeBindType";
-		} else if (context && context.callee === "atom_phase" && context.argIndex === 0) {
+		} 
+		else if (context && context.callee === "atom_phase" && context.argIndex === 0) {
 			type = "tapePhase";
 			modifiers = ["declaration"];
-		} else if (context && context.callee === "atom_ctx" && context.argIndex === 0) {
+		} 
+		else if (context && context.callee === "atom_ctx" && context.argIndex === 0) {
 			type = "tapeAtomName";
-		} else if (context && context.callee === "atom_label" && context.argIndex === 0) {
+		} 
+		else if (context && context.callee === "atom_label" && context.argIndex === 0) {
 			type = "tapeLabel";
 			modifiers = ["declaration"];
-		} else if (context && context.callee === "atom_offset" && context.argIndex <= 1) {
+		} 
+		else if (context && context.callee === "atom_offset" && context.argIndex <= 1) {
 			type = "tapeLabel";
-		} else if (context && context.callee === "atom_reads") {
+		} 
+		else if (context && context.callee === "atom_reads") {
 			type = registerType(token.text, index);
 			if (type) modifiers = ["tapeRead"];
-		} else if (context && context.callee === "atom_writes") {
+		} 
+		else if (context && context.callee === "atom_writes") {
 			type = registerType(token.text, index);
 			if (type) modifiers = ["tapeWrite"];
-		} else if (context && context.callee === "atom_auto_reg") {
+		} 
+		else if (context && context.callee === "atom_auto_reg") {
 			if (context.argIndex === 0) type = "tapeAtomName";
 			if (context.argIndex === 1) {
 				type      = "tapeGprRegister";
 				modifiers = ["declaration", "tapeAuto"];
 			}
-		} else if (context && context.callee === "phase_auto_reg") {
+		} 
+		else if (context && context.callee === "phase_auto_reg") {
 			if (context.argIndex === 0) type = "tapePhase";
 			if (context.argIndex === 1) {
 				type      = "tapeGprRegister";

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

@@ -39,7 +39,8 @@ async function activate(context) {
 				const result = scanSource(source, uri.fsPath);
 				nextIndex    = mergeIndexes(nextIndex, result.index);
 				for (const error of result.errors) output.appendLine(formatError(uri.fsPath, error));
-			} catch (error) {
+			} 
+			catch (error) {
 				output.appendLine(`${uri.fsPath}: ${error.stack || error.message || error}`);
 			}
 		}
@@ -55,7 +56,9 @@ async function activate(context) {
 		debounceHandle = setTimeout(() => {
 				debounceHandle = null;
 				rebuildIndex().catch((error) => output.appendLine(error.stack || String(error)));
-		}, 100);
+			}, 
+			100
+		);
 	}
 
 	const provider = {
@@ -77,7 +80,8 @@ async function activate(context) {
 					output.appendLine(formatError(document.uri.fsPath || document.uri.toString(), error));
 				}
 				return builder.build();
-			} catch (error) {
+			}
+			catch (error) {
 				output.appendLine(`${document.uri}: ${error.stack || error.message || error}`);
 				return new vscode.SemanticTokensBuilder(legend).build();
 			}

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

@@ -10,7 +10,8 @@ function isIdentifierContinue(code) {
 	return isIdentifierStart(code) || (code >= 48 && code <= 57);
 }
 
-function lex(source) {
+function lex(source)
+{
 	if (typeof source !== "string") throw new TypeError("source must be a string");
 
 	const tokens    = [];
@@ -47,7 +48,8 @@ function lex(source) {
 		});
 	}
 
-	while (offset < source.length) {
+	while (offset < source.length)
+	{
 		const ch = source[offset];
 
 		if (/\s/.test(ch)) {
@@ -60,12 +62,14 @@ function lex(source) {
 			continue;
 		}
 
-		if (ch === "/" && source[offset + 1] === "*") {
+		if (ch === "/" && source[offset + 1] === "*")
+		{
 			const start = offset;
 			advance();
 			advance();
 			let closed = false;
-			while (offset < source.length) {
+			while (offset < source.length)
+			{
 				if (source[offset] === "*" && source[offset + 1] === "/") {
 					advance();
 					advance();
@@ -78,12 +82,14 @@ function lex(source) {
 			continue;
 		}
 
-		if (ch === "\"" || ch === "'") {
+		if (ch === "\"" || ch === "'")
+		{
 			const quote = ch;
 			const start = offset;
 			advance();
 			let closed = false;
-			while (offset < source.length) {
+			while (offset < source.length)
+			{
 				if (source[offset] === "\\") {
 					advance();
 					if (offset < source.length) advance();
@@ -134,7 +140,8 @@ function buildCallContexts(tokens) {
 		if (token.text === ")") {
 			if (stack.length === 0) {
 				errors.push({ kind: "unmatched-close-paren", offset: token.start });
-			} else {
+			}
+			else {
 				const frame = stack.pop();
 				if (frame.callee !== null) calls.push({ ...frame, closeTokenIndex: tokenIndex });
 			}

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

@@ -4,8 +4,10 @@ const path = require("node:path");
 const { buildCallContexts, lex, nearestCall } = require("./lexer");
 
 const BASE_TYPES = [
-	"B1", "B2", "B4", "B8", "F4", "F8", "S1", "S2", "S4", "S8",
+	"B1", "B2", "B4", "B8",
-	"U1", "U2", "U4", "U8", "MipsAtom", "MipsCode", "Reg",
+	"F4", "F8", "S1", "S2", "S4", "S8",
+	"U1", "U2", "U4", "U8",
+	"MipsAtom", "MipsCode", "Reg",
 ];
 
 const C_BUILTINS = new Set([
@@ -15,11 +17,13 @@ const C_BUILTINS = new Set([
 ]);
 
 const BASE_ATTRIBUTES = [
-	"FI_", "I_", "NI_", "Relative_", "Struct_", "Enum_", "Union_", "Array_",
+	"FI_", "I_", "NI_", 
-	"Slice_", "TypeR_", "TypeV_", "align_", "internal", "local_persist", "global",
+	"Relative_", "Struct_", "Enum_", "Union_", "Array_", "Slice_", 
-	"RO_", "LP_", "gknown", "expect_", "cexpr_",
+	"align_", "internal", "local_persist", "global",
+	"RO_", "LP_", 
+	"gknown", "expect_", "cexpr_",
 	"asm", "asm_words", "asm_rpins", "asm_clobber",
-	"O_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "rt_", "vt_",
+	"O_", "OA_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "rt_", "vt_",
 	"rgcc", "r_use", "r_set", "r_mod", "r_imm", "r_mem",
 	"u1_", "u2_", "u4_", "u8_", "s1_", "s2_", "s4_", "s8_",
 	"u1_r", "u2_r", "u4_r", "u8_r", "u1_v", "u2_v", "u4_v", "u8_v",
@@ -161,7 +165,8 @@ function findFunctionNameBefore(tokens, calleeTokenIndex) {
 	return null;
 }
 
-function scanSource(source, filePath) {
+function scanSource(source, filePath)
+{
 	const lexical      = lex(source);
 	const balanced     = buildCallContexts(lexical.tokens);
 	const tokens       = lexical.tokens;
@@ -191,7 +196,8 @@ function scanSource(source, filePath) {
 		if (!index.macros.has(alias)) index.macros.set(alias, "component");
 	}
 
-	for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex += 1) {
+	for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex += 1)
+	{
 		const token = tokens[tokenIndex];
 		if (token.kind !== "identifier") continue;
 
@@ -240,12 +246,14 @@ function scanSource(source, filePath) {
 			mark(token, "gprRegister", ["declaration", "tapeAuto"]);
 		}
 
-		if (token.text === "define" && tokens[tokenIndex - 1] && tokens[tokenIndex - 1].text === "#") {
+		if (token.text === "define" && tokens[tokenIndex - 1] && tokens[tokenIndex - 1].text === "#")
+		{
 			const name = tokens[tokenIndex + 1];
 			if (name && name.kind === "identifier" && name.line === token.line) {
 				if (/^(?:RegUse_|Struct_|Enum_|Union_|TypeR_|TypeV_|Relative_|Binds_)/.test(name.text)) {
 					index.types.add(name.text);
-				} else if (/^(?:ac_|mac_)/.test(name.text)) {
+				}
+				else if (/^(?:ac_|mac_)/.test(name.text)) {
 					const alias = name.text.startsWith("ac_") ? componentAlias(name.text) : name.text;
 					const rest = [];
 					for (let restIndex = tokenIndex + 2; restIndex < tokens.length && tokens[restIndex].line === name.line; restIndex += 1) {
@@ -256,7 +264,8 @@ function scanSource(source, filePath) {
 						index.macros.set(alias, prefixDomain(alias) || "component");
 						if (rest.length) index.componentCallees.set(alias, rest);
 					}
-				} else {
+				}
+				else {
 					index.macros.set(name.text, domain || "utility");
 				}
 			}

code/duffle/dsl.h

@@ -31,7 +31,6 @@
 
 #define A_(data)      (& (data))
 #define align_(value) __attribute__((aligned (value)))             // for easy alignment
-#define align_(value) __attribute__((aligned (value)))             // for easy alignment
 #define C_(type,data) ((type)(data))                               // for enforced precedence
 #define expect_(x, y) __builtin_expect(x, y)                       // so compiler knows the common path
 #define cexpr_        __builtin_constant_p
@@ -121,7 +120,6 @@ typedef unsigned char   TSet_(B1);
 typedef __UINT16_TYPE__ TSet_(B2); 
 typedef __UINT32_TYPE__ TSet_(B4);
 
-
 #define b1_(value)  C_(B1, value)
 #define b2_(value)  C_(B2, value)
 #define b4_(value)  C_(B4, value)

code/duffle/gen/macs.h

@@ -19,7 +19,7 @@
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.atom.c
-//   source: C:\projects\Pikuma\ps1\code\duffle\gte.atom.h
+//   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
@@ -35,6 +35,7 @@
  *  These do NOT yield. They are expanded inline inside Tape Atoms.
  * ---------------------------------------------------------------------------*/
 // The 'Yield' sequence for Tape Atoms (mac_yield).
+// In Forth this is considered the "NEXT" mechanism.
 #define mac_yield(...) \
 	load_word(R_AtomJmp, R_TapePtr, 0) \
 	LdSlot_ \
@@ -55,6 +56,12 @@ WORD_COUNT(mac_yield_load, 1)
 ,	BdSlot_ nop
 WORD_COUNT(mac_yield_tail, 3)
 
+/* atom_dbg_skip */
+#define mac_yield_to(code_ptr) \
+	jump_reg(code_ptr) \
+,	BdSlot_ nop
+WORD_COUNT(mac_yield_to, 2)
+
 /* atom_dbg_skip */
 #define mac_load_half_v3(tx, ty, tz, base, offset) \
 	load_half(tx, base, offset + OA_(U2,[0])) \

code/duffle/gen/offsets.h

@@ -16,7 +16,7 @@
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.atom.c
-//   source: C:\projects\Pikuma\ps1\code\duffle\gte.atom.h
+//   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

code/duffle/gte.atom.c

@@ -4,6 +4,7 @@
 #	include "gte.h"
 #	include "gp.h"
 #	include "tape.h"	
+#	include "math.atom.h"
 #endif
 
 ATOM_FILE_DEBUGGER_LINE_MARKER(gte_atom_c);
@@ -183,59 +184,94 @@ MipsAtomComp_Proc_(ab, {
 	gte_mv_from_data_r(fr_mac3, C2_MAC3),
 })
 
-FI_ Slice_MipsCode ac_gte_mv_from_data_r_mac123(AtomBuilder_R ab
+FI_ Slice_MipsCode ac_gte_mv_from_data_r_mac123(AtomBuilder_R ab, Reg fr_mac1, Reg fr_mac2, Reg fr_mac3) 
-	, Reg fr_mac1, Reg fr_mac2, Reg fr_mac3)
 MipsAtomComp_Proc_(ab, {
 	gte_mv_from_data_r(fr_mac1, C2_MAC1),
 	gte_mv_from_data_r(fr_mac2, C2_MAC2),
 	gte_mv_from_data_r(fr_mac3, C2_MAC3),
 })
 
-
 FI_ Slice_MipsCode ac_gte_mv_from_mac123_v3s4(AtomBuilder_R ab, Reg_(V3_S4) v) MipsAtomComp_ProcMap_(ab, mac_gte_mv_from_data_r_mac123(v.x, v.y, v.z))
 
 #pragma endregion MACs (Mips Atom Components)
 
 #pragma region Atom Procs
 
-/* ─── Local copy of PSYQ's sqrtbl (1/sqrt lookup table for VectorNormal). ───
+/* Normalize V3_S4 using the PSYQ/libgte reciprocal-sqrt method:
- * Source: PSYQ 4.7 libgte sqrtbl at 0x800185B4 in hello_camera.elf.
+ *   |v|² = x² + y² + z²
- *   objdump -s --start-address=0x800185B4 --stop-address=0x800185F4 hello_camera.elf → 192 entries × 16-bit signed, in 1.12 fixed-point (max value 0x1000 = 1.0).
+ *   LZCR determines the exponent of |v|².
+ *   Round that exponent even and shift |v|² into [1, 4).
+ *   sqrtbl approximates 1/sqrt(mantissa).
+ *   GPF multiplies v by that reciprocal-sqrt mantissa.
+ *   srav_shift restores the exponent scale.
+ * Effectively: v_normalized = v * (1 / sqrt(|v|²)).
  * 
+ * ─── Local port of PSYQ's sqrtbl (1/sqrt lookup table for VectorNormal). ───
+ * Source: PSYQ 4.7 libgte sqrtbl at 0x800185B4 in hello_camera.elf.
+ *   objdump -s --start-address=0x800185B4 --stop-address=0x800185F4 hello_camera.elf -> 192 entries x 16-bit signed, stored in 1.12 fixed point.
  * Data is identical to the libgte original (byte-for-byte verified).
  *
- * ─── Per-entry semantics (decoded from libgte msc02 VectorNormal) ───
+ * ─── Table semantics ───
- * Each entry is `1/sqrt(x)` in 1.12 fixed point (value / 4096).
+ * For table index i in [0, 192):
- * The 192 entries span 4 octaves of the input magnitude, with 48 entries per octave:
+ *     x      = 1 + i / 64
- *   Octave 0 (entries  0- 47): mantissa in [0x8000,  0x10000)  output ~[1.000, 0.707]
+ *     tbl[i] = floor(4096 / sqrt(x))
- *   Octave 1 (entries 48- 95): mantissa in [0x10000, 0x20000)  output ~[0.707, 0.500]
+ * Thus the table uniformly samples 1/sqrt(x) over:
- *   Octave 2 (entries 96-143): mantissa in [0x20000, 0x40000)  output ~[0.500, 0.354]
+ *     x in [1.0, 4.0)
- *   Octave 3 (entries144-191): mantissa in [0x40000, 0x80000)  output ~[0.354, 0.251]
+ * at steps of 1/64, with the result represented in 1.12 fixed point (0x1000 = 1.0).
- * Within each octave, 8 sub-entries interpolate over the 8 fractional bits of the mantissa
- * (the byte `(0x80 | (i mod 8))` for the lower-byte of the aligned value).
- * Sampling the first value of each octave:
- *   [0]   0x1000 = 1.0000                 ; 1 / sqrt(1.0000)
- *   [48]  0x0e4f = 0.8940                 ; 1 / sqrt(1.2500)
- *   [96]  0x0d10 = 0.8164                 ; 1 / sqrt(1.5000)
- *   [144] 0x0c0a = 0.7520                 ; 1 / sqrt(1.7500)
- * And representative sub-entries within octave 0 (mantissa in [0x8000, 0x8100)):
- *   [0]   0x1000 = 1.0000                 ; 1 / sqrt(0x8000)
- *   [1]   0x0fe0 = 0.9922                 ; 1 / sqrt(0x8100)
- *   [2]   0x0fc1 = 0.9846                 ; 1 / sqrt(0x8200)
- *   [3]   0x0fa3 = 0.9773                 ; 1 / sqrt(0x8300)
- *   [4]   0x0f85 = 0.9700                 ; 1 / sqrt(0x8400)
- *   [5]   0x0f68 = 0.9629                 ; 1 / sqrt(0x8500)
- *   [6]   0x0f4c = 0.9561                 ; 1 / sqrt(0x8600)
- *   [7]   0x0f30 = 0.9492                 ; 1 / sqrt(0x8700)
  *
- * The algorithm's `addi -64 / sll 1 / lh` selects the entry at `(aligned - 64) * 2` for the case where `aligned` has its top bit at bit 24.
+ * Representative entries:
- * After the sllv/srav pair, `aligned` always lands in `[0x80, 0x100)` 
+ *     [  0] 0x1000 = 1.000000   ; 1 / sqrt(1.000000)
- * (with top bit at bit 24 → after `sub $aligned - 64`, the index sits in `[0x40, 0x80) * 2 = [0x80, 0x100)` bytes = entries [64, 128) within the sqrtbl).
+ *     [ 16] 0x0e4f = 0.894287   ; 1 / sqrt(1.250000)
- * The earlier 64 entries (octave 0) are reached when the magnitude after shifting puts the top bit below bit 24 (the `sllv` branch),
+ *     [ 32] 0x0d10 = 0.816406   ; 1 / sqrt(1.500000)
- * and the load upper_halves of the table bracket the input range.
+ *     [ 48] 0x0c18 = 0.755859   ; 1 / sqrt(1.750000)
- * The later 64 entries (octaves 2-3) are the `srav` branch when the magnitude's top bit is well above bit 24.
+ *     [ 64] 0x0b50 = 0.707031   ; 1 / sqrt(2.000000)
+ *     [128] 0x093c = 0.577148   ; 1 / sqrt(3.000000)
+ *     [191] 0x0804 = 0.500977   ; 1 / sqrt(3.984375)
  *
- * Reproduced verbatim from libgte (verified against libpsn00b/psxgte/vector.s:100-123 — 24 rows × 8 halfwords, last entry 0x0804).
+ * ─── How VectorNormal indexes it ───
+ * Let:
+ *     mag_sq = x*x + y*y + z*z
+ *     lzcr   = leading-zero count of mag_sq
+ * For a non-zero magnitude, libgte first rounds LZCR down to an even number:
+ *     lzcr_even = lzcr & ~1
+ *
+ * It then shifts mag_sq so that its significant bits land in one of two
+ * adjacent normalized ranges:
+ *     if lzcr_even >= 24:
+ *         aligned = mag_sq << (lzcr_even - 24)
+ *     else:
+ *         aligned = mag_sq >> (24 - lzcr_even)
+ *
+ * Because lzcr_even differs from the true LZCR by at most one bit:
+ *     raw LZCR even -> aligned in [0x80, 0x100)
+ *     raw LZCR odd  -> aligned in [0x40, 0x080)
+ * therefore:
+ *     aligned in [0x40, 0x100)
+ *
+ * Dividing this normalized integer by 64 gives exactly the table domain:
+ *     x = aligned / 64
+ *     x in [1.0, 4.0)
+ *
+ * The lookup is therefore:
+ *     index       = aligned - 0x40
+ *     byte_offset = index * sizeof(S2)
+ *     inv_len     = sqrtbl[index]
+ * or equivalently, matching the libgte instructions:
+ *     addi aligned, -64
+ *     sll  aligned, 1
+ *     lh   inv_len, sqrtbl + aligned
+ *
+ * ─── Why the domain spans [1, 4) instead of [1, 2) ───
+ * Square-root scaling depends on the parity of the exponent.
+ * Rounding LZCR to even absorbs exponent changes in pairs of bits, leaving the lookup mantissa normalized over a factor-of-four interval [1, 4).
+ *
+ * The corresponding exponent correction is retained separately as:
+ *     srav_shift = (31 - lzcr_even) >> 1
+ *
+ * After GPF multiplies the original vector components by the table's reciprocal-square-root coefficient,
+ * this shift restores the exponent scale and yields the normalized vector.
+ *
+ * Reproduced verbatim from libgte; also matches PSn00bSDK VectorNormalS _norm_table (24 rows x 8 halfwords, final entry 0x0804).
  **/
 internal S2 const gte_normalize_sqr_tbl[192] align_(2) = {
 	0x1000, 0x0fe0, 0x0fc1, 0x0fa3, 0x0f85, 0x0f68, 0x0f4c, 0x0f30,
@@ -269,10 +305,10 @@ typedef Struct_(RegUse_normalize_v3s4) {
 	union { Reg_(V3_S4) res, src; };
 	union { Reg r0, src_ptr, mac2; };
 	union { Reg r1, dst_ptr; };
-	union { Reg r2, dst_offset, mac1, v_sqr_aligned; };
+	union { Reg r2, dst_offset, mac1, v_sqr_aligned, sqrtbl_byte_offset; };
-	union { Reg r3, src_offset, btarget, shift_count, sqrtbl_index; };
+	union { Reg r3, src_offset, align_delta, shift_count, sqrtbl_lookup; };
-	union { Reg r4, mac3, v_sqr_sum, scale_exp, srav_shift; };
+	union { Reg r4, mac3, v_sqr_sum, srav_shift; };
-	union { Reg r5, lzcr, inv_len; };
+	union { Reg r5, lzcr_raw, lzcr_even, inv_len; };
 };
 /* ─── Full normalize (all 4 stages inline) ───
  * Generic 4-stage GTE normalize (SQR → sum+LZCR → align+sqrtbl → GPF+srav). */
@@ -294,30 +330,30 @@ MipsAtom_Proc_(aa, {
 	add_u_self(        r.v_sqr_sum, r.mac1),
 	add_u_self(        r.v_sqr_sum, r.mac2),
 	gte_mv_to_data_r(  r.v_sqr_sum, C2_LZCS), GteDelay_ nop2,
-	gte_mv_from_data_r(r.lzcr,      C2_LZCR), GteDelay_ nop,
+	gte_mv_from_data_r(r.lzcr_raw,  C2_LZCR), GteDelay_ nop,
 
 	/* Stage 3: even(LZCR), half-shift, align |v|² to bit 24. */
-	mac_lzcr_round_even_half_shift(r.lzcr, r.v_sqr_sum, r.v_sqr_aligned),
+	mac_lzcr_round_even_half_shift(r.lzcr_raw, r.v_sqr_sum, r.v_sqr_aligned),
-	add_si(        r.btarget, r.lzcr, -24),
+	add_si(        r.align_delta, r.lzcr_even, -24),
-	branch_lt_zero(r.btarget, atom_offset(aligned_done, srav_path)), BdSlot_ nop, /* bltz → srav_path (LZCR <  24 path) */
+	branch_lt_zero(r.align_delta, atom_offset(aligned_done, srav_path)), BdSlot_ nop, /* bltz → srav_path (LZCR <  24 path) */
 		jump_rel(atom_offset(srav_path, aligned_done)),                             /* b → aligned_done (LZCR >= 24 path) */
-		BdSlot_ shift_lleft_var(r.v_sqr_aligned, r.v_sqr_aligned, r.btarget),
+		BdSlot_ shift_lleft_var(r.v_sqr_aligned, r.v_sqr_aligned, r.align_delta),
 		atom_label(srav_path)
 			li_s( r.shift_count, 24),
-			sub_s(r.shift_count, r.shift_count, r.lzcr),
+			sub_s(r.shift_count, r.shift_count, r.lzcr_even),
 			shift_aright_var(r.v_sqr_aligned, r.v_sqr_aligned, r.shift_count),
 	atom_label(aligned_done)
-		add_si(     r.v_sqr_aligned, r.v_sqr_aligned, -64),
+		add_si(     r.sqrtbl_byte_offset, r.v_sqr_aligned,    -64),
-		shift_lleft(r.v_sqr_aligned, r.v_sqr_aligned, 1),
+		shift_lleft(r.sqrtbl_byte_offset, r.sqrtbl_byte_offset, 1),
-		mac_load_word_imm(r.sqrtbl_index, & gte_normalize_sqr_tbl), add_u_self(r.sqrtbl_index, r.v_sqr_aligned),
+		mac_load_word_imm(r.sqrtbl_lookup, & gte_normalize_sqr_tbl), add_u_self(r.sqrtbl_lookup, r.sqrtbl_byte_offset),
-		load_half(r.inv_len, r.sqrtbl_index, 0),
+		load_half(r.inv_len, r.sqrtbl_lookup, 0),
 		LdSlot_ nop,
 
 	mac_gte_general_purpose_interopolation(r.inv_len,
 		r.src.x, r.src.y, r.src.z,
 		r.res.x, r.res.y, r.res.z,
 		GteDelay_ load_word(R_AtomJmp, R_TapePtr, 0), LdSlot_   // ac_yield: word 1
-		GteDelay_ add_ui_self(         R_TapePtr, S_(MipsCode)) // ac_yield: word 2
+		GteDelay_ add_ui_self(         R_TapePtr, S_(MipsCode)) // ac_yield: word 
 	),
 	mac_shift_aright_var_v3s4_self(r.res, r.srav_shift),
 	mac_store_v3s4(r.res, r.dst_ptr, 0),

code/duffle/memory.h

@@ -5,7 +5,7 @@
 
 #define MEM_ALIGNMENT_DEFAULT  4
 
-#define assert_bounds(point, start, end) for(;0;){ \
+#define assert_bounds(point, start, end) do{ \
 	assert((start) <= (point)); \
 	assert((point) <= (end));   \
 } while(0)

code/duffle/tape.h

@@ -13,56 +13,32 @@
 
 #pragma region Tape Drive
 /* -----------------------------------------------------------------------------------------------------------
- *  TAPE DRIVE ABI
+ *  THREADED ATOMS - TAPE EXECUTION & ABI
+ *  _________
+ * |   ___   |         
+ * |  o___o  |              ,-----<-----.
+ * |__/___\__|              V           ^
+ *          \_[Enter]_[A]->[A]->[A]->[A(B)]->[A]->[Exit]
  * -----------------------------------------------------------------------------------------------------------
- * Note(Ed): One of the main purposes of this codebase is to help me learn this, 
+ * This ABI and its associated legos were directly inspired by researching the work of Timothy Lottes and
- * as such the information below may not* be entirely realized or finalized conceptually.
+ * Onat Türkçüoğlu; Forth, threaded code system, and various other people or programming techniques.
- * -----------------------------------------------------------------------------------------------------------
+ * 
- * This ABI and its associated legos were directly inspired by researching the work of 
+ * The setup is simple: 
- * Timothy Lottes and Onat Türkçüoğlu; along with many others. It's the simplest bootstrap of a 
+ * A tape is a linear stream containing addresses of directly executable native-code fragments ("Atoms").
- * directly executed chain of assemby arrays (Atoms) that terminate with a yield sequence to the next atom.
+ * Most atoms terminate in a small yield sequence which loads the next atom address from the tape.
- * These eventually lead to a terminal atom for the tape which is defined below as "tape_exit".
+ * It's a runtime composed of directly executed native machine-code sequences (Atoms) that usually terminate 
+ * in a yield sequence to the next atom. These eventually lead to a terminal atom for the tape
+ * which is defined below as "tape_exit". Traditionally referred to as Direct Threaded Execution.
  * 
  * It 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 within atoms or between atoms.
+ * The tape itself does not have have any branching behavior.
- * Branching nearly is always downstream. Automatic stack usage is non-existent.
+ * Branches, loops, skips, or other control-flow policies must be implemented explicitly by atoms.
- * Push/Pop, FIFO, or Arena/Bump data structures are used by atoms explicitly.
+ * Push/Pop, FIFO, or Arena/Bump data structures are utilized by atoms explicitly.
- * In it's current form with the C11 macro DSL, the user also has fullfill manual register allocation per atom.
+ * There is no implicit call-stack, return stack, or per-atom stack-frame.
- * 
+ * The user must also explictly handle register allocation per atom (by default). 
- * One of the remarkable things about utilizing this ABI is its essentially interopable with CPUs, GPUs, FPGA, 
+ * However they could procedurally automate it using metaprogramming functionality.
- * 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 for eventually expanding this ABI's paradigm 
- * 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 cannot ignore excessive argument shuffle across workload or
- * waves and thier phases. Crossing ABI boundaries to other runtimes that do has obviouss penalties.
- * 
- * Learning data-oriented code becomes a natural progression. Your not fighting a stack-based procedural 
- * paradigm that wants to argument shuffle. There is no ambiguity due to the lack of constraints, for example,
- * on how the user may "call" a procedure in traditional random dispatch runtimes. The user does have to
- * hammer down "rules" or patterns for massaging the compiler to dissolve those call frames; just to get 
- * the asesmbly into its desired form. The form is obvious, and once the user gets to author these 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 like a color forth, or maybe something more familar like an immediate mode library 
- * for various systems such as GUIs. 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 need pretty ascii diagrams and proper guides, articles, etc.
- * -----------------------------------------------------------------------------------------------------------
- * For now this ideation has just started functioning. 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 provides 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 either an editor in-emulator or on the actual machine itself. Assembly is tedius,
- * but I think this codebase most likely has a pretty ergonomic flavor worst case...
  * */
 /* Register Allocation Info */
 enum {
@@ -242,7 +218,6 @@ FI_ void tape_run(Tape tape) { C_(TapeEntryFn*, tape_enter)(tape.ptr); }
 // Procedural authoring of tapes:
 typedef Relative_(FArena) Struct_(TapeBuilder) { U4 ptr; U4 capacity; U4 used; };
 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){ u4_(mem.ptr), mem.len, 0 }; }  /* capacity in elements (matches used units) */
 
 FI_ void tb_emit(TapeBuilder* tb, MipsAtom* atom) { u4_r(tb->ptr)[tb->used] = u4_(atom); ++ tb->used; }
@@ -273,6 +248,7 @@ FI_ void tb_scope_run_end(TapeBuilder* tb) { tb_emit(tb,tape_exit); tape_run(tb_
  * ---------------------------------------------------------------------------*/
 
 // The 'Yield' sequence for Tape Atoms (mac_yield). 
+// In Forth this is considered the "NEXT" mechanism.
 
 atom_dbg_skip MipsAtomComp_(ac_yield) {
 	load_word(R_AtomJmp, R_TapePtr, 0), LdSlot_
@@ -359,9 +335,7 @@ internal Reg const regfile_alloc_order[] = {
 typedef Struct_(RegFile) { A2_U2 GPR; };
 #define regfile(pin_mask) {.GPR={u4_lo(pin_mask), u4_hi(pin_mask)} }
 FI_ void regfile_init(RegFile_R rf) {
-	/* pack the 32-bit ABI mask into the two U2s */
+	rf->GPR[0] = u4_lo(regfile_abi_mask); rf->GPR[1] = u4_hi(regfile_abi_mask);
-	rf->GPR[0] = u4_lo(regfile_abi_mask);
-	rf->GPR[1] = u4_hi(regfile_abi_mask);
 }
 FI_ RegFile regfile_make(void) { RegFile rf; regfile_init(& rf); return rf; }
 
@@ -405,16 +379,19 @@ FI_ void regfile_free_reg(RegFile_R rf, Reg r_id) {
 	RegFile_RInfo info = regfile_rinfo(rf->GPR, r_id);
 	info.section[0] &= ~info.mask;
 }
-FI_ void regfile_reset(RegFile_R rf) {
+FI_ void regfile_reset        (RegFile_R rf)          { rf->GPR[0] = u4_lo(regfile_abi_mask); rf->GPR[1] = u4_hi(regfile_abi_mask); }
-	rf->GPR[0] = u4_lo(regfile_abi_mask);
+FI_ void regfile_reset_to_mask(RegFile_R rf, U4 mask) { rf->GPR[0] = u4_lo(mask);             rf->GPR[1] = u4_hi(mask); }
-	rf->GPR[1] = u4_hi(regfile_abi_mask);
-}
-FI_ void regfile_reset_to_mask(RegFile_R rf, U4 mask) {
-	rf->GPR[0] = u4_lo(mask);
-	rf->GPR[1] = u4_hi(mask);
-}
 #pragma endregion RegFileArena (Register File Allocator)
 
+#pragma region Mips Atom Components (Procedures)
+
+// For doing direct-chaining of "atoms or fragments".
+FI_ Slice_MipsCode ac_yield_to(AtomBuilder_R ab, Reg code_ptr) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	jump_reg(code_ptr), BdSlot_ nop,
+})
+
+#pragma endregion Mips Atom Components (Procedures)
+
 #pragma region Mips Atom Procs
 /* RegUse structs are a convention to organize register allocations for a mips atom procedure.
 	Unlike the usual enum-based declarations, they provide a namespaced scope and have view types via union declarations. */

code/hello_camera/hello_camera.atom.c

@@ -11,7 +11,7 @@
 #	include "duffle/word_count.metadata.h"
 #	include "duffle/psyq.h"
 #	include "duffle/math.atom.h"
-#	include "duffle/gte.atom.h"
+#	include "duffle/gte.atom.c"
 #	include "duffle/mips.atom.c"
 #	include "duffle/gp.atom.c"
 #	include "duffle/psyq.atom.c"

code/hello_camera/hello_camera.c

@@ -34,7 +34,7 @@
 #include "duffle/pad.c"
 #include "duffle/math.atom.h"
 #include "duffle/mips.atom.c"
-#include "duffle/gte.atom.h"
+#include "duffle/gte.atom.c"
 #include "duffle/gp.atom.c"
 #include "duffle/pad.atom.c"
 #include "duffle/psyq.atom.c"
@@ -292,6 +292,8 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		gte_matrix_set_rotation   (& smem.tform_view);
 		gte_matrix_set_translation(& smem.tform_view);
 
+		// 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.
 		U1* prim_base   = u1_r(pa->buf[smem.active_buf_id]);
 		U1* prim_cursor = prim_base + pa->used;
 		tb.used = 0; tb_scope_run(& tb) {
@@ -317,21 +319,16 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 		mt3s2s4_rotation   (& smem.floor.rot,   & smem.tform_world);
 		mt3s2s4_translation(& smem.tform_world, & smem.floor.pos);
 		mt3s2s4_scale      (& smem.tform_world, & smem.floor.scale);
-
 		// Combine world and look_at matrix.
 		gte_comp_coord_m3s2(& smem.cam.look_at, & smem.tform_world, & smem.tform_view);
-
 		gte_matrix_set_rotation   (& smem.tform_view);
 		gte_matrix_set_translation(& smem.tform_view);
 
-		U1_R prim_base   = u1_r(pa->buf[smem.active_buf_id]);
-		U1_R 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.
-
+		U1_R prim_base   = u1_r(pa->buf[smem.active_buf_id]);
-		// Prepare the tape. (Push protocol to tape)
+		U1_R prim_cursor = prim_base + pa->used;
-		tb.used = 0; tb_scope_run(& tb) {
+		tb.used = 0; tb_scope_run(& tb) { // Prepare the tape. (Push protocol to tape)
 			tb_emit(& tb, rbind_floor_f3_face); tb_bind_(& tb, Binds_FloorTri,
 				.prim_cursor = prim_cursor,
 				.face_cursor = smem.floor.faces,