--- name: blog-series description: docs/blog/ holds a numbered Xe-voice post series about the port; conventions + which topics are already taken metadata: node_type: memory type: project originSessionId: a7154a32-7647-441a-aff5-45ddd4ab06e6 --- `docs/blog/` is a numbered blog-post series narrating the C→Rust port for a public audience, written in Xe Iaso's voice. When asked to "work on another blogpost," write the next `00N-*.md`. **Always use the `/xe-writing:xe-writing-style` skill** before drafting — the user corrected me once for not loading it. Source material: [[rust-migration-plan]] (PLAN.md), the `docs/superpowers/plans/` + `specs/`, and project memory. **Format = match the existing posts, NOT the live-xeiaso.net MDX.** Plain markdown with `title/desc/date` frontmatter; character asides as blockquotes `> **Cadey** (coffee): …` / `> **Mara** (hacker): …` (not `` JSX, no imports); a standing "leave the IRCNet team alone, this is an unsanctioned experiment" disclaimer; footer `---` linking `PLAN.md` + `docs/superpowers`. Hard rule from the skill that bites: **no two successive paragraphs may start with the same letter** (check every draft). Commit pattern: `docs(blog): add 00N- …`. Each post = one topic, written for peers: - 001-project-goals — why/goals; the verifiable-faithfulness tradeoff; Leveva name reveal ([[project-name-leveva-p10]]) - 002-strangler-fig — outside-in (Rust owns `main`) vs bottom-up porting order; the clean `.o`-drop seam - 003-the-oracle — the differential test harness: L1 `objcopy --redefine-syms` cref_ trick, the tests/ link-anchor gotcha, L2 golden harness + the clock-pinning trap - 004-variadic-trampolines — why stable Rust can call but not *define* an `extern "C"` variadic; the ~25 C sender shims (`va_start`→format→Rust core); per-recipient `va_arg` in `vsendpreprep` kills "format once"; "100% Rust" is a dated P8 goal - 005-the-greenfield-exception — iauth is the ONE component rewritten from scratch (not faithfully ported), because its contract is the fd-0 text wire, not in-process ABI; the 8-fn start/work/timeout/clean module vtable collapses to one `async fn run`; SOCKS `goto again` → sequential await; STILL oracle-gated (relinked C-iauth over fd-0 socketpair, byte-identical handshake); had to reproduce the rfc931 dead-else-if popt bug bug-for-bug. Decision rule: where does the contract live? ABI → translate; text socket → rewrite + diff the wire. - 006-the-retrospective-is-where-you-round-up — the P0-P6 halfway retrospective, framed as "a retrospective is where you round up." The un-rounded ledger of what the differential harness caught: the c_char-signedness test bug that only failed on aarch64; the clean-checkout s2s golden red because reference-C `report_myservers` prints an uninitialized peer sendq (`3544950785030750208kB`) — oracle so precise it catches the reference being nondeterministic; brief callback to the rfc931 bug-on-purpose; `calculate_preference` calls libc `pow` via FFI (not `f64::powf`) so a last-ULP drift can't flip the `(u_int)` truncation on the wire. Harder-than-planned: P5's 56 clusters over shared file-statics (can't port one m_* without its neighbors); `replies[]`/`alphabet_id` dumped from the oracle not text-extracted. Cost: P9-P12 exist to un-do the faithfulness P1-P8 built. - 007-prove-the-structs — the P0b foundation post ([[p0b-bindgen-constraints]]): before any faithful port, prove Rust and C agree on struct layout byte-for-byte (else every port silently corrupts shared memory). Two SILENT bindgen failures: (1) bindgen defaults to C++ → chokes on `class` field name (class_def.h:25, struct_def.h:323) + `register` storage class → clang error-recovery leaves structs as opaque `pub struct X { _address: u8 }` blobs, build still green; fix `.clang_arg("-x").clang_arg("c")`; diagnose with `grep -c 'pub _address: u8,'`. (2) bindgen 0.70 picks forward-decl over later definition (struct_def.h:23-40 `typedef struct X Y;`) → opaque again; 0.72 fixes. Then the real point: "bindgen agrees with bindgen" ≠ "bindgen agrees with the real compiler" (config drift: MAXCONNECTIONS/USE_IAUTH/AFINET=AF_INET6 move fields). Drift net = ctruth.c (same flags, exports cref_sizeof/alignof/offsetof for 14 structs + aClient's 24 local-tail offsets + CLIENT_REMOTE_SIZE=offsetof(count) + MAXCONNECTIONS) + layout.rs (`cargo test`, red on drift). Honest holes: the 256-tables + local[] are sizeless `extern[]` → unreachable, asserted later at P1/P7; MAXCONNECTIONS is the cheap proxy. Throughline: build the thing that catches you before you can be wrong. - 009-hand-both-of-them-the-same-socket — diffing I/O functions in the L1 oracle (P7w `send_authports`/`read_authports`, P7z `check_client`). Earlier posts diffed PURE fns; these call `getpeername`/`getsockname`/`read`/`write` so their real input is the kernel, not their args. Thesis: mocking a syscall makes both impls agree with the FIXTURE not the kernel → defeats a faithfulness oracle. Fix = hand the C `cref_` original and the Rust port the SAME real fd (one connected IPv6-loopback socket for getsockname/getpeername, one AF_UNIX socketpair for pipe I/O), separate aClients (the fn mutates them), diff what comes out. Beats: the socketpair-leaves-`sin6_port`-untouched trap (C reads uninit stack, Rust reads zeroed → FALSE diff → use a real `::1` socket when the bytes-under-test are kernel-filled, socketpair when they're bytes YOU wrote); the `World` struct + `GLOBALS_LOCK` for `cref_`-twinned process globals under parallel `#[test]`s ([[p7-l1-shared-global-race]]); empty-`conf` → `attach_Iline` returns -2 deterministically (no fixture); the faithful 4×`c_ulong` over-read of a 16-byte `h_addr` (pad to 32 in the harness, ship the bug). Quotes verified against check_client_diff.rs/authports_diff.rs + s_bsd.c:914/871 + s_auth.c:690/740. - 010-you-dont-write-a-test-for-the-front-door — coverage-by-ubiquity + the trap in "it's covered". P7bb ported `add_connection` (s_bsd.c:1641), the universal inbound acceptor (every connection enters via read_listener's accept loop → add_connection), so it got NO new L2 golden test — all 111 golden scenarios already flow through it; a botched success path turns the whole suite red at once (free, loud regression coverage). The TRAP: ubiquity only covers the ONE branch the suite walks (the connection that succeeds); the 3 refusal paths (getpeername ENOTCONN, IsIllegal conf, clone-flood > CLONE_MAX=10) are branches no well-behaved client takes → no honest harness takes them → must be STAGED in the L1. That's why P7bb skipped L2 but not L1. The static `check_clones` twin (no cref_ oracle) is only visible through the public door's clone-reject (the 11th connection). Reuses 009's same-fd trick. Throughline: the most-run fn is also one of the least-tested in its BRANCHES; "it's on the hot path, it's covered" feels rigorous and isn't. Footer-links 003/008/009. All claims verified vs s_bsd.rs:1746/1810 + add_connection_diff.rs + read_listener s_bsd.c:1821. - 011-the-dial-out-you-can-only-test-by-not-dialing — the OUTBOUND counterpart to 010, closing the I/O trilogy (009 leaves → 010 inbound front door → 011 outbound dial). P7cc ported connect_server (s_bsd.c:2516) + static connect_inet. Thesis = the MIRROR of 010: connect_server's whole point is the connect() succeeding, and that path is UNTESTABLE at L1 (needs a live listening peer + event loop = L2; and all 111 golden scenarios dial INTO the daemon, never make it dial out → the most-tested program has ZERO coverage of this fn's success path). So the L1 oracle diffs the NEGATIVE SPACE — the 3 deterministic ways it refuses to dial: find_server-hit (already present, -1 before any socket, s_bsd.c:2528), the remote-by sendto_one arm, and connect_inet's bind() failure → free_server cleanup (assert highest_fd unchanged + hash clean). Three tests for a connect fn, none of which connect. Secondary beat = the faithful-dead-code edge: DNS-resolution block at s_bsd.c:2544 guarded by `!aconf->ipnum.S_ADDR` is DEAD under AF_INET6 (S_ADDR=s6_addr embedded array → `!&array` constant-false; common/os.h:686) → ported by OMITTING it; dead code has no behavior so the oracle can't tell present from absent, but the oracle also can't PROVE it dead (no test enters the branch) — it's a reading of the macro, not a test result (honest-limit beat). Gotcha: find_server/hash_find_server's suffix-mask scan overwrites '.'→'*' in-place → faults on read-only `c"..."` literals (heap-alloc the keys). Footer-links 010/009/003. All claims verified vs s_bsd.c:2516/2528/2544/2726 + connect_server_diff.rs + os.h:686. - 012-you-cant-rename-a-symbol-that-isnt-there — the class of fn the L1 oracle STRUCTURALLY can't test: file-`static` fns ([[l1-cref-static-symbol-limit]]). Oracle = `objcopy --redefine-syms foo cref_foo`, map from `nm -g --defined-only` (globals only) → a `static` has internal linkage, no external symbol, no `cref_` twin without editing the C. First hit P6 (`lookup_confhost`, static int s_conf.c → L1 linked but undefined; non-static neighbor `ipv6_convert` got its diff). Two OPPOSITE outs: (a) de-static it (the ONE C edit the faithful port allows — storage-class only, comment every time; `mysk` P7s minted `cref_mysk` free) vs (b) leave it static + port a PRIVATE Rust twin (`unsafe fn`, no `pub`/`#[no_mangle]`) verified only transitively through its exported caller. The 4 P7 twins: `set_sock_opts`(s_bsd.c:1489, via inetport)/`check_init`(:873, via check_client+check_server_init)/`check_clones`(:1577, via add_connection)/`connect_inet`(:2680, via connect_server). Honest limit = the oracle diffs at exported-SYMBOL granularity, so a red caller-diff can't LOCALIZE to the static callee: GCC already inlined the static into its sole remaining caller C-side (PLAN P7z finding), Rust un-fused them for readability, but the diff stays whole-symbol; once the last C caller is ported the C static is guarded out entirely (no oracle at any linkage). The 010 branch-trap recurs: transitive coverage only walks the caller's tested path (`check_clones` age-out branch needs a 2s inter-connection gap no golden scenario waits → covered by a reading, not a test). Funny beat: the twin's `static mut BACKLOG` = a static inside a static (same C keyword, internal-linkage one scope out + persist-across-calls one scope in). Footer-links 003/010/008. Topic chosen by user via AskUserQuestion (vs the P5 connected-component option). Verified vs s_bsd.rs (4 twins) + ircd-testkit/build.rs (nm -g filter) + p6.md (lookup_confhost). - 008-eat-the-file-one-function-at-a-time — the sub-file partial-port seam (the candidate flagged below, now TAKEN): how to port one function inside a `.c` that has to stay C for more phases. The `.o` is all-or-nothing at the linker, so a mid-port file exists in THREE compiled forms at once: (1) the guarded second compile `s_bsd_link.o` — same source + a parade of `-DPORT_S_BSD_*_P7x` flags, each `#ifndef`-guarding one function body down to a bare prototype so the still-C neighbours resolve to the Rust `#[no_mangle]` def; goes in the real binary via the build.rs `match o { "s_bsd.o" => "s_bsd_link.o", … }` redirect. (2) the full unguarded `.o` → renamed `foo`→`cref_foo` by ircd-testkit/build.rs (`nm -g --defined-only` → objcopy `--redefine-syms`) into libcref.a, the L1 oracle, which OUTLIVES the C binary. (3) the Rust port itself. Plus the de-static gotcha: `static` fns have no external symbol → can't satisfy C callers OR get a cref_ oracle, so de-static first (storage-class-only, behaviour-preserving, single-TU-no-collision — the one C edit allowed, justified in a source comment every time). Worked example = set_clean_username (P7v, s_auth.c:44-98, callers read_iauth/start_auth). Ends: file gets eaten leaf-by-leaf, then the whole apparatus evaporates into a PORTED tombstone (s_conf.c P6m). All code quotes verified against real source. - 013-the-function-that-launches-the-program-i-didnt-port — P7dd `start_iauth` (s_bsd.c:625/566), the C launcher of the GREENFIELD iauth from 005 — the seam where the two opposite strategies (rewrite-from-scratch vs translate-byte-for-byte) meet at one fd. NEW oracle puzzle (distinct from 009 kernel-input / 011 no-peer / 012 static-symbol): the fn's success is `fork`+`execl` → the child STOPS being your process (execl replaces the image with the rewritten iauth), so there's nothing in the child to diff. You diff the PARENT-SIDE SHORELINE — the L1 spawn case (start_iauth_diff.rs:152) actually forks BOTH worlds for real (child execl-fails on absent IAUTH_PATH in CI → `_exit(-1)`), captures only `(adfd>=0, O_NONBLOCK set, iauth_spawn==1)` per world, asserts they match + ==`(true,true,1)`. Testing a fork = reaping after one: bounded WNOHANG `reap_children` (:65) so the test can't zombie/hang. CENTERPIECE faithfulness beat = the `vfork()`→`fork()` swap (s_bsd.rs:310): faithful DEVIATION justified (child only close-loop/dup2/execl = async-signal-safe, CoW fork identical result, Rust libc deprecates vfork as memory-unsafe) BUT the failure log still says `"vfork() failed!"` — kept the wrong word on purpose: syscall is BELOW the oracle's resolution (unobservable → free to change), the log string is ABOVE it (on the wire to opers → must match). "Faithful to what's observable, free below it" crystallized in one string. Honest limits: child plumbing (close-loop/dup2/exec-the-right-binary) unverified at L1 (both children vanish → L2/soak); the non-first-call burst block (`"%d O\n"` of live local clients, gated by the function `static first`) is green by SYMMETRIC ABSENCE — L1 only ever makes a first call so both worlds skip it (needs populated local[] + 2nd call = L2/soak). The 3 function statics last/first/iauth_pid → module-private ([[l1-cref-static-symbol-limit]]/012 callback). Footer-links 005/012/003. Verified vs s_bsd.c:566/625/642 + s_bsd.rs:236/310/315 + start_iauth_diff.rs:65/152. - 014-a-daemons-first-job-is-to-stop-being-watched — P7ee `daemonize` (s_bsd.c:794), the boot detach glue called once from ircd.c:1152 (warning-label comment "daemonize() closes 0,1,2 -- make sure you don't have any fd open"). Sits directly above 013's start_iauth (calls it at the bottom). NEW untestability flavor, named distinct from 011: 011 was can't-AFFORD-it (success needs a live peer/event loop = infra); this is can't-SURVIVE-it — the fn's whole JOB is to make the process unobservable (fclose/close 0/1/2, `fork`+parent `exit(0)`, `/dev/tty`+TIOCNOTTY, setpgrp), so running the detach path destroys the test harness (closes cargo's stdout/stderr, exits the parent=the test process). Fork-isolation doesn't save you either: the thing it PRODUCES is a detached process — "successfully detached" has no return/struct/errno to diff, the evidence of success is the ABSENCE of everything you'd observe with. Only differentially-safe path = the `bootopt & BOOT_TTY` → `goto init_dgram` short-circuit (=-t "foreground mode", ircd.c:1140), which skips the whole detach AND is the only path any rig takes (golden always boots `-t`, ircd-golden/src/lib.rs:50) → testing the config the harness lives in, not a fiction. CENTERPIECE test beat (daemonize_diff.rs:67, one case, GLOBALS_LOCK): pin BOOT_TTY|BOOT_NOIAUTH, resfd=-99 sentinel + adfd=-1, run both worlds; assert resfd CHANGED to a valid fd (init_resolver(0x1f) ran, both worlds agree) AND adfd STAYS -1 (start_iauth(0) reached but short-circuited on BOOT_NOIAUTH) — the inverse check: prove one tail call left a mark and the other correctly left none, because "nothing happened" also looks like a broken short-circuit. Secondary faithful-text beat (lighter cousin of 013's vfork-message): C calls `setpgrp(0, getpid())` 2-arg but glibc setpgrp is `setpgrp(void)` (ignores args) → declared 2-arg in Rust to mirror the source verbatim (faithfulness for the READER, below the wire); TIOCNOTTY defined on Linux so ported straight. Honest hole: the ENTIRE detach path has ZERO differential coverage (not a missed branch — the reason the fn exists), ported by inspection-against-the-C only; real coverage = boot WITHOUT -t + check the process actually backgrounded (new session/no ctty/reparented to init) from OUTSIDE = L2/soak, logged in the plan. Closing callback to the warning-label comment. Footer-links 013/011/003. Topic auto-picked (freshest commit, continues the I/O thread); user didn't name it. Verified vs s_bsd.c:794 + s_bsd.rs:2443 + daemonize_diff.rs + ircd.c:1151/1140/889 + struct_def.h:105/111 + ircd-golden/src/lib.rs:50. - 015-the-loop-that-runs-every-test — P7ff `read_message` (s_bsd.c:2091/2088), the select() event loop, body of `io_loop` (ircd.c:1264, called up to ~6×/pass over fdas/fdall), LAST logic in s_bsd.c. THE post on the function the L1 oracle can barely touch: its real input is the kernel (select/accept/recvfrom/exit_client), so there's exactly ONE differentially-safe path — the EMPTY LOOP (`FdAry.highest=-1`, udpfd/resfd/adfd=-1, delay=0 → empty fd_set → `select(0,…,200ms)`=0 → no dispatch → return 0; read_message_diff.rs:73, two cases incl ro=1). Two near-empty asserts for the busiest fn in the program; the test file's own doc says "Why L1 here is one case by design." CENTERPIECE INVERSION (vs 010's coverage-by-ubiquity TRAP): here ubiquity is AIRTIGHT — read_message IS io_loop, so every byte the daemon moves flows through it → the whole golden_*/golden_s2s_* suite (~190 #[test]s, 2 real daemons, real bytes diffed) is its real test end-to-end. "You don't write a test for the event loop; the event loop runs every other test." Mara caveat: L2 is a great gate, lousy DEBUGGER (red = 1-of-50 suspects); the empty-loop L1 catches one thing but localizes. Secondary beats: (1) the DEAD `USE_POLL` half — C read_message is two event loops in a trenchcoat (#if/#else, SET_READ_EVENT/SET_WRITE_EVENT macros serve both backends), USE_POLL off → poll side never compiles → Rust ports select-only, macros evaporate to direct `libc::FD_SET`; ~430-line C fn → one Rust loop. Faithful-dead-code, CLEANER than 011 (compile-time `#if` vs 011's runtime-macro-constant-false). (2) the 8 statics (completed_connection/read_listener/read_packet/client_packet/ircd_no_fakelag/do_dns_async/polludp/check_ping) — all `static`, no cref_ oracle ([[l1-cref-static-symbol-limit]]/012), ported as module-private twins w/ read_message → 8 of 9 fns in the I/O-engine heart have ZERO L1 oracle, the 9th has the empty-loop case; biggest P7 port, thinnest L1 footprint. OPENS on the honest miscount in 014's closing (it said "two little static helpers"; it was EIGHT). Honest ledger: skeleton proven, all dispatch (accept/read/write/exit_client/do_dns_async/polludp/check_ping) untested-by-design → L2/soak. Closing mirrors 014's "So that's daemonize" cadence ("So that's read_message"). Footer-links 010/012/003/008/009/001. Topic was flagged in 014's closing as "the next one I'm nervous about"; user didn't name it. Verified vs s_bsd.rs:3201/3216/2500 + read_message_diff.rs + ircd.c:1264 + s_bsd.c:2091/2094/2110. - 016-the-trampoline-with-no-riders — the INVERSE of 004 + the OPENING of P8 (delete the C). 004 explained why ~25 variadic `sendto_*` trampolines had to stay C and promised they die in P8 by deletion-not-translation; this is the first one out: **P8a `sendto_iauth`** (s_auth.c:120-170). THESIS = deleting a variadic isn't about the variadic — by P8 every caller is already Rust, so you move the `va_start` work to the call sites (where `format!` already lives) and the fn loses its `...` → becomes `pub unsafe fn sendto_iauth(line:&[u8])` (s_auth.rs:38). CLEANEST-FIRST insight (title metaphor): `nm` showed ZERO live C callers (all remaining C callers in `#ifdef`'d-out bodies) = "no riders"; all 24 callers already Rust → deleting touches only Rust sites I control → picked it first ON PURPOSE as the safe one to learn the mechanics on. Mechanics shown: the before/after `sendto_iauth(c"%d U %s",fd,user)`→`sendto_iauth(format!("{} U {}",fd,ia_str(user)).as_bytes())`; `ia_str` (s_auth.rs:77) = lossy C-string read, byte-faithful bc iauth pipe protocol is ASCII. FAITHFUL-BUG beat (REACHABLE-behavior-adjacent but actually unreachable): the C write loop sets `p=abuf` then `write(adfd,abuf,len)` from the BASE while advancing `p+=i` never used → dead cursor, would double-send on a partial write, but tiny lines on a local pipe = one write so it never fires; replicated bug-for-bug anyway (re-issue from base). ORACLE-IS-ALLOWED-TO-BE-VARIADIC beat (the funny one): I can't DEFINE an extern"C" variadic in stable Rust but the cref_ oracle is STILL C (unguarded s_auth.o) so `cref_sendto_iauth(fmt,...)` stays variadic — drive same line both ways (oracle vsprintf vs Rust pre-formatted bytes), 2 socketpairs, byte-diff the pipe (sendto_iauth_diff.rs). Honest holes: debug `-1 E last=%u start=%x` pointer line (nondeterministic→not diffed) + lost-slave hard-error branch (can't force fatal write→by-inspection). leveva-deferred note: format!-now not leveva typed Message bc this carries the iauth PIPE protocol ` ` not IRC msgs ([[p8-started]] decision). Ledger: 1 of ~25; keystones `sendto_one`(~478)/`sendto_flag`(~255) still per-recipient-hard per 004's vsendpreprep. Guard `PORT_S_AUTH_SENDTO_IAUTH_P8a` (build.rs:292). Footer-links 004/003/005. Topic auto-picked (freshest commit, opens P8); user didn't name it. Verified vs s_auth.rs:38/77 + s_auth.c:120 + sendto_iauth_diff.rs + build.rs:292 + 2026-06-07-p8a plan. - 017-the-keystone-wasnt-the-monster — P8l `sendto_one` (send.c:450-468), THE keystone, the direct continuation of 016's cliffhanger; topic chosen by user via AskUserQuestion (vs the per-recipient-prefix-senders option, the "not one line of C remains" P8v finale, and the leveva-pivot option). THESIS = the keystone was mislabeled: 004+016 named `sendto_one` the scary one (~478 call sites + per-recipient formatting), but the per-recipient horror lives in `vsendpreprep` (send.c:388)/the PREFIX senders (P8e `sendto_prefix_one` & kin, pulled a few cuts EARLIER, e