refactor!: delete the utils barrel and make utils a leaf package

[isayev]

Wave 3: the utils barrel is gone and utils/ is a leaf package. Three findings that had
to move together, because all three are about which module a name is imported from.

utils/__init__.py re-exported 41 names

The recorded cause — "names missing from __all__" — was stale. The file's imports and
its __all__ were an exact bijection.

The real defect is inconsistency. Five of eight submodules were re-exported and three were
not, so energy, convergence and stereo_check had no barrel presence at all. Meanwhile
check_connectivity was reached through the barrel in filtering.py:13 and through its own
module in ranking.py:12 — two sibling files, two different paths to the same function.

utils/__init__.py is now docstring-only, documenting what each of the eight modules owns.
The 14 barrel import lines across 12 files name the defining module instead. An AST test,
scoped to src/Auto3D/**, asserts no first-party module imports through it again — AST
rather than regex, so it cannot be fooled by a mention in a comment or string.

Full 41-name mapping table (old barrel path → new dotted path) is in the CHANGELOG.

batchopt.py's compat barrel was narrower than recorded

Only print_stats was a pure re-export; it is deleted. EnForce_ANI and n_steps are
genuinely used in-module and stay imported, now with a comment saying they are not
re-exports so the next reader doesn't delete them.

Its consumers were exactly two: SPE.py:9 and ASE/thermo.py:26, both now pointing at
batch_opt.model_wrapper. The finding also named ASE/geometry.py, auto3D.py and
workflow_workers.py — those are wrong. They import optimizing, which is defined
there, and are untouched.

utils/ is now a leaf

Both Auto3D.models.* imports in validation.py move to function scope. It was the only
non-leaf module in the package. A subprocess tripwire asserts that importing
Auto3D.utils.validation loads no Auto3D.models module — it was red for the stated reason,
pulling in six of them.

import torch in validation.py stays at module level, deliberately

22 test sites patch Auto3D.utils.validation.torch.cuda.is_available. Deferring that import
breaks all 22 at once — confirmed by performing the mutation and counting, not by
reasoning about it. A test now pins the import scope so the next person doesn't rediscover
this the expensive way. M43 was about the models/ import, not about torch; conflating the
two is the cheap-looking shortcut to an import-cost number that this test now blocks.

The public-surface rule, corrected

The rule proposed for this phase was "public iff in Auto3D.__all__ and in api.rst".
That is wrong, and implementing it literally would have been a mistake: api.rst documents
24 entries, ten of which are Auto3D.exceptions.*, none of which belong at top level.
api.rst documents dotted paths; __all__ is the top-level barrel. They are not the same
set and never were.

So the implication is enforced one way only — exported ⟹ documented, plus every
documented path must resolve. Both directions are enforced by test, and api.rst now states
the rule in prose. __all__ is unchanged at 13 names.

Under that rule, the four names that were inconsistent resolve as:

name	decision	why
get_device	stays api.rst-only	documented and referenced as Auto3D.model_factory.get_device (5× in the migration guide). Its apparent notebook uses are torch.cuda.get_device_*, a different thing. A top-level alias would mint a second supported path for nothing.
CustomNNP	stays api.rst-only	the migration guide names from Auto3D.models import CustomNNP as the removed form and Auto3D.models.contract.CustomNNP as the survivor. A third path would contradict it.
IsomerEngineFactory	stays api.rst-only	the one reserved package-path exception, which isomers/__init__.py's docstring already teaches.
generate_conformers	added to api.rst	it has no defining module — it exists only as the top-level alias __init__.py calls canonical. Deleting the intended-canonical name to satisfy a docs list is the wrong direction.

Found while implementing, and not swept under the rug

Two more package barrels violate the rule: cli/__init__.py (6 names) and
models/__init__.py (7 names). Neither is documented at its package path. Both are out of
scope here, so test_only_documented_subpackages_define_all freezes the allowed set at
{isomers, cli, models} with a comment recording the latter two as debt rather than
blessing them. Removing one means deleting it from that frozen set, and nobody can add a
fourth by accident.

Three comments this change falsified, corrected minimally — mechanism updated, conclusion
kept. Two lazy imports (models/species.py, models/preflight.py) were justified by
"import Auto3D.utils reaches this module", which is no longer true, as was a test docstring.
Left as-is they would have invited someone to un-defer rdkit and requests and quietly
undo wave 1's import-cost win.

Verification

• 1357 passed, 9 skipped, 1 xfailed, ruff clean. (+11 boundary tests, −3 barrel-pinning tests.)
• The remaining xfail is the E_tot filter divergence, still owned by a later cluster.
• Four seeds — 12345, 1351916419, 20260804, 7 — all 1357.
• The documented order-sensitive trio run in order
  (test_lazy_torchani_import → test_torch_config → test_thermo_helpers): 111 passed.
  This is the change most likely to break module identity, since it rewrites import sources
  across 12 modules.
• All eight tripwires confirmed red first for their stated reasons; all eight mutations
  verified red and restored under sha256 check.