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

{pen_stack-5.5.0 → pen_stack-5.6.0}/CHANGELOG.md

@@ -3,6 +3,40 @@
 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

{pen_stack-5.5.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.5.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.5.0 → pen_stack-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.5.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.5.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,22 @@ 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
@@ -217,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 |
@@ -381,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.
 ```
@@ -395,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 |
@@ -519,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)
@@ -540,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.5.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.5.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,22 @@ 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
@@ -142,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 |
@@ -306,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.
 ```
@@ -320,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 |
@@ -444,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)
@@ -465,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.5.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.5.0 → pen_stack-5.6.0}/configs/oracles/scope_cards.yaml

@@ -166,3 +166,16 @@ oracles:
     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/docs/delivery_immunology.md

@@ -0,0 +1,150 @@
+# Delivery immunology — the safety↔efficacy balance (v5.1 → v5.5)
+
+PEN-STACK scores and constrains the **whole** delivery palette (8 vehicles), not just dual-AAV. v5.1–v5.5 added
+a delivery **safety↔efficacy** layer: a per-vehicle immune / safety / efficacy profile, a user-weightable
+ranking, and — crucially — **four of the five immune/safety axes are now grounded in real data or sequence**
+rather than hand-typed `low/moderate/high` tiers.
+
+> **The honesty invariant (unchanged across the program).** The in-vivo immune *magnitude* — how strongly a
+> given patient or construct will actually react — is a declared **known-unknown**
+> (`configs/known_unknowns.yaml: in_vivo_immunogenicity`) and is **never predicted**. Every oracle below
+> abstains rather than fabricate when it lacks data, and each carries a scope card stating exactly what it is
+> *not* valid for. What is surfaced is a relative, auditable, cited signal — not a per-patient prediction.
+
+## The 8-vehicle palette
+
+`configs/delivery_vehicles.yaml` — AAV (single / dual), lentivirus, helper-dependent adenovirus, HSV amplicon,
+LNP-mRNA, eVLP, electroporation. Each carries cargo capacity, integration, cargo form, an `immune_safety` block
+(documented ordinal priors + cited DOIs), and the computed-oracle hooks below.
+
+## The safety↔efficacy profile
+
+`pen_stack/planner/delivery_immunology.py::safety_efficacy_profile(vehicle)` returns, per vehicle:
+
+- **two separate safety sub-axes** — never collapsed, because they are different *kinds* of risk:
+  - `immune_score` — immunogenicity (largely reversible; bears on eligibility / re-dosing), the mean of four
+    immune axes (pre-existing, NAb, innate, adaptive);
+  - `genotox_score` — insertional / oncogenic risk (permanent);
+- a headline `safety_score = min(immune_score, genotox_score)` (precautionary worst-axis);
+- `efficacy_score`, the documented `tradeoff` sentence, and the standing magnitude scope flag.
+
+`recommend_delivery(cargo_form, cargo_bp, safety_weight, in_vivo)` ranks the eligible palette along the
+frontier: `balance = safety_weight·safety + (1−safety_weight)·efficacy`. Move `safety_weight` from 0→1 to slide
+from efficacy-first to safety-first. This reproduces the motivating tradeoff: **AAV** is dinged on
+immunogenicity (non-integrating, but NAb-limited), **lentivirus** on genotoxicity (a highly efficacious
+integrator whose insertional risk is the dominant concern).
+
+`verify(design)` surfaces the profile as `delivery_profile` plus a `delivery_immune_profile` scope flag, and —
+when a `cargo_seq` is supplied — a `cargo_innate_sensing` flag (see below).
+
+## v5.6 — completion & calibration: anti-PEG, proxy honesty, and the unified profile
+
+v5.6 finishes the picture and tells the truth about it (`docs` + `pen_stack/planner/{antipeg_oracle,immune_profile}.py`,
+`pen_stack/validate/immune_calibration.py`):
+
+- **Anti-PEG axis (WS-PEG)** — `antipeg_oracle.py` + `configs/antipeg.yaml`. Pre-existing/induced anti-PEG
+  antibodies gate **re-dosing** of PEGylated LNP. Same honest serosurvey pattern as v5.5: a population
+  prevalence **range** (25–72 %, Chen 2016 / Yang & Lai 2015 / Armstrong 2007 / Kozma 2020) →
+  `preexisting_antipeg_score = 1 − midpoint/100 = 0.515`, range surfaced as uncertainty. **Abstains** for
+  non-PEGylated vehicles. Patient titer and post-dose-1 *induced* anti-PEG stay known-unknowns.
+- **Proxy calibration (WS-CALIB)** — `immune_calibration.py`. `calibrate_axis()` computes a Spearman ρ +
+  bootstrap CI and labels an axis **outcome-validated only when the CI excludes zero** (else `weak_proxy`;
+  `mechanistic_proxy` when N < 6). Because no sufficient public *paired* (proxy, observed-immunogenicity)
+  dataset exists, **every axis is currently labelled a mechanistic/population proxy** — that honest label is
+  the deliverable, and it travels with the profile. (The machinery is proven on synthetic data; it will
+  promote an axis only from real data.)
+- **Unified immune-risk profile (WS-PROFILE)** — `immune_profile.py`, exposed as **`Verdict.immune_profile`**.
+  A per-design **vector** of all axes, each with its own value + uncertainty + scope + validation label;
+  **`collapsed_score is None`** (never fused into one overconfident number — asserted by test);
+  `known_unknowns` listed; abstaining axes report `None`, not a guess.
+- **WS-EXT** — a documented qualitative **route/immune-privilege modifier** (eye/CNS materially lower realized
+  immunogenicity vs systemic; Streilein 2003 `10.1038/nri1224`; *no* fabricated magnitude), and three
+  mechanistically-distinct axes registered as **known-unknowns**: CD4/MHC-II helper epitopes,
+  pre-existing capsid-specific T-cell immunity, and complement/CARPA.
+
+## The axes — four computed/grounded, anti-PEG added, one documented
+
+| Axis | Risk kind | v5.1 | Now | Grounding |
+|---|---|---|---|---|
+| **Genotoxicity** | permanent / oncogenic | tier | **computed** (v5.2) | integration-site catalogues × oncogene loci |
+| **Adaptive (CD8 T-cell)** | reversible | tier | **computed** (v5.3) | MHC-I epitope load over the capsid sequence |
+| **Innate** | reversible | tier | **computed** (v5.4) | CpG / dsRNA motif load of the cargo sequence |
+| **Pre-existing / NAb (B-cell)** | reversible (eligibility) | tier | **data-grounded** (v5.5) | published serosurveys |
+| **Anti-PEG (LNP re-dosing)** | reversible (re-dosing) | — | **data-grounded** (v5.6) | anti-PEG serosurveys |
+| **Efficacy** | — | tier | documented | construct/context-specific by nature |
+
+Each computed signal answers through the v4.0 `OracleResult` contract (value + provenance + native uncertainty
++ scope card + `output_kind="baseline"`), and the small committed artifacts (where any) keep the heavy
+data/models on the VM so the package and CI stay light.
+
+### Genotoxicity — `genotoxicity_oracle.py` (v5.2, WS-GENOTOX)
+
+For an **integrating** vector, the observed enrichment of its integration sites near COSMIC Cancer-Gene-Census
+oncogenes: `P(site within 50 kb of an oncogene)` over the vector class's VISDB catalogue, vs genome background
+(2.21 %). `genotox_score = min(1, 1/enrichment)`.
+
+- **Lentiviral (HIV) 2.08×** enrichment (n = 88,743, robust) vs **gammaretroviral (MLV) 5.65×** (the LMO2 /
+  SCID-X1 comparator; n = 32, flagged small-n) — reproducing the *lentivirus-safer-than-gammaretrovirus*
+  ordering **from data**. The computed lentivirus score (0.48) **validates** the v5.1 documented "moderate"
+  tier (0.5).
+- Non-integrating vehicles → 1.0 by mechanism. *Not valid for:* the in-vivo clonal / leukemogenesis **outcome**
+  (a known-unknown). Build: `scripts/p52_build_genotox_oracle.py` → `configs/genotoxicity_oracle.yaml`.
+  Provenance: VISDB `10.1093/nar/gkz867`, COSMIC CGC `10.1038/s41568-018-0060-1`.
+
+### Adaptive / CD8 — `capsid_epitope_oracle.py` (v5.3, WS-EPITOPE)
+
+For a **viral** vector, the fraction of its capsid/envelope antigen presentable to CD8 T cells across a
+frequent HLA-I panel (MHCflurry 2.0, %rank ≤ 0.5 over 9-mers × 12 alleles): `capsid_immune_score = 1 −
+epitope_fraction_strong`.
+
+- AAV2 VP1 is the **least** epitope-dense capsid (0.72), Ad5 hexon among the most (0.82) — the documented
+  adaptive ordering reproduced **from sequence**. All 8 vehicles covered (5 viral computed, 3 non-viral 1.0 by
+  mechanism).
+- The score is *intrinsic* presentability, so it is folded into the adaptive axis **only for in-vivo**
+  vehicles; for **ex-vivo lentivirus** (VSV-G is intrinsically epitope-dense but barely seen ex vivo) it is
+  reported but muted. *Not valid for:* the patient-HLA-specific response (a known-unknown); antibody immunity
+  (this is CD8/MHC-I only). Sequences UniProt-verified (`configs/capsid_sequences.fasta`: AAV2 VP1 P03135, Ad5
+  hexon P04133, VSV-G P03522, HSV-1 gD P57083 + gB P06437). Provenance: MHCflurry `10.1016/j.cels.2020.06.010`,
+  HLA supertypes `10.1186/1471-2172-9-1`.
+
+### Innate — `innate_sensing.py` (v5.4, WS-INNATE)
+
+For the **cargo sequence** (computed live in `verify()` when a `cargo_seq` is supplied):
+
+- **DNA** → CpG observed/expected (TLR9/cGAS): vertebrate genome ~0.2 is tolerated, non-depleted DNA → 1 is
+  stimulatory; `innate_score = max(0, 1 − CpG_O/E)`.
+- **mRNA** → U-richness + ViennaRNA dsRNA pairing (TLR7/8 + RIG-I/MDA5/PKR); a **partial** signal (flagged
+  `extrapolating`) — the dominant evasion lever, nucleoside modification (m1-pseudouridine), is *not*
+  sequence-derivable.
+- **RNP** → minimal/transient. *Not valid for:* the realized in-vivo innate response, RNA nucleoside
+  modification, DNA methylation state. Provenance: CpG-TLR9 `10.1073/pnas.161293498`, CpG-depleted AAV
+  `10.1172/JCI68205`, RNA modification `10.1016/j.immuni.2005.06.008`.
+
+### Pre-existing / neutralizing antibody — `seroprevalence_oracle.py` (v5.5, WS-SEROPREV)
+
+The one axis that **cannot** be computed from sequence — anti-capsid NAb seroprevalence is a population
+prevalence from natural exposure. Grounded in published serosurveys (`configs/seroprevalence.yaml`, ranges with
+DOIs): `preexisting_score = 1 − midpoint(seroprevalence)/100`, range half-width surfaced as native uncertainty.
+
+| Serotype (vehicle) | NAb seroprevalence | pre-existing score |
+|---|---|---|
+| Ad5 → HDAd | 40–90 % | 0.35 |
+| HSV-1 → HSV | 50–70 % | 0.40 |
+| AAV (aggregate) → AAV | 30–60 % | 0.55 |
+| VSV → lentivirus | 0–5 % | 0.975 (muted, ex-vivo) |
+
+Folded for in-vivo vehicles (serum NAb neutralises the vector in vivo), muted for ex-vivo; non-viral → 1.0 by
+mechanism. *Not valid for:* a given **patient's** NAb titer / sero-status (a clinical test, patient-specific →
+a known-unknown). Provenance: Calcedo `10.1086/595830`, Boutin `10.1089/hum.2009.182`, Mast
+`10.1016/j.vaccine.2009.10.145`, Looker `10.1371/journal.pone.0140765`.
+
+## Outcome
+
+Across v5.1→v5.5 the delivery immune/safety profile moved from documented `low/moderate/high` tiers to **real
+calculations from data and sequence** on four of the five axes, spanning all 8 vehicles — each grounded, each
+abstaining rather than fabricating, with the in-vivo magnitude always a declared known-unknown. The result is
+the safety↔efficacy balance the program set out to provide: *computed wherever the science allows, documented
+where it does not, and explicitly out-of-scope where no one can yet predict.*
+
+See also: [Oracle mesh](oracles.md) · [Delivery palette & router](delivery.md) · [Verification](verify.md) ·
+[Scope & known-unknowns](scope.md). Pre-registrations: `prereg/ws_{immune,genotox,epitope,innate,seroprev}.yaml`.

{pen_stack-5.5.0 → pen_stack-5.6.0}/docs/index.md

@@ -12,6 +12,7 @@ Three layers, one engine:
 | **Writer Atlas** (`pen_stack.atlas` / `mech` / `score`) | What can write, and how well? (33,370 systems across 8 families, measured axes) |
 | **Cross-link** (`pen_stack.atlas.crosslink`) | Which writers reach a locus / which loci a writer reaches |
 | **Write Planner** (`pen_stack.planner`, Phase 3) | Find the optimal site x writer x cargo x delivery for a goal |
+| **Delivery immunology** (`pen_stack.planner.delivery_immunology` + oracles) | Balance safety vs efficacy across the 8-vehicle palette — four of five immune/safety axes **computed from data/sequence** ([details](delivery_immunology.md)) |
 
 ## Install
 

{pen_stack-5.5.0 → pen_stack-5.6.0}/pen_stack/__init__.py

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

{pen_stack-5.5.0 → pen_stack-5.6.0}/pen_stack/agent/cite.py

@@ -46,6 +46,15 @@ def curated_dois() -> frozenset[str]:
             dois.update(_rec.get("dois", []) or [])
     except FileNotFoundError:
         pass
+    # v5.6 anti-PEG serosurvey provenance
+    try:
+        ap = yaml.safe_load(resource("configs/antipeg.yaml").read_text(encoding="utf-8"))
+        dois.update((ap.get("prevalence") or {}).get("dois", []) or [])
+    except FileNotFoundError:
+        pass
+    # v5.6 WS-EXT route/immune-privilege modifier provenance
+    from pen_stack.planner.immune_profile import ROUTE_MODIFIER_DOI
+    dois.add(ROUTE_MODIFIER_DOI)
     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.6.0/pen_stack/planner/antipeg_oracle.py

@@ -0,0 +1,75 @@
+"""Anti-PEG immunity axis for PEGylated LNP (v5.6, WS-PEG).
+
+The one delivery-immunology axis missing from v5.1-v5.5: pre-existing / induced anti-PEG antibodies, which
+gate RE-DOSING of PEGylated LNP. Anti-PEG is a property of the PEGylation chemistry, not of any encoded
+sequence — so, exactly like the v5.5 anti-vector seroprevalence oracle, it is grounded in published serosurvey
+DATA (configs/antipeg.yaml, a population prevalence range with DOIs):
+
+    preexisting_antipeg_score = 1 - midpoint(anti_PEG_prevalence_pct) / 100    # 1 = fewest excluded
+
+Answers through the v4.0 OracleResult contract (output_kind="baseline"). ABSTAINS for non-PEGylated vehicles.
+HONESTY: a POPULATION prevalence (a range, region/age/assay-dependent), NOT a given patient's anti-PEG titer
+(a clinical test, patient-specific -> a known-unknown); induced anti-PEG after dose 1 is a separate, larger
+dynamic (noted, not modelled).
+"""
+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
+
+_SCOPE_CARD = "antipeg"
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict:
+    return yaml.safe_load(resource("configs/antipeg.yaml").read_text(encoding="utf-8"))
+
+
+def _all_dois() -> list[str]:
+    return list((_table().get("prevalence") or {}).get("dois", []) or [])
+
+
+def _prov(**extra) -> Provenance:
+    return Provenance(model="anti_peg_seroprevalence", version=str(_table().get("version", "1.0")),
+                      source="cache", extra=extra)
+
+
+def antipeg_oracle(vehicle_name: str, pegylated: bool | None = None) -> OracleResult:
+    """Anti-PEG pre-existing immunity for a vehicle, as an OracleResult (v4.0 contract).
+
+    - PEGylated vehicle -> preexisting_antipeg_score = 1 - midpoint(prevalence)/100 (gates RE-DOSING).
+    - non-PEGylated vehicle -> ABSTAINS (available=False, value=None): the anti-PEG axis is not applicable.
+    `pegylated` overrides the config's vehicle list when given. Never fabricates a patient titer."""
+    t = _table()
+    is_peg = pegylated if pegylated is not None else (vehicle_name in (t.get("pegylated_vehicles") or []))
+    if not is_peg:
+        return OracleResult(oracle="genome", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                            in_scope=False, available=False, output_kind="baseline",
+                            note=f"non-PEGylated vehicle {vehicle_name!r}: anti-PEG axis not applicable (abstains).")
+
+    rec = t["prevalence"]
+    lo, hi = rec["anti_peg_prevalence_pct"]
+    mid = (lo + hi) / 2.0
+    score = max(0.0, min(1.0, 1.0 - mid / 100.0))
+    return OracleResult(
+        oracle="genome",
+        value={"preexisting_antipeg_score": round(score, 3), "anti_peg_prevalence_pct": [lo, hi],
+               "midpoint_pct": mid, "gates": "re-dosing", "dois": rec.get("dois", [])},
+        provenance=_prov(dois=rec.get("dois", [])), native_uncertainty=round((hi - lo) / 200.0, 4),
+        scope_card=_SCOPE_CARD, in_scope=True, extrapolating=False, output_kind="baseline", available=True,
+        note=(f"population anti-PEG prevalence {lo}-{hi}% -> preexisting_antipeg_score={score:.3f}; gates "
+              "RE-DOSING of PEGylated LNP. A POPULATION range (region/age/assay-dependent) - NOT a patient's "
+              "anti-PEG titer (a known-unknown); induced anti-PEG after dose 1 is a separate, larger dynamic "
+              "(not modelled)."))
+
+
+def computed_antipeg_score(vehicle_name: str, pegylated: bool | None = None) -> tuple[float | None, OracleResult]:
+    """Convenience: (anti-PEG score or None, full OracleResult). None when the oracle abstains (non-PEG).
+    Never fabricates."""
+    r = antipeg_oracle(vehicle_name, pegylated)
+    val = (r.value or {}).get("preexisting_antipeg_score") if (r.available and r.value) else None
+    return val, r