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

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

@@ -3,6 +3,67 @@
 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.5.0] - 2026-06-10 - v5.5 release: Anti-vector seroprevalence oracle (the last immune axis, from data)
+
+Completes the computable delivery-immunology axes. **Pre-existing humoral immunity** (B-cell / neutralizing
+antibody) to a viral capsid is the one immune axis that *cannot* be computed from sequence — it is a population
+prevalence from natural exposure. v5.5 grounds it in published **serosurvey data**. Workstream WS-SEROPREV,
+SHA-locked.
+
+### Added
+- **WS-SEROPREV table** — `configs/seroprevalence.yaml`: curated population NAb/IgG seroprevalence per serotype
+  as **ranges** (region/age/assay variation) with DOIs — AAV (Calcedo 2009, Boutin 2010), adenovirus type 5
+  (Mast 2010), HSV-1 (Looker 2015), VSV (negligible).
+- **WS-SEROPREV oracle** — `pen_stack/planner/seroprevalence_oracle.py`: `seroprevalence_oracle(vehicle,
+  serotype=None)` → `OracleResult`. `preexisting_score = 1 − midpoint(seroprevalence)/100`; the range width is
+  surfaced as `native_uncertainty`. Non-viral → 1.0 by mechanism; unknown → **abstains**.
+- **Wired into the pre-existing axis** — `safety_efficacy_profile()` folds the computed seroprevalence score
+  into the `preexisting_immunity` sub-axis **only for in-vivo vehicles** (serum NAb neutralises the vector in
+  vivo; ex-vivo transduction in a dish is not reached by host antibody → reported but muted). `seroprevalence_score`
+  surfaces the raw value.
+- **Result (from data):** adenovirus has the highest pre-existing seroprevalence (40–90%, score 0.35), AAV
+  intermediate (30–60%, 0.55), VSV/lentivirus negligible (0–5%, 0.975) — the documented ordering quantified
+  from serosurveys. `prereg/ws_seroprev.yaml`.
+
+### Changed
+- Version 5.4.0 -> 5.5.0 (minor — additive data-grounded oracle); `cite.curated_dois()` ingests the
+  seroprevalence DOIs.
+
+### Honesty invariant (unchanged)
+- A **population** prevalence (a range; region/age/assay-dependent), **not** a given **patient's** NAb titer /
+  sero-status (a clinical test, patient-specific → a known-unknown); the **humoral (B-cell)** axis only,
+  distinct from the v5.3 T-cell epitope load. No patient-specific magnitude predicted.
+
+## [5.4.0] - 2026-06-10 - v5.4 release: Computed innate-sensing scorer (completes the computable immune axes)
+
+The third computed delivery-immunology signal, after v5.2 genotoxicity and v5.3 capsid epitope load. Innate
+sensing of a delivered nucleic acid is computed directly from the **cargo sequence** — CpG O/E for DNA (TLR9),
+U-richness + dsRNA for mRNA (TLR7/RIG-I) — covering every cargo form. Workstream WS-INNATE, SHA-locked.
+
+### Added
+- **WS-INNATE scorer** — `pen_stack/planner/innate_sensing.py`: `cpg_observed_expected()` (Gardiner-Garden &
+  Frommer) + `innate_sensing(seq, cargo_form)` → `OracleResult`. **DNA** → CpG O/E (vertebrate genome ~0.2
+  tolerated; non-depleted DNA → 1 TLR9-stimulatory), `innate_score = max(0, 1 − CpG_O/E)`. **mRNA** → uridine
+  fraction + ViennaRNA dsRNA pairing (graceful when ViennaRNA absent), flagged **partial/`extrapolating`**.
+  **RNP** → minimal/transient. Abstains on empty / unrecognised input (never fabricates). Pure sequence
+  computation — no external data, runs in CI.
+- **Surfaced in `verify()`** — when a design supplies `cargo_seq`, the computed innate load is attached as a
+  `cargo_innate_sensing` scope flag (cargo form from the writer output form, else the vehicle's first
+  compatible form) and added to `delivery_profile.cargo_innate`. No confidence added; the realized in-vivo
+  innate response stays a known-unknown.
+- Scope card `innate_sensing`; `prereg/ws_innate.yaml`. `cite.curated_dois()` ingests the innate provenance
+  DOIs (CpG-TLR9 10.1073/pnas.161293498, CpG-depleted AAV 10.1172/JCI68205, RNA modification
+  10.1016/j.immuni.2005.06.008, + Krieg 1995 / Hornung 2006).
+
+### Changed
+- Version 5.3.0 -> 5.4.0 (minor — additive computed scorer).
+
+### Honesty invariant (unchanged)
+- Sequence-intrinsic motif-**load** signal. The realized **in-vivo innate response** magnitude in a patient is
+  **not** modelled (known-unknown); the mRNA score is **partial** because the dominant evasion lever —
+  **nucleoside modification** (m1-pseudouridine) — is a manufacturing choice not derivable from sequence; DNA
+  methylation state is likewise out of scope. No magnitude predicted.
+
 ## [5.3.0] - 2026-06-10 - v5.3 release: Computed capsid epitope-load oracle (covers all vectors)
 
 v5.2 computed genotoxicity only meaningfully touches integrating vectors. v5.3 brings the **NetMHC-style

{pen_stack-5.3.0 → pen_stack-5.5.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 5.3.0
+version: 5.5.0
 date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-5.3.0 → pen_stack-5.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.3.0
+Version: 5.5.0
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -91,7 +91,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.5.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -135,6 +135,47 @@ 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.5 — Anti-vector seroprevalence oracle (the last immune axis, from data)
+
+This completes the computable delivery-immunology axes. **Pre-existing humoral immunity** (B-cell / NAb) to a
+viral capsid is the one axis that *cannot* be computed from sequence — it is a population prevalence from
+natural exposure — so v5.5 grounds it in published **serosurvey data** (AAV: Calcedo 2009 / Boutin 2010;
+adenovirus: Mast 2010; HSV-1: Looker 2015). `preexisting_score = 1 − midpoint(seroprevalence)/100`, with the
+literature range surfaced as native uncertainty.
+
+| serotype (vehicle) | NAb seroprevalence | pre-existing score |
+|---|---|---|
+| Ad5 → HDAd | 40–90% | 0.35 |
+| AAV (aggregate) → AAV | 30–60% | 0.55 |
+| HSV-1 → HSV | 50–70% | 0.40 |
+| VSV → lentivirus | 0–5% | 0.975 |
+
+Folded into the pre-existing axis for **in-vivo** vehicles (muted for ex-vivo, where serum NAb can't reach
+ex-vivo cells); non-viral → 1.0 by mechanism. It is a **population** prevalence — **not** a given patient's NAb
+titer (a known-unknown). See `pen_stack/planner/seroprevalence_oracle.py`, `configs/seroprevalence.yaml`,
+`prereg/ws_seroprev.yaml`, and the `seroprevalence` scope card.
+
+**With v5.5, four of the five delivery-immunology axes are grounded in data or sequence** — genotoxicity
+(VISDB×COSMIC), adaptive/CD8 (MHCflurry), innate (CpG/dsRNA), pre-existing/NAb (serosurveys) — each abstaining
+rather than fabricating, with the in-vivo *magnitude* always a declared known-unknown.
+
+## What is new in v5.4 — Computed innate-sensing scorer (completes the computable immune axes)
+
+The third computed delivery-immunology signal (after v5.2 genotoxicity and v5.3 capsid epitope load). Innate
+sensing of a delivered nucleic acid is computed directly from the **cargo sequence**, covering every cargo
+form. It is a sequence-intrinsic motif-*load* signal; the realized in-vivo innate response stays a
+known-unknown, and the mRNA score is honestly *partial* (the dominant lever — nucleoside modification — isn't
+derivable from sequence).
+
+| Cargo form | Pathway | Computed from sequence | Score |
+|---|---|---|---|
+| **DNA** (AAV / HDAd / HSV / plasmid) | TLR9 / cGAS | CpG observed/expected ratio | `max(0, 1 − CpG_O/E)` — vertebrate genome ~0.2 tolerated, non-depleted DNA → 1 stimulatory |
+| **mRNA** (LNP-mRNA / electroporation) | TLR7/8 + RIG-I/MDA5/PKR | U-fraction + ViennaRNA dsRNA pairing | partial / `extrapolating` (nucleoside modification out of scope) |
+| **RNP** (eVLP / electroporation) | minimal (transient gRNA) | — | ~0.9 by mechanism |
+
+`verify()` surfaces it as a `cargo_innate_sensing` flag whenever a `cargo_seq` is supplied. See
+`pen_stack/planner/innate_sensing.py`, `prereg/ws_innate.yaml`, and the `innate_sensing` scope card.
+
 ## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
 
 v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the

{pen_stack-5.3.0 → pen_stack-5.5.0}/README.md

@@ -16,7 +16,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.5.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -60,6 +60,47 @@ 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.5 — Anti-vector seroprevalence oracle (the last immune axis, from data)
+
+This completes the computable delivery-immunology axes. **Pre-existing humoral immunity** (B-cell / NAb) to a
+viral capsid is the one axis that *cannot* be computed from sequence — it is a population prevalence from
+natural exposure — so v5.5 grounds it in published **serosurvey data** (AAV: Calcedo 2009 / Boutin 2010;
+adenovirus: Mast 2010; HSV-1: Looker 2015). `preexisting_score = 1 − midpoint(seroprevalence)/100`, with the
+literature range surfaced as native uncertainty.
+
+| serotype (vehicle) | NAb seroprevalence | pre-existing score |
+|---|---|---|
+| Ad5 → HDAd | 40–90% | 0.35 |
+| AAV (aggregate) → AAV | 30–60% | 0.55 |
+| HSV-1 → HSV | 50–70% | 0.40 |
+| VSV → lentivirus | 0–5% | 0.975 |
+
+Folded into the pre-existing axis for **in-vivo** vehicles (muted for ex-vivo, where serum NAb can't reach
+ex-vivo cells); non-viral → 1.0 by mechanism. It is a **population** prevalence — **not** a given patient's NAb
+titer (a known-unknown). See `pen_stack/planner/seroprevalence_oracle.py`, `configs/seroprevalence.yaml`,
+`prereg/ws_seroprev.yaml`, and the `seroprevalence` scope card.
+
+**With v5.5, four of the five delivery-immunology axes are grounded in data or sequence** — genotoxicity
+(VISDB×COSMIC), adaptive/CD8 (MHCflurry), innate (CpG/dsRNA), pre-existing/NAb (serosurveys) — each abstaining
+rather than fabricating, with the in-vivo *magnitude* always a declared known-unknown.
+
+## What is new in v5.4 — Computed innate-sensing scorer (completes the computable immune axes)
+
+The third computed delivery-immunology signal (after v5.2 genotoxicity and v5.3 capsid epitope load). Innate
+sensing of a delivered nucleic acid is computed directly from the **cargo sequence**, covering every cargo
+form. It is a sequence-intrinsic motif-*load* signal; the realized in-vivo innate response stays a
+known-unknown, and the mRNA score is honestly *partial* (the dominant lever — nucleoside modification — isn't
+derivable from sequence).
+
+| Cargo form | Pathway | Computed from sequence | Score |
+|---|---|---|---|
+| **DNA** (AAV / HDAd / HSV / plasmid) | TLR9 / cGAS | CpG observed/expected ratio | `max(0, 1 − CpG_O/E)` — vertebrate genome ~0.2 tolerated, non-depleted DNA → 1 stimulatory |
+| **mRNA** (LNP-mRNA / electroporation) | TLR7/8 + RIG-I/MDA5/PKR | U-fraction + ViennaRNA dsRNA pairing | partial / `extrapolating` (nucleoside modification out of scope) |
+| **RNP** (eVLP / electroporation) | minimal (transient gRNA) | — | ~0.9 by mechanism |
+
+`verify()` surfaces it as a `cargo_innate_sensing` flag whenever a `cargo_seq` is supplied. See
+`pen_stack/planner/innate_sensing.py`, `prereg/ws_innate.yaml`, and the `innate_sensing` scope card.
+
 ## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
 
 v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the

{pen_stack-5.3.0 → pen_stack-5.5.0}/configs/oracles/scope_cards.yaml

@@ -138,3 +138,31 @@ oracles:
       a viral vehicle whose antigen sequence is not committed (abstains)"
     generalizes_to_unseen_loci: false
     license: "open (this work; MHCflurry 10.1016/j.cels.2020.06.010, HLA-I supertypes 10.1186/1471-2172-9-1)"
+
+  innate_sensing:               # v5.4 WS-INNATE: computed nucleic-acid innate-sensing motif load
+    family: genome
+    version: "cpg-oe+dsrna-2026"
+    output_kind: baseline       # deterministic sequence statistic, not generative
+    valid_for: "sequence-intrinsic innate-sensing LOAD of a cargo sequence: CpG observed/expected (DNA ->
+      TLR9/cGAS; CpG-depleted DNA is tolerated, non-depleted is stimulatory) and U-richness + dsRNA pairing
+      (mRNA -> TLR7/8 + RIG-I/MDA5/PKR); a relative, computable proxy"
+    not_valid_for: "the realized IN-VIVO innate RESPONSE magnitude in a patient (a known-unknown); RNA
+      NUCLEOSIDE MODIFICATION (m1-pseudouridine), the dominant mRNA evasion lever - NOT sequence-derivable
+      (the mRNA score is PARTIAL / extrapolating); DNA methylation state of the delivered cargo"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; CpG-TLR9 10.1073/pnas.161293498, CpG-depleted AAV 10.1172/JCI68205,
+      RNA modification 10.1016/j.immuni.2005.06.008)"
+
+  seroprevalence:               # v5.5 WS-SEROPREV: anti-vector NAb seroprevalence from serosurvey data
+    family: genome
+    version: "serosurvey-2026"
+    output_kind: baseline       # curated empirical population data, not a model
+    valid_for: "POPULATION pre-existing neutralizing-antibody seroprevalence per capsid serotype, from published
+      serosurveys (AAV Calcedo/Boutin, Ad5 Mast, HSV-1 Looker); preexisting_score = 1 - midpoint/100. The one
+      immune axis that is empirical, not sequence-computable"
+    not_valid_for: "a given PATIENT's NAb titer / sero-status (a clinical test, patient-specific -> a
+      known-unknown); precise region/age/assay-specific values (a range, not a point); functional-NAb vs
+      IgG-binding distinctions; T-cell immunity (that is the capsid_epitope oracle); anti-PEG immunity"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; Calcedo 10.1086/595830, Boutin 10.1089/hum.2009.182, Mast
+      10.1016/j.vaccine.2009.10.145, Looker 10.1371/journal.pone.0140765)"

pen_stack-5.5.0/configs/seroprevalence.yaml

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

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

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

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

@@ -36,6 +36,16 @@ def curated_dois() -> frozenset[str]:
             dois.update(a.get("provenance_dois", []) or [])
         except FileNotFoundError:
             pass
+    # v5.4 computed innate-sensing provenance (CpG-TLR9 / AAV CpG-depletion / RNA modification)
+    from pen_stack.planner.innate_sensing import PROVENANCE_DOIS as _innate_dois
+    dois.update(_innate_dois)
+    # v5.5 anti-vector seroprevalence provenance (serosurveys)
+    try:
+        sp = yaml.safe_load(resource("configs/seroprevalence.yaml").read_text(encoding="utf-8"))
+        for _rec in (sp.get("serotypes") or {}).values():
+            dois.update(_rec.get("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"):

{pen_stack-5.3.0 → pen_stack-5.5.0}/pen_stack/planner/delivery_immunology.py

@@ -78,6 +78,17 @@ def safety_efficacy_profile(name: str) -> dict | None:
         adaptive_source = "computed"
     elif cap_score is not None and not in_vivo:
         adaptive_source = "computed_ex_vivo_muted"          # reported, but ex-vivo mutes the realized response
+    # PRE-EXISTING immunity (B-cell / NAb): grounded in published serosurvey data (v5.5 WS-SEROPREV). Folded
+    # only for IN-VIVO vehicles (serum NAb neutralises the vector in vivo; ex-vivo transduction in a dish is
+    # not reached by host antibody, so for ex-vivo vehicles it is reported but muted).
+    from pen_stack.planner.seroprevalence_oracle import computed_preexisting_score
+    pre_score, pre_oracle = computed_preexisting_score(name)
+    preexisting_source = "documented"
+    if pre_score is not None and in_vivo:
+        axis_scores["preexisting_immunity"] = pre_score
+        preexisting_source = "computed"
+    elif pre_score is not None and not in_vivo:
+        preexisting_source = "computed_ex_vivo_muted"
     immune_present = [s for s in axis_scores.values() if s is not None]
     immune_score = (sum(immune_present) / len(immune_present)) if immune_present else None
     # genotoxicity: prefer the COMPUTED oracle (v5.2 WS-GENOTOX: integration-site x COSMIC-oncogene
@@ -102,6 +113,9 @@ def safety_efficacy_profile(name: str) -> dict | None:
         "adaptive_source": adaptive_source,      # computed | computed_ex_vivo_muted | documented
         "capsid_presentability_score": _r(cap_score),   # computed intrinsic capsid CD8 presentability (or None)
         "adaptive_provenance": (cap_oracle.note if cap_score is not None else None),
+        "preexisting_source": preexisting_source,       # computed | computed_ex_vivo_muted | documented
+        "seroprevalence_score": _r(pre_score),          # computed pre-existing-NAb score (or None)
+        "preexisting_provenance": (pre_oracle.note if pre_score is not None else None),
         "genotox_score": _r(genotox_score),
         "genotox_source": genotox_source,        # "computed" (VISDBxCOSMIC oracle) | "documented" (ordinal tier)
         "genotox_provenance": (gtox_oracle.note if genotox_source == "computed" else None),

pen_stack-5.5.0/pen_stack/planner/innate_sensing.py

@@ -0,0 +1,135 @@
+"""Computed innate-immune-sensing scorer for nucleic-acid cargo (v5.4, WS-INNATE).
+
+Innate sensing of a delivered nucleic acid is a property of the CARGO SEQUENCE (and its form), computed here
+directly from sequence - the third computed delivery-immunology signal (after v5.2 genotoxicity and v5.3 capsid
+epitope load). It covers every cargo form the palette carries:
+
+  * DNA  (AAV / HDAd / HSV / electroporated plasmid) -> TLR9 / cGAS sensing of unmethylated CpG. The standard
+    sequence statistic is the CpG observed/expected ratio (Gardiner-Garden & Frommer): vertebrate genomes are
+    CpG-DEPLETED (O/E ~ 0.2) and tolerated, while non-depleted plasmid/viral DNA (O/E -> 1) is TLR9-stimulatory;
+    CpG-DEPLETED vectors evade detection. innate_score = max(0, 1 - CpG_O/E).
+  * mRNA (LNP-mRNA / electroporated mRNA) -> TLR7/8 (U-rich ssRNA) + RIG-I / MDA5 / PKR (dsRNA). Computed from
+    uridine fraction + ViennaRNA base-pairing. This signal is PARTIAL and flagged `extrapolating`: the dominant
+    innate-evasion lever for mRNA is NUCLEOSIDE MODIFICATION (m1-pseudouridine), which is NOT derivable from the
+    nucleotide sequence (a manufacturing choice) - a stated known-limitation.
+  * RNP / protein -> minimal, transient nucleic-acid exposure (no DNA; short-lived gRNA): score ~ high.
+
+Answers through the v4.0 OracleResult contract (output_kind="baseline"). HONESTY: this is a sequence-intrinsic
+motif-LOAD signal; the realized in-vivo innate RESPONSE magnitude in a patient is NOT modelled and stays a
+known-unknown; DNA methylation state and RNA nucleoside modification are out of sequence scope.
+"""
+from __future__ import annotations
+
+from pen_stack.oracles.schema import OracleResult, Provenance
+
+_SCOPE_CARD = "innate_sensing"
+_DNA = set("ACGT")
+_RNA = set("ACGU")
+# CpG-TLR9 (Krieg 1995 / Bauer 2001), CpG-depleted AAV evasion (Faust 2013), RNA nucleoside modification
+# (Kariko 2005), 5'ppp dsRNA RIG-I (Hornung 2006).
+PROVENANCE_DOIS = ["10.1038/374546a0", "10.1073/pnas.161293498", "10.1172/JCI68205",
+                   "10.1016/j.immuni.2005.06.008", "10.1126/science.1132505"]
+
+
+def _clean(seq: str) -> str:
+    return "".join(c for c in (seq or "").upper() if c.isalpha())
+
+
+def cpg_observed_expected(dna: str) -> dict:
+    """CpG observed/expected ratio (Gardiner-Garden & Frommer): (n_CpG / (n_C * n_G)) * length. Vertebrate
+    genome ~0.2 (depleted); non-depleted plasmid/viral DNA approaches 1; engineered CpG-free -> 0."""
+    s = _clean(dna).replace("U", "T")
+    L = len(s)
+    nC, nG = s.count("C"), s.count("G")
+    n_cpg = s.count("CG")
+    oe = (n_cpg / (nC * nG) * L) if (nC and nG) else 0.0
+    gc = (nC + nG) / L if L else 0.0
+    return {"length": L, "cpg_count": n_cpg, "cpg_oe": round(oe, 4), "gc": round(gc, 4)}
+
+
+def _dsrna_paired_fraction(rna: str) -> float | None:
+    """Fraction of bases paired in the ViennaRNA MFE structure (dsRNA -> RIG-I/MDA5/PKR). None if ViennaRNA
+    absent (graceful degradation, as in bridge/fold_qc.py)."""
+    try:
+        import RNA
+    except Exception:  # noqa: BLE001
+        return None
+    s = _clean(rna).replace("T", "U")
+    if not s:
+        return None
+    struct, _ = RNA.fold_compound(s).mfe()
+    paired = sum(1 for c in struct if c in "()")
+    return round(paired / len(struct), 4) if struct else None
+
+
+def _prov() -> Provenance:
+    return Provenance(model="cargo_innate_sensing", version="1.0", source="adapter",
+                      extra={"provenance_dois": PROVENANCE_DOIS})
+
+
+def innate_sensing(seq: str, cargo_form: str) -> OracleResult:
+    """Computed innate-sensing score for a cargo sequence + form, as an OracleResult (v4.0 contract).
+
+    `cargo_form` in {DNA, mRNA, RNP}. Returns innate_score in [0,1] (1 = least innate-stimulatory). Abstains
+    (available=False) on an empty sequence or an unrecognised/uncomputable form. Never fabricates."""
+    s = _clean(seq)
+    form = (cargo_form or "").strip()
+    if not s:
+        return OracleResult(oracle="genome", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                            in_scope=False, available=False, output_kind="baseline",
+                            note="no cargo sequence supplied")
+
+    if form == "DNA":
+        c = cpg_observed_expected(s)
+        score = max(0.0, min(1.0, 1.0 - c["cpg_oe"]))
+        return OracleResult(
+            oracle="genome",
+            value={"innate_score": round(score, 3), "pathway": "TLR9/cGAS (unmethylated CpG)",
+                   "cpg_oe": c["cpg_oe"], "cpg_count": c["cpg_count"], "gc": c["gc"], "length": c["length"]},
+            provenance=_prov(), native_uncertainty=None, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note=(f"CpG O/E={c['cpg_oe']} ({c['cpg_count']} CpG, {c['length']} bp); innate_score=max(0,1-O/E). "
+                  "Vertebrate genome O/E~0.2 (tolerated), non-depleted DNA ->1 (TLR9-stimulatory). DNA "
+                  "methylation state and the realized in-vivo innate RESPONSE are known-unknowns (not modelled)."))
+
+    if form == "mRNA":
+        u_frac = s.replace("T", "U").count("U") / len(s)
+        paired = _dsrna_paired_fraction(s)
+        # partial sequence-only signal: U-richness (TLR7/8) + dsRNA pairing (RIG-I/PKR). The dominant evasion
+        # lever (nucleoside modification, m1-pseudouridine) is NOT sequence-derivable -> flagged extrapolating.
+        if paired is None:
+            score = max(0.0, min(1.0, 1.0 - u_frac))
+            note_ds = "ViennaRNA absent: dsRNA term omitted; score from U-fraction only."
+        else:
+            score = max(0.0, min(1.0, 1.0 - 0.5 * u_frac - 0.5 * paired))
+            note_ds = f"dsRNA paired_fraction={paired} (RIG-I/MDA5/PKR)."
+        return OracleResult(
+            oracle="rna",
+            value={"innate_score": round(score, 3), "pathway": "TLR7/8 (U-rich ssRNA) + RIG-I/MDA5/PKR (dsRNA)",
+                   "u_fraction": round(u_frac, 4), "dsrna_paired_fraction": paired, "length": len(s)},
+            provenance=_prov(), native_uncertainty=None, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=True, output_kind="baseline", available=True,
+            note=("PARTIAL sequence-only signal. " + note_ds + " The dominant mRNA innate-evasion lever - "
+                  "NUCLEOSIDE MODIFICATION (m1-pseudouridine) - is NOT sequence-derivable and is out of scope; "
+                  "the realized in-vivo innate response is a known-unknown."))
+
+    if form == "RNP":
+        return OracleResult(
+            oracle="rna",
+            value={"innate_score": 0.9, "pathway": "minimal (transient gRNA; no DNA)", "length": len(s)},
+            provenance=_prov(), native_uncertainty=None, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=True, output_kind="baseline", available=True,
+            note=("RNP cargo: transient, no DNA -> minimal nucleic-acid innate sensing (synthetic gRNA may "
+                  "trigger RIG-I via 5'-triphosphate; modification mitigates - not sequence-derivable). "
+                  "Realized response is a known-unknown."))
+
+    return OracleResult(oracle="genome", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                        in_scope=False, available=False, output_kind="baseline",
+                        note=f"unrecognised cargo_form {cargo_form!r} (expected DNA / mRNA / RNP)")
+
+
+def computed_innate_score(seq: str, cargo_form: str) -> tuple[float | None, OracleResult]:
+    """Convenience: (innate_score or None, full OracleResult). None when the scorer abstains. Never fabricates."""
+    r = innate_sensing(seq, cargo_form)
+    val = (r.value or {}).get("innate_score") if (r.available and r.value) else None
+    return val, r

pen_stack-5.5.0/pen_stack/planner/seroprevalence_oracle.py

@@ -0,0 +1,92 @@
+"""Anti-vector neutralizing-antibody seroprevalence oracle (v5.5, WS-SEROPREV).
+
+The last computable delivery-immunology axis: PRE-EXISTING humoral immunity (B-cell / neutralizing antibody)
+to a viral capsid. Unlike genotoxicity (v5.2), capsid T-cell epitope load (v5.3) and innate sensing (v5.4),
+this CANNOT be computed from sequence - it is the prevalence, in a population, of people who already carry
+NAbs against the vector from natural exposure. The honest grounding is published serosurvey DATA
+(configs/seroprevalence.yaml), curated as ranges with provenance.
+
+    preexisting_score = 1 - midpoint(seroprevalence_pct) / 100    # 1 = fewest patients excluded by NAb
+
+Answers through the v4.0 OracleResult contract (output_kind="baseline"). Non-viral vehicles carry no foreign
+capsid -> no pre-existing ANTI-VECTOR humoral immunity (score 1.0 by mechanism). HONESTY: a POPULATION
+prevalence, NOT a given patient's NAb titer (a known-unknown); region/age/assay-dependent (a range, surfaced);
+the humoral (B-cell) axis only - distinct from the T-cell epitope load of v5.3.
+"""
+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 = "seroprevalence"
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict:
+    return yaml.safe_load(resource("configs/seroprevalence.yaml").read_text(encoding="utf-8"))
+
+
+def _all_dois() -> list[str]:
+    dois: set[str] = set()
+    for rec in (_table().get("serotypes") or {}).values():
+        dois.update(rec.get("dois", []) or [])
+    return sorted(dois)
+
+
+def _prov(**extra) -> Provenance:
+    return Provenance(model="anti_vector_seroprevalence", version=str(_table().get("version", "1.0")),
+                      source="cache", extra=extra)
+
+
+def seroprevalence_oracle(vehicle_name: str, serotype: str | None = None) -> OracleResult:
+    """Pre-existing anti-vector NAb seroprevalence for a vehicle (or an explicit serotype), as an OracleResult.
+
+    - viral vehicle (or serotype) with curated data -> preexisting_score = 1 - midpoint(seroprevalence)/100.
+    - non-viral vehicle -> 1.0 by mechanism (no foreign capsid).
+    - unknown vehicle / no curated serotype -> available=False (caller falls back to the documented tier).
+    Never fabricates a number."""
+    t = _table()
+    sero = t.get("serotypes") or {}
+    key = serotype or (t.get("vehicle_serotype") or {}).get(vehicle_name)
+
+    if key and key in sero:
+        rec = sero[key]
+        lo, hi = rec["nab_seroprevalence_pct"]
+        mid = (lo + hi) / 2.0
+        score = max(0.0, min(1.0, 1.0 - mid / 100.0))
+        return OracleResult(
+            oracle="genome",
+            value={"preexisting_score": round(score, 3), "serotype": key,
+                   "nab_seroprevalence_pct": [lo, hi], "midpoint_pct": mid, "dois": rec.get("dois", [])},
+            provenance=_prov(serotype=key, 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"{key}: documented NAb seroprevalence {lo}-{hi}% (population); preexisting_score="
+                  f"1-midpoint/100={score:.3f}. " + (rec.get("note", "") + " " if rec.get("note") else "")
+                  + "A POPULATION prevalence, region/age/assay-dependent - NOT a given patient's NAb titer "
+                  "(a known-unknown)."))
+
+    if vehicle_name in (t.get("non_viral") or []):
+        return OracleResult(
+            oracle="genome",
+            value={"preexisting_score": 1.0, "serotype": None, "mechanism": "non-viral"},
+            provenance=_prov(), native_uncertainty=0.0, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note="non-viral vehicle: no foreign capsid -> no pre-existing ANTI-VECTOR humoral immunity (1.0). "
+                 "Anti-PEG immunity for LNP is an emerging, separate exception (not a vector seroprevalence).")
+
+    return OracleResult(oracle="genome", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                        in_scope=False, available=False, output_kind="baseline",
+                        note=f"no curated seroprevalence for {vehicle_name!r}; fall back to the documented "
+                             "preexisting_immunity tier.")
+
+
+def computed_preexisting_score(vehicle_name: str, serotype: str | None = None) -> tuple[float | None, OracleResult]:
+    """Convenience: (preexisting_score or None, full OracleResult). None when the oracle abstains. Never
+    fabricates."""
+    r = seroprevalence_oracle(vehicle_name, serotype)
+    val = (r.value or {}).get("preexisting_score") if (r.available and r.value) else None
+    return val, r

{pen_stack-5.3.0 → pen_stack-5.5.0}/pen_stack/verify/service.py

@@ -107,6 +107,27 @@ def verify(design: Design | dict, question: str | None = None) -> Verdict:
                                 "reason": "documented ordinal immune/safety priors surfaced; the in-vivo immune "
                                           "MAGNITUDE remains a known-unknown (not predicted)"})
 
+    # v5.4 WS-INNATE: if a cargo SEQUENCE is supplied, compute its innate-sensing load from sequence
+    # (CpG/TLR9 for DNA, U/dsRNA for mRNA). Surfaced as a scope flag; the realized innate RESPONSE magnitude
+    # is a known-unknown. Cargo form = the writer output form, else the vehicle's first compatible form.
+    if design.cargo_seq:
+        form = design.writer_output_form
+        if not form and design.delivery_vehicle:
+            from pen_stack.planner.delivery_vehicles import vehicle as _veh
+            forms = (_veh(design.delivery_vehicle) or {}).get("compatible_cargo_form") or []
+            form = forms[0] if forms else None
+        if form:
+            from pen_stack.planner.innate_sensing import innate_sensing
+            inr = innate_sensing(design.cargo_seq, form)
+            if inr.available:
+                scope_flags.append({"kind": "cargo_innate_sensing", "cargo_form": form,
+                                    "innate_score": inr.value["innate_score"], "pathway": inr.value["pathway"],
+                                    "reason": "computed sequence-intrinsic innate-sensing load; the realized "
+                                              "in-vivo innate RESPONSE magnitude is a known-unknown"})
+                if delivery_profile is not None:
+                    delivery_profile = dict(delivery_profile)
+                    delivery_profile["cargo_innate"] = inr.value
+
     return Verdict(
         legal=routed["legal"], deferred=False, write_type=design.write_type, routing=routing,
         rule_results=results,