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

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

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

{pen_stack-5.4.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.4.0
+version: 5.5.0
 date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.4.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.4.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,30 @@ 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

{pen_stack-5.4.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.4.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,30 @@ 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

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

@@ -152,3 +152,17 @@ oracles:
     generalizes_to_unseen_loci: false
     license: "open (this work; CpG-TLR9 10.1073/pnas.161293498, CpG-depleted AAV 10.1172/JCI68205,
       RNA modification 10.1016/j.immuni.2005.06.008)"
+
+  seroprevalence:               # v5.5 WS-SEROPREV: anti-vector NAb seroprevalence from serosurvey data
+    family: genome
+    version: "serosurvey-2026"
+    output_kind: baseline       # curated empirical population data, not a model
+    valid_for: "POPULATION pre-existing neutralizing-antibody seroprevalence per capsid serotype, from published
+      serosurveys (AAV Calcedo/Boutin, Ad5 Mast, HSV-1 Looker); preexisting_score = 1 - midpoint/100. The one
+      immune axis that is empirical, not sequence-computable"
+    not_valid_for: "a given PATIENT's NAb titer / sero-status (a clinical test, patient-specific -> a
+      known-unknown); precise region/age/assay-specific values (a range, not a point); functional-NAb vs
+      IgG-binding distinctions; T-cell immunity (that is the capsid_epitope oracle); anti-PEG immunity"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; Calcedo 10.1086/595830, Boutin 10.1089/hum.2009.182, Mast
+      10.1016/j.vaccine.2009.10.145, Looker 10.1371/journal.pone.0140765)"

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.4.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.4.0"
+__version__ = "5.5.0"

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

@@ -39,6 +39,13 @@ def curated_dois() -> frozenset[str]:
     # 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.4.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/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.4.0 → pen_stack-5.5.0}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.4.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.4.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,30 @@ 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

{pen_stack-5.4.0 → pen_stack-5.5.0}/pen_stack.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ configs/known_unknowns.yaml
 configs/llm.yaml
 configs/monitor_queries.yaml
 configs/score_axes.yaml
+configs/seroprevalence.yaml
 configs/target_sites.yaml
 configs/universe_crosswalk.yaml
 configs/write_types.yaml
@@ -166,6 +167,7 @@ pen_stack/planner/optimize.py
 pen_stack/planner/pipeline.py
 pen_stack/planner/report.py
 pen_stack/planner/router.py
+pen_stack/planner/seroprevalence_oracle.py
 pen_stack/planner/target_site.py
 pen_stack/rag/__init__.py
 pen_stack/rag/index.py
@@ -261,6 +263,7 @@ prereg/SHA256_LOCK_ws_o.json
 prereg/SHA256_LOCK_ws_plan.json
 prereg/SHA256_LOCK_ws_r.json
 prereg/SHA256_LOCK_ws_route.json
+prereg/SHA256_LOCK_ws_seroprev.json
 prereg/SHA256_LOCK_ws_uq.json
 prereg/SHA256_LOCK_ws_v.json
 prereg/SHA256_LOCK_ws_wv.json
@@ -299,6 +302,7 @@ prereg/ws_o.yaml
 prereg/ws_plan.yaml
 prereg/ws_r.yaml
 prereg/ws_route.yaml
+prereg/ws_seroprev.yaml
 prereg/ws_uq.yaml
 prereg/ws_v.yaml
 prereg/ws_wv.yaml

pen_stack-5.5.0/prereg/SHA256_LOCK_ws_seroprev.json

@@ -0,0 +1,8 @@
+{
+  "cycle": "v5.5",
+  "workstream": "WS-SEROPREV",
+  "prepared": "2026-06-10",
+  "sha256": {
+    "prereg/ws_seroprev.yaml": "18cc27da5b6aee682195e9c57abff49ca1d6338b71d5ac7c4b87084d25fa803b"
+  }
+}

pen_stack-5.5.0/prereg/ws_seroprev.yaml

@@ -0,0 +1,40 @@
+# PEN-STACK v5.5 - WS-SEROPREV (anti-vector neutralizing-antibody seroprevalence). Directional.
+cycle: "v5.5"
+workstream: "WS-SEROPREV"
+prepared: "2026-06-10"
+
+motivation: >
+  Completes the computable delivery-immunology axes (after v5.2 genotoxicity, v5.3 capsid epitope load, v5.4
+  innate sensing). PRE-EXISTING humoral immunity (B-cell / NAb) to a viral capsid is the one immune axis that
+  CANNOT be computed from sequence - it is a POPULATION prevalence from natural exposure. The honest grounding
+  is published serosurvey DATA.
+
+deliverable: >
+  configs/seroprevalence.yaml (curated per-serotype NAb seroprevalence ranges + DOIs); pen_stack/planner/
+  seroprevalence_oracle.py (OracleResult); wired into delivery_immunology.safety_efficacy_profile
+  preexisting_immunity axis; scope card `seroprevalence`.
+
+method: >
+  Curate published population NAb/IgG seroprevalence per serotype as RANGES (region/age/assay variation), each
+  with >=1 DOI: AAV (Calcedo 2009 [10.1086/595830], Boutin 2010 [10.1089/hum.2009.182]); adenovirus type 5
+  (Mast 2010 [10.1016/j.vaccine.2009.10.145]); HSV-1 (Looker 2015 [10.1371/journal.pone.0140765]); VSV
+  (negligible). preexisting_score = 1 - midpoint(seroprevalence_pct)/100; native_uncertainty = range half-width.
+  v4.0 OracleResult (output_kind="baseline"). Folded into the preexisting 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). Non-viral vehicles: 1.0 by mechanism (no foreign capsid).
+
+acceptance: >
+  (1) per-serotype seroprevalence maps to a pre-existing score (1 - midpoint/100), with the range surfaced as
+  native uncertainty. (2) the ordering matches the literature: adenovirus (highest pre-existing immunity) <
+  AAV < VSV (lowest) by score. (3) an explicit serotype overrides the vehicle default (AAV8 > AAV2 score).
+  (4) non-viral -> 1.0 by mechanism; unknown vehicle -> ABSTAINS (never fabricates). (5) folds for in-vivo /
+  muted for ex-vivo. (6) provenance DOIs Crossref-verified + curated.
+
+honesty_invariant: >
+  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; anti-PEG immunity is a separate emerging exception. No patient-specific magnitude
+  predicted.
+
+gate: "per-serotype seroprevalence -> pre-existing score with range; Ad>AAV>VSV ordering; serotype override; non-viral 1.0; abstains not fabricates; in-vivo folds/ex-vivo muted; provenance curated; no-fabrication intact."
+locked_files: [prereg/ws_seroprev.yaml]

{pen_stack-5.4.0 → pen_stack-5.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pen-stack"
-version = "5.4.0"
+version = "5.5.0"
 description = "Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner."
 readme = "README.md"
 requires-python = ">=3.11"