fix: validate() traverses providers supplied via kwargs=

[lesnik512]

Closes a hole where validate() reported a clean graph that then failed at resolve time.

WiringPlan built a third dict, dependencies, alongside the buckets the runtime resolves from. The declaration-time kwargs={...} overlay wrote to provider_kwargs but not to dependencies — so a provider supplied that way was a real runtime edge that validation could not see.

Both consequences reproduced against fe090f4:

G.b = Factory(scope=Scope.APP, creator=B, kwargs={"a": G.a})
G.a = Factory(scope=Scope.APP, creator=A, kwargs={"b": G.b})

c.validate()   # PASSES -- reports no cycle
c.resolve(A)   # RecursionError: maximum recursion depth exceeded

A bare RecursionError is the exact failure CircularDependencyError exists to prevent, and the runtime cycle guard could not save it: find_cycle_from walks the same blind edge set. A scope inversion routed through kwargs= behaved the same way, passing validate() and dying at resolve with ScopeNotInitializedError.

What changed

Delete the dependencies field. WiringPlan.edges is now derived from provider_kwargs + context_kwargs — the same buckets resolve() reads. validate() traverses exactly what resolve() follows, so the two graphs cannot drift apart again; the fix falls out of the derivation rather than being a second write someone has to remember to make.

What differs between the two ways of declaring a dependency is how the edge is declared, never whether it exists.

The runtime keeps its partition — provider_kwargs and context_kwargs take different resolution paths, and context resolution needs the SignatureItem carried alongside. The partition was load-bearing; the third dict was not.

Design and rejected alternatives: planning/changes/2026-07-14.06-unify-wiring-edge-set.md.

Upgrade note

Ships as a bug fix in a 2.x minor. Any config this newly reports was already broken at runtime (verified: RecursionError / ScopeNotInitializedError), so there are no false positives — but a user with a dormant broken config they never resolve will see a green validate() go red. Worth calling out in the release notes.

Not in scope

validate() builds each Factory's plan twice (measured: 120 WiringPlan.build calls for a 60-provider chain). Every way of fixing it either makes validate() touch the cache (violating get_dependencies' documented "no cache touch" contract), adds validate-only lifecycle state to Container, breaks dependency_graph.py's no-concrete-providers layering rule, or changes AbstractProvider's interface — the last of which is a provider-seam change deserving its own design. Left in place deliberately; the derivation adds ~4.9% to a cold boot-time validate() and nothing to resolve().

Also

• dependency_graph.py's module docstring described the event order against Container.validate's recursive _visit, deleted in Unify provider-graph traversal behind a DependencyGraph module #308. A reader would hunt for a function that no longer exists.
• test_dependency_graph_parity.py -> test_dependency_graph_contract.py. It tests no parity; Unify provider-graph traversal behind a DependencyGraph module #308 left no second implementation to be at parity with, and the name advertised a synchronization hazard the code does not have.

Testing

TDD, both failing tests written first from the reproductions above.

• test_walk_emits_cycle_closed_through_kwargs_overlay — cycle through the overlay is now a Cycle event.
• test_validate_raises_on_inverted_scope_dependency_supplied_via_kwargs — scope inversion through the overlay now raises InvalidScopeDependencyError from validate().
• test_wiring_plan_dependencies_excludes_static_supplied_providers pinned the bug as intended behavior; inverted to ..._edges_include_....
• test_factory_self_reference* stay green — a type-matched self-reference must keep falling through to the creator default. (find_dep_provider excludes the owner; the kwargs overlay needs no such exclusion, since a provider cannot be passed to its own constructor.)

just test-ci: 381 passed, 100% coverage. just lint-ci: clean.

🤖 Generated with Claude Code