Release 0.9.8: Tiny PyPI sdist, reviewed model objectives, and formula-faithful contracts

.github/workflows/tests.yml

@@ -38,6 +38,9 @@ jobs:
       matrix:
         include:
           - {python: "3.11", shard: 0}
+          - {python: "3.11", shard: 1}
+          - {python: "3.11", shard: 2}
+          - {python: "3.11", shard: 3}
           - {python: "3.12", shard: 0}
           - {python: "3.12", shard: 1}
           - {python: "3.12", shard: 2}
@@ -68,33 +71,23 @@ jobs:
         if: matrix.python == '3.12' && matrix.shard == 0
         run: python scripts/check_lint.py
       - name: Test numerical kernels and experiment workflows
-        if: matrix.python == '3.12'
         run: >-
           python scripts/ci_pytest.py run --index ${{ matrix.shard }} --count 4
-          --receipt /tmp/pytest-shard-${{ matrix.shard }}.json --
-          -q --durations=25 -o faulthandler_timeout=600
-          --ignore=tests/test_e22_routed_caption_late_phase_renderer.py
-      # The minimum supported Python runs one deterministic quarter of the same
-      # suite. Its receipt stays local: release coverage is checked on 3.12.
-      - name: Test one suite shard on the minimum supported Python
-        if: matrix.python == '3.11'
-        run: >-
-          python scripts/ci_pytest.py run --index ${{ matrix.shard }} --count 4
-          --receipt /tmp/pytest-py311-shard-${{ matrix.shard }}.json --
+          --receipt /tmp/pytest-${{ matrix.python }}-shard-${{ matrix.shard }}.json --
           -q --durations=25 -o faulthandler_timeout=600
           --ignore=tests/test_e22_routed_caption_late_phase_renderer.py
       - name: Save collection coverage receipt
-        if: always() && matrix.python == '3.12'
+        if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: pytest-shard-${{ matrix.shard }}
-          path: /tmp/pytest-shard-${{ matrix.shard }}.json
+          name: pytest-${{ matrix.python }}-shard-${{ matrix.shard }}
+          path: /tmp/pytest-${{ matrix.python }}-shard-${{ matrix.shard }}.json
           if-no-files-found: error
       - name: Test bounded late-phase renderer in a fresh process
-        if: matrix.python == '3.12' && matrix.shard == 0
+        if: matrix.shard == 0
         run: timeout --signal=INT --kill-after=5s 60s python -m pytest -q tests/test_e22_routed_caption_late_phase_renderer.py
       - name: Exercise the complete Lunar pipeline and GIF exports
-        if: matrix.python == '3.11'
+        if: matrix.python == '3.11' && matrix.shard == 0
         env:
           SDL_VIDEODRIVER: dummy
         run: python -u examples/fast_lander.py --smoke --out /tmp/lunar-smoke
@@ -217,9 +210,42 @@ jobs:
           PY
           /tmp/particlegan-base-env/bin/python -m particlegan_forge --help
 
+  minimum-base:
+    name: Minimum base dependencies / Python 3.11
+    if: >-
+      github.event_name != 'workflow_dispatch' ||
+      github.ref == 'refs/heads/develop' ||
+      github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      CUDA_VISIBLE_DEVICES: ""
+      OMP_NUM_THREADS: "1"
+      MKL_NUM_THREADS: "1"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_ref || github.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install exact minimum base versions
+        run: |
+          python -m pip install 'torch==2.6.0' --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install 'numpy==1.26.0'
+      - name: Build and install the base wheel without experiment extras
+        run: |
+          python -m pip wheel --no-deps . --wheel-dir /tmp/minimum-wheel
+          python -m pip install --no-deps /tmp/minimum-wheel/*.whl
+          python -m pip check
+          cp scripts/base_compatibility_smoke.py /tmp/particlegan-minimum-smoke.py
+      - name: Check public API and exact checkpoint continuation outside checkout
+        working-directory: /tmp
+        run: python /tmp/particlegan-minimum-smoke.py
+
   distributions:
     name: Build release distributions
-    needs: [cpu-tests, base-wheel]
+    needs: [cpu-tests, base-wheel, minimum-base]
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -233,11 +259,13 @@ jobs:
         run: python -m pip install build twine
       - uses: actions/download-artifact@v4
         with:
-          pattern: pytest-shard-*
+          pattern: pytest-*-shard-*
           path: /tmp/pytest-shards
           merge-multiple: true
       - name: Require complete nonoverlapping regression coverage
-        run: python scripts/ci_pytest.py check /tmp/pytest-shards/*.json
+        run: |
+          python scripts/ci_pytest.py check /tmp/pytest-shards/pytest-3.11-shard-*.json
+          python scripts/ci_pytest.py check /tmp/pytest-shards/pytest-3.12-shard-*.json
       - name: Build source archive and wheel
         run: python -m build
       - name: Keep research artifacts outside release distributions
@@ -247,17 +275,39 @@ jobs:
           import tarfile
           import zipfile
 
+          max_bytes = 600_000
           for wheel in Path('dist').glob('*.whl'):
+              assert wheel.stat().st_size < max_bytes, wheel.stat().st_size
               with zipfile.ZipFile(wheel) as archive:
-                  roots = {name.split('/')[0] for name in archive.namelist()}
+                  names = archive.namelist()
+                  roots = {name.split('/')[0] for name in names}
+                  license_path = next(name for name in names if name.endswith('.dist-info/licenses/LICENSE'))
+                  assert archive.read(license_path) == Path('LICENSE').read_bytes()
+                  metadata_path = next(name for name in names if name.endswith('.dist-info/METADATA'))
+                  metadata = archive.read(metadata_path).decode()
+                  assert 'License-Expression: MIT' in metadata
+                  assert 'License-File: LICENSE' in metadata
               # particlegan_forge is the documented external tier API (EXPERIMENTATION.md).
               packages = {'particlegan', 'particlegan_forge'}
               assert all(root in packages or root.endswith('.dist-info') for root in roots), roots
-          research = {'reports', 'results', 'experiments', 'benchmarks', 'lib', 'configs', 'data', 'runs', 'artifacts'}
+          excluded = {
+              'tests', 'reports', 'results', 'experiments', 'benchmarks', 'lib',
+              'configs', 'data', 'runs', 'artifacts', 'docs', 'examples', 'ops', 'scripts',
+          }
+          allowed_sdist_roots = {
+              'LICENSE', 'MANIFEST.in', 'PKG-INFO', 'README.md',
+              'particlegan', 'particlegan.egg-info', 'particlegan_forge',
+              'pyproject.toml', 'setup.cfg',
+          }
           for source in Path('dist').glob('*.tar.gz'):
+              assert source.stat().st_size < max_bytes, source.stat().st_size
               with tarfile.open(source) as archive:
-                  roots = {parts[1] for name in archive.getnames() if len(parts := name.split('/')) > 1}
-              assert not roots & research, roots & research
+                  names = archive.getnames()
+                  roots = {parts[1] for name in names if len(parts := name.split('/')) > 1}
+                  license_path = next(name for name in names if name.count('/') == 1 and name.endswith('/LICENSE'))
+                  assert archive.extractfile(license_path).read() == Path('LICENSE').read_bytes()
+              assert not roots & excluded, roots & excluded
+              assert roots <= allowed_sdist_roots, roots - allowed_sdist_roots
           PY
       - name: Validate package metadata and README
         run: python -m twine check --strict dist/*

.gitignore

@@ -161,3 +161,4 @@ dist/
 runs/prior-coulomb/
 /runs/prior-mmd/
 /runs/test_m3/
+/TODO.md

.ruff-baseline.json

@@ -46,21 +46,11 @@
         "`benchmarks.legacy.recipe.get_recipe` imported but unused": 1
       }
     },
-    "benchmarks/toy_audit/api_gaussian1d.py": {
-      "F401": {
-        "`.gaussian1d_quality` imported but unused": 1
-      }
-    },
     "benchmarks/toy_audit/api_model_ae_ddgan.py": {
       "F401": {
         "`.api_model_ddgan.task_recipe` imported but unused": 1
       }
     },
-    "benchmarks/toy_audit/api_run.py": {
-      "F401": {
-        "`textwrap` imported but unused": 1
-      }
-    },
     "benchmarks/toy_audit/api_sources/circle.py": {
       "F401": {
         "`torch.nn.functional` imported but unused": 1,
@@ -89,11 +79,6 @@
         "`copy.deepcopy` imported but unused": 1
       }
     },
-    "benchmarks/toy_audit/prior_proximal_smoke.py": {
-      "F821": {
-        "Undefined name `restored`": 1
-      }
-    },
     "benchmarks/toy_audit/proposal.py": {
       "F841": {
         "Local variable `result` is assigned to but never used": 1
@@ -232,16 +217,6 @@
         "`benchmarks.legacy.recipe.get_recipe` imported but unused": 1
       }
     },
-    "examples/e22_routed_caption_late_phase.py": {
-      "F821": {
-        "Undefined name `p`": 1
-      }
-    },
-    "examples/e22_routed_caption_untied.py": {
-      "F821": {
-        "Undefined name `p`": 1
-      }
-    },
     "examples/e22_routed_g_clean.py": {
       "F402": {
         "Import `time` from an earlier line shadowed by loop variable": 1
@@ -309,11 +284,6 @@
         "`collections.defaultdict` imported but unused": 1
       }
     },
-    "experiments/forge/runtime.py": {
-      "F401": {
-        "`os` imported but unused": 1
-      }
-    },
     "experiments/forge/scaling_profile.py": {
       "F401": {
         "`.contracts.stable_hash` imported but unused": 1
@@ -532,7 +502,7 @@
       },
       "F811": {
         "Redefinition of unused `checkout` from an earlier line: `checkout` redefined here": 5,
-        "Redefinition of unused `spec` from an earlier line: `spec` redefined here": 5
+        "Redefinition of unused `spec` from an earlier line: `spec` redefined here": 4
       }
     },
     "tests/test_forge_dispositions.py": {
@@ -550,7 +520,7 @@
       },
       "F811": {
         "Redefinition of unused `checkout` from an earlier line: `checkout` redefined here": 6,
-        "Redefinition of unused `spec` from an earlier line: `spec` redefined here": 4
+        "Redefinition of unused `spec` from an earlier line: `spec` redefined here": 3
       }
     },
     "tests/test_forge_family_documentation.py": {

AGENTS.md

@@ -40,6 +40,49 @@ sampling law. Check these against the qualified evidence before attributing a
 failure to a formulation change. Clean and noisy served results are separate
 cohorts; matching training settings alone does not make their gates comparable.
 
+**A faithful numerical FAIL is better evidence than a PASS obtained by changing
+the formula.** Keep these boundaries explicit in implementation, tests and reports:
+
+- The recipe owns every training update and intervention, including prior moves,
+  gradient transformations, controllers, regularizers and noise. Task hosts must
+  not add cluster fitting, particle placement, weight resets, auxiliary solvers,
+  surrogate gradients or other post-optimizer repairs to make a recipe pass.
+  A useful new mechanism needs its own public recipe capability, declared delta
+  and evidence identity before comparison.
+- Execute the exact resolved recipe. Never substitute a different preset,
+  schedule, prior, guard or noise policy to accommodate a host. Implement the
+  missing capability or report BLOCKED; do not silently drop the mechanism.
+- Evaluate the object and law named by the question: a neural-imputer test must
+  call that neural imputer; no-posterior-resampling means no fallback to posterior
+  resampling. Live, EMA, averaged and clean/noisy serving are separate contracts.
+  Record the observed sampler and resolved recipe, not just the requested labels.
+- Architecture and initialization belong to the task. Imports must not replace
+  shared model classes or change constructor defaults. Normalized, scaled,
+  identity-initialized and assisted variants need explicit separate task/cohort
+  identities. Custom backward functions must implement their declared derivative;
+  a surrogate update is a recipe mechanism, not an invisible architecture repair.
+- Checkpoint every behavior-changing state and consumed RNG stream, including
+  host caches, control flags, penalty clocks and actual EMA histories. Verify
+  continuation in a fresh object/process across mechanism activation boundaries;
+  reject incompatible old checkpoints rather than reconstructing missing history.
+- Keep numerical FAIL distinct from BLOCKED, ERROR, INVALID, INCOMPLETE, TIMEOUT
+  and unmeasured outcomes. A negative eligibility decision is not a numerical
+  failure. Diagnostic, assisted, adapted or incompatible-source results cannot
+  fill ordinary qualification or a selected recipe's matched comparison cells.
+- Preserve affected historical receipts byte for byte. Publish explicit,
+  source-bound scope corrections instead of rewriting old grades or presenting
+  old assisted passes as evidence for a corrected implementation. Keep one
+  current leaderboard and derive its current explanations from the same records.
+- Add semantic controls that would detect the wrong formula or evaluator:
+  forbidden-fallback checks, deliberate damage to the measured model, fresh-process
+  import-order checks and exact continuation checks. Passing software tests, an
+  oracle witness or a training GIF does not itself establish learned quality.
+
+Scientific superiority and default adoption also require accepted compatible
+calibration and independent confirmation. Keep unequal tuning budgets, selection
+tasks, untouched task-level holdouts and unresolved uncertainty visible; never
+manufacture calibration acceptance or run seed-only searches to improve a score.
+
 Toy tests must follow the [public-API test contract](reports/toy_audit/api_contract/README.md):
 execute through the ParticleGAN API, declare a numerical pass/fail metric, and
 provide an actual-training GIF that illustrates the test's goal. Reform an
@@ -50,3 +93,4 @@ Each agent can queue experiments on the GPUs without waiting for it to be free.
 
 ---
 develop->master PR should always exist and have a link to the up to date https://github.com/255BITS/ParticleGAN/blob/develop/reports/forge/technique-inventory.md
+master should always reflect whats in pypi

CHANGELOG.md

@@ -1,7 +1,31 @@
 # Changelog
 
-## Unreleased
-
+## 0.9.8 — 2026-11-09
+
+- **Tiny PyPI source distribution (`sdist`) and strict distribution gates.**
+  Prune non-package trees (`tests`, `reports`, `results`, `experiments`,
+  `benchmarks`, `lib`, `configs`, `data`, `runs`, `artifacts`, `docs`,
+  `examples`, `ops`, `scripts`) and workspace files via `MANIFEST.in`,
+  shrinking `particlegan-0.9.8.tar.gz` from `1.7 MB` (`7.14 MB` uncompressed)
+  to `~343 KiB` (`~373 KiB` wheel) and enforcing `< 600 KB` byte-size and root
+  allowlists in CI and packaging tests.
+- **Reviewed model objectives, pre-subtraction `NaN` masking, and public exports.**
+  Export `conditional_energy_score`, `joint_reconstruction_loss`,
+  `masked_mixture_nll`, `NeuralComponentImputer`, `masked_quantile_transport_loss`,
+  `EmulatedLinear`, and `emulate_linear_training_` from top-level `particlegan`.
+  Mask `observed` via `torch.where` before subtracting `components` in
+  `masked_mixture_nll` so unobserved `NaN` entries cannot contaminate gradients
+  when `observed.requires_grad` is `True`.
+- **Formula-faithful recipe admission, independent critic histories, and provenance.**
+  Enforce formula-faithful admission across vector, BiGAN, DDGAN, VAE-GAN, and
+  MisGAN hosts (including rejecting unsupported `model="ddgan"` and
+  `training_precision="bf16_channels_last"` settings on MisGAN hosts before
+  optimizer construction and isolating independent MisGAN critic histories),
+  separate faithful numerical `FAIL` from `BLOCKED`/`INCOMPLETE`/`UNMEASURED`
+  outcomes, and preserve byte-exact historical receipts with ancestral
+  source-binding verification
+  ([integration scope](reports/forge/reviewed-pr-integration-20261109/README.md),
+  [audit](reports/gpt-audit-2026-11-08.md)).
 - **Exact trainer checkpoint continuation with gradient response.** Save,
   validate and restore gradient-coherence history when enabled, preserving the
   next update in fresh and previously used trainers. Reject older enabled-response

EXPERIMENTATION.md

@@ -160,6 +160,16 @@ per-mode moments before another supported, bounded training hypothesis. No
 automatic matrix filling, tuning, seed study, continuation or promotion follows.
 
 The history, recall, compile, validate, and board commands launch no training.
+The alternate `ops/formulaic_coverage.py` executor is retired after the
+[2026-11-08 scientific audit](reports/gpt-audit-2026-11-08.md). It changed
+recipes and host update rules outside ordinary admission. Its old receipts
+remain source-bound diagnostic evidence; a reporting refresh must not repeat
+them or use them to qualify a corrected implementation. Use the frozen-study
+workflow above for new measurements. An unsupported public adapter remains
+BLOCKED, and a correctly measured numerical FAIL remains FAIL. The ownership,
+sampler, architecture and continuation boundaries in [AGENTS.md](AGENTS.md)
+apply to every execution path, including coverage diagnostics.
+
 Recall includes source-bound concluded configuration and policy publications as
 non-qualifying summaries. It returns compact source identity pins and a file
 count by default. Add `recall --full-provenance` when the complete source-file

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Martyn Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,20 @@
+prune tests
+prune reports
+prune results
+prune experiments
+prune benchmarks
+prune lib
+prune configs
+prune data
+prune runs
+prune artifacts
+prune docs
+prune examples
+prune ops
+prune scripts
+exclude .ruff-baseline.json
+exclude AGENTS.md
+exclude CLAUDE.md
+exclude EXPERIMENTATION.md
+exclude RESEARCH_GLOSSARY.md
+exclude TODO.md