One core behind N frontends, the board's own runner moved in, and every board cap on one screen

## The wire is the effect stream, not a new protocol

`pardes --detach` leaves a core running with no terminal; `pardes --attach` is a frontend that owns
a terminal and a socket and nothing else. N frontends on one core all look at the same screen —
`screen -x`, not N sessions.

The codec (`src/detached/wire.zig`) carries exactly one `Event` or one `Host.VTable` call per
message. That is not a coincidence and it is why there is no third vocabulary to keep in step: the
core's IO seam was already a struct of function pointers with plain-data arguments, so a socket is
a legal implementation of it. `nested.zig`'s socket could not be reused — it carries a builtin
command line, and a command line cannot carry a frame.

ARCHITECTURE-NEUTRAL on purpose, not as decoration. The frontend on the far end may be
riscv32-freestanding on the ESP32-P4 while the core is x86_64 Linux, so every field is an explicit
little-endian fixed width and no message is a blit of a native struct. A protocol that only works
between two builds of the same compiler would have thrown away the one frontend that motivated it.

## The board comes in; its toolchain stays out

`src/p4.zig` becomes `src/esp32p4.zig`, and the pardes half of `../05-zig-p4` — the vaxis-over-
serial runner, the UART editor terminal, the keystroke rescue ring, the on-die test suite — moves
into `src/esp32p4/`. `build.zig.zon` gains `.zig_p4 = .{ .path = "../05-zig-p4" }`, so
`zig build -Dplatform=esp32p4 -Desp32p4-firmware` builds, flashes, monitors and self-tests the
board from this repo's `build.zig`.

The DIVISION is the point. What moved is what only pardes wants: the runner that drives a pardes
core over a serial line. What stayed is everything a second project would also want — the HAL, the
register/radio/oracle layers, the linker script, `_start`. `zig_p4` declares no dependencies of its
own and its `build()` early-returns when it is not the root package, so this costs the package
graph exactly zero packages and the editor's own builds nothing at all.

## limits.zig: nine forgettable places become one budget

Nine `platform == .esp32p4` capacity tests lived in nine files. They were never nine decisions —
they are ONE decision, how much memory this build may spend, taken nine times where no reader could
see the total. `src/limits.zig` puts the whole budget on one screen with every cap named against
what it is measured against, derived from two booleans.

The payoff is testability on a machine that is not the board: the caps are ordinary comptime values,
so a host build can be compiled against the board's numbers and the parking, eviction and clamping
paths a 240 KiB core takes get exercised by the normal test suite instead of only over a UART.

## A bare `zig build`

`zig build` with no arguments now builds the tty and GUI binaries and installs them into
`~/.local/bin`, and says so once on stdout with the flag that overrides it. The old default built
one binary into `zig-out` — a path nothing on a `PATH` ever looks at, which made "build it" and
"use it" two different commands for no reason.

1 files changed, 165 insertions, 0 deletions

diff --git a/src/esp32p4/uart.zig b/src/esp32p4/uart.zig
new file mode 100644
index 00000000..0afd145b
--- /dev/null
+++ b/src/esp32p4/uart.zig
@@ -0,0 +1,165 @@
+//! UART0 as the editor's terminal: bytes out, bytes in, and nothing else.
+//!
+//! This is the whole of the firmware's I/O. There is no framebuffer and no keyboard; the board
+//! emits ANSI and consumes ANSI, and the terminal emulator on the far end of the CH340 does the
+//! rest of the work - including answering the editor's own capability queries, which travel down
+//! this wire like any other bytes.
+//!
+//! WHY IT IS IN THIS REPOSITORY. It is not a UART driver - that is `hal.uart`, which stays in the
+//! toolchain package and is checked against ESP-IDF's own headers by `zig build diff` there. This is
+//! the EDITOR's use of one: which instance the console is, that the transmitter is real
+//! backpressure because a truncated escape sequence corrupts the host terminal, that rescued
+//! keystrokes must come out before FIFO ones, and that the first thing to do at startup is discard
+//! the host bridge's synthetic resize report. Every one of those is a statement about the editor, so
+//! the file moved to sit beside it. See `app.zig`'s header for the boundary in full.
+//!
+//! What it expects from the toolchain package is exactly one module: `hal`, for `hal.uart.Uart`.
+//! Nothing else here reaches the chip. The sibling `input_rescue.zig` is a plain file, not a module,
+//! because it is this repository's own policy.
+//!
+//! Deliberately not a `std.Io.Writer`. The ANSI encoding lives on the other side of the C ABI, next
+//! to the vaxis that produces it (see `app.zig` for why the seam is there and not elsewhere), so
+//! what crosses into this file is already a finished run of bytes. A writer here would be a second
+//! buffer in front of one that already exists.
+//!
+//! Two decisions worth stating, because both are measurements rather than preferences.
+//!
+//! **Batched FIFO access.** The naive push is `while (txFree() == 0) {}` then `pushByte`, once per
+//! byte: one MMIO read per byte at best, many while the FIFO is full. Reading `txFree` once and
+//! then pushing that many cuts the status reads by up to the FIFO depth (128, the toolchain
+//! package's `src/hal/uart.zig:52`). At 115200 the wire costs ~86 us per byte and dwarfs either
+//! version, so today this is merely free - and it stops being free the moment the divider is raised.
+//!
+//! **UART0's configuration is never touched.** Not the divider, not the format, not the pad
+//! routing, and above all not `reset()`. The second-stage bootloader configured this block, and
+//! `src/hal/uart.zig:195-211` records what happens if it is reset: UART_CLKDIV returns to its
+//! power-on value, the console turns to garbage mid-sentence, and the board takes a watchdog reset
+//! with nothing readable left to explain it. Everything here touches FIFO offset 0x000 and the
+//! status register, and nothing else.
+
+const hal = @import("hal");
+const input_rescue = @import("input_rescue.zig");
+
+/// UART0: the instance the CH340 is wired to, and the one the ROM and bootloader configured.
+const uart0 = hal.uart.Uart.init(0);
+
+/// Keystrokes taken off the receiver while the transmitter was full. See `input_rescue`: without
+/// this, anything typed into a frame longer than the 128-byte FIFO was silently gone.
+var rescued: input_rescue.Ring = .{};
+
+/// Push `bytes` into the TX FIFO, blocking while it is full.
+///
+/// The spin is normally bounded by the wire - a full 128-byte FIFO drains in 11 ms at 115200 - and
+/// dropping instead of waiting would truncate an escape sequence, leaving the host terminal in the
+/// wrong colour for the rest of the session. So the wait is real backpressure.
+///
+/// But it is BOUNDED, for the reason the toolchain package's `src/hal/uart.zig:182-186` gives about
+/// `update()`: a UART whose core clock has been gated never makes progress, and "on a board with no
+/// debugger an infinite spin is indistinguishable from a crash". That is not hypothetical here - it
+/// is how this port spent an afternoon: output stopped mid-boot with no panic and no watchdog (the
+/// RTC watchdog having been correctly disabled), which looked like a hang in whatever code came next
+/// rather than a stalled transmitter. A bounded wait turns that into visibly dropped output plus a
+/// counter, which is a diagnosis instead of a mystery.
+///
+/// The limit is per burst, not per call, and generous: 1,000,000 status reads is far longer than
+/// any legitimate drain and still a fraction of a second.
+pub fn write(bytes: []const u8) void {
+    dropped +%= input_rescue.pump(uart0, &rescued, bytes, 1_000_000);
+}
+
+/// Bytes abandoned because the transmitter stopped making progress. Nonzero means the console is
+/// lying about what happened, so it is worth printing.
+pub var dropped: u32 = 0;
+
+/// One byte, for callers that must not touch `.rodata` to say anything - which during bring-up is
+/// the difference between a diagnostic and a second copy of the bug being diagnosed.
+pub fn writeByte(b: u8) void {
+    var spins: u32 = 0;
+    while (uart0.txFree() == 0) {
+        spins += 1;
+        if (spins > 1_000_000) {
+            dropped +%= 1;
+            return;
+        }
+    }
+    uart0.pushByte(b);
+}
+
+/// Emit `n` bytes read from `addr` as two hex digits each, computing the digits arithmetically so
+/// nothing here reads a lookup table. Used to answer "does a load from this address return what the
+/// linker put there", which is not a question a string literal can be trusted to ask.
+pub fn dumpHex(addr: u32, n: u32) void {
+    const p: [*]const volatile u8 = @ptrFromInt(addr);
+    var i: u32 = 0;
+    while (i < n) : (i += 1) {
+        const byte = p[i];
+        for ([2]u8{ byte >> 4, byte & 0xf }) |nib| {
+            writeByte(if (nib < 10) '0' + nib else 'a' + (nib - 10));
+        }
+    }
+    writeByte('\r');
+    writeByte('\n');
+}
+
+/// A u32 as eight hex digits, reading no memory at all.
+pub fn dumpWord(v: u32) void {
+    var shift: u5 = 28;
+    while (true) {
+        const nib: u8 = @intCast((v >> shift) & 0xf);
+        writeByte(if (nib < 10) '0' + nib else 'a' + (nib - 10));
+        if (shift == 0) break;
+        shift -= 4;
+    }
+    writeByte('\r');
+    writeByte('\n');
+}
+
+/// Move whatever the host has sent into `buf`, without waiting. Returns the count.
+///
+/// Non-blocking on purpose: the loop has a frame to render and a core to pump, and the editor must
+/// not stall on a keystroke that may never come. `rxCount` is read once per call and the FIFO
+/// drained to that mark, so a fast typist or a pasted buffer cannot hold the loop here.
+pub fn read(buf: []u8) usize {
+    // RESCUED BYTES FIRST. They arrived before anything still sitting in the FIFO, and an editor
+    // that reorders keystrokes is worse than one that drops them.
+    var n = rescued.pop(buf);
+    const waiting = @min(uart0.rxCount(), buf.len - n);
+    for (buf[n..][0..waiting]) |*slot| slot.* = uart0.popByte();
+    n += waiting;
+    return n;
+}
+
+/// Take whatever has arrived off the receiver right now, without waiting and without handing it to
+/// anyone. For callers that are about to spend a while not reading: `write` does this while the
+/// transmitter is full, and the loop does it between chunks of input, because applying a keystroke
+/// gets more expensive as the line grows and 128 bytes of FIFO is only 11 ms at 115200.
+pub fn rescueNow() void {
+    input_rescue.rescue(uart0, &rescued);
+}
+
+/// Input abandoned because even the rescue buffer overflowed. Distinct from `dropped`, which is
+/// OUTPUT abandoned by a stalled transmitter.
+pub fn inputDropped() u32 {
+    return rescued.dropped;
+}
+
+/// Discard anything already received, returning how much. Used once at startup: the host-side
+/// bridge injects a window-size report before this program exists, and the bootloader's chatter has
+/// already been echoed at the host. Neither is user input.
+///
+/// Pops rather than calling `resetRxFifo`, which is a CONF0_SYNC read-modify-write plus two commits
+/// on the console UART - see this file's header.
+pub fn drainInput() u32 {
+    var discarded: u32 = 0;
+    while (uart0.rxCount() > 0) : (discarded += 1) _ = uart0.popByte();
+    discarded += @intCast(rescued.len);
+    rescued.clear();
+    return discarded;
+}
+
+/// The rate the hardware is actually producing, by reading its dividers back. Reported rather than
+/// assumed: the host has to be opened at the same rate, and a mismatch shows up as garbage on the
+/// screen rather than as an error anyone can act on.
+pub fn baudrate() u32 {
+    return uart0.baudrate(uart0.clockSource().nominalHz());
+}