pen-stack 5.8.0__tar.gz → 5.9.0__tar.gz

{pen_stack-5.8.0 → pen_stack-5.9.0}/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [5.9.0] - 2026-06-11 - v5.9 release: The Digital Twin (calibrated outcome prediction)
+
+**Closed-Loop arc, Cycle 3 of 7.** The missing layer: *what does the cell do after the write?* — predicted with
+calibrated honesty. The twin computes what mechanism allows, adds an in-distribution virtual-cell estimate
+(OOD-gated), screens immune outcome from the v5.6 profile, and is explicit about its boundary at phenotype.
+Workstreams WS-{VCELL,MECH,OUTCOME,CAL}, SHA-locked.
+
+### Added
+- **WS-VCELL** — `pen_stack/oracles/vcell.py` + scope cards `state`/`scgpt`: `predict_response(cell_state,
+  perturbation, model)` wraps **Arc STATE** / **scGPT** under the v4.0 `OracleResult` contract. A
+  perturbation-response prediction is a **candidate**, OOD-gated (a context outside the documented envelope →
+  `extrapolating`), cached/deferred (value `None` when absent — never fabricated). Encodes the field's own result
+  (Arc Virtual Cell Challenge): perturbation models don't yet consistently beat naive baselines.
+- **WS-MECH** — `pen_stack/twin/mechanistic.py`: `cassette_expression` = `promoter_strength × copy_number ×
+  accessibility` (closed-form steady state); assumptions + scope flags attached; **physics where computable, NOT
+  a phenotype**.
+- **WS-OUTCOME** — `pen_stack/twin/outcome.py`: `predict_outcome(design, cell_state)` fuses mechanism +
+  in-distribution virtual-cell response + the v5.6 immune profile into one prediction with an interval that
+  **widens under OOD**, an immune-outcome dimension, and an explicit **phenotype / in-vivo-magnitude boundary**.
+  In-vivo durability may be **conditioned on the grounded pre-existing-NAb axis** (no invented immune numbers);
+  `output_kind="candidate"`.
+- **WS-CAL** — `pen_stack/twin/calibrate.py`: `calibrate_outcome(...)` reports calibration **two-sided** — interval
+  coverage + a bootstrap CI on the MAE gap vs a naive mean baseline; the twin "beats" naive **only when the CI
+  excludes zero**, else the negative is reported verbatim; abstains at `N < 3`.
+- **WS-BENCH** — bench **v0.3.5**: new `outcome_prediction` hard-gate task (`pen_stack/validate/outcome_prediction.py`)
+  — the gate is the twin's **honesty properties** (two-sided calibration + OOD widening + immune dimension +
+  phenotype out-of-scope), which an overconfident predictor fails by construction; twin-vs-naive skill is reported
+  informationally on a labelled synthetic stream (no public perturbation-outcome calibration set exists).
+- Docs: `docs/digital_twin.md`; prereg `ws_{vcell,mech,outcome,twincal}` + SHA locks; deposit `phase_5.9/`.
+
+### Notes
+- The twin is a **hypothesis engine, not an oracle of truth**: predictions are candidates with intervals;
+  phenotype, in-vivo behaviour, immunogenicity *magnitude*, and durability beyond the computable stay
+  scope-flagged. The interval is a heuristic band, **not** a trained conformal interval (no public outcome
+  calibration set). Immune-outcome is sourced from v5.6, never invented.
+
 ## [5.8.0] - 2026-06-11 - v5.8 release: The Live Agent & Generative Designer
 
 **Closed-Loop arc, Cycle 2 of 7.** PEN-STACK turns from a *checker* into a grounded *designer*: it generates

{pen_stack-5.8.0 → pen_stack-5.9.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: 5.8.0
+version: 5.9.0
 date-released: 2026-06-11
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-5.8.0 → pen_stack-5.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.8.0
+Version: 5.9.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,12 +90,12 @@ 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-5.8.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-317%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-5.9.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-324%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.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.4-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.5-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -134,6 +134,25 @@ 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 v5.9 — The Digital Twin (calibrated outcome prediction)
+
+v5.9 (**Closed-Loop arc, Cycle 3 of 7**) adds the missing layer — *what does the cell do after the write?* —
+predicted with calibrated honesty. The twin computes what mechanism allows, adds an in-distribution virtual-cell
+estimate (OOD-gated), screens immune outcome from the v5.6 profile, and is explicit about its boundary at
+phenotype. A **hypothesis engine, not an oracle of truth**.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **VCELL** | `oracles/vcell.py` + scope cards `state`/`scgpt` | Arc STATE / scGPT under the OracleResult contract; perturbation prediction is a **candidate**, **OOD-gated**, deferred value never fabricated |
+| **MECH** | `twin/mechanistic.py` | `cassette_expression` = promoter × copy × accessibility (closed form); **physics where computable, NOT a phenotype** |
+| **OUTCOME** | `twin/outcome.py` | fuses mechanism + in-dist VC + v5.6 immune; interval **widens under OOD**; in-vivo durability conditioned on the **grounded NAb axis**; phenotype/in-vivo-magnitude scope-flagged |
+| **CAL** | `twin/calibrate.py` | calibration reported **two-sided** (coverage + MAE-gap-vs-naive bootstrap CI); beats naive **only if CI excludes 0**, else the negative is reported |
+| **BENCH** | bench **v0.3.5** `outcome_prediction` hard gate | gate = the twin's honesty properties (two-sided cal + OOD widening + immune dim + phenotype out-of-scope); an overconfident predictor fails by construction |
+
+The interval is a **heuristic band, not a trained conformal interval** (no public perturbation-outcome calibration
+set; Arc's Virtual Cell Challenge shows models don't yet consistently beat naive baselines). See
+[`docs/digital_twin.md`](docs/digital_twin.md) and `prereg/ws_{vcell,mech,outcome,twincal}.yaml`.
+
 ## What is new in v5.8 — The Live Agent & Generative Designer
 
 v5.8 (**Closed-Loop arc, Cycle 2 of 7**) turns PEN-STACK from a *checker* into a grounded *designer*: it
@@ -599,11 +618,12 @@ pen-stack/
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails; v5.0 co_scientist + cite (multi-strategy, self-critique, cited rationale, scope ledger); v5.8 orchestrator_live (live, cache-replayable, generate→oracle→verify→refine)
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
 │   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
-│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache; v5.2-5.6 delivery-immunology scope cards (delivery_genotoxicity/capsid_epitope/innate_sensing/seroprevalence/antipeg)
+│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache; v5.2-5.6 delivery-immunology scope cards (delivery_genotoxicity/capsid_epitope/innate_sensing/seroprevalence/antipeg); v5.9 vcell (Arc STATE/scGPT, OOD-gated, output_kind=candidate)
 │   ├── 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; v4.0 writer_critique; v5.1 delivery_profile; v5.6 immune_profile per-axis vector; v5.7 safety SafetyVerdict)
 │   ├── safety/                       v5.7 the Guardian: biosecurity/dual-use gate (registry/screen/policy/gate/audit/redteam); runs first in verify(); refuse short-circuits; tamper-evident audit
 │   ├── design/                       v5.8 generative designer: space (candidate_space) / generate (verifier-as-discriminator; hazardous+illegal discarded) / pareto (frontier w/ grounded v5.6 immune axis)
+│   ├── twin/                         v5.9 digital twin: mechanistic (cassette expression, closed-form) / outcome (fuse mech+vcell+v5.6 immune; OOD widens interval; phenotype-bounded) / calibrate (honest two-sided)
 │   ├── adapt/                        local recalibration / private-data adaptation behind a gate (v3.1, WS-F)
 │   ├── env/                          v3.4 full Gymnasium environment over router+verifier (genome_writing_env + policies; [env] extra)
 │   ├── monitor/                      PEN-MONITOR living database (Europe PMC)
@@ -615,12 +635,13 @@ pen-stack/
 │   │                                   v3.3 bench_rule_tasks (T12) / v3.4 bench_writetype_tasks + bench_adversarial_tasks (T13-16) + outcome_calibration /
 │   │                                   v5.6 immune_calibration (proxy-vs-observed; labels each axis validated-or-proxy, two-sided) /
 │   │                                   v5.7 safety_screening (the Guardian hard-gate: benign 0-false-refusal · hazards refused/escalated · evasions never clear) /
-│   │                                   v5.8 generative_design (verifier-as-discriminator hard-gate: hazardous+illegal discarded; survivors calibrated+immune; grounded-immune Pareto)
+│   │                                   v5.8 generative_design (verifier-as-discriminator hard-gate: hazardous+illegal discarded; survivors calibrated+immune; grounded-immune Pareto) /
+│   │                                   v5.9 outcome_prediction (digital-twin hard-gate: two-sided calibration + OOD widening + immune dim + phenotype out-of-scope)
 │   ├── 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 (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
-├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.3.4 (T1-T16 + co_scientist + safety_screening + generative_design; tasks / harness / solvers / LEADERBOARD / SHAs)
+├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.3.5 (T1-T16 + co_scientist + safety_screening + generative_design + outcome_prediction; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
 ├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, p52/p53 delivery-immunology oracle builds, ws_*_report)
 ├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2 known_unknowns /
@@ -629,10 +650,10 @@ pen-stack/
 │                                       seroprevalence / antipeg + oracles/scope_cards (+ v5.6 known_unknowns:
 │                                       cd4_mhcii_help / preexisting_capsid_tcell / complement_carpa);
 │                                       v5.7 safety/{hazard_registry,policy,probes} (Guardian; function/family/taxon-level only)
-├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v5.8 ws_{uq,ep,mc,ba,
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v5.9 ws_{uq,ep,mc,ba,
 │                                       r,v,route,env,bench,cal,o,wv,atlas,graph,mon,ct,plan,crit,cite,immune,
 │                                       genotox,epitope,innate,seroprev,peg,calib,profile,screen,policy,redteam,
-│                                       gen,pareto,orch} + SHA256 locks)
+│                                       gen,pareto,orch,vcell,mech,outcome,twincal} + SHA256 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)

{pen_stack-5.8.0 → pen_stack-5.9.0}/README.md

@@ -15,12 +15,12 @@ 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-5.8.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-317%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-5.9.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-324%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.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.4-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.5-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -59,6 +59,25 @@ 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 v5.9 — The Digital Twin (calibrated outcome prediction)
+
+v5.9 (**Closed-Loop arc, Cycle 3 of 7**) adds the missing layer — *what does the cell do after the write?* —
+predicted with calibrated honesty. The twin computes what mechanism allows, adds an in-distribution virtual-cell
+estimate (OOD-gated), screens immune outcome from the v5.6 profile, and is explicit about its boundary at
+phenotype. A **hypothesis engine, not an oracle of truth**.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **VCELL** | `oracles/vcell.py` + scope cards `state`/`scgpt` | Arc STATE / scGPT under the OracleResult contract; perturbation prediction is a **candidate**, **OOD-gated**, deferred value never fabricated |
+| **MECH** | `twin/mechanistic.py` | `cassette_expression` = promoter × copy × accessibility (closed form); **physics where computable, NOT a phenotype** |
+| **OUTCOME** | `twin/outcome.py` | fuses mechanism + in-dist VC + v5.6 immune; interval **widens under OOD**; in-vivo durability conditioned on the **grounded NAb axis**; phenotype/in-vivo-magnitude scope-flagged |
+| **CAL** | `twin/calibrate.py` | calibration reported **two-sided** (coverage + MAE-gap-vs-naive bootstrap CI); beats naive **only if CI excludes 0**, else the negative is reported |
+| **BENCH** | bench **v0.3.5** `outcome_prediction` hard gate | gate = the twin's honesty properties (two-sided cal + OOD widening + immune dim + phenotype out-of-scope); an overconfident predictor fails by construction |
+
+The interval is a **heuristic band, not a trained conformal interval** (no public perturbation-outcome calibration
+set; Arc's Virtual Cell Challenge shows models don't yet consistently beat naive baselines). See
+[`docs/digital_twin.md`](docs/digital_twin.md) and `prereg/ws_{vcell,mech,outcome,twincal}.yaml`.
+
 ## What is new in v5.8 — The Live Agent & Generative Designer
 
 v5.8 (**Closed-Loop arc, Cycle 2 of 7**) turns PEN-STACK from a *checker* into a grounded *designer*: it
@@ -524,11 +543,12 @@ pen-stack/
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails; v5.0 co_scientist + cite (multi-strategy, self-critique, cited rationale, scope ledger); v5.8 orchestrator_live (live, cache-replayable, generate→oracle→verify→refine)
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
 │   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
-│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache; v5.2-5.6 delivery-immunology scope cards (delivery_genotoxicity/capsid_epitope/innate_sensing/seroprevalence/antipeg)
+│   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache; v5.2-5.6 delivery-immunology scope cards (delivery_genotoxicity/capsid_epitope/innate_sensing/seroprevalence/antipeg); v5.9 vcell (Arc STATE/scGPT, OOD-gated, output_kind=candidate)
 │   ├── 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; v4.0 writer_critique; v5.1 delivery_profile; v5.6 immune_profile per-axis vector; v5.7 safety SafetyVerdict)
 │   ├── safety/                       v5.7 the Guardian: biosecurity/dual-use gate (registry/screen/policy/gate/audit/redteam); runs first in verify(); refuse short-circuits; tamper-evident audit
 │   ├── design/                       v5.8 generative designer: space (candidate_space) / generate (verifier-as-discriminator; hazardous+illegal discarded) / pareto (frontier w/ grounded v5.6 immune axis)
+│   ├── twin/                         v5.9 digital twin: mechanistic (cassette expression, closed-form) / outcome (fuse mech+vcell+v5.6 immune; OOD widens interval; phenotype-bounded) / calibrate (honest two-sided)
 │   ├── adapt/                        local recalibration / private-data adaptation behind a gate (v3.1, WS-F)
 │   ├── env/                          v3.4 full Gymnasium environment over router+verifier (genome_writing_env + policies; [env] extra)
 │   ├── monitor/                      PEN-MONITOR living database (Europe PMC)
@@ -540,12 +560,13 @@ pen-stack/
 │   │                                   v3.3 bench_rule_tasks (T12) / v3.4 bench_writetype_tasks + bench_adversarial_tasks (T13-16) + outcome_calibration /
 │   │                                   v5.6 immune_calibration (proxy-vs-observed; labels each axis validated-or-proxy, two-sided) /
 │   │                                   v5.7 safety_screening (the Guardian hard-gate: benign 0-false-refusal · hazards refused/escalated · evasions never clear) /
-│   │                                   v5.8 generative_design (verifier-as-discriminator hard-gate: hazardous+illegal discarded; survivors calibrated+immune; grounded-immune Pareto)
+│   │                                   v5.8 generative_design (verifier-as-discriminator hard-gate: hazardous+illegal discarded; survivors calibrated+immune; grounded-immune Pareto) /
+│   │                                   v5.9 outcome_prediction (digital-twin hard-gate: two-sided calibration + OOD widening + immune dim + phenotype out-of-scope)
 │   ├── 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 (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
-├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.3.4 (T1-T16 + co_scientist + safety_screening + generative_design; tasks / harness / solvers / LEADERBOARD / SHAs)
+├── benchmarks/genome_writing_bench/  Genome-Writing Bench v0.3.5 (T1-T16 + co_scientist + safety_screening + generative_design + outcome_prediction; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
 ├── scripts/                          reproducible pipeline drivers (p1_*, p2_*, p4_*, p52/p53 delivery-immunology oracle builds, ws_*_report)
 ├── configs/                          pinned datasets + thresholds + curation (YAML); v3.2 known_unknowns /
@@ -554,10 +575,10 @@ pen-stack/
 │                                       seroprevalence / antipeg + oracles/scope_cards (+ v5.6 known_unknowns:
 │                                       cd4_mhcii_help / preexisting_capsid_tcell / complement_carpa);
 │                                       v5.7 safety/{hazard_registry,policy,probes} (Guardian; function/family/taxon-level only)
-├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v5.8 ws_{uq,ep,mc,ba,
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v5.9 ws_{uq,ep,mc,ba,
 │                                       r,v,route,env,bench,cal,o,wv,atlas,graph,mon,ct,plan,crit,cite,immune,
 │                                       genotox,epitope,innate,seroprev,peg,calib,profile,screen,policy,redteam,
-│                                       gen,pareto,orch} + SHA256 locks)
+│                                       gen,pareto,orch,vcell,mech,outcome,twincal} + SHA256 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)

{pen_stack-5.8.0 → pen_stack-5.9.0}/benchmarks/genome_writing_bench/SHA256SUMS

@@ -1,4 +1,4 @@
-d5d306cdd81cb6f0c67e88de4741610da1898cdb7a2a097e6acfa9226b0c7024  benchmarks/genome_writing_bench/tasks.yaml
+8a88af94053456909a2a03561d721a97e82d012f867eaf1d632ff3518a2bf0d1  benchmarks/genome_writing_bench/tasks.yaml
 5ca511c6763b4e3703e8009031ff8dc385c2a99540e2731d875a9fbbb16f5ecd  configs/gsh_validated_heldout.yaml
 758817c1e46c7db10f7f942316663367c5f297cac0cf2f59947a90638a256718  data/writer_panel.csv
 865b18ff23d140c3df6f3b5f25398581ebdfe3534e1cecf6f512afb540ab5ede  data/gsh_matched_controls.parquet

{pen_stack-5.8.0 → pen_stack-5.9.0}/benchmarks/genome_writing_bench/tasks.yaml

@@ -8,7 +8,7 @@
 # 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.3.4"
+version: "0.3.5"
 prepared: "2026-06-11"
 
 taxonomy:
@@ -41,6 +41,8 @@ taxonomy:
   SF_safety_screening:  "screen a design for select-agent / pandemic-pathogen / controlled-toxin signatures: benign therapeutics pass (0 false refusals), hazards refused/escalated, AI-homolog + chimera + reframing evasions never `clear` (vs a no-safety baseline that clears everything)"
   # v0.3.4 (v5.8): the generative designer - verifier-as-discriminator over a mixed candidate pool.
   GD_generative_design: "generate candidate writing systems and keep ONLY legal+safe+calibrated+immune-profiled survivors (hazardous toxin payload + illegal oversize/form-incompatible designs DISCARDED), returning a Pareto frontier with a grounded immune-risk axis (vs an ungrounded generator that ships hazardous/illegal designs)"
+  # v0.3.5 (v5.9): the digital twin - calibrated, OOD-aware, immune-aware, phenotype-bounded outcome prediction.
+  OP_outcome_prediction: "predict a write's computable outcome with HONEST calibration (two-sided MAE-vs-naive with bootstrap CI), an interval that WIDENS under OOD, an immune-outcome dimension from v5.6, and phenotype out of scope (vs an overconfident predictor with a fixed narrow interval and no scope awareness)"
 
 tasks:
   - id: site_selection_blind_gsh
@@ -261,3 +263,20 @@ tasks:
     note: "v5.8 verifier-as-discriminator: the ungrounded generator returns the raw pool (ships hazardous +
       illegal designs) and fails by construction; the grounded designer discards them and returns calibrated,
       immune-profiled candidates on a Pareto frontier with a grounded immune-risk axis."
+
+  - id: outcome_prediction
+    family: OP_outcome_prediction
+    scorer: "pen_stack.validate.outcome_prediction:run"
+    metric: "twin_honest_and_calibrated"
+    baseline_metric: "overconfident_predictor_honest"
+    higher_is_better: true
+    hard_gate: true
+    gate_rule: "twin_honest_and_calibrated == True (calibration two-sided w/ CI AND OOD widens interval AND immune-outcome present AND phenotype out-of-scope)"
+    ground_truth: "structural honesty properties of the outcome prediction (two-sided calibration + OOD widening +
+      immune dimension from v5.6 + phenotype out-of-scope), NOT a beat-the-world claim - non-circular; twin-vs-naive
+      skill is reported informationally on a labelled synthetic stream because no public perturbation-outcome
+      calibration set exists (Arc Virtual Cell Challenge: models do not yet consistently beat naive baselines)"
+    circular: false
+    note: "v5.9 the digital twin: a trustworthy predictor is calibrated + OOD-aware + immune-aware + phenotype-
+      bounded; an overconfident predictor (fixed narrow interval, no OOD/scope awareness) fails the gate by
+      construction. Honest about what the field cannot yet do."

{pen_stack-5.8.0 → pen_stack-5.9.0}/configs/oracles/scope_cards.yaml

@@ -179,3 +179,26 @@ oracles:
     generalizes_to_unseen_loci: false
     license: "open (this work; Chen 10.1021/acs.analchem.6b03109, Yang&Lai 10.1002/wnan.1339,
       Armstrong 10.1002/cncr.22739, Kozma 10.1016/j.addr.2020.07.024)"
+
+  state:                          # v5.9 WS-VCELL: Arc STATE virtual-cell perturbation-response model
+    family: vcell
+    version: "state-2025"
+    output_kind: candidate        # a perturbation-response PREDICTION is a candidate/hypothesis, never a claim
+    valid_for: "IN-DISTRIBUTION single-gene / chemical / cytokine perturbation transcriptional-response estimates
+      in TRAINED human cell contexts (Arc STATE; ~70 contexts, 167M+100M cells)"
+    not_valid_for: "OUT-OF-DISTRIBUTION cell types / perturbations (Arc's own Virtual Cell Challenge result:
+      perturbation models do NOT yet consistently beat naive baselines -> OOD sets extrapolating=True); phenotype;
+      in-vivo behaviour; clinical endpoints"
+    generalizes_to_unseen_loci: false
+    license: "Arc Institute (github.com/ArcInstitute/state)"
+
+  scgpt:                          # v5.9 WS-VCELL: scGPT single-cell foundation model (perturbation prediction)
+    family: vcell
+    version: "scgpt-2024"
+    output_kind: candidate
+    valid_for: "IN-DISTRIBUTION genetic-perturbation transcriptional-response estimates within trained single-cell
+      contexts (scGPT; >33M cells)"
+    not_valid_for: "OOD cell types / perturbations (does not consistently beat naive baselines); phenotype; in-vivo;
+      absolute expression"
+    generalizes_to_unseen_loci: false
+    license: "MIT (github.com/bowang-lab/scGPT; Nature Methods 10.1038/s41592-024-02201-0)"

pen_stack-5.9.0/docs/digital_twin.md

@@ -0,0 +1,55 @@
+# The digital twin (v5.9)
+
+From v5.9, PEN-STACK can predict *what the cell does after the write* — calibrated, OOD-gated, and scope-bounded.
+It computes what mechanism allows, adds an in-distribution virtual-cell estimate, screens immune outcome from the
+v5.6 profile, and is honest about its boundary at phenotype. The twin is a **hypothesis engine, not an oracle of
+truth**.
+
+```python
+from pen_stack.twin import predict_outcome
+o = predict_outcome(design, cell_state="k562")
+o["predicted_outcome"]   # {relative_expression, vcell_response, units}
+o["interval"]            # heuristic band; WIDENS under OOD
+o["immune_outcome"]      # the v5.6 per-axis profile (sourced, not invented)
+o["scope_flags"]         # phenotype_not_modeled, in_vivo_magnitude_unknown, (vcell_OOD if extrapolating)
+```
+
+## Mechanism where computable (`pen_stack/twin/mechanistic.py`)
+
+`cassette_expression(design, chromatin_ctx)` = `promoter_strength × copy_number × accessibility` — a closed-form
+steady-state estimate. Assumptions (steady-state, no silencing, linear copy scaling) and scope flags
+(`episomal_durability_unknown`, `phenotype_not_modeled`) travel with the output. It is **physics where
+computable, never a phenotype**.
+
+## Virtual-cell oracle, OOD-gated (`pen_stack/oracles/vcell.py`)
+
+`predict_response(cell_state, perturbation, model="state")` wraps Arc **STATE** / **scGPT** under the v4.0
+`OracleResult` contract. A perturbation-response prediction is a **candidate**, never a claim; a cell context or
+perturbation outside the documented validity envelope sets `extrapolating=True` / `in_scope=False`. The backend is
+deferred/cache-replayed (value `None` when absent — never fabricated). This encodes the field's own result (Arc's
+Virtual Cell Challenge): **perturbation models do not yet consistently beat naive baselines** and do not
+generalize to unseen contexts.
+
+## Fused outcome (`pen_stack/twin/outcome.py`)
+
+`predict_outcome(design, cell_state)` fuses the computable mechanistic estimate (backbone) + an in-distribution
+virtual-cell response (when available) + the v5.6 immune profile. The interval **widens under OOD** rather than
+over-trusting an extrapolating model. For in-vivo vehicles, durability **may be conditioned on the grounded
+pre-existing-NAb axis** (no invented immune numbers). Phenotype and in-vivo magnitude stay scope-flagged.
+
+> The interval is a heuristic band, **not** a trained conformal interval — there is no public
+> perturbation-outcome calibration set. The twin says so.
+
+## Honest calibration (`pen_stack/twin/calibrate.py`)
+
+`calibrate_outcome(predictions, observations, intervals=…)` reports calibration **two-sided, whatever the shape**:
+interval coverage vs nominal, and a skill comparison against a naive mean baseline with a **bootstrap CI on the
+MAE gap**. The twin "beats" the baseline **only when the CI excludes zero** — otherwise the negative is reported
+verbatim. At `N < 3` it abstains honestly.
+
+## Honest scope
+
+The twin predicts what mechanism computes, what an in-distribution virtual-cell model supports, and what the v5.6
+immune profile screens — with calibrated intervals. It does **not** predict phenotype, in-vivo behaviour,
+immunogenicity *magnitude*, or durability beyond the computable; these stay scope-flagged. Perturbation prediction
+is an open problem; the twin is a calibrated hypothesis engine, honest where it is weak.

{pen_stack-5.8.0 → pen_stack-5.9.0}/pen_stack/__init__.py

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

pen_stack-5.9.0/pen_stack/oracles/vcell.py

@@ -0,0 +1,51 @@
+"""Virtual-cell outcome oracles (v5.9, WS-VCELL) — Arc STATE / scGPT under the v4.0 OracleResult contract.
+
+A perturbation-response prediction is a CANDIDATE (a hypothesis), never a claim. It is OOD-gated: a cell context
+or perturbation outside the model's documented validity envelope sets `extrapolating=True` / `in_scope=False`,
+because the field's own evidence (Arc's Virtual Cell Challenge) is that perturbation models do not yet
+consistently beat naive baselines and do not generalize to unseen contexts. Heavy backends run on-demand and are
+cached; absent → deferred / cache replay (the value may be None, never fabricated).
+"""
+from __future__ import annotations
+
+from pen_stack.oracles import build_result, cache_get
+from pen_stack.oracles.schema import OracleResult
+
+# documented in-distribution envelope (representative trained human cell contexts + perturbation kinds).
+_IN_DISTRIBUTION_CONTEXTS = {
+    "k562", "hepg2", "jurkat", "hek293", "hek293t", "h1_hesc", "h1", "a549", "thp1", "raw264",
+    "hela", "mcf7", "ipsc", "pbmc", "cd4_t", "cd8_t", "hspc",
+}
+_VALID_PERTURBATION_KINDS = {"genetic", "crispr", "knockout", "knockdown", "overexpression",
+                             "chemical", "drug", "cytokine"}
+
+
+def _normalize(s) -> str:
+    return str(s or "").strip().lower().replace("-", "").replace(" ", "")
+
+
+def in_distribution(cell_state: str, perturbation: dict) -> bool:
+    """True iff the cell context is a documented trained context AND the perturbation kind is supported."""
+    ctx_ok = _normalize(cell_state) in {_normalize(c) for c in _IN_DISTRIBUTION_CONTEXTS}
+    kind = _normalize(perturbation.get("kind") or perturbation.get("type"))
+    kind_ok = (not kind) or kind in {_normalize(k) for k in _VALID_PERTURBATION_KINDS}
+    return bool(ctx_ok and kind_ok)
+
+
+def predict_response(cell_state: str, perturbation: dict, *, model: str = "state",
+                     live: bool = False) -> OracleResult:
+    """Virtual-cell outcome oracle (Arc STATE / scGPT). OOD-gated: a context outside the scope card ->
+    `extrapolating`, never a confident claim. Cached/deferred when the backend is absent (replay is CI default)."""
+    extrap = not in_distribution(cell_state, perturbation)
+    inputs = {"cell_state": cell_state, "perturbation": perturbation, "live": bool(live)}
+    hit = cache_get(build_result("vcell", model, inputs=inputs).provenance.cache_key)
+    if hit is not None:
+        return build_result("vcell", model, inputs=inputs, value=hit.get("value"),
+                            native_uncertainty=hit.get("native_uncertainty"), available=True, cached=True,
+                            source="cache", extrapolating=extrap, in_scope=not extrap,
+                            note="replayed from committed oracle cache")
+    # backend not wired here -> deferred (value None), but the contract + OOD gate are real
+    return build_result("vcell", model, inputs=inputs, value=None, available=False,
+                        extrapolating=extrap, in_scope=not extrap,
+                        note=(f"{model} virtual-cell backend deferred; OOD={extrap}. "
+                              "Perturbation prediction does not yet consistently beat naive baselines (Arc VCC)."))

pen_stack-5.9.0/pen_stack/twin/__init__.py

@@ -0,0 +1,14 @@
+"""pen_stack.twin — the digital twin for genome writing (v5.9).
+
+A calibrated, scope-bounded write-outcome predictor: mechanism where computable (cassette expression), an
+in-distribution virtual-cell transcriptional-response estimate (OOD-gated), and an immune-outcome dimension
+sourced from the v5.6 profile — fused into one prediction with an interval that widens under OOD and an explicit
+boundary at phenotype. A hypothesis engine, honest where it is weak; never an oracle of truth.
+"""
+from __future__ import annotations
+
+from pen_stack.twin.calibrate import calibrate_outcome, interval_coverage
+from pen_stack.twin.mechanistic import cassette_expression
+from pen_stack.twin.outcome import predict_outcome
+
+__all__ = ["predict_outcome", "cassette_expression", "calibrate_outcome", "interval_coverage"]

pen_stack-5.9.0/pen_stack/twin/calibrate.py

@@ -0,0 +1,61 @@
+"""Twin calibration — honest, two-sided (v5.9, WS-CAL).
+
+Reports the twin's calibration on held-out (predicted, observed) outcomes WHATEVER the shape: interval coverage
+vs nominal, and a skill comparison against a NAIVE baseline (predict the mean) with a bootstrap CI on the MAE
+gap. A twin "beats" the baseline only when the CI excludes zero in its favour — otherwise the negative is
+reported verbatim. This mirrors the field's own result (Arc VCC): perturbation prediction does not yet
+consistently beat naive baselines, and the twin says so rather than hiding it.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def _mae(pred, obs) -> float:
+    return float(np.mean(np.abs(np.asarray(pred, float) - np.asarray(obs, float))))
+
+
+def _bootstrap_gap(twin_pred, naive_pred, obs, *, reps: int = 300, seed: int = 0) -> tuple[float, list[float]]:
+    """Bootstrap the MAE gap (naive - twin); positive => twin better. Returns mean gap + 95% CI."""
+    rng = np.random.default_rng(seed)
+    twin_pred, naive_pred, obs = map(lambda a: np.asarray(a, float), (twin_pred, naive_pred, obs))
+    n = len(obs)
+    gaps = []
+    for _ in range(reps):
+        idx = rng.integers(0, n, n)
+        gaps.append(_mae(naive_pred[idx], obs[idx]) - _mae(twin_pred[idx], obs[idx]))
+    lo, hi = np.percentile(gaps, [2.5, 97.5])
+    return float(np.mean(gaps)), [round(float(lo), 4), round(float(hi), 4)]
+
+
+def interval_coverage(intervals, obs) -> dict:
+    """Empirical coverage of the prediction intervals vs the observed outcomes."""
+    obs = np.asarray(obs, float)
+    covered = np.array([lo <= y <= hi for (lo, hi), y in zip(intervals, obs)])
+    return {"empirical_coverage": round(float(np.mean(covered)), 4), "n": int(len(obs))}
+
+
+def calibrate_outcome(predictions, observations, *, intervals=None, reps: int = 300, seed: int = 0) -> dict:
+    """Honest two-sided calibration of the twin against a naive mean baseline. Reports the MAE gap with a
+    bootstrap CI (beats-or-not), and interval coverage when intervals are supplied."""
+    pred = np.asarray(predictions, float)
+    obs = np.asarray(observations, float)
+    n = len(obs)
+    if n < 3:
+        return {"available": False, "n": n, "reason": "too few held-out outcomes to calibrate (honest)"}
+    naive = np.full(n, float(np.mean(obs)))
+    mae_twin, mae_naive = _mae(pred, obs), _mae(naive, obs)
+    gap, ci = _bootstrap_gap(pred, naive, obs, reps=reps, seed=seed)
+    beats = bool(ci[0] > 0)                                     # CI excludes 0 in the twin's favour
+    out = {
+        "available": True, "n": n,
+        "mae_twin": round(mae_twin, 4), "mae_naive": round(mae_naive, 4),
+        "mae_gap_naive_minus_twin": round(gap, 4), "gap_ci": ci,
+        "beats_naive_baseline": beats,
+        "honest_note": ("twin beats naive (CI excludes 0)" if beats
+                        else "twin does NOT beat naive on this data (CI spans 0) - reported, not hidden"),
+        "no_fabrication": True,
+    }
+    if intervals is not None:
+        out["interval_coverage"] = interval_coverage(intervals, obs)
+    return out

pen_stack-5.9.0/pen_stack/twin/mechanistic.py

@@ -0,0 +1,37 @@
+"""Mechanistic simulation where computable (v5.9, WS-MECH).
+
+Computes the consequences MECHANISM allows — steady-state cassette expression in a chromatin context — and
+nothing more. Physics where computable; explicitly NOT a phenotype, NOT in-vivo behaviour, NOT durability beyond
+the steady state. Assumptions and scope flags travel with every output.
+"""
+from __future__ import annotations
+
+# documented relative promoter strengths (ordinal, dimensionless) — a curated default palette.
+_PROMOTER_STRENGTH = {"ef1a": 1.0, "cag": 1.0, "cmv": 0.9, "pgk": 0.6, "ubc": 0.5,
+                      "endogenous": 0.4, "minimal": 0.2}
+
+
+def _promoter_strength(design: dict) -> float:
+    p = design.get("promoter")
+    if isinstance(p, dict) and p.get("strength") is not None:
+        return float(p["strength"])
+    if isinstance(p, str):
+        return _PROMOTER_STRENGTH.get(p.strip().lower(), 0.5)
+    return _PROMOTER_STRENGTH.get(str(p or "").strip().lower(), 0.5)
+
+
+def cassette_expression(design: dict, chromatin_ctx: dict) -> dict:
+    """Computable steady-state relative expression from an integrated cassette:
+    promoter_strength x copy_number x accessibility. Physics where computable; NOT a phenotype."""
+    p = _promoter_strength(design)
+    cn = float(design.get("copy_number", 1) or 1)
+    acc = float(chromatin_ctx.get("accessibility", 1.0) if chromatin_ctx else 1.0)
+    rel = p * cn * acc
+    return {
+        "relative_expression": round(rel, 4),
+        "units": "relative (dimensionless)",
+        "assumptions": ["steady-state", "no silencing modeled", "linear copy scaling"],
+        "scope_flags": ["episomal_durability_unknown", "phenotype_not_modeled"],
+        "provenance": {"promoter_strength": p, "copy_number": cn, "accessibility": acc,
+                       "source": "twin.mechanistic (closed-form steady state)"},
+    }