Skip to content

Code health: rationalise rank-0 module sprawl and make module docs track _LAYERS #1933

Closed

Description

@pzfreo

Part of the code-health epic. Evidence pinned to main @ 71b8c94.

Problem

src went from 66 to 123 modules in a month. _LAYERS has 62 entries, and 32 of them are at rank 0. Ranks 1 to 8 hold only 2, 9, 1, 2, 1, 3, 11 and 1 entries. When a third of the modules share one rank, the DAG guard can't restrict imports among them.

About 15 of the rank-0 modules are under 200 lines, and seven are under 60:

  • score (10)
  • obligations (22)
  • intents (40)
  • feature_identity (43)
  • _warnings (51)
  • leader_policy (52)
  • location_contract and measurement_support (56 each)

There are also three recognition_*, three recogniser_* and five *_contract modules. Several look like they were split out to break an import cycle, not because they hold a separate concept.

The documentation has drifted from the code in several places:

  • model/ (17.2k lines) is rank 0 in _LAYERS but listed as a "Stage module" in the agent guide.
  • audit.py and view_plan.py (868 lines, about 17 importers) are missing from the compact map.
  • docs/architecture.md is missing view_plan, annotation_layout_profile, layout_selection and section_recess_contract.
  • Only _LAYERS is checked for completeness, so the two documents drift silently.

Proposal

  1. Fold modules under about 60 lines into their natural consumer, or group them into a contracts/ or recognition/ subpackage with an internal rank order.
  2. Re-rank the leaf band so that rank 0 means "imports nothing in the package".
  3. Make _LAYERS the only module list. Cut the compact map in the agent guide down to one line per module group. Add a test that every module is named in docs/architecture.md.

Maintainer decision and progress

The maintainer chose to fold small modules into natural consumers and group any cohesive remainder. ADR text requires sign-off on exact wording before edits.

The strict rank-0 import boundary and documentation exit criteria remain open.

Activity

  1. added
    tech-debtInternal maintainability or refactoring work
    designArchitecture or API design work
    area:architecturePackage layering and architectural structure
    on Sep 28, 2026
  2. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    Current main 4183a238 rank-0 runtime import census (using the guard's own AST resolver, excluding imports within one top-level subpackage): 17 source files have a cross-module rank-0 dependency. The edges include layout -> obligations, layout_scheme -> model/obligations/view_plan, location_contract -> measurement_support -> registry, recognition_cache -> progress, recognition_frame -> _geometry/progress, and recognition_ownership -> six leaves. Several model/ files depend on other rank-0 leaves, so model itself cannot remain rank 0 under the epic's strict “imports nothing in the package” exit rule.

    Suggested verified slices: (1) fold genuinely tiny leaves into their natural consumers where import fan-out allows it; (2) rank the remaining leaf graph in topological order and add an executable guard that rank 0 has no package runtime imports; (3) make architecture docs mechanically account for every _LAYERS key. Preserve the public compatibility shims from #1936 until their stated removal version. No ADR wording change is necessary for the census; any proposed ADR edit remains subject to the agreed specific-text sign-off.

  3. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    First reviewed slice merged in #1972 (688aa344). Pocket/pad location applicability predicates now live with their natural measurement-support owner; compiler and lint consumers import that owner. location_contract remains an explicitly supported import path, preserving existing callers without a new warning. The independent review's import-lifecycle concern was resolved before merge. Focused boundary/location and coverage tests, static checks, and all CI jobs passed. No ADR text changed.

    The agent census moved rank-0 files with direct package runtime imports from 18 to 17 (direct imports 58 to 57). The strict rank-0 criterion, broader module consolidation, and complete architecture-doc map remain open.

  4. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    Completed in #2102 after the earlier ownership slices. Rank 0 is a strict package leaf band with a fail-closed import guard (including lazy and type-only imports); every ranked module is named in docs/architecture.md, and the AGENTS map matches the grouped DAG. The 22 import-boundary/architecture-doc tests pass on merged main at 502bbc4. Stable compatibility paths remain at their ranked facade homes; no ADR text changed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:architecturePackage layering and architectural structuredesignArchitecture or API design worktech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions