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

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

@@ -3,6 +3,86 @@
 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
+closed-form **heuristic** to a **learned, trained-conformal, decomposable** position-effect model — and ships the
+held-out benchmark the expression capability never had. Wrap, don't rebuild: extends `twin` + `wgenome.uncertainty`
++ `wgenome.ood` + `benchmarks`. No fabrication: every metric is from a real CV run on real TRIP supervision, and
+the cross-cell-type transfer claim is **data-gated**, never faked.
+
+### Added — the learned model + trained conformal (WS-EXPRESS2: WS-D/M/U)
+- `pen_stack/twin/data/position_effect.py` — unified position-effect schema + dataset registry with **verified
+  accessions/DOIs** (TRIP live; PatchMPRA/MPIRE/lentiMPRA/Leemans registered + honestly `available=False` until
+  fetched), z-normalization within (dataset × cassette), domain-blocked + held-out-cell-type splits + leakage check.
+- `pen_stack/twin/position_effect.py` — `PositionEffectModel` (factored `f_cassette` + `g_context`, LightGBM),
+  `evaluate()` (chromosome-blocked CV vs the v3.x durability head + cassette-only, paired-bootstrap CIs,
+  separability), split-conformal calibration (`ConformalRegressor`, chromosome-Mondrian, OOD-widened),
+  `predict_stage_h()` serving seam. **Result (real TRIP):** expression ρ **0.428 → 0.469** (CI excludes 0);
+  held-out conformal coverage **0.885** vs 0.90 nominal.
+- `configs/twin/position_effect_conformal.json` — the shipped calibration (qhat + N + held-out coverage).
+- `scripts/p1_build_position_effect.py` — regenerates the model + conformal artifacts (real CV report).
+
+### Changed — Stage H integration (WS-I)
+- `pen_stack/twin/outcome.py` — when a chromatin context is supplied and the artifact is present, `predict_outcome`
+  serves the **learned trained-conformal** interval + `p_silenced` + OOD tier (`position_effect` block,
+  `stage_h_mode`); with no context/artifact it falls back to the heuristic band — **backward compatible** (the
+  v5.9 relative-scale contract is intact).
+
+### Added — TPE-Bench + controls (WS-B / WS-V)
+- `benchmarks/position_effect/` — TPE-Bench: a **sealed, SHA-locked** held-out-chromosome track + baseline
+  leaderboard (cassette-only / durability head / PEN-EXPRESS factored), submission harness. Leave-one-cell-type-out
+  transfer track scaffolded + **data-gated** (no fabricated transfer number).
+- `pen_stack/validate/{expr_controls,known_biology_expr,heldout_celltype_expr}.py` — label-shuffle→chance control,
+  H3K9me3-heterochromatin→silencing recovery, the data-gated transfer harness.
+- `tests/unit/test_ws_pe.py` — CI-safe (synthetic planted signal); the real-TRIP claim runs on a checkout, skips in CI.
+
+### Honesty
+- Public data **cannot** flip expression to ✅ (the v6.5 wall) — v6.7 ships the learned+calibrated upgrade + the
+  benchmark + the honest data-gating, not a manufactured checkmark. Cross-cell-type transfer needs the additional
+  human datasets (a data-acquisition step), reported as such. Wet-lab validation omitted by scope.
+
 ## [6.6.0] - 2026-06-16 - License-clean provenance (COSMIC → CancerMine)
 
 **MINOR — provenance refactor, no new science, no capability lost.** The shipped artifact now sources the

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.6.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.6.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,58 @@ 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*
+independent validation (ρ=0.12 vs Damdindorj 2014), with an interval the code itself labelled "**NOT a trained
+conformal interval**." v6.7 replaces it — **wrapping, not rebuilding** the digital twin:
+
+- **A learned cassette × context position-effect model** (`pen_stack/twin/position_effect.py`) — factored and
+  decomposable (`f_cassette` + `g_context`), trained on the **real TRIP supervision** (Akhtar 2013; GEO
+  GSE49806/49807). On chromosome-blocked CV it **beats the v3.x durability head** on expression (ρ **0.428 →
+  0.469**, paired-bootstrap CI excludes 0) and matches it on silencing — reported honestly, with the separability
+  result (additive `f_cassette + g_context` suffices at this N).
+- **Stage H is now trained-conformal.** The model ships a split-conformal calibration (`ConformalRegressor`,
+  chromosome-Mondrian, OOD-widened): **held-out coverage 0.885 vs 0.90 nominal** — the named gap, closed. When a
+  chromatin context is supplied, `predict_outcome` serves the calibrated interval + `p_silenced` + OOD tier; with
+  no context (or no artifact) it falls back to the heuristic — **backward compatible**.
+- **TPE-Bench** (`benchmarks/position_effect/`) — the held-out benchmark the expression capability never had: a
+  **sealed, SHA-locked** held-out-chromosome split + a baseline leaderboard (cassette-only / durability head /
+  PEN-EXPRESS). A leave-one-**cell-type**-out transfer track is scaffolded and **honestly data-gated** until the
+  additional human datasets (PatchMPRA / MPIRE / lentiMPRA / Leemans) are fetched — **no transfer number is
+  fabricated**. Controls: label-shuffle → chance; known-biology recovery (H3K9me3 ↑ → silencing ↑).
+
+The honest limit (the v6.5 wall, restated): public data alone cannot flip expression to ✅ — that needs measured
+outcome data at a power the literature does not provide. v6.7 ships the learned+calibrated upgrade + the
+benchmark; the green checkmark stays earned, not manufactured. See [docs/position_effect.md](docs/position_effect.md)
+and [docs/tpe_bench.md](docs/tpe_bench.md).
+
 ## What is new in v6.4 — Live Oracles (the foundation models actually execute)
 
 The foundation-model oracles now **run for real**, not just defer: **ViennaRNA** (in-process), **AlphaGenome**
@@ -976,18 +1028,6 @@ independently verified.
 - **Grounded services** - every quantitative answer comes from a validated tool call (never a language
   model); the living database never auto-edits the atlas; clinical directives are refused.
 
-## Papers and phases
-
-| # | Title | Phase | Status |
-|---|---|---|---|
-| 1 (flagship) | The Writable Genome: a predictive, writer-aware atlas of safe & durable insertion sites | 1 | complete |
-| 2 (platform) | PEN-STACK: unified open infrastructure for non-destructive genome writing | 2 | complete |
-| 3 (capstone) | The Write Planner: end-to-end inverse design of genomic writes | 3 | complete |
-| 4 (beachhead) | Genome-wide off-target prediction for RNA-guided bridge recombinases | 1.5 | complete |
-| M1 (v3.1) | Writable Genome hardened: strong baselines, AlphaGenome sequence + 3D structural-risk axis | v3.1 B,C,D,F | complete |
-| M2 (v3.1) | The Genome-Writing Bench + PEN-Agent: the writing-side benchmark and a grounded agent | v3.1 E | complete |
-| M3 (v3.1) | Multiplex translocation-risk + bridge-RNA guide QC | v3.1 G | complete |
-
 The v3.1 cycle (workstreams A-H) is recorded in `CHANGELOG.md`, `docs/positioning.md`, and the SHA-locked
 `prereg/ws_*.yaml`; preprint drafts are in `manuscripts/`.
 

{pen_stack-6.6.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.6.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,58 @@ 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*
+independent validation (ρ=0.12 vs Damdindorj 2014), with an interval the code itself labelled "**NOT a trained
+conformal interval**." v6.7 replaces it — **wrapping, not rebuilding** the digital twin:
+
+- **A learned cassette × context position-effect model** (`pen_stack/twin/position_effect.py`) — factored and
+  decomposable (`f_cassette` + `g_context`), trained on the **real TRIP supervision** (Akhtar 2013; GEO
+  GSE49806/49807). On chromosome-blocked CV it **beats the v3.x durability head** on expression (ρ **0.428 →
+  0.469**, paired-bootstrap CI excludes 0) and matches it on silencing — reported honestly, with the separability
+  result (additive `f_cassette + g_context` suffices at this N).
+- **Stage H is now trained-conformal.** The model ships a split-conformal calibration (`ConformalRegressor`,
+  chromosome-Mondrian, OOD-widened): **held-out coverage 0.885 vs 0.90 nominal** — the named gap, closed. When a
+  chromatin context is supplied, `predict_outcome` serves the calibrated interval + `p_silenced` + OOD tier; with
+  no context (or no artifact) it falls back to the heuristic — **backward compatible**.
+- **TPE-Bench** (`benchmarks/position_effect/`) — the held-out benchmark the expression capability never had: a
+  **sealed, SHA-locked** held-out-chromosome split + a baseline leaderboard (cassette-only / durability head /
+  PEN-EXPRESS). A leave-one-**cell-type**-out transfer track is scaffolded and **honestly data-gated** until the
+  additional human datasets (PatchMPRA / MPIRE / lentiMPRA / Leemans) are fetched — **no transfer number is
+  fabricated**. Controls: label-shuffle → chance; known-biology recovery (H3K9me3 ↑ → silencing ↑).
+
+The honest limit (the v6.5 wall, restated): public data alone cannot flip expression to ✅ — that needs measured
+outcome data at a power the literature does not provide. v6.7 ships the learned+calibrated upgrade + the
+benchmark; the green checkmark stays earned, not manufactured. See [docs/position_effect.md](docs/position_effect.md)
+and [docs/tpe_bench.md](docs/tpe_bench.md).
+
 ## What is new in v6.4 — Live Oracles (the foundation models actually execute)
 
 The foundation-model oracles now **run for real**, not just defer: **ViennaRNA** (in-process), **AlphaGenome**
@@ -901,18 +953,6 @@ independently verified.
 - **Grounded services** - every quantitative answer comes from a validated tool call (never a language
   model); the living database never auto-edits the atlas; clinical directives are refused.
 
-## Papers and phases
-
-| # | Title | Phase | Status |
-|---|---|---|---|
-| 1 (flagship) | The Writable Genome: a predictive, writer-aware atlas of safe & durable insertion sites | 1 | complete |
-| 2 (platform) | PEN-STACK: unified open infrastructure for non-destructive genome writing | 2 | complete |
-| 3 (capstone) | The Write Planner: end-to-end inverse design of genomic writes | 3 | complete |
-| 4 (beachhead) | Genome-wide off-target prediction for RNA-guided bridge recombinases | 1.5 | complete |
-| M1 (v3.1) | Writable Genome hardened: strong baselines, AlphaGenome sequence + 3D structural-risk axis | v3.1 B,C,D,F | complete |
-| M2 (v3.1) | The Genome-Writing Bench + PEN-Agent: the writing-side benchmark and a grounded agent | v3.1 E | complete |
-| M3 (v3.1) | Multiplex translocation-risk + bridge-RNA guide QC | v3.1 G | complete |
-
 The v3.1 cycle (workstreams A-H) is recorded in `CHANGELOG.md`, `docs/positioning.md`, and the SHA-locked
 `prereg/ws_*.yaml`; preprint drafts are in `manuscripts/`.
 

pen_stack-6.8.0/benchmarks/position_effect/README.md

@@ -0,0 +1,60 @@
+# TPE-Bench — the Position-Effect / Expression track
+
+The **expression** capability of PEN-STACK never had a held-out benchmark. TPE-Bench is the position-effect
+track for the [Genome-Writing Challenge](../genome_writing_challenge/) (v6.7 PEN-EXPRESS): given a genomic
+**chromatin context** + **cassette**, predict the **integrated-reporter expression** (and silencing) — scored on
+a **sealed held-out split** whose labels the submitter never sees.
+
+## Why
+
+Position-effect (where an integrated cassette lands → how strongly/durably it expresses) is the writing-relevant
+quantity no safe-harbour resource predicts. TRIP (Akhtar 2013) supervises it directly. TPE-Bench seals a held-out
+split and anchors a baseline leaderboard, so others can build *to* a calibrated expression predictor.
+
+## Tracks
+
+| Track | Status | What is held out | Metric |
+|---|---|---|---|
+| `chrom_holdout` | **LIVE** | whole chromosomes (`chr2, chr5, chr14, chrX`), frozen + SHA-locked in `split.json` | Spearman ρ (expression) + AUROC (silenced) |
+| `celltype_holdout` | **DATA-GATED** | leave-one-cell-type-out (the headline transfer track) | — |
+
+`celltype_holdout` is the headline cross-cell-type transfer test. With a single available position-effect cell
+type (mESC) it reports `data_gated` **honestly** and activates once PatchMPRA / MPIRE / lentiMPRA / Leemans are
+fetched — **no transfer number is fabricated** until then.
+
+## Baseline leaderboard (sealed `chrom_holdout`, n_test = 2257)
+
+| Predictor | Expression ρ | Silenced AUROC |
+|---|---|---|
+| cassette-only (f_cassette) | 0.178 | — |
+| context-only (v3.x durability head) | 0.431 | 0.660 |
+| **PEN-EXPRESS factored (f_cassette + g_context)** | **0.475** | 0.660 |
+
+The factored model's gain is on **expression** (the cassette term lifts ρ 0.431 → 0.475 on the sealed test); the
+silenced classifier matches the durability head (the silencing question is chromatin-driven — reported honestly,
+not inflated). See `../../out/position_effect_report.json` for the full CV report + bootstrap CIs.
+
+## How to submit
+
+```python
+from benchmarks.position_effect.harness import Submission, evaluate
+
+def my_predict(public_input: dict):
+    # public_input = {task_id, family, cassette, chromatin_features:{H3K27ac,...}, instructions}; label hidden
+    return {"expression": 0.0, "p_silenced": 0.5}   # return your prediction (abstain-safe)
+
+print(evaluate(Submission(name="my-model", predict_fn=my_predict)))
+```
+
+Reference baselines: `python -c "from benchmarks.position_effect.harness import baseline_leaderboard as b; print(b())"`.
+
+## Rules
+
+- **Sealed + SHA-locked.** `split.json` (held-out chromosomes) is frozen and checksummed (`SHA256SUMS`) before
+  model selection — verify with `sha256sum -c SHA256SUMS`.
+- **No circular labels.** The label is the **measured** TRIP expression, never a submitter claim.
+- **Leakage-controlled.** Held out by whole chromosome (nearby integrations share chromatin).
+- **Honest data-gating.** The transfer track abstains until ≥2 cell types exist; no fabricated number.
+- **Deterministic.** PEN-EXPRESS anchors the leaderboard.
+
+Data: TRIP (Akhtar et al., *Cell* 2013; GEO GSE49806/GSE49807; trip.nki.nl). License: see `DATA_LICENSES.md`.

pen_stack-6.8.0/benchmarks/position_effect/SHA256SUMS

@@ -0,0 +1 @@
+2fc12cbf28531e68f6e25586da1d84003eeb6a098c9015998ce03f518546bc8a  split.json

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/position_effect_data.md

@@ -0,0 +1,36 @@
+# Data card — position-effect supervision (v6.7 PEN-EXPRESS)
+
+The unified table behind Stage H (`pen_stack/twin/data/position_effect.py`). One row = one integrated reporter /
+element measurement. Schema: `dataset, organism, cell_type, chrom, pos, cassette, expression_raw, expression_z,
+silenced, <chromatin features>`. `expression_z` is z-scored within (dataset × cassette).
+
+## Dataset registry (verified accessions — 2026-06-19 verification pass)
+
+| Dataset | Citation | DOI | Accession | Cell types | Status in v6.7 |
+|---|---|---|---|---|---|
+| **TRIP** | Akhtar et al., *Cell* 2013 | 10.1016/j.cell.2013.07.018 | GEO **GSE49806** (tetO) + **GSE49807** (mPGK); trip.nki.nl | mESC | **LIVE** (n=11,433) |
+| PatchMPRA | Maricque, Chaudhari & Cohen, *Nat Biotechnol* 2019 | 10.1038/nbt.4285 | GEO (per paper) | mESC | registered, data-gated |
+| MPIRE | Hong et al., *Nat Commun* 2024 | 10.1038/s41467-024-52599-6 | GEO **GSE223403**; github.com/claricehong/MPIRE_insulators | K562 | registered, data-gated |
+| lentiMPRA | Agarwal et al., *Nature* **639**:411–420 (2025) | 10.1038/s41586-024-08430-9 | ENCODE + GEO; bioRxiv 2023.03.05.531189 | HepG2, K562, WTC11 | registered, data-gated |
+| Leemans | Leemans et al., *Cell* 2019 | 10.1016/j.cell.2019.03.009 | GEO (per paper); van Steensel lab | K562 | registered, data-gated |
+
+> The bioRxiv id `2023.03.05.531189` is **lentiMPRA's** (Agarwal → *Nature* 2025), not e2MPRA/ccMPRA — corrected
+> in the 2026-06-19 citation verification pass.
+
+## TRIP (the LIVE supervision)
+
+- **What:** thousands of identical reporters integrated in parallel across the mESC genome; each row is a genomic
+  position with normalized expression → the position effect on an integrated cassette (the writing-relevant quantity).
+- **Columns used:** `chrom, pos, promoter` (cassette: tetO 10,903 / mPGK 530), `expression` (log2, −13…+9),
+  `silenced` (low-expression tail, 25%), + 5 chromatin marks (H3K27ac, H3K4me1, H3K4me3, H3K9me3, H3K27me3).
+- **Provenance:** same `trip_with_chromatin.parquet` the v3.x durability head trains on (regenerated by
+  `pen_stack/data/ingest_trip.py` + chromatin extraction).
+- **License:** TRIP data is from a public GEO deposit (Akhtar 2013); see `DATA_LICENSES.md`. Raw data is gitignored
+  (`data/external/`), pulled from the VM for local runs; the shipped wheel carries the loaders + accessions, not the data.
+
+## Honest limits
+
+- **Mouse, single cell type.** TRIP is mESC. The model learns `chromatin → expression` (never a coordinate), so it
+  *applies* to a human epigenome — but the cross-cell-type **transfer** is unproven until ≥2 cell types are unified.
+  Until then the transfer track is **data-gated** (no fabricated number).
+- **Reporter-based** (GFP-class), relative not absolute. Titer / % of normal stay known-unknowns.

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/position_effect.md

@@ -0,0 +1,57 @@
+# Stage H — the learned, trained-conformal position-effect model (v6.7 PEN-EXPRESS)
+
+Stage H predicts how strongly an integrated cassette expresses in its **chromatin context** (the position effect).
+Through v6.6 this was a closed-form **heuristic** with a heuristic ±0.20 band that the code itself labelled *"NOT
+a trained conformal interval"*, and which **failed** independent validation (ρ=0.12 vs Damdindorj 2014). v6.7
+replaces the model behind Stage H with a **learned, decomposable, trained-conformal** one — wrapping the digital
+twin, not rebuilding it.
+
+## The model
+
+`pen_stack/twin/position_effect.py::PositionEffectModel` is **factored and decomposable**:
+
+```
+E_raw  ≈  f_cassette(cassette)            # the cassette's intrinsic strength (per-cassette mean)
+       +  g_context(chromatin features)    # the position effect — a LightGBM on local chromatin
+       (+ h_interaction, reported)         # does the context function differ by cassette? (separability)
+```
+
+`g_context` is supervised on the residual `E_raw − f_cassette`, so it learns the *position* effect on a scale
+comparable across cassettes. A `silenced` classifier shares the chromatin features. The model is wrapped with the
+**existing** `wgenome.uncertainty.ConformalRegressor` (chromosome-Mondrian split-conformal) and `wgenome.ood.OODDetector`
+— so a prediction is a **calibrated interval that widens out of distribution**.
+
+## Results (real, on TRIP supervision — Akhtar 2013, GEO GSE49806/49807, mESC, n=11,433)
+
+Chromosome-blocked GroupKFold; paired bootstrap 95% CIs. *Every number is from a real CV run — no fabrication.*
+
+| Metric | cassette-only | context-only (v3.x durability head) | **PEN-EXPRESS factored** | Δ vs head (CI) |
+|---|---|---|---|---|
+| Expression Spearman ρ | 0.032 | 0.427 | **0.469** | +0.041 [0.036, 0.046] ✅ excludes 0 |
+| Silenced AUROC | — | 0.647 | 0.651 | +0.004 [0.001, 0.007] ✅ excludes 0 |
+
+- **Gate G-M passed:** the factored model beats the durability head (CI excludes 0) → it serves behind Stage H.
+- **Separability:** interaction adds **−0.002** R² → *additive `f_cassette + g_context` suffices at this N*
+  (reported honestly; the cassette term lifts expression, the silencing question is chromatin-driven).
+- **Trained-conformal (the named gap, closed):** split-conformal (α=0.10) → **held-out coverage 0.885 vs 0.90
+  nominal** (within tolerance), qhat=5.50 on the log2 scale. Coverage is measured on a **half-chromosome held-out**
+  split, not on the calibration set.
+
+## Stage H integration (`twin/outcome.py`)
+
+`predict_outcome(design, cell_state)` now:
+- **With a chromatin context** (`design["chromatin_features"]`) **and the model artifact present** → serves the
+  learned **trained-conformal** interval + `p_silenced` + OOD tier in a `position_effect` block; `stage_h_mode =
+  "learned_trained_conformal"`.
+- **Without a context (or artifact)** → the closed-form heuristic band, exactly as before — **backward compatible**
+  (the v5.9 relative-scale contract and all prior tests are intact).
+
+## Honest limits
+
+- **Single-context supervision.** TRIP is mESC. The cross-cell-type **transfer** claim is **data-gated** — see
+  [tpe_bench.md](tpe_bench.md); no transfer number is fabricated until PatchMPRA/MPIRE/lentiMPRA/Leemans are fetched.
+- **Public data cannot earn the ✅** (the v6.5 wall). v6.7 ships the learned+calibrated upgrade + the benchmark, not
+  a manufactured validated axis. Titer / absolute expression / phenotype stay **known-unknowns**.
+- The model artifact (`models/position_effect.pkl`) is gitignored; regenerate it with
+  `python scripts/p1_build_position_effect.py` (the shipped calibration `configs/twin/position_effect_conformal.json`
+  is committed). Without the artifact, Stage H falls back to the heuristic.

pen_stack-6.8.0/docs/tpe_bench.md

@@ -0,0 +1,48 @@
+# TPE-Bench — the position-effect / expression benchmark (v6.7)
+
+The **expression** capability never had a held-out benchmark. TPE-Bench fills that gap as a track of the
+[Genome-Writing Challenge](../benchmarks/genome_writing_challenge/): given a genomic **chromatin context** +
+**cassette**, predict the **integrated-reporter expression** (and silencing), scored on a **sealed** split.
+
+Location: `benchmarks/position_effect/` (`harness.py`, `split.json`, `SHA256SUMS`, `README.md`).
+
+## Two tracks
+
+| Track | Status | Held out | Metric |
+|---|---|---|---|
+| `chrom_holdout` | **LIVE** | whole chromosomes `chr2, chr5, chr14, chrX` (frozen + SHA-locked) | Spearman ρ + AUROC |
+| `celltype_holdout` | **DATA-GATED** | leave-one-cell-type-out (the headline transfer test) | — |
+
+`celltype_holdout` is the cross-cell-type transfer test. With one available position-effect cell type (mESC) it
+returns `data_gated` **honestly** and activates once PatchMPRA / MPIRE / lentiMPRA / Leemans are fetched — **no
+transfer number is fabricated**.
+
+## Baseline leaderboard (`chrom_holdout`, sealed, n_test = 2257)
+
+| Predictor | Expression ρ | Silenced AUROC |
+|---|---|---|
+| cassette-only | 0.178 | — |
+| context-only (v3.x durability head) | 0.431 | 0.660 |
+| **PEN-EXPRESS factored** | **0.475** | 0.660 |
+
+The factored model's gain is on **expression** (ρ 0.431 → 0.475 on the sealed held-out chromosomes); the silencing
+classifier matches the durability head (chromatin-driven) — reported honestly, not inflated.
+
+## Discipline
+
+- **Sealed + SHA-locked.** `split.json` is frozen and checksummed (`SHA256SUMS`) **before model selection**;
+  verify with `sha256sum -c benchmarks/position_effect/SHA256SUMS`.
+- **Non-circular labels.** The label is the **measured** TRIP expression, never a submitter claim.
+- **Leakage-controlled.** Held out by whole chromosome (nearby integrations share chromatin).
+- **Honest data-gating.** The transfer track abstains until ≥2 cell types exist.
+
+## Submit
+
+```python
+from benchmarks.position_effect.harness import Submission, evaluate
+def predict(pi):  # pi = {task_id, cassette, chromatin_features, instructions}; label hidden
+    return {"expression": 0.0, "p_silenced": 0.5}
+print(evaluate(Submission("my-model", predict)))
+```
+
+Reproduce the baselines: `python -c "from benchmarks.position_effect.harness import baseline_leaderboard as b; print(b())"`.