How do you govern what a large codebase provides ambiently through the component tree, and what does over-use cost?

Ambient provision is the one mechanism in a component tree that lets a dependency exist without appearing in a contract. That makes it indispensable for a handful of values and corrosive as a habit, so the interesting work is deciding membership and then holding the line. ## The admission test Admit a value when it passes all of these, not just the first: - **Many readers, few writers.** Dozens of components consume it; one place, or a small number, changes it. - **Genuinely ambient.** It describes the environment a subtree runs in, rather than parameterising one parent's use of one child. - **Slow relative to rendering.** It changes orders of magnitude less often than the subtree renders, or the channel it rides has read-level notification granularity. - **One honest instance per scope.** "The session", "the theme", "the client" is a coherent singular thing at the scope where it is provided. - **The alternative is real threading.** Without provision the value would pass through three or more components that never use it. | candidate | verdict | why | |---|---|---| | theme and design tokens | admit | read nearly everywhere, changed rarely, one per scope | | display locale and formatting rules | admit | same shape, and correctness depends on every reader agreeing | | session or signed-in user | admit, scoped deliberately | many readers, and its lifetime should bound a subtree | | a configured transport or data client | admit | a collaborator chosen once by an ancestor for a whole subtree | | one screen's fetched record | refuse | its readers are two levels away; pass it | | a field's value at keystroke rate | refuse on a coarse channel | wakes every consumer in the subtree per keystroke | | coordination inside one compound widget | provide locally, not at app scope | ambient to that widget's subtree only | | anything with a single reader | refuse | nothing is threaded, so nothing is saved | ## What over-use costs - **The contract stops describing the component.** Its inputs no longer list what it needs, so a reader must know the ambient set to know whether it will work. - **Nothing renders standalone.** Every consumer needs a scaffold of providers above it, in previews, in showcases, in tests - and test wiring is its own subject with its own owner. - **Refactors re-bind silently.** Moving a component into another subtree can change which provider it resolves to, with no signal at the call site and no error. - **Scope creep.** Provisions drift towards the root "so everything can read them", which quietly makes every value application-lifetime and removes per-scope isolation. - **The bag problem.** One wide provision accumulates unrelated fields; on a coarse channel unrelated features then wake each other, and every new field widens the blast radius. - **Debugging altitude rises.** "Where did this value come from?" becomes a question about run-time tree position rather than a two-second read of the parent. ## Governing it 1. **Keep a register.** A short document listing every ambient provision, what it carries, at what scope, and who owns it. If a provision is not on the list, it is not architecture, it is a shortcut. 2. **One provision per concern.** Resist the single mega-provision; split by cohesion and by change rate so notification and ownership both stay proportionate. 3. **Require loudly.** Provisions with no honest neutral value refuse to resolve rather than returning a default, so a misplaced consumer fails at its first render instead of behaving wrongly. 4. **Hold a library boundary.** Reusable components take their dependencies explicitly; only application-level wrappers read ambiently. A reusable piece that reaches for an ambient value the caller cannot see works in one app and misbehaves in the next. 5. **Ask one review question**: who reads this, and how far away are they? One reader or one level means pass it. 6. **Audit periodically.** Count readers per provision and per field. Single-reader provisions become explicit values; fields with disjoint reader sets become separate provisions. ## The altitude note Provision is dependency choice expressed through tree position: an ancestor selects the implementation and the descendant names only the capability. The general design principle behind that - who should own an abstraction, and what inverting a dependency buys - is a design-level subject in its own right. What is specific here is that the tree is both the scoping mechanism and the wiring mechanism, so a decision about the ambient set is simultaneously a decision about lifetime, reach and testability. That is why it deserves an owner rather than an accretion of individually reasonable additions. ## The failure mode to watch for The channel rarely gets abused in one decision. It gets abused by twenty small ones, each of which saved a little threading, until a component's real interface is the union of its inputs and an undocumented ambient set nobody has written down. The register exists to make that union visible while it is still small.