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

@@ -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/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,101 @@ 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] = f(((T*)(unsigned long long)self->data)[i]);
+		```
+		```
+		#arch: aarch64
+		// x19 = self, x1 = i, x2 = f. Scalar elements round-trip through x0
+		// (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]!
+		mov x22, x2
+		ldr x9, [x19, #8]
+		mov x3, #T_SIZE
+		madd x20, x1, x3, xzr
+		add x20, x20, x9
+		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 x0, [x20]
+		b .Lbuffer_modify_T_call
+		.Lbuffer_modify_T_ld1:
+		ldrb w0, [x20]
+		b .Lbuffer_modify_T_call
+		.Lbuffer_modify_T_ld2:
+		ldrh w0, [x20]
+		b .Lbuffer_modify_T_call
+		.Lbuffer_modify_T_ld4:
+		ldr w0, [x20]
+		.Lbuffer_modify_T_call:
+		blr x22
+		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
+		mov x0, sp
+		mov x8, x20
+		blr x22
+		add sp, sp, x23
+		.Lbuffer_modify_T_end:
+		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 +506,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 +580,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 +599,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 +620,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 +640,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;

package/core/System/ClassBuffer.nm

@@ -8,27 +8,28 @@
  * A flat buffer of owned class pointers of type T — the backing store for collections of classes
  **/
 pub struct ClassBuffer<T> {
-	var uint64 data = 0
-	var cap = 0
+	internal var uint64 data = 0
+	// Publicly readable; grown only by ClassBuffer's own methods (`readonly`).
+	readonly cap = 0
 
-	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
 	}
 
-	// Semantic parity with Buffer<T>.alloc_T: generic code (e.g. Map#init's
-	// `self.values.alloc_T(N)`) forwards to either Buffer — where alloc_T is
+	// Semantic parity with Buffer<T>.alloc: generic code (e.g. Map#init's
+	// `self.values.alloc(N)`) forwards to either Buffer — where alloc is
 	// T_SIZE-aware (string slots are 16 bytes) — or this ClassBuffer, whose
 	// slots are always one pointer wide. The compiler routes value-struct
 	// element types to Buffer and class/trait elements to ClassBuffer
 	// (monomorphize's field rewrite), so a call arriving HERE is always
 	// pointer-sized: delegate to alloc_int.
-	func alloc_T = (ref self, int size, out int: out >= size) {
+	func alloc = (ref self, int size, out int: out >= size) {
 		return self.alloc_int(size)
 	}
 
-	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
 		}
@@ -43,7 +44,7 @@ pub struct ClassBuffer<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];
@@ -57,14 +58,14 @@ pub struct ClassBuffer<T> {
 		```
 	}
 
-	// T_SIZE-aware aliases of the _int primitives. ClassBuffer only ever holds
-	// 8-byte class pointers (T_SIZE is 8), so these are behaviorally identical
-	// to their _int counterparts — they exist so List<T> can call a single
-	// uniform `_T` API whether T is a value struct (Buffer) or a class
-	// (ClassBuffer, after the Buffer<T> field is rewritten). Bodies use 8-byte
-	// slots, matching _int.
+	// Generic (T-typed) counterparts of the _int primitives. ClassBuffer only
+	// ever holds 8-byte class pointers (T_SIZE is 8), so these are
+	// behaviorally identical to their _int counterparts — they exist so
+	// List<T> can call a single uniform API whether T is a value struct
+	// (Buffer) or a class (ClassBuffer, after the Buffer<T> field is
+	// rewritten). Bodies use 8-byte slots, matching _int.
 
-	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
 		}
@@ -79,7 +80,7 @@ pub struct ClassBuffer<T> {
 		return self.cap
 	}
 
-	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 (void*)((long*)(unsigned long long)self->data)[i];
@@ -94,11 +95,15 @@ pub struct ClassBuffer<T> {
 	}
 
 	// Store the owned class pointer `val` into slot `i`, which MUST be fresh
-	// (calloc'd, or zeroed by move_T/move_int). This is a plain pointer
-	// store — it does NOT destroy/free the slot's previous occupant, so a
-	// second `store_T` at an occupied index leaks that instance. Use
-	// replace_T (or replace_int) to overwrite a live slot.
-	inline func store_T = (ref self, int i: i >= 0 && i < self.cap, T val: val != 0) {
+	// (calloc'd, or zeroed by move/move_int). Takes OWNERSHIP of `val`
+	// (`move`): the slot's #destroy reclaims the instance, so the caller must
+	// not free its copy — a fresh constructor result transfers here directly,
+	// and a local must be moved (its own cleanup is suppressed at the call
+	// site). This is a plain pointer store — it does NOT destroy/free the
+	// slot's previous occupant, so a second `store` at an occupied index
+	// leaks that instance. Use replace (or replace_int) to overwrite a live
+	// slot.
+	internal inline func store = (ref self, int i: i >= 0 && i < self.cap, move T val: val != 0) {
 		```
 		#arch: c
 		((long*)(unsigned long long)self->data)[i] = (long)val;
@@ -116,11 +121,11 @@ pub struct ClassBuffer<T> {
 	// buffer no longer references it. Declared `move out T` so the borrow
 	// checker treats the result as OWNED — the slot is relinquished, so the
 	// caller is the sole remaining owner. This is the owning-extract primitive
-	// (parallel to List.pop); use it (not load_T) when transferring ownership
+	// (parallel to List.pop); use it (not load) when transferring ownership
 	// out of a ClassBuffer slot, or moving a value into a fresh owning
-	// container — load_T returns a BORROW (the slot is unchanged) and storing
+	// container — load returns a BORROW (the slot is unchanged) and storing
 	// it elsewhere would create shared ownership (double-free at destroy).
-	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
 		long *slots = (long*)(unsigned long long)self->data;
@@ -138,7 +143,52 @@ pub struct ClassBuffer<T> {
 		```
 	}
 
-	inline func store_int = (ref self, int i: i >= 0 && i < self.cap, int val: val != 0) {
+	// Apply `f` to slot `i` in place — the owning-counterpart of Buffer's
+	// modify for class elements. `f` receives the current instance pointer
+	// as a borrow and returns the replacement instance (fresh, or the same
+	// pointer); the primitive frees the displaced instance (destroy + free)
+	// unless `f` returned it. Storing the returned instance raw is sound:
+	// the slot takes sole ownership and `f`'s return is not retained
+	// elsewhere. NOT `inline`: the body calls through the fn pointer.
+	func modify = (ref self, int i: i >= 0 && i < self.cap, func (T, out T) f) {
+		```
+		#arch: c
+		long *slots = (long*)(unsigned long long)self->data;
+		void *old = (void*)slots[i];
+		void *new_value = (void*)f(old);
+		slots[i] = (long)new_value;
+		if (old != new_value) {
+			T_destroy(old);
+			free(old);
+		}
+		```
+		```
+		#arch: aarch64
+		// x19 = self, x1 = i, x2 = f. Class slots are one pointer wide.
+		stp x20, x21, [sp, #-16]!
+		stp x22, x23, [sp, #-16]!
+		mov x22, x2
+		ldr x9, [x19, #8]
+		lsl x3, x1, #3
+		add x20, x9, x3
+		ldr x0, [x20]
+		blr x22
+		mov x23, x0
+		ldr x9, [x20]
+		str x23, [x20]
+		cmp x9, x23
+		b.eq .Lcb_modify_T_done
+		mov x0, x9
+		bl T_destroy
+		mov x0, x9
+		bl _free
+		.Lcb_modify_T_done:
+		ldp x22, x23, [sp], #16
+		ldp x20, x21, [sp], #16
+		```
+	}
+
+	internal inline func store_int = (ref self, int i: i >= 0 && i < self.cap, int val: val != 0) {
 		```
 		#arch: c
 		((long*)(unsigned long long)self->data)[i] = val;
@@ -152,7 +202,7 @@ pub struct ClassBuffer<T> {
 		```
 	}
 
-	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;
@@ -172,7 +222,7 @@ pub struct ClassBuffer<T> {
 
 	// Store into a slot, freeing the previous value (it is an owned class
 	// pointer): run its destroy then free it before overwriting.
-	func replace_int = (ref self, int i: i >= 0 && i < self.cap, int val: val != 0) {
+	internal func replace_int = (ref self, int i: i >= 0 && i < self.cap, int val: val != 0) {
 		```
 		#arch: c
 		long *slots = (long*)(unsigned long long)self->data;
@@ -204,9 +254,11 @@ pub struct ClassBuffer<T> {
 	}
 
 	// T-typed alias of replace_int: free the outgoing class pointer (destroy +
-	// free) then store the new one. Used by List.set so the uniform `_T` API
+	// free) then store the new one. Used by List.set so the uniform API
 	// preserves ownership for class elements.
-	func replace_T = (ref self, int i: i >= 0 && i < self.cap, T val: val != 0) {
+	// Overwrite a live slot: destroy + free the displaced instance, then take
+	// OWNERSHIP of `val` (`move`) — same transfer rule as store.
+	func replace = (ref self, int i: i >= 0 && i < self.cap, move T val: val != 0) {
 		```
 		#arch: c
 		long *slots = (long*)(unsigned long long)self->data;
@@ -239,10 +291,10 @@ pub struct ClassBuffer<T> {
 
 	// Move slot src into slot dst: reclaim dst's previous instance (destroy +
 	// free), take over src's pointer, and zero src — exactly one slot owns the
-	// instance afterwards. The class-buffer counterpart of Buffer.shift_T,
+	// instance afterwards. The class-buffer counterpart of Buffer.shift,
 	// used by Map/Set.remove's backward-shift so shifting entries neither
 	// duplicates nor orphans owned instances.
-	func shift_T = (ref self, int dst: dst >= 0 && dst < self.cap, int src: src >= 0 && src < self.cap) {
+	func shift = (ref self, int dst: dst >= 0 && dst < self.cap, int src: src >= 0 && src < self.cap) {
 		```
 		#arch: c
 		long *slots = (long*)(unsigned long long)self->data;
@@ -286,7 +338,7 @@ pub struct ClassBuffer<T> {
 	// pointers, returned as a `view T` (T is a class, so each element is an
 	// 8-byte pointer). Borrows from self — invalidated on reassignment. Mirrors
 	// Buffer.slice; ClassBuffer stores 8-byte slots, so the element width is 8.
-	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;