// vstream — Hare-shaped vtable wrappers over an fd sink. Project #94
// fold-e3 (Option C, parallel API for lib/fmt).
//
// Adds four wrappers that take a raw fd and dispatch through an
// [[io.vstream]] (= `*io.vtable`, the Hare-shape from
// lib/io/stream.ww) alongside the pre-vtable fdprint / fdprintln /
// fdprintf / fdprintfln in fmt.ww. The OLD surface stays untouched
// here — fold-eFinal (task #50) atomically flips the package shape:
// deletes the OLD wrappers + callbacks, renames `_v` suffix off, and
// migrates the few callers.
//
// Hare routes fmt's fd sinks through `io::handle = (io::file | int)`
// (ref/hare/fmt/wrappers.ha:9-25); ww doesn't have the handle sum yet
// so the pure-vstream sink — drew-deferred per fold-d/fold-e3 —
// stands in until io fold-2 lands the handle port. fd_ctx is the
// minimum carrier: one tagged field (vt) + one i32 (fd). Single-
// tagged-field shape lets direct struct-lit init through (sibling
// task #207 only bites multi-tagged-field copies); ken's escape-risk
// discipline holds — every wrapper stack-allocates fd_ctx inside its
// own frame, gets `vs = &c.vt` from the same frame, and dispatches
// without returning &c outside it.
//
// Cast workaround per #206: bare `&fn_name` does not type-check as a
// `(*<alias> | void)` field-init / let-binding. Explicit
// `(&fn_name): *io.<role>` cast at each store site is the Hare-
// faithful minimum-touch route — same workaround memio/vstream.ww
// uses (2 cast tokens here at the vtable wire-up site; both drop out
// wholesale once #206 closes).
//
// Dispatch chain (per wrapper):
//   fd{print,println,printf,printfln}_v
//     → vfprint / vfprintf (internal vstream-side formatter)
//       → io.st_write(vs, buf)
//         → vs.writer  (= fdsinkwrite_v after the cast)
//           → os.write(c.fd, ...)
//
// The internal vfprint/vfprintf duplicate the per-arg and {n}-
// placeholder loops from fmt.ww (fprint at line 177, fprintf at 676)
// because the OLD versions take `*io.stream` (the legacy struct) and
// fmt.ww must stay UNCHANGED this fold. Shared bits — `i64dec`,
// `modsinit`, `scandigits`, `scanmods`, `formattable`, `field`,
// `mods`, `fmtabort`, `signof`, `digitsu64`, `basenum`, the modifier
// enums (`neg`, `alignment`) — are reused directly from fmt.ww (same
// package). The v* modifier-formatting helpers (vrawleni64 / vrawlenstr
// / vrawlenf64 / vrawlen / vformatraw / vformatone) mirror the OLD
// rawlen* / formatraw / formatone verbatim (compute body identical;
// vputbytes + (size | io.error) routing instead of putbytes +
// (i32 | io.closed)) — #94 fold-e6 ports them V-side so V's printf
// honours modifiers (fold-e3 dropped them after parse). eFinal (#50)
// collapses both surfaces.
//
// Sibling tasks parked here (filed, NOT fixed):
//
//   - io fold-2 (handle port): drew-deferred. Hare's
//     ref/hare/fmt/wrappers.ha:9-25 routes through io::handle;
//     fdNNN_v collapses into bare fNNN_v once handle = (file | int)
//     lands and the V API graduates over the OLD per-fd surface.
//   - #206 (bare &fn → (*alias|void)): 2 cast sites here; drops
//     out wholesale on close.
//   - #173 (TRY-on-tagged-return both-stages broken): fdsinkwrite_v
//     constructs nomem and widens to io.error explicitly rather
//     than using `os.trywrite(...)?`; same shape memio.vstream.ww
//     adopted at line 71-74.

package fmt;

import io;
import memio;
import os;
import strconv;
import strings;

// fd_ctx — vt at offset 0 for the intrusive vstream→*fd_ctx cast.
// Mirrors lib/memio.fixed_ctx (memio/vstream.ww:48); single tagged
// field (vt) means the multi-tagged-field drop in #207 doesn't bite.
export type fd_ctx = struct {
	vt: io.vtable,
	fd: i32,
};

// fdsinkread_v — eof-only sink; the fd half of fmt is write-only.
// Mirrors OLD fdsinkread (fmt.ww:765). The unused-`buf` parameter
// matches io.reader's signature.
fn fdsinkread_v(s: io.vstream, buf: []u8) (size | io.eof | io.error) = {
	let e: io.eof;
	return e;
};

// fdsinkwrite_v — recover fd via intrusive cast, dispatch one
// os.write. -errno collapses to a nomem-widened io.error: the OLD
// fdsinkwrite (fmt.ww:768) flattens this to io.closed; we keep the
// Hare-shape error here because the V surface returns io.error
// directly. Construction-then-widen (vs `os.trywrite(...)?`)
// sidesteps #173 same as memio.vstream.ww (line 71-74 note).
fn fdsinkwrite_v(s: io.vstream, buf: []u8) (size | io.error) = {
	let c: *fd_ctx = s: *fd_ctx;
	let r: i64 = os.write(c.fd, buf.ptr, buf.len: u64);
	if (r < 0) {
		let nm: nomem;
		let e: io.error = nm;
		return e;
	};
	return r: size;
};

// ---- internal vstream-side formatters -------------------------------

// vputbytes — io.st_write(vs, [ptr..ptr+n)). Internal helper; the
// inline `let v` slice synthesis mirrors fmt.putbytes (fmt.ww:160)
// for the legacy *io.stream sink.
fn vputbytes(vs: io.vstream, p: *u8, n: i32) (size | io.error) = {
	let v: []u8;
	v.ptr = p;
	v.len = n;
	return io.st_write(vs, v);
};

// vwriteone — emit one formattable through io.st_write. Mirror of
// the per-arm dispatch in fmt.fdprint (fmt.ww:103-138) and fmt.fprint
// (fmt.ww:188-234); shape matches OLD modulo the (size | io.error)
// return instead of i64 / (i32 | io.closed).
fn vwriteone(vs: io.vstream, a: formattable) (size | io.error) = {
	match (a) {
	case let n: i64 => {
		let s: str = i64dec(n);
		return vputbytes(vs, s.ptr, s.len);
	};
	case let s: str => return vputbytes(vs, s.ptr, s.len);
	case let b: bool => {
		let s: str = "false";
		if (b) { s = "true"; };
		return vputbytes(vs, s.ptr, s.len);
	};
	case let r: rune => {
		let buf: [4]u8;
		buf[0] = r: u8;
		return vputbytes(vs, &buf[0], 1);
	};
	case let v: f64 => {
		// strconv.f64tos static-buffer view consumed before next
		// strconv call — same shape as fmt.fdprint (fmt.ww:130).
		let s: str = strconv.f64tos(v);
		return vputbytes(vs, s.ptr, s.len);
	};
	};
	return 0: size;
};

// ---- V-side modifier formatting (port of OLD rawlen*/formatraw/
// formatone from fmt.ww:443-641). Project #94 fold-e6.
//
// V-side mirror of the OLD modifier-formatting machinery so the V
// printf path honours width / alignment / pad / sign / base / prec
// instead of dropping mods after parse. Drew-signoff: NaN/Inf safe
// — strconv.f64tos / f32tos render "nan"/"infinity" with no leading
// '-', so the sign-peel in vrawlenf64 / vformatraw f64 arm is a
// no-op on those views (sibling of OLD rawlenf64's same path). Ken-
// signoff: cs==ww mechanical — both stages compile the new V-side
// identically; eFinal (#50) graduates the V-side over the OLD.
//
// Helpers mirror fmt.ww verbatim (compute-only, no I/O) rather than
// reusing OLD by call — fold-eFinal (#50) atomically deletes the OLD
// surface AND collapses these v* names back, so the duplication is
// transient. Mirror sites:
//
//   vrawleni64   fmt.ww:443 rawleni64
//   vrawlenstr   fmt.ww:457 rawlenstr
//   vrawlenf64   fmt.ww:569 rawlenf64
//   vrawlen      fmt.ww:585 rawlen
//   vformatraw   fmt.ww:465 formatraw
//   vformatone   fmt.ww:598 formatone

// vrawleni64 — bytes the raw render of `v` under `m` would emit; the
// signof / digitsu64 / basenum helpers are read from fmt.ww (same
// package). Mirror fmt.ww:443.
fn vrawleni64(v: i64, m: *mods) i32 = {
	let neg_flag: bool = v < 0;
	let u: u64 = v: u64;
	if (neg_flag) { u = (-v): u64; };
	let signlen: i32 = 0;
	if (signof(neg_flag, m) != 0u8) { signlen = 1; };
	let dlen: i32 = digitsu64(u, basenum(m.base));
	let inner: i32 = dlen;
	if (m.prec > signlen + dlen) { inner = m.prec - signlen; };
	return signlen + inner;
};

// vrawlenstr — bytes the raw render of `s` would emit (after `prec`
// truncation). Mirror fmt.ww:457.
fn vrawlenstr(s: str, m: *mods) i32 = {
	if (m.prec > 0 && m.prec < s.len) { return m.prec; };
	return s.len;
};

// vrawlenf64 — bytes the raw render of `v` under `m` would emit; the
// strconv.f64tos static-buffer view is consumed by reading view.len
// + view.ptr[0] before the sign byte is folded into signof. Mirror
// fmt.ww:569; drew NaN/Inf safe (strconv emits no leading '-' on
// nan/inf, so the peel is a no-op on those views).
fn vrawlenf64(v: f64, m: *mods) i32 = {
	let view: str = strconv.f64tos(v);
	let body: i32 = view.len;
	let had_neg: bool = false;
	if (body > 0 && view.ptr[0] == 45u8) {
		had_neg = true;
		body -= 1;
	};
	let signlen: i32 = 0;
	if (signof(had_neg, m) != 0u8) { signlen = 1; };
	return signlen + body;
};

// vrawlen — dispatch the rawlen sum over formattable. Mirror fmt.ww:585.
fn vrawlen(arg: formattable, m: *mods) i32 = {
	match (arg) {
	case let v: i64  => return vrawleni64(v, m);
	case let v: str  => return vrawlenstr(v, m);
	case let b: bool => { if (b) { return 4; }; return 5; };
	case let r: rune => return 1;
	case let v: f64  => return vrawlenf64(v, m);
	};
	return 0;	// unreachable — match is exhaustive
};

// vformatraw — write the bare value (no width padding) to `vs`. Mirror
// fmt.ww:465 formatraw, vputbytes-routed and (size | io.error)-typed.
// `prec` ignored on f64 (strconv.f64tos is shortest-G with no precision
// knob); base ignored on f64 (Hare too — base is int-only). Drew-
// signoff: NaN/Inf strings emitted unchanged via vputbytes.
fn vformatraw(vs: io.vstream, arg: formattable, m: *mods) (size | io.error) = {
	match (arg) {
	case let v: i64 => {
		let neg_flag: bool = v < 0;
		let u: u64 = v: u64;
		if (neg_flag) { u = (-v): u64; };
		let sb: u8 = signof(neg_flag, m);
		let total: size = 0;
		if (sb != 0u8) {
			let buf: [1]u8;
			buf[0] = sb;
			let r: (size | io.error) = vputbytes(vs, &buf[0], 1);
			match (r) {
			case let n: size => { total += n; };
			case let e: io.error => return e;
			};
		};
		let dlen: i32 = digitsu64(u, basenum(m.base));
		let signlen: i32 = 0;
		if (sb != 0u8) { signlen = 1; };
		let pad0: i32 = 0;
		if (m.prec > signlen + dlen) { pad0 = m.prec - signlen - dlen; };
		let pi: i32 = 0;
		for (pi < pad0) {
			let buf: [1]u8;
			buf[0] = 48u8;	// '0'
			let r: (size | io.error) = vputbytes(vs, &buf[0], 1);
			match (r) {
			case let n: size => { total += n; };
			case let e: io.error => return e;
			};
			pi += 1;
		};
		let view: str = strconv.u64tos(u, m.base);
		let r: (size | io.error) = vputbytes(vs, view.ptr, view.len);
		match (r) {
		case let n: size => { total += n; };
		case let e: io.error => return e;
		};
		return total;
	};
	case let v: str => {
		let n: i32 = vrawlenstr(v, m);
		return vputbytes(vs, v.ptr, n);
	};
	case let b: bool => {
		let v: str = "false";
		if (b) { v = "true"; };
		return vputbytes(vs, v.ptr, v.len);
	};
	case let r: rune => {
		let buf: [4]u8;
		buf[0] = r: u8;
		return vputbytes(vs, &buf[0], 1);
	};
	case let v: f64 => {
		// strconv.f64tos prepends '-' for negative values; peel
		// here so signof folds neg/plus/space mods uniformly with
		// the i64 arm. Drew NaN/Inf signoff: nan/infinity views
		// have no leading '-', so this peel is a no-op for them
		// (sign-mod on a nan emits e.g. "+nan" — a fmt-layer edge,
		// not strconv's; same OLD behaviour at fmt.ww:520-562).
		let view: str = strconv.f64tos(v);
		let neg_flag: bool = false;
		if (view.len > 0 && view.ptr[0] == 45u8) {	// '-'
			neg_flag = true;
			view.ptr = view.ptr + 1u64;
			view.len -= 1;
		};
		let sb: u8 = signof(neg_flag, m);
		let total: size = 0;
		if (sb != 0u8) {
			let buf: [1]u8;
			buf[0] = sb;
			let r: (size | io.error) = vputbytes(vs, &buf[0], 1);
			match (r) {
			case let n: size => { total += n; };
			case let e: io.error => return e;
			};
		};
		let r: (size | io.error) = vputbytes(vs, view.ptr, view.len);
		match (r) {
		case let n: size => { total += n; };
		case let e: io.error => return e;
		};
		return total;
	};
	};
	let z: size = 0; return z;	// unreachable — match is exhaustive
};

// vformatone — render `arg` to `vs` with `m`'s width / alignment / pad
// applied. Mirror fmt.ww:598 formatone; the tail-pad loop drives on
// a counter (mirrors OLD) because vputbytes over memio.fixed reports
// a full buffer as a 0-byte partial write, not io.error — looping on
// `total < m.width` would spin on bsprintf_v when the sink runs out.
fn vformatone(vs: io.vstream, arg: formattable, m: *mods) (size | io.error) = {
	let start: i32 = 0;
	if (m.width > 0 && m.alignment != alignment.LEFT) {
		let raw: i32 = vrawlen(arg, m);
		let pad: i32 = 0;
		if (raw < m.width) { pad = m.width - raw; };
		if (m.alignment == alignment.CENTER) { start = (pad + 1) / 2; }
		else { start = pad; };
	};
	let total: size = 0;
	let i: i32 = 0;
	let padb: [1]u8;
	padb[0] = m.pad: u8;
	for (i < start) {
		let r: (size | io.error) = vputbytes(vs, &padb[0], 1);
		match (r) {
		case let n: size => { total += n; };
		case let e: io.error => return e;
		};
		i += 1;
	};
	let r1: (size | io.error) = vformatraw(vs, arg, m);
	match (r1) {
	case let n: size => { total += n; };
	case let e: io.error => return e;
	};
	let need: i32 = 0;
	let twidth: size = m.width: size;
	if (twidth > total) { need = (twidth - total): i32; };
	let j: i32 = 0;
	for (j < need) {
		let r: (size | io.error) = vputbytes(vs, &padb[0], 1);
		match (r) {
		case let n: size => { total += n; };
		case let e: io.error => return e;
		};
		j += 1;
	};
	return total;
};

// vformatfield — field→formattable inline-per-arm dispatch through
// vformatone. The for-loop call site in vfprintf would trip task #18
// (silent miscompile of 24B return-by-value in for-loop context) if
// widened via a helper; inline-per-arm sidesteps it — same shape OLD
// formatfield uses at fmt.ww:648. `*mods` arm aborts (parametric '%'
// form not implemented; OLD fprintf aborts identically). #94 fold-e6
// widens the signature with `*mods` so the V path honours modifiers
// (fold-e3 dropped them after parse).
fn vformatfield(vs: io.vstream, f: field, m: *mods) (size | io.error) = {
	match (f) {
	case let v: i64 => {
		let a: formattable = v;
		return vformatone(vs, a, m);
	};
	case let v: str => {
		let a: formattable = v;
		return vformatone(vs, a, m);
	};
	case let b: bool => {
		let a: formattable = b;
		return vformatone(vs, a, m);
	};
	case let r: rune => {
		let a: formattable = r;
		return vformatone(vs, a, m);
	};
	case let v: f64 => {
		let a: formattable = v;
		return vformatone(vs, a, m);
	};
	case let p: *mods => { fmtabort(); let z: size = 0; return z; };
	};
};

// vfprint — vstream-side fprint. Mirror of fmt.fprint (fmt.ww:177).
// Per-arg loop with a space separator; returns total bytes written
// or the first io.error. Exported so lib/log's V API (fold-e5) can
// dispatch through it; eFinal (#50) collapses fprint over the unified
// surface.
export fn vfprint(vs: io.vstream, args: formattable...) (size | io.error) = {
	let total: size = 0;
	let i: i32 = 0;
	for (i < args.len) {
		if (i > 0) {
			let r: (size | io.error) = vputbytes(vs, " ".ptr, 1);
			match (r) {
			case let n: size => { total += n; };
			case let e: io.error => return e;
			};
		};
		let r: (size | io.error) = vwriteone(vs, args[i]);
		match (r) {
		case let n: size => { total += n; };
		case let e: io.error => return e;
		};
		i += 1;
	};
	return total;
};

// vfprintf — vstream-side fprintf. Mirror of fmt.fprintf (fmt.ww:676).
// {n}-placeholder parser routed through vformatfield + vputbytes
// instead of fmt.formatfield + fmt.putbytes; the placeholder language
// (incl. `{N:mods}` modifier subset) is identical — scandigits /
// scanmods / modsinit reused directly from fmt.ww. Exported (same
// rationale as vfprint above) so lib/log's V API dispatches through it.
export fn vfprintf(vs: io.vstream, fmt: str, args: field...) (size | io.error) = {
	let total: size = 0;
	let i: i32 = 0;
	let nextimpl: i32 = 0;
	let checkunused: bool = true;
	for (i < fmt.len) {
		let c: u8 = fmt[i];
		if (c == 123u8) {	// '{'
			i += 1;
			if (i >= fmt.len) { fmtabort(); };
			if (fmt[i] == 123u8) {	// '{{' literal
				let r: (size | io.error) = vputbytes(vs, fmt.ptr + i: u64, 1);
				match (r) {
				case let n: size => { total += n; };
				case let e: io.error => return e;
				};
				i += 1;
			} else {
				let idx: i32 = 0;
				let d: u8 = fmt[i];
				if (d >= 48u8 && d <= 57u8) {
					checkunused = false;
					idx = scandigits(fmt, &i);
				} else {
					idx = nextimpl;
					nextimpl += 1;
				};
				let m: mods;
				modsinit(&m);
				if (i < fmt.len && fmt[i] == 58u8) {	// ':'
					i += 1;
					scanmods(fmt, &i, &m);
				};
				if (i >= fmt.len || fmt[i] != 125u8) { fmtabort(); };
				i += 1;
				if (idx >= args.len) { fmtabort(); };
				let r: (size | io.error) = vformatfield(vs, args[idx], &m);
				match (r) {
				case let n: size => { total += n; };
				case let e: io.error => return e;
				};
			};
		} else if (c == 125u8) {	// '}'
			i += 1;
			if (i >= fmt.len || fmt[i] != 125u8) { fmtabort(); };
			let r: (size | io.error) = vputbytes(vs, fmt.ptr + i: u64, 1);
			match (r) {
			case let n: size => { total += n; };
			case let e: io.error => return e;
			};
			i += 1;
		} else {
			let r: (size | io.error) = vputbytes(vs, fmt.ptr + i: u64, 1);
			match (r) {
			case let n: size => { total += n; };
			case let e: io.error => return e;
			};
			i += 1;
		};
	};
	if (checkunused && nextimpl != args.len) { fmtabort(); };
	return total;
};

// ---- public fd-sink wrappers (V API) ---------------------------------

// fdprint_v — fdprint over io.vstream. Stack-allocates fd_ctx; the
// &c.vt vstream pointer never escapes this frame (ken's escape-risk
// discipline). Mirrors fmt.fdprint (fmt.ww:94).
export fn fdprint_v(fd: i32, args: formattable...) (size | io.error) = {
	let c: fd_ctx;
	c.fd = fd;
	c.vt.reader = (&fdsinkread_v):  *io.reader;
	c.vt.writer = (&fdsinkwrite_v): *io.writer;
	let vs: io.vstream = &c.vt;
	return vfprint(vs, args...);
};

// fdprintln_v — fdprint_v + trailing newline. Mirrors fmt.fdprintln
// (fmt.ww:145).
export fn fdprintln_v(fd: i32, args: formattable...) (size | io.error) = {
	let c: fd_ctx;
	c.fd = fd;
	c.vt.reader = (&fdsinkread_v):  *io.reader;
	c.vt.writer = (&fdsinkwrite_v): *io.writer;
	let vs: io.vstream = &c.vt;
	let total: size = 0;
	match (vfprint(vs, args...)) {
	case let n: size => { total = n; };
	case let e: io.error => return e;
	};
	match (vputbytes(vs, "\n".ptr, 1)) {
	case let n: size => { total += n; };
	case let e: io.error => return e;
	};
	return total;
};

// fdprintf_v — fdprintf over io.vstream. Mirrors fmt.fdprintf
// (fmt.ww:786).
export fn fdprintf_v(fd: i32, fmt: str, args: field...) (size | io.error) = {
	let c: fd_ctx;
	c.fd = fd;
	c.vt.reader = (&fdsinkread_v):  *io.reader;
	c.vt.writer = (&fdsinkwrite_v): *io.writer;
	let vs: io.vstream = &c.vt;
	return vfprintf(vs, fmt, args...);
};

// fdprintfln_v — fdprintf_v + trailing newline. Mirrors
// fmt.fdprintfln (fmt.ww:797) and Hare's wrappers.ha:69.
export fn fdprintfln_v(fd: i32, fmt: str, args: field...) (size | io.error) = {
	let c: fd_ctx;
	c.fd = fd;
	c.vt.reader = (&fdsinkread_v):  *io.reader;
	c.vt.writer = (&fdsinkwrite_v): *io.writer;
	let vs: io.vstream = &c.vt;
	let total: size = 0;
	match (vfprintf(vs, fmt, args...)) {
	case let n: size => { total = n; };
	case let e: io.error => return e;
	};
	match (vputbytes(vs, "\n".ptr, 1)) {
	case let n: size => { total += n; };
	case let e: io.error => return e;
	};
	return total;
};

// ---- V-side compositions over the vfprint / vfprintf primitives.
// Project #94 fold-e7. drew-approved bundle (memio.string_v is the
// collapsed single accessor over the common `stream` header — direct
// enabler, not churn — feedback_refactor_routing_same_class_drops);
// ken cs==ww mechanical
// (additive only). eFinal (#50) collapses both surfaces and renames
// `v` suffix off.
//
// Mirror sites:
//   vfprintln    fmt.ww:240 fprintln          ref/hare/fmt/wrappers.ha:48
//   vfprintfln   fmt.ww:740 fprintfln         ref/hare/fmt/wrappers.ha:69
//   vbsprintf    fmt.ww:839 bsprintf          ref/hare/fmt/wrappers.ha:42
//   vasprintf    fmt.ww:873 asprintf          ref/hare/fmt/wrappers.ha:29

// vfprintln — vfprint + trailing newline. Mirror fmt.fprintln
// (fmt.ww:240); vputbytes + (size | io.error) routing.
export fn vfprintln(vs: io.vstream, args: formattable...) (size | io.error) = {
	let total: size = 0;
	match (vfprint(vs, args...)) {
	case let n: size => { total = n; };
	case let e: io.error => return e;
	};
	match (vputbytes(vs, "\n".ptr, 1)) {
	case let n: size => { total += n; };
	case let e: io.error => return e;
	};
	return total;
};

// vfprintfln — vfprintf + trailing newline. Mirror fmt.fprintfln
// (fmt.ww:740).
export fn vfprintfln(vs: io.vstream, fmt: str, args: field...) (size | io.error) = {
	let total: size = 0;
	match (vfprintf(vs, fmt, args...)) {
	case let n: size => { total = n; };
	case let e: io.error => return e;
	};
	match (vputbytes(vs, "\n".ptr, 1)) {
	case let n: size => { total += n; };
	case let e: io.error => return e;
	};
	return total;
};

// vbsprintf — render into `buf` through memio.fixed_vstream; return
// the str view of bytes actually written. Mirror fmt.bsprintf
// (fmt.ww:839). memio.fixed_vstream now returns the `stream` BY VALUE
// (fold-eFinal PREP, ref/hare/memio/stream.ha:46) — no alloc, no
// `nomem` arm. The stream lives in this frame; `&st.vt` is the
// io.vstream and `&st` the accessor handle. Hare wrappers.ha:42 returns
// `(const str | nomem)`; ww collapses to (str | io.error) so the
// vfprintf path's io.error arm stays uniform. Short writes surface as a
// prefix (memio.fixed contract, vstream.ww fixedwrite note).
export fn vbsprintf(buf: []u8, fmt: str, args: field...) (str | io.error) = {
	let st: memio.stream = memio.fixed_vstream(buf);
	let vs: io.vstream = &st.vt;
	match (vfprintf(vs, fmt, args...)) {
	case let n: size => { return memio.string_v(&st); };
	case let e: io.error => return e;
	};
};

// vasprintf — render `fmt`/`args` into a heap-allocated str through
// memio.dynamic_vstream, shrink-copy to a tight allocation, close the
// dynamic backing. Mirror fmt.asprintf (fmt.ww:873) modulo: bare `str`
// return (Hare returns `(str | nomem)`; ww has no `nomem` variant on
// the public surface — os.alloc faults on OOM per lib/os.ww). Caller
// frees with `os.free(r.ptr, r.len: u64)` when r.len > 0; r.len == 0
// is a no-op free (same shape strings.dup uses at strings.ww:70).
// Shrink-to-fit rationale: memio.dynamic_vstream's cap doubles past
// pos during growth (memio dynamicgrow_v); io.st_close frees the
// cap-sized mapping. Returning memio.string_v directly would
// leak the cap-vs-len slack (skip close) or dangle the view (close
// first); the copy lets the caller free with r.len.
export fn vasprintf(fmt: str, args: field...) str = {
	let out: str;
	out.ptr = nil;
	out.len = 0;
	// memio.dynamic_vstream returns the `stream` BY VALUE (fold-eFinal
	// PREP, ref/hare/memio/stream.ha:58) — no alloc, no `nomem` arm.
	// The stream lives in this frame across the vfprintf + close; the
	// heap-grown backing (st.ptr) is freed by io.st_close.
	let st: memio.stream = memio.dynamic_vstream();
	let vs: io.vstream = &st.vt;
	let wres: (size | io.error) = vfprintf(vs, fmt, args...);
	match (wres) {
	case let n: size => {};
	case let e: io.error => {};
	};
	let view: str = memio.string_v(&st);
	if (view.len == 0) {
		let cres: (void | io.error) = io.st_close(vs);
		match (cres) { case void => {}; case let e: io.error => {}; };
		return out;
	};
	let tight: []u8 = alloc([], view.len: u64)!;
	let i: i32 = 0;
	for (i < view.len) {
		tight[i] = view.ptr[i];
		i += 1;
	};
	let cres: (void | io.error) = io.st_close(vs);
	match (cres) { case void => {}; case let e: io.error => {}; };
	tight.len = view.len;
	return strings.frombytes(tight);
};