Entry contracts
The client half rests on a small wire contract: the shape of one entry’s membership and status, and of the frames that carry its calls. Every choice in it applies one principle: the framework owns the keyed volatility, and the app owns policy.
Why the status is a sum, not a flag
The surface map publishes each entry’s status as EntryStatus<Failure>, a sum of exactly three arms:
// `Conn` (SR9): the fine per-entry connection payload, carried on the LIVE arms and
// parameterized like `Failure` — the map validates it against its own `connection`
// schema, never enumerating it. It is the ONE authority the coarse `kind` (the dot) and
// the fine word both derive from; optional, so a connection-less map omits it. The
// `failed` arm carries none at all — see the note on that arm below.
type EntryStatus<Failure = unknown, Conn = unknown> =
// `membershipId`: opaque, never-reused per-add identity — a BRANDED `MembershipId`
// (an empty/fabricated bare string is a compile error), minted only by
// `serveSurfaceMap` / the wire decode. Clients key cached owners on
// `{encodedKey, membershipId}`, so a same-key re-add / authority restart rebuilds.
| { kind: "warming"; membershipId: MembershipId; connection?: Conn }
| {
kind: "connected";
membershipId: MembershipId;
clockOffset: number | null; // own-clock offset; null = not-yet-measured
connection?: Conn;
}
// No `connection` on this arm — deliberately. The failed entry's live word would be
// the same frame `evidence` was pinned from, so `connection?.log` here was a second,
// floorable copy of the tail. Removing the field makes that read a compile error.
| {
kind: "failed";
membershipId: MembershipId;
failure: Failure; // schema-valid domain failure
evidence: FailureEvidence; // the retained output tail that EVIDENCES it
};
There is no absent arm: absence means absence. A collection already says “not a member” by not containing the key, and a second encoding of the same fact is a second writer waiting to disagree. So membership lives in the key set, status in the value, and one writer publishes both.
The three arms exist because the client must tell apart states that look alike but need opposite responses:
- warming: the system is doing something and will resolve on its own. First provision and a transient reconnect backoff both land here. The right UI is a spinner, not an alarm. Because of
unobservable(below), this arm means a campaign the publisher is narrating to you right now, so you may put a clock on it. - connected: live.
clockOffsetis this entry’s clock seam. - failed: it will not resolve unless someone acts. It is a bounded give-up, or a standing refusal (“another owner holds this host”). The right UI is an actionable card, not an eternal spinner.
Why the connection word and the dot have one source
A map may declare a connection schema, and the live arms then carry that fine payload beside the coarse kind: a word such as “connecting” beside the dot a fleet view paints from kind. Both derive from one projection of one session frame, so a consumer reads the word off the same entry value it reads the dot from (state().connection), never from a second subscription.
Two reads of one fact latch out of step. Drishti’s fleet view once showed a connected dot beside a host stuck on “connecting”, because the dot and the word came from different places (srid/drishti#102). One payload on one arm leaves the two nothing to disagree about.
Why there is a fourth arm on your side
entry(key).state() has one more arm that the wire never carries: unobservable. The client’s liveness floor mints it when your own link to the publisher is dead. It means “we cannot see this entry”.
The bug it prevents
The floor demotes a connected entry when your link dies, so nothing renders green over a dead transport. Demoting it to warming merged two opposite facts: “the host is coming up” and “we cannot see the publisher at all”.
A consumer that only spins is fine either way. A consumer that times the entry can certify a healthy thing dead. kolu did: a backgrounded tab lost its socket, the entry dropped to warming, and a 30-second boot deadline declared a daemon that had run for twelve hours dead (kolu#2129).
Why an arm and not a flag
A separate arm makes every .exhaustive() match in every consumer say what it does while blind. The compiler asks the question. An optional flag on warming would be a field you can ignore, which is a rule you can forget.
What it carries
membershipId: the floor is about liveness, not identity, so it is still the same member.published: "warming" | "connected": the last thing the publisher said. You can show “last seen: connected” without the framework pretending the claim still holds.- No
clockOffsetand noconnection. A frozen in-progress word cannot keep narrating work that stopped, and there is nothing green to paint.
failed is not floored, because a post-mortem does not go stale the way a live claim does. That is why published has no failed value.
For a consumer that only wants a spinner, isSettling(state) covers both warming and unobservable. Anything that puts a clock on an entry must narrow the union itself, which is the point.
The arm has no wire schema: it is a projection of your own transport. So entryStatusSchema cannot encode it, and a floored value can never be republished.
Why a failure carries its evidence
The failed arm is a FailureRecord: the reason, and the output that evidences it, as one named value. Neither half is optional, because a cause without what the machine printed is a card nobody can act on. One value is a rule you cannot forget, where two correlated fields are a rule to remember. For the same reason, a disconnected session state carries an optional refuse: FailureRecord.
The pairing also survives the liveness floor. The floor drops the live connection payload when the browser’s link goes quiet. If the output tail rode that payload, a laptop waking from sleep would see a reason with no evidence. The floor drops liveness payloads, and a failure record is not one. The failed arm carries no connection at all, so the old read does not compile.
Where warming ends and failed begins
The session’s domain failure draws the line.
- A specific failure, such as a contract skew or a cross-supervisor refusal, is a standing condition. It projects
failed. - No specific failure means a transient drop. It projects
warming.
Collapsing the two produces two opposite bugs: a retriable reconnect shown as red “failed” makes a live system look dead, and a standing refusal shown as warming spins forever. The sum makes both unrepresentable.
The domain owns its failures
Failure is a type parameter (defaulting to unknown), inferred from the map’s required failure schema. The generic package cannot know a domain’s failure taxonomy, so it carries only the discriminant and one thing of its own.
A domain instantiates EntryStatus<PadiEntryFailure> at its own map. PadiEntryFailure is a validated Schema.Union of Schema.Structs over a structural cause. Each arm carries its human reason, and the contract-skew-refused arm also a typed running/expected version pair. Domain vocabulary stays in the domain, and the dependency arrow points out.
The framework’s one field on that arm is evidence: readonly { source: "local" | "remote"; line: string }[]. It is a fixed type, not a third type parameter, because evidence is not domain volatility. Every transport that can fail produces output lines tagged with their source, and there is nothing for a domain to disagree about. @kolu/surface-remote’s session log already has this shape, so the producer hands its tail straight through.
Why the fold envelope omits void
Every member’s call folds to one wire shape: { mapKey, input }, whatever the input is. The folded key rides outside input, so an entry input with its own mapKey field cannot collide with it.
A member that takes no input carries no input field at all: { mapKey }, never { mapKey, input: undefined }. The tempting version relies on two accidents: that JSON drops an undefined value, and that the decoder accepts the missing key. A schema library that rejects a missing declared-void field would break every void-input call the moment a lockfile drifted onto it.
Omitting the field makes “void = no input key” the one representation, so a dependency bump cannot silently break the wire.
Why a sibling is a whole surface
An entry can carry a sibling surface beside the entry surface: a second daemon on the same host, re-served through the map and addressed per key. The simpler-looking move is to drop that daemon’s members into the entry surface and keep one spec.
A sibling is a different program’s contract, with its own release cadence and its own version. Folding its members into the entry spec makes that contract part of the entry’s: one spec two daemons must agree about, where a version skew in either is a skew the other has to carry. So a sibling is declared as a whole Surface, never as a spec fragment, and each program ships on its own schedule.
Why keys are codecs, not strings
A Key can be anything the schema validates: kolu’s HostKey is a discriminated-sum object, not a string. But every channel name, dedup key and membership entry is keyed on a string. KeyCodec<K> bridges the two:
interface KeyCodec<K> { encode(key: K): string; decode(wire: string): K; }
An explicit codec keeps two boundaries apart. Parsing loose human input (localhost, 127.0.0.1, user@host) is a separate function from decoding a canonical wire key, so a lax parse never leaks into the wire.
encode is a bare, cheap call because it sits on the hottest paths: a per-key cache lookup on every entry(key), and a fold on every entries read. decode is paired with keySchema.parse and need not validate alone: the server re-validates the real key on arrival.
The typed end of a subscription follows the same discipline:
- A call to an absent key is not a thrown socket error. It is a typed rejection (
MAP_KEY_UNKNOWN) for a procedure, and an immediate typed end for a stream. - A key that leaves membership mid-stream ends its subscriptions with a typed
{ reason: "removed" }before the session is torn down. A consumer sees a clean, expected end, never a socket-error frame after a typed end.
Absence is always a value you handle, never an exception that surprises you.
Why the clock is per entry
A timestamp stamped on a remote host means nothing against the browser’s wall clock, because the two clocks disagree. So connected carries the entry’s measured clockOffset, and a host-stamped time is read through that entry’s seam: entry(key).clock.toLocal(remoteMs), which is remoteMs − offset.
The seam returns number | null. It returns null, never a silent identity, whenever the entry has no offset yet: warming, failed or not a member. The null is deliberately contagious, since now − null is a type error. A caller cannot fall back to the raw remote value, which is exactly the foreign-clock lie the seam prevents. This is reactive honesty’s rule, that a caught absence must surface, pushed into a type.
Where it costs you
The map’s wire makes one trade five times: it refuses a convenient shortcut in exchange for a lie it cannot tell.
| Choice | What you pay |
|---|---|
No absent arm | You read status through a total lens instead of a nullable one. |
| A per-entry clock | You thread every host-stamped time through a seam, and render ”—” while it warms. |
A typed domain failure on failed | The app must say what each failure means, instead of showing one red dot. |
Each is more ceremony than a single-host client needs. The bet is that in a fleet, where the set changes underfoot and every fact belongs to one host, the ceremony is the only thing that stays true. If a future addition encodes an opinion about which host matters, that is policy dressed as framework, and it belongs in the app.