kolu
Docs

The client half

The server half is about one surface crossing a machine. The client half is the other problem: a browser facing many surfaces of the same shape, keyed by host, with the set changing while you watch.

The shape of the map clientOne browser talks over one socket that carries enveloped frames of map key and input. The map holds one entries collection — the sole authority on membership — plus a per-key slot for each host, reached as app.entry(host). One slot is warming and one has failed while the others stay connected.browserone tabONE socket{ mapKey, input }every frame envelopedthe map — appentriesthe ONE authority on membership · absence = not a memberper-key slots — app.entry(host)…zestcells · collectionsconnectedlabcells · collectionsconnectednaiveintentunreachable — retryingwarmingstale-boxa standing faultfailed
One browser, one socket carrying enveloped { mapKey, input } frames. The map is an entries membership collection — the sole authority on presence — plus a per-key slot for each host reached through app.entry(host)…. One slot warms and one fails on their own while the rest stay connected.

One contract, many hosts

Every host serves the identical entry surface. That is the leverage. You type the surface once, and the map form keys every member, so one socket carries all the instances. A client reaches any host’s cells or streams through the entry lens, app.entry("zest").cells.daemonStatus.use(…), and the type is the same for every host because the contract is the same for every host. There is no per-host client to write and no branch on which host you are reading.

The hard part a fleet adds is not the plumbing. It is a single rule: the view must never show host A’s data under host B’s name. Every fact on the wire is true of one host. The client half exists to make that misattribution impossible to write, rather than something you avoid by being careful.

Why entries is the only authority on presence

The map publishes exactly one collection of membership, entries, and absence means absence. A host that is not in entries is not in the map. There is no absent status arm to keep in sync, because a collection already expresses absence by not containing the key. One writer publishes membership and status together, so the two cannot disagree, and a second authority for membership has no way to exist.

Why reading a host is total

Ask entry(key).state() for any key, present or not, and you get an honest value. not-a-member is one of them. You never get a nullable entry() that you might forget to guard, so existence is a value you render rather than an exception you catch.

Switching which host a tab views is then a plain app signal. useEntry(activeHost) re-keys the whole readout when the signal changes: the old host’s subscriptions dispose and the new host’s populate. Switch the chip, and every readout follows, by wiring rather than by discipline.

A fleet client faces a subtler lie than a broken pipe. A host the server last saw as connected can be drawn green while your own link to that server is dead. A connected published by the server is only as trustworthy as the transport carrying it.

So the map floors every status on real transport liveness. With the link dead, a stale connected leaves the published union for unobservable, an arm that says “we cannot see this” instead of borrowing a word that means something else. No status renders green over a dead transport, and live is a required input to the fold, so it cannot be forgotten. Entry contracts covers why that is its own arm rather than a demotion to warming.

This is also why a client never hand-rolls a probe. The framework-reserved liveness round-trip is the one probe, and the watchdog-backed handle from connectSurface carries it by default. The map slices its scoped view after that guard, so every entry inherits the parent’s watchdog. A hand-rolled check for whether a host is up would be a second opinion about liveness, and two opinions about liveness is how a green dot ends up floating over a dead socket.

Why a roster move does not rebuild your page

Which hosts exist is part of the served contract, so a roster change moves the member set. A client resolves its schemas through the group fixed when its link opened, which means a wire whose members move needs a new link at both ends. Most links own their transport for life: dispose one and the dispatch it minted is dead.

If that replacement has nowhere to stop, it reaches all the way up. Every client, every standing subscription and every reactive handle built over the old dispatch is dead, and the page rebuilds its tree to follow a roster move.

So the browser’s wire keeps one stable pair of halves over a generation it can replace underneath, and everything built on the stable halves survives the swap. Calls in flight when the generation moves are failed rather than parked, and the shared retry fence, the one place a subscription re-opens after a failure, re-subscribes them onto the new generation. A link that re-subscribed inside itself would hide the very failure that fence has to see.

Where it costs you

Making misattribution impossible has a price. You read every per-host fact through the entry lens, never off a bare client you cached yourself. That is one more indirection on every read, and it forbids stashing “the current host’s client” in a variable, because a stashed client is exactly how host B’s data ends up under host A’s name after a switch.

The framework trades the convenience of a flat client for a guarantee the flat client cannot make. For a single host that is overhead. For a fleet, where the set changes underfoot and every fact belongs to one host, it is the only version that stays true. Why entries carries the arms it does is Entry contracts.