pen-stack 8.0.0__tar.gz → 8.0.2__tar.gz

{pen_stack-8.0.0 → pen_stack-8.0.2}/CHANGELOG.md

@@ -3,10 +3,54 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.0.2] - 2026-07-13
+
+A documentation-correctness and reproducibility-enforcement patch. No scientific result and no public
+function signature changes.
+
+### Fixed
+- **Corrected the MCP tool count.** The MCP server exposes twenty-two tools; the README, CHANGELOG, and
+  manuscript are corrected from "twenty," and a guard test now fails if the registered count ever diverges
+  from the documented one.
+- **Synced the Docker image version** to the package version, enforced by the release version-consistency
+  test so the image label cannot drift again.
+
+### Changed
+- **CI enforces reproducibility on every commit.** `make repro` now runs in CI on each Python version, so the
+  two headline recomputations, the frozen-input integrity check, and the no-fabrication gate are verified
+  rather than assumed.
+
+## [8.0.1] - 2026-07-13
+
+A reproducibility and API-hardening patch. No scientific result and no public function signature changes.
+
+### Changed
+- **Result, verdict, and safety types are now immutable (frozen).** `OracleResult` and its nested
+  `Provenance`, `Verdict`, `SafetyVerdict`, `ScreenHit`, `Rule`, and `RuleResult` can no longer be mutated
+  after construction, so a result's provenance and scope, a verdict's legality, or a screen hit's severity
+  cannot be edited downstream. Build a changed copy with `model_copy(update=...)`.
+- **The REST, MCP, and Gymnasium-environment tests and the SBOL3/GenBank round-trip run by default.**
+  `fastapi`, `uvicorn`, `httpx`, `fastmcp`, `gymnasium`, `sbol3`, and `biopython` are in the `[dev]` extra, so
+  the full suite exercises these features rather than skipping them. Heavy compiled extras stay opt-in.
+- **The one-command reproduction recomputes a second headline from committed source.**
+  `scripts/pa_epridict_distinctness.py` (wired into `make repro`) re-derives the durability-vs-ePRIDICT
+  distinctness result, and `scripts/reproduce.py` now distinguishes recomputed headlines from echoed sealed
+  metrics.
+
+### Fixed
+- **An abstention is no longer reported as high confidence.** A design verified with no calibrated confidence
+  is now `not-computable`, not `grounded-confident`.
+- **The frozen-input integrity check works on a fresh checkout.** `python bench/run.py --verify` parses the
+  standard `sha256sum` manifest format (two-space, CRLF-tolerant); the manifest re-seals only on explicit
+  `--seal`; a `.gitattributes` pins the hashed inputs to LF for cross-platform stability.
+- **The reproduction harness can fail.** `scripts/reproduce.py` exits non-zero if any block fails instead of
+  always reporting success.
+- Corrected the ePRIDICT variance figure in the README (R-squared 0.041, matching the committed metrics).
+
 ## [8.0.0] - 2026-07-13 - Stable release of record
 
 The first stable, citable release. The major version marks a committed public API surface (the SDK
-functions, the REST endpoints, and the twenty MCP tools) governed by a one-minor-version deprecation policy.
+functions, the REST endpoints, and the twenty-two MCP tools) governed by a one-minor-version deprecation policy.
 It consolidates the gated 7.x development trail rather than replacing it: the pre-registrations, SHA-locked
 benchmarks, and disclosed negatives that trail documents remain intact and referenced. Stable surfaces
 carry calibrated uncertainty and validation status; the mechanism-based paths (serine-integrase, bridge, and
@@ -39,7 +83,7 @@ CAST off-target) are marked experimental and may change.
   the repository.
 
 ### Changed
-- Benchmark provenance references relative paths only. The license (MIT), MCP tool count (twenty), and
+- Benchmark provenance references relative paths only. The license (MIT), MCP tool count (twenty-two), and
   Verify-Bench rule count (eleven) are reconciled across the package metadata, the repository, and the
   manuscript. The repository was confirmed free of hardcoded credentials, addresses, and absolute local paths.
 

{pen_stack-8.0.0 → pen_stack-8.0.2}/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: 8.0.0
+version: 8.0.2
 date-released: 2026-07-13
 # The concept DOI is minted when the Zenodo record is published; add it here and in the manuscript:
 # identifiers:

{pen_stack-8.0.0 → pen_stack-8.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 8.0.0
+Version: 8.0.2
 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
@@ -75,6 +75,13 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: fastapi>=0.111; extra == "dev"
+Requires-Dist: uvicorn>=0.30; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: fastmcp>=2.3; extra == "dev"
+Requires-Dist: gymnasium>=0.29; extra == "dev"
+Requires-Dist: sbol3>=1.1; extra == "dev"
+Requires-Dist: biopython>=1.84; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
@@ -99,7 +106,7 @@ Foundation models generate candidate edits; PEN-STACK checks them. It tells you
 
 PEN-STACK is an installable Python package and service for the genome-*writing* era, the modality that installs new information into a genome (inserting genes, flipping or excising kilobases, placing programmable landing pads) rather than editing a base in place. Writing is harder and less tooled than editing, and it is gated by questions that have no canonical answer: where can you write, what can write there, and how should the write be designed.
 
-The package consolidates five earlier research projects into one citable stack and adds the reference maps and the design engine the field was missing. It runs on a single GPU, uses bulk-downloadable public data, and is validated against pre-registered baselines.
+The package consolidates five earlier research projects into one citable stack and adds the maps and the design engine the field was missing: a genome-wide Writable-Genome atlas, a cross-family Writer Atlas, an inverse-design Write Planner, a per-mechanism off-target engine, a design-stage biosecurity gate, immunogenicity and delivery profiling, a calibrated digital twin, and a grounded agent that drives them end to end. All of it runs under one engineered invariant: every reported quantity comes from a validated tool or an out-of-distribution-gated oracle, never from a language model, and anything out of scope is returned as a known-unknown rather than guessed. It runs on a single GPU, uses bulk-downloadable public data, and is validated against pre-registered baselines with the negatives reported in full.
 
 See the [CHANGELOG](CHANGELOG.md) for release history and [docs/](docs/) for the full documentation.
 
@@ -110,55 +117,57 @@ See the [CHANGELOG](CHANGELOG.md) for release history and [docs/](docs/) for the
 | Where can you write? | Labs re-derive ad-hoc "safe harbour" shortlists from inconsistent criteria; published lists range from thousands of sites to a few dozen, rarely predict expression durability, and usually cover one cell type. | The Writable Genome: a learned, cell-type-aware, writer-aware atlas scoring every locus for safety (genotoxicity risk), durability (whether a cassette stays expressed), and reachability (which enzyme can engage it). |
 | What can write there, and how well? | Enzyme capabilities are scattered across papers, with no catalogue placing the genome-writing families on common measured axes with their targeting requirements. | The Writer Atlas: 33,370 enzyme systems across 8 families on common measured axes, joined to the Writable Genome by a bidirectional cross-link. |
 | How do I design the write? | Destination, enzyme, cargo, and delivery are interdependent and goal-dependent, and no tool optimises them together. | The Write Planner: inverse design that, given a goal and an edit intent, returns ranked, traceable site, writer, cargo, and delivery plans. |
-| Where might a bridge-recombinase design go off-target? | Bridge recombinases are highly programmable but had no genome-wide off-target screening tool. | A bridge off-target engine that nominates and ranks candidate off-target locations from measured data (a screen, not a per-site risk calculator). |
+| Where might the write go off-target? | Off-target behaviour differs by writer mechanism, and most writer classes had no genome-wide screening tool. | A per-mechanism off-target engine across five writer classes (RNA-guided nuclease, serine integrase, prime-editing integrase, CAST, and bridge recombinase). It behaves like established nuclease tools where genome-wide assay data exists and reports a truthful mechanism-based screen, with its validation status, where it does not. |
+| Can I trust the outputs? | LLM design assistants produce fluent but unsourced quantities, and large-cargo design is dual-use. | A no-fabrication invariant (every number traces to a validated tool) that we verify with the model live, and a design-stage biosecurity gate that screens function, family, taxon, and raw sequence before any protocol can be emitted. |
 
 ## Architecture
 
-A goal enters through one of the interfaces. The agent layer turns it into candidate designs. Every candidate passes through the verifier, the central gate: it runs a biosecurity screen first, checks the design against the rule base, attaches a calibrated confidence and a per-axis immune-risk profile, and discards anything that is unsafe, illegal, or uncalibrated. The reference layers and the oracle mesh supply the grounded answers the verifier and planner rely on, and everything rests on public data. No value is reported without a traceable source.
-
-```mermaid
-flowchart TB
-    subgraph interfaces ["Interfaces"]
-        direction LR
-        cli["CLI"]
-        rest["REST API"]
-        mcp["MCP server"]
-        web["Web app"]
-    end
-
-    subgraph agent ["Agent layer"]
-        direction LR
-        cosci["Co-scientist"]
-        planner["Write planner"]
-        expdesign["Experiment designer"]
-    end
-
-    verifier{{"Verifier (central gate): biosecurity screen, legality rules, calibrated confidence, per-axis immune-risk profile"}}
-
-    subgraph refs ["Reference and model layers"]
-        direction LR
-        wgenome["Writable Genome: per-locus safety, durability, reachability, with bridge off-target screening"]
-        watlas["Writer Atlas: 33,370 enzyme systems across 8 families, cross-linked to loci"]
-        oracles["Oracle mesh: AlphaFold3, Evo2, AlphaGenome, ESM3, RFdiffusion, ProteinMPNN under one contract"]
-    end
-
-    data[("Public data: hg38, ENCODE and Roadmap chromatin, TRIP, COSMIC, VISDB, UniProt, Pfam, serosurveys, Perry 2025 bridge data")]
-
-    interfaces --> agent
-    agent --> verifier
-    verifier --> refs
-    refs --> data
+A goal enters through one of the interfaces. The agent layer turns it into candidate designs. Every candidate passes through the verifier, the central gate: it runs a biosecurity screen first, checks the design against the rule base, attaches a calibrated confidence and a per-axis immune-risk profile, and discards anything that is unsafe, illegal, or uncalibrated. The reference layers and the oracle mesh supply the grounded answers the verifier and planner rely on, and everything rests on public data. No value is reported without a traceable source, and no value comes from a language model.
+
+```text
+                         Interfaces
+          CLI    |    REST API    |    MCP server    |    Web app
+                                |
+                                v
+                        Agent layer
+       Co-scientist   |   Write Planner   |   Experiment Designer
+       (goal -> typed WriteSpec -> ranked site / writer / cargo / delivery plan)
+                                |
+                                v
+   +===========================================================+
+   |   VERIFIER  (the central gate, runs on every design)      |
+   |   1. biosecurity screen   2. legality rules               |
+   |   3. calibrated confidence   4. per-axis immune-risk       |
+   |   unsafe / illegal / uncalibrated designs are rejected    |
+   +===========================================================+
+                                |
+                                v
+                   Reference and model layers
+   +-------------------+  +----------------+  +-------------------+
+   | Writable Genome   |  | Writer Atlas   |  | Oracle mesh       |
+   | per-locus safety, |  | 33,370 enzyme  |  | AlphaFold3, Evo2, |
+   | durability,       |  | systems, 8     |  | AlphaGenome,      |
+   | expression-       |  | families, on   |  | ESM3, RFdiffusion,|
+   | robustness,       |  | common axes,   |  | ProteinMPNN under |
+   | reachability,     |  | cross-linked   |  | one OracleResult  |
+   | per-mechanism     |  | to every locus |  | contract (scope-  |
+   | off-target        |  |                |  | gated, provenance)|
+   +-------------------+  +----------------+  +-------------------+
+                                |
+                                v
+   Public data: hg38, ENCODE / Roadmap chromatin, TRIP, CancerMine (CC0),
+   DepMap, VISDB, UniProt, Pfam / InterPro, Europe PMC, Perry 2025 bridge data
 ```
 
 ## Components
 
 | Component | Module | What it does |
 |---|---|---|
-| Writable Genome | `pen_stack.wgenome` | Learned per-locus safety, durability, and reachability; 3D structural-risk axis; bridge off-target screening. |
+| Writable Genome | `pen_stack.wgenome` | Learned per-locus safety (genotoxicity risk), expression-robustness (durability), and writer reachability; a 3D structural-risk axis; and a per-mechanism off-target engine across five writer classes with per-class validation status. |
 | Writer Atlas | `pen_stack.atlas`, `.mech`, `.score` | Cross-family enzyme catalogue and Writer-Targeting knowledge base, cross-linked to loci. |
 | Write Planner | `pen_stack.planner` | Inverse design conditioned on an edit intent, including the delivery palette and the delivery-immunology profile. |
 | Verifier | `pen_stack.verify`, `pen_stack.rules` | `verify(design)` returns legality, biosecurity verdict, calibrated confidence, and the immune-risk profile as distinct axes. |
-| Biosecurity gate | `pen_stack.safety` | A dual-use screening gate that runs first in `verify()`, screening declared function, family, and taxon signatures and translating a raw cargo sequence against curated Pfam toxin-family profiles; a refusal short-circuits scoring, with a tamper-evident audit trail. |
+| Biosecurity gate | `pen_stack.safety` | A dual-use screening gate that runs first in `verify()`, screening declared function, family, and taxon signatures and translating a raw cargo sequence against curated Pfam toxin-family profiles; a refusal short-circuits scoring, with a tamper-evident audit trail. It reads hazard content only from declared fields (`cargo_function`, `function_annotation`, `goal_function`, `source_taxon`, `organism`, `host_taxon`, `cargo_seq`, `cargo_sequence`); content in `edit_intent` or other framing fields is not screened, so a verdict with `declared_signal=False` means "nothing screenable was declared", not "screened and safe" (see [`docs/biosecurity.md`](docs/biosecurity.md)). |
 | Oracle mesh | `pen_stack.oracles` | One `OracleResult` contract over the biomolecular foundation models, with provenance, native uncertainty, and a scope card; generated output is a candidate, out-of-distribution inputs are flagged. |
 | World-model graph | `pen_stack.graph` | A typed, provenanced knowledge graph with a gated, propose-only update loop. |
 | Generative designer | `pen_stack.design` | Proposes candidate writing systems and keeps only those that pass safety, legality, and calibration, returning a Pareto frontier. |
@@ -168,17 +177,18 @@ flowchart TB
 | Closed loop | `pen_stack.loop`, `pen_stack.active` | A gated design, build, test, learn loop with drift detection and versioned, reversible recalibration; an SDL-brain benchmark and a validation-campaign engine that orders the most-informative next measurements by expected information gain. |
 | Write intent (WriteSpec) | `pen_stack.spec` | A typed, ontology-backed `WriteRequest` (an SBOL3 profile) with a grounded extractor that resolves free text to verified ontology ids, asks clarifying questions on ambiguity, and runs a SAT feasibility check. |
 | Agent, co-scientist, and chat | `pen_stack.agent`, `pen_stack.web`, `pen_stack.rag` | Goal to cited, auditable plan; MCP server; the co-scientist that drives the loop; and the grounded conversational chat (four lanes: design, explain, meta, general; provenance-tagged retrieval; a swappable LLM provider). |
-| Bridge off-target engine | `pen_stack.bridge` | Off-target nomination and guide QC for bridge recombinases. |
+| Bridge off-target engine | `pen_stack.bridge` | The measured-data-validated off-target engine for bridge recombinases (IS110/IS621): candidate-site nomination, ranking, and guide QC, validated on the Perry 2025 data. |
+| Immunogenicity and delivery | `pen_stack.planner` | Per-writer T-cell immunogenicity profiling (NetMHCpan / NetMHCIIpan) with a human-albumin self-control, a delivery-vehicle palette, and anti-drug-antibody and anti-PEG proxies, each labelled by validation status. |
 | Interfaces | `pen_stack.server`, `pen_stack.web`, `pen_stack.ui`, `pen_stack.cli` | REST API, web application, and command-line tools. |
 
 ## Key results
 
 All results are blind and pre-registered (success criteria, baselines, and held-out sets are SHA-locked in [`prereg/`](prereg/) before any model sees the test data). Estimates are reported with their sample size and confidence interval.
 
-- **Writable Genome.** A genome-wide atlas of 3,031,030 loci across 3 cell types (K562, HepG2, CD34+ HSPC) recovers validated safe harbours as highly writable and clinical genotoxic loci as non-writable, blind. Durability transfers from mouse to human (Spearman rho 0.42).
-- **Writer Atlas.** 33,370 enzyme systems across 8 families on common measured axes; the mechanism classifier agrees with the audited labels on the curated core (1.00); the cross-link is validated on AAVS1.
-- **Write Planner.** Run genome-wide so that no on-target identity term fires, the planner's writability ranks held-out safe harbours above matched-context controls. On a gold set of 16 loci (8 functionally validated, 8 computationally defined) this is a weak, bounded signal: all-loci AUROC 0.68 (95% CI 0.53 to 0.82), validated-only 0.70 (95% CI 0.48 to 0.91, underpowered at N=8) against a safety-only baseline of 0.51. Writer-family recovery at rank 1 is 0.86 against a prevalence of 0.29 across 4 families.
-- **Bridge off-target engine.** To our knowledge the first measured-data-validated tool that nominates and ranks candidate off-target locations for bridge recombinases. On the Perry 2025 data (6,856 measured off-targets) the per-position profile confirms the central core (positions 7 to 9) as the specificity determinant, and the model ranks real off-targets above core-disrupted decoys at AUROC 0.77 against 0.62 for Hamming distance. It is a screening tool, not a quantitative safety calculator: it does not quantify how much recombination occurs at each site.
+- **Expression-robustness axis (the headline result).** A per-locus prediction of whether an integrated cassette stays expressed rather than being positionally silenced. On measured human K562 position-effect data (Leemans 2019) the axis reaches a held-out Spearman rho of 0.571 (0.558 on an independent held-out variant), and it is empirically *distinct* from ePRIDICT's chromatin prediction of prime-editing efficiency (rho 0.212, R-squared 0.041 across 7,295 loci): a complementary signal, not a restatement of one. It is validated at exact-site resolution; the deployment commonly serves coarse 1-kb features, at which the axis reaches rho about 0.16, and that gap is reported as a result rather than claimed away. See [`benchmarks/position_effect_human/`](benchmarks/position_effect_human/).
+- **Writable Genome and the integrated safety filter.** A genome-wide atlas of 3,031,030 loci across three cell types (K562, HepG2, CD34+ HSPC) recovers experimentally validated safe harbours as highly writable and clinical genotoxic loci as non-writable, blind. The three-way integrated score (safety x durability x reachability) is characterised honestly as a *reject-known-bad safety filter*: against oncogene-distance and accessibility-matched controls it reaches AUROC 0.679 (95% CI 0.536 to 0.825) versus a safety-only baseline of 0.51, with real false negatives on documented clinical genotoxic loci reported in full; it is not a calibrated genotoxicity predictor.
+- **Writer Atlas.** 33,370 enzyme systems across 8 families on common measured axes; the mechanism classifier agrees with the audited labels on the curated core (1.00); the cross-link to loci is validated on AAVS1. Writer-family recovery at rank 1 is 0.86 against a prevalence of 0.29.
+- **Per-mechanism off-target engine.** The RNA-guided nuclease path *wraps* the published CRISOT scorer (which beats naive homology, CRISOT's own result, stated plainly). The serine-integrase path, on the Chalberg 115-site human genomic pseudo-attP set, reaches AUROC 0.637 and AUPRC 0.215, beating a palindrome baseline (CI excludes zero) and matching an attP-similarity baseline on AUROC while beating it on AUPRC: an informative two-stage result, reported as such. The bridge path (Perry 2025, 6,856 measured off-targets) ranks real off-targets above core-disrupted decoys at AUROC 0.77 versus 0.62 for Hamming distance. The bridge and CAST paths are mechanism-based screens, not per-site risk calculators, and are labelled as such.
 - **No fabrication, measured with the model live.** Given no tools, an ungrounded LLM fabricates 91 to 99 percent of the tool-only planning quantities (writability, safety, durability, off-target count, structural risk, coordinate) under a naive prompt, across three model families spanning a small local model to hosted-frontier models; the same models driving the validated tools as an agent fabricate none, every number audited to a direct tool call. Anti-fabrication prompting is an uneven guardrail; grounding is not. See [`benchmarks/grounding_llm_on/`](benchmarks/grounding_llm_on/) and [`benchmarks/agentic_baseline/`](benchmarks/agentic_baseline/).
 
 ## Installation
@@ -248,6 +258,23 @@ docker compose run --rm bench python bench/run.py --agent       # on the clean i
 
 The deterministic planner beats the naive baselines on the grounded tasks; a tool-using LLM agent reaches the planner's numbers only by grounding every value (zero fabricated), while the same models with no tools fabricate the tool-only fields. See [`benchmarks/genome_writing_bench/`](benchmarks/genome_writing_bench/). The held-out public leaderboard is the [Genome-Writing Challenge](benchmarks/genome_writing_challenge/).
 
+Every benchmark ships a frozen split with a SHA-256 lock and a committed `metrics.json`, so a fresh clone reproduces the central numbers with no download and no API key:
+
+```bash
+make repro        # demo-atlas quickstart, grounding eval, agentic baseline, and the recomputed headline result
+make repro-human  # recompute the headline human K562 expression-robustness result (rho=0.571) from source data
+make repro-full   # the above plus the genome-wide atlas benchmarks (needs 'make fetch' with ZENODO_DOI)
+```
+
+The headline expression-robustness result is **recomputed from source, not read from a stored number**:
+`scripts/p2_build_human_head.py` (run by `make repro-human`, and folded into `make repro`) trains the shipped
+twin on the committed Leemans K562 features table, holds out chromosomes 3/8/12 exactly as the sealed
+pre-registration specifies, and asserts the recomputed held-out Spearman correlation (0.5711) matches the
+committed metrics. The three headline analyses each ship their metrics: the human K562 expression-robustness
+head ([`benchmarks/position_effect_human/`](benchmarks/position_effect_human/)), the integrase off-target set
+([`benchmarks/offtarget/integrase_chalberg/`](benchmarks/offtarget/integrase_chalberg/)), and the clinical
+genotoxicity panel ([`benchmarks/genotox_panel/`](benchmarks/genotox_panel/)).
+
 ## Built on prior repositories
 
 PEN-STACK consolidates and re-grounds five earlier projects. Their reusable assets are imported here; the originals are archived read-only for provenance and DOI stability.
@@ -312,16 +339,19 @@ Large artifacts (multi-million-row atlases, BigWig tracks, trained models) and a
 
 ## Data sources
 
-All public: hg38 (UCSC); ENCODE and Roadmap chromatin (ATAC/DNase and histone marks for K562, HepG2, CD34+ progenitor, mouse ES-Bruce4); GENCODE v46; COSMIC Cancer Gene Census v104; DepMap Public 26Q1; LaFave 2014 MLV integrations; VISDB; TRIP (Akhtar 2013, GEO GSE49806/49807); UniProt orthologs; Pfam and InterPro; Europe PMC; Addgene; and the Perry 2025 bridge-recombinase off-target and DMS data (copyrighted, kept local, only derived products released). Every accession and DOI is pinned in `configs/datasets.yaml` and independently verified.
+All public, and license-clean by policy. Genome and annotation: hg38 (UCSC), GENCODE v46. Chromatin: ENCODE and Roadmap (ATAC/DNase and histone marks for K562, HepG2, CD34+ progenitor, and mouse ES-Bruce4). Position-effect: TRIP (Akhtar 2013, GEO GSE49806/GSE49807) and the Leemans 2019 K562 TRIP data, which is the external validation of the expression-robustness axis. Safety: **CancerMine (CC0)** is the default oncogene and tumour-suppressor source; DepMap Public 26Q1 essentiality; LaFave 2014 MLV integrations; VISDB. Enzymes: UniProt orthologs, Pfam and InterPro. Off-target: the Perry 2025 bridge-recombinase off-target and DMS data (copyrighted, kept local, only derived products released) and the Chalberg 2006 genomic pseudo-attP set. Literature and reagents: Europe PMC, Addgene.
+
+License-restricted sources (COSMIC Cancer Gene Census, OncoKB) are **never committed and never used as training data**; they are optional, local-only enrichers a registered user pulls under their own license, and a CI test fails if a restricted source appears as a shipped derived-data source. Every accession and DOI is pinned in [`configs/datasets.yaml`](configs/datasets.yaml) and indexed in [`DATA_SOURCES.md`](DATA_SOURCES.md); the full open-data policy is in [`DATA_LICENSES.md`](DATA_LICENSES.md).
 
 ## Validation approach
 
-- Pre-register before training: success criteria, baselines, and held-out sets are SHA-locked in `prereg/` before any model sees test data.
-- Always report a baseline (oncogene distance for safety, H3K9me3/LAD for durability, intent-blind ranking for the planner, Hamming distance for the bridge engine).
+- Pre-register before training: success criteria, baselines, and held-out sets are SHA-locked in `prereg/` before any model sees the test data.
+- Always report a baseline: a safety-only far-from-oncogene prior and CancerMine oncogene distance for the integrated score; a learned lamina-associated-domain chromatin baseline and ePRIDICT for the expression-robustness axis; intent-blind ranking for the planner; and attP-similarity, palindrome, or Hamming-distance baselines for the per-mechanism off-target paths.
+- Guard against circularity: the expression-robustness axis is validated with lamina and heterochromatin features removed, so it cannot restate a chromatin baseline, and no task is scored against a label derived from the model's own features (asserted by a dedicated de-circularization test).
 - Blind external concordance: recover validated safe harbours, clinical genotoxic loci, documented writes, and measured off-targets the model never trained on.
-- Report failure: cross-cell-type degradation, small benchmark sizes, and the limits of sequence-only off-target magnitude prediction are reported as results, not footnotes.
+- Report failure: cross-cell-type degradation, the exact-site-versus-served-resolution gap, small benchmark sizes, and the limits of sequence-only off-target magnitude prediction are reported as results, not footnotes.
 - Every estimate carries its sample size and confidence interval. The validated gold sets are small, and statistical power is a stated limitation; scaling them is the top priority for turning the proof of concept into an adopted resource.
-- Grounded services: every quantitative answer comes from a validated tool call, never a language model; the living database never auto-edits the atlas; clinical directives are refused.
+- Grounded services: every quantitative answer comes from a validated tool call, never a language model, verified with the model live; the living database never auto-edits the atlas; clinical directives are refused.
 
 ## Citation
 
@@ -330,7 +360,7 @@ All public: hg38 (UCSC); ENCODE and Roadmap chromatin (ATAC/DNase and histone ma
   author  = {Mahaboob Ali, Anees Ahmed},
   title   = {PEN-STACK: open infrastructure for genome writing (The Writable Genome)},
   year    = {2026},
-  version = {8.0.0},
+  version = {8.0.2},
   url     = {https://github.com/ahmedanees-m/pen-stack}
 }
 ```
@@ -339,9 +369,10 @@ Author: Anees Ahmed Mahaboob Ali, VIT University, Vellore. MIT licensed.
 
 ## API stability
 
-Version 8.0.0 is the first stable release of record. The committed public API is the SDK functions, the REST
-endpoints, and the twenty MCP tools; these follow semantic versioning with a one-minor-version deprecation
-warning before any breaking change. Stable surfaces carry calibrated uncertainty and an explicit validation
+Version 8.0.2 is the current stable release; 8.0.0 established the committed public API and the 8.0.x patches
+(8.0.1, 8.0.2) are reproducibility, documentation, and API-hardening fixes within it (no signature changes). The committed public API is the SDK
+functions, the REST endpoints, and the twenty-two MCP tools; these follow semantic versioning with a
+one-minor-version deprecation warning before any breaking change. Stable surfaces carry calibrated uncertainty and an explicit validation
 status. The mechanism-based off-target paths (serine-integrase, bridge, and CAST) are marked experimental and
 may change as measured data becomes available. The major version marks this API commitment; it consolidates
 the gated 7.x development history rather than replacing it, so every pre-registration, sealed benchmark, and

{pen_stack-8.0.0 → pen_stack-8.0.2}/README.md

@@ -20,7 +20,7 @@ Foundation models generate candidate edits; PEN-STACK checks them. It tells you
 
 PEN-STACK is an installable Python package and service for the genome-*writing* era, the modality that installs new information into a genome (inserting genes, flipping or excising kilobases, placing programmable landing pads) rather than editing a base in place. Writing is harder and less tooled than editing, and it is gated by questions that have no canonical answer: where can you write, what can write there, and how should the write be designed.
 
-The package consolidates five earlier research projects into one citable stack and adds the reference maps and the design engine the field was missing. It runs on a single GPU, uses bulk-downloadable public data, and is validated against pre-registered baselines.
+The package consolidates five earlier research projects into one citable stack and adds the maps and the design engine the field was missing: a genome-wide Writable-Genome atlas, a cross-family Writer Atlas, an inverse-design Write Planner, a per-mechanism off-target engine, a design-stage biosecurity gate, immunogenicity and delivery profiling, a calibrated digital twin, and a grounded agent that drives them end to end. All of it runs under one engineered invariant: every reported quantity comes from a validated tool or an out-of-distribution-gated oracle, never from a language model, and anything out of scope is returned as a known-unknown rather than guessed. It runs on a single GPU, uses bulk-downloadable public data, and is validated against pre-registered baselines with the negatives reported in full.
 
 See the [CHANGELOG](CHANGELOG.md) for release history and [docs/](docs/) for the full documentation.
 
@@ -31,55 +31,57 @@ See the [CHANGELOG](CHANGELOG.md) for release history and [docs/](docs/) for the
 | Where can you write? | Labs re-derive ad-hoc "safe harbour" shortlists from inconsistent criteria; published lists range from thousands of sites to a few dozen, rarely predict expression durability, and usually cover one cell type. | The Writable Genome: a learned, cell-type-aware, writer-aware atlas scoring every locus for safety (genotoxicity risk), durability (whether a cassette stays expressed), and reachability (which enzyme can engage it). |
 | What can write there, and how well? | Enzyme capabilities are scattered across papers, with no catalogue placing the genome-writing families on common measured axes with their targeting requirements. | The Writer Atlas: 33,370 enzyme systems across 8 families on common measured axes, joined to the Writable Genome by a bidirectional cross-link. |
 | How do I design the write? | Destination, enzyme, cargo, and delivery are interdependent and goal-dependent, and no tool optimises them together. | The Write Planner: inverse design that, given a goal and an edit intent, returns ranked, traceable site, writer, cargo, and delivery plans. |
-| Where might a bridge-recombinase design go off-target? | Bridge recombinases are highly programmable but had no genome-wide off-target screening tool. | A bridge off-target engine that nominates and ranks candidate off-target locations from measured data (a screen, not a per-site risk calculator). |
+| Where might the write go off-target? | Off-target behaviour differs by writer mechanism, and most writer classes had no genome-wide screening tool. | A per-mechanism off-target engine across five writer classes (RNA-guided nuclease, serine integrase, prime-editing integrase, CAST, and bridge recombinase). It behaves like established nuclease tools where genome-wide assay data exists and reports a truthful mechanism-based screen, with its validation status, where it does not. |
+| Can I trust the outputs? | LLM design assistants produce fluent but unsourced quantities, and large-cargo design is dual-use. | A no-fabrication invariant (every number traces to a validated tool) that we verify with the model live, and a design-stage biosecurity gate that screens function, family, taxon, and raw sequence before any protocol can be emitted. |
 
 ## Architecture
 
-A goal enters through one of the interfaces. The agent layer turns it into candidate designs. Every candidate passes through the verifier, the central gate: it runs a biosecurity screen first, checks the design against the rule base, attaches a calibrated confidence and a per-axis immune-risk profile, and discards anything that is unsafe, illegal, or uncalibrated. The reference layers and the oracle mesh supply the grounded answers the verifier and planner rely on, and everything rests on public data. No value is reported without a traceable source.
-
-```mermaid
-flowchart TB
-    subgraph interfaces ["Interfaces"]
-        direction LR
-        cli["CLI"]
-        rest["REST API"]
-        mcp["MCP server"]
-        web["Web app"]
-    end
-
-    subgraph agent ["Agent layer"]
-        direction LR
-        cosci["Co-scientist"]
-        planner["Write planner"]
-        expdesign["Experiment designer"]
-    end
-
-    verifier{{"Verifier (central gate): biosecurity screen, legality rules, calibrated confidence, per-axis immune-risk profile"}}
-
-    subgraph refs ["Reference and model layers"]
-        direction LR
-        wgenome["Writable Genome: per-locus safety, durability, reachability, with bridge off-target screening"]
-        watlas["Writer Atlas: 33,370 enzyme systems across 8 families, cross-linked to loci"]
-        oracles["Oracle mesh: AlphaFold3, Evo2, AlphaGenome, ESM3, RFdiffusion, ProteinMPNN under one contract"]
-    end
-
-    data[("Public data: hg38, ENCODE and Roadmap chromatin, TRIP, COSMIC, VISDB, UniProt, Pfam, serosurveys, Perry 2025 bridge data")]
-
-    interfaces --> agent
-    agent --> verifier
-    verifier --> refs
-    refs --> data
+A goal enters through one of the interfaces. The agent layer turns it into candidate designs. Every candidate passes through the verifier, the central gate: it runs a biosecurity screen first, checks the design against the rule base, attaches a calibrated confidence and a per-axis immune-risk profile, and discards anything that is unsafe, illegal, or uncalibrated. The reference layers and the oracle mesh supply the grounded answers the verifier and planner rely on, and everything rests on public data. No value is reported without a traceable source, and no value comes from a language model.
+
+```text
+                         Interfaces
+          CLI    |    REST API    |    MCP server    |    Web app
+                                |
+                                v
+                        Agent layer
+       Co-scientist   |   Write Planner   |   Experiment Designer
+       (goal -> typed WriteSpec -> ranked site / writer / cargo / delivery plan)
+                                |
+                                v
+   +===========================================================+
+   |   VERIFIER  (the central gate, runs on every design)      |
+   |   1. biosecurity screen   2. legality rules               |
+   |   3. calibrated confidence   4. per-axis immune-risk       |
+   |   unsafe / illegal / uncalibrated designs are rejected    |
+   +===========================================================+
+                                |
+                                v
+                   Reference and model layers
+   +-------------------+  +----------------+  +-------------------+
+   | Writable Genome   |  | Writer Atlas   |  | Oracle mesh       |
+   | per-locus safety, |  | 33,370 enzyme  |  | AlphaFold3, Evo2, |
+   | durability,       |  | systems, 8     |  | AlphaGenome,      |
+   | expression-       |  | families, on   |  | ESM3, RFdiffusion,|
+   | robustness,       |  | common axes,   |  | ProteinMPNN under |
+   | reachability,     |  | cross-linked   |  | one OracleResult  |
+   | per-mechanism     |  | to every locus |  | contract (scope-  |
+   | off-target        |  |                |  | gated, provenance)|
+   +-------------------+  +----------------+  +-------------------+
+                                |
+                                v
+   Public data: hg38, ENCODE / Roadmap chromatin, TRIP, CancerMine (CC0),
+   DepMap, VISDB, UniProt, Pfam / InterPro, Europe PMC, Perry 2025 bridge data
 ```
 
 ## Components
 
 | Component | Module | What it does |
 |---|---|---|
-| Writable Genome | `pen_stack.wgenome` | Learned per-locus safety, durability, and reachability; 3D structural-risk axis; bridge off-target screening. |
+| Writable Genome | `pen_stack.wgenome` | Learned per-locus safety (genotoxicity risk), expression-robustness (durability), and writer reachability; a 3D structural-risk axis; and a per-mechanism off-target engine across five writer classes with per-class validation status. |
 | Writer Atlas | `pen_stack.atlas`, `.mech`, `.score` | Cross-family enzyme catalogue and Writer-Targeting knowledge base, cross-linked to loci. |
 | Write Planner | `pen_stack.planner` | Inverse design conditioned on an edit intent, including the delivery palette and the delivery-immunology profile. |
 | Verifier | `pen_stack.verify`, `pen_stack.rules` | `verify(design)` returns legality, biosecurity verdict, calibrated confidence, and the immune-risk profile as distinct axes. |
-| Biosecurity gate | `pen_stack.safety` | A dual-use screening gate that runs first in `verify()`, screening declared function, family, and taxon signatures and translating a raw cargo sequence against curated Pfam toxin-family profiles; a refusal short-circuits scoring, with a tamper-evident audit trail. |
+| Biosecurity gate | `pen_stack.safety` | A dual-use screening gate that runs first in `verify()`, screening declared function, family, and taxon signatures and translating a raw cargo sequence against curated Pfam toxin-family profiles; a refusal short-circuits scoring, with a tamper-evident audit trail. It reads hazard content only from declared fields (`cargo_function`, `function_annotation`, `goal_function`, `source_taxon`, `organism`, `host_taxon`, `cargo_seq`, `cargo_sequence`); content in `edit_intent` or other framing fields is not screened, so a verdict with `declared_signal=False` means "nothing screenable was declared", not "screened and safe" (see [`docs/biosecurity.md`](docs/biosecurity.md)). |
 | Oracle mesh | `pen_stack.oracles` | One `OracleResult` contract over the biomolecular foundation models, with provenance, native uncertainty, and a scope card; generated output is a candidate, out-of-distribution inputs are flagged. |
 | World-model graph | `pen_stack.graph` | A typed, provenanced knowledge graph with a gated, propose-only update loop. |
 | Generative designer | `pen_stack.design` | Proposes candidate writing systems and keeps only those that pass safety, legality, and calibration, returning a Pareto frontier. |
@@ -89,17 +91,18 @@ flowchart TB
 | Closed loop | `pen_stack.loop`, `pen_stack.active` | A gated design, build, test, learn loop with drift detection and versioned, reversible recalibration; an SDL-brain benchmark and a validation-campaign engine that orders the most-informative next measurements by expected information gain. |
 | Write intent (WriteSpec) | `pen_stack.spec` | A typed, ontology-backed `WriteRequest` (an SBOL3 profile) with a grounded extractor that resolves free text to verified ontology ids, asks clarifying questions on ambiguity, and runs a SAT feasibility check. |
 | Agent, co-scientist, and chat | `pen_stack.agent`, `pen_stack.web`, `pen_stack.rag` | Goal to cited, auditable plan; MCP server; the co-scientist that drives the loop; and the grounded conversational chat (four lanes: design, explain, meta, general; provenance-tagged retrieval; a swappable LLM provider). |
-| Bridge off-target engine | `pen_stack.bridge` | Off-target nomination and guide QC for bridge recombinases. |
+| Bridge off-target engine | `pen_stack.bridge` | The measured-data-validated off-target engine for bridge recombinases (IS110/IS621): candidate-site nomination, ranking, and guide QC, validated on the Perry 2025 data. |
+| Immunogenicity and delivery | `pen_stack.planner` | Per-writer T-cell immunogenicity profiling (NetMHCpan / NetMHCIIpan) with a human-albumin self-control, a delivery-vehicle palette, and anti-drug-antibody and anti-PEG proxies, each labelled by validation status. |
 | Interfaces | `pen_stack.server`, `pen_stack.web`, `pen_stack.ui`, `pen_stack.cli` | REST API, web application, and command-line tools. |
 
 ## Key results
 
 All results are blind and pre-registered (success criteria, baselines, and held-out sets are SHA-locked in [`prereg/`](prereg/) before any model sees the test data). Estimates are reported with their sample size and confidence interval.
 
-- **Writable Genome.** A genome-wide atlas of 3,031,030 loci across 3 cell types (K562, HepG2, CD34+ HSPC) recovers validated safe harbours as highly writable and clinical genotoxic loci as non-writable, blind. Durability transfers from mouse to human (Spearman rho 0.42).
-- **Writer Atlas.** 33,370 enzyme systems across 8 families on common measured axes; the mechanism classifier agrees with the audited labels on the curated core (1.00); the cross-link is validated on AAVS1.
-- **Write Planner.** Run genome-wide so that no on-target identity term fires, the planner's writability ranks held-out safe harbours above matched-context controls. On a gold set of 16 loci (8 functionally validated, 8 computationally defined) this is a weak, bounded signal: all-loci AUROC 0.68 (95% CI 0.53 to 0.82), validated-only 0.70 (95% CI 0.48 to 0.91, underpowered at N=8) against a safety-only baseline of 0.51. Writer-family recovery at rank 1 is 0.86 against a prevalence of 0.29 across 4 families.
-- **Bridge off-target engine.** To our knowledge the first measured-data-validated tool that nominates and ranks candidate off-target locations for bridge recombinases. On the Perry 2025 data (6,856 measured off-targets) the per-position profile confirms the central core (positions 7 to 9) as the specificity determinant, and the model ranks real off-targets above core-disrupted decoys at AUROC 0.77 against 0.62 for Hamming distance. It is a screening tool, not a quantitative safety calculator: it does not quantify how much recombination occurs at each site.
+- **Expression-robustness axis (the headline result).** A per-locus prediction of whether an integrated cassette stays expressed rather than being positionally silenced. On measured human K562 position-effect data (Leemans 2019) the axis reaches a held-out Spearman rho of 0.571 (0.558 on an independent held-out variant), and it is empirically *distinct* from ePRIDICT's chromatin prediction of prime-editing efficiency (rho 0.212, R-squared 0.041 across 7,295 loci): a complementary signal, not a restatement of one. It is validated at exact-site resolution; the deployment commonly serves coarse 1-kb features, at which the axis reaches rho about 0.16, and that gap is reported as a result rather than claimed away. See [`benchmarks/position_effect_human/`](benchmarks/position_effect_human/).
+- **Writable Genome and the integrated safety filter.** A genome-wide atlas of 3,031,030 loci across three cell types (K562, HepG2, CD34+ HSPC) recovers experimentally validated safe harbours as highly writable and clinical genotoxic loci as non-writable, blind. The three-way integrated score (safety x durability x reachability) is characterised honestly as a *reject-known-bad safety filter*: against oncogene-distance and accessibility-matched controls it reaches AUROC 0.679 (95% CI 0.536 to 0.825) versus a safety-only baseline of 0.51, with real false negatives on documented clinical genotoxic loci reported in full; it is not a calibrated genotoxicity predictor.
+- **Writer Atlas.** 33,370 enzyme systems across 8 families on common measured axes; the mechanism classifier agrees with the audited labels on the curated core (1.00); the cross-link to loci is validated on AAVS1. Writer-family recovery at rank 1 is 0.86 against a prevalence of 0.29.
+- **Per-mechanism off-target engine.** The RNA-guided nuclease path *wraps* the published CRISOT scorer (which beats naive homology, CRISOT's own result, stated plainly). The serine-integrase path, on the Chalberg 115-site human genomic pseudo-attP set, reaches AUROC 0.637 and AUPRC 0.215, beating a palindrome baseline (CI excludes zero) and matching an attP-similarity baseline on AUROC while beating it on AUPRC: an informative two-stage result, reported as such. The bridge path (Perry 2025, 6,856 measured off-targets) ranks real off-targets above core-disrupted decoys at AUROC 0.77 versus 0.62 for Hamming distance. The bridge and CAST paths are mechanism-based screens, not per-site risk calculators, and are labelled as such.
 - **No fabrication, measured with the model live.** Given no tools, an ungrounded LLM fabricates 91 to 99 percent of the tool-only planning quantities (writability, safety, durability, off-target count, structural risk, coordinate) under a naive prompt, across three model families spanning a small local model to hosted-frontier models; the same models driving the validated tools as an agent fabricate none, every number audited to a direct tool call. Anti-fabrication prompting is an uneven guardrail; grounding is not. See [`benchmarks/grounding_llm_on/`](benchmarks/grounding_llm_on/) and [`benchmarks/agentic_baseline/`](benchmarks/agentic_baseline/).
 
 ## Installation
@@ -169,6 +172,23 @@ docker compose run --rm bench python bench/run.py --agent       # on the clean i
 
 The deterministic planner beats the naive baselines on the grounded tasks; a tool-using LLM agent reaches the planner's numbers only by grounding every value (zero fabricated), while the same models with no tools fabricate the tool-only fields. See [`benchmarks/genome_writing_bench/`](benchmarks/genome_writing_bench/). The held-out public leaderboard is the [Genome-Writing Challenge](benchmarks/genome_writing_challenge/).
 
+Every benchmark ships a frozen split with a SHA-256 lock and a committed `metrics.json`, so a fresh clone reproduces the central numbers with no download and no API key:
+
+```bash
+make repro        # demo-atlas quickstart, grounding eval, agentic baseline, and the recomputed headline result
+make repro-human  # recompute the headline human K562 expression-robustness result (rho=0.571) from source data
+make repro-full   # the above plus the genome-wide atlas benchmarks (needs 'make fetch' with ZENODO_DOI)
+```
+
+The headline expression-robustness result is **recomputed from source, not read from a stored number**:
+`scripts/p2_build_human_head.py` (run by `make repro-human`, and folded into `make repro`) trains the shipped
+twin on the committed Leemans K562 features table, holds out chromosomes 3/8/12 exactly as the sealed
+pre-registration specifies, and asserts the recomputed held-out Spearman correlation (0.5711) matches the
+committed metrics. The three headline analyses each ship their metrics: the human K562 expression-robustness
+head ([`benchmarks/position_effect_human/`](benchmarks/position_effect_human/)), the integrase off-target set
+([`benchmarks/offtarget/integrase_chalberg/`](benchmarks/offtarget/integrase_chalberg/)), and the clinical
+genotoxicity panel ([`benchmarks/genotox_panel/`](benchmarks/genotox_panel/)).
+
 ## Built on prior repositories
 
 PEN-STACK consolidates and re-grounds five earlier projects. Their reusable assets are imported here; the originals are archived read-only for provenance and DOI stability.
@@ -233,16 +253,19 @@ Large artifacts (multi-million-row atlases, BigWig tracks, trained models) and a
 
 ## Data sources
 
-All public: hg38 (UCSC); ENCODE and Roadmap chromatin (ATAC/DNase and histone marks for K562, HepG2, CD34+ progenitor, mouse ES-Bruce4); GENCODE v46; COSMIC Cancer Gene Census v104; DepMap Public 26Q1; LaFave 2014 MLV integrations; VISDB; TRIP (Akhtar 2013, GEO GSE49806/49807); UniProt orthologs; Pfam and InterPro; Europe PMC; Addgene; and the Perry 2025 bridge-recombinase off-target and DMS data (copyrighted, kept local, only derived products released). Every accession and DOI is pinned in `configs/datasets.yaml` and independently verified.
+All public, and license-clean by policy. Genome and annotation: hg38 (UCSC), GENCODE v46. Chromatin: ENCODE and Roadmap (ATAC/DNase and histone marks for K562, HepG2, CD34+ progenitor, and mouse ES-Bruce4). Position-effect: TRIP (Akhtar 2013, GEO GSE49806/GSE49807) and the Leemans 2019 K562 TRIP data, which is the external validation of the expression-robustness axis. Safety: **CancerMine (CC0)** is the default oncogene and tumour-suppressor source; DepMap Public 26Q1 essentiality; LaFave 2014 MLV integrations; VISDB. Enzymes: UniProt orthologs, Pfam and InterPro. Off-target: the Perry 2025 bridge-recombinase off-target and DMS data (copyrighted, kept local, only derived products released) and the Chalberg 2006 genomic pseudo-attP set. Literature and reagents: Europe PMC, Addgene.
+
+License-restricted sources (COSMIC Cancer Gene Census, OncoKB) are **never committed and never used as training data**; they are optional, local-only enrichers a registered user pulls under their own license, and a CI test fails if a restricted source appears as a shipped derived-data source. Every accession and DOI is pinned in [`configs/datasets.yaml`](configs/datasets.yaml) and indexed in [`DATA_SOURCES.md`](DATA_SOURCES.md); the full open-data policy is in [`DATA_LICENSES.md`](DATA_LICENSES.md).
 
 ## Validation approach
 
-- Pre-register before training: success criteria, baselines, and held-out sets are SHA-locked in `prereg/` before any model sees test data.
-- Always report a baseline (oncogene distance for safety, H3K9me3/LAD for durability, intent-blind ranking for the planner, Hamming distance for the bridge engine).
+- Pre-register before training: success criteria, baselines, and held-out sets are SHA-locked in `prereg/` before any model sees the test data.
+- Always report a baseline: a safety-only far-from-oncogene prior and CancerMine oncogene distance for the integrated score; a learned lamina-associated-domain chromatin baseline and ePRIDICT for the expression-robustness axis; intent-blind ranking for the planner; and attP-similarity, palindrome, or Hamming-distance baselines for the per-mechanism off-target paths.
+- Guard against circularity: the expression-robustness axis is validated with lamina and heterochromatin features removed, so it cannot restate a chromatin baseline, and no task is scored against a label derived from the model's own features (asserted by a dedicated de-circularization test).
 - Blind external concordance: recover validated safe harbours, clinical genotoxic loci, documented writes, and measured off-targets the model never trained on.
-- Report failure: cross-cell-type degradation, small benchmark sizes, and the limits of sequence-only off-target magnitude prediction are reported as results, not footnotes.
+- Report failure: cross-cell-type degradation, the exact-site-versus-served-resolution gap, small benchmark sizes, and the limits of sequence-only off-target magnitude prediction are reported as results, not footnotes.
 - Every estimate carries its sample size and confidence interval. The validated gold sets are small, and statistical power is a stated limitation; scaling them is the top priority for turning the proof of concept into an adopted resource.
-- Grounded services: every quantitative answer comes from a validated tool call, never a language model; the living database never auto-edits the atlas; clinical directives are refused.
+- Grounded services: every quantitative answer comes from a validated tool call, never a language model, verified with the model live; the living database never auto-edits the atlas; clinical directives are refused.
 
 ## Citation
 
@@ -251,7 +274,7 @@ All public: hg38 (UCSC); ENCODE and Roadmap chromatin (ATAC/DNase and histone ma
   author  = {Mahaboob Ali, Anees Ahmed},
   title   = {PEN-STACK: open infrastructure for genome writing (The Writable Genome)},
   year    = {2026},
-  version = {8.0.0},
+  version = {8.0.2},
   url     = {https://github.com/ahmedanees-m/pen-stack}
 }
 ```
@@ -260,9 +283,10 @@ Author: Anees Ahmed Mahaboob Ali, VIT University, Vellore. MIT licensed.
 
 ## API stability
 
-Version 8.0.0 is the first stable release of record. The committed public API is the SDK functions, the REST
-endpoints, and the twenty MCP tools; these follow semantic versioning with a one-minor-version deprecation
-warning before any breaking change. Stable surfaces carry calibrated uncertainty and an explicit validation
+Version 8.0.2 is the current stable release; 8.0.0 established the committed public API and the 8.0.x patches
+(8.0.1, 8.0.2) are reproducibility, documentation, and API-hardening fixes within it (no signature changes). The committed public API is the SDK
+functions, the REST endpoints, and the twenty-two MCP tools; these follow semantic versioning with a
+one-minor-version deprecation warning before any breaking change. Stable surfaces carry calibrated uncertainty and an explicit validation
 status. The mechanism-based off-target paths (serine-integrase, bridge, and CAST) are marked experimental and
 may change as measured data becomes available. The major version marks this API commitment; it consolidates
 the gated 7.x development history rather than replacing it, so every pre-registration, sealed benchmark, and