nomen-lang 0.3.0 → 0.5.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

@@ -76,8 +76,8 @@ pub struct Arena<T> {
 			self.generations.grow_int(index + 1)
 			self.generations.store_int(index, 0)
 		}
-		self.values.grow_T(index + 1)
-		self.values.store_T(index, value)
+		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)
@@ -92,7 +92,7 @@ pub struct Arena<T> {
 		if !self.is_valid(handle) {
 			panic("arena: free of a stale handle")
 		}
-		var T discarded = self.values.move_T(handle.index)
+		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)
@@ -124,7 +124,7 @@ pub struct Arena<T> {
 		if !self.is_valid(handle) {
 			panic("arena: get of a stale handle")
 		}
-		return self.values.load_T(handle.index)
+		return self.values.load(handle.index)
 	}
 
 	/**
@@ -134,7 +134,7 @@ pub struct Arena<T> {
 		if !self.is_valid(handle) {
 			return fallback
 		}
-		return self.values.load_T(handle.index)
+		return self.values.load(handle.index)
 	}
 
 	/**
@@ -144,7 +144,7 @@ pub struct Arena<T> {
 		if !self.is_valid(handle) {
 			panic("arena: set through a stale handle")
 		}
-		self.values.replace_T(handle.index, value)
+		self.values.replace(handle.index, value)
 	}
 
 	/**
@@ -161,6 +161,6 @@ pub struct Arena<T> {
 	 * 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_T(index)
+		return self.values.load(index)
 	}
 }

package/core/System/Awaitable.nm

@@ -0,0 +1,21 @@
+// Awaitable — the consumption side of the async model (ASYNC.md,
+// "Awaitable trait"). Park-flavored by design: `wait` MAY park the current
+// execution context (inside a fiber it parks the fiber and frees its
+// worker; on a raw thread it blocks). A Rust-style poll/Waker trait is
+// deliberately rejected — it would smuggle the state-machine transform back
+// in through the trait definition.
+//
+// `Task<T>` is the conformer: `Thread(...).start()` and `Fiber(...).start()`
+// both yield one, so a generic helper taking `Awaitable` waits on either.
+// The trait is deliberately NOT the place for must-start semantics —
+// start-optional lifecycles are legitimate for user primitives; must-start
+// is a per-struct `#destroy` contract (see Thread.nm / Fiber.nm and
+// ASYNC.md).
+
+/**
+ * Something whose completion can be waited on (may park the current context)
+ **/
+pub trait Awaitable {
+	func wait = (ref self) {
+	}
+}

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,7 +20,6 @@ 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
@@ -528,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) {

package/core/System/Buffer.nm

@@ -1,25 +1,35 @@
 // Buffer<T>: a flat buffer of value slots of type T. The value counterpart to
 // ClassBuffer<T>: no per-element freeing, store_int unconstrained. When T is a
 // class, the monomorphizer rewrites a Buffer<T> field to ClassBuffer<T>.
+//
+// Public API is the size-aware family (`alloc`/`grow`/`load`/`replace`/
+// `move`/`modify`/`shift`/`slice` plus the readonly `cap`). `replace` is the
+// public write — it reclaims the displaced element, so it is correct on both
+// fresh and occupied slots. `store` (which assumes a fresh slot and leaks on
+// overwrite), `zero`, the fixed-width `*_u32`/`*_int`/`*_float` primitives,
+// and the raw `data` pointer are `internal` and reserved for the System
+// containers.
 
 /**
  * A flat, low-level buffer of value slots of type T — the backing store for arrays and collections
  **/
 pub struct Buffer<T> {
-	var uint64 data = 0
-	var cap = 0
+	internal var uint64 data = 0
+	// Publicly readable capacity (`i < self.cap` guards every accessor), but
+	// only Buffer's own methods may grow it — `readonly`.
+	readonly cap = 0
 
 	// Allocation / sizing primitives are `unsafe` Nomen single-sourced for
 	// both backends. They run once per container op (never per element), so
 	// the aarch64 inline-method ABI cost that keeps the per-limb load/store
 	// primitives raw (see BigInt.nm) doesn't apply here.
-	func alloc = (ref self, int size, out int: out >= size) {
+	internal func alloc_u32 = (ref self, int size, out int: out >= size) {
 		self.cap = size
 		self.data = calloc(size, 4)
 		return self.cap
 	}
 
-	func grow = (ref self, int needed, out int: out >= needed) {
+	internal func grow_u32 = (ref self, int needed, out int: out >= needed) {
 		if self.cap >= needed {
 			return self.cap
 		}
@@ -34,11 +44,11 @@ pub struct Buffer<T> {
 		return self.cap
 	}
 
-	func zero = (ref self, int len) {
+	internal func zero_u32 = (ref self, int len) {
 		memset(self.data, 0, len * 4)
 	}
 
-	inline func load = (self, int i: i >= 0 && i < self.cap, out uint32) {
+	internal inline func load_u32 = (self, int i: i >= 0 && i < self.cap, out uint32) {
 		```
 		#arch: c
 		return ((unsigned int*)(unsigned long long)self->data)[i];
@@ -53,7 +63,7 @@ pub struct Buffer<T> {
 		```
 	}
 
-	inline func store = (ref self, int i: i >= 0 && i < self.cap, uint32 val) {
+	internal inline func store_u32 = (ref self, int i: i >= 0 && i < self.cap, uint32 val) {
 		```
 		#arch: c
 		((unsigned int*)(unsigned long long)self->data)[i] = val;
@@ -67,7 +77,7 @@ pub struct Buffer<T> {
 		```
 	}
 
-	inline func store_or = (ref self, int i: i >= 0 && i < self.cap, uint32 val) {
+	internal inline func store_or_u32 = (ref self, int i: i >= 0 && i < self.cap, uint32 val) {
 		```
 		#arch: c
 		((unsigned int*)(unsigned long long)self->data)[i] |= val;
@@ -83,13 +93,13 @@ pub struct Buffer<T> {
 		```
 	}
 
-	func alloc_int = (ref self, int size, out int: out >= size) {
+	internal func alloc_int = (ref self, int size, out int: out >= size) {
 		self.cap = size
 		self.data = calloc(size, 8)
 		return self.cap
 	}
 
-	func grow_int = (ref self, int needed, out int: out >= needed) {
+	internal func grow_int = (ref self, int needed, out int: out >= needed) {
 		if self.cap >= needed {
 			return self.cap
 		}
@@ -104,7 +114,7 @@ pub struct Buffer<T> {
 		return self.cap
 	}
 
-	inline func load_int = (self, int i: i >= 0 && i < self.cap, out int) {
+	internal inline func load_int = (self, int i: i >= 0 && i < self.cap, out int) {
 		```
 		#arch: c
 		return ((long*)(unsigned long long)self->data)[i];
@@ -118,7 +128,7 @@ pub struct Buffer<T> {
 		```
 	}
 
-	inline func store_int = (ref self, int i: i >= 0 && i < self.cap, int val) {
+	internal inline func store_int = (ref self, int i: i >= 0 && i < self.cap, int val) {
 		```
 		#arch: c
 		((long*)(unsigned long long)self->data)[i] = val;
@@ -136,7 +146,7 @@ pub struct Buffer<T> {
 	// the ownership-extracting primitive (used by e.g. List.pop) — unlike
 	// load_int (a borrow read), it relinquishes the slot so the buffer no
 	// longer owns the value.
-	inline func move_int = (ref self, int i: i >= 0 && i < self.cap, out int) {
+	internal inline func move_int = (ref self, int i: i >= 0 && i < self.cap, out int) {
 		```
 		#arch: c
 		long *slots = (long*)(unsigned long long)self->data;
@@ -157,7 +167,7 @@ pub struct Buffer<T> {
 	// Store into a slot, freeing the previous value when the buffer holds
 	// owned class pointers (has_class_refs). For non-class buffers this is a
 	// plain store, so it is safe to use anywhere store_int would be.
-	inline func replace_int = (ref self, int i: i >= 0 && i < self.cap, int val) {
+	internal inline func replace_int = (ref self, int i: i >= 0 && i < self.cap, int val) {
 		```
 		#arch: c
 		((long*)(unsigned long long)self->data)[i] = val;
@@ -171,7 +181,7 @@ pub struct Buffer<T> {
 		```
 	}
 
-	inline func zero_int = (ref self, int len) {
+	internal inline func zero_int = (ref self, int len) {
 		memset(self.data, 0, len * 8)
 	}
 
@@ -180,13 +190,13 @@ pub struct Buffer<T> {
 	// correctly. Classes route to ClassBuffer<T> (per-element destroy), so T
 	// reaching here is always a value type (primitive or struct).
 
-	func alloc_T = (ref self, int size, out int: out >= size) {
+	func alloc = (ref self, int size, out int: out >= size) {
 		self.cap = size
 		self.data = calloc(size, T_SIZE)
 		return self.cap
 	}
 
-	func grow_T = (ref self, int needed, out int: out >= needed) {
+	func grow = (ref self, int needed, out int: out >= needed) {
 		if self.cap >= needed {
 			return self.cap
 		}
@@ -205,7 +215,7 @@ pub struct Buffer<T> {
 	// call sites — the load/store pair behind every container `.at`/`set` is
 	// the hottest path in data-heavy code, and the naked-inline path keeps it
 	// to a handful of instructions with no call overhead.
-	inline func load_T = (self, int i: i >= 0 && i < self.cap, out T) {
+	inline func load = (self, int i: i >= 0 && i < self.cap, out T) {
 		```
 		#arch: c
 		return ((T*)(unsigned long long)self->data)[i];
@@ -249,12 +259,14 @@ pub struct Buffer<T> {
 	}
 
 	// Store `val` into slot `i`, which MUST be fresh (calloc'd, or zeroed by
-	// move_T). For an owning T (string, or a struct with string fields) the
+	// move). For an owning T (string, or a struct with string fields) the
 	// specialised body deep-copies the incoming value but does NOT free the
-	// slot's previous occupant — a second `store_T` at an occupied index
-	// leaks it. To overwrite a live slot use replace_T (frees the displaced
+	// slot's previous occupant — a second `store` at an occupied index
+	// leaks it. To overwrite a live slot use replace (frees the displaced
 	// value) — this is the primitive every container's `set` uses.
-	inline func store_T = (ref self, int i: i >= 0 && i < self.cap, T val) {
+	// Internal: assumes a FRESH slot (see the contract comment). The public
+	// write is `replace`, which is correct on fresh and occupied slots alike.
+	internal inline func store = (ref self, int i: i >= 0 && i < self.cap, T val) {
 		```
 		#arch: c
 		((T*)(unsigned long long)self->data)[i] = val;
@@ -300,7 +312,7 @@ pub struct Buffer<T> {
 	// the result is treated as OWNED by the borrow checker — the slot is
 	// relinquished, so the caller is the sole remaining owner. The value
 	// counterpart of ClassBuffer.move_int — used by List.pop for any value T.
-	inline func move_T = (ref self, int i: i >= 0 && i < self.cap, move out T) {
+	inline func move = (ref self, int i: i >= 0 && i < self.cap, move out T) {
 		```
 		#arch: c
 		T* _slots = (T*)(unsigned long long)self->data;
@@ -356,14 +368,108 @@ pub struct Buffer<T> {
 		```
 	}
 
+	// Apply `f` to slot `i` in place: the safe way to do a load→modify→store
+	// round-trip on a live slot. `f` receives the current value as a borrow
+	// (by value) and returns the replacement; the primitive itself handles
+	// ownership — the displaced value is freed, and a returned field that
+	// aliases the slot's own copy (the round-trip case) is kept, not freed or
+	// re-copied. Unlike store this never leaks on overwrite, and unlike
+	// replace it is safe to derive the new value from the old one. The
+	// returned struct's owning fields must be fresh, null, or identical to
+	// the corresponding input fields (no cross-field aliasing). For owning
+	// elements (string / structs with string fields) the build phase replaces
+	// this body with a specialized one (see owning_buffer_specialize.ts);
+	// this raw form is correct for trivially-copyable elements only. NOT
+	// `inline`: the body calls through the fn pointer, so splicing the raw
+	// block into a caller would bypass the per-element specializations.
+	func modify = (ref self, int i: i >= 0 && i < self.cap, func (T, out T) f) {
+		```
+		#arch: c
+		((T*)(unsigned long long)self->data)[i] = ((T (*)(void *, T))f->code)(f->env, ((T*)(unsigned long long)self->data)[i]);
+		```
+		```
+		#arch: aarch64
+		// x19 = self, x1 = i, x2 = f (a closure descriptor: { code, env,
+		// owned } — the call loads both words and passes env first, shifting
+		// the value argument to x1). Scalar elements round-trip through x1
+		// (width-matched); larger trivially-copyable structs pass the slot
+		// address and an sret pointer (x8) — the fn writes the replacement
+		// straight into the slot from a stack-stage copy of the old value.
+		stp x20, x21, [sp, #-16]!
+		stp x22, x23, [sp, #-16]!
+		stp x24, x25, [sp, #-16]!
+		mov x22, x2
+		ldr x9, [x19, #8]
+		mov x3, #T_SIZE
+		madd x20, x1, x3, xzr
+		add x20, x20, x9
+		ldr x24, [x22]
+		ldr x0, [x22, #8]
+		cmp x3, #8
+		b.gt .Lbuffer_modify_T_big
+		cmp x3, #1
+		b.eq .Lbuffer_modify_T_ld1
+		cmp x3, #2
+		b.eq .Lbuffer_modify_T_ld2
+		cmp x3, #4
+		b.eq .Lbuffer_modify_T_ld4
+		ldr x1, [x20]
+		b .Lbuffer_modify_T_call
+		.Lbuffer_modify_T_ld1:
+		ldrb w1, [x20]
+		b .Lbuffer_modify_T_call
+		.Lbuffer_modify_T_ld2:
+		ldrh w1, [x20]
+		b .Lbuffer_modify_T_call
+		.Lbuffer_modify_T_ld4:
+		ldr w1, [x20]
+		.Lbuffer_modify_T_call:
+		blr x24
+		cmp x3, #1
+		b.eq .Lbuffer_modify_T_st1
+		cmp x3, #2
+		b.eq .Lbuffer_modify_T_st2
+		cmp x3, #4
+		b.eq .Lbuffer_modify_T_st4
+		str x0, [x20]
+		b .Lbuffer_modify_T_end
+		.Lbuffer_modify_T_st1:
+		strb w0, [x20]
+		b .Lbuffer_modify_T_end
+		.Lbuffer_modify_T_st2:
+		strh w0, [x20]
+		b .Lbuffer_modify_T_end
+		.Lbuffer_modify_T_st4:
+		str w0, [x20]
+		b .Lbuffer_modify_T_end
+		.Lbuffer_modify_T_big:
+		add x23, x3, #15
+		bic x23, x23, #15
+		sub sp, sp, x23
+		mov x0, sp
+		mov x1, x20
+		mov x2, x3
+		bl _memcpy
+		ldr x0, [x22, #8]
+		mov x1, sp
+		mov x8, x20
+		blr x24
+		add sp, sp, x23
+		.Lbuffer_modify_T_end:
+		ldp x24, x25, [sp], #16
+		ldp x22, x23, [sp], #16
+		ldp x20, x21, [sp], #16
+		```
+	}
+
 	// Store into a T_SIZE-sized slot, overwriting the previous value. For
 	// trivially-destructible value structs this is a plain overwrite. For
 	// owning value structs (with string fields), the build phase replaces this
 	// body with a specialised version that calls T_destroy on the old slot
 	// value, then deep-copies (strdup per string field). See
-	// owning_buffer_specialize.ts (both backends). ClassBuffer.replace_T
+	// owning_buffer_specialize.ts (both backends). ClassBuffer.replace
 	// destroys+frees class slots soundly.
-	inline func replace_T = (ref self, int i: i >= 0 && i < self.cap, T val) {
+	inline func replace = (ref self, int i: i >= 0 && i < self.cap, T val) {
 		```
 		#arch: c
 		((T*)(unsigned long long)self->data)[i] = val;
@@ -407,14 +513,14 @@ pub struct Buffer<T> {
 	// Move slot src into slot dst: overwrite dst with src's bytes and zero
 	// src, so exactly ONE slot owns the value afterwards. The
 	// ownership-transferring primitive behind backward-shift deletion
-	// (Map/Set.remove) — unlike store_T, which gives the slot its own deep
+	// (Map/Set.remove) — unlike store, which gives the slot its own deep
 	// copy and leaves the source slot intact, a shift transfers the source's
 	// heap pointers wholesale. For owning elements (string / value structs
 	// with string fields) the build replaces this body with a specialized
 	// version that also reclaims dst's previous value first (see
 	// owning_buffer_specialize.ts); this raw form is correct for
 	// trivially-destructible elements only.
-	inline func shift_T = (ref self, int dst: dst >= 0 && dst < self.cap, int src: src >= 0 && src < self.cap) {
+	inline func shift = (ref self, int dst: dst >= 0 && dst < self.cap, int src: src >= 0 && src < self.cap) {
 		```
 		#arch: c
 		T* _slots = (T*)(unsigned long long)self->data;
@@ -481,7 +587,7 @@ pub struct Buffer<T> {
 	// self's scope and is invalidated if self is reassigned. This is the single
 	// primitive every other slice (Array<T>, List<T>, user containers) builds
 	// on — higher layers just `return self.items.slice(start, end)`.
-	func slice = (self, int start: start >= 0, int end: end >= start, out view T) {
+	func slice = (self, int start: start >= 0, int end: end >= start && end <= self.cap, out view T) {
 		```
 		#arch: c
 		nomen_view _r;
@@ -500,11 +606,12 @@ pub struct Buffer<T> {
 		```
 	}
 
-	inline func zero_T = (ref self, int len) {
+	// Internal: zeroes slots without reclaiming owning elements.
+	internal inline func zero = (ref self, int len) {
 		memset(self.data, 0, len * T_SIZE)
 	}
 
-	inline func store_or_int = (ref self, int i: i >= 0 && i < self.cap, int val) {
+	internal inline func store_or_int = (ref self, int i: i >= 0 && i < self.cap, int val) {
 		```
 		#arch: c
 		((long*)(unsigned long long)self->data)[i] |= val;
@@ -520,13 +627,13 @@ pub struct Buffer<T> {
 		```
 	}
 
-	func alloc_float = (ref self, int size, out int: out >= size) {
+	internal func alloc_float = (ref self, int size, out int: out >= size) {
 		self.cap = size
 		self.data = calloc(size, 8)
 		return self.cap
 	}
 
-	inline func load_float = (self, int i: i >= 0 && i < self.cap, out float) {
+	internal inline func load_float = (self, int i: i >= 0 && i < self.cap, out float) {
 		```
 		#arch: c
 		return ((double*)(unsigned long long)self->data)[i];
@@ -540,7 +647,7 @@ pub struct Buffer<T> {
 		```
 	}
 
-	inline func store_float = (ref self, int i: i >= 0 && i < self.cap, float val) {
+	internal inline func store_float = (ref self, int i: i >= 0 && i < self.cap, float val) {
 		```
 		#arch: c
 		((double*)(unsigned long long)self->data)[i] = val;