@kolu/surface reference
The core package. You declare a surface with defineSurface, serve it with
implementSurface, and consume it with surfaceClient. Everything below is
imported from a @kolu/surface/* subpath.
Defining a surface
You declare the whole reactive surface of an app at one site, with
defineSurface, and compose several of them into one wire.
| Export | Subpath | What it is |
|---|---|---|
defineSurface(spec) | . | Declares a surface and returns a Surface<S>. |
WireSchema<T> | . | The schema bound every wire field meets. |
| The five member kinds | . | cells, collections, streams, events, procedures. |
Declaring array identity — arrayKey | . | The field that identifies an element of an array inside a member’s value. |
Surface<S> | . | The declared value: group, tagPrefix, spec, descriptors. |
ProcedureSpec.error | . | A procedure’s declared error channel. |
| The three reserved members | . | surface/system/{live,identity,clockNow}, injected by the framework. |
probeSurfaceClockNow(client) / measureSurfaceClockOffset(client) | . | The raw clock round-trip and the offset it yields. |
| Composing siblings | . | composeSurfaceContracts keys several surfaces into one flat group. |
mergeDisjointGroups({ <label>: group }) | . | Merges flat groups and proves no tag was swallowed. |
isStandaloneRoot(surface) / notStandaloneRootDetail(seam, what, tagPrefix, alternative) | . | The rooted-root check and its shared sentence. |
Declaring a client error policy — defineSurfaceWithPolicy | . | Threads an app-typed client error policy through the spec. |
defineSurface(spec)
Declares the whole reactive surface of an app at one site and returns a
Surface<S>.
export const surface = defineSurface({
cells: { load: { schema: Load, default: ZERO } },
collections: { processes: { keySchema: Pid, schema: Proc } },
streams: { nodeLog: { inputSchema: NodeId, outputSchema: LogFrame } },
events: { autosave: { inputSchema: DocId, outputSchema: SavedAt } },
procedures: { proc: { kill: { input: KillArgs, output: Killed } } },
});
- Every schema on the spec is a
WireSchema<T>. - It claims every tag as it walks the spec and throws on a duplicate, then asserts the assembled group’s size against the claim count.
- A member or verb name that is empty or contains
/is refused outright, becausestream "conn/get"andprocedure conn.getwould otherwise spell the same tag with different (member, verb) pairs. - Plain
defineSurfaceis theTPolicy = nevercase ofdefineSurfaceWithPolicy: itsclientslot is unfillable, so callers that declare no policy pay nothing.
WireSchema<T>
The bound every schema on a spec meets. A wire field is an Effect Schema, and
specifically a WireSchema<T> (Schema.Codec<T, unknown, never, never>): decode
and encode must require no Effect services, because the wire has no environment
to provide them. That is a type bound, not a convention.
Two spellings are fixed for a wire field. The other Effect variants change the encoded bytes.
| Kind of key | Spelling |
|---|---|
| Optional | Schema.optionalKey, never Schema.optional, which round-trips an explicit undefined through null. |
| Defaulted | Schema.withDecodingDefaultKey: the encoded side stays T and the key stays omittable. |
The five member kinds
A surface has five member kinds. The first four are the reactive primitives;
procedures is the imperative escape hatch.
| Member | Question it answers | Cardinality | Server sends | Client-mutable | Current value |
|---|---|---|---|---|---|
cells | ”What’s the current X?“ | one singleton | snapshot, then deltas | yes | yes |
collections | ”current X for each key?“ | many, keyed | per-key snapshot, then deltas | yes | yes (per key) |
streams | ”live output for input I?“ | one per input | snapshot, then deltas | no | yes |
events | ”has X happened?“ | occurrences | occurrences, no snapshot | no | no (handler-based) |
procedures | ”do this now” | per call | a return value | — | — |
- Cells, collections, and streams are state: a current value to render.
- An event is an occurrence: a handler fires per yield and there is no current value.
- Anything genuinely outside these shapes (bidirectional binary streams, custom
retry plumbing) stays outside the surface as a raw
Rpcin the host’s own group. - For why these four and not one, see Why surfaces.
Declaring array identity — arrayKey
A CellSpec, a StreamSpec or a CollectionSpec may declare
arrayKey?: string, the field that identifies an element of an array inside
that member’s value (for a collection, inside one entry’s value).
streams: {
page: { inputSchema: PageRequest, outputSchema: PageReading, arrayKey: "key" },
}
- It exists because
solid-js/store’sreconcilecannot be told this anywhere else, and a framework merging arbitrary app payloads must not guess it (see how a push reconciles). - Undeclared, a frame replaces every array element it merges, so a frame that repeats itself still notifies every reader of every array.
- Declared, an array whose elements carry the field is diffed by it: a repeated frame notifies nothing, and a reorder moves the objects rather than rewriting them.
Name a field the schema types required and non-nullable
The merge decides keyed-versus-positional for a whole array from its first element’s value, so an optional field lets whichever row happens to be first decide for every other row in that frame.
- It cannot corrupt anything. An object survives a position only when its key matches the one already standing there, so a mismatch replaces rather than recycles.
- It silently drops that frame back to the undeclared behaviour. The schema is where that is made unrepresentable; the merge sees values, not schemas.
Three things arrayKey is not
- Not a
CollectionSpec.keySchema. That is the dictionary key a collection’s entries are filed under, on the wire and in the store;arrayKeynames a field inside one value. A collection declares both. - Not per-array. One field per member, because
reconciletakes one, and it reaches every array in the value at every depth. - Not a use-site option. It is declared on the spec and travels on the member’s
descriptor, so no
.use()call site can spell it, override it, or disagree with another call site about it.
Which of a collection’s two deliveries applies the arrayKey is decided per call
site. The per-key path (.use({ keys }), and any collection whose verbs omit
deltas) merges an entry’s value through the same seam a cell’s goes through, so
it honours the declaration. The batched deltas path replaces each named leaf
whole rather than merging, since a fold consumer may be holding that very
object, so there is no merge there for a key to govern.
Arrays whose elements do not carry the field are merged by position: that is the declared reach of the key, not a fallback around it, and it too is silent on a repeated frame. Name the field that identifies the arrays whose identity a consumer actually follows, and read the rest by value.
The field is also identity wherever it appears, not only inside arrays: a nested object that happens to carry the field is merged in place while the field reads the same, and replaced whole the moment it reads different.
Surface<S>
The value defineSurface returns. It carries four fields, and the wire it
describes is one flat tag namespace.
| Field | Meaning |
|---|---|
group | the flat Effect RpcGroup — one Rpc per member verb, tagged <tagPrefix><member>/<verb> |
tagPrefix | "surface/" standalone, "surface/<key>/" for a composed sibling — carried on the value, never assumed by a caller |
spec | the declaration verbatim; read member types back with SurfaceTypes<typeof surface.spec> |
descriptors | the Cell/Collection/Stream/Event handles, for the manual escape hatch |
- There is no router and no nesting on the wire, only string tags. A cell
loadmintssurface/load/get; a procedureproc.killmintssurface/proc/kill. - The
surface/root is what keeps a surface composable with hand-written raw RPC: a host mergessurface.groupwith its own group and no host tag (terminal/create,git/status) can collide with a surface member. - The flatness is checked, not assumed.
RpcGroup.makeis a plainMap.set, so a colliding tag is silently overwritten;defineSurfaceclaims and counts tags instead. groupis typed with the erasedRpc.Anyelement. It is assembled from a runtime spec walk, so its type parameter carries nothing a caller could trust.- Per-member precision lives in the spec-derived
SurfaceRpcsFor<S>and its_tagprojectionSurfaceTags<S>, and in the bound client faces.
ProcedureSpec.error
A procedure may declare an error channel: ProcedureSpec.error, one Effect
Schema, normally a Schema.Union of Schema.TaggedErrors.
client.procedures.lifecycle.recycleKaval().pipe(
Effect.catchTag("KavalBusy", (e) => /* typed: e is the declared class */ …),
);
- A declaring handler fails with an instance of a declared class. The caller
receives it decoded,
_tagand data intact, and narrows on the_tag. - A typed domain error does not flatten to an opaque transport failure at a
generic hop, through a
SurfaceMap’s keyed proxy andmirrorRemoteSurface’s forwarders included. - A procedure call is an
Effect, so the declared union rides its error channel and you narrow it there. There is noerrors: ErrorMapkeyed by a code string. - The channel is the declared union plus
SurfaceCallFailure, which is Effect RPC’sRpcClientErrorand the framework’s own tagged vocabulary. A transport death is never mistaken for an application rejection, and once you have caught every declared tag the compiler still reports the transport failure as unhandled. WriteEffect.orDieif you mean “any failure here is fatal”. - An undeclared throw is a defect (
Effect.die), not a failure. It crosses as an opaque defect, which remains the fail-fast crash-loudly channel. - Declare exactly the failures a caller can act on. An undeclared spec resolves
its error channel to
Schema.Never(“declares no failures”).
The three reserved members
Every surface also carries three framework-reserved members at
surface/system/{live,identity,clockNow}, injected by defineSurface, answered
by the server, never declared or implemented by an app (see
Liveness).
- They share one
systemnamespace with any app-ownedsystemprocedures. Only a duplicate tag is a boot-time collision. system/clockNow(@kolu/surface/clock-now) returns the server’s own wall clock ({ epochMs }), so a consumer that binds a remote surface can measure the clock offset between the two hosts once at admit.
probeSurfaceClockNow(client) / measureSurfaceClockOffset(client)
The raw clock round-trip and the offset derived from it.
probeSurfaceClockNow(client)performs the raw round-trip and fails with a typedClockNowUnavailableErrorwhen the member is structurally absent. The check is inside the effect, so an absent member arrives on the channel the caller is already handling rather than throwing at the moment the probe was merely built.measureSurfaceClockOffset(client)returns the RTT-compensated offset (round(remoteEpochMs − (sentMs + rtt/2))), sampling local time at the round-trip midpoint so the one-way latency does not bias the result.- Both take the value carrying
.surface(aSurfaceFaceor a bound client). - Both are
Effects: a caller that gives up cancels the in-flight probe by interrupting, so there is no signal to pass. probeSurfaceLive(client)andprobeSurfaceIdentity(client)are the same shape.
Composing siblings
composeSurfaceContracts({ <key>: surface }) keys several standalone surfaces
into one flat group and returns { group, siblings }.
- Composition is per-sibling tag prefixing (
surface/<key>/<member>/<verb>), never a bareRpcGroup.merge: every surface carries the same three reservedsystem/*members, so merging two bare groups would collide them, silently,mergebeing last-writer-wins. - Each
siblings[key]is the sameSurfaceshape as a standalone surface, carrying only its own members at its owntagPrefix. That is what lets handler binding and client dispatch be keyed by sibling without re-deriving the tag rule.
mergeDisjointGroups({ <label>: group })
Merges several flat groups into one and proves nothing was swallowed.
RpcGroup.mergeis a last-writer-winsMap.set, so a tag two halves both spell survives once and then answers under the other’s schema: well-formed, one member short, and invisible downstream.- Every tag is claimed into one map before any merge runs, and a tag claimed twice throws naming the tag and both labels. The halves arrive labelled because the useful half of a collision report is which two of the caller’s own halves claimed it.
- Its consumers are
composeSurfaceContractsitself, a rooted bundle’s root beside its siblings (connectSurfaces’core), a keyed map’s group or a host’s hand-written root procedures multiplexed on the same wire, and a server’s served superset. - The value type is open, so a precisely-typed group (
RpcGroupis invariant in its element union) goes in without a cast and the result is the erased group every serving and transport seam takes. - A merge of nothing is the empty group, the identity. A rooted wire whose sibling roster is empty this run composes one, and refusing it would make that wire unspellable.
isStandaloneRoot(surface) / notStandaloneRootDetail(seam, what, tagPrefix, alternative)
isStandaloneRoot(surface) and notStandaloneRootDetail(seam, what, tagPrefix, alternative) are the predicate for a rooted bundle’s root and the sentence that
explains a refusal, beside the tag prefix they are about.
- A rooted bundle’s root must be a standalone surface. A sibling-scoped one
would bind its members at
surface/<key>/…while every sibling prefixes its own key on top of nothing, so the bundle would serve a root nobody can address. - The three doors that carry a root are
implementRootedSurfaces(serve),exposeRootedFaces(gate) andconnectSurfaces’core(dial). - Each door asks the predicate and raises its own error class with the shared sentence, naming the alternative that door can offer. Only the predicate and the sentence are shared; nothing else about the three doors is.
Declaring a client error policy — defineSurfaceWithPolicy
A member can carry an opaque, app-typed client error policy on its spec: a value
the framework never interprets, only threads to the app’s registered interpreter
when that member’s client subscription fails. The app owns both the policy union
and the interpreter; @kolu/surface names neither.
type Toast = { kind: "toast"; label: string };
const surface = defineSurfaceWithPolicy<Toast>()({
cells: {
preferences: {
schema: PreferencesSchema,
default: DEFAULT_PREFERENCES,
client: { authority: "local", coalesceMs: 150,
onError: { kind: "toast", label: "Preferences" } },
},
},
});
defineSurfaceWithPolicy<TPolicy>()(spec)is the curried form ofdefineSurfacethat threads the app’s policy unionTPolicythrough the spec. The two-step call pinsTPolicyexplicitly while the spec keeps its preciseconst Sinference.ClientCellPolicy<TPolicy>is a cell’sclientslot. TheonErrorpolicy sits flat, intersected with anauthoritydiscriminant:{ onError?: TPolicy } & ({ authority?: "server" } | { authority: "local"; coalesceMs?: number }).- There is no
initial. A local-authority cell seeds its store from the mandatoryCellSpec.default, so “local-authority without a seed” is a type error, not a runtime surprise. - The client runtime sources
authorityandcoalesceMsfrom this declaration, so a bare.cells.X.use()inherits them (a use-site value still overrides). Declaringauthority: "local"on the spec is what makes a use-site bag empty. ClientCollectionPolicy<TPolicy>is a collection’sclientslot,onErroronly: a collection’skeysfilter is per-site use-site wiring, not policy.
Registering the interpreter
The interpreter is registered at the connection seam: onClientError on
connectSurfaces (@kolu/surface-app) or connectSurfaceMap
(@kolu/surface-map), threaded inward to every buildSurfaceClient.
- The base interpreter is origin-free (
(policy, err) => void). The{ key }origin a keyed map needs is injected in@kolu/surface-map(see its reference). - A member that declares
client.onErrorbut whose client was built with no interpreter makesbuildSurfaceClientthrow at construction, so a declared policy can never route nowhere. - The policy is interpreted per subscription: a deduped cell fires once, a keyed collection’s per-key subs each fire.
Serving a surface
You wire a surface’s handlers with one of the implement* constructors. Each
returns a supervised runtime: handlers keyed by wire tag, a typed write face, a
fault promise and a close().
| Export | Subpath | What it is |
|---|---|---|
implementSurface(surface, deps, opts?) | @kolu/surface/server | Serves one surface and returns a supervised SurfaceRuntime. |
SurfaceRuntimeHandle | @kolu/surface/server | The handle every runtime answers: group, handlers, ctx, done, close. |
cells dependencies | @kolu/surface/server | store, patch? and a CellConnector<T> source. |
collections dependencies | @kolu/surface/server | readAll, upsert, remove, readOne? and holders?. |
streams dependencies | @kolu/surface/server | A source(input) stream, or a declarative poll form. |
procedures dependencies | @kolu/surface/server | Verb handlers that mutate through ctx. |
mirrorRemoteSurface | @kolu/surface/mirror | The consume-side twin of the fault audit, with onFault. |
| Stores and channels | @kolu/surface/server | The in-memory and conf-backed adapters. |
implementSurfaceOnPublisher(surface, deps, channel) | @kolu/surface/server | Serves one surface on a shared, caller-owned publisher. |
implementSurfaces(surfaces, base, deps) | @kolu/surface/server | Serves N surfaces over one transport. |
implementSurfacesOnPublisher(surfaces, base, deps) | @kolu/surface/server | The shared-publisher twin of implementSurfaces. |
implementRootedSurfaces(core, base, deps) | @kolu/surface/server | Serves an unprefixed root plus siblings that mount and drop while served. |
siblingDroppedDetail(key) | @kolu/surface/server | The one sentence a dropped sibling’s refusal carries. |
extendSurface(base, ext) | @kolu/surface/server | Composes a parent-local runtime onto a re-served base. |
superviseTerminalSource(runtime, terminal) | @kolu/surface/server | Pairs a passive owned runtime with a terminal driver. |
implementSurface(surface, deps, opts?)
implementSurface(surface, deps, opts?) wires every handler and returns a
supervised SurfaceRuntime — { group, handlers, ctx, done, close }.
Persistence and pub/sub are supplied as dependencies.
export const deps: ImplementSurfaceDeps<typeof surface.spec> = {
cells: { load: { store: inMemoryStore(ZERO) } },
collections: { processes: { readAll, upsert, remove } },
streams: { nodeLog: { source } },
procedures: {
proc: {
// A procedure returns an `Effect`. Its DECLARED failures are the spec's
// `error` schema (none here); an undeclared throw stays a DEFECT.
kill: ({ input, ctx }) =>
Effect.sync(() => {
ctx.collections.processes.remove(input.pid);
return { ok: true };
}),
},
},
};
const runtime = implementSurface(surface, deps);
// `runtime.group` + `runtime.handlers` go straight to a transport.
opts.identityis the server’s declared build triple, which the reservedsystem/identitymember serves as itsidentifiedarm. The framework stampsstartedAtandprocessId.- Omit
opts.identityand the surface is servedanonymous, stamped with the same two. implementSurfaceasserts at boot that the handler key set equals the group’s tag set. A route nobody answers (a 404 at the far end) and a handler nobody advertises are both boot crashes.- An eager-seed throw (a non-poll derived cell’s pull, a compute cell’s bind)
throws out of
implementSurfaceas a boot crash. It is not ondone.
SurfaceRuntimeHandle
The handle every runtime in this section answers.
| Member | What it is |
|---|---|
group | The surface’s own flat RpcGroup, by identity. |
handlers | Every bound member handler, keyed by full wire tag. |
ctx | The typed cells/collections/events mutation map. |
done | A Promise<void> that rejects on an owned runtime fault. |
close() | Releases every owned source. |
A unary handler returns an Effect, a streaming one a Stream. Both take the
member’s decoded payload.
group + handlers is the pair every transport takes: serveOverStdio,
serveOverUnixSocket, serveSurfaceSocket, or directDispatch in-process.
There is nothing to finalize and nothing to re-prefix at a mount site, because a
tag carries its own route.
Read the two as a pair, in one synchronous turn. That is a rule of the handle, not of any one constructor. Most runtimes hand back fixed values, so it costs them nothing.
A runtime whose served set moves
(implementRootedSurfaces) answers
both as live reads off one snapshot, so reading them either side of an await
can hand you two generations. The handler/group assertion then refuses, at a
serve door far from the await that caused it. A function written against
SurfaceRuntimeHandle cannot tell which implementation it holds.
What settles done
done rejects on an owned runtime fault (a cell connector’s wiring failing, or
one of its finalizers) and resolves after a clean close(). A serving site must
observe it and treat a rejection as fatal: log it whole, then exit through its
shutdown path so a supervisor respawns. Every fallible periodic thing is
deliberately off this channel.
| Path | Settles done? | Class |
|---|---|---|
| Builder wiring throws (one-shot guard, builder body) | rejects | runtime-fatal |
A push source’s install throws | rejects | runtime-fatal |
A poll source’s cadence install(tick) throws | rejects | runtime-fatal |
A scope finalizer throws during close() | rejects (aggregated) | runtime-fatal |
| Poll T+0 seed read/publish fails | no | cell-local — logged, cadence held, retried |
| Poll later tick read/publish fails | no | cell-local — log-skip-continue |
scan step throws | no | cell-local — stop-hold |
computed recompute throws (later read) | no | cell-local — holds last, heals |
Interruption (close()), clean close | resolves | end-of-life |
This table, on SurfaceRuntimeHandle.done, is the single home for the audit.
Nothing you hand the engine may throw
Every callback the reactive engine runs executes inside the batch drain on the
writer’s stack: an effect body, a source listener, a cell’s onWrite, a
channel subscriber.
- The framework brackets each one (
containThrow): a throw is logged loudly and contained, siblings still run, and the write completes. - The alternative is not a crash but a silent global freeze, because an exception mid-drain costs every remaining subscriber that frame.
close()
close() releases every owned source.
- Each connector runs as a fiber in its own scope, so
close()interrupts each one and awaits its exit. - A fiber’s exit already includes its scope’s finalizers, so “abort, then observe the settle, then dispose” is one await rather than three steps.
- It is idempotent, and always resolves. A teardown fault is routed to
done.
cells dependencies
cells: { <k>: { store, patch?, connect? } }. store is a CellStore<T>.
connect is a CellConnector<T>: (cell) => Effect<void, unknown, Scope>. It
is an owned source of the runtime. A failure reaches done, and close()
interrupts it, which releases whatever it acquired (Effect.acquireRelease /
addFinalizer / forkScoped).
- There is no abort signal to thread and no disposer to return. Cancellation is interruption, so an interrupted connector is end-of-life and can never masquerade as a fault.
- Install synchronously. The runtime forks the connector and Effect runs a
syncstep on the forking stack, so anacquireReleasewhose acquire subscribes is live the instantimplementSurfacereturns. - Do not fork the publish. Routing a frame through a fiber or a queue moves it
behind an event published in the same tick, which is the delivery order
kill.featurepins. Fork what must be concurrent, never the publish.
collections dependencies
collections: { <k>: { readAll, upsert, remove, readOne?, holders? } } is
persistence only; the surface wraps publish.
holders?: CollectionHolders<K> (that is (key: K) => Effect<unknown, never, Scope>)
is the last-reader seam. The wire already says when a reader opens a key: a
per-key get is a subscription, and readOne is where the server hears one
arrive. holders publishes the other end.
A reader holds key for the lifetime of the scope holders runs in, which is
the get stream’s own scope. Fiber interruption is the release: the scope
closes when the tab navigates, the socket drops, the runtime tears down, or a
one-shot reader takes its frame and leaves.
| Fact | Behaviour |
|---|---|
| Pull order | hold → channel subscribe → readOne snapshot, as contract. Pinned by test. |
| Release | Acquired in the returned stream’s scope, the same scope the channel subscription rides. |
| Multiplicity | Every get is its own stream, own scope, own hold. |
| Failure | The error channel is never, so failure is unspellable. |
| Scope | get only. keys and deltas are collection-wide streams. |
| Absent | The exact expression served today, not a wrapped equivalent. |
- A
readOnethat acts on the hold (reading a body only a held path is read for) finds the hold already in place. - An interruption anywhere, including between the hold and the subscribe or mid-snapshot, releases exactly once. A subscription nobody runs holds nothing, because the stream is lazy.
- Two readers, two holds; the first to leave takes only its own. The framework reports lifetimes and does not count: the refcount is the consumer’s.
- A defect propagates as a defect and kills that one subscription loudly. There is no degrade-to-unheld path.
- “Who holds this key” has no meaning on a collection-wide stream, and a collection-wide hold would be a second axis on the same knob.
- A collection that never asked for
holderspays zero overhead and zero behaviour delta. - Nothing crosses the wire: there is no verb, no member, no schema. A release verb a reader had to call would be a promise a closed tab cannot keep, and the readers this is about are exactly the ones that vanish.
streams dependencies
streams: { <k>: { source } }. source(input) returns an Effect Stream.
- Cancellation is fiber interruption, so there is no
AbortSignalto thread and none to forget. - Or supply a declarative poll form
{ read, install, isEqual }. - Supplying both is a type error.
procedures dependencies
procedures: { <ns>: { <verb>: ({ input, ctx }) => Effect } }.
- Mutate through
ctx.cells.X.set(…),ctx.collections.X.upsert(k, v)andctx.events.X.publish(input, payload), so the apply-and-publish chain stays single. - A procedure that declares an
errorschema fails the Effect with an instance of a declared tagged class (Effect.fail(new KavalBusy({ … }))). - An undeclared throw stays a defect, so reach for
Effect.promiseoverEffect.tryPromisewhere no error is declared.
mirrorRemoteSurface
The consume-side twin of the done audit lives in the header docblock of
mirrorRemoteSurface (@kolu/surface/mirror): every fiber it starts, how it
dies, and who is told. Neither audit may grow a mute row.
mirrorRemoteSurface takes { signal?, onFault? }.
onFaultis a structuredMirrorFault({ label, err, scope: "member" | "key" }) that a serving consumer wires at error level.- A
memberfault also rejects the mirror’sdone. That member is never re-subscribed, so the mirror is dead. - A
keyfault is key-local and never reachesdone, which makesonFaultits only notice.
Stores and channels
| Adapter | Import | Purpose |
|---|---|---|
inMemoryStore<T>(initial) | @kolu/surface/server | in-memory cell store |
inMemoryCollection<K, V>() | @kolu/surface/server | in-memory additive collection deps ({ readAll, upsert, remove }) |
confStore<T>(conf, key) | @kolu/surface/server | conf-backed persistent cell |
inMemoryChannel<T>() | @kolu/surface/server | single-process broadcast |
inMemoryChannelByName() | @kolu/surface/server | the channel factory form |
inMemoryPublisher() | @kolu/surface/server | a name-keyed { publish, subscribe } publisher |
publisherChannel<T>(publisher, name) | @kolu/surface/server | adapt any name-keyed publisher to a typed Channel<T> |
implementSurfaceOnPublisher(surface, deps, channel)
Serves one surface on a shared, caller-owned publisher.
- The ordinary
implementSurface(surface, deps)owns an internalinMemoryChannelByName(), so its in-process channels are self-contained. - Reach for
implementSurfaceOnPublisher(surface, deps, channel)when the publisher is shared, its cross-channel microtask order is load-bearing, and its teardown is the caller’s. - It is a distinct constructor, never a mode flag.
- The runtime’s
close()releases only what it minted, never the shared publisher.
implementSurfaces(surfaces, base, deps)
Serves N surfaces over one transport, keyed the same as the map. It likewise
returns a supervised SurfacesRuntime.
implementSurfacesOnPublisher(surfaces, base, deps)
The shared-publisher twin of implementSurfaces, where base carries the
channel factory.
implementRootedSurfaces(core, base, deps)
implementRootedSurfaces(core, base, deps) serves an unprefixed root surface
plus a sibling set that changes while it is served. It is the serve-side third
member of the family whose other two doors already carry a root:
exposeRootedFaces at the gate and
connectSurfaces’ core in the
browser. Like those, it is a distinct constructor rather than a mode flag on
implementSurfaces.
const runtime = implementRootedSurfaces(coreSurface, {}, coreDeps);
// …later, whenever a plugin is enabled:
const mounted = runtime.mount("kolu", pluginSurface, pluginDeps);
mounted.ctx.cells.fleet.set(next); // the sibling's own write face
await mounted.drop(); // …and the registration's own undo
| Member | What it is |
|---|---|
mount(key, surface, deps, opts?) | Mounts a sibling live: the only way one joins, at boot and forever after. |
MountedSurface | { key, surface, ctx, drop() } — the scoped sibling surface, its write face, and the registration’s own undo. |
roster | The keys currently mounted, in mount order. |
group,handlers,ctx,doneandcloseareSurfaceRuntimeHandle’s, so this serves through the ordinary door with nothing in between.ctxis the root’s, and a sibling’s rides itsMountedSurface.groupandhandlersare live reads: they answer for the roster as it stands when they are read. Read them as a pair inside one synchronous turn. A mount between the two reads hands you a group and a handler record of different generations, whichassertHandlersMatchGroupthen refuses.- A bundle whose roster moves would otherwise have two composition paths, and the one that runs at boot is the one that gets tested.
mountis transactional. The sibling is walked, its route set proved and the whole bundle re-composed before anything is committed, so a missing dep, a duplicate key or a collision with the root throws with the roster and the running sources untouched.dropis on the valuemounthanded back rather than adrop(key)verb, so a holder can retract its own sibling and nobody else’s. A stale holder’sdrop()on a key someone re-mounted is a no-op rather than a stranger’s teardown.
Which serve door re-reads group and handlers
serveSurfaceSocket
takes the pair per accepted connection, because each socket builds its own
RpcServer. An accept loop reading runtime.group and runtime.handlers
inside its onAccepted closure serves the current roster.
serveSurfaceApp and serveOverUnixSocket take the
same ServedGenerationSource:
{ group, handlers, expose? }is the generation written at the call.{ live: () => ({ group, handlers, expose? }) }is re-read at each accept, as a pair.
A socket accepted after a mount is indistinguishable from one accepted on a boot that already had that sibling. A connection accepted before the roster moved keeps the generation it was built over until the client redials. The granular accept loop remains the seam for “the app picks which runtime serves this socket” (drishti’s per-host dispatch).
Composition is incremental
Mounting walks the arriving sibling only. Every survivor keeps the handler values, cell stores, channels and running sources it already had. Re-implementing the whole map on each roster change silently forks that state, and a connection accepted before the change goes on answering out of the previous copy.
A drop reaches a connection that was already open
Each of a sibling’s tags is bound to a handler stable for that mount’s whole life, which refuses the instant the mount is dropped.
- A record captured before the drop stops serving the dropped members: a new
call gets a
SurfaceSiblingDroppeddefect. - An in-flight subscription dies with the same defect rather than hanging on a producer nobody drives any more.
- A unary call already in flight is left to finish. It cannot go stale, because it does not outlive its own answer.
- A key that is dropped and later re-mounted mints a new handler at the same tags, so a recycled name can never route a stale connection into a different sibling’s members.
drop()is idempotent and always resolves. A teardown fault reachesdone, the runtime’s one owned-fault channel, exactly as a finalizer faulting duringclose()does.
Channel names under a root
The root’s channels are its own (<member>:changed). A sibling’s are prefixed
by its key and its mount generation (<key>#<n>/<member>:changed), not the
<key>/<member> rewrite implementSurfaces performs. A key here can be dropped
and re-used and the publisher is name-addressed, so the plain rewrite would let
the new occupant subscribe to topics the retired one still publishes into. The
generation is internal: channel names never cross the wire.
A dropped sibling’s ctx refuses, and so does a closed bundle’s
A mount has two faces, the wire handlers and the write face mount handed back,
and a drop retracts both.
- Every accessor on
MountedSurface.ctx, reads included, throwsSurfaceSiblingDroppedfrom the instant of the drop. - That covers the sibling’s own procedure handlers too, which close over the same retracting value. An in-flight unary call is deliberately not interrupted, and its side effects would otherwise outlive the drop and write into a store nobody serves.
close()is the runtime-wide drop and retracts every surviving mount for the same reason.- The root’s
ctxis the deliberate asymmetry:SurfaceSiblingDroppednames a sibling, and the root is not one.
What reaching done costs
A done rejection is structural wiring death a serving site must treat as
fatal, so one sibling’s teardown finalizer faulting ends the whole bundle, root
included. Those are the two rows the done audit table
carries for this door. A host that mounts siblings it does not control is
accepting that: a source nobody drives is damage.
How a client learns the roster moved
This door and
conn.redial
are the two ends of one axis, and the framework carries the middle (“the served
roster is now [a, c]”) nowhere.
- A consumer publishes it and drives
redialoff it. A cell on the root is the natural carrier, since the root is on every serve this wire can reach. - An over-firing effect that re-publishes an unchanged roster costs nothing,
because
redialis idempotent: a roster the connection is already on dials no wire. - Forgetting it fails silently. Clients never learn about the new sibling and nothing errors.
- A framework-reserved
system/rostercell plus aconnectSurfacesoption that redials on its change is the receptacle that would close it, recorded as an atlas candidate rather than built at a population of one.
Why the live door is the rooted one
A composed wire’s two reserved round-trips, the system/identity echo and the
system/live watchdog, must address a member on every serve the wire can reach.
- On a rootless bundle that target is the first sibling, and a first sibling that can be dropped is not a target. A watchdog probing a tag the serve stopped carrying reads “unknown member” as a dead wire and reconnects forever.
- A root is by definition on every serve, so
liveis a property of the rooted door andimplementSurfacesstays the fixed bundle it is. - There is no
*OnPublishertwin of this door. The shared-publisher constructors exist because kolu’s shared publisher carries non-surface channels and its teardown is the caller’s, and no rooted-bundle consumer has that problem.
siblingDroppedDetail(key)
The one sentence a dropped sibling’s refusal carries: “the sibling "<key>" was
dropped from this rooted bundle”, read by SurfaceSiblingDropped.message.
- Its second reader is not on the wire at all:
@kolu/surface-mcp’s retirement table, which words the same fact for an agent holding a staletools/list. - Each caller keeps its own surrounding clause (what the name was, what to do
next). Only the sentence is shared, the same arrangement
notStandaloneRootDetailmakes for the three rooted doors.
extendSurface(base, ext)
extendSurface(base, ext) composes a parent-local runtime (ext) onto a
re-served base (a reServeSurface mirror of a remote agent) into one served
surface. Parent-owned additions stay causally separate from mirroring:
post-commit observation, no second mirror.
- Both arguments are the structural
ServedSurface<S>—{ surface, handlers, done, close }. AreServeSurfaceresult satisfies it directly. A localimplementSurfaceruntime does once itssurfacedescriptor is carried alongside. - It returns
ExtendedSurface<Base, Ext>: the same supervision contract over the merged surfaceSurface<ComposedSurfaceSpec<Base, Ext>>, a flat per-kind merge of the two specs. - Both sides’ handlers are already keyed by full wire tag, so the merge is a handler-record union under one combined group. The tags are byte-identical to what each half served alone, on every transport rather than only in-process.
- A member-name collision between base and extension fails loud. The check is on the flat, per-name wire namespace across all kinds, so a base cell and an ext procedure of the same name collide too.
- A duplicate bound tag is a second, independent crash.
- Supervision routes through
superviseTerminalSource: the base is the terminal driver (its mirror pump ends when the remote session is destroyed, the composite’s resolving edge), and the localextis passive, so only its fault settlesdonebefore close. closetears the base down fully first (base.close()awaited to completion, which aborts the base’s pump and releases the base runtime’s own sources), then releases the local runtime.
superviseTerminalSource(runtime, terminal)
superviseTerminalSource(runtime, terminal) pairs a passive owned runtime
with a terminal driver whose close: () => Promise<void> is the atomic teardown
verb: tear down and settle.
- It is the framework home for the terminal-source teardown, and the seam both
reServeSurface(a sync-abort pump wrapped as oneclose) andextendSurface(a full re-served base runtime) route through. - Both closes are always attempted in that order.
- One close failure is rethrown unchanged. Several are surfaced together as an
AggregateError.
The reactor (reactive bridge)
@kolu/surface/reactor is the one exit from a backend signal graph into the
cell machinery. State is a signal, derived state a computed, and the wire is the
signal boundary that snapshots and replays.
| Export | Subpath | What it is |
|---|---|---|
source(install, initial?) | /reactor | An external push input, installed lazily on the first subscriber. |
source({read, install}) | /reactor | An external poll input read on a caller-owned cadence. |
source({ read, install, label }) | /reactor | The poll source options, including the loop guard’s label. |
everyMs(ms) | /reactor | The fixed-interval install closure for a poll source. |
everyMsOr(ms, subscribe) | /reactor | The interval-plus-edge cadence fuse. |
assertCellConverges({ build, kick?, settleMs? }) | /assert-cell-converges | Drives a poll source in a test and asserts it settles. |
viewerAddressOf({ peerAddress, forwardedFor, hostAddresses }) | /viewer-identity | Which machine a viewer is at, behind a reverse proxy. |
scan(src, initial, step) | /reactor | Folds a source’s occurrences into a level. |
computed(fn) | /reactor | A derived value reading other graph nodes. |
batch(fn) | /reactor | Groups several graph writes into one frame. |
derived.cell(node) | /reactor | Publishes a pre-built graph node as a cell. |
derived.cell(($) => …) | /reactor | Publishes a sibling derivation as a cell. |
derived.collection(node) | /reactor | Publishes a keyed node as a collection, through a keyed reconciler. |
reactiveFamily(opts) | /reactor | A keyed family of member states, as a graph source. |
derived.registry(family, resolve) | /reactor | The pull-face MapRegistry exit over a reactiveFamily. |
The signals engine is Effect’s own Atom / AtomRegistry (effect/reactivity),
wrapped here and lint-banned everywhere else, so this wrapper is the graph’s only
exit. No engine type reaches the public surface: a node’s level is a
ReadonlyLevel<T>, with .value (the tracked read, so reading it inside a
derivation is depending on it) and .peek() (untracked).
Streams and events do not ride the graph. A signal conflates same-batch frames, and a stream must see every one.
source(install, initial?)
An external push input. Signature: (SourceInstall<T>, T?) → Source<T>.
install(emit)returns an uninstall function. It is installed lazily on the first subscriber and torn down when the last one leaves.initialseeds the level. Without it the level readsundefineduntil the first frame.
source({read, install})
An external poll input, read on a caller-owned cadence. Signature:
({read, install}) → PollSource<T>. install(tick) schedules the re-reads.
Publish it through derived.cell or derived.collection. The bridge owns the
read-failure policy:
- A read failure is cell-local at every tick, T+0 included. It is logged loudly, nothing is published (no fabricated default), and the cadence is held and retried on the next tick or edge.
- A non-overlap (
inFlight) guard keeps two reads from running at once. - It never faults
runtime.done. Connectors and builders do that; periodic reads do not. So a poll read is never the right home for a deterministic boot defect. - A consumer that must stop on a permanent verdict (padi’s port sampler on an unreadable platform) owns that decision itself, at whichever tick produces it.
source({ read, install, label })
The poll source’s full options: PollSourceOptions<T> → PollSource<T>.
label is required. It names the source in a loop-guard error, and is
diagnostics only: there is no field that can silence the guard.
Why: A poll read may reconcile, but it publishes only by returning.
The loop guard
Each read runs inside an AsyncLocalStorage context keyed to its source, so a
change edge firing under that context was caused by the read it is about to
re-trigger. Three consecutive self-caused ticks crash, naming the source.
- A read that announces on the edge that triggers it is an unbounded cycle the reactor executes forever. One such cycle froze a kolu process (HTTP dead,
SIGTERMignored). - Timer, I/O and other cells’ microtask bursts carry a different context and can never count toward the three, however fast or value-equal they are.
everyMs(ms)
The cadence half of a poll source: the fixed-interval install closure.
Signature: (number) → (tick: () => void) => SourceCleanup. Write it as
source({ read, install: everyMs(5_000) }).
- The interval is
unref’d, so a live sampler never keeps the event loop alive. - The returned cleanup clears the interval. This is the one home for the unref’d-interval hygiene every interval-driven poll source would otherwise re-spell.
everyMsOr(ms, subscribe)
The interval-plus-edge cadence fuse, for a poll whose value can move faster than
its coarse interval. Signature:
(number, (tick) => () => void) → (tick: () => void) => SourceCleanup.
- It is
everyMs’s interval plus an edgesubscribe(tick). The edge is any change source: a reconnect or state feed, a config-changed hook. - It re-reads on the tick and the instant
subscribefires. - Cleanup tears down both the interval and the subscription.
assertCellConverges({ build, kick?, settleMs? })
The authoring-time twin of the loop guard, from
@kolu/surface/assert-cell-converges. Signature: → Promise<{reads, loop}>.
Drive a poll source, kick the act that would start a
cycle, and assert it settles. Reach for it because the defect lives in the join
between a read and the edge it is fused with, which neither module’s own unit
tests can see.
viewerAddressOf({ peerAddress, forwardedFor, hostAddresses })
Which machine a viewer is actually at, for an app behind a reverse proxy, from
@kolu/surface/viewer-identity. It is the trust gate whole, so the order it
rests on is enforced here rather than by each consumer re-reading prose.
- A forwarded header on an untrusted connection is ignored entirely.
- On a trusted connection the last forwarded entry wins.
forwardedFortakes the header as a string or as a list a caller already split. Node itself folds a repeated header into one string.- Beside it in the same subpath:
viewerIsOnHost,normalizeAddress,isTrustedLocalPeer. - All of them are pure and total. DNS and interface enumeration stay with the consumer.
scan(src, initial, step)
Folds a source’s occurrences into a level; each emission steps once. Signature:
(Source<F>, S, (state, frame) => S) → ScanNode<S>.
- A step returning the previous reference (
===) means no change: the level holds and nothing publishes.
The stop-hold error law
A step that throws stops the derivation, disposes its source subscription, holds
the last value (never a fabricated reset), logs loudly, and latches stopped.
stoppedis aReadonlyLevel<boolean>, server-observable in phase 0. It gates the scan from stepping again, and distinguishes a frozen derivation from a legitimately quiet one.- A scan never heals. Recovery is a restart.
- Bridging
stoppedinto the surface’s client-side liveness, by folding it into a member’sliveWhen, is a later phase. In phase 0liveWhenreceives the serialized cell value, not the signal, so a stopped scan does not flip client health.
computed(fn)
A derived value reading other graph nodes: (() => T) → GraphNode<T>. Use it as
a private intermediate several wire members can share without any of them
becoming a wire member. It is glitch-free by the engine’s version-checked lazy
pull, and there is nothing to dispose.
batch(fn)
Groups several graph writes into one frame, so derivations recompute once:
(() => T) → T. It is the knob an app reaches for to coalesce a multi-member
burst of ctx writes. Every write the bridge itself makes already opens a batch
(the engine has no implicit batch), so this only ever nests.
derived.cell(node) / derived.cell(($) => …)
Publishes a graph value as a cell: the deps for an implementSurface
cells.<key> slot.
| Form | Signature | What it publishes |
|---|---|---|
derived.cell(node) | (GraphNode<T>) → DerivedCell<T> | A pre-built graph node (a scan, a computed). |
derived.cell(($) => …) | (($: SiblingRead<S>) => T) → DerivedComputeCell<S, T> | A sibling derivation. Reading a sibling is depending on it, so the cell recomputes when a sibling it read changed. |
The $ sibling-read face
$ is the typed sibling-read face: $.someCell(): T and
$.someCollection(): ReadonlyMap<K, T>.
- It is a plain mapped type over the surface spec (
SiblingRead<S>in@kolu/surface/define), typed at the declaration site by the deps slot, so there is nokeyofunion explosion. - An authored sibling’s graph face is a mirror the bridge pokes post-spec-equals, riding a bridge-owned store wrapper both cell write paths pass through, so a missed poke is unwritable rather than a rider held by tests. A suppressed write never pokes.
- A derived sibling reads as its own
computed, so every chain is a pure computed graph: glitch-free by the engine’s lazy pull, even across a diamond. - Declaration order is irrelevant. The boot walk builds every derived node before it seeds any, so a
derived.cellmay read a siblingderived.cellvia$whether declared before or after it. Only a genuine cycle fails.
What a derived cell guarantees
- Wire-read-only. A
derived.celldep is branded, and the boot walk crashes if that cell declares any write verb (set/patch/test__set). The graph is the member’s only writer. - Dedup at the member’s
equals, once. A derived value flows through the member’s ownequals → onWrite → store.set → bus.publishgate (theconnectseam), so the wire dedup point is unchanged and anequals-equal recompute never crosses the wire.equalslives on the member’s spec. - It never fabricates. The cell seeds from its node’s current level by an eager pull at wiring, so a throw at seed time is a boot crash and no default is served before the value exists. A compute cell’s node is built after every sibling mirror exists, then eager-pulled.
- Compute error policy is log-skip-continue. A throw in a
derived.cell(($) => …)recompute is logged and the last published value held; the next successful recompute heals it. (scan’s stop-hold is different because it carries state.) - The publish is synchronous with the writer. A derived cell’s
connectis aCellConnectorwhose acquire subscribes the node on the runtime’s own stack, and the graph notifies synchronously, so a graph write and an event published in the same tick reach a consumer in publish order. - Teardown is the scope’s.
close()interrupts the connector, which disposes the subscription and the backing node. - A poll-source cell suspends inside the connector for its T+0 seed. A failed seed is cell-local: the cell keeps serving its spec default and the cadence retries. Interruption becomes the
AbortSignalits Promise-shapedreadsees.
derived.collection(node)
Publishes a keyed node (a poll source reading a whole Map, or a computed
producing one) as a collection:
(GraphNode<ReadonlyMap<K,V>>) → DerivedCollection. It is the keyed-reconciler
wire adapter.
- It holds the current map and diffs each new frame against it by the collection’s value
equals, then drives the surface’s own per-keyupsert/removepublishers for exactly the changed and removed keys. A poll-backed collection therefore republishes only what moved. - The graph is its one writer: the ctx
upsert/removethrow.
CollectionSpec.equals?: (a, b) => boolean
Per-key value equality, the collection sibling of CellSpec.equals. It is the
reconciler’s diff predicate, declared once on the spec instead of hand-held at
each write site. Omit it and every present key republishes each frame, at an
always-moving per-tick rate.
CollectionImplDeps.materializeSiblingView?: boolean
A pure optimization behind readAll(), for an authored collection whose
readAll is an expensive per-key fold. Set it and the $-sibling read returns a
per-key cache maintained by the collection’s own upsert / remove writes,
instead of re-folding the whole collection on every $-read. That is the fix for
a derived member folding $.<coll>() on a firehose (O(M²)→O(M) recomputes).
It is safe only when every mutation flows through the ctx upsert / remove
seam, the view’s single write path.
reactiveFamily(opts)
A keyed family of member states, as a graph source:
({members, attach, onEvict?}) → ReactiveFamily<K,S>.
membersis aSource<readonly K[]>;attach(key, set)subscribes one member’s state.- It owns, once for every consumer: membership diff (attach entrants, detach and evict leavers), last-frame hold (a version-signal change edge, O(1) per frame), per-key disposal, and per-member error isolation.
derived.registry(family, resolve)
The pull-face MapRegistry exit over a reactiveFamily:
(ReactiveFamily<K,S>, (key, state?) => Entry) → DerivedRegistry<K,Entry>.
- It resolves each member’s entry on demand from its cached state, and fires
subscribeon every family change. - It is the exit half of
registryFromFamily, split along the source/exit axis.
Consuming in SolidJS
@kolu/surface/solid binds a surface to SolidJS hooks: one accessor per member,
one client per surface, and one fold face for a delta stream.
| Export | Subpath | What it is |
|---|---|---|
surfaceClient(surface, transport, onClientError?) | /solid | A client with a bound accessor per member. |
surfaceClients(transport, map) | /solid | Splits one combined transport into a sibling client per surface. |
surfaceClientsHealth(clients) | /solid | And-reduces a record of clients into one health fact. |
Subscription<T> | /solid | The accessor plus pending / error / complete and the change channel. |
.streams.X.useCollection(input, descriptor) | /solid | A keyed, read-only collection view over a stream of snapshots and deltas. |
fold | /solid | Folds a deltas collection’s whole frames into your own accumulator. |
useCollectionDeltas | /solid | The delta hook .use() drives, for an un-enrolled stream. |
surfaceClient(surface, transport, onClientError?)
Returns a client with a bound accessor per member. It replaces the source /
mutate / keyToInput refs you would otherwise thread at every hook.
const app = surfaceClient(surface, dispatch);
const load = app.cells.load.use({ authority: "server" }); // Accessor<Load>
const procs = app.collections.processes.use(); // .byKey(id) / .keys()
const log = app.streams.nodeLog.use(() => nodeId, { onError }); // .pending() / .error()
app.events.autosave.use(() => docId, handler, { onError }); // returns nothing
Effect.runFork(app.procedures.proc.kill({ pid })); // an Effect, run at the UI edge
transportis either a watchdog-backedLiveSignalHandleor a bare in-processSurfaceDispatch. See Wire links must carry a watchdog.onClientErroris the app’s one interpreter, the same slotsurfaceClientstakes in the same position.- A surface whose spec declares a
client.onErrorpolicy, built into a client without one, throws at construction: a declared policy may never route nowhere.
| Member | Hook | Returns |
|---|---|---|
| cell (mutable) | .cells.X.use({ authority, initial, applyPatch, onError, coalesceMs }) | a UseCellResult { value, pending, error, set, patch, sub }; mutate with .set(v) / .patch(p) |
cell (read-only, verbs: ["get"]) | .cells.X.use({ onError? }) | a ReadOnlyUseCellResult { value, pending, error, sub }, with no set / patch |
| collection | .collections.X.use({ keys?, onError? }) | .byKey(id)?.(), .keys(); mutate with .upsert(k,v) / .delete(k) |
| stream | .streams.X.use(inputFn, { onError? }) | a Subscription directly: an accessor plus .pending(), .error(), .complete(), .updated(...) and .changed(...) |
| collection-shaped stream | .streams.X.useCollection(input, descriptor) | a keyed, read-only collection view with byKey and fold; equal static inputs share one subscription |
| event | .events.X.use(inputFn, handler, { onError?, signal? }) | nothing (no current value) |
| procedure | .procedures.<ns>.<verb>(input) | a ProcedureEffect<O, E>, that is Effect<O, E | SurfaceCallFailure>: the declared union in a channel the compiler tracks |
- A read-only cell’s options accept only
onError. There is noauthority: "local"branch, because a get-only cell carries no wire mutation verb. - A
deltas-declaring collection’s whole-collection.use()also carries.fold({ init, step }). - A cell’s
authorityis"server"(the default: every push reconciles) or"local"(the local store wins after the first server yield). - An
inputFnthat returnsnullpauses a stream or an event.
Calling a procedure
Every declared procedure is bound at .procedures.<ns>.<verb> and typed from its
declaration: the typed dual of the reactive .use() primitives.
- The input is the encoded side of the member’s schema (the face decodes at the edge, where zod’s
.parseruns), while the result is the decoded side. A decoding default therefore stays omittable at the call site. - Positions the client also holds stay decoded: a cell’s
set/patchpayload, a collection key. The client feeds them to the spec’s ownpatchand keys its own maps with them. - A call is a description, not a request already in flight. Nothing is dispatched until the effect runs, so the call can be part of a program: several members folded concurrently, a read with a deadline, a request superseded by the next one, anything that must die on Ctrl-C. Each of those is a combinator here.
- There is no
AbortSignalto thread. Cancellation is fiber interruption, and interrupting the caller tears the call’s own work down with it.
.rpc, the structural face
.rpc serves the framework-reserved members (system.live, system.identity,
system.clockNow, never in spec.procedures) and is the escape hatch for a
member the bound shapes cannot model.
- It is the structural
SurfaceFace:rpc.surface.<member>.<verb>, typedunknownper leaf by design. Per-member precision lives in the bound faces, and a second precise mapped type over the same spec is the union-budget blowup that split avoids. - It covers every member: cells’
set/patch, collections’upsert/delete, and the reservedsystem.*. - As on the bound face, a unary leaf there is an
Effect. - A declared procedure never needs it.
How a push reconciles
A push merges by the member’s declared key, else positionally, never by an
inferred one. An undeclared merge into a bound store passes Solid’s
reconcile(..., { key: null }).
Solid’s own default is key: "id", which reads a field called id as an
element’s identity and recycles the previous row objects for the records it
thinks matched. On a payload whose elements have no top-level id, every
element’s key reads undefined and they all match, so the object that held one
record comes to hold another.
A reader that goes by position never notices. A <For> keyed by reference, a
per-row memo, or a component holding a row across frames sees a row whose
identity and whose fields disagree. A framework merging arbitrary app payloads
has no basis for inferring identity from a field name, so undeclared, an element
is replaced rather than recycled.
The member pays for that safety or opts out of it:
- Replacement is total. A frame that merely repeats what the store holds still replaces every element and notifies every reader of every array under it. A keyed
<For>tears its DOM down on every frame, and every per-row binding re-runs for every row for a one-character change in one row. - A cell or stream that declares
arrayKeyis merged by that field instead: a repeated frame notifies nothing, and a reorder moves the objects a keyed view is following. - A
deltascollection’s keyed dictionary is not merged here at all. Its hook owns a store and writes the keys a frame names, replacing each leaf whole, so an entry afoldconsumer is holding never mutates under it. - A collection’s per-key delivery does come through this merge, and honours the same declaration.
Wire links must carry a watchdog
surfaceClient throws if handed a bare wire dispatch, because a
websocketLink / stdioLink / unixSocketLink can silently half-open.
- Pass a watchdog-backed handle from
connectSurface(see @kolu/surface-app), or a baredirectDispatch, whose transport is always live. - The refusal is by brand: every wire link factory brands what it returns, so a new wire link inherits the guard.
Subscription<T>
A SolidJS Accessor<T | undefined> (@kolu/surface/solid) with .pending(),
.error(), .complete() (it latches once the stream ends normally, and the
value is then frozen), .updated(handler) and .changed(handler).
Where it sits differs by member:
| Member | Where the subscription is |
|---|---|
| stream | streams.X.use(...) returns the Subscription directly; call it for the value |
| cell (mutable) | cells.X.use(...) returns a UseCellResult, whose .value is the accessor and whose .sub is the Subscription |
| cell (read-only) | a cell declared verbs: ["get"] (a derived.cell, say) returns a ReadOnlyUseCellResult instead |
| collection | the handle depends on the delivery path (see below) |
- A mutable cell’s result is
{ value, pending, error, set, patch, sub }, wherevalueis the accessor andsubis theSubscription. The change channel is thereforecells.X.use(...).sub.updated(...). - A read-only cell’s result has no
set/patch, and its.use()accepts onlyonError, since a get-only cell has no wire mutation verb to reconcile against. - A collection view answers
error(),pending()andkeys()whatever the path. Under batched delivery the per-key handlebyKey(id)returns is assembled from the one stream’s signals, so it carries no.updated(). Askfoldinstead, which hands over the wire’s whole frame rather than one key’s before and after.
.updated(handler) and .changed(handler)
.updated() is the change half of an FRP Dynamic: subscribe to
{ prev, next } change pairs (CellChange<T>) under the change-iff-fired law.
- A first frame is a value, not a change, and never fires.
- A reconnect snapshot equal (by value) to the last-seen frame never fires.
- A frame that differs fires exactly once, with
prevthe last-seen value. - It returns a
Dispose. It is optional for the same reason ascomplete: a hand-assembledSubscription-shaped value may omit it, while every subscription this package’s factories mint provides it. .changed(handler)is the same law without the payload: same moments, sameDispose, no{ prev, next }..updated()must hand its handlers a snapshot, because the store adopts a frame and mutates it on the next write, so a retained pair would change out from under the consumer. That snapshot is twostructuredClones of a whole frame, and it is the price of the payload. Subscribing with.changed(), the clones do not happen at all.- Reach for
.updated()when you readprev/next,.changed()when you do not. Neither is a raw arrival count: an equal reconnect snapshot is silent on both.
surfaceClients(transport, map)
Splits one combined transport into a sibling client per surface. Each is built
over a tag-scoped dispatch: the face mints standalone tags and the wrapper
splices the sibling key in, landing on exactly the tags implementSurfaces
bound. It returns a bundle:
| Member | Answers |
|---|---|
clients | the per-key map, one object for the bundle’s life, mutated in place. Read a client through it; do not fold it in a tracking scope (next row) |
roster() | that same object, read reactively: the accessor reads the bundle’s own membership signal first, so a memo or a <For> that goes through it re-runs when a sibling arrives or leaves |
health() | the bundle’s combined fact: surfaceClientsHealth over its own clients, each sub’s name already prefixed by its sibling key, reactive about the roster as well as the subs |
moves(next) | would reroster(next) change anything? false when every key is present with the same Surface value. This is the bundle’s own comparison, the one reroster makes |
reroster(next) | move onto a new roster in place; returns this same bundle, retyped to the roster it now carries |
dispose() | end every client on the roster |
- Re-bind through
reroster, asbundle = bundle.reroster(next).clientsandroster()are typed on the roster, so a binding still typed on the old one keeps claiming departed keys exist. clientsis a plain object mutated in place, which is what keeps its identity across a move, and Solid tracks nothing about a plain object’s key set.- So a
<For each={Object.keys(bundle.clients)}>, a memo foldingObject.values(…), or a hand-writtensurfaceClientsHealth(bundle.clients)is blind to a roster move: it keeps naming departed siblings and never names an arrival. Reach forbundle.roster()orbundle.health()in any tracking scope. - The notification lives on the bundle, beside the mutation, because
rerosteris the only code that knows the key set moved. movesis there because the expensive half of following a roster lives one layer up:conn.redialasks it before it dials, so a roster the connection is already on costs nothing instead of a whole transport churn.
What reroster does to each key
reroster is what makes a roster change follow in
place.
- A key on both rosters with the same
Surfacevalue keeps its client, standing subscriptions and all. - A key that arrives gets a client built now.
- A key that leaves, or whose
Surfacevalue was replaced (a different contract under one name), has its client retracted and dropped from the map. - Retracted means its scoped dispatch refuses in words. A departed sibling’s client is still held by whatever component has not unmounted. Left alone it would re-subscribe through the fence onto a wire that no longer serves those tags, which reads as a broken connection rather than as what happened.
- Arrivals are built before anything is retracted, so an arrival that throws leaves the bundle on its current roster rather than half-moved.
surfaceClientsHealth(clients)
And-reduces a plain record of clients into one fact. It is the fold
bundle.health() performs, exported for a record you assembled yourself.
.streams.X.useCollection(input, descriptor)
A parameterized stream yielding collection snapshots and deltas is consumed as
app.streams.X.useCollection(input, descriptor). The descriptor supplies the
collection key and value types; the stream supplies the frames.
- Input is a static JSON key captured on acquisition. Mount a new owner to change it.
- Equal inputs share one upstream subscription and one health entry until the last owner disposes. Distinct inputs remain independent.
- The existing retry fence handles reconnection, whose first snapshot replaces the old collection contents.
fold on a deltas collection
A collection that declares the deltas verb is served by one coalesced
snapshot-then-delta stream, and the client applies each frame to a keyed store by
writing exactly the keys the frame names. That store is the right answer for a
consumer whose accumulator is a keyed map.
For a consumer whose accumulator is something else (an index, a patched document
set, a running total) the frame itself is the answer, so the whole-collection
.use() of a deltas collection carries one more member.
const view = client.collections.entries.use();
const index = view.fold({
// A full-set frame: the wire's first frame, every reconnect snapshot, and the
// seeding a fold registered mid-stream is given. Entries are the client store's
// own values, in its arrival order — the same objects `byKey` reads.
init: (entries) => buildIndex(entries),
// One coalesced delta frame — the wire's own `{ upserts, removes }`, unchanged.
step: (held, { upserts, removes }) => patch(held, { upserts, removes }),
});
index(); // Accessor<A | undefined>
init and step are the consumer’s, and A is inferred from them: the
framework never sees inside the accumulator.
| Fact | Behaviour |
|---|---|
| Snapshot | Re-initializes every registered fold (acc = init(entries)), after the store applies it |
| Registering mid-stream | Seeded synchronously from the held store, so arriving late is indistinguishable from a reconnect |
What init is handed | The client store’s own values, in its arrival order: the same objects byKey reads |
undefined | Means exactly one thing: there is no valid accumulator |
| Removes of unknown keys | Delivered verbatim, so step must be total over a remove of a key it never saw |
| Ordering | Assert keys, apply to the store, notify the folds, clear pending, all in one tick |
| Aliasing | step receives the wire’s decoded frame objects and init receives the store’s held ones; a fold may retain either without cloning |
| Errors | The batched stream’s error is collection-wide and terminal; a throwing init / step is contained to its own fold |
| Teardown | fold() must be called under a reactive owner; the registration is dropped by that owner’s onCleanup |
- First-connect and reconnect are the same event to a fold; it never classifies a frame. Registered while
pending(), the accessor readsundefineduntil the real snapshot lands. initis never handed the wire’s entries directly. The store’s snapshot write is value-diffed, so an entry a reconnect re-serialized unchanged keeps the object already held and the fresh copy is dropped. Seeding from the wire would hand a fold objects the store refused, and make whatinitreceives depend on when the fold registered.undefinedis the state before the first snapshot, and the state a throwinginit/stepreturns the fold to until the next snapshot re-seeds it.- The server’s tick coalescer resolves an upsert-then-remove within one producer tick to a bare remove. The framework does not filter such a remove out, since that would be swallowing part of the frame.
- A
stepthat readsbyKeysees state consistent with the frame it holds.
What a fold may hold, and what fails it
- The store adopts a value by replacement and neither side ever mutates one. A fold that keeps what
initgave it holds the very objectsbyKeyserves, not a second copy of them. - On a collection-wide error, fold accessors keep their last value, frozen, exactly as
byKeydoes, and the failure surfaces through the sharederror()/onError/ health enrolment. - A throwing
init/stepis reported loudly, never killing the stream, the store or another fold, and it invalidates that fold’s accumulator. Later deltas have no valid base to land on, so the accessor returns toundefinedrather than reading live while frozen forever. - Called ownerless,
fold()throws rather than minting an accumulator nothing can drop.
Frames are bounded
A snapshot (or a coalesced delta) that scales with the set is split into
RPC_STREAM_CHUNK_BYTES parts on the wire, and reassembled at the client face
before the store, any fold, mirrorRemoteSurface or a SurfaceMap fold sees
it. So init and step receive exactly the whole frames described above, and
the frame format is unchanged for a small collection.
- The
CollectionDeltasMsgarms carry an optional internalpartmarker purely so the reassembler can join them. A consumer never meets one. - The drain arithmetic behind the 256 KiB figure is under the wire’s frame cap.
Where fold is spellable
fold is typed only on the whole-collection .use() of a collection whose
verbs declare deltas, the same verb gate unenrolledDeltas rides.
- A collection without the verb has no frames.
- Neither does a narrowed
.use({ keys }), which is served by the per-keykeys+getpath even on adeltascollection. - In both,
foldis a type error rather than anundefinedat runtime.
useCollectionDeltas
The hook .use() drives for a deltas collection, exported from
@kolu/surface/solid for the deliberately un-enrolled reach.
- A consumer that takes
.unenrolledDeltas(the #1591 health carve-out) hands the raw stream to it assourceand gets the same store and the samefold, instead of hand-rolling a second one. - Its result carries one member the bound
.use()does not:.stream, the single batched stream’s ownerror()/pending()/complete(). - That reach has no
client.health()fact to join its feed to, so a dead feed surfaces there or nowhere. Under the enrolled.use()the health fact owns that, and a parallel accessor would be one more thing to remember to read.
The dispatch seam — @kolu/surface/link
The face and the links meet at one transport-neutral value. A link factory
produces a SurfaceDispatch; the face consumes one, and nothing else crosses.
| Export | What it is |
|---|---|
SurfaceDispatch | The erased { unary, stream } seam both stages compile against. |
WireStatus | What a transport is doing: connecting, open, closed or retired. |
WatchableWire | What the half-open watchdog needs from a transport. |
WireTransport | A dispatch and its wire, minted together. |
brandHalfOpenDispatch · isHalfOpenDispatch | The wire brand and its guard. |
brandDirectDispatch · isDirectDispatch | The in-process brand and its guard. |
SurfaceDispatch
The erased seam both stages compile against: a link mints one, a face runs on one.
interface SurfaceDispatch {
unary(tag: string, payload: unknown): Effect.Effect<unknown, unknown>;
stream(tag: string, payload: unknown): Stream.Stream<unknown, unknown>;
}
Two rules ride on it.
- Payloads are the decoded side. The face decodes at its edge, so a wire
dispatcher hands the value to Effect RPC (which encodes it) and
directDispatchhands it straight to a handler, with no encode/decode pair to skip. streammust not emit or end synchronously with the subscribe. A stream that reaches its typed end inside the subscribe evicts the keyed subscription cache’s slot while the slot is still being built, so N consumers of one member each open their own upstream subscription. Every wire dispatch satisfies this for free;directDispatchsatisfies it deliberately, with a yield before it touches a handler.
WireStatus
What a transport is doing, published from the protocol’s connect and disconnect.
| Value | Meaning |
|---|---|
connecting | The protocol is dialling. |
open | The protocol can send, not merely that the socket fired open. |
closed | The transport is down and may re-dial. |
retired | Terminal: the server closed a stale tab’s socket with 4001. |
WatchableWire
What the half-open watchdog needs from a transport:
{ status, onStatus, forceReconnect }.
WireTransport
A { dispatch, wire } pair, minted together, so a watchdog provably probes the
transport it reconnects.
brandHalfOpenDispatch · isHalfOpenDispatch
The wire brand and its guard.
brandDirectDispatch · isDirectDispatch
The in-process brand and its guard. A direct dispatch reports constant true
liveness, because there is no wire to lose.
Links
A link maps a way of reaching the served group to a dispatch. Pick one per transport; see How to choose a link.
| Link | Import | What it is |
|---|---|---|
websocketLink({ group, url, … }) | @kolu/surface/links/websocket | Reaches a server over a WebSocket (the browser path). |
websocketLink().diagnostics | @kolu/surface/links/websocket | The link’s own dial history and open count. |
stdioLink({ group, read, write, readiness }) | @kolu/surface/links/stdio | Reaches a subprocess or ssh stdio pair; takes a readiness proof. |
socketDuplexLink({ group, socket, describe }) | @kolu/surface/links/stdio | Reaches an already-connected local unix socket you dialled yourself. |
unixSocketLink({ group, socketPath }) | @kolu/surface/links/unix-socket | Reaches a daemon on the same machine; it dials. |
directDispatch(served) | @kolu/surface/links/direct | Calls the in-process handlers, with no wire. |
followingWire(first) | @kolu/surface/links/following | One standing wire over a succession of wire links. |
| Stream delivery on a wire link | — | How a stalled consumer affects the rest of the link. |
| The keep-alive numbers | @kolu/surface/keepAlive | The ping interval and silence timeout every wire link runs. |
| Failure and re-subscription across re-dials | — | What a socket loss does to calls and standing streams. |
createLoopbackPair() | @kolu/surface/loopback | Two cross-piped ends for an end-to-end test without a subprocess. |
| The stdio readiness gate | @kolu/surface/links/readiness | The banner a stdio peer writes, and the proof stdioLink needs. |
serveOverUnixSocket | @kolu/surface/unix-socket | Serves a group on a unix socket path. |
isPrivateOwnedDir(dir) | @kolu/surface/unix-socket | The privacy predicate used on a socket’s parent directory. |
Every wire link
Every wire link takes the served surface’s group and is async, because
building a protocol and its fibers is an effect. It returns a WireLink:
{ dispatch, dispose }.
dispose()releases the link’s scope (dial, ping and response fibers) and is idempotent.websocketLinkadditionally returns thewirehalf, so it satisfiesWireTransportand can be handed whole tocreateLiveSignal.- Every wire link runs the keep-alive described below. No link factory takes a timing parameter.
websocketLink
Reaches a server over a WebSocket. This is the browser path.
urlis a thunk, re-evaluated on every dial and re-dial.- The thunk is allowed to throw. A thunk that cannot answer yet (kolu’s reads
the server’s process id out of live state) fails that dial as an ordinary
SocketOpenError, so the reconnect schedule backs off and asks again. - A throwing thunk does not kill the link. A link that stopped dialling would
sit
connectingforever with nothing logged.
websocketLink().diagnostics
What a client-side diagnostic needs to prove a wire incident without the server’s log.
| Member | Answers |
|---|---|
dialHistory() | The last 20 dial attempts, oldest first: startedAt, openedAt?, endedAt?, closeCode? and a classification. |
epoch() | How many times this wire has reached open. |
classification | What it means |
|---|---|
"in-flight" | Dialling or connected. |
"opened-then-closed" | The socket opened and then closed. |
"terminal" | The close classifier retired the wire. |
"ended-without-open" | A dial that failed before its socket opened. |
- An
"ended-without-open"attempt is swallowed, publishes no status of its own and never reaches the server, so the dial history is the only record of it. - Timestamps are
Date.now(), so they sit beside a server log. - Diagnostics ride on the returned link object rather than on
WatchableWire. Consumers and tests implementWatchableWireby hand, and widening it would break every such implementation for a fact only a real link can produce.
The shapes are exported from @kolu/surface/links/websocket: WebsocketLink
(the returned link, a WireLink and a WireTransport, plus diagnostics),
WireDiagnostics ({ dialHistory, epoch }), DialAttempt (one record) and
DialClassification (the four verdicts above).
stdioLink
Reaches a subprocess or an ssh stdio pair.
readiness: StdioReadinessProofis required. See the readiness gate.
socketDuplexLink
Reaches a unix socket you have already dialled. You own the dial and its
close.
- It deliberately takes no readiness proof. It is a documented residual for a local unix rendezvous, where epoch safety is owed by the supervisor’s converge-before-dial discipline rather than by a banner over a pipe that never leaves the box.
- Its
Socketparameter is what keeps the ssh or subprocess leg from being spelled through it.
unixSocketLink
Reaches a daemon on the same machine. The link dials the socketPath itself.
directDispatch
Calls the in-process handlers, with no wire. It is the identity element of this family.
- It takes the served surface itself: anything carrying
handlers, so aSurfaceRuntime, aServedSurfaceor aserveSurfaceMapresult. - A tag it cannot resolve throws loudly rather than resolving
undefined. An in-process dispatch can only 404 if the face and the runtime were built from different surfaces.
Stream delivery on a wire link
Every wire link (websocketLink, stdioLink, socketDuplexLink,
unixSocketLink) delivers stream responses off its socket reader.
- A consumer that stops pulling holds up only its own stream. Other streams, unary calls and the keep-alive keep flowing.
- The stalled stream’s sender waits on its withheld
Ack, and the consumer resumes where it left off with nothing dropped. - A subscription that ends (completes, fails, or is interrupted) releases its buffer.
- Delivery is bounded only by the
Ack, so a client protocol without acks is refused when the link is built. - Why Effect RPC needs this, and when it can go:
packages/surface/src/links/deliveryLanes.ts.
The keep-alive numbers — @kolu/surface/keepAlive
Every wire link runs Effect RPC’s pinger with the framework’s own numbers, exported from this subpath.
| Constant | Value | Meaning |
|---|---|---|
RPC_PING_INTERVAL_MS | 5 s | How often a ping goes out. |
RPC_PING_TIMEOUT_MS | 60 s | The link ends once this much time passes with no frame of any kind decoded from the peer. |
RPC_PING_FATAL_SILENCE_MS | 65 s | The worst case, so a silent link dies 60 to 65 s in. |
- No link factory takes a timing parameter.
- The numbers sit above the liveness checks that know more: the framework watchdog (25 s at its defaults) and ssh’s own dead-peer policy (30 s by default).
- Every watchdog is suspension-aware. The rest depends on the leg.
- In a browser,
createLiveSignalis also wake-aware and progress-aware: a probe that times out while frames are still arriving is not a verdict. makeSession’s heartbeat, on an ssh or same-box arm, does not count progress. On a same-box arm it consults a process oracle before it cycles anything.- A peer that really exits is reported at once by the OS (EOF) on a stdio or unix-socket leg.
- So the pinger only ever ends a link that is alive but saying nothing for a minute, after everything above has had its say.
- On a duplex leg that death is
SurfaceStdioTransportClosedwithdeath: "keepAliveUnanswered", named by Effect’sonPingTimeouthook. On the websocket leg it is the same retryableRpcClientErroras any other socket loss.
Failure and re-subscription across re-dials
Effect broadcasts failures from established sockets, including the keep-alive
backstop’s (SocketReadError with a ping timeout cause) and a socket the link
cycles after an undecodable frame.
- Registered calls fail before the next socket opens.
- The retry fence re-subscribes streams once on the new wire; an unfenced unary receives the error.
- No additional epoch fence wraps the WebSocket dispatch.
- Pre-open
SocketOpenErrorfailures are swallowed byretryTransientErrors: true. - Calls waiting for their first connection remain pending across those attempts and send when a socket opens.
- The diagnostic epoch counts open edges; dial history also records attempts that never opened.
followingWire
followingWire({ transport, dispose }) is one standing wire over a succession
of real links. Its dispatch and wire are stable values over a current
generation, which adopt replaces. Everything built over the stable halves
survives a generation change.
Every other link owns a transport for its whole life: dispose it and the
dispatch it minted is a corpse. That holds when the thing underneath is a
socket the link itself re-dials, which websocketLink already hides.
It does not hold when the thing underneath has to be replaced, because the
served member set changed. The RpcGroup a client resolves its schemas through
is fixed when a link is opened, so a wire whose siblings move needs a new link
at both ends.
| Member | Answers |
|---|---|
dispatch / wire | The standing halves: the same values for the wire’s whole life, branded half-open exactly as a generation’s are, so createLiveSignal accepts the pair. |
current() | The generation’s own link, for a fact that belongs to a generation rather than to the wire (a dial history). Read it where you need it; never hold it. |
establishments() / onEstablished(h) | How many usable connections this wire has established, and a subscription to that count. |
adopt(next) | Take next as the generation every call from now on rides, fail what was in flight over the old one, and release it. |
dispose() | Release the generation currently held. |
Why: Why a roster move does not rebuild your page.
adopt and dispose
adoptis notasync. The swap is synchronous and so is every refusal it makes, so the statement a caller writes after it runs only if the wire really moved.- What
adoptreturns is the superseded generation’s release, the one asynchronous half. It never rejects: a failed teardown is logged. dispose()is idempotent. A later call gets the same promise, and therefore the same verdict, rather than resolving early over a teardown still running.- After
dispose(), a lateradoptis refused rather than opening a generation nobody will close. - A generation’s own drop is not a generation change and is forwarded unchanged.
forceReconnectreaches the current generation, and its status changes reach the standing funnel, so a reader and a watcher never disagree about what this wire is doing. - Adopting a generation in the same state publishes nothing at all.
A call in flight when adopt runs
A call is bound to one link: Effect RPC registers an entry exactly once, and an
answer can only travel the link its request went out on. A call in flight when
the generation moved could only park forever, so it is failed with an
RpcClientError.
- That is the same shape, for the same reason, as an established socket failing one layer down.
- It is precisely what the retry fence re-subscribes on, so standing subscriptions re-open themselves onto the new generation.
- A link never re-subscribes internally. That would hide the failure the fence must see.
establishments() and the connection epoch
establishments() counts usable connections: 0 before the first, and monotonic
across every generation. A generation’s own
diagnostics.epoch() is a different number, since
it counts one link’s open edges and starts again at the next generation.
- It counts two edges and only these: a reconnect inside the held generation, and an adopt that lands on a connection.
- An adopt whose replacement is still
connectingcounts when that connection opens. - A replacement that was never adopted (a dial that failed, a refused adopt) never counts, because no new connection was established.
- The status funnel is deduplicated, so adopting a replacement that is already open publishes nothing, while a brand-new socket carries every call. That is the ordinary shape of a roster move, because the replacement is dialled before the old one is given up.
- Use it for anything whose answer was computed from the connection rather than merely over it. A viewer identity resolved from the WebSocket upgrade’s headers is the case that asked for it. Such an answer is stale the moment a different socket carries the calls, while every subscription riding that socket has healed itself and says nothing.
- It is not a rebuild signal. Standing subscriptions re-open themselves.
The consumer is connectSurfaces’ redial.
createLoopbackPair() · greetLoopback · stallLoopback
createLoopbackPair() (@kolu/surface/loopback) is not a link: it produces no
dispatch. It is two cross-piped PassThrough ends you feed into one.
- Hand
pair.clienttostdioLinkandpair.servertoserveOverStdio. - The framing is the same ndjson the real stdio and socket legs carry, so a loopback round-trip is end-to-end evidence without a subprocess.
greetLoopback(pair, describe?)(same module) performs the readiness handshake over that pair. The server half writes the banner, the client half reads it, and you get back the proofstdioLinkneeds.describedefaults to"loopback"and is the name the link puts in its transport errors.stallLoopback(pair)returns{ stall, resume }, which cork and uncork both directions. Nothing is destroyed and no FIN is sent, so it injects only “the peer said nothing for a while”: the shape a starved but living peer has from the far end.
The stdio readiness gate — @kolu/surface/links/readiness
stdioLink takes a required readiness: StdioReadinessProof, and the only way
to obtain one is to read a peer’s ready banner off the very stream you are
about to attach to.
| Export | What it does |
|---|---|
writeStdioReadiness(write, verdict) | Write the one banner line, the first thing a stdio server puts on the wire. |
awaitStdioReadiness({ read, deadlineMs, describe }) | Read it back and mint the proof; rejects StdioReadinessError otherwise. |
isStdioReadinessProof(v) / isStdioReadinessError(v) | Narrow a proof (un-forgeable WeakSet brand) or a failure. |
StdioReadinessVerdict | { verdict: "ready" } or { verdict: "refused", detail, anomaly }. |
STDIO_READINESS_KEY / STDIO_READINESS_VERSION | The reserved banner key and its version. |
- The wire form is exactly one newline-terminated JSON line, before any RPC
frame:
{"surfaceStdioGate":{"v":1,"verdict":"ready"}}. anomalyon a refusal is opaque to the framework. The app that writes it owns its shape, and the app that reads it decodes it with its own schema.awaitStdioReadinessconsumes exactly up to and including the first\nand unshifts every remaining byte back onto the stream, in paused mode, so a banner and a first frame arriving in one chunk cannot lose the frame.- Its failures are classified, never swallowed:
refused(the peer said no, and why),undecodable(the first line was not a banner, with a bounded excerpt),silent(the deadline passed) andclosed. - The gate exists because building an RPC protocol starts the link’s pinger. A peer from a previous protocol epoch accepts the pipe and then says nothing, so the pinger ends the link at its keep-alive backstop, and a consumer that reconnects on that retries a peer that will never speak.
- Why: Why a dial waits for the peer to greet.
Which death it was
Both tags isDeadTransportError unions carry a death field, under the same
name so the union is uniformly branchable.
| Tag | death values |
|---|---|
SurfaceStdioTransportClosed | A StdioTransportDeath: "keepAliveUnanswered", "undecodableFrame", "streamEnded" or "disposed". |
SurfaceTransportRetired | A RetiredTransportDeath: "retiredByServer" or "disposed". |
- A consumer that puts words on a screen branches on the field rather than
reading
reason. - A duplex leg reports an unanswered keep-alive as itself and explicitly declines to claim the peer exited.
- The distinction is diagnostic, not behavioural: the link is dead either way,
and
neverReconnectstill halts on the first failure. - Each field is an optional key, so a payload from a peer that does not classify still decodes. Absent means the producer did not classify, never a defaulted guess.
Who writes the banner
serveOverStdiowrites thereadybanner itself when the process is the agent (notransportoverride).- Over an explicit transport the caller plays the server and greets with
writeStdioReadiness. That is also what a daemon front does, after it has converged the daemon it is about to relay to.
serveOverUnixSocket
Serves a group on a unix socket path. The matching serve-side entry points all
take the same { group, handlers } pair: serveOverStdio
(@kolu/surface/peer-server), serveOverUnixSocket (@kolu/surface/unix-socket)
and serveSurfaceSocket (@kolu/surface-app/server) for browsers.
serveOverUnixSocket takes two arguments the others do not: log, and the
optional per-face expose.
serveOverUnixSocket({ socketPath, group, handlers, log, expose? })
: Promise<UnixSocketListener>
log is a @kolu/log Logger and is required, because the alternative default
is silence. It is where the listener’s own lifetime is narrated, one structured
line each with the socketPath in the context object.
| Event | Level | Message |
|---|---|---|
| the path is bound and accepting | info | unix-socket listener bound |
| a post-listen fault on the server (nobody dialling, no handler in flight) | error | unix-socket listener error (post-listen), carrying the whole err |
| an established peer’s socket errors | debug | unix-socket peer error |
close() runs (first call only) | info | unix-socket listener closed |
Bind-time verdicts are not logged here. They are UnixSocketListener.outcome
values, and the app-flavored advice for each (“pass --pty-host-socket”)
belongs to the caller.
isPrivateOwnedDir(dir): boolean
The three-check privacy predicate serveOverUnixSocket uses on the socket’s
parent directory: lstat (never stat), a directory, and current-uid owned
with no group or other bits.
- It is public so a consumer that did not create the directory can make the same judgement. olai’s vault lock is the first.
- A failed
lstatthrows (ENOENT, EACCES) rather than collapsing to “not private”. - It returns
trueon platforms without uid semantics.
Server-side subpaths
Two subpaths sit under a serve path: @kolu/surface/expose gates which members
a face serves, and @kolu/surface/server builds the RpcServer half every
serve site is made of.
| Export | Subpath | What it is |
|---|---|---|
ExposeMap<S> · ToolExposure | /expose | The map shape a face’s allowlist is written in. |
exposureMutates(exposure) | /expose | Does this exposure declare a mutating procedure? |
classifyExpose(spec, map, face?) | /expose | The key grammar: what each key of a map names. |
exposeFace(surface, map) | /expose | Map plus standalone surface to a FaceExposure. |
exposeFaces(surfaces, maps) | /expose | The sibling-bundle twin: one map per sibling. |
exposeRootedFaces(core, coreMap, siblings, siblingMaps) | /expose | The rooted-bundle twin: root and siblings gated as one face. |
restrictHandlers(group, handlers, exposure?) | /expose | Applies an exposure to a handler record. |
ServedGeneration · ServedGenerationSource · restrictServedGeneration(source) | /expose | The triple a listener serves, and how it obtains it. |
SurfaceMemberNotExposed · ExposeMapError | /expose | The per-request refusal, and every boot-time refusal. |
surfaceRpcServerLayer(group, handlers) | /server | The RpcServer layer, with the defect policy a surface needs. |
serveOverStdio lifetime | . | What happens after a stdio serve resolves. |
Per-face expose (@kolu/surface/expose)
One surface is usually served by several faces at once, and they do not carry
the same trust. A local CLI on a 0700 socket is not an anonymous tab someone
left open. A face therefore takes its own default-deny allowlist, in the
same ExposeMap shape @kolu/surface-mcp takes.
Three steps, and the middle one binds the map to its surface:
import { exposeFace } from "@kolu/surface/expose";
// Bind the map to the surface it describes — where the surface is in scope, so
// `S` is inferred and a typo'd key is a TYPE error, not a boot crash.
// `notes` is a collection, `admin` a procedure NAMESPACE — a dotted key always
// names a procedure, never a primitive's write verb (which has no spelling).
const browser = exposeFace(surface, { notes: "resource" });
const cli = exposeFace(surface, { notes: "resource", "admin.wipe": "tool" });
// Hand each face its own.
serveSurfaceApp({ group, handlers, host, port, allowedOrigins, clientDist, expose: browser });
serveOverUnixSocket({ socketPath, group, handlers, log, expose: cli });
Membership is the allowlist. Omit expose and the face serves the whole
surface; pass one and every member it does not name is refused on that face,
while another face may still serve it.
What a key grants
| Key | Grants |
|---|---|
"<ns>.<verb>" → a ToolExposure ("tool" / { tool: { mutates } }) | That one procedure, split at whichever dot the spec’s own procedures resolve at, uniquely. |
"<member>" → "resource" | The read verbs that primitive declares, never its writes. |
- A member name may itself contain a
.(only/is refused), so a key two procedures both answer to is refused as ambiguous rather than granted to the first. - A malformed
ToolExposureis refused here too, so the erased call path gets the sameExposeMapErrorthe typed one gets at compile time. - A wire face reads only the membership.
mutatesdescribes how an MCP host should present a call, not whether this face may make it. - “A dot” means the ASCII full stop. A lookalike (
a.b,a․b) reads as a primitive key and refuses as one. - The read verbs are
get/keys/deltas(@kolu/surface/define’sREAD_VERBS, which lives beside the verb vocabulary it partitions). The writes areset/patch/upsert/delete/test__set: the tab reads the cell, the socket writes it. - A primitive that must be writable on a gated face has no spelling today:
"resource"is the read word and there is no second one. It is a known gap, tracked with the feature itself (#2169). - Every key resolves against the surface’s own members. A spec table is a plain
object literal, so it inherits
Object.prototype:toString,constructor,valueOfand their siblings name nothing and refuse like any other absent key, while a member a surface really namestoStringstays exposable on every face.
The reserved members
The three reserved system/* members are always reachable on a gated face (per
sibling, in a bundle) and are not spellable in a map: a client’s heartbeat rides
system/live, its stale-tab handshake system/identity, and its clock offset
system/clockNow. Gating those off would break the link rather than restrict
the face.
That carve-out belongs to restrictHandlers, which asks isReservedSurfaceTag
(@kolu/surface/define) of each tag as it applies the policy. It therefore
holds for any FaceExposure, including one a consumer assembled itself, and not
only the ones the constructors in this family built.
What a denied member does
A denied member answers; it does not vanish. Every tag stays bound. The denied
ones are replaced with a handler that raises SurfaceMemberNotExposed
(surface: "<tag>" is not exposed on this face) as a per-request defect, in the
shape its Rpc promised (a dying Stream for a streaming member).
- The class is matchable in-process. A client sees only the message text, because a defect crosses the wire unstructured.
- It is a defect and not a typed failure because there is no declared arm to
fail into: a primitive’s
Rpchas no error channel and a procedure’s defaults toSchema.Never. surfaceRpcServerLayerruns withdisableFatalDefects, so one member’s refusal never touches a sibling subscription on the same connection.
ExposeMap<S> · ToolExposure
The map shape, and the one home for it. @kolu/surface-mcp imports it from here
rather than re-exporting or declaring its own.
exposureMutates(exposure)
Does this exposure declare a mutating procedure? It is conservative: anything
that does not explicitly say mutates: false is mutating.
One derivation serves every face, because it is a safety default. A read-only hint can let a host auto-execute a call unconfirmed, and a rule spelled twice can be relaxed in one place and noticed in neither.
classifyExpose(spec, map, face?)
The key grammar: what each key names, with the member spec it resolved carried on the entry.
- Every face reads a map through this one function,
serveSurfaceAsMcpincluded, so the same key means the same thing on every face. faceis the optional brand a non-framework face stamps on the refusal, at the throw.@kolu/surface-mcppasses its adapter name.
exposeFace(surface, map)
Map plus standalone surface gives a FaceExposure: the tag set one wire face
serves, plus the universe of tags the surface it was built from advertises.
Everything is checked before anything is served, and nothing a map can get
wrong is a no-op. It throws an ExposeMapError on:
- a key that names nothing;
- a key two of the spec’s procedures answer to;
- a procedure exposed as
"resource", or a primitive exposed as a tool; - a malformed
ToolExposure(the{ tool: … }wrapper forgotten); - a key that resolves but grants nothing: a write-only primitive, whose
"resource"offers only read verbs the member does not declare.
exposeFaces(surfaces, maps)
The sibling-bundle twin: one map per sibling, keyed the way the bundle is, over the standalone sibling surfaces.
- It is a fold of
exposeFace’s step overcomposeSurfaceContracts, the same compositionimplementSurfacesbinds against, so the scoped tags the gate names and the ones the runtime serves come from one walk. - A sibling with no map is fully denied.
- A map for a sibling that does not exist is an
ExposeMapError. An omitted sibling is a deliberate full denial; a misspelled one is a policy nobody reads.
exposeRootedFaces(core, coreMap, siblings, siblingMaps)
The rooted-bundle twin: an unprefixed root surface beside the sibling map,
gated as one face. exposeRootedFaces exists so the two halves are never
unioned by hand. A set union is sound only while the two groups are disjoint;
when they are not it keeps one copy of the shared tag, restrictHandlers still
matches, and one member answers under the other’s policy.
- The
universehere ismergeDisjointGroupsof the two halves, so disjointness is established by the same counted composition the serve path runs. - The root is refused unless it is standalone, the same rule
connectSurfacesstates about its owncore. A surface’s prefix is read off the value, so a sibling-scoped surface handed in as the root carriessurface/<key>/…tags, which either collide with that sibling or quietly describe a bundle nobody serves. - It shares
exposeFaces’ refusal of a map keyed by a sibling the bundle does not have, naming itself in the error so a reader is not sent to the wrong door. - It gates surfaces only. Tags multiplexed on the wire that are not a surface
(
connectSurfaces’extraGroups) are not part of anyFaceExposure, and are gated, if at all, by whatever serves them.
restrictHandlers(group, handlers, exposure?)
Applies an exposure: the filter the two faces above call for you. It is also where the reserved members are granted, and where the handler record is proved to be exactly the group’s.
- It is total over an absent exposure. No policy returns the handlers unchanged
(the same record, not a copy), so the “omit
expose= ungated” rule has one implementation. - It throws
ExposeMapErrorif the exposure’suniverse(the tags the surface it was built from advertises) is not exactly the set the group being served carries. A different surface and a merely partial one (a bundle exposed with a sibling left out, which would silently deny that sibling’ssystem/liveheartbeat) are both caught, in both directions. - It throws if the exposure grants a tag the surface does not serve, reachable
only on a hand-assembled
FaceExposureand otherwise ignored in silence. - It throws if the handler record is not exactly the group’s, the same proof
implementSurfaceowes when it builds one. - None of these degrade to a quieter face. A gate that matches nothing denies
everything and still binds, which is the one failure mode that looks like
success from outside. On
serveOverUnixSocketthis is the one thing that rejects: every transport verdict comes back as anoutcomea host can survive.
ServedGeneration · ServedGenerationSource · restrictServedGeneration(source)
The triple a listener serves (group, handlers, expose?), and how it
obtains it: { group, handlers } at the call, or { live: () => triple }
re-read at each accept. Both serveSurfaceApp and serveOverUnixSocket take
the source.
SurfaceMemberNotExposed · ExposeMapError
The per-request refusal, and every boot-time refusal this module raises: a map
that names nothing on its surface, and an exposure that does not describe the
group being served. face carries which door the consumer came through.
SurfaceMemberNotExposed is matchable server-side; over the wire it arrives as
an unstructured defect, so a client reads its message text.
A hand-built serve path gates itself
serveSurfaceApp and serveOverUnixSocket take expose directly. Every other
serve path calls restrictHandlers itself and serves the result. The rule lives
in the module header of
@kolu/surface/expose.
A gated face over a live bundle
On an
implementRootedSurfaces
bundle, a mount or a drop changes the served group, so an exposure built for the
previous roster no longer set-equals it and restrictHandlers refuses, loudly.
The alternative is a face that silently denies a whole sibling.
A gated serve over a live bundle therefore builds the exposure and the
restricted record from the current roster, per accepted connection. Both
listener doors do that when passed { live: () => ({ group, handlers, expose }) }
and the thunk rebuilds the exposure from the current roster. A static expose
next to a live pair is the mismatch restrictHandlers refuses.
surfaceRpcServerLayer(group, handlers)
surfaceRpcServerLayer(group, handlers)
: Layer<never, never, RpcServer.Protocol>
The RpcServer half every one of those serve sites is built from
(@kolu/surface/server): the group’s bound handlers plus the one defect policy
a multiplexed surface requires. A caller supplies only the protocol,
serialization and transport layers below it, so the policy cannot differ
between the unix-socket, websocket and stdio legs.
- It serves with
disableFatalDefects: true. Effect RPC’s default answers an unhandled handler defect with a connection-levelDefectmessage, which fails every other in-flight request on that connection and closes the transport. On a surface that multiplexes a dozen members over one socket, one member’s bad minute is a total blackout. - With it on, the defect is delivered as that request’s own exit: the subscriber that asked sees it, loudly, and every sibling subscription keeps flowing.
- Nothing is swallowed. The server still reports the cause through Effect’s logger, and the failing member still fails.
- Reach for it only when hand-building a serve path; the three entry points above already go through it.
serveOverUnixSocket teardown
The listener’s close() runs the whole ordered teardown: it stops accepting,
disconnects every established peer, and removes the socket file.
- Each severed connection then settles its own serve in the event-loop turns
behind the call (in-flight subscriptions finalize and their timers clear)
without
close()waiting on it. A closed host cannot go on serving live peers. - A wedged half-open peer is destroyed without drain negotiation, and its unflushed frames are dropped.
- Closing one listener never touches another listener’s connections.
close()stays synchronous, idempotent, and safe from aprocess.on("exit")handler.
serveOverStdio lifetime
serveOverStdio({ group, handlers }) never rejects: it resolves a discriminated
{ reason: "end" } | { reason: "error", error } when the read stream ends.
The reason classification is arm-independent. Clean teardown reads as "end"
from both directions: a clean EOF (the peer closed its end) and a benign write
death (EPIPE/ERR_STREAM_DESTROYED, the peer’s read side vanishing
mid-push). "error" is reserved for a genuinely abnormal death (a read error, a
frame-size limit violation, a non-benign write failure).
What happens after the resolve follows from how the transport was chosen:
- No
transportoverride (the defaultprocess.stdin/stdout, the subprocess-agent case): the process is the agent, and the framework owns its lifetime. After the returned promise settles, every synchronous post-settle continuation (anawait-site’sdispose()and log) still runs, and then the framework exits the process:0for"end",1for"error". There is no opt-out, so a live handle (a poll interval, a watcher) cannot keep an agent alive after its link died. - Explicit
transport(loopback pairs in tests, a socket, any embedded peer): the promise resolves the value and the caller owns the process lifetime.
Client-side subpaths
These subpaths are the client half of the framework: the face a caller holds, the fence under every subscription, the error vocabulary all three tiers share, and the readers, waits and budgets a consumer builds on.
| Entry | Subpath | What it is |
|---|---|---|
| The face and its retry fence | @kolu/surface/client | The nested member face over a dispatch, and the per-subscription retry fence. |
| Per-subscription liveness | @kolu/surface/subscriptions | What every fenced subscription has received, for a diagnostic to read. |
| The tagged-error vocabulary | @kolu/surface/errors | The errors that survive a wire hop, their type guards, and messageOf. |
| One-shot snapshot reads | @kolu/surface/first-frame | Take a member’s opening frame, then stop. |
| Running a stream outside Effect | @kolu/surface/run-stream | Run a Stream on its own fiber, behind callbacks. |
| Bounded waits | @kolu/surface/wait | Block until a condition lands on a stream, or time out. |
pollOnChange | @kolu/surface/poll-on-change | Pulse, then requery. |
| The classified failure ledger | @kolu/surface/failure-ledger | A retry budget whose classes count separately. |
| The projection vocabulary | @kolu/surface/verbs | What a projecting face needs that no transport owns. |
The face and its retry fence (@kolu/surface/client)
The addressing layer every higher client stands on, plus the retry fence that sits under each subscription.
| Export | What it is |
|---|---|
buildSurfaceFace(surface, dispatch) | The nested member face over a dispatch: face.surface[member][verb]. |
SurfaceFace · StreamingProcedure<I,O> | The face, and its streaming leaf shape: (encoded input) => Stream<O>. |
UnaryEffect<I,O,E> | The unary leaf: (encoded input) => Effect<O, E | SurfaceCallFailure>, lazy, interruptible, composable. |
SurfaceCallFailure | What a call can fail with that no spec declared. |
isTransportError(err) | Positive test for Effect RPC’s RpcClientError. |
shouldRetryStreamError(err) | The shared fence: which failures a subscription retries. |
STREAM_RETRY · STREAM_RETRY_DELAY_MS | The schedule: spaced 1s, forever, gated on the fence. |
fenceStream(stream, { label?, onRetry? }) | Applies the fence to a raw stream. |
StreamFenceOptions | That options bag: label and onRetry. |
unenrolledStreamCall(procedure, input, { label?, onRetry? }) | Calls a streaming member with the fence applied and no health() enrolment. |
SurfaceClientCallable | The callable-leaved client shape a projecting face holds opaquely. |
OwnedSurfaceConnection<Client> | That client plus the release the face is responsible for. |
SiblingKey | Which surface of a bundle something belongs to: string | undefined. |
disposeQuietly(conn) | Lets go of a connection without leaving an unhandled rejection. |
RootedSurfaceClients | The client half of a rooted bundle: { core?, clients? }. |
clientAt(bundle, sibling) | The client of one leg of a bundle, or undefined. |
declarationTarget(bundle, sibling) | The client a verb receives: the thing that verb is declared on. |
rootedBundleEntries(core, siblings) | Every position of a rooted bundle, in render order. |
notABundleDetail(seam) | The one sentence a face refuses a value that is not a bundle with. |
The face and its leaves
buildSurfaceFacere-nests the flat tags once intoface.surface[member][verb].- It reads
surface.tagPrefixoff the value, so it never learns whether it faces a standalone surface or a composed sibling. - Both leaf shapes are lazy, and neither takes an
AbortSignal. - A unary leaf is a
UnaryEffect<I, O, E>: a lazyEffectthat dispatches nothing until it runs. A caller composes it: catch a declared_tag, race it, bound it, let interruption tear it down. - A streaming leaf is a
StreamingProcedure<I, O>returning a lazyStream. Running it is the subscription, and interrupting the fiber tears the wire subscription down. - The argument is decoded eagerly, at the call site, exactly where a zod
.parseat input throws. Only the dispatch is deferred. SurfaceCallFailureis Effect RPC’sRpcClientErrorplus the framework’s ownSurfaceErrorvocabulary. Defects are deliberately not in it: an undeclared throw stays anEffect.die.isTransportError(err)matches structurally on_tag, so it survives a secondeffectcopy or a relay hop.
The shapes a projecting face holds
SurfaceClientCallableis the callable-leaved loosening ofSurfaceFace: permissive enough that a concreteSurfaceClientOf<S>assigns without a cast, yet callable at the leaf, whichSurfaceFace’sunknownleaves forbid.OwnedSurfaceConnection<Client>is that client plus the release the face is responsible for:dispose, and the transport’s optionalonClose.- It is one shape whether the span is one CLI command or an MCP subscription’s lifetime, so a host writes one connection factory that feeds both faces.
@kolu/surface-mcp’sPusherConnection/OwnedSurfaceConnectionand@kolu/surface-cli’sSurfaceCliConnectionare aliases of it.SiblingKeyisstring | undefined, andundefinedis the bare core, never an omitted value. It lives here so neither projecting face has to import the other’s copy.disposeQuietly(conn)is the one way a face lets go of a connection. It defers the call, swallows a rejection and a synchronous throw, and returns a promise that never rejects.- A bare
conn.dispose()on an async disposer leaves an unhandled rejection, which on Node ends the process at the moment the code is being resilient about a transport going away.
Rooted-bundle lookups
RootedSurfaceClientsis{ core?, clients? }, the shapeconnectSurfaceshands back and the shape both projecting faces dial.clientAt(bundle, sibling)is the one lookup both faces do:undefinednames the core, a key names that sibling, and a missing leg comes backundefined.- Each face then words its own refusal, because an MCP host and a person at a shell are not the same reader.
declarationTarget(bundle, sibling)is a different lookup: a verb receives the client of the thing it is declared on. A verb declared at the bundle root is handed the whole bundle, and one declared on a sibling is handed that sibling’s client.- The root arm can never come back
undefined, because the bundle is the value. A bundle-root verb that wants the core asksclientAtfor it and refuses there. rootedBundleEntries(core, siblings)returns{ sibling, value }for every position of a rooted bundle: the core first, withsibling: undefined, then the siblings in key order.- That order is the order a
tools/list, aresources/listand a--helppage are rendered in. - The walk does not refuse. An empty walk is the shape that is not a bundle, and
notABundleDetail(seam)is that refusal’s one sentence, in the calling face’s own name. - So the predicate and the wording are each written once while each face still
throws its own error class, the same arrangement
notStandaloneRootDetailmakes for the three rooted doors.
The retry fence
- The fence is per subscription and lives here rather than in a link. A link that retried inside itself could not tell one subscriber’s supersession from another’s.
STREAM_RETRYretries forever on a failure the fence accepts, spacedSTREAM_RETRY_DELAY_MS, re-running the whole stream. The next frame a consumer sees is the member’s fresh snapshot.shouldRetryStreamError(err)retries a transport error, plus the one retryable relay end. It never retries a declared error, and never a dead transport.- The fence retries failures, so it only covers what fails. Effect broadcasts established-socket failures, including the keep-alive backstop (above), and those failures trigger this schedule.
- Pre-open retries leave calls pending until the first connection.
unenrolledStreamCall(procedure, input, { label?, onRetry? })applies the fence without enrolling the subscription inhealth().
label and onRetry
onRetryfires once per retryable failure, between the failed attempt’s last frame and the next attempt’s first. It is the place to clear a view the fresh snapshot will replace.labelnames the subscription in the liveness registry below. It is optional and additive: an unlabelled subscription still registers, as"(unlabeled)", so a gap in coverage shows up in a diagnostic rather than hiding a stream from it.- Spell it in the
client.health()vocabulary. A cell or stream is its bare key, a collection’s keys-stream is"<key>.keys", and a per-key value sub is"<key>[<id>]". - That is what the framework’s own enrolment sites pass, so the two records name one subscription one way.
- A raw call site adds whatever scope makes it identifiable. kolu appends the host key or the terminal id, because the same member is legitimately opened once per host and once per pane.
- A throw from
onRetryis contained and logged, never propagated. The hook runs on the fence’s own stack, where unwinding would end the stream immediately after telling you to clear your view. - That would leave a cleared view with no stream left to refill it, and, through
rawStream, ahealth()entry stuckpendingforever. - Containment is what makes “fired means a re-subscribe follows” true even when the hook is broken. Clean up defensively anyway: the log names your hook, not framework code.
Per-subscription liveness (@kolu/surface/subscriptions)
Every fenced subscription funnels through fenceStream, and that is where the
framework records what each one has actually received.
| Export | What it is |
|---|---|
subscriptionLiveness() | Every subscription this runtime holds, plus the last 20 it finished with, in subscribe order. |
resetSubscriptionLiveness() | Drops every record. Tests only. |
SubscriptionLiveness | One record’s shape, which is what a diagnostic reads. |
registerSubscription(label?) | Mints a record and its writer. Framework-internal: fenceStream is its only caller. |
SubscriptionProbe | That writer: frame() · retry(error) · finish(exit). |
UNLABELED_SUBSCRIPTION · ENDED_RETENTION | The "(unlabeled)" fallback label, and how many ended records are kept. |
- That record is the only thing that can tell a parked subscription from a
healthy one. A parked stream is not
pending, since its first frame landed long ago, and nothing failed, soclient.health()reads it as perfectly fine. Only a frame timestamp says otherwise. fenceStreambeing the only caller is what makes registration total: a consumer labels its subscription and never callsregisterSubscriptionitself.- Each record carries
label,subscribedAt,lastFrameAt?,framesReceived,retries,state(live/ended/failed),endedAt?andlastError?. - Timestamps are
Date.now(), like the dial history’s, so the two read side by side and beside a server log. - The registry is module-scoped. Its question spans every client in a runtime: a root surface, a control plane, one keyed-map client per host, and the deliberately un-enrolled raw streams that belong to no client.
- That is a different scope from the per-client health fact.
- It is bounded. Live records are bounded by the subscriptions you hold, ended
ones by
ENDED_RETENTION. - A re-subscribe updates the same record, and
retriesclimbs, rather than minting a second one. - A record is minted when a fenced stream runs, never when its lazy value is built.
- The verdict, whether a subscription is parked, is not stored. It is a
comparison between a record’s
lastFrameAtand the wire’s current open-since (diagnostics.dialHistory()), both of which move on their own. - So a consumer computes the verdict at the moment it reports. kolu’s Diagnostic Info block is the worked example.
The tagged-error vocabulary (@kolu/surface/errors)
Every error that has to be recognized on the far side of a wire hop lives in one
module all three tiers import, as a Schema.TaggedError.
| Class | Meaning | Retryable |
|---|---|---|
SurfaceTransportRetired | The server retired this browser socket (a stale tab, close 4001). Carries death: RetiredTransportDeath, the death field. | Never. |
SurfaceStdioTransportClosed | A stdio or unix-socket leg closed, and the owner re-dials for a new link. Carries death: StdioTransportDeath. | Never. |
SurfaceRelayTransportLost | A re-serve relay’s middle-hop upstream drop, which the parent will heal. | Yes, the one retryable framework error. |
MapKeyNonCanonical · MapKeyUnknown · MapEntryFailed | The keyed-map rejections (see @kolu/surface-map). | Never. |
- The single home is the requirement. A re-serving parent decodes an error from
upstream and re-encodes it downstream, and only a schema both ends were built
from survives serialize, deserialize and re-serialize with its
_tagand data intact. SurfaceErrorSchemais the closed union of all six, which is what a relay decodes against rather than guessing per call.SurfaceErroris its decoded type.- The predicates beside them are type guards, so a call site narrows instead of
re-checking
_tagby hand:isSurfaceError,isDeadTransportError(the two permanently-dead tags),isSurfaceTransportRetired,isSurfaceStdioTransportClosedandisSurfaceRelayTransportLost. - App-declared procedure errors are not in this union. They are declared per
procedure on
ProcedureSpec.errorand travel on that procedure’s own error channel. - A defect is still a defect: an undeclared throw stays an
Effect.dieand is not modelled here.
SurfaceUpstreamRefused
The one framework error that is not in that union, because it is raised as a defect: the upstream answered, and this build will not speak to it (a contract skew, a socket owned by a stranger).
- The member that meets that is a stream minted by
defineSurface, which declares no error channel:Rpc.make({stream: true})resolves an undeclared one toSchema.Never. - A typed failure there is encoded against that
Neverand reaches the subscriber as a complaint about the encoding. - A defect crosses with its
reasonintact and is never retried, which is what a standing refusal wants. Narrow on it in-process withisSurfaceUpstreamRefused. - A map-folded stream is the exception.
@kolu/surface-mapgives those a declared framework channel (foldedError), which is why the transport deaths above cross a map hop by_tag. - Giving
defineSurface’s own streams the same union is juspay/kolu#2297. A relay with a standing condition to report raises a defect rather than declaring a channel that is not there.
messageOf(error)
What a face falls back to when the value it caught is not one of the declared errors: a defect, a scaffold’s throw, a plain object someone failed with.
- One derivation, so every projecting face words one failure the same way.
- It handles the two shapes
e instanceof Error ? e.message : String(e)gets wrong: a tagged error whosemessageis empty, its identity being in_tag, and a failure declared as a plain object ([object Object]). - A value JSON cannot render is named by its constructor and its keys, carrying the reason it refused.
One-shot snapshot reads (@kolu/surface/first-frame)
Every member verb hands back a lazy Stream, and a one-shot read takes the
opening snapshot frame, then stops.
| Export | Signature | What it is |
|---|---|---|
firstFrameOrUndefined(stream) | (Stream<T>) → Effect<T | undefined> | The snapshot frame, or undefined when the stream ends empty. |
firstFrameOrThrow(stream, onEmptyMessage) | (Stream<T>, string) → Effect<T> | The snapshot frame. Fails on an empty stream. |
firstFrameOfCollectionItem(item, keys, key, onEmptyItem, deadlineMs) | (Stream<T>, Stream<unknown> | null, unknown, string, number) → Effect<CollectionItemFrame<T>> | The bounded one-shot read of a collection item. |
CollectionItemFrame<T> | {present:true, value:T} | {present:false, reason:"absent"|"deadline"} | A typed sum: present with a value, or absent with a reason. |
NoSnapshotFrame | Data.TaggedError("NoSnapshotFrame")<{message}> | The empty-open failure both readers raise. |
isNoSnapshotFrame(error) | (unknown) → error is NoSnapshotFrame | The one predicate to discriminate on. |
ITEM_READ_DEADLINE_MS | 5_000 | The deadline a bounded item read uses by default. |
- These readers take that
Streamdirectly and consume it withStream.runHead, whose interruption of the rest is the unsubscribe. No consumer writes atoAsyncIterablebridge, and none re-derives the held-open-gethazard below. - An empty end from
firstFrameOrUndefinedis a benign “no value yet”. - For
firstFrameOrThrow, a missing snapshot is a dropped link, never a silentundefined. It is a recoverable failure, not a thrown defect, so a caller mayEffect.catchit without swallowing bugs. - The empty open fails as a tagged
NoSnapshotFrame, never a bareError, so it can be told from the stream’s own error channel. isNoSnapshotFrame(error)is the one predicate to discriminate on, so no consumer re-derives it from a message or aninstanceofacross a package boundary.- All three readers are Effects, and there is no
signalto pass, because cancellation already is interruption. - A one-shot read is almost always part of something larger: a concurrent fold
over a host’s terminals, an MCP
resources/readunder the request’s own cancellation, a CLI command that must die on Ctrl-C. - Staying inside the fiber tree that bounds it is what makes “the caller gave up” reach the read, so it never waits out a wedged-but-retrying link.
The bounded item read
A get for a not-yet-member key is held open and yields nothing forever
(#1681). So firstFrameOfCollectionItem races the item’s first frame against
both a live keys-absence watch and a hard deadline, always both, never one.
CollectionItemFrame<T>is a typed sum so “present with anundefinedvalue” and “absent” can never collapse into one nullable hole, and so a caller can log the uncertaindeadlinecase distinctly from a known absence.ITEM_READ_DEADLINE_MSis5_000, the deadline a bounded item read uses when its caller has no reason of its own to pick one. Both projecting faces read it rather than spelling the number each.
Telling an empty open from a failure
Both readers can fail two ways: the stream opened and closed without its snapshot, or the stream’s own error channel failed. Those mean opposite things. The first says the link went away and nothing answered. The second says the far side answered and the answer was no.
A reader that catches the whole failure channel and re-words it collapses the
two. Discriminate with isNoSnapshotFrame and let everything else through:
Effect.catch(firstFrameOrThrow(stream, "…opened and closed with no snapshot"), (error) =>
isNoSnapshotFrame(error) ? Effect.fail(myLinkDropped(error.message)) : Effect.fail(error),
)
Running a stream outside Effect (@kolu/surface/run-stream)
A member verb hands back a lazy Stream, and runStreamScoped is where a
non-Effect consumer runs one, so its frames become signal writes, terminal output
or a redraw.
| Export | Signature | What it is |
|---|---|---|
runStreamScoped(stream, handlers) | (Stream<T>, { onFrame, onEnd, onFailure }) → () => void | Runs the stream on its own fiber, and returns the idempotent, synchronous stopper. |
StreamRunHandlers<T> | { onFrame, onEnd, onFailure } | The three mutually-exclusive outcomes. |
toError(value) | (unknown) → Error | The one failure normalization. |
It is one function, not one Effect.runFork per subscription primitive, and it
owns three rules so nobody re-derives them:
- Teardown is a fiber interrupt, and the returned stopper latches before interrupting. After it runs nothing reports: not a late frame, not the interruption exit, not a failure racing the stop.
- An interruption is never a failure, so an unmount does not register as a
subscription error in
health(). - A failure is normalized once to an
Error. A tagged surface error passes through with its_tagintact, so a caller can narrow on it.
The handlers see frames, then either a typed end or a failure, or silence if the stopper ran first.
It lives at the package root, on its own subpath, because it has nothing to do
with Solid. pollOnChange is deliberately Solid-free and runs its pulse through
this same edge, and so do consumers outside this repo. It is also re-exported
from @kolu/surface/solid, so a Solid consumer may import it from either path.
Bounded waits (@kolu/surface/wait)
The client-side “block until a condition lands on a stream” discipline. Zero
imports: a stream-consumption leaf beside first-frame.
| Export | What it is |
|---|---|
WaitOutcome<Met> | The one outcome union: met · gone · timeout · interrupted · closed. |
runWait(opts, watchers) | Owns the race: the caller’s signal, the timeout, settle, and the fallback. |
WaitCtx<Met> | What watchers receive: settle · signal · elapsedMs() · recordUpstreamError. |
waitOutcomeJson(id, outcome, metJson) | Serializes an outcome to the driver-facing JSON frame. |
MAX_TIMER_MS / isValidTimerMs | The setTimeout 32-bit-ceiling range rule. |
- The
metarm spreads its payload flat, soMetmust not carry its ownkind. runWaitchains the caller’s signal, arms the timeout, settles first-writer-wins, and resolves theinterruptedorclosedfallback.- A watcher chains every subscription it opens to the
signalit is handed. waitOutcomeJsonowns the four terminal arms (timeout,gone,interruptedandclosed) once. The per-facemetshape is the injectedmetJsoncallback.- Every timeout and idle window flows through the
MAX_TIMER_MSandisValidTimerMsrange rule. - A watcher that rejects is a bug, not an outcome. The rejection propagates out
of
runWaitverbatim, andclosedis reserved for the link settling without an outcome. - The condition watchers stay in each consumer, because they bind that consumer’s surface contract. Only the outcome union and the race lifecycle live here.
- kaval-tui’s output-idle wait, padi-tui’s agent-state wait and the kolu MCP
face’s composite
wait_*tools share it.
pollOnChange (@kolu/surface/poll-on-change)
The framework-free client dual of the server’s pollOnEvent: pulse, then
requery.
- It subscribes a value-bearing
{seq}pulse stream overunenrolledStreamCall, so the pulse carriesSTREAM_RETRY. - It re-runs a request/response procedure on every frame: the initial snapshot, each change, and each post-reconnect snapshot.
- A slow read is abort-superseded by the next one.
- Results reach the caller through
onResult/onError/onComplete. - It has zero Solid and zero kolu imports: the loop only.
- The SolidJS ergonomics wrap it in
packages/client’screatePolledQuery: a reconciled store,.pending(), and the #818 selection-stability guard. - A consumer that needs the same pattern reaches for that wrapper, not this engine directly.
The classified failure ledger (@kolu/surface/failure-ledger)
A bounded retry budget whose classes cannot count each other’s failures. Zero
imports: a counting leaf beside wait.
| Export | What it is |
|---|---|
makeFailureLedger(spec) | Builds the ledger from a Record<K, FailureClassSpec>. |
FailureClassSpec | One class’s budget: ceiling and resets?. |
FailureVerdict | What a recording says about the class recorded: exhausted · run · ceiling. |
FailureLedger<K> | record(cause) → FailureVerdict · success() · attempts(). |
makeFailureLedgerthrows at construction on aresetsentry naming a class the spec does not declare.ceilingis anumber, ornullfor unbounded, in which case that class can never produce an exhausted verdict.resets?is the interleaving rule as data: the classes whose run a recording of this class restarts.- A verdict reports the class recorded, and only it. Its
runis that class’s run after the recording, safe to print, beside theceilingit was measured against. exhaustedis computed from that class’s own run and that class’s own ceiling. No cross-class read exists in the verdict path, so a message built fromverdict.runcan only name the run that tripped.success()clears every run and the attempt count.attempts()is the display and pacing tier: the total across all classes since the lastsuccess(), exposed for backoff exponents and “attempt N” log lines, and read by no ceiling.- The increment predicate and the ceiling predicate are one predicate here.
Counting
consecutiveFailures += 1for every cause while gating oncause === "remote" && count >= 5spends one class’s budget on another’s failures (juspay/kolu#2101). - A single-class budget does not need this, since its one increment and one ceiling already share the one predicate. Reach for it when a budget has more than one failure class.
@kolu/surface-remote’s session is the consumer:{ network: { ceiling: null, resets: ["remote"] }, remote: { ceiling: 5 } }.
The projection vocabulary (@kolu/surface/verbs)
What a projecting face needs that belongs to neither transport.
@kolu/surface-mcp projects a surface as MCP and
@kolu/surface-cli projects it as argv, and both
read one contract by one grammar, as
expose does for the allowlist.
| Export | What it is |
|---|---|
SurfaceVerb<I, O> | A hand-authored, call-shaped verb. The record an app hands to every face verbatim. |
SurfaceVerbInputSchema<I> | The bound on a verb’s input: Schema.Codec<I, unknown, never, never>. |
toolName(ns, verb) | The flat name a procedure answers to on a face with no dots to spend: <ns>_<verb>. |
toInputSchema(schema?) | The Effect Schema to JSON-Schema bridge, draft 2020-12. |
inputSchema(schema?) | An AdvertisedInput: that document plus the wrapped bit. |
unwrapArgs · wrapValue | The two halves of the wrapping rule a face performs. |
decodeTextValue(schema, text) | Lands a text token in a declared type. |
admitsNoArgument(schema) | Does this member’s declared input admit no argument at all? |
- A
SurfaceVerb<I, O>carriesinput?(an Effect Schema),handler(args, client, signal)returning anEffect, plusdescription?,title?andmutates?. SurfaceVerbInputSchema<I>is context-free, because an argument that arrived as argv or as JSON has no environment to decode in.toolNamerewrites only the separator, soa.bandcminta.b_cand stay reversible to one pair.decodeTextValue(schema, text)reads a token verbatim first, then as its JSON reading, and answers aResult. Success carries both readings:decodedfor a face that addresses by value,encodedfor one that hands a member’s own ref something to decode.- A token that lands in neither reading fails with the verbatim reading’s own
SchemaError, such as a filter’s sentence. A face quotes it in its refusal: MCP refuses an item address with it. admitsNoArgument(schema)is the question every face asks before offering a member that carries none: MCP before publishing a staticsurface://resource, the CLI before lettingget <member>stand with no[arg].- One predicate, because each face turns a
falseinto its own refusal, and two spellings is how they come to disagree about which members are addressable. mutatesdefaults conservatively: absent means mutating, because a read-only hint can let an MCP host auto-run a verb unconfirmed. Mark a genuinely read-only verbmutates: false.- For a procedure, that default is
exposureMutates(exposure), one derivation both faces read, because a safety default spelled once per face is one that can be relaxed on one face. @kolu/surface-mcpre-exportsSurfaceVerbandSurfaceVerbInputSchemaunder its own names,BespokeToolandToolInputSchema. New code imports them from@kolu/surface/verbs.
The Schema to JSON-Schema bridge
toInputSchema · inputSchema · unwrapArgs · wrapValue have a module of
their own behind this subpath, which re-exports them.
toInputSchema’s document is dereferenced, opened, numeric-normalized, and enforced to a top-level object.- The
wrappedbit ofinputSchemasays whether a non-object input had to travel under one property. It is a union on that bit: the wrapped arm carries that value’s owninnernode, so a face never names the wrapper property, and the unwrapped arm has no such field to test for. - The key a scalar travels under stays private to the module, which is what
unwrapArgsandwrapValueperform for a face. - They are the one piece of this vocabulary with a version seam: the converter’s option defaults shift between effect betas, with a byte fixture standing over them, so the file that holds the volatility says which half moves.
- Nothing about how you import them changes: one concept, one import path.
Names that live on other subpaths
Two things a face reads are deliberately not here, so nothing has to import the projection vocabulary to reach them.
SurfaceClientCallable, the callable-leaved client shape a face holds opaquely, and the connection it owns, are@kolu/surface/client’s, beside thebuildSurfaceFacethat mints one.messageOfis@kolu/surface/errors’s, because what a failure said is failure vocabulary, and it words a stdin read and a run-edge defect that have nothing to do with verbs.- There is no re-export of either: one concept, one import path.
Liveness and health
Every surface answers a reserved liveness member, and a client watchdog calls it. client.health() reports what is true, and the readout folds that into the one verdict a connection indicator may say.
| Export | Subpath | What it is |
|---|---|---|
probeSurfaceLive(client) | @kolu/surface/liveness | The round trip that tells a live link from a half-open one. |
probeSurfaceIdentity(client) | @kolu/surface/liveness | The identity twin of that probe. |
surfaceProcessId() | @kolu/surface/identity | This process’s identity nonce. |
monotonicNow() | @kolu/surface/time | The shared monotonic clock. |
createLiveSignal(transport, opts) | @kolu/surface/solid | The watchdog-backed live signal for a wire. |
client.health() | . | What is true of the transport and every enrolled subscription. |
probeSurfaceLive(client) / probeSurfaceIdentity(client)
probeSurfaceLive(client) calls the reserved system/live member: a surface-agnostic round trip a client watchdog uses to tell a live link from a silently half-open one.
- It walks
.surface.system.livestructurally. No app nominates its own probe. - The socket and ssh seams default their watchdog to it.
probeSurfaceIdentity(client)is thesystem/identitytwin. It returns theidentified | anonymousunion thatimplementSurface’sidentityoption declares.- Both arms carry
startedAt(the uptime axis) andprocessId(the restart axis).
surfaceProcessId()
The processId the reserved identity member answers with: a nonce minted once per process, on first read.
- A surface app’s client echoes it back as
?pid=on every reconnect, andgateStaleSocketcompares a reconnecting claim against it. - There is no way to inject one. A process has one identity, read from one place, so a stale-tab handshake cannot compare two unrelated strings.
- Anything that stamps a log line with a process identity reads it from here.
- It is distinct from
startedAt, because two processes can start in the same millisecond, and a timestamp read as an identity is a near-miss waiting to happen.
monotonicNow()
The shared monotonic-clock primitive: performance.now() where present, else Date.now().
- The heartbeat’s suspension check and a consumer’s own dead-man ceiling clock both read it.
- It lives in its own neutral module rather than in
@kolu/surface/heartbeat, so neither the heartbeat nor a downstream watchdog reaches into the other for the clock.
createLiveSignal(transport, opts)
The sole minter of the branded LiveSignalHandle: a watchdog-backed live, paired by construction with the dispatch it probes.
Beyond the heartbeat tuning it takes one option, siblingKey?: () => string | undefined: on a composed wire, which sibling’s scoped system/live the probe addresses.
siblingKeyis a thunk, re-read on every probe. A watchdog outlives the wire underneath it when that wire follows a roster, and which siblings a generation serves is a fact about that generation.- A key resolved once at construction would keep probing a member the current generation no longer carries. The “unknown tag” answer then reads as a dead wire, which is the opposite of the truth.
- Resolve to
undefinedor omit the option: the two spellings mean the same thing, the baresurface/system/live. That is a single-surface wire, or a rooted bundle whose root is on every serve this wire can reach. - A wire whose roster cannot move passes a constant thunk and pays nothing.
client.health()
Returns a fact, not a verdict: { live: boolean, subs: [{ name, pending, error }] }.
liveis the full conjunction of transport-live and every readiness predicate.- A subscription error stays in
subsand is never folded intolive. That is what lets the UI stay honest. Why: Reactive honesty.
The readout
The fact answers what is true. The readout (@kolu/surface/solid) is the one verdict the framework owns: what a connection indicator may say. It folds the transport’s four states together with the fact into five, and connectSurface / connectSurfaces hand it back in place of a transport-only status.
| Export | Type | Meaning |
|---|---|---|
SurfaceReadoutStatus | "connecting" | "live" | "degraded" | "reconnecting" | "retired" | the five states. Type your wording table Record<SurfaceReadoutStatus, …> and a new state is a type error in your file, not a silent default |
SurfaceReadout | TransportReadout | DegradedReadout | { status, presentingDown, needsReload }, plus stopped on the degraded arm |
surfaceReadout(status, health, presentingDown) | → SurfaceReadout | the pure fold. Unit-test your look table against every state without a wire. The graced bit is passed in, because the pure fold owns no clock |
createSurfaceReadout(status, health) | → { readout, dispose } | the memoized accessor over the two reactive facts, in a root of its own. It also derives presentingDown once, so no consumer has to remember the grace policy |
DISCONNECT_OVERLAY_GRACE_MS | number | 1 000. The one grace window presentingDown folds over. Baked, never a knob |
liveis the conjunction. The socket is live, the fact agrees, and nothing enrolled is erroring. A socket that is open and answering under a dead subscription readsdegraded, notlive.degradednames what stopped.stoppedcarries the erroring subscriptions’ own names (documents.keys,terminals[3], and across siblingssurfaceApp/buildInfo), non-empty by type, so an indicator can always say what is missing rather than that “something” is.- Pending does not degrade. A subscription waiting for its first frame is what every page load looks like. This is a universal default, not app policy. It differs from
gateStatus, the gate’s verdict, where a pending first frame legitimately blocks the body. statusitself stays instantaneous. The header dot, the heartbeat probe gate and the client read the raw state with no delay, and only the overlay gate is graced. Do not debouncestatus.needsReloadis true forretiredand nothing else: the one state a reload, and only a reload, recovers. Read it rather than keeping a list of which states are terminal, which can readdownas transient and draw “reconnecting…” over a page that never would.- The app owns the look: which words, which colours, whether the names go in a tooltip or a strip. The framework owns which state is true.
- Why: Green is a claim about the page, not about the socket.
presentingDown and the grace window
presentingDown is the graced down-state, the bit a full-screen overlay gates on.
- It is
falsewhilestatusisliveordegraded. - Once
statushas been continuously not-live forDISCONNECT_OVERLAY_GRACE_MS(1 s), it turnstrue. A recovery flips it back instantly, with no second window. createSurfaceReadoutderives it once, from the same window, forconnectSurface/connectSurfacesand every consumer of a readout, so the policy cannot be forgotten.- A
retiredreadout presents immediately. A retired wire never re-dials, so there is nothing a grace window could hold back. - The frozen
retiredreadout a disposed connection hands back istruefor the same reason, so the two cannot disagree. - Why: Why the overlay waits a second.
Transport loss and frame limits
Two ends a link can meet that are not application errors: the upstream of a re-served surface dying, and a frame too large for the decoder. Both are tagged, and both are recoverable by re-dialling or re-subscribing.
| Export | Subpath | What it is |
|---|---|---|
isSurfaceStdioTransportClosed(reason) | @kolu/surface/errors | Recognizes the raw stdio close of a re-served surface. |
isSurfaceRelayTransportLost(reason) | @kolu/surface/errors | Recognizes the retryable wrapped upstream death. |
| The wire’s frame cap | @kolu/surface/frame-limit | The largest ndjson frame a link will carry, and the close code for one over it. |
| Fitting under the cap | @kolu/surface/frame-chunking | The sender’s arithmetic: chunk sizes, budgets and base64 helpers. |
isSurfaceStdioTransportClosed(reason) / isSurfaceRelayTransportLost(reason)
A re-serve relay ends a live downstream with one of two tagged errors on a transport loss: SurfaceStdioTransportClosed (the raw stdio close), or the retryable SurfaceRelayTransportLost when the relay catches an upstream death mid-stream and re-raises it wrapped.
- A client whose stream rides the fence re-subscribes on
SurfaceRelayTransportLostautomatically, viaSTREAM_RETRY. - A consumer that dials the re-served surface with a raw dispatch (no fence) recognizes them with
isSurfaceStdioTransportClosed(reason)andisSurfaceRelayTransportLost(reason), and retries the subscribe across a reconnect window. - Both tags are deliberately tight. The relay re-raises genuine application errors unchanged, so neither tag is ever an app error.
The wire’s frame cap (@kolu/surface/frame-limit)
Every link’s ndjson serialization is built here, from one owned constant, rather than from Effect’s default. The two values are the same 16 MiB. Passing it explicitly means an Effect bump cannot move kolu’s wire silently.
| Export | Type | Meaning |
|---|---|---|
RPC_MAX_FRAME_BYTES | number | 16 MiB. The largest single ndjson frame the decoder will buffer. |
rpcSerializationLayer | Layer<RpcSerialization> | The ndjson layer carrying that cap. Use instead of RpcSerialization.layerNdjson at every client and server leg. |
exceedsFrameLimit(bytes) | (number) → boolean | Mirrors Effect’s own predicate, boundary included: a frame of exactly RPC_MAX_FRAME_BYTES passes. |
FRAME_TOO_LARGE_CLOSE_CODE | number | 1009. |
isFrameTooLargeClose(code) | (number) → boolean | Classifies the frame-cap close distinctly. |
The close-on-exceed semantics carry a BETA-ASSUMPTION marker stamped with the pinned Effect version (governed by packages/tests/governance/betaAssumptions.ts), so an Effect bump must re-measure them before it can land.
A malformed frame ends the link
A malformed JSON line on an ndjson link ends the link. The decoder has already dropped what was buffered with it, so nothing after that line can be trusted.
- Every call then in flight, and every later call, fails. This holds whether or not a call was in flight.
- On a stdio or unix-socket leg they fail as
SurfaceStdioTransportClosedwithdeath: "undecodableFrame", and the owner re-dials a fresh link. - The websocket leg cycles its socket instead. The failed calls are the retryable
RpcClientErrorthat the face’s fence re-subscribes on the new socket. - The daemon identity probe separately rejects a malformed first frame.
An oversized frame is a closed socket
An oversized frame is not a failed call. Effect’s server-side decode answers a frame over the cap with CloseEvent(1009), which takes every subscription on that multiplexed connection with it.
- The client leg is asymmetric. An oversized frame arriving server to client surfaces as a broadcast
ClientProtocolError, so the socket survives and the retry fence recovers. 1009must stay out of anyisTerminalCloseset. It is recoverable, and halting the retry schedule on it would strand the tab with no subscriptions.
What a member author owns
- No member’s payload may scale with user data. Chunk it into bounded calls (
scratch.write’sappendTocontinuation is the worked example) or cap it with a typed refusal. The cap is a backstop, not a budget. - Refuse client-side, before send. A frame that would bust the limit must be rejected with an honest message rather than handed to the transport to die on.
- The framework bounds the one member whose size is not the author’s to choose. A collection’s
deltassnapshot scales with the number of entries, so it is split intoRPC_STREAM_CHUNK_BYTESparts. Every other member is still the author’s.
@kolu/surface/frame-chunking
The sender’s half of the cap. An app that ever puts bytes on the wire (a drop, a paste, an attachment) has to cut them so no single frame scales with the file. The arithmetic lives here, once: give it an encoded payload and the budget derived from the cap, and get legal frames.
Encoding is the caller’s. chunkBase64 splits a base64 string, and base64CharsFor sizes one before you build it.
| Export | Type | Meaning |
|---|---|---|
FRAME_CHUNK_BYTES | number | 3 MiB. Raw bytes one frame carries. A multiple of 3, so the base64 division is exact. |
FRAME_CHUNK_BASE64_CHARS | number | 4 MiB. FRAME_CHUNK_BYTES after the 4/3 expansion — a multiple of 4 by construction. |
FRAME_ENVELOPE_BYTES | number | 64 KiB. What everything on the frame other than the payload is budgeted at. |
FRAME_PAYLOAD_BUDGET | number | RPC_MAX_FRAME_BYTES − FRAME_ENVELOPE_BYTES. |
chunkBase64(data, chunkChars?) | (string, number?) → readonly [string, ...string[]] | Splits a base64 string on 4-character boundaries. Always at least one piece, so an empty input still performs exactly one write. Throws if chunkChars is not a multiple of 4. |
base64CharsFor(rawBytes) | (number) → number | ceil(R / 3) * 4. |
base64DecodedLength(data) | (string) → number | Decoded size without decoding — for a size gate that must not materialize a buffer. |
frameBytesFor(base64Chars) | (number) → number | What a frame carrying that payload costs, envelope included. Hand it to exceedsFrameLimit for a pre-send refusal. |
RPC_STREAM_CHUNK_BYTES | number | 256 KiB. The budget one outbound stream frame may carry before the framework splits it, a drain bound far under the 16 MiB cap. |
What the derivation turns on
- Two expansions, and only two. base64 is 4/3, and the JSON envelope is a bounded constant. There is no third: base64’s alphabet contains no character JSON escapes, so the payload does not grow again inside the JSON string.
- The chunk is a multiple of 3. That puts every boundary on a 4-character group, which is the unit base64 decodes independently. Split off it and the pieces reassemble as a string while decoding to garbage. A round 4 MiB is not divisible by 3; 3 MiB is, and 3 MiB of bytes is exactly 4 MiB of base64.
- The chunk does not fill the budget. About 3.9x of headroom, so the number survives a bump that adds envelope fields, while a 50 MB file still costs 17 round trips.
- The margin is a test (
frameChunking.test.ts), not a paragraph. It measures the chunk against the imported cap, so a bump that moved the cap fails there.
What stays with the app
This module pays the arithmetic, not the gate. A size policy cap, an extension allowlist, the wording of a refusal and where the bytes land on disk are the consuming app’s. kolu’s own live in @kolu/padi-client/upload.
Why: Where the framework stops.
The framework’s own stream frames (RPC_STREAM_CHUNK_BYTES)
A collection’s batched deltas snapshot re-sends the whole set on every subscribe and every reconnect, so for a long conversation that one frame is megabytes. On a slow link everything else on the socket queues behind it while it drains, including the liveness probe’s answer.
- A snapshot, or a large coalesced delta, is split into
RPC_STREAM_CHUNK_BYTESparts at the server, each a separate ack-gated frame. buildSurfaceFacereassembles them before any consumer sees a frame, souseCollection,fold,mirrorRemoteSurfaceand aSurfaceMapfold are all transparent.- The split and the reassembly both live beside the wire’s frame budget, in the package’s
collectionDeltasFramingmodule.
Why 256 KiB rather than the 16 MiB cap: the cap answers whether the decoder will reject a frame, and the drain budget answers whether the watchdog’s probe answer is still stuck behind a frame when its timeout fires.
A subscription’s frames are ack-gated, so at most one part is in flight. 256 KiB drains in about 2 s at a 1 Mbit/s floor plus a 0.5 s ack round trip, a quarter of the 10 s probe timeout and far inside the link’s 60 s keep-alive backstop.
The bound is per stream. A reconnect re-subscribes every collection at once, so up to K parts can share the socket (K being the collections whose snapshot exceeds the budget), and the probe answer queues behind all K.
- The keep-alive is never at risk, because every decoded part counts as liveness.
- The browser watchdog is not at risk either, because a part landing after its probe launched voids the timeout.
- The ssh-leg watchdog is not progress-aware, so K ≥ 5 large snapshots resuming together at the 1 Mbit/s floor can read as a dead host.
Cross-cutting invariants
Five rules hold across every member, helper and transport on this page.
| Invariant | What it means |
|---|---|
| Snapshot-then-deltas | The first frame of every stream is a fresh full snapshot. |
patch is a cross-runtime contract | A cell’s patch runs on both sides, so changing it is a wire-format change. |
| The group and the handlers are one route set | Advertised tags and answered tags must match at boot. |
| Raw streams join health | A raw stream still reaches health(), through client.rawStream / client.enroll. |
| The 2-file invariant | A member is one spec entry plus one wiring entry. |
Snapshot-then-deltas
The first frame of every stream is a fresh full snapshot, and every server helper enforces it. The retry fence re-runs the source on each reconnect, so a delta-first frame would silently lose state.
patch is a cross-runtime contract
A cell’s patch(current, p) runs on both the server and the client. Treat any change to it as a wire-format change, and redeploy both sides together.
The group and the handlers are one route set
implementSurface (and implementSurfaces, and extendSurface) asserts the two key sets are equal at boot. An advertised-but-unanswered tag and an answered-but-unadvertised one are both crashes rather than a runtime 404.
Raw streams join health
A raw stream joins health through client.rawStream / client.enroll, so it cannot escape health().
unenrolledStreamCall(@kolu/surface/client) applies the retry fence without enrolling, for non-descriptor shapes.- Its captured
inputis replayed verbatim on every re-subscribe, so keep it a stable key. A live fact (a viewport, a cursor) would be re-sent stale after a drop.
.use() is the default; the un-enrolled ref is the carve-out
A stream’s .use() and a collection’s .use() drive the subscription and enrol its pending / error into health(), where the transport gate sees them.
For the narrow class whose transient re-subscribe is normal and self-healing, and so must not flicker that gate (a terminal re-attach, #1591, or a change-pulse that drives a requery), reach the raw ref instead and pass it to unenrolledStreamCall:
| Raw ref | What it is |
|---|---|
.streams.X.unenrolled | A StreamingProcedure. |
.collections.X.unenrolledKeys | The raw keys StreamingProcedure, present iff the collection declares the keys verb. |
.collections.X.unenrolledDeltas | The raw batched CollectionDeltasMsg StreamingProcedure, present iff the collection declares the deltas verb. The deltas twin of unenrolledKeys. |
Each is typed from the declaration, with no cast, and named so the health carve-out is legible at the call site rather than a casual bypass of .use().
The 2-file invariant
Adding a member is one spec entry plus one wiring entry. If the count creeps up, something is wrong.