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

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

@@ -3,6 +3,102 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [7.2.1] - 2026-07-02 - PhiC31 integrase: close the O-WS3/O-G2 data gap with verified data + a sealed recall benchmark (honest NEGATIVE)
+
+Closes the one genuine open item from v7.2.0 — the PhiC31 integrase data gap — with independently-verified,
+open, citable sequences (no fabrication) and a **sealed recall benchmark whose result is reported verbatim**.
+
+### Added
+- **PhiC31 is now encoded** (`data/curated/integrase_att.yaml`), replacing the v7.2.0 abstain-with-disclosure. All
+  data was **independently validated against NCBI/RCSB** (which caught two errors in the completion pack's
+  citations, since corrected): att from **PDB 9U2T/9U2S** ("PhiC31 integrase-attB-attP synaptic complex"; the
+  canonical Groth-2000 34 bp attB is present in attB53); the documented human pseudo-attP **ψA/ψC/ψD** from
+  **GenBank AF333429/AF333430/AF333431** (Thyagarajan 2001, *Mol Cell Biol* 21(12), PMID 11359900,
+  DOI `10.1128/MCB.21.12.3926-3934.2001`; chr8/16/15). Corrected DOIs: Groth 2000 `10.1073/pnas.090527097`,
+  Chalberg 2006 `10.1016/j.jmb.2005.11.098` (was `...11.108`).
+- **Sealed PhiC31 pseudo-attP recall benchmark** (`benchmarks/offtarget/integrase/`, O-G2): does attP-sequence-
+  similarity recover the documented pseudo-attP above length-matched GRCh38 background? **Result — NEGATIVE,
+  reported verbatim:** all three sites score 14 mm / 30 bp (53.3% identity), exactly the background **median**
+  (60.6% / 77.0% / 82.4% of random windows are as-or-more attP-similar). Sequence identity to attP is **not** a
+  validated PhiC31 pseudo-attP predictor — φC31 recognition depends on palindromic architecture (Chalberg 2006) /
+  a learned model (IntQuery), not raw identity.
+
+### Changed
+- **Integrase status corrected: `semi_validated` → `mechanism_based_unvalidated` (with a sealed-NEGATIVE benchmark).**
+  The v7.2.0 "semi-validated (documented pseudosites as partial ground truth)" implied the sites validated the
+  method; the sealed benchmark shows they do not. This is a *stronger, more honest* outcome — a tested negative
+  rather than an untested claim. The verified att + documented pseudosites remain grounded facts and are surfaced
+  as verified known off-target loci. `nominate_integrase` PhiC31 returns the documented pseudo-attP + the sealed
+  benchmark; Bxb1 returns genome-wide similarity candidates carrying the same `similarity_ranking_validated: false`
+  caveat. Prereg O-G2 amended + re-SHA-locked; data card + deviations ledger updated; Off-Target page shows the
+  documented sites + the benchmark verdict.
+
+## [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.1}/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.1
+date-released: 2026-07-02
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-7.1.8 → pen_stack-7.2.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 7.1.8
+Version: 7.2.1
 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.1/benchmarks/offtarget/integrase/README.md

@@ -0,0 +1,23 @@
+# PhiC31 pseudo-attP recall benchmark (O-G2) — SEALED
+
+**Question:** does attP-sequence-similarity recover the documented human pseudo-attP above random genomic background?
+
+**Data (all independently verified against NCBI/RCSB):**
+- **Positives** — `phic31_pseudo.fasta`: human pseudo-attP ψA/ψC/ψD, GenBank **AF333429/AF333430/AF333431**
+  (Thyagarajan 2001, *Mol Cell Biol* 21(12), PMID 11359900, DOI `10.1128/MCB.21.12.3926-3934.2001`; chr8/16/15).
+- **Query** — the phage φC31 attP central 30 bp from **PDB 9U2T (attP60)**, the "PhiC31 integrase-attB-attP synaptic
+  complex" structure; the canonical Groth-2000 34 bp attB is present in **PDB 9U2S (attB53)** (Groth 2000, PNAS,
+  DOI `10.1073/pnas.090527097`).
+- **Background** — 1000 GC/N-filtered, length-matched random GRCh38 windows per positive.
+
+**Result (`phic31_recall_metrics.json`) — NEGATIVE, reported verbatim:** every documented pseudosite scores 14 mm /
+30 bp (53.3% identity), which is exactly the **background median** (14 mm); 60.6% / 77.0% / 82.4% of random windows
+are as-or-more attP-similar. Sequence identity to attP does **not** recover the documented pseudo-attP above
+background — consistent with the field (φC31 pseudosite recognition depends on palindromic architecture, Chalberg
+2006 DOI `10.1016/j.jmb.2005.11.098`, / a learned model, IntQuery). The integrase genome-wide pseudo-attP
+**similarity ranking is therefore unvalidated**; the verified att and documented pseudosites remain grounded facts.
+
+**Honest limits:** N=3 (the open GenBank subset; the full Chalberg 19-site set is paywalled); tests
+sequence-identity only (no palindrome/learned model); deterministic (seed 20260701), pysam over GRCh38.
+
+Run: `docker run --rm --entrypoint bash -v <genomes>:/genome -v $PWD:/work -w /work penstack:phase1.5 -lc 'python harness.py'`

pen_stack-7.2.1/benchmarks/offtarget/integrase/SHA256SUMS

@@ -0,0 +1,4 @@
+701efce23441ba6ec3865060aa3a749d7165d013628f3ed8010737861b306557  README.md
+888dd4ba69bbe1eccd323797adc89b242b1c8ec6208a5f9f41df839d641d10e6  harness.py
+fe23827ff34204bc2cd1f903fcd3e32b120c4521787342e6590824249573a4d4  phic31_pseudo.fasta
+2a0f22d700f0db0bafd1c98b8b8893f14e86ae9574ff789042bd3ad1c7f6a3c0  phic31_recall_metrics.json

pen_stack-7.2.1/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.1/data/curated/integrase_att.yaml

@@ -0,0 +1,66 @@
+# 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. Confirming assay: Cryptic-seq / HIDE-seq.
+#
+# HONEST STATUS (v7.2.1): the att sequences and the documented human pseudo-attP are VERIFIED grounded facts, but a
+# SEALED recall benchmark on the best-documented pseudosites (PhiC31 psiA/psiC/psiD) is NEGATIVE — att-sequence-
+# similarity does NOT recover them above random background (see PhiC31.recall_benchmark below). So the genome-wide
+# pseudo-attP SIMILARITY RANKING is a mechanism-based scan that is NOT validated as a predictor; it is honestly
+# labelled as such, not "semi-validated." The documented pseudosites are surfaced as verified known-off-target loci.
+#
+# 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 — now ENCODED with independently-verified sequences (v7.2.1, closes the O-WS3 data gap). att from the
+  # phiC31 integrase-attB-attP synaptic-complex structure (PDB 9U2T attP60 / 9U2S attB53; the canonical Groth-2000
+  # 34 bp attB is present in attB53); documented human pseudo-attP from Thyagarajan 2001 (GenBank AF333429/30/31).
+  PhiC31:
+    origin: "phage phiC31 (Streptomyces)"
+    attB: "GTGCCAGGGCGTGCCCTTGGGCTCCCCGGGCGCG"  # canonical 34 bp minimal attB (verified inside PDB 9U2S attB53)
+    attP: "CGGGAGTAGTGCCCCAACTGGGGTAACCTTTGAGTTCTCTCAGTTGGGGGCGTAGGGTCG"  # PDB 9U2T attP60 (60 bp)
+    core: "TTG"
+    central_dinucleotide: "TT"
+    scan_window: "AACTGGGGTAACCTTTGAGTTCTCTCAGTT"  # attP central 30 bp (localises to the psiA recombination core)
+    scan_max_mismatch: 8
+    source: "Groth et al., PNAS 2000; PDB 9U2T/9U2S (phiC31 integrase-attB-attP synaptic complex)"
+    doi: "10.1073/pnas.090527097"
+    pdb: ["9U2T", "9U2S"]
+    # documented human pseudo-attP positive set (verified GenBank; the integration loci)
+    pseudo_attP_positive_set:
+      - {name: psiA, genbank: AF333429, chrom: chr8}
+      - {name: psiC, genbank: AF333430, chrom: chr16}
+      - {name: psiD, genbank: AF333431, chrom: chr15}
+    positive_set_source: "Thyagarajan et al., Mol Cell Biol 21(12), 2001"
+    positive_set_doi: "10.1128/MCB.21.12.3926-3934.2001"
+    # SEALED recall benchmark (O-G2) — result reported VERBATIM: benchmarks/offtarget/integrase/phic31_recall_metrics.json
+    recall_benchmark:
+      recovered_above_background: false
+      verdict: "NEGATIVE — attP-sequence-similarity does NOT recover the documented pseudo-attP above random
+        background (all 3 sites at 14 mm / 30 bp = the background median; 60.6/77.0/82.4% of background as-or-more
+        similar). Sequence identity alone is not a validated PhiC31 pseudo-attP predictor; recognition depends on
+        palindromic architecture (Chalberg 2006, 10.1016/j.jmb.2005.11.098) / a learned model (IntQuery)."
+      metrics: "benchmarks/offtarget/integrase/phic31_recall_metrics.json"
+    specificity_note: "PhiC31 is a PROMISCUOUS serine integrase with documented human pseudo-attP (unlike Bxb1).
+      The sealed recall benchmark (above) is NEGATIVE: the att-similarity scan does not distinguish the documented
+      pseudosites from background, so the genome-wide similarity RANKING is unvalidated (honest negative)."

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

@@ -90,3 +90,28 @@ 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, PhiC31) | recombination at genomic pseudo-attP | fixed-sequence att-window scan | 🔵 **mechanism-based, sealed-NEGATIVE benchmark** (v7.2.1) | att verified (Bxb1: FlyBase FBto0000359 / Ghosh 2003 `10.1016/S1097-2765(03)00444-1`; PhiC31: **PDB 9U2T/9U2S** + Groth 2000 `10.1073/pnas.090527097`); the PhiC31 human pseudo-attP set is verified (Thyagarajan 2001, **GenBank AF333429/30/31**, `10.1128/MCB.21.12.3926-3934.2001`; chr8/16/15). The v7.2.1 **SEALED recall benchmark** (`benchmarks/offtarget/integrase/`) is **NEGATIVE**: att-sequence-similarity does NOT recover the documented pseudo-attP above random background (all three at 14 mm / 30 bp = the background median). The genome-wide similarity RANKING is therefore **unvalidated** — φC31 recognition needs palindromic architecture (Chalberg 2006, `10.1016/j.jmb.2005.11.098`) / a learned model (IntQuery), not raw identity. Documented pseudosites surfaced as verified known loci; the negative is reported verbatim (a stronger, more honest O-G2 than an untested "semi-validated"). |
+| **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.1}/pen_stack/__init__.py

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

{pen_stack-7.1.8 → pen_stack-7.2.1}/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.1}/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.1}/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.1}/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.1/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}