Layer Dependency Contract

The six import-linter contracts in pyproject.toml, drawn. Arrows are permitted imports; pyproject.toml is the source of truth.

Layer Dependency Contract The six import-linter contracts in pyproject.toml, drawn. Arrows are permitted imports; pyproject.toml is the source of truth. _cli · commands, scaffold · Architecture component _cli commands, scaffold Public surface · app job plugin types testing workflow · Architecture component Public surface app job plugin types testing workflow _app · composition root · Architecture component _app composition root _discovery · job finding · Peer layers — may not import each other _discovery job finding _config · resolution · Peer layers — may not import each other _config resolution _engine · lifecycle · Peer layers — may not import each other _engine lifecycle _plugins · loading · Peer layers — may not import each other _plugins loading _gate · resolver, strategy · Peer layers — may not import each other _gate resolver, strategy _events · EventBus, hooks · Foundation _events EventBus, hooks _primitives · DI, middleware · Foundation _primitives DI, middleware _types · stdlib only · Foundation _types stdlib only public API only Peer layers — may not import each other Foundation Legend Frontend Backend Database Cloud Message bus External

The six contracts

  • • Peer layers are independent — _discovery, _config, _engine, _plugins, _gate
  • • Events depends on foundation only — _events reaches _types and _primitives
  • • Primitives import nothing internal — _primitives reaches _types only
  • • Types import nothing internal — _types reaches stdlib only
  • • Internal never imports public — no _pkg may import the six public packages
  • • _cli uses public API only — _cli may import no _pkg

Known blind spot

  • • exclude_type_checking_imports=true hides all TYPE_CHECKING imports
  • • _config/chain.py and sources.py import EventBus that way
  • • So _config -> _events is invisible to every contract above
  • • Flipping the flag is unmeasured; treat this direction as ungoverned