lib/os+test: export alloc + free via rt_alloc/rt_free

Add os.alloc(n: u64) *void and os.free(p: *void, n: u64) void as
`export fn` via @symbol("rt_alloc") / @symbol("rt_free"). Signatures
mirror lib/memio's existing internal bindings byte-for-byte — only
the name and `export` keyword change. lib/memio + lib/shlex + lib/
getopt drop their own copies in a follow-up commit.

Doc comment spells out the actual failure ABI: rt_alloc wraps the
raw mmap syscall (no libc), so OOM yields a negative-errno cast to
`*void` (e.g. (void*)-12 for ENOMEM). Neither `== nil` nor the libc
MAP_FAILED `(void*)-1` value catches it; deref faults. A typed
fallible variant is future work (alongside #16 fmt.asprintf).

Test (ostest test_alloc_free_roundtrip, signalled=5): alloc 4096B,
write 0x5a at head + 0xa5 at tail, read-back asserts both, free.
The head+tail write/read prevents DCE (failure path calls os.exit)
and proves a real page is backing the returned pointer.

selfhost/cmd/w6a/main.combined.ww

@@ -9,8 +9,29 @@
 @symbol("rt_syscall") fn syscall3(num: nr, a: i64, b: i64, c: i64) i64;
 @symbol("rt_syscall") fn syscall4(num: nr, a: i64, b: i64, c: i64, d: i64) i64;
 
-@symbol("rt_alloc") fn alloc(n: u64) *void;
-@symbol("rt_free")  fn free(p: *void, n: u64) void;
+// alloc / free — runtime mmap-backed page allocator. Untyped:
+// `alloc(n)` returns a `*void` and `free(p, n)` requires the byte
+// count back because rt_free is munmap-based and doesn't track
+// mapping sizes (the kernel needs the length to release the
+// reservation).
+//
+// Diverges from Hare. Hare exposes `alloc` / `free` as typed
+// language builtins (`alloc(value, cap)?` / `free(ptr)`) that the
+// compiler lowers to rt::malloc/rt::free; ww has no such builtins,
+// so the rt-symbol surface is exposed directly. Stdlib callers
+// that need a typed allocation pattern wrap this with a cast plus
+// a stored capacity (see [[strings.dup]], [[memio.dynamic]]).
+//
+// OOM: rt_alloc is a bare mmap(MAP_ANON|MAP_PRIVATE) wrapper with
+// no error path. The raw Linux mmap syscall returns a negative
+// errno cast to `*void` on failure (e.g. `(void*)-12` for ENOMEM);
+// the `MAP_FAILED` (`(void*)-1`) value is a libc-wrapper convention
+// that rt_alloc doesn't apply. Neither `== nil` nor `== (void*)-1`
+// catches it; any deref of such a return faults. Today the stdlib
+// does not check; OOM faults on first dereference. A typed
+// fallible variant is a future task.
+@symbol("rt_alloc") export fn alloc(n: u64) *void;
+@symbol("rt_free")  export fn free(p: *void, n: u64) void;
 @symbol("rt_abort") fn abort(msg: str) void;
 
 // Hare-style runtime check. Caller passes a message that's printed

selfhost/cmd/w6c/main.combined.ww

@@ -9,8 +9,29 @@
 @symbol("rt_syscall") fn syscall3(num: nr, a: i64, b: i64, c: i64) i64;
 @symbol("rt_syscall") fn syscall4(num: nr, a: i64, b: i64, c: i64, d: i64) i64;
 
-@symbol("rt_alloc") fn alloc(n: u64) *void;
-@symbol("rt_free")  fn free(p: *void, n: u64) void;
+// alloc / free — runtime mmap-backed page allocator. Untyped:
+// `alloc(n)` returns a `*void` and `free(p, n)` requires the byte
+// count back because rt_free is munmap-based and doesn't track
+// mapping sizes (the kernel needs the length to release the
+// reservation).
+//
+// Diverges from Hare. Hare exposes `alloc` / `free` as typed
+// language builtins (`alloc(value, cap)?` / `free(ptr)`) that the
+// compiler lowers to rt::malloc/rt::free; ww has no such builtins,
+// so the rt-symbol surface is exposed directly. Stdlib callers
+// that need a typed allocation pattern wrap this with a cast plus
+// a stored capacity (see [[strings.dup]], [[memio.dynamic]]).
+//
+// OOM: rt_alloc is a bare mmap(MAP_ANON|MAP_PRIVATE) wrapper with
+// no error path. The raw Linux mmap syscall returns a negative
+// errno cast to `*void` on failure (e.g. `(void*)-12` for ENOMEM);
+// the `MAP_FAILED` (`(void*)-1`) value is a libc-wrapper convention
+// that rt_alloc doesn't apply. Neither `== nil` nor `== (void*)-1`
+// catches it; any deref of such a return faults. Today the stdlib
+// does not check; OOM faults on first dereference. A typed
+// fallible variant is a future task.
+@symbol("rt_alloc") export fn alloc(n: u64) *void;
+@symbol("rt_free")  export fn free(p: *void, n: u64) void;
 @symbol("rt_abort") fn abort(msg: str) void;
 
 // Hare-style runtime check. Caller passes a message that's printed

selfhost/cmd/w6l/main.combined.ww

@@ -9,8 +9,29 @@
 @symbol("rt_syscall") fn syscall3(num: nr, a: i64, b: i64, c: i64) i64;
 @symbol("rt_syscall") fn syscall4(num: nr, a: i64, b: i64, c: i64, d: i64) i64;
 
-@symbol("rt_alloc") fn alloc(n: u64) *void;
-@symbol("rt_free")  fn free(p: *void, n: u64) void;
+// alloc / free — runtime mmap-backed page allocator. Untyped:
+// `alloc(n)` returns a `*void` and `free(p, n)` requires the byte
+// count back because rt_free is munmap-based and doesn't track
+// mapping sizes (the kernel needs the length to release the
+// reservation).
+//
+// Diverges from Hare. Hare exposes `alloc` / `free` as typed
+// language builtins (`alloc(value, cap)?` / `free(ptr)`) that the
+// compiler lowers to rt::malloc/rt::free; ww has no such builtins,
+// so the rt-symbol surface is exposed directly. Stdlib callers
+// that need a typed allocation pattern wrap this with a cast plus
+// a stored capacity (see [[strings.dup]], [[memio.dynamic]]).
+//
+// OOM: rt_alloc is a bare mmap(MAP_ANON|MAP_PRIVATE) wrapper with
+// no error path. The raw Linux mmap syscall returns a negative
+// errno cast to `*void` on failure (e.g. `(void*)-12` for ENOMEM);
+// the `MAP_FAILED` (`(void*)-1`) value is a libc-wrapper convention
+// that rt_alloc doesn't apply. Neither `== nil` nor `== (void*)-1`
+// catches it; any deref of such a return faults. Today the stdlib
+// does not check; OOM faults on first dereference. A typed
+// fallible variant is a future task.
+@symbol("rt_alloc") export fn alloc(n: u64) *void;
+@symbol("rt_free")  export fn free(p: *void, n: u64) void;
 @symbol("rt_abort") fn abort(msg: str) void;
 
 // Hare-style runtime check. Caller passes a message that's printed

selfhost/cmd/ww/main.combined.ww

@@ -9,8 +9,29 @@
 @symbol("rt_syscall") fn syscall3(num: nr, a: i64, b: i64, c: i64) i64;
 @symbol("rt_syscall") fn syscall4(num: nr, a: i64, b: i64, c: i64, d: i64) i64;
 
-@symbol("rt_alloc") fn alloc(n: u64) *void;
-@symbol("rt_free")  fn free(p: *void, n: u64) void;
+// alloc / free — runtime mmap-backed page allocator. Untyped:
+// `alloc(n)` returns a `*void` and `free(p, n)` requires the byte
+// count back because rt_free is munmap-based and doesn't track
+// mapping sizes (the kernel needs the length to release the
+// reservation).
+//
+// Diverges from Hare. Hare exposes `alloc` / `free` as typed
+// language builtins (`alloc(value, cap)?` / `free(ptr)`) that the
+// compiler lowers to rt::malloc/rt::free; ww has no such builtins,
+// so the rt-symbol surface is exposed directly. Stdlib callers
+// that need a typed allocation pattern wrap this with a cast plus
+// a stored capacity (see [[strings.dup]], [[memio.dynamic]]).
+//
+// OOM: rt_alloc is a bare mmap(MAP_ANON|MAP_PRIVATE) wrapper with
+// no error path. The raw Linux mmap syscall returns a negative
+// errno cast to `*void` on failure (e.g. `(void*)-12` for ENOMEM);
+// the `MAP_FAILED` (`(void*)-1`) value is a libc-wrapper convention
+// that rt_alloc doesn't apply. Neither `== nil` nor `== (void*)-1`
+// catches it; any deref of such a return faults. Today the stdlib
+// does not check; OOM faults on first dereference. A typed
+// fallible variant is a future task.
+@symbol("rt_alloc") export fn alloc(n: u64) *void;
+@symbol("rt_free")  export fn free(p: *void, n: u64) void;
 @symbol("rt_abort") fn abort(msg: str) void;
 
 // Hare-style runtime check. Caller passes a message that's printed

selfhost/cmd/wwdump/main.combined.ww

@@ -9,8 +9,29 @@
 @symbol("rt_syscall") fn syscall3(num: nr, a: i64, b: i64, c: i64) i64;
 @symbol("rt_syscall") fn syscall4(num: nr, a: i64, b: i64, c: i64, d: i64) i64;
 
-@symbol("rt_alloc") fn alloc(n: u64) *void;
-@symbol("rt_free")  fn free(p: *void, n: u64) void;
+// alloc / free — runtime mmap-backed page allocator. Untyped:
+// `alloc(n)` returns a `*void` and `free(p, n)` requires the byte
+// count back because rt_free is munmap-based and doesn't track
+// mapping sizes (the kernel needs the length to release the
+// reservation).
+//
+// Diverges from Hare. Hare exposes `alloc` / `free` as typed
+// language builtins (`alloc(value, cap)?` / `free(ptr)`) that the
+// compiler lowers to rt::malloc/rt::free; ww has no such builtins,
+// so the rt-symbol surface is exposed directly. Stdlib callers
+// that need a typed allocation pattern wrap this with a cast plus
+// a stored capacity (see [[strings.dup]], [[memio.dynamic]]).
+//
+// OOM: rt_alloc is a bare mmap(MAP_ANON|MAP_PRIVATE) wrapper with
+// no error path. The raw Linux mmap syscall returns a negative
+// errno cast to `*void` on failure (e.g. `(void*)-12` for ENOMEM);
+// the `MAP_FAILED` (`(void*)-1`) value is a libc-wrapper convention
+// that rt_alloc doesn't apply. Neither `== nil` nor `== (void*)-1`
+// catches it; any deref of such a return faults. Today the stdlib
+// does not check; OOM faults on first dereference. A typed
+// fallible variant is a future task.
+@symbol("rt_alloc") export fn alloc(n: u64) *void;
+@symbol("rt_free")  export fn free(p: *void, n: u64) void;
 @symbol("rt_abort") fn abort(msg: str) void;
 
 // Hare-style runtime check. Caller passes a message that's printed