molforge 0.2.0__tar.gz → 0.4.0__tar.gz

{molforge-0.2.0 → molforge-0.4.0}/CHANGELOG.md

@@ -7,6 +7,614 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] 2026-06-25
+
+### Added
+
+- **Provenance adoption pass 2 — MD wrappers and prep functions.**
+  Completes the wrapper-adoption work. Where
+  pass 1 demonstrated cross-wrapper chaining (ESMFold → Vina),
+  pass 2 exercises chaining **within** a single wrapper's
+  multi-step pipeline and across the composable prep functions —
+  the harder case and the one that proves the design composes.
+
+  Adopted (2 wrappers + 5 functions):
+
+  - **`molforge.wrappers.md.OpenMM`** — `prepare` / `minimize` /
+    `run` each attach a `Provenance` to the output's metadata. Each
+    step's parent is the previous step's `Provenance`, so a full
+    pipeline leaves the final `Trajectory` with a 3-deep chain
+    that reads as `["OpenMM.prepare", "OpenMM.minimize", "OpenMM.run"]`
+    oldest-first. When the input `Protein` has its own `Provenance`
+    (e.g. it came from ESMFold), the chain extends back through it
+    — a sequence-to-trajectory workflow ends with a 4-deep chain
+    that traces all the way to the sequence.
+
+  - **`molforge.wrappers.md.GROMACS`** — same three-step pattern
+    as OpenMM, with the engine strings `"GROMACS.prepare"`,
+    `"GROMACS.minimize"`, `"GROMACS.run"`. The minimize step
+    appends to `simulation.metadata` (since minimize returns the
+    same Simulation in-place, not a new one), preserving the
+    chain across the mutation.
+
+  - **`molforge.prep.{remove_heterogens, fix_missing_atoms,
+    add_caps, add_hydrogens, prepare_for_md}`** — each prep
+    function chains a `Provenance` step onto the output's
+    metadata. `prepare_for_md` (which composes the other four in
+    sequence) leaves the result with a 4-deep chain naturally:
+    `["molforge.prep.remove_heterogens",
+      "molforge.prep.fix_missing_atoms",
+      "molforge.prep.add_caps",
+      "molforge.prep.add_hydrogens"]`. No special handling needed
+    in the composite — the inner functions chain themselves.
+
+  Two helpers, both private:
+
+  - **`molforge.wrappers.md.{openmm,gromacs}._parent_provenance(meta)`**
+    — extracts a `Provenance | None` from a free-form metadata
+    dict, narrowing the type. Per-wrapper rather than shared so
+    each MD wrapper stays self-contained.
+
+  - **`molforge.prep._provenance.chain_prep_provenance(output, *,
+    engine, parameters, input_protein)`** — the DRY-up for the
+    five prep functions. One place to evolve the prep-side
+    provenance shape later (e.g. when we want to also stamp the
+    PDBFixer / OpenMM versions used).
+
+  Backwards compatibility: every existing ad-hoc metadata key
+  (`metadata["engine"]`, `metadata["run_dir"]`, `metadata["emtol"]`,
+  etc.) is preserved unchanged. The new `metadata[PROVENANCE]` is
+  additive.
+
+  Tests (`tests/unit/wrappers/test_provenance_adoption.py`, 8 new
+  in addition to the 11 from pass 1):
+
+  - `TestOpenMMProvenanceChain` (2 tests) drives a full prepare →
+    minimize → run pipeline against a real OpenMM install
+    (skipped if openmm missing). The headline scenario
+    `["ESMFold", "OpenMM.prepare", "OpenMM.run"]` is exercised
+    end-to-end.
+
+  - `TestGROMACSProvenanceWiring` (2 tests) — GROMACS needs the
+    `gmx` binary which CI usually lacks. The tests inspect the
+    module source to assert the three step engine strings appear
+    and that `_parent_provenance(...)` is used — a regression net
+    that catches future code that bypasses the helper without
+    needing the real engine to run.
+
+  - `TestPrepProvenanceChain` (4 tests) — exercises each prep
+    function individually, then a two-function chain, then the
+    full `prepare_for_md` 4-step chain, then the "ESMFold + 4
+    prep steps" 5-deep chain (the most realistic scenario).
+    Skipped if openmm + pdbfixer aren't both installed.
+
+  With pass 2 complete, the headline scenario from the roadmap
+  ("20 designs from ProteinMPNN, docked with Vina, refined with
+  OpenMM") is now fully traceable: every output object's
+  `metadata[PROVENANCE].chain()` reads as the producer pipeline,
+  with sufficient detail in each step's `parameters` to
+  reconstruct the exact call. The remaining provenance work is
+  optional polish: persistence to a sidecar format, hash-keyed
+  caching (the next roadmap item), and richer engine-version
+  introspection.
+
+- **Provenance adoption across folding, docking, and generative
+  wrappers (pass 1).** Builds on the `Provenance` surface added in
+  `9fafbba`. Every wrapper in scope now attaches a `Provenance` to
+  the output's `metadata[PROVENANCE]` alongside its existing ad-hoc
+  keys, so the "20 designs from ProteinMPNN, docked with Vina"
+  scenario is now traceable end-to-end.
+
+  Wrappers adopted:
+    - **Folding**: ESMFold, AlphaFold, Boltz, RoseTTAFold. Each
+      records its `__init__` config (model name, device, msa mode,
+      recycles, etc.) in `parameters` and the input sequence in
+      `inputs`. Folding has no upstream wrapper, so `parent` is
+      `None`.
+    - **Docking**: Vina, DiffDock. Each `DockingResult.metadata`
+      gets a `Provenance` covering the run (box, exhaustiveness,
+      seed, etc. in `parameters`; receptor + ligand refs in
+      `inputs`); when the receptor was a `Protein` with its own
+      `Provenance`, that becomes the `parent` so a Vina pose
+      docked against an ESMFold prediction chains back to the
+      sequence. Per-pose `Pose.metadata` keeps existing per-pose
+      keys (`confidence`, `source_file`) — poses aren't
+      independently produced, so they share the result-level
+      provenance rather than each carrying their own.
+    - **Generative**: RFdiffusion, ProteinMPNN. Each returned
+      design (a `Protein` for RFdiffusion, a `DesignedSequence`
+      for ProteinMPNN) gets its own `Provenance` — all designs
+      from one call share the same Provenance object (frozen +
+      immutable, so by-reference sharing is safe). `design_index`
+      stays as a separate metadata key, not part of `parameters`,
+      since it identifies *which* design rather than the engine
+      config.
+    - **`molforge.io.load_alphafold`**: the loader helper. The
+      engine name reflects that this is the loader, not the
+      AlphaFold run itself (`engine="load_alphafold"`); the file
+      path goes in `inputs["path"]`.
+
+  Existing ad-hoc metadata keys are preserved across every change
+  — `metadata["engine"]`, `metadata["source_sequence"]`,
+  `metadata["source_args"]`, etc. continue to work for 1.x
+  backwards compatibility. The new `metadata[PROVENANCE]` is
+  *additive*, not a replacement, until 2.x.
+
+  Two wrapper-side surface changes worth noting:
+    - `Vina._parse_poses_pdbqt` and `DiffDock._parse_outputs`
+      gained optional `provenance_parameters` /
+      `provenance_inputs` / `provenance_parent` kwargs (and
+      DiffDock additionally `receptor_ref` / `ligand_ref`). The
+      kwargs are optional so legacy tests calling the parsers
+      directly without those refs still work — they just don't
+      get a Provenance attached. The main `dock()` entry points
+      always pass them.
+    - The `Vina` module gained a `_provenance_ref` helper for
+      converting a `Protein | str | PathLike` to a JSON-native
+      string identifier.
+
+  Tests (`tests/unit/wrappers/test_provenance_adoption.py`, 11
+  new): one assertion per adopted wrapper plus a parent-chaining
+  integration test that exercises the headline scenario
+  (`ESMFold -> Vina` chain). Each adoption test holds the wrapper
+  to a uniform contract: `engine` matches the documented name,
+  `parameters` contains every promised key, `inputs` contains the
+  expected input identifier(s). The chaining test confirms
+  `result.metadata[PROVENANCE].chain()` reads as
+  `["ESMFold", "Vina"]` oldest-first.
+
+- **First-class provenance tracking: `molforge.core.Provenance`.** A
+  raw PDB and a folded AlphaFold prediction look identical at the
+  AtomArray level; the only difference is *how the structure was
+  produced*. Pre-existing engine wrappers already wrote some of this
+  information into `metadata` ad-hoc — ESMFold sets
+  `metadata["engine"] = "ESMFold"`, RFdiffusion sets
+  `metadata["source_args"]` — but the keys are scattered, the shapes
+  disagree across engines, and there's no concept of a *parent*
+  output, so a chain of operations (fold -> dock -> MD) is not
+  traceable. This commit canonicalises the shape.
+
+  The new `Provenance` dataclass (frozen, JSON-round-trippable) has:
+    - **`engine`** — producer name; an engine ("ESMFold", "Vina")
+      or a molforge function path ("molforge.prep.prepare_for_md").
+    - **`engine_version`** — engine's own version string.
+    - **`molforge_version`** — auto-filled from `molforge.__version__`.
+    - **`timestamp`** — ISO-8601 UTC, auto-filled.
+    - **`parameters`** — engine-specific arguments (must be
+      JSON-native; validated eagerly at construction so a wrapper
+      can't smuggle in a `Path` or NumPy array that crashes much
+      later at serialisation).
+    - **`inputs`** — identifiers of the input data (e.g.
+      `{"sequence": "MKTVRQ..."}`, `{"receptor": "/path/to.pdb"}`).
+    - **`parent`** — the provenance of the input this step
+      *consumed*. Recursively a `Provenance` or `None`. This is what
+      makes the system compositional: walking the parent chain
+      reconstructs the whole history.
+
+  Construction goes through `Provenance.from_engine(engine=...,
+  parameters=..., inputs=..., parent=...)` which auto-fills the two
+  version fields and the timestamp so wrappers don't have to think
+  about them. The dataclass is frozen — mutating an attached
+  provenance would corrupt the audit trail; use `.replace(**changes)`
+  to derive an amended copy.
+
+  Traversal helpers: `walk()` yields self then ancestors newest-first;
+  `chain()` returns the same list oldest-first (suitable for printing
+  as a left-to-right pipeline); `depth` is the step count.
+
+  Serialisation: `to_dict()` / `from_dict()` give a stable plain-dict
+  shape with parents nested recursively; `to_json()` / `from_json()`
+  are JSON convenience wrappers. The on-disk shape is part of the
+  stability commitment.
+
+  The new `metadata_keys.PROVENANCE = "provenance"` constant is the
+  documented key; `ProteinMetadata` TypedDict declares it. The
+  intended use is `protein.metadata[mk.PROVENANCE] = prov`.
+  **Wrappers are NOT updated in this commit** — that's deliberately
+  separate work. The existing ad-hoc `metadata["engine"]` keys
+  continue to work for the 1.x series; engines opt into the
+  `Provenance` system gradually.
+
+  *NOT persisted through PDB / mmCIF writers* — those preserve only
+  the six documented IO header keys (per the mmCIF audit in
+  `c3a012e`). Provenance is an in-memory concept; users wanting
+  persistence serialise via `to_json` to a sidecar file. This is a
+  documented limitation, not a bug. A future "molforge bundle"
+  format could carry provenance alongside structure data; out of
+  scope here.
+
+  33 new tests in `tests/unit/core/test_provenance.py` covering
+  construction (minimal, autofill, defensive copies, parent),
+  strict JSON-input validation, immutability (FrozenInstanceError +
+  `.replace`), traversal (walk / chain / depth), serialisation
+  (dict shape, JSON round-trip, missing-engine error, forward-
+  compatible deserialisation of older shapes), equality, and the
+  metadata-key integration. Module coverage 96.8%; the residual
+  two lines are a defensive `_molforge_version` exception fallback.
+
+- **mmCIF writer round-trip audit and fidelity fixes.** A systematic
+  audit of `write_cif_string` against every PDB fixture in the repo
+  surfaced five concrete fidelity bugs in the pre-audit writer; all
+  five are now fixed.
+    1. **`model_id == 0` was clobbered to 1.** The old writer used
+       `int(model_id) or 1`, which turned every single-model PDB's
+       `model_id=0` (the `read_pdb` convention for files without
+       MODEL records) into 1 on write. The reader's matching
+       `or 1` default reinforced the change — every PDB → CIF
+       round-trip silently lost the convention. Writer now emits
+       the value verbatim; reader's default flipped from 1 to 0.
+       *Affected every PDB fixture (19/19) before the fix.*
+    2. **Partial / non-integer charges were truncated to int.** The
+       old writer emitted `f"{int(charge):d}"`, turning typical
+       PDBQT / PQR partial charges like `-0.297` into `0` and
+       `-1.5` into `-1`. Writer now emits `f"{charge:.4f}"` (4
+       decimal places preserves enough precision for typical
+       force-field partial charges); zero still emits the `?`
+       sentinel so "no charge information" round-trips cleanly.
+    3. **`metadata['classification']` and `metadata['deposition_date']`
+       not emitted at all.** Both PDB HEADER fields were captured
+       by `read_pdb` and dropped by `write_cif`. Writer now emits
+       `_struct_keywords.text` for classification and
+       `_pdbx_database_status.recvd_initial_deposition_date` for
+       the deposition date; reader picks them up symmetrically.
+    4. **`_entry.id` and `data_<id>` block name could disagree.**
+       The old writer used `protein.name` for the block name but
+       `metadata[pdb_id]` for `_entry.id`. When those differed, the
+       reader's `_entry.id` won and silently rewrote both fields on
+       round-trip (e.g. dipeptide.pdb's `name='dipeptide'` became
+       `'TEST'` because the HEADER's PDB id was `TEST`). The fix
+       uses one chosen identifier — preferring `metadata[pdb_id]`,
+       falling back to `protein.name`, then `"molforge"` — for both.
+       Identifiers with embedded whitespace (which `read_pdb`
+       tolerates from malformed HEADER lines) are now quoted in
+       `_entry.id` even though the block name has to substitute
+       underscores, so `pdb_id` whitespace survives round-trip.
+       When no `pdb_id` exists at all, the writer emits the
+       `_entry.id .` mmCIF sentinel and the reader knows to leave
+       `metadata[pdb_id]` absent rather than manufacturing one from
+       the block name.
+    5. **`serial == 0` was clobbered to `i+1`.** Latent twin of #1;
+       no fixture triggered it but the bug was there. Same fix
+       pattern: only synthesize a default when `serial <= 0`.
+  38 new tests in `tests/unit/io/test_mmcif.py` codify each fix as
+  a regression guard. The `TestFixtureSweep` parametrized test
+  iterates every PDB fixture in the repo and asserts that
+  coordinates, residue/chain/atom-name fields, residue_id, model_id,
+  serial, insertion_code, altloc, record_type, entity_type, and the
+  six tracked metadata keys all survive a PDB → CIF → in-memory
+  round-trip. Three classes — `TestEntryIdAndBlockNameConsistency`,
+  `TestAltlocRoundTrip`, and `TestFixtureSweep` — explicitly
+  document the two structural mmCIF limitations: (a) `Protein.name`
+  is recovered from `metadata[pdb_id]` on round-trip because mmCIF
+  carries only one identifier slot, and (b) altloc round-trip
+  requires the caller to pass `altloc="all"` (the default strategy
+  collapses to highest-occupancy and drops the label). Module
+  coverage at 82.9%; the residual misses are defensive error
+  branches in the tokenizer and reader.
+- **Trajectory I/O: `read_trajectory`, `iter_trajectory`,
+  `write_trajectory`.** `Trajectory` was previously in-memory only —
+  any real MD trajectory bigger than RAM had no way into molforge.
+  This commit adds binary-trajectory I/O wrapping mdtraj, exposed
+  from `molforge.io`. Supported formats are everything mdtraj
+  handles: `.xtc` (GROMACS lossy, the common case), `.trr` (GROMACS
+  lossless), `.dcd` (CHARMM / NAMD / OpenMM), `.nc` / `.netcdf`
+  (AMBER), `.h5` / `.h5md` (HDF5-based), and multi-MODEL PDB. Three
+  functions: `read_trajectory(path, topology=..., stride=1,
+  atom_indices=None)` loads a whole file into a
+  `molforge.md.Trajectory` (use when it fits in memory);
+  `iter_trajectory(path, topology=..., chunk_size=100, stride=1,
+  atom_indices=None)` yields chunks of frames as `Trajectory` objects
+  with bounded memory; `write_trajectory(trajectory, path)` writes
+  out, format inferred from the extension. Coordinates are converted
+  nm ↔ Å automatically (molforge convention is Å throughout; mdtraj's
+  is nm), times in picoseconds either side. The `topology` argument
+  is required for binary formats that don't embed it (XTC, TRR, DCD,
+  NetCDF); it accepts either a `molforge.core.Protein` (reused
+  directly — no PDB round-trip when the caller passes a Protein in)
+  or a path to a PDB. PDB-format trajectories can pass
+  `topology=None`. The `atom_indices` parameter slices both the
+  coordinate array AND the returned topology, so callers analyzing
+  a subset (e.g. backbone atoms only) get a self-consistent
+  Trajectory rather than coords-and-topology mismatched. Lazy mdtraj
+  import: importing `molforge.io` does not import mdtraj; only the
+  trajectory functions do, and they raise
+  `MDEngineNotInstalledError` with install instructions when mdtraj
+  is absent. NOT wired into `load()` / `save()`: trajectories return
+  a different type than the dispatcher's `Protein` / `list[Protein]`
+  contract, and the topology argument is something the dispatcher
+  has no way to supply. Kept as dedicated entry points. 21 new tests
+  in `tests/unit/io/test_trajectory.py` covering reading from PDB,
+  the Å unit conversion, Protein-topology reuse identity, path-string
+  topology, no-topology PDB, atom-indices subset (including the
+  metadata-preserving Protein-slice path), stride, time-array
+  carry-through, the "source: mdtraj" metadata marker, the streaming
+  chunk count (3+3+3+1 from 10 frames), chunk validation, the
+  stride-plus-chunking compose case, the DCD / XTC / PDB write paths
+  (XTC round-trip with the documented 0.001-nm precision), and the
+  missing-mdtraj error path; mdtraj-using tests are
+  `pytest.importorskip` gated. The new module is at high coverage
+  (the few uncovered branches are unreachable error-handling
+  fallbacks). `pdbfixer.*` was added to mypy's missing-stubs override
+  list when `molforge.prep` shipped; no new mypy override is needed
+  here since mdtraj is already there.
+- **New subpackage: `molforge.prep` for MD-system preparation.** A
+  raw PDB from AlphaFold, RoseTTAFold, the RCSB, or a docking engine
+  almost always needs the same clean-up before MD: drop
+  crystallographic clutter (waters, buffer salts, sometimes the
+  ligand), rebuild missing heavy atoms, cap free termini with ACE /
+  NME, and add explicit hydrogens at the right pH. The new
+  `molforge.prep` subpackage exposes one composable function per
+  step plus a convenience pipeline:
+    - `remove_heterogens(protein)` — pure-Python residue-name filter.
+      By default drops waters, ions, ligands, and everything outside
+      the 20 canonical amino acids + standard nucleotides. `keep_water`
+      / `keep_ions` / `keep_ligands` toggles plus an explicit `keep`
+      allow-list for cofactors. Recognises multiple water aliases
+      (HOH, WAT, H2O, SOL, TIP*) and the common monatomic ions.
+    - `fix_missing_atoms(protein)` — wraps PDBFixer's rotamer-library
+      rebuild for incomplete side chains. `fix_missing_residues=False`
+      by default (de-novo loop modelling is risky);
+      `replace_nonstandard=True` by default (MSE → MET, etc.).
+    - `add_caps(protein)` — wraps PDBFixer to add ACE / NME caps at
+      free termini of every protein chain. Multi-chain aware;
+      non-protein chains (ligands, DNA) skipped. Either cap can be
+      disabled with an empty string.
+    - `add_hydrogens(protein, pH=7.4)` — wraps OpenMM
+      `Modeller.addHydrogens` for pH-aware protonation. Idempotent on
+      already-protonated input. The `force_field` kwarg accepts both
+      registered aliases (`"amber14"`, `"charmm36"`) and bare XML
+      filenames.
+    - `prepare_for_md(protein)` — convenience entry point that chains
+      the four steps with sensible defaults for an
+      AlphaFold-PDB-to-OpenMM workflow. Each step's options are
+      forwarded; individual steps can be turned off
+      (`add_caps_to_termini=False`, `add_explicit_hydrogens=False`).
+
+## [v0.3.0] 2026-06-22
+
+### Added
+- **`molforge.io.read_pqr` / `write_pqr` are implemented.** PQR
+  (PDB2PQR / APBS) was a committed import path but a
+  `NotImplementedError` stub; it now parses and writes PQR files,
+  completing the format-I/O backlog (SDF, MOL2, PDBQT, PQR all real).
+  PQR is a PDB-like format that appends per-atom partial charge and
+  atomic radius as whitespace-separated trailing fields. Unlike PDB
+  or PDBQT, PQR is **not** strictly fixed-column past the
+  coordinates — different generators (PDB2PQR, AMBER, CHARMM, APBS)
+  emit different widths. The reader handles all of them by parsing
+  columns 1-54 as fixed (the atom record through coordinates,
+  PDB-compatible) and whitespace-splitting the remainder for charge
+  and radius. Charges land on `AtomArray.charge`; radii land on
+  `protein.metadata["radii"]` as a per-atom list (no native
+  `radius` field on `AtomArray` — electrostatics is a small enough
+  slice of the surface that this didn't warrant a core-type change).
+  The writer is the symmetric operation: it calls `write_pdb_string`,
+  truncates each atom line at column 54, then appends
+  `charge radius`. When no radii are recorded in metadata, a default
+  1.5 Å is used (a reasonable middle-of-the-road heavy-atom radius
+  that lets a charge-only Protein still be written as PQR). 19 new
+  tests in `tests/unit/io/test_pqr.py` covering the charge/radius
+  extractor (clean tokens, trailing garbage, defaults), reading from
+  string and from disk, the dispatcher routes, two variant-width
+  tails seen in real-world PDB2PQR / AMBER output, the full
+  round-trip (coordinates, charges, radii), and the default-radius
+  writer path; `pqr.py` is at 92.0% coverage.
+  `test_dispatch.py`: the two stub-format tests (load and save) now
+  monkeypatch a synthetic planned format rather than depending on
+  any real format being unimplemented — the dispatcher's
+  planned-readers fallback machinery still exists for future use, so
+  the tests are still meaningful. The `_PLANNED_READERS` dict in
+  `dispatch.py` is now empty.
+- **`molforge.io.read_pdbqt` / `write_pdbqt` are implemented.** PDBQT
+  (AutoDock / Vina) was a committed import path but a
+  `NotImplementedError` stub; it now parses and writes PDBQT files.
+  PDBQT is a thin extension of PDB — columns 1-66 are PDB-compatible,
+  columns 71-76 hold the per-atom partial charge, and columns 78-79
+  hold the AutoDock atom type (`C`, `OA`, `HD`, `NA`, ...). The
+  reader reuses `molforge.io.read_pdb_string` for the heavy lifting
+  (atom-array construction, altloc handling, entity classification,
+  multi-MODEL parsing) and post-processes each atom line to pick up
+  the extra columns: charges are written to `AtomArray.charge`,
+  AutoDock types land on `protein.metadata["autodock_types"]` as a
+  per-atom list. `ROOT` / `BRANCH` / `TORSDOF` rotatable-bond markers
+  are read-tolerated (recognised and skipped — `AtomArray` doesn't
+  carry bond topology). The writer is the symmetric operation: it
+  calls `write_pdb_string`, then rewrites each `ATOM` / `HETATM` line
+  to append the charge and AutoDock-type columns; when no AutoDock
+  type is recorded in metadata, the element is used as a documented
+  best-effort fallback. Round-tripping preserves coordinates,
+  charges, and types. The Vina wrapper's pose parser is refactored to
+  go through `read_pdbqt_string` rather than its previous "truncate
+  every atom line to 66 columns and feed to the PDB reader" hack — so
+  per-atom charges now propagate to `Pose.ligand` instead of being
+  silently discarded. 23 new tests in `tests/unit/io/test_pdbqt.py`
+  covering the column extractors (charge and AutoDock type, including
+  the whitespace-split fallback), reading from string and from disk,
+  the dispatcher routes, the full round-trip (coordinates, charges,
+  types), the element-fallback writer path, multi-MODEL handling
+  (Vina pose output), and `ROOT` / `BRANCH` / `TORSDOF` tolerance;
+  `pdbqt.py` is at 93.8% coverage. The `test_dispatch.py` stub-format
+  tests are updated to use `.pqr` (the only remaining stub format).
+- **`molforge.io.read_mol2` / `write_mol2` are implemented.** MOL2
+  (Tripos) was a committed import path but a `NotImplementedError`
+  stub; it now parses and writes Tripos MOL2 files. Like the SDF
+  reader, `read_mol2` is multi-molecule by default and returns
+  `list[Protein]` (the format supports multi-molecule files via
+  repeated `@<TRIPOS>MOLECULE` markers, common in docking output
+  libraries). The reader populates coordinates, elements (extracted
+  from the prefix of the Tripos atom type — `C.ar` → `C`, `N.am` →
+  `N`, two-letter `Cl`/`Br` preserved), atom names, per-atom partial
+  charges from the atom line's last column, and substructure info
+  (residue id / name from the MOL2 `subst_id` / `subst_name`
+  columns). Short atom lines (optional trailing columns omitted) and
+  non-conforming writers that emit `***` for the subst_id or a
+  non-numeric charge are tolerated with silent fallbacks rather
+  than crashing the whole molecule. Bond orders, ring information,
+  stereochemistry, and the `@<TRIPOS>SUBSTRUCTURE` /
+  `@<TRIPOS>CRYSIN` / `@<TRIPOS>UNITY` sections are intentionally
+  dropped — those need a chemistry toolkit. The writer emits a
+  minimal, spec-conformant MOL2 with an empty `@<TRIPOS>BOND` section
+  (some downstream tools error without the tag). The MOLECULE header
+  declares the atom count; a mismatch between that and the ATOM
+  section raises a clear error. `read_mol2` is wired into
+  `molforge.io.load`. 34 new tests in `tests/unit/io/test_mol2.py`
+  covering single/multi-molecule reading, Tripos atom-type element
+  extraction, two-letter elements, partial charges, optional-column
+  fallbacks, blank-line tolerance, every error path, dispatcher
+  integration, and the full round-trip; mol2.py is at 94.4% coverage
+  (the residual misses are unreachable defensive branches).
+- **`molforge.io.read_sdf` / `write_sdf` are implemented.** SDF was a
+  committed import path but a `NotImplementedError` stub; it now
+  parses and writes V2000 SDF / MOL files. The reader is multi-
+  molecule by default, returning a `list[Protein]` (a single-molecule
+  `.mol` file still returns a one-element list, keeping the return
+  type uniform across callers). The atom block, title line, and the
+  ``> <Name>`` / value property block all round-trip; properties land
+  on `Protein.metadata["properties"]`. The implementation uses no
+  chemistry toolkit — the V2000 atom block has a fixed positional
+  layout that's enough for everything molforge does downstream
+  (coordinates, pose ranking, distance calculations). Bond orders,
+  aromaticity, and stereochemistry are intentionally dropped; users
+  who need them should call RDKit directly. V3000 files are detected
+  and raise a clear error pointing at conversion paths. `read_sdf` is
+  wired into `molforge.io.load`, so `load("foo.sdf")` works. The
+  DiffDock wrapper, which previously parsed SDF inline, now goes
+  through `molforge.io.sdf.read_sdf_string` — the inline
+  `_ligand_from_sdf` helper is removed (-1 duplicated parser).
+  `api-stability.md` is updated; MOL2, PDBQT, and PQR remain
+  tentative. 26 new tests in `tests/unit/io/test_sdf.py` covering
+  single/multi-molecule reading, the title and property block,
+  round-trip writing, dispatcher integration, and every error path;
+  the eight DiffDock tests that exercised the inline parser are
+  removed (now subsumed by the SDF tests).
+- **`GROMACS` is now a real MD engine.** `GROMACS`
+  (`molforge.wrappers.md`) was a coherent stub whose `prepare` /
+  `minimize` / `run` all raised `NotImplementedError`; it is now
+  fully implemented. [GROMACS](https://www.gromacs.org/) is a
+  command-line program (`gmx`), not a Python library, so the wrapper
+  drives it as a subprocess. One `prepare` / `minimize` / `run` cycle
+  maps onto the standard GROMACS workflow: `prepare` runs
+  `pdb2gmx` → `editconf` → (optionally) `solvate`; `minimize` writes
+  a steepest-descent `.mdp`, then `grompp` → `mdrun`; `run` writes a
+  production `.mdp`, runs `grompp` → `mdrun`, then reads the frames
+  back with `trjconv` and per-frame energies with `gmx energy`. All
+  state for a simulation lives in one run directory whose path is
+  carried on `Simulation.engine_handle` (and mirrored in
+  `metadata["run_dir"]`), so `minimize` and `run` continue from
+  whatever `prepare` produced. Trajectory frames are read back by
+  asking GROMACS itself (`gmx trjconv`) to convert its binary `.xtc`
+  to a multi-model PDB, which molforge's own PDB reader then parses —
+  the wrapper deliberately takes no dependency on a third-party
+  binary-trajectory library. Three small fixed-layout parsers
+  (`.gro` coordinates, multi-model PDB, `.xvg` columns) handle the
+  GROMACS outputs directly. `gmx` is resolved lazily via
+  `shutil.which`, so construction never touches the filesystem; a
+  clear `MDEngineNotInstalledError` (pointing at OpenMM) is raised
+  when it is absent. A constructor flag covers the water model, box
+  margin/type, and a `verbose` pass-through. 36 tests (a new
+  `test_gromacs.py`), covering construction and validation, `gmx`
+  resolution, the three parsers and their error paths, and the full
+  `prepare` / `minimize` / `run` pipeline driven by a mocked
+  `subprocess.run` that writes the files each `gmx` step would
+  produce; the wrapper module is at 94% coverage (the residual
+  misses are defensive `except` branches for corrupt output GROMACS
+  would never actually emit). The 6 obsolete `TestGROMACSStub` tests
+  are removed.
+- **`DiffDock` is now a real docking engine.** `DiffDock`
+  (`molforge.wrappers.docking`) was a coherent stub whose `dock()`
+  raised `NotImplementedError`; it is now fully implemented.
+  [DiffDock](https://github.com/gcorso/DiffDock) is a
+  diffusion-generative model for *blind* protein-ligand docking — it
+  needs no search box, sampling poses over the whole receptor and
+  ranking them with a learned confidence model. Like the
+  `RoseTTAFold` wrapper, DiffDock ships as a research repository
+  rather than a pip package, so the wrapper drives it as a
+  subprocess: it locates the cloned repo (`$DIFFDOCK_HOME` or an
+  explicit `repo_dir`), materializes the receptor to PDB, accepts the
+  ligand as a SMILES string or a path to an SDF/MOL2 file, runs
+  `python -m inference`, and parses the ranked
+  `rank{N}_confidence{C}.sdf` output into a `DockingResult`. DiffDock
+  reports a *confidence* (higher = better), the opposite of Vina's
+  affinity convention; the wrapper stores the raw value in
+  `Pose.metadata["confidence"]` and sets `Pose.score` to its
+  negation, so `score` ascending is best-first for every engine. SDF
+  poses are parsed by reading the V2000 atom block directly (molforge's
+  RDKit-backed SDF reader is still a stub, and the atom block —
+  3D coordinates plus element symbols — needs no chemistry toolkit).
+  A constructor flag covers `samples_per_complex`, `inference_steps`,
+  and `batch_size`. 30 tests (a new `test_diffdock.py`), covering
+  construction and validation, install resolution, SDF and
+  confidence-from-filename parsing, and the `_run_cli` subprocess seam
+  via a mocked `subprocess.run`; the wrapper module is at 100%
+  coverage. The 4 obsolete `TestDiffDockStub` tests are removed.
+- **OpenMM wrapper test coverage raised from 24% to 95%.** The
+  OpenMM tests previously gated every real path behind
+  `skipif(openmm installed)` — so `prepare` / `minimize` / `run`
+  were exercised by *nothing*: when openmm was absent they couldn't
+  run, and when present the negative-path tests skipped. The file is
+  restructured into a dependency-free half (construction, the
+  force-field registry, the missing-dependency errors) and a new
+  `TestRealOpenMM` class that runs `prepare` / `minimize` / `run`
+  end to end against a real OpenMM install — system building,
+  hydrogen addition, the minimizer, the integration loop, trajectory
+  assembly, and argument validation. A new chemically complete
+  heavy-atom fixture, `tests/fixtures/pdb/ala_tripeptide_heavy.pdb`
+  (ALA-ALA-ALA with all standard heavy atoms plus the C-terminal
+  OXT), gives the force field something it can template. The
+  real-engine tests are deliberately *not* marked `slow` — the
+  tripeptide is tiny and a 20-step run is sub-second — so they run
+  in the normal suite wherever openmm is installed, and skip cleanly
+  (9 skips) where it isn't. A new CI job, `md-openmm`, installs the
+  `[md]` extra and runs the MD wrapper tests on every push so
+  `TestRealOpenMM` is actually exercised.
+- **RFdiffusion wrapper test coverage raised from 84% to 99%.** The
+  `_run_cli` subprocess seam of `wrappers.generative.rfdiffusion` —
+  previously untested — now has direct tests via a mocked
+  `subprocess.run` (no RFdiffusion or torch needed): command and
+  Hydra-arg assembly, the `design_*.pdb` output-parsing path, the
+  no-output `RuntimeError`, `CalledProcessError` → `RuntimeError`
+  translation, the public `generate()` entry point, and
+  `contigs` / `symmetry` pass-through. 5 new tests (16 → 21 in the
+  file). Mirrors the ProteinMPNN coverage work from the previous
+  cycle.
+
+### Removed
+- **BREAKING `molforge.wrappers.folding.Rosetta` removed.** The `Rosetta`
+  name was a placeholder from the `0.0.x` series whose meaning was
+  ambiguous — it could read as PyRosetta (the classical
+  sequence-design library) or RoseTTAFold (the deep-learning
+  model). The real wrapper now lives at `RoseTTAFold`. `Rosetta`
+  had been kept this cycle as a `DeprecationWarning`-emitting alias,
+  but since it never appeared in a tagged release, carrying it —
+  and the day-one deprecation it implies — into the 1.0 stable
+  surface added nothing. It is removed outright: import
+  `RoseTTAFold` instead. A PyRosetta wrapper, if ever added, would
+  be a separate class (`PyRosetta`) in its own module, since
+  PyRosetta's surface is far wider than the `FoldingEngine`
+  contract. The 3 alias tests are removed (folding-engine count
+  unchanged: ESMFold, AlphaFold, Boltz, RoseTTAFold).
+
+ ### Fixed
++- **`OpenMM.prepare()` now adds missing hydrogens, so heavy-atom
+  structures are usable.** A force field needs explicit hydrogens,
+  but `prepare()` called `ForceField.createSystem()` directly on
+  whatever atoms the input had. Heavy-atom structures — the normal
+  output of every folding and docking engine, and what most PDB
+  files on disk contain — therefore failed with a cryptic
+  OpenMM "no template found for residue" error, making the wrapper
+  effectively unusable on exactly the structures molforge produces.
+  `prepare()` now runs `Modeller.addHydrogens()` before building the
+  system; the step is idempotent, so an already-protonated structure
+  is unaffected. Because adding hydrogens changes the atom count, the
+  molforge `Protein` attached to the returned `Simulation` is rebuilt
+  from the protonated structure, so its topology and the coordinate
+  array agree (previously a heavy-atom topology could be paired with
+  a protonated coordinate array). A new `add_hydrogens` constructor
+  flag (default `True`) lets callers who have pre-protonated their
+  structure opt out.
+
+## [v0.2.0] 2026-05-26 
+
 ### Added
 - **ProteinMPNN wrapper test coverage raised from 69% to 96%.** The
   two previously-untested seams of `wrappers.generative.proteinmpnn`
@@ -72,148 +680,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   still permitted but carry no cross-version stability guarantee. 15
   new tests, including consistency checks that the parsers only emit
   documented keys and that the TypedDict matches `DOCUMENTED_KEYS`.
-
-### Fixed
-- **`load_alphafold` now emits the uniform confidence metadata keys.**
-  `molforge.io.load_alphafold` previously wrote only AlphaFold-specific
-  keys (`plddt`, `plddt_per_residue`, `mean_plddt`, `source`), while
-  the AlphaFold *wrapper* wrote the cross-engine-uniform keys
-  (`confidence_per_atom`, `confidence_per_residue`, `mean_confidence`,
-  `engine`). Downstream code reading confidence uniformly across
-  engines silently missed AlphaFold structures loaded from disk.
-  `load_alphafold` now populates both sets (uniform keys preferred,
-  legacy keys retained for backward compatibility); the two carry
-  identical values. Surfaced by the API audit.
-- **`GROMACS` and `DiffDock` are now coherent stubs.** Both are
-  exported (committed import paths) but unimplemented. Previously
-  they were *incoherent*: `GROMACS` didn't implement its `MDEngine`
-  abstract methods at all, so `GROMACS()` failed with a cryptic
-  "Can't instantiate abstract class" `TypeError` rather than a
-  meaningful message; both engines' methods raised a bare
-  `NotImplementedError` with no text. They are now coherent stubs —
-  instantiable, satisfying their respective engine ABCs
-  (`MDEngine` / `DockingEngine`), with every method raising
-  `NotImplementedError` carrying a clear message that points at the
-  working alternative (`OpenMM` / `Vina`) and the tracking issue.
-  10 new tests. Surfaced by the API audit.
-- - **Lint drift from a Ruff version bump cleared; CI lint job green
-  again.** `.pre-commit-config.yaml` pinned `ruff-pre-commit` at
-  `v0.5.0`, but the `[dev]` extra installs `ruff>=0.5` unpinned, so
-  CI resolved a much newer Ruff (0.15.x) whose added rules flagged
-  33 pre-existing issues — meaning the CI `lint` job was effectively
-  red. All 33 are now resolved: a genuine dead variable in
-  `ensembles.clustering` removed, an unused `shutil` import dropped,
-  five `pytest.raises(match=...)` patterns with unescaped regex
-  metacharacters made explicit (raw strings / escaped dots), a
-  `zip()` given an explicit `strict=`, four nested `with` statements
-  collapsed, a `getattr()` call with a string literal in
-  `ensembles.weighting` replaced by a `cast`-backed direct attribute
-  access (dropping a now-misplaced `# noqa`), and a Ruff-version
-  formatting refresh applied across 24 files (cosmetic line-joining
-  only). Two intentional-notation cases
-  are configured rather than rewritten: `allowed-confusables`
-  permits `×`, `σ`, and `–` in docstrings (matrix dimensions, the
-  standard deviation, prose dashes), and `RUF022` is per-file-ignored
-  for the two modules whose `__all__` is deliberately grouped by
-  category with section comments. The `ruff` and `mypy` pre-commit
-  pins are bumped to the versions CI resolves, so the two stay in
-  lock-step and this drift cannot silently recur. No source-behaviour
-  or test-count change (918 pass + 11 skipped, unchanged).
-
-### Changed
-- **BREAKING: `cross_validate` now defaults to `on_error="raise"`.**
-  Previously `cross_validate` defaulted to `on_error="record"` —
-  exceptions raised by individual validators were silently caught,
-  recorded in verdict metadata, and the verdict marked
-  `passed=False`. The problem: a validator that throws on every
-  design (a misconfigured engine, a missing dependency, a bad
-  input) produced a full list of `passed=False` verdicts that
-  *looked* like a real result, hiding the bug. The new default
-  fails loud. Code that genuinely wants a batch to survive
-  individual validator failures must now pass `on_error="record"`
-  explicitly. Flagged and resolved by the API audit.
-- **The entire `molforge` package is now `mypy --strict` clean.**
-  With `wrappers` and `plugins` brought up to strict, all 77 source
-  modules across every subpackage pass `mypy --strict` with zero
-  errors. The CI `typecheck` job is correspondingly simplified: the
-  previous two-step arrangement (a strict gate on the clean
-  subpackages plus a non-blocking informational full-tree run)
-  collapses to a single `mypy src` gate that fails the build on any
-  type error. The `tests/unit/test_typing.py` regression test is
-  likewise simplified to one whole-package check. 31 errors fixed in
-  this final tranche: 20 stale `# type: ignore` comments (made
-  redundant when the optional heavy dependencies were added to the
-  mypy `ignore_missing_imports` override), four deliberate engine-
-  method `# type: ignore[override]` annotations (the concrete
-  engine wrappers refine the permissive `**kwargs` signatures of
-  their `DockingEngine` / `MDEngine` / `GenerativeEngine` abstract
-  bases — an intentional, documented refinement that mypy's strict
-  Liskov check cannot model), `cast`s for the opaque
-  `Simulation.engine_handle` inside the OpenMM wrapper and for the
-  unstubbed-dependency return values, and `Vina.dock`'s receptor
-  narrowing switched from `hasattr` to `isinstance` (a more correct
-  check that mypy can also narrow on).
-- **`molforge.ml` is now `mypy --strict` clean.** The ML subpackage
-  (sequence/structure featurization, protein-language-model
-  embeddings) joins the strict gate — eight strict-clean
-  subpackages in total, 51 source files. Six errors fixed: the four
-  numpy-widening `no-any-return`s in `embeddings.py` (resolved with
-  `cast`s), and two real type bugs in `structure_features.py` —
-  `pair_distances` and `pair_distance_features` declared
-  `atom_choice: str` but pass it to `distance_map`, which requires
-  the `Literal["ca","cb","heavy","all"]` the docstrings already
-  specify, and a coordinate feature array silently upcast to
-  float64 by a division. The `torch` and `transformers` (and
-  `colabfold`, `meeko`, `vina`) optional heavy dependencies, which
-  ship no type stubs, are added to the mypy `ignore_missing_imports`
-  override alongside the existing `Bio` / `biotite` / `mdtraj` /
-  `openmm` / `rdkit` entries. CI strict gate and the
-  `tests/unit/test_typing.py` regression test updated; only
-  `plugins` and `wrappers` remain outside the gate.
-- **Six more subpackages are now `mypy --strict` clean.**
-  `molforge.io`, `molforge.sequence`, `molforge.structure`,
-  `molforge.metrics`, `molforge.ensembles`, and
-  `molforge.validation` now pass `mypy --strict` with zero errors,
-  joining `molforge.core` — seven strict-clean subpackages in total,
-  46 source files. The 12 errors fixed were mostly numpy operations
-  mypy widens to `Any` (resolved with explicit `cast`s that document
-  the known array dtype) and two stale `type: ignore` comments; two
-  were genuine annotation bugs — `_place_hydrogens` in `dssp.py` was
-  declared to return a single array but actually returns a
-  `(coords, mask)` tuple, and `_score` in `alignment.py` was
-  declared `NDArray[np.int_]` but builds an `int32` array (`np.int_`
-  is `int64` on 64-bit platforms). The CI strict gate now covers all
-  seven subpackages; the regression test
-  (`tests/unit/test_typing.py`, moved up from `tests/unit/core/` and
-  parametrized) checks each one in-suite. The remaining subpackages
-  (`ml`, `plugins`, `wrappers`) are still tracked by the
-  non-blocking informational `mypy src` CI step.
-- **`molforge.core` is now `mypy --strict` clean, and CI enforces
-  it.** The `core` subpackage — the data model the rest of the
-  library is built on — now passes `mypy --strict` with zero
-  errors (fixed: two missing `NDArray` type arguments in
-  `AtomArray`, an `Any`-return in `Atom.coord`, and an untyped
-  `Chain.__iter__` that was suppressed with a `type: ignore`). The
-  CI `typecheck` job now runs `mypy --strict src/molforge/core/`
-  as a hard gate, with a separate non-blocking full-tree `mypy src`
-  step that keeps the remaining (out-of-`core`) type errors visible
-  while they're worked through. A new `slow`-marked regression test
-  (`tests/unit/core/test_typing.py`) runs the strict check in-suite
-  so a `core` type regression is caught locally too.
-
-### Documented
-- **`Simulation.engine_handle` contract clarified.** The attribute
-  type (`object | None`) is correct — it really is an opaque,
-  engine-specific handle — but the contract was under-specified.
-  The docstring now states explicitly that `engine_handle` is
-  engine-private (callers must not inspect it or set it), is **not
-  serialized** (it typically wraps unpicklable C-extension state;
-  persistence layers must drop it and let the engine wrapper
-  rebuild it on resume), and carries **no semver guarantee**. For
-  inspectable per-simulation data, `Simulation.metadata` is the
-  supported field. No code change. Flagged by the API audit.
-
-### Added 
 - **RoseTTAFold All-Atom folding wrapper.** New file
   `src/molforge/wrappers/folding/rosettafold.py` implements a real
   wrapper around the Baker lab's RoseTTAFold-All-Atom (Krishna et
@@ -241,25 +707,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   prediction matching the rest of the folding wrappers; protein-
   ligand and covalent-modification co-folding (RFAA's headline
   capability) need a separate `predict_complex()` surface and
-  remain planned. 47 new tests (45 passing + 2 correctly skipped:
+  remain planned. 
+- 47 new tests (45 passing + 2 correctly skipped:
   one for the torch tensor conversion when torch isn't installed,
   one @slow end-to-end requiring `$RFAA_HOME`). Total test count:
   830 → 875 passed + 11 skipped.
-
-### Deprecated
-- **`molforge.wrappers.folding.Rosetta` is now a deprecated alias
-  for `RoseTTAFold`.** The original `rosetta.py` placeholder was
-  ambiguous about whether it referred to PyRosetta (the Baker lab's
-  classical sequence-design library) or RoseTTAFold (the deep-
-  learning model). The new real wrapper lives at
-  `RoseTTAFold` for clarity. `Rosetta` is retained as a thin
-  subclass that emits `DeprecationWarning` on construction so
-  existing imports / isinstance checks keep working through the
-  next minor release. A PyRosetta wrapper, if added, would live in
-  a separate module (`pyrosetta.py`) since PyRosetta's surface is
-  much wider than the `FoldingEngine` contract.
-
-### Added 
 - **Boltz / Boltz-2 folding wrapper.** Real implementation replacing
   the `boltz.py` stub. Drives the `boltz predict` CLI via subprocess
   against a temporary directory and parses the resulting mmCIF +
@@ -275,7 +727,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   metadata follows the uniform folding-engine convention
   (`confidence_per_residue`, `confidence_per_atom`, `mean_confidence`)
   and additionally surfaces Boltz-specific `ptm`, `iptm`, and
-  `confidence_score` from the JSON sidecar. 47 new tests (46 passing
+  `confidence_score` from the JSON sidecar. 
+- 47 new tests (46 passing
   + 1 correctly skipped @slow end-to-end), structured as a series of
   testable seams: construction, sequence validation, YAML input
   construction, command-line assembly, environment setup, output
@@ -477,6 +930,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the empty-entry-points fallthrough.
 
 ### Fixed
+- **`load_alphafold` now emits the uniform confidence metadata keys.**
+  `molforge.io.load_alphafold` previously wrote only AlphaFold-specific
+  keys (`plddt`, `plddt_per_residue`, `mean_plddt`, `source`), while
+  the AlphaFold *wrapper* wrote the cross-engine-uniform keys
+  (`confidence_per_atom`, `confidence_per_residue`, `mean_confidence`,
+  `engine`). Downstream code reading confidence uniformly across
+  engines silently missed AlphaFold structures loaded from disk.
+  `load_alphafold` now populates both sets (uniform keys preferred,
+  legacy keys retained for backward compatibility); the two carry
+  identical values. Surfaced by the API audit.
+- **`GROMACS` and `DiffDock` are now coherent stubs.** Both are
+  exported (committed import paths) but unimplemented. Previously
+  they were *incoherent*: `GROMACS` didn't implement its `MDEngine`
+  abstract methods at all, so `GROMACS()` failed with a cryptic
+  "Can't instantiate abstract class" `TypeError` rather than a
+  meaningful message; both engines' methods raised a bare
+  `NotImplementedError` with no text. They are now coherent stubs —
+  instantiable, satisfying their respective engine ABCs
+  (`MDEngine` / `DockingEngine`), with every method raising
+  `NotImplementedError` carrying a clear message that points at the
+  working alternative (`OpenMM` / `Vina`) and the tracking issue.
+  10 new tests. Surfaced by the API audit.
+- - **Lint drift from a Ruff version bump cleared; CI lint job green
+  again.** `.pre-commit-config.yaml` pinned `ruff-pre-commit` at
+  `v0.5.0`, but the `[dev]` extra installs `ruff>=0.5` unpinned, so
+  CI resolved a much newer Ruff (0.15.x) whose added rules flagged
+  33 pre-existing issues — meaning the CI `lint` job was effectively
+  red. All 33 are now resolved: a genuine dead variable in
+  `ensembles.clustering` removed, an unused `shutil` import dropped,
+  five `pytest.raises(match=...)` patterns with unescaped regex
+  metacharacters made explicit (raw strings / escaped dots), a
+  `zip()` given an explicit `strict=`, four nested `with` statements
+  collapsed, a `getattr()` call with a string literal in
+  `ensembles.weighting` replaced by a `cast`-backed direct attribute
+  access (dropping a now-misplaced `# noqa`), and a Ruff-version
+  formatting refresh applied across 24 files (cosmetic line-joining
+  only). Two intentional-notation cases
+  are configured rather than rewritten: `allowed-confusables`
+  permits `×`, `σ`, and `–` in docstrings (matrix dimensions, the
+  standard deviation, prose dashes), and `RUF022` is per-file-ignored
+  for the two modules whose `__all__` is deliberately grouped by
+  category with section comments. The `ruff` and `mypy` pre-commit
+  pins are bumped to the versions CI resolves, so the two stay in
+  lock-step and this drift cannot silently recur. No source-behaviour
+  or test-count change (918 pass + 11 skipped, unchanged).
 - **Docs notebooks no longer use symlinks.** The walkthrough and
   example notebooks were previously symlinked from `docs/` into the
   canonical `notebooks/` directory. Symlinks broke two things: (1)
@@ -499,6 +997,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the actual public attributes. Discovered while writing ensemble
   test fixtures.
 
+### Changed
+- **BREAKING: `cross_validate` now defaults to `on_error="raise"`.**
+  Previously `cross_validate` defaulted to `on_error="record"` —
+  exceptions raised by individual validators were silently caught,
+  recorded in verdict metadata, and the verdict marked
+  `passed=False`. The problem: a validator that throws on every
+  design (a misconfigured engine, a missing dependency, a bad
+  input) produced a full list of `passed=False` verdicts that
+  *looked* like a real result, hiding the bug. The new default
+  fails loud. Code that genuinely wants a batch to survive
+  individual validator failures must now pass `on_error="record"`
+  explicitly. Flagged and resolved by the API audit.
+- **The entire `molforge` package is now `mypy --strict` clean.**
+  With `wrappers` and `plugins` brought up to strict, all 77 source
+  modules across every subpackage pass `mypy --strict` with zero
+  errors. The CI `typecheck` job is correspondingly simplified: the
+  previous two-step arrangement (a strict gate on the clean
+  subpackages plus a non-blocking informational full-tree run)
+  collapses to a single `mypy src` gate that fails the build on any
+  type error. The `tests/unit/test_typing.py` regression test is
+  likewise simplified to one whole-package check. 31 errors fixed in
+  this final tranche: 20 stale `# type: ignore` comments (made
+  redundant when the optional heavy dependencies were added to the
+  mypy `ignore_missing_imports` override), four deliberate engine-
+  method `# type: ignore[override]` annotations (the concrete
+  engine wrappers refine the permissive `**kwargs` signatures of
+  their `DockingEngine` / `MDEngine` / `GenerativeEngine` abstract
+  bases — an intentional, documented refinement that mypy's strict
+  Liskov check cannot model), `cast`s for the opaque
+  `Simulation.engine_handle` inside the OpenMM wrapper and for the
+  unstubbed-dependency return values, and `Vina.dock`'s receptor
+  narrowing switched from `hasattr` to `isinstance` (a more correct
+  check that mypy can also narrow on).
+- **`molforge.ml` is now `mypy --strict` clean.** The ML subpackage
+  (sequence/structure featurization, protein-language-model
+  embeddings) joins the strict gate — eight strict-clean
+  subpackages in total, 51 source files. Six errors fixed: the four
+  numpy-widening `no-any-return`s in `embeddings.py` (resolved with
+  `cast`s), and two real type bugs in `structure_features.py` —
+  `pair_distances` and `pair_distance_features` declared
+  `atom_choice: str` but pass it to `distance_map`, which requires
+  the `Literal["ca","cb","heavy","all"]` the docstrings already
+  specify, and a coordinate feature array silently upcast to
+  float64 by a division. The `torch` and `transformers` (and
+  `colabfold`, `meeko`, `vina`) optional heavy dependencies, which
+  ship no type stubs, are added to the mypy `ignore_missing_imports`
+  override alongside the existing `Bio` / `biotite` / `mdtraj` /
+  `openmm` / `rdkit` entries. CI strict gate and the
+  `tests/unit/test_typing.py` regression test updated; only
+  `plugins` and `wrappers` remain outside the gate.
+- **Six more subpackages are now `mypy --strict` clean.**
+  `molforge.io`, `molforge.sequence`, `molforge.structure`,
+  `molforge.metrics`, `molforge.ensembles`, and
+  `molforge.validation` now pass `mypy --strict` with zero errors,
+  joining `molforge.core` — seven strict-clean subpackages in total,
+  46 source files. The 12 errors fixed were mostly numpy operations
+  mypy widens to `Any` (resolved with explicit `cast`s that document
+  the known array dtype) and two stale `type: ignore` comments; two
+  were genuine annotation bugs — `_place_hydrogens` in `dssp.py` was
+  declared to return a single array but actually returns a
+  `(coords, mask)` tuple, and `_score` in `alignment.py` was
+  declared `NDArray[np.int_]` but builds an `int32` array (`np.int_`
+  is `int64` on 64-bit platforms). The CI strict gate now covers all
+  seven subpackages; the regression test
+  (`tests/unit/test_typing.py`, moved up from `tests/unit/core/` and
+  parametrized) checks each one in-suite. The remaining subpackages
+  (`ml`, `plugins`, `wrappers`) are still tracked by the
+  non-blocking informational `mypy src` CI step.
+- **`molforge.core` is now `mypy --strict` clean, and CI enforces
+  it.** The `core` subpackage — the data model the rest of the
+  library is built on — now passes `mypy --strict` with zero
+  errors (fixed: two missing `NDArray` type arguments in
+  `AtomArray`, an `Any`-return in `Atom.coord`, and an untyped
+  `Chain.__iter__` that was suppressed with a `type: ignore`). The
+  CI `typecheck` job now runs `mypy --strict src/molforge/core/`
+  as a hard gate, with a separate non-blocking full-tree `mypy src`
+  step that keeps the remaining (out-of-`core`) type errors visible
+  while they're worked through. A new `slow`-marked regression test
+  (`tests/unit/core/test_typing.py`) runs the strict check in-suite
+  so a `core` type regression is caught locally too.
+
+### Documented
+- **`Simulation.engine_handle` contract clarified.** The attribute
+  type (`object | None`) is correct — it really is an opaque,
+  engine-specific handle — but the contract was under-specified.
+  The docstring now states explicitly that `engine_handle` is
+  engine-private (callers must not inspect it or set it), is **not
+  serialized** (it typically wraps unpicklable C-extension state;
+  persistence layers must drop it and let the engine wrapper
+  rebuild it on resume), and carries **no semver guarantee**. For
+  inspectable per-simulation data, `Simulation.metadata` is the
+  supported field. No code change. Flagged by the API audit.
+
+### Deprecated
+- **`molforge.wrappers.folding.Rosetta` is now a deprecated alias
+  for `RoseTTAFold`.** The original `rosetta.py` placeholder was
+  ambiguous about whether it referred to PyRosetta (the Baker lab's
+  classical sequence-design library) or RoseTTAFold (the deep-
+  learning model). The new real wrapper lives at
+  `RoseTTAFold` for clarity. `Rosetta` is retained as a thin
+  subclass that emits `DeprecationWarning` on construction so
+  existing imports / isinstance checks keep working through the
+  next minor release. A PyRosetta wrapper, if added, would live in
+  a separate module (`pyrosetta.py`) since PyRosetta's surface is
+  much wider than the `FoldingEngine` contract.
+
 ### Removed
 - **`tests/unit/core/test_core_types.py`.** A pre-existing fossil
   from before the view-based data-model refactor: it imported from