Add import contracts and a legacy-name check for packages

[aacostadiaz]

The old package stays in the tree as the reference the new code is measured against. That only holds while the new code cannot reach it: a legacy class you can import is one you can subclass and quietly copy, and then the reference is no longer independent of what it is judging. Two gates, so this stops depending on review attention.

Import contracts. .importlinter holds five: the v1 packages never import mace, mace never imports them, mace_core depends on no framework and no sibling, the torch and jax sides never import each other, and mace_torch layers only import downwards. Each was checked by breaking it and watching it fail on the right file and line.

Every layer in the layering contract is optional. mace_torch has none of cli, train, models, nn or kernels yet, and a contract naming a module that does not exist is simply broken, so the alternative was adding this gate after the imports it exists to prevent.

Name check. A file can copy structure without importing anything, so this catches a legacy symbol named in a v1 file at all. It reads the parsed syntax tree, not the text: the list contains MACE, which is also the project's name and is in nearly every docstring here, so a text search would flag the whole repository and be switched off within a week. getattr(module, "ScaleShiftMACE") is caught; """The PyTorch stack for MACE v1.""" is not. The model-class list is checked against the classes the old code declares, so one added there fails here.

Where it runs. tests/architecture moves out of unit into a new architecture job, so it runs once. That job is the only one installing both trees editable, which the contracts need: import-linter resolves each package on the filesystem, so a missing one reads as a broken contract rather than a missing install. It does not wait on lint, since a formatting failure and an import-direction failure are different answers.

Checks run

Check	Result
lint-imports --config .importlinter	5 kept, 0 broken, over 147 files
pytest tests/architecture	20 passed
pytest tests/unit tests/golden -m "not slow" -n auto	1045 passed, 61 skipped, 1 xfailed
pre-commit run --all-files	passed
git ls-files mace/	83, and the diff against mace/ is empty

The runtime half of the guard already exists in mace_launcher.audit. Its other activation point is the tests/parity/ conftest, which PAR-1 (#1572) creates.

What to look at

That exactly two things may import both stacks: mace_launcher, which holds the dispatcher and the guard, and tests/parity/. The launcher's entry is its absence from the contract's source list, which is easy to widen by accident and impossible to notice, so a test pins that list.

Closes #1552

---

Note

Low Risk
Changes are CI and dev-tooling guardrails only; they do not alter training, inference, or user-facing runtime behavior.

Overview
Adds static enforcement so the frozen legacy mace tree stays isolated from the v1 packages under packages/, complementing the existing runtime guard in mace_launcher.audit.

Import contracts (.importlinter, run via lint-imports): five rules—no cross-import between legacy and v1 (with mace_launcher intentionally outside the v1→legacy sources), framework-free mace_core, no mace_torch↔mace_jax mixing, and optional downward layering for mace_torch. import-linter is added to the dev extra.

CI: tests/architecture is removed from the unit matrix and moved to a dedicated architecture job that installs both stacks (legacy via setup-mace, v1 editable), runs lint-imports, then pytest tests/architecture—in parallel with lint, not behind it.

New architecture tests: mirror the contracts locally (including pinning that only mace_core/mace_torch/mace_jax are forbidden-from-legacy sources) and scan all packages/**/*.py with an AST denylist of legacy model/registry/data names so structural ports are caught even without imports.

^{Reviewed by Cursor Bugbot for commit ef56d31. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e564800. Configure here.}