The two shapes every pooled component in the house has, the capital one that constructs and pools and the lowercase one that uses, with install as the tether between components, and the rules that keep downstreams from allocating.
By Bogdan Vladoiu, 2026-11-17
Two shapes per component, split by case.
Browser { } (capital) — construction, retention, pooling. Private constructor plus operator fun invoke on the companion, so creation reads as a function while the companion keeps control of whether it constructs, reuses or multiplexes. Downstream cannot allocate, so downstream cannot invent a pool.
browser("chrome17") { } (lowercase) — usage. The argument SELECTS from the pool the capital shape set up, multiplexing when absent. The block is an isolated workload boundary so concurrent callers do not run over each other. Apis inside dogfood: visit(url): Page → page.extractUrls() → visit(next).
install { } — tethering. Components installing one another, or the runtime installing into a component. Also the remember{} replacement on Compose, taking a Sink/Source when the caller has one.
A usage closure never allocates its component or its pool — it receives them. Ordinary local values inside the block are fine; what it must never do is construct, pool, index or multiplex the thing it was handed.
Why this lives beside the component: a user of a browser never meets batching, multiplexing, throughput or lookup — one user, one browser. Those answers do not exist in everyday use of the thing, so if the component does not answer them in its own package, every downstream invents its own and none of them agree.
Downstreams offer PERSPECTIVES only, never allocation. Requiring a downstream to take over any aspect is the literal definition of technical debt. Seams are functional shapes or stdlib types, never invented ones.
A convention, not a type family: no Entity<T> hierarchy, ever.
Favour optional arguments with default values, and overload, as far as it will go. It is the only thing that keeps a domain's surface and its seams minimal. The alternative — a new shape per nuance — creeps fast into an ensemble that is very hard to recognise as self-inflicted complexity, and by the time it is recognised it can only be removed in bulk. A nuance is a defaulted parameter or an overload until proven otherwise; a new named shape is the last resort, not the first. This is what makes anticipated behaviour (onLowMemory eviction, a length-prefix degrading to chunked streaming on -1, a poll cadence for hosts that cannot block) arrive as arguments rather than as types.
A seam's default has a polarity. A defaulted lambda that opens data-backed CONTENT (a translation, a theme, a label, an enrichment) falls back to what the code holds and logs one warning: a miss is never an outage. A defaulted lambda that decides ACCESS (a grant, the ownership of a row, what a door forwards) refuses on a miss and logs it: a permission seam left closed, unanswered or failing must never read as allowed. Same shape, opposite default — never copy the content form onto a permission.
Scope: this describes components that pool or multiplex. It is NOT licence to retrofit existing classes — an existing shape changes only under the Naming rule.