pen-stack 5.1.0__tar.gz → 5.3.0__tar.gz

{pen_stack-5.1.0 → pen_stack-5.3.0}/CHANGELOG.md

@@ -3,6 +3,74 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [5.3.0] - 2026-06-10 - v5.3 release: Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only meaningfully touches integrating vectors. v5.3 brings the **NetMHC-style
+calculation** to the **adaptive (CD8 T-cell)** axis — the fraction of a viral vector's capsid/envelope that is
+presentable across a frequent HLA-I panel (MHCflurry) — so the computed immune signal **covers all 8 vehicles**
+(5 viral computed, 3 non-viral by mechanism). Workstream WS-EPITOPE, SHA-locked.
+
+### Added
+- **WS-EPITOPE build** — `scripts/p53_build_epitope_oracle.py` (runs in a dedicated `penstack:mhcflurry` image)
+  slides 9-mers across each capsid/envelope antigen and predicts MHCflurry 2.0 affinity %rank per allele across
+  12 frequent HLA-I alleles; `epitope_fraction_strong` = residues covered by a strong binder (%rank ≤ 0.5);
+  `capsid_immune_score = 1 − epitope_fraction_strong`. Sequences UniProt-verified and committed
+  (`configs/capsid_sequences.fasta`): AAV2 VP1 P03135, Ad5 hexon P04133, VSV-G P03522, HSV-1 gD P57083 + gB
+  P06437. Emits the small committed summary `configs/capsid_epitope_oracle.yaml` (MHCflurry + raw sequences stay
+  on the VM → CI-safe).
+- **WS-EPITOPE oracle** — `pen_stack/planner/capsid_epitope_oracle.py`: `capsid_epitope_oracle(vehicle)` returns
+  an `OracleResult` (`output_kind="baseline"`, scope card `capsid_epitope`). Non-viral vehicles → 1.0 by
+  mechanism; unknown / sequence-less → **abstains**.
+- **Wired into the adaptive axis** — `safety_efficacy_profile()` folds the computed capsid score into the
+  adaptive (CD8) sub-axis **only for in-vivo vehicles**. The computed score is *intrinsic* antigen
+  presentability; for **ex-vivo** lentivirus (whose VSV-G envelope is intrinsically epitope-dense but barely
+  seen by the host ex vivo) it is **reported but not folded** (`adaptive_source = computed_ex_vivo_muted`), the
+  documented tier kept. `capsid_presentability_score` surfaces the raw computed value.
+- **Result:** AAV2 capsid is the *least* epitope-dense (0.72) and Ad5 hexon among the most (0.82); HDAd's in-vivo
+  immune score drops accordingly — the documented adaptive ordering reproduced from sequence. `prereg/ws_epitope.yaml`.
+
+### Changed
+- Version 5.2.0 -> 5.3.0 (minor — additive computed oracle); `cite.curated_dois()` ingests the epitope
+  provenance DOIs (MHCflurry 10.1016/j.cels.2020.06.010, HLA-I supertypes 10.1186/1471-2172-9-1).
+
+### Honesty invariant (unchanged)
+- Population-level, **sequence-intrinsic presentation** signal (does the capsid contain HLA binders) — **not**
+  the realized in-vivo / **patient-HLA-specific** T-cell response (a known-unknown), and **CD8/MHC-I only** (not
+  antibody / neutralizing-antibody). No magnitude predicted.
+
+## [5.2.0] - 2026-06-10 - v5.2 release: Computed genotoxicity oracle (data, not a documented tier)
+
+The v5.1 genotoxicity axis was a documented ordinal tier; for **integrating** vectors that signal is in fact
+computable from data the stack already holds. v5.2 adds a **computed genotoxicity oracle** — the observed
+enrichment of a vector class's integration sites near COSMIC oncogenes — answering through the v4.0
+OracleResult contract. Workstream WS-GENOTOX, SHA-locked.
+
+### Added
+- **WS-GENOTOX build** — `scripts/p52_build_genotox_oracle.py` (runs on the VM where the data lives) computes,
+  per integrating vector class, `P(integration site within 50 kb of a COSMIC Cancer-Gene-Census oncogene)` and
+  its enrichment over genome background, from **VISDB** per-virus catalogues × the Phase-1 oncogene annotation
+  (**COSMIC CGC v104**). Emits the small, auditable, committed summary `configs/genotoxicity_oracle.yaml` (raw
+  catalogues stay on the VM; only the statistics ship → CI-safe).
+- **WS-GENOTOX oracle** — `pen_stack/planner/genotoxicity_oracle.py`: `genotoxicity_oracle(vehicle)` returns an
+  `OracleResult` (`output_kind="baseline"`) with `genotox_score = min(1, 1/enrichment)`, native uncertainty
+  (CI on the observed fraction), the `delivery_genotoxicity` scope card, and `extrapolating` for small-n
+  classes. Non-integrating vehicles → 1.0 by mechanism; no computed class → **abstains** (never fabricates).
+- **Wired into the v5.1 balance** — `safety_efficacy_profile()` now **prefers the computed genotox_score** for
+  integrating vectors and falls back to the documented tier otherwise (`genotox_source` records which).
+- **Result (from data):** lentiviral (HIV) integration is **2.08×** enriched near oncogenes (n=88,743, robust)
+  vs **5.65×** for gammaretroviral (MLV, the LMO2/SCID-X1 comparator, small-n flagged) — reproducing the
+  lentivirus-safer-than-gammaretrovirus ordering **from VISDB×COSMIC**, and the computed lentivirus score
+  (0.48) **validates** the v5.1 documented "moderate" tier (0.5). `prereg/ws_genotox.yaml`.
+
+### Changed
+- Version 5.1.0 -> 5.2.0 (minor — additive computed oracle); `cite.curated_dois()` ingests the genotox
+  provenance DOIs (VISDB 10.1093/nar/gkz867, COSMIC CGC 10.1038/s41568-018-0060-1, HIV/MLV integration biology).
+
+### Honesty invariant (unchanged)
+- This is a **relative integration-preference** signal. The in-vivo clonal-expansion / leukemogenesis OUTCOME
+  in a patient is **not** modelled and stays a known-unknown (`delivery_genotoxicity` scope card); the immune
+  MAGNITUDE likewise stays `in_vivo_immunogenicity`. No magnitude is predicted.
+
 ## [5.1.0] - 2026-06-10 - v5.1 release: Delivery immunology (the safety↔efficacy balance)
 
 The delivery palette gains a **documented, cited, qualitative immune + safety + efficacy profile** per vehicle,

{pen_stack-5.1.0 → pen_stack-5.3.0}/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: 5.1.0
+version: 5.3.0
 date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-5.1.0 → pen_stack-5.3.0}/MANIFEST.in

@@ -2,7 +2,7 @@
 # source build is reproducible. Large artifacts (atlases, BigWig, models) are NOT shipped - they are on
 # Zenodo (DOI) per the data policy; clone the repo + fetch Zenodo for the full pipeline.
 include README.md LICENSE CHANGELOG.md CITATION.cff pyproject.toml
-recursive-include configs *.yaml *.yml *.txt.example
+recursive-include configs *.yaml *.yml *.txt.example *.fasta
 recursive-include prereg *.yaml *.json
 recursive-include data/curated *
 recursive-include benchmarks *.yaml *.md SHA256SUMS

{pen_stack-5.1.0 → pen_stack-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.1.0
+Version: 5.3.0
 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
@@ -91,7 +91,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-5.1.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -135,6 +135,38 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the
+**adaptive (CD8 T-cell)** axis: the fraction of a viral vector's capsid/envelope presentable across a frequent
+HLA-I panel (MHCflurry), so the computed immune signal now **covers all 8 vehicles** — 5 viral computed, 3
+non-viral by mechanism. It is a population-level, *sequence-intrinsic* presentation signal; the realized
+patient-HLA-specific T-cell response stays a known-unknown (and it is CD8/MHC-I only, not antibody).
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **EPITOPE build** | `scripts/p53_build_epitope_oracle.py` → committed `configs/capsid_epitope_oracle.yaml` | per viral capsid: `epitope_fraction_strong` over 9-mers × 12 HLA-I alleles (MHCflurry %rank ≤ 0.5), from UniProt-verified sequences (AAV2 VP1, Ad5 hexon, VSV-G, HSV gD/gB); MHCflurry stays on the VM, only the summary ships |
+| **EPITOPE oracle** | `planner/capsid_epitope_oracle.py` (`OracleResult`) | `capsid_immune_score = 1 − epitope_fraction_strong`; non-viral → 1.0 by mechanism; abstains when no sequence |
+| **wired into the adaptive axis** | folded **only for in-vivo** vehicles | AAV2 least epitope-dense (0.72), Ad5 hexon among the most (0.82) — documented adaptive ordering reproduced from sequence; **ex-vivo** lentivirus's intrinsic VSV-G load is *reported but muted* (host barely sees it ex vivo) |
+
+See `prereg/ws_epitope.yaml` and the `capsid_epitope` scope card.
+
+## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
+
+v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for
+integrating vectors: the observed enrichment of a vector class's integration sites near COSMIC oncogenes
+(VISDB integration catalogues × the Phase-1 COSMIC-CGC oncogene annotation), surfaced through the v4.0
+`OracleResult` contract. The in-vivo clonal / leukemogenesis **outcome** stays a known-unknown — this is a
+relative integration-*preference* signal, not a per-patient oncogenesis probability.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **GENOTOX build** | `scripts/p52_build_genotox_oracle.py` → committed `configs/genotoxicity_oracle.yaml` | per integrating class: `P(site within 50 kb of a COSMIC oncogene)`, enrichment vs background, CI, n — from VISDB × COSMIC CGC v104 (raw data stays on the VM; only the auditable summary ships) |
+| **GENOTOX oracle** | `planner/genotoxicity_oracle.py` (`OracleResult`, `output_kind="baseline"`) | `genotox_score = min(1, 1/enrichment)`; non-integrating → 1.0 by mechanism; **abstains** when it has no computed class (never fabricates); small-n classes flagged `extrapolating` |
+| **wired into v5.1 balance** | `safety_efficacy_profile()` prefers computed genotox, falls back to the documented tier | **lentiviral 2.08×** vs **gammaretroviral 5.65×** oncogene-proximity enrichment — reproduces the lentivirus-safer-than-gammaretrovirus ordering **from data**; computed LV score (0.48) **validates** the v5.1 documented tier (0.5) |
+
+See `prereg/ws_genotox.yaml` and the `delivery_genotoxicity` scope card.
+
 ## What is new in v5.1 — Delivery immunology (the safety↔efficacy balance)
 
 v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now

{pen_stack-5.1.0 → pen_stack-5.3.0}/README.md

@@ -16,7 +16,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-5.1.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -60,6 +60,38 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the
+**adaptive (CD8 T-cell)** axis: the fraction of a viral vector's capsid/envelope presentable across a frequent
+HLA-I panel (MHCflurry), so the computed immune signal now **covers all 8 vehicles** — 5 viral computed, 3
+non-viral by mechanism. It is a population-level, *sequence-intrinsic* presentation signal; the realized
+patient-HLA-specific T-cell response stays a known-unknown (and it is CD8/MHC-I only, not antibody).
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **EPITOPE build** | `scripts/p53_build_epitope_oracle.py` → committed `configs/capsid_epitope_oracle.yaml` | per viral capsid: `epitope_fraction_strong` over 9-mers × 12 HLA-I alleles (MHCflurry %rank ≤ 0.5), from UniProt-verified sequences (AAV2 VP1, Ad5 hexon, VSV-G, HSV gD/gB); MHCflurry stays on the VM, only the summary ships |
+| **EPITOPE oracle** | `planner/capsid_epitope_oracle.py` (`OracleResult`) | `capsid_immune_score = 1 − epitope_fraction_strong`; non-viral → 1.0 by mechanism; abstains when no sequence |
+| **wired into the adaptive axis** | folded **only for in-vivo** vehicles | AAV2 least epitope-dense (0.72), Ad5 hexon among the most (0.82) — documented adaptive ordering reproduced from sequence; **ex-vivo** lentivirus's intrinsic VSV-G load is *reported but muted* (host barely sees it ex vivo) |
+
+See `prereg/ws_epitope.yaml` and the `capsid_epitope` scope card.
+
+## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
+
+v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for
+integrating vectors: the observed enrichment of a vector class's integration sites near COSMIC oncogenes
+(VISDB integration catalogues × the Phase-1 COSMIC-CGC oncogene annotation), surfaced through the v4.0
+`OracleResult` contract. The in-vivo clonal / leukemogenesis **outcome** stays a known-unknown — this is a
+relative integration-*preference* signal, not a per-patient oncogenesis probability.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **GENOTOX build** | `scripts/p52_build_genotox_oracle.py` → committed `configs/genotoxicity_oracle.yaml` | per integrating class: `P(site within 50 kb of a COSMIC oncogene)`, enrichment vs background, CI, n — from VISDB × COSMIC CGC v104 (raw data stays on the VM; only the auditable summary ships) |
+| **GENOTOX oracle** | `planner/genotoxicity_oracle.py` (`OracleResult`, `output_kind="baseline"`) | `genotox_score = min(1, 1/enrichment)`; non-integrating → 1.0 by mechanism; **abstains** when it has no computed class (never fabricates); small-n classes flagged `extrapolating` |
+| **wired into v5.1 balance** | `safety_efficacy_profile()` prefers computed genotox, falls back to the documented tier | **lentiviral 2.08×** vs **gammaretroviral 5.65×** oncogene-proximity enrichment — reproduces the lentivirus-safer-than-gammaretrovirus ordering **from data**; computed LV score (0.48) **validates** the v5.1 documented tier (0.5) |
+
+See `prereg/ws_genotox.yaml` and the `delivery_genotoxicity` scope card.
+
 ## What is new in v5.1 — Delivery immunology (the safety↔efficacy balance)
 
 v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now

pen_stack-5.3.0/configs/capsid_epitope_oracle.yaml

@@ -0,0 +1,85 @@
+version: '1.0'
+built: '2026-06-10'
+description: 'computed capsid/envelope CD8 T-cell epitope-load oracle: fraction of
+  the antigen presentable (MHCflurry %rank<=0.5) across a frequent HLA-I panel. capsid_immune_score
+  = 1 - epitope_fraction_strong. Patient-HLA-specific response is NOT modelled (known-unknown);
+  this is a population-level sequence-intrinsic signal.'
+method:
+  predictor: MHCflurry 2.0 Class1AffinityPredictor (per-allele %rank)
+  peptide_len: 9
+  strong_rank: 0.5
+  binder_rank: 2.0
+  hla_panel:
+  - HLA-A*01:01
+  - HLA-A*02:01
+  - HLA-A*03:01
+  - HLA-A*11:01
+  - HLA-A*24:02
+  - HLA-A*26:01
+  - HLA-B*07:02
+  - HLA-B*08:01
+  - HLA-B*15:01
+  - HLA-B*40:01
+  - HLA-B*44:03
+  - HLA-B*58:01
+provenance_dois:
+- 10.1016/j.cels.2020.06.010
+- 10.1186/1471-2172-9-1
+proteins:
+  AAV2_VP1:
+    length: 735
+    n_9mers: 727
+    epitope_fraction_strong: 0.7197
+    epitope_fraction_binder: 0.9755
+    strong_binder_density: 0.01433
+  Ad5_hexon:
+    length: 952
+    n_9mers: 944
+    epitope_fraction_strong: 0.8204
+    epitope_fraction_binder: 0.979
+    strong_binder_density: 0.02127
+  VSVg_Indiana:
+    length: 511
+    n_9mers: 503
+    epitope_fraction_strong: 0.8356
+    epitope_fraction_binder: 0.9922
+    strong_binder_density: 0.0174
+  HSV1_gD:
+    length: 394
+    n_9mers: 386
+    epitope_fraction_strong: 0.7893
+    epitope_fraction_binder: 0.9822
+    strong_binder_density: 0.01619
+  HSV1_gB:
+    length: 904
+    n_9mers: 896
+    epitope_fraction_strong: 0.7965
+    epitope_fraction_binder: 0.979
+    strong_binder_density: 0.01851
+vehicles:
+  AAV_single:
+    antigens:
+    - AAV2_VP1
+    epitope_fraction_strong: 0.7197
+    capsid_immune_score: 0.2803
+  AAV_dual:
+    antigens:
+    - AAV2_VP1
+    epitope_fraction_strong: 0.7197
+    capsid_immune_score: 0.2803
+  lentivirus:
+    antigens:
+    - VSVg_Indiana
+    epitope_fraction_strong: 0.8356
+    capsid_immune_score: 0.1644
+  helper_dependent_adenovirus:
+    antigens:
+    - Ad5_hexon
+    epitope_fraction_strong: 0.8204
+    capsid_immune_score: 0.1796
+  hsv_amplicon:
+    antigens:
+    - HSV1_gD
+    - HSV1_gB
+    epitope_fraction_strong: 0.7929
+    capsid_immune_score: 0.2071

pen_stack-5.3.0/configs/capsid_sequences.fasta

@@ -0,0 +1,66 @@
+>AAV2_VP1|P03135 len=735
+MAADGYLPDWLEDTLSEGIRQWWKLKPGPPPPKPAERHKDDSRGLVLPGYKYLGPFNGLD
+KGEPVNEADAAALEHDKAYDRQLDSGDNPYLKYNHADAEFQERLKEDTSFGGNLGRAVFQ
+AKKRVLEPLGLVEEPVKTAPGKKRPVEHSPVEPDSSSGTGKAGQQPARKRLNFGQTGDAD
+SVPDPQPLGQPPAAPSGLGTNTMATGSGAPMADNNEGADGVGNSSGNWHCDSTWMGDRVI
+TTSTRTWALPTYNNHLYKQISSQSGASNDNHYFGYSTPWGYFDFNRFHCHFSPRDWQRLI
+NNNWGFRPKRLNFKLFNIQVKEVTQNDGTTTIANNLTSTVQVFTDSEYQLPYVLGSAHQG
+CLPPFPADVFMVPQYGYLTLNNGSQAVGRSSFYCLEYFPSQMLRTGNNFTFSYTFEDVPF
+HSSYAHSQSLDRLMNPLIDQYLYYLSRTNTPSGTTTQSRLQFSQAGASDIRDQSRNWLPG
+PCYRQQRVSKTSADNNNSEYSWTGATKYHLNGRDSLVNPGPAMASHKDDEEKFFPQSGVL
+IFGKQGSEKTNVDIEKVMITDEEEIRTTNPVATEQYGSVSTNLQRGNRQAATADVNTQGV
+LPGMVWQDRDVYLQGPIWAKIPHTDGHFHPSPLMGGFGLKHPPPQILIKNTPVPANPSTT
+FSAAKFASFITQYSTGQVSVEIEWELQKENSKRWNPEIQYTSNYNKSVNVDFTVDTNGVY
+SEPRPIGTRYLTRNL
+>Ad5_hexon|P04133 len=952
+MATPSMMPQWSYMHISGQDASEYLSPGLVQFARATETYFSLNNKFRNPTVAPTHDVTTDR
+SQRLTLRFIPVDREDTAYSYKARFTLAVGDNRVLDMASTYFDIRGVLDRGPTFKPYSGTA
+YNALAPKGAPNPCEWDEAATALEINLEEEDDDNEDEVDEQAEQQKTHVFGQAPYSGINIT
+KEGIQIGVEGQTPKYADKTFQPEPQIGESQWYETEINHAAGRVLKKTTPMKPCYGSYAKP
+TNENGGQGILVKQQNGKLESQVEMQFFSTTEATAGNGDNLTPKVVLYSEDVDIETPDTHI
+SYMPTIKEGNSRELMGQQSMPNRPNYIAFRDNFIGLMYYNSTGNMGVLAGQASQLNAVVD
+LQDRNTELSYQLLLDSIGDRTRYFSMWNQAVDSYDPDVRIIENHGTEDELPNYCFPLGGV
+INTETLTKVKPKTGQENGWEKDATEFSDKNEIRVGNNFAMEINLNANLWRNFLYSNIALY
+LPDKLKYSPSNVKISDNPNTYDYMNKRVVAPGLVDCYINLGARWSLDYMDNVNPFNHHRN
+AGLRYRSMLLGNGRYVPFHIQVPQKFFAIKNLLLLPGSYTYEWNFRKDVNMVLQSSLGND
+LRVDGASIKFDSICLYATFFPMAHNTASTLEAMLRNDTNDQSFNDYLSAANMLYPIPANA
+TNVPISIPSRNWAAFRGWAFTRLKTKETPSLGSGYDPYYTYSGSIPYLDGTFYLNHTFKK
+VAITFDSSVSWPGNDRLLTPNEFEIKRSVDGEGYNVAQCNMTKDWFLVQMLANYNIGYQG
+FYIPESYKDRMYSFFRNFQPMSRQVVDDTKYKDYQQVGILHQHNNSGFVGYLAPTMREGQ
+AYPANFPYPLIGKTAVDSITQKKFLCDRTLWRIPFSSNFMSMGALTDLGQNLLYANSAHA
+LDMTFEVDPMDEPTLLYVLFEVFDVVRVHRPHRGVIETVYLRTPFSAGNATT
+>VSVg_Indiana|P03522 len=511
+MKCLLYLAFLFIGVNCKFTIVFPHNQKGNWKNVPSNYHYCPSSSDLNWHNDLIGTAIQVK
+MPKSHKAIQADGWMCHASKWVTTCDFRWYGPKYITQSIRSFTPSVEQCKESIEQTKQGTW
+LNPGFPPQSCGYATVTDAEAVIVQVTPHHVLVDEYTGEWVDSQFINGKCSNYICPTVHNS
+TTWHSDYKVKGLCDSNLISMDITFFSEDGELSSLGKEGTGFRSNYFAYETGGKACKMQYC
+KHWGVRLPSGVWFEMADKDLFAAARFPECPEGSSISAPSQTSVDVSLIQDVERILDYSLC
+QETWSKIRAGLPISPVDLSYLAPKNPGTGPAFTIINGTLKYFETRYIRVDIAAPILSRMV
+GMISGTTTERELWDDWAPYEDVEIGPNGVLRTSSGYKFPLYMIGHGMLDSDLHLSSKAQV
+FEHPHIQDAASQLPDDESLFFGDTGLSKNPIELVEGWFSSWKSSIASFFFIIGLIIGLFL
+VLRVGIHLCIKLKHTKKRQIYTDIEMNRLGK
+>HSV1_gD|P57083 len=394
+MGGTAARLGAVILFVVIVGLHGVRGKYALADASLKMADPNRFRGKDLPVLDQLTDPPGVR
+RVYHIQAGLPDPFQPPSLPITVYYAVLERACRSVLLNAPSEAPQIVRGASEDVRKQPYNL
+TIAWFRMGGNCAIPITVMEYTECSYNKSLGACPIRTQPRWNYYDSFSAVSEDNLGFLMHA
+PAFETAGTYLRLVKINDWTEITQFILEHRAKGSCKYALPLRIPPSACLSPQAYQQGVTVD
+SIGMLPRFIPENQRTVAVYSLKIAGWHGPKAPYTSTLLPPELSETPNATQPELAPEDPED
+SALLEDPVGTVAPQIPPNWHIPSIQDAATPYHPPATPNNMGLIAGAVGGSLLAALVICGI
+VYWMHRRTRKAPKRIRLPHIREDDQPSSHQPLFY
+>HSV1_gB|P06437 len=904
+MHQGAPSWGRRWFVVWALLGLTLGVLVASAAPTSPGTPGVAAATQAANGGPATPAPPPLG
+AAPTGDPKPKKNKKPKNPTPPRPAGDNATVAAGHATLREHLRDIKAENTDANFYVCPPPT
+GATVVQFEQPRRCPTRPEGQNYTEGIAVVFKENIAPYKFKATMYYKDVTVSQVWFGHRYS
+QFMGIFEDRAPVPFEEVIDKINAKGVCRSTAKYVRNNLETTAFHRDDHETDMELKPANAA
+TRTSRGWHTTDLKYNPSRVEAFHRYGTTVNCIVEEVDARSVYPYDEFVLATGDFVYMSPF
+YGYREGSHTEHTTYAADRFKQVDGFYARDLTTKARATAPTTRNLLTTPKFTVAWDWVPKR
+PSVCTMTKWQEVDEMLRSEYGGSFRFSSDAISTTFTTNLTEYPLSRVDLGDCIGKDARDA
+MDRIFARRYNATHIKVGQPQYYQANGGFLIAYQPLLSNTLAELYVREHLREQSRKPPNPT
+PPPPGASANASVERIKTTSSIEFARLQFTYNHIQRHVNDMLGRVAIAWCELQNHELTLWN
+EARKLNPNAIASVTVGRRVSARMLGDVMAVSTCVPVAADNVIVQNSMRISSRPGACYSRP
+LVSFRYEDQGPLVEGQLGENNELRLTRDAIEPCTVGHRRYFTFGGGYVYFEEYAYSHQLS
+RADITTVSTFIDLNITMLEDHEFVPLEVYTRHEIKDSGLLDYTEVQRRNQLHDLRFADID
+TVIHADANAAMFAGLGAFFEGMGDLGRAVGKVVMGIVGGVVSAVSGVSSFMSNPFGALAV
+GLLVLAGLAAAFFAFRYVMRLQSNPMKALYPLTTKELKNPTNPDASGEGEEGGDFDEAKL
+AEAREMIRYMALVSAMERTEHKAKKKGTSALLSAKVTDMVMRKRRNTNYTQVPNKDGDAD
+EDDL

pen_stack-5.3.0/configs/genotoxicity_oracle.yaml

@@ -0,0 +1,48 @@
+version: '1.0'
+built: '2026-06-10'
+description: 'computed integration-site genotoxicity oracle: per vector class, the
+  observed enrichment of integration sites within window_bp of a COSMIC oncogene vs
+  genome background. genotox_score = min(1, 1/enrichment). In-vivo clonal outcome
+  is NOT modelled (stays a known-unknown).'
+window_bp: 50000
+genome_background_frac_oncogene_50kb: 0.02211
+inputs:
+  visdb: VISDB per-virus hg38 catalogues
+  oncogenes: COSMIC CGC v104 (safety_annot)
+provenance_dois:
+- 10.1093/nar/gkz867
+- 10.1038/s41568-018-0060-1
+- 10.1016/S0092-8674(02)00864-4
+- 10.1126/science.1083413
+robust_min_n: 1000
+classes:
+  lentiviral:
+    virus: HIV
+    n_sites: 88743
+    frac_oncogene_50kb: 0.04602
+    ci95: 0.00138
+    enrichment: 2.081
+    frac_genotoxic_cis: 0.000293
+    median_dist_oncogene: 2339098
+    robust: true
+  deltaretroviral:
+    virus: HTLV
+    n_sites: 51508
+    frac_oncogene_50kb: 0.02648
+    ci95: 0.00139
+    enrichment: 1.198
+    frac_genotoxic_cis: 0.000369
+    median_dist_oncogene: 3766674
+    robust: true
+  gammaretroviral:
+    virus: MLV
+    n_sites: 32
+    frac_oncogene_50kb: 0.125
+    ci95: 0.11459
+    enrichment: 5.653
+    frac_genotoxic_cis: 0.0
+    median_dist_oncogene: 2871705
+    robust: false
+vehicle_class:
+  lentiviral:
+  - lentivirus

{pen_stack-5.1.0 → pen_stack-5.3.0}/configs/oracles/scope_cards.yaml

@@ -112,3 +112,29 @@ oracles:
     not_valid_for: "absolute off-target rates; non-bridge writers; a non-recombining background"
     generalizes_to_unseen_loci: false
     license: "open (this work)"
+
+  delivery_genotoxicity:        # v5.2 WS-GENOTOX: computed integration-site oncogene-proximity
+    family: genome
+    version: "visdb+cgc_v104-2026"
+    output_kind: baseline       # an observed-data comparator (integration catalogues), not generative
+    valid_for: "RELATIVE genotoxicity ordering of INTEGRATING vector classes via the observed enrichment of
+      integration sites near COSMIC oncogenes (lentiviral vs gammaretroviral, from VISDB x CGC); reproduces the
+      lentivirus-safer-than-gammaretrovirus ordering from data"
+    not_valid_for: "the IN-VIVO clonal-expansion / leukemogenesis OUTCOME in a patient (a known-unknown); an
+      absolute per-insertion oncogenesis probability; non-integrating vectors (no insertional mechanism);
+      classes with too few catalogued sites (flagged extrapolating)"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; VISDB 10.1093/nar/gkz867, COSMIC CGC 10.1038/s41568-018-0060-1)"
+
+  capsid_epitope:               # v5.3 WS-EPITOPE: computed capsid/envelope CD8 T-cell epitope load
+    family: protein_design
+    version: "mhcflurry2.0-2026"
+    output_kind: baseline       # sequence-intrinsic presentation comparator, not generative
+    valid_for: "RELATIVE adaptive (CD8 / MHC-I) immunogenicity ordering of VIRAL vector capsids/envelopes via
+      the fraction of the antigen presentable across a frequent HLA-I panel (MHCflurry %rank<=0.5), from
+      UniProt-sourced sequences; population-level, sequence-intrinsic"
+    not_valid_for: "the realized in-vivo / PATIENT-HLA-specific T-cell response (a known-unknown); antibody /
+      neutralizing-antibody (B-cell) immunity (this is CD8/MHC-I only); non-viral vehicles (no capsid protein);
+      a viral vehicle whose antigen sequence is not committed (abstains)"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; MHCflurry 10.1016/j.cels.2020.06.010, HLA-I supertypes 10.1186/1471-2172-9-1)"

{pen_stack-5.1.0 → pen_stack-5.3.0}/pen_stack/__init__.py

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

{pen_stack-5.1.0 → pen_stack-5.3.0}/pen_stack/agent/cite.py

@@ -29,6 +29,13 @@ def curated_dois() -> frozenset[str]:
     for v in veh.values():
         dois.update(v.get("dois", []) or [])
         dois.update((v.get("immune_safety") or {}).get("immune_dois", []) or [])  # v5.1 immune priors
+    # v5.2/v5.3 computed-oracle provenance (genotoxicity: VISDB/COSMIC; capsid epitope: MHCflurry/HLA)
+    for _art in ("configs/genotoxicity_oracle.yaml", "configs/capsid_epitope_oracle.yaml"):
+        try:
+            a = yaml.safe_load(resource(_art).read_text(encoding="utf-8"))
+            dois.update(a.get("provenance_dois", []) or [])
+        except FileNotFoundError:
+            pass
     gsh = yaml.safe_load(resource("configs/gsh_validated_heldout.yaml").read_text(encoding="utf-8"))["gsh"]
     for g in gsh:
         if g.get("doi"):

pen_stack-5.3.0/pen_stack/planner/capsid_epitope_oracle.py

@@ -0,0 +1,97 @@
+"""Computed capsid/envelope T-cell epitope-load oracle for viral delivery vectors (v5.3, WS-EPITOPE).
+
+Refines the documented `adaptive_immune` (CD8 T-cell) tier with a DATA-COMPUTED signal for VIRAL vectors: the
+fraction of the capsid/envelope antigen that is presentable across a frequent HLA-I panel (MHCflurry %rank
+<= 0.5), from configs/capsid_epitope_oracle.yaml (built by scripts/p53_build_epitope_oracle.py in the dedicated
+`penstack:mhcflurry` image over UniProt-sourced sequences).
+
+    capsid_immune_score = 1 - epitope_fraction_strong      # 1 = least presentable / least immunogenic
+
+This is the NetMHC-style calculation the user asked for, made population-level (averaged over a frequent-allele
+panel) so it is NOT a patient-HLA-specific magnitude. Answers through the v4.0 OracleResult contract
+(output_kind="baseline").
+
+Coverage of the whole palette: VIRAL vectors (AAV, lentivirus[VSV-G], HDAd, HSV) get a computed score;
+NON-VIRAL vectors (LNP-mRNA, eVLP, electroporation) have no foreign capsid protein -> score 1.0 by mechanism;
+a viral vector with no committed antigen sequence -> ABSTAINS (never fabricates).
+
+HONESTY: this is a population-level, sequence-intrinsic PRESENTATION signal (does the capsid contain HLA
+binders), NOT the realized in-vivo / patient-HLA-specific T-cell response (a known-unknown); it is also CD8
+(MHC-I) only - it does not model antibody / neutralizing-antibody (B-cell) immunity.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.oracles.schema import OracleResult, Provenance
+from pen_stack.planner.delivery_vehicles import vehicle
+
+_SCOPE_CARD = "capsid_epitope"
+# non-viral vehicles have no foreign capsid/envelope protein -> no capsid CD8 epitope load (1.0 by mechanism).
+_NON_VIRAL = {"lnp_mrna", "evlp", "electroporation"}
+
+
+@lru_cache(maxsize=1)
+def _artifact() -> dict:
+    return yaml.safe_load(resource("configs/capsid_epitope_oracle.yaml").read_text(encoding="utf-8"))
+
+
+def _prov(**extra) -> Provenance:
+    art = _artifact()
+    return Provenance(model="mhcflurry_capsid_epitope", version=str(art.get("version", "1.0")), source="cache",
+                      extra={"built": art.get("built"), "predictor": art.get("method", {}).get("predictor"),
+                             "provenance_dois": art.get("provenance_dois", []), **extra})
+
+
+def capsid_epitope_oracle(vehicle_name: str) -> OracleResult:
+    """Computed capsid CD8 epitope load for a delivery vehicle, as an OracleResult (v4.0 contract).
+
+    - viral vehicle with a committed antigen -> computed `capsid_immune_score` from MHCflurry x HLA panel.
+    - non-viral vehicle -> 1.0 by mechanism (no foreign capsid protein).
+    - unknown vehicle / viral-without-sequence -> available=False (caller falls back to the documented
+      adaptive_immune tier; no number fabricated)."""
+    rec = vehicle(vehicle_name)
+    if rec is None:
+        return OracleResult(oracle="protein_design", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                            in_scope=False, available=False, output_kind="baseline",
+                            note=f"unknown vehicle {vehicle_name!r}")
+
+    vehs = _artifact().get("vehicles") or {}
+    if vehicle_name in vehs:
+        v = vehs[vehicle_name]
+        ef = v["epitope_fraction_strong"]
+        return OracleResult(
+            oracle="protein_design",
+            value={"capsid_immune_score": v["capsid_immune_score"], "epitope_fraction_strong": ef,
+                   "antigens": v.get("antigens"),
+                   "hla_panel_size": len(_artifact().get("method", {}).get("hla_panel", []))},
+            provenance=_prov(antigens=v.get("antigens")), native_uncertainty=None,
+            scope_card=_SCOPE_CARD, in_scope=True, extrapolating=False, output_kind="baseline", available=True,
+            note=(f"{ef:.1%} of the {'/'.join(v.get('antigens', []))} antigen is presentable (MHCflurry "
+                  f"%rank<=0.5) across a frequent HLA-I panel; capsid_immune_score=1-epitope_fraction. "
+                  "Patient-HLA-specific T-cell response is a known-unknown (not modelled); CD8/MHC-I only "
+                  "(not antibody/NAb)."))
+
+    if vehicle_name in _NON_VIRAL:
+        return OracleResult(
+            oracle="protein_design",
+            value={"capsid_immune_score": 1.0, "epitope_fraction_strong": 0.0, "mechanism": "non-viral"},
+            provenance=_prov(), native_uncertainty=0.0, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note="non-viral vehicle: no foreign capsid/envelope protein -> no capsid CD8 epitope load (1.0).")
+
+    return OracleResult(oracle="protein_design", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                        in_scope=False, available=False, output_kind="baseline",
+                        note=f"viral vehicle {vehicle_name!r} has no committed antigen sequence; "
+                             "fall back to the documented adaptive_immune tier.")
+
+
+def computed_capsid_immune_score(vehicle_name: str) -> tuple[float | None, OracleResult]:
+    """Convenience: (capsid_immune_score or None, full OracleResult). None when the oracle abstains (caller
+    then uses the documented adaptive_immune tier). Never fabricates."""
+    r = capsid_epitope_oracle(vehicle_name)
+    val = (r.value or {}).get("capsid_immune_score") if (r.available and r.value) else None
+    return val, r

{pen_stack-5.1.0 → pen_stack-5.3.0}/pen_stack/planner/delivery_immunology.py

@@ -58,10 +58,38 @@ def safety_efficacy_profile(name: str) -> dict | None:
     if rec is None:
         return None
     imm = rec.get("immune_safety") or {}
-    immune_present = [t for ax in _IMMUNE_AXES if (t := _tier(imm.get(ax))) is not None]
-    immune_score = (1.0 - (sum(immune_present) / len(immune_present)) / 2.0) if immune_present else None
-    gtox = _tier(imm.get(_GENOTOX_AXIS))
-    genotox_score = (1.0 - gtox / 2.0) if gtox is not None else None
+    # per immune axis -> a 0..1 "safety" score (1 = least immunogenic). The ADAPTIVE (CD8 T-cell) axis can be
+    # COMPUTED from the capsid epitope load (v5.3 WS-EPITOPE: MHCflurry x HLA panel over the capsid/envelope
+    # antigen). The computed signal is INTRINSIC antigen presentability; it only translates to a realized host
+    # response when the host is actually exposed to the capsid (IN-VIVO use). So it is folded into the adaptive
+    # axis only for in-vivo vehicles; for EX-VIVO-only viral vectors (e.g. lentivirus, whose VSV-G envelope is
+    # intrinsically epitope-dense but barely seen by the host ex vivo) it is surfaced but NOT folded, and the
+    # documented tier is kept. The other three axes stay documented ordinal tiers. No number is fabricated.
+    from pen_stack.planner.capsid_epitope_oracle import computed_capsid_immune_score
+    cap_score, cap_oracle = computed_capsid_immune_score(name)
+    in_vivo = bool(rec.get("in_vivo"))
+    axis_scores: dict[str, float | None] = {}
+    for ax in _IMMUNE_AXES:
+        t = _tier(imm.get(ax))
+        axis_scores[ax] = (1.0 - t / 2.0) if t is not None else None
+    adaptive_source = "documented"
+    if cap_score is not None and in_vivo:
+        axis_scores["adaptive_immune"] = cap_score          # in-vivo: host sees the capsid -> fold computed
+        adaptive_source = "computed"
+    elif cap_score is not None and not in_vivo:
+        adaptive_source = "computed_ex_vivo_muted"          # reported, but ex-vivo mutes the realized response
+    immune_present = [s for s in axis_scores.values() if s is not None]
+    immune_score = (sum(immune_present) / len(immune_present)) if immune_present else None
+    # genotoxicity: prefer the COMPUTED oracle (v5.2 WS-GENOTOX: integration-site x COSMIC-oncogene
+    # enrichment, from VISDB) for integrating vectors; fall back to the documented ordinal tier when the
+    # oracle abstains. No number is fabricated either way.
+    from pen_stack.planner.genotoxicity_oracle import computed_genotox_score
+    computed, gtox_oracle = computed_genotox_score(name)
+    gtox_tier = _tier(imm.get(_GENOTOX_AXIS))
+    documented_genotox = (1.0 - gtox_tier / 2.0) if gtox_tier is not None else None
+    genotox_score = computed if computed is not None else documented_genotox
+    genotox_source = "computed" if computed is not None else ("documented" if documented_genotox is not None
+                                                              else None)
     sub = [s for s in (immune_score, genotox_score) if s is not None]
     safety_score = min(sub) if sub else None       # worst-axis; abstain if neither documented
     eff = _tier(imm.get("efficacy"))
@@ -71,7 +99,12 @@ def safety_efficacy_profile(name: str) -> dict | None:
         "vehicle": name,
         "tiers": {ax: imm.get(ax) for ax in (*_IMMUNE_AXES, _GENOTOX_AXIS)} | {"efficacy": imm.get("efficacy")},
         "immune_score": _r(immune_score),
+        "adaptive_source": adaptive_source,      # computed | computed_ex_vivo_muted | documented
+        "capsid_presentability_score": _r(cap_score),   # computed intrinsic capsid CD8 presentability (or None)
+        "adaptive_provenance": (cap_oracle.note if cap_score is not None else None),
         "genotox_score": _r(genotox_score),
+        "genotox_source": genotox_source,        # "computed" (VISDBxCOSMIC oracle) | "documented" (ordinal tier)
+        "genotox_provenance": (gtox_oracle.note if genotox_source == "computed" else None),
         "safety_score": _r(safety_score),
         "efficacy_score": _r(efficacy_score),
         "re_dosable": imm.get("re_dosable", rec.get("re_dosable")),