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

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

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

{pen_stack-5.1.0 → pen_stack-5.2.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.1.0
+version: 5.2.0
 date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.1.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
@@ -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.1.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/)
@@ -135,6 +135,22 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.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

{pen_stack-5.1.0 → pen_stack-5.2.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.1.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/)
@@ -60,6 +60,22 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.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

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.1.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.1.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.1.0"
+__version__ = "5.2.0"

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

@@ -29,6 +29,12 @@ def curated_dois() -> frozenset[str]:
     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"):

{pen_stack-5.1.0 → pen_stack-5.2.0}/pen_stack/planner/delivery_immunology.py

@@ -60,8 +60,16 @@ def safety_efficacy_profile(name: str) -> dict | None:
     imm = rec.get("immune_safety") or {}
     immune_present = [t for ax in _IMMUNE_AXES if (t := _tier(imm.get(ax))) is not None]
     immune_score = (1.0 - (sum(immune_present) / len(immune_present)) / 2.0) if immune_present else None
-    gtox = _tier(imm.get(_GENOTOX_AXIS))
-    genotox_score = (1.0 - gtox / 2.0) if gtox is not None else None
+    # genotoxicity: prefer the COMPUTED oracle (v5.2 WS-GENOTOX: integration-site x COSMIC-oncogene
+    # enrichment, from VISDB) for integrating vectors; fall back to the documented ordinal tier when the
+    # oracle abstains. No number is fabricated either way.
+    from pen_stack.planner.genotoxicity_oracle import computed_genotox_score
+    computed, gtox_oracle = computed_genotox_score(name)
+    gtox_tier = _tier(imm.get(_GENOTOX_AXIS))
+    documented_genotox = (1.0 - gtox_tier / 2.0) if gtox_tier is not None else None
+    genotox_score = computed if computed is not None else documented_genotox
+    genotox_source = "computed" if computed is not None else ("documented" if documented_genotox is not None
+                                                              else None)
     sub = [s for s in (immune_score, genotox_score) if s is not None]
     safety_score = min(sub) if sub else None       # worst-axis; abstain if neither documented
     eff = _tier(imm.get("efficacy"))
@@ -72,6 +80,8 @@ def safety_efficacy_profile(name: str) -> dict | None:
         "tiers": {ax: imm.get(ax) for ax in (*_IMMUNE_AXES, _GENOTOX_AXIS)} | {"efficacy": imm.get("efficacy")},
         "immune_score": _r(immune_score),
         "genotox_score": _r(genotox_score),
+        "genotox_source": genotox_source,        # "computed" (VISDBxCOSMIC oracle) | "documented" (ordinal tier)
+        "genotox_provenance": (gtox_oracle.note if genotox_source == "computed" else None),
         "safety_score": _r(safety_score),
         "efficacy_score": _r(efficacy_score),
         "re_dosable": imm.get("re_dosable", rec.get("re_dosable")),

pen_stack-5.2.0/pen_stack/planner/genotoxicity_oracle.py

@@ -0,0 +1,112 @@
+"""Computed genotoxicity oracle for integrating delivery vectors (v5.2, WS-GENOTOX).
+
+Replaces the hard-coded `genotoxicity` ordinal tier (v5.1, documented prior) with a DATA-COMPUTED signal for
+INTEGRATING vehicles: the observed enrichment of a vector class's integration sites near COSMIC Cancer-Gene-
+Census oncogenes, from VISDB integration catalogues x the Phase-1 oncogene annotation (configs/
+genotoxicity_oracle.yaml, built by scripts/p52_build_genotox_oracle.py on the VM where the data lives).
+
+    genotox_score = min(1, 1 / enrichment)      # 1 = safest; episomal/non-targeting ~ 1.0
+
+This reproduces the lentivirus-safer-than-gammaretrovirus ordering FROM DATA (lentiviral ~2x oncogene-proximity
+enrichment vs gammaretroviral ~5-6x — the LMO2 / SCID-X1 pattern), instead of asserting it. It answers through
+the v4.0 OracleResult contract (value + provenance + native_uncertainty + scope_card + output_kind) and is an
+`output_kind="baseline"` observed-data comparator, NOT a generative claim.
+
+HONESTY: 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; a class with too few catalogued sites is
+flagged `extrapolating`; non-integrating vehicles have no insertional mechanism (score 1.0 by mechanism).
+"""
+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
+from pen_stack.planner.delivery_vehicles import vehicle
+
+_SCOPE_CARD = "delivery_genotoxicity"
+
+
+@lru_cache(maxsize=1)
+def _artifact() -> dict:
+    return yaml.safe_load(resource("configs/genotoxicity_oracle.yaml").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def _vehicle_to_class() -> dict:
+    art = _artifact()
+    out: dict[str, str] = {}
+    for cls, vehs in (art.get("vehicle_class") or {}).items():
+        for v in vehs or []:
+            out[v] = cls
+    return out
+
+
+def _prov(source: str, **extra) -> Provenance:
+    art = _artifact()
+    return Provenance(model="visdb_integration_x_cosmic_cgc", version=str(art.get("version", "1.0")),
+                      source=source, extra={"built": art.get("built"),
+                                            "provenance_dois": art.get("provenance_dois", []), **extra})
+
+
+def genotoxicity_oracle(vehicle_name: str) -> OracleResult:
+    """Computed genotoxicity for a delivery vehicle, as an OracleResult (v4.0 contract).
+
+    - non-integrating vehicle  -> genotox_score 1.0 by mechanism (episomal/transient; no insertional risk).
+    - integrating + computed class -> data-derived score from VISDB x COSMIC; small-n class -> extrapolating.
+    - integrating but no computed class / unknown vehicle -> available=False (caller falls back to the
+      documented `immune_safety.genotoxicity` tier; no number is fabricated)."""
+    rec = vehicle(vehicle_name)
+    if rec is None:
+        return OracleResult(oracle="genome", value=None, provenance=_prov("cache"),
+                            scope_card=_SCOPE_CARD, in_scope=False, available=False, output_kind="baseline",
+                            note=f"unknown vehicle {vehicle_name!r}")
+
+    if not rec.get("integrating"):
+        return OracleResult(
+            oracle="genome",
+            value={"genotox_score": 1.0, "enrichment": None, "mechanism": "non-integrating"},
+            provenance=_prov("cache"), native_uncertainty=0.0, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note="episomal/transient vector: no integration -> no insertional-mutagenesis mechanism (score 1.0).")
+
+    cls = _vehicle_to_class().get(vehicle_name)
+    classes = _artifact().get("classes") or {}
+    if not cls or cls not in classes:
+        return OracleResult(oracle="genome", value=None, provenance=_prov("cache"),
+                            scope_card=_SCOPE_CARD, in_scope=False, available=False, output_kind="baseline",
+                            note=f"integrating vehicle {vehicle_name!r} has no computed class; "
+                                 "fall back to the documented genotoxicity tier.")
+
+    rc = classes[cls]
+    enrich = rc.get("enrichment")
+    frac, ci95, n = rc.get("frac_oncogene_50kb"), rc.get("ci95"), rc.get("n_sites")
+    score = min(1.0, 1.0 / enrich) if enrich else None
+    robust = bool(rc.get("robust"))
+    # native uncertainty = relative CI on the observed oncogene-proximity fraction (coefficient of variation)
+    nu = round(ci95 / frac, 4) if (ci95 and frac) else None
+    return OracleResult(
+        oracle="genome",
+        value={"genotox_score": round(score, 3) if score is not None else None,
+               "enrichment": enrich, "frac_oncogene_50kb": frac, "ci95": ci95, "n_sites": n,
+               "frac_genotoxic_cis": rc.get("frac_genotoxic_cis"), "vector_class": cls,
+               "background_frac": _artifact().get("genome_background_frac_oncogene_50kb")},
+        provenance=_prov("cache", virus=rc.get("virus"), vector_class=cls),
+        native_uncertainty=nu, scope_card=_SCOPE_CARD, in_scope=True,
+        extrapolating=not robust, output_kind="baseline", available=True,
+        note=(f"{cls} integration is {enrich}x enriched within "
+              f"{_artifact().get('window_bp')} bp of a COSMIC oncogene vs background "
+              f"({frac:.3%}, n={n}); genotox_score=min(1,1/enrichment)."
+              + ("" if robust else " SMALL-N class: directional only (extrapolating).")
+              + " In-vivo clonal outcome is a known-unknown (not modelled).")
+    )
+
+
+def computed_genotox_score(vehicle_name: str) -> tuple[float | None, OracleResult]:
+    """Convenience: (genotox_score or None, full OracleResult). None when the oracle abstains (caller then
+    uses the documented tier). Never fabricates a number."""
+    r = genotoxicity_oracle(vehicle_name)
+    val = (r.value or {}).get("genotox_score") if (r.available and r.value) else None
+    return val, r

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.1.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
@@ -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.1.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/)
@@ -135,6 +135,22 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.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

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

@@ -19,6 +19,7 @@ configs/delivery_constraints.yaml
 configs/delivery_rules.yaml
 configs/delivery_vehicles.yaml
 configs/gates_v3.yaml
+configs/genotoxicity_oracle.yaml
 configs/gsh_validated_heldout.yaml
 configs/intent_weights.yaml
 configs/known_unknowns.yaml
@@ -155,6 +156,7 @@ pen_stack/planner/delivery.py
 pen_stack/planner/delivery_constraints.py
 pen_stack/planner/delivery_immunology.py
 pen_stack/planner/delivery_vehicles.py
+pen_stack/planner/genotoxicity_oracle.py
 pen_stack/planner/multiplex.py
 pen_stack/planner/optimize.py
 pen_stack/planner/pipeline.py
@@ -243,6 +245,7 @@ prereg/SHA256_LOCK_ws_env.json
 prereg/SHA256_LOCK_ws_ep.json
 prereg/SHA256_LOCK_ws_f.json
 prereg/SHA256_LOCK_ws_g.json
+prereg/SHA256_LOCK_ws_genotox.json
 prereg/SHA256_LOCK_ws_graph.json
 prereg/SHA256_LOCK_ws_h.json
 prereg/SHA256_LOCK_ws_immune.json
@@ -278,6 +281,7 @@ prereg/ws_env.yaml
 prereg/ws_ep.yaml
 prereg/ws_f.yaml
 prereg/ws_g.yaml
+prereg/ws_genotox.yaml
 prereg/ws_graph.yaml
 prereg/ws_h.yaml
 prereg/ws_immune.yaml
@@ -299,5 +303,6 @@ scripts/p1_validation_report.py
 scripts/p2_build_atlas.py
 scripts/p3_benchmark_report.py
 scripts/p4_genome_scan.py
+scripts/p52_build_genotox_oracle.py
 scripts/ws_b_report.py
 scripts/ws_c_report.py

pen_stack-5.2.0/prereg/SHA256_LOCK_ws_genotox.json

@@ -0,0 +1,8 @@
+{
+  "cycle": "v5.2",
+  "workstream": "WS-GENOTOX",
+  "prepared": "2026-06-10",
+  "sha256": {
+    "prereg/ws_genotox.yaml": "4cd8534034fd42986708345eb911bdf62200d0a9c528f80378b29920b4ce434b"
+  }
+}

pen_stack-5.2.0/prereg/ws_genotox.yaml

@@ -0,0 +1,41 @@
+# PEN-STACK v5.2 - WS-GENOTOX (computed integration-site genotoxicity oracle). Directional.
+cycle: "v5.2"
+workstream: "WS-GENOTOX"
+prepared: "2026-06-10"
+
+motivation: >
+  Follow-up to v5.1 (user): "do we have the option of getting an actual CALCULATION from the datasets /
+  databases, like we used to with NetMHC / ENCODE / COSMIC?" The v5.1 genotoxicity axis was a documented
+  ordinal tier; for INTEGRATING vectors the signal is in fact computable from data the stack already holds.
+
+deliverable: >
+  scripts/p52_build_genotox_oracle.py (VM build) -> configs/genotoxicity_oracle.yaml (committed summary);
+  pen_stack/planner/genotoxicity_oracle.py (OracleResult); wired into delivery_immunology.safety_efficacy_profile
+  (computed genotox_score preferred, documented tier fallback); scope card `delivery_genotoxicity`.
+
+method: >
+  For each integrating vector CLASS, compute from real data the observed enrichment of its integration sites
+  near COSMIC Cancer-Gene-Census oncogenes: risk = P(site within 50 kb of an oncogene) over the class's VISDB
+  catalogue; enrichment = risk / genome_background_frac; genotox_score = min(1, 1/enrichment). HIV ~ lentiviral
+  (-> lentivirus vehicle); MLV ~ gammaretroviral (the LMO2 / SCID-X1 comparator, NOT in the palette). Inputs:
+  VISDB per-virus hg38 catalogues [10.1093/nar/gkz867] x the Phase-1 oncogene annotation from COSMIC CGC v104
+  [10.1038/s41568-018-0060-1]; integration biology [HIV 10.1016/S0092-8674(02)00864-4; MLV 10.1126/science.1083413].
+  Answers through the v4.0 OracleResult contract (output_kind="baseline"); raw catalogues stay on the VM, only
+  the auditable summary ships (CI-safe).
+
+acceptance: >
+  (1) the integrating in-palette vehicle (lentivirus) gets a COMPUTED genotox_score from VISDB x COSMIC, with a
+  native uncertainty and an in-scope OracleResult; (2) the computation reproduces the lentivirus-safer-than-
+  gammaretrovirus ordering FROM DATA (lentiviral enrichment < gammaretroviral enrichment); (3) the computed
+  lentivirus score VALIDATES the v5.1 documented "moderate" tier (within +/-0.1 of 0.5), i.e. the prior is
+  confirmed not contradicted; (4) non-integrating vehicles are 1.0 by mechanism; (5) the oracle ABSTAINS
+  (available=False, no number) when it has no computed class - never fabricates; (6) small-n classes are flagged
+  extrapolating; (7) provenance DOIs resolve in the curated set.
+
+honesty_invariant: >
+  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 (scope card `delivery_genotoxicity.not_valid_for`); the
+  immune MAGNITUDE likewise stays `in_vivo_immunogenicity`. No magnitude is predicted.
+
+gate: "lentivirus genotox computed from VISDBxCOSMIC; LV<gammaretro ordering reproduced; computed validates the documented tier; non-integrating=1.0 by mechanism; oracle abstains not fabricates; provenance curated; no-fabrication intact."
+locked_files: [prereg/ws_genotox.yaml]

{pen_stack-5.1.0 → pen_stack-5.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pen-stack"
-version = "5.1.0"
+version = "5.2.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"

pen_stack-5.2.0/scripts/p52_build_genotox_oracle.py

@@ -0,0 +1,112 @@
+"""Build the COMPUTED genotoxicity-oracle artifact (v5.2, WS-GENOTOX).
+
+For each integrating-vector CLASS we compute, from real data, how strongly its integration sites land near
+known oncogenes — the data-grounded genotoxicity signal that replaces the hard-coded `genotoxicity` tier in
+configs/delivery_vehicles.yaml for integrating vehicles:
+
+    risk(class)       = P(an integration site of this class falls within `window_bp` of a COSMIC Cancer-Gene-
+                        Census oncogene)              [observed fraction over the class's site catalogue]
+    enrichment(class) = risk(class) / genome_background_frac        [fold over a random-bin baseline]
+    genotox_score     = min(1, 1 / enrichment)        [1 = safest; episomal/non-targeting ~ 1.0]
+
+Inputs (staged on the VM under /data; NOT shipped — this script runs where the data lives):
+  - /data/external/visdb/*.csv          VISDB per-virus integration-site catalogues (hg38)  [10.1093/nar/gkz867]
+  - /data/features/safety_annot.parquet per-1kb-bin dist_oncogene + genotoxic_cis (COSMIC CGC v104)
+                                                                                  [COSMIC 10.1038/s41568-018-0060-1]
+HIV ~= lentiviral integration biology (favors active gene bodies) [10.1016/S0092-8674(02)00864-4];
+MLV ~= gammaretroviral (favors TSS/enhancers -> the LMO2 / SCID-X1 genotoxicity)  [10.1126/science.1083413].
+
+Output: a SMALL, committable YAML (configs/genotoxicity_oracle.yaml) of per-class summary statistics +
+provenance — the raw catalogues stay on the VM; only the auditable summary ships. Magnitude (in-vivo clonal
+outcome) is NOT modelled here and stays the `in_vivo_immunogenicity` / clonal known-unknown.
+
+Run (on the VM, in the data-mounted image):
+    docker run --rm --entrypoint "" -v ~/data:/data -v ~/penstack:/app -w /app penstack:phase1.5 \\
+        python scripts/p52_build_genotox_oracle.py > configs/genotoxicity_oracle.yaml
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import glob
+import os
+import sys
+
+import pandas as pd
+import yaml
+
+WINDOW_BP = 50_000
+SAFETY_ANNOT = "/data/features/safety_annot.parquet"
+VISDB_DIR = "/data/external/visdb"
+ROBUST_MIN_N = 1000            # below this, a class is directional-only (flagged extrapolating)
+
+# VISDB virus -> integration biology class + the palette vehicle(s) it grounds.
+VIRUS_CLASS = {"HIV": "lentiviral", "HTLV": "deltaretroviral",
+               "MLV": "gammaretroviral", "XMLV": "gammaretroviral"}
+# which palette vehicles each computed class grounds (others are non-integrating -> handled by mechanism)
+CLASS_VEHICLES = {"lentiviral": ["lentivirus"]}
+
+PROVENANCE_DOIS = ["10.1093/nar/gkz867", "10.1038/s41568-018-0060-1",
+                   "10.1016/S0092-8674(02)00864-4", "10.1126/science.1083413"]
+
+
+def _sites(csv: str, main_chroms: set[str]) -> pd.DataFrame:
+    df = pd.read_csv(csv, dtype=str)
+    cols = {c.lower().strip(): c for c in df.columns}
+    cc, sc = cols.get("human chromosome"), cols.get("hg38_start")
+    if not cc or not sc:
+        return pd.DataFrame(columns=["chrom", "bin"])
+    d = pd.DataFrame({
+        "chrom": df[cc].astype(str).map(lambda x: x if x.startswith("chr") else f"chr{x}"),
+        "pos": pd.to_numeric(df[sc], errors="coerce")}).dropna()
+    d = d[d["chrom"].isin(main_chroms)].copy()
+    d["bin"] = (d["pos"].astype(int) // 1000)
+    return d[["chrom", "bin"]]
+
+
+def build() -> dict:
+    sa = pd.read_parquet(SAFETY_ANNOT)[["chrom", "bin", "dist_oncogene", "genotoxic_cis"]]
+    main = set(sa["chrom"].unique())
+    background = float((sa["dist_oncogene"] <= WINDOW_BP).mean())
+
+    classes: dict[str, dict] = {}
+    for csv in sorted(glob.glob(os.path.join(VISDB_DIR, "*.csv"))):
+        virus = os.path.basename(csv).replace(".csv", "")
+        cls = VIRUS_CLASS.get(virus)
+        if cls is None:
+            continue
+        m = _sites(csv, main).merge(sa, on=["chrom", "bin"], how="inner")
+        n = int(len(m))
+        if n == 0:
+            continue
+        frac = float((m["dist_oncogene"] <= WINDOW_BP).mean())
+        ci95 = float(1.96 * (frac * (1 - frac) / n) ** 0.5)
+        enrich = float(frac / background) if background else None
+        rec = {"virus": virus, "n_sites": n,
+               "frac_oncogene_50kb": round(frac, 5), "ci95": round(ci95, 5),
+               "enrichment": round(enrich, 3) if enrich else None,
+               "frac_genotoxic_cis": round(float(m["genotoxic_cis"].mean()), 6),
+               "median_dist_oncogene": int(m["dist_oncogene"].median()),
+               "robust": n >= ROBUST_MIN_N}
+        # keep the larger-n catalogue if a class has multiple viruses (e.g. gammaretro: MLV+XMLV)
+        if cls not in classes or n > classes[cls]["n_sites"]:
+            classes[cls] = rec
+
+    return {
+        "version": "1.0",
+        "built": _dt.date.today().isoformat(),
+        "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": WINDOW_BP,
+        "genome_background_frac_oncogene_50kb": round(background, 5),
+        "inputs": {"visdb": "VISDB per-virus hg38 catalogues", "oncogenes": "COSMIC CGC v104 (safety_annot)"},
+        "provenance_dois": PROVENANCE_DOIS,
+        "robust_min_n": ROBUST_MIN_N,
+        "classes": classes,
+        "vehicle_class": CLASS_VEHICLES,
+    }
+
+
+if __name__ == "__main__":
+    yaml.safe_dump(build(), sys.stdout, sort_keys=False, default_flow_style=False)