pen-stack 5.2.0__tar.gz → 5.4.0__tar.gz

{pen_stack-5.2.0 → pen_stack-5.4.0}/CHANGELOG.md

@@ -3,6 +3,71 @@
 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.4.0] - 2026-06-10 - v5.4 release: Computed innate-sensing scorer (completes the computable immune axes)
+
+The third computed delivery-immunology signal, after v5.2 genotoxicity and v5.3 capsid epitope load. Innate
+sensing of a delivered nucleic acid is computed directly from the **cargo sequence** — CpG O/E for DNA (TLR9),
+U-richness + dsRNA for mRNA (TLR7/RIG-I) — covering every cargo form. Workstream WS-INNATE, SHA-locked.
+
+### Added
+- **WS-INNATE scorer** — `pen_stack/planner/innate_sensing.py`: `cpg_observed_expected()` (Gardiner-Garden &
+  Frommer) + `innate_sensing(seq, cargo_form)` → `OracleResult`. **DNA** → CpG O/E (vertebrate genome ~0.2
+  tolerated; non-depleted DNA → 1 TLR9-stimulatory), `innate_score = max(0, 1 − CpG_O/E)`. **mRNA** → uridine
+  fraction + ViennaRNA dsRNA pairing (graceful when ViennaRNA absent), flagged **partial/`extrapolating`**.
+  **RNP** → minimal/transient. Abstains on empty / unrecognised input (never fabricates). Pure sequence
+  computation — no external data, runs in CI.
+- **Surfaced in `verify()`** — when a design supplies `cargo_seq`, the computed innate load is attached as a
+  `cargo_innate_sensing` scope flag (cargo form from the writer output form, else the vehicle's first
+  compatible form) and added to `delivery_profile.cargo_innate`. No confidence added; the realized in-vivo
+  innate response stays a known-unknown.
+- Scope card `innate_sensing`; `prereg/ws_innate.yaml`. `cite.curated_dois()` ingests the innate provenance
+  DOIs (CpG-TLR9 10.1073/pnas.161293498, CpG-depleted AAV 10.1172/JCI68205, RNA modification
+  10.1016/j.immuni.2005.06.008, + Krieg 1995 / Hornung 2006).
+
+### Changed
+- Version 5.3.0 -> 5.4.0 (minor — additive computed scorer).
+
+### Honesty invariant (unchanged)
+- Sequence-intrinsic motif-**load** signal. The realized **in-vivo innate response** magnitude in a patient is
+  **not** modelled (known-unknown); the mRNA score is **partial** because the dominant evasion lever —
+  **nucleoside modification** (m1-pseudouridine) — is a manufacturing choice not derivable from sequence; DNA
+  methylation state is likewise out of scope. No magnitude predicted.
+
+## [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

{pen_stack-5.2.0 → pen_stack-5.4.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.2.0
+version: 5.4.0
 date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-5.2.0 → pen_stack-5.4.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.2.0 → pen_stack-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.2.0
+Version: 5.4.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.2.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.4.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,39 @@ 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.4 — Computed innate-sensing scorer (completes the computable immune axes)
+
+The third computed delivery-immunology signal (after v5.2 genotoxicity and v5.3 capsid epitope load). Innate
+sensing of a delivered nucleic acid is computed directly from the **cargo sequence**, covering every cargo
+form. It is a sequence-intrinsic motif-*load* signal; the realized in-vivo innate response stays a
+known-unknown, and the mRNA score is honestly *partial* (the dominant lever — nucleoside modification — isn't
+derivable from sequence).
+
+| Cargo form | Pathway | Computed from sequence | Score |
+|---|---|---|---|
+| **DNA** (AAV / HDAd / HSV / plasmid) | TLR9 / cGAS | CpG observed/expected ratio | `max(0, 1 − CpG_O/E)` — vertebrate genome ~0.2 tolerated, non-depleted DNA → 1 stimulatory |
+| **mRNA** (LNP-mRNA / electroporation) | TLR7/8 + RIG-I/MDA5/PKR | U-fraction + ViennaRNA dsRNA pairing | partial / `extrapolating` (nucleoside modification out of scope) |
+| **RNP** (eVLP / electroporation) | minimal (transient gRNA) | — | ~0.9 by mechanism |
+
+`verify()` surfaces it as a `cargo_innate_sensing` flag whenever a `cargo_seq` is supplied. See
+`pen_stack/planner/innate_sensing.py`, `prereg/ws_innate.yaml`, and the `innate_sensing` scope card.
+
+## 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

{pen_stack-5.2.0 → pen_stack-5.4.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.2.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.4.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,39 @@ 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.4 — Computed innate-sensing scorer (completes the computable immune axes)
+
+The third computed delivery-immunology signal (after v5.2 genotoxicity and v5.3 capsid epitope load). Innate
+sensing of a delivered nucleic acid is computed directly from the **cargo sequence**, covering every cargo
+form. It is a sequence-intrinsic motif-*load* signal; the realized in-vivo innate response stays a
+known-unknown, and the mRNA score is honestly *partial* (the dominant lever — nucleoside modification — isn't
+derivable from sequence).
+
+| Cargo form | Pathway | Computed from sequence | Score |
+|---|---|---|---|
+| **DNA** (AAV / HDAd / HSV / plasmid) | TLR9 / cGAS | CpG observed/expected ratio | `max(0, 1 − CpG_O/E)` — vertebrate genome ~0.2 tolerated, non-depleted DNA → 1 stimulatory |
+| **mRNA** (LNP-mRNA / electroporation) | TLR7/8 + RIG-I/MDA5/PKR | U-fraction + ViennaRNA dsRNA pairing | partial / `extrapolating` (nucleoside modification out of scope) |
+| **RNP** (eVLP / electroporation) | minimal (transient gRNA) | — | ~0.9 by mechanism |
+
+`verify()` surfaces it as a `cargo_innate_sensing` flag whenever a `cargo_seq` is supplied. See
+`pen_stack/planner/innate_sensing.py`, `prereg/ws_innate.yaml`, and the `innate_sensing` scope card.
+
+## 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

pen_stack-5.4.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.4.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.2.0 → pen_stack-5.4.0}/configs/oracles/scope_cards.yaml

@@ -125,3 +125,30 @@ oracles:
       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)"
+
+  innate_sensing:               # v5.4 WS-INNATE: computed nucleic-acid innate-sensing motif load
+    family: genome
+    version: "cpg-oe+dsrna-2026"
+    output_kind: baseline       # deterministic sequence statistic, not generative
+    valid_for: "sequence-intrinsic innate-sensing LOAD of a cargo sequence: CpG observed/expected (DNA ->
+      TLR9/cGAS; CpG-depleted DNA is tolerated, non-depleted is stimulatory) and U-richness + dsRNA pairing
+      (mRNA -> TLR7/8 + RIG-I/MDA5/PKR); a relative, computable proxy"
+    not_valid_for: "the realized IN-VIVO innate RESPONSE magnitude in a patient (a known-unknown); RNA
+      NUCLEOSIDE MODIFICATION (m1-pseudouridine), the dominant mRNA evasion lever - NOT sequence-derivable
+      (the mRNA score is PARTIAL / extrapolating); DNA methylation state of the delivered cargo"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; CpG-TLR9 10.1073/pnas.161293498, CpG-depleted AAV 10.1172/JCI68205,
+      RNA modification 10.1016/j.immuni.2005.06.008)"

{pen_stack-5.2.0 → pen_stack-5.4.0}/pen_stack/__init__.py

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

{pen_stack-5.2.0 → pen_stack-5.4.0}/pen_stack/agent/cite.py

@@ -29,12 +29,16 @@ 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 computed-genotoxicity oracle provenance (VISDB, COSMIC CGC, integration-biology refs)
-    try:
-        gt = yaml.safe_load(resource("configs/genotoxicity_oracle.yaml").read_text(encoding="utf-8"))
-        dois.update(gt.get("provenance_dois", []) or [])
-    except FileNotFoundError:
-        pass
+    # 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
+    # v5.4 computed innate-sensing provenance (CpG-TLR9 / AAV CpG-depletion / RNA modification)
+    from pen_stack.planner.innate_sensing import PROVENANCE_DOIS as _innate_dois
+    dois.update(_innate_dois)
     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.4.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.2.0 → pen_stack-5.4.0}/pen_stack/planner/delivery_immunology.py

@@ -58,8 +58,28 @@ 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
+    # 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.
@@ -79,6 +99,9 @@ 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),