Skip to content

Explicit Environment Object

Reified-environment artifact — instantiates Definition-Time Context Binding

Reifies the context a unit depends on into a single value passed explicitly at the call, so the unit resolves its dependencies from that parameter rather than ambient globals.

An Explicit Environment Object takes the context a behavior unit would otherwise pull from the ambient environment — configuration, request identity, deadlines, service handles — and packages it into one value that is passed as an argument. The unit is written to read what it needs from this parameter, never from globals, so its dependencies are visible in its signature and supplied deliberately at the boundary. It is the archetype's sanctioned escape hatch: rather than capture ambient context at definition time and hope it means the same thing later, you make the context an explicit interface and hand it in at the call. Its defining move is that binding becomes a policy of the signature — nothing resolves by accident, because everything the unit depends on has to be handed to it, in the open.

Example

A web service handles each request through a chain of functions: authenticate, authorize, load the account, render. Each step needs the same request-scoped facts — who the caller is, a deadline for the whole request, a trace ID, the tenant's config. The ambient way stashes these in thread-locals or globals and hopes every step reads the right ones; under concurrency that quietly breaks, and in a test there is no "current request" at all. The explicit way threads a single request-context value through every call — Go's context.Context is the canonical shape — carrying exactly those request-scoped facts and no more. Each handler resolves the deadline and caller from the value it was given, so two requests in flight never cross wires, and a unit test simply constructs a context and passes it. What the unit depends on is now written on its front door instead of reached for behind the scenes.

How it works

  • Reify the environment. Collect the context the unit needs into one explicit value with a clear shape, instead of leaving it scattered across ambient globals.
  • Thread it, don't fetch it. Pass the object into the unit (and onward through its calls); the unit resolves context from the parameter, making the dependency part of the contract.
  • Keep it minimal and scoped. Include only what the unit legitimately needs, and scope the object to the operation, so it is a precise interface rather than a global by another name.

Tuning parameters

  • Contents breadth — a tight, typed set of exactly-needed values, or a broad grab-bag "context." Tight keeps the interface honest; broad is convenient but drifts toward an ambient dump.
  • Immutability — a frozen snapshot passed down, or a mutable object accumulated along the way. Immutable is predictable and safe to share; mutable enables passing results back but invites hidden coupling.
  • Threading discipline — passed explicitly at every hop, or attached to a carrier that flows implicitly. Explicit threading is verbose but fully visible; implicit carriers re-introduce ambient risk.
  • Typed vs. bag-of-keys — a structured type with named fields, or an untyped key-value map. Types catch missing context at compile time; maps are flexible but defer errors to runtime.

When it helps, and when it misleads

Its strength is that it puts a unit's context in the open: dependencies show up in signatures, testing needs no ambient setup, and concurrent operations cannot cross-contaminate because each carries its own explicit context. In spirit it is dependency injection by parameter rather than by lookup.[1] The honest failure mode is the grab-bag: an environment object that swells into a catch-all "context" becomes an ambient global smuggled through a parameter — everything reaches into it, and the honesty of the interface is lost. The classic misuse is stuffing unrelated values into the object "since it's already being passed," or mutating it as a side channel, both of which quietly rebuild the coupling it was meant to remove. The discipline is to keep the object minimal, typed, immutable where possible, and scoped to the operation — an interface, not a junk drawer.

How it implements the components

  • binding_time_policy — it chooses explicit-interface binding: context is supplied at the call boundary through the signature, not captured from the ambient environment at definition.
  • captured_environment_manifest — the object is an explicit manifest of the context the unit depends on, enumerated as a passable value.
  • context_minimization_filter — by including only what the unit legitimately needs, it filters the passed context down to a precise interface rather than a global by another name.

It supplies context by passing a value, not by resolving stable handles through a shared lookup — that is Dependency Handle Registry — and it deliberately avoids definition-site capture, the ambient-capturing route taken by Lexical Closure.

Notes

The explicit environment object and the dependency handle registry are complementary answers to the same problem: both replace ambient resolution, one by passing context as a value, the other by looking it up through a governed handle. A system often uses both — a registry to resolve long-lived services, an environment object to carry request-scoped facts — and the failure mode of each is the other's discipline (a bloated environment object wants a registry; a hidden registry wants explicit passing).

References

[1] Dependency injection by parameter (the "Reader"-style approach): a unit declares the context it needs and receives it as an argument, rather than fetching it from a global or a locator. Making the dependency explicit in the signature is precisely what distinguishes this mechanism from ambient capture. ↩