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; ② hides a hard volatility — transport, reconnect, GPU-context loss, persistence — not a 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 plan 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 hard volatility it hides — transport, GPU-context loss, sandboxing, reconnect — before reaching for @kolu/.

“Decompose based on volatility.” Functional decomposition splits a system by what it does; volatility-based decomposition isolates each area likely to change behind a stable interface — the way a body keeps blood-pressure, pulse, and salinity volatility “encapsulated behind the service called the heart.” An electricity, here, is one such volatility pulled out into its own package. — Juval Löwy, Volatility-Based Decomposition (excerpt from 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 (surface-connection). 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/solid-xterm (createSolidXterm)	xterm.js lifecycle — 8-addon orchestration, WebGL single-owner + context-loss recovery, FitAddon resize, owner-correct async dispose across `await`.	#1116 (plan)	to build
@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. 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). 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.

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.

Next: extract @kolu/solid-xterm

The one genuine not-yet-built electricity — mis-filed at first as “terminal domain,” but a SolidJS adapter for xterm.js is agnostic (the .agency/lowy.md §6.5 “what library is this?” test). It owns two declared volatility rows — async-init cleanup (the #598/#600 ~900 KB leaks) and canvas/WebGL lifecycle (the #591 zombie-context hunt, #575/#239/#595).

Inline today in one Terminal.tsx onMount (982 lines): new XTerm packages/client/src/terminal/Terminal.tsx:482, 8× loadAddon packages/client/src/terminal/Terminal.tsx:500-519, the WebGL single-owner dance packages/client/src/terminal/Terminal.tsx:231-295, owner-correct async init packages/client/src/terminal/Terminal.tsx:473-481, fit/resize packages/client/src/terminal/Terminal.tsx:179 / packages/client/src/terminal/Terminal.tsx:760, touch-scroll packages/client/src/terminal/Terminal.tsx:559-606.

// one primitive (not a topic-bundle, per §6.5):
createSolidXterm({ container, theme, fontSize, canUseWebgl?, enabledAddons?,
  onData?, onResize?, onLinkActivate?, onCustomKeyEvent?, plugins? })
  -> { terminal, searchAddon, hasWebgl, renderer, dispose }

Owns the agnostic core; kolu bits (link provider, soft-keyboard, diagnostics probes, the PTY terminal.attach stream) stay consumer-injected via callbacks. Dissolves ~240–314 lines of Terminal.tsx. Survived the skeptic (“the domain braid runs too deep”) on the interface — those are orchestration concerns, not xterm-lifecycle concerns. Graduates the way surface did: any SolidJS app embedding xterm can plug in.

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 `solid-xterm` (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.