pen-stack 3.2.0__tar.gz → 3.3.0__tar.gz

{pen_stack-3.2.0 → pen_stack-3.3.0}/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [3.3.0] - 2026-06-09 - v3.3 release: the Verifier (a type checker for genome writes)
+
+v3.3 lifts the laws of genome writing into a versioned, machine-readable rule base and exposes a single
+`verify(design) -> Verdict` call (legal/illegal + named rule + calibrated confidence + scope) over Python,
+REST, and MCP. Workstreams WS-{R,D,ROUTE,V,BA}, each SHA-locked.
+
+### Added
+- **WS-R - rule base + solver.** `pen_stack/rules/{schema,evaluators,loader,solver}.py` + `configs/rules/*.yaml`
+  (9 rules across reachability/fold/payload/multiplex/delivery), each id/kind/mechanism/param/provenance(DOI)/
+  test. Evaluators delegate to the existing validated functions; a parity test proves no decision changed.
+  Legality and confidence are kept as distinct axes.
+- **WS-D - delivery palette.** `configs/delivery_vehicles.yaml` + `planner/delivery_vehicles.py`: 8 vehicles
+  (AAV single/dual, lentivirus, HDAd, HSV amplicon, LNP-mRNA, eVLP, electroporation) with capacity/integration/
+  cargo-form/DOIs; delivery rules (hard rejects + soft penalties + an immunogenicity-magnitude scope flag).
+- **WS-ROUTE - write-type router.** `planner/router.py` + `configs/write_types.yaml`: dispatches insertion/
+  excision/inversion/replacement/regulatory_rewrite/landing_pad_install/multiplex; unsupported types defer.
+- **WS-V - verification service.** `pen_stack/verify/{service,schema}.py`: `verify(design) -> Verdict`; `POST
+  /verify` + MCP `verify_write`; `docs/verify.md`. No fabrication (every number tool-sourced).
+- **WS-BA - bench v0.2.1 + agent.** T12 rule-grounded legality-with-explanation (verifier reason accuracy 1.0
+  vs ungrounded 0.0); the agent submits its plan to the verifier. Bench 12/12 available, planner beats baseline
+  8/8.
+- **Docs:** `docs/verify.md`, `docs/rules.md`, `docs/delivery.md`.
+
+### Changed
+- Version 3.2.0 -> 3.3.0 (pyproject, `__init__`, CITATION.cff). README "what is new in v3.3"; bench badge v0.2.1.
+
 ## [3.2.0] - 2026-06-08 - v3.2 release: a calibrated, self-aware co-scientist
 
 The v3.2 cycle makes the genome-writing funnel **trustworthy**: every value carries a calibrated confidence,
@@ -24,8 +50,11 @@ honest negatives. The Genome-Writing Bench bumps to **v0.2**.
 - **WS-MC - mechanistic filters.** A hard target-site/PAM/att-site reachability reject
   (`pen_stack.planner.target_site`, `configs/target_sites.yaml`; controls 9/9); vehicle-specific
   delivery-sequence penalties (`pen_stack.planner.delivery_constraints`); and an off-target **energetics**
-  model (`pen_stack.bridge.offtarget_energetics`) that beats the 0.77 baseline at held-out AUROC 0.88 (robust
-  over 5 seeds) and ships as the default ranker.
+  model (`pen_stack.bridge.offtarget_energetics`) that beats the 0.77 baseline at held-out AUROC 0.88 on the
+  comparable (core-disrupted) construction and ships as the default ranker. A reviewer-driven re-run
+  (`by_negative_construction`) shows that gap is mostly the core-penalisation artifact; with the core held
+  matched the non-core substitution-identity gain is real but modest (Δ≈0.04, 0.687 vs 0.646). Both AUROCs
+  carry a favourable-negative-set caveat (decoys derived from real off-targets; no non-recombining background).
 - **WS-BA - bench v0.2 + uncertainty-aware agent.** Four trust tasks (T8 calibration, T9 selective prediction,
   T10 OOD honesty, T11 out-of-scope refusal) contrasting the uncertainty-aware agent with an over-confident
   baseline (4/4); PEN-Agent emits confidence + epistemic status + abstains; UI surfaces them. Bench re-SHA-locked.

{pen_stack-3.2.0 → pen_stack-3.3.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 3.2.0
+version: 3.3.0
 date-released: 2026-06-01
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-3.2.0 → pen_stack-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 3.2.0
+Version: 3.3.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
@@ -89,12 +89,12 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![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-3.2.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-176%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-3.3.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-179%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
-[![Genome-Writing Bench v0.2](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.2-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.2](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.2.1-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -133,6 +133,24 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v3.3 — the Verifier (a type checker for genome writes)
+
+v3.3 lifts the *laws of genome writing* out of code into a **versioned, machine-readable rule base** and
+exposes a single **`verify(design) → Verdict`** call: submit a proposed write and get back *legal / illegal +
+the named violated rule + a calibrated confidence + a scope flag* — over Python, REST (`POST /verify`), and an
+MCP tool (`verify_write`) any AI agent can submit to. PEN-STACK becomes the layer that *checks* what the
+foundation models *generate*.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **R — rule base + solver** | the laws lifted into `configs/rules/*.yaml` (9 rules: reachability, fold, payload, multiplex, delivery), each id/kind/mechanism/param/**citation**/test; a solver returning legality + named reasons | a **parity test** proves the rules reproduce the prior in-code decisions (relocation, not behaviour change); positives legal, negatives rejected by the **correct named rule** |
+| **D — delivery palette** | the AAV-only assumption replaced by an **8-vehicle palette** (AAV single/dual, lentivirus, HDAd ~35 kb, HSV amplicon >100 kb, LNP-mRNA, eVLP, electroporation) with capacity/integration/cargo-form/DOIs | hard rejects (cargo>capacity, RNP-into-DNA-only-vehicle, non-integrating-goal+integrating-vehicle); immunogenicity *magnitude* declared out-of-scope, never predicted |
+| **ROUTE — write-type router** | the fixed insertion chain becomes one sub-graph of a router over insertion / excision / inversion / replacement / regulatory-rewrite / landing-pad / multiplex | each type routes to its rule sub-graph; unsupported/ambiguous types **defer**, never guess |
+| **V — verification service** | `verify(design) → Verdict` over Python/REST/MCP; legality (rules) + confidence (v3.2 L4) + scope, kept as **distinct axes** | every Verdict carries legality + (confidence ∨ abstention) + scope; **no fabrication** (every number tool-sourced) |
+| **BA — bench + agent** | Bench **v0.2.1** adds **T12 rule-grounded legality-with-explanation**; the agent submits its own plan to the verifier | verifier verdict+reason accuracy **1.0**; an ungrounded judge cannot cite a rule (0.0) — the verifier uniquely supplies grounded reasons; no-fabrication intact |
+
+See `docs/verify.md`, `docs/rules.md`, `docs/delivery.md`.
+
 ## What is new in v3.2 — a calibrated, self-aware co-scientist
 
 v3.2 makes the genome-writing funnel **trustworthy**: every value the funnel returns now carries a calibrated
@@ -143,9 +161,9 @@ each number* and *where the edge of its knowledge is*. Every workstream is pre-r
 
 | Workstream | What it adds | Honest headline result |
 |---|---|---|
-| **UQ — calibrated uncertainty + OOD** | conformal prediction intervals / sets over the existing heads (no retraining), an out-of-distribution detector, and selective prediction | durability **expression interval covers 0.895** vs 0.90 nominal on held-out chromosomes (within tolerance); the silenced set over-covers (0.996) because the head is weak — honest; **risk-coverage: accuracy rises 0.739→0.930** as low-confidence predictions are abstained (the uncertainty is *useful*). OOD across human cell types is **weak** (K562→HSPC AUROC 0.72, K562→HepG2 0.65–0.73) — chromatin marks are conserved across cell types; reported as a heuristic signal, not a guarantee |
+| **UQ — calibrated uncertainty + OOD** | conformal prediction intervals / sets over the existing heads (no retraining), an out-of-distribution detector, and selective prediction | calibrated UQ is **useful on the expression axis**: the durability **expression interval covers 0.895** vs 0.90 nominal on held-out chromosomes (within tolerance) and **risk-coverage accuracy rises 0.739→0.930** under abstention. On the **silenced axis it is informative-in-name-only** at this N — the set covers 0.996 with mean size 1.93 of 2 (≈ the full label set), because the head is weak (we say so plainly). OOD fires strongly on a real **chromatin-state** shift (euchromatin→heterochromatin AUROC **0.98**) but is **weak across biological context** — K562→HSPC 0.72, K562→HepG2 0.65, even cross-species mESC→human **0.56** — because chromatin-mark distributions barely move across cell types/species; reported as a heuristic feature-space-novelty signal, not a guarantee |
 | **EP — epistemic scope** | a three-tier status (grounded-confident / grounded-extrapolating / not-computable) on every output, plus a known-unknowns registry + scope matcher | out-of-scope probes deferred **1.0**, in-scope false-defer **0.0** (zero fabrication); the no-fabrication hard gate still holds. The unknown funnel (structure→phenotype, in-vivo immunogenicity, long-term durability, epistasis, polygenic, germline) is made *legible*, not closed |
-| **MC — mechanistic filters** | a hard target-site/PAM/att-site reachability reject, vehicle-specific delivery-sequence penalties, and an off-target **energetics** model | positive+negative target-site controls 9/9 (a physically impossible writer–site pairing is rejected); **off-target energetics (position × substitution identity) beats the 0.77 baseline at held-out AUROC 0.88** (robust over 5 seeds) and ships as the default ranker |
+| **MC — mechanistic filters** | a hard target-site/PAM/att-site reachability reject, vehicle-specific delivery-sequence penalties, and an off-target **energetics** model | positive+negative target-site controls 9/9 (a physically impossible writer–site pairing is rejected); off-target **energetics beats the 0.77 baseline at AUROC 0.88** on the comparable (core-disrupted) construction and ships as the default ranker — but a reviewer-driven re-run shows that gap is *mostly the core-penalisation artifact*: with the core held matched, the non-core substitution-identity gain is real but **modest (Δ≈0.04: 0.687 vs 0.646)**; both AUROCs carry a favourable-negative-set caveat |
 | **BA — bench v0.2 + uncertainty-aware agent** | four trust tasks (T8 calibration, T9 selective prediction, T10 OOD honesty, T11 out-of-scope) + the agent emits confidence + epistemic status + abstains | the uncertainty-aware agent beats an over-confident baseline **4/4** on the trust tasks; the leaderboard now separates *trustworthy* agents, not just grounded ones |
 
 Optional: a thin **Gymnasium environment interface** (`pen_stack/env/`, `[env]` extra) for agent-developer
@@ -251,7 +269,7 @@ PEN-STACK is organised as **two reference layers + one engine + a services layer
   magnitude, rho approximately 0.30). A first-of-its-kind beachhead for a genuinely unoccupied gap, not a
   Nature-tier breakthrough; the Writable Genome (Paper 1) remains the flagship novelty.
 
-## The Genome-Writing Bench (v0.2, M2)
+## The Genome-Writing Bench (v0.2.1, M2)
 
 The first benchmark for the **writing** side of genome engineering - *where* to write, *what* writer to use,
 *how* to design the cargo, and *what off-target / structural risk* a write carries - complementing the many
@@ -321,6 +339,9 @@ pen-stack/
 │   │   ├── safety.py                 calibrated genotoxicity-risk model (chrom-block CV + baseline)
 │   │   ├── durability.py             conditional chromatin->expression model (TRIP-trained, transferable)
 │   │   ├── writability.py            decomposable safety x durability x reachability integration
+│   │   ├── uncertainty.py            v3.2 conformal intervals/sets over the heads (no retraining)
+│   │   ├── ood.py                    v3.2 out-of-distribution / extrapolation detector
+│   │   ├── structure3d.py            3D structural-risk axis (AlphaGenome contact-map deltas, 11 hijack loci)
 │   │   └── export_tracks.py          BigWig / BED atlas export
 │   ├── atlas/                        Writer Atlas + WT-KB + cross-link (Papers 1-2)
 │   │   ├── schema.py                 pydantic WriterEntry (enforces >=1 DOI per row)
@@ -333,29 +354,39 @@ pen-stack/
 │   ├── mech/                         mechanism classification at scale (audited 18-family whitelist v1.2.1)
 │   ├── score/                        re-grounded axes + therapeutic-readiness scoring
 │   ├── planner/                      Write Planner (Paper 3): optimize / cargo / cargo_polish / multiplex / pipeline
+│   │                                   + v3.2 target_site (hard PAM/att/core reject) / delivery_constraints
+│   │                                   + v3.3 router (write-type dispatch) / delivery_vehicles (8-vehicle palette)
 │   ├── bridge/                       bridge off-target engine (Paper 4): offtarget / fold_qc / guide_qc / pipeline / cli
+│   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails
+│   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
+│   ├── rules/                        v3.3 machine-readable rules engine (schema/evaluators/loader/solver) over configs/rules/*.yaml
+│   ├── verify/                       v3.3 verification service: verify(design) -> Verdict (legal+reasons+confidence+scope)
 │   ├── adapt/                        local recalibration / private-data adaptation behind a gate (v3.1, WS-F)
+│   ├── env/                          v3.2 optional Gymnasium interface (genome_writing_env; [env] extra)
 │   ├── monitor/                      PEN-MONITOR living database (Europe PMC)
 │   ├── rag/                          grounded, cited Q&A (hybrid LLM: Ollama primary, Nemotron fallback)
-│   ├── validate/                     benchmarks: blind_gsh_discovery / durability_baselines (B1+B2 with CIs) /
-│   │                                   seq_vs_measured / writer_recovery / within_locus_ranking / agent_eval /
-│   │                                   ungrounded_baseline (T7) / guide_qc_demo / adapt_demo
-│   ├── wgenome/structure3d.py        3D structural-risk axis (AlphaGenome contact-map deltas, 11 hijack loci)
+│   ├── validate/                     benchmarks: blind_gsh_discovery / durability_baselines / writer_recovery /
+│   │                                   within_locus_ranking / agent_eval / ungrounded_baseline (T7) / adapt_demo /
+│   │                                   v3.2 selective_prediction / uncertainty_eval / bench_trust_tasks (T8-T11) /
+│   │                                   out_of_scope_refusal / target_site_controls / offtarget_energetics_eval
 │   ├── data/                         ingestion (genome, chromatin, integration, TRIP, safety annotations)
 │   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask)
-│   ├── ui/app.py                     Streamlit web app (11 pages)
+│   ├── ui/app.py                     Streamlit web app (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
-├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.1 (tasks / harness / solvers / LEADERBOARD / SHAs)
+├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.2 (T1-T11; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
 ├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, ws_*_report)
-├── configs/                          pinned datasets + thresholds + curation (YAML; gsh_validated_heldout = 51-locus gold set)
-├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + locks)
-├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile)
+├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2: known_unknowns /
+│                                       target_sites / delivery_constraints
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2 ws_{uq,ep,mc,ba} + locks)
+├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile,
+│                                       v3.2 bridge_offtarget_energetics.json)
 ├── data/llm_bench_cache/             28 cached ungrounded-LLM transcripts (T7, offline/CI replay)
 ├── data/alphagenome_cache/           cached AlphaGenome predictions (tracks + contact maps; offline reproducibility)
 ├── tests/unit/                       unit + regression + blind-validation suite
-├── docs/                             mkdocs site (cards, tutorials, INFRA, DEPLOY, MCP)
+├── docs/                             mkdocs site (cards, tutorials, INFRA, DEPLOY, MCP);
+│                                       v3.2: uncertainty.md / scope.md / mechanistic_constraints.md / BACKLOG.md
 ├── docker/                           CUDA image + UI image + pinned requirements
 ├── tools/penctl.py                   laptop<->VM orchestrator (paramiko SSH/SFTP, Docker-only)
 ├── docker-compose.yml                one-command self-hostable platform
@@ -487,7 +518,7 @@ plan. Data releases are deposited on Zenodo (one per paper).
   author  = {Mahaboob Ali, Anees Ahmed},
   title   = {PEN-STACK: open infrastructure for genome writing (The Writable Genome)},
   year    = {2026},
-  version = {3.1.0},
+  version = {3.3.0},
   url     = {https://github.com/ahmedanees-m/pen-stack}
 }
 ```

{pen_stack-3.2.0 → pen_stack-3.3.0}/README.md

@@ -14,12 +14,12 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![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-3.2.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-176%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-3.3.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-179%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
-[![Genome-Writing Bench v0.2](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.2-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.2](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.2.1-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -58,6 +58,24 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v3.3 — the Verifier (a type checker for genome writes)
+
+v3.3 lifts the *laws of genome writing* out of code into a **versioned, machine-readable rule base** and
+exposes a single **`verify(design) → Verdict`** call: submit a proposed write and get back *legal / illegal +
+the named violated rule + a calibrated confidence + a scope flag* — over Python, REST (`POST /verify`), and an
+MCP tool (`verify_write`) any AI agent can submit to. PEN-STACK becomes the layer that *checks* what the
+foundation models *generate*.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **R — rule base + solver** | the laws lifted into `configs/rules/*.yaml` (9 rules: reachability, fold, payload, multiplex, delivery), each id/kind/mechanism/param/**citation**/test; a solver returning legality + named reasons | a **parity test** proves the rules reproduce the prior in-code decisions (relocation, not behaviour change); positives legal, negatives rejected by the **correct named rule** |
+| **D — delivery palette** | the AAV-only assumption replaced by an **8-vehicle palette** (AAV single/dual, lentivirus, HDAd ~35 kb, HSV amplicon >100 kb, LNP-mRNA, eVLP, electroporation) with capacity/integration/cargo-form/DOIs | hard rejects (cargo>capacity, RNP-into-DNA-only-vehicle, non-integrating-goal+integrating-vehicle); immunogenicity *magnitude* declared out-of-scope, never predicted |
+| **ROUTE — write-type router** | the fixed insertion chain becomes one sub-graph of a router over insertion / excision / inversion / replacement / regulatory-rewrite / landing-pad / multiplex | each type routes to its rule sub-graph; unsupported/ambiguous types **defer**, never guess |
+| **V — verification service** | `verify(design) → Verdict` over Python/REST/MCP; legality (rules) + confidence (v3.2 L4) + scope, kept as **distinct axes** | every Verdict carries legality + (confidence ∨ abstention) + scope; **no fabrication** (every number tool-sourced) |
+| **BA — bench + agent** | Bench **v0.2.1** adds **T12 rule-grounded legality-with-explanation**; the agent submits its own plan to the verifier | verifier verdict+reason accuracy **1.0**; an ungrounded judge cannot cite a rule (0.0) — the verifier uniquely supplies grounded reasons; no-fabrication intact |
+
+See `docs/verify.md`, `docs/rules.md`, `docs/delivery.md`.
+
 ## What is new in v3.2 — a calibrated, self-aware co-scientist
 
 v3.2 makes the genome-writing funnel **trustworthy**: every value the funnel returns now carries a calibrated
@@ -68,9 +86,9 @@ each number* and *where the edge of its knowledge is*. Every workstream is pre-r
 
 | Workstream | What it adds | Honest headline result |
 |---|---|---|
-| **UQ — calibrated uncertainty + OOD** | conformal prediction intervals / sets over the existing heads (no retraining), an out-of-distribution detector, and selective prediction | durability **expression interval covers 0.895** vs 0.90 nominal on held-out chromosomes (within tolerance); the silenced set over-covers (0.996) because the head is weak — honest; **risk-coverage: accuracy rises 0.739→0.930** as low-confidence predictions are abstained (the uncertainty is *useful*). OOD across human cell types is **weak** (K562→HSPC AUROC 0.72, K562→HepG2 0.65–0.73) — chromatin marks are conserved across cell types; reported as a heuristic signal, not a guarantee |
+| **UQ — calibrated uncertainty + OOD** | conformal prediction intervals / sets over the existing heads (no retraining), an out-of-distribution detector, and selective prediction | calibrated UQ is **useful on the expression axis**: the durability **expression interval covers 0.895** vs 0.90 nominal on held-out chromosomes (within tolerance) and **risk-coverage accuracy rises 0.739→0.930** under abstention. On the **silenced axis it is informative-in-name-only** at this N — the set covers 0.996 with mean size 1.93 of 2 (≈ the full label set), because the head is weak (we say so plainly). OOD fires strongly on a real **chromatin-state** shift (euchromatin→heterochromatin AUROC **0.98**) but is **weak across biological context** — K562→HSPC 0.72, K562→HepG2 0.65, even cross-species mESC→human **0.56** — because chromatin-mark distributions barely move across cell types/species; reported as a heuristic feature-space-novelty signal, not a guarantee |
 | **EP — epistemic scope** | a three-tier status (grounded-confident / grounded-extrapolating / not-computable) on every output, plus a known-unknowns registry + scope matcher | out-of-scope probes deferred **1.0**, in-scope false-defer **0.0** (zero fabrication); the no-fabrication hard gate still holds. The unknown funnel (structure→phenotype, in-vivo immunogenicity, long-term durability, epistasis, polygenic, germline) is made *legible*, not closed |
-| **MC — mechanistic filters** | a hard target-site/PAM/att-site reachability reject, vehicle-specific delivery-sequence penalties, and an off-target **energetics** model | positive+negative target-site controls 9/9 (a physically impossible writer–site pairing is rejected); **off-target energetics (position × substitution identity) beats the 0.77 baseline at held-out AUROC 0.88** (robust over 5 seeds) and ships as the default ranker |
+| **MC — mechanistic filters** | a hard target-site/PAM/att-site reachability reject, vehicle-specific delivery-sequence penalties, and an off-target **energetics** model | positive+negative target-site controls 9/9 (a physically impossible writer–site pairing is rejected); off-target **energetics beats the 0.77 baseline at AUROC 0.88** on the comparable (core-disrupted) construction and ships as the default ranker — but a reviewer-driven re-run shows that gap is *mostly the core-penalisation artifact*: with the core held matched, the non-core substitution-identity gain is real but **modest (Δ≈0.04: 0.687 vs 0.646)**; both AUROCs carry a favourable-negative-set caveat |
 | **BA — bench v0.2 + uncertainty-aware agent** | four trust tasks (T8 calibration, T9 selective prediction, T10 OOD honesty, T11 out-of-scope) + the agent emits confidence + epistemic status + abstains | the uncertainty-aware agent beats an over-confident baseline **4/4** on the trust tasks; the leaderboard now separates *trustworthy* agents, not just grounded ones |
 
 Optional: a thin **Gymnasium environment interface** (`pen_stack/env/`, `[env]` extra) for agent-developer
@@ -176,7 +194,7 @@ PEN-STACK is organised as **two reference layers + one engine + a services layer
   magnitude, rho approximately 0.30). A first-of-its-kind beachhead for a genuinely unoccupied gap, not a
   Nature-tier breakthrough; the Writable Genome (Paper 1) remains the flagship novelty.
 
-## The Genome-Writing Bench (v0.2, M2)
+## The Genome-Writing Bench (v0.2.1, M2)
 
 The first benchmark for the **writing** side of genome engineering - *where* to write, *what* writer to use,
 *how* to design the cargo, and *what off-target / structural risk* a write carries - complementing the many
@@ -246,6 +264,9 @@ pen-stack/
 │   │   ├── safety.py                 calibrated genotoxicity-risk model (chrom-block CV + baseline)
 │   │   ├── durability.py             conditional chromatin->expression model (TRIP-trained, transferable)
 │   │   ├── writability.py            decomposable safety x durability x reachability integration
+│   │   ├── uncertainty.py            v3.2 conformal intervals/sets over the heads (no retraining)
+│   │   ├── ood.py                    v3.2 out-of-distribution / extrapolation detector
+│   │   ├── structure3d.py            3D structural-risk axis (AlphaGenome contact-map deltas, 11 hijack loci)
 │   │   └── export_tracks.py          BigWig / BED atlas export
 │   ├── atlas/                        Writer Atlas + WT-KB + cross-link (Papers 1-2)
 │   │   ├── schema.py                 pydantic WriterEntry (enforces >=1 DOI per row)
@@ -258,29 +279,39 @@ pen-stack/
 │   ├── mech/                         mechanism classification at scale (audited 18-family whitelist v1.2.1)
 │   ├── score/                        re-grounded axes + therapeutic-readiness scoring
 │   ├── planner/                      Write Planner (Paper 3): optimize / cargo / cargo_polish / multiplex / pipeline
+│   │                                   + v3.2 target_site (hard PAM/att/core reject) / delivery_constraints
+│   │                                   + v3.3 router (write-type dispatch) / delivery_vehicles (8-vehicle palette)
 │   ├── bridge/                       bridge off-target engine (Paper 4): offtarget / fold_qc / guide_qc / pipeline / cli
+│   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails
+│   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
+│   ├── rules/                        v3.3 machine-readable rules engine (schema/evaluators/loader/solver) over configs/rules/*.yaml
+│   ├── verify/                       v3.3 verification service: verify(design) -> Verdict (legal+reasons+confidence+scope)
 │   ├── adapt/                        local recalibration / private-data adaptation behind a gate (v3.1, WS-F)
+│   ├── env/                          v3.2 optional Gymnasium interface (genome_writing_env; [env] extra)
 │   ├── monitor/                      PEN-MONITOR living database (Europe PMC)
 │   ├── rag/                          grounded, cited Q&A (hybrid LLM: Ollama primary, Nemotron fallback)
-│   ├── validate/                     benchmarks: blind_gsh_discovery / durability_baselines (B1+B2 with CIs) /
-│   │                                   seq_vs_measured / writer_recovery / within_locus_ranking / agent_eval /
-│   │                                   ungrounded_baseline (T7) / guide_qc_demo / adapt_demo
-│   ├── wgenome/structure3d.py        3D structural-risk axis (AlphaGenome contact-map deltas, 11 hijack loci)
+│   ├── validate/                     benchmarks: blind_gsh_discovery / durability_baselines / writer_recovery /
+│   │                                   within_locus_ranking / agent_eval / ungrounded_baseline (T7) / adapt_demo /
+│   │                                   v3.2 selective_prediction / uncertainty_eval / bench_trust_tasks (T8-T11) /
+│   │                                   out_of_scope_refusal / target_site_controls / offtarget_energetics_eval
 │   ├── data/                         ingestion (genome, chromatin, integration, TRIP, safety annotations)
 │   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask)
-│   ├── ui/app.py                     Streamlit web app (11 pages)
+│   ├── ui/app.py                     Streamlit web app (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
-├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.1 (tasks / harness / solvers / LEADERBOARD / SHAs)
+├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.2 (T1-T11; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
 ├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, ws_*_report)
-├── configs/                          pinned datasets + thresholds + curation (YAML; gsh_validated_heldout = 51-locus gold set)
-├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + locks)
-├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile)
+├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2: known_unknowns /
+│                                       target_sites / delivery_constraints
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2 ws_{uq,ep,mc,ba} + locks)
+├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile,
+│                                       v3.2 bridge_offtarget_energetics.json)
 ├── data/llm_bench_cache/             28 cached ungrounded-LLM transcripts (T7, offline/CI replay)
 ├── data/alphagenome_cache/           cached AlphaGenome predictions (tracks + contact maps; offline reproducibility)
 ├── tests/unit/                       unit + regression + blind-validation suite
-├── docs/                             mkdocs site (cards, tutorials, INFRA, DEPLOY, MCP)
+├── docs/                             mkdocs site (cards, tutorials, INFRA, DEPLOY, MCP);
+│                                       v3.2: uncertainty.md / scope.md / mechanistic_constraints.md / BACKLOG.md
 ├── docker/                           CUDA image + UI image + pinned requirements
 ├── tools/penctl.py                   laptop<->VM orchestrator (paramiko SSH/SFTP, Docker-only)
 ├── docker-compose.yml                one-command self-hostable platform
@@ -412,7 +443,7 @@ plan. Data releases are deposited on Zenodo (one per paper).
   author  = {Mahaboob Ali, Anees Ahmed},
   title   = {PEN-STACK: open infrastructure for genome writing (The Writable Genome)},
   year    = {2026},
-  version = {3.1.0},
+  version = {3.3.0},
   url     = {https://github.com/ahmedanees-m/pen-stack}
 }
 ```

{pen_stack-3.2.0 → pen_stack-3.3.0}/benchmarks/genome_writing_bench/LEADERBOARD.md

@@ -1,12 +1,12 @@
-# Genome-Writing Bench v0.2 - Leaderboard
+# Genome-Writing Bench v0.2.1 - Leaderboard
 
-Tasks: **11/11 available** in this run (unavailable = needs the Phase-1 atlas / Perry tables / an LLM, which run on the VM/local).
-Deterministic planner beats the naive baseline on **7/7** grounded tasks with a baseline.
+Tasks: **12/12 available** in this run (unavailable = needs the Phase-1 atlas / Perry tables / an LLM, which run on the VM/local).
+Deterministic planner beats the naive baseline on **8/8** grounded tasks with a baseline.
 
 | Solver | Tasks scored | Beats naive | No-fabrication | Note |
 |---|---|---|---|---|
-| deterministic_planner | 11 | 7/7 | n/a (deterministic) | validated planning tools - the reference |
-| naive_baseline | 7 | - | n/a (deterministic) | safety-only / prevalence / Hamming baselines |
+| deterministic_planner | 12 | 8/8 | n/a (deterministic) | validated planning tools - the reference |
+| naive_baseline | 8 | - | n/a (deterministic) | safety-only / prevalence / Hamming baselines |
 
 ## Per-task results
 | Task | Family | Available | Planner | Naive baseline | Gate |
@@ -22,6 +22,7 @@ Deterministic planner beats the naive baseline on **7/7** grounded tasks with a
 | selective_prediction_usefulness | T9_selective_pred | True | 0.9300087489063867 | 0.7393510014869238 | - |
 | ood_honesty | T10_ood_honesty | True | 1.0 | 0.0 | - |
 | out_of_scope_refusal | T11_out_of_scope | True | 1.0 | 0.0 | - |
+| rule_grounded_legality | T12_rule_legality | True | 1.0 | 0.0 | - |
 
 ## Trust tasks (T8-T11) - calibration + scope-awareness separate *trustworthy* agents
 Each contrasts the **uncertainty-aware** agent (conformal coverage, selective prediction, OOD flagging, out-of-scope deferral) with an **over-confident** baseline (an uncalibrated interval, no abstention, never flags OOD, no scope layer). The over-confident agent is the realistic failure mode a calibrated co-scientist must beat.

{pen_stack-3.2.0 → pen_stack-3.3.0}/benchmarks/genome_writing_bench/SHA256SUMS

@@ -1,4 +1,4 @@
-ca392477b92ce3ec97304ea1391cd49e29d5a94c4b8adb95c9303da306da5a0b  benchmarks/genome_writing_bench/tasks.yaml
+1242bdc091219e42af7b74ca8b397190af60a52d7be3d0e4048d5a0fe5ca191c  benchmarks/genome_writing_bench/tasks.yaml
 51a1f8acfd49c243f545588f62c48720b1438758ae17b09e097aa7a5c2156cf0  configs/gsh_validated_heldout.yaml
 758817c1e46c7db10f7f942316663367c5f297cac0cf2f59947a90638a256718  data/writer_panel.csv
 865b18ff23d140c3df6f3b5f25398581ebdfe3534e1cecf6f512afb540ab5ede  data/gsh_matched_controls.parquet

{pen_stack-3.2.0 → pen_stack-3.3.0}/benchmarks/genome_writing_bench/tasks.yaml

@@ -8,8 +8,8 @@
 # A task names a `scorer` (module.function in pen_stack.validate / pen_stack.bridge) and a `metric` key to
 # read from its report. Solvers (deterministic planner, naive baseline, LLM agent) are compared on the same
 # tasks; a solver that cannot ground a number must refuse, not invent (no-fabrication is a hard gate).
-version: "0.2"
-prepared: "2026-06-08"
+version: "0.2.1"
+prepared: "2026-06-09"
 
 taxonomy:
   T1_site_selection:    "rank genomic sites for writability; recover validated safe-harbours from controls"
@@ -25,6 +25,8 @@ taxonomy:
   T9_selective_pred:    "risk-coverage: does abstaining on low-confidence predictions improve accuracy?"
   T10_ood_honesty:      "on OOD queries, flag extrapolation rather than answer over-confidently"
   T11_out_of_scope:     "defer known-unknown (out-of-scope) probes instead of fabricating a value"
+  # v0.2.1 (v3.3): the verifier supplies rule-grounded legality + a NAMED, CITED reason.
+  T12_rule_legality:    "judge a design legal/illegal AND name the violated rule (vs an ungrounded judge that cannot cite a rule)"
 
 tasks:
   - id: site_selection_blind_gsh
@@ -144,3 +146,15 @@ tasks:
       agent that answers them (deferral 0.0); plus 0.0 false-defer on in-scope questions"
     circular: false
     note: "deterministic (pure-logic, CI-safe); the scope layer is what prevents the out-of-scope fabrication."
+
+  - id: rule_grounded_legality
+    family: T12_rule_legality
+    scorer: "pen_stack.validate.bench_rule_tasks:run"
+    metric: "verifier_reason_accuracy"
+    baseline_metric: "ungrounded_baseline_reason_accuracy"
+    higher_is_better: true
+    ground_truth: "frozen panel of legal + illegal designs; legality defined by documented physical mechanism
+      (not the verifier's own output); each illegal case has an expected violated rule id"
+    circular: false
+    note: "v3.3 verifier: legal/illegal + NAMED, CITED reason. The ungrounded baseline cannot cite a rule
+      (reason accuracy 0 by construction) — the verifier uniquely supplies correct grounded reasons."

pen_stack-3.3.0/configs/delivery_vehicles.yaml

@@ -0,0 +1,105 @@
+# PEN-STACK v3.3 — Delivery vehicle palette (WS-D / North-Star §4). The substrate must score and constrain
+# the WHOLE delivery palette, not just dual-AAV. Each row: cargo capacity, integration, division dependence,
+# immunogenicity PRIOR (qualitative; MAGNITUDE is a known-unknown — never predicted), re-dosability, tropism,
+# ex/in-vivo, compatible cargo form {DNA, mRNA, RNP}, and >=1 DOI. Values cited to 2026 sources.
+# `constraint_key` maps to configs/delivery_constraints.yaml for the sequence-level scan.
+
+version: "1.0"
+
+vehicles:
+  AAV_single:
+    cargo_capacity_bp: 4700
+    integrating: false            # episomal
+    division_dependent: false
+    immunogenicity_prior: "moderate-high; pre-existing NAbs exclude 30-60% of patients"
+    re_dosable: false
+    tropism: "serotype-dependent (liver, muscle, CNS, retina)"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: AAV
+    dois: ["10.1038/s41573-019-0012-9"]
+
+  AAV_dual:
+    cargo_capacity_bp: 9000       # split across 2 capsids (~9 kb); efficiency drops sharply
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "as AAV; split lowers efficiency"
+    re_dosable: false
+    tropism: "serotype-dependent"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: AAV
+    dois: ["10.1089/hum.2017.084"]
+
+  lentivirus:
+    cargo_capacity_bp: 8000
+    integrating: true             # semi-random integration
+    division_dependent: false     # integrates in non-dividing too; strong in dividing
+    immunogenicity_prior: "moderate"
+    re_dosable: false
+    tropism: "broad (VSV-G pseudotyped)"
+    ex_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: lentiviral
+    dois: ["10.1126/science.1233151"]
+
+  helper_dependent_adenovirus:
+    cargo_capacity_bp: 35000      # "gutless" HDAd, up to ~35 kb
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "high (innate + adaptive)"
+    re_dosable: false
+    tropism: "liver and others"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: plasmid
+    dois: ["10.1089/hum.2009.213"]
+
+  hsv_amplicon:
+    cargo_capacity_bp: 100000     # >100 kb
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "high; neurotropic"
+    re_dosable: false
+    tropism: "neurotropic (CNS)"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: plasmid
+    dois: ["10.1038/sj.gt.3302529"]
+
+  lnp_mrna:
+    cargo_capacity_bp: 15000      # large RNA payload (mRNA encoding the writer/RNP)
+    integrating: false            # transient
+    division_dependent: false
+    immunogenicity_prior: "low/transient"
+    re_dosable: true
+    tropism: "liver-tropic by default"
+    in_vivo: true
+    compatible_cargo_form: [mRNA, RNP]
+    constraint_key: lnp_mrna
+    dois: ["10.1038/s41578-021-00358-0"]
+
+  evlp:
+    cargo_capacity_bp: null       # RNP payload (not a DNA packaging limit)
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "low (transient, no DNA)"
+    re_dosable: true
+    tropism: "engineerable (T cells, retina)"
+    in_vivo: true
+    ex_vivo: true
+    compatible_cargo_form: [RNP]
+    constraint_key: evlp
+    dois: ["10.1016/j.cell.2022.03.045"]
+
+  electroporation:
+    cargo_capacity_bp: null       # physical; no packaging limit
+    integrating: false            # depends on cargo
+    division_dependent: false
+    immunogenicity_prior: "n/a (ex vivo)"
+    re_dosable: false
+    tropism: "n/a (ex vivo)"
+    ex_vivo: true
+    compatible_cargo_form: [DNA, mRNA, RNP]
+    constraint_key: electroporation
+    dois: ["10.1038/nprot.2014.157"]

pen_stack-3.3.0/configs/rules/delivery.yaml

@@ -0,0 +1,40 @@
+# Delivery compatibility (WS-D; new in v3.3, reads configs/delivery_vehicles.yaml). Replaces the single
+# dual-AAV rule with vehicle-aware hard rejects + soft penalties + an explicit out-of-scope flag.
+category: delivery
+rules:
+  - id: delivery.cargo_form_compatible
+    kind: hard_reject
+    category: delivery
+    mechanism: "the writer's output form (DNA cargo / mRNA / RNP) must be carriable by the chosen vehicle (e.g. an RNP-only payload cannot ride a DNA-only AAV; an mRNA/RNP rides LNP or eVLP)"
+    evaluator: delivery_cargo_form
+    param: {}
+    provenance: { doi: ["10.1038/s41578-021-00358-0", "10.1016/j.cell.2022.03.045"], note: "cargo-form column in configs/delivery_vehicles.yaml" }
+    test_ref: "tests/unit/test_ws_r.py::test_delivery_controls"
+    scope: "form compatibility is computable; precise tropism is not"
+  - id: delivery.no_integration_constraint
+    kind: hard_reject
+    category: delivery
+    mechanism: "if the goal forbids genomic integration, an integrating vehicle (e.g. lentivirus) is illegal"
+    evaluator: delivery_no_integration
+    param: {}
+    provenance: { doi: ["10.1126/science.1233151"], note: "integration column in configs/delivery_vehicles.yaml" }
+    test_ref: "tests/unit/test_ws_r.py::test_delivery_controls"
+    scope: "integration status is a documented vehicle property"
+  - id: delivery.sequence_constraints
+    kind: soft_penalty
+    category: delivery
+    mechanism: "vehicle-specific construct hazards (lentiviral internal poly(A), AAV inverted-repeat/homopolymer, recombinogenic direct repeats, GC extremes) lower titre/yield"
+    evaluator: delivery_sequence_constraints
+    param: {}
+    provenance: { doi: ["10.1089/hum.2017.084"], note: "v3.2 MC2 delivery_constraints scan" }
+    test_ref: "tests/unit/test_ws_r.py::test_delivery_controls"
+    scope: "labeled heuristic, directional; not a titre predictor"
+  - id: delivery.immunogenicity_magnitude
+    kind: scope_flag
+    category: delivery
+    mechanism: "the MAGNITUDE of immunogenicity and the precise in-vivo tropism of a vehicle are not modeled"
+    evaluator: delivery_immunogenicity_scope
+    param: {}
+    provenance: { note: "known-unknown; surfaced, never predicted (Invariant 2)" }
+    test_ref: "tests/unit/test_ws_r.py::test_delivery_controls"
+    scope: "declared out of scope; never a hard reject dressed as physics"

pen_stack-3.3.0/configs/rules/fold.yaml

@@ -0,0 +1,15 @@
+# Fold / cross-loop legality (relocated from bridge/fold_qc.py). A bridge RNA whose target- and donor-binding
+# loops are complementary can self/cross-recombine instead of engaging the genome — a measured failure mode.
+category: fold
+rules:
+  - id: fold.cross_loop_complementarity
+    kind: soft_penalty
+    category: fold
+    mechanism: "bridge-RNA target/donor binding loops must not be mutually (or self-) complementary above threshold, or they recombine with each other (TBL-DBL / self cross-loop)"
+    evaluator: fold_cross_loop
+    param: { cross_loop_threshold: 0.6 }
+    provenance:
+      doi: ["10.1126/science.adz0276", "10.1038/s41586-024-07552-4"]
+      note: "v3.1.5 fold_qc cross-loop screen (ViennaRNA fold optional)"
+    test_ref: "tests/unit/test_ws_r.py::test_fold_controls"
+    scope: "crude antiparallel-complementarity screen; sequence-level, not a full co-fold simulation"

pen_stack-3.3.0/configs/rules/multiplex.yaml

@@ -0,0 +1,13 @@
+# Multiplex translocation safety (relocated from planner/multiplex.py). Concurrent DSBs at multiple loci can
+# mis-join into translocations; DSB-free programmable recombinases (bridge/seek/PE) carry ~zero by construction.
+category: multiplex
+rules:
+  - id: multiplex.translocation_risk
+    kind: soft_penalty
+    category: multiplex
+    mechanism: "in a multi-edit plan, concurrent double-strand breaks at different loci can mis-join into a translocation; risk rises with cut count / cut probability / proximity, and is ~zero for DSB-free writers"
+    evaluator: multiplex_translocation
+    param: { risk_threshold: 0.2 }
+    provenance: { doi: ["10.1038/nbt.3198"], note: "v3.1 WS-G1 pairwise translocation screen" }
+    test_ref: "tests/unit/test_ws_r.py::test_multiplex_controls"
+    scope: "interpretable pairwise screen, not a calibrated translocation-rate predictor"

pen_stack-3.3.0/configs/rules/payload.yaml

@@ -0,0 +1,22 @@
+# Payload arithmetic (relocated from planner/delivery*.py). Cargo must fit the chosen vehicle's packaging
+# capacity; AAV beyond a single capsid needs split/dual delivery (sharp efficiency loss).
+category: payload
+rules:
+  - id: payload.cargo_within_capacity
+    kind: hard_reject
+    category: payload
+    mechanism: "cargo size (bp) must not exceed the delivery vehicle's packaging capacity"
+    evaluator: payload_capacity
+    param: {}
+    provenance: { doi: ["10.1038/s41573-019-0012-9"], note: "vehicle capacities in configs/delivery_vehicles.yaml" }
+    test_ref: "tests/unit/test_ws_r.py::test_payload_controls"
+    scope: "capacity is a hard packaging limit; efficiency near the limit is a separate soft penalty"
+  - id: payload.split_aav_efficiency
+    kind: soft_penalty
+    category: payload
+    mechanism: "an AAV cargo above a single capsid (~4.7 kb) requires split/dual AAV, which drops efficiency sharply"
+    evaluator: split_aav_penalty
+    param: { single_aav_cap_bp: 4700 }
+    provenance: { doi: ["10.1089/hum.2017.084"], note: "dual-AAV split efficiency" }
+    test_ref: "tests/unit/test_ws_r.py::test_payload_controls"
+    scope: "directional efficiency flag, not a titre prediction"