V3 issue #227: subsystem ownership and architecture boundaries
Issue: https://github.com/EvanProgramming/OpenKyrozen/issues/227 Base: f8eeb4bb5bd0d35f315620cf597142a9962682b2 (main) Branch: Evan/v3-227-architecture
Contract
Complete R236–R249 by documenting one package owner, existing implementation, permitted dependencies, and authority boundary for each subsystem. These are V3 contracts; subsequent linked issues implement the new engine, typed events, provider contracts and plan semantics. Do not create placeholder services or claim those later implementations are complete.
Task 1: checker regression and fix
- Add temporary-package unittest fixtures for absolute/relative interface root and descendant imports, allowed imports, concrete/external adapters, legacy imports, runtime cycles and TYPE_CHECKING exclusions.
- Demonstrate the interface-root bypass against the unchanged checker.
- Add
check(root: Path = ROOT)and use root-relative scanning/diagnostics. - Reject the exact interface namespace and descendants in the existing shared guard. Keep existing check() callers and adapter/cycle rules working.
- Run focused checker tests on Python 3.12 and 3.13 and the real package check.
Task 2: ownership contract
Extend docs/architecture.md with all fourteen requirement IDs, package owners, existing component pointers, implementation issue links and authority limits. Document composition/injection, core-to-adapter rules and the limits of static import checking. Preserve the distinction between current V2 behavior and V3 contracts, including mutable Working Plans and approved Strategic Plans.
Task 3: verification and delivery
Run focused architecture tests, make test, make check, make lint and make docs-check using the supported dependency-equipped Python 3.12 environment. Run checker fixtures with Python 3.13 as well. Capture failures and determine whether they predate this diff; blocked validation is not a pass. Obtain a fresh independent review of the whole diff and resolve material findings. Commit only scoped files with GPG signing and verify the signature. Push the issue branch, create and attach one PR with coverage/evidence and compatibility/security notes. Check CI. Stop; do not merge or start another issue.
Review focus
Absolute and relative import resolution, package init cases, default callers, fixture isolation, retained cycle/legacy/adapter checks, accurate current-versus- planned ownership, all R236–R249 covered. No paid provider calls or runtime data.
Review follow-up: PR #269
Reproduce and fix all three verified Codex findings: qualified type-checking guards, missing import-time compound bodies, and concrete named adapter re-exports. Preserve runtime else branches, deferred function bodies and allowed contract re-exports. Test aliased/chained re-exports and cycle termination without executing application modules. Run fixtures on both supported Python versions and the full browser suite/checks, obtain independent review, then push a signed follow-up commit and resolve the three original review threads with evidence. Do not merge.