A shared collections.ChainMap holds an invoice renderer's config — why do per-invoice overrides leak into later invoices?

## The failure, precisely The renderer builds one `ChainMap` at import time — file defaults at the bottom, environment above them — and the seventeen services in the render dependency graph each reach for that module-level object to read `dpi`, `locale`, `watermark` and the rest. Somewhere in the fan-out, one service applies a per-invoice override by *writing* to it: `cfg["watermark"] = True`. `ChainMap.__setitem__` writes into `maps[0]`. That mapping is shared with everything else in the process. The invoice that asked for a watermark gets one; so does the next invoice, and the one after that, because nothing ever removes the entry. The visible symptom is a duplicated side effect — the same stamp drawn on documents that never requested it — and it is intermittent in a way that makes it look like a concurrency bug, because whether an invoice is affected depends only on whether some earlier invoice happened to set the flag. The deeper mistake is treating a ChainMap as if it scoped writes the way it scopes reads. It does not. Reads traverse all layers; writes are pinned to one. ## Why `del` does not save you The instinctive patch is to write the override, render, then delete it. Two problems. First, if the key exists in a deeper layer, `del cfg[key]` raises `KeyError` — deletion only ever consults the first mapping, and a ChainMap cannot mask a deeper key. Second, even where it works, the write/delete pair is not exception-safe and not concurrency-safe: an exception between them leaves the flag set, and two invoices rendering concurrently in threads interleave on the same front dict. A `try/finally` narrows the first hole and does nothing about the second. ## The fix: a child layer per unit of work `new_child(m=None)` returns a **new** `ChainMap` whose `maps` list is `[m or {}] + self.maps`. The receiver is not modified; the shared layers are shared by reference, so no data is copied. Every per-invoice write lands in that fresh front dict, and when the render finishes and the object is dropped, the overrides go with it. Reads still fall through to the shared defaults exactly as before, so the seventeen consumers need no change beyond receiving the child instead of reaching for the module global. That last clause is the real remedy: **stop letting call sites reach for the shared object**. Pass the per-invoice ChainMap down explicitly, or bind it to a `contextvars.ContextVar` so concurrent renders each see their own. `parents` gives any layer a read-only view of everything it is shadowing if a service genuinely needs the un-overridden value. ## Liveness is the second hazard A ChainMap holds references, not copies. If a config-reload path swaps values into the defaults dict mid-render, a render that read `dpi` at step 3 and again at step 11 can see two different numbers, producing a document that is internally inconsistent. When a unit of work must be self-consistent, take a snapshot at its boundary: `dict(cfg)` flattens the distinct keys into an ordinary dict, or `cfg.copy()` gives a new ChainMap with a fresh copy of the front layer and shared references to the rest — note that `copy()` is *not* a deep snapshot of the deeper layers. Which you want depends on whether you are isolating writes or isolating reads. ## Diagnosing it in the wild The tell is state that persists across units of work in an object nobody thinks of as mutable. Three moves find it quickly: * **Assert the front layer is empty** at the end of each render in a debug build — the shared instance's front mapping should never accumulate keys. * **Log the layer that supplied a value** when behaviour looks wrong: walk the mappings and report the index of the first one containing the key. Because layers stay separate objects, provenance is recoverable, which is one of the reasons to use a ChainMap at all. * **Grep for writes to the shared name.** Reads of a config object are everywhere; writes should be countable on one hand, and every one of them is a candidate. ## The rule to carry away A `ChainMap` is a stack of read-only context plus one writable scratch layer. Whoever owns the scratch layer owns everything written through the chain. Make that layer belong to the narrowest scope that does the writing — per request, per invoice, per frame — and mutate a process-wide chain only during startup, before anything concurrent can observe it.