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

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

@@ -3,6 +3,35 @@
 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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.0.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
@@ -90,9 +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-6.0.0-blue.svg)](CHANGELOG.md)
+[![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-354%20passing-success.svg)](tests/)
+[![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/)
@@ -148,6 +148,24 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.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
@@ -520,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 |
 |---|---|---|---|
@@ -569,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 |
@@ -728,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 /
@@ -741,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-6.0.0 → pen_stack-6.1.0}/README.md

@@ -15,9 +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-6.0.0-blue.svg)](CHANGELOG.md)
+[![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-354%20passing-success.svg)](tests/)
+[![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/)
@@ -73,6 +73,24 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.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
@@ -445,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 |
 |---|---|---|---|
@@ -494,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 |
@@ -653,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 /
@@ -666,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/integrations.md

@@ -0,0 +1,87 @@
+# Integrate PEN-STACK in your AI (v6.1)
+
+PEN-STACK is a **grounding substrate** an AI agent can depend on. From v6.1 the AI-facing surface is
+**self-describing**: an 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. Integrate in minutes over REST or MCP.
+
+## The four guarantees
+
+When your agent calls PEN-STACK, every answer carries:
+
+1. **Rule-grounded legality** — a design is legal/illegal per machine-readable rules, with the *named* rule cited.
+2. **Calibrated confidence** — soft scores come with conformal intervals; out-of-distribution is flagged.
+3. **Explicit scope** — what PEN-STACK *cannot* tell you is returned as data (`out_of_scope` / `extrapolating`), never guessed.
+4. **Biosecurity safety** — a dual-use/hazardous design is refused or escalated, as a structured verdict.
+
+…and **no fabrication**: every number is computed by a validated tool.
+
+## Discover capabilities — and scope (the differentiator)
+
+```bash
+GET /capabilities      # machine-readable: the tools, inputs, outputs, stability
+GET /scope             # machine-readable: the known-unknowns + every oracle's in-distribution envelope
+```
+
+`/scope` is the contract that makes depending on PEN-STACK safe: it lists, as data, the questions PEN-STACK
+**refuses** to answer (phenotype, in-vivo immunogenicity magnitude, long-term clinical durability, …) and what
+each wrapped model is *not* valid for. Your agent reads it and never builds on a non-answer.
+
+```python
+from pen_stack.api import capability_manifest, scope_manifest   # in-process
+caps = capability_manifest()      # {"tools": [...], "guarantees": [...], "stability": "stable"}
+scope = scope_manifest()          # {"known_unknowns": [...], "oracle_scope_cards": [...], "policy": "..."}
+```
+
+## REST — the golden path
+
+```python
+import requests
+BASE = "http://localhost:8000"            # uvicorn pen_stack.server.api:app
+
+scope = requests.get(f"{BASE}/scope").json()
+v = requests.post(f"{BASE}/verify", json=design).json()
+if v["safety"]["decision"] == "refuse":   # safety branch — halt
+    ...
+elif not v["legal"]:                      # legality branch — revise
+    ...
+else:                                     # proceed, with calibrated confidence + immune profile
+    use(v["confidence"], v["immune_profile"])
+```
+
+Tool routes: `/verify · /safety · /immune · /generate · /predict · /suggest · /session` + `/capabilities · /scope`.
+The full typed contract is the auto-generated **OpenAPI 3.1** spec at `/openapi.json`. Runnable example:
+[`examples/external_agent.py`](../examples/external_agent.py).
+
+## MCP — call PEN-STACK from any MCP client
+
+```bash
+python -m pen_stack.agent.mcp_server      # fastmcp; tools + the capabilities/scope resources
+```
+
+Tools: `verify_write · safety_screen · immune_profile · generate_designs · predict_outcome · suggest_experiment
+· co_scientist_session · graph_query · plan_write · …`. Resources: `pen-stack://capabilities`,
+`pen-stack://scope`. A hazardous design returns a **structured refusal** (`safety.decision == "refuse"`) an agent
+branches on. Runnable example: [`examples/mcp_client.py`](../examples/mcp_client.py).
+
+## Drop into any tool-calling framework
+
+[`examples/agent_tools.py`](../examples/agent_tools.py) builds OpenAI/Anthropic-shaped tool specs **from the live
+capability manifest** (so they never drift from the code) and dispatches to the validated engine in-process:
+
+```python
+from examples.agent_tools import tool_specs, dispatch
+specs = tool_specs()                                  # hand to LangChain / the OpenAI or Anthropic SDK
+result = dispatch("verify_write", {"payload": {...}}) # numbers come only from the engine
+```
+
+## Stability
+
+All exposed contracts (the manifests, the OpenAPI schemas, the MCP tool/resource shapes) are versioned and
+deprecation-policed under the **1.0 commitment** — see [API stability](STABILITY.md). The
+`OracleResult`/`Verdict`/`SafetyVerdict`/immune-profile contracts and invariants are stable across 6.x.
+
+## The honest bottleneck
+
+This surface makes integration **easy and dependable**; it does not, by itself, create adoption — landing a first
+external integration and a demonstrated real-world result remain the standing outreach work. The surface is
+shipped; `benchmarks/genome_writing_challenge/SUBMISSIONS.md` records external entries as they arrive.

{pen_stack-6.0.0 → pen_stack-6.1.0}/pen_stack/__init__.py

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