Fix audit findings: bugs B-1..B-11, X-1, dead code, pinning tests, doc drift

[lesnik512]

Summary

Fixes selected findings from the 2026-06-12 code & docs audit (planning/audits/2026-06-12-code-docs-audit-report.md). 24 commits; 179 tests, 100% line coverage, lint/ty clean.

Bugs (B-1…B-11)

• B-1/B-3 — parameterized-generic and positional-only creator params now raise a clear UnsupportedCreatorParameterError at declaration (B-1 allows a kwargs/default escape hatch) instead of silently degrading to the origin type or dying with a raw TypeError at resolve.
• B-2 — get_type_hints TypeError (e.g. functools.partial creators) is caught and warn-skipped with a workaround hint, like the existing NameError path.
• B-4 — honest ArgumentResolutionError for unannotated params ("has no usable type annotation") and union params (names both members) instead of "of type None".
• B-5 — validate() aggregates a dangling-Alias error into ValidationFailedError instead of aborting the whole validation.
• B-6 — the public Container(parent_container=…) constructor enforces the same scope-ordering check as build_child_container.
• B-7 — cached instances are finalized in reverse creation order (true LIFO teardown), matching the docs. Closes drift D-1.
• B-8 — a sync finalizer that returns an awaitable is now awaited in close_async (and rejected in close_sync), instead of leaking an un-awaited coroutine.
• B-9 — set_context invalidates compiled kwargs so a later resolve picks up the new value.
• B-10 — group registration is atomic: a failed registration leaves the shared registry untouched.
• B-11 — ProvidersRegistry locks its mutations and iterates snapshots (no "dictionary changed size during iteration" under concurrent registration).

DX (X-1) — resolving from / building a child of a closed container raises ContainerClosedError. Re-entering the context manager (with container:) reopens it; clear_cache=False instances persist across the close→reopen cycle (same object returned), clear_cache=True rebuild. The closed-guard also covers resolution of a parent-scoped provider through an open child.

Internals — removed dead code: unused TypeVars, _UNSET sentinel, a no-op get_origin pass (Q-2, Q-3, Q-4).

Tests (Q-10…Q-15) — pinned previously-untested contracts: static-kwargs precedence, creator-failure (nothing cached / retry / LIFO finalize), context scope-selection, alias chains, child→APP-cache identity, duplicate-type-across-groups.

Docs (D-3, D-6…D-14) — fixed the crashing intro example, wrong scope rendering, the broken alias override walkthrough, three troubleshooting pages that quoted error messages the library never raises, false typing claims, the clear_cache=False migration guidance, and a websocket example that didn't parse; rewrote the context "set before building the child" advice to the correct scope rule (context never propagates between containers); documented the open/close/reopen lifecycle.

Design rulings recorded during the work

• B-1 → declaration-time error for parameterized generics, with a kwargs/default escape hatch.
• D-6 → context never propagates parent→child by design (docs + docstring only, no code change).
• clear_cache=False → precisely defined as persist-across-reopen (same instance returned after re-entering the context manager).

Deferred (not in this round)

Q-1, Q-5…Q-9, X-2…X-6, D-2, D-4, D-5, G-1…G-11.

Test Plan

• just lint-ci — clean (ruff format/check, ty)
• just test — 179 passed, 100% line coverage
• uv run pytest benchmarks/ --benchmark-disable — 22 passed
• Every fixed doc example executed against the current library
• Each commit individually reviewed (spec + adversarial quality); full branch reviewed holistically

🤖 Generated with Claude Code