nomen-lang 0.2.3 → 0.4.0

package/NOMEN_AGENTS.md

@@ -128,7 +128,13 @@ const y = x + 1     // Error: 'x' is null
 
 ### Visibility
 
-`pub` exports; everything else is module-private. There is no `private` keyword.
+`pub` exports. `internal` is visible only within the declaring library/module
+(the System library uses it to hide implementation details). Everything else is
+private to its declaring scope.
+
+`readonly` is a field-write modifier, not a visibility: the field reads at its
+declared visibility but can only be assigned inside its declaring struct/class
+(and its `extend`s). `const` fields are immutable everywhere.
 
 ### Imports
 

package/core/System/Arena.nm

@@ -0,0 +1,166 @@
+// Arena<T>: a generational arena — one owner of every slot, with cheap
+// copyable handles (`ArenaRef<T>`) instead of borrows. This is the single-ownership
+// answer to "many places need to refer to the same node": the arena owns the
+// values, everyone else holds `ArenaRef<T>` (a plain { index, generation } value
+// that copies freely and never dangles undetected).
+//
+// Why not `List<T>` + raw `int` indices? An index silently aliases a recycled
+// slot after a removal — the classic stale-index bug. An `ArenaRef<T>` carries the
+// slot's generation, bumped on every `free`; a stale handle fails the
+// generation check and `get` panics (`is_valid` / `get_or` test it without
+// trapping), so use-after-free is DETECTED instead of silently reading
+// another node.
+//
+// The arena is the sole owner: `free` relinquishes the slot's value (moved out
+// and reclaimed by the ordinary ownership machinery) and bumps the generation;
+// the arena's own #destroy reclaims every still-live slot at scope exit.
+
+/**
+ * A copyable, non-owning handle to an `Arena<T>` slot. The generation makes a
+ * reused slot distinguishable from the one this handle was issued for.
+ **/
+pub struct ArenaRef<T> {
+	var int index = -1
+	var int generation = -1
+
+	pub func is_null = (self, out bool) {
+		return self.index < 0
+	}
+}
+
+/**
+ * A generational arena: one owner of a set of `T` values, addressed by
+ * copyable `ArenaRef<T>` handles.
+ **/
+pub struct Arena<T> {
+	// Slot payloads. T = value struct/primitive routes to Buffer<T>; T =
+	// class/trait routes to ClassBuffer<T> (monomorphize rewrites the field),
+	// so slot ownership follows the usual element rules.
+	var Buffer<T> values = Buffer<T>()
+	// Per-slot generation, bumped on every free. Slots are calloc'd, so a
+	// fresh slot's generation is 0.
+	var Buffer<int> generations = Buffer<int>()
+	// Freed slot indices available for reuse (LIFO free list). A raw Buffer
+	// plus an explicit count: a `List<int>` field would need its own
+	// monomorphization from inside a generic struct body.
+	var Buffer<int> free_indices = Buffer<int>()
+	var int free_count = 0
+	// High-water mark: every index < count has a slot (live or free).
+	var int count = 0
+
+	/**
+	 * A fresh arena with no slots.
+	 **/
+	pub func #init = (ref self) {
+		self.values = Buffer<T>()
+		self.generations = Buffer<int>()
+		self.free_indices = Buffer<int>()
+		self.free_count = 0
+		self.count = 0
+	}
+
+	/**
+	 * Store `value` in a slot (reusing a freed slot when one is available) and
+	 * return a handle to it.
+	 **/
+	pub func alloc = (ref self, move T value, out ArenaRef<T>) {
+		var int index = -1
+		if self.free_count > 0 {
+			// Reuse a freed slot. Its generation was already bumped by `free`,
+			// so stale handles to it are already invalid.
+			self.free_count = self.free_count - 1
+			index = self.free_indices.load_int(self.free_count)
+		} else {
+			index = self.count
+			self.count = index + 1
+			self.generations.grow_int(index + 1)
+			self.generations.store_int(index, 0)
+		}
+		self.values.grow(index + 1)
+		self.values.store(index, value)
+		var ArenaRef<T> handle = ArenaRef<T>()
+		handle.index = index
+		handle.generation = self.generations.load_int(index)
+		return handle
+	}
+
+	/**
+	 * Relinquish the slot `handle` points at (its value is reclaimed), bumping the
+	 * generation so every outstanding handle to that slot becomes stale.
+	 **/
+	pub func free = (ref self, ArenaRef<T> handle) {
+		if !self.is_valid(handle) {
+			panic("arena: free of a stale handle")
+		}
+		var T discarded = self.values.move(handle.index)
+		self.generations.store_int(handle.index, handle.generation + 1)
+		self.free_indices.grow_int(self.free_count + 1)
+		self.free_indices.store_int(self.free_count, handle.index)
+		self.free_count = self.free_count + 1
+	}
+
+	/**
+	 * The current generation of a slot index (raw; for `ArenaRef` bookkeeping).
+	 **/
+	pub func generation_of = (self, int index: index >= 0 && index < self.count, out int) {
+		return self.generations.load_int(index)
+	}
+
+	/**
+	 * Whether `handle` still names a live slot.
+	 **/
+	pub func is_valid = (self, ArenaRef<T> handle, out bool) {
+		if handle.index < 0 || handle.index >= self.count {
+			return false
+		}
+		return self.generations.load_int(handle.index) == handle.generation
+	}
+
+	/**
+	 * The value `handle` names. Panics on a stale handle (use-after-free is a
+	 * bug, not a case — use `is_valid` / `get_or` when absence is expected).
+	 **/
+	pub func get = (self, ArenaRef<T> handle, out T) {
+		if !self.is_valid(handle) {
+			panic("arena: get of a stale handle")
+		}
+		return self.values.load(handle.index)
+	}
+
+	/**
+	 * The value `handle` names, or `fallback` when the handle is stale.
+	 **/
+	pub func get_or = (self, ArenaRef<T> handle, T fallback, out T) {
+		if !self.is_valid(handle) {
+			return fallback
+		}
+		return self.values.load(handle.index)
+	}
+
+	/**
+	 * Replace the value `handle` names (same slot, same handle).
+	 **/
+	pub func set = (ref self, ArenaRef<T> handle, move T value) {
+		if !self.is_valid(handle) {
+			panic("arena: set through a stale handle")
+		}
+		self.values.replace(handle.index, value)
+	}
+
+	/**
+	 * The number of slots ever allocated (live + freed). Indices `0 .. count()`
+	 * can be walked with `get_index`; freed slots return their stale value, so
+	 * prefer `is_valid` + `get` when iterating handles.
+	 **/
+	pub func count_all = (self, out int) {
+		return self.count
+	}
+
+	/**
+	 * Raw slot access by index — for iteration over the index space. Does not
+	 * generation-check; callers own the index bookkeeping.
+	 **/
+	pub func get_index = (self, int index: index >= 0 && index < self.count, out T) {
+		return self.values.load(index)
+	}
+}

package/core/System/Array.nm

@@ -30,134 +30,40 @@ pub struct Array<T>: Viewable {
 		```
 	}
 
+	// Inline-storage element access — `unsafe` Nomen single-sourced for both
+	// backends (docs/CORE_RAW.md roadmap item 2). `self[index]` lowers to the
+	// element base each backend already uses for Array receivers (C skips the
+	// struct header; aarch64's receiver IS the first element).
 	pub inline func at = (self, int index: index >= 0 && index < self.length, out T) {
-		```
-		#arch: c
-		T* _data = (T*)((char*)self + sizeof(*self));
-		return _data[index];
-		```
-		```
-		#arch: aarch64
-		// x19 = self (first elem), x1 = index, x8 = return buf for structs
-		mov x2, #T_SIZE
-		mul x1, x1, x2
-		cmp x2, #8
-		b.eq .L_at_8
-		b.gt .L_at_copy
-		cmp x2, #1
-		b.eq .L_at_1
-		cmp x2, #2
-		b.eq .L_at_2
-		ldr w0, [x19, x1]
-		b .L_at_end
-		.L_at_8:
-		ldr x0, [x19, x1]
-		b .L_at_end
-		.L_at_1:
-		ldrb w0, [x19, x1]
-		b .L_at_end
-		.L_at_2:
-		ldrh w0, [x19, x1]
-		b .L_at_end
-		// Struct element (T_SIZE > 8): copy the slot bytes into the x8
-		// sret buffer and return its address (Buffer.load_T convention).
-		.L_at_copy:
-		mov x0, x8
-		add x1, x19, x1
-		bl _memcpy
-		mov x0, x8
-		.L_at_end:
-		```
+		unsafe {
+			return self[index]
+		}
 	}
 
 	pub func first = (self: self.length > 0, out T) {
-		```
-		#arch: c
-		T* _data = (T*)((char*)self + sizeof(*self));
-		return _data[0];
-		```
-		```
-		#arch: aarch64
-		// x19 = self (first elem), x8 = return buf for structs
-		mov x3, #T_SIZE
-		cmp x3, #8
-		b.eq .L_first_8
-		b.gt .L_first_copy
-		cmp x3, #1
-		b.eq .L_first_1
-		cmp x3, #2
-		b.eq .L_first_2
-		ldr w0, [x19]
-		b .L_first_end
-		.L_first_8:
-		ldr x0, [x19]
-		b .L_first_end
-		.L_first_1:
-		ldrb w0, [x19]
-		b .L_first_end
-		.L_first_2:
-		ldrh w0, [x19]
-		b .L_first_end
-		// Struct element (T_SIZE > 8): copy the first slot's bytes into
-		// the x8 sret buffer and return its address.
-		.L_first_copy:
-		mov x0, x8
-		mov x1, x19
-		mov x2, x3
-		bl _memcpy
-		mov x0, x8
-		.L_first_end:
-		```
+		unsafe {
+			return self[0]
+		}
 	}
 
+	// The string-slot specialization the raw `#if T_NEEDS_STRDUP` blocks used
+	// to express: T_NEEDS_STRDUP is a per-instantiation constant the
+	// monomorphizer substitutes (true for string, false otherwise) and folds,
+	// so each mono body keeps only its arm.
 	pub func set = (ref self, int index: index >= 0 && index < self.length, T value) {
-		```
-		#arch: c
-		T* _data = (T*)((char*)self + sizeof(*self));
-		// T_NEEDS_STRDUP is 1 when T is string (a fat value whose backing
-		// bytes must be heap-copied per slot — otherwise the slot would share
-		// the incoming pointer and auto_free would double-free it). 0 for all
-		// other T (plain assignment).
-		#if T_NEEDS_STRDUP
-			free(_data[index].ptr);
-			_data[index] = nomen_str_dup(value);
-		#else
-			_data[index] = value;
-		#endif
-		```
-		```
-		#arch: aarch64
-		// x19 = self (first elem), x1 = index, x2 = value (address if struct)
-		mov x3, #T_SIZE
-		mul x1, x1, x3
-		cmp x3, #8
-		b.eq .L_set_8
-		b.gt .L_set_copy
-		cmp x3, #1
-		b.eq .L_set_1
-		cmp x3, #2
-		b.eq .L_set_2
-		str w2, [x19, x1]
-		b .L_set_done
-		.L_set_8:
-		str x2, [x19, x1]
-		b .L_set_done
-		.L_set_1:
-		strb w2, [x19, x1]
-		b .L_set_done
-		.L_set_2:
-		strh w2, [x19, x1]
-		b .L_set_done
-		// Struct element (T_SIZE > 8): x2 holds the ADDRESS of the value
-		// bytes — memcpy them into the slot (Buffer.store_T convention).
-		.L_set_copy:
-		mov x0, x19
-		add x0, x0, x1
-		mov x1, x2
-		mov x2, x3
-		bl _memcpy
-		.L_set_done:
-		```
+		unsafe {
+			if T_NEEDS_STRDUP {
+				// T is string: a fat value whose backing bytes must be
+				// heap-copied per slot — otherwise the slot would share the
+				// incoming pointer and auto_free would double-free it. Free
+				// the displaced slot's bytes (no local: a named copy would be
+				// auto-freed too), then store a fresh deep copy.
+				free((self[index] as ptr char) as uint64)
+				self[index] = strdup(value)
+			} else {
+				self[index] = value
+			}
+		}
 	}
 
 	// Bounds-checked accessors — the runtime-checked escape hatch for
@@ -181,46 +87,9 @@ pub struct Array<T>: Viewable {
 	}
 
 	pub func at_end = (self, out T) {
-		```
-		#arch: c
-		T* _data = (T*)((char*)self + sizeof(*self));
-		return _data[self->length - 1];
-		```
-		```
-		#arch: aarch64
-		// x19 = self (first elem), length at [x19 - 8], x8 = return buf for structs
-		ldr x0, [x19, #-8]
-		sub x0, x0, #1
-		mov x1, #T_SIZE
-		mul x0, x0, x1
-		cmp x1, #8
-		b.eq .L_at_end_8
-		b.gt .L_at_end_copy
-		cmp x1, #1
-		b.eq .L_at_end_1
-		cmp x1, #2
-		b.eq .L_at_end_2
-		ldr w0, [x19, x0]
-		b .L_at_end_done
-		.L_at_end_8:
-		ldr x0, [x19, x0]
-		b .L_at_end_done
-		.L_at_end_1:
-		ldrb w0, [x19, x0]
-		b .L_at_end_done
-		.L_at_end_2:
-		ldrh w0, [x19, x0]
-		b .L_at_end_done
-		// Struct element (T_SIZE > 8): x0 = byte offset of the last slot —
-		// copy its bytes into the x8 sret buffer and return its address.
-		.L_at_end_copy:
-		mov x2, x1
-		add x1, x19, x0
-		mov x0, x8
-		bl _memcpy
-		mov x0, x8
-		.L_at_end_done:
-		```
+		unsafe {
+			return self[self.length - 1]
+		}
 	}
 
 	// A non-owning (ptr, len) slice [start, end) over self's inline element

package/core/System/BigInt.nm

@@ -6,7 +6,10 @@ pub struct BigInt {
 	var len = 0
 	var digits = Buffer<int>()
 
-	pub func new = (ref self, int val, out BigInt) {
+	pub func #init = (ref self) {
+	}
+
+	pub func #init = (ref self, int val) {
 		self.sign = 1
 		var int v = val
 		if v < 0 {
@@ -17,68 +20,56 @@ pub struct BigInt {
 		self.digits.zero_int(self.digits.cap)
 		self.digits.store_int(0, v)
 		self.len = 1
-		return self
 	}
 
+	// Per-limb get/set stay raw: they are `inline` and splice into the limb
+	// loops, where the raw bodies are 1-2 instructions with no param
+	// marshalling. The unsafe-Nomen forms measured a 3x pidigits regression
+	// on aarch64 (the inline-method ABI parks self and spills locals per
+	// splice); the C backend (single TU, -O2) showed no difference either
+	// way, so the raw blocks win on single-sourcing grounds being equal.
+	// See docs/CORE_RAW.md "unsafe outcomes".
 	inline func get = (self, int i, out uint64) {
-		```
-		#arch: c
-		return ((unsigned long long*)self->digits.data)[i];
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x0, #32]
-		ldr x0, [x0, x1, lsl #3]
-		```
+		unsafe {
+			var ptr uint64 limbs = self.digits.data as ptr uint64
+			return limbs[i]
+		}
 	}
 
 	inline func set = (ref self, int i, uint64 val) {
-		```
-		#arch: c
-		((unsigned long long*)self->digits.data)[i] = val;
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x19, #32]
-		str x2, [x0, x1, lsl #3]
-		```
+		unsafe {
+			var ptr uint64 limbs = self.digits.data as ptr uint64
+			limbs[i] = val
+		}
 	}
 
 	// Raw data-pointer accessors. The limb loops below hoist `digits.data`
 	// into a local once (before the loop) and index through it via get_at /
 	// set_at, so each limb access is a single strided load/store instead of
 	// re-reading self->digits.data every iteration. ptr is held in a uint64.
+	// All five stay raw: measured on aarch64, even the loop-hoisted
+	// data_ptr as Nomen cost pidigits ~30% (the inline splice perturbs the
+	// whole-function asm plan); the C backend was identical either way.
+	// See docs/CORE_RAW.md "unsafe outcomes".
 	inline func data_ptr = (self, out uint64) {
-		```
-		#arch: c
-		return (unsigned long long)self->digits.data;
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x0, #32]
-		```
+		return self.digits.data
 	}
 
+	// Same story as get/set above: the hoisted-pointer limb accessors stay
+	// raw for the aarch64 splice path. `data_ptr` is called once per loop
+	// (to hoist the slab address), so its Nomen body is free.
 	inline func get_at = (self, uint64 ptr, int i, out uint64) {
-		```
-		#arch: c
-		return ((unsigned long long*)ptr)[i];
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x1, x2, lsl #3]
-		```
+		unsafe {
+			var ptr uint64 limbs = ptr as ptr uint64
+			return limbs[i]
+		}
 	}
 
 	inline func set_at = (ref self, uint64 ptr, int i, uint64 val) {
-		```
-		#arch: c
-		((unsigned long long*)ptr)[i] = val;
-		```
-		```
-		#arch: aarch64
-		str x3, [x1, x2, lsl #3]
-		```
+		unsafe {
+			var ptr uint64 limbs = ptr as ptr uint64
+			limbs[i] = val
+		}
 	}
 
 	func ensure = (ref self, int needed) {
@@ -539,20 +530,8 @@ pub struct BigInt {
 			}
 			self.len = self.len - 1
 		}
-
-		a0.digits.destroy()
-		a1.digits.destroy()
-		b0.digits.destroy()
-		b1.digits.destroy()
-		z0.digits.destroy()
-		z2.digits.destroy()
-		aa.digits.destroy()
-		bb.digits.destroy()
-		z1.digits.destroy()
-		s0.digits.destroy()
-		s1.digits.destroy()
-		s2.digits.destroy()
 	}
+
 	// self = quotient, a = dividend, b = divisor, remainder = remainder
 	// Uses remainder's internal buffer as working space
 	pub func div_to = (ref self, BigInt a, BigInt b, ref BigInt remainder) {