fix(packaging): enforce release artifact contract

Ship only the approved generated SN2 reference resource and make its provenance and integrity explicit. Require configured roots for scientific data that cannot be redistributed.

Validate wheel and sdist allowlists, rebuild from the sdist, and smoke-test the installed package before publication.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: ericchansen

.gitattributes

@@ -0,0 +1,5 @@
+q2mm/data/sn2/*.json text eol=lf
+q2mm/data/sn2/*.txt text eol=lf
+q2mm/data/sn2/*.xyz text eol=lf
+q2mm/data/sn2/*.npy -text
+q2mm/data/sn2/*.npz -text

.github/workflows/publish.yml

@@ -26,6 +26,9 @@ jobs:
       - name: Build sdist and wheel
         run: python -m build
 
+      - name: Validate artifact and installed-data contracts
+        run: python scripts/check_release_artifacts.py --dist-dir dist
+
       - name: Verify version matches tag
         run: |
           TAG="${GITHUB_REF#refs/tags/v}"

.gitignore

@@ -5,7 +5,7 @@ psi4_generation.log
 psi*.clean
 
 # ── Generated Psi4 logs (large, regenerated by generate_qm_data.py) ──
-examples/sn2-test/qm-reference/psi4-output*.dat
+examples/sn2-test/psi4-output*.dat
 examples/rh-enamide/psi4_reference/
 
 # ── External validation data (large, not redistributable) ──

MANIFEST.in

@@ -0,0 +1,24 @@
+include LICENSE
+include README.md
+include pyproject.toml
+graft q2mm
+
+prune .copilot
+prune .github
+prune .vscode
+prune docs
+prune examples
+prune scripts
+prune test
+prune validation
+
+exclude .gitignore
+exclude .gitattributes
+exclude .pre-commit-config.yaml
+exclude AGENTS.md
+exclude CHANGELOG.md
+exclude CONTRIBUTING.md
+exclude properdocs.yml
+
+global-exclude *.py[cod]
+global-exclude __pycache__

docs/getting-started.md

@@ -37,6 +37,31 @@ cd q2mm
 pip install -e ".[dev]"            # editable install with dev tools
 ```
 
+### External data for published systems
+
+Q2MM does not distribute the licensed or third-party datasets used by the
+published transition-state systems. Configure their locations before running
+those systems:
+
+| Variable | Required by | Value |
+|----------|-------------|-------|
+| `Q2MM_RH_ENAMIDE` | Rh-enamide | Directory containing `mm3.fld` and `rh_enamide_training_set/` |
+| `Q2MM_SUPPORTING_INFO` | Heck relay; Pd/Rh conjugate; Pd-allyl | Root of the extracted Wahlers/Rosales supporting information |
+| `Q2MM_MM3_BASE` | Pd-allyl; Pd/Rh conjugate | Licensed `mm3_base.fld` file |
+
+For example, in Bash:
+
+```bash
+export Q2MM_RH_ENAMIDE=/path/to/q2mm/examples/rh-enamide
+export Q2MM_SUPPORTING_INFO=/path/to/q2mm/validation/supporting-info
+export Q2MM_MM3_BASE=/path/to/mm3_base.fld
+```
+
+In PowerShell, use `$env:Q2MM_RH_ENAMIDE = "..."` (and likewise for the
+other variables). Missing or invalid roots raise an error naming the exact
+variable or `ExternalDataRoots` field to configure; Q2MM never searches above
+the installed package.
+
 ---
 
 ## QM/MM backends
@@ -72,14 +97,15 @@ cd q2mm
 ```python
 from q2mm.io import GaussLog, load_mm3_fld
 from q2mm.models import Q2MMMolecule
+from q2mm.resources import sn2_reference_dir
 
 # Parse a Gaussian log for the QM Hessian (matrix of energy second derivatives)
 log = GaussLog("examples/ethane/TS.log")
 structure = log.structures[0]
 print(f"Atoms: {structure.num_atoms}, Hessian shape: {structure.hess.shape}")
 
 # Load an XYZ geometry into the unified molecule model
-mol = Q2MMMolecule.from_xyz("examples/sn2-test/qm-reference/ch3f-optimized.xyz")
+mol = Q2MMMolecule.from_xyz(sn2_reference_dir() / "ch3f-optimized.xyz")
 print(f"Q2MMMolecule atoms: {mol.n_atoms}")
 
 # Load an MM3 force field
@@ -105,4 +131,3 @@ q2mm/
 1. Follow the [Tutorial](tutorial.md) for a complete parameterization walkthrough
 2. Read [Theory & Methods](how-it-works/theory.md) to understand the pipeline
 3. See [Platform Support](platform-support.md) for GPU and backend setup
-

docs/how-it-works/architecture.md

@@ -192,6 +192,8 @@ q2mm/
 ├── constants.py          # Physical constants
 ├── elements.py           # Periodic table data
 ├── geometry.py           # Geometry helpers (distances, angles, alignment)
+├── resources.py          # Installed scientific-resource lookup and integrity checks
+├── data/sn2/             # Approved CH3F/SN2 package resource + provenance manifest
 ├── benchmark_runner.py   # Canonical convergence benchmark runner (backs q2mm.benchmark)
 ├── systems.py            # Benchmark system registry (SYSTEMS, SystemData, load_system)
 │
@@ -270,6 +272,30 @@ q2mm/
     └── tables.py         # Formatted table output
 ```
 
+### Release and scientific-data boundary
+
+Q2MM's release artifacts use an explicit data contract:
+
+- Wheels contain Python modules, `py.typed`, distribution metadata, and only
+  the generated CH3F/SN2 resource in `q2mm/data/sn2/`.
+- Source distributions contain only the inputs needed to build that wheel.
+  Tests, examples, documentation, workflows, validation data, and raw
+  third-party outputs are repository-only.
+- `q2mm.resources.sn2_reference_dir()` resolves the built-in data through
+  `importlib.resources`, so source checkouts and installed wheels use the same
+  canonical files. `manifest.json` records provenance, license, size, and
+  SHA-256 for every scientific payload file.
+- Rh-enamide, dissertation supporting information, and the licensed MM3 base
+  force field are not distributed. Pass `ExternalDataRoots` to
+  `load_system(data_roots=...)`, or configure `Q2MM_RH_ENAMIDE`,
+  `Q2MM_SUPPORTING_INFO`, and `Q2MM_MM3_BASE`. Loaders never search above the
+  installed package or substitute a tracked force field.
+
+The publish workflow runs `scripts/check_release_artifacts.py` before upload.
+It validates both manifests, rebuilds the wheel from the sdist, compares wheel
+payloads, installs the rebuilt wheel into a clean environment, and exercises
+the import, CLI, resource integrity, and built-in CH3F system.
+
 ### Dependency flow
 
 ```mermaid

docs/systems/heck-relay.md

@@ -179,6 +179,10 @@ Heck relay identifies a cross-engine boundary for literature transfer that canno
 
 ## Reproduce
 
+Configure `Q2MM_SUPPORTING_INFO` as described in
+[External data for published systems](../getting-started.md#external-data-for-published-systems)
+before running this command.
+
 ```bash
 python -m q2mm.diagnostics.cli --system heck-relay --backend jax --optimizer optax-adam-cosine
 ```

docs/systems/pd-allyl.md

@@ -144,6 +144,10 @@ The negative R² reflects incomplete composed-force-field transfer, not a proble
 
 ## Reproduce
 
+Configure both `Q2MM_SUPPORTING_INFO` and `Q2MM_MM3_BASE` as described in
+[External data for published systems](../getting-started.md#external-data-for-published-systems)
+before running this command.
+
 ```bash
 python -m q2mm.diagnostics.cli --system pd-allyl --backend jax --optimizer optax-adam-cosine
 ```

docs/systems/pd-conjugate.md

@@ -143,6 +143,10 @@ The negative R² reflects a transfer gap in the composed FF workflow.
 
 ## Reproduce
 
+Configure both `Q2MM_SUPPORTING_INFO` and `Q2MM_MM3_BASE` as described in
+[External data for published systems](../getting-started.md#external-data-for-published-systems)
+before running this command.
+
 ```bash
 python -m q2mm.diagnostics.cli --system pd-conjugate --backend jax --optimizer optax-adam-cosine
 ```

docs/systems/rh-conjugate.md

@@ -158,6 +158,10 @@ The negative R² reflects a real transfer gap in the composed FF workflow.
 
 ## Reproduce
 
+Configure both `Q2MM_SUPPORTING_INFO` and `Q2MM_MM3_BASE` as described in
+[External data for published systems](../getting-started.md#external-data-for-published-systems)
+before running this command.
+
 ```bash
 python -m q2mm.diagnostics.cli --system rh-conjugate --backend jax --optimizer optax-adam
 ```