refactor!: one conformer filter, gated writers, and drop reasons that say why

[isayev]

Wave 5: the behavior changes the file splits made safe to do. The suite now has zero
xfailed tests — the E_tot divergence pinned four waves ago is resolved.

One conformer filter

Auto3D carried two duplicate filters with the same criterion but different behavior on
malformed input: the energy-clustered one raised KeyError on a record with no E_tot, the
legacy all-pairs one tolerated it. That was pinned as xfail(strict=True) in wave 1
specifically so it could not be forgotten or silently "fixed". The marker is gone.

The order was load-bearing: harden the survivor, pin the oracle with recorded values while
both filters still existed, then delete the legacy one. Deleting first would have destroyed
the oracle its own tests compared against.

What the tolerant path does, and why the naive version would be a bug

A record missing E_tot gets sort key (True, 0.0) against (False, energy), so it sorts
last and the 0.0 never participates in a comparison. That is deliberate: E_tot is a
user-supplied property, so if the placeholder took part in the comparison, a genuine
positive energy would let a missing-energy record sort first and become top_k's
reference conformer.

Such records are not dropped. They reach the within-cluster filter, whose energy guard already
treats None as "cannot apply — RMSD alone decides". Since no energy gap can prove such a
record is not a duplicate, the presence of one switches clustering off and compares all
pairs — which is exactly what the deleted filter did, so its verdicts are preserved.

The inverse assertions

A dedup guard that declared everything distinct would satisfy every "these must not merge"
test while silently disabling deduplication entirely. So: two energy-less duplicates still
collapse to one, and an energy-less record still merges with an energy-bearing duplicate.

Overwrite gates on the public writers

smiles2smi, encode_ids, decode_ids and select_tautomers take a keyword-only
overwrite — permissive where the caller named the file, restrictive where Auto3D invented
it. The concrete hazard: select_tautomers("/data/results.sdf", k=1) truncated
/data/results_top_tautomers.sdf with no gate at all. It now resolves and gates the path
before reading its input.

Nine of seventeen new tests failed first. Thirteen mutations verified, including the
over-fire direction — a gate that refuses correctly but blocks legitimate writes is not an
improvement. The free paths are confirmed by coverage rather than assumed: each gate's
line is executed by the real orchestrator finalize path in test_workflow.py and
test_pipeline_e2e.py.

Drop reasons that say why

ranking.py logged "No structure converged" whenever nothing survived — including when
every conformer was dropped for stereochemistry. Filters now return a frozen
FilterResult(kept, dropped) that rejects unknown reason keys at construction, and that
literal survives only when unconverged is the sole reason.

The final warning previously hard-coded "the rest were dropped by the connectivity,
stereochemistry or energy-window filters" — a hand-maintained disjunction listing reasons it
had no way to know applied. It now reports the actual tally.

Two of the new tests for this were themselves vacuous on first writing (one built the merged
result it then asserted on; another used records run() drops before the filter ever sees
them). Both were rewritten until they discriminated.

Selector dispatch

The k/window if/elif chain becomes a registry checked against config.SELECTOR_FIELDS
at import, so adding a selector to config without wiring it fails at import rather than
being silently ignored.

The mutation for this first survived — reverting to the hand-written chain is behaviorally
identical when there are only two selectors, so the new code was unproven. A test now wires a
genuine third selector (percentile) through config, registry and method and asserts run()
dispatches to it. The mutation is red.

Five .smi parsers become one

iter_smi_records is the survivor. The differences found before switching, since this cluster
has already produced two pairs of "identical-looking" functions that differed subtly:

• check_smi_format's hand-rolled loop already matched almost exactly — same blank/comment
  skip, same tolerance for extra columns. Only an unasserted message string changed.
• remove_enantiomers and amend_configuration had no guard at all. A blank line raised a
  bare IndexError or ValueError: not enough values to unpack, and neither skipped #
  comments. Both now raise a named InputValidationError, and blank and comment lines skip —
  previously fatal. Malformed non-blank rows still raise, so this is added robustness, not a
  silent behavior change.
• chunk_manager.py's pandas reader stays separate for performance, with a new
  cross-agreement test against iter_smi_records so the two cannot drift. That test also pins
  the one deliberate divergence: pandas does not skip # comment lines.

Also

• create_enantiomer's len(keys)==1 special case and its post-loop read of a loop
  variable — which worked only by a scoping accident — become one cursor-based pass, verified
  bit-identical across 0 to 4 stereocenters including ring and leading positions.
• ASE/thermo.py used atoms.set_calculator/get_calculator, deprecated in ASE 3.22.1,
  in three places. Now atoms.calc. (This finding was left open by an earlier pass that
  couldn't identify it without the manifest text, and was right to leave it rather than guess.)
• The output_guard re-export in utils/validation.py is deleted now that every call site
  names utils/output_guard directly.
• Six docstrings claimed changes landed in 4.0.0 or 4.1.0 — versions that will not exist,
  since this ships as 3.0.0.

One process note on that last item

When checking whether the re-export was safe to delete, a single-line grep for
from Auto3D.utils.validation import.*check_output reported "safe" — but ASE/geometry.py
imported it in a multi-line parenthesized block, which that pattern cannot match. Collection
broke in two modules. Fixed by repointing the import. Worth recording because two independent
checks made the identical false-negative: a grep for an import must match the parenthesized
form, or it under-reports.

Public signature changes

• ConformerRanker.__init__: use_optimized_filtering removed; energy_cluster_window
  and overwrite each shift down one positional slot (no positional callers in-tree). Default
  is now DEFAULT_ENERGY_CLUSTER_WINDOW.
• Auto3D.filtering.filter_unique deleted. filter_conformers, FilterResult and
  DROP_REASONS added.
• ConformerRanker._filter_mols returns FilterResult, not list.
• smiles2smi(smiles, path, *, overwrite=True), encode_ids(path, out_dir=None, *, overwrite=False),
  decode_ids(path, mapping, *, overwrite=False),
  select_tautomers(sdf, k=None, window=None, *, overwrite=False).
• encode_ids' refusal message now matches the shared one.
• top_k's k == 1 fast path applies converged_or_unfiltered, so its predicates match
  filter_conformers. No pipeline effect — run() already filters convergence upstream — but
  a direct top_k(group, k=1) call with Converged=false records now returns [].

Verification

1622 passed, 9 skipped, 0 xfailed, ruff clean. Every fix mutation-verified by reverting it
and confirming the named test goes red.