Electricity — identified, and their progress

What counts as electricity

Löwy’s receptacle — hide the volatility behind a socket you plug into. Three tests at once: ① domain-agnostic — no terminal/canvas/git/xterm leaks into the interface; ② encapsulates a real volatility — an axis the system actually varies along (transport, reconnect, GPU-context loss, persistence), not a stable 3-line ===; ③ graduates — ships as @kolu/* and a different app plugs in. The proof of ③ is real, not aspirational. @kolu/surface is kolu’s own client↔server transport first — and it has since picked up a second consumer in srid/drishti (a fleet process-monitor; browser ↔ Bun ↔ ssh-agent) that vendors it from this repo and declares its own per-host schema with none of kolu’s domain. The second consumer isn’t the point of the extraction — it’s the proof it was real electricity: surface never noticed the domain changed.

How a session mis-identifies electricity — three traps, learned the hard way

The live example: asked to add back/forward to the Code-tab preview, a session proposed extracting a history stack. Wrong three ways, each caught only by re-asking the test above — and the solid-browser extraction (archived) is the corrected end-to-end.

Naming an organ, not the concept. A history stack is a transformer — a working part inside a larger thing. The electricity was the browser (location + history + link-nav + render-host); history is one chamber of it. Test: is the name self-describing standalone? “history” → history of what?; “browser” → obvious. If you must append “…of X” to explain the name, you’ve named a part, not the receptacle.
A module in client/src/ is not electricity. Location is structure (Hickey): a generic-looking helper living inside the app is part of the app, however agnostic the code reads. Electricity is its own package, the dependency arrow pointing out — client → @kolu/x, never back. (createSharedRoot sits in client/src marked “publish?” — a leaf awaiting graduation, not a precedent for calling in-app modules electricity.)
Agnostic ≠ electricity — apply test ② honestly. A clean, reusable, agnostic primitive that hides only a bounded algorithm (a stack, a debounce, an ===) is a leaf (nonempty/html-escape-tier), not a receptacle. “I found a tidy generic module” is the feeling that precedes the mistake. Ask what volatility it actually encapsulates — what axis of change (transport, GPU-context loss, sandboxing, reconnect) — before reaching for @kolu/.

“Decompose based on volatility” — Löwy’s directive: encapsulate each area likely to change behind a stable interface, rather than split a system by what it does. “Electricity” is his own example, and the source of our term: “the electricity that powers a house … is highly volatile: power can be AC or DC; 110 volts or 220 volts … produced by solar panels … a generator … or plain grid connectivity … All that volatility is encapsulated behind a receptacle … all the user sees is an opaque receptacle.” The body does the same — blood-pressure, salinity, and pulse volatility “encapsulated behind the service called the heart.” An electricity, in kolu, is one such volatility lifted into its own @kolu/* package; a receptacle is the socket a consumer plugs into. — Juval Löwy, Software System Decomposition, ch. 2 of Righting Software.

The electricities

Electricity	Owns (volatility)	PR	Progress
@kolu/surface	Live client↔server state — `Cell`/`Collection`/`Stream`/`Event` over oRPC, reconnect, fine-grained reconcile.	#805	done · 2nd consumer: drishti
@kolu/surface-app	The app shell for surface apps — fresh delivery + server/build identity + the connection/update lifecycle model + desktop-install. Owns the stale-tab handshake gate (#1231) and now the connection plumbing (#1234) — the `pid`-echo, the partysocket construction, and the upgrade gate, lifted from both consumers into three composable primitives (see archived notes). The restart axis already lived here, so each leak plugs into a receptacle the package had.	#1154 · #1231 · #1234	done · 2nd consumer: drishti
@kolu/surface-nix-host	`HostSession` — `nix copy` a closure to a host, realise, run `--stdio` over ssh.	#984	done · also in drishti
@kolu/artifact-sdk	Two volatilities under one roof — the agnostic anchoring core (W3C quote re-find; speaks only `Range`/`Document`/`ShadowRoot`) and the sandboxed-iframe parent↔frame bridge (opaque-origin postMessage, now carrying comments + in-frame navigation + back/forward input). See the re-eval note below.	#922	done re-eval
@kolu/transcript-core + transcript-html	Transcript model + rendering.	#744	done
@kolu/solid-pierre	SolidJS adapters for Pierre tree/diff.	#823	done
persistedPref	Validated localStorage (validate-on-read; closed the zoom-`NaN` + maximize bugs).	#1089	done
@kolu/log · @kolu/html-escape	Zero-dep leaf types every package can import without dragging the domain tree.	#1089	done
dom/ + injectable `isMac`	`walkShadowRoots` relocated to a neutral wall; keybind core no longer reads the UA singleton.	#1089	done
createSharedRoot	Lazy app-scoped reactive singleton (7 consumers). 100% agnostic SolidJS.	#974	done publish?
@kolu/serve-dir	Fetch-native file serving from an absolute root — streaming byte-range (`206`/`416`), content-type, lexical traversal guard; a pure `(root, relPath, request) → Response`. Its *own package, zero workspace* deps** (`node:fs`/`path`/`stream` + the focused `mrmime` MIME table) — the dependency arrow points out (`kolu-server → @kolu/serve-dir`). Agnostic of terminals/git/kolu; the consumer injects the root and composes the artifact-sdk `<script>` decorator downstream. A 20-agent prior-art survey found no static-serve library fits the serving shape (all pipe to a Node `res`, breaking the Fetch-`Response` + decorator composition; none takes a per-request absolute root or does a realpath guard), so the serving is owned here — but the MIME table leans on `mrmime` (the separable commodity the survey explicitly didn’t cover). That’s load-bearing for decomposition: a complete table means adding a format to kolu’s `_EXTENSIONS` classifier needs no edit here* (mrmime already types it), so the ext↔MIME shared-volatility the lens debated is dissolved for every mrmime-known format. For the mrmime gap set (`.m4v`/`.ico`, and any future classifier entry mrmime doesn’t know) the coupling is instead contained-by-test: a 2-entry `OVERRIDES` in serve-dir supplies the MIME, and the coverage invariant in `iframePreviewRoute.test.ts` is load-bearing, not a thin sanity check — delete an `OVERRIDES` row and the classifier still routes the file to a `<video>`/`<img>` appliance while serve-dir answers `application/octet-stream`, so only that test catches the silent download regression. Path safety is two-stage by volatility: the lexical guard (decode-then-split + `path.relative` containment) is built in (pure, universal), while the realpath/symlink guard is an injected `realpathGuard` the consumer supplies (fs-touching, threat-model-specific) — `kolu-server` wires kolu-git’s `assertRealpathUnder`, so the package stays agnostic without dropping the security boundary. A leaf (bounded algorithm, not a transport-grade volatility).	#1225	done ②/③ proof-pending
@kolu/terminal-protocol	The VT/device-query protocol policy both terminal clients and the server must agree on — the query-reply suppression grammars (whole-payload predicate for the browser’s `onData`, streaming boundary-aware stripper for kolu-tui’s raw tty), the headless forward/drop rule, the answered/silent device-query matrix as data (executed against a real headless by `@kolu/pty-host`’s contract tests, so policy and implementation can’t drift), the bracketed-paste delimiters, and the snapshot-reciprocal TTY reset. Born when the second terminal client (kolu-tui `attach`, #1255) made the fragmentation visible: the same concept lived in `kolu-common`, `pty-host`, and `pty-tui`, held in lockstep by prose — and the browser may not depend on `@kolu/pty-host`, so a leaf both sides import is the only receptacle that dissolves the cross-references. Hashed into the pty-host staleKey (a protocol change is observable daemon behaviour; pinned by `buildId.closure.test.ts`). A leaf (bounded protocol tables, not a transport-grade volatility) — the `serve-dir` tier, not the `surface` tier.	#1255	done
@kolu/xterm-kit	The accumulated high-level xterm.js machinery — pinned `_core` internals with two failure philosophies, in-place scrollback surgery + seam-token write path, the mirror anchoring lifted from kaval, and the SolidJS lifecycle (WebGL single-owner + context-loss recovery, owner-correct async dispose across `await`) — as a runtime-neutral core + `/solid` adapter; kaval and the client as two consumers. (archived plan).	#1795 (PR 1) #1808 (PR 2)	core graduated `<Xterm>` wrapper
osfacts + osfacts-client	How an OS answers “which processes in this subtree hold listening TCP sockets, and on what addresses?” — one Rust binary on both platforms; TypeScript client is `osfacts-client` (no `@kolu` scope; exactly one npm runtime dep, `effect`, pinned to the same version both consumers already pin — its spawning verbs hand back Effects, so an abandoned read kills its child instead of running out a five-second deadline). The former `@kolu/port-scan` package dissolved: OS volatility lives in osfacts; kolu policy (bind judge, U-row blindness) in padi; browser-safe `PortInfo` + fold in `@kolu/terminal-vocab`. Test ② measured: darwin’s mechanism changed three times before settling on osfacts. Consumers call `scanSubtreePorts` (padi) / `snapshotSubtree` (client) and learn none of the OS detail. Test ①: pid → identity join is the CALLER’s. Test ③ closed: drishti shipped as the second consumer of `osfacts-client` (#122), retiring its own hand-rolled readers.	#1982 · #1996	extracted ③ two consumers
@kolu/port-forward	How a port that answers only on some other machine’s loopback is made to answer here — an `ssh -L` child on a connection of its own for a remote target, an in-process TCP relay for this machine’s own loopback, behind one `ForwardManager` receptacle (`create` idempotent by target · `cancel` · `list` · `dispose` · `onLost`). Test ② is the strong one and it is measured: the mechanism was rebuilt mid-PRT0 when a shared ssh master was proved unable to give the one property the whole feature rests on — a live sshd showed `-O forward` listeners outliving their requester by the full `ControlPersist` window, with no `-O list` to re-adopt them — so lifetime won and each forward took its own connection. Consumers call `create(target)` and learn none of it. Test ① passes by construction: a target is `(host, port)` where `host` is any ssh destination, so nothing of terminals, tiles or kolu’s host model crosses the boundary. Test ③ is PROVEN, not pending — PRT0 shipped a standalone TUI consumer (vazhi; since removed) beside the library with no kolu running, and PRT2’s Inspector embed was the second genuinely independent app: embedding it changed the library’s mechanism API by exactly one field (`lastLocalPort`, so a restarted dev server comes back on the URL you already have), and BOTH of the shape changes the plan predicted a second consumer would force — a `list()` subscription, a tagged error union — turned out unwanted when that second consumer actually arrived. Production consumer today is kolu’s Inspector only.	#1975 (PR0) · #1991 (PRT2)	done · consumer: kolu’s Inspector
holdOneLink (candidate — recorded, not extracted)	One live connection to a dialed surface — memoized across concurrent callers, dropped the instant the transport announces its close (identity-guarded, so a late announcement from a disposed predecessor cannot stomp the successor a redial already published), re-dialed on demand, disposed under a teardown latch. Test ② is measured, not asserted: the axis has moved twice in this tree — #1719 split dead-vs-transient transport tags, and #2117 moved discovery→announcement. Test ① passes by construction: nothing of terminals, padi or MCP crosses it. Test ③ is where it stands: three hand-rolled implementations today — `surface-mcp`’s shared connection slot and its `ResourcePusher` attachment (`packages/surface-mcp/src/{server,pusher}.ts`), and `surface-daemon-supervisor`’s `holdConnection` (`endpoint.ts`, which already does the identity-guarded `onClose`→drop in almost the same words); `@kolu/port-forward` publishes the same verb as a required member (`onLost`). odu’s `redialingAClient` is deliberately not counted, and the reason cuts against this row rather than for it: it opens a fresh `.ci/odu.sock` for every upstream call and holds nothing, so it has no slot to invalidate and pays a dial per call to avoid needing one. That is a real alternative to this receptacle, not an instance of it — a consumer can buy the same freshness by making dials cheap enough not to memoize. The evidence it is one concept and not three: `koluCliConnectionOf` (`kolu-cli/src/connect.ts`) exists only because two packages declare the same handle, so the boundary can only be crossed by carrying each wire over by hand — under a shared `HeldLink<C>` it collapses to a client-narrowing wrapper with no per-field carry and no drift class. Home would be `@kolu/surface` beside `links/` + `isDeadTransportError` — not a new package: a parallel receptacle for an axis the supervisor already encapsulates is the duplicated-receptacle trap. Extraction is deliberately deferred (prove-then-extract); this row exists so the candidate cannot evaporate.	#2117	candidate · ③ population 3 in-tree, extraction unproven
@kolu/solid-browser	The Code tab is a browser — location/address model, back-forward history, cross-content-type link interception, GitHub-relative resolution, sandboxed-iframe lifecycle. git is an injected resolver; the renderer packages plug in. (archived plan).	#1191	phases 1+2 primitives + `createBrowser` history shipped · `<Browser>`/gitResolver deferred, ③ proof-pending

surface-app's stale-tab gate — what graduates, what stays a socket the consumer plugs in

The restart axis already lived in createServerLifecycle (restartCloseCode + the transport:"open"\|"closed" discriminant), so #1231 only had to graduate the shared pieces and leave the per-socket ones behind. The split is the whole test ① at work — none of the graduated parts knows a terminal from an ssh-agent.

Graduates (the second consumer shares the identical partysocket + oRPC stack, so the volatility is genuinely common): the pid/4001 constants and a runtime-free rejectStaleProcess(claimedPid, liveId): boolean; serverIdentity() returning its minted processId so the gate compares against the SAME id identity.info reports (drishti otherwise mints a second randomUUID() and the gate never matches); and — the F1 reversal of the prior “keep it per-consumer” — retireSocket, whose two reverse-engineered side-effects (close() flips partysocket’s _shouldReconnect; a throwing send makes oRPC’s ClientPeer reject pending instead of letting maxEnqueuedMessages:Infinity grow) bind to internals drishti has byte-for-byte. It takes a structural { close; send }, not a PartySocket, so it never drags the concrete type across the boundary.

Stays the consumer’s socket to plug in: the socket builder (drishti’s makeSocket cold-start deadlines, its wsUrlFor query) and the per-runtime pid read off the request (kolu’s Node IncomingMessage, drishti’s Bun Fetch-URL) — surface-app emits the id, never the URL. The client’s last-known id stays a per-consumer mutable on purpose: the lifecycle’s serverProcessId() deliberately reports undefined on a stale close (the only id on hand is the dead process), but the pid echo must keep re-presenting that dead id to get re-rejected — two different facts, not one projected twice, so the URL thunk owns its own lastServerProcessId.

Then it graduated too (#1234, surface-connection — archived). Reading drishti’s actual post-#1231 source — not assuming it — overturned the “stays the consumer’s socket” line above: both consumers hand-roll the identical partysocket construction and pid-echo threading (drishti’s “Bun Fetch-URL” runtime is in fact the same ws stack as kolu). So the socket builder and the echo did graduate, as createSurfaceSocket + createProcessIdEcho in @kolu/surface-app/connect. The “two different facts” insight is preserved inside the echo — createProcessIdEcho still re-presents the dead id, distinct from serverProcessId() — it just isn’t hand-rolled per consumer anymore. What genuinely stays per-consumer narrowed to lifecycle ownership (kolu’s rpc.ts vs drishti’s <SurfaceAppProvider>) and socket topology (one socket vs per-host + admin sharing one echo). Same lesson as the F1 retireSocket reversal: the boundary is set by what’s actually duplicated, found by reading source, not by what looked per-consumer at first.

liveWhen — predicate-as-data: the fold graduates, the meaning plugs in

The sharpest proof the receptacle stays domain-blind is the verb it refuses to learn. client.health().live is the full conjunction — transport-live ∧ every readiness cell’s predicate — yet @kolu/surface core never knows what “connected” means. The fold is the receptacle: a generic CellSpec.liveWhen?: (value) => boolean marks a cell a readiness gate, and core AND-reduces that cell’s verdict into live (registry.enrollReadiness) without ever naming a state literal. The volatile knowledge rides the cell as data — surface-nix-host’s connectionCell declares liveWhen: (v) => v.state === "connected", and the ssh vocabulary (the predicate, the four-state enum) stays there, beside the schema. It’s the runtime sibling of CellSpec.equals / resolveCellVerbs: core owns the mechanism, the plug owns the meaning — the receptacle is domain-agnostic, the volatility plugs in as data. So every surface mirrored through mirroredSurface carries its mirror-liveness leg by construction — no consumer hand-ANDs connection.state === "connected", and no widget can paint a dot green from raw cell state. Location is structure in the un-obvious direction too: the === "connected" can’t migrate into core without dragging ssh’s domain across the boundary, so the split isn’t a convention you keep — it’s load-bearing.

Re-evaluating @kolu/artifact-sdk — its electricity framing shifted (open; resolve outside this PR)

“Anchoring” (the original #922 framing) now under-describes the package. It holds two volatilities: (1) the anchoring core (core/ — W3C quote extract/re-find/highlight; pure and agnostic, speaks only Range/Document/ShadowRoot), and (2) the sandboxed-iframe parent↔frame bridge (client/bridge.ts + iframe/ — opaque-origin postMessage with event.source identity as the only trust boundary). The bridge is the harder volatility, and it has quietly accreted clients: comments (selection → SelectMsg → highlights), then in-frame navigation (observeIframeNavigation), then back/forward input (observeIframeHistory, #1191). The lens-debate in #1191 already reframed the package’s stated identity to “the in-iframe sandbox bridge, with comments as one client” — but that was a docs fix, not a decomposition.

The open question (work it outside this PR): is “talk to code inside an opaque-origin sandboxed frame” one sound receptacle — a transport-grade volatility with comments / navigation / input as interchangeable clients — or a topic-bundle that should split the agnostic anchoring core from the bridge transport? Note the smell that prompted this: the back/forward client landed in this package only by physical necessity (the one script inside the sandbox is this one), which is exactly the “easy to put it here” the three traps above warn against. Flagged, not decided.

Plus external electricity correctly leaned on instead of hand-rolled: Corvu (dialog/drawer/focus-trap/scroll-lock), @solid-primitives/* (resize-observer, media). Origin: a 41-agent Hickey/Lowy audit (16 candidates) → its “ship now” tier landed in #1089; a framework-scale re-test + adversarial skeptic surfaced the missed solid-xterm.

Built: @kolu/xterm-kit

The one electricity still unbuilt at the framework audit — mis-filed at first as “terminal domain,” but a runtime-neutral adapter over xterm.js is agnostic (the .agency/lowy.md §6.5 “what library is this?” test). It owns the declared volatility rows — async-init cleanup (the #598/#600 ~900 KB leaks), canvas/ WebGL lifecycle (the #591 zombie-context hunt, #575/#239/#595), the pinned _core internals with two failure philosophies, and the mirror anchoring lifted from kaval.

Graduated into @kolu/xterm-kit — a runtime-neutral core + /solid adapter, with kaval and the client as two consumers from day one, so the population-of-one caveat that shadowed the old solid-xterm name is gone. The behavior-neutral core + mirror-anchor lift ship in #1795 (PR 1); the <Xterm> component wrapper + the touch-divisor unification ship in the e2e-gated #1808 (PR 2). Plan of record: archived notes.

Considered — not electricity

Looked framework-sized (the audit’s biggest braids), but fail the bar — recorded so they don’t get re-proposed.

Candidate	Verdict	Why
defineMutation (optimisticOverlay)	helper	One module, one domain (canvas layouts); the write echo is already owned by `surface`’s metadata subscription. Pending is a UI cache, not a transport axis.
@kolu/fs-watch	helper	Owns a refcount/debounce lifecycle, not a streaming transport — no wire contract, Node-bound. A `@kolu/shared` helper, not a socket.
@kolu/geometry	domain-coupled	`TileLayout` binds it to a server-persisted domain type; a `Rect` package re-adapts at every boundary — moves the braid, doesn’t dissolve it.
@kolu/surface-publish	already-covered	Surface’s `cellHandlers`/`collectionHandlers`/`pollOnEvent` already own server snapshot+delta. Only `terminal.attach` is a raw escape hatch.
@kolu/commands (palette)	domain-coupled	Palette engine is already agnostic; all coupling is isolated in `createCommands`, which must stay in the app. Extracting deletes ~0 kolu lines.
God-procedure split	refactor	Its biggest dissolvable chunk is `xterm-kit` (above); the rest is kolu orchestration — a refactor, not a receptacle.

Bar from Juval Löwy, Righting Software (receptacle/volatility) + Rich Hickey, Simple Made Easy (complecting); one-socket-not-a-topic-bundle is .agency/lowy.md §6.5. file:line verified against the codebase; ③ demonstrated by drishti — a second consumer (kolu is the first) that vendors @kolu/surface via npins.