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

{pen_stack-5.0.0 → pen_stack-5.2.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.2.0] - 2026-06-10 - v5.2 release: Computed genotoxicity oracle (data, not a documented tier)
+
+The v5.1 genotoxicity axis was a documented ordinal tier; for **integrating** vectors that signal is in fact
+computable from data the stack already holds. v5.2 adds a **computed genotoxicity oracle** — the observed
+enrichment of a vector class's integration sites near COSMIC oncogenes — answering through the v4.0
+OracleResult contract. Workstream WS-GENOTOX, SHA-locked.
+
+### Added
+- **WS-GENOTOX build** — `scripts/p52_build_genotox_oracle.py` (runs on the VM where the data lives) computes,
+  per integrating vector class, `P(integration site within 50 kb of a COSMIC Cancer-Gene-Census oncogene)` and
+  its enrichment over genome background, from **VISDB** per-virus catalogues × the Phase-1 oncogene annotation
+  (**COSMIC CGC v104**). Emits the small, auditable, committed summary `configs/genotoxicity_oracle.yaml` (raw
+  catalogues stay on the VM; only the statistics ship → CI-safe).
+- **WS-GENOTOX oracle** — `pen_stack/planner/genotoxicity_oracle.py`: `genotoxicity_oracle(vehicle)` returns an
+  `OracleResult` (`output_kind="baseline"`) with `genotox_score = min(1, 1/enrichment)`, native uncertainty
+  (CI on the observed fraction), the `delivery_genotoxicity` scope card, and `extrapolating` for small-n
+  classes. Non-integrating vehicles → 1.0 by mechanism; no computed class → **abstains** (never fabricates).
+- **Wired into the v5.1 balance** — `safety_efficacy_profile()` now **prefers the computed genotox_score** for
+  integrating vectors and falls back to the documented tier otherwise (`genotox_source` records which).
+- **Result (from data):** lentiviral (HIV) integration is **2.08×** enriched near oncogenes (n=88,743, robust)
+  vs **5.65×** for gammaretroviral (MLV, the LMO2/SCID-X1 comparator, small-n flagged) — reproducing the
+  lentivirus-safer-than-gammaretrovirus ordering **from VISDB×COSMIC**, and the computed lentivirus score
+  (0.48) **validates** the v5.1 documented "moderate" tier (0.5). `prereg/ws_genotox.yaml`.
+
+### Changed
+- Version 5.1.0 -> 5.2.0 (minor — additive computed oracle); `cite.curated_dois()` ingests the genotox
+  provenance DOIs (VISDB 10.1093/nar/gkz867, COSMIC CGC 10.1038/s41568-018-0060-1, HIV/MLV integration biology).
+
+### Honesty invariant (unchanged)
+- This is a **relative integration-preference** signal. The in-vivo clonal-expansion / leukemogenesis OUTCOME
+  in a patient is **not** modelled and stays a known-unknown (`delivery_genotoxicity` scope card); the immune
+  MAGNITUDE likewise stays `in_vivo_immunogenicity`. No magnitude is predicted.
+
+## [5.1.0] - 2026-06-10 - v5.1 release: Delivery immunology (the safety↔efficacy balance)
+
+The delivery palette gains a **documented, cited, qualitative immune + safety + efficacy profile** per vehicle,
+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.2.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.2.0
+date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.0.0
+Version: 5.2.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.2.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,39 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
+
+v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for
+integrating vectors: the observed enrichment of a vector class's integration sites near COSMIC oncogenes
+(VISDB integration catalogues × the Phase-1 COSMIC-CGC oncogene annotation), surfaced through the v4.0
+`OracleResult` contract. The in-vivo clonal / leukemogenesis **outcome** stays a known-unknown — this is a
+relative integration-*preference* signal, not a per-patient oncogenesis probability.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **GENOTOX build** | `scripts/p52_build_genotox_oracle.py` → committed `configs/genotoxicity_oracle.yaml` | per integrating class: `P(site within 50 kb of a COSMIC oncogene)`, enrichment vs background, CI, n — from VISDB × COSMIC CGC v104 (raw data stays on the VM; only the auditable summary ships) |
+| **GENOTOX oracle** | `planner/genotoxicity_oracle.py` (`OracleResult`, `output_kind="baseline"`) | `genotox_score = min(1, 1/enrichment)`; non-integrating → 1.0 by mechanism; **abstains** when it has no computed class (never fabricates); small-n classes flagged `extrapolating` |
+| **wired into v5.1 balance** | `safety_efficacy_profile()` prefers computed genotox, falls back to the documented tier | **lentiviral 2.08×** vs **gammaretroviral 5.65×** oncogene-proximity enrichment — reproduces the lentivirus-safer-than-gammaretrovirus ordering **from data**; computed LV score (0.48) **validates** the v5.1 documented tier (0.5) |
+
+See `prereg/ws_genotox.yaml` and the `delivery_genotoxicity` scope card.
+
+## What is new in v5.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+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.2.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.2.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,39 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
+
+v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for
+integrating vectors: the observed enrichment of a vector class's integration sites near COSMIC oncogenes
+(VISDB integration catalogues × the Phase-1 COSMIC-CGC oncogene annotation), surfaced through the v4.0
+`OracleResult` contract. The in-vivo clonal / leukemogenesis **outcome** stays a known-unknown — this is a
+relative integration-*preference* signal, not a per-patient oncogenesis probability.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **GENOTOX build** | `scripts/p52_build_genotox_oracle.py` → committed `configs/genotoxicity_oracle.yaml` | per integrating class: `P(site within 50 kb of a COSMIC oncogene)`, enrichment vs background, CI, n — from VISDB × COSMIC CGC v104 (raw data stays on the VM; only the auditable summary ships) |
+| **GENOTOX oracle** | `planner/genotoxicity_oracle.py` (`OracleResult`, `output_kind="baseline"`) | `genotox_score = min(1, 1/enrichment)`; non-integrating → 1.0 by mechanism; **abstains** when it has no computed class (never fabricates); small-n classes flagged `extrapolating` |
+| **wired into v5.1 balance** | `safety_efficacy_profile()` prefers computed genotox, falls back to the documented tier | **lentiviral 2.08×** vs **gammaretroviral 5.65×** oncogene-proximity enrichment — reproduces the lentivirus-safer-than-gammaretrovirus ordering **from data**; computed LV score (0.48) **validates** the v5.1 documented tier (0.5) |
+
+See `prereg/ws_genotox.yaml` and the `delivery_genotoxicity` scope card.
+
+## What is new in v5.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+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.2.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.2.0/configs/genotoxicity_oracle.yaml

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

{pen_stack-5.0.0 → pen_stack-5.2.0}/configs/oracles/scope_cards.yaml

@@ -112,3 +112,16 @@ oracles:
     not_valid_for: "absolute off-target rates; non-bridge writers; a non-recombining background"
     generalizes_to_unseen_loci: false
     license: "open (this work)"
+
+  delivery_genotoxicity:        # v5.2 WS-GENOTOX: computed integration-site oncogene-proximity
+    family: genome
+    version: "visdb+cgc_v104-2026"
+    output_kind: baseline       # an observed-data comparator (integration catalogues), not generative
+    valid_for: "RELATIVE genotoxicity ordering of INTEGRATING vector classes via the observed enrichment of
+      integration sites near COSMIC oncogenes (lentiviral vs gammaretroviral, from VISDB x CGC); reproduces the
+      lentivirus-safer-than-gammaretrovirus ordering from data"
+    not_valid_for: "the IN-VIVO clonal-expansion / leukemogenesis OUTCOME in a patient (a known-unknown); an
+      absolute per-insertion oncogenesis probability; non-integrating vectors (no insertional mechanism);
+      classes with too few catalogued sites (flagged extrapolating)"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; VISDB 10.1093/nar/gkz867, COSMIC CGC 10.1038/s41568-018-0060-1)"

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

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

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

@@ -28,6 +28,13 @@ 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
+    # v5.2 computed-genotoxicity oracle provenance (VISDB, COSMIC CGC, integration-biology refs)
+    try:
+        gt = yaml.safe_load(resource("configs/genotoxicity_oracle.yaml").read_text(encoding="utf-8"))
+        dois.update(gt.get("provenance_dois", []) or [])
+    except FileNotFoundError:
+        pass
     gsh = yaml.safe_load(resource("configs/gsh_validated_heldout.yaml").read_text(encoding="utf-8"))["gsh"]
     for g in gsh:
         if g.get("doi"):