refactor!: one model contract, one authoritative config schema

[isayev]

Wave 2: the two clusters that had to land together, because both change call sites in
auto3D.py.

One model contract

ModelAdapter moves from models/adapter.py into models/contract.py, 40 lines from
CustomNNP. That proximity is the point. The two Protocols deliberately take their
arguments in opposite orders — CustomNNP is forward(species, coords, charges) -> energies
and is the public custom-NNP contract; ModelAdapter is
forward(coords, species, charges) -> (energies, forces) and is internal. Confusing them is
the failure this layout prevents structurally rather than by comment.

REQUIRED_ATTRIBUTES is now derived from the Protocol's own annotations instead of being
maintained by hand beside it, so the two cannot drift. That makes those annotations
load-bearing for TorchScript archives, since contract.py skips the signature check for
them and is therefore the only gate — the code says so explicitly.

CustomNNP loses @runtime_checkable. It was never used, and it would not have helped:
isinstance against a Protocol checks only attribute presence, so it cannot see
Module.forward's stub, which the validator already handles by hand. isinstance now
raises TypeError and points at validate_custom_nnp. CustomNNP's signature is
unchanged — it is the public contract.

batch_opt no longer imports model_factory at all. The adapter is injected, constructed
inside the worker so it never crosses a spawn boundary, and batch_opt/species.py is
deleted in favour of models/species.py — the species convention now lives next to the
models that define it.

The fp32 trap, and what was done about it

ANI2xAdapter.forward and CustomModelAdapter.forward both call coords.float(), and
ANI2xt additionally calls requires_grad_(True), which raises on the non-leaf tensor an
autograd Hessian supplies. So defining energy() as forward(...)[0] would have silently
downgraded an fp64 Hessian to fp32 — no error, just quietly worse thermochemistry. All
three adapters get their own dtype-preserving energy. AIMNet2Adapter.energy is written
out explicitly to record that its inherited default is safe there (fp64 is an upcast).
Four tests pin this; each was mutation-verified by replacing the override with the inherited
default and watching it go red.

Seven copy-pasted MLPs, and the checkpoint question answered rather than assumed

ANI2xt_no_rep.py's seven near-identical MLP blocks collapse to a WIDTHS table plus a
factory — 75 lines to 9. The obvious risk is checkpoint compatibility, so it was measured,
not reasoned about: a test loads the shipped ani2xt_no_repulsion.pt into the verbatim old
seven-block ModuleList and into the new one, then compares. All 56 tensors satisfy
torch.equal, with identical key sets. nn.ModuleList state_dict keys are positional
indices and never derived from Python variable names, which is why. aev_dim is read off
the checkpoint rather than hardcoded. Mutating one WIDTHS entry turns the test red.

Incidentally, the old source declared S_network before F_network but placed F before S
in the ModuleList. Harmless only because F, S and Cl share widths.

One authoritative config schema

check_valid_configuration took ten keyword arguments and carried a third set of
defaults, including a literal opt_steps=2000 — which is exactly how a schema drifts away
from the one users actually configure. It now takes an Auto3DOptions, which is the single
source of truth, and the two byte-identical ten-kwarg marshalling blocks in auto3D.py and
workflow.py become one line each. Engine choices move to one ENGINE_CHOICES table.

A test walks CLIConfig.model_fields metadata and rejects any pydantic constraint on a
field whose bound lives in FIELD_BOUNDS. It works against Field(ge=),
Annotated[..., Ge()] and conint alike, because it inspects pydantic metadata rather than
source text. The duplicated constraint set that had to be backed out once cannot come back.

opt_steps had two different minimums; 10 wins

FIELD_BOUNDS declared ("ge", 1) while utils/validation.py hand-wrote >= 10 in two
places. 10 is correct: n_steps only tests all-converged on istep % 10 == 0, emits
progress on the same cadence, and guards its statistics with an explicit n >= 10. Below 10
there is no early exit, no progress and no reporting, and FIRE needs several steps to build
velocity — so opt_steps < 10 returned an unconverged structure labelled as optimized.
Loosening the bound to 1 would have accepted that; tightening only moves an existing refusal
earlier.

The test that pinned this defect was xfail(strict=True) and asserted only that the two
minimums agree, deliberately declining to pick a winner so that whoever fixed it would
choose. It is now rewritten to assert exactly one declared minimum exists, and AST-scans
validation.py for any comparison on opt_steps — text matching flagged the explanatory
comment.

The malformed-config exit code, and why no test caught it

An empty file, a non-mapping top level, or a YAML syntax error exited 1 "Unexpected
Error" through auto3d <config>.yaml, but 2 ConfigurationError through
auto3d run -c. A script gating on exit 2 got different answers from the two entry points.
The legacy path now uses the same loader, and the startup banner moved after validation so
an unrunnable config is no longer announced as running.

The test that should have caught this claimed in its docstring to use "the exact
construction _run_legacy_yaml uses" — and then re-implemented it inline. That replica is
precisely why the missing shape guards were invisible: the test exercised its own copy, not
the code. It now calls the real function.

Documentation that had gone stale

config.py's docstring example still called optimizing positionally with a model, and the
migration guide still showed pad_from_mols taking a model name and to_model_species
taking an engine string.

The guide's warning about optimizing silently binding a stray positional argument to
progress_cb is replaced rather than edited, because that hazard no longer exists —
everything after out_f is keyword-only, so such a call now raises TypeError instead of
handing n_steps a wrong-typed callback to swallow in except Exception: pass. The section
records what the hazard was, since it explains why the parameters are keyword-only.

Deliberately not done

• B1's phase 3 — unifying the four Hessian model-calling conventions in ASE/thermo.py.
  Not approved, and the design's own author recommended handing the thermo migration to a
  later cluster. B1 took only the single species import line there.
• to_model_species survives in models/species.py, documented as a residual with its
  delete condition, because migrating thermo.py's two call sites means dropping
  model_name from Calculator and mol2aimnet_input — a thermo.py restructuring. Its
  body is a two-line name dispatch onto to_ani2xt_species, so no table or error message is
  duplicated.

Verification

• 1349 passed, 9 skipped, 1 xfailed, ruff clean.
• The remaining xfail is the E_tot filter divergence, owned by a later cluster. The
  opt_steps pin is resolved and its marker removed — with strict=True, fixing the defect
  while leaving the pin would have turned the suite red.
• Every fix mutation-verified: revert it, confirm the named test goes red, restore. Eleven
  mutations across the two clusters.
• Tripwires written first and confirmed failing for the stated reason before each fix.
• Eight-seed order-independence sweep on a quiescent tree.

Found while implementing

A third optimizing call site at auto3D.py:231 that the design missed. Leaving it
would have shipped a broken smiles2mols.