pen-stack 6.9.1__tar.gz → 6.9.2__tar.gz

{pen_stack-6.9.1 → pen_stack-6.9.2}/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [6.9.2] - 2026-06-19 - WS-IMMUNE2 real-tool rigor pass (no proxies / no heuristics across the immune + writer axes)
+
+**PATCH — a top-to-bottom audit replacing every remaining proxy/heuristic in the immune & writer-design stack with
+the real on-VM tool (gold-standard, licensed) or an honest abstention. No silent fallbacks.** Triggered by the
+directive *"use the real on-VM tool. No proxy or heuristics … check previous versions too … re-confirm the MHC-I
+capsid axis against NetMHCpan-4.1."* All licensed binaries stay on the VM — only derived numbers are cached.
+
+### Changed
+- **MHC-I capsid axis re-grounded on NetMHCpan-4.1** (`pen_stack/planner/capsid_epitope_oracle.py`). The PRIMARY
+  capsid CD8 predictor is now the gold-standard licensed **NetMHCpan-4.1** (%Rank_EL≤0.5, residue coverage, 12-allele
+  panel; `configs/mhc_epitope_oracle.yaml` `mhc1`); the v5.3 **MHCflurry** value is kept as an explicit, reported
+  **cross-check** (never silently substituted). Both agree AAV is the least CD8-immunogenic capsid
+  (AAV `capsid_immune_score` 0.4585 NetMHCpan / 0.2803 MHCflurry — the predictor disagreement is surfaced, not hidden).
+- **ADA-risk re-grounded** (`pen_stack/planner/ada_risk.py`). `ada_risk = real NetMHCIIpan-4.0 density × foreignness`,
+  where **foreignness is the protein ORIGIN** (authoritative central-tolerance signal). Unknown origin / uncached
+  density now **ABSTAINS** (no k-mer guess, no heuristic) — replacing the v6.9.0 albumin-only self-tolerance
+  heuristic. The **real human-proteome 9-mer self-match** (computed on the VM over the full UniProt reference
+  proteome, 20 431 proteins / 10.4 M 9-mers) is reported as a cross-check: human albumin **1.0** (self), the
+  foreign writers (SpCas9/ISCro4/Bxb1) and capsids **0.0** (non-self) — clean self/non-self separation.
+- **MHC-II axis no longer falls back to a production proxy** (`pen_stack/planner/immune_mhc2.py`). `mhc2_epitope_load`
+  uses the real NetMHCIIpan-4.0 cache by antigen name and otherwise **abstains**; the documented promiscuous-binder
+  estimate is retained as `mhc2_proxy_estimate` for **offline triage only** (explicitly labelled, not the production axis).
+- **Real Bxb1 attB written** (`pen_stack/atlas/guide_design.py`). The PASTE/PASSIGE pegRNA 3′ extension now writes the
+  **real documented Bxb1 minimal attB** verbatim (FlyBase FBto0000359; Ghosh, Kim & Hatfull, Mol Cell 2003;
+  8-bp common core GCGGTCTC around the central GT crossover) instead of the schematic poly-G/poly-C arms. Integrases
+  without a bundled documented site expose only the central core (never a fabricated full sequence).
+- `pen_stack/planner/immune_profile.py` — the writer-as-antigen card surfaces `foreignness`, the real
+  `self_match_human_proteome` cross-check, and the MHC-II/ADA backends (was the removed `self_tolerance` field).
+
+### Honest deviations from the v6.9 pre-registration (`prereg/ws_immune2.yaml`)
+- The pre-registered "1 − self_match_fraction from a human-proteome k-mer filter" foreignness *fallback* is
+  **dropped**: foreignness is the authoritative origin, and an unknown origin abstains rather than imputing from a
+  k-mer match (the real self-match is reported only as a cross-check). This is a strictly more honest rule.
+
+### Data / tests
+- `configs/mhc_epitope_oracle.yaml` — corrected `self_match` (the v6.9.x cache had a FASTA-keying bug that collapsed
+  the 20 431-protein proteome to 1 protein, zeroing every self-match incl. albumin); recomputed correctly on the VM.
+- `tests/unit/{test_ws_immune2,test_ws_epitope,test_ws_writer,test_ws_rel}.py` updated for the abstain semantics,
+  the NetMHCpan-4.1 primary capsid value + MHCflurry cross-check, the real attB, and the 6.9.2 version pins.
+
 ## [6.9.1] - 2026-06-20 - Real NetMHCIIpan-4.0 / NetMHCpan-4.1 MHC epitope load (replaces the v6.9.0 proxy)
 
 **PATCH — rigour upgrade.** v6.9.0's MHC-II axis was a documented *heuristic proxy* (P1-anchor density). The

{pen_stack-6.9.1 → pen_stack-6.9.2}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 6.9.1
+version: 6.9.2
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.9.1 → pen_stack-6.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.9.1
+Version: 6.9.2
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -90,7 +90,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.9.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.9.2-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
@@ -161,16 +161,24 @@ are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that ga
   never distributed), with a documented promiscuous-binder proxy as the offline/CI fallback. Population-level proxy
   (🟡), never a patient-HLA magnitude. *(v6.9.0 used the heuristic proxy; the real tool is more discriminating —
   human-self albumin 0.066 vs foreign writers 0.11–0.15.)*
-- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, with a
-  **self-tolerance filter** (JanusMatrix-style: self epitopes are tolerated; foreign drive ADA). It **recovers
+- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, where
+  **foreignness is the protein ORIGIN** (the authoritative central-tolerance signal). It **recovers
   immunogenic-vs-tolerated**: the foreign writers (real UniProt SpCas9 / ISCro4 / Bxb1) score **above** the human
-  self control (albumin), even without the origin label (the k-mer self-match tolerates the human protein).
+  self control (albumin). The **real full-human-proteome 9-mer self-match** (computed on the VM, 20 431 proteins) is
+  reported as a cross-check (albumin 1.0 self, foreign writers 0.0).
 - **The writer as a distinct antigen** — the profile now carries a `writer_as_antigen` card and a
   `writer_dominant_risk` flag: for **non-viral delivery of a bacterial writer there is no capsid antigen, so the
   WRITER is the dominant immunogen** — the insight the capsid-only profile missed.
 - **Immuno-Bench** (`benchmarks/immuno/`) — the immunogenic-vs-tolerated recovery track + an honest `calibrate_axis`
   ADA pass (it stays 🟡 at public-data power — no manufactured ✅, the standing wet-lab bottleneck).
 
+**v6.9.2 — real-tool rigor pass (no proxies / no heuristics).** A top-to-bottom audit: the **MHC-I capsid axis is
+re-grounded on the gold-standard NetMHCpan-4.1** (MHCflurry kept as a reported cross-check); **ADA foreignness is the
+authoritative origin** and **abstains** when unknown (no k-mer guess); the MHC-II axis **abstains** rather than
+falling back to a production proxy (the promiscuous-binder estimate is offline-triage only); and the PASTE pegRNA
+writes the **real documented Bxb1 minimal attB** (FlyBase / Ghosh 2003) instead of a schematic. Real tool or honest
+abstention — never a silent fallback.
+
 Real UniProt sequences only (no fabricated sequence); the axes are reported as a vector with `collapsed_score: None`;
 the realized CD4 response / ADA titer stay known-unknowns. See [docs/immune_profiler.md](docs/immune_profiler.md).
 

{pen_stack-6.9.1 → pen_stack-6.9.2}/README.md

@@ -15,7 +15,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.9.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.9.2-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
@@ -86,16 +86,24 @@ are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that ga
   never distributed), with a documented promiscuous-binder proxy as the offline/CI fallback. Population-level proxy
   (🟡), never a patient-HLA magnitude. *(v6.9.0 used the heuristic proxy; the real tool is more discriminating —
   human-self albumin 0.066 vs foreign writers 0.11–0.15.)*
-- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, with a
-  **self-tolerance filter** (JanusMatrix-style: self epitopes are tolerated; foreign drive ADA). It **recovers
+- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, where
+  **foreignness is the protein ORIGIN** (the authoritative central-tolerance signal). It **recovers
   immunogenic-vs-tolerated**: the foreign writers (real UniProt SpCas9 / ISCro4 / Bxb1) score **above** the human
-  self control (albumin), even without the origin label (the k-mer self-match tolerates the human protein).
+  self control (albumin). The **real full-human-proteome 9-mer self-match** (computed on the VM, 20 431 proteins) is
+  reported as a cross-check (albumin 1.0 self, foreign writers 0.0).
 - **The writer as a distinct antigen** — the profile now carries a `writer_as_antigen` card and a
   `writer_dominant_risk` flag: for **non-viral delivery of a bacterial writer there is no capsid antigen, so the
   WRITER is the dominant immunogen** — the insight the capsid-only profile missed.
 - **Immuno-Bench** (`benchmarks/immuno/`) — the immunogenic-vs-tolerated recovery track + an honest `calibrate_axis`
   ADA pass (it stays 🟡 at public-data power — no manufactured ✅, the standing wet-lab bottleneck).
 
+**v6.9.2 — real-tool rigor pass (no proxies / no heuristics).** A top-to-bottom audit: the **MHC-I capsid axis is
+re-grounded on the gold-standard NetMHCpan-4.1** (MHCflurry kept as a reported cross-check); **ADA foreignness is the
+authoritative origin** and **abstains** when unknown (no k-mer guess); the MHC-II axis **abstains** rather than
+falling back to a production proxy (the promiscuous-binder estimate is offline-triage only); and the PASTE pegRNA
+writes the **real documented Bxb1 minimal attB** (FlyBase / Ghosh 2003) instead of a schematic. Real tool or honest
+abstention — never a silent fallback.
+
 Real UniProt sequences only (no fabricated sequence); the axes are reported as a vector with `collapsed_score: None`;
 the realized CD4 response / ADA titer stay known-unknowns. See [docs/immune_profiler.md](docs/immune_profiler.md).
 

pen_stack-6.9.2/configs/mhc_epitope_oracle.yaml

@@ -0,0 +1,296 @@
+version: 6.9.2
+method:
+  mhc2: NetMHCIIpan-4.0 EL %Rank<=2, residue coverage
+  hla2_panel:
+  - DRB1_0101
+  - DRB1_0301
+  - DRB1_0401
+  - DRB1_0701
+  - DRB1_1101
+  - DRB1_1301
+  - DRB1_1501
+  mhc1: NetMHCpan-4.1 %Rank_EL<=0.5, residue coverage
+  hla1_panel:
+  - HLA-A01:01
+  - HLA-A02:01
+  - HLA-A03:01
+  - HLA-A11:01
+  - HLA-A24:02
+  - HLA-A26:01
+  - HLA-B07:02
+  - HLA-B08:01
+  - HLA-B15:01
+  - HLA-B40:01
+  - HLA-B44:03
+  - HLA-B58:01
+  metric: residue coverage by strong binders, union over panel (matches v5.3 MHCflurry)
+provenance_dois:
+- 10.1093/nar/gkac1029
+- 10.1093/nar/gkaa379
+note: population-level epitope load (frequent-HLA panel; NOT patient-HLA-specific).
+  Licensed NetMHC binaries run locally; only derived fractions cached.
+mhc2:
+  SpCas9:
+    epitope_fraction_strong: 0.636
+    immune_score: 0.364
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 1368
+    n_covered: 870
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  ISCro4:
+    epitope_fraction_strong: 0.5644
+    immune_score: 0.4356
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 326
+    n_covered: 184
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  Bxb1:
+    epitope_fraction_strong: 0.6467
+    immune_score: 0.3533
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 501
+    n_covered: 324
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  HumanAlbumin:
+    epitope_fraction_strong: 0.3186
+    immune_score: 0.6814
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 609
+    n_covered: 194
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  AAV2_VP1:
+    epitope_fraction_strong: 0.5592
+    immune_score: 0.4408
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 735
+    n_covered: 411
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  Ad5_hexon:
+    epitope_fraction_strong: 0.6229
+    immune_score: 0.3771
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 952
+    n_covered: 593
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  VSVg_Indiana:
+    epitope_fraction_strong: 0.3914
+    immune_score: 0.6086
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 511
+    n_covered: 200
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  HSV1_gD:
+    epitope_fraction_strong: 0.5355
+    immune_score: 0.4645
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 394
+    n_covered: 211
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  HSV1_gB:
+    epitope_fraction_strong: 0.4746
+    immune_score: 0.5254
+    metric: residue coverage by strong 15-mers (%Rank<=2.0), union over 7 alleles
+    length: 904
+    n_covered: 429
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+mhc1:
+  AAV2_VP1:
+    epitope_fraction_strong: 0.5415
+    immune_score: 0.4585
+    metric: residue coverage by strong 9-mers (%Rank<=0.5), union over 12 alleles
+    length: 735
+    n_covered: 398
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B40:01
+    - HLA-B44:03
+    - HLA-B58:01
+  Ad5_hexon:
+    epitope_fraction_strong: 0.7216
+    immune_score: 0.2784
+    metric: residue coverage by strong 9-mers (%Rank<=0.5), union over 12 alleles
+    length: 952
+    n_covered: 687
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B40:01
+    - HLA-B44:03
+    - HLA-B58:01
+  VSVg_Indiana:
+    epitope_fraction_strong: 0.6223
+    immune_score: 0.3777
+    metric: residue coverage by strong 9-mers (%Rank<=0.5), union over 12 alleles
+    length: 511
+    n_covered: 318
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B40:01
+    - HLA-B44:03
+    - HLA-B58:01
+  HSV1_gD:
+    epitope_fraction_strong: 0.6853
+    immune_score: 0.3147
+    metric: residue coverage by strong 9-mers (%Rank<=0.5), union over 12 alleles
+    length: 394
+    n_covered: 270
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B40:01
+    - HLA-B44:03
+    - HLA-B58:01
+  HSV1_gB:
+    epitope_fraction_strong: 0.5962
+    immune_score: 0.4038
+    metric: residue coverage by strong 9-mers (%Rank<=0.5), union over 12 alleles
+    length: 904
+    n_covered: 539
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B40:01
+    - HLA-B44:03
+    - HLA-B58:01
+self_match:
+  SpCas9:
+    fraction: 0.0
+    n: 1360
+    n_matched: 0
+  ISCro4:
+    fraction: 0.0
+    n: 318
+    n_matched: 0
+  Bxb1:
+    fraction: 0.0
+    n: 493
+    n_matched: 0
+  HumanAlbumin:
+    fraction: 1.0
+    n: 601
+    n_matched: 601
+  AAV2_VP1:
+    fraction: 0.0
+    n: 727
+    n_matched: 0
+  Ad5_hexon:
+    fraction: 0.0
+    n: 944
+    n_matched: 0
+  VSVg_Indiana:
+    fraction: 0.0
+    n: 503
+    n_matched: 0
+  HSV1_gD:
+    fraction: 0.0
+    n: 386
+    n_matched: 0
+  HSV1_gB:
+    fraction: 0.0
+    n: 896
+    n_matched: 0
+self_match_meta:
+  reference: UniProt reviewed human reference proteome UP000005640 (20431 proteins)
+  k: 9
+  tool: exact 9-mer identity vs full human proteome (JanusMatrix-style self-similarity
+    cross-check)

{pen_stack-6.9.1 → pen_stack-6.9.2}/docs/immune_profiler.md

@@ -9,12 +9,18 @@ adaptive axis was **CD8/MHC-I only** (capsid epitope load via MHCflurry). v6.9 a
 > **v6.9.1 — real predictor.** The MHC-II epitope load is computed with the **licensed NetMHCIIpan-4.0** (EL
 > %Rank≤2 over a frequent HLA-II panel; MHC-I via **NetMHCpan-4.1**), run inside `penmhc:tools` Docker on the VM
 > with the licensed tools **mounted** (never committed). Only the **derived fractions** are cached
-> (`configs/mhc_epitope_oracle.yaml`), exactly like the v5.3 MHCflurry cache. The documented proxy below remains as
-> the offline/CI fallback for sequences not in the cache. Real result: human-self albumin **0.066** vs foreign
-> writers **0.11–0.15** (the gold-standard tool discriminates self from foreign — the v6.9.0 proxy gave ~0.08–0.10
-> for all). Still a 🟡 population-level proxy (frequent-HLA panel, not a patient-HLA magnitude).
+> (`configs/mhc_epitope_oracle.yaml`), exactly like the v5.3 MHCflurry cache. Computed with the v6.9.2 residue-coverage
+> metric (residues covered by ≥1 strong binder, union over the panel — matches the v5.3 MHCflurry convention): the
+> gold-standard tool discriminates self from foreign (human-self albumin **0.319** vs foreign writers **0.56–0.65**;
+> the v6.9.0 heuristic proxy gave ~0.08–0.10 for all). Still a 🟡 population-level proxy (frequent-HLA panel, not a
+> patient-HLA magnitude).
+>
+> **v6.9.2 — no production proxy.** For a sequence **not** in the real cache the axis now **abstains** (an honest
+> known-unknown) rather than emitting a proxy number; the documented promiscuous-binder density below is retained
+> only as `mhc2_proxy_estimate` for **offline triage** (explicitly labelled, never the production axis). The **capsid
+> MHC-I axis** is likewise re-grounded on **NetMHCpan-4.1** as the primary, with MHCflurry kept as a reported cross-check.
 
-A grounded, dependency-free **promiscuous MHC-II binder density** (the offline/CI fallback): MHC-II presents a 9-mer core in an open groove
+A grounded, dependency-free **promiscuous MHC-II binder density** (`mhc2_proxy_estimate`, offline triage only): MHC-II presents a 9-mer core in an open groove
 whose **P1 pocket is deep and hydrophobic** — the single dominant anchor (M/F/Y/W/L/I/V; Stern & Wiley, *Nature*
 1994), with secondary pockets at P4/P6/P9. A *promiscuous* epitope (binds many HLA-DR) has a strong P1 anchor +
 favorable secondaries (Southwood 1998). We count promiscuous-binder cores → an epitope-density proxy, computed over
@@ -29,19 +35,22 @@ Epitope load is necessary but not sufficient — **self** proteins carry MHC-II
 ADA-risk = MHC-II epitope density × foreignness
 ```
 
-with a **self-tolerance filter** (JanusMatrix-style: an epitope whose core matches the human proteome is
-tolerated). `foreignness` uses the **authoritative protein origin** (self vs bacterial/viral/phage) when known,
-else `1 − self_match_fraction` from a human-proteome k-mer filter. This **recovers immunogenic-vs-tolerated**:
+where `foreignness` is the **authoritative protein origin** (self vs bacterial/viral/phage) — the definitive
+central-tolerance signal. **v6.9.2:** the MHC-II density is the real NetMHCIIpan-4.0 value (by antigen name), and an
+**unknown origin abstains** (no k-mer guess, no heuristic). The **real full-human-proteome 9-mer self-match**
+(computed on the VM over the full UniProt reference proteome, 20 431 proteins / 10.4 M 9-mers) is reported as a
+**cross-check**, not as a foreignness imputation. This **recovers immunogenic-vs-tolerated**:
 
-| Protein (real UniProt) | origin | ADA-risk |
-|---|---|---|
-| Bxb1 integrase (Q9B086) | foreign | **0.095** |
-| SpCas9 (Q99ZW2) | foreign | **0.093** |
-| ISCro4 bridge recombinase (D2TGM5) | foreign | **0.082** |
-| Human albumin (P02768) | self | **0.0** (tolerated) |
+| Protein (real UniProt) | origin | MHC-II density (NetMHCIIpan-4.0) | ADA-risk | human-proteome self-match |
+|---|---|---|---|---|
+| SpCas9 (Q99ZW2) | foreign | 0.636 | **0.636** | 0.0 (non-self) |
+| Bxb1 integrase (Q9B086) | foreign | 0.647 | **0.647** | 0.0 (non-self) |
+| ISCro4 bridge recombinase (D2TGM5) | foreign | 0.564 | **0.564** | 0.0 (non-self) |
+| Human albumin (P02768) | self | 0.319 | **0.0** (tolerated, × origin) | **1.0** (self) |
 
-The human self control scores 0 **even without the origin label** — the k-mer self-match tolerates it. The foreign
-writers separate cleanly above it.
+ADA-risk = density × foreignness, so the self control is zeroed by its `self` origin while the foreign writers carry
+their full MHC-II load. The independent human-proteome self-match agrees: albumin is fully self (1.0), the bacterial
+writers are non-self (0.0).
 
 ## The writer as a distinct antigen
 

{pen_stack-6.9.1 → pen_stack-6.9.2}/pen_stack/__init__.py

@@ -1,2 +1,2 @@
 """PEN-STACK v3.0 - open infrastructure for genome writing."""
-__version__ = "6.9.1"
+__version__ = "6.9.2"

{pen_stack-6.9.1 → pen_stack-6.9.2}/pen_stack/atlas/guide_design.py

@@ -8,8 +8,10 @@ Auto-designs the targeting component each writer family needs, from the DOCUMENT
     10.1038/s41586-024-07552-4). We compute the loop guide sequences (reverse-complement of the specificity arms,
     core preserved) and validate by round-trip recovery.
   * **pegRNA + attB** (PASTE / PASSIGE) — a prime-editing guide whose 3' extension WRITES a serine-integrase
-    attachment site (e.g. Bxb1 attB, central dinucleotide **GT**) at the nick, so the integrase can then place
-    large cargo (Yarnall et al., Nat Biotechnol 2023, 10.1038/s41587-022-01527-4; Pandey/Liu, Nat Biomed Eng 2025).
+    attachment site at the nick, so the integrase can then place large cargo (Yarnall et al., Nat Biotechnol 2023,
+    10.1038/s41587-022-01527-4; Pandey/Liu, Nat Biomed Eng 2025). v6.9.2 writes the **REAL documented Bxb1 minimal
+    attB** (FlyBase FBto0000359; Ghosh, Kim & Hatfull, Mol Cell 2003, 10.1016/S1097-2765(03)00444-1) — not a
+    schematic — with the 8-bp common core **GCGGTCTC** around the central **GT** crossover dinucleotide.
   * **orthogonal att-pair selection** — serine-integrase att sites with distinct central dinucleotides
     (e.g. **GA vs GT**) recombine only with their cognate partner, enabling multiplexed/orthogonal landing pads
     (Roelle, Kamath & Matreyek, ACS Synth Biol 2023, 10.1021/acssynbio.3c00355).
@@ -34,6 +36,20 @@ _INTEGRASE_CORE = {
 # mismatched cores are ~orthogonal.
 _ORTHOGONAL_BXB1_CORES = ["GT", "GA", "GC", "CT", "TA"]
 
+# REAL, documented serine-integrase attachment sites (verbatim, never fabricated). Bxb1: FlyBase FBto0000359
+# (attB) / FBto0000358 (attP); Ghosh, Kim & Hatfull, Mol Cell 2003 (10.1016/S1097-2765(03)00444-1) — attB/attP
+# share the 8-bp common core GCGGTCTC around the central GT crossover dinucleotide (the sole determinant of
+# integration orientation). Only integrases with a documented site bundled here get a full attB written.
+_INTEGRASE_ATT = {
+    "Bxb1": {
+        "attB": "TCGGCCGGCTTGTCGACGACGGCGGTCTCCGTCGTCAGGATCATCCGGGC",
+        "attP": "GTCGTGGTTTGTCTGGTCAACCACCGCGGTCTCAGTGGTGTACGGTACAAACCCCGAC",
+        "core": "GCGGTCTC", "central_dinucleotide": "GT",
+        "source": "FlyBase FBto0000359/358; Ghosh, Kim & Hatfull, Mol Cell 2003",
+        "doi": "10.1016/S1097-2765(03)00444-1",
+    },
+}
+
 
 def revcomp(seq: str) -> str:
     return "".join(_COMP.get(b, "N") for b in reversed(seq))
@@ -92,24 +108,34 @@ class PegRNAAttDesign:
     note: str = ""
 
 
-def design_pegrna_attb(target_site: str, integrase: str = "Bxb1", attb_arm: int = 18) -> PegRNAAttDesign:
+def design_pegrna_attb(target_site: str, integrase: str = "Bxb1") -> PegRNAAttDesign:
     """Design a PASTE/PASSIGE pegRNA that writes a serine-integrase **attB** at `target_site`.
 
-    The prime-edit installs a minimal attB (cognate central dinucleotide for the integrase); the integrase then
-    recombines cargo flanked by attP. We return the spacer + the 3' extension (revcomp of the att template, the
-    PE convention) and the att site written. Sequences are DESIGN CANDIDATES — empirical validation required.
+    The prime-edit installs the integrase's minimal attB; the integrase then recombines cargo flanked by the
+    cognate attP. We return the spacer + the 3' extension (revcomp of the att template, the PE convention) and the
+    att site written. For integrases with a documented site bundled (`_INTEGRASE_ATT`, e.g. Bxb1) the REAL minimal
+    attB is written verbatim — never a schematic; integrases without a bundled documented site expose only the
+    central core (the full sequence is NOT fabricated). Sequences are DESIGN CANDIDATES — empirical validation
+    required.
     """
     integrase = integrase if integrase in _INTEGRASE_CORE else "Bxb1"
     core = _INTEGRASE_CORE[integrase]
     ts = target_site.upper()
     spacer = ts[:20] if len(ts) >= 20 else ts
-    # minimal attB = left arm + core + right arm (schematic minimal site; real arms are integrase-specific)
-    attb = ("G" * attb_arm) + core + ("C" * attb_arm)
+    att = _INTEGRASE_ATT.get(integrase)
+    if att:
+        attb = att["attB"]                       # REAL documented minimal attB (verbatim) — no schematic arms
+        note = (f"pegRNA 3' extension writes the REAL documented {integrase} minimal attB ({len(attb)} bp; central "
+                f"crossover {att['central_dinucleotide']}, 8-bp common core {att['core']}; {att['source']}) at the "
+                f"nick; cargo is delivered flanked by the cognate attP. Candidate scaffold — empirical validation "
+                "required (Yarnall 2023).")
+    else:
+        attb = core                              # no bundled documented site: expose the core only, never fabricate
+        note = (f"no bundled documented minimal att sequence for {integrase!r}: only the central core {core} is "
+                "asserted (the full site is NOT fabricated). Add a documented attB to design the full scaffold.")
     return PegRNAAttDesign(
         integrase=integrase, att_core=core, target_site=ts, pegrna_spacer=spacer,
-        pe_3prime_extension=revcomp(attb), written_att=attb,
-        note=(f"pegRNA writes a minimal {integrase} attB (central core {core}) at the nick; cargo is delivered "
-              "flanked by attP. Arm sequences are integrase-specific; this is a candidate scaffold (Yarnall 2023)."))
+        pe_3prime_extension=revcomp(attb), written_att=attb, note=note)
 
 
 def select_orthogonal_att_pairs(n: int, integrase: str = "Bxb1") -> dict:

pen_stack-6.9.2/pen_stack/planner/ada_risk.py

@@ -0,0 +1,64 @@
+"""ADA-risk (v6.9 PEN-IMMUNE, G-WS2; v6.9.2 real-tool re-grounding).
+
+A protein's MHC-II epitope load (presentation potential) is necessary but not sufficient for anti-drug antibodies
+(ADA): **self** proteins carry MHC-II epitopes too, yet are tolerated (central tolerance deletes self-reactive T
+cells). What drives ADA is **non-self** (foreign) presentable epitopes. So:
+
+    ADA-risk  =  MHC-II epitope density (real, NetMHCIIpan-4.0)  x  foreignness
+
+where **foreignness is the protein ORIGIN** (self vs bacterial/viral/phage) — the authoritative, definitive
+self/non-self signal (central tolerance), not a heuristic. The **real human-proteome 9-mer self-match** (computed
+on the VM against the full UniProt human reference proteome) is reported as a cross-check. NO heuristic fallback:
+when the MHC-II density is not cached (NetMHCIIpan not run) OR the origin is unknown, ADA-risk **abstains** (an
+honest known-unknown) rather than guessing.
+
+Honest: a population-level proxy (🟡), never a patient-specific ADA titer (a known-unknown). The calibration
+against a public ADA-incidence set runs through the EXISTING calibrate_axis gate and stays 🟡 at public-data power.
+"""
+from __future__ import annotations
+
+from pen_stack.planner.immune_mhc2 import _real_cache, mhc2_epitope_load, writer_sequences
+
+ADA_DOIS = ["10.1038/s41467-021-25414-9"]   # Cas9 MHC-II CD4 immunogenicity (Simhadri 2021)
+_FOREIGN = {"self": 0.0, "foreign": 1.0}
+
+
+def real_self_match(name: str) -> dict | None:
+    """The REAL human-proteome 9-mer self-match for a bundled antigen (cross-check; computed on the VM against the
+    full UniProt human reference proteome). Foreign proteins ~0, human ~1. None if not in the cache."""
+    rec = (_real_cache().get("self_match") or {}).get(name)
+    if rec is None:
+        return None
+    return {"human_9mer_match_fraction": rec.get("fraction"), "n_9mers": rec.get("n"),
+            "reference": (_real_cache().get("self_match_meta") or {}).get("reference",
+                          "UniProt human reference proteome (full)")}
+
+
+def ada_risk(seq: str, origin: str | None = None, name: str | None = None) -> dict:
+    """ADA-risk = real MHC-II epitope density x foreignness(origin). Abstains (no proxy/heuristic) when the MHC-II
+    density is uncached or the origin is unknown. Higher ada_risk_score = MORE ADA risk; ada_immune_score = 1 - it."""
+    el = mhc2_epitope_load(seq, name)
+    density = el.get("epitope_density")
+    foreign = _FOREIGN.get(str(origin)) if origin is not None else None
+    sm = real_self_match(name) if name else None
+    base = {"epitope_density": density, "foreignness": foreign, "origin": origin,
+            "self_match_human_proteome": sm, "dois": ADA_DOIS,
+            "filter": "central tolerance: foreign (non-self) MHC-II epitopes drive ADA; self tolerated. Foreignness "
+                      "= protein origin (authoritative); MHC-II density = NetMHCIIpan-4.0; real human-proteome "
+                      "self-match reported as cross-check (no heuristic).",
+            "status": "population-level (🟡); patient ADA titer / magnitude is a known-unknown"}
+    if density is None or foreign is None:
+        return {**base, "ada_risk_score": None, "ada_immune_score": None, "backend": "abstain",
+                "note": ("abstains (no proxy): " + ("NetMHCIIpan-4.0 not run for this sequence" if density is None
+                         else "protein origin unknown — foreignness is not guessed"))}
+    risk = round(density * foreign, 4)
+    return {**base, "ada_risk_score": risk, "ada_immune_score": round(1.0 - risk, 4), "backend": "real"}
+
+
+def ada_risk_named(name: str) -> dict:
+    """ADA-risk for a bundled writer/control protein by name (uses its declared origin + the real MHC-II cache)."""
+    rec = writer_sequences().get(name)
+    if not rec:
+        return {"available": False, "note": f"no bundled sequence {name!r}"}
+    return {"available": True, "name": name, "family": rec.get("family"),
+            **ada_risk(rec["seq"], rec.get("origin"), name=name)}