Expand description
Pre-boot port-availability guidance for EXPLICITLY-stated addresses,
shared by frame run and frame host.
Under the portless ruling (2026-07-22) a frame.toml need state no ports at
all: the page server prefers 127.0.0.1:4190 and walks forward to a free
port, and a synthesized [bus]’s internal listeners bind OS-assigned free
ports. Those are chosen at boot and cannot collide, so there is nothing to
probe for them.
A STATED address is different: it is LAW, the host binds exactly it, and a
taken port is a loud refusal. This module probes each stated socket BEFORE
boot and, on a collision, returns a CliError::PortUnavailable that names
the socket role, the exact frame.toml key, and the coherence rule to follow
when moving it — an earlier, more actionable surfacing of the same refusal
the host would raise mid-bind.
A socket counts as stated when its address is present in the loaded config
with a non-zero port: [frame].bind when present (the page server), and any
[bus] listener whose port is not the OS-assigned 0 sentinel. A fully
portless config therefore probes nothing and this is a clean pass.
Functions§
- ensure_
ports_ available - Probes each explicitly-stated host socket, failing with actionable guidance the moment one is unavailable — before the host is spawned or booted. A fully portless config probes nothing and passes cleanly.