v0.8.2: docs cleanup + 9-PR bug-fix bundle (#21)

Docs cleanup, fixing post-2026-05-25 staleness around the
narrowed two-channel rule (open-question #24, `47e03e8`):

  - AGENTS.md: rewrites the bullet that said "no fallible(E)
    on locus methods" and the matching diagnostics hint.
    Substrate-facing surfaces (lifecycle, mode, closure-
    assertion, bus-handler) reject fallible; user-declared
    `fn` members + free fns allow it.
  - agents/library-dev.md: same shape with a worked example
    showing a fallible user `fn` member inside a locus.
  - docs/src/concepts/error-handling.md: bridging-channels
    intro paragraph distinguishes the rejected surfaces from
    the allowed ones explicitly.
  - spec/projects.md: passing reference updated.
  - spec/stdlib.md: `std::io::udp` row's parenthetical drops
    the "multicast bus transport is a separate design under
    consideration" note (shipped this cycle via `udp://`
    substrate transport) and cross-refs the `std::bus` row.

Workspace version bumps 0.8.1 → 0.8.2.

What landed since v0.8.1:

  - #5  docs: document udp:// bus transport surface
  - #6  bus: spill-to-heap payloads + jumbo-aware UDP transport
  - #7  bus deserialize: bound-check length prefixes
        (closes priceview crash)
  - #8  bus udp: bind multicast receivers to the group address
        (fix crosstalk)
  - #14 std::crypto: add crc32(b: Bytes) -> Int (#12)
  - #15 std::io::tcp: add set_recv_timeout / set_send_timeout
        (#13)
  - #16 std::io::tcp::Stream: bus-routed I/O observability
        (#10, TCP part)
  - #17 std::http::Server: bus-routed observability
        (closes #10 modulo TLS)
  - #19 bus udp: array-of-pointers for remote entries
        (fix listen+connect SIGSEGV)
  - #20 release: drop macos-13 (Intel Mac) from the build matrix

Three orthogonal udp:// bugs closed in this cycle (#7, #8,
#19); release-workflow Intel-Mac hang resolved (#20); two
new stdlib surfaces shipped (CRC32, tcp timeouts); bus
observability extended to Stream + http::Server via
log_subject.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: rileyr

AGENTS.md

@@ -146,11 +146,17 @@ Filter these reflexes before they cost you time.
   concatenates its args. F-strings `f"hello {name}"` interpolate.
 - **No `return` inside `birth` / `run` / `dissolve` bodies.**
   Factor short-circuit logic into helper free fns.
-- **No `fallible(E)` on locus methods.** Free fns and
-  `@form(...)`-synthesized methods are the only fallible
-  surfaces. Locus methods communicate failure structurally via
-  the `↑` channel (closures + `on_failure`). Two-channel rule,
-  locked.
+- **`fallible(E)` is rejected on substrate-facing surfaces:**
+  lifecycle methods (`birth` / `run` / `dissolve`), mode bodies
+  (`bulk` / `harmonic` / `resolution`), closure-assertion
+  bodies, and bus-subscribed handlers. Those have no caller
+  frame to address the error channel, so a `fallible(E)`
+  declaration would describe a contract that can't be
+  satisfied. User-declared `fn` members on a locus and free
+  fns DO carry `fallible(E)` — they have a real caller. The
+  narrowed two-channel rule (2026-05-25) keeps `↑` and `fallible`
+  separate at the substrate boundary; everywhere else they
+  compose. See `spec/semantics.md § fallible-on-locus`.
 - **No `panic(msg)` / `assert(cond)`.** Failure is structural,
   routed through closure-tests + `on_failure` (the `↑` channel)
   or value-level via `fallible(E)`.
@@ -197,8 +203,13 @@ surprises:
   they address bus channels only.
 - `self` outside a method body → you're in a free fn or top
   level; no enclosing Σ.
-- Lifecycle method declared `fallible(E)` → see "no fallible on
-  locus methods" above. Convert to free fn.
+- Lifecycle / mode / closure-assertion / bus-handler method
+  declared `fallible(E)` → the substrate orchestrates these,
+  so the error channel has no caller to address. Drop the
+  `fallible(E)` and route failure through `↑` (closure-test
+  + `on_failure`), OR factor the body into a user-declared
+  `fn` member that the lifecycle method calls with `or` to
+  bridge the channels.
 - "Error not addressed" on a `fallible` call → add `or raise` /
   `or default` / `or handler(err)`.
 

Cargo.lock

@@ -10,7 +10,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.8.1"
+version = "0.8.2"
 edition = "2021"
 authors = ["the Hale authors"]
 license = "Apache-2.0"

Cargo.toml

@@ -128,18 +128,47 @@ The spec is **not aspirational**. If it's in
 shipped behavior. If a feature has been removed, the spec
 entry must be removed too.
 
-## Two-channel rule (locked design)
-
-Locus methods cannot declare `fallible(E)`. The two surfaces
-that *can* are free fns and `@form(...)`-synthesized methods.
-This is permanent design, not a temporary limit — see
-`spec/design-rationale.md` F-numbered commitment on the
-two-channel rule.
-
-If you need a stdlib operation to be fallible, add it as a
-free fn (`std::io::fs::read_to_string(path) -> fallible(String,
-IoError)`) or surface it through an `@form` whose synthesis
-produces fallible accessors.
+## Two-channel rule (narrowed 2026-05-25)
+
+`fallible(E)` is rejected on **substrate-facing surfaces**:
+lifecycle methods (`birth` / `run` / `dissolve`), mode bodies
+(`bulk` / `harmonic` / `resolution`), closure-assertion
+bodies, and bus-subscribed handlers. The substrate
+orchestrates those — there's no caller frame to address
+the error channel, so a `fallible(E)` declaration would
+describe a contract that can't be satisfied. Surface failure
+there through `↑` (closure-test + `on_failure`).
+
+`fallible(E)` IS allowed on user-declared `fn` members and
+on free fns — both have a real caller that can `or raise` /
+`or default` / `or handler(err)` the result. Library code
+that wants to expose a fallible operation as a method on a
+locus type can declare it as a user `fn` member:
+
+```hale
+locus Reader {
+    fn parse(b: Bytes) -> Message fallible(ParseError) {
+        if bad { fail ParseError { msg: "bad header" }; }
+        return Message { ... };
+    }
+    run() {
+        let m = self.parse(b) or default_message();
+    }
+}
+```
+
+The earlier blanket rule ("locus methods can't be fallible
+at all") was narrowed because the friction signal across
+multiple libraries showed devs extracting free fns just to
+get a value-error channel back — losing `self` ergonomics
+and splitting closely-related code across two top-level
+decls. See `spec/semantics.md § fallible-on-locus` for the
+canonical statement and `notes/open-questions.md § #24` for
+the rationale + rejected alternatives.
+
+`@form(...)`-synthesized accessors (`get` / `set` /
+`array_at`) remain fallible like before — that's
+orthogonal to the narrowing.
 
 ## Naming aliases for libraries
 

agents/library-dev.md

@@ -296,12 +296,15 @@ loci, so the value channel fits.
 
 ## Bridging the channels: structural failure from value-error context
 
-The two-channel rule keeps locus methods off the value channel —
-but real systems regularly need to *cross from one to the other*.
-A locus method catches a value error in an `or` clause, decides
-the error is unrecoverable, and wants to immediately escalate
-into the structural channel so the parent's `on_failure` policy
-takes over.
+The two-channel rule (narrowed 2026-05-25) keeps **substrate-facing
+surfaces** — lifecycle / mode / closure-assertion / bus-handler
+bodies — off the value channel. User-declared `fn` member fns
+on a locus and free fns DO carry `fallible(E)` and live on the
+value channel like normal. Real systems regularly need to *cross
+from value to structural* — a method catches a value error in an
+`or` clause, decides the error is unrecoverable, and wants to
+immediately escalate into the structural channel so the parent's
+`on_failure` policy takes over.
 
 Hale's primitive for this is **inline closure violation**: a
 locus declares a *named structural-failure type* as an

docs/src/concepts/error-handling.md

@@ -154,9 +154,11 @@ import "<path>" as <alias>;
 The alias-required rule is the same forcing-function discipline
 v1.x-3 enforces for `: projection recognition` (no default
 sub-mode) and v1.x-FORM-2 enforces for the two-channel rule
-(locus methods can't declare `fallible(E)`): the user names the
-commitment at the surface so a downstream reader doesn't have
-to reconstruct the namespace from the path.
+(substrate-facing surfaces — lifecycle, mode, closure assertions,
+bus handlers — can't declare `fallible(E)`; user-declared `fn`
+members and free fns can): the user names the commitment at the
+surface so a downstream reader doesn't have to reconstruct the
+namespace from the path.
 
 Imports appear at the top of a file, before any top-level
 declaration. Multi-file seeds may declare imports in any file;

spec/projects.md

@@ -69,7 +69,7 @@ surface without touching the compiler.
 | `std::io::file` | `File` locus (held-open fd with auto-dissolve close). `open(path, mode) -> File fallible(IoError)`; `read_line(f) -> String` (returns "" at EOF or error — pair with `at_eof`); `at_eof(f) -> Bool`; `write_bytes(f, b)`, `write_line(f, s)`, `seek(f, offset)` all `fallible(IoError)`. Mode strings `"r"` / `"w"` / `"a"` / `"r+"` / `"w+"`. Returned Strings live in the bus payload arena. | `lotus_file_*` C primitives + `runtime/stdlib/file.hl` |
 | `std::io::stdin` | `read_line() -> String`, `read_line_status() -> Int` (status `-1` = EOF/IO error; `0` = OK including empty-line) | POSIX `getline` + payload-arena copy |
 | `std::io::tcp` | `Listener` locus, `Stream` locus, `send`, `send_bytes`, `recv_bytes`, `recv_into(fd, buf: Bytes, max_bytes) -> Int` (caller-provided builder destination). Path-calls `listen_socket`, `connect`, `accept_one` are `fallible(IoError)`. `connect` accepts dotted-quad hosts directly and falls back to hostname resolution via `getaddrinfo(AF_INET)`. Send/recv timeouts (2026-05-27): `set_recv_timeout(fd, d: Duration) -> () fallible(IoError)` wraps `SO_RCVTIMEO`; `set_send_timeout(fd, d: Duration)` wraps `SO_SNDTIMEO`. `d = 0` disables (blocking default). After `set_recv_timeout(fd, 100ms)` a `recv_bytes` on a quiet socket returns ~100ms instead of blocking forever — unblocks recv loops that need periodic silence-detection / heartbeat / watchdog work. Shares the `sock_set_timeout_ns` helper with the udp siblings (P4, 2026-05-26). **Bus-routed I/O observability** (2026-05-27): `Stream` gains a `log_subject: String = ""` param and a `bus { publish "io.tcp.**" of type std::io::tcp::LogEvent; }` declaration. When `log_subject` is set, every send / recv / close on that Stream publishes a `LogEvent { phase, detail, bytes, fd }` on the configured subject. Empty `log_subject` (the default) gates the publish with a single `len(s) > 0` branch — zero hot-path cost. Users wire any subscriber locus they want (`subscribe "io.tcp.**" as on_evt of type std::io::tcp::LogEvent`) — stderr sink, structured log, metrics, ring buffer; the bus is the indirection so no `Logger` interface or per-Stream sink locus is needed. Closes the "I/O lib is silent by default with no hook" friction. | `lotus_tcp_*` C primitives |
-| `std::io::udp` | `bind(host, port) -> Int fallible(IoError)` (`host=""` → INADDR_ANY); `send(fd, host, port, msg)`, `recv(fd, max_bytes)`, `recv_into(fd, buf: Bytes, max_bytes)`, `close(fd)`. Multicast (2026-05-26 P1): `join_group(fd, group, iface) -> () fallible(IoError)` (iface=`""` → INADDR_ANY), `leave_group(fd, group, iface)`, `set_multicast_ttl(fd, ttl)` (0..255), `set_multicast_loop(fd, enabled: Bool)` (whether the sender receives its own packets), `set_multicast_iface(fd, addr)`. Transparent setsockopt pass-through (P2): `set_option_int(fd, level, name, value)`, `set_option_bool(fd, level, name, enabled)`, `get_option_int(fd, level, name) -> Int` — paired with `std::io::sockopt::<NAME>()` named constants below for the `level` / `name` args. Source-bearing recv + timeouts (2026-05-26 P4): `recv_with_source(fd, max_bytes) -> Bytes fallible(IoError)` populates a thread-local source cache; `last_source_host() -> String` / `last_source_port() -> Int` read the cache from the most-recent recv_with_source on the current thread (errno-style; read immediately after recv). `set_recv_timeout(fd, d: Duration) -> () fallible(IoError)` / `set_send_timeout(fd, d: Duration)` wrap `SO_RCVTIMEO` / `SO_SNDTIMEO` (they take a struct timeval so can't ride `set_option_int`); `d = 0` disables (blocking default). Datagram boundaries preserved. **NOT a bus transport** — UDP doesn't satisfy the bus's atomic-delivery contract (multicast bus transport is a separate design under consideration; see open questions). | `lotus_udp_*` C primitives |
+| `std::io::udp` | `bind(host, port) -> Int fallible(IoError)` (`host=""` → INADDR_ANY); `send(fd, host, port, msg)`, `recv(fd, max_bytes)`, `recv_into(fd, buf: Bytes, max_bytes)`, `close(fd)`. Multicast (2026-05-26 P1): `join_group(fd, group, iface) -> () fallible(IoError)` (iface=`""` → INADDR_ANY), `leave_group(fd, group, iface)`, `set_multicast_ttl(fd, ttl)` (0..255), `set_multicast_loop(fd, enabled: Bool)` (whether the sender receives its own packets), `set_multicast_iface(fd, addr)`. Transparent setsockopt pass-through (P2): `set_option_int(fd, level, name, value)`, `set_option_bool(fd, level, name, enabled)`, `get_option_int(fd, level, name) -> Int` — paired with `std::io::sockopt::<NAME>()` named constants below for the `level` / `name` args. Source-bearing recv + timeouts (2026-05-26 P4): `recv_with_source(fd, max_bytes) -> Bytes fallible(IoError)` populates a thread-local source cache; `last_source_host() -> String` / `last_source_port() -> Int` read the cache from the most-recent recv_with_source on the current thread (errno-style; read immediately after recv). `set_recv_timeout(fd, d: Duration) -> () fallible(IoError)` / `set_send_timeout(fd, d: Duration)` wrap `SO_RCVTIMEO` / `SO_SNDTIMEO` (they take a struct timeval so can't ride `set_option_int`); `d = 0` disables (blocking default). Datagram boundaries preserved. **`std::io::udp` is the raw-socket primitive, not a bus transport** — its `recv` / `send` calls don't carry the bus's typed-payload-dispatch contract. For UDP-as-bus see the `std::bus` row's `udp://host:port` substrate transport (shipped 2026-05-26): single URL scheme covers IPv4 unicast and multicast, dispatch goes through the same `LOTUS_BUS_CONFIG` route as `unix://`, lossy delivery (publisher-side "sendto returned" durability; subscribers best-effort). | `lotus_udp_*` C primitives |
 | `std::io::sockopt` | Named-constant getters returning the platform's numeric value for each setsockopt level / name. Use as the `level` / `name` args to `std::io::udp::set_option_*` / `get_option_int`. Each is a zero-arg fn (`std::io::sockopt::SO_RCVBUF()` etc.) so the value tracks the kernel headers; cross-platform without hardcoding. Shipped (2026-05-26): `SOL_SOCKET`, `IPPROTO_IP`, `IPPROTO_IPV6`, `IPPROTO_TCP`, `IPPROTO_UDP`, `SO_REUSEADDR`, `SO_REUSEPORT`, `SO_RCVBUF`, `SO_SNDBUF`, `SO_RCVTIMEO`, `SO_SNDTIMEO`, `SO_BROADCAST`, `SO_KEEPALIVE`, `SO_LINGER`, `SO_PRIORITY`, `SO_BINDTODEVICE`, `IP_TTL`, `IP_TOS`, `IP_MULTICAST_TTL`, `IP_MULTICAST_LOOP`, `IP_MULTICAST_IF`, `IP_ADD_MEMBERSHIP`, `IP_DROP_MEMBERSHIP`, `IP_PKTINFO`. PMTU surface added 2026-05-27: `IP_MTU_DISCOVER` + `IP_PMTUDISC_DONT` / `IP_PMTUDISC_WANT` / `IP_PMTUDISC_DO` / `IP_PMTUDISC_PROBE` (Linux-only; returns -1 on platforms missing the constant — caller can detect and skip). | `lotus_sockopt_<NAME>` C getters |
 | `std::io::tls` | Client-side TLS via system OpenSSL. `connect(host, port) -> Int fallible(IoError)` does the TCP connection + TLS 1.2+ handshake with SNI + system-trust-store cert verification. `send_bytes` / `recv_bytes` / `recv_into` / `close` over the handshaked connection. Process-global `SSL_CTX` runs with `SSL_MODE_RELEASE_BUFFERS` — OpenSSL releases its read/write buffers between records so long-running TLS clients don't accumulate ~32 KiB per idle connection. The `lotus_tls.c` TU compiles separately so helper tests linking `lotus_arena.c` directly don't drag in libssl/libcrypto. | `lotus_tls_*` in `runtime/lotus_tls.c` |
 | `std::http` | `Request` + `Response` types (`Response.headers: String` carries CRLF-joined user-supplied headers — no trailing CRLF — for Set-Cookie / CORS / custom headers); `parse_request`, `write_response`; case-insensitive symmetric `header(receiver, name)` lookup; `Handler` interface (`fn handle(req: Request) -> Response`); `Server` locus with `shutdown()` (cross-thread safe — see [§ Server.shutdown](#servershutdown--interruptible-accept-loop)) and optional `ready_signal: String` for piped oracles. **Bus-routed observability** (2026-05-27): `Server` gains a `log_subject: String = ""` param and a `bus { publish "io.http.**" of type std::io::tcp::LogEvent; }` declaration. When `log_subject` is set, listen-start / accept / listen-close events publish on the configured subject; empty (default) keeps the hot path at a single `len > 0` branch per event. Reuses the `std::io::tcp::LogEvent` type so one subscriber can observe both TCP and HTTP layers. | `runtime/stdlib/http.hl` |