ScopedValue has no set() method — how do you provide a different value to part of a call, and why is this design chosen?

## The starting point A `ScopedValue<T>` is bound for the dynamic extent of a `where(KEY, value).run(task)` call. Crucially, there is **no `KEY.set(...)`** — once bound, the value is fixed for that scope. New learners coming from `ThreadLocal` (which has `set()`) often ask: "how do I change it partway through?" The answer reframes the question. ## Rebinding via nesting You don't *change* a value; you **shadow** it with a fresh binding around a smaller region: ```java static final ScopedValue<String> TENANT = ScopedValue.newInstance(); ScopedValue.where(TENANT, "acme").run(() -> { System.out.println(TENANT.get()); // acme ScopedValue.where(TENANT, "globex").run(() -> { System.out.println(TENANT.get()); // globex (inner scope) }); System.out.println(TENANT.get()); // acme again (restored) }); ``` The inner `where` introduces a new binding that **shadows** the outer one only for the dynamic extent of the inner `run`. When the inner `run` returns, the binding stack pops and the outer value (`acme`) is automatically back in effect. This is exactly like nested lexical variable shadowing, but along the *call stack* (dynamic scope) rather than the source text. ## Why immutable? — three reasons **1. Eliminates action-at-a-distance.** With a mutable `ThreadLocal`, any method reachable from a call could do `tl.set(x)` and silently alter what a caller reads afterward. Bugs from this are notoriously hard to trace because the mutation point and the read point are far apart. With ScopedValue, the value is constant within a scope, and *every* value change corresponds to a visible `where(...)` at a known site. Data flow becomes local and auditable. **2. Stack discipline = automatic, exception-safe cleanup.** Because a value can only be introduced by entering a scope and can never be mutated in place, bindings form a strict stack that unwinds with the call stack. The runtime restores the previous binding on scope exit — including when the inner block throws — with no `finally`/`remove()` from you. Correctness is structural, not a matter of remembering cleanup. **3. Cheap sharing with subtasks.** Immutability means a binding can be **shared by reference** rather than copied. In structured concurrency, a parent that forks many virtual-thread subtasks lets them all read the same binding without per-thread copies (contrast `InheritableThreadLocal`, which copies to each child). Mutability would forbid this safe sharing because a subtask could change a value other subtasks see. ## Practical consequences - Treat a ScopedValue as a *constant within its scope*. If you find yourself wishing you could mutate it, that usually signals you actually want a *nested scope* (a genuinely different sub-context) or a different tool (e.g., a mutable holder object you bind once and whose contents you change — but be deliberate, that reintroduces mutability of the referenced state, not of the binding). - Rebinding is local: sibling code outside the inner scope is unaffected. There is no way for the inner scope to push a value *outward* to its caller — information only flows *down* the call stack. ## Mental model ScopedValue bindings are like dynamically-scoped `final` constants on a stack: each scope can introduce its own constant value, nested scopes can shadow it, and exiting a scope pops back to the enclosing value — always, automatically, even on exceptions.