modern-python
diff --git a/‎architecture/containers.md‎
Lines changed: 9 additions & 2 deletions b/‎architecture/containers.md‎
Lines changed: 9 additions & 2 deletions
diff --git a/‎architecture/providers.md‎
Lines changed: 5 additions & 2 deletions b/‎architecture/providers.md‎
Lines changed: 5 additions & 2 deletions
diff --git a/‎architecture/validation.md‎
Lines changed: 85 additions & 55 deletions b/‎architecture/validation.md‎
Lines changed: 85 additions & 55 deletions
diff --git a/‎docs/providers/advanced-api.md‎
Lines changed: 5 additions & 4 deletions b/‎docs/providers/advanced-api.md‎
Lines changed: 5 additions & 4 deletions
@@ -84,10 +84,17 @@ dispatch) are the blessed integration seam — see
 `add_providers` is **root-only**: called on a child, it raises
 `ChildContainerRegistrationError` (`modern_di/exceptions.py`), since the
 registry it mutates is shared tree-wide. `Container` tracks a private
-`_validated` flag, set once `validate()` succeeds (construction or a manual
-call); `add_providers` on an already-validated container re-runs `validate()`
+`_validated` flag, set once `validate()` succeeds on **this** container
+(construction or a manual call); it is the per-container gate for
+`add_providers`, which on an already-validated container re-runs `validate()`
 after registering and, if that fails, removes the just-added batch again —
 the container ends up either fully registered and valid, or unchanged.
+Whether the graph is *currently* validation-clean is tracked separately and
+registry-level, by `ProvidersRegistry.validated_version` (see
+[validation.md](validation.md#what-validate-checks)). Because that registry is
+shared tree-wide, validating any container in the tree marks the whole graph
+clean, so a child's `resolve` benefits from the root's validation — its runtime
+cycle guard short-circuits — without the child ever calling `validate()` itself.
 `resolve_dependency` carries no such restriction; it is a resolve verb,
 callable on any container regardless of validation state.
 
 
@@ -153,8 +153,11 @@ providers.Alias(ConcreteDatabase, bound_type=DatabaseProtocol)
 accepts an optional `bound_type` override. See [docs/providers/alias.md](../docs/providers/alias.md) for the
 user-facing rationale and caching implications.
 
-`Alias.effective_scope` follows alias chains transitively to the terminal non-alias provider and returns that
-provider's scope. This is what `Container.validate()` and scope-error reporting use — the alias's own `scope`
+`Alias` overrides the `redirect_target(container)` node hook to return its source provider (`None` when the
+source type is unregistered), marking the alias as a transparent redirect. `DependencyGraph.terminal_scope`
+follows that hook down an alias chain to the terminal non-alias provider and returns that provider's scope —
+which is what `Container.validate()` and scope-error reporting compare against (see
+[validation.md](validation.md#terminal-scope-and-alias-transparency)). The alias's own `scope`
 attribute is only a stored default.
 
 ### Deprecated `scope=` parameter
 
@@ -32,90 +32,120 @@ containers never emit this warning regardless of `validate` — see
 
 ## What validate() checks
 
-`validate()` performs a depth-first search (DFS) over every provider in `providers_registry` (the walk itself is
-`Container.validate()` in `modern_di/container.py`). It collects **all errors** across the entire walk before
-raising, so a single call surfaces all wiring bugs at once rather than stopping at the first one. `validate()`
-raises `exceptions.ValidationFailedError` if any are found; its `.errors` attribute lists every collected
-exception, and its `__str__` groups them by class name so a report mixing several error kinds reads as one
-section per kind — see `ValidationFailedError.__str__` in `modern_di/exceptions.py`. Validation runs entirely
-against `providers_registry`, so a root APP-scope container validates deeper-scoped providers without building
+`validate()` is a **fold** over one depth-first walk of the provider graph:
+`DependencyGraph().walk(providers_registry, self)` (in `modern_di/dependency_graph.py`) runs a single
+iterative, explicit-stack traversal and yields an event stream — `NodeEntered`, `Edge`, `Cycle`,
+`DependenciesError` — while `validate()` applies one policy per event kind (`NodeEntered` →
+`iter_validation_issues`; `Edge` → the scope-ordering check; `Cycle` → `CircularDependencyError`;
+`DependenciesError` → collect the raised exception). The walk emits *structure*; `validate()` supplies
+*policy*. That same walker also backs the runtime cycle guard (see the blockquote below), so the two
+share one traversal — a stance reversed, on the extraction axis only, from the "deliberate duplication"
+defense this file once carried; the reasoning is recorded in
+[decisions/2026-07-12-unify-graph-traversal.md](../planning/decisions/2026-07-12-unify-graph-traversal.md).
+
+It collects **all errors** across the entire walk before raising, so a single call surfaces all wiring
+bugs at once rather than stopping at the first one. `validate()` raises `exceptions.ValidationFailedError`
+if any are found; its `.errors` attribute lists every collected exception, and its `__str__` groups them
+by class name so a report mixing several error kinds reads as one section per kind — see
+`ValidationFailedError.__str__` in `modern_di/exceptions.py`. Validation runs entirely against
+`providers_registry`, so a root APP-scope container validates deeper-scoped providers without building
 child containers.
 
+**Validated-version short-circuit.** `ProvidersRegistry` carries a `validated_version: int | None`. On a
+successful walk `validate()` stamps `validated_version = version`; a later `validate()` whose
+`validated_version == version` returns immediately without re-walking, so a repeat `validate()` is free.
+Every registry mutation (`register` / `add_providers` / `_remove_providers`) bumps `version` and resets
+`validated_version = None`, so any change to the graph re-arms both `validate()` and the runtime guard.
+The stamp lives on the registry, which is shared tree-wide, so validating any one container marks the
+graph clean for every container in the tree.
+
 ### Circular dependencies
 
-During the DFS, a provider encountered a second time while it is still on the active path (i.e., it appears in
-`visiting`) means a cycle exists. `validate()` records a `CircularDependencyError` with a `.cycle_path` list of
-type names showing the loop (e.g., `["A", "B", "A"]`). The recursive walk does **not** continue into the cycle,
-but the rest of the graph continues to be checked. `CircularDependencyError.__str__` renders `.cycle_path` as a
-multi-line arrow chain, not an inline `A -> B -> A` string — see `CircularDependencyError` in `exceptions.py`.
+When the walk follows an edge to a provider still on the active path (tracked in the walk's internal
+`visiting` set), it emits a `Cycle` event whose `providers` list closes the loop by repeating the first
+node last (e.g., `[A, B, A]`). `validate()` maps that event to a `CircularDependencyError` (built via
+`dependency_graph.build_cycle_error`) whose `.cycle_path` is the list of type names showing the loop
+(e.g., `["A", "B", "A"]`). The walk does **not** descend into the cycle, but the rest of the graph
+continues to be checked. `CircularDependencyError.__str__` renders `.cycle_path` as a multi-line arrow
+chain, not an inline `A -> B -> A` string — see `CircularDependencyError` in `exceptions.py`.
 
 Each node in that chain may also carry an optional definition site — the creator's declaration
 point — rendered as a trailing `module:line` anchor alongside the provider name, using the same
 lazy, memoized, best-effort capture described for breadcrumb steps in
 [resolution.md](resolution.md#breadcrumb-definition-sites). The public `.cycle_path` stays the bare
-list of type names; the parallel locations live on a separate `.cycle_locations` attribute, kept in
-sync at both construction sites (the DFS above and the runtime `RecursionError` conversion below).
+list of type names; the parallel locations live on a separate `.cycle_locations` attribute. Both
+`validate()` and the runtime guard build the error through the one `dependency_graph.build_cycle_error`
+helper, so the two attributes stay in sync by construction rather than by parallel edit.
 
 > **Runtime resolution has a cycle guard too — but `validate()` remains the way to see all errors up front.**
-> `Container.resolve_provider` wraps the final `provider.resolve(self)` in `try/except RecursionError`. When an
-> unvalidated circular graph's first resolve overflows the stack, the handler iteratively re-walks the static
-> graph from the failing provider (an explicit-stack DFS — the walk must stay flat, since it runs close to the
-> recursion limit) and, if a static cycle is reachable, raises `CircularDependencyError` with the cycle path,
-> `from` the original `RecursionError`. `resolve_provider` is re-entrant (`Factory`/`Alias` call it per dependency
-> edge), so it is the innermost frame that converts; outer frames see a `ResolutionError` and the existing
-> breadcrumb machinery (see [resolution.md](resolution.md)) prepends steps as it propagates back up, so the
-> converted error arrives with the dependency chain attached. A `RecursionError` from a creator that recurses on
-> its own (no static cycle in the graph) is re-raised untouched, not misreported as a circular dependency. This is
-> a deliberate duplication of cycle detection, not a refactor of the one DFS above into two callers: `validate()`
-> collects *all* errors of *all* kinds in one walk, while the runtime guard only answers "is a cycle reachable
-> from here" on an exhausted stack — unifying them would couple the resolve hot path to the all-errors walker for
-> no user benefit. Run with `validate=True` (or call `container.validate()`) in development to surface *every*
-> cycle (and other wiring bugs) before the first resolve, rather than only the one a particular resolve happens
-> to hit.
+> `Container.resolve_provider` wraps the final `provider.resolve(self)` in `try/except RecursionError`. The
+> handler first short-circuits: if the registry is already validated (`validated_version == version`), the static
+> graph is known acyclic, so the overflow is genuine self-recursion and the `RecursionError` re-raises untouched
+> without any walk. Otherwise, when an unvalidated circular graph's first resolve overflows the stack, the handler
+> re-walks the static graph from the failing provider via `DependencyGraph().find_cycle_from` — the same
+> iterative, explicit-stack `walk` that `validate()` uses (it must stay flat, since it runs close to the recursion
+> limit) — and, if a static cycle is reachable, raises `CircularDependencyError` (built by
+> `dependency_graph.build_cycle_error`) with the cycle path, `from` the original `RecursionError`.
+> `resolve_provider` is re-entrant (`Factory`/`Alias` call it per dependency edge), so it is the innermost frame
+> that converts; outer frames see a `ResolutionError` and the existing breadcrumb machinery (see
+> [resolution.md](resolution.md)) prepends steps as it propagates back up, so the converted error arrives with the
+> dependency chain attached. A `RecursionError` from a creator that recurses on its own (no static cycle in the
+> graph) is re-raised untouched, not misreported as a circular dependency. Both the guard and `validate()` consume
+> the one `DependencyGraph` walker: `validate()` collects *all* errors of *all* kinds up front, while the guard
+> only answers "is a cycle reachable from here" on an already-exhausted stack. Run with `validate=True` (or call
+> `container.validate()`) in development to surface *every* cycle (and other wiring bugs) before the first resolve,
+> rather than only the one a particular resolve happens to hit.
 
 ### Inverted scope dependencies
 
-For every dependency edge `provider → dep`, `validate()` compares their **effective scopes** (see below). If
-`dep`'s effective scope is strictly deeper than `provider`'s effective scope, the dependency is inverted: a
-shallower-lived provider cannot hold a reference to a deeper-lived one. The error is recorded as
-`InvalidScopeDependencyError` (see `exceptions.py` for the exact message), which names the provider, the
-parameter, the dependent provider, and the offending scopes. The walk continues into the dependency so further
-issues in that subtree are also surfaced.
+For every dependency edge `provider → dep` (the walk's `Edge` event), `validate()` compares their
+**terminal scopes** (see below). If `dep`'s terminal scope is strictly deeper than `provider`'s terminal
+scope, the dependency is inverted: a shallower-lived provider cannot hold a reference to a deeper-lived
+one. The error is recorded as `InvalidScopeDependencyError` (see `exceptions.py` for the exact message),
+which names the provider, the parameter, the dependent provider, and the offending scopes. The walk
+continues into the dependency so further issues in that subtree are also surfaced.
 
 ### Missing required dependencies
 
-Before recursing into a provider's dependencies, `validate()` calls `provider.iter_validation_issues(container)`
-and appends any returned exceptions to the error list. `Factory` implements this hook to yield
-`ArgumentResolutionError` for each constructor parameter that has no matching provider in `providers_registry`,
-no default value, and no static `kwargs` entry.
+When the walk enters a provider (the `NodeEntered` event, emitted before that provider's dependencies are
+read), `validate()` calls `provider.iter_validation_issues(container)` and appends any returned exceptions
+to the error list. `Factory` implements this hook to yield `ArgumentResolutionError` for each constructor
+parameter that has no matching provider in `providers_registry`, no default value, and no static `kwargs`
+entry.
 
-## Effective scope and alias transparency
+## Terminal scope and alias transparency
 
-`validate()`'s scope-ordering check uses `provider.effective_scope(container)` on both sides of every dependency
-edge — not `provider.scope` directly.
+`validate()`'s scope-ordering check uses `DependencyGraph.terminal_scope(provider, container)` on both
+sides of every dependency edge — not `provider.scope` directly.
 
-For most providers, `effective_scope` simply returns `self.scope`. `Alias` overrides it to follow the alias chain
-to its terminal non-alias target and return **that provider's scope**. This makes validation transitive through
-aliases. Consider:
+`terminal_scope` follows the `AbstractProvider.redirect_target(container)` node hook from provider to
+provider until it reaches one whose resolution terminates there (`redirect_target` returns `None`), then
+returns that terminal provider's `.scope`. The hook defaults to `None` on `AbstractProvider`, so for most
+providers `terminal_scope` returns `self.scope` in a single step. `Alias` overrides `redirect_target` to
+return its source provider (and `None` when the source type is unregistered), so `terminal_scope` follows
+an alias chain to its terminal non-alias target and reports **that provider's scope**. This makes
+validation transitive through aliases. Consider:
 
 ```
 Factory(scope=APP, creator=Caller)   # depends on IFace
 Alias(source_type=Impl, bound_type=IFace)  # no scope parameter
 Factory(scope=REQUEST, creator=Impl)
 ```
 
-The alias's effective scope is `REQUEST` (the scope of `Impl`). When `validate()` checks the `Caller → IFace`
-edge, it compares `APP` against `REQUEST` and raises `InvalidScopeDependencyError`. Without `effective_scope`,
-the alias's internal `scope` attribute (defaulting to `APP`) would mask the true depth of the dependency.
+The alias's terminal scope is `REQUEST` (the scope of `Impl`). When `validate()` checks the `Caller → IFace`
+edge, it compares `APP` against `REQUEST` and raises `InvalidScopeDependencyError`. Without `terminal_scope`,
+the alias's own `scope` attribute (defaulting to `APP`) would mask the true depth of the dependency.
 
-Two edge cases in `Alias.effective_scope` are handled safely:
+Two edge cases in `terminal_scope` are handled safely:
 
-- **Alias cycle**: if the same alias is encountered twice during the chain walk, the method falls back to
-  `self.scope` and returns immediately. The cycle itself is separately detected and reported by the DFS cycle
-  check.
-- **Dangling source**: if the alias's source type is not registered, the method falls back to `self.scope`. The
-  dangling source is separately detected and reported by `iter_validation_issues` or by the dependency lookup
-  raising `AliasSourceNotRegisteredError` during the walk.
+- **Redirect cycle**: if the chain revisits a provider (tracked in `terminal_scope`'s `seen` set), it
+  breaks out and falls back to the starting provider's own `.scope` instead of looping forever. The cycle
+  itself is separately detected and reported as a `Cycle` event by the walk, which traverses the same
+  `source` edge.
+- **Dangling source**: if an alias's source type is not registered, `redirect_target` returns `None`, so
+  `terminal_scope` stops at the alias and falls back to its `.scope`. The dangling source is separately
+  reported by the alias's dependency lookup raising `AliasSourceNotRegisteredError` during the walk
+  (a `ResolutionError`, surfaced as a `DependenciesError` event).
 
 ## Exception types
 
 
@@ -21,10 +21,11 @@ To implement a custom provider, subclass `AbstractProvider` and implement:
   traversal.
 - **`iter_validation_issues(container)`** *(optional)* — yields `Exception` instances for
   validation-time problems found in this provider; default yields nothing.
-- **`effective_scope(container)`** *(optional override)* — override this method to report the
-  scope of whatever the provider ultimately resolves to. A transparent or redirect provider (like
-  `Alias`) should override it to follow the source chain so that `Container.validate()` checks
-  callers against the real target scope rather than any nominal scope on the wrapper itself.
+- **`redirect_target(container)`** *(optional override)* — return the provider this one
+  transparently forwards to, or `None` (the default) when resolution terminates here. A transparent
+  or redirect provider (like `Alias`) overrides it to point at its source, so that `Container.validate()`
+  follows the redirect to the real target and checks callers against that target's scope rather than any
+  nominal scope on the wrapper itself.
 
 ### `CacheSettings.is_async_finalizer`