Using @kolu/surface (downstream consumer guide)

Declare a typed reactive surface once; the framework derives the Effect RPC group, wires the server, and binds the Solid client hooks. This is the consumer guide — changing the framework needs a paired drishti PR (see "Changing the framework" below).

Who uses it — match the closest consumer, don't hand-roll

Consumer	Shape	Notable
kolu (client+server)	one browser ⇄ one Node server, ONE ws	single-tier; two sibling surfaces; uses surface+surface-app only (not -remote)
drishti (srid/drishti)	browser ⇄ Node ⇄ ssh agent mirror	the canonical twin; 3 workspaces (common/agent/app)
odu (juspay/odu)	CI runner: stdio lanes → unix-socket fan-in → CLI/MCP	serve+consume+mirror over every transport at once; surface-mcp projection
kolu-cli (kolu ls/create/send/wait/…)	one-shot CLI verbs, no browser	the primary CLI consumer: a PURE padi client — transport-blind {client,dispose}, unix-socket local, ssh remote (--host); no .use() hooks. padi-tui/kaval-tui are the same shape, retiring

The spine (real import paths)

• Define — defineSurface({cells,collections,streams,events,procedures}) (@kolu/surface/define). Many surfaces over one transport: composeSurfaceContracts(map) + sibling clients, never merged. Several flat GROUPS onto one wire (a sibling bundle beside a keyed map, hand-written root procedures, an unprefixed root surface): mergeDisjointGroups({label: group}) — the one counted merge, which names the tag and both halves on a collision. Never a bare RpcGroup.merge (last-writer-wins, silent).
• Serve — implementSurface(surface, deps) / implementSurfaces(map, base, perKeyDeps) (@kolu/surface/server) returns a supervised runtime { router, ctx, done, close }. router is the FINAL top-level router — serve it directly (no implement(surface.contract).router(...) re-wrap; a second finalize double-prefixes /surface/surface/… and 404s). Observe done (owned-fault channel) and own close at teardown. Serve on a SHARED caller-owned publisher via implementSurfaceOnPublisher / implementSurfacesOnPublisher. A ROOTED bundle whose sibling set MOVES while it is served is implementRootedSurfaces(core, base, coreDeps) — mount(key, surface, deps) returns a MountedSurface {key, surface, ctx, drop()} (the registration carries its own undo), group/handlers are LIVE reads (read them as a pair in one turn), composition is INCREMENTAL (survivors keep handler identity, stores and sources), and a drop refuses at a record an open connection already captured — in-flight subscriptions included (SurfaceSiblingDropped). Live-ness is a property of the ROOTED door because a rootless wire's reserved probes target the FIRST sibling, which a moving roster can drop.
• Consume (SolidJS) — surfaceClient(surface, link) / surfaceClients(link, map) (@kolu/surface/solid) → client.cells.X.use({authority,initial,onError}), .collections.X.use({keys,onError}) then .byKey(id)?.() / .keys(), .streams.X.use(inputFn,{onError}) with .pending()/.error(), .events.X.use(inputFn,handler).
• Consume (CLI/TUI) — no reactive hooks; raw awaited conn.client.surface.<verb>(…) + async-iterator iteration; a live board uses mirrorRemoteSurface(spec, client, {collections,streams}, {log}) (@kolu/surface/mirror) into plain callbacks.

Links (transport, swappable)

websocketLink(ws) (/links/websocket) · stdioLink (/links/stdio) · unixSocketLink({socketPath}) (/links/unix-socket) · directLink(router) (/links/direct, in-process identity, for tests). Serve side: serveOverStdio (/peer-server), serveOverUnixSocket (/unix-socket), and for browsers serveSurfaceApp (@kolu/surface-app/serve) — don't hand-roll a listener: it owns the whole order (origin gate → upgrade → stale-tab check → heartbeat enrolment → serve) plus the shell layers, the bind and the scope-registered teardown, and it reads the inbound frame cap from RPC_MAX_FRAME_BYTES so a consumer cannot undercut the wire. TLS (tls), an HTTP middleware, an app's own routes and a dist-less dev shell (clientDist is optional) are all options — kolu's own listener rides it. Reach past it to the granular acceptSurfaceSocket + serveSurfaceSocket only when the app picks WHICH runtime serves each upgrade — ?host= per-host dispatch (drishti), the one decision the accept seam leaves at the call site. CLIs keep ONE transport-blind Connection = {client, dispose} so every command is written once across local vs ssh. serveSurfaceApp and serveOverUnixSocket take an optional per-face expose (@kolu/surface/expose: exposeFace(surface, map) / exposeFaces for a bundle / exposeRootedFaces for a root beside a bundle, the same ExposeMap serveSurfaceAsMcp takes and the same classifyExpose grammar), so a verb can be reachable over the unix socket and not to browsers. WHICH faces take a map, which gate themselves, and what a key grants are stated once — in that module's header. Read it there rather than from memory.

Mirror a remote surface (drishti / pulam-web / odu)

1. Dial the host — makeSession({connectOnce: sshConnector<contract>({host, binary, resolveDrvPath})}) (@kolu/surface-remote): long-lived, nix copys the agent closure, runs <bin> --stdio over ssh, reconnects. buildRemotePool fans out N hosts; one-shot CLIs use dialAgentOnce instead.
2. Mirror inward — pumpRemoteSurface({source, session, makeSink, …}) (-remote) folds the remote agent's frames into a local implementSurface re-serve via a SurfaceSink (makeSink, @kolu/surface/mirror). The parent implements the same surface; a remotely-unobservable cell (e.g. connection state) is parent-authoritative.
3. Re-serve — the local re-served surface (a FINAL implementSurface router) served on /rpc/ws, accepted via acceptSurfaceSocket (@kolu/surface-app/server). Browsers connect with connectSurface (@kolu/surface-app/solid), which bundles socket + websocketLink + surfaceClient + a default-on liveness heartbeat. connectSurfaces is the multi-surface twin, and its core: {surface, name} slot carries an UNPREFIXED root beside the siblings — typed client, health enrolment under name, and the reserved probes addressed to the root's bare surface/system/*. A rooted app has no reason to hand-assemble the seam. A SIBLING ROSTER CHANGE IS A REDIAL, not an update — Effect RPC bakes the RpcGroup into the client at openWireLink, so new tags need a new wire at both ends; conn.redial(surfaces) owns it, re-using this connection's own options, keeping the root, and dialling the replacement BEFORE releasing the old wire.

Gotchas (hard-won, all real)

• Procedures call off the FULL link, not the scoped client — surfaceClients per-key .rpc is typed unknown; reach the root link for raw procedures.
• Raw streaming — unenrolledStreamCall(client.X, input, {signal, onRetry}) (@kolu/surface/client) carries the reconnect (STREAM_RETRY) context; a bare client.X(…) silently loses it. There is no stream namespace (the streaming skill owns the full rule).
• Consume streams fine-grained — value-bearing → .streams.use() (replace-each-frame); delta-accumulate → mirrorRemoteSurface / createSubscription+reduce. Never coarse-read-and-copy: same-shape frames coalesce and the view freezes.
• Snapshot-then-deltas + fail-fast — a cell always opens with a snapshot; firstFrameOrThrow (@kolu/surface/first-frame) treats an empty stream as a link failure, never a silent empty.
• Liveness is on by construction — framework-reserved surface.system.live; connectSurface / HostSession / createServerLifecycle default their watchdog to it (probeSurfaceLive). Don't nominate your own probe unless you mean to.
• Version skew — gate on isContractVersionCompatible (major.minor), never a string ==.
• Nix-baked deps — odu declares no @kolu/* in package.json; they're symlinked at Nix build (the bake-in-via-Nix convention). A bare pnpm install won't resolve them.

Reference

Runnable end-to-end: packages/surface/example/ (its mini-ci stdio example is odu's seed). Full API + rationale: each package's README.md. Match the closest consumer above; don't reinvent a primitive the table already shows how to use.

Changing the framework

The consumer guide above is for using the stack. Changing it has two gates and one docs requirement: the drishti pair, the ODU-IMPACT verdict, and the Reference-page update below.

Surface libraries are shared — mirror API changes to drishti

@kolu/surface and its sibling libraries (@kolu/surface-app, @kolu/surface-map, @kolu/surface-remote, and — since drishti's durable agent landed (UW3) — @kolu/surface-daemon and @kolu/surface-daemon-supervisor) are not kolu-internal: they are consumed by drishti as well as kolu. Drishti's daemon serves the frozen control-core fragment, rides daemonHome/daemonMain/frontDaemonOverStdio, converges via convergeAdmit/probeDaemonIdentityFrom, and imports ./upgrade-window.testlib — the daemon packages are production surface for it, gate file included. Drishti's client reads the host map through @kolu/surface-map: EntryState and the entries collection back its host dot, its fleet card, its tab chip and its readiness gate across a dozen files.

How this list is kept honest: it is the set of @kolu/* packages drishti IMPORTS FROM SOURCE, which is not the set it hydrates into node_modules. Re-derive it, never recall it — grep -rhoE '"@kolu/[a-z-]+' packages/*/src --include=*.ts --include=*.tsx | sort -u in a drishti checkout. Today that yields exactly the five above plus @kolu/solid-pwa-install (one import, TabStrip.tsx), while @kolu/log and @kolu/shell-quote are hydrated by Nix and imported by nothing — so they need no gate. solid-pwa-install is deliberately outside this rule (it is not part of the surface stack and its one consumer is a leaf hook); if it ever grows a second consumer or a contract-shaped API, it wants a gate of its own rather than a quiet addition to this one.

Any API-facing change to packages/surface/, packages/surface-app/, packages/surface-map/, packages/surface-remote/, packages/surface-daemon/, or packages/surface-daemon-supervisor/ — exported types, function signatures, the Effect RPC contract (the defineSurface spec, the wire tags an RpcGroup mints from it, a member's payload/success/error Schema), package exports, runtime behaviour a consumer depends on, or anything else that changes how a downstream consumer wires these packages — requires a corresponding PR to github.com/srid/drishti that updates drishti for the change and passes full CI.

• Open the drishti PR before (or alongside) merging the kolu change, and link the two PRs to each other. Cut and keep the pair branch on CURRENT drishti master: git fetch origin and branch off origin/master at open — never a stale local master — and merge origin/master into the pair branch again at every repin, confirming GitHub reports it MERGEABLE before calling it ready. The recorded failure: a pair PR (drishti#107) cut off a stale base reached the human CONFLICTING — unmergeable at the exact moment it was needed.
• The drishti PR is not optional and "done" is not "done" until drishti's CI is green against the new surface API.
• The gate is only satisfied against the final kolu HEAD — re-validate it after any post-gate edit that touches the surface API. A drishti CI green pinned to a pre-gauntlet SHA is stale: the review gauntlet (lens/debate/police) and CI fix-commits routinely reshape the shared API after the gate first passed — e.g. a gauntlet fix dropping a parameter (pumpRemoteSurface's makeSink client arg) silently breaks drishti's consumer ((_client, {seq}) → ({seq})), which a gate validated at the earlier SHA never caught. Whenever the surface API moves after the gate was last green, bump the drishti PR's pin to the final kolu HEAD and re-confirm its CI is green there before calling it done.
• Purely internal changes (private helpers, tests, comments, refactors with no observable API delta) do not need a drishti PR.
• The recorded near-miss this list's completeness exists to prevent: juspay/kolu#2129 added an arm to @kolu/surface-map's client-facing EntryState — a change that fails drishti's build outright — while surface-map was absent from the package list above. The gate did not fire, and the pair PR (srid/drishti#134) was opened only because the author grepped drishti's tree by hand. A glob that is nearly right is worse than an obviously partial one: it reads as authoritative, so nobody re-derives it. Hence the grep above, and hence this note.

The third consumer — odu rides a loose pin, and pays with a verdict

odu also consumes @kolu/surface*, but deliberately loosely: it pins kolu by npins and absorbs changes at its own pin bumps — there is no per-PR odu pair (three-repo lockstep was considered and rejected; drishti is the tight twin because it tracks kolu master continuously). The recorded failure this section exists to prevent: a whole campaign of surface changes accumulated with zero odu-impact accounting, so nobody knew what the eventual bump would break until it was scheduled.

• Every PR the drishti gate applies to also posts an ODU-IMPACT VERDICT in its body — one of breaks-at-bump / adoption-opportunity / none, each grounded by an actual grep of odu's tree at its pinned kolu SHA for consumption of the changed exports (a verdict without the grep is hollow).
• Any non-none verdict is appended as a line item to the standing ledger — odu#43 — naming the kolu PR, the affected odu site, and the verdict. The ledger, not memory, is what the next pin bump drains.
• A breaks-at-bump item makes the next bump schedulable work, not someday-work — the coordinator surfaces it; the bump PR's body checks off every drained line item.

Surface public-API changes must update the Reference docs in the same PR

The @kolu/surface* packages each have a Reference page in the four-quadrant Surface docs at website/src/content/surface/. Those pages are the austere, authoritative record of the public API — they are only trustworthy if they move with the code.

Any public-API change to one of these packages — an exported type or function signature, the Effect RPC contract (the defineSurface spec, the wire tags an RpcGroup mints from it, a member's payload/success/error Schema), package exports, a member added to or removed from defineSurface, or any runtime behaviour a documented consumer wires against — must update the matching Reference page in the same PR.

Package	Reference page
@kolu/surface	website/src/content/surface/ref-surface.mdx
@kolu/surface-app	website/src/content/surface/ref-surface-app.mdx
@kolu/surface-mcp	website/src/content/surface/ref-surface-mcp.mdx
@kolu/surface-cli	website/src/content/surface/ref-surface-cli.mdx
@kolu/surface-daemon	website/src/content/surface/ref-surface-daemon.mdx
@kolu/surface-daemon-supervisor	website/src/content/surface/ref-surface-supervisor.mdx
@kolu/surface-remote	website/src/content/surface/ref-surface-remote.mdx
@kolu/surface-map	website/src/content/surface/ref-surface-map.mdx

• Update the affected entries (names, signatures, tables, snippets) so the page describes the new surface, not the old one. If the change touches an invariant, update surface-daemon-invariants.mdx or the relevant Explanation page too.
• "Done" is not done until the page matches the shipped API. This is the mirror, on the docs side, of the drishti-consumer gate above — the same "the record must not lie" discipline that the docs themselves are built on.
• Purely internal changes (private helpers, tests, comments, refactors with no observable API delta) do not need a docs update.
• A new export that a consumer is meant to use is an API change: add it to the Reference page. If the package's README changes shape, keep the ~15-line README (identity + install + one snippet + links into the quadrants) pointing at the Reference page rather than duplicating it.