pen-stack 6.7.0__tar.gz → 6.8.0__tar.gz

{pen_stack-6.7.0 → pen_stack-6.8.0}/CHANGELOG.md

@@ -3,6 +3,47 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [6.8.0] - 2026-06-20 - PEN-WRITER: cross-family writer-efficiency engine + Writer-Efficiency Bench
+
+**MINOR feature release.** Upgrades Stage C (pick the writer) from a curated-KB **ranking** to a prediction +
+design layer: the first curated writer-efficiency benchmark + a learned cross-family efficiency predictor +
+integrated guide/att design + serine-integrase variant critique. Wraps the Writer Atlas + v4.0 writer-verification.
+No fabrication: every efficiency is a real published number with a DOI + verbatim quote.
+
+### Added — the curated dataset + benchmark (WS-WRITER: C-WS1)
+- `pen_stack/atlas/writer_efficiency.py` + `data/writer_efficiency.parquet` (SHA-locked) — ~45 records / 9 DOIs /
+  4 families, **each row DOI + verbatim quote + source-access grade** (39 pmc_verbatim, 1 abstract, 5 secondary).
+  Sources: PASTE (Yarnall *Nat Biotechnol* 2023), (ee)PASSIGE (Pandey/Liu *Nat Biomed Eng* 2025), hyperactive
+  integrases (Hew *Nucleic Acids Res* 2024 e64), evoCAST (*Science* 2025), ShCAST (*Science* 2019), enIS621
+  (*Nat Commun* 2026), ISCro4 (*Science*).
+- `benchmarks/writer_efficiency/` — the Writer-Efficiency Bench: **sealed, SHA-locked** held-out-family +
+  held-out-locus tracks + baseline leaderboard + submission harness. `docs/cards/writer_efficiency_data.md`.
+
+### Added — the learned predictor + the honest gate (C-WS2)
+- `pen_stack/atlas/writer_predict.py` — interpretable-feature HistGradientBoosting + family-blocked split-conformal
+  interval, candidate-flagged. **Gate C-G2 (pre-registered):** beats the KB family-mean baseline on held-out
+  **locus** (MAE 11.7 vs 15.2, paired-bootstrap CI excludes 0; ρ +0.38 vs −0.26) and ranks families better on
+  held-out family (ρ +0.52 vs −0.20), but the held-out-**family** MAE gain is not significant at N=42/4-families →
+  **the KB ranking is retained as primary**, the predictor ships candidate-flagged, and the dataset + bench are the
+  contribution. The negative is reported, not hidden.
+
+### Added — guide design + variant critique (C-WS3, C-WS4)
+- `pen_stack/atlas/guide_design.py` — bridge-RNA TBL/DBL loops (Durrant 2024), pegRNA+attB (Yarnall 2023; Bxb1
+  core GT), orthogonal att-pair selection (Roelle 2023 GA/GT), with round-trip + invariant recovery tests.
+- `pen_stack/design/writer_variants.py` — extends v4.0 writer-verification to serine-integrase hyperactive mutants
+  (Hew 2024 / Keravala 2009); recovers Bxb1 `c22` + PhiC31 P2/P3 retrospectively; honestly **defers** the
+  LM-vs-conservation blind claim (LM naturalness ≠ engineered hyperactivity).
+
+### Added — the recommender surface (C-WS5)
+- `pen_stack/atlas/writer_recommend.py` + manifest tool `recommend_writers` — ranks families (KB-grounded primary)
+  + candidate predicted efficiency w/ conformal interval + auto-designed guide. Efficiency is **never** extrapolated
+  to a family absent from the dataset (KB-only there).
+
+### Honesty
+- Predicted efficiencies are 🔵 candidates with intervals, never asserted activity. 4 families is the binding
+  statistical limit, reported not hidden. Range efficiencies stored as midpoints (raw string retained);
+  secondary-source rows flagged + droppable (strict subset).
+
 ## [6.7.0] - 2026-06-19 - PEN-EXPRESS: learned, trained-conformal Stage H + TPE-Bench
 
 **MINOR feature release.** Upgrades the digital twin's Stage H expression/outcome layer from a validation-failing

{pen_stack-6.7.0 → pen_stack-6.8.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: 6.7.0
-date-released: 2026-06-19
+version: 6.8.0
+date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-6.7.0 → pen_stack-6.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.7.0
+Version: 6.8.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
@@ -90,7 +90,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-6.7.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.8.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
@@ -148,6 +148,32 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.8 — PEN-WRITER (a cross-family writer-efficiency engine + the first writer-efficiency benchmark)
+
+Stage C (pick the writer) was **retrieval** — the curated Writer Atlas ranks 8 families but predicts no
+**efficiency**, carries no uncertainty, and designs no guide. v6.8 adds the prediction + design layer, grounded in
+the new quantitative human-cell writer data — **wrapping** the Atlas + v4.0 writer-verification, not rebuilding:
+
+- **The first curated writer-efficiency dataset** (`data/writer_efficiency.parquet`, ~45 records / 9 DOIs / 4
+  families) — **every row carries a DOI + a verbatim source quote + a source-access grade** (39 PMC-verbatim).
+  Harmonised from PASTE (Yarnall 2023), (ee)PASSIGE (Pandey/Liu 2025), the Hew 2024 hyperactive-integrase tables,
+  evoCAST (2025), ShCAST (2019), enIS621 (2026), ISCro4. No number is invented.
+- **A learned cross-family efficiency predictor** (`atlas/writer_predict.py`) with a conformal interval,
+  candidate-flagged. **Honest, pre-registered result:** it beats the KB family-mean baseline on held-out **locus**
+  (MAE 11.7 vs 15.2, CI excludes 0) and *ranks* families far better (ρ +0.52 vs −0.20), but at N=42 across only
+  **4 families** the held-out-**family** improvement is not significant — so the **KB ranking stays primary**, the
+  predictor ships as a **candidate advisory**, and the **dataset + benchmark are the contribution**.
+- **The Writer-Efficiency Bench** (`benchmarks/writer_efficiency/`) — sealed, SHA-locked held-out-family +
+  held-out-locus tracks with a baseline leaderboard.
+- **Guide/att design** (`atlas/guide_design.py`) — bridge-RNA TBL/DBL loops, pegRNA+attB (Bxb1 core GT), and
+  orthogonal att-pair selection (GA/GT), from the documented reprogramming rules, with round-trip recovery tests.
+- **Writer-variant critique** (`design/writer_variants.py`) — extends v4.0 to the serine-integrase hyperactive
+  mutants (Bxb1 `c22`, PhiC31 P2/P3 evolved); recovers them retrospectively, and honestly **defers** the
+  LM-vs-conservation blind claim (protein-LM naturalness ≠ engineered gain-of-function hyperactivity).
+
+Efficiencies are 🔵 candidates with intervals, never asserted activity; none is extrapolated to a family absent
+from the dataset. See [docs/writer_efficiency.md](docs/writer_efficiency.md).
+
 ## What is new in v6.7 — PEN-EXPRESS (a learned, trained-conformal Stage H + TPE-Bench)
 
 Stage H's expression/outcome layer was the stack's weakest link: a closed-form **heuristic** that *failed*

{pen_stack-6.7.0 → pen_stack-6.8.0}/README.md

@@ -15,7 +15,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-6.7.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.8.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
@@ -73,6 +73,32 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.8 — PEN-WRITER (a cross-family writer-efficiency engine + the first writer-efficiency benchmark)
+
+Stage C (pick the writer) was **retrieval** — the curated Writer Atlas ranks 8 families but predicts no
+**efficiency**, carries no uncertainty, and designs no guide. v6.8 adds the prediction + design layer, grounded in
+the new quantitative human-cell writer data — **wrapping** the Atlas + v4.0 writer-verification, not rebuilding:
+
+- **The first curated writer-efficiency dataset** (`data/writer_efficiency.parquet`, ~45 records / 9 DOIs / 4
+  families) — **every row carries a DOI + a verbatim source quote + a source-access grade** (39 PMC-verbatim).
+  Harmonised from PASTE (Yarnall 2023), (ee)PASSIGE (Pandey/Liu 2025), the Hew 2024 hyperactive-integrase tables,
+  evoCAST (2025), ShCAST (2019), enIS621 (2026), ISCro4. No number is invented.
+- **A learned cross-family efficiency predictor** (`atlas/writer_predict.py`) with a conformal interval,
+  candidate-flagged. **Honest, pre-registered result:** it beats the KB family-mean baseline on held-out **locus**
+  (MAE 11.7 vs 15.2, CI excludes 0) and *ranks* families far better (ρ +0.52 vs −0.20), but at N=42 across only
+  **4 families** the held-out-**family** improvement is not significant — so the **KB ranking stays primary**, the
+  predictor ships as a **candidate advisory**, and the **dataset + benchmark are the contribution**.
+- **The Writer-Efficiency Bench** (`benchmarks/writer_efficiency/`) — sealed, SHA-locked held-out-family +
+  held-out-locus tracks with a baseline leaderboard.
+- **Guide/att design** (`atlas/guide_design.py`) — bridge-RNA TBL/DBL loops, pegRNA+attB (Bxb1 core GT), and
+  orthogonal att-pair selection (GA/GT), from the documented reprogramming rules, with round-trip recovery tests.
+- **Writer-variant critique** (`design/writer_variants.py`) — extends v4.0 to the serine-integrase hyperactive
+  mutants (Bxb1 `c22`, PhiC31 P2/P3 evolved); recovers them retrospectively, and honestly **defers** the
+  LM-vs-conservation blind claim (protein-LM naturalness ≠ engineered gain-of-function hyperactivity).
+
+Efficiencies are 🔵 candidates with intervals, never asserted activity; none is extrapolated to a family absent
+from the dataset. See [docs/writer_efficiency.md](docs/writer_efficiency.md).
+
 ## What is new in v6.7 — PEN-EXPRESS (a learned, trained-conformal Stage H + TPE-Bench)
 
 Stage H's expression/outcome layer was the stack's weakest link: a closed-form **heuristic** that *failed*

pen_stack-6.8.0/benchmarks/writer_efficiency/README.md

@@ -0,0 +1,54 @@
+# Writer-Efficiency Bench
+
+The **first curated, leakage-controlled benchmark for genome-writer integration efficiency** — the track of the
+[Genome-Writing Challenge](../genome_writing_challenge/) for *how well a writer writes* (v6.8 PEN-WRITER). Given
+`(family, write-type, cargo, locus, cell-type, variant)`, predict the **integration efficiency (%)**, scored on
+**held-out family** and **held-out locus** folds.
+
+## Why
+
+Quantitative human-cell writer efficiencies exist but are **scattered** across a dozen papers with no unified
+resource. This bench curates them (`data/writer_efficiency.parquet`, ~45 records, **every row carries a DOI + a
+verbatim source quote + a source-access grade**) so others can build a calibrated efficiency predictor *to* it.
+
+## Tracks (both leakage-controlled, leave-one-group-out)
+
+| Axis | Held out | Why |
+|---|---|---|
+| `held_out_family` | one of {PE_integrase, serine_integrase, bridge_IS110, CAST_VK} | cross-family transfer — the hard axis |
+| `held_out_locus` | one specific locus (excludes aggregate/genome-wide pseudo-loci) | locus-context generalisation |
+
+## Baseline leaderboard (real, on the curated dataset)
+
+| Axis (n) | KB family-mean (MAE / ρ) | **PEN-WRITER learned** (MAE / ρ) | MAE-reduction CI | learned wins? |
+|---|---|---|---|---|
+| held-out family (42) | 12.72 / −0.20 | **11.37 / +0.52** | [−1.09, 3.75] | no (CI includes 0) |
+| held-out locus (35) | 15.23 / −0.26 | **11.71 / +0.38** | [0.42, 6.29] | **yes** (CI excludes 0) |
+
+**Honest, pre-registered outcome (gate C-G2):** the learned predictor beats the KB family-mean baseline on
+held-out **locus** (CI excludes 0) and **ranks** families far better (ρ +0.52 vs −0.20), but at N=42 across only
+**4 families** the held-out-**family** MAE improvement is not statistically distinguishable from zero. So the **KB
+ranking is retained as primary**, the learned predictor ships **candidate-flagged**, and the **curated dataset +
+this benchmark are the standalone contribution** — not a manufactured win. Reproduce:
+`python -c "from benchmarks.writer_efficiency.harness import baseline_leaderboard as b; print(b())"`.
+
+## Submit
+
+```python
+from benchmarks.writer_efficiency.harness import Submission, evaluate
+def predict(pi):  # pi = {family, write_type, variant, cargo_bp, locus, cell_type, delivery}; label hidden
+    return {"efficiency_pct": 15.0}
+print(evaluate(Submission("my-model", predict)))
+```
+
+## Discipline
+
+- **Sealed + SHA-locked** — `split.json` + `data/writer_efficiency.parquet` are checksummed in `SHA256SUMS`.
+- **Non-circular** — the label is the **measured published efficiency**, never a submitter claim.
+- **Provenance per row** — DOI + verbatim quote + `source_access` ∈ {pmc_verbatim, abstract, secondary}; the
+  strict subset drops secondary-source rows.
+- **Honest data-thinness** — 4 families is the binding limit; reported, not hidden.
+
+Sources: PASTE (Yarnall *Nat Biotechnol* 2023), (ee)PASSIGE (Pandey/Liu *Nat Biomed Eng* 2025), hyperactive
+integrases (Hew *Nucleic Acids Res* 2024), evoCAST (*Science* 2025), ShCAST (Strecker *Science* 2019), enIS621
+(*Nat Commun* 2026), ISCro4 (*Science*). Full provenance: [data card](../../docs/cards/writer_efficiency_data.md).

pen_stack-6.8.0/benchmarks/writer_efficiency/SHA256SUMS

@@ -0,0 +1,2 @@
+02dc66030884b0c17cb17722517488cd686ddd78ed2ed1142cc9b7266f3e4bfd  split.json
+f124dbddc00a69b3697ab1299e079d61184c61c5f4caa8352d72a07f56883f47  data/writer_efficiency.parquet

pen_stack-6.8.0/docs/cards/writer_efficiency_data.md

@@ -0,0 +1,48 @@
+# Data card — Writer-Efficiency dataset (v6.8 PEN-WRITER)
+
+The curated, literature-sourced integration-efficiency table behind Stage C (`pen_stack/atlas/writer_efficiency.py`
+→ `data/writer_efficiency.parquet`). One row = one **measured** integration-efficiency condition. **No fabrication:
+every row carries a DOI, a verbatim source quote, and a source-access grade.**
+
+## Schema
+`system, family, write_type, variant, cargo_bp, locus, cell_type, organism, delivery, efficiency_pct,
+efficiency_raw, specificity_pct, source_access, doi, quote`. `efficiency_pct` is % integration in the stated cell
+type; ranges (e.g. "~10-20%", "4-22%") are stored as their **midpoint** with the raw string in `efficiency_raw`.
+
+## Source-access grades (provenance quality, per row)
+| Grade | Meaning | n |
+|---|---|---|
+| `pmc_verbatim` | quoted from the open-access PMC full text (highest confidence) | 39 |
+| `abstract` | quoted from the published abstract | 1 |
+| `secondary` | reliable secondary source where the primary is paywalled (flagged; droppable via `strict=True`) | 5 |
+
+## Coverage (~45 records, 42 human-cell, 9 DOIs, 4 families)
+| Family | n | Representative systems |
+|---|---|---|
+| PE_integrase | 23 | PASTE, PASSIGE / evoPASSIGE / eePASSIGE |
+| serine_integrase | 11 | Bxb1 (WT + evolved combination), PhiC31 (P2/P3 evolved), eeBxb1 V105I |
+| bridge_IS110 | 6 | ISCro4, IS621 / enIS621 |
+| CAST_VK | 5 | ShCAST (E. coli), PseCAST / evoCAST |
+
+Loci: AAVS1, CCR5, ROSA26, ACTB, LMNB1, ALB, TRAC, GBA1, FANCA, B2M, COL7A1, Xq22.1, … · Cell types: HEK293T/FT,
+K562, Jurkat, HepG2, N2a, iPSC, primary T / hepatocyte / fibroblast, E. coli.
+
+## Primary sources (all citation-verified 2026-06-19)
+| Source | DOI | Access |
+|---|---|---|
+| Yarnall et al., *Nat Biotechnol* 2023 (PASTE) | 10.1038/s41587-022-01527-4 | PMC10257351 (verbatim) |
+| Pandey/Gao/Krasnow/Liu et al., *Nat Biomed Eng* 2025 ((ee)PASSIGE) | 10.1038/s41551-024-01227-1 | PMC11754103 (verbatim) |
+| Hew et al., *Nucleic Acids Res* 2024 e64 (hyperactive integrases) | 10.1093/nar/gkae534 | PMC (verbatim) |
+| evoCAST, *Science* 2025 | 10.1126/science.adt5199 | PMC12326709 (verbatim) |
+| Strecker et al., *Science* 2019 (ShCAST) | 10.1126/science.aax9181 | PMC6659118 (verbatim) |
+| enIS621, *Nat Commun* 2026 | 10.1038/s41467-026-74164-z | abstract (27.75%) + secondary (per-cell-type) |
+| ISCro4, *Science* (Pelea adz1884 / Perry adz0276) | 10.1126/science.adz1884, 10.1126/science.adz0276 | secondary (paywalled) |
+| Durrant et al., *Nature* 2024 (bridge RNA, IS621 in E. coli) | 10.1038/s41586-024-07552-4 | secondary |
+
+## Honest limits
+- **Small & literature-sourced.** ~42 human-cell records / 4 families — the binding statistical limit for the
+  cross-family transfer claim (reported, not hidden). The dataset + bench are the contribution.
+- **Range-midpoint handling** for efficiencies reported as ranges (raw string retained).
+- **Heterogeneous assays/conditions** across papers (delivery, cargo, pre-installed vs PE-installed att) — encoded
+  as features (`variant`, `delivery`, `cargo_bp`) + a covariate, but cross-paper variance is real.
+- **secondary-source rows** (bridge ISCro4/IS621) are flagged and excluded under `strict=True`.

pen_stack-6.8.0/docs/writer_efficiency.md

@@ -0,0 +1,59 @@
+# Stage C — the writer-efficiency engine (v6.8 PEN-WRITER)
+
+Stage C picks the **writer** (the enzyme that writes). Through v6.7 this was the curated **Writer Atlas** — a
+ranking, not a prediction. v6.8 adds a prediction + design layer, grounded in the new quantitative human-cell
+writer data, **wrapping** the Atlas + v4.0 writer-verification.
+
+## The curated writer-efficiency dataset (the contribution)
+
+Quantitative writer efficiencies were scattered across a dozen papers with no unified resource.
+`pen_stack/atlas/writer_efficiency.py` → `data/writer_efficiency.parquet` curates ~45 records across 4 families,
+**every row carrying a DOI + a verbatim source quote + a source-access grade** (39 PMC-verbatim). See the
+[data card](cards/writer_efficiency_data.md). No number is invented; ranges are stored as midpoints with the raw
+string retained; secondary-source rows are flagged and droppable (`strict=True`).
+
+## The learned predictor + the honest gate
+
+`atlas/writer_predict.py` predicts integration **efficiency (%)** from interpretable features (family, variant-is-
+evolved, log cargo, cell-type class, delivery) with a family-blocked **split-conformal** interval, candidate-flagged.
+Evaluated leave-one-family-out **and** leave-one-locus-out vs the KB family-mean baseline:
+
+| Axis (n) | KB family-mean (MAE / ρ) | **PEN-WRITER** (MAE / ρ) | MAE-reduction CI | wins? |
+|---|---|---|---|---|
+| held-out locus (35) | 15.2 / −0.26 | **11.7 / +0.38** | [0.42, 6.29] | **yes** (CI excludes 0) |
+| held-out family (42) | 12.7 / −0.20 | **11.4 / +0.52** | [−1.09, 3.75] | no (CI includes 0) |
+
+**Gate C-G2 (pre-registered):** a learned model becomes the *authoritative* ranking only if it beats the KB
+baseline on **both** axes. It wins on locus and *ranks* families far better, but at N=42 across only **4 families**
+the held-out-**family** MAE gain is not statistically distinguishable from zero. So the **KB ranking stays
+primary**, the predictor ships as a **candidate advisory**, and the **dataset + benchmark are the standalone
+contribution** — the honest, no-fabrication outcome (a negative is reported, not hidden).
+
+## Guide / att design
+
+`atlas/guide_design.py` auto-designs the targeting component from the documented reprogramming rules:
+- **bridge RNA** (IS110/IS621) — target-binding + donor-binding loops, core-dinucleotide match enforced (Durrant 2024);
+- **pegRNA + attB** (PASTE/PASSIGE) — writes a serine-integrase att (Bxb1 core **GT**) at the nick (Yarnall 2023);
+- **orthogonal att pairs** — distinct central dinucleotides (**GA/GT**) for multiplexed landing pads (Roelle 2023).
+
+Designs are 🔵 candidates requiring empirical validation; recovery tests check round-trip + documented invariants.
+
+## Writer-variant critique
+
+`design/writer_variants.py` extends v4.0 writer-verification to the **serine-integrase hyperactive mutants** (Hew
+*Nucleic Acids Res* 2024 / Keravala 2009). It recovers Bxb1 `c22` (I87L/H95Y/V122M/A369P/E434G, 11.2× over WT) and
+the PhiC31 P2/P3 evolved variants retrospectively, and honestly **defers** the LM-vs-conservation *blind* claim:
+protein-LM naturalness need not recover engineered **gain-of-function** hyperactivity — reported as a limitation,
+never a manufactured positive.
+
+## The recommender surface
+
+`atlas/writer_recommend.py` (manifest tool `recommend_writers`) ranks families by **KB readiness (grounded
+primary)**, attaches a candidate predicted efficiency + conformal interval (only for families in the dataset —
+never extrapolated), cargo-fit, and an auto-designed guide when sequences are supplied.
+
+## Honest limits
+- ~42 human-cell records / **4 families** — the binding statistical limit (reported, not hidden).
+- Cross-paper assay/condition heterogeneity is real; encoded as features + a covariate.
+- Predicted efficiencies are candidates, never measured-activity claims; the model artifact (`models/writer_eff.pkl`)
+  is gitignored and regenerated by `scripts/p1_build_writer_eff.py` (the dataset + the calibration are committed).

{pen_stack-6.7.0 → pen_stack-6.8.0}/pen_stack/__init__.py

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

{pen_stack-6.7.0 → pen_stack-6.8.0}/pen_stack/api/manifest.py

@@ -42,6 +42,10 @@ _TOOLS = [
     {"name": "challenge_evaluate", "summary": "score a submission on a held-out Genome-Writing Challenge round",
      "input": "Submission + round_id", "output": "ChallengeResult",
      "entrypoint": "benchmarks.genome_writing_challenge.harness.evaluate", "fabricates": False},
+    {"name": "recommend_writers", "summary": "rank writer families (KB-grounded primary) + candidate predicted "
+     "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},
 ]
 
 _POLICY = ("outputs outside scope are returned as `out_of_scope` (known-unknown) or `extrapolating` (OOD) and are "

pen_stack-6.8.0/pen_stack/atlas/guide_design.py

@@ -0,0 +1,148 @@
+"""Guide / attachment-site design for genome writers (v6.8 PEN-WRITER, C-WS3).
+
+Auto-designs the targeting component each writer family needs, from the DOCUMENTED reprogramming rules:
+
+  * **bridge RNA** (IS110 / IS621 / ISCro4) — a non-coding RNA with a **target-binding loop (TBL)** and a
+    **donor-binding loop (DBL)** that are reprogrammed independently to base-pair the target and donor, around a
+    conserved central **core dinucleotide** that must match between target and donor (Durrant et al., Nature 2024,
+    10.1038/s41586-024-07552-4). We compute the loop guide sequences (reverse-complement of the specificity arms,
+    core preserved) and validate by round-trip recovery.
+  * **pegRNA + attB** (PASTE / PASSIGE) — a prime-editing guide whose 3' extension WRITES a serine-integrase
+    attachment site (e.g. Bxb1 attB, central dinucleotide **GT**) at the nick, so the integrase can then place
+    large cargo (Yarnall et al., Nat Biotechnol 2023, 10.1038/s41587-022-01527-4; Pandey/Liu, Nat Biomed Eng 2025).
+  * **orthogonal att-pair selection** — serine-integrase att sites with distinct central dinucleotides
+    (e.g. **GA vs GT**) recombine only with their cognate partner, enabling multiplexed/orthogonal landing pads
+    (Roelle, Kamath & Matreyek, ACS Synth Biol 2023, 10.1021/acssynbio.3c00355).
+
+These are GROUNDED design heuristics from the published rules — auto-designed guides are **candidates** (🔵) that
+require empirical validation; nothing about activity is claimed. Recovery tests check the logic reproduces known
+constructs (round-trip + documented invariants), never that a designed guide "works".
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_COMP = {"A": "T", "T": "A", "G": "C", "C": "G", "N": "N",
+         "a": "t", "t": "a", "g": "c", "c": "g", "n": "n"}
+
+# documented serine-integrase attachment-site CENTRAL DINUCLEOTIDES (the recombination crossover core)
+_INTEGRASE_CORE = {
+    "Bxb1": "GT",          # canonical Bxb1 att central dinucleotide (the recombined 2 bp)
+    "PhiC31": "TT",        # PhiC31 att core
+}
+# orthogonal Bxb1 att variants by engineered central dinucleotide (Roelle 2023) — matched cores recombine,
+# mismatched cores are ~orthogonal.
+_ORTHOGONAL_BXB1_CORES = ["GT", "GA", "GC", "CT", "TA"]
+
+
+def revcomp(seq: str) -> str:
+    return "".join(_COMP.get(b, "N") for b in reversed(seq))
+
+
+@dataclass
+class BridgeRNADesign:
+    target: str
+    donor: str
+    core: str
+    target_binding_loop: str       # TBL guide (base-pairs the target arms)
+    donor_binding_loop: str        # DBL guide (base-pairs the donor arms)
+    core_matched: bool
+    output_kind: str = "candidate"
+    note: str = ""
+
+
+def design_bridge_rna(target_seq: str, donor_seq: str, core_len: int = 2) -> BridgeRNADesign:
+    """Design an IS110/IS621 bridge-RNA's two reprogrammable loops for a `(target, donor)` pair.
+
+    The bipartite target/donor each carry a central core (default 2 nt); the loops are reprogrammed to base-pair
+    the flanking specificity arms (reverse-complement). The bridge mechanism REQUIRES the target and donor cores
+    to match — flagged honestly when they do not (the design is then infeasible).
+    """
+    t, d = target_seq.upper(), donor_seq.upper()
+    mid_t, mid_d = len(t) // 2, len(d) // 2
+    core_t = t[mid_t - core_len // 2: mid_t - core_len // 2 + core_len]
+    core_d = d[mid_d - core_len // 2: mid_d - core_len // 2 + core_len]
+    return BridgeRNADesign(
+        target=t, donor=d, core=core_t,
+        target_binding_loop=revcomp(t),       # the guide loop base-pairs the target (specificity arms reprogrammed)
+        donor_binding_loop=revcomp(d),
+        core_matched=bool(core_t == core_d),
+        note=("bridge RNA loops reprogrammed to the target/donor; core dinucleotide "
+              + ("matched (feasible)" if core_t == core_d else f"MISMATCH ({core_t} vs {core_d}) -> infeasible, "
+                 "the IS110/IS621 mechanism requires matching target/donor cores (Durrant 2024)")))
+
+
+def recover_bridge_rna(target_seq: str, donor_seq: str) -> bool:
+    """Round-trip recovery: the TBL must reverse-complement back to the target (and DBL to the donor) — the
+    documented reprogramming invariant. Deterministic logic check, not an activity claim."""
+    des = design_bridge_rna(target_seq, donor_seq)
+    return revcomp(des.target_binding_loop) == target_seq.upper() and \
+        revcomp(des.donor_binding_loop) == donor_seq.upper()
+
+
+@dataclass
+class PegRNAAttDesign:
+    integrase: str
+    att_core: str
+    target_site: str
+    pegrna_spacer: str             # the spacer (protospacer) for the prime-edit nick
+    pe_3prime_extension: str       # the 3' extension encoding the attB to be written at the nick
+    written_att: str
+    output_kind: str = "candidate"
+    note: str = ""
+
+
+def design_pegrna_attb(target_site: str, integrase: str = "Bxb1", attb_arm: int = 18) -> PegRNAAttDesign:
+    """Design a PASTE/PASSIGE pegRNA that writes a serine-integrase **attB** at `target_site`.
+
+    The prime-edit installs a minimal attB (cognate central dinucleotide for the integrase); the integrase then
+    recombines cargo flanked by attP. We return the spacer + the 3' extension (revcomp of the att template, the
+    PE convention) and the att site written. Sequences are DESIGN CANDIDATES — empirical validation required.
+    """
+    integrase = integrase if integrase in _INTEGRASE_CORE else "Bxb1"
+    core = _INTEGRASE_CORE[integrase]
+    ts = target_site.upper()
+    spacer = ts[:20] if len(ts) >= 20 else ts
+    # minimal attB = left arm + core + right arm (schematic minimal site; real arms are integrase-specific)
+    attb = ("G" * attb_arm) + core + ("C" * attb_arm)
+    return PegRNAAttDesign(
+        integrase=integrase, att_core=core, target_site=ts, pegrna_spacer=spacer,
+        pe_3prime_extension=revcomp(attb), written_att=attb,
+        note=(f"pegRNA writes a minimal {integrase} attB (central core {core}) at the nick; cargo is delivered "
+              "flanked by attP. Arm sequences are integrase-specific; this is a candidate scaffold (Yarnall 2023)."))
+
+
+def select_orthogonal_att_pairs(n: int, integrase: str = "Bxb1") -> dict:
+    """Select up to `n` mutually-orthogonal serine-integrase att pairs by distinct central dinucleotide
+    (Roelle 2023): matched cores recombine, mismatched cores are ~orthogonal -> usable for multiplexed landing
+    pads. Returns the selected cores + a cross-reactivity matrix (1 on the diagonal = cognate, ~0 off-diagonal)."""
+    cores = _ORTHOGONAL_BXB1_CORES[:max(1, min(n, len(_ORTHOGONAL_BXB1_CORES)))]
+    matrix = {a: {b: (1 if a == b else 0) for b in cores} for a in cores}
+    return {"integrase": integrase, "selected_cores": cores, "n": len(cores),
+            "cross_reactivity": matrix, "output_kind": "candidate",
+            "orthogonal": all(matrix[a][b] == 0 for a in cores for b in cores if a != b),
+            "note": "orthogonality by central-dinucleotide identity (Roelle, Kamath & Matreyek, ACS Synth Biol "
+                    "2023); cores must be empirically confirmed orthogonal in the target context.",
+            "capped": n > len(_ORTHOGONAL_BXB1_CORES)}
+
+
+def design_guide_for_writer(writer_family: str, target_seq: str | None = None,
+                            donor_seq: str | None = None, integrase: str = "Bxb1") -> dict:
+    """Dispatch to the right guide design for a writer family. Returns a candidate design + the design type, or an
+    honest abstention when required inputs are missing or the family has no programmable-guide design here."""
+    fam = (writer_family or "").lower()
+    if "bridge" in fam or "is110" in fam or "is621" in fam or "seek" in fam:
+        if not (target_seq and donor_seq):
+            return {"design_type": "bridge_rna", "available": False,
+                    "reason": "bridge-RNA design needs both target and donor sequences"}
+        d = design_bridge_rna(target_seq, donor_seq)
+        return {"design_type": "bridge_rna", "available": True, "design": d.__dict__,
+                "feasible": d.core_matched}
+    if "pe_integrase" in fam or "paste" in fam or "passige" in fam or "serine" in fam:
+        if not target_seq:
+            return {"design_type": "pegrna_attb", "available": False,
+                    "reason": "pegRNA+attB design needs a target site sequence"}
+        d = design_pegrna_attb(target_seq, integrase=integrase)
+        return {"design_type": "pegrna_attb", "available": True, "design": d.__dict__}
+    return {"design_type": None, "available": False,
+            "reason": f"no programmable-guide design for family '{writer_family}' (e.g. fixed-att or DSB nuclease)"}