kolu
Docs

@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.

ExportSubpathWhat 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, because stream "conn/get" and procedure conn.get would otherwise spell the same tag with different (member, verb) pairs.
  • Plain defineSurface is the TPolicy = never case of defineSurfaceWithPolicy: its client slot 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 keySpelling
OptionalSchema.optionalKey, never Schema.optional, which round-trips an explicit undefined through null.
DefaultedSchema.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.

MemberQuestion it answersCardinalityServer sendsClient-mutableCurrent value
cells”What’s the current X?“one singletonsnapshot, then deltasyesyes
collections”current X for each key?“many, keyedper-key snapshot, then deltasyesyes (per key)
streams”live output for input I?“one per inputsnapshot, then deltasnoyes
events”has X happened?“occurrencesoccurrences, no snapshotnono (handler-based)
procedures”do this now”per calla 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 Rpc in 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’s reconcile cannot 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; arrayKey names a field inside one value. A collection declares both.
  • Not per-array. One field per member, because reconcile takes 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.

FieldMeaning
groupthe 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
specthe declaration verbatim; read member types back with SurfaceTypes<typeof surface.spec>
descriptorsthe 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 load mints surface/load/get; a procedure proc.kill mints surface/proc/kill.
  • The surface/ root is what keeps a surface composable with hand-written raw RPC: a host merges surface.group with its own group and no host tag (terminal/create, git/status) can collide with a surface member.
  • The flatness is checked, not assumed. RpcGroup.make is a plain Map.set, so a colliding tag is silently overwritten; defineSurface claims and counts tags instead.
  • group is typed with the erased Rpc.Any element. 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 _tag projection SurfaceTags<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, _tag and 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 and mirrorRemoteSurface’s forwarders included.
  • A procedure call is an Effect, so the declared union rides its error channel and you narrow it there. There is no errors: ErrorMap keyed by a code string.
  • The channel is the declared union plus SurfaceCallFailure, which is Effect RPC’s RpcClientError and 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. Write Effect.orDie if 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 system namespace with any app-owned system procedures. 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 typed ClockNowUnavailableError when 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 (a SurfaceFace or 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) and probeSurfaceIdentity(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 bare RpcGroup.merge: every surface carries the same three reserved system/* members, so merging two bare groups would collide them, silently, merge being last-writer-wins.
  • Each siblings[key] is the same Surface shape as a standalone surface, carrying only its own members at its own tagPrefix. 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.merge is a last-writer-wins Map.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 composeSurfaceContracts itself, 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 (RpcGroup is 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) and connectSurfaces’ 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 of defineSurface that threads the app’s policy union TPolicy through the spec. The two-step call pins TPolicy explicitly while the spec keeps its precise const S inference.
  • ClientCellPolicy<TPolicy> is a cell’s client slot. The onError policy sits flat, intersected with an authority discriminant: { onError?: TPolicy } & ({ authority?: "server" } | { authority: "local"; coalesceMs?: number }).
  • There is no initial. A local-authority cell seeds its store from the mandatory CellSpec.default, so “local-authority without a seed” is a type error, not a runtime surprise.
  • The client runtime sources authority and coalesceMs from this declaration, so a bare .cells.X.use() inherits them (a use-site value still overrides). Declaring authority: "local" on the spec is what makes a use-site bag empty.
  • ClientCollectionPolicy<TPolicy> is a collection’s client slot, onError only: a collection’s keys filter 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.onError but whose client was built with no interpreter makes buildSurfaceClient throw 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().

ExportSubpathWhat it is
implementSurface(surface, deps, opts?)@kolu/surface/serverServes one surface and returns a supervised SurfaceRuntime.
SurfaceRuntimeHandle@kolu/surface/serverThe handle every runtime answers: group, handlers, ctx, done, close.
cells dependencies@kolu/surface/serverstore, patch? and a CellConnector<T> source.
collections dependencies@kolu/surface/serverreadAll, upsert, remove, readOne? and holders?.
streams dependencies@kolu/surface/serverA source(input) stream, or a declarative poll form.
procedures dependencies@kolu/surface/serverVerb handlers that mutate through ctx.
mirrorRemoteSurface@kolu/surface/mirrorThe consume-side twin of the fault audit, with onFault.
Stores and channels@kolu/surface/serverThe in-memory and conf-backed adapters.
implementSurfaceOnPublisher(surface, deps, channel)@kolu/surface/serverServes one surface on a shared, caller-owned publisher.
implementSurfaces(surfaces, base, deps)@kolu/surface/serverServes N surfaces over one transport.
implementSurfacesOnPublisher(surfaces, base, deps)@kolu/surface/serverThe shared-publisher twin of implementSurfaces.
implementRootedSurfaces(core, base, deps)@kolu/surface/serverServes an unprefixed root plus siblings that mount and drop while served.
siblingDroppedDetail(key)@kolu/surface/serverThe one sentence a dropped sibling’s refusal carries.
extendSurface(base, ext)@kolu/surface/serverComposes a parent-local runtime onto a re-served base.
superviseTerminalSource(runtime, terminal)@kolu/surface/serverPairs 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.identity is the server’s declared build triple, which the reserved system/identity member serves as its identified arm. The framework stamps startedAt and processId.
  • Omit opts.identity and the surface is served anonymous, stamped with the same two.
  • implementSurface asserts 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 implementSurface as a boot crash. It is not on done.

SurfaceRuntimeHandle

The handle every runtime in this section answers.

MemberWhat it is
groupThe surface’s own flat RpcGroup, by identity.
handlersEvery bound member handler, keyed by full wire tag.
ctxThe typed cells/collections/events mutation map.
doneA 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.

PathSettles done?Class
Builder wiring throws (one-shot guard, builder body)rejectsruntime-fatal
A push source’s install throwsrejectsruntime-fatal
A poll source’s cadence install(tick) throwsrejectsruntime-fatal
A scope finalizer throws during close()rejects (aggregated)runtime-fatal
Poll T+0 seed read/publish failsnocell-local — logged, cadence held, retried
Poll later tick read/publish failsnocell-local — log-skip-continue
scan step throwsnocell-local — stop-hold
computed recompute throws (later read)nocell-local — holds last, heals
Interruption (close()), clean closeresolvesend-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 sync step on the forking stack, so an acquireRelease whose acquire subscribes is live the instant implementSurface returns.
  • 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.feature pins. 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.

FactBehaviour
Pull orderhold → channel subscribe → readOne snapshot, as contract. Pinned by test.
ReleaseAcquired in the returned stream’s scope, the same scope the channel subscription rides.
MultiplicityEvery get is its own stream, own scope, own hold.
FailureThe error channel is never, so failure is unspellable.
Scopeget only. keys and deltas are collection-wide streams.
AbsentThe exact expression served today, not a wrapped equivalent.
  • A readOne that 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 holders pays 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 AbortSignal to 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) and ctx.events.X.publish(input, payload), so the apply-and-publish chain stays single.
  • A procedure that declares an error schema 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.promise over Effect.tryPromise where 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? }.

  • onFault is a structured MirrorFault ({ label, err, scope: "member" | "key" }) that a serving consumer wires at error level.
  • A member fault also rejects the mirror’s done. That member is never re-subscribed, so the mirror is dead.
  • A key fault is key-local and never reaches done, which makes onFault its only notice.

Stores and channels

AdapterImportPurpose
inMemoryStore<T>(initial)@kolu/surface/serverin-memory cell store
inMemoryCollection<K, V>()@kolu/surface/serverin-memory additive collection deps ({ readAll, upsert, remove })
confStore<T>(conf, key)@kolu/surface/serverconf-backed persistent cell
inMemoryChannel<T>()@kolu/surface/serversingle-process broadcast
inMemoryChannelByName()@kolu/surface/serverthe channel factory form
inMemoryPublisher()@kolu/surface/servera name-keyed { publish, subscribe } publisher
publisherChannel<T>(publisher, name)@kolu/surface/serveradapt 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 internal inMemoryChannelByName(), 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
MemberWhat 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.
rosterThe keys currently mounted, in mount order.
  • group, handlers, ctx, done and close are SurfaceRuntimeHandle’s, so this serves through the ordinary door with nothing in between. ctx is the root’s, and a sibling’s rides its MountedSurface.
  • group and handlers are 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, which assertHandlersMatchGroup then 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.
  • mount is 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.
  • drop is on the value mount handed back rather than a drop(key) verb, so a holder can retract its own sibling and nobody else’s. A stale holder’s drop() 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 SurfaceSiblingDropped defect.
  • 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 reaches done, the runtime’s one owned-fault channel, exactly as a finalizer faulting during close() 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, throws SurfaceSiblingDropped from 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 ctx is the deliberate asymmetry: SurfaceSiblingDropped names 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 redial off 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 redial is 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/roster cell plus a connectSurfaces option 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 live is a property of the rooted door and implementSurfaces stays the fixed bundle it is.
  • There is no *OnPublisher twin 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 stale tools/list.
  • Each caller keeps its own surrounding clause (what the name was, what to do next). Only the sentence is shared, the same arrangement notStandaloneRootDetail makes 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 }. A reServeSurface result satisfies it directly. A local implementSurface runtime does once its surface descriptor is carried alongside.
  • It returns ExtendedSurface<Base, Ext>: the same supervision contract over the merged surface Surface<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 local ext is passive, so only its fault settles done before close.
  • close tears 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 one close) and extendSurface (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.

ExportSubpathWhat it is
source(install, initial?)/reactorAn external push input, installed lazily on the first subscriber.
source({read, install})/reactorAn external poll input read on a caller-owned cadence.
source({ read, install, label })/reactorThe poll source options, including the loop guard’s label.
everyMs(ms)/reactorThe fixed-interval install closure for a poll source.
everyMsOr(ms, subscribe)/reactorThe interval-plus-edge cadence fuse.
assertCellConverges({ build, kick?, settleMs? })/assert-cell-convergesDrives a poll source in a test and asserts it settles.
viewerAddressOf({ peerAddress, forwardedFor, hostAddresses })/viewer-identityWhich machine a viewer is at, behind a reverse proxy.
scan(src, initial, step)/reactorFolds a source’s occurrences into a level.
computed(fn)/reactorA derived value reading other graph nodes.
batch(fn)/reactorGroups several graph writes into one frame.
derived.cell(node)/reactorPublishes a pre-built graph node as a cell.
derived.cell(($) => …)/reactorPublishes a sibling derivation as a cell.
derived.collection(node)/reactorPublishes a keyed node as a collection, through a keyed reconciler.
reactiveFamily(opts)/reactorA keyed family of member states, as a graph source.
derived.registry(family, resolve)/reactorThe 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.
  • initial seeds the level. Without it the level reads undefined until 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, SIGTERM ignored).
  • 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 edge subscribe(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 subscribe fires.
  • 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.
  • forwardedFor takes 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.

  • stopped is a ReadonlyLevel<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 stopped into the surface’s client-side liveness, by folding it into a member’s liveWhen, is a later phase. In phase 0 liveWhen receives 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.

FormSignatureWhat 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 no keyof union 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.cell may read a sibling derived.cell via $ whether declared before or after it. Only a genuine cycle fails.

What a derived cell guarantees

  • Wire-read-only. A derived.cell dep 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 own equals → onWrite → store.set → bus.publish gate (the connect seam), so the wire dedup point is unchanged and an equals-equal recompute never crosses the wire. equals lives 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 connect is a CellConnector whose 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 AbortSignal its Promise-shaped read sees.

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-key upsert / remove publishers 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 / remove throw.

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>.

  • members is a Source<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 subscribe on 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.

ExportSubpathWhat it is
surfaceClient(surface, transport, onClientError?)/solidA client with a bound accessor per member.
surfaceClients(transport, map)/solidSplits one combined transport into a sibling client per surface.
surfaceClientsHealth(clients)/solidAnd-reduces a record of clients into one health fact.
Subscription<T>/solidThe accessor plus pending / error / complete and the change channel.
.streams.X.useCollection(input, descriptor)/solidA keyed, read-only collection view over a stream of snapshots and deltas.
fold/solidFolds a deltas collection’s whole frames into your own accumulator.
useCollectionDeltas/solidThe 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
  • transport is either a watchdog-backed LiveSignalHandle or a bare in-process SurfaceDispatch. See Wire links must carry a watchdog.
  • onClientError is the app’s one interpreter, the same slot surfaceClients takes in the same position.
  • A surface whose spec declares a client.onError policy, built into a client without one, throws at construction: a declared policy may never route nowhere.
MemberHookReturns
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 no authority: "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 authority is "server" (the default: every push reconciles) or "local" (the local store wins after the first server yield).
  • An inputFn that returns null pauses 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 .parse runs), 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 / patch payload, a collection key. The client feeds them to the spec’s own patch and 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 AbortSignal to 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>, typed unknown per 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 reserved system.*.
  • 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 arrayKey is merged by that field instead: a repeated frame notifies nothing, and a reorder moves the objects a keyed view is following.
  • A deltas collection’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 a fold consumer is holding never mutates under it.
  • A collection’s per-key delivery does come through this merge, and honours the same declaration.

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 bare directDispatch, 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:

MemberWhere the subscription is
streamstreams.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
collectionthe handle depends on the delivery path (see below)
  • A mutable cell’s result is { value, pending, error, set, patch, sub }, where value is the accessor and sub is the Subscription. The change channel is therefore cells.X.use(...).sub.updated(...).
  • A read-only cell’s result has no set / patch, and its .use() accepts only onError, since a get-only cell has no wire mutation verb to reconcile against.
  • A collection view answers error(), pending() and keys() whatever the path. Under batched delivery the per-key handle byKey(id) returns is assembled from the one stream’s signals, so it carries no .updated(). Ask fold instead, 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 prev the last-seen value.
  • It returns a Dispose. It is optional for the same reason as complete: a hand-assembled Subscription-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, same Dispose, 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 two structuredClones 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 read prev / 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:

MemberAnswers
clientsthe 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, as bundle = bundle.reroster(next). clients and roster() are typed on the roster, so a binding still typed on the old one keeps claiming departed keys exist.
  • clients is 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 folding Object.values(…), or a hand-written surfaceClientsHealth(bundle.clients) is blind to a roster move: it keeps naming departed siblings and never names an arrival. Reach for bundle.roster() or bundle.health() in any tracking scope.
  • The notification lives on the bundle, beside the mutation, because reroster is the only code that knows the key set moved.
  • moves is there because the expensive half of following a roster lives one layer up: conn.redial asks 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 Surface value keeps its client, standing subscriptions and all.
  • A key that arrives gets a client built now.
  • A key that leaves, or whose Surface value 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.

FactBehaviour
SnapshotRe-initializes every registered fold (acc = init(entries)), after the store applies it
Registering mid-streamSeeded synchronously from the held store, so arriving late is indistinguishable from a reconnect
What init is handedThe client store’s own values, in its arrival order: the same objects byKey reads
undefinedMeans exactly one thing: there is no valid accumulator
Removes of unknown keysDelivered verbatim, so step must be total over a remove of a key it never saw
OrderingAssert keys, apply to the store, notify the folds, clear pending, all in one tick
Aliasingstep receives the wire’s decoded frame objects and init receives the store’s held ones; a fold may retain either without cloning
ErrorsThe batched stream’s error is collection-wide and terminal; a throwing init / step is contained to its own fold
Teardownfold() 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 reads undefined until the real snapshot lands.
  • init is 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 what init receives depend on when the fold registered.
  • undefined is the state before the first snapshot, and the state a throwing init / step returns 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 step that reads byKey sees 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 init gave it holds the very objects byKey serves, not a second copy of them.
  • On a collection-wide error, fold accessors keep their last value, frozen, exactly as byKey does, and the failure surfaces through the shared error() / onError / health enrolment.
  • A throwing init / step is 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 to undefined rather 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 CollectionDeltasMsg arms carry an optional internal part marker 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-key keys+get path even on a deltas collection.
  • In both, fold is a type error rather than an undefined at 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 as source and gets the same store and the same fold, instead of hand-rolling a second one.
  • Its result carries one member the bound .use() does not: .stream, the single batched stream’s own error() / 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 face and the links meet at one transport-neutral value. A link factory produces a SurfaceDispatch; the face consumes one, and nothing else crosses.

ExportWhat it is
SurfaceDispatchThe erased { unary, stream } seam both stages compile against.
WireStatusWhat a transport is doing: connecting, open, closed or retired.
WatchableWireWhat the half-open watchdog needs from a transport.
WireTransportA dispatch and its wire, minted together.
brandHalfOpenDispatch · isHalfOpenDispatchThe wire brand and its guard.
brandDirectDispatch · isDirectDispatchThe 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 directDispatch hands it straight to a handler, with no encode/decode pair to skip.
  • stream must 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; directDispatch satisfies it deliberately, with a yield before it touches a handler.

WireStatus

What a transport is doing, published from the protocol’s connect and disconnect.

ValueMeaning
connectingThe protocol is dialling.
openThe protocol can send, not merely that the socket fired open.
closedThe transport is down and may re-dial.
retiredTerminal: 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.

A link maps a way of reaching the served group to a dispatch. Pick one per transport; see How to choose a link.

LinkImportWhat it is
websocketLink({ group, url, … })@kolu/surface/links/websocketReaches a server over a WebSocket (the browser path).
websocketLink().diagnostics@kolu/surface/links/websocketThe link’s own dial history and open count.
stdioLink({ group, read, write, readiness })@kolu/surface/links/stdioReaches a subprocess or ssh stdio pair; takes a readiness proof.
socketDuplexLink({ group, socket, describe })@kolu/surface/links/stdioReaches an already-connected local unix socket you dialled yourself.
unixSocketLink({ group, socketPath })@kolu/surface/links/unix-socketReaches a daemon on the same machine; it dials.
directDispatch(served)@kolu/surface/links/directCalls the in-process handlers, with no wire.
followingWire(first)@kolu/surface/links/followingOne 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/keepAliveThe 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/loopbackTwo cross-piped ends for an end-to-end test without a subprocess.
The stdio readiness gate@kolu/surface/links/readinessThe banner a stdio peer writes, and the proof stdioLink needs.
serveOverUnixSocket@kolu/surface/unix-socketServes a group on a unix socket path.
isPrivateOwnedDir(dir)@kolu/surface/unix-socketThe privacy predicate used on a socket’s parent directory.

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.
  • websocketLink additionally returns the wire half, so it satisfies WireTransport and can be handed whole to createLiveSignal.
  • Every wire link runs the keep-alive described below. No link factory takes a timing parameter.

Reaches a server over a WebSocket. This is the browser path.

  • url is 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 connecting forever with nothing logged.

websocketLink().diagnostics

What a client-side diagnostic needs to prove a wire incident without the server’s log.

MemberAnswers
dialHistory()The last 20 dial attempts, oldest first: startedAt, openedAt?, endedAt?, closeCode? and a classification.
epoch()How many times this wire has reached open.
classificationWhat 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 implement WatchableWire by 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).

Reaches a subprocess or an ssh stdio pair.

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 Socket parameter is what keeps the ssh or subprocess leg from being spelled through it.

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 a SurfaceRuntime, a ServedSurface or a serveSurfaceMap result.
  • 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.

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.

ConstantValueMeaning
RPC_PING_INTERVAL_MS5 sHow often a ping goes out.
RPC_PING_TIMEOUT_MS60 sThe link ends once this much time passes with no frame of any kind decoded from the peer.
RPC_PING_FATAL_SILENCE_MS65 sThe 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, createLiveSignal is 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 SurfaceStdioTransportClosed with death: "keepAliveUnanswered", named by Effect’s onPingTimeout hook. On the websocket leg it is the same retryable RpcClientError as 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 SocketOpenError failures are swallowed by retryTransientErrors: 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.

MemberAnswers
dispatch / wireThe 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

  • adopt is not async. 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 adopt returns 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 later adopt is refused rather than opening a generation nobody will close.
  • A generation’s own drop is not a generation change and is forwarded unchanged. forceReconnect reaches 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 connecting counts 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.client to stdioLink and pair.server to serveOverStdio.
  • 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 proof stdioLink needs.
  • describe defaults 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.

ExportWhat 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_VERSIONThe 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"}}.
  • anomaly on 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.
  • awaitStdioReadiness consumes exactly up to and including the first \n and 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) and closed.
  • 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.

Tagdeath values
SurfaceStdioTransportClosedA StdioTransportDeath: "keepAliveUnanswered", "undecodableFrame", "streamEnded" or "disposed".
SurfaceTransportRetiredA 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 neverReconnect still 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

  • serveOverStdio writes the ready banner itself when the process is the agent (no transport override).
  • 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.

EventLevelMessage
the path is bound and acceptinginfounix-socket listener bound
a post-listen fault on the server (nobody dialling, no handler in flight)errorunix-socket listener error (post-listen), carrying the whole err
an established peer’s socket errorsdebugunix-socket peer error
close() runs (first call only)infounix-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 lstat throws (ENOENT, EACCES) rather than collapsing to “not private”.
  • It returns true on 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.

ExportSubpathWhat it is
ExposeMap<S> · ToolExposure/exposeThe map shape a face’s allowlist is written in.
exposureMutates(exposure)/exposeDoes this exposure declare a mutating procedure?
classifyExpose(spec, map, face?)/exposeThe key grammar: what each key of a map names.
exposeFace(surface, map)/exposeMap plus standalone surface to a FaceExposure.
exposeFaces(surfaces, maps)/exposeThe sibling-bundle twin: one map per sibling.
exposeRootedFaces(core, coreMap, siblings, siblingMaps)/exposeThe rooted-bundle twin: root and siblings gated as one face.
restrictHandlers(group, handlers, exposure?)/exposeApplies an exposure to a handler record.
ServedGeneration · ServedGenerationSource · restrictServedGeneration(source)/exposeThe triple a listener serves, and how it obtains it.
SurfaceMemberNotExposed · ExposeMapError/exposeThe per-request refusal, and every boot-time refusal.
surfaceRpcServerLayer(group, handlers)/serverThe 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

KeyGrants
"<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 ToolExposure is refused here too, so the erased call path gets the same ExposeMapError the typed one gets at compile time.
  • A wire face reads only the membership. mutates describes 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’s READ_VERBS, which lives beside the verb vocabulary it partitions). The writes are set / 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, valueOf and their siblings name nothing and refuse like any other absent key, while a member a surface really names toString stays 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 Rpc has no error channel and a procedure’s defaults to Schema.Never.
  • surfaceRpcServerLayer runs with disableFatalDefects, 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, serveSurfaceAsMcp included, so the same key means the same thing on every face.
  • face is the optional brand a non-framework face stamps on the refusal, at the throw. @kolu/surface-mcp passes 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 over composeSurfaceContracts, the same composition implementSurfaces binds 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 universe here is mergeDisjointGroups of 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 connectSurfaces states about its own core. A surface’s prefix is read off the value, so a sibling-scoped surface handed in as the root carries surface/<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 any FaceExposure, 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 ExposeMapError if the exposure’s universe (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’s system/live heartbeat) 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 FaceExposure and otherwise ignored in silence.
  • It throws if the handler record is not exactly the group’s, the same proof implementSurface owes 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 serveOverUnixSocket this is the one thing that rejects: every transport verdict comes back as an outcome a 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-level Defect message, 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 a process.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 transport override (the default process.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 (an await-site’s dispose() and log) still runs, and then the framework exits the process: 0 for "end", 1 for "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.

EntrySubpathWhat it is
The face and its retry fence@kolu/surface/clientThe nested member face over a dispatch, and the per-subscription retry fence.
Per-subscription liveness@kolu/surface/subscriptionsWhat every fenced subscription has received, for a diagnostic to read.
The tagged-error vocabulary@kolu/surface/errorsThe errors that survive a wire hop, their type guards, and messageOf.
One-shot snapshot reads@kolu/surface/first-frameTake a member’s opening frame, then stop.
Running a stream outside Effect@kolu/surface/run-streamRun a Stream on its own fiber, behind callbacks.
Bounded waits@kolu/surface/waitBlock until a condition lands on a stream, or time out.
pollOnChange@kolu/surface/poll-on-changePulse, then requery.
The classified failure ledger@kolu/surface/failure-ledgerA retry budget whose classes count separately.
The projection vocabulary@kolu/surface/verbsWhat 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.

ExportWhat 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.
SurfaceCallFailureWhat 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_MSThe schedule: spaced 1s, forever, gated on the fence.
fenceStream(stream, { label?, onRetry? })Applies the fence to a raw stream.
StreamFenceOptionsThat options bag: label and onRetry.
unenrolledStreamCall(procedure, input, { label?, onRetry? })Calls a streaming member with the fence applied and no health() enrolment.
SurfaceClientCallableThe callable-leaved client shape a projecting face holds opaquely.
OwnedSurfaceConnection<Client>That client plus the release the face is responsible for.
SiblingKeyWhich surface of a bundle something belongs to: string | undefined.
disposeQuietly(conn)Lets go of a connection without leaving an unhandled rejection.
RootedSurfaceClientsThe 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

  • buildSurfaceFace re-nests the flat tags once into face.surface[member][verb].
  • It reads surface.tagPrefix off 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 lazy Effect that 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 lazy Stream. 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 .parse at input throws. Only the dispatch is deferred.
  • SurfaceCallFailure is Effect RPC’s RpcClientError plus the framework’s own SurfaceError vocabulary. Defects are deliberately not in it: an undeclared throw stays an Effect.die.
  • isTransportError(err) matches structurally on _tag, so it survives a second effect copy or a relay hop.

The shapes a projecting face holds

  • SurfaceClientCallable is the callable-leaved loosening of SurfaceFace: permissive enough that a concrete SurfaceClientOf<S> assigns without a cast, yet callable at the leaf, which SurfaceFace’s unknown leaves forbid.
  • OwnedSurfaceConnection<Client> is that client plus the release the face is responsible for: dispose, and the transport’s optional onClose.
  • 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’s PusherConnection / OwnedSurfaceConnection and @kolu/surface-cli’s SurfaceCliConnection are aliases of it.
  • SiblingKey is string | undefined, and undefined is 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

  • RootedSurfaceClients is { core?, clients? }, the shape connectSurfaces hands back and the shape both projecting faces dial.
  • clientAt(bundle, sibling) is the one lookup both faces do: undefined names the core, a key names that sibling, and a missing leg comes back undefined.
  • 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 asks clientAt for it and refuses there.
  • rootedBundleEntries(core, siblings) returns { sibling, value } for every position of a rooted bundle: the core first, with sibling: undefined, then the siblings in key order.
  • That order is the order a tools/list, a resources/list and a --help page 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 notStandaloneRootDetail makes 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_RETRY retries forever on a failure the fence accepts, spaced STREAM_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 in health().

label and onRetry

  • onRetry fires 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.
  • label names 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 onRetry is 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, a health() entry stuck pending forever.
  • 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.

ExportWhat it is
subscriptionLiveness()Every subscription this runtime holds, plus the last 20 it finished with, in subscribe order.
resetSubscriptionLiveness()Drops every record. Tests only.
SubscriptionLivenessOne record’s shape, which is what a diagnostic reads.
registerSubscription(label?)Mints a record and its writer. Framework-internal: fenceStream is its only caller.
SubscriptionProbeThat writer: frame() · retry(error) · finish(exit).
UNLABELED_SUBSCRIPTION · ENDED_RETENTIONThe "(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, so client.health() reads it as perfectly fine. Only a frame timestamp says otherwise.
  • fenceStream being the only caller is what makes registration total: a consumer labels its subscription and never calls registerSubscription itself.
  • Each record carries label, subscribedAt, lastFrameAt?, framesReceived, retries, state (live / ended / failed), endedAt? and lastError?.
  • 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 retries climbs, 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 lastFrameAt and 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.

ClassMeaningRetryable
SurfaceTransportRetiredThe server retired this browser socket (a stale tab, close 4001). Carries death: RetiredTransportDeath, the death field.Never.
SurfaceStdioTransportClosedA stdio or unix-socket leg closed, and the owner re-dials for a new link. Carries death: StdioTransportDeath.Never.
SurfaceRelayTransportLostA re-serve relay’s middle-hop upstream drop, which the parent will heal.Yes, the one retryable framework error.
MapKeyNonCanonical · MapKeyUnknown · MapEntryFailedThe 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 _tag and data intact.
  • SurfaceErrorSchema is the closed union of all six, which is what a relay decodes against rather than guessing per call. SurfaceError is its decoded type.
  • The predicates beside them are type guards, so a call site narrows instead of re-checking _tag by hand: isSurfaceError, isDeadTransportError (the two permanently-dead tags), isSurfaceTransportRetired, isSurfaceStdioTransportClosed and isSurfaceRelayTransportLost.
  • App-declared procedure errors are not in this union. They are declared per procedure on ProcedureSpec.error and travel on that procedure’s own error channel.
  • A defect is still a defect: an undeclared throw stays an Effect.die and 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 to Schema.Never.
  • A typed failure there is encoded against that Never and reaches the subscriber as a complaint about the encoding.
  • A defect crosses with its reason intact and is never retried, which is what a standing refusal wants. Narrow on it in-process with isSurfaceUpstreamRefused.
  • A map-folded stream is the exception. @kolu/surface-map gives 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 whose message is 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.

ExportSignatureWhat 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.
NoSnapshotFrameData.TaggedError("NoSnapshotFrame")<{message}>The empty-open failure both readers raise.
isNoSnapshotFrame(error)(unknown) → error is NoSnapshotFrameThe one predicate to discriminate on.
ITEM_READ_DEADLINE_MS5_000The deadline a bounded item read uses by default.
  • These readers take that Stream directly and consume it with Stream.runHead, whose interruption of the rest is the unsubscribe. No consumer writes a toAsyncIterable bridge, and none re-derives the held-open-get hazard below.
  • An empty end from firstFrameOrUndefined is a benign “no value yet”.
  • For firstFrameOrThrow, a missing snapshot is a dropped link, never a silent undefined. It is a recoverable failure, not a thrown defect, so a caller may Effect.catch it without swallowing bugs.
  • The empty open fails as a tagged NoSnapshotFrame, never a bare Error, 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 an instanceof across a package boundary.
  • All three readers are Effects, and there is no signal to 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/read under 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 an undefined value” and “absent” can never collapse into one nullable hole, and so a caller can log the uncertain deadline case distinctly from a known absence.
  • ITEM_READ_DEADLINE_MS is 5_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.

ExportSignatureWhat it is
runStreamScoped(stream, handlers)(Stream<T>, { onFrame, onEnd, onFailure }) → () => voidRuns 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) → ErrorThe 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 _tag intact, 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.

ExportWhat 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 / isValidTimerMsThe setTimeout 32-bit-ceiling range rule.
  • The met arm spreads its payload flat, so Met must not carry its own kind.
  • runWait chains the caller’s signal, arms the timeout, settles first-writer-wins, and resolves the interrupted or closed fallback.
  • A watcher chains every subscription it opens to the signal it is handed.
  • waitOutcomeJson owns the four terminal arms (timeout, gone, interrupted and closed) once. The per-face met shape is the injected metJson callback.
  • Every timeout and idle window flows through the MAX_TIMER_MS and isValidTimerMs range rule.
  • A watcher that rejects is a bug, not an outcome. The rejection propagates out of runWait verbatim, and closed is 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 over unenrolledStreamCall, so the pulse carries STREAM_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’s createPolledQuery: 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.

ExportWhat it is
makeFailureLedger(spec)Builds the ledger from a Record<K, FailureClassSpec>.
FailureClassSpecOne class’s budget: ceiling and resets?.
FailureVerdictWhat a recording says about the class recorded: exhausted · run · ceiling.
FailureLedger<K>record(cause) → FailureVerdict · success() · attempts().
  • makeFailureLedger throws at construction on a resets entry naming a class the spec does not declare.
  • ceiling is a number, or null for 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 run is that class’s run after the recording, safe to print, beside the ceiling it was measured against.
  • exhausted is 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 from verdict.run can 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 last success(), 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 += 1 for every cause while gating on cause === "remote" && count >= 5 spends 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.

ExportWhat 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 · wrapValueThe 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> carries input? (an Effect Schema), handler(args, client, signal) returning an Effect, plus description?, title? and mutates?.
  • SurfaceVerbInputSchema<I> is context-free, because an argument that arrived as argv or as JSON has no environment to decode in.
  • toolName rewrites only the separator, so a.b and c mint a.b_c and stay reversible to one pair.
  • decodeTextValue(schema, text) reads a token verbatim first, then as its JSON reading, and answers a Result. Success carries both readings: decoded for a face that addresses by value, encoded for 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 static surface:// resource, the CLI before letting get <member> stand with no [arg].
  • One predicate, because each face turns a false into its own refusal, and two spellings is how they come to disagree about which members are addressable.
  • mutates defaults conservatively: absent means mutating, because a read-only hint can let an MCP host auto-run a verb unconfirmed. Mark a genuinely read-only verb mutates: 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-mcp re-exports SurfaceVerb and SurfaceVerbInputSchema under its own names, BespokeTool and ToolInputSchema. 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 wrapped bit of inputSchema says 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 own inner node, 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 unwrapArgs and wrapValue perform 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 the buildSurfaceFace that mints one.
  • messageOf is @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.

ExportSubpathWhat it is
probeSurfaceLive(client)@kolu/surface/livenessThe round trip that tells a live link from a half-open one.
probeSurfaceIdentity(client)@kolu/surface/livenessThe identity twin of that probe.
surfaceProcessId()@kolu/surface/identityThis process’s identity nonce.
monotonicNow()@kolu/surface/timeThe shared monotonic clock.
createLiveSignal(transport, opts)@kolu/surface/solidThe 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.live structurally. No app nominates its own probe.
  • The socket and ssh seams default their watchdog to it.
  • probeSurfaceIdentity(client) is the system/identity twin. It returns the identified | anonymous union that implementSurface’s identity option declares.
  • Both arms carry startedAt (the uptime axis) and processId (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, and gateStaleSocket compares 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.

  • siblingKey is 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 undefined or omit the option: the two spellings mean the same thing, the bare surface/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 }] }.

  • live is the full conjunction of transport-live and every readiness predicate.
  • A subscription error stays in subs and is never folded into live. 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.

ExportTypeMeaning
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
SurfaceReadoutTransportReadout | DegradedReadout{ status, presentingDown, needsReload }, plus stopped on the degraded arm
surfaceReadout(status, health, presentingDown)→ SurfaceReadoutthe 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_MSnumber1 000. The one grace window presentingDown folds over. Baked, never a knob
  • live is 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 reads degraded, not live.
  • degraded names what stopped. stopped carries the erroring subscriptions’ own names (documents.keys, terminals[3], and across siblings surfaceApp/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.
  • status itself 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 debounce status.
  • needsReload is true for retired and 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 read down as 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 false while status is live or degraded.
  • Once status has been continuously not-live for DISCONNECT_OVERLAY_GRACE_MS (1 s), it turns true. A recovery flips it back instantly, with no second window.
  • createSurfaceReadout derives it once, from the same window, for connectSurface / connectSurfaces and every consumer of a readout, so the policy cannot be forgotten.
  • A retired readout presents immediately. A retired wire never re-dials, so there is nothing a grace window could hold back.
  • The frozen retired readout a disposed connection hands back is true for 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.

ExportSubpathWhat it is
isSurfaceStdioTransportClosed(reason)@kolu/surface/errorsRecognizes the raw stdio close of a re-served surface.
isSurfaceRelayTransportLost(reason)@kolu/surface/errorsRecognizes the retryable wrapped upstream death.
The wire’s frame cap@kolu/surface/frame-limitThe largest ndjson frame a link will carry, and the close code for one over it.
Fitting under the cap@kolu/surface/frame-chunkingThe 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 SurfaceRelayTransportLost automatically, via STREAM_RETRY.
  • A consumer that dials the re-served surface with a raw dispatch (no fence) recognizes them with isSurfaceStdioTransportClosed(reason) and isSurfaceRelayTransportLost(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.

ExportTypeMeaning
RPC_MAX_FRAME_BYTESnumber16 MiB. The largest single ndjson frame the decoder will buffer.
rpcSerializationLayerLayer<RpcSerialization>The ndjson layer carrying that cap. Use instead of RpcSerialization.layerNdjson at every client and server leg.
exceedsFrameLimit(bytes)(number) → booleanMirrors Effect’s own predicate, boundary included: a frame of exactly RPC_MAX_FRAME_BYTES passes.
FRAME_TOO_LARGE_CLOSE_CODEnumber1009.
isFrameTooLargeClose(code)(number) → booleanClassifies 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 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 SurfaceStdioTransportClosed with death: "undecodableFrame", and the owner re-dials a fresh link.
  • The websocket leg cycles its socket instead. The failed calls are the retryable RpcClientError that 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.
  • 1009 must stay out of any isTerminalClose set. 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’s appendTo continuation 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 deltas snapshot scales with the number of entries, so it is split into RPC_STREAM_CHUNK_BYTES parts. 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.

ExportTypeMeaning
FRAME_CHUNK_BYTESnumber3 MiB. Raw bytes one frame carries. A multiple of 3, so the base64 division is exact.
FRAME_CHUNK_BASE64_CHARSnumber4 MiB. FRAME_CHUNK_BYTES after the 4/3 expansion — a multiple of 4 by construction.
FRAME_ENVELOPE_BYTESnumber64 KiB. What everything on the frame other than the payload is budgeted at.
FRAME_PAYLOAD_BUDGETnumberRPC_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) → numberceil(R / 3) * 4.
base64DecodedLength(data)(string) → numberDecoded size without decoding — for a size gate that must not materialize a buffer.
frameBytesFor(base64Chars)(number) → numberWhat a frame carrying that payload costs, envelope included. Hand it to exceedsFrameLimit for a pre-send refusal.
RPC_STREAM_CHUNK_BYTESnumber256 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_BYTES parts at the server, each a separate ack-gated frame.
  • buildSurfaceFace reassembles them before any consumer sees a frame, so useCollection, fold, mirrorRemoteSurface and a SurfaceMap fold are all transparent.
  • The split and the reassembly both live beside the wire’s frame budget, in the package’s collectionDeltasFraming module.

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.

InvariantWhat it means
Snapshot-then-deltasThe first frame of every stream is a fresh full snapshot.
patch is a cross-runtime contractA cell’s patch runs on both sides, so changing it is a wire-format change.
The group and the handlers are one route setAdvertised tags and answered tags must match at boot.
Raw streams join healthA raw stream still reaches health(), through client.rawStream / client.enroll.
The 2-file invariantA 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 input is 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 refWhat it is
.streams.X.unenrolledA StreamingProcedure.
.collections.X.unenrolledKeysThe raw keys StreamingProcedure, present iff the collection declares the keys verb.
.collections.X.unenrolledDeltasThe 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.