pen-stack 5.13.0__tar.gz → 6.1.0__tar.gz

{pen_stack-5.13.0 → pen_stack-6.1.0}/CHANGELOG.md

@@ -3,6 +3,55 @@
 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.1.0] - 2026-06-11 - v6.1: The AI Integration Surface
+
+**Post-1.0 adoption surface for AI builders.** Not new capability — the *introspectable, documented, dependable*
+contract that lets an external agent discover what PEN-STACK offers **and what it refuses to answer**. MINOR
+release on the stable 6.0 API. Workstreams WS-{MANIFEST,OPENAPI,MCP} + examples, SHA-locked.
+
+### Added
+- **WS-MANIFEST** *(the differentiator)* — `pen_stack/api/manifest.py`: `capability_manifest()` (machine-readable:
+  the stable tools, inputs/outputs, all `fabricates=False`, guarantees, stability) and **`scope_manifest()`**
+  (machine-readable: the **known-unknowns** registry + every **oracle scope card** — what PEN-STACK *refuses* to
+  answer). Generated from the live registry/scope cards (never hand-written); internal matcher fields not leaked.
+- **WS-OPENAPI** — `pen_stack/server/api.py`: `GET /capabilities` + `GET /scope` + `POST /verify /safety /immune
+  /generate /predict /suggest /session`; FastAPI auto-generates the **OpenAPI 3.1** spec at `/openapi.json`.
+- **WS-MCP** — `pen_stack/agent/mcp_server.py`: the self-describing **resources** `pen-stack://capabilities` +
+  `pen-stack://scope`, plus the engine tools (`safety_screen`, `immune_profile`, `generate_designs`,
+  `predict_outcome`, `suggest_experiment`, `co_scientist_session`). A hazardous design returns a **structured
+  refusal** an agent branches on.
+- **WS-EXAMPLE** — runnable golden path: `examples/external_agent.py` (REST: discover scope → submit → branch on
+  safety/legality), `examples/mcp_client.py` (MCP), `examples/agent_tools.py` (framework-agnostic tool specs built
+  **from the live manifest** + an in-process dispatcher to the validated engine).
+- Docs: `docs/integrations.md` rewritten as "Integrate PEN-STACK in your AI" (the four guarantees + the scope
+  contract + REST/MCP/framework quickstarts); prereg `ws_{manifest,openapi,mcp}` + SHA locks; deposit `phase_6.1/`.
+
+### Notes
+- **Scope is data, not a disclaimer.** The scope manifest makes the honesty machinery itself an API — the thing
+  that makes trustworthy autonomy something another system can build on. This cycle lowers the barrier to
+  adoption; it does not, by itself, create it — outreach + a real result remain the standing bottleneck. No new
+  science or validation; contracts versioned + deprecation-policed under the 1.0 commitment.
+
+## [6.0.0] - 2026-06-11 - 1.0 — First Stable (the graduation)
+
+**The Closed-Loop arc is complete (7/7), and PEN-STACK graduates to "1.0 — First Stable."** The public API
+exercised across every surface — verify, safety, generative design, twin, experiment design, build interface,
+closed loop, co-scientist, and the Genome-Writing Challenge — is documented and **frozen** with a deprecation
+policy. "First Stable" is **earned, not declared**: it is cut only after the closed loop is demonstrated (v5.12),
+the benchmark is public (v5.13), and the integration surface ships.
+
+### Changed
+- **`Development Status :: 5 - Production/Stable`** (was Beta). Version **6.0.0** (MAJOR).
+- The public API is documented + frozen with a deprecation policy: **`docs/STABILITY.md`** (semver from 6.0.0;
+  deprecations warn ≥1 MINOR before removal in a MAJOR; the `OracleResult`/`Verdict`/`SafetyVerdict`/immune-profile
+  contracts and invariants — incl. `collapsed_score is None` and the no-fabrication guard — are stable across 6.x).
+- The Genome-Writing Challenge is **public**.
+
+### Notes
+- "1.0 — First Stable" is a commitment to **API stability**, **not** a claim of solving genetic engineering. The
+  unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
+  hidden. The high version numbers of the program's fast youth finally meet a real stability commitment.
+
 ## [5.13.0] - 2026-06-11 - v5.13 release: The Standard (Genome-Writing Challenge + Co-Scientist II)
 
 **Closed-Loop arc, Cycle 7 of 7.** Make PEN-STACK the field's reference — an open, recurring, held-out benchmark

{pen_stack-5.13.0 → pen_stack-6.1.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.13.0
+version: 6.1.0
 date-released: 2026-06-11
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-5.13.0 → pen_stack-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.13.0
+Version: 6.1.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
@@ -11,7 +11,7 @@ Project-URL: Changelog, https://github.com/ahmedanees-m/pen-stack/blob/main/CHAN
 Project-URL: Issues, https://github.com/ahmedanees-m/pen-stack/issues
 Project-URL: Benchmark, https://github.com/ahmedanees-m/pen-stack/tree/main/benchmarks/genome_writing_bench
 Keywords: genome-writing,genome-editing,bridge-recombinase,safe-harbor,writable-genome,writer-atlas,write-planner,bioinformatics
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -90,8 +90,9 @@ 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.13.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-353%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-6.1.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-360%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/)
@@ -134,6 +135,37 @@ 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.
 
+## 🎓 v6.0.0 — "1.0 — First Stable"
+
+The **Closed-Loop arc is complete (7/7)** and PEN-STACK has graduated to **1.0 — First Stable**. The public API
+exercised across every surface — `verify`, `safety`, generative `design`, the `twin`, `active` experiment design,
+the `build` interface, the closed `loop`, the `co_scientist`, and the **Genome-Writing Challenge** — is documented
+and **frozen** with a deprecation policy ([`docs/STABILITY.md`](docs/STABILITY.md)). `Development Status ::
+5 - Production/Stable`. "First Stable" is **earned, not declared** — cut only after the closed loop was
+demonstrated (v5.12) and the benchmark went public (v5.13).
+
+> "1.0 — First Stable" is a commitment to **API stability**, not a claim of solving genetic engineering. The
+> unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
+> hidden.
+
+## What is new in v6.1 — The AI Integration Surface
+
+Post-1.0, the adoption surface for **AI builders**: PEN-STACK is now **self-describing** — an external agent can
+ask, programmatically, *"what can you do, and what do you refuse to answer?"* and get a typed, honest answer it can
+route on.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **MANIFEST** *(the differentiator)* | `pen_stack/api/manifest.py` | `capability_manifest()` (tools, all `fabricates=False`) + **`scope_manifest()`** — the known-unknowns + oracle scope cards as **machine-readable data** (what PEN-STACK *refuses* to answer) |
+| **OPENAPI** | `server/api.py` | `GET /capabilities` + `GET /scope` + tool routes (`/verify /safety /immune /generate /predict /suggest /session`); auto **OpenAPI 3.1** at `/openapi.json` |
+| **MCP** | `agent/mcp_server.py` | resources `pen-stack://capabilities` + `pen-stack://scope`; engine tools; a hazardous design returns a **structured refusal** |
+| **EXAMPLE** | `examples/` | golden-path `external_agent.py` (REST), `mcp_client.py` (MCP), `agent_tools.py` (framework specs built from the live manifest + dispatcher) |
+
+**Scope is data, not a disclaimer** — the honesty machinery becomes an API, the thing that makes trustworthy
+autonomy something another system can build on. See [Integrate PEN-STACK in your AI](docs/integrations.md) and
+`prereg/ws_{manifest,openapi,mcp}.yaml`. (Lowers the adoption barrier; outreach + a real result remain the
+standing bottleneck — no new science.)
+
 ## What is new in v5.13 — The Standard (Genome-Writing Challenge + Co-Scientist II)
 
 v5.13 (**Closed-Loop arc, Cycle 7 of 7**) makes PEN-STACK the field's reference and its most useful face: the
@@ -506,45 +538,68 @@ benchmark with deterministic scorers and no circular labels. See
 
 ## Architecture
 
+At **1.0**, PEN-STACK is a **closed design→build→test→learn loop** standing on two reference layers, the oracle
+mesh, and the data foundation — with **the verifier at the centre as the discriminator**: nothing is generated,
+built, or learned unless it passes *safe + legal + calibrated*, and no number is fabricated. The loop stops
+deliberately at **autonomy Level 3** (a human in control at every gate).
+
 ```
-                           +-------------------------------------------+
-                           |            WRITE PLANNER (engine)         |
-                           |   inverse design: destination x writer    |
-                           |   x cargo/guide x delivery -> ranked plan  |
-                           +----------------^-------------^-------------+
-                                            |             |
-                  +-------------------------+--+      +---+------------------------+
-                  |    WRITABLE GENOME (B)     |      |      WRITER ATLAS (A)      |
-                  |    flagship reference      |<---->|   companion reference      |
-                  |                            | reach|                            |
-                  |  - Safety layer (learned)  | ability  - Family targeting KB    |
-                  |  - Durability layer (learned)|      |  - Measured scoring axes   |
-                  |  - Reachability layer  -----+------+  - Mechanism classifier    |
-                  |  -> writability profile    |      |  - DMS variant model        |
-                  +-------------------------^--+      +---+------------------------+
-                                            |             |
-         +----------------------------------+-------------+-------------------------+
-         |                       DATA FOUNDATION (bulk-downloadable)                |
-         |  hg38 . ENCODE/Roadmap chromatin . Hi-C/LADs . TRIP position effects .   |
-         |  RID/VISDB/MLV integration sites . clinical genotoxic CIS . COSMIC .     |
-         |  DepMap . gnomAD . GTEx . UniProt . Pfam/InterPro . bridge-recombinase   |
-         |  off-target + DMS (Perry 2025)                                           |
-         +-------------------------------------------------------------------------+
-
-   Delivery immunology (v5.1-5.6, feeds the planner): a safety<->efficacy balance over the 8-vehicle palette,
-   with the immune/safety axes computed/grounded from data + sequence (genotoxicity = VISDB x COSMIC;
-   adaptive/CD8 = MHCflurry over the capsid; innate = CpG/dsRNA of the cargo; pre-existing/NAb = serosurveys;
-   anti-PEG = serosurveys, gates LNP re-dosing) -> a unified per-axis immune-risk PROFILE (Verdict.immune_profile),
-   each axis labelled validated-or-proxy (WS-CALIB), never collapsed into one number; in-vivo magnitude + patient
-   titer stay declared known-unknowns.
-
-   Platform services (on top of the validated core): PEN-MONITOR (Europe PMC living database),
-   grounded RAG/Q&A, a tool-using agent + MCP server, and a Streamlit web app.
+                  +-----------------------------------------------------------------------+
+                  |  THE FACES (v5.13 / 1.0)                                               |
+                  |  Co-Scientist (drives the loop) . Genome-Writing Challenge (held-out)  |
+                  |  . MCP server . REST API . Streamlit web app                           |
+                  +-----------------------------------^-----------------------------------+
+                                                      |
+ +----------------------------------------------------+---------------------------------------------------+
+ |  THE CLOSED LOOP  (v5.12 - autonomy Level 3; a human in control at safety / build / belief-admission)  |
+ |                                                                                                        |
+ |   GENERATE ----> PREDICT ----> DECIDE ----> [ SAFETY ] ----> BUILD ----> INGEST ----> LEARN            |
+ |   v5.8           v5.9          v5.10         v5.7            v5.11       v4.5 gate    v5.12             |
+ |   generative     digital       experiment    GUARDIAN        protocol    (no auto-    continual         |
+ |   designer       twin          designer       gate           export      edit)        + drift          |
+ |   (Pareto)       (OOD-gated)   (EIG+immVOI)   (refuse=stop)  (DRAFT)                  (versioned)       |
+ |                                                                                                        |
+ |   Every candidate is DISCARDED unless it passes THE VERIFIER below.  No number is fabricated.          |
+ +----------------------------------------------------+---------------------------------------------------+
+                                                      |
+                  +-----------------------------------v-----------------------------------+
+                  |  THE VERIFIER   verify(design) -> Verdict        (the discriminator)   |
+                  |  legality (v3.3 rules)  .  SAFETY gate (v5.7, runs first)  .            |
+                  |  calibrated confidence (v3.2)  .  per-axis immune-risk profile (v5.6)   |
+                  +-----------------------------------^-----------------------------------+
+                                                      |
+ +--------------------------------+-------------------+----------------+--------------------------------+
+ |  WRITABLE GENOME  (Paper 1)    |  WRITER ATLAS  (Paper 2)           |  ORACLE MESH  (v4.0)            |
+ |  learned safety x durability   |  33,370 systems on measured axes   |  AF3 . Boltz-2 . Chai-1 . ESM3  |
+ |  x reachability                |  + Writer-Targeting KB (8 families)|  . Evo2 . AlphaGenome . RFdiff. |
+ |  -> writability profile        |      <----- reachability ----->    |  ProteinMPNN . v5.9 STATE/scGPT |
+ |  + WRITE PLANNER (Paper 3)     |  + BRIDGE OFF-TARGET ENGINE (P4)   |  one OracleResult contract,     |
+ |    inverse design (edit_intent)|                                    |  OOD-gated, generative=candidate|
+ |  + DELIVERY IMMUNOLOGY (v5.1-6) per-axis immune-risk profile (each axis validated-or-proxy, never collapsed) |
+ |  + WORLD-MODEL GRAPH (v4.5)     typed provenanced edges, gated living loop (propose-only)              |
+ +--------------------------------+------------------------------------+--------------------------------+
+ +----------------------------------------------------------------------------------------------------+
+ |  DATA FOUNDATION  (bulk-downloadable, public)                                                       |
+ |  hg38 . ENCODE/Roadmap chromatin . Hi-C/LADs . TRIP position effects . RID/VISDB/MLV integration .   |
+ |  clinical genotoxic CIS . COSMIC . DepMap . gnomAD . GTEx . UniProt . Pfam/InterPro .                |
+ |  bridge off-target + DMS (Perry 2025) . anti-vector + anti-PEG serosurveys (immunology)              |
+ +----------------------------------------------------------------------------------------------------+
 ```
 
+**Reading the loop.** A *goal* enters at the top. The **generative designer** (v5.8) proposes candidate
+writing systems; the **twin** (v5.9) predicts their calibrated outcomes; the **experiment designer** (v5.10)
+chooses the most informative ones to test; the **Guardian** (v5.7) refuses anything hazardous; the **build
+interface** (v5.11) exports a safety-gated protocol DRAFT and ingests results through the v4.5 gate; and
+**continual learning** (v5.12) recalibrates, drift-aware, versioned and reversible. Each stage is gated by the
+**verifier** — the single discriminator that keeps the whole loop honest. Two **faces** sit on top: a
+**co-scientist** that drives the loop for a working scientist, and the **Genome-Writing Challenge**, an open
+held-out benchmark others build to.
+
 ## How it works
 
-PEN-STACK is organised as **two reference layers + one engine + a services layer**.
+PEN-STACK is organised as **the data + reference layers, the oracle mesh, the verifier (the discriminator), the
+closed loop, and the faces** — each layer below feeding the one above, with the verifier keeping the whole loop
+honest.
 
 | Component | Module | Role | Status |
 |---|---|---|---|
@@ -555,6 +610,16 @@ PEN-STACK is organised as **two reference layers + one engine + a services layer
 | **Delivery immunology** (v5.1-5.6) | `pen_stack.planner.delivery_immunology` + `{genotoxicity,capsid_epitope,seroprevalence,antipeg}_oracle`, `innate_sensing`, `immune_profile`; `validate.immune_calibration` | safety↔efficacy balance over the 8-vehicle palette; immune axes **computed/grounded from data+sequence** + anti-PEG (gates LNP re-dosing) → a unified per-axis `Verdict.immune_profile` (each axis validated-or-proxy, never collapsed); magnitude + patient titer stay known-unknowns ([docs](docs/delivery_immunology.md)) | M2 |
 | **Agentic platform** | `pen_stack.agent` | goal to cited, auditable plan; MCP server; one-command deploy | Paper 3 |
 | **Bridge off-target engine** | `pen_stack.bridge` | "CRISPOR for bridge recombinases" + guide QC (v3.1) | Paper 4 |
+| **Oracle Mesh** (v4.0) | `pen_stack.oracles` | one `OracleResult` contract over AF3/Boltz-2/Chai-1/ESM3/Evo2/AlphaGenome/STATE/scGPT; OOD-gated; generative=candidate | v4.0 |
+| **World-Model Graph** (v4.5) | `pen_stack.graph` | living knowledge graph; typed provenanced edges; gated propose-only loop | v4.5 |
+| **The Verifier** (v3.3+) | `pen_stack.verify` | `verify(design) -> Verdict`: legality + **safety** + calibrated confidence + immune profile — the discriminator | v3.3 |
+| **The Guardian** (v5.7) | `pen_stack.safety` | biosecurity / dual-use gate; runs first in `verify()`; refuse short-circuits; tamper-evident audit | v5.7 |
+| **Generative Designer** (v5.8) | `pen_stack.design` | generate → verifier-as-discriminator (hazardous/illegal discarded); Pareto with grounded immune axis | v5.8 |
+| **Digital Twin** (v5.9) | `pen_stack.twin` | calibrated, OOD-gated outcome prediction; immune-outcome from v5.6; phenotype-bounded | v5.9 |
+| **Experiment Designer** (v5.10) | `pen_stack.active` | active learning (EIG + immune-VOI); retrospective active-vs-random (reps+CI) | v5.10 |
+| **Build Interface** (v5.11) | `pen_stack.build` | safety-gated protocol export (DRAFT + immune metadata); gated ingestion; sim-lab | v5.11 |
+| **The Closed Loop** (v5.12) | `pen_stack.loop` | one gated DBTL command; autonomy **Level 3**; drift-aware; versioned/reversible continual learning | v5.12 |
+| **Co-Scientist + Challenge** (v5.13) | `pen_stack.agent.co_scientist`, `benchmarks/genome_writing_challenge` | the co-scientist drives the loop; the public held-out benchmark others build to | v5.13 |
 | **Genome-Writing Bench** (v3.1) | `benchmarks/`, `bench/run.py` | first writing-side benchmark; deterministic scorers, leaderboard | M2 |
 | **PEN-Agent** (v3.1) | `pen_stack.agent.pen_agent` | grounded write-planning state machine; zero fabrication | M2 |
 | **3D structural risk** (v3.1) | `pen_stack.wgenome.structure3d` | AlphaGenome contact-map deltas as a safety axis | M1 |
@@ -714,12 +779,14 @@ pen-stack/
 │   │                                   v5.11 protocol_safety (build-interface hard-gate: cleared exports w/ immune metadata · hazard+illegal blocked · sim loop completes) /
 │   │                                   v5.12 closed_loop (loop-integrity hard-gate: gated end-to-end run · Level-3 human-in-control · drift detection · versioned/reversible continual learning)
 │   ├── data/                         ingestion (genome, chromatin, integration, TRIP, safety annotations)
-│   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask)
+│   ├── api/                          v6.1 AI integration surface: manifest (capability_manifest + scope_manifest = machine-readable known-unknowns + oracle scope cards)
+│   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask; v3.3 verify; v6.1 /capabilities /scope /safety /immune /generate /predict /suggest /session + openapi.json 3.1)
 │   ├── 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.8 (T1-T16 + co_scientist + safety_screening + generative_design + outcome_prediction + experiment_design + protocol_safety + closed_loop; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── benchmarks/genome_writing_challenge/ v5.13 the public Genome-Writing Challenge (held-out rounds + immune-risk task + submission API; harness / run / README / SUBMISSIONS)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
+├── examples/                         v6.1 runnable golden path: external_agent.py (REST) / mcp_client.py (MCP) / agent_tools.py (framework-agnostic tool specs from the live manifest + dispatcher)
 ├── 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 /
 │                                       target_sites / delivery_constraints; v5.1-5.6 delivery_vehicles immune_safety /
@@ -727,18 +794,25 @@ 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.9 ws_{uq,ep,mc,ba,
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v6.0 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,vcell,mech,outcome,twincal,acq,aldesign,alvalidate,
-│                                       proto,ingest,simlab,loop,continual,drift,challenge,cosci2} + SHA256 locks)
+│                                       proto,ingest,simlab,loop,continual,drift,challenge,cosci2,
+│                                       manifest,openapi,mcp} + 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)
 ├── 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);
-│                                       v3.2: uncertainty.md / scope.md / mechanistic_constraints.md / BACKLOG.md
+│                                       v3.2: uncertainty.md / scope.md / mechanistic_constraints.md / BACKLOG.md;
+│                                       v4.0-4.5: oracles.md / writer_verification.md / world_model.md;
+│                                       v5.0-5.6: co_scientist.md / delivery_immunology.md;
+│                                       v5.7-v6.0 (the closed loop): responsible_use.md / biosecurity.md /
+│                                       generative_design.md / digital_twin.md / experiment_design.md /
+│                                       build_interface.md / closed_loop.md / autonomy.md / challenge.md /
+│                                       co_scientist_loop.md / integrations.md / STABILITY.md (1.0 API freeze)
 ├── 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

{pen_stack-5.13.0 → pen_stack-6.1.0}/README.md

@@ -15,8 +15,9 @@ 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.13.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-353%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-6.1.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-360%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/)
@@ -59,6 +60,37 @@ 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.
 
+## 🎓 v6.0.0 — "1.0 — First Stable"
+
+The **Closed-Loop arc is complete (7/7)** and PEN-STACK has graduated to **1.0 — First Stable**. The public API
+exercised across every surface — `verify`, `safety`, generative `design`, the `twin`, `active` experiment design,
+the `build` interface, the closed `loop`, the `co_scientist`, and the **Genome-Writing Challenge** — is documented
+and **frozen** with a deprecation policy ([`docs/STABILITY.md`](docs/STABILITY.md)). `Development Status ::
+5 - Production/Stable`. "First Stable" is **earned, not declared** — cut only after the closed loop was
+demonstrated (v5.12) and the benchmark went public (v5.13).
+
+> "1.0 — First Stable" is a commitment to **API stability**, not a claim of solving genetic engineering. The
+> unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
+> hidden.
+
+## What is new in v6.1 — The AI Integration Surface
+
+Post-1.0, the adoption surface for **AI builders**: PEN-STACK is now **self-describing** — an external agent can
+ask, programmatically, *"what can you do, and what do you refuse to answer?"* and get a typed, honest answer it can
+route on.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **MANIFEST** *(the differentiator)* | `pen_stack/api/manifest.py` | `capability_manifest()` (tools, all `fabricates=False`) + **`scope_manifest()`** — the known-unknowns + oracle scope cards as **machine-readable data** (what PEN-STACK *refuses* to answer) |
+| **OPENAPI** | `server/api.py` | `GET /capabilities` + `GET /scope` + tool routes (`/verify /safety /immune /generate /predict /suggest /session`); auto **OpenAPI 3.1** at `/openapi.json` |
+| **MCP** | `agent/mcp_server.py` | resources `pen-stack://capabilities` + `pen-stack://scope`; engine tools; a hazardous design returns a **structured refusal** |
+| **EXAMPLE** | `examples/` | golden-path `external_agent.py` (REST), `mcp_client.py` (MCP), `agent_tools.py` (framework specs built from the live manifest + dispatcher) |
+
+**Scope is data, not a disclaimer** — the honesty machinery becomes an API, the thing that makes trustworthy
+autonomy something another system can build on. See [Integrate PEN-STACK in your AI](docs/integrations.md) and
+`prereg/ws_{manifest,openapi,mcp}.yaml`. (Lowers the adoption barrier; outreach + a real result remain the
+standing bottleneck — no new science.)
+
 ## What is new in v5.13 — The Standard (Genome-Writing Challenge + Co-Scientist II)
 
 v5.13 (**Closed-Loop arc, Cycle 7 of 7**) makes PEN-STACK the field's reference and its most useful face: the
@@ -431,45 +463,68 @@ benchmark with deterministic scorers and no circular labels. See
 
 ## Architecture
 
+At **1.0**, PEN-STACK is a **closed design→build→test→learn loop** standing on two reference layers, the oracle
+mesh, and the data foundation — with **the verifier at the centre as the discriminator**: nothing is generated,
+built, or learned unless it passes *safe + legal + calibrated*, and no number is fabricated. The loop stops
+deliberately at **autonomy Level 3** (a human in control at every gate).
+
 ```
-                           +-------------------------------------------+
-                           |            WRITE PLANNER (engine)         |
-                           |   inverse design: destination x writer    |
-                           |   x cargo/guide x delivery -> ranked plan  |
-                           +----------------^-------------^-------------+
-                                            |             |
-                  +-------------------------+--+      +---+------------------------+
-                  |    WRITABLE GENOME (B)     |      |      WRITER ATLAS (A)      |
-                  |    flagship reference      |<---->|   companion reference      |
-                  |                            | reach|                            |
-                  |  - Safety layer (learned)  | ability  - Family targeting KB    |
-                  |  - Durability layer (learned)|      |  - Measured scoring axes   |
-                  |  - Reachability layer  -----+------+  - Mechanism classifier    |
-                  |  -> writability profile    |      |  - DMS variant model        |
-                  +-------------------------^--+      +---+------------------------+
-                                            |             |
-         +----------------------------------+-------------+-------------------------+
-         |                       DATA FOUNDATION (bulk-downloadable)                |
-         |  hg38 . ENCODE/Roadmap chromatin . Hi-C/LADs . TRIP position effects .   |
-         |  RID/VISDB/MLV integration sites . clinical genotoxic CIS . COSMIC .     |
-         |  DepMap . gnomAD . GTEx . UniProt . Pfam/InterPro . bridge-recombinase   |
-         |  off-target + DMS (Perry 2025)                                           |
-         +-------------------------------------------------------------------------+
-
-   Delivery immunology (v5.1-5.6, feeds the planner): a safety<->efficacy balance over the 8-vehicle palette,
-   with the immune/safety axes computed/grounded from data + sequence (genotoxicity = VISDB x COSMIC;
-   adaptive/CD8 = MHCflurry over the capsid; innate = CpG/dsRNA of the cargo; pre-existing/NAb = serosurveys;
-   anti-PEG = serosurveys, gates LNP re-dosing) -> a unified per-axis immune-risk PROFILE (Verdict.immune_profile),
-   each axis labelled validated-or-proxy (WS-CALIB), never collapsed into one number; in-vivo magnitude + patient
-   titer stay declared known-unknowns.
-
-   Platform services (on top of the validated core): PEN-MONITOR (Europe PMC living database),
-   grounded RAG/Q&A, a tool-using agent + MCP server, and a Streamlit web app.
+                  +-----------------------------------------------------------------------+
+                  |  THE FACES (v5.13 / 1.0)                                               |
+                  |  Co-Scientist (drives the loop) . Genome-Writing Challenge (held-out)  |
+                  |  . MCP server . REST API . Streamlit web app                           |
+                  +-----------------------------------^-----------------------------------+
+                                                      |
+ +----------------------------------------------------+---------------------------------------------------+
+ |  THE CLOSED LOOP  (v5.12 - autonomy Level 3; a human in control at safety / build / belief-admission)  |
+ |                                                                                                        |
+ |   GENERATE ----> PREDICT ----> DECIDE ----> [ SAFETY ] ----> BUILD ----> INGEST ----> LEARN            |
+ |   v5.8           v5.9          v5.10         v5.7            v5.11       v4.5 gate    v5.12             |
+ |   generative     digital       experiment    GUARDIAN        protocol    (no auto-    continual         |
+ |   designer       twin          designer       gate           export      edit)        + drift          |
+ |   (Pareto)       (OOD-gated)   (EIG+immVOI)   (refuse=stop)  (DRAFT)                  (versioned)       |
+ |                                                                                                        |
+ |   Every candidate is DISCARDED unless it passes THE VERIFIER below.  No number is fabricated.          |
+ +----------------------------------------------------+---------------------------------------------------+
+                                                      |
+                  +-----------------------------------v-----------------------------------+
+                  |  THE VERIFIER   verify(design) -> Verdict        (the discriminator)   |
+                  |  legality (v3.3 rules)  .  SAFETY gate (v5.7, runs first)  .            |
+                  |  calibrated confidence (v3.2)  .  per-axis immune-risk profile (v5.6)   |
+                  +-----------------------------------^-----------------------------------+
+                                                      |
+ +--------------------------------+-------------------+----------------+--------------------------------+
+ |  WRITABLE GENOME  (Paper 1)    |  WRITER ATLAS  (Paper 2)           |  ORACLE MESH  (v4.0)            |
+ |  learned safety x durability   |  33,370 systems on measured axes   |  AF3 . Boltz-2 . Chai-1 . ESM3  |
+ |  x reachability                |  + Writer-Targeting KB (8 families)|  . Evo2 . AlphaGenome . RFdiff. |
+ |  -> writability profile        |      <----- reachability ----->    |  ProteinMPNN . v5.9 STATE/scGPT |
+ |  + WRITE PLANNER (Paper 3)     |  + BRIDGE OFF-TARGET ENGINE (P4)   |  one OracleResult contract,     |
+ |    inverse design (edit_intent)|                                    |  OOD-gated, generative=candidate|
+ |  + DELIVERY IMMUNOLOGY (v5.1-6) per-axis immune-risk profile (each axis validated-or-proxy, never collapsed) |
+ |  + WORLD-MODEL GRAPH (v4.5)     typed provenanced edges, gated living loop (propose-only)              |
+ +--------------------------------+------------------------------------+--------------------------------+
+ +----------------------------------------------------------------------------------------------------+
+ |  DATA FOUNDATION  (bulk-downloadable, public)                                                       |
+ |  hg38 . ENCODE/Roadmap chromatin . Hi-C/LADs . TRIP position effects . RID/VISDB/MLV integration .   |
+ |  clinical genotoxic CIS . COSMIC . DepMap . gnomAD . GTEx . UniProt . Pfam/InterPro .                |
+ |  bridge off-target + DMS (Perry 2025) . anti-vector + anti-PEG serosurveys (immunology)              |
+ +----------------------------------------------------------------------------------------------------+
 ```
 
+**Reading the loop.** A *goal* enters at the top. The **generative designer** (v5.8) proposes candidate
+writing systems; the **twin** (v5.9) predicts their calibrated outcomes; the **experiment designer** (v5.10)
+chooses the most informative ones to test; the **Guardian** (v5.7) refuses anything hazardous; the **build
+interface** (v5.11) exports a safety-gated protocol DRAFT and ingests results through the v4.5 gate; and
+**continual learning** (v5.12) recalibrates, drift-aware, versioned and reversible. Each stage is gated by the
+**verifier** — the single discriminator that keeps the whole loop honest. Two **faces** sit on top: a
+**co-scientist** that drives the loop for a working scientist, and the **Genome-Writing Challenge**, an open
+held-out benchmark others build to.
+
 ## How it works
 
-PEN-STACK is organised as **two reference layers + one engine + a services layer**.
+PEN-STACK is organised as **the data + reference layers, the oracle mesh, the verifier (the discriminator), the
+closed loop, and the faces** — each layer below feeding the one above, with the verifier keeping the whole loop
+honest.
 
 | Component | Module | Role | Status |
 |---|---|---|---|
@@ -480,6 +535,16 @@ PEN-STACK is organised as **two reference layers + one engine + a services layer
 | **Delivery immunology** (v5.1-5.6) | `pen_stack.planner.delivery_immunology` + `{genotoxicity,capsid_epitope,seroprevalence,antipeg}_oracle`, `innate_sensing`, `immune_profile`; `validate.immune_calibration` | safety↔efficacy balance over the 8-vehicle palette; immune axes **computed/grounded from data+sequence** + anti-PEG (gates LNP re-dosing) → a unified per-axis `Verdict.immune_profile` (each axis validated-or-proxy, never collapsed); magnitude + patient titer stay known-unknowns ([docs](docs/delivery_immunology.md)) | M2 |
 | **Agentic platform** | `pen_stack.agent` | goal to cited, auditable plan; MCP server; one-command deploy | Paper 3 |
 | **Bridge off-target engine** | `pen_stack.bridge` | "CRISPOR for bridge recombinases" + guide QC (v3.1) | Paper 4 |
+| **Oracle Mesh** (v4.0) | `pen_stack.oracles` | one `OracleResult` contract over AF3/Boltz-2/Chai-1/ESM3/Evo2/AlphaGenome/STATE/scGPT; OOD-gated; generative=candidate | v4.0 |
+| **World-Model Graph** (v4.5) | `pen_stack.graph` | living knowledge graph; typed provenanced edges; gated propose-only loop | v4.5 |
+| **The Verifier** (v3.3+) | `pen_stack.verify` | `verify(design) -> Verdict`: legality + **safety** + calibrated confidence + immune profile — the discriminator | v3.3 |
+| **The Guardian** (v5.7) | `pen_stack.safety` | biosecurity / dual-use gate; runs first in `verify()`; refuse short-circuits; tamper-evident audit | v5.7 |
+| **Generative Designer** (v5.8) | `pen_stack.design` | generate → verifier-as-discriminator (hazardous/illegal discarded); Pareto with grounded immune axis | v5.8 |
+| **Digital Twin** (v5.9) | `pen_stack.twin` | calibrated, OOD-gated outcome prediction; immune-outcome from v5.6; phenotype-bounded | v5.9 |
+| **Experiment Designer** (v5.10) | `pen_stack.active` | active learning (EIG + immune-VOI); retrospective active-vs-random (reps+CI) | v5.10 |
+| **Build Interface** (v5.11) | `pen_stack.build` | safety-gated protocol export (DRAFT + immune metadata); gated ingestion; sim-lab | v5.11 |
+| **The Closed Loop** (v5.12) | `pen_stack.loop` | one gated DBTL command; autonomy **Level 3**; drift-aware; versioned/reversible continual learning | v5.12 |
+| **Co-Scientist + Challenge** (v5.13) | `pen_stack.agent.co_scientist`, `benchmarks/genome_writing_challenge` | the co-scientist drives the loop; the public held-out benchmark others build to | v5.13 |
 | **Genome-Writing Bench** (v3.1) | `benchmarks/`, `bench/run.py` | first writing-side benchmark; deterministic scorers, leaderboard | M2 |
 | **PEN-Agent** (v3.1) | `pen_stack.agent.pen_agent` | grounded write-planning state machine; zero fabrication | M2 |
 | **3D structural risk** (v3.1) | `pen_stack.wgenome.structure3d` | AlphaGenome contact-map deltas as a safety axis | M1 |
@@ -639,12 +704,14 @@ pen-stack/
 │   │                                   v5.11 protocol_safety (build-interface hard-gate: cleared exports w/ immune metadata · hazard+illegal blocked · sim loop completes) /
 │   │                                   v5.12 closed_loop (loop-integrity hard-gate: gated end-to-end run · Level-3 human-in-control · drift detection · versioned/reversible continual learning)
 │   ├── data/                         ingestion (genome, chromatin, integration, TRIP, safety annotations)
-│   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask)
+│   ├── api/                          v6.1 AI integration surface: manifest (capability_manifest + scope_manifest = machine-readable known-unknowns + oracle scope cards)
+│   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask; v3.3 verify; v6.1 /capabilities /scope /safety /immune /generate /predict /suggest /session + openapi.json 3.1)
 │   ├── 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.8 (T1-T16 + co_scientist + safety_screening + generative_design + outcome_prediction + experiment_design + protocol_safety + closed_loop; tasks / harness / solvers / LEADERBOARD / SHAs)
 ├── benchmarks/genome_writing_challenge/ v5.13 the public Genome-Writing Challenge (held-out rounds + immune-risk task + submission API; harness / run / README / SUBMISSIONS)
 ├── bench/run.py                      one-command bench entrypoint (--agent, --verify)
+├── examples/                         v6.1 runnable golden path: external_agent.py (REST) / mcp_client.py (MCP) / agent_tools.py (framework-agnostic tool specs from the live manifest + dispatcher)
 ├── 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 /
 │                                       target_sites / delivery_constraints; v5.1-5.6 delivery_vehicles immune_safety /
@@ -652,18 +719,25 @@ 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.9 ws_{uq,ep,mc,ba,
+├── prereg/                           SHA-locked success criteria (paper1..4 + ws_a..ws_h + v3.2-v6.0 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,vcell,mech,outcome,twincal,acq,aldesign,alvalidate,
-│                                       proto,ingest,simlab,loop,continual,drift,challenge,cosci2} + SHA256 locks)
+│                                       proto,ingest,simlab,loop,continual,drift,challenge,cosci2,
+│                                       manifest,openapi,mcp} + 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)
 ├── 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);
-│                                       v3.2: uncertainty.md / scope.md / mechanistic_constraints.md / BACKLOG.md
+│                                       v3.2: uncertainty.md / scope.md / mechanistic_constraints.md / BACKLOG.md;
+│                                       v4.0-4.5: oracles.md / writer_verification.md / world_model.md;
+│                                       v5.0-5.6: co_scientist.md / delivery_immunology.md;
+│                                       v5.7-v6.0 (the closed loop): responsible_use.md / biosecurity.md /
+│                                       generative_design.md / digital_twin.md / experiment_design.md /
+│                                       build_interface.md / closed_loop.md / autonomy.md / challenge.md /
+│                                       co_scientist_loop.md / integrations.md / STABILITY.md (1.0 API freeze)
 ├── 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

pen_stack-6.1.0/docs/STABILITY.md

@@ -0,0 +1,51 @@
+# API stability & deprecation policy (v6.0.0 — "1.0 — First Stable")
+
+At **v6.0.0**, PEN-STACK graduates to **1.0 — First Stable**: the public API exercised across all surfaces is
+documented and frozen, with a deprecation policy. "First Stable" is **earned, not declared** — it is cut only
+after the closed loop is demonstrated (v5.12), the benchmark is public (v5.13), and the integration surface ships.
+
+> "1.0 — First Stable" is a commitment to **API stability**, not a claim of solving genetic engineering. The
+> unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines), not hidden.
+
+## Versioning
+
+PEN-STACK follows **semantic versioning** from 6.0.0:
+
+- **MAJOR** (`x.0.0`) — backward-incompatible changes to the public API (below).
+- **MINOR** (`6.x.0`) — backward-compatible additions.
+- **PATCH** (`6.0.x`) — backward-compatible fixes.
+
+## The public API (frozen at 1.0)
+
+These are the supported entry points. Their **signatures and return-shape keys** are stable across 6.x:
+
+| Surface | Entry point |
+|---|---|
+| Verify a write | `pen_stack.verify.verify(design, question=None, *, actor=…) -> Verdict` (legal · safety · immune_profile · confidence · scope) |
+| Safety gate | `pen_stack.safety.safety_gate(design, *, actor=…) -> SafetyVerdict` |
+| Generative design | `pen_stack.design.generate_designs(...)`, `pen_stack.design.pareto_front(...)` |
+| Digital twin | `pen_stack.twin.predict_outcome(design, cell_state)`, `pen_stack.twin.calibrate_outcome(...)` |
+| Experiment design | `pen_stack.active.select_batch(...)`, `pen_stack.active.expected_information_gain(...)` |
+| Build interface | `pen_stack.build.export_protocol(...)`, `pen_stack.build.ingest_result(...)`, `pen_stack.build.run_simulated(...)` |
+| Closed loop | `pen_stack.loop.run_loop(goal, cell_state, …)` |
+| Co-scientist | `pen_stack.agent.co_scientist.co_scientist_session(goal, cell_state)` |
+| Challenge | `benchmarks.genome_writing_challenge.harness.evaluate(submission, round_id)` |
+| CLI / MCP | `pen-stack` / `pen-bridge` console scripts; `pen_stack.agent.mcp_server` |
+
+Internal helpers (underscore-prefixed names, modules under `pen_stack/*/_*`, the `data/`/`wgenome/` training
+pipelines) are **not** part of the public API and may change in any release.
+
+## Deprecation policy
+
+- A public API element is deprecated by a **`DeprecationWarning`** and a CHANGELOG note **at least one MINOR
+  release** before removal.
+- Removal happens only in a **MAJOR** release.
+- The `OracleResult` / `Verdict` / `SafetyVerdict` / immune-profile **contracts** (field names + invariants such as
+  `collapsed_score is None` and the no-fabrication guard) are stable across 6.x.
+
+## What stability does NOT promise
+
+- Model **numbers** may change as oracles / data are updated (they are version-pinned + provenanced; results are
+  reproducible *given a pinned version*, not constant forever).
+- **Scope** stays honest: out-of-scope questions are deferred, known-unknowns declared, baselines reported — at
+  1.0 and beyond.