Glossary
Every framework term the surface docs use is defined here once, in plain language, with a link to the page that covers it. When a word on another page is unfamiliar, look it up here.
The surface and its members
- Surface — a typed, reactive slice of live state you declare once with
defineSurface. The framework derives the wire contract, the server handlers and the client hooks from that declaration. → Why surfaces - Cell — one value with an identity over time, such as a load average. The server sends a snapshot and then deltas, and a client may set it. → Reference
- Collection — many values, each under a key and watchable on its own, such as one row per process. Each key gets its own snapshot and deltas. → Reference
- Stream — a read-only view the server computes from an input you supply, such as the live tail of a log. → Reference
- Event — an occurrence rather than a value. A handler fires each time it happens, and there is no snapshot and no current value. → Reference
- Procedure — a plain call that does something now, such as killing a process. It is the imperative member among the five. → Reference
- Group — the flat set of wire members derived from a surface spec, one tag per member verb (
surface/<member>/<verb>). The server and the client both compile against it. → Reference - Snapshot-then-deltas — every cell, collection and stream opens with a full snapshot and sends only changes after it, so a reconnect re-seeds from truth. → Reactive honesty
Reaching a surface from a client
- Link — how a client reaches a served surface over one transport. Every link yields the same typed client:
directDispatch,websocketLink,unixSocketLink,stdioLink. → Choose a link - Dispatch — what a link hands back: one flat
{ unary, stream }pair keyed by wire tag. It is the seam between the client face and the transport. → Reference - Watchdog — a heartbeat that tells a live connection from a silently dead one, since a socket can read open while no bytes flow. Wire links carry one. → @kolu/surface-app
- Health — what
client.health()reports: whether the transport is up, and what each subscription is doing. The app decides what to show. → Reactive honesty - Reactive honesty — the discipline that a live view never silently lies. It opens with a snapshot, fails loud on a broken stream, and is read fine-grained. → Reactive honesty
Long-lived processes (daemons)
- Daemon — a long-lived local process that serves a surface over a socket and outlives the clients that connect to it. → The daemon spine
- Pid gate (single-instance) — an atomic claim on disk, so only one daemon serves a given home. A second instance finds the gate held and steps aside. → @kolu/surface-daemon
- Daemon spine — the part of a daemon that never changes shape, so a client can ask which build it is talking to across a version mismatch. → The daemon spine
- Frozen control core — the identity channel of the spine, read before the versioned handshake, so a contract skew cannot hide the answer. → The daemon spine
- Supervisor — the client-side half that spawns, watches, recycles and upgrades a daemon. It runs in the client process, never in the daemon. → @kolu/surface-daemon-supervisor
- Recycle and converge — replacing a running daemon with a new build without dropping connected clients.
convergeprobes the running identity, decides by policy, then enacts. → Recycle and upgrade - Baked identity (
staleKey/navigableCommit) — a build hash and a git commit baked in by Nix, which a daemon reads back at runtime to say which build it is running. → Bake an identity - Contract version and build id — contract versions are ordered, so one can be newer than another. Build ids are match-only: the same, or not. → Daemon invariants
Many machines (multi-host)
- Mirror — a local copy of a remote surface, kept current over the pipe and served onward, so the browser only ever talks to a local server. → The server half
- Pump and re-serve — folding a remote agent’s frames into a local implementation (the pump), then serving that copy to your own clients (the re-serve). → Mirror over ssh
- Session — the reconnect appliance that keeps a link to one host alive:
makeSessionplus a connector, such assshConnector. → @kolu/surface-remote - Surface map — the same entry surface, keyed by host and served as one, so a client reaches any host through
app.entry(host). → The client half entries— the map’s single authority on membership. A host that is not inentriesis not in the map. → @kolu/surface-map- entry and
useEntry— the two lenses onto one host’s members.entry(key)is total and owner-free, anduseEntry(keyAccessor)re-keys a Solid view when the key changes. → @kolu/surface-map - EntryStatus (
warming/failed) — a host’s published status.warmingmeans it is in motion and resolves on its own,connectedmeans live, andfailedmeans someone has to act. → Entry contracts - KeyCodec — how a host key is encoded to the wire string every channel name and membership entry is keyed on, and decoded back. → @kolu/surface-map
- Fold envelope (void-input) — the
{ mapKey, input }shape every map call carries. A member that takes no input carries noinputfield at all. → Entry contracts - Clock seam — reprojecting a host-stamped time into your local clock. It returns
null, never a guess, when the entry has no measured offset. → Entry contracts
The apps these docs use as examples
- kolu — one browser and one Node server over a single WebSocket.
- kaval — kolu’s PTY daemon, consumed by a TUI over a unix socket. It is a daemon that is not multi-host.
- drishti — a browser fronting an ssh fleet, every host serving the same surface. It is multi-host without daemons.
- odu — a CI runner that fans stdio lanes into a unix-socket hub and projects its surface as MCP tools.
- padi — kolu’s workspace daemon, which drains a newer build in rather than killing the old one.