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

{pen_stack-5.4.0 → pen_stack-5.6.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.6.0] - 2026-06-11 - v5.6 release: Immunology completion & calibration (anti-PEG · proxy honesty · unified profile)
+
+Finishes the delivery-immunology arc (v5.1–v5.5): adds the missing **anti-PEG** axis, **calibrates** the
+proxies honestly, and exposes a **unified per-design immune-risk profile** that never collapses into one number.
+Workstreams WS-{PEG,CALIB,PROFILE} (+ optional WS-EXT), SHA-locked.
+
+### Added
+- **WS-PEG** — `pen_stack/planner/antipeg_oracle.py` + `configs/antipeg.yaml`: pre-existing/induced anti-PEG
+  antibodies gate **re-dosing** of PEGylated LNP. Population prevalence range (25–72 %) →
+  `preexisting_antipeg_score = 1 − midpoint/100`, range surfaced as `native_uncertainty`; **abstains** for
+  non-PEGylated vehicles. Serosurvey DOIs Crossref-verified (Chen 2016 `10.1021/acs.analchem.6b03109`, Yang &
+  Lai `10.1002/wnan.1339`, Armstrong `10.1002/cncr.22739`, Kozma `10.1016/j.addr.2020.07.024`). Scope card `antipeg`.
+- **WS-CALIB** — `pen_stack/validate/immune_calibration.py`: `calibrate_axis()` (Spearman ρ + percentile
+  bootstrap CI) labels an axis **outcome-validated only when the CI excludes zero**, else `weak_proxy`, and
+  `mechanistic_proxy` when N < 6. With no sufficient public paired (proxy, observed) dataset, **every axis is
+  honestly labelled a mechanistic/population proxy** — the label travels with the profile. (No fabricated
+  outcome data; machinery proven on synthetic input.)
+- **WS-PROFILE** — `pen_stack/planner/immune_profile.py` + **`Verdict.immune_profile`**: a per-design **vector**
+  of all axes (genotoxicity, CD8 epitope, innate, pre-existing NAb, anti-PEG), each with its own value +
+  uncertainty + scope + validation label. **`collapsed_score is None`** (never fused — asserted); known-unknowns
+  listed; abstaining axes report `None`.
+- **WS-EXT** — a documented qualitative **route/immune-privilege modifier** (eye/CNS lower realized
+  immunogenicity vs systemic; Streilein 2003 `10.1038/nri1224`; no fabricated magnitude); **CD4/MHC-II helper
+  epitopes**, **pre-existing capsid-specific T-cell immunity**, and **complement/CARPA** registered as
+  known-unknowns. `prereg/ws_{peg,calib,profile}.yaml` + SHA locks.
+
+### Changed
+- Version 5.5.0 -> 5.6.0 (minor — additive); `cite.curated_dois()` ingests the anti-PEG + immune-privilege DOIs.
+
+### Honesty invariant (unchanged)
+- Every axis is a **relative-risk screen** (sequence/mechanistic or population proxy), labelled as such until
+  outcome-validated; the profile is **never** collapsed into one number; patient-specific titer, post-dose-1
+  induced immunity, and exact in-vivo magnitude stay **known-unknowns**.
+
+## [5.5.0] - 2026-06-10 - v5.5 release: Anti-vector seroprevalence oracle (the last immune axis, from data)
+
+Completes the computable delivery-immunology axes. **Pre-existing humoral immunity** (B-cell / neutralizing
+antibody) to a viral capsid is the one immune axis that *cannot* be computed from sequence — it is a population
+prevalence from natural exposure. v5.5 grounds it in published **serosurvey data**. Workstream WS-SEROPREV,
+SHA-locked.
+
+### Added
+- **WS-SEROPREV table** — `configs/seroprevalence.yaml`: curated population NAb/IgG seroprevalence per serotype
+  as **ranges** (region/age/assay variation) with DOIs — AAV (Calcedo 2009, Boutin 2010), adenovirus type 5
+  (Mast 2010), HSV-1 (Looker 2015), VSV (negligible).
+- **WS-SEROPREV oracle** — `pen_stack/planner/seroprevalence_oracle.py`: `seroprevalence_oracle(vehicle,
+  serotype=None)` → `OracleResult`. `preexisting_score = 1 − midpoint(seroprevalence)/100`; the range width is
+  surfaced as `native_uncertainty`. Non-viral → 1.0 by mechanism; unknown → **abstains**.
+- **Wired into the pre-existing axis** — `safety_efficacy_profile()` folds the computed seroprevalence score
+  into the `preexisting_immunity` sub-axis **only for in-vivo vehicles** (serum NAb neutralises the vector in
+  vivo; ex-vivo transduction in a dish is not reached by host antibody → reported but muted). `seroprevalence_score`
+  surfaces the raw value.
+- **Result (from data):** adenovirus has the highest pre-existing seroprevalence (40–90%, score 0.35), AAV
+  intermediate (30–60%, 0.55), VSV/lentivirus negligible (0–5%, 0.975) — the documented ordering quantified
+  from serosurveys. `prereg/ws_seroprev.yaml`.
+
+### Changed
+- Version 5.4.0 -> 5.5.0 (minor — additive data-grounded oracle); `cite.curated_dois()` ingests the
+  seroprevalence DOIs.
+
+### Honesty invariant (unchanged)
+- A **population** prevalence (a range; region/age/assay-dependent), **not** a given **patient's** NAb titer /
+  sero-status (a clinical test, patient-specific → a known-unknown); the **humoral (B-cell)** axis only,
+  distinct from the v5.3 T-cell epitope load. No patient-specific magnitude predicted.
+
 ## [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

{pen_stack-5.4.0 → pen_stack-5.6.0}/CITATION.cff

@@ -1,8 +1,8 @@
 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.4.0
-date-released: 2026-06-10
+version: 5.6.0
+date-released: 2026-06-11
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-5.4.0 → pen_stack-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.4.0
+Version: 5.6.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
@@ -87,11 +87,10 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![PyPI](https://img.shields.io/pypi/v/pen-stack.svg)](https://pypi.org/project/pen-stack/)
 [![CI](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml)
 [![Publish](https://github.com/ahmedanees-m/pen-stack/actions/workflows/publish.yml/badge.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/publish.yml)
-[![coverage](https://raw.githubusercontent.com/ahmedanees-m/pen-stack/main/.github/badges/coverage.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml)
 [![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.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.6.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 +134,46 @@ 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.6 — Immunology completion & calibration (anti-PEG · proxy honesty · unified profile)
+
+v5.6 finishes the delivery-immunology arc and tells the truth about it. It adds the missing **anti-PEG** axis
+(gates LNP re-dosing), **calibrates** every proxy two-sided, and exposes a **unified per-design immune-risk
+profile** in which each axis keeps its own uncertainty and none is ever fused into one overconfident number.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **PEG** | `planner/antipeg_oracle.py` + `configs/antipeg.yaml` | anti-PEG prevalence (25–72%) → `preexisting_antipeg_score`; gates **re-dosing**; abstains for non-PEG vehicles; range surfaced as uncertainty |
+| **CALIB** | `validate/immune_calibration.py` | each axis labelled **outcome-validated** (ρ + CI excluding 0) or **mechanistic/population proxy**; with no public paired-outcome data, all axes are honestly labelled proxies (the label travels with the profile) |
+| **PROFILE** | `planner/immune_profile.py` + `Verdict.immune_profile` | per-design **vector** of all axes, each with value + uncertainty + scope + validation label; **`collapsed_score is None`** (never fused); known-unknowns listed |
+| **EXT** | route/immune-privilege modifier + new known-unknowns | eye/CNS immune-privilege as a *documented qualitative* modifier (no magnitude); CD4/MHC-II, pre-existing capsid T-cell, complement/CARPA registered as known-unknowns |
+
+The in-vivo magnitude and patient-specific titer stay declared known-unknowns. See
+[`docs/delivery_immunology.md`](docs/delivery_immunology.md) and `prereg/ws_{peg,calib,profile}.yaml`.
+
+## What is new in v5.5 — Anti-vector seroprevalence oracle (the last immune axis, from data)
+
+This completes the computable delivery-immunology axes. **Pre-existing humoral immunity** (B-cell / NAb) to a
+viral capsid is the one axis that *cannot* be computed from sequence — it is a population prevalence from
+natural exposure — so v5.5 grounds it in published **serosurvey data** (AAV: Calcedo 2009 / Boutin 2010;
+adenovirus: Mast 2010; HSV-1: Looker 2015). `preexisting_score = 1 − midpoint(seroprevalence)/100`, with the
+literature range surfaced as native uncertainty.
+
+| serotype (vehicle) | NAb seroprevalence | pre-existing score |
+|---|---|---|
+| Ad5 → HDAd | 40–90% | 0.35 |
+| AAV (aggregate) → AAV | 30–60% | 0.55 |
+| HSV-1 → HSV | 50–70% | 0.40 |
+| VSV → lentivirus | 0–5% | 0.975 |
+
+Folded into the pre-existing axis for **in-vivo** vehicles (muted for ex-vivo, where serum NAb can't reach
+ex-vivo cells); non-viral → 1.0 by mechanism. It is a **population** prevalence — **not** a given patient's NAb
+titer (a known-unknown). See `pen_stack/planner/seroprevalence_oracle.py`, `configs/seroprevalence.yaml`,
+`prereg/ws_seroprev.yaml`, and the `seroprevalence` scope card.
+
+**With v5.5, four of the five delivery-immunology axes are grounded in data or sequence** — genotoxicity
+(VISDB×COSMIC), adaptive/CD8 (MHCflurry), innate (CpG/dsRNA), pre-existing/NAb (serosurveys) — each abstaining
+rather than fabricating, with the in-vivo *magnitude* always a declared known-unknown.
+
 ## 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
@@ -193,6 +232,11 @@ efficacious integrator but its genotoxicity is the dominant concern). Crucially,
 **magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
 patient-specific immune response.
 
+> **The full delivery-immunology story (v5.1 → v5.5), with every axis, method, and outcome, is in
+> [`docs/delivery_immunology.md`](docs/delivery_immunology.md).** By v5.5, four of the five immune/safety axes
+> are computed from data or sequence (genotoxicity, adaptive/CD8, innate, pre-existing/NAb) rather than
+> hand-typed tiers.
+
 | Workstream | What it adds | Result |
 |---|---|---|
 | **IMMUNE config** | `immune_safety` block on all 8 vehicles in `configs/delivery_vehicles.yaml` | documented ordinal (low/moderate/high) priors for pre-existing immunity, neutralizing antibody, innate/adaptive immune, **genotoxicity**, efficacy — every `immune_doi` Crossref-verified and in the curated-DOI set |
@@ -357,6 +401,10 @@ benchmark with deterministic scorers and no circular labels. See
          |  off-target + DMS (Perry 2025)                                           |
          +-------------------------------------------------------------------------+
 
+   Delivery layer (v5.1-5.5, feeds the planner): a safety<->efficacy balance over the 8-vehicle palette,
+   with four of five immune/safety axes computed from data/sequence (genotoxicity = VISDB x COSMIC;
+   adaptive/CD8 = MHCflurry over the capsid; innate = CpG/dsRNA of the cargo; pre-existing/NAb = serosurveys).
+
    Platform services (on top of the validated core): PEN-MONITOR (Europe PMC living database),
    grounded RAG/Q&A, a tool-using agent + MCP server, and a Streamlit web app.
 ```
@@ -371,6 +419,7 @@ PEN-STACK is organised as **two reference layers + one engine + a services layer
 | **Writer Atlas** (companion) | `pen_stack.atlas`, `.mech`, `.score` | cross-family enzyme catalogue + Writer-Targeting KB | Paper 2 |
 | **Cross-link** | `pen_stack.atlas.crosslink` | bidirectional writer to locus queries | Paper 2 |
 | **Write Planner** (engine) | `pen_stack.planner` | inverse design, `edit_intent`-conditioned | Paper 3 |
+| **Delivery immunology** (v5.1-5.5) | `pen_stack.planner.delivery_immunology` + `{genotoxicity,capsid_epitope,seroprevalence}_oracle`, `innate_sensing` | safety↔efficacy balance over the 8-vehicle palette; 4 of 5 immune axes **computed from data/sequence**, magnitude stays a known-unknown ([docs](docs/delivery_immunology.md)) | M2 |
 | **Agentic platform** | `pen_stack.agent` | goal to cited, auditable plan; MCP server; one-command deploy | Paper 3 |
 | **Bridge off-target engine** | `pen_stack.bridge` | "CRISPOR for bridge recombinases" + guide QC (v3.1) | Paper 4 |
 | **Genome-Writing Bench** (v3.1) | `benchmarks/`, `bench/run.py` | first writing-side benchmark; deterministic scorers, leaderboard | M2 |
@@ -495,12 +544,16 @@ pen-stack/
 │   ├── planner/                      Write Planner (Paper 3): optimize / cargo / cargo_polish / multiplex / pipeline
 │   │                                   + v3.2 target_site (hard PAM/att/core reject) / delivery_constraints
 │   │                                   + v3.3 router (write-type dispatch) / delivery_vehicles (8-vehicle palette)
+│   │                                   + v5.1-5.5 delivery_immunology (safety<->efficacy balance) and the four
+│   │                                     computed immune-axis oracles: genotoxicity_oracle (VISDB x COSMIC) /
+│   │                                     capsid_epitope_oracle (MHCflurry) / innate_sensing (CpG-O/E + dsRNA) /
+│   │                                     seroprevalence_oracle (anti-vector NAb serosurveys)
 │   ├── bridge/                       bridge off-target engine (Paper 4): offtarget / fold_qc / guide_qc / pipeline / cli
 │   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails; v5.0 co_scientist + cite (multi-strategy, self-critique, cited rationale, scope ledger)
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
 │   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
-│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache
+│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache; v5.2-5.5 delivery-immunology scope cards (delivery_genotoxicity/capsid_epitope/innate_sensing/seroprevalence)
 │   ├── rules/                        v3.3 machine-readable rules engine (schema/evaluators/loader/solver) over configs/rules/*.yaml
 │   ├── verify/                       v3.3 verification service: verify(design) -> Verdict (legal+reasons+confidence+scope; v4.0 writer_critique)
 │   ├── adapt/                        local recalibration / private-data adaptation behind a gate (v3.1, WS-F)
@@ -516,12 +569,16 @@ pen-stack/
 │   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask)
 │   ├── ui/app.py                     Streamlit web app (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
-├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.2 (T1-T11; tasks / harness / solvers / LEADERBOARD / SHAs)
+├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.3 (T1-T16 + co_scientist; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
-├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, ws_*_report)
-├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2: known_unknowns /
-│                                       target_sites / delivery_constraints
-├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2 ws_{uq,ep,mc,ba} + locks)
+├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, p52/p53 delivery-immunology oracle builds, ws_*_report)
+├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2 known_unknowns /
+│                                       target_sites / delivery_constraints; v5.1-5.5 delivery_vehicles immune_safety /
+│                                       genotoxicity_oracle / capsid_epitope_oracle + capsid_sequences.fasta /
+│                                       seroprevalence + oracles/scope_cards
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v5.5 ws_{uq,ep,mc,ba,
+│                                       r,v,route,env,bench,cal,o,wv,atlas,graph,mon,ct,plan,crit,cite,immune,
+│                                       genotox,epitope,innate,seroprev} + SHA256 locks)
 ├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile,
 │                                       v3.2 bridge_offtarget_energetics.json)
 ├── data/llm_bench_cache/             28 cached ungrounded-LLM transcripts (T7, offline/CI replay)

{pen_stack-5.4.0 → pen_stack-5.6.0}/README.md

@@ -12,11 +12,10 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![PyPI](https://img.shields.io/pypi/v/pen-stack.svg)](https://pypi.org/project/pen-stack/)
 [![CI](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml)
 [![Publish](https://github.com/ahmedanees-m/pen-stack/actions/workflows/publish.yml/badge.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/publish.yml)
-[![coverage](https://raw.githubusercontent.com/ahmedanees-m/pen-stack/main/.github/badges/coverage.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml)
 [![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.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.6.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 +59,46 @@ 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.6 — Immunology completion & calibration (anti-PEG · proxy honesty · unified profile)
+
+v5.6 finishes the delivery-immunology arc and tells the truth about it. It adds the missing **anti-PEG** axis
+(gates LNP re-dosing), **calibrates** every proxy two-sided, and exposes a **unified per-design immune-risk
+profile** in which each axis keeps its own uncertainty and none is ever fused into one overconfident number.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **PEG** | `planner/antipeg_oracle.py` + `configs/antipeg.yaml` | anti-PEG prevalence (25–72%) → `preexisting_antipeg_score`; gates **re-dosing**; abstains for non-PEG vehicles; range surfaced as uncertainty |
+| **CALIB** | `validate/immune_calibration.py` | each axis labelled **outcome-validated** (ρ + CI excluding 0) or **mechanistic/population proxy**; with no public paired-outcome data, all axes are honestly labelled proxies (the label travels with the profile) |
+| **PROFILE** | `planner/immune_profile.py` + `Verdict.immune_profile` | per-design **vector** of all axes, each with value + uncertainty + scope + validation label; **`collapsed_score is None`** (never fused); known-unknowns listed |
+| **EXT** | route/immune-privilege modifier + new known-unknowns | eye/CNS immune-privilege as a *documented qualitative* modifier (no magnitude); CD4/MHC-II, pre-existing capsid T-cell, complement/CARPA registered as known-unknowns |
+
+The in-vivo magnitude and patient-specific titer stay declared known-unknowns. See
+[`docs/delivery_immunology.md`](docs/delivery_immunology.md) and `prereg/ws_{peg,calib,profile}.yaml`.
+
+## What is new in v5.5 — Anti-vector seroprevalence oracle (the last immune axis, from data)
+
+This completes the computable delivery-immunology axes. **Pre-existing humoral immunity** (B-cell / NAb) to a
+viral capsid is the one axis that *cannot* be computed from sequence — it is a population prevalence from
+natural exposure — so v5.5 grounds it in published **serosurvey data** (AAV: Calcedo 2009 / Boutin 2010;
+adenovirus: Mast 2010; HSV-1: Looker 2015). `preexisting_score = 1 − midpoint(seroprevalence)/100`, with the
+literature range surfaced as native uncertainty.
+
+| serotype (vehicle) | NAb seroprevalence | pre-existing score |
+|---|---|---|
+| Ad5 → HDAd | 40–90% | 0.35 |
+| AAV (aggregate) → AAV | 30–60% | 0.55 |
+| HSV-1 → HSV | 50–70% | 0.40 |
+| VSV → lentivirus | 0–5% | 0.975 |
+
+Folded into the pre-existing axis for **in-vivo** vehicles (muted for ex-vivo, where serum NAb can't reach
+ex-vivo cells); non-viral → 1.0 by mechanism. It is a **population** prevalence — **not** a given patient's NAb
+titer (a known-unknown). See `pen_stack/planner/seroprevalence_oracle.py`, `configs/seroprevalence.yaml`,
+`prereg/ws_seroprev.yaml`, and the `seroprevalence` scope card.
+
+**With v5.5, four of the five delivery-immunology axes are grounded in data or sequence** — genotoxicity
+(VISDB×COSMIC), adaptive/CD8 (MHCflurry), innate (CpG/dsRNA), pre-existing/NAb (serosurveys) — each abstaining
+rather than fabricating, with the in-vivo *magnitude* always a declared known-unknown.
+
 ## 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
@@ -118,6 +157,11 @@ efficacious integrator but its genotoxicity is the dominant concern). Crucially,
 **magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
 patient-specific immune response.
 
+> **The full delivery-immunology story (v5.1 → v5.5), with every axis, method, and outcome, is in
+> [`docs/delivery_immunology.md`](docs/delivery_immunology.md).** By v5.5, four of the five immune/safety axes
+> are computed from data or sequence (genotoxicity, adaptive/CD8, innate, pre-existing/NAb) rather than
+> hand-typed tiers.
+
 | Workstream | What it adds | Result |
 |---|---|---|
 | **IMMUNE config** | `immune_safety` block on all 8 vehicles in `configs/delivery_vehicles.yaml` | documented ordinal (low/moderate/high) priors for pre-existing immunity, neutralizing antibody, innate/adaptive immune, **genotoxicity**, efficacy — every `immune_doi` Crossref-verified and in the curated-DOI set |
@@ -282,6 +326,10 @@ benchmark with deterministic scorers and no circular labels. See
          |  off-target + DMS (Perry 2025)                                           |
          +-------------------------------------------------------------------------+
 
+   Delivery layer (v5.1-5.5, feeds the planner): a safety<->efficacy balance over the 8-vehicle palette,
+   with four of five immune/safety axes computed from data/sequence (genotoxicity = VISDB x COSMIC;
+   adaptive/CD8 = MHCflurry over the capsid; innate = CpG/dsRNA of the cargo; pre-existing/NAb = serosurveys).
+
    Platform services (on top of the validated core): PEN-MONITOR (Europe PMC living database),
    grounded RAG/Q&A, a tool-using agent + MCP server, and a Streamlit web app.
 ```
@@ -296,6 +344,7 @@ PEN-STACK is organised as **two reference layers + one engine + a services layer
 | **Writer Atlas** (companion) | `pen_stack.atlas`, `.mech`, `.score` | cross-family enzyme catalogue + Writer-Targeting KB | Paper 2 |
 | **Cross-link** | `pen_stack.atlas.crosslink` | bidirectional writer to locus queries | Paper 2 |
 | **Write Planner** (engine) | `pen_stack.planner` | inverse design, `edit_intent`-conditioned | Paper 3 |
+| **Delivery immunology** (v5.1-5.5) | `pen_stack.planner.delivery_immunology` + `{genotoxicity,capsid_epitope,seroprevalence}_oracle`, `innate_sensing` | safety↔efficacy balance over the 8-vehicle palette; 4 of 5 immune axes **computed from data/sequence**, magnitude stays a known-unknown ([docs](docs/delivery_immunology.md)) | M2 |
 | **Agentic platform** | `pen_stack.agent` | goal to cited, auditable plan; MCP server; one-command deploy | Paper 3 |
 | **Bridge off-target engine** | `pen_stack.bridge` | "CRISPOR for bridge recombinases" + guide QC (v3.1) | Paper 4 |
 | **Genome-Writing Bench** (v3.1) | `benchmarks/`, `bench/run.py` | first writing-side benchmark; deterministic scorers, leaderboard | M2 |
@@ -420,12 +469,16 @@ pen-stack/
 │   ├── planner/                      Write Planner (Paper 3): optimize / cargo / cargo_polish / multiplex / pipeline
 │   │                                   + v3.2 target_site (hard PAM/att/core reject) / delivery_constraints
 │   │                                   + v3.3 router (write-type dispatch) / delivery_vehicles (8-vehicle palette)
+│   │                                   + v5.1-5.5 delivery_immunology (safety<->efficacy balance) and the four
+│   │                                     computed immune-axis oracles: genotoxicity_oracle (VISDB x COSMIC) /
+│   │                                     capsid_epitope_oracle (MHCflurry) / innate_sensing (CpG-O/E + dsRNA) /
+│   │                                     seroprevalence_oracle (anti-vector NAb serosurveys)
 │   ├── bridge/                       bridge off-target engine (Paper 4): offtarget / fold_qc / guide_qc / pipeline / cli
 │   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails; v5.0 co_scientist + cite (multi-strategy, self-critique, cited rationale, scope ledger)
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
 │   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
-│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache
+│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache; v5.2-5.5 delivery-immunology scope cards (delivery_genotoxicity/capsid_epitope/innate_sensing/seroprevalence)
 │   ├── rules/                        v3.3 machine-readable rules engine (schema/evaluators/loader/solver) over configs/rules/*.yaml
 │   ├── verify/                       v3.3 verification service: verify(design) -> Verdict (legal+reasons+confidence+scope; v4.0 writer_critique)
 │   ├── adapt/                        local recalibration / private-data adaptation behind a gate (v3.1, WS-F)
@@ -441,12 +494,16 @@ pen-stack/
 │   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask)
 │   ├── ui/app.py                     Streamlit web app (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
-├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.2 (T1-T11; tasks / harness / solvers / LEADERBOARD / SHAs)
+├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.3 (T1-T16 + co_scientist; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
-├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, ws_*_report)
-├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2: known_unknowns /
-│                                       target_sites / delivery_constraints
-├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2 ws_{uq,ep,mc,ba} + locks)
+├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, p52/p53 delivery-immunology oracle builds, ws_*_report)
+├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2 known_unknowns /
+│                                       target_sites / delivery_constraints; v5.1-5.5 delivery_vehicles immune_safety /
+│                                       genotoxicity_oracle / capsid_epitope_oracle + capsid_sequences.fasta /
+│                                       seroprevalence + oracles/scope_cards
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v5.5 ws_{uq,ep,mc,ba,
+│                                       r,v,route,env,bench,cal,o,wv,atlas,graph,mon,ct,plan,crit,cite,immune,
+│                                       genotox,epitope,innate,seroprev} + SHA256 locks)
 ├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile,
 │                                       v3.2 bridge_offtarget_energetics.json)
 ├── data/llm_bench_cache/             28 cached ungrounded-LLM transcripts (T7, offline/CI replay)

pen_stack-5.6.0/configs/antipeg.yaml

@@ -0,0 +1,28 @@
+# PEN-STACK v5.6 — anti-PEG antibody prevalence (WS-PEG).
+#
+# Pre-existing / induced anti-PEG antibodies gate RE-DOSING of PEGylated LNP. Anti-PEG is a property of the
+# PEGylation chemistry, NOT of any encoded sequence — so, like the v5.5 anti-vector seroprevalence, the only
+# honest grounding is published serosurvey DATA. Curated as a population prevalence RANGE (wide assay/region
+# variation), with serosurvey DOIs.
+#
+#   preexisting_antipeg_score = 1 - midpoint(anti_PEG_prevalence_pct) / 100   (1 = fewest patients excluded).
+#
+# HONESTY (scope card `antipeg`): a POPULATION prevalence, NOT a given patient's anti-PEG titer (a clinical
+# test, patient-specific -> a known-unknown); region/age/assay-dependent (a range, surfaced as uncertainty);
+# applies ONLY to PEGylated vehicles (abstains otherwise). INDUCED anti-PEG after dose 1 (boosted markedly by
+# mRNA-LNP vaccination) is a separate, larger dynamic — NOTED here, not modelled (a known-unknown).
+
+version: "1.0"
+
+prevalence:
+  anti_peg_prevalence_pct: [25, 72]
+  note: "pre-existing anti-PEG IgG/IgM in healthy adults; wide assay/region variation (Chen 2016 ~72% had
+    detectable anti-PEG; high-TITER prevalence is lower). Induced anti-PEG post-dose-1 is separate + larger."
+  dois:
+    - "10.1021/acs.analchem.6b03109"   # Chen 2016 — pre-existing IgG/IgM anti-PEG in healthy individuals
+    - "10.1002/wnan.1339"              # Yang & Lai 2015 — anti-PEG immunity review
+    - "10.1002/cncr.22739"             # Armstrong 2007 — anti-PEG antibodies adversely affect PEG-asparaginase
+    - "10.1016/j.addr.2020.07.024"     # Kozma 2020 — anti-PEG antibodies (properties/formation/testing)
+
+# which palette vehicles are PEGylated (LNP-mRNA uses a PEG-lipid). All others abstain.
+pegylated_vehicles: [lnp_mrna]

{pen_stack-5.4.0 → pen_stack-5.6.0}/configs/known_unknowns.yaml

@@ -65,3 +65,30 @@ known_unknowns:
     match_terms: ["germline", "heritable", "pass to offspring", "embryo", "inherited by children",
                   "future generations"]
     patterns: []
+
+  # v5.6 WS-EXT — immune axes that are mechanistically distinct from what the v5.2-v5.6 oracles compute, and
+  # for which PEN-STACK has no grounded model: declared known-unknowns rather than faked.
+  - id: cd4_mhcii_help
+    title: "CD4 / MHC-II helper-epitope load"
+    requires: "MHC-II binding prediction over the capsid/transgene + a model linking CD4 help to antibody/memory formation"
+    why: "the v5.3 capsid-epitope oracle computes CD8 / MHC-I presentation ONLY; CD4 / MHC-II helper epitopes
+      (which drive antibody formation and durable memory) are NOT modelled — a distinct, ungrounded axis here"
+    match_terms: ["cd4", "mhc-ii", "mhc class ii", "helper t", "helper epitope", "th cell", "t-helper"]
+    patterns: []
+
+  - id: preexisting_capsid_tcell
+    title: "pre-existing capsid-specific memory T-cell immunity"
+    requires: "population prevalence of capsid-specific memory T cells (distinct from neutralizing-antibody serosurveys)"
+    why: "v5.5 seroprevalence is anti-vector ANTIBODY (B-cell) prevalence; pre-existing capsid-specific
+      memory T-CELL immunity is a separate dimension PEN-STACK does NOT model (sparse, assay-dependent data)"
+    match_terms: ["pre-existing t-cell", "preexisting t cell", "capsid-specific t cell", "memory t cell",
+                  "t-cell immunity to capsid", "cellular pre-existing immunity"]
+    patterns: []
+
+  - id: complement_carpa
+    title: "complement activation / CARPA (complement-activation-related pseudoallergy)"
+    requires: "a model of complement activation by the vector/LNP surface (C3/C5 turnover, anaphylatoxins) and infusion-reaction risk"
+    why: "complement/CARPA is mechanistically distinct from the cargo CpG/dsRNA innate axis (v5.4) and the
+      capsid epitope axis; PEN-STACK does NOT model complement activation or infusion-reaction risk"
+    match_terms: ["complement", "carpa", "c3a", "c5a", "anaphylatox", "infusion reaction", "pseudoallergy"]
+    patterns: []

{pen_stack-5.4.0 → pen_stack-5.6.0}/configs/oracles/scope_cards.yaml

@@ -152,3 +152,30 @@ oracles:
     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)"
+
+  seroprevalence:               # v5.5 WS-SEROPREV: anti-vector NAb seroprevalence from serosurvey data
+    family: genome
+    version: "serosurvey-2026"
+    output_kind: baseline       # curated empirical population data, not a model
+    valid_for: "POPULATION pre-existing neutralizing-antibody seroprevalence per capsid serotype, from published
+      serosurveys (AAV Calcedo/Boutin, Ad5 Mast, HSV-1 Looker); preexisting_score = 1 - midpoint/100. The one
+      immune axis that is empirical, not sequence-computable"
+    not_valid_for: "a given PATIENT's NAb titer / sero-status (a clinical test, patient-specific -> a
+      known-unknown); precise region/age/assay-specific values (a range, not a point); functional-NAb vs
+      IgG-binding distinctions; T-cell immunity (that is the capsid_epitope oracle); anti-PEG immunity"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; Calcedo 10.1086/595830, Boutin 10.1089/hum.2009.182, Mast
+      10.1016/j.vaccine.2009.10.145, Looker 10.1371/journal.pone.0140765)"
+
+  antipeg:                      # v5.6 WS-PEG: anti-PEG antibody prevalence (gates LNP re-dosing)
+    family: genome
+    version: "serosurvey-2026"
+    output_kind: baseline       # curated empirical population data, not a model
+    valid_for: "POPULATION pre-existing anti-PEG antibody prevalence for PEGylated LNP (a property of the PEG
+      chemistry, not an encoded sequence); preexisting_antipeg_score = 1 - midpoint/100; gates RE-DOSING"
+    not_valid_for: "a given PATIENT's anti-PEG titer / sero-status (a clinical test, patient-specific -> a
+      known-unknown); INDUCED anti-PEG after dose 1 (a separate, larger dynamic, esp. post mRNA-LNP); precise
+      region/age/assay values (a range, not a point); non-PEGylated vehicles (abstains)"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; Chen 10.1021/acs.analchem.6b03109, Yang&Lai 10.1002/wnan.1339,
+      Armstrong 10.1002/cncr.22739, Kozma 10.1016/j.addr.2020.07.024)"

pen_stack-5.6.0/configs/seroprevalence.yaml

@@ -0,0 +1,64 @@
+# PEN-STACK v5.5 - anti-vector neutralizing-antibody SEROPREVALENCE (WS-SEROPREV).
+#
+# Pre-existing humoral immunity to a viral capsid is the one immune axis that CANNOT be computed from sequence:
+# it is the prevalence, in a population, of people who already carry neutralizing antibodies against the vector
+# from natural exposure. The only honest grounding is published serosurvey DATA. This table curates the
+# population NAb/IgG seroprevalence per serotype from canonical serosurveys, as RANGES (the literature varies by
+# region, age, and assay - IgG-binding vs functional-NAb), each with >=1 DOI.
+#
+# preexisting_score = 1 - midpoint(seroprevalence_pct)/100   (1 = fewest patients excluded by pre-existing NAb).
+#
+# HONESTY (scope card `seroprevalence`): this is a POPULATION prevalence, NOT a given patient's NAb titer (that
+# is a clinical test, patient-specific -> a known-unknown); it is region/age/assay-dependent (ranges, not point
+# values); and it is the pre-existing HUMORAL axis only (B-cell / antibody), distinct from the T-cell epitope
+# load computed in v5.3.
+
+version: "1.0"
+
+serotypes:
+  AAV_aggregate:                 # serotype-agnostic AAV (AAV_single / AAV_dual): across common serotypes
+    nab_seroprevalence_pct: [30, 60]
+    note: "serotype- and region-dependent; AAV2 highest, AAV8/9 lower"
+    dois: ["10.1086/595830", "10.1089/hum.2009.182"]
+  AAV2:
+    nab_seroprevalence_pct: [50, 72]
+    note: "highest of the common serotypes (Calcedo ~72%, Boutin IgG ~67%)"
+    dois: ["10.1086/595830", "10.1089/hum.2009.182"]
+  AAV1:
+    nab_seroprevalence_pct: [50, 67]
+    dois: ["10.1089/hum.2009.182"]
+  AAV5:
+    nab_seroprevalence_pct: [30, 40]
+    dois: ["10.1089/hum.2009.182", "10.1086/595830"]
+  AAV6:
+    nab_seroprevalence_pct: [30, 46]
+    dois: ["10.1089/hum.2009.182"]
+  AAV8:
+    nab_seroprevalence_pct: [20, 40]
+    note: "lower pre-existing immunity (Calcedo ~38%)"
+    dois: ["10.1086/595830", "10.1089/hum.2009.182"]
+  AAV9:
+    nab_seroprevalence_pct: [30, 50]
+    dois: ["10.1086/595830"]
+  Ad5:
+    nab_seroprevalence_pct: [40, 90]
+    note: "very high and strongly region-dependent (highest in sub-Saharan Africa); Mast 2010"
+    dois: ["10.1016/j.vaccine.2009.10.145"]
+  HSV1:
+    nab_seroprevalence_pct: [50, 70]
+    note: "global adult HSV-1 seroprevalence (Looker 2015, ages 0-49 ~67%)"
+    dois: ["10.1371/journal.pone.0140765"]
+  VSV:
+    nab_seroprevalence_pct: [0, 5]
+    note: "VSV is not endemic in humans -> negligible pre-existing immunity to VSV-G-pseudotyped lentivirus"
+    dois: ["10.1038/mt.2011.287"]
+
+# which serotype grounds each vehicle's pre-existing-immunity axis. Non-viral vehicles carry no foreign capsid
+# -> no pre-existing ANTI-VECTOR humoral immunity (anti-PEG for LNP is an emerging, separate exception).
+vehicle_serotype:
+  AAV_single: AAV_aggregate
+  AAV_dual: AAV_aggregate
+  helper_dependent_adenovirus: Ad5
+  hsv_amplicon: HSV1
+  lentivirus: VSV
+non_viral: [lnp_mrna, evlp, electroporation]