The Surface framework · the kolu Atlas

Surface is how a kolu-family daemon publishes its live state. A daemon declares its data once — cells, collections, streams, events, procedures — as a typed surface, and the framework does the rest: serve it over a socket, mirror it across machines, re-serve a mirror to further consumers, and hand every client a typed reader. Three applications consume it today: kolu (padi + kaval), drishti, and odu.

The packages, one line each:

@kolu/surface — the core: declarations, serving, the mirror, the typed client.
@kolu/surface-map — a dynamic keyed map of remote surfaces over one socket (hosts come and go; the client keys on membership).
@kolu/surface-remote — the ssh leg: sessions, host fan-out, connection state.
@kolu/surface-daemon / -supervisor — the daemon spine (socket lifecycle, contract handshake, identity) and the side that supervises daemons (convergence, drain/recycle).
@kolu/surface-app — the app shell for browser apps run against your own server (delivery, identity, connection lifecycle).
@kolu/surface-mcp — a rooted bundle (core + siblings, live roster) re-exposed as an MCP server.
@kolu/surface-cli — the same rooted bundle projected as command-line verbs, the sibling key as the first argv word (the argv sibling of the MCP adapter: one expose map, one verb table, one set of names).

How the runtime is shaped

The reactive bridge — backend reactivity: state is a signal, derived state is a computed, the wire is a signal boundary.
The reactor engine — decided — the engine behind the bridge: Effect’s Atom, since the daemon’s whole vocabulary became Effect.
The surface-framework consolidation plan (surface-runtime-boundary) is shipped and archived.

Learn it — the primers

How a surface ships live data — value-bearing vs pulse-then-requery, and why kolu uses both.
The client half, taught — what surface-map added: membership, EntryStatus, per-entry scopes.
The hosting side, taught — how a surface travels between machines: serve, mirror, re-serve, sessions, the host registry.
The attention pieces, taught — the cell’s updated() and the notify seam behind cross-host attention.

The package notes

surface-daemon — one spine for kaval and odu serve.
surface-app — the app-shell electricity and its lifecycle (includes the connection plumbing that surface-connection graduated).
@kolu/surface-mcp — the MCP adapter (archived plan).
@kolu/surface-cli — the argv adapter (see kolu.dev/surface/ref-surface-cli).
remoteSurfaces — the keyed map of re-served remote surfaces the host switch stands on.

The design records

Surface hosting — the four roadblocks — the build-time design questions the hosting work answered in code.
Electricity — the volatility doctrine that decides when something graduates into a @kolu/* package at all; every extraction above passed its tests.