4.0: remove the deprecated surface

[lesnik512]

Already documented as leaving in 4.0; listed here so the release has a checklist.

• Container(validate=...) and ValidateArgumentWarning
• Container.scope_map and Container.lock properties (DeprecationWarning since they went private)
• ContextValueNoneWarning (never emitted since 3.0; kept importable)
• ContainerClosedError as a back-compat shell (becomes the real error again if the terminal-close proposal lands; otherwise removed as its docstring says)
• UnvalidatedContainerWarning if nothing emits it (verify before removing)

Each removal is a one-line migration note. Agent-ready once 4.0 is scheduled; the troubleshooting pages and slug census must be updated alongside.

[lesnik512]

This was generated by AI during triage.

Triage Notes

Verified against main at fc39046. Staying needs-triage; this records what is settled so the checklist doesn't get re-derived later.

What we've established so far:

• UnvalidatedContainerWarning is safe to remove. The body's "verify before removing" is answered: nothing emits it. The only references repo-wide are its own docstring and the modern_di.exceptions re-export. Same for ContextValueNoneWarning — confirmed never emitted.
• Container(validate=...), Container.scope_map, Container.lock are all still live and all still warn. scope_map/lock have no internal callers; validate= is covered by two tests that assert ValidateArgumentWarning.
• The list of five is complete. Nothing else in the package is deprecated. The other three warnings.warn sites are UserWarning/ContainerClosedWarning, not deprecations, and the Alias(scope=) / Factory(cache_settings=) deprecations that docs/migration/to-3.x.md still narrates are already gone from the code.
• Bullet 4 is blocked by 4.0: close() is terminal; resolving through a closed container raises #476, now recorded as a GitHub dependency. 4.0: close() is terminal; resolving through a closed container raises #476 reinstates ContainerClosedError as a real raise and deletes ContainerClosedWarning and its page instead — the opposite direction for the same symbol. That bullet's outcome is undetermined until 4.0: close() is terminal; resolving through a closed container raises #476 is decided.
• 4.0 is not scheduled. Milestones are 2.0 and 3.0; latest tag is 3.4.0; the repo is trunk-based with no 4.x branch. Merging these removals into main today would ship breaking changes in the next 3.x release. This is the body's own stated gate.

Implementation notes for whoever picks this up:

• Removing ContainerClosedError also means deleting docs/troubleshooting/container-closed-error.md and its mkdocs.yml nav entry. tests/test_docs_slug_census.py enforces a strict bijection between docs_slug values and pages, so a half-removal fails there rather than in review.
• docs/providers/errors-and-exceptions.md and docs/providers/lifecycle.md both describe ContainerClosedError and ValidateArgumentWarning in prose.
• "Each removal is a one-line migration note" implies creating docs/migration/to-4.x.md; it doesn't exist and needs an mkdocs.yml nav entry alongside to-3.x.md.
• docs/migration/to-3.x.md must keep describing these symbols — it documents the 2.x→3.x hop — so it should not be edited to drop them.

What's still needed before ready-for-agent:

• 4.0 scheduled (a milestone, a release branch, or an explicit decision on where breaking changes land).
• 4.0: close() is terminal; resolving through a closed container raises #476 resolved, which settles bullet 4.

[lesnik512]

This was generated by AI during triage.

4.0 decision log

Milestone 4.0 now exists and carries #475, #476, #477, #478, #481. That satisfies the first of the two gates in the triage note above; the second (#476 resolved) is decision 1 below.

This comment lives on #477 because #477 is the release checklist. Four decisions block the milestone, and they can be answered in one pass. Answering in this thread is enough; each issue can then be updated from here.

1. #476: ancestor closed under an open child

Where does the closed check live once close() is terminal?

• (a) Entry point only. resolve / resolve_provider on the child walk its chain, one attribute read per ancestor. The per-hop check leaves every generated resolver. This is the issue's own recommendation.
• (b) Hop-time. Only raises when a hop actually reaches the closed ancestor, which requires keeping the per-hop target.closed check, which is the thing the proposal exists to delete.

Recommendation: (a), with "closing an ancestor under a live descendant" documented as a programming error.

Unblocks #477 bullet 4. Under (a) or (b), ContainerClosedError becomes a real raise again and is kept rather than removed, and ContainerClosedWarning plus docs/troubleshooting/container-closed-error.md change meaning rather than disappearing. If #476 is declined instead, bullet 4 reverts to a plain removal and the page is deleted, with tests/test_docs_slug_census.py enforcing the nav entry goes with it.

2. #475: is default= enough, and what does the error name?

Two sub-answers:

• (a) Does ContextProvider(Request, default=None) cover the real optional-context cases? The only one the current tests describe is a handler usable outside a request. If that is the whole set, the per-parameter runtime disposition goes and 13 tests are rewritten to the new rule.
• (b) Does ContextValueNotSetError name the parameter as well as the type? Naming the type alone is what makes the registry-less error variant deletable. Naming the parameter keeps a plan-time fact on the error and is the better diagnostic.

These are separable: (a) can be yes while (b) is still open.

3. #481: which alias shape

• (a) Bind and accept the shorter chain. Runtime chains show the parent and the terminal; validate() keeps drawing the redirect hops. Simplest, and a disclosed diagnostic regression: after fix: draw the redirect chain on validate() scope violations #469 made validate and runtime agree on the chain, this deliberately un-agrees them.
• (b) Bind and reconstruct. Add a provider reference to ResolutionStep and rebuild the redirect hops from the static graph via terminal_chain when the parent prepends its step. Compiler stays bound, diagnostic survives, cost is in error rendering only.

Recommendation: (b), unless the added ResolutionStep field is judged too much for a 35% win on a hop with no scenario in the comparative suite.

Second, smaller question in the same issue: is an alias hop common enough in real graphs to be worth either shape. A Protocol per service is the documented pattern, which argues yes, but the published tables will not move either way.

4. #478: measurement gate, not a design call

Nothing to decide until G6 (child build) and G15 (concurrent first-resolve) are measured end to end. The 107 ns is a microbenchmark of RLock() alone against an 829 ns child build. What the decision will be once the numbers exist: whether removing use_lock from the public constructor is worth a per-tree lock that serialises concurrent cold misses across sibling requests.

Also needs a pass over the free-threading tests. use_lock currently appears in four tests in tests/test_container.py, two of which assert the False path specifically.

Not in the milestone, but adjacent

#474 (private-access boundary) is non-breaking and can land in any 3.x. Its option 1 adds read-only public views to ProvidersRegistry, which is additive and therefore not a 4.0 requirement. Flagging it only because a major is a natural moment to make that surface public if option 1 is the answer; if it is, say so and it can ride along rather than shipping separately.

Sequencing once the above are answered

#476 then #477 (hard dependency, already recorded). Then #475, then #481. #478 last, since it waits on benchmarks rather than on an answer here. #475, #476 and #481 all delete from or change resolver_compiler.py templates, so they should be serialised rather than run in parallel.

docs/migration/to-4.x.md does not exist yet and needs an mkdocs.yml nav entry alongside to-3.x.md. docs/migration/to-3.x.md keeps describing the removed symbols, since it documents the 2.x to 3.x hop.