nomen-lang 0.10.0 → 0.11.0

package/core/System/Format.nm

@@ -0,0 +1,751 @@
+/**
+ * Compile-time-checked rendering helpers behind interpolation format specs
+ * (`\{expr:spec}` — SPEC, String Interpolation). The checker validates each
+ * spec against the argument's type and lowers the argument into one of these
+ * calls, so the interpolation helper keeps receiving an ordinary owned
+ * string. Every function is also usable directly.
+ *
+ * Widths are signed: positive right-aligns, negative left-aligns, 0 means
+ * "no padding". `zero` pads with '0' between the sign and the digits (the
+ * printf `0` flag); alignment and zero-padding never combine (`<`/`>` and
+ * `0` are alternative fills in the spec grammar).
+ **/
+pub struct Format {
+	// Render a float with a fixed number of decimal places. `spec` is the
+	// full printf directive the checker built from the format spec (e.g.
+	// "%.2f", "%08.2f", "%-10.3f") — the body formats nothing itself, it
+	// only hands the directive to snprintf (twice: size, then render, so
+	// any width is safe).
+	pub func float_fixed = (float value, string spec, mv out string) {
+		```
+		#arch: c
+		int need = snprintf(NULL, 0, spec.ptr, value);
+		char* str = (char*)malloc((size_t)need + 1);
+		snprintf(str, (size_t)need + 1, spec.ptr, value);
+		str[need] = 0;
+		return (nomen_string){ str, need };
+		```
+		```
+		#arch: aarch64
+		// x0 = value (double bits — GP param), x1/x2 = the spec's (ptr, len)
+		// pair. The spec IS the directive. The variadic double rides the
+		// stack (Darwin AAPCS64 varargs); [sp] is re-armed before each call.
+		stp x19, x20, [sp, #-16]!
+		stp x21, x22, [sp, #-16]!
+		mov x19, x0                // value bits
+		mov x20, x1                // spec ptr
+		sub sp, sp, #16
+		fmov d0, x19
+		str d0, [sp]               // variadic double slot
+		mov x0, #0                 // NULL — sizing pass
+		mov x1, #0
+		mov x2, x20
+		bl _snprintf
+		mov x21, x0                // need
+		add x0, x21, #1
+		bl _malloc
+		mov x22, x0                // str
+		fmov d0, x19
+		str d0, [sp]               // re-arm the slot
+		mov x0, x22
+		add x1, x21, #1
+		mov x2, x20
+		bl _snprintf               // writes need bytes + NUL at str[need]
+		mov x0, x22
+		mov x1, x21
+		add sp, sp, #16
+		ldp x21, x22, [sp], #16
+		ldp x19, x20, [sp], #16
+		```
+	}
+
+	// Grouped fixed-point rendering — the `\{value:.2n}` / `\{value:n}` spec
+	// (C#'s "N" standard format): render with %.Nf (2 decimals when the spec
+	// omits a precision, the C# default), then comma the integer part every
+	// three digits. Width and alignment compose at the call site through
+	// `Format.pad`; zero-padding and grouping never combine (checked).
+	pub func float_grouped = (float value, int places: places >= 0, mv out string) {
+		var sb = StringBuilder()
+		sb.append_char('%')
+		sb.append_char('.')
+		sb.append_int(places)
+		sb.append_char('f')
+		var string rendered = Format.float_fixed(value, sb.to_string())
+		return Format.group_int_part(rendered)
+	}
+
+	// Insert ',' every three digits of the integer part of an already
+	// rendered number ("1234.50" → "1,234.50", "-987654" → "-987,654").
+	// A sign and any fractional part pass through untouched.
+	internal func group_int_part = (string text, mv out string) {		var int len = text.length
+		var int dot = len
+		var int i = 0
+		while i < len; i += 1 {
+			if text.at(i) == '.' {
+				dot = i
+			}
+		}
+		var int digits = 0
+		i = 0
+		while i < dot; i += 1 {
+			var char c = text.at(i)
+			if c != '-' && c != '+' {
+				digits += 1
+			}
+		}
+		var sb = StringBuilder()
+		var int seen = 0
+		i = 0
+		while i < len; i += 1 {
+			var char c = text.at(i)
+			sb.append_char(c)
+			if i < dot && c != '-' && c != '+' {
+				seen += 1
+				var int remaining = digits - seen
+				if remaining > 0 && remaining % 3 == 0 {
+					sb.append_char(',')
+				}
+			}
+		}
+		return sb.to_string()
+	}
+
+	// Render a signed integer in base 2/8/10/16. A negative value renders
+	// its magnitude with a leading '-' in every base (not two's complement).
+	// `group` inserts thousands separators every three digits — intended for
+	// base 10 (the `\{value:n}` spec); a grouped other base is the caller's
+	// choice and commas every three digits regardless.
+	pub func int_base = (int64 value, int base: base >= 2 && base <= 16, bool upper, int width, bool zero, bool group, mv out string) {
+		const string digits = "0123456789abcdef"
+		const string upper_digits = "0123456789ABCDEF"
+		var int w = width
+		var bool left = false
+		if w < 0 {
+			left = true
+			w = 0 - w
+		}
+		var bool neg = value < 0
+		var uint64 mag = value as uint64
+		if neg {
+			// Two's-complement negate on the UNSIGNED magnitude (wraps
+			// correctly for INT64_MIN — no signed-overflow UB).
+			var uint64 zero = 0
+			mag = zero - mag
+		}
+		var uint64 b = base as uint64
+		// Digits arrive least-significant first; the emit walks the scratch
+		// backwards. 72 slots covers binary's 64 digits plus the sign.
+		var Array<char> chars = Array<char>.with('0', 72)
+		var int count = 0
+		if mag == 0 {
+			chars.set(0, '0')
+			count = 1
+		} else {
+			while mag > 0 {
+				var uint64 d = mag % b
+				mag = mag / b
+				var int di = d as int
+				if di < 10 {
+					chars.set(count, digits.at(di))
+				}
+				if di >= 10 && upper {
+					chars.set(count, upper_digits.at(di))
+				}
+				if di >= 10 && !upper {
+					chars.set(count, digits.at(di))
+				}
+				count += 1
+			}
+		}
+		var int total = count
+		if neg {
+			total += 1
+		}
+		var int padding = 0
+		if w > total {
+			padding = w - total
+		}
+		var sb = StringBuilder()
+		var int i = 0
+		if left {
+			// sign, digits, spaces
+			if neg {
+				sb.append_char('-')
+			}
+			while i < count; i += 1 {
+				sb.append_char(chars.at(count - 1 - i))
+				if group && base == 10 && count - 1 - i > 0 && (count - 1 - i) % 3 == 0 {
+					sb.append_char(',')
+				}
+			}
+			i = 0
+			while i < padding; i += 1 {
+				sb.append_char(' ')
+			}
+		} else {
+			if zero {
+				// sign, zeros, digits (printf's `0` flag)
+				if neg {
+					sb.append_char('-')
+				}
+				while i < padding; i += 1 {
+					sb.append_char('0')
+				}
+			} else {
+				// spaces, sign, digits
+				while i < padding; i += 1 {
+					sb.append_char(' ')
+				}
+				if neg {
+					sb.append_char('-')
+				}
+			}
+			i = 0
+			while i < count; i += 1 {
+				sb.append_char(chars.at(count - 1 - i))
+				if group && base == 10 && count - 1 - i > 0 && (count - 1 - i) % 3 == 0 {
+					sb.append_char(',')
+				}
+			}
+		}
+		return sb.to_string()
+	}
+
+	// Unsigned twin of int_base — the value argument keeps the uint64 family
+	// (uint8..uint64) so no value is reinterpreted through a signed width.
+	pub func uint_base = (uint64 value, int base: base >= 2 && base <= 16, bool upper, int width, bool zero, bool group, mv out string) {
+		const string digits = "0123456789abcdef"
+		const string upper_digits = "0123456789ABCDEF"
+		var int w = width
+		var bool left = false
+		if w < 0 {
+			left = true
+			w = 0 - w
+		}
+		var uint64 mag = value
+		var uint64 b = base as uint64
+		var Array<char> chars = Array<char>.with('0', 72)
+		var int count = 0
+		if mag == 0 {
+			chars.set(0, '0')
+			count = 1
+		} else {
+			while mag > 0 {
+				var uint64 d = mag % b
+				mag = mag / b
+				var int di = d as int
+				if di < 10 {
+					chars.set(count, digits.at(di))
+				}
+				if di >= 10 && upper {
+					chars.set(count, upper_digits.at(di))
+				}
+				if di >= 10 && !upper {
+					chars.set(count, digits.at(di))
+				}
+				count += 1
+			}
+		}
+		var int padding = 0
+		if w > count {
+			padding = w - count
+		}
+		var sb = StringBuilder()
+		var int i = 0
+		if left {
+			while i < count; i += 1 {
+				sb.append_char(chars.at(count - 1 - i))
+				if group && base == 10 && count - 1 - i > 0 && (count - 1 - i) % 3 == 0 {
+					sb.append_char(',')
+				}
+			}
+			i = 0
+			while i < padding; i += 1 {
+				sb.append_char(' ')
+			}
+		} else {
+			while i < padding; i += 1 {
+				if zero {
+					sb.append_char('0')
+				} else {
+					sb.append_char(' ')
+				}
+			}
+			i = 0
+			while i < count; i += 1 {
+				sb.append_char(chars.at(count - 1 - i))
+				if group && base == 10 && count - 1 - i > 0 && (count - 1 - i) % 3 == 0 {
+					sb.append_char(',')
+				}
+			}
+		}
+		return sb.to_string()
+	}
+
+	// Align an already-rendered text in a field of `|width|` spaces. The
+	// text is borrowed; the result is always a fresh owned string.
+	pub func pad = (string text, int width, mv out string) {
+		var int w = width
+		var bool left = false
+		if w < 0 {
+			left = true
+			w = 0 - w
+		}
+		if w <= text.length {
+			return text.copy()
+		}
+		var int padding = w - text.length
+		var sb = StringBuilder()
+		if left {
+			// text, then spaces
+			sb.append(text)
+			var int i = 0
+			while i < padding; i += 1 {
+				sb.append_char(' ')
+			}
+		} else {
+			// spaces, then text
+			var int i = 0
+			while i < padding; i += 1 {
+				sb.append_char(' ')
+			}
+			sb.append(text)
+		}
+		return sb.to_string()
+	}
+
+	// --- Custom patterns (the `\{value:#,##0.00}` mini-language) ------------
+	//
+	// Subset, validated at compile time (SPEC, String Interpolation):
+	//   0        digit slot, always renders (zero-pads)
+	//   #        digit slot, renders only when a digit exists
+	//   .        decimal point; trailing '#' fraction slots trim zeros
+	//   ,        group separator between digit slots; the rightmost comma
+	//            sets the group size for all groups
+	//   %        value scaled x100; '%' emitted at its position
+	//   '...'    quoted literal; any other character passes through
+	//   ;        at most two sections (positive;negative) — the negative
+	//            section renders the absolute value, sign and all
+	// Not in the language: exponential patterns (use the `:e` spec), the
+	// per-mille sign, trailing-comma scaling, three-section forms.
+	//
+	// The scanners below share one shape: snapshot `was_quoted`, toggle the
+	// quote state on a quote character, then run each structural check as
+	// its own top-level `if` gated on "this character is structural" —
+	// Nomen has no `else if`.
+
+	// The section of `pattern` that applies to `negative` values.
+	internal func pat_section = (string pattern, bool negative, mv out string) {
+		var int split = -1
+		var bool quoted = false
+		var int i = 0
+		while i < pattern.length; i += 1 {
+			var char c = pattern.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			if !was_quoted && !quoted && c == ';' {
+				split = i
+			}
+		}
+		var sb = StringBuilder()
+		if split == -1 {
+			return pattern.copy()
+		}
+		var int from = 0
+		if negative {
+			from = split + 1
+		}
+		i = from
+		while i < pattern.length; i += 1 {
+			sb.append_char(pattern.at(i))
+		}
+		return sb.to_string()
+	}
+
+	// True when the pattern carries two ';'-separated sections.
+	internal func pat_has2 = (string pattern, out bool) {
+		var bool quoted = false
+		var bool found = false
+		var int i = 0
+		while i < pattern.length; i += 1 {
+			var char c = pattern.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			if !was_quoted && !quoted && c == ';' {
+				found = true
+			}
+		}
+		return found
+	}
+
+	// True when the pattern carries a '%' anywhere (unquoted).
+	internal func pat_has_percent = (string pattern, out bool) {
+		var bool quoted = false
+		var bool found = false
+		var int i = 0
+		while i < pattern.length; i += 1 {
+			var char c = pattern.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			if !was_quoted && !quoted && c == '%' {
+				found = true
+			}
+		}
+		return found
+	}
+
+	// The widest fraction-slot count across both sections — the snprintf
+	// pass renders at least this many digits; shaping trims to the applied
+	// section's own slots.
+	internal func pat_max_frac = (string pattern, out int) {
+		var bool quoted = false
+		var bool in_frac = false
+		var int count = 0
+		var int best = 0
+		var int i = 0
+		while i < pattern.length; i += 1 {
+			var char c = pattern.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			var bool structural = !was_quoted && !quoted
+			if structural && c == '.' {
+				in_frac = true
+			}
+			if structural && (c == '0' || c == '#') {
+				if in_frac {
+					count += 1
+					if count > best {
+						best = count
+					}
+				}
+			}
+			if structural && c == ';' {
+				in_frac = false
+				count = 0
+			}
+			if structural && c != '.' && c != '0' && c != '#' {
+				// any other literal ends the fraction run
+				in_frac = false
+				count = 0
+			}
+		}
+		return best
+	}
+
+	// Decimal digits of a magnitude, most-significant first, no sign.
+	internal func pat_digits10 = (uint64 mag, mv out string) {
+		var sb = StringBuilder()
+		if mag == 0 {
+			sb.append_char('0')
+			return sb.to_string()
+		}
+		var Array<char> chars = Array<char>.with('0', 20)
+		var int count = 0
+		var uint64 m = mag
+		var string dig = "0123456789"
+		while m > 0 {
+			var uint64 d = m % 10
+			m = m / 10
+			chars.set(count, dig.at(d as int))
+			count += 1
+		}
+		var int j = count - 1
+		while j >= 0; j -= 1 {
+			sb.append_char(chars.at(j))
+		}
+		return sb.to_string()
+	}
+
+	// Shape digit strings against one pattern section. `int_digits` is the
+	// unsigned integer part; `frac_raw` the rendered fraction digits at the
+	// section's full precision ("" for integers — zeros fill up to the
+	// section's minimum). Emits prefix literals, the grouped integer part,
+	// the trimmed fraction, and the suffix. Every helper call result lands
+	// in a single-binding local: no owned string is ever reassigned (the
+	// displaced-free pass does not cover every conditional reassignment
+	// shape — FOLLOWUP.md).
+	internal func pat_render = (string section, string int_digits, string frac_raw, bool negative, mv out string) {
+		// Pass 1 — locate the regions: prefix (before the first integer
+		// slot), the integer slot run, the fraction slots, and the suffix
+		// (after the last slot).
+		var bool quoted = false
+		var int first_slot = -1
+		var int last_slot = -1
+		var int dot = -1
+		var int pad_slots = 0
+		var int frac_slots = 0
+		var int frac_min = 0
+		var bool has_comma = false
+		var int slots_after_comma = 0
+		var int i = 0
+		while i < section.length; i += 1 {
+			var char c = section.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			var bool structural = !was_quoted && !quoted
+			if structural && c == '.' {
+				if dot == -1 {
+					dot = i
+				}
+			}
+			if structural && (c == '0' || c == '#') {
+				last_slot = i
+				if dot == -1 {
+					// an integer slot — never counted before the dot
+					if first_slot == -1 {
+						first_slot = i
+					}
+					slots_after_comma += 1
+					if c == '0' {
+						// only '0' slots force zero-padding ('#' drops out)
+						pad_slots += 1
+					}
+				} else {
+					frac_slots += 1
+					if c == '0' {
+						frac_min = frac_slots
+					}
+				}
+			}
+			if structural && c == ',' && dot == -1 {
+				has_comma = true
+				slots_after_comma = 0
+			}
+		}
+		// Pass 2 — emit.
+		var sb = StringBuilder()
+		if negative {
+			sb.append_char('-')
+		}
+		// prefix: [0, first_slot), quotes stripped
+		i = 0
+		quoted = false
+		while i < first_slot; i += 1 {
+			var char c = section.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			if was_quoted && c != '\'' {
+				sb.append_char(c)
+			}
+			if !was_quoted && c != '\'' {
+				sb.append_char(c)
+			}
+		}
+		// integer part: zero-pad to the '0' slots, group per the rightmost
+		// comma's run, drop a lone zero when every slot is '#' (the shape
+		// helper's own empty case). The shape result lands in a local — an
+		// inline call argument to append_string would never be anchored.
+		sb.append_string(Format.pat_shape_int(int_digits, pad_slots, has_comma, slots_after_comma))
+		// fraction: trim trailing zeros down to the section minimum, then
+		// zero-fill up to it (integer values arrive with no fraction at all).
+		var string kept = Format.pat_shape_frac(frac_raw, frac_slots, frac_min)
+		if kept.length > 0 {
+			sb.append_char('.')
+			sb.append(kept)
+		}
+		// suffix: (last_slot, end), quotes stripped, structural dot dropped
+		i = last_slot + 1
+		quoted = false
+		while i < section.length; i += 1 {
+			var char c = section.at(i)
+			var bool was_quoted = quoted
+			if c == '\'' {
+				if was_quoted {
+					quoted = false
+				}
+				if !was_quoted {
+					quoted = true
+				}
+			}
+			if was_quoted && c != '\'' {
+				sb.append_char(c)
+			}
+			if !was_quoted && c != '\'' && i != dot {
+				sb.append_char(c)
+			}
+		}
+		return sb.to_string()
+	}
+
+	// The integer part of a pattern: zero-pad to the '0' slots, then insert
+	// group separators every `group_size` digits. A value of "0" with no '0'
+	// slots renders empty (the `#`-only shapes).
+	internal func pat_shape_int = (string int_digits, int pad_slots, bool has_comma, int group_size, mv out string) {
+		var sb = StringBuilder()
+		if int_digits == "0" && pad_slots == 0 {
+			return sb.to_string()
+		}
+		var int total = int_digits.length
+		if total < pad_slots {
+			total = pad_slots
+		}
+		var int pad_count = total - int_digits.length
+		var int k = 0
+		while k < total; k += 1 {
+			if k < pad_count {
+				sb.append_char('0')
+			} else {
+				sb.append_char(int_digits.at(k - pad_count))
+			}
+			var int remaining = total - k - 1
+			if has_comma && group_size > 0 && remaining > 0 && remaining % group_size == 0 {
+				sb.append_char(',')
+			}
+		}
+		return sb.to_string()
+	}
+
+	// The fraction part of a pattern: clip to the slot count, trim trailing
+	// zeros down to the minimum ('0' slots), then zero-fill back up to it.
+	internal func pat_shape_frac = (string frac_raw, int frac_slots, int frac_min, mv out string) {
+		var sb = StringBuilder()
+		var int n = frac_raw.length
+		if n > frac_slots {
+			n = frac_slots
+		}
+		var bool trimming = true
+		while trimming && n > frac_min {
+			var char last = frac_raw.at(n - 1)
+			if last == '0' {
+				n -= 1
+			}
+			if last != '0' {
+				trimming = false
+			}
+		}
+		var int i = 0
+		while i < n; i += 1 {
+			sb.append_char(frac_raw.at(i))
+		}
+		while n < frac_min; n += 1 {
+			sb.append_char('0')
+		}
+		return sb.to_string()
+	}
+
+	// Pick the sign's section, render, and prepend '-' when a negative value
+	// has no dedicated section.
+	internal func pat_render_all = (string pattern, bool negative, string int_digits, string frac_raw, mv out string) {
+		var string section = Format.pat_section(pattern, negative)
+		var bool has2 = Format.pat_has2(pattern)
+		return Format.pat_render(section, int_digits, frac_raw, negative && !has2)
+	}
+
+	// `#,##0`-style rendering of a signed integer.
+	pub func int_pattern = (int64 value, string pattern, mv out string) {
+		var bool neg = value < 0
+		var uint64 mag = value as uint64
+		if neg {
+			var uint64 zero = 0
+			mag = zero - mag
+		}
+		if Format.pat_has_percent(pattern) {
+			mag = mag * 100
+		}
+		// The digit string stays a named local on purpose: a plain `string`
+		// parameter is a borrow, so this local must free at scope exit, and
+		// the per-function ownership sets must isolate it from the
+		// same-named `const string digits` locals in int_base/uint_base
+		// (name-keyed marks bleeding across library methods suppressed this
+		// free — FOLLOWUP receipt; displaced_free.test.ts pins the class).
+		var string digits = Format.pat_digits10(mag)
+		var string rendered = Format.pat_render_all(pattern, neg, digits, "")
+		return rendered
+	}
+
+	// Unsigned twin of int_pattern — no sign, no reinterpretation.
+	pub func uint_pattern = (uint64 value, string pattern, mv out string) {
+		var uint64 mag = value
+		if Format.pat_has_percent(pattern) {
+			mag = mag * 100
+		}
+		return Format.pat_render_all(pattern, false, Format.pat_digits10(mag), "")
+	}
+
+	// Fixed-point pattern rendering of a float: snprintf renders the
+	// fraction at the pattern's widest precision, then the shaping pass
+	// trims to the applied section's slots.
+	pub func float_pattern = (float value, string pattern, mv out string) {
+		var bool neg = value < 0
+		var float v = value
+		if neg {
+			var float zero = 0
+			v = zero - v
+		}
+		if Format.pat_has_percent(pattern) {
+			v = v * (100 as float)
+		}
+		var int max_frac = Format.pat_max_frac(pattern)
+		var spec_sb = StringBuilder()
+		spec_sb.append_char('%')
+		spec_sb.append_char('.')
+		spec_sb.append_int(max_frac)
+		spec_sb.append_char('f')
+		var string rendered = Format.float_fixed(v, spec_sb.to_string())
+		// rendered = digits '.' frac — split them
+		var int dot = rendered.length
+		var int i = 0
+		while i < rendered.length; i += 1 {
+			if rendered.at(i) == '.' {
+				dot = i
+			}
+		}
+		var int_sb = StringBuilder()
+		var frac_sb = StringBuilder()
+		var int s = 0
+		while s < rendered.length; s += 1 {
+			if s < dot {
+				int_sb.append_char(rendered.at(s))
+			}
+			if s > dot {
+				frac_sb.append_char(rendered.at(s))
+			}
+		}
+		// Both digit strings pass as call results (not locals at their last
+		// use) so the boundary keeps them borrows the call site anchors.
+		return Format.pat_render_all(pattern, neg, int_sb.to_string(), frac_sb.to_string())
+	}
+
+}

package/dist/index.mjs

@@ -7257,6 +7257,15 @@ var FunctionCallNode = class extends BaseNode {
 	*/
 	in_place_payload_indices;
 	/**
+	* Per-argument format specs for a `_string_interpolate_N` call
+	* (`\{expr:spec}`): entry `i - 1` corresponds to param `i` (index 0 is
+	* the pattern literal). Null entry = no spec for that argument. Set by
+	* the parser; the checker validates each spec against the argument's
+	* type and rewrites the argument into a `Format.*` rendering call (see
+	* check/utils/format_spec_arg.ts).
+	*/
+	format_specs;
+	/**
 	* The checker-stamped mangled label for a call resolved to an overloaded
 	* callee (`Struct_method_int`). For struct constructor calls resolved to
 	* an overloaded `#init`, the backends emit/bl the call through this label
@@ -15835,7 +15844,11 @@ function is_fresh_heap_string(node) {
 	if (!node) return false;
 	if (node.node_type === "access") {
 		const access = node.access;
-		if (access.node_type === "access_func" && access.name === "to_string") return true;
+		if (access.node_type === "access_func") {
+			const fn = access;
+			if (fn.name === "to_string") return true;
+			if (fn.owned_return) return true;
+		}
 	}
 	if (node.type?.name !== "string") return false;
 	if (node.node_type === "op") return true;
@@ -15843,8 +15856,7 @@ function is_fresh_heap_string(node) {
 	if (node.node_type === "access") {
 		const access = node.access;
 		if (access.node_type !== "access_func") return false;
-		const fn = access;
-		return !(!fn.owned_return && is_call_site_borrow_accessor(fn.name));
+		return !is_call_site_borrow_accessor(access.name);
 	}
 	return false;
 }
@@ -36405,6 +36417,7 @@ function clone_node(node) {
 			c.swap_params = n.swap_params ? new Map([...n.swap_params].map(([k, v]) => [k, clone_node(v)])) : void 0;
 			c.variadic_param_name = n.variadic_param_name;
 			c.variadic_param_index = n.variadic_param_index;
+			c.format_specs = n.format_specs?.slice();
 			c.is_enum_shorthand = n.is_enum_shorthand;
 			c.is_thread_ctor = n.is_thread_ctor;
 			c.is_fiber_ctor = n.is_fiber_ctor;
@@ -47524,6 +47537,116 @@ function promote_allocations(node, status) {
 	}
 }
 //#endregion
+//#region ../src/check/utils/format_spec_arg.ts
+/**
+* Compile-time-checked format specs (`\{expr:spec}` — SPEC, String
+* Interpolation). The parse layer splits the spec text off the interpolation
+* argument and attaches it to the call (`FunctionCallNode.format_specs`);
+* this module validates the spec against the argument's TYPE — the
+* compile-time half of the feature — and lowers the argument into a call of
+* the matching System `Format` function, so the interpolation helper keeps
+* receiving an ordinary owned string.
+*
+*   \{f:.2} / \{f:08.2} / \{f:<10.3}  → Format.float_fixed(v, "<directive>")
+*       The checker builds the full printf directive (it knows the spec is
+*       constant), so the raw body is one snprintf with no flag logic.
+*   \{i:03} / \{i:x} / \{u:08X} / \{i:b} → Format.int_base / Format.uint_base
+*       Signed arguments widen to int64, unsigned to uint64 (both accepted
+*       families under the implicit-int coercion ranking), then the library's
+*       digit loop renders base/width/zero/alignment.
+*   \{s:>8} / anything with only width/align → Format.pad(rendered, width)
+*       The argument keeps its `.to_string()` wrap; pad aligns the text.
+*
+* Type mismatches are REJECTED here (precision on a non-float, base on a
+* non-integer, zero-padding on a non-numeric) with the spec text in the
+* message — an invalid `\{expr:spec}` never reaches codegen.
+*/
+/** Lower one spec'd interpolation argument. Returns the replacement node, or
+*  undefined when the spec was rejected (error already reported) or the
+*  argument shape is unexpected (keep the plain wrap). */
+function check_format_spec_arg(param, spec, status) {
+	const wrap = param.node_type === "access" && param.access.node_type === "access_func" && param.access.name === "to_string" ? param : void 0;
+	const target = wrap ? param.target : param;
+	const t = type_from_value_node(target, status);
+	const info = !t.is_array && !t.is_view && !t.is_ref && !t.is_pointer ? get_built_in_type(t.name) : void 0;
+	const kind = info?.kind;
+	const is_float = kind === "float";
+	const is_int = kind === "int";
+	if (spec.precision !== void 0 && !is_float) {
+		add_error(status, `format spec ':${spec.text}': precision requires a float, but the value is ${t.name || "value"}`, spec.start);
+		return;
+	}
+	if (spec.base && "xXbo".includes(spec.base) && !is_int) {
+		add_error(status, `format spec ':${spec.text}': base requires an integer, but the value is ${t.name || "value"}`, spec.start);
+		return;
+	}
+	if (spec.base && "nN".includes(spec.base) && !is_int && !is_float) {
+		add_error(status, `format spec ':${spec.text}': grouping requires an integer or float, but the value is ${t.name || "value"}`, spec.start);
+		return;
+	}
+	if (spec.pattern !== void 0 && !is_int && !is_float) {
+		add_error(status, `format spec ':${spec.text}': pattern requires an integer or float, but the value is ${t.name || "value"}`, spec.start);
+		return;
+	}
+	if (spec.base && "eE".includes(spec.base) && !is_float) {
+		add_error(status, `format spec ':${spec.text}': exponential requires a float, but the value is ${t.name || "value"}`, spec.start);
+		return;
+	}
+	if (spec.zero && !is_float && !is_int) {
+		add_error(status, `format spec ':${spec.text}': zero-padding requires an integer or float, but the value is ${t.name || "value"}`, spec.start);
+		return;
+	}
+	const signed_width = (spec.align === "left" ? -1 : 1) * (spec.width ?? 0);
+	const is_exponential = spec.base === "e" || spec.base === "E";
+	const is_grouped = spec.base === "n" || spec.base === "N";
+	if (spec.pattern !== void 0) {
+		const fname = is_float ? "float_pattern" : info?.signed ? "int_pattern" : "uint_pattern";
+		const rendered = format_call(spec.start, fname, [new CastNode(target.start, target, new Type(is_float ? "float" : info?.signed ? "int64" : "uint64")), new ValueNode(target.start, `"${escape_pattern(spec.pattern)}"`, new Type("string", true))]);
+		if (signed_width === 0) return rendered;
+		return format_call(spec.start, "pad", [rendered, new ValueNode(target.start, String(signed_width), new Type("int", true))]);
+	}
+	if (is_grouped && is_float) {
+		const places = spec.precision ?? 2;
+		const grouped = format_call(spec.start, "float_grouped", [new CastNode(target.start, target, new Type("float")), new ValueNode(target.start, String(places), new Type("int", true))]);
+		if (signed_width === 0) return grouped;
+		return format_call(spec.start, "pad", [grouped, new ValueNode(target.start, String(signed_width), new Type("int", true))]);
+	}
+	if (is_float && (spec.precision !== void 0 || is_exponential)) {
+		let directive = "%";
+		if (spec.zero && signed_width > 0) directive += "0";
+		if (spec.align === "left") directive += "-";
+		if (signed_width !== 0) directive += String(signed_width);
+		directive += `.${spec.precision ?? 6}`;
+		directive += is_exponential ? spec.base : "f";
+		return format_call(spec.start, "float_fixed", [new CastNode(target.start, target, new Type("float")), new ValueNode(target.start, `"${directive}"`, new Type("string", true))]);
+	}
+	if (is_int && (spec.base || spec.zero)) {
+		const grouped = is_grouped;
+		const base = spec.base === "x" || spec.base === "X" ? 16 : spec.base === "b" ? 2 : spec.base === "o" ? 8 : 10;
+		const fname = info?.signed ? "int_base" : "uint_base";
+		const render_width = grouped ? 0 : signed_width;
+		const rendered = format_call(spec.start, fname, [
+			new CastNode(target.start, target, new Type(info?.signed ? "int64" : "uint64")),
+			new ValueNode(target.start, String(base), new Type("int", true)),
+			new ValueNode(target.start, spec.base === "X" ? "true" : "false", new Type("bool", true)),
+			new ValueNode(target.start, String(render_width), new Type("int", true)),
+			new ValueNode(target.start, spec.zero && !grouped ? "true" : "false", new Type("bool", true)),
+			new ValueNode(target.start, grouped ? "true" : "false", new Type("bool", true))
+		]);
+		if (grouped && signed_width !== 0) return format_call(spec.start, "pad", [rendered, new ValueNode(target.start, String(signed_width), new Type("int", true))]);
+		return rendered;
+	}
+	return format_call(spec.start, "pad", [wrap ?? param, new ValueNode(target.start, String(signed_width), new Type("int", true))]);
+}
+function format_call(start, fname, params) {
+	return new AccessNode(start, new ValueNode(start, "Format"), new AccessFunctionCallNode(start, fname, void 0, params));
+}
+/** The pattern rides a Nomen string literal — escape the two characters
+*  that would terminate or escape it. */
+function escape_pattern(pattern) {
+	return pattern.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+//#endregion
 //#region ../src/check/utils/regex_pattern_lint.ts
 /**
 * Compile-time lint for Regex pattern literals (FOLLOWUP "Regex pattern
@@ -47949,6 +48072,15 @@ function check_function_call(node, status, func, target_type, self_value, self_p
 		status.expected_type = old_expected_type;
 		status.allow_null_value = old_allow_null;
 		status.checking_variadic_arg = old_variadic_arg;
+		const spec = i > 0 && is_interp_name(node.name) && node.node_type === "func_call" ? node.format_specs?.[i - 1] : void 0;
+		if (spec) {
+			const lowered = check_format_spec_arg(param, spec, status);
+			if (lowered) {
+				node.params[i] = lowered;
+				param = lowered;
+				check_node(lowered, status);
+			}
+		}
 		if (i > 0 && is_interp_name(node.name) && parse_interp_name(node.name).kinds === null) {
 			const rewrite = interp_arg_rewrite(param, status);
 			if (rewrite.kind && rewrite.target) {
@@ -55356,6 +55488,12 @@ function build_struct_functions(node, status, skip_init = false) {
 		status.ref_class_param_types = /* @__PURE__ */ new Map();
 		status.scoped_declarations = enter_c_scope(status);
 		status.c_borrow_only_strings = scan_borrow_only_strings(func);
+		const old_string_borrow_vars = status.string_borrow_vars;
+		status.string_borrow_vars = /* @__PURE__ */ new Set();
+		const old_moved_string_vars = status.moved_string_vars;
+		status.moved_string_vars = /* @__PURE__ */ new Set();
+		const old_owned_string_vars = status.owned_string_vars;
+		status.owned_string_vars = /* @__PURE__ */ new Set();
 		status.force_heap_strings = scan_force_heap_strings(func.statements ?? [], status.structs);
 		status.function_return_type = func.return_type;
 		const old_nullable_ret_has = status.nullable_ret_has_param;
@@ -55480,6 +55618,9 @@ function build_struct_functions(node, status, skip_init = false) {
 		status.ref_local_vars = old_ref_locals;
 		status.ref_slot_vars = old_slot_locals;
 		status.variable_types = old_variable_types;
+		status.string_borrow_vars = old_string_borrow_vars;
+		status.moved_string_vars = old_moved_string_vars;
+		status.owned_string_vars = old_owned_string_vars;
 	}
 	status.current_struct = old_current_struct;
 	for (let traitName of node.traits) {
@@ -71760,7 +71901,10 @@ const PREFIX_POSITIONS = /* @__PURE__ */ new Set([
 function join$2(pieces) {
 	let out = "";
 	for (let i = 0; i < pieces.length; i++) {
-		if (i > 0 && needs_space(pieces, i)) out += " ";
+		if (i > 0) {
+			if (pieces[i].kind === "comment") out += pieces[i].gap_before ?? (pieces[i].space_before ? " " : "");
+			else if (needs_space(pieces, i)) out += " ";
+		}
 		out += pieces[i].text;
 	}
 	return out;
@@ -71770,13 +71914,12 @@ function needs_space(pieces, i) {
 	const current = pieces[i];
 	if (KEEP_SPACING.has(current.text) || KEEP_SPACING.has(previous.text)) return current.space_before;
 	if (NO_SPACE_BEFORE.has(current.text)) return false;
-	if (current.text === "}") return true;
+	if (current.text === "}") return previous.text !== "{";
 	if (NO_SPACE_AFTER.has(previous.text)) return false;
 	if (previous.text === "out") return current.text !== ".";
 	if (is_sign(pieces, i - 1)) return false;
 	if (current.text === ".") return !is_value_end(pieces, i - 1);
 	if (current.text === "(" || current.text === "[") return !is_value_end(pieces, i - 1) && !CALL_KEYWORDS.has(previous.text);
-	if (current.kind === "comment") return current.space_before;
 	return true;
 }
 /** Is the piece at `i` a sign (`-5`) rather than an operator (`a - 5`)? */
@@ -72000,11 +72143,21 @@ function consume_string(input, status) {
 		});
 		let end = consume_interpolated_expression(input, status.i);
 		let fragment = input.substring(status.i + 2, end);
+		const spec_at = find_format_spec_split(fragment);
+		let spec_token;
+		if (spec_at !== -1) {
+			spec_token = {
+				value: fragment.substring(spec_at),
+				i: status.i + 2 + spec_at
+			};
+			fragment = fragment.substring(0, spec_at);
+		}
 		status.i = status.i + 2;
 		for (let subtoken of tokenize(fragment)) {
 			subtoken.i += status.i;
 			status.tokens.push(subtoken);
 		}
+		if (spec_token) status.tokens.push(spec_token);
 		status.i = end;
 		status.tokens.push({
 			value: "}",
@@ -72031,6 +72184,35 @@ function consume_interpolated_expression(input, i) {
 	}
 	return input.length - 1;
 }
+/** Index of the `:` starting a format spec in an interpolation body, or -1.
+*  The spec (if any) always runs to the end of the fragment, so the
+*  RIGHTMOST top-level `:` wins; colons inside string/char literals and
+*  parentheses/brackets are skipped. The parse layer validates the spec
+*  grammar — a top-level `:` has no other meaning in an expression, so any
+*  one found here is treated as a spec attempt and reported there. */
+function find_format_spec_split(fragment) {
+	let depth = 0;
+	let candidate = -1;
+	let in_string = false;
+	let in_char = false;
+	for (let j = 0; j < fragment.length; j++) {
+		const c = fragment[j];
+		if (in_string || in_char) {
+			if (c === "\\") j += 1;
+			else if (in_string && c === "\"") in_string = false;
+			else if (in_char && c === "'") in_char = false;
+			continue;
+		}
+		if (c === "\"") in_string = true;
+		else if (c === "'") in_char = true;
+		else if (c === "(" || c === "[") depth += 1;
+		else if (c === ")" || c === "]") depth -= 1;
+		else if (c === ":" && depth === 0) {
+			if (fragment[j + 1] !== ":" && fragment[j - 1] !== ":") candidate = j;
+		}
+	}
+	return candidate;
+}
 function consume_comment(input, status) {
 	for (let j = status.i + 1; j < input.length; j++) if (input[j] === "\n") return j;
 	return input.length - 1;
@@ -72125,12 +72307,12 @@ function scan_line(text, state) {
 		return verbatim(text);
 	}
 	const pieces = [];
-	let space_before = false;
+	let gap = "";
 	let i = 0;
 	while (i < text.length) {
 		const c = text[i];
 		if (is_space(c)) {
-			space_before = true;
+			gap += c;
 			i++;
 			continue;
 		}
@@ -72164,9 +72346,10 @@ function scan_line(text, state) {
 		pieces.push({
 			kind,
 			text: text.slice(start, i),
-			space_before
+			space_before: gap.length > 0,
+			gap_before: gap
 		});
-		space_before = false;
+		gap = "";
 	}
 	if (!pieces.length) return {
 		kind: "blank",
@@ -72415,6 +72598,11 @@ function join_import(pieces) {
 			out = piece.text;
 			continue;
 		}
+		if (piece.kind === "comment") {
+			out += piece.gap_before ?? (piece.space_before ? " " : "");
+			out += piece.text;
+			continue;
+		}
 		if (!(piece.text === "::" || piece.text === "." || piece.text === "-" || pieces[i - 1].text === "::" || pieces[i - 1].text === "." || pieces[i - 1].text === "-")) out += " ";
 		out += piece.text;
 	}
@@ -74437,17 +74625,202 @@ function parse_match_branch(status) {
 }
 //#endregion
 //#region ../src/parse/parse_string_interpolation.ts
+/** A format spec token emitted by the tokenizer: the `:` plus the raw spec
+*  text (`:.2`, `:>8`, `:08x` — or invalid text, which the strict grammar
+*  below reports). The tokenizer splits on ANY top-level `:` (none can occur
+*  in an ordinary expression; `::` namespace separators are excluded), so
+*  this accepts any colon-leading token, including a bare `:`. */
+const FORMAT_SPEC_TOKEN = /^:/;
+/** Strict grammar walk over the raw spec text (without the `:`). A spec
+*  containing `#` or `,` tries the simple grammar first, then the custom
+*  pattern grammar; everything else reports the simple-grammar failure. */
+function parse_format_spec(text, start, status) {
+	const simple = parse_simple_spec(text, start);
+	if (simple.spec) return simple.spec;
+	if (!simple.structural) {
+		add_error(status, simple.error ?? "empty format spec", start);
+		return;
+	}
+	const pattern = parse_pattern_spec(text, start);
+	if (pattern.spec) return pattern.spec;
+	if (/[#,;%'"]/.test(text) || text.includes("E")) add_error(status, pattern.error ?? "empty format spec", start);
+	else add_error(status, simple.error ?? "empty format spec", start);
+}
+/** The simple spec grammar: `[fill][width][.precision][mode]`. Returns the
+*  spec, or an error plus whether the failure was STRUCTURAL (the text
+*  isn't simple-shaped at all — a custom pattern may still apply) versus a
+*  combination rule the simple grammar rejects outright. */
+function parse_simple_spec(text, start) {
+	const spec = {
+		text,
+		start
+	};
+	let i = 0;
+	let filled = false;
+	const read_digits = () => {
+		const begin = i;
+		while (i < text.length && text[i] >= "0" && text[i] <= "9") i += 1;
+		if (i === begin) return void 0;
+		return parseInt(text.substring(begin, i), 10);
+	};
+	if (text[i] === "<" || text[i] === ">") {
+		spec.align = text[i] === "<" ? "left" : "right";
+		i += 1;
+		filled = true;
+		const width = read_digits();
+		if (width === void 0) return { error: `invalid format spec ':${text}': expected width digits after '${spec.align === "left" ? "<" : ">"}'` };
+		spec.width = width;
+	} else if (text[i] === "0") {
+		spec.zero = true;
+		i += 1;
+		filled = true;
+		const width = read_digits();
+		if (width === void 0) return {
+			error: `invalid format spec ':${text}': expected width digits after '0'`,
+			structural: true
+		};
+		spec.width = width;
+	}
+	if (spec.width === void 0) {
+		const width = read_digits();
+		if (width !== void 0) {
+			spec.width = width;
+			filled = true;
+		}
+	}
+	if (text[i] === ".") {
+		i += 1;
+		const precision = read_digits();
+		if (precision === void 0) return {
+			error: `invalid format spec ':${text}': expected digits after '.'`,
+			structural: true
+		};
+		spec.precision = precision;
+		filled = true;
+	}
+	const BASE_LETTERS = "xXbo";
+	if (i < text.length && "xXbonNeE".includes(text[i]) && text.length - i === 1) {
+		spec.base = text[i];
+		i += 1;
+		filled = true;
+	}
+	if (i < text.length) return {
+		error: `invalid format spec ':${text}': unexpected character '${text[i]}'`,
+		structural: true
+	};
+	if (!filled) return {
+		error: "empty format spec",
+		structural: true
+	};
+	if (spec.precision !== void 0 && spec.base && BASE_LETTERS.includes(spec.base)) return { error: `invalid format spec ':${text}': precision and base cannot combine` };
+	if (spec.zero && spec.base && (spec.base === "n" || spec.base === "N")) return { error: `invalid format spec ':${text}': zero-padding cannot combine with grouping` };
+	if (spec.width === 0) return { error: `invalid format spec ':${text}': width must be at least 1` };
+	return { spec };
+}
+/** The custom-pattern grammar (C#-style subset — see FormatSpec). An
+*  optional `<N`/`>N` alignment prefix composes; the rest is the pattern,
+*  validated section by section. Returns the spec or the error message. */
+function parse_pattern_spec(text, start) {
+	const spec = {
+		text,
+		start
+	};
+	let i = 0;
+	if (text[i] === "<" || text[i] === ">") {
+		spec.align = text[i] === "<" ? "left" : "right";
+		i += 1;
+		const begin = i;
+		while (i < text.length && text[i] >= "0" && text[i] <= "9") i += 1;
+		if (i === begin) return { error: `invalid format spec ':${text}': expected width digits after '${spec.align === "left" ? "<" : ">"}'` };
+		spec.width = parseInt(text.substring(begin, i), 10);
+		if (spec.width === 0) return { error: `invalid format spec ':${text}': width must be at least 1` };
+	}
+	const pattern = text.substring(i);
+	if (pattern.length === 0) return { error: "empty format spec" };
+	const failf = (message) => {
+		return { error: `invalid format spec ':${text}': ${message}` };
+	};
+	let quoted = false;
+	let sections = 1;
+	let section_has_slot = false;
+	let section_dot = false;
+	let slots_since_comma = -1;
+	for (const c of pattern) {
+		if (quoted) {
+			if (c === "'") quoted = false;
+			continue;
+		}
+		if (c === "'") {
+			quoted = true;
+			continue;
+		}
+		if (c === ";") {
+			if (!section_has_slot) return failf("each section needs at least one digit placeholder ('0' or '#')");
+			if (slots_since_comma === 0) return failf("group commas must sit between digit placeholders");
+			sections += 1;
+			if (sections > 2) return failf("at most two ';'-separated sections");
+			section_has_slot = false;
+			section_dot = false;
+			slots_since_comma = -1;
+			continue;
+		}
+		if (c === "E" || c === "e") return failf("exponential patterns are not supported — use the ':e' spec");
+		if (c === ".") {
+			if (section_dot) return failf("at most one '.' per section");
+			section_dot = true;
+			slots_since_comma = -1;
+			continue;
+		}
+		if (c === "0" || c === "#") {
+			section_has_slot = true;
+			if (slots_since_comma >= 0) slots_since_comma += 1;
+			continue;
+		}
+		if (c === ",") {
+			if (!section_has_slot || section_dot || slots_since_comma === 0) return failf("group commas must sit between digit placeholders");
+			slots_since_comma = 0;
+			continue;
+		}
+	}
+	if (quoted) return failf("unbalanced pattern quotes");
+	if (!section_has_slot) return failf("each section needs at least one digit placeholder ('0' or '#')");
+	if (slots_since_comma === 0) return failf("group commas must sit between digit placeholders");
+	spec.pattern = pattern;
+	return { spec };
+}
 function parse_string_interpolation(status) {
 	const start = get_index(status);
 	let pattern = consume(status);
 	let values = [];
+	let specs = [];
+	let has_spec = false;
 	while (true) {
 		const value = consume(status);
 		if (value === "\\{") {
 			pattern += "\\{}";
+			const peeked = status.tokens[status.i];
+			if (peeked && FORMAT_SPEC_TOKEN.test(peeked.value)) {
+				add_error(status, `format spec '${peeked.value}' requires an expression before ':'`, peeked.i);
+				while (status.i < status.tokens.length && status.tokens[status.i].value !== "}") status.i += 1;
+				accept("}", status);
+				values.push(new ValueNode(start, "\"\"", new Type("string", true)));
+				specs.push(null);
+				continue;
+			}
 			let param = parse_expression(status);
+			let spec = null;
+			const spec_token = status.tokens[status.i];
+			if (spec_token && FORMAT_SPEC_TOKEN.test(spec_token.value)) {
+				status.i += 1;
+				const parsed = parse_format_spec(spec_token.value.substring(1), spec_token.i, status);
+				if (parsed) {
+					spec = parsed;
+					has_spec = true;
+				}
+			}
 			if (!(param.node_type === "access" && param.access.node_type === "access_func" && param.access.name === "to_string")) param = new AccessNode(start, param, new AccessFunctionCallNode(start, "to_string"));
 			values.push(param);
+			specs.push(spec);
 			accept("}", status);
 		} else if (value.endsWith("\"")) {
 			pattern += value;
@@ -74455,7 +74828,9 @@ function parse_string_interpolation(status) {
 		} else pattern += value;
 	}
 	pattern = pattern.replaceAll("\\{}", "%s");
-	return new FunctionCallNode(start, `_string_interpolate_${values.length}`, new Type("string"), [new ValueNode(0, pattern, new Type("string", true)), ...values]);
+	const call = new FunctionCallNode(start, `_string_interpolate_${values.length}`, new Type("string"), [new ValueNode(0, pattern, new Type("string", true)), ...values]);
+	if (has_spec) call.format_specs = specs;
+	return call;
 }
 //#endregion
 //#region ../src/parse/parse_switch.ts
@@ -76188,6 +76563,7 @@ function resolve_linked_types(source, library, file_path) {
 		if (user_defined.has(token.value)) continue;
 		if (library.types.has(token.value) && !BASE_TYPES.includes(token.value)) needed.add(token.value);
 		else if (library.functions.has(token.value) && !user_declared_funcs.has(token.value)) needed.add(token.value);
+		else if (token.value.length > 1 && token.value.startsWith(":") && !token.value.startsWith("::")) needed.add("Format");
 	}
 	if (tokens.some((t) => t.value === "async")) needed.add("Nursery");
 	const resolved = resolve_types_with_deps(needed, library, is_library_file ? file_path : void 0);
@@ -76599,11 +76975,18 @@ function heading_of(item) {
 	return `${item.kind} ${item.name}${generic}`;
 }
 function signature_of(fn) {
-	const params = fn.params.filter((p) => !p.is_self_param).map((p) => `${render_type(p.type)}${p.name ? " " + p.name : ""}`);
+	const params = fn.params.filter((p) => !p.is_self_param).map((p) => `${render_type(p.type)}${p.name ? " " + p.name : ""}${field_set_of(p)}`);
 	let sig = `${fn.name}(${params.join(", ")})`;
 	if (fn.return_type?.name) sig += ` -> ${render_type(fn.return_type)}`;
 	return sig;
 }
+/** The declared field set suffix (FIELD_EFFECTS.md): `{}` for "displaces
+*  nothing", `{ a, b }` for a named set, nothing for a wildcard. */
+function field_set_of(param) {
+	if (param.field_set === void 0) return "";
+	if (param.field_set.length === 0) return " {}";
+	return ` { ${param.field_set.join(", ")} }`;
+}
 function members_of(node) {
 	if (node.node_type === "struct" || node.node_type === "trait") return node.functions.filter((f) => f.visibility === "pub" && !f.name.startsWith("#"));
 	return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nomen-lang",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The CLI for the Nomen programming language.",
   "keywords": [],
   "license": "ISC",

package/src/docs.ts

@@ -6,6 +6,7 @@ import type BaseNode from "../../src/nodes/BaseNode.ts";
 import type BitsetNode from "../../src/nodes/BitsetNode.ts";
 import type EnumNode from "../../src/nodes/EnumNode.ts";
 import type FunctionNode from "../../src/nodes/FunctionNode.ts";
+import type ParameterNode from "../../src/nodes/ParameterNode.ts";
 import type StructNode from "../../src/nodes/StructNode.ts";
 import type TraitNode from "../../src/nodes/TraitNode.ts";
 import type Type from "../../src/nodes/Type.ts";
@@ -231,12 +232,20 @@ function heading_of(item: DocItem): string {
 function signature_of(fn: FunctionNode): string {
 	const params = fn.params
 		.filter((p) => !p.is_self_param)
-		.map((p) => `${render_type(p.type)}${p.name ? " " + p.name : ""}`);
+		.map((p) => `${render_type(p.type)}${p.name ? " " + p.name : ""}${field_set_of(p)}`);
 	let sig = `${fn.name}(${params.join(", ")})`;
 	if (fn.return_type?.name) sig += ` -> ${render_type(fn.return_type)}`;
 	return sig;
 }
 
+/** The declared field set suffix (FIELD_EFFECTS.md): `{}` for "displaces
+ *  nothing", `{ a, b }` for a named set, nothing for a wildcard. */
+function field_set_of(param: ParameterNode): string {
+	if (param.field_set === undefined) return "";
+	if (param.field_set.length === 0) return " {}";
+	return ` { ${param.field_set.join(", ")} }`;
+}
+
 function members_of(node: BaseNode): FunctionNode[] {
 	if (node.node_type === "struct" || node.node_type === "trait") {
 		const n = node as unknown as { functions: FunctionNode[] };