ADR 0010: Module boundaries and the facade re-export contract¶

Dependency direction¶

Dependencies flow one way, from the leaves toward the facade:

records / _types / _text   (dependency-free domain vocabulary + presentation)
        |
readers                     (read-only file, sqlite, protobuf, subprocess I/O floor)
        |
adapters / discovery        (per-agent parsers + normalization; store discovery)
        |
_engine                     (planning, execution, orchestration, matching)
        |
cli / ui / mcp / query      (frontends; depend down only)
        |
__init__.py                 (thin re-export shim + main())

No module under records, readers, adapters, discovery, _engine, query, cli, or ui may import the agentgrep facade (a bare import agentgrep or a facade-level from agentgrep import X). Modules import their dependencies directly from the owning module (from agentgrep.records import SearchRecord). Importing a sibling submodule (for example the typed agentgrep.events stream, or from agentgrep._engine.planning import ...) is permitted, because it names a concrete lower module rather than the facade’s re-export namespace.

A guard test (test_engine_does_not_import_facade and siblings) enforces the rule by scanning each package for a bare import agentgrep. Removing the residual facade imports from the satellite packages and landing that guard is the final step of the migration; everything below it is already in place.

The facade is a re-export shim¶

__init__.py re-exports the public names from the owning modules so import agentgrep; agentgrep.SearchRecord stays byte-stable, and keeps only the process entry points (main), the TUI launchers (run_ui, build_streaming_ui_app), the pydantic-adapter bridge (maybe_use_pydantic), and the interpreter setup. It contains no parsing, discovery, matching, or orchestration logic. Re-exports that pull from a satellite package whose __init__ imports the facade entry point stay in the trailing # noqa: E402 block so they resolve after main is defined.

Module docstrings state the single responsibility¶

Every module’s docstring opens by naming its one responsibility and the layers it must not import (for example, records.py is dependency-free; progress.py sits below the engine that drives it and the frontends that render it). The docstring is the human-readable half of the boundary; the guard test is the enforced half.

The public surface is __all__¶

The facade declares an explicit __all__; its union with the trailing compatibility re-exports is the public surface ADR 0006 governs. New modules declare __all__ as they are created. Sealing the facade __all__ is treated as a deliberate compatibility step rather than a refactor freebie, because adding __all__ to a module that lacked one narrows from agentgrep import *.

Optional-dependency import rules¶

pydantic, textual, fastmcp, and the orjson/rapidfuzz accelerators stay behind t.TYPE_CHECKING or lazy, call-site imports. The pydantic-free CLI JSON fallback is mandatory (see test_json_output_falls_back_without_pydantic). The agentgrep --help cold-start budget is preserved by keeping the query registry, the events module, and the per-agent parsers off the eager import agentgrep path; tests/test_import_time.py pins it.

No native rewrite is implied¶

This is a pure-Python module-boundary decision. ADR 0002 and ADR 0003 still hold: pure Python is the semantic source of truth, and any Rust accelerator or native engine must be justified by measurement. The boundary in fact helps a future accelerator drop in behind records/readers without the facade noticing.

Positive¶

• The dependency graph has one direction; the engine owns its logic where ADR 0004 places it.

• The facade becomes a readable, reviewable public-surface contract instead of an 8,000-line grab bag.

• A Rust accelerator can replace a leaf module without touching callers.

• Strict ty checks gain a real public/private boundary.

Tradeoffs¶

• Re-exports must be maintained so old import paths stay byte-stable; identity tests (agentgrep.X is agentgrep.<module>.X) prove each move neutral.

• Tests that monkeypatch an engine helper must patch it where the caller resolves it (its owning module) rather than on the facade.

Risks¶

• The boundary can erode if a helper is dropped into __init__.py “just for now.” The guard test is the mitigation.