ww/lib/CLAUDE.md

lib/ — Hare-shaped standard library, deliberately a subset.

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 verbatim (strings.compare, bytes.index, strconv.stoi64, io.read, path.init). Don't invent. Don't shorten. Don't reorder parameters.

Signatures are intentionally a Plan 9 / pre-tagged-union subset, because the wwstage compiler doesn't yet have ergonomic tagged-union returns or full variadic ABI:

• i32 with -1 sentinel stands in for Hare's (size | void) and (size | io::EOF). Example: bytes.indexbyte(s, c) i32 returning -1 for not-found.
• Plain str errors stand in for tagged error types (invalid, overflow, io::error). Example: strconv.parse64(s) (i64 | str) where the str is the message Hare would have tagged.
• lib/fmt is print/println-only — printf-family waits on a variadic ABI.
• Allocation-free at the boundary: where Hare returns a freshly- allocated slice, take a caller-supplied buffer. No GC, and the rt allocator is not a stable public surface yet.

Don't ship a richer surface than Hare has. A documented subset is fine; an extension, rename, or convenience-wrapper is not — return shapes will change as the compiler gains tagged unions, variadics, and a stable rt allocator, and callers should not bake the current subset shape into themselves.

When the compiler can express the full Hare signature, graduate the module — replace the -1 / str shape with the tagged-union shape in one go and fix the callers. Don't keep both around.