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

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

@@ -3,6 +3,72 @@
 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
+gold-standard licensed predictors were already on the VM — so v6.9.1 computes the MHC-II epitope load with **real
+NetMHCIIpan-4.0** (and MHC-I with **NetMHCpan-4.1**) over a frequent HLA panel, and re-grounds the axis on the real
+values. Honest: the licensed binaries are **never committed/distributed** — only the **derived fractions** are
+cached (`configs/mhc_epitope_oracle.yaml`), exactly like the v5.3 MHCflurry cache.
+
+### Changed
+- `pen_stack/planner/immune_mhc2.py` — `mhc2_epitope_load(seq, name)` now uses the **real NetMHCIIpan-4.0 EL
+  %Rank≤2** cache (over 7 frequent HLA-II alleles) when the antigen is cached; the documented promiscuous-binder
+  proxy remains only as the **offline/CI fallback** for uncached sequences. `real_mhc2_load(name)` exposes the cache.
+- `ada_risk` + `immune_profile` (writer-as-antigen) + `benchmarks/immuno` thread the antigen name → real values.
+- `configs/mhc_epitope_oracle.yaml` (committed) — derived epitope fractions for the writer + capsid antigens.
+
+### Result (real tool is more discriminating than the proxy)
+- Real NetMHCIIpan-4.0 strong-binder fraction: SpCas9 **0.153**, Bxb1 **0.152**, ISCro4 **0.112**, AAV2 0.114 vs
+  **human albumin (self) 0.066 — the lowest**. The gold-standard tool shows the self protein has a genuinely lower
+  MHC-II load and the foreign writers higher — a signal the heuristic proxy flattened (~0.08–0.10 for all). The
+  immunogenic-vs-tolerated recovery is unchanged (foreign ≫ self) but now on real predictions.
+
+### How it ran (no host install; per the VM Docker rule)
+- `penmhc:tools` (debian + tcsh + gawk + perl) with `~/netmhc` (the licensed tools) **mounted**, NMHOME fixed at
+  runtime; `scratch/v691_mhc_compute.py` runs both predictors and writes the derived cache. The axis stays a 🟡
+  population-level proxy (frequent-HLA panel, not a patient-HLA magnitude — a known-unknown).
+
 ## [6.9.0] - 2026-06-20 - PEN-IMMUNE: MHC-II/CD4 + ADA + writer-as-antigen
 
 **MINOR feature release.** Extends the immune profile from CD8/MHC-I-only to a full T-cell profile — MHC-I +

{pen_stack-6.9.0 → 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.0
+version: 6.9.2
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.9.0
+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.0-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)
@@ -155,19 +155,30 @@ driver is **MHC-II / CD4 help → anti-drug antibodies (ADA)**, and the **writer
 (Cas9 elicits MHC-II-presented CD4 responses, Simhadri *Nat Commun* 2021; bridge recombinases / serine integrases
 are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that gap, **never collapsing** the axes:
 
-- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — a grounded, dependency-free **promiscuous MHC-II
-  binder density** over the documented P1 hydrophobic anchor (Stern & Wiley 1994) + secondary pockets, scored over
-  **capsid AND writer** sequences. Population-level proxy (🟡), never a patient-HLA magnitude.
-- **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
+- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — **v6.9.1 computes it with the real, licensed
+  NetMHCIIpan-4.0** (EL %Rank≤2 over a frequent HLA-II panel; MHC-I via NetMHCpan-4.1), scored over **capsid AND
+  writer** sequences; only the derived fractions are cached (`configs/mhc_epitope_oracle.yaml`, the binaries are
+  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**, 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.0 → 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.0-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)
@@ -80,19 +80,30 @@ driver is **MHC-II / CD4 help → anti-drug antibodies (ADA)**, and the **writer
 (Cas9 elicits MHC-II-presented CD4 responses, Simhadri *Nat Commun* 2021; bridge recombinases / serine integrases
 are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that gap, **never collapsing** the axes:
 
-- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — a grounded, dependency-free **promiscuous MHC-II
-  binder density** over the documented P1 hydrophobic anchor (Stern & Wiley 1994) + secondary pockets, scored over
-  **capsid AND writer** sequences. Population-level proxy (🟡), never a patient-HLA magnitude.
-- **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
+- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — **v6.9.1 computes it with the real, licensed
+  NetMHCIIpan-4.0** (EL %Rank≤2 over a frequent HLA-II panel; MHC-I via NetMHCpan-4.1), scored over **capsid AND
+  writer** sequences; only the derived fractions are cached (`configs/mhc_epitope_oracle.yaml`, the binaries are
+  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**, 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.2/docs/immune_profiler.md

@@ -0,0 +1,70 @@
+# Stage G — the immune profiler (v6.9 PEN-IMMUNE)
+
+Stage G profiles a design's immunogenicity/toxicity across **separate, never-collapsed axes**. Through v6.8 the
+adaptive axis was **CD8/MHC-I only** (capsid epitope load via MHCflurry). v6.9 adds the **dominant** driver —
+**MHC-II/CD4 → ADA** — and scores the **writer enzyme as a distinct antigen**.
+
+## The MHC-II/CD4 axis (`planner/immune_mhc2.py`)
+
+> **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. 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** (`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
+**capsid AND writer** sequences. It is a **population-level, sequence-intrinsic proxy (🟡)** — not a trained
+allele-specific predictor, not a patient-HLA magnitude (a known-unknown).
+
+## The ADA-risk axis + self-tolerance (`planner/ada_risk.py`)
+
+Epitope load is necessary but not sufficient — **self** proteins carry MHC-II epitopes yet are tolerated. So:
+
+```
+ADA-risk = MHC-II epitope density × foreignness
+```
+
+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 | 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) |
+
+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
+
+`immune_profile` now carries a `writer_as_antigen` card and a `writer_dominant_risk` flag. The insight the
+capsid-only profile missed: **for non-viral delivery (LNP/mRNA, eVLP) of a bacterial writer there is no capsid
+antigen — so the WRITER is the dominant immunogen.** The flag fires accordingly; the axes are reported as a vector
+with `collapsed_score: None` (never fused).
+
+## Honest limits
+- Population-level proxies (🟡), never a patient-specific ADA titer / realized CD4 magnitude (known-unknowns).
+- The MHC-II method is presentation potential, not a trained allele-specific predictor.
+- The self-tolerance k-mer filter is seeded by the bundled human reference; the **full human proteome** is
+  substitutable on the VM (the authoritative foreignness signal is the protein origin).
+- The ADA axis's `calibrate_axis` pass **stays 🟡** — no public observed-incidence set at N≥6 power (the standing
+  wet-lab/clinical-data bottleneck), reported, never manufactured.
+
+See `benchmarks/immuno/` (Immuno-Bench) and `prereg/ws_immune2.yaml`.

{pen_stack-6.9.0 → 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.0"
+__version__ = "6.9.2"

{pen_stack-6.9.0 → 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: