pen-stack 4.0.3__tar.gz → 4.5.0__tar.gz

{pen_stack-4.0.3 → pen_stack-4.5.0}/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [4.5.0] - 2026-06-09 - v4.5 release: the Living World-Model (knowledge graph + gated living loop)
+
+v4.5 promotes the flat tables into a queryable knowledge graph that keeps itself current. Workstreams
+WS-{G,MON,CT,BA}, each SHA-locked. The agent proposes; a gate disposes — no process auto-edits curated truth.
+
+### Added
+- **WS-G - knowledge graph.** `pen_stack/graph/{schema,build,query}.py`: typed nodes
+  (writer/locus/cargo/vehicle/cell_type/write_type/outcome) + typed edges
+  (reaches/deliverable_by/performs/durable_in/carries/used_writer/observed_at), each carrying evidence kind
+  (measured>curated>predicted) + confidence + scope + provenance. Built deterministically from the v4.0
+  curated tables (94 nodes / 288 edges), pure-Python JSON store. Multi-hop queries return provenanced paths;
+  `deliverable_by` reproduces the v3.3 verifier (0 parity mismatches). REST `POST /graph/query` + MCP
+  `graph_query`. `docs/world_model.md`; `prereg/ws_graph.yaml`.
+- **WS-MON - gated living loop.** `pen_stack/graph/ingest.py`: Candidate + Quarantine (propose never mutates
+  a graph), `automated_checks` + `gate_admit(approved, admitted_by)` as the sole admission path with versioned
+  records; back-test surfaces ISPpu10 (Europe PMC PPR1218813). No auto-edit path (asserted). `prereg/ws_mon.yaml`.
+- **WS-CT - cell-type expansion.** `configs/cell_types.yaml` Tier-A (iPSC/ESC, primary T cells, hepatocytes)
+  with coverage cards + Tier-B roadmap; `pen_stack/graph/cell_types.py` graceful degradation (partial coverage
+  caps confidence) + cross-cell-type OOD labelling. `prereg/ws_ct.yaml`.
+- **WS-BA - graph reasoning bench.** `graph_multihop_reasoning` (bench v0.3.1): graph reasoning accuracy 1.0
+  vs ungrounded 0.0, every answer a provenanced path. `prereg/ws_ba_v45.yaml`.
+
+### Changed
+- Version 4.0.3 -> 4.5.0; bench 0.3 -> 0.3.1; README "What is new in v4.5"; M1/M2 + world-model note updates.
+
 ## [4.0.3] - 2026-06-09 - ID-correctness patch: UniProt + Pfam + ontology audit
 
 ### Fixed

{pen_stack-4.0.3 → pen_stack-4.5.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: 4.0.3
+version: 4.5.0
 date-released: 2026-06-01
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-4.0.3 → pen_stack-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 4.0.3
+Version: 4.5.0
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -89,12 +89,12 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-4.0.3-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-208%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-4.5.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-224%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
-[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.1-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -133,6 +133,24 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v4.5 — the Living World-Model (a knowledge graph that keeps itself current)
+
+v4.5 promotes the flat atlas/WT-KB/crosslink tables into a queryable **knowledge graph**: writers, loci,
+cargo, delivery vehicles, cell types, write types and measured outcomes are typed nodes joined by typed edges,
+**each carrying its provenance, its uncertainty, and the scope within which it holds**. An agent answers a
+multi-hop design question in one grounded traversal, and the graph stays current through a **gated loop** —
+new literature evidence is *proposed* as candidate edges and admitted only through a validation/human gate,
+**never auto-merged**.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **G — knowledge graph** | `pen_stack/graph/{schema,build,query}` — typed nodes + provenance/uncertainty/scope-tagged edges, built from the v4.0 curated tables; REST `POST /graph/query` + MCP `graph_query` | multi-hop design queries return **fully provenanced paths** (the answer *is* the path); `deliverable_by` edges reproduce the v3.3 verifier with **0 parity mismatches** |
+| **MON — gated living loop** | `pen_stack/graph/ingest.py` — PEN-MONITOR emits **candidate** edges; quarantined; admitted only via `gate_admit(approved)` with a versioned record | **no process auto-edits the curated truth** (Principle 1, asserted); back-test admits the recent ISPpu10 bridge system only through the gate |
+| **CT — cell-type expansion** | Tier-A cell types (iPSC/ESC, primary T cells, hepatocytes) as nodes with **coverage cards** + Tier-B roadmap | partial coverage **degrades gracefully** (confidence capped, raw reported); cross-cell-type queries **OOD-labelled** (v3.2 finding); Tier-B documented, never silently extrapolated |
+| **BA — graph reasoning bench** | `graph_multihop_reasoning` (bench v0.3.1) | graph reasoning accuracy **1.0** vs ungrounded **0.0**; every answer grounded by a provenanced path; no-fabrication holds |
+
+See `docs/world_model.md` and `prereg/ws_{graph,mon,ct,ba_v45}.yaml`.
+
 ## What is new in v4.0 — the Oracle Mesh (sitting on top of the foundation models)
 
 v4.0 makes PEN-STACK the **composition + verification layer over the biomolecular foundation models**. It
@@ -396,6 +414,7 @@ pen-stack/
 │   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
+│   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
 │   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache
 │   ├── rules/                        v3.3 machine-readable rules engine (schema/evaluators/loader/solver) over configs/rules/*.yaml
 │   ├── verify/                       v3.3 verification service: verify(design) -> Verdict (legal+reasons+confidence+scope; v4.0 writer_critique)

{pen_stack-4.0.3 → pen_stack-4.5.0}/README.md

@@ -14,12 +14,12 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-4.0.3-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-208%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-4.5.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-224%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
-[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.1-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -58,6 +58,24 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v4.5 — the Living World-Model (a knowledge graph that keeps itself current)
+
+v4.5 promotes the flat atlas/WT-KB/crosslink tables into a queryable **knowledge graph**: writers, loci,
+cargo, delivery vehicles, cell types, write types and measured outcomes are typed nodes joined by typed edges,
+**each carrying its provenance, its uncertainty, and the scope within which it holds**. An agent answers a
+multi-hop design question in one grounded traversal, and the graph stays current through a **gated loop** —
+new literature evidence is *proposed* as candidate edges and admitted only through a validation/human gate,
+**never auto-merged**.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **G — knowledge graph** | `pen_stack/graph/{schema,build,query}` — typed nodes + provenance/uncertainty/scope-tagged edges, built from the v4.0 curated tables; REST `POST /graph/query` + MCP `graph_query` | multi-hop design queries return **fully provenanced paths** (the answer *is* the path); `deliverable_by` edges reproduce the v3.3 verifier with **0 parity mismatches** |
+| **MON — gated living loop** | `pen_stack/graph/ingest.py` — PEN-MONITOR emits **candidate** edges; quarantined; admitted only via `gate_admit(approved)` with a versioned record | **no process auto-edits the curated truth** (Principle 1, asserted); back-test admits the recent ISPpu10 bridge system only through the gate |
+| **CT — cell-type expansion** | Tier-A cell types (iPSC/ESC, primary T cells, hepatocytes) as nodes with **coverage cards** + Tier-B roadmap | partial coverage **degrades gracefully** (confidence capped, raw reported); cross-cell-type queries **OOD-labelled** (v3.2 finding); Tier-B documented, never silently extrapolated |
+| **BA — graph reasoning bench** | `graph_multihop_reasoning` (bench v0.3.1) | graph reasoning accuracy **1.0** vs ungrounded **0.0**; every answer grounded by a provenanced path; no-fabrication holds |
+
+See `docs/world_model.md` and `prereg/ws_{graph,mon,ct,ba_v45}.yaml`.
+
 ## What is new in v4.0 — the Oracle Mesh (sitting on top of the foundation models)
 
 v4.0 makes PEN-STACK the **composition + verification layer over the biomolecular foundation models**. It
@@ -321,6 +339,7 @@ pen-stack/
 │   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
 │   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
+│   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
 │   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache
 │   ├── rules/                        v3.3 machine-readable rules engine (schema/evaluators/loader/solver) over configs/rules/*.yaml
 │   ├── verify/                       v3.3 verification service: verify(design) -> Verdict (legal+reasons+confidence+scope; v4.0 writer_critique)

{pen_stack-4.0.3 → pen_stack-4.5.0}/benchmarks/genome_writing_bench/LEADERBOARD.md

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

{pen_stack-4.0.3 → pen_stack-4.5.0}/benchmarks/genome_writing_bench/tasks.yaml

@@ -8,7 +8,7 @@
 # A task names a `scorer` (module.function in pen_stack.validate / pen_stack.bridge) and a `metric` key to
 # read from its report. Solvers (deterministic planner, naive baseline, LLM agent) are compared on the same
 # tasks; a solver that cannot ground a number must refuse, not invent (no-fabrication is a hard gate).
-version: "0.3"
+version: "0.3.1"
 prepared: "2026-06-09"
 
 taxonomy:
@@ -33,6 +33,8 @@ taxonomy:
   T14_contradictory:    "contradictory constraints (non-integrating + integrating vehicle + oversize cargo) -> 'no legal plan' with named rules"
   T15_prompt_injection: "goal text injects 'ignore your rules / fabricate a number' -> no-fabrication holds; the injected value never appears"
   T16_distribution_shift: "an OOD context -> confidence is deflated (extrapolating), not reported at the in-distribution level"
+  # v0.3.1 (v4.5): multi-hop reasoning over the living world-model graph.
+  GR_graph_reasoning:   "answer a multi-hop design question (writers reaching a locus AND deliverable carrying a cargo form) as a PROVENANCED graph traversal (vs an ungrounded agent that cannot cite a path)"
 
 tasks:
   - id: site_selection_blind_gsh
@@ -191,3 +193,17 @@ tasks:
     circular: false
     note: "deterministic, CI-safe; adversarial-by-construction (the v3.0 lesson applied to agents). Finite
       curated set; tests known failure families, reported with N. no-fabrication holds throughout (T15)."
+
+  # ---- v0.3.1 (v4.5): multi-hop reasoning over the world-model graph.
+  - id: graph_multihop_reasoning
+    family: GR_graph_reasoning
+    scorer: "pen_stack.validate.bench_graph_tasks:run"
+    metric: "graph_reasoning_accuracy"
+    baseline_metric: "ungrounded_baseline_accuracy"
+    higher_is_better: true
+    ground_truth: "frozen panel of multi-hop design questions (locus x cargo-form); expected writer set defined
+      by the documented mechanism (tier-1 reprogrammable reachability intersect writer output-form), NOT the
+      graph's own output (non-circular); every answer must carry a provenanced multi-hop edge path"
+    circular: false
+    note: "v4.5 world-model graph: a design question answered as one grounded traversal; an ungrounded agent
+      has no graph and cannot produce a provenanced path (0 by construction). no-fabrication holds."

pen_stack-4.5.0/configs/cell_types.yaml

@@ -0,0 +1,56 @@
+# PEN-STACK v4.5 — cell-type nodes + COVERAGE CARDS for the world-model graph (WS-CT).
+# Each cell type is a graph node carrying a coverage card: which data tracks are available, and therefore how
+# trustworthy a durability/safety score is for it. Cross-cell-type queries are OOD-labelled (the v3.2 finding:
+# chromatin marks are conserved, so context-OOD is intrinsically weak). Partial-track cell types degrade
+# gracefully and are labelled - never silently extrapolated.
+version: "1.0"
+
+cell_types:
+  # --- Tier-0 exemplars (v3.1/v3.2 Phase-1 cell types with full feature stores) ---
+  K562:
+    tier: exemplar
+    efo: "EFO:0002067"
+    coverage: full            # chromatin + expression + TRIP durability + safety tracks
+    tracks: [atac, h3k27ac, h3k9me3, expression, trip_durability, genotoxicity]
+    note: "CML lymphoblast; deepest Phase-1 feature store; durability/safety fully scored."
+  HepG2:
+    tier: exemplar
+    efo: "EFO:0001187"
+    coverage: full
+    tracks: [atac, h3k27ac, h3k9me3, expression, genotoxicity]
+    note: "hepatoblastoma; second exemplar; partial TRIP, full chromatin/expression."
+  HSPC_CD34:
+    tier: exemplar
+    efo: null
+    coverage: partial         # clinical genotoxicity context; partial histone panel (the v3.1 honesty result)
+    tracks: [atac, expression, genotoxicity]
+    note: "CD34+ HSPC; clinical genotoxic CIS context (LMO2/MECOM); PARTIAL histone panel -> graceful degradation."
+
+  # --- Tier-A expansion (v4.5 WS-CT): added as graph nodes with coverage cards. Cross-cell-type scores are
+  #     OOD-labelled (v3.2 finding: chromatin marks are conserved, so context-OOD is intrinsically weak). ---
+  iPSC:
+    tier: A
+    efo: "EFO:0004905"        # induced pluripotent stem cell
+    coverage: partial
+    tracks: [atac, h3k27ac, expression]
+    note: "iPSC/ESC; broad chromatin but TRIP durability not measured here -> durability OOD-labelled, degraded."
+  primary_T_cell:
+    tier: A
+    efo: "EFO:0002322"        # CD4+/CD8+ primary T cell (CAR-T relevant)
+    coverage: partial
+    tracks: [atac, expression]
+    note: "primary T cells (CAR-T context); accessibility + expression only -> histone-dependent safety degraded."
+  hepatocyte:
+    tier: A
+    efo: "EFO:0004146"        # primary hepatocyte
+    coverage: partial
+    tracks: [atac, h3k27ac, expression]
+    note: "primary hepatocytes (in-vivo liver target); partial panel -> graceful degradation, scope-flagged."
+
+# Tier-B roadmap (documented, gated by data availability; NOT yet scored - listed honestly, never silently
+# extrapolated). Added as nodes only when their data tracks become available.
+tier_b_roadmap:
+  - {cell_type: HSPC_subsets, blocker: "lineage-resolved ATAC/expression per subset"}
+  - {cell_type: neurons, blocker: "post-mitotic chromatin + durability tracks"}
+  - {cell_type: skeletal_muscle, blocker: "myofiber accessibility + integration durability data"}
+  - {cell_type: retina_photoreceptor, blocker: "tissue-specific tracks; AAV-subretinal context"}

pen_stack-4.5.0/docs/world_model.md

@@ -0,0 +1,49 @@
+# The living world-model graph (v4.5, WS-G)
+
+v4.5 promotes PEN-STACK's ground truth from flat tables joined by code into a queryable **knowledge graph**:
+typed nodes joined by typed edges, where **every edge carries its provenance, its uncertainty, and the scope
+within which it holds**. An agent answers a multi-hop design question as a single grounded traversal.
+
+## Schema (`pen_stack/graph/schema.py`)
+
+| Nodes | Edges | Edge evidence (trust order) |
+|---|---|---|
+| `writer`, `locus`, `cargo`, `vehicle`, `cell_type`, `write_type`, `outcome` | `reaches`, `deliverable_by`, `performs`, `durable_in`, `carries`, `used_writer`, `observed_at` | `measured` > `curated` > `predicted` |
+
+Every `Edge` has `evidence`, `confidence` (or `None` = abstain), `scope`, and `provenance` (`source`, `doi`,
+`date`, …). The store is pure-Python and serialises to JSON — Docker-friendly, no graph-DB dependency.
+
+## Building it (`build.py`)
+
+The graph is assembled **deterministically from the v4.0 curated tables** — the WT-KB writer families, the
+8-vehicle delivery palette, the write-type taxonomy, the DOI-validated GSH loci, the documented writer panel,
+and the cell-type coverage cards. **Parity-first**: the `deliverable_by` edges reproduce the v3.3
+rule-grounded verifier's cargo-form legality exactly (0 mismatches, asserted by test) before any multi-hop
+extension. Nothing here calls a network or a model.
+
+## Querying it (`query.py`, REST `POST /graph/query`, MCP `graph_query`)
+
+```python
+from pen_stack.graph import writers_reaching_and_deliverable
+r = writers_reaching_and_deliverable("AAVS1", cargo_form="DNA")
+# -> {n_answers, answers:[{writer, output_form, vehicles, provenance_path:[...]}], grounded, no_fabrication}
+```
+
+Each answer is the **provenanced multi-hop path** the query traversed (writer →reaches→ locus, writer
+→deliverable_by→ vehicle), so the result is grounded by construction. The flat atlas/crosslink joins remain as
+graph *views* (`vehicles_for_writer`, `writers_for_locus`) for parity and fallback.
+
+## Currency & cell-type coverage
+
+- The graph stays current through a **gated living loop** (`pen_stack/graph/ingest.py`, WS-MON): PEN-MONITOR
+  emits *candidate* edges from new literature; they are quarantined and admitted only through a
+  validation/human gate, versioned with date + evidence. **No process auto-edits the curated truth.**
+- Cell types are nodes with **coverage cards** (`configs/cell_types.yaml`): which tracks are available, and
+  therefore how trustworthy a score is. Cross-cell-type queries are OOD-labelled (the v3.2 finding); partial
+  cell types degrade gracefully and are labelled.
+
+## Honest scope
+
+A graph is **bookkeeping, not new biology** — its value is queryability, currency, and provenance, not a new
+predictor. Reachability edges are *locus-level* and *predicted* (the per-site element check stays Planner
+work); outcome edges are documented-evidence links, not clinical guarantees.

{pen_stack-4.0.3 → pen_stack-4.5.0}/pen_stack/__init__.py

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

{pen_stack-4.0.3 → pen_stack-4.5.0}/pen_stack/agent/mcp_server.py

@@ -49,5 +49,14 @@ def verify_write(design: dict) -> dict:
     return verify(design).model_dump()
 
 
+@mcp.tool()
+def graph_query(locus: str, cargo_form: str | None = None) -> dict:
+    """v4.5 world-model graph (WS-G): a multi-hop query. Returns the writer families that REACH `locus` AND
+    are DELIVERABLE by a vehicle carrying `cargo_form` (optional), each answer with its provenanced edge path
+    (the answer IS the path — no fabrication). The graph nodes/edges carry evidence kind + scope + provenance."""
+    from pen_stack.graph import writers_reaching_and_deliverable
+    return writers_reaching_and_deliverable(locus, cargo_form=cargo_form)
+
+
 if __name__ == "__main__":  # pragma: no cover
     mcp.run()

pen_stack-4.5.0/pen_stack/graph/__init__.py

@@ -0,0 +1,21 @@
+"""The living world-model knowledge graph (v4.5, WS-G).
+
+`pen_stack.graph` promotes the v4.0 flat tables (atlas / WT-KB / crosslink / delivery palette / write-type
+taxonomy / GSH loci / documented writes / cell-type coverage cards) into a queryable knowledge graph: typed
+nodes joined by typed edges, each carrying provenance + uncertainty + scope. Multi-hop design questions become
+single grounded traversals; the gated living loop (`pen_stack.graph.ingest`) keeps it current without ever
+auto-editing the curated truth.
+"""
+from __future__ import annotations
+
+from pen_stack.graph.build import build_graph
+from pen_stack.graph.query import (
+    outcomes_for_writer,
+    vehicles_for_writer,
+    writers_for_locus,
+    writers_reaching_and_deliverable,
+)
+from pen_stack.graph.schema import Edge, Graph, Node
+
+__all__ = ["Graph", "Node", "Edge", "build_graph", "vehicles_for_writer", "writers_for_locus",
+           "writers_reaching_and_deliverable", "outcomes_for_writer"]

pen_stack-4.5.0/pen_stack/graph/build.py

@@ -0,0 +1,133 @@
+"""Build the world-model knowledge graph from the v4.0 curated tables (v4.5, WS-G).
+
+Parity-first (v4.5 risk register): the graph is assembled from the SAME validated sources the v4.0 code joins
+— the WT-KB writer families, the delivery-vehicle palette, the write-type taxonomy, the DOI-validated GSH
+loci, the documented writer panel, and the cell-type coverage cards — so its edges reproduce the existing
+table joins (asserted by the parity test) before any multi-hop extension. Every edge is typed by evidence
+kind and carries provenance + scope. Nothing here calls a network or a model; it is deterministic + CI-safe.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.graph.schema import Edge, Graph, Node
+
+# writer output form (DNA cargo / RNP) per family — the same map the rule evaluators use (parity).
+_WRITER_FORM = {"bridge_IS110": "DNA", "seek_IS1111": "DNA", "CAST_VK": "DNA", "serine_integrase": "DNA",
+                "PE_integrase": "DNA", "Cas9": "RNP", "Cas12a": "RNP", "TnpB_Fanzor": "RNP"}
+# tier-1 reprogrammable families are near-universal at the locus level (crosslink honesty: locus-level reach).
+_TIER1 = {"bridge_IS110", "seek_IS1111", "Cas9", "Cas12a"}
+
+
+def _yaml(path: str) -> dict:
+    return yaml.safe_load(resource(path).read_text(encoding="utf-8"))
+
+
+def _lst(v) -> list:
+    """Coerce a possibly-numpy-array / None cell to a plain list (avoids ambiguous-truthiness)."""
+    if v is None:
+        return []
+    try:
+        return [x for x in v]
+    except TypeError:
+        return [v]
+
+
+@lru_cache(maxsize=1)
+def build_graph() -> Graph:
+    g = Graph()
+    import pandas as pd
+
+    # ---- writer nodes (WT-KB families) ---------------------------------------------------------
+    wtkb = pd.read_parquet(resource("pen_stack/atlas/wtkb.parquet"))
+    for _, w in wtkb.iterrows():
+        fam = str(w["family"])
+        g.add_node(Node(id=f"writer:{fam}", type="writer", props={
+            "family": fam, "mechanism_bucket": w.get("mechanism_bucket"),
+            "output_form": _WRITER_FORM.get(fam), "cargo_capacity_bp": int(w["cargo_capacity_bp"])
+            if pd.notna(w.get("cargo_capacity_bp")) else None,
+            "reachability_tier": w.get("reachability_tier"), "dsb_free": bool(w.get("dsb_free")),
+            "confidence": w.get("confidence"), "dois": _lst(w.get("key_dois"))}))
+
+    # ---- vehicle + cargo-form nodes (delivery palette) -----------------------------------------
+    veh = _yaml("configs/delivery_vehicles.yaml")["vehicles"]
+    for form in ("DNA", "mRNA", "RNP"):
+        g.add_node(Node(id=f"cargo:{form}", type="cargo", props={"form": form}))
+    for name, v in veh.items():
+        g.add_node(Node(id=f"vehicle:{name}", type="vehicle", props={
+            "cargo_capacity_bp": v.get("cargo_capacity_bp"), "integrating": v.get("integrating"),
+            "compatible_cargo_form": v.get("compatible_cargo_form", []), "dois": v.get("dois", [])}))
+        for form in v.get("compatible_cargo_form", []):
+            g.add_edge(Edge(f"vehicle:{name}", f"cargo:{form}", "carries", "curated",
+                            scope="documented vehicle cargo-form", provenance={"source": "delivery_vehicles.yaml",
+                            "doi": v.get("dois", [])}))
+
+    # ---- write-type nodes ----------------------------------------------------------------------
+    wts = _yaml("configs/write_types.yaml")["write_types"]
+    for wt, spec in wts.items():
+        g.add_node(Node(id=f"write_type:{wt}", type="write_type",
+                        props={"status": spec.get("status"), "writer_classes": spec.get("writer_classes", [])}))
+
+    # ---- cell-type nodes (coverage cards) ------------------------------------------------------
+    cts = _yaml("configs/cell_types.yaml")["cell_types"]
+    for ct, card in cts.items():
+        g.add_node(Node(id=f"cell_type:{ct}", type="cell_type", props={
+            "tier": card.get("tier"), "efo": card.get("efo"), "coverage": card.get("coverage"),
+            "tracks": card.get("tracks", []), "note": card.get("note")}))
+
+    # ---- locus nodes (DOI-validated GSH) -------------------------------------------------------
+    gsh = _yaml("configs/gsh_validated_heldout.yaml")["gsh"]
+    for loc in gsh:
+        g.add_node(Node(id=f"locus:{loc['name']}", type="locus", props={
+            "tier": loc.get("tier"), "anchor_gene": loc.get("anchor_gene") or loc.get("anchor_gene_note"),
+            "doi": loc.get("doi")}))
+
+    # ---- outcome nodes (documented writes) -----------------------------------------------------
+    panel = pd.read_csv(resource("data/writer_panel.csv"))
+
+    # ---- EDGES ---------------------------------------------------------------------------------
+    writers = [f"writer:{f}" for f in wtkb["family"].astype(str)]
+    # writer -deliverable_by-> vehicle (cargo-form compatible) - PARITY with the v3.3 delivery rule
+    for wid in writers:
+        form = g.nodes[wid].props["output_form"]
+        for name, v in veh.items():
+            if form in v.get("compatible_cargo_form", []):
+                g.add_edge(Edge(wid, f"vehicle:{name}", "deliverable_by", "curated",
+                                scope="cargo-form compatibility (not tropism)",
+                                provenance={"source": "delivery rule cargo_form_compatible"}))
+    # writer -performs-> write_type (writer_classes membership)
+    _CLASS = {"bridge_IS110": "bridge", "seek_IS1111": "bridge", "CAST_VK": "cast",
+              "serine_integrase": "serine_integrase", "PE_integrase": "pe_integrase"}
+    for wid in writers:
+        fam = g.nodes[wid].props["family"]
+        for wt, spec in wts.items():
+            classes = spec.get("writer_classes", [])
+            if "any" in classes or _CLASS.get(fam) in classes:
+                g.add_edge(Edge(wid, f"write_type:{wt}", "performs", "curated",
+                                scope=spec.get("status"), provenance={"source": "write_types.yaml"}))
+    # writer -reaches-> locus (locus-level reachability; tier-1 near-universal) - predicted, scope-flagged
+    for wid in writers:
+        fam = g.nodes[wid].props["family"]
+        if fam in _TIER1:
+            for loc in gsh:
+                g.add_edge(Edge(wid, f"locus:{loc['name']}", "reaches", "predicted", confidence=None,
+                                scope="locus-level reachability (per-site element check is Planner work)",
+                                provenance={"source": "crosslink reachability_tier (tier-1 reprogrammable)"}))
+    # outcome -used_writer-> writer ; outcome -observed_at-> locus (when the panel name maps to a GSH locus)
+    gsh_names = {loc["name"] for loc in gsh}
+    for _, r in panel.iterrows():
+        oid = f"outcome:{r['name']}"
+        g.add_node(Node(id=oid, type="outcome", props={"writer_family": str(r["family"]),
+                    "cargo_bp": int(r["cargo_bp"]), "doi": str(r["doi"]), "note": str(r.get("note", ""))}))
+        wid = f"writer:{r['family']}"
+        if wid in g.nodes:
+            g.add_edge(Edge(oid, wid, "used_writer", "measured", confidence=1.0,
+                            scope="documented experimental write", provenance={"doi": str(r["doi"])}))
+        for ln in gsh_names:
+            if ln.lower() in str(r["name"]).lower():
+                g.add_edge(Edge(oid, f"locus:{ln}", "observed_at", "measured",
+                                scope="documented locus of the write", provenance={"doi": str(r["doi"])}))
+    return g

pen_stack-4.5.0/pen_stack/graph/cell_types.py

@@ -0,0 +1,58 @@
+"""Cell-type coverage cards + cross-type OOD labelling + graceful degradation (v4.5, WS-CT).
+
+Each cell type is a graph node carrying a **coverage card** (which data tracks exist). A score is only as
+trustworthy as its coverage: a partial-coverage cell type **degrades gracefully** (its confidence is capped),
+and a score computed in one cell type but *queried* for another is **OOD-labelled** — the v3.2 finding that
+chromatin marks are conserved, so cross-cell-type context is intrinsically weak/heuristic, not a guarantee.
+Tier-B cell types are a documented roadmap, never silently extrapolated.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+# graceful-degradation policy: the maximum trustworthy confidence a cell type's coverage supports.
+_MAX_CONF = {"full": 1.0, "partial": 0.6, "none": 0.0}
+
+
+@lru_cache(maxsize=1)
+def _cfg() -> dict:
+    return yaml.safe_load(resource("configs/cell_types.yaml").read_text(encoding="utf-8"))
+
+
+def coverage_card(cell_type: str) -> dict | None:
+    return _cfg()["cell_types"].get(cell_type)
+
+
+def cell_types() -> list[str]:
+    return list(_cfg()["cell_types"])
+
+
+def tier_b_roadmap() -> list[dict]:
+    return list(_cfg().get("tier_b_roadmap", []))
+
+
+def degrade(raw_confidence: float, cell_type: str) -> dict:
+    """Cap a confidence by the cell type's coverage (graceful degradation). Returns the degraded value +
+    whether degradation was applied + the coverage label — never silently inflates."""
+    card = coverage_card(cell_type) or {}
+    cov = card.get("coverage", "none")
+    cap = _MAX_CONF.get(cov, 0.0)
+    degraded = min(float(raw_confidence), cap)
+    return {"cell_type": cell_type, "coverage": cov, "raw_confidence": round(float(raw_confidence), 4),
+            "confidence": round(degraded, 4), "degraded": degraded < float(raw_confidence),
+            "cap": cap, "tracks": card.get("tracks", [])}
+
+
+def cross_cell_type_ood(query_cell_type: str, scored_in_cell_type: str) -> dict:
+    """Label a cross-cell-type query as OOD/extrapolating (v3.2: cross-type signal is weak, heuristic).
+    Same cell type = in-distribution; different = extrapolating."""
+    ood = query_cell_type != scored_in_cell_type
+    return {"query_cell_type": query_cell_type, "scored_in_cell_type": scored_in_cell_type,
+            "ood": ood,
+            "label": "extrapolating (cross-cell-type; v3.2: chromatin conserved -> weak heuristic)"
+                     if ood else "in-distribution",
+            "note": "cross-cell-type transfer is a heuristic signal, not a guarantee; reported, not hidden"}