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

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

@@ -3,6 +3,38 @@
 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.1.0] - 2026-06-10 - v5.1 release: Delivery immunology (the safety↔efficacy balance)
+
+The delivery palette gains a **documented, cited, qualitative immune + safety + efficacy profile** per vehicle,
+so the substrate can make the safety↔efficacy tradeoff legible and user-weightable — without ever predicting an
+immune magnitude (that stays a declared known-unknown). Workstream WS-IMMUNE, SHA-locked.
+
+### Added
+- **WS-IMMUNE config** — `configs/delivery_vehicles.yaml` (v1.1): an `immune_safety` block on all 8 vehicles
+  (`preexisting_immunity`, `neutralizing_antibody`, `innate_immune`, `adaptive_immune`, `genotoxicity`,
+  `efficacy`, `tradeoff`, `immune_dois`) — DOCUMENTED ordinal low/moderate/high priors, every `immune_doi`
+  Crossref-verified and in the curated-DOI set (citations resolve by construction).
+- **WS-IMMUNE planner** — `pen_stack/planner/delivery_immunology.py`: `safety_efficacy_profile()` reports two
+  **separate** safety sub-axes — `immune_score` (immunogenicity; reversible, eligibility/re-dosing) and
+  `genotox_score` (insertional/oncogenic; permanent) — never collapsed, with headline
+  `safety_score = min(immune_score, genotox_score)` (precautionary worst-axis). `recommend_delivery(cargo_form,
+  cargo_bp, safety_weight, in_vivo)` ranks the eligible palette along the safety↔efficacy frontier by a
+  user-supplied weight. Reproduces the stated tradeoff: AAV is dinged on immunogenicity, lentivirus on
+  genotoxicity. `prereg/ws_immune.yaml`.
+- **WS-IMMUNE verify** — `Verdict.delivery_profile` + a `delivery_immune_profile` scope flag: `verify()` now
+  surfaces the documented profile and tradeoff for a chosen vehicle, always attaching the standing
+  `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude.
+
+### Changed
+- Version 5.0.0 -> 5.1.0 (minor — additive delivery-immunology layer); `cite.curated_dois()` now also ingests
+  the per-vehicle `immune_dois`.
+
+### Honesty invariant (unchanged)
+- The in-vivo immune MAGNITUDE (patient/construct-specific response) remains a declared known-unknown
+  (`configs/known_unknowns.yaml: in_vivo_immunogenicity`) and is **never** predicted. v5.1 exposes only
+  documented ordinal priors plus a transparent, user-weighted ranking — it makes the boundary legible, it does
+  not close it.
+
 ## [5.0.0] - 2026-06-09 - v5.0 release: the Co-Scientist (capstone — smart because it is grounded)
 
 The reasoning ceiling rises while the grounding floor stays fixed: a co-scientist that proposes multiple

{pen_stack-5.0.0 → pen_stack-5.1.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.0.0
-date-released: 2026-06-01
+version: 5.1.0
+date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.0.0
+Version: 5.1.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
@@ -77,10 +77,12 @@ Dynamic: license-file
 
 # PEN-STACK
 
-### The Writable Genome - open infrastructure for genome *writing*
+### The verification & grounding substrate for genome-writing AI — matured into a co-scientist
 
-*Editing tools tell you **how** to change a base. PEN-STACK tells you **where** in the genome you can safely
-and durably write new DNA, **which enzyme** can write it there, and **how** to design the write end-to-end.*
+*The foundation models *generate*; PEN-STACK *checks*. It tells you **where** in the genome you can safely and
+durably write, **which enzyme** can write it there, and **how** to design the write end-to-end — then verifies
+every design against rule-grounded mechanism, reports calibrated confidence, cites its reasoning, and says
+"out of scope" rather than guess. Every number comes from a validated tool; nothing is fabricated.*
 
 [![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)
@@ -89,7 +91,7 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![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.0.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.1.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/)
@@ -133,6 +135,23 @@ 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.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+carries a documented, cited, qualitative immune + safety + efficacy profile — so you can ask for a *balance*
+(AAV is safe by integration but neutralizing-antibody/pre-existing-immunity limited; lentivirus is a highly
+efficacious integrator but its genotoxicity is the dominant concern). Crucially, the in-vivo immune
+**magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
+patient-specific immune response.
+
+| 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 |
+| **IMMUNE planner** | `planner/delivery_immunology.py` — `safety_efficacy_profile()` / `recommend_delivery()` | two **separate** safety sub-axes (`immune_score` reversible vs `genotox_score` permanent), never collapsed; headline `safety_score = min(...)` (worst-axis); ranks the palette along the safety↔efficacy frontier by a **user weight** |
+| **IMMUNE verify** | `Verdict.delivery_profile` + `delivery_immune_profile` scope flag | `verify()` surfaces the documented tradeoff for a chosen vehicle, always attaching the `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude |
+
+See `prereg/ws_immune.yaml`.
+
 ## What is new in v5.0 — the Co-Scientist (smart because it is grounded)
 
 v5.0 matures the reasoning layer on top of everything beneath it. Given a goal and an intent, PEN-STACK

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

@@ -2,10 +2,12 @@
 
 # PEN-STACK
 
-### The Writable Genome - open infrastructure for genome *writing*
+### The verification & grounding substrate for genome-writing AI — matured into a co-scientist
 
-*Editing tools tell you **how** to change a base. PEN-STACK tells you **where** in the genome you can safely
-and durably write new DNA, **which enzyme** can write it there, and **how** to design the write end-to-end.*
+*The foundation models *generate*; PEN-STACK *checks*. It tells you **where** in the genome you can safely and
+durably write, **which enzyme** can write it there, and **how** to design the write end-to-end — then verifies
+every design against rule-grounded mechanism, reports calibrated confidence, cites its reasoning, and says
+"out of scope" rather than guess. Every number comes from a validated tool; nothing is fabricated.*
 
 [![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)
@@ -14,7 +16,7 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![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.0.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.1.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/)
@@ -58,6 +60,23 @@ 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.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+carries a documented, cited, qualitative immune + safety + efficacy profile — so you can ask for a *balance*
+(AAV is safe by integration but neutralizing-antibody/pre-existing-immunity limited; lentivirus is a highly
+efficacious integrator but its genotoxicity is the dominant concern). Crucially, the in-vivo immune
+**magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
+patient-specific immune response.
+
+| 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 |
+| **IMMUNE planner** | `planner/delivery_immunology.py` — `safety_efficacy_profile()` / `recommend_delivery()` | two **separate** safety sub-axes (`immune_score` reversible vs `genotox_score` permanent), never collapsed; headline `safety_score = min(...)` (worst-axis); ranks the palette along the safety↔efficacy frontier by a **user weight** |
+| **IMMUNE verify** | `Verdict.delivery_profile` + `delivery_immune_profile` scope flag | `verify()` surfaces the documented tradeoff for a chosen vehicle, always attaching the `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude |
+
+See `prereg/ws_immune.yaml`.
+
 ## What is new in v5.0 — the Co-Scientist (smart because it is grounded)
 
 v5.0 matures the reasoning layer on top of everything beneath it. Given a goal and an intent, PEN-STACK

pen_stack-5.1.0/configs/delivery_vehicles.yaml

@@ -0,0 +1,185 @@
+# PEN-STACK v3.3 — Delivery vehicle palette (WS-D / North-Star §4). The substrate must score and constrain
+# the WHOLE delivery palette, not just dual-AAV. Each row: cargo capacity, integration, division dependence,
+# immunogenicity PRIOR (qualitative; MAGNITUDE is a known-unknown — never predicted), re-dosability, tropism,
+# ex/in-vivo, compatible cargo form {DNA, mRNA, RNP}, and >=1 DOI. Values cited to 2026 sources.
+# `constraint_key` maps to configs/delivery_constraints.yaml for the sequence-level scan.
+#
+# v5.1 — `immune_safety`: a DOCUMENTED, CITED, QUALITATIVE (low/moderate/high) immune + safety + efficacy
+# profile per vehicle, for the safety<->efficacy balance (planner/delivery_immunology.py). These are ordinal
+# DOCUMENTED PRIORS from the literature — NOT a predicted, patient- or construct-specific immune magnitude
+# (that stays a known-unknown / scope flag, `in_vivo_immunogenicity`, never predicted). `genotoxicity` = the
+# integration / insertional-mutagenesis risk; `efficacy` = transduction/integration efficiency.
+
+version: "1.1"
+
+vehicles:
+  AAV_single:
+    cargo_capacity_bp: 4700
+    integrating: false            # episomal
+    division_dependent: false
+    immunogenicity_prior: "moderate-high; pre-existing NAbs exclude 30-60% of patients"
+    re_dosable: false
+    tropism: "serotype-dependent (liver, muscle, CNS, retina)"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: AAV
+    dois: ["10.1038/s41573-019-0012-9"]
+    immune_safety:
+      preexisting_immunity: high       # serotype-dependent; seroprevalence ~30-60% of patients
+      neutralizing_antibody: high      # pre-existing + vector-elicited NAbs; exclude/relapse risk
+      innate_immune: low
+      adaptive_immune: moderate        # capsid-directed CD8 T-cell responses
+      genotoxicity: low                # episomal, non-integrating
+      efficacy: high                   # efficient in-vivo transduction (cargo-limited ~4.7 kb)
+      tradeoff: "safe vector (non-integrating, low genotoxicity) BUT pre-existing/elicited NAbs limit eligibility and prevent re-dosing"
+      immune_dois: ["10.1182/blood-2013-01-306647", "10.1089/hum.2009.182", "10.1016/j.ymthe.2019.12.010"]
+
+  AAV_dual:
+    cargo_capacity_bp: 9000       # split across 2 capsids (~9 kb); efficiency drops sharply
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "as AAV; split lowers efficiency"
+    re_dosable: false
+    tropism: "serotype-dependent"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: AAV
+    dois: ["10.1128/JVI.79.15.9933-9944.2005"]   # Grieger & Samulski 2005, AAV packaging capacity
+    immune_safety:
+      preexisting_immunity: high       # same AAV capsid immunology as single
+      neutralizing_antibody: high
+      innate_immune: low
+      adaptive_immune: moderate
+      genotoxicity: low                # episomal
+      efficacy: moderate               # split across 2 capsids -> co-transduction needed, efficiency drops
+      tradeoff: "as AAV (non-integrating, NAb-limited) AND split-capsid co-transduction lowers efficiency"
+      immune_dois: ["10.1182/blood-2013-01-306647", "10.1089/hum.2009.182"]
+
+  lentivirus:
+    cargo_capacity_bp: 8000
+    integrating: true             # semi-random integration
+    division_dependent: false     # integrates in non-dividing too; strong in dividing
+    immunogenicity_prior: "moderate"
+    re_dosable: false
+    tropism: "broad (VSV-G pseudotyped)"
+    ex_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: lentiviral
+    dois: ["10.1126/science.1233151"]
+    immune_safety:
+      preexisting_immunity: low        # pseudotyped, typically ex-vivo (no host pre-immunity to the vector)
+      neutralizing_antibody: low       # ex-vivo use avoids humoral neutralisation
+      innate_immune: low               # ex-vivo
+      adaptive_immune: low             # ex-vivo
+      genotoxicity: moderate           # INTEGRATING: insertional-mutagenesis risk; SIN-LTR + gene-body bias reduce but do not eliminate it (gamma-retro LMO2 precedent)
+      efficacy: high                   # efficient, STABLE integration; large-ish cargo (~8 kb); transduces non-dividing cells
+      tradeoff: "highly efficacious STABLE integration BUT insertional-mutagenesis / genotoxicity is the dominant safety concern (mitigated by SIN design, not eliminated)"
+      immune_dois: ["10.1038/s41375-018-0106-0", "10.1038/nbt1216", "10.1126/science.1088547"]
+
+  helper_dependent_adenovirus:
+    cargo_capacity_bp: 35000      # "gutless" HDAd, up to ~35 kb
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "high (innate + adaptive)"
+    re_dosable: false
+    tropism: "liver and others"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: plasmid
+    dois: ["10.1128/JVI.72.2.926-933.1998"]   # multiply-deleted (gutless-class) adenovirus vectors
+    immune_safety:
+      preexisting_immunity: high       # widespread prior adenovirus exposure in the population
+      neutralizing_antibody: high      # anti-Ad NAbs common; limit systemic in-vivo dosing
+      innate_immune: high              # potent acute innate/inflammatory response to the capsid
+      adaptive_immune: high            # strong anti-vector adaptive response
+      genotoxicity: low                # non-integrating, episomal "gutless" genome
+      efficacy: high                   # very large cargo (~35 kb), efficient hepatic transduction
+      tradeoff: "huge cargo + non-integrating BUT strong innate+adaptive anti-Ad immunity and pre-existing NAbs are the dominant safety limit for systemic use"
+      immune_dois: ["10.1089/hum.2004.15.1157"]
+
+  hsv_amplicon:
+    cargo_capacity_bp: 100000     # >100 kb
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "high; neurotropic"
+    re_dosable: false
+    tropism: "neurotropic (CNS)"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: plasmid
+    dois: ["10.1038/nbt1101-1067"]   # Wade-Martins 2001, HSV-1 amplicon (iBAC) large genomic-DNA transfer
+    immune_safety:
+      preexisting_immunity: moderate   # prior HSV exposure common, but helper-free amplicon is gene-free of HSV ORFs
+      neutralizing_antibody: moderate  # anti-HSV humoral immunity in seropositive hosts
+      innate_immune: high              # immunogenic / inflammatory in CNS
+      adaptive_immune: high
+      genotoxicity: low                # non-integrating, episomal
+      efficacy: moderate               # massive cargo (>100 kb) + neurotropism, but transient/variable expression
+      tradeoff: "unmatched cargo (>100 kb) and CNS tropism BUT immunogenic/inflammatory and expression is transient"
+      immune_dois: ["10.1089/hum.2004.15.1157"]
+
+  lnp_mrna:
+    cargo_capacity_bp: 15000      # large RNA payload (mRNA encoding the writer/RNP)
+    integrating: false            # transient
+    division_dependent: false
+    immunogenicity_prior: "low/transient"
+    re_dosable: true
+    tropism: "liver-tropic by default"
+    in_vivo: true
+    compatible_cargo_form: [mRNA, RNP]
+    constraint_key: lnp_mrna
+    dois: ["10.1038/s41578-021-00358-0"]
+    immune_safety:
+      preexisting_immunity: low        # no widespread pre-existing immunity to the LNP (anti-PEG is an emerging exception)
+      neutralizing_antibody: low       # anti-PEG antibodies emerging; can accelerate clearance on repeat dosing
+      innate_immune: moderate          # transient innate sensing of mRNA / ionizable lipid (mitigated by mod-nucleosides)
+      adaptive_immune: low             # no anti-vector adaptive memory to a protein capsid
+      genotoxicity: low                # NON-integrating, transient (no insertional risk)
+      efficacy: moderate               # transient expression; potent for hepatic RNP/mRNA but durability is short
+      re_dosable: yes                  # repeatable dosing is the key advantage
+      tradeoff: "SAFEST profile (non-integrating, transient, re-dosable, low pre-existing immunity) BUT expression is transient and anti-PEG immunity can blunt repeat doses"
+      immune_dois: ["10.1016/j.addr.2020.07.024"]
+
+  evlp:
+    cargo_capacity_bp: null       # RNP payload (not a DNA packaging limit)
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "low (transient, no DNA)"
+    re_dosable: true
+    tropism: "engineerable (T cells, retina)"
+    in_vivo: true
+    ex_vivo: true
+    compatible_cargo_form: [RNP]
+    constraint_key: evlp
+    dois: ["10.1016/j.cell.2022.03.045"]
+    immune_safety:
+      preexisting_immunity: low        # protein/RNP payload, no viral capsid; transient
+      neutralizing_antibody: low
+      innate_immune: low               # no DNA, transient delivery
+      adaptive_immune: low
+      genotoxicity: low                # non-integrating RNP, transient nuclease exposure
+      efficacy: moderate               # engineerable tropism; emerging modality, in-vivo efficiency still maturing
+      re_dosable: yes
+      tradeoff: "low-immunogenicity transient RNP delivery with engineerable tropism BUT an emerging modality with still-maturing in-vivo efficiency"
+      immune_dois: ["10.1016/j.ymthe.2019.12.010"]
+
+  electroporation:
+    cargo_capacity_bp: null       # physical; no packaging limit
+    integrating: false            # depends on cargo
+    division_dependent: false
+    immunogenicity_prior: "n/a (ex vivo)"
+    re_dosable: false
+    tropism: "n/a (ex vivo)"
+    ex_vivo: true
+    compatible_cargo_form: [DNA, mRNA, RNP]
+    constraint_key: electroporation
+    dois: ["10.1038/nprot.2014.157"]
+    immune_safety:
+      preexisting_immunity: low        # ex-vivo, physical method; no vector immunology
+      neutralizing_antibody: low       # ex-vivo (n/a in host)
+      innate_immune: low               # ex-vivo
+      adaptive_immune: low             # ex-vivo
+      genotoxicity: low                # cargo-dependent; RNP/transient cargo carries no insertional risk
+      efficacy: high                   # high ex-vivo delivery efficiency across DNA/mRNA/RNP
+      tradeoff: "no vector immunology and high ex-vivo efficiency BUT EX-VIVO ONLY (cell harvest/manufacture required) and cytotoxic at high field strength"
+      immune_dois: ["10.1016/j.ymthe.2019.12.010"]

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

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

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

@@ -28,6 +28,7 @@ def curated_dois() -> frozenset[str]:
     veh = yaml.safe_load(resource("configs/delivery_vehicles.yaml").read_text(encoding="utf-8"))["vehicles"]
     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
     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.1.0/pen_stack/planner/delivery_immunology.py

@@ -0,0 +1,160 @@
+"""Delivery safety<->efficacy balance over DOCUMENTED immune priors (v5.1, WS-IMMUNE).
+
+Motivation (user, v5.1): "we should be able to give a good balance between safety and efficacy. AAV is
+safe but neutralizing antibodies / pre-existing immunity will be there; lentivirus is highly efficacious at
+integrating but its safety is bad." This module turns the per-vehicle ``immune_safety`` block in
+configs/delivery_vehicles.yaml into a transparent, user-weightable ranking of the delivery palette.
+
+THE HONESTY INVARIANT (unchanged across the program): the immune MAGNITUDE — how strongly a given patient or
+construct will react in vivo — is a declared known-unknown (configs/known_unknowns.yaml: ``in_vivo_immunogenicity``)
+and is NEVER predicted here. What this module exposes is strictly:
+
+  * the DOCUMENTED, CITED, ORDINAL (low/moderate/high) literature priors per vehicle, and
+  * a transparent ranking that combines those ordinal tiers under a USER-SUPPLIED safety<->efficacy weight.
+
+The composite scores are an explicit, reproducible function of the documented tiers and the user's weight — not
+a learned or predicted immunogenicity. Every profile carries the scope flag that the magnitude is out of scope,
+plus the curated DOIs so the prior is auditable.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack.planner.delivery_vehicles import load_vehicles, names, vehicle
+
+# Ordinal map for the documented qualitative tiers. Higher = more of the named property.
+# For the BURDEN axes (immunity / NAb / innate / adaptive / genotoxicity) higher = worse (less safe);
+# for the EFFICACY axis higher = better.
+_TIER = {"low": 0.0, "moderate": 1.0, "high": 2.0}
+# Two DISTINCT safety sub-axes are kept separate, never collapsed into one mean, because they are different
+# KINDS of risk: immunogenicity is (largely) reversible and bears on eligibility/re-dosing, whereas
+# genotoxicity (insertional mutagenesis) is a permanent, potentially oncogenic risk. This is exactly the
+# tradeoff the v5.1 request is about ("AAV is safe but NAbs; LV is highly efficacious at integrating but its
+# safety is bad") — so genotoxicity must be a first-class, separately-visible axis, not 1/5 of an average.
+_IMMUNE_AXES = ("preexisting_immunity", "neutralizing_antibody", "innate_immune", "adaptive_immune")
+_GENOTOX_AXIS = "genotoxicity"
+# magnitude is NEVER predicted; this is the known-unknown the profile points back to.
+_MAGNITUDE_SCOPE_ID = "in_vivo_immunogenicity"
+
+
+def _tier(val) -> float | None:
+    if val is None:
+        return None
+    return _TIER.get(str(val).strip().lower())
+
+
+def safety_efficacy_profile(name: str) -> dict | None:
+    """Documented safety<->efficacy profile for one vehicle, derived ONLY from its ``immune_safety`` block.
+
+    Reports the ordinal tiers verbatim and THREE normalised sub-scores (1 = best):
+      * ``immune_score``   = 1 - mean(immune-burden axes)/2  (1 = least immunogenic)
+      * ``genotox_score``  = 1 - genotoxicity/2              (1 = least insertional/oncogenic risk)
+      * ``efficacy_score`` = efficacy/2                       (1 = most efficacious)
+    plus a headline ``safety_score = min(immune_score, genotox_score)`` — a precautionary worst-axis aggregation
+    so a vehicle is only as "safe" as its WORST safety dimension (a non-immunogenic but genotoxic vector is not
+    called safe). Also returns the documented tradeoff sentence, curated DOIs, and the standing scope flag that
+    the immune MAGNITUDE is not predicted. Returns ``None`` for an unknown vehicle; invents no number."""
+    rec = vehicle(name)
+    if rec is None:
+        return None
+    imm = rec.get("immune_safety") or {}
+    immune_present = [t for ax in _IMMUNE_AXES if (t := _tier(imm.get(ax))) is not None]
+    immune_score = (1.0 - (sum(immune_present) / len(immune_present)) / 2.0) if immune_present else None
+    gtox = _tier(imm.get(_GENOTOX_AXIS))
+    genotox_score = (1.0 - gtox / 2.0) if gtox is not None else None
+    sub = [s for s in (immune_score, genotox_score) if s is not None]
+    safety_score = min(sub) if sub else None       # worst-axis; abstain if neither documented
+    eff = _tier(imm.get("efficacy"))
+    efficacy_score = (eff / 2.0) if eff is not None else None
+    _r = lambda x: None if x is None else round(x, 3)  # noqa: E731
+    return {
+        "vehicle": name,
+        "tiers": {ax: imm.get(ax) for ax in (*_IMMUNE_AXES, _GENOTOX_AXIS)} | {"efficacy": imm.get("efficacy")},
+        "immune_score": _r(immune_score),
+        "genotox_score": _r(genotox_score),
+        "safety_score": _r(safety_score),
+        "efficacy_score": _r(efficacy_score),
+        "re_dosable": imm.get("re_dosable", rec.get("re_dosable")),
+        "integrating": rec.get("integrating"),
+        "tradeoff": imm.get("tradeoff"),
+        "immune_dois": list(imm.get("immune_dois", []) or []),
+        "magnitude_scope_flag": {
+            "kind": "known_unknown", "id": _MAGNITUDE_SCOPE_ID,
+            "reason": "the in-vivo immune MAGNITUDE (patient/construct-specific response) is a known-unknown; "
+                      "only documented ordinal priors are surfaced, never a predicted magnitude"},
+        "note": "safety_score = min(immune_score, genotox_score) over DOCUMENTED ordinal tiers — a precautionary "
+                "worst-axis aggregation, not a predicted immunogenicity.",
+    }
+
+
+@lru_cache(maxsize=1)
+def all_profiles() -> tuple:
+    """All vehicle profiles (tuple so it is hashable/cacheable)."""
+    return tuple(p for n in names() if (p := safety_efficacy_profile(n)) is not None)
+
+
+def _balance(profile: dict, safety_weight: float) -> float | None:
+    """Composite = safety_weight * safety_score + (1 - safety_weight) * efficacy_score. None if either axis is
+    undocumented (abstain rather than impute)."""
+    s, e = profile["safety_score"], profile["efficacy_score"]
+    if s is None or e is None:
+        return None
+    w = min(max(float(safety_weight), 0.0), 1.0)
+    return round(w * s + (1.0 - w) * e, 4)
+
+
+def recommend_delivery(cargo_form: str, cargo_bp: int | None = None, *, safety_weight: float = 0.5,
+                       in_vivo: bool | None = None) -> dict:
+    """Rank the delivery palette for a cargo by a USER-WEIGHTED safety<->efficacy balance over documented priors.
+
+    Args:
+        cargo_form: required cargo form (DNA / mRNA / RNP) — only vehicles compatible with it are considered.
+        cargo_bp: if given, vehicles whose ``cargo_capacity_bp`` is smaller are excluded (hard packaging limit).
+        safety_weight: in [0, 1]. 1.0 = rank purely on documented safety; 0.0 = purely on efficacy; 0.5 = balance.
+        in_vivo: if True, exclude ex-vivo-only vehicles (and vice-versa) when the field is documented.
+
+    Returns a dict with the eligible vehicles ranked best-first by the composite, each carrying its documented
+    tiers, tradeoff, and curated DOIs, plus the standing magnitude scope flag. No magnitude is predicted; the
+    composite is an explicit function of the documented ordinal tiers and the caller's weight."""
+    form = (cargo_form or "").strip()
+    veh = load_vehicles()
+    eligible: list[dict] = []
+    excluded: list[dict] = []
+    for n, rec in veh.items():
+        forms = rec.get("compatible_cargo_form", []) or []
+        if form and form not in forms:
+            continue
+        if cargo_bp is not None and rec.get("cargo_capacity_bp") is not None \
+                and int(cargo_bp) > int(rec["cargo_capacity_bp"]):
+            excluded.append({"vehicle": n, "reason": f"cargo {cargo_bp} bp exceeds capacity "
+                                                     f"{rec['cargo_capacity_bp']} bp"})
+            continue
+        if in_vivo is True and rec.get("ex_vivo") and not rec.get("in_vivo"):
+            excluded.append({"vehicle": n, "reason": "ex-vivo-only; an in-vivo route was required"})
+            continue
+        if in_vivo is False and rec.get("in_vivo") and not rec.get("ex_vivo"):
+            excluded.append({"vehicle": n, "reason": "in-vivo-only; an ex-vivo route was required"})
+            continue
+        prof = safety_efficacy_profile(n)
+        if prof is None:
+            continue
+        prof = dict(prof)
+        prof["balance"] = _balance(prof, safety_weight)
+        eligible.append(prof)
+
+    # rank: documented balance first (None last); tie-break by efficacy then safety.
+    eligible.sort(key=lambda p: (p["balance"] is None, -(p["balance"] or 0.0),
+                                 -(p["efficacy_score"] or 0.0), -(p["safety_score"] or 0.0)))
+    return {
+        "cargo_form": form, "cargo_bp": cargo_bp, "safety_weight": min(max(float(safety_weight), 0.0), 1.0),
+        "in_vivo": in_vivo,
+        "ranked": eligible,
+        "recommended": eligible[0]["vehicle"] if eligible else None,
+        "excluded": excluded,
+        "scope_flags": [{"kind": "known_unknown", "id": _MAGNITUDE_SCOPE_ID,
+                         "reason": "ranking is over DOCUMENTED ordinal immune priors; the patient/construct-"
+                                   "specific immune MAGNITUDE is a known-unknown and is not predicted"}],
+        "no_fabrication": True,
+        "note": "balance = safety_weight*safety + (1-safety_weight)*efficacy over documented low/moderate/high "
+                "tiers; change safety_weight to move along the safety<->efficacy frontier.",
+    }

{pen_stack-5.0.0 → pen_stack-5.1.0}/pen_stack/verify/schema.py

@@ -26,6 +26,8 @@ class Verdict(BaseModel):
     no_fabrication: bool = True
     writer_critique: dict[str, Any] | None = None   # v4.0 WS-WV: critique of a generated candidate writer
                                                      # (pass/flag + reasons); NEVER a claim that it works
+    delivery_profile: dict[str, Any] | None = None  # v5.1 WS-IMMUNE: documented ordinal immune/safety/efficacy
+                                                     # priors for the chosen vehicle (NEVER a predicted magnitude)
 
     def summary(self) -> str:
         if self.deferred:

{pen_stack-5.0.0 → pen_stack-5.1.0}/pen_stack/verify/service.py

@@ -92,6 +92,21 @@ def verify(design: Design | dict, question: str | None = None) -> Verdict:
                             "flags": writer_critique["flags"],
                             "reason": "generated writer is critiqued, never claimed to work (v4.0 WS-WV)"})
 
+    # v5.1 WS-IMMUNE: if the design names a delivery vehicle, surface its DOCUMENTED ordinal immune/safety/
+    # efficacy priors (with the standing "magnitude is a known-unknown" scope flag). This never adds confidence
+    # and never predicts a magnitude — it exposes the curated qualitative tradeoff so safety can be weighed.
+    delivery_profile = None
+    if design.delivery_vehicle:
+        from pen_stack.planner.delivery_immunology import safety_efficacy_profile
+        delivery_profile = safety_efficacy_profile(design.delivery_vehicle)
+        if delivery_profile and delivery_profile.get("tradeoff"):
+            scope_flags.append({"kind": "delivery_immune_profile",
+                                "vehicle": delivery_profile["vehicle"],
+                                "tradeoff": delivery_profile["tradeoff"],
+                                "magnitude_id": delivery_profile["magnitude_scope_flag"]["id"],
+                                "reason": "documented ordinal immune/safety priors surfaced; the in-vivo immune "
+                                          "MAGNITUDE remains a known-unknown (not predicted)"})
+
     return Verdict(
         legal=routed["legal"], deferred=False, write_type=design.write_type, routing=routing,
         rule_results=results,
@@ -101,4 +116,4 @@ def verify(design: Design | dict, question: str | None = None) -> Verdict:
         scope_flags=scope_flags,
         confidence=pc["confidence"], interval=pc["interval"], epistemic_status=verdict.status,
         provenance={"rules_version": RULES_VERSION, "source": "rules.solver + L4(uncertainty/scope/epistemic)"},
-        no_fabrication=True, writer_critique=writer_critique)
+        no_fabrication=True, writer_critique=writer_critique, delivery_profile=delivery_profile)

{pen_stack-5.0.0 → pen_stack-5.1.0}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.0.0
+Version: 5.1.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
@@ -77,10 +77,12 @@ Dynamic: license-file
 
 # PEN-STACK
 
-### The Writable Genome - open infrastructure for genome *writing*
+### The verification & grounding substrate for genome-writing AI — matured into a co-scientist
 
-*Editing tools tell you **how** to change a base. PEN-STACK tells you **where** in the genome you can safely
-and durably write new DNA, **which enzyme** can write it there, and **how** to design the write end-to-end.*
+*The foundation models *generate*; PEN-STACK *checks*. It tells you **where** in the genome you can safely and
+durably write, **which enzyme** can write it there, and **how** to design the write end-to-end — then verifies
+every design against rule-grounded mechanism, reports calibrated confidence, cites its reasoning, and says
+"out of scope" rather than guess. Every number comes from a validated tool; nothing is fabricated.*
 
 [![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)
@@ -89,7 +91,7 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![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.0.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.1.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/)
@@ -133,6 +135,23 @@ 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.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+carries a documented, cited, qualitative immune + safety + efficacy profile — so you can ask for a *balance*
+(AAV is safe by integration but neutralizing-antibody/pre-existing-immunity limited; lentivirus is a highly
+efficacious integrator but its genotoxicity is the dominant concern). Crucially, the in-vivo immune
+**magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
+patient-specific immune response.
+
+| 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 |
+| **IMMUNE planner** | `planner/delivery_immunology.py` — `safety_efficacy_profile()` / `recommend_delivery()` | two **separate** safety sub-axes (`immune_score` reversible vs `genotox_score` permanent), never collapsed; headline `safety_score = min(...)` (worst-axis); ranks the palette along the safety↔efficacy frontier by a **user weight** |
+| **IMMUNE verify** | `Verdict.delivery_profile` + `delivery_immune_profile` scope flag | `verify()` surfaces the documented tradeoff for a chosen vehicle, always attaching the `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude |
+
+See `prereg/ws_immune.yaml`.
+
 ## What is new in v5.0 — the Co-Scientist (smart because it is grounded)
 
 v5.0 matures the reasoning layer on top of everything beneath it. Given a goal and an intent, PEN-STACK

{pen_stack-5.0.0 → pen_stack-5.1.0}/pen_stack.egg-info/SOURCES.txt

@@ -153,6 +153,7 @@ pen_stack/planner/cargo.py
 pen_stack/planner/cargo_polish.py
 pen_stack/planner/delivery.py
 pen_stack/planner/delivery_constraints.py
+pen_stack/planner/delivery_immunology.py
 pen_stack/planner/delivery_vehicles.py
 pen_stack/planner/multiplex.py
 pen_stack/planner/optimize.py
@@ -244,6 +245,7 @@ prereg/SHA256_LOCK_ws_f.json
 prereg/SHA256_LOCK_ws_g.json
 prereg/SHA256_LOCK_ws_graph.json
 prereg/SHA256_LOCK_ws_h.json
+prereg/SHA256_LOCK_ws_immune.json
 prereg/SHA256_LOCK_ws_mc.json
 prereg/SHA256_LOCK_ws_mon.json
 prereg/SHA256_LOCK_ws_o.json
@@ -278,6 +280,7 @@ prereg/ws_f.yaml
 prereg/ws_g.yaml
 prereg/ws_graph.yaml
 prereg/ws_h.yaml
+prereg/ws_immune.yaml
 prereg/ws_mc.yaml
 prereg/ws_mon.yaml
 prereg/ws_o.yaml