[abrichr]

From: Grok.

Part of the import-boundary workstream (tracked in the maintainers' tracker).

Summary

openadapt_flow had no enforced layering. This adds a small pytest check and a contract file, with no new dependency:

• packages/flow/import_layers.json names the core modules (runtime, verifier, verify, verify_run, verification, ensure_record, readback_ladder, ir, backend, receipt, write_receipt, fault_gate, record_sor, provenance) and four forbidden groups: app-specific (mockmed, mockloan, demo_driver, demo_proof, tutorial), benchmark (benchmark, openadapt_flow.bench), desktop-UI (adapters, console.app, console.server, desktop_record, interactive_recorder), and lab and harness (rl_env, teach_authorization_fixture).
• packages/flow/tests/test_import_layers.py reads every module's imports from source (nothing is imported to run it). Lazy imports inside functions count. Importing a.b.c counts as importing a and a.b too, and a name a package __getattr__ re-exports lazily counts as an import of the module it comes from, at the place a caller asks for it.
• Core may not import a forbidden module directly. There are no exceptions to that, and none are needed today.
• Core may not reach a forbidden module through any chain of imports either. An edge that can't be removed yet must be listed in the contract's exceptions with a reason and an issue. An exception that no longer exists fails the test, so the list can only shrink. Every module the contract names must exist, so a rename can't quietly empty a rule.

The new test is one more file under packages/flow/tests, so the required flow core unit shards pick it up (shard 1 of 3 on a pull request). It complements scripts/check_engine_generality.py and test_runtime_never_imports_benchmark.py.

The earlier attempt, #1535, was a move-only extraction that went stale while the replayer kept growing. This PR moves no code, so it can't go stale that way, and it changes no behavior.

The one exception left

qualification_oracle_gate -> mockmed.fault_server. The qualification oracle gate runs its break-it fault against the bundled MockMed fault server, which is its only fixture. Core reaches the gate through receipt > repair.standard_change > repair.self_repair > agent.repair > agent.authoring > agent.bridge > agent.admission > admit_pipeline > qualification_proposal. Removing the edge means passing the fault fixture in from the caller, which changes the gate and its callers, so it belongs in its own change. The contract links it to #1876, and the test now requires every exception to link a public issue.

Classification choices a reviewer should check

• reward is not in the lab group. compiler.probing and undo_proposal use its oracles and bundle loader on product paths (deployment probes and undo), not only in training.
• qualification_dev_signer is not in the lab group. Its refusal helpers (reject_local_dev_in_production_trust and friends) are what keep the local-dev key out of production trust, and qualification_admission needs them.
• console as a whole is not forbidden, only the web app and server. agent.attended reads the attention queue helpers in console.attention, which import neither.
• recorder and visualize are not desktop-UI: the recorder wraps a Backend, and visualize renders a program graph to HTML or Mermaid.

Testing

• pytest -n 4 tests/test_import_layers.py tests/test_runtime_never_imports_benchmark.py: 10 passed.
• Control on the real package: a lazy from openadapt_flow.console.server import serve planted inside a function in verify_run.py failed both the direct and the transitive test, naming the edge and line. The file was restored afterwards.
• Control on the exceptions list: with exceptions emptied, the transitive check reports the MockMed path above.
• Three checker tests run against a planted package: a lazy chain into forbidden code, a direct import, and a lazy __getattr__ re-export, along with a clean sibling import from the same package.
• ruff check, ruff format --check, and scripts/check_engine_generality.py pass.

Not tested: the full flow suite (the PR adds two files and changes no code), and a CI run, which is pending.

[abrichr]

From: Grok

5d3116b links the one exception (qualification_oracle_gate -> mockmed.fault_server) to #1876. test_import_layers.py now requires every exception's issue to be an OpenAdapt issue URL, not just any non-empty text. Control: with the old TODO text, the new check fails (1 failed, 6 passed). With the link, it's 7 passed, and ruff is clean. The branch merges cleanly with main c21ba89. Marked ready.

[abrichr]

Independent adversarial review: APPROVE

Reviewed head 5d3116bd5c61d91c03f5a3d8a709e498ccfe543a, in detached worktrees at the head and the parent c21ba89c4. I first reviewed 248ef7808, where the exception's issue was a TODO. 5d3116bd5 fixes that.

What I ran

• pytest tests/test_import_layers.py tests/test_runtime_never_imports_benchmark.py: 10 passed.
• With the exception's issue set back to "TODO", test_every_exception_is_documented_and_still_needed now fails. The test requires a github.com/OpenAdaptAI/OpenAdapt/issues/N link, and the contract links Core reaches the mockmed break-it fixture through qualification_oracle_gate #1876.
• The test and contract on the parent tree: 7 passed. That is expected, because the PR moves no code.
• Classification: core reaches 341 modules in 117 top-level packages. I checked the borderline ones (judgment_cases, qualification_faults, qualification_drills, learning, qualification_web_session, reward, qualification_dev_signer, console.attention). All are on product paths. I found nothing app-specific, benchmark, UI or lab that core reaches outside the forbidden groups. The test refuses a contract that names a nonexistent module, so a rename can't silently empty a rule.

Probes (mine)

Each probe plants a core module that reaches a forbidden module in one of the ways below and checks whether the checker catches it.

Import form	Result
from planted.demo import app (control)	caught
importlib.import_module('planted.demo.app')	missed
__import__('planted.demo.app')	missed
package __getattr__ that uses an import x.y statement	missed
package __getattr__ that uses a _LAZY_EXPORTS map with import_module (the pattern runtime/__init__.py uses)	missed

On the real package, appending importlib.import_module("openadapt_flow.console.server") inside a function in verify_run.py left the suite green.

Non-blocking

Today nothing escapes through these gaps: all of runtime's lazy exports point at core modules, which are checked as roots anyway. But the docstring says lazy re-exports count, and a string-literal import_module is the obvious way around the rule. Suggested follow-up hardening:

• treat import_module and __import__ calls with a constant string argument as edges;
• harvest ast.Import nodes, and constant string values of _LAZY_EXPORTS-style dicts, inside __getattr__;
• optionally, refuse non-literal dynamic imports in core unless they are allow-listed.

Other checks

The PR changes no runtime code. I found no secrets or customer names, and no test was weakened.

[abrichr]

Independent adversarial review: BLOCK

Reviewed head e7c7aca1bc8e225600470e5fbe15aa8556d66ec5, literal parent 573a5fdc5b50c94abc6c0d1923113a90b4836ffb, and main merge base 800f450047c3195bb28a5e6b6b8f862a5e21a16f in clean detached worktrees, with tests on Linux.

• P2 — ordinary dynamic and lazy imports escape the new guard. packages/flow/tests/test_import_layers.py:99 handles only Import/ImportFrom nodes. _lazy_exports at :52 also handles only ImportFrom, ignores aliases, and the traversal skips the whole __getattr__ body at :92. Literal import_module, its aliases, __import__, aliased lazy re-exports, lazy import statements, export maps and star exports went undetected. In temporary copies of the actual package, adding importlib.import_module("openadapt_flow.console.server") to verify_run or redirecting runtime's established Replayer lazy-map entry to that module left both violation lists empty. Handle these static forms, with clean lookalike controls, before claiming lazy import chains are enforced.
• P2 — empty policy sections disable the checks successfully. The loader at test_import_layers.py:195 parses JSON without validating a nonempty policy. test_contract_names_real_modules at :230 only checks prefixes that remain. {"core": [], "forbidden": {}, "exceptions": []} passes all four policy checks, as do separate empty-core, empty-forbidden and empty-group-list cases. Require the policy's necessary sections and nonempty module sets. Missing files, malformed JSON, missing keys and invalid types already refused in the controls.
• P2 — an allowed edge hides additional forbidden dependencies. reached_edges at test_import_layers.py:176 never visits a forbidden target. In the source graph core -> helper -> demo.app -> ui.window, documenting only helper -> demo.app as an exception makes every check pass; the additional UI edge is never reported. Continue traversal through the permitted edge so an exception admits only the documented edge. The stale-exception, bad-issue, direct-core-exception and rebuild-invalidation controls all refused correctly.

The advertised 10 tests passed at head and literal parent. An explicit external overlay of the exact head checker and contract also passed all 10 against main's source; main itself has neither file. The frozen 41-probe matrix gave 18 failed / 23 passed, with zero errors or skips, on each comparison. These are three groups of checker gaps, not 18 distinct runtime bugs. Ruff, format, release consistency and generality passed at the head; its CI and source-boundary job are green.

The probes parse synthetic source and temporary copies; they never import a planted module. I did not establish a current forbidden production import, execute these planted dependencies, or run the full Flow suite or builds. The main overlay measures the introduced checker's coverage of baseline source and is not a claim that main ships the guard. No reviewed source changed or was pushed.

[abrichr]

All three findings are addressed in the stacked #1924, which targets this branch. Literal dynamic imports and lazy re-exports, tables and statements are read (05c8bdf). An incomplete policy is refused, and the walk continues past an excepted edge, so an exception admits only that edge (3a08641). That surfaced two MockMed-internal edges behind the existing #1876 exception, now documented under the same issue. Each change has controls that fail without it. Re-review welcome on #1924.

[abrichr]

Closing as superseded by #1955. It adds the same three files (import_layers.json, test_import_layers.py, the public-artifacts.json entry) with exceptions: [], because main no longer needs the mockmed.fault_server exception this PR carries. Review and fixes continue on #1955.