Standard library

Bundled with the toolchain, no separate install required. This document describes the current stdlib surface. Milestone / phase history lives in…

Reference material, synced from the compiler repo’s spec/. The guide is the gentler path in.

Bundled with the toolchain, no separate install required. This document describes the current stdlib surface. Milestone / phase history lives in ../CHANGELOG.md.

.hl source references stdlib symbols by fully-qualified path:

let p = std::process::pid();
let contents = std::io::fs::read_file("config.toml");
std::io::tcp::Listener { host: "127.0.0.1", port: 8080 };

The parser tokenizes :: as a path separator. The type checker resolves std::* paths that name Hale-source stdlib declarations to their real nominal types (GH #470 — literals, fields, methods, and interface coercions check like user code, and a std:: literal that matches nothing is an error); remaining namespaced paths (Rust-implemented builtins) type permissively, with their path-call names validated against the stdlib surface registry. A path-call carrying a row in that registry’s signature table also checks its arity, its argument types and its RETURN type, and every function the compiler lowers natively or through a named Hale body has one: the signature its lowering enforced (F.40 phase 4, S6; before, 118 had none, so any arguments passed hale check and a wrong count or type failed at build, without a location). The seven std::io::mirror cursor primitives are signed with the arguments their lowering reads, so a call with more is refused by hale check, where lowering ignored the rest. A function the rename table maps onto a Hale body is checked against that body’s own signature. The return may itself be a stdlib struct (GH #771): a std::json::string_field(...) is a std::json::JsonString, so a misspelled field on the result is a located error naming the public path, and passing the result where a String is expected is refused. A row also says whether the function can fail, and every function lowering lowers only under an or has a row that does (F.40 phase 4, S5): the std::io::tcp and std::io::tls timeout and option setters (set_recv_timeout, set_send_timeout, and tls’s set_nodelay and set_rx_timestamps) and the __ primitives the stdlib’s own File, udp and Child wrappers call (std::io::file::__open / __seek / __write_bytes, std::io::udp::__bind / __send / __recv, the seven std::process::__* primitives) all fail with IoError, so a bare call of one is the located bare-fallible error from hale check (spec/semantics.md § “A bare fallible call is an error”), where lowering used to refuse it without a span or answer “not implemented”. Lowering keeps no list of its own: whether it refuses a stdlib call is that same row. The check refuses a bare call of a function whose row can fail, and an or over one whose row cannot; the one such call that still reaches the build is an or over one of those unsigned functions, or over one whose success the table cannot state (std::bytes::builder::__view / __text_view, a view; the check types both permissively), which the build refuses with “is not a fallible call — remove the or clause” (some used to read “or over unknown path call”). A stdlib function written in Hale (a body the stdlib’s rename table names, like std::process::adopt or the std::io::file wrappers) is called like any fn: a statement drops what it returns, and one that returns nothing can be called as a statement and only there (F.40 phase 4, S5: before, only adopt could, through a branch of lowering’s own). An ARGUMENT position names a stdlib type the same way (GH #829): recv_into’s buf is a std::bytes::BytesBuilder, the one type its lowering accepts, so std::io::tcp::recv_into(fd, 0, 64) is a located error at the argument instead of a spanless codegen refusal. Only a path-call with no row at all — or a row whose parameter is deliberately polymorphic, like the user @form(vec) destination of std::str::split_into — types permissively, as does an argument whose own type the checker cannot see; incompleteness therefore degrades to the historical tolerance, never to a false error. Lowering resolves a std::* path through the function’s row (the stdlib_surface family): the row names an intrinsic id, a Hale body, a rename, or nothing, and one exhaustive match on the id lowers the call at each position.

Some operations are bare builtins rather than stdlib functions (len, to_string, abs, min, max, the printers — grammar intrinsics, see types.md). A path that is a conventional spelling of one of those — std::str::len, std::string::length, std::math::abs, std::cmp::min, std::io::println and their siblings — is answered with that builtin’s call shape (the length of a String is the builtin `len(s)` ) rather than an edit-distance guess, as is the member spelling s.len() / s.length / s.size on a String or Bytes (GH #722). Every other unknown name keeps the plain unknown-function or unknown-namespace diagnostic: an operation with no builtin equivalent is never pointed anywhere.

There is no general module system at v1 — no use statements, no user-defined modules, no multi-file .hl packages via the std-style mechanism. std::* is the only recognized prefix. Adding a new stdlib function means: one row in SURFACES (crates/hale-types/src/stdlib_surface.rs: its signature, effect classes, fallibility and how it lowers), its IntrinsicId variant, an arm in lower_std_intrinsic and one in lower_std_intrinsic_fallible (the compiler refuses a missing arm), its libc backer in declare_builtins and the C function, a program that calls it (the coverage gate fails without one), the table-answers golden, this document’s row and the book’s.

Cross-binary user code uses the F.25 cross-seed-imports mechanism (import "path/to/lib" as alias;) — distinct from the std::* magic path; see decisions.md § F.25.

• Batteries included. Go’s approach: if a typical Hale program needs it, it ships. A new Hale user shouldn’t need third-party packages for table-stakes coordinator-system work.
• One canonical implementation. Per Go’s “one obvious way”: one std::collections::Map, not seven. Multiple options live in third-party packages.
• Framework-aware. Stdlib types use the language’s projection classes, modes, and closure tests where appropriate. The stdlib is itself disciplined.
• Replaceable. Anything in stdlib can be replaced by a third-party module; nothing in stdlib is tied into the compiler.

std::* is the curated path for ships-with-the-compiler bindings (libc + OpenSSL only at the link floor). User-extensible C-ABI bindings live outside this surface — see spec/ffi.md for @ffi("c") declarations, the mechanism by which library authors land bindings to third-party C libraries (raylib, sqlite, curl, …) in community repos like pond. The stdlib’s narrow link surface is preserved exactly because user code can extend the FFI surface without touching the compiler.

Hale doesn’t use parametric stdlib collection types (Map<K, V>, Vec<T>, Set<T>, etc.). Storage is locus-shaped via the @form(...) annotation machinery — see forms.md. v1 ships @form(vec) (contiguous-buffer), @form(hashmap) (intrusive open-addressing, String / Int keys), and @form(ring_buffer) (fixed-capacity FIFO).

Bytes and std::bytes::BytesBuilder are deliberately distinct types because their runtime ABIs are incompatible:

• Bytes blob. Single contiguous allocation: [i64 len][u8 data[len]]. The handle points at the length prefix. lotus_bytes_len(b) reads *(int64_t*)b. lotus_bytes_at(b, i) reads ((u8*)b)[8 + i]. Stable across the value’s lifetime.
• BytesBuilder locus. Owns a lotus_bytes_builder_t header {cap, buf, mutation_epoch} whose body lives in a separately malloc’d region pointed to by buf and can move on realloc (the header is stable; the body is not).

The two ABIs cannot be unified without giving up stable handles (the body has to be relocatable; the Bytes blob layout doesn’t tolerate that). Lifting the builder into its own locus type turns std::bytes::at(builder, i) into a typecheck error rather than the silent footgun it was when the builder shared the Bytes static type.

The discipline that follows:

1. Pick one role per binding. A binding is either a BytesBuilder (long-lived growable buffer with methods append (chunk: Bytes) / append_str (s: String — append the string’s bytes verbatim in one strlen + memcpy; String only, a non-NUL-terminated StringView must be materialized first) / len / shift_front / clear / snapshot / finish / view / text_view, plus the binary-pack writers below) or a Bytes (immutable length-prefixed blob with functions at / slice / len / concat). The typechecker enforces this; no implicit coercion between them.

   Binary-pack writers (2026-06-06, shm-ring-interop Proposal A — the inverse of std::bytes::read_*): b.append_u8(n), b.append_u16_{le,be}(n) / u32 / u64, the signed b.append_i8/i16_{le,be}/i32/i64 (identical byte pattern — width is what matters), b.append_f32_le(x) / b.append_f64_{le,be}(x) (x: Float), and b.append_pad(to_align) (zero-fill to the next to_align boundary). Each appends the low width bytes in the named endianness; a realloc failure routes through violate alloc_failed like append.

2. Cross between roles via explicit calls. BytesBuilder → Bytes is either b.snapshot() (copies into the bus payload arena — stable across mutations) or b.view() (no copy, aliases the builder’s buffer — valid until the next mutation; the right choice for parser passes). Bytes → BytesBuilder is let b = std::bytes::BytesBuilder { ... }; b.append(bytes) (copies). The Builder → Bytes direction has a zero-cost path via view(); the reverse does not. snapshot() and finish() are -> Bytes fallible(ClosureViolation) (F.42): a failed allocation violates alloc_failed, the owner’s on_failure runs, and the call fails, so each call carries an or (b.snapshot() or raise where the activation should not go on). view() and text_view() allocate nothing and are not fallible.

3. Long-lived accumulators live as locus state. Either a method-body let-binding (dissolves at scope exit) or a param-typed field on the owning service locus (dissolves via the F.29 cascade at the parent’s dissolve). Method-body let is simpler when the lifetime fits in one method call; field-typed is needed when the buffer must outlive a single call (e.g., state held across bus subscription callbacks).

4. Read syscalls write directly into the builder. The recv_into family takes a BytesBuilder as buf and writes into its tail. Combined with b.shift_front after each peeled frame (streaming) or b.clear() at message boundaries (per-message accumulator), the steady-state recv loop is zero-alloc against g_bus_payload_arena.

Canonical pattern, a held-open socket locus that accumulates inbound frames:

locus FrameClient {
  params { sock: Int = -1; recv_chunk: Int = 4096; }
  run() {
    let rx_buf = std::bytes::BytesBuilder {
      initial_cap: 4096,
    };
    loop {
      let got = std::io::tcp::recv_into(
        self.sock, rx_buf, self.recv_chunk);
      if got <= 0 { break; }
      // peel complete frames off the front via rx_buf.len() /
      // rx_buf.shift_front(consumed); for a per-frame snapshot
      // use rx_buf.snapshot() only at the point of handoff to
      // logic that needs a Bytes view (parsers that read via
      // std::bytes::at / slice).
    }
    // rx_buf dissolves here → buffer freed, no explicit cleanup
  }
}

Try writing std::bytes::at(rx_buf, 0) inside that loop — it fails at typecheck (at expects Bytes, got __StdBytesBytesBuilder). The discipline is mechanical, not documentary.

The same pattern with the builder held as locus state (per F.29), for cases where the accumulator must survive across multiple method calls (bus callbacks, message state held between handler firings):

locus WsClient {
  params {
    sock: Int = -1;
    recv_chunk: Int = 4096;
    rx_buf:   std::bytes::BytesBuilder
            = std::bytes::BytesBuilder { initial_cap: 4096 };
    last_msg: std::bytes::BytesBuilder
            = std::bytes::BytesBuilder { initial_cap: 4096 };
  }
  fn read_one() {
    let got = std::io::tcp::recv_into(
      self.sock, self.rx_buf, self.recv_chunk);
    // ... peel frames, append payload bytes into self.last_msg
    // via self.last_msg.clear() + .append(...) between message
    // boundaries — no per-frame allocation.
  }
  // No dissolve() needed for rx_buf / last_msg — the cascade
  // fires their dissolve when WsClient itself dissolves.
}

Consumer reads self.last_msg via a contract that exposes b.view() — zero-copy across the F.14 interface.

A String is a NUL-terminated blob with no stored length, and the operations a hand-written parser reaches for first are the O(n) ones. The costs below are the shipped ones, measured on a 1 MiB input (GH #720):

So the natural bounded-parser loop is quadratic:

let mut i = 0;
while i < len(s) {            // hoisted, but see above
    let c = s[i..(i + 1)];    // O(n) EVERY iteration
    i = i + 1;
}

and the view is the linear form of the same loop, with the bound kept in a register and every read checked against it:

let v = std::str::bytes_view(s);   // one strlen + one copy
let mut i = 0;
while i < v.n {
    let c = std::str::byte_at(v, i);   // 0..255, or -1 if out of range
    if c == 44 { … }                   // 44 = ','
    i = i + 1;
}

Measured on the same 1 MiB input: 13.2 s → 29 µs for the scan (the loop vectorizes, because the bound is loop-invariant), and the whole program including construction runs in 2 ms. At 1 / 2 / 4 MiB the scan costs 29 / 57 / 114 µs — linear, pinned by byte_view_scan_scales_linearly in crates/hale-codegen/tests/stdlib_str.rs.

Three properties the surface commits to:

1. Refusal, not UB. byte_at answers -1 for any i outside [0, n) and slice clamps into [0, n], so a truncated frame or an attacker-supplied length field yields short data rather than a read past the end. A length taken from untrusted input needs no validation before it reaches slice.
2. Bytes, not characters. n is a byte count, byte_at returns one byte, and slice can cut a multi-byte sequence in half. That is the right default for protocol and format work (every delimiter, digit and quote is one byte in UTF-8, and a continuation byte is never mistaken for one). When the unit of meaning is a character, walk with std::str::cp_at / cp_size, which refuse mid-sequence offsets with -1.
3. The view’s n is the bound. It comes from bytes_view, which is why the checks can be one compare. A view fabricated by hand with an n larger than its text is the one way to get past them (the byte_at byte-is-NUL guard still stops a sequential scan at the real end).

std::str::byte_at_unchecked stays for the case where the bound is already proven by the surrounding scan — the stdlib JSON range-walkers use it — and keeps its “misuse is UB” contract.

Hale doesn’t have panic(msg), assert(cond), or any other value-level “bail from this function” primitive. Failure is structural, not parametric:

1. Declare a closure in the relevant locus asserting the invariant you want enforced.
2. When the assertion fails at the closure’s epoch, the runtime constructs a ClosureViolation and routes it to the parent’s on_failure handler per F.9.
3. The parent picks one of restart / restart_in_place / quarantine / reorganize / bubble, or absorbs the violation by returning without calling any of them.
4. A violation that bubbles past main exits the process non-zero with the violation report on stderr.

That covers every legitimate use of panic. “Impossible state” becomes “a closure asserting state is possible.” “Bail from this function” is a category error in Hale — functions return values; failure lives at the locus level.

Writing panic("…") anyway is an ordinary unbound callee: hale check <directory> reports call to `panic`: no free fn, generic fn or fn-pointer binding with that name is in scope at the call. Until GH #800 the name sat in the checker’s bare-builtin exemption table, so check accepted it and only hale build objected, at lowering, without a source location.

Beyond the explicit std::* namespace, the resolver injects form-specific error payload types into the top scope when any locus in the bundle uses the corresponding form. These behave like ordinary user types after injection — they can be the target of fallible(...), declared as fn parameters / fields, or pattern-matched in match. They are NOT importable via std::* (they’re not in a namespace); their names live at the top level.

Idempotency: if a user / library declares a type with the same name, the user declaration wins. The injection only runs if the target name isn’t already in scope.

std::io::fs::* (except file_exists) and the path-call surface of std::io::tcp::* (listen_socket, connect, accept_one) return fallible(IoError). Agents address failures uniformly:

let s = std::io::fs::read_file(path) or raise;
let n = std::io::fs::file_size(path) or 0;
std::io::fs::mkdir(out_dir) or show(err);

The kind tag is errno-derived — "not_found", "permission_denied", "is_dir", "already_exists", "would_block", "connection_refused", "timeout", "host_unreachable", "broken_pipe", "interrupted", etc., with "io" as the catch-all for unmapped codes. errno carries the raw platform errno for callers that want it; path carries the file path / connection target / empty string for socket-fd ops without a useful path label.

Stream.send / Stream.send_bytes / Stream.recv / Stream.recv_bytes are locus methods on std::io::tcp::Stream, all fallible(IoError) since 2026-07-15 (#209; they previously used a legacy -1/0-sentinel shape predating open-question #24 lifting the “no fallible on locus methods” restriction). Semantics: send(msg: String) / send_bytes(b: Bytes) succeed with Unit (the old Int return was only ever a 0/-1 status), so fire-and-forget callers write s.send(x) or discard; and strict ones or raise. recv(max) -> String / recv_bytes(max) -> Bytes fail only on a genuine I/O error (connection reset, broken pipe, bad fd, …): a clean EOF and a set_recv_timeout expiry both return the empty value as before — timeout is a liveness signal, not an error. The error path is built from the errno the primitive records in a thread-local (__last_io_status / __io_error_kind, the same taxonomy the fallible path-calls use). IoError itself is now declared in the stdlib seed (io_tcp.hl), so user code can construct / fail it directly. std::io::stdin::read_line keeps its sentinel shape (path-call pairing with read_line_status for EOF-vs-error distinction).

Stream fd ownership (owns_fd: Bool = true). By default a Stream owns its conn_fd and closes it on dissolve — the contract the Listener / http::Server accept-loop helpers rely on for per-connection cleanup (__handle_one_connection wraps the accepted fd in a Stream whose scope-exit dissolve closes it). Set owns_fd: false to borrow an fd owned elsewhere: a transient Stream { conn_fd: self.conn_fd, owns_fd: false } built only to call send/recv against a long-lived connection. A borrowed Stream’s dissolve is a no-op (no __close_fd, no close LogEvent), so building one per operation against a persistent connection — e.g. a WebSocket conn locus that wraps its fd per frame — no longer closes the shared fd out from under the next operation. Owning a fd from two live Streams at once is still a double-close bug; owns_fd: false is precisely the opt-out for the borrow case.

std::str::parse_int(s) / parse_float(s) / parse_decimal(s) return fallible(ParseError). The non-fallible siblings exist only as can_parse_* predicate spellings; every parsing call site must address the failure with or. ParseError carries:

• kind: String — "empty" (s was ""), "trailing_chars" (s parsed a prefix and had junk after), "invalid" (no leading numeric prefix), "overflow" (parse_int only — magnitude exceeds Int range).
• input: String — the original s (truncated to a reasonable preview if very long), for diagnostic surfaces.

let n = std::str::parse_int(s) or 0;
let n = std::str::parse_int(s) or raise;
let n = std::str::parse_int(s) or self.report(err);

Reach for the predicate sibling can_parse_int(s) -> Bool only when you genuinely want to branch before parsing. In most cases or is shorter.

The qualified form std::str::ParseError resolves to the same struct as bare ParseError — useful in projects that also declare a local error type with the same name.

Returns the calling process’s peak resident-set size in bytes via getrusage(RUSAGE_SELF). There’s no syscall for current RSS that doesn’t go through /proc/self/statm; for alarm thresholds peak is usually what matters anyway. Returns 0 if getrusage rejects (vanishingly rare). On Linux the underlying value is reported in KiB and we multiply by 1024.

let bytes = std::process::rss_bytes();
println("rss=", to_string(bytes));

A spawned process inherits its parent’s peak. execve does not reset ru_maxrss: fork hands the child a copy-on-write duplicate of the parent’s address space, so the pre-exec child’s RSS high-water mark is the parent’s RSS, and the exec folds that mark into the new image’s ru_maxrss for the life of the process. A program started by a large parent therefore reports at least that parent’s RSS forever after — measured, one unmodified binary reads 4.7 MB standalone and 411 MB when spawned from a parent holding 400 MB. rss_bytes() is a peak for a process that owns its own history (a service started by an init system, a CLI run from a shell); it is not a way to measure a child you spawned, and a supervised worker’s reading carries its supervisor’s footprint.

For the current RSS — and for any measurement that must be the program’s own — parse /proc/self/statm’s line one field two via read_file (size-tolerant for synthesized files); that file is read from the post-exec address space and carries none of the inherited history. Both surfaces ship; pick by use case (peak for alarms on a top-level process, current for heartbeat gauges and for anything spawned).

A listener — a std::http::Server, a std::io::tcp::Acceptor or a std::io::tcp::Listener — is stopped by shutting its listening socket down (shutdown(SHUT_RDWR)): its blocked or parked accept returns an error, the accept loop ends, and dissolve() does the close(). The wake has to be the syscall: a pinned listener blocked in accept(2) services no mailbox, so a stop delivered over the bus would wait for the next connection.

std::io::tcp::stop(name: String) -> Bool stops the listener the process knows by name (its name param; a listener enters its name when it is born and leaves when its socket is closed, 64 listeners a process). A listener’s name is unique. A listener binds in its birth() and then takes its name: the name it was given, or, left empty, the host and the port the socket is actually bound to (127.0.0.1:<port>, the kernel’s pick for port: 0, so two port: 0 servers are two names and two routes). The name it goes by is its listener field. An explicit name another live listener holds is the listener’s name_taken violation at birth, with its socket closed before anything runs. A listener whose birth failed holds no subscription that matches a live route: a Server builds its consumer in birth(), on the route of its final name, only once the name is its own, and its relay closes nothing until then — so a refused server can never shadow another listener’s catch-unmatched close. Because birth binds, restart(server) binds afresh (a supervisor that corrected host, a port that came free), closing the socket a previous birth left. It is a free call, pool-neutral, so a checked program stops a listener on another pool with it — where a method call across pools is refused (F.31’s single-threaded-method invariant, spec/types.md). true when a listener had the name:

main locus App {
    params {
        web: std::http::Server = std::http::Server { port: 8080, name: "web", handler: Routes { } };
    }
    placement { web: cooperative(pool = web) where async_io; }
    run() {
        while !self.draining { std::time::sleep(20ms); }
        std::io::tcp::stop("web");
    }
}

Server.shutdown() does the same from the Server’s own thread (a locus on its pool, or a test harness that runs no checker).

The accept loop treats any negative accept_one return as a clean shutdown signal, so even degenerate fd closes (external fd-closes, etc.) terminate gracefully.

Shutdown is a drain, never a cut. Once the Server’s accept loop ends — stop, shutdown(), or max_accepts reached — its run() returns only after every connection it accepted has been answered, so dissolve() never tears down a connection mid-request. Inline (one at a time) that is the connection being served; on an async_io pool it is every connection in flight, each finishing its handler and its write. A connection is bounded by its 5 s recv timeout while it reads and by the handler’s own time after that. The drain is the Server’s: a program that ends (its main locus’s run() returns, the pool workers are joined) while connections are still in flight ends them with the process, unanswered — wait for them before returning when they must be answered. (Under SIGTERM the process drain also ends the sleeps a handler was in when it began, spec/runtime.md, so a sleeping handler answers early.)

std::http::Server is a listener and a consumer of the TCP connection substrate (below), both in the Server’s own placement. It serves concurrently exactly where a blocking call parks rather than holds the thread: on a cooperative pool declared where async_io.

main locus App {
    params {
        web: std::http::Server = std::http::Server { port: 8080, handler: Routes { } };
    }
    placement { web: cooperative(pool = web) where async_io; }
}

There the accept loop parks on the listening socket between connections and relays each one to the Server’s consumer, which serves it in a child of its own (an accept’d flow child) whose run() reads the request, calls the handler and writes the response. A park anywhere in a connection — the request’s recv, a std::time::sleep, a socket read or an outbound plain-HTTP call in the handler, a send to a slow client — yields the pool’s worker to the other connections and to the accept loop. Five concurrent requests to a handler that sleeps a second take one second, not five; fifty take one second. At most max_connections (default 256) are served at once; the next connection waits for a slot (a parked coroutine holding its descriptor), as many again may wait, and past that a connection is closed unserved — which bounds the descriptors and the 64 KiB coroutine stacks a burst holds. Each connection’s region is reclaimed as its run() returns.

Anywhere else — fn main()’s thread, the main pool, a pinned thread, a classic cooperative pool — a blocking call holds the thread, so the Server serves one connection at a time, inline, as it always has: a handler that takes a minute holds every other request for that minute. (On main and a pinned thread the accept loop yields after each relay, which runs the consumer’s delivery on the same thread before the next accept; on a classic pool, which runs its queued cells only between cells, the Server hands the connection to its consumer directly.) Concurrency is not the default because it cannot be: the main pool cannot be async_io, placement is written only on the main locus, and the Server’s consumer is a param of the Server, so it inherits the Server’s thread like any nested locus (spec/runtime.md § “Nested-instantiation inheritance”) — making the consumer a separate locus does not let the statement form std::http::Server { … }; in fn main() place it elsewhere, and moving the user’s handler to a thread its program did not name would change what that handler may assume. macOS and musl targets have no async_io pools at all. The one switch is the Server’s placement entry; a program that wants the listener and the serving apart places a std::io::tcp::Acceptor and std::io::tcp::Connections itself (below).

The handler’s state. Every connection calls the same handler locus. On an async_io pool its handle runs inside the connection’s coroutine, on the pool’s one worker thread (spec/runtime.md § “One worker thread per named cooperative pool”), so two calls never run in parallel: each runs uninterrupted until it parks, and while it is parked another connection’s handle may run and change the handler’s params. A value a handler read before a park may be stale after it; state that must hold across a park is re-read, or kept in the request’s own locals. Off async_io every call runs to completion before the next begins. Either way the handler’s code runs on the consumer’s thread — the Server’s; a handler locus that is a field of a locus on another pool is entered from that thread, not its own.

Every server has the same shape, and the substrate writes it once (crates/hale-stdlib/hl/io_tcp_serve.hl): a listener that only binds, accepts and relays each connection over the bus as an owned handle, and consumers that take a handle and serve its connection. The syscalls are stitched by placement: a listener placed pinned blocks in accept(2) on its own thread, one on a where async_io pool parks there; a consumer on an async_io pool serves each connection on a coroutine of its own, and anywhere else one at a time.

• std::io::tcp::Acceptor { host, port, path, name, shards, max_accepts, ready_signal } — the listener. Binds at birth (a socket it cannot bind is its listen_failed violation; a restart binds afresh), enters its name (name, or host:<bound port>, or unix:<path>; one taken is name_taken) for stop, prints ready_signal, and accepts until stopped or max_accepts, relaying each connection. It serves nothing. Two address families, one substrate: with path set it binds a Unix stream socket there in place of host:port (a stale socket file is replaced, a path a live process holds is listen_failed) and removes the file when it dissolves — only while the path still names the file it bound (std::io::unix::__release_path): a listener stopped by name keeps its fd until it goes, a shut Unix socket refuses connects, so a replacement may take the path as stale and bind its own file there, and the old listener’s cleanup leaves that file alone; accept, read, write and close are the same calls for both, so the relay, the handle and the consumers do not know which family a connection is. A failed accept nobody asked for (out of descriptors, a connection that failed between the handshake and the accept: __accept_one’s -2) ends that connection and never the listener, which accepts again 20 ms later; a requested wake (stop, shutdown(), the pool’s shutdown) is -1 and ends the loop. shards: K (default 1) deals connections round-robin over K routes. Place it pinned or where async_io; on a classic pool its accept holds the pool, and consumers on that pool are never served. It is on the checker’s long-running list, like the Server.
• std::io::tcp::Accepted { listener, route, fd, seq } — the handle: the listener’s name, the route it was sent on (<listener>#<shard>), the descriptor and the listener’s count from
  1. Whoever takes it owns fd and closes it. The handle itself lives for its delivery: a long-lived consumer keeps nothing of the connections it takes (spec/memory.md § “Every wire delivery takes the wire cell”; it used to keep the two names, ~34 B a connection).
• __TcpAcceptedT — the substrate’s topic, on the wire subject __tcp.accepted, keyed_by route, on_unmatched: fallback. A consumer subscribes where key == <its route>; every listener holds the topic’s catch-unmatched subscription (where key == _) and closes a handle that is its own. An accepted connection is served or closed — never leaked, never dropped in silence, so a program may state it: require no_silent_loss(topic __TcpAcceptedT) holds (spec/verification.md), and cover keys is not available (the key is a String).
• std::io::tcp::ConnHandler — fn serve(c: std::io::tcp::Accepted): what serves one connection, on its consumer’s thread.
• std::io::tcp::Connections { listener, shard, handler, max_connections } — the consumer: subscribes to the route <listener>#<shard> and serves each connection with handler in a child of its own — a flow child on an async_io pool (concurrent, bounded and drained as above, reclaimed as its run() returns), an inline child anywhere else (one at a time). refused counts the connections closed unserved past its bound. Two consumers on one route would both take every handle, so routes are one consumer each: replicas share a listener through its shards.
• std::http::Responder { handler } — the HTTP ConnHandler: reads one request (reassembled, 1 MiB cap, 5 s recv timeout), asks handler, writes the response (takeover included).
• std::io::tcp::stop(name) — above.
• std::io::tcp::Listener { host, port, max_accepts, on_connection, max_connections } — the m83 listener, on the substrate: one locus holding both ends, as the Server does, whose consumer’s handler calls on_connection: fn(std::io::tcp::Stream) with a Stream over each connection and closes the connection when the call returns. max_accepts (default 1; negative = until stopped) bounds the accepts, and run() returns once each accepted connection has been served. Placed where async_io it serves its connections concurrently, a coroutine each (at most max_connections, 256); anywhere else one at a time. Its name is its bound address (listener, host:<bound port>), for stop. A socket it cannot bind is no violation, as before the substrate: it accepts nothing and run() returns. Birth and dissolve print __StdIoTcpListener.birth host=… port=… and __StdIoTcpListener.dissolve host=… port=…; the default on_connection prints __default_on_connection fd=<n>.

Two replicas behind one pinned listener, each on an async_io pool of its own, the listener stopped by name from the main locus:

main locus App {
    params {
        zero: std::io::tcp::Connections = std::io::tcp::Connections { listener: "web", shard: 0, handler: std::http::Responder { handler: Api { } } };
        one: std::io::tcp::Connections = std::io::tcp::Connections { listener: "web", shard: 1, handler: std::http::Responder { handler: Api { } } };
        acceptor: std::io::tcp::Acceptor = std::io::tcp::Acceptor { port: 8080, name: "web", shards: 2 };
    }
    placement {
        zero: cooperative(pool = zero) where async_io;
        one: cooperative(pool = one) where async_io;
        acceptor: pinned;
    }
    claims { handed_over: require no_silent_loss(topic __TcpAcceptedT); }
    run() {
        while !self.draining { std::time::sleep(20ms); }
        std::io::tcp::stop("web");
    }
}

Consumers are declared before the listener, so they are subscribed before it accepts. std::http::Server is one locus that holds both ends: its relay (the listener’s end of the bus) and its conns (a Connections on its own route, handler: std::http::Responder { … }).

The api runtime’s socket transports are substrate listeners (spec/api.md § The Unix JSON transport, § The HTTP transport, § gRPC, § Streams). std::api::unix::Listener, std::api::http::Listener (the latter mcp::Rpc’s too), std::api::ws::Listener (a ws::Hub’s) and std::io::h2::Listener (grpc::Rpc’s) hold both ends as the Server does: a relay that accepts and relays, and a conns on the route of the listener’s name (unix:<path>, host:<bound port>), built in birth() once the name is entered, whose ConnHandler starts the transport’s connection locus (the peer that reads requests, publishes them as the exposure’s ingress and writes the replies; the hub’s WebSocket peer, which upgrades the connection and carries its subscriptions and calls; the HTTP/2 Conn, which owns the connection’s nghttp2 session) as a flow child of its own — accepted and released, on the listener’s async_io pool, and reclaimed with its region when the connection ends. A per-connection locus that subscribes to the bus has to be a flow child rather than a local of serve: a locus born in a method body and gone at its end has its deliveries queued for the main thread, which would answer the connection from another thread than the one reading it. What is the api’s own is the policy around the substrate: an address it cannot bind or a name it cannot enter is the boot’s failure (api: <transport> could not listen on <address>, exit 2), nothing is accepted until the exposure (the hub’s core, the gRPC transport) is subscribed, and the exposure’s stop() shuts the socket (the accept returns and the listener releases it, the Unix socket file with it) and ends its connections as its transport does (a hang-up; the hub’s closed frame; HTTP/2’s GOAWAY once the streams in flight are answered). Every api listener closes a handle on its own name’s route that no consumer takes, and stop(name) reaches it: the socket is shut and released, and the connections it accepted are served on until they end or the exposure stops (a drain, never a cut).

The substrate is source the program carries only when it names it: std::http::Server, std::http::Responder or one of std::io::tcp::{Listener, Acceptor, Connections, Accepted, ConnHandler} appends it (and its topic) to the program before the check, as the api runtime is (hale_stdlib::TCP_SERVE_SOURCE), and std::io::tcp::Listener appends the Listener after it (hale_stdlib::TCP_LISTENER_SOURCE, io_tcp_listener.hl); every other program carries none of it. It is stdlib source in every judgment: its loci start where the program names them, a scope of it holds dynamic sites in the placement table only once the program reaches it, the cooperative-pool blocking advisory does not read its bodies, the resource budget counts none of its descriptor sites, and a capability it needs is refused at the program’s literal (--target wasm32), with the witness down into it.

Not yet. The peer address: accept is called without one, so a consumer cannot be keyed by peer. The api listeners’ consumers start each connection’s locus and return, so max_connections does not bound them: an api listener’s connections are as many as clients open, as they were before the move.

std::http::Server accepts an optional ready_signal: String = "" param. When non-empty, the server emits it via println from birth() immediately after listen_socket succeeds and before the accept loop begins. Test harnesses, oracles, and shell scripts that pipe the server’s stdout (./bin | grep -m1 READY) key off this line:

std::http::Server {
    port: 8080,
    handler: Routes { },
    ready_signal: "READY"
};

Pair with the line-buffered stdout setup (the prelude installs setvbuf(stdout, NULL, _IOLBF, 0)) so a single println is flushed even under pipes.

Builder is a @form(...)-less locus that accumulates a JSON document into an internal buffer. It tracks scope state in a single context stack (one char per open scope: O/A for object/array with at least one value already emitted, o/a for empty). The Builder inserts separators (, between siblings, : between key and value) automatically.

Methods, grouped:

• Scopes: begin_object(), end_object(), begin_array(), end_array().
• Object entries (key + value in one call): field(name, value) for the common string case; string_field, int_field, bool_field, null_field for explicit typing.
• Array entries / bare values: value(v) (string), plus string_value, int_value, bool_value, null_value.
• Nested scopes inside an object: begin_object_field(name) / begin_array_field(name) — emit "name": then open the sub-scope.
• Finish: result() -> String returns the assembled buffer.

let b = std::json::Builder { };
b.begin_object();
b.field("name", "alice");
b.int_field("age", 30);
b.begin_array_field("tags");
b.value("admin"); b.value("ops");
b.end_array();
b.end_object();
let out = b.result();   // {"name":"alice","age":30,"tags":["admin","ops"]}

The flat-object readers (find_*_field, array_first/next) are the input side of the same v1 commitment: JSON is a wire format, not a tree value type, and the API surface reflects that.

escape_string(s) emits RFC 8259 §7: \\ and \", the four short forms \b \f \n \r \t, and \u00XX for the remaining control bytes. Every other byte passes through, so UTF-8 in the input is UTF-8 in the output.

unescape_string(s) is the inverse, and decodes \uHHHH to the scalar it names (GH #709 — before 2026-09-19 every \uHHHH decoded to ?, so an escaped literal never compared equal to its plain form):

The two refusals are deliberate. A native String is NUL-terminated, so U+0000 has no representation in one: writing the raw byte would truncate the value and let a prefix compare equal to the whole, which is worse than a visibly wrong character. An unpaired surrogate is not a Unicode scalar and has no UTF-8 encoding at all. Both answer U+FFFD rather than failing, because these helpers read untrusted wire bytes and the rest of the document is still worth decoding.

escape_string, unescape_string and every Builder emitter accumulate into one growing byte buffer and materialize a String once, so each is linear in the bytes it produces and the transient cost is bounded by the output size (GH #708).

This is a contract, not an optimization: a String is immutable, so the earlier out = out + piece form copied the whole accumulated prefix per write AND left every prefix behind in arena storage until the call returned — quadratic in both time and retained memory. A downstream handoff generating a document with a 600,000-byte shared value and 512 references reached 23–24 GiB of scratch and exhausted swap.

result() copies the buffer, so a snapshot taken mid-document is a stable String: the Builder keeps accumulating after it, and the earlier snapshot does not change.

valid(text) is true when text is one well-formed RFC 8259 value and nothing else: objects, arrays, strings, numbers, true / false / null, with JSON whitespace (space, tab, LF, CR) permitted around every token. Leading and trailing whitespace is fine; trailing anything else is not, and "" is not a document. The number rules are the grammar’s, so 01, 1., .5, 1e and +1 are all refused while -0, 1e5 and -1.25e-3 are values.

valid_object(text) is valid plus: the top-level value is an object, its keys are unique, and none of them is written with an escape. That is the shape a gate in front of a record wants. A duplicate key is syntactically valid JSON — last-wins is a convention, not the spec — so valid accepts it and two readers of the same bytes can disagree about the record; an escaped key spelling ("\u0061" for "a") compares unequal to the plain spelling in every find_* lookup in this module, so admitting one lets a field be present and unfindable at the same time. Keys of NESTED objects are checked for syntax only.

Three refusals go past the grammar. Each is a value this runtime cannot carry, and each is the same call the escape helpers make:

valid is linear in the input. Both are bounded:

• Depth 64. Nesting deeper than that is refused rather than scanned, so a hostile [[[[… costs a constant walk. The walk is iterative — one Int holds a bit per open level saying whether that level is an object — and 64 is where one machine word of that mask runs out. The bound is also the reason the scan is not a recursive descent: a coroutine stack is 64 KiB, and 64 frames of one is a real fraction of it.
• 64 top-level fields, for valid_object only. Uniqueness is decided by walking the object’s earlier members and comparing keys where they already live, so the check needs no table and no accumulator — and the width bound is what keeps that walk from being the quadratic cost it would otherwise become (uniqueness is at most 64 passes over the object). A wider object answers false. valid has no width bound, so it is still checkable as JSON — only the unique-key guarantee stops at 64, and a caller that needs both on a wider object can valid it and walk the keys with object_first / obj_key_eq.

Both are classified pure, and both allocate nothing at all: bytes are read with std::str::byte_at_unchecked after explicit bounds checks, whitespace runs skip through the SIMD next_non_ws, and nothing intermediate is materialized — no substring, no key set, no accumulator. That is a contract, not an accident: these fns are meant to run on every inbound message, so a per-call scratch buffer would land in the caller’s arena and be retained there until the caller returned. Cost is one pass for UTF-8, one for the grammar, and for valid_object up to one per field over the top-level keys — measured at ~10 ms per MiB, against 10.6 s for the per-character checked-slice shape (text[p..p + 1], which allocates per byte) that hand-rolled validators reach for first (GH #720).

String bodies are deliberately NOT scanned with the sibling next_quote_or_bs jump: it cannot see the raw control bytes RFC 8259 §7 forbids inside a string, and accepting those would make valid weaker than the validators it exists to replace.

These are the strict counterpart to the find_* family, which stays permissive on purpose (find_string_field("{\"x\":1", "x") answers 1). Validate at the boundary, then scan.

find_string_field(json, name) answers with a String whatever the value was. That is its contract and it does not change — but it means eight different documents give one answer, and an optional field cannot be read safely:

string_field(json, name) -> JsonString is the typed read (GH #719). JsonString is { kind: String; text: String; }:

• kind is one of "string", "null", "missing", "number", "bool", "array", "object", "invalid".
• text is the DECODED string content — surrounding quotes stripped, escapes resolved through the same \uHHHH path as unescape_string — and only when kind is "string". Every other kind carries "", so a caller that ignores kind gets an empty name rather than a plausible wrong one.
• "missing" means json IS an object with no such member; "invalid" means json is not an object at all, or the member’s value is not a JSON value the scanner can name (an unterminated string, a bare token like NaN).
• A key repeated within one object resolves to the FIRST member with that name — the same answer find_string_field gives, since both walk the top-level object cursor and stop at the first match.

The reader is not string-specific: an Int or Bool caller can gate the coercion on string_field(json, name).kind == "number" / == "bool" before trusting find_int_field / find_bool_field, which coerce the same way find_string_field does.

The result types in this namespace — JsonString, JsonFieldRange, ArrayIter, ArrayIterSpan, ObjectIterSpan — are nominal types the CHECKER knows, not opaque values (GH #771). string_field(body, "owner").knd is a type error naming std::json::JsonString with a did-you-mean for kind; so are a wrong arity, a swapped (json, it) argument pair on the span cursors, and handing one of these structs to a String parameter. let r: std::json::JsonFieldRange = … is the same type as the call’s inferred one, so the annotation is optional rather than lossy.

let owner = std::json::string_field(body, "owner");
if owner.kind == "string" {
    node.adopt(owner.text);
} else if owner.kind == "null" || owner.kind == "missing" {
    // a root: parentless, and NOT a node named `null`
} else {
    return "owner must be a string or null";
}

std::io::fs::read_file(path) uses a growing buffer internally (4 KiB initial, doubling, 64 MiB cap) rather than pre-sizing from fstat. Synthesized files under /proc and /sys report st_size=0 from fstat, so a fstat-then-read approach would return an empty String for /proc/self/statm, FIFOs, sockets, and similar synthetic sources. The growing-buffer shape reads real bytes from all of them.

The 64 MiB cap is a runaway guard, not a memory budget — real /proc / config files are 4–64 KiB. Callers hitting the cap probably want a streaming API; the cap surfaces as IoError { kind="io", errno=EFBIG }.

• ML / learning libraries
• Database drivers (Postgres, etc.)
• Web frameworks beyond basic HTTP
• Image / audio / video processing
• Cloud SDKs (AWS, GCP, etc.)
• GUI / TUI frameworks
• Cryptography beyond TLS + SHA-2 basics
• Compression formats beyond ones used in stdlib

These live in the Hale package ecosystem (per packages.md).

1. Module organization — flat (std::collections, std::string) vs hierarchical (std::collections::Map). Probably the Go-style middle ground (std/collections/map.go).
2. What’s exported by default vs deep-imported. import std; for everything? import std::time; only? Probably the latter: explicit per-module imports.
3. API stability commitments. Go’s stdlib is famously stable. v0 stdlib is unstable; v1 marks specific APIs as stable; only stable APIs survive long-term.
4. Versioning. Stdlib versioned with the language? Or independently? Probably with the language for v0; consider independent versioning when stable.

• Lower adoption barrier. New users don’t need to evaluate third-party packages for table-stakes functionality.
• Discipline propagation. Stdlib uses framework primitives correctly; new code following stdlib examples inherits the discipline.
• Ecosystem trust. When the language ships a std::crypto, it’s vetted; trust transfers to programs that use it.
• Cross-language consistency. Programs from different teams share the same vocabulary because they share the same stdlib.

Cost: stdlib is permanently load-bearing once shipped. Bad decisions are hard to undo. Discipline at design time matters more here than in third-party.