kolu
Docs

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. converge probes 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: makeSession plus a connector, such as sshConnector. → @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 in entries is 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, and useEntry(keyAccessor) re-keys a Solid view when the key changes. → @kolu/surface-map
  • EntryStatus (warming / failed) — a host’s published status. warming means it is in motion and resolves on its own, connected means live, and failed means 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 no input field 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.