pen-stack 7.1.8__tar.gz → 7.2.0__tar.gz

{pen_stack-7.1.8 → pen_stack-7.2.0}/CHANGELOG.md

@@ -3,6 +3,72 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [7.2.0] - 2026-07-01 - PEN-OFFTGT v2: Stage E becomes a genome-wide, per-mechanism off-target FINDER (all 5 writer classes)
+
+Stage E was a candidate *scorer* — it ranked off-target sites you supplied. A real off-target tool (CRISPOR /
+CHOPCHOP) takes a guide/target and *finds* the genome-wide off-target set itself. PEN-OFFTGT v2 closes that
+enumeration gap AND applies the **correct off-target mechanism for each writer class**, each carrying a truthful
+per-mechanism validation status (O-WS0–O-WS9 of the plan).
+
+### Per-mechanism paths (O-WS3–O-WS6)
+- **Serine integrase** (`offtarget_integrase.py`, O-WS3): a genome-wide **pseudo-attP** scan — a fixed-sequence
+  Cas-OFFinder scan of the attP core window over GRCh38, scored by att-arm similarity. **Bxb1** is fully encoded
+  (FlyBase FBto0000359 / Ghosh 2003) and is highly specific. Status **semi-validated**. **PhiC31 is a disclosed
+  data gap** (its documented human pseudo-attP set — Chalberg 2006 — could not be verified from an open source in
+  this build, so it abstains rather than fabricate). `data/curated/integrase_att.yaml`.
+- **Bridge** (`offtarget_bridge.py`, O-WS4): wraps the existing DMS-scored genome scan (measured Perry-2025
+  specificity, held-out ranking AUROC 0.88). Status **hard-locked mechanism-based-unvalidated** — the ranker is
+  DMS-validated but **no genome-wide cellular off-target assay exists** for bridge recombinases, so genomic
+  recovery is unvalidated (stated in a no-ground-truth disclosure).
+- **CAST** (`offtarget_cast.py` + `data/curated/cast_systems.yaml`, O-WS5) — NEW: guide-directed spacer scan +
+  the distinctive **guide-independent untargeted-transposition** background per system (ShCAST/Type V-K high +
+  AT-biased; VchCAST/Type I-F >95–99% on-target), all DOI-tagged. Status **mechanism-based-unvalidated**.
+- **PASTE / (ee)PASSIGE** (`offtarget_paste.py`, O-WS6) — NEW: composes the validated nuclease finder (Cas9
+  nickase, pegRNA) with the semi-validated integrase pseudo-attP scan (installed att); returns both component sets
+  and recommends BOTH a nuclease assay and an integrase assay. Status **composite**.
+
+### Status labels + assay recommender (O-WS7) + disclosures (O-WS8 / gate O-G3)
+- Every nomination carries a per-mechanism status label + the mechanism-appropriate confirm assay; `recommend_assay`
+  now covers CAST (transposon insertion-site seq) and PASTE (dual). `docs/cards/offtarget_data.md` documents the
+  per-mechanism ground-truth status — **O-G3: every mechanism has either a sealed benchmark (nuclease) or an
+  explicit no-ground-truth / data-gap disclosure (integrase-PhiC31, bridge, CAST) — never a fabricated metric.**
+- Disclosed deviations from the plan (no silent substitution): `att_pwm.json` → an att-similarity model in
+  `integrase_att.yaml` (a per-position PWM needs aligned pseudosites that do not exist at genome scale);
+  `bridge_dms_specificity.parquet` → the existing measured `bridge_offtarget_profile_measured.parquet` is reused;
+  `known_pseudosites.parquet` → not created (Bxb1 highly specific; PhiC31 disclosed data gap).
+
+### Nuclease finder (O-WS0–O-WS2)
+
+### Added
+- **Genome-wide enumeration engine** (`pen_stack/wgenome/offtarget_enumerate.py`, O-WS1). Given a guide + enzyme,
+  enumerates every genomic site within the mismatch tolerance across GRCh38 via **Cas-OFFinder** (Bae, Park & Kim,
+  Bioinformatics 2014, `10.1093/bioinformatics/btu048`), returning coordinates, strand, matched sequence, and
+  mismatch count. Supports SpCas9 (NGG), SaCas9 (NNGRRT), and Cas12a (TTTV, 5' PAM). A full scan is heavy, so it
+  runs **only on the VM** (`casoffinder:tools` Docker image, `docker/casoffinder.Dockerfile`); the live app
+  **replays a committed coordinate cache** for the canonical guides or **abstains honestly** for a novel one
+  (never fabricates sites) — the same replay-or-abstain pattern as the heavy structure oracles. The enumerated
+  coordinates are facts from the public GRCh38 assembly (no license restriction), so the cache is committed
+  (`data/offtarget/enumerated_cache.parquet`, 8 canonical guides, 40,268 sites).
+- **Nuclease off-target FINDER** (`pen_stack/wgenome/offtarget_nuclease.py`, O-WS2): chains enumeration into the
+  existing, validated scorer — real CRISOT-Score → mismatch-calibrated risk band → chromatin annotation — so a
+  guide returns the genome-wide ranked off-target set *with coordinates*. Scoring is unchanged from v6.10 (still
+  validated: CRISOT beats homology on four unbiased assays); v2 adds the enumeration front end.
+- **O-G1 gate PASSED**: enumeration recovers **100%** of EMX1's documented GUIDE-seq off-targets within the ≤5-mm
+  tolerance (all 16 validated-active sites, which are all ≤4 mm; the higher-mismatch fixture rows are inactive
+  negatives). The on-target is recovered at chr2:72,933,852. `tests/unit/test_ws_offtarget2.py`.
+- **Prereg** `prereg/ws_offtarget2.yaml` (SHA-locked): the mechanism taxonomy, per-enzyme enumeration parameters,
+  the truthful per-mechanism status-label rules (validated / semi-validated / mechanism-based-unvalidated), and
+  the O-G1/G2/G3 gates.
+- REST: `POST /offtarget` is now a **finder by default** for a nuclease guide with no supplied `candidate_sites`
+  (accepts `enzyme`, `max_mismatch`); `GET /offtarget/enumerated` lists the cached guides. The web **Off-Target**
+  page is rebuilt as a finder (guide in → genome-wide ranked off-targets with coordinates), with the scorer→finder
+  explanation and the VM/cache architecture stated.
+
+### Unchanged / backward compatible
+- Supplying `candidate_sites` keeps the v6.10 score-my-candidates path. The integrase (pseudo-attB sequence scan),
+  bridge (Perry-DMS), chromatin annotation, and validation-assay recommender are unchanged. Nomination remains a
+  candidate, never a clearance.
+
 ## [7.1.8] - 2026-06-30 - Writer immunogenicity moves to the Writer Atlas; SpCas9 removed from the writer options
 
 ### Changed

{pen_stack-7.1.8 → pen_stack-7.2.0}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 7.1.8
-date-released: 2026-06-30
+version: 7.2.0
+date-released: 2026-07-01
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-7.1.8 → pen_stack-7.2.0}/MANIFEST.in

@@ -5,6 +5,7 @@ include README.md LICENSE CHANGELOG.md CITATION.cff pyproject.toml
 recursive-include configs *.yaml *.yml *.txt.example *.fasta
 recursive-include prereg *.yaml *.json
 recursive-include data/curated *
+recursive-include data/offtarget *.parquet
 recursive-include benchmarks *.yaml *.md SHA256SUMS
 recursive-include bench *.py
 recursive-include docs *.md

{pen_stack-7.1.8 → pen_stack-7.2.0}/PKG-INFO

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

pen_stack-7.2.0/data/curated/cast_systems.yaml

@@ -0,0 +1,59 @@
+# CRISPR-associated transposase (CAST) systems — per-system off-target properties (PEN-OFFTGT v2, O-WS5).
+#
+# CAST off-target has TWO distinct modes, and the balance differs by system type:
+#   1. guide-directed  — integration at genomic sites matching the crRNA spacer (a sequence-match scan, like a
+#                        nuclease off-target, but the transposon inserts ~49-66 bp downstream of the protospacer).
+#   2. guide-INDEPENDENT untargeted transposition — the Tn7-like transposase machinery (TnsB/TnsC/TniQ) inserting
+#                        WITHOUT the CRISPR effector or the guide. This is the DISTINCTIVE, dominant off-target mode
+#                        for Type V-K systems (ShCAST) and is largely absent in Type I-F systems (VchCAST).
+#
+# All values are DOCUMENTED facts from the primary literature (DOIs below), reported as a qualitative tier plus the
+# published on-target fidelity where a number is stated. This is NOT a genome-wide cellular off-target assay
+# (none exists for CAST at genome scale) -> status is mechanism_based_unvalidated; the confirming assay is
+# transposon insertion-site sequencing.
+
+version: "1.0"
+
+systems:
+  ShCAST:
+    full_name: "Scytonema hofmanni CAST"
+    cast_type: "V-K"
+    effector: "Cas12k"
+    untargeted_transposition: high            # guide/Cas12k-INDEPENDENT, AT-biased (the dominant off-target mode)
+    guide_independent: true
+    at_biased_untargeted: true
+    on_target_fidelity_note: "up to ~80% integration in E. coli without selection, but LOW fidelity: prone to
+      extensive RNA-independent (guide-independent) transposition via TnsB/TnsC/TniQ; improved vectors that
+      suppress the RNA-independent pathway raise specificity up to 98.1% (Type V-K)."
+    dois:
+      - "10.1126/science.aax9181"   # Strecker et al. 2019, ShCAST (Science) — RNA-guided DNA insertion with CAST
+      - "10.1126/science.adj8543"   # Type V-K target-site selection + untargeted mechanism (Science 2024)
+  VchCAST:
+    full_name: "Vibrio cholerae CAST (Tn6677 / INTEGRATE)"
+    cast_type: "I-F"
+    effector: "Cascade (Cas6-Cas7-Cas8/Cas5) + TniQ"
+    untargeted_transposition: low             # high fidelity; guide-independent transposition largely absent
+    guide_independent: false
+    at_biased_untargeted: false
+    on_target_fidelity_note: "remarkable fidelity — the majority of crRNAs direct >95% on-target integration and
+      many exceed 99%; up to ~100% integration efficiency of cargo up to ~10 kb in bacteria."
+    dois:
+      - "10.1038/s41586-019-1323-z" # Klompe et al. 2019, VchCAST / Tn6677 (Nature)
+      - "10.1038/s41587-020-00745-y" # Vo et al. 2021, INTEGRATE high-efficiency multiplexed (Nat Biotechnol)
+  evoCAST:
+    full_name: "evolved Scytonema hofmanni CAST (PACE-evolved)"
+    cast_type: "V-K"
+    effector: "Cas12k (evolved)"
+    untargeted_transposition: moderate        # directed evolution improved specificity over WT ShCAST
+    guide_independent: true
+    at_biased_untargeted: true
+    on_target_fidelity_note: "evolved Type V-K CAST with substantially improved on-target integration in human
+      cells; guide-independent transposition is reduced relative to WT ShCAST but not eliminated."
+    dois:
+      - "10.1126/science.adr8492"   # Tou et al. 2025, evoCAST (Science) — evolved CAST for human-cell insertion
+      - "10.1038/s41587-023-01748-1" # Lampe et al. 2024, targeted integration in human cells without DSBs (Nat Biotechnol)
+
+# scope: human-cell CAST is emerging (evoCAST 2025); the untargeted-transposition rates above are characterised in
+# bacteria / biochemically. No genome-wide unbiased CELLULAR off-target assay exists for human-cell CAST -> the
+# genomic predictions are mechanism-based, unvalidated; confirm with transposon insertion-site sequencing.
+confirm_assay: "transposon insertion-site sequencing (e.g. Tn-seq / integration-site amplicon sequencing)"

pen_stack-7.2.0/data/curated/integrase_att.yaml

@@ -0,0 +1,43 @@
+# Serine-integrase attachment sites for the genome-wide pseudo-att off-target scan (PEN-OFFTGT v2, O-WS3).
+#
+# A serine integrase recombines a donor attB with a genomic pseudo-attP resembling the phage attP. The off-target
+# scan enumerates genomic sites similar to the attP core region (a fixed-sequence Cas-OFFinder scan over GRCh38,
+# tolerating mismatches), then scores each by att-arm similarity. Status: SEMI-VALIDATED (documented pseudosites as
+# partial ground truth). Confirming assay: Cryptic-seq / HIDE-seq.
+#
+# DEVIATION (disclosed): the prereg named `att_pwm.json`. A position-weight MATRIX requires many aligned pseudosite
+# sequences to estimate per-position tolerance; that alignment does not exist at genome scale for these integrases.
+# So the scan uses att-arm SIMILARITY (mismatch count to the documented att, core-anchored) rather than a fitted
+# PWM — a mechanism-based similarity model, honestly labelled, not a fabricated per-position matrix.
+
+version: "1.0"
+
+integrases:
+  Bxb1:
+    origin: "phage Bxb1 (Mycobacterium)"
+    attB: "TCGGCCGGCTTGTCGACGACGGCGGTCTCCGTCGTCAGGATCATCCGGGC"
+    attP: "GTCGTGGTTTGTCTGGTCAACCACCGCGGTCTCAGTGGTGTACGGTACAAACCCCGAC"
+    core: "GCGGTCTC"
+    central_dinucleotide: "GT"
+    # 34-nt attP window centred on the core — the fixed sequence scanned genome-wide for pseudo-attP
+    scan_window: "CTGGTCAACCACCGCGGTCTCAGTGGTGTACGGT"
+    scan_max_mismatch: 8
+    specificity_note: "Bxb1 is highly specific — very few genomic pseudo-attP in human cells (a reason it is the
+      integrase of choice for PASTE/PASSIGE). The scan therefore returns few high-similarity candidates."
+    source: "FlyBase FBto0000359/358; Ghosh, Kim & Hatfull, Mol Cell 2003"
+    doi: "10.1016/S1097-2765(03)00444-1"
+
+# PhiC31 — DISCLOSED DATA GAP (reported, not fabricated): PhiC31 is the integrase with the best-documented human
+# pseudo-attP set (~19 sites, Chalberg et al. 2006), which would make the strongest semi-validation benchmark.
+# Its exact minimal attB/attP arm sequences and the pseudo-attP genomic coordinates could not be verified from an
+# open, citable source in this build (the central crossover is a documented TT dinucleotide; the minimal attB is
+# ~34 bp). Rather than fabricate the arm sequence or the pseudosite coordinates, PhiC31 is NOT encoded here; the
+# integrase scan abstains for PhiC31 with this disclosure. Encoding the verified PhiC31 att + the Chalberg-2006
+# pseudo-attP table is the follow-up that would upgrade O-G2 from "stated" to a sealed recall benchmark.
+phic31_disclosure:
+  status: "not_encoded_data_gated"
+  documented_fact: "PhiC31 has ~19 characterised human pseudo-attP sites (a promiscuous serine integrase)."
+  central_dinucleotide: "TT"
+  minimal_attB_length_bp: 34
+  reference: "Chalberg et al., J Mol Biol 2006 (PhiC31 human pseudo-attP mapping); Thyagarajan et al., Mol Cell Biol 2001"
+  doi: "10.1016/j.jmb.2005.11.108"

{pen_stack-7.1.8 → pen_stack-7.2.0}/docs/cards/offtarget_data.md

@@ -90,3 +90,29 @@ candidate ENUMERATION needs the on-VM Cas-OFFinder/genome scan; this benchmark c
 candidates. Bridge/integrase off-target is data-thin: there is **no published genome-wide unbiased off-target assay
 or predictor for bridge recombinases** (verified), and the large-serine-integrase assays (Cryptic-seq/HIDE-seq) and
 predictor (IntQuery) are recent single-company preprints with no public weights.
+
+---
+
+## v7.2 (PEN-OFFTGT v2) — per-mechanism ground-truth status (O-WS8 / gate O-G3)
+
+Stage E is now a genome-wide **finder** (Cas-OFFinder over GRCh38; heavy scan on the VM, cached coordinates
+replayed by the app). Each writer class applies the correct off-target mechanism and carries a **truthful
+validation status** — a sealed benchmark where ground truth exists, an explicit **no-genome-wide-ground-truth
+disclosure** where it does not. No mechanism is ever presented as validated where the data cannot support it.
+
+| Writer class | Mechanism | Enumeration | Status | Ground truth / benchmark |
+|---|---|---|---|---|
+| **Nuclease** (SpCas9/SaCas9/Cas12a) | mismatch-tolerant cleavage at protospacer+PAM | Cas-OFFinder genome scan | ✅ **validated** | 4-assay Off-Target-Bench (above) + **O-G1**: enumeration recovers 100% of EMX1's documented GUIDE-seq off-targets ≤5 mm |
+| **Serine integrase** (Bxb1) | recombination at genomic pseudo-attP | fixed-sequence att-window scan | 🟡 **semi-validated** | documented pseudosites are partial ground truth; Bxb1 att verified (FlyBase FBto0000359 / Ghosh 2003, `10.1016/S1097-2765(03)00444-1`); Bxb1 is highly specific (few genomic pseudo-attP) |
+| **Serine integrase** (PhiC31) | — | — | 🟡 semi-validated | **DISCLOSED DATA GAP**: PhiC31 has ~19 documented human pseudo-attP (Chalberg 2006, `10.1016/j.jmb.2005.11.108`) — the strongest integrase benchmark — but its exact att arm / pseudosite sequences were not verifiable from an open source in this build, so PhiC31 is **not encoded and abstains** rather than fabricate. Encoding it is the follow-up that upgrades O-G2 to a sealed recall benchmark. |
+| **Bridge** (IS110/IS621) | recombination at bridge-RNA target-loop matches | core-seeded genome scan (pysam) | 🔵 **mechanism-based, unvalidated** | **NO genome-wide unbiased CELLULAR off-target assay exists** (technology ~2024). The mismatch-tolerance RANKER is validated on the measured Perry-2025 in-vitro DMS specificity (held-out ranking AUROC 0.88), but genomic recovery is unvalidated. |
+| **CAST** (ShCAST V-K / VchCAST I-F) | guide-directed integration + guide-independent untargeted transposition | spacer scan + per-system untargeted background | 🔵 **mechanism-based, unvalidated** | untargeted-transposition rates documented per system (`data/curated/cast_systems.yaml`): ShCAST high/AT-biased (Strecker 2019 `10.1126/science.aax9181`; Science 2024 `10.1126/science.adj8543`), VchCAST >95–99% on-target (Klompe 2019 `10.1038/s41586-019-1323-z`; Vo 2021 `10.1038/s41587-020-00745-y`). No genome-wide cellular assay for human-cell CAST. |
+| **PASTE / (ee)PASSIGE** | Cas9-nickase off-target + integrase pseudo-attP | compose(nuclease, integrase) | composite (✅ nickase + 🟡 integrase) | inherits the nuclease benchmark for the nickase and the integrase status for the installed att; recommends BOTH a nuclease assay AND an integrase assay |
+
+**O-G3 satisfied:** every mechanism has either a sealed benchmark (nuclease) or an explicit no-ground-truth /
+data-gap disclosure (integrase-PhiC31, bridge, CAST) — never a fabricated metric. The bridge and CAST paths are
+**hard-locked** to 🔵 unvalidated in code.
+
+**Honest limits (v7.2):** enumeration recall depends on the mismatch tolerance (≤5 mm nuclease, ≤8 mm integrase
+att window); very divergent off-targets can be missed (a limitation shared with CRISPOR). DNA/RNA bulges are not
+enumerated in v2.0 (substitutions only). The engine nominates and ranks; it does not clear a design.

{pen_stack-7.1.8 → pen_stack-7.2.0}/pen_stack/__init__.py

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

{pen_stack-7.1.8 → pen_stack-7.2.0}/pen_stack/agent/mcp_server.py

@@ -156,14 +156,17 @@ def immune_profile(design: dict) -> dict:
 
 @mcp.tool()
 def offtarget_scan(writer_family: str, guide: str | None = None, candidate_sites: list | None = None,
-                   sequence: str | None = None, assay: str = "guideseq") -> dict:
-    """v6.10 PEN-OFFTGT cross-family off-target NOMINATION (NOT a clearance). Ranks candidate sites with a
-    real-data mismatch-calibrated risk band + the real CRISOT learned score (nuclease), a pseudo-attB scan
-    (integrase), or the Perry-DMS pseudosite engine (bridge); ships the validation assay that would confirm
-    each candidate. Abstains without inputs; never fabricates sites."""
+                   sequence: str | None = None, assay: str = "guideseq", enzyme: str | None = None,
+                   max_mismatch: int = 5) -> dict:
+    """PEN-OFFTGT v2 genome-wide, per-mechanism off-target FINDER (NOT a clearance). For a nuclease guide it
+    enumerates the genome-wide off-target set over GRCh38 (Cas-OFFinder, cached) + real CRISOT + risk + chromatin
+    (validated); serine integrase = genome-wide pseudo-attP scan (semi-validated); bridge = DMS-scored scan
+    (mechanism-based, unvalidated); CAST = guide-directed + untargeted-transposition background (unvalidated);
+    PASTE = nuclease + integrase composition. Each carries a truthful status label + the confirming assay.
+    Abstains for a novel input (VM scan); never fabricates sites."""
     from pen_stack.wgenome.offtarget_predict import nominate_offtargets
     return nominate_offtargets(writer_family, guide=guide, candidate_sites=candidate_sites,
-                               sequence=sequence, assay=assay)
+                               sequence=sequence, assay=assay, enzyme=enzyme, max_mismatch=max_mismatch)
 
 
 @mcp.tool()

{pen_stack-7.1.8 → pen_stack-7.2.0}/pen_stack/api/manifest.py

@@ -50,11 +50,13 @@ _TOOLS = [
      "efficiency w/ conformal interval + auto-designed guide/att (v6.8 PEN-WRITER)",
      "input": "write request (write-type, cargo, cell type, optional target/donor seq)", "output": "WriterRanking",
      "entrypoint": "pen_stack.atlas.writer_recommend.recommend_writers", "fabricates": False},
-    {"name": "nominate_offtargets", "summary": "cross-writer-family off-target NOMINATION: rank candidate sites "
-     "with a real-data mismatch-calibrated risk band + the real CRISOT learned score (nuclease), pseudo-attB "
-     "scan (integrase), Perry-DMS pseudosite engine (bridge); nomination is NOT a clearance (v6.10 PEN-OFFTGT)",
-     "input": "writer family + guide/candidate sites (nuclease) or locus sequence (integrase)",
-     "output": "ranked off-target candidates + calibrated risk + recommended validation assay",
+    {"name": "nominate_offtargets", "summary": "genome-wide, per-mechanism off-target FINDER (v7.2 PEN-OFFTGT v2): "
+     "enumerates the off-target set over GRCh38 (Cas-OFFinder) and applies the correct mechanism per writer class "
+     "- nuclease cleavage (validated: CRISOT + risk + chromatin), integrase pseudo-attP (semi-validated), bridge "
+     "target-specificity (unvalidated), CAST guide + untargeted transposition (unvalidated), PASTE composition - "
+     "each with a truthful status label; nomination is NOT a clearance",
+     "input": "writer family + guide/target (enumerated genome-wide) or supplied candidate sites",
+     "output": "genome-wide ranked off-target candidates + per-mechanism status + calibrated risk + validation assay",
      "entrypoint": "pen_stack.wgenome.offtarget_predict.nominate_offtargets", "fabricates": False},
     {"name": "recommend_delivery", "summary": "cross-modality delivery recommender: rank vehicles by cargo-form + "
      "safety<->efficacy + a grounded serotype->tissue tropism prior (approved therapies) + the learned FLIP-AAV "

{pen_stack-7.1.8 → pen_stack-7.2.0}/pen_stack/server/api.py

@@ -374,15 +374,19 @@ def immune_endpoint(design: dict):
 
 @app.post("/offtarget", tags=["v6.10 off-target"])
 def offtarget_endpoint(req: dict):
-    """v6.10 PEN-OFFTGT cross-family off-target NOMINATION (NOT a clearance). Body:
-    {writer_family, guide?, candidate_sites?, sequence?, accessibility?, assay?}. Returns ranked candidate
-    off-targets with a real-data mismatch-calibrated risk band + the recommended validation assay; abstains
-    without inputs and never fabricates sites."""
+    """PEN-OFFTGT cross-family off-target NOMINATION (NOT a clearance). Body:
+    {writer_family, guide?, enzyme?, max_mismatch?, candidate_sites?, sequence?, accessibility?, assay?}.
+
+    v7.2 (finder): for a nuclease guide with NO ``candidate_sites``, enumerates the genome-wide off-target set
+    over GRCh38 (Cas-OFFinder, replayed from the committed cache) and ranks it by the real CRISOT-Score +
+    mismatch-calibrated risk + chromatin annotation - the CRISPOR-like default. Supplying ``candidate_sites``
+    keeps the v6.10 score-my-candidates path. Abstains (never fabricates) for a novel guide with no VM scan."""
     from pen_stack.wgenome.offtarget_predict import nominate_offtargets
     return nominate_offtargets(
         req.get("writer_family", ""), guide=req.get("guide"), candidate_sites=req.get("candidate_sites"),
         sequence=req.get("sequence"), accessibility=req.get("accessibility"),
-        target_core=req.get("target_core"), assay=req.get("assay", "guideseq"))
+        target_core=req.get("target_core"), assay=req.get("assay", "guideseq"),
+        enzyme=req.get("enzyme"), max_mismatch=int(req.get("max_mismatch", 5)))
 
 
 @app.get("/offtarget/assay", tags=["v6.10 off-target"])
@@ -392,6 +396,20 @@ def offtarget_assay_endpoint(writer_family: str):
     return recommend_assay(writer_family)
 
 
+@app.get("/offtarget/enumerated", tags=["v6.10 off-target"])
+def offtarget_enumerated_endpoint():
+    """v7.2: the guides whose genome-wide off-target enumeration is CACHED (so the finder works here without a VM
+    scan). A novel guide abstains (its scan runs on the VM). Enumerated coordinates are public-genome facts."""
+    from pen_stack.wgenome.offtarget_data import CANONICAL_GUIDES
+    from pen_stack.wgenome.offtarget_enumerate import enumerated_guides
+    cached = enumerated_guides()
+    seq2name = {v: k for k, v in CANONICAL_GUIDES.items()}
+    return {"enzyme": "SpCas9",
+            "guides": [{"guide": g, "name": seq2name.get(g, g), "enzyme": e} for e, g in cached],
+            "note": ("genome-wide enumeration for these guides is replayed from the committed GRCh38 Cas-OFFinder "
+                     "cache; a novel guide requires an on-VM scan (the finder abstains rather than fabricate).")}
+
+
 @app.get("/campaign", tags=["v7.0 closed-loop"])
 def campaign_endpoint():
     """v7.0 Stage J: the validation-campaign engine. Returns the expression-validation campaign: the next batch of

{pen_stack-7.1.8 → pen_stack-7.2.0}/pen_stack/wgenome/offtarget_assay.py

@@ -29,7 +29,7 @@ def recommend_assay(writer_family: str) -> dict:
                             "in the target cell type (GUIDE-seq), chromatin masks a fraction of in vitro sites",
                 "available": True,
                 "note": "nomination ranks CANDIDATES; an empirical assay is required for clearance."}
-    if "integrase" in fam or "paste" in fam or "passige" in fam or "bxb1" in fam or "phic31" in fam:
+    if ("integrase" in fam or "bxb1" in fam or "phic31" in fam) and "paste" not in fam and "passige" not in fam:
         return {"family": writer_family, "writer_class": "large serine integrase",
                 "recommended": [{"assay": "Cryptic-seq / HIDE-seq", "setting": "unbiased LSI off-target discovery",
                                  "doi": "10.1101/2024.08.23.609471",
@@ -39,6 +39,29 @@ def recommend_assay(writer_family: str) -> dict:
                             "quantitative prediction (IntQuery) is paper-only (no public weights)",
                 "available": True,
                 "note": "LSI off-target assays are recent preprints; coverage is single-company / largely Bxb1."}
+    if "paste" in fam or "passige" in fam:
+        return {"family": writer_family, "writer_class": "prime-editing integrase (PASTE / PASSIGE)",
+                "recommended": [
+                    {"assay": "GUIDE-seq / CHANGE-seq", "setting": "nuclease (nickase) off-target", "doi": "10.1038/nbt.3117",
+                     "use": "confirm the Cas9-nickase off-targets of the pegRNA spacer"},
+                    {"assay": "Cryptic-seq / HIDE-seq", "setting": "integrase off-target", "doi": "10.1101/2024.08.23.609471",
+                     "use": "confirm the integrase pseudo-attP sites of the installed att"}],
+                "strategy": "PASTE off-target is composite — run BOTH a nuclease assay (for the nickase) AND an "
+                            "integrase assay (for the installed att); the two components are independent.",
+                "available": True,
+                "note": "two independent off-target mechanisms; neither assay alone clears a PASTE design."}
+    if "cast" in fam or "cas12k" in fam or "shcast" in fam or "vchcast" in fam or "evocast" in fam:
+        return {"family": writer_family, "writer_class": "CRISPR-associated transposase (CAST)",
+                "recommended": [{"assay": "transposon insertion-site sequencing", "setting": "unbiased integration mapping",
+                                 "doi": "10.1126/science.aax9181",
+                                 "use": "map genome-wide integration sites, including guide-INDEPENDENT untargeted "
+                                        "transposition (the dominant off-target mode for Type V-K, e.g. ShCAST)"}],
+                "strategy": "sequence integration sites to capture BOTH guide-directed off-targets and the "
+                            "guide-independent untargeted-transposition background (Type V-K high; Type I-F low)",
+                "available": True,
+                "note": "KNOWN GAP: no genome-wide unbiased CELLULAR off-target assay is standardised for human-cell "
+                        "CAST; untargeted-transposition rates are characterised in bacteria/biochemically. "
+                        "Mechanism-based, unvalidated."}
     if "bridge" in fam or "is110" in fam or "is621" in fam or "seek" in fam or "iscro4" in fam:
         return {"family": writer_family, "writer_class": "bridge recombinase (IS110/IS621 RNA-guided)",
                 "recommended": [{"assay": "targeted amplicon / capture sequencing at nominated pseudosites",

pen_stack-7.2.0/pen_stack/wgenome/offtarget_bridge.py

@@ -0,0 +1,47 @@
+"""Bridge-recombinase (IS110 / IS621) off-target path (PEN-OFFTGT v2, O-WS4).
+
+Bridge recombinases are RNA-guided: the bridge RNA's target-binding loop base-pairs with a bipartite ~14-nt
+genomic target (central CT). Off-target = genomic sites matching that target with tolerated mismatches. This
+wraps the existing genome-wide scanner (`pen_stack.bridge.offtarget`), which seeds on the central core and scores
+each pseudosite by the **measured Perry-2025 DMS specificity landscape** (which target mismatches the recombinase
+tolerates) — a held-out ranking AUROC of 0.88 on that in-vitro DMS data.
+
+**Status: mechanism_based_unvalidated (hard-locked).** Crucially, the DMS ranker being validated on *in-vitro
+specificity* does NOT make the *genomic off-target predictions* validated: there is **no published genome-wide
+unbiased CELLULAR off-target assay** for bridge recombinases (the technology is ~2024), so the genomic pseudosite
+calls cannot be validated. The honest report is: a mechanism-based scan with a DMS-grounded mismatch-tolerance
+model, labelled unvalidated, with the no-genome-wide-assay disclosure. Confirm by targeted amplicon /
+integration-site sequencing. Never claims validation.
+"""
+from __future__ import annotations
+
+_STATUS = "mechanism_based_unvalidated"
+_DISCLOSURE = (
+    "NO published genome-wide unbiased CELLULAR off-target assay exists for bridge recombinases (IS110/IS621; the "
+    "technology is ~2024). The pseudosite RANKER is validated on the measured Perry-2025 in-vitro DMS specificity "
+    "landscape (held-out ranking AUROC 0.88), but genomic recovery is NOT validated. Treat nominations as "
+    "high-uncertainty, mechanism-based candidates — never a clearance."
+)
+
+
+def nominate_bridge(target_core: str | None = None, writer_family: str = "bridge_IS110",
+                    fasta=None, chroms: list[str] | None = None, top: int = 20) -> dict:
+    """Genome-wide bridge off-target scan for a bridge-RNA target core, via the DMS-scored engine. Returns the
+    ranked pseudosites when a genome + target core are supplied (VM), else reports the engine is ready and how to
+    run the scan. Always carries the hard-locked unvalidated status + the no-genome-wide-assay disclosure."""
+    from pen_stack.bridge.offtarget import predict_offtargets
+    fam = "seek_IS1111" if ("seek" in (writer_family or "").lower() or "is1111" in (writer_family or "").lower()) \
+        else "bridge_IS110"
+    res = predict_offtargets(fam, target_core=target_core, fasta=fasta, chroms=chroms, top=top)
+    return {"family": "bridge", "writer_family": fam, "status": _STATUS,
+            "ranker": "Perry-2025 DMS specificity landscape (measured; held-out ranking AUROC 0.88)",
+            "no_ground_truth_disclosure": _DISCLOSURE,
+            "confirm_assay": "targeted amplicon / integration-site sequencing at nominated pseudosites",
+            "available": res.get("status") == "scanned",
+            "abstain": not (res.get("status") == "scanned"),
+            "engine": res,
+            "method": ("seed on the central core (CT), verify the bipartite ~14-nt target with tolerated "
+                       "mismatches, score by the measured DMS specificity (position + substitution identity)"),
+            "honesty": ("mechanism-based CANDIDATES with a DMS-grounded mismatch-tolerance model; NOT a validated "
+                        "genome-wide predictor (no cellular assay exists) and NOT a clearance."),
+            "nomination_is_not_clearance": True}

pen_stack-7.2.0/pen_stack/wgenome/offtarget_cast.py

@@ -0,0 +1,97 @@
+"""CAST (CRISPR-associated transposase) off-target path (PEN-OFFTGT v2, O-WS5) — NEW.
+
+CAST off-target is two mechanisms, and their balance is system-dependent:
+  * **guide-directed** — integration at genomic sites matching the crRNA spacer (a sequence-match scan; the
+    transposon inserts a fixed distance downstream of the protospacer). Enumerated genome-wide on the VM (or
+    replayed from cache); abstains for a novel spacer.
+  * **guide-INDEPENDENT untargeted transposition** — the Tn7-like machinery (TnsB/TnsC/TniQ) inserting without the
+    CRISPR effector. This is the DISTINCTIVE, dominant off-target mode for **Type V-K** (ShCAST) and is largely
+    absent in **Type I-F** (VchCAST). It is reported as a per-system documented property (`cast_systems.yaml`),
+    with DOIs — NOT a genome-wide prediction.
+
+Status: **mechanism_based_unvalidated** (no genome-wide unbiased CELLULAR off-target assay exists for CAST). The
+confirming assay is transposon insertion-site sequencing. Never fabricates a validated metric.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack.wgenome.offtarget_enumerate import DEFAULT_MAX_MISMATCH, enumerate_motif
+
+_STATUS = "mechanism_based_unvalidated"
+_ALIAS = {"shcast": "ShCAST", "vchcast": "VchCAST", "evocast": "evoCAST",
+          "cast": "ShCAST", "cast_vk": "ShCAST", "cast_v-k": "ShCAST", "cast_if": "VchCAST",
+          "type_v-k": "ShCAST", "type_i-f": "VchCAST", "cas12k": "ShCAST"}
+
+
+@lru_cache(maxsize=1)
+def cast_systems() -> dict:
+    """The curated CAST system table (per-system untargeted-transposition properties + DOIs), or {} when absent."""
+    try:
+        import yaml
+
+        from pen_stack._resources import resource
+        return yaml.safe_load(resource("data/curated/cast_systems.yaml").read_text(encoding="utf-8")) or {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def resolve_cast_system(name: str) -> str | None:
+    sysd = cast_systems().get("systems", {})
+    n = (name or "").strip()
+    if n in sysd:
+        return n
+    return _ALIAS.get(n.lower())
+
+
+def nominate_cast(system: str = "ShCAST", spacer: str | None = None,
+                  max_mismatch: int = DEFAULT_MAX_MISMATCH) -> dict:
+    """CAST off-target nomination: the guide-independent untargeted-transposition background (per-system documented
+    property) PLUS guide-directed enumeration for a supplied spacer (genome-wide, replayed/abstained). Never
+    fabricates sites or a validated metric; status is mechanism_based_unvalidated."""
+    tbl = cast_systems()
+    key = resolve_cast_system(system) or "ShCAST"
+    rec = (tbl.get("systems") or {}).get(key, {})
+    if not rec:
+        return {"family": "cast", "available": False, "abstain": True, "status": _STATUS,
+                "note": f"no curated CAST system {system!r}; known: {sorted((tbl.get('systems') or {}))}"}
+
+    untargeted = {
+        "mode": "guide-independent untargeted transposition (TnsB/TnsC/TniQ, no CRISPR effector)",
+        "tier": rec.get("untargeted_transposition"),
+        "guide_independent": rec.get("guide_independent"),
+        "at_biased": rec.get("at_biased_untargeted"),
+        "cast_type": rec.get("cast_type"),
+        "fidelity_note": rec.get("on_target_fidelity_note"),
+        "dois": rec.get("dois", []),
+        "note": ("the DISTINCTIVE CAST off-target mode: Type V-K (ShCAST) shows HIGH guide-independent, AT-biased "
+                 "untargeted transposition; Type I-F (VchCAST) is high-fidelity (low untargeted). A documented "
+                 "per-system property, NOT a genome-wide prediction."),
+    }
+
+    # guide-directed: a spacer-match genome scan (enumerated on the VM; replayed from cache or abstains).
+    guided = None
+    if spacer:
+        enum = enumerate_motif(f"CAST_{key}_{spacer.upper()}")
+        if enum.get("available"):
+            sites = enum["sites"]
+            n_on = sum(1 for s in sites if s["n_mismatch"] == 0)
+            guided = {"mode": "guide-directed (crRNA spacer match)", "available": True,
+                      "n_sites_genome_wide": len(sites), "n_on_target": n_on,
+                      "n_offtargets": len(sites) - n_on, "source": enum["source"],
+                      "sites": sorted(sites, key=lambda s: s["n_mismatch"])[:50],
+                      "note": "genomic sites matching the crRNA spacer; the transposon inserts a fixed distance "
+                              "downstream. Ranked by mismatch (no CRISOT — that is a Cas9-nuclease model)."}
+        else:
+            guided = {"mode": "guide-directed (crRNA spacer match)", "available": False, "abstain": True,
+                      "note": enum["note"], "cached_motifs": enum.get("cached_motifs", [])}
+
+    return {"family": "cast", "system": key, "cast_type": rec.get("cast_type"), "available": True, "abstain": False,
+            "status": _STATUS, "untargeted_background": untargeted, "guide_directed": guided,
+            "confirm_assay": tbl.get("confirm_assay"),
+            "method": ("CAST off-target = guide-directed spacer-match enumeration (genome-wide, VM) + the "
+                       "guide-independent untargeted-transposition background (documented per-system property). "
+                       "No genome-wide unbiased cellular assay exists -> mechanism-based, unvalidated."),
+            "honesty": "CANDIDATES + a documented untargeted-transposition risk; NOT a clearance and NOT a "
+                       "validated genome-wide predictor. Confirm by transposon insertion-site sequencing.",
+            "nomination_is_not_clearance": True}