Dependency & Layer Review Lens
Review against code conventions
and the executable import-linter contracts in pyproject.toml.
The historical six-layer/plugin map is not the current dependency contract.
Ownership and direction
evolve -> evals -> core
evolve --------> core
core owns the runtime; evals measures it; evolve searches over runtime
evidence. Neither core -> evals/evolve nor evals -> evolve is allowed.
Within core, follow the named process/capability contracts rather than
inventing a numeric layer order.
core.wiring composes services through constructors and existing typed contexts.- Use a narrow, named Protocol at a real consumer/provider boundary. A concrete
import inside the owning subsystem is not automatically a port violation;
one implementation does not invalidate an existing isolation boundary.
- ContextVars carry request identity, diagnostics, or request-local state, not
service-locator DI. Do not hide a forbidden dependency behind a late import.
Review Checklist
1. Trace imports against the active contracts
rg -n '^(from|import) (evals|evolve)' core/ -g '*.py'
rg -n '^(from|import) evolve' evals/ -g '*.py'
uv run lint-imports
Search results are candidates: inspect guarded, dynamic, and transitive imports
and the importing caller. The gate owns the declared forbidden directions.
2. Check cycles and composition
rg -n 'from core\.memory' core/orchestration/ -g '*.py'
rg -n 'from core\.orchestration' core/memory/ -g '*.py'
rg -n 'TYPE_CHECKING|ContextVar|Protocol' core/ -g '*.py'
For each suspected cycle, trace the actual import chain and the service's
construction, binding, and teardown. A TYPE_CHECKING guard is not evidence
that runtime composition is safe, and a Protocol count is not a quality score.
3. Verify optional and cold-start imports
Keep imports at module level unless an optional dependency, a measured startup
cost, or a genuine cycle justifies deferral. Load optional SDKs at their owning
adapter boundary. A fresh-interpreter check must fail if the forbidden eager
import occurs; do not skip merely because the SDK is already imported.
4. Report ownership and the surviving contract
Name the caller, dependency owner, violated contract, smallest correction, and
the behavioral/import test that must survive. Use current source evidence;
historical architecture inventories are not automatic deletion instructions.