Skip to content

Circular import: four consolidation submodules cannot be imported first (headless_authoring hub) #237

Description

@cdeust

Reproduction

Each of these fails in a fresh interpreter (verified on main, 3a1ba1e, 2026-07-28):

$ python -c "import mcp_server.handlers.consolidation.candidate_scan"
ImportError: cannot import name '_collect_anchor_candidates' from partially
initialized module ... (most likely due to a circular import)

Same failure shape for claude_cli (_build_argv), cycle_orchestration
(run_headless_authoring_cycle), and drain_operations
(drain_all_gaps_on_page).

Cause

The four submodules each do from . import headless_authoring as _root at
module top while headless_authoring imports names back from them — the
same load-order-sensitive hub cycle as #233's synaptic pair, one package
over. Importing headless_authoring first resolves it, which is why the
suite stays green; any consumer (REPL, script, future module) that imports
a submodule directly fails. tests_py/handlers/test_s110_sweep_handlers.py
already has to import headless_authoring first with a comment noting the
load-order sensitivity.

Surfaced by the #197 family-4 (PLC0415) sweep's per-module import
verification, which imports every mcp_server module in a fresh
interpreter. The sweep touched these files (hoisting unrelated lazy
imports) but deliberately did not restructure the hub cycle
(behavior-preserving mandate; a seam-creating refactor is its own PR per
coding-standards §15.1). The sweep's baseline check proves these four
failures are pre-existing on main, byte-for-byte identical before and
after the hoist.

Acceptance criteria

  1. python -c "import mcp_server.handlers.consolidation.<m>" succeeds in
    a fresh interpreter for all four modules (regression test iterating them
    in subprocesses, as Circular import: synaptic_plasticity_hebbian cannot be imported first #233 criterion 1).
  2. The _root back-reference is replaced by a leaf module (or explicit
    parameter passing) so no submodule imports the hub at load time.
  3. Existing suite passes unchanged.
  4. The load-order comment/workaround in
    tests_py/handlers/test_s110_sweep_handlers.py becomes unnecessary and
    is removed.

Refs #233 (same defect class), #197 (surfaced by family 4).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions