ww/lib/CLAUDE.md

lib/ — Hare-shaped standard library.

Scope: every lib/* directory except lib/ww/, which is the compiler frontend port and has its own rules (see lib/ww/CLAUDE.md).

Names mirror Hare. Before adding a function, find its counterpart in ref/hare/<module>/ and copy the name — drop Hare's underscores per plan 9 style (trim_prefix → trimprefix, next_token → nexttoken). Don't invent. Don't shorten further. Don't reorder parameters.

Signatures mirror Hare too, modulo:

• Tagged-union returns are spelled with the ww ! error tag where Hare uses !void / !T, and indices use the underlying length type (i32 under root CLAUDE.md rule 9). Example: strconv.stoi64(s: str, b: strconv.base) (i64 | invalid | overflow) — same shape as Hare's. The base parameter is the named enum strconv.base (Hare uses enum uint; we pick enum i32 to match the index type).

• Static-buffer str returns where Hare uses them. strconv.*tos returns a const str view into a module-level buffer that is overwritten on the next call to the same function. Callers that need the bytes to outlive the next call duplicate via strings.dup. Functions that genuinely allocate a fresh buffer (strings.dup, strings.concat) still return an owned str that callers free via os.free(r.ptr, r.len: u64).

• Call-site variadic sugar matches Hare. fn f(args: T...) declares a Hare-style variadic; call sites either gather N args into a fresh []T (fmt.println(42, "hi", true)) or forward an existing slice with xs... (fprintln(h, args...)). The bare T... form in tagged unions still means spread-flatten ((...inner | E)); the two uses don't overlap because T... only attaches to a param decl. lib/fmt ships both the print family (print / println / fprint / fprintln) and the {n}-placeholder family (printf / fprintf / bsprintf / fatalf), including Hare's %-parametric *mods form.

• (T | U) sum-typed parameters dispatch via match inside the callee. strings.byteindex(haystack: str, needle: (str | rune)), bytes.index(s: []u8, needle: (u8 | []u8)), and rbyteindex/ rindex follow Hare's shape directly. strings.index/rindex expose rune positions; byteindex/rbyteindex expose byte offsets. UTF-8 iterators and both indexing axes are shipped and tested.

Don't ship a richer surface than Hare has. A documented subset is fine; an extension, rename, or convenience-wrapper is not — callers should not bake the current subset shape into themselves.

Modules with intentional divergence:

• lib/os and lib/net stay below the Hare abstraction — they are syscall wrappers, not the high-level io::handle / net::socket API. Use them as the foundation that lib/io and the buffered layers build on. lib/os also plays Hare's sys role (ww folds sys into os), so it is the import floor: lib/os must never import io OR errors — everything points down to os; os's only edge is the import-free time leaf. This is what lets errors import os (for os.errno / os.strerror) without a cycle, mirroring Hare's sys ← errors, sys ← io.
• lib/io keeps the ww-specific intrusive vtable stream (function pointers, no closures or methods) and collapses Hare's extra stream pointer layer. Its handle is the shipped (file | stream) sum.
• lib/bufio ships Hare-shaped buffered-stream and scanner subsets; the exact supported operations and ownership rules are documented in its source header. lib/sort still awaits its Hare cmpfunc shape.
• lib/time and lib/math ship only what callers need today; they're not aiming for parity yet.

When the compiler can express a Hare signature that's still in the ww-specific shape (e.g., once a module-level *u8 is mutable, the strconv *tos family graduates to static-buffer returns), graduate the module in one go — replace the current shape with the Hare shape and fix the callers. Don't keep both around.