feat(protonpotts): protonpotts_features wave graded pass by record; P4d (spec §40)

.github/workflows/ci.yml

@@ -27,6 +27,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       PYTHONDONTWRITEBYTECODE: 1
+      # requires-python is ">=3.13" with no upper bound, so uv otherwise resolves CPython 3.15, which torch has no wheel for.
+      UV_PYTHON: "3.13"
     steps:
       - uses: actions/checkout@v4
         with:

.github/workflows/pages.yml

@@ -1,9 +1,14 @@
-name: Deploy browser ProteinMPNN demo
+name: Deploy browser demos (ProteinMPNN + ProtonPotts)
 
 # Manual dispatch ONLY. Publishing model weights (when
-# AMINX_MODELS_RELEASE_TAG is set) is a deliberate act, not something a push
-# to main should trigger silently -- see the redistribution-rights note on
-# the "Fetch released model weights" step below.
+# AMINX_MODELS_RELEASE_TAG or AMINX_PROTONPOTTS_MODELS_RELEASE_TAG is set) is a
+# deliberate act, not something a push to main should trigger silently -- see
+# the redistribution-rights notes on the "Fetch released" steps below.
+#
+# One workflow deploys both sub-sites: the ProteinMPNN demo at the site root and
+# the ProtonPotts demo at /protonpotts/. Both come out of ONE build invocation
+# (tools/build_site.py), so the allow-lists and the import rewrites are checked
+# together and a refusal publishes nothing.
 on:
   workflow_dispatch:
 
@@ -25,12 +30,9 @@ jobs:
       # No node, no npm, no install step: the page loads site/*.mjs and
       # site/*.js as written, so assembling the site is a copy with an
       # allow-list (tools/build_site.py). python3 is already on the runner.
-      - name: Verify the site allow-list matches the tree
+      - name: Verify the site allow-lists match the tree
         run: python3 tools/build_site.py --check
 
-      - name: Build the site (no model weights yet)
-        run: python3 tools/build_site.py --out dist
-
       # 🔴 WEIGHTS REDISTRIBUTION IS A DELIBERATE, OPT-IN ACT. ProteinMPNN's
       # checkpoint license must be confirmed to cover public redistribution
       # via GitHub Pages BEFORE this variable is ever set -- do not set
@@ -45,11 +47,60 @@ jobs:
           mkdir -p models
           gh release download "${{ vars.AMINX_MODELS_RELEASE_TAG }}" \
             -p 'p07_sample_L*.onnx' -D models/
-          # Rebuild WITH the fetched weights; --models-dir only ever copies
+          # The build below passes --models-dir models; it only ever copies
           # the two exact filenames tools/build_site.py allow-lists
           # (p07_sample_L128.onnx / p07_sample_L256.onnx), never a stray
           # *.onnx.data.
-          python3 tools/build_site.py --out dist --models-dir models
+
+      # 🔴 PROTONPOTTS WEIGHTS: the same redistribution rule as above, and in
+      # addition the ProtonPottsMPNN checkpoint license must be confirmed to
+      # cover public redistribution BEFORE AMINX_PROTONPOTTS_MODELS_RELEASE_TAG
+      # is set. Three tarballs are expected on that release, one per kind:
+      # protonpotts-scoring.tar, protonpotts-ph.tar, protonpotts-decoder.tar.
+      # Each is extracted into pp_models/<kind>/, where tools/build_site.py
+      # reads its MANIFEST.json and copies only the files that manifest names.
+      - name: Fetch released ProtonPotts weights
+        if: ${{ vars.AMINX_PROTONPOTTS_MODELS_RELEASE_TAG != '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PP_TAG: ${{ vars.AMINX_PROTONPOTTS_MODELS_RELEASE_TAG }}
+        run: |
+          mkdir -p pp_downloads
+          for kind in scoring ph decoder; do
+            asset="protonpotts-${kind}.tar"
+            dest="pp_models/${kind}"
+            mkdir -p "$dest"
+            gh release download "$PP_TAG" -p "$asset" -D pp_downloads/
+            # --no-same-owner: the archive is ours, but extract it as the
+            # runner user regardless of what it recorded.
+            tar -xf "pp_downloads/$asset" -C "$dest" --no-same-owner
+            if [ ! -f "$dest/MANIFEST.json" ]; then
+              echo "::error::$asset did not contain $dest/MANIFEST.json after extraction"
+              exit 1
+            fi
+          done
+
+      # ONE build. Each flag appears only when its weights were fetched above:
+      # --models-dir for the ProteinMPNN tag, and the three --protonpotts-*-dir
+      # flags together for the ProtonPotts tag. With neither tag set, this is the
+      # bare build and the pages report missing models at runtime, as before.
+      - name: Build the site
+        env:
+          MPNN_FETCHED: ${{ vars.AMINX_MODELS_RELEASE_TAG != '' }}
+          PP_FETCHED: ${{ vars.AMINX_PROTONPOTTS_MODELS_RELEASE_TAG != '' }}
+        run: |
+          args=(--out dist)
+          if [ "$MPNN_FETCHED" = "true" ]; then
+            args+=(--models-dir models)
+          fi
+          if [ "$PP_FETCHED" = "true" ]; then
+            args+=(
+              --protonpotts-scoring-dir pp_models/scoring
+              --protonpotts-ph-dir pp_models/ph
+              --protonpotts-decoder-dir pp_models/decoder
+            )
+          fi
+          python3 tools/build_site.py "${args[@]}"
 
       # No release tag configured: point the built site at a remote model
       # base instead of shipping weights inline (e.g. a release asset URL,
@@ -76,6 +127,30 @@ jobs:
         env:
           AMINX_MODEL_BASE_URL: ${{ vars.AMINX_MODEL_BASE_URL }}
 
+      # The ProtonPotts analogue of the step above, for the built
+      # dist/protonpotts/config.js. Gated on its own remote base and on NO
+      # ProtonPotts release tag, for the same reason: a locally bundled weight
+      # set must not be pointed away from.
+      - name: Point the built ProtonPotts site at a remote model base
+        if: ${{ vars.AMINX_PROTONPOTTS_MODELS_RELEASE_TAG == '' && vars.AMINX_PROTONPOTTS_MODEL_BASE_URL != '' }}
+        run: |
+          python3 - "$AMINX_PROTONPOTTS_MODEL_BASE_URL" <<'PY'
+          import sys
+          from pathlib import Path
+          base_url = sys.argv[1]
+          path = Path("dist/protonpotts/config.js")
+          text = path.read_text(encoding="utf-8")
+          rewritten = text.replace(
+              'export const MODEL_BASE = "./models";',
+              f'export const MODEL_BASE = {base_url!r};',
+          )
+          if rewritten == text:
+              raise SystemExit("dist/protonpotts/config.js did not contain the expected MODEL_BASE line")
+          path.write_text(rewritten, encoding="utf-8")
+          PY
+        env:
+          AMINX_PROTONPOTTS_MODEL_BASE_URL: ${{ vars.AMINX_PROTONPOTTS_MODEL_BASE_URL }}
+
       - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/parity-audit.yml

@@ -11,6 +11,8 @@ jobs:
     env:
       PYTHONDONTWRITEBYTECODE: 1
       PRXTEIN_PARITY_TIER: parity_audit
+      # requires-python is ">=3.13" with no upper bound, so uv otherwise resolves CPython 3.15, which torch has no wheel for.
+      UV_PYTHON: "3.13"
     steps:
       - name: Checkout Aminx repository
         uses: actions/checkout@v4

.github/workflows/parity.yml

@@ -12,6 +12,8 @@ jobs:
     env:
       PYTHONDONTWRITEBYTECODE: 1
       PRXTEIN_PARITY_TIER: parity_heavy
+      # requires-python is ">=3.13" with no upper bound, so uv otherwise resolves CPython 3.15, which torch has no wheel for.
+      UV_PYTHON: "3.13"
     steps:
       - name: Checkout Aminx repository
         uses: actions/checkout@v4

.praxia/docs/INDEX.md

@@ -25,6 +25,7 @@
 
 ## Specs
 - [261007_potts-onnx-export-scope](specs/261007_potts-onnx-export-scope.md) — Scope, phase plan and acceleration levers for shipping Potts-family ONNX exports, reusing the ProteinMPNN split-export process
+- [261007_protonpottsmpnn-support](specs/261007_protonpottsmpnn-support.md) — V1 scope (inference + design) for porting ProtonPottsMPNN into aminx, with the atomworks featurization re-scoped as a front end rather than a feature algebra, and a decision rule for when tensor-level parity is required versus whole-pipeline agreement
 - [261006_aminx-cisternal-cutover](specs/261006_aminx-cisternal-cutover.md) — Make aminx agent-native through cisternal: a manifest-driven plugin bundle of targeted skills (using-aminx router + five task skills), an aminx-mcp server wired with @cisternal.tool over host.runner (launched via uvx by default, switchable to a local venv), cisternal provenance/telemetry for campaign runs; the Typer-to-cyclopts CLI port is deferred.
 - [261006_runner-length-bucketing-xtrax-adoption](specs/261006_runner-length-bucketing-xtrax-adoption.md) — The core runner trims each batch from the loader's max_length to the smallest xtrax BUCKET_LADDER rung that covers it, then re-pads the outputs. On by default, with length_bucketing=False to opt out. Also retires the private bucket ladders and dead xtrax duplicates, and adopts device_memory_budget and loop_scaling. Closes
 - [261002_streaming-xtrax-migration-scope](specs/261002_streaming-xtrax-migration-scope.md) — Opus-tier scoping report (task 261002_streaming-xtrax-migration, debt #2421): premise check, current-state map, xtrax capability map, gap analysis, target architecture, preemption/resume design, staged plan, asks of xtrax, decisions. Includes the verified reuse-safety defect in the campaign row hash.
@@ -95,6 +96,7 @@
 
 ## Decisions
 - [261008_per-row-closure-staleness](decisions/261008_per-row-closure-staleness.md) — Ledger rows go stale only when a changed path is in that row's import closure, not on any scoped-prefix change; fail-safe rules, declared edges, and a run-time loaded-files check.
+- [261008_protonpottsmpnn-v1-scope](decisions/261008_protonpottsmpnn-v1-scope.md) — What ProtonPottsMPNN V1 ships (score:energy/ddg/selectivity and pH design on the Potts energy), what is refused and tracked as debt, and the choices that put it in the ledger as one combined vehicle.
 - [261005_tiling-plan-discarded-stage2-2371](decisions/261005_tiling-plan-discarded-stage2-2371.md) — Measured evidence that BatchPlanner says Vmap+Bucket for the sample axes while execution is a Python loop, plus the T2.GATE blocker on deleting aminx's duplicate strategy types
 - [261004_laser-pdb-output-scope](decisions/261004_laser-pdb-output-scope.md) — Decision request: upstream LASEr writes PDBs through backbone N-H imputation, titratable-H cleanup with a geometric H-bond detector, and probability B-factors -- none of which the spec names; choose minimal writer vs full parity port
 - [261004_sample-dist-pilot-fixtures-and-low-t](decisions/261004_sample-dist-pilot-fixtures-and-low-t.md) — Decision request before the Potts sample_dist pilot runs: spec names no pssm or tied fixture, and the T=0.1 near-margin control looks unworkable (as with ProteinMPNN 260929)

.praxia/docs/decisions/261008_protonpottsmpnn-v1-scope.md

@@ -0,0 +1,74 @@
+---
+title: ProtonPottsMPNN V1 -- scope, the 30-token vocabulary, and how it enters the redsox gate
+description: What ProtonPottsMPNN V1 ships (score:energy/ddg/selectivity and pH design on the Potts energy), what is refused and tracked as debt, and the choices that put it in the ledger as one combined vehicle.
+status: accepted
+task_id: 261008_protonpotts-p10
+date: '261008'
+supersedes: ''
+backlog_ids: '5781'
+---
+# ProtonPottsMPNN V1 -- scope, the 30-token vocabulary, and how it enters the redsox gate
+
+Spec: `.praxia/docs/specs/261007_protonpottsmpnn-support.md` (sections 42-51). Implementation: PR #211.
+
+## Decisions
+
+Taken by the user over 261007-261008 (each is quoted from the session where it was made, in the spec's section 11 and
+sections 42-49):
+
+1. **Protonation labels are consumed, not assigned** (spec 11a). aminx reads pre-assigned labels from a JSON file; the
+   end-to-end labeller (HBPLUS binary plus a FLAML ensemble) is out of scope.
+2. **The pH design engine is in V1** (11b), restricted to block descent and the centre-free greedy on the Potts energy.
+   MCMC, two-phase and Gibbs methods are refused naming debt #2616; decoder-backed design and the 30-token decoder are
+   refused naming #2617; upstream knobs that are not exposed are #2621; known gaps of the pH surface are #2622;
+   ProteinSMC kernels for the Potts-head families are #2615.
+3. **Each inference path declares its alphabet** (11c). The v6 vocabulary is 30 tokens and is a property of the path,
+   not a module constant; result arrays carry a `vocabulary` attribute, and aminx's token order differs from upstream's.
+4. **Own options class**: `ProtonPottsOptions`, not `PottsMPNNOptions`, most of whose knobs do not apply.
+5. **No fallback to stock MPNN.** A purpose the driver does not run is refused.
+
+## Decided in P10, flagged for reversal
+
+6. **One combined ledger vehicle, `protonpotts_parity`, not seven rows.** The seven waves share sealed dumps, so a row per
+   wave would multiply manifest rows (47 either way: each control is a row) without adding independence. The vehicle
+   runs the waves unchanged as subprocesses and reports controls as `<wave>.<control>`. The cost: a change that stales
+   one wave re-runs all seven (minutes of CPU, not hours).
+7. **The wave scripts and the checkpoint converter moved from `scripts/protonpotts/` to `scripts/parity/`.** The closure
+   scanner only reads `src/` and `scripts/parity/`, and the `scripts/protonpotts/` tree is unscoped, so leaving them
+   there would have put the measuring code outside the row's closure. Earlier graded runs keep their records under the
+   old paths; only path strings in the moved files changed.
+8. **The `protonpottsmpnn_` weights arm is inert** like the two it joins (no vehicle slug carries the prefix). Adding it
+   follows the spec; tightening it would be a separate decision about a pre-registered criterion.
+9. **Known gap, not closed:** `scripts/convert_weights.py` (loaded by the converter) is outside every scoped prefix, so
+   editing it cannot stale the row. The converted weights are still pinned by the checkpoint sha and graded against
+   upstream whenever the row runs.
+10. **`block_zscales` maps its blocks through xtrax, and L-DRV gets no new allowlist reason.** An earlier P10 draft added a
+    `memory_bounded_map` reason for the one carry-free `lax.scan` in `block_zscales`. The user asked for it to be composed in
+    xtrax instead (261009): the block axis is an `AxisSpec`, `plan_axis_strategy` chooses a vmap or tiles of it from the
+    memory budget (each block holds a V^B joint), and `make_axis_dispatch_via_xtrax` builds the map, padding a ragged last
+    tile and slicing the padding off before the pool. The three genuinely sequential loops keep `sequential_dependency`.
+    The axis is declared in `ph_descent.py`, not `aminx/tiling/axes.py`, because the host runner imports that registry
+    and an edit there would stale every row; move it there with the next wave that touches shared files.
+
+## Consequences
+
+- Every existing ledger row's closure includes `host/runner.py` and `run/`, which P8 edited, so all eight are stale and
+  the final `launch_wave.sh --stale-only` re-wave re-runs them with the ninth row.
+- `record_trajectory` is accepted and changes nothing (trajectories are not recorded); its knob test says so.
+- Three families now sit in `tests/knob_gate`: 50 alias rows and 23 knob-semantics tests cover ProtonPottsMPNN, and the
+  closure self-test pins that a Potts change reaches the ProtonPotts row, never the reverse, and that no family reaches LASEr.
+
+## Decided 261009 (user): browser shape and the decoder
+
+11. **pH design in the browser is a per-block graph driven by a JS loop**, not one sweep graph. Block descent is a host-side
+    sweep over placement blocks on the Potts energy; each block's conditional energy is one loop-free graph call and JS owns
+    the sweep, the convergence test and the injected uniforms. This follows the Potts export lesson (no in-graph `Loop`/`Scan`:
+    control flow forces device copies on WebGPU, and the monolith was abandoned for the split in the ProteinMPNN export). Graded
+    by the same ladder as scoring: export gate (ORT-CPU/ORT-Web), Node loop gate against the real driver, headless Chromium gate.
+12. **The 30-token decoder is implemented now (debt #2617)**, ahead of the remaining browser work. It is the shared blocker for
+    plain ProtonPotts `sample`, the decoder-backed pH methods (`autoregressive`, `mpnn_sample`, `selective_source='decoder'`, the
+    whole-chain `gibbs` baseline, `backend='mpnn'`) and a browser sampler. Order: upstream oracle dump (draw-shimmed AR step, as the
+    Potts and LASEr oracles did) -> port and grade the V=30 decoder -> driver `sample` path -> decoder-backed pH methods ->
+    browser export. Each step is a pre-registered wave with negative controls; no tolerance is widened.
+13. **Browser work is sequenced behind its blockers**, not built speculatively: per-block pH graph first (needs nothing new),
+    decoder graphs after the decoder is graded.