pen-stack 0.1.0__py3-none-any.whl

pen_stack/design/writer_variants.py

@@ -0,0 +1,121 @@
+"""Writer-variant critique, serine-integrase hyperactive mutants.
+
+Extends the writer-verification (`atlas.writer_verify`, which scores ISCro4 bridge-recombinase variants
+against the Perry DMS) to the **serine integrases**, using the directed-evolution hyperactive-mutant tables of
+Hew, Gupta, Sato et al. (Nucleic Acids Res 2024, 52(14):e64, 10.1093/nar/gkae534) and the foundational PhiC31
+mutants of Keravala et al. (Mol Ther 2009, 10.1038/mt.2008.241).
+
+Scope spine (carried forward): a variant score is a CANDIDATE plausibility, never a measured-activity claim.
+Two distinct things are kept separate, and the SECOND is reported as the scientifically-correct caveat:
+  * **Retrospective recovery**, the measured hyperactive mutants (fold > 1) outrank wild-type. This is a
+    catalogue criterion over a FROZEN, DOI'd panel of real fold-improvements (deterministic, CI-safe), it
+    recovers the known hyperactive mutations, but it is NOT a blind sequence-only predictor (it uses the measured
+    folds), exactly as `writer_verify.blind_recovery` is labelled.
+  * **LM recovery vs a conservation baseline**, can a protein LM (ESM3/Evo2) or conservation RANK the hyperactive
+    mutants above WT *blind*? This is the genuinely hard, falsifiable claim. We attempt it via the oracle when the
+    model server is available and **report the result verbatim**, including the expected NEGATIVE: protein LMs
+    score *naturalness*, while hyperactive engineered mutants are **gain-of-function** and need not be LM-favoured.
+    Deferred (no fabrication) when the server is absent.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# FROZEN, DOI'd panel of REAL serine-integrase variants + measured fold-improvement over wild-type.
+# fold = measured integration-efficiency fold over WT (>1 = hyperactive); WT anchor = 1.0.
+# Bxb1 combination "c22" = I87L + H95Y + V122M + A369P + E434G (Hew NAR 2024); 11.2-fold in K562 (2.7% -> 30.3%).
+_HYPERACTIVE = {
+    # integrase, variant, fold_over_wt, basis (cell/context), doi
+    "Bxb1_WT": {"integrase": "Bxb1", "fold": 1.00, "basis": "WT anchor (2.7% K562)", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_I87L": {"integrase": "Bxb1", "fold": 1.30, "basis": "single mutation (component of c22)", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_H95Y": {"integrase": "Bxb1", "fold": 1.30, "basis": "single mutation (component of c22)", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_V122M": {"integrase": "Bxb1", "fold": 1.30, "basis": "single mutation (component of c22)", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_A369P": {"integrase": "Bxb1", "fold": 1.30, "basis": "single mutation (component of c22)", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_E434G": {"integrase": "Bxb1", "fold": 1.30, "basis": "single mutation (component of c22)", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_L8-5": {"integrase": "Bxb1", "fold": 2.50, "basis": "best single-step IntePACE variant", "doi": "10.1093/nar/gkae534"},
+    "Bxb1_c22": {"integrase": "Bxb1", "fold": 11.2, "basis": "combination (2.7%->30.3% K562)", "doi": "10.1093/nar/gkae534"},
+    "PhiC31_WT": {"integrase": "PhiC31", "fold": 1.00, "basis": "WT anchor", "doi": "10.1038/mt.2008.241"},
+    "PhiC31_P2": {"integrase": "PhiC31", "fold": 2.00, "basis": "Keravala P2 (2x WT)", "doi": "10.1038/mt.2008.241"},
+    "PhiC31_P2-L2-1": {"integrase": "PhiC31", "fold": 9.30, "basis": "evolved from P2 (1.3%->12.1% ROSA26)", "doi": "10.1093/nar/gkae534"},
+    "PhiC31_P3-L1-2": {"integrase": "PhiC31", "fold": 14.2, "basis": "evolved P3 (18.4% ROSA26)", "doi": "10.1093/nar/gkae534"},
+}
+# the c22 component mutations (1-based positions), the conserved-residue check should NOT flag these as core
+_C22_MUTATIONS = ["I87L", "H95Y", "V122M", "A369P", "E434G"]
+
+
+@dataclass
+class WriterVariantScore:
+    variant: str
+    integrase: str
+    measured_fold: float
+    hyperactive: bool
+    claimable: bool
+    note: str
+
+
+def hyperactive_panel(integrase: str | None = None) -> dict:
+    """The frozen, DOI'd serine-integrase hyperactive-mutant panel (real measured folds). Filtered to a single
+    integrase when given (matching the by_integrase filter); the full panel when omitted."""
+    return {k: dict(v) for k, v in _HYPERACTIVE.items() if integrase is None or v["integrase"] == integrase}
+
+
+def hyperactive_recovery(integrase: str | None = None) -> dict:
+    """Retrospective recovery: the measured hyperactive mutants (fold > 1) rank ABOVE wild-type for each
+    integrase. A catalogue criterion over the frozen DOI'd panel, recovers the known hyperactive mutations, but
+    (like writer_verify.blind_recovery) is NOT a blind sequence-only predictor. Deterministic + CI-safe."""
+    panel = {k: v for k, v in _HYPERACTIVE.items()
+             if integrase is None or v["integrase"] == integrase}
+    by_int: dict = {}
+    for k, v in panel.items():
+        by_int.setdefault(v["integrase"], []).append((k, v["fold"]))
+    results = {}
+    for integ, items in by_int.items():
+        ranked = sorted(items, key=lambda kv: kv[1], reverse=True)
+        wt = next((f for k, f in items if k.endswith("_WT")), 1.0)
+        hyper = [k for k, f in items if f > 1.0]
+        top = ranked[0][0]
+        results[integ] = {
+            "n": len(items), "top": top, "wt_fold": wt,
+            "hyperactive_variants": hyper,
+            "all_hyperactive_outrank_wt": all(f > wt for k, f in items if not k.endswith("_WT")),
+            "ranking": [{"variant": k, "fold": f} for k, f in ranked],
+        }
+    return {"available": True, "model": "frozen_NAR2024_panel", "by_integrase": results,
+            "note": "recovers known serine-integrase hyperactive mutants (Hew NAR 2024 / Keravala 2009) above "
+                    "wild-type, a retrospective catalogue criterion, NOT a blind sequence-only predictor."}
+
+
+def lm_recovery(model: str = "esm3") -> dict:
+    """The HARD, falsifiable claim: can a protein LM rank the hyperactive mutants above WT *blind*? Attempts the
+    LM oracle; defers (no fabrication) when the model server is absent. Reports verbatim, including the expected
+    negative, since LMs score naturalness and hyperactive mutants are gain-of-function."""
+    try:
+        from pen_stack.oracles.protein_design import _oracle_net_enabled
+        if not _oracle_net_enabled():
+            raise RuntimeError("oracle net disabled")
+        # The ESM3 oracle is generative, not a per-variant fitness scorer; a clean blind per-variant likelihood
+        # endpoint is not exposed -> we do not fabricate a score. Defer with the scientific caveat.
+        return {"available": False, "model": model,
+                "note": "deferred: the protein-LM oracle is generative (no blind per-variant fitness endpoint). "
+                        "Scientifically, LM naturalness need NOT recover gain-of-function hyperactivity, this is "
+                        "reported as a known limitation, not a manufactured positive."}
+    except Exception: # noqa: BLE001
+        return {"available": False, "model": model,
+                "note": "deferred (model server / oracle net absent); see hyperactive_recovery (retrospective). "
+                        "LM naturalness != engineered hyperactivity (gain-of-function), limitation."}
+
+
+def score_writer_variants(integrase: str, variants: list[str]) -> list[WriterVariantScore]:
+    """Score serine-integrase variants against the frozen measured panel. Measured variants are claimable with
+    their fold; unmeasured variants are flagged NOT claimable (no activity asserted), the scope spine."""
+    out: list[WriterVariantScore] = []
+    for v in variants:
+        key = v if v in _HYPERACTIVE else f"{integrase}_{v}"
+        if key in _HYPERACTIVE:
+            rec = _HYPERACTIVE[key]
+            out.append(WriterVariantScore(v, rec["integrase"], rec["fold"], rec["fold"] > 1.0, True,
+                                          f"measured fold {rec['fold']}x over WT ({rec['basis']}; {rec['doi']})"))
+        else:
+            out.append(WriterVariantScore(v, integrase, float("nan"), False, False,
+                                          "not in the measured panel, plausibility only, NO activity claim"))
+    return out

pen_stack/env/__init__.py

@@ -0,0 +1 @@
+"""Optional Gymnasium interface for PEN-STACK. Requires the `[env]` extra (gymnasium)."""

pen_stack/env/genome_writing_env.py

@@ -0,0 +1,248 @@
+"""Gymnasium environment for genome-write planning, the train/eval surface.
+
+The interface began *thin* (insertion only) and is now a **full environment** whose state is
+a partial design across **all write types**, whose every action is checked by the **rule-grounded
+verifier** (`pen_stack.verify.verify`), and whose reward is the **legal, calibrated plan score** (the planner
+objective scaled by the L4 calibrated confidence, minus soft-rule penalties). An episode is a complete legal
+plan **or a justified refusal** (an explicit abstain action):
+
+    stage 0: WRITE TYPE -> stage 1: SITE -> stage 2: WRITER family ->
+    stage 3: CARGO bucket -> stage 4: DELIVERY vehicle -> terminate (verify -> reward)
+
+At any stage the agent may take the reserved **abstain** action (``action == action_space.n - 1``) and end
+the episode with a refusal: refusing beats committing to an *illegal* plan (refusal reward > illegal penalty),
+but a good legal plan beats refusing, the contract that makes "abstention over guessing" measurable.
+
+**Explicitly an INTERFACE + EVALUATION HARNESS, not an RL-superiority claim.** The genome-writing decision is
+near-one-shot; the greedy(planner) policy *is* the deterministic optimum and is the reference. No learned
+policy is claimed to beat it (the `greedy >= random` check is a sanity test, not a result). Behind the
+optional ``[env]`` extra (gymnasium); the rest of PEN-STACK does not import this module.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+try:
+    import gymnasium as gym
+    from gymnasium import spaces
+    _HAVE_GYM = True
+except Exception: # noqa: BLE001 - gymnasium only in the [env] extra
+    _HAVE_GYM = False
+    gym = None
+    spaces = None
+
+from pen_stack.planner.optimize import (
+    EditIntent,
+    load_intent_weights,
+    writer_activity_by_family,
+)
+
+WRITE_TYPES = ["insertion", "excision", "inversion", "replacement",
+               "regulatory_rewrite", "landing_pad_install", "multiplex"]
+WRITER_FAMILIES = ["bridge_IS110", "seek_IS1111", "CAST_VK", "serine_integrase",
+                   "PE_integrase", "Cas9", "Cas12a"]
+# writers whose output is DNA (AAV/lenti/HDAd-compatible). Cas9/Cas12a deliver RNP.
+_DNA_WRITERS = ["bridge_IS110", "seek_IS1111", "CAST_VK", "serine_integrase", "PE_integrase"]
+CARGO_BUCKETS = [1000, 3000, 6000, 12000, 30000] # bp
+_N_STAGES = 5
+
+# reward shaping constants (pre-registered in prereg/ws_env.yaml)
+_ILLEGAL_PENALTY = -1.0 # committing to an illegal plan is the worst outcome
+_ABSTAIN_REWARD = 0.05 # a justified refusal beats an illegal plan, loses to a good legal one
+_SOFT_PENALTY = 0.1 # per soft-rule flag (e.g. split-AAV efficiency)
+_CARGO_SHORT_PENALTY = 0.1 # chosen bucket smaller than the target insert
+
+
+def delivery_vehicles() -> list[str]:
+    from pen_stack.planner.delivery_vehicles import names
+    return list(names())
+
+
+def demo_candidates(n: int = 8, seed: int = 0) -> pd.DataFrame:
+    """A small synthetic candidate table (safety, p_durable, reachable_tier1) so the env runs without the
+    atlas. Real use passes the writability atlas rows instead."""
+    rng = np.random.default_rng(seed)
+    fams = [";".join(rng.choice(WRITER_FAMILIES, size=rng.integers(2, 5), replace=False)) for _ in range(n)]
+    return pd.DataFrame({"chrom": ["chr1"] * n, "bin": list(range(n)),
+                         "safety": rng.uniform(0.3, 0.95, n).round(3),
+                         "p_durable": rng.uniform(0.3, 0.95, n).round(3),
+                         "reachable_tier1": fams})
+
+
+def _base():
+    return gym.Env if _HAVE_GYM else object
+
+
+def writer_form(family: str | None) -> str:
+    """DNA for integrase/recombinase/prime-editor writers; RNP for Cas9/Cas12a."""
+    return "DNA" if family in _DNA_WRITERS else "RNP"
+
+
+class GenomeWritingEnv(_base()):
+    """Full Gymnasium environment over the router + verifier (see module docstring).
+
+    State = partial design; actions build it stage by stage; the terminal reward is the verifier's legality
+    gate times the L4 calibrated plan confidence. The reserved abstain action ends the episode with a refusal.
+    """
+    metadata = {"render_modes": []}
+
+    def __init__(self, candidates: pd.DataFrame | None = None,
+                 intent: str | EditIntent = "safe_harbour_insertion", cargo_bp: int = 3000, seed: int = 0):
+        if not _HAVE_GYM:
+            raise ImportError("GenomeWritingEnv needs the optional [env] extra: pip install pen-stack[env]")
+        super().__init__()
+        self.cands = (candidates if candidates is not None else demo_candidates(seed=seed)).reset_index(drop=True)
+        self.intent = EditIntent(intent) if not isinstance(intent, EditIntent) else intent
+        self.cargo_bp = int(cargo_bp) # target insert size the plan must accommodate
+        self.w = load_intent_weights()["intents"][self.intent.value]
+        self.activity = writer_activity_by_family()
+        self.vehicles = delivery_vehicles()
+        self.n_sites = len(self.cands)
+        self._stage_sizes = [len(WRITE_TYPES), self.n_sites, len(WRITER_FAMILIES),
+                             len(CARGO_BUCKETS), len(self.vehicles)]
+        # one fixed Discrete space sized to the largest stage + 1 reserved ABSTAIN action.
+        self._abstain = max(self._stage_sizes)
+        self.action_space = spaces.Discrete(self._abstain + 1)
+        # observation: [stage_frac, write_type_frac, site_safety, site_p_durable, writer_activity,
+        # cargo_frac, delivery_cap_frac, legal_flag]
+        self.observation_space = spaces.Box(low=0.0, high=1.0, shape=(8,), dtype=np.float32)
+        self._rng = np.random.default_rng(seed)
+        self.reset(seed=seed)
+
+    # ---- helpers -------------------------------------------------------------------------------
+    def _obs(self) -> np.ndarray:
+        site = self.cands.iloc[self._site] if self._site is not None else None
+        cap = 0.0
+        if self._delivery:
+            from pen_stack.planner.delivery_vehicles import vehicle
+            c = (vehicle(self._delivery) or {}).get("cargo_capacity_bp")
+            cap = min(1.0, (c or 0) / 100000.0)
+        return np.array([
+            self._stage / _N_STAGES,
+            (WRITE_TYPES.index(self._write_type) / len(WRITE_TYPES)) if self._write_type else 0.0,
+            float(site["safety"]) if site is not None else 0.0,
+            float(site["p_durable"]) if site is not None else 0.0,
+            float(self.activity.get(self._writer, 0.0)) if self._writer else 0.0,
+            (self._cargo / max(CARGO_BUCKETS)) if self._cargo else 0.0,
+            cap,
+            1.0 if self._legal else 0.0,
+        ], dtype=np.float32)
+
+    def site_options(self) -> list[int]:
+        return list(range(self.n_sites))
+
+    def writer_options(self) -> list[str]:
+        """Writer families reachable at the chosen site (tier-1 reachability), or all if no site yet."""
+        if self._site is None:
+            return WRITER_FAMILIES
+        return [f for f in str(self.cands.iloc[self._site]["reachable_tier1"]).split(";") if f] or WRITER_FAMILIES
+
+    def _build_design(self):
+        from pen_stack.rules import Design
+        site = self.cands.iloc[self._site] if self._site is not None else None
+        return Design(
+            write_type=self._write_type or "insertion",
+            writer_family=self._writer,
+            writer_output_form=writer_form(self._writer),
+            cargo_bp=self._cargo,
+            delivery_vehicle=self._delivery,
+            edit_intent=self.intent.value,
+            chrom=str(site["chrom"]) if site is not None else None,
+            # per-axis scores let the verifier attach a CALIBRATED confidence (no fabrication otherwise)
+            safety=float(site["safety"]) if site is not None else None,
+            p_durable=float(site["p_durable"]) if site is not None else None,
+            writer_activity=float(self.activity.get(self._writer, 0.4)),
+        )
+
+    # ---- Gymnasium API -------------------------------------------------------------------------
+    def reset(self, seed: int | None = None, options: dict | None = None):
+        super().reset(seed=seed) # seeds gymnasium's self.np_random (env-checker contract)
+        if seed is not None:
+            self._rng = np.random.default_rng(seed)
+        self._stage = 0
+        self._write_type = None
+        self._site = None
+        self._writer = None
+        self._cargo = None
+        self._delivery = None
+        self._legal = False
+        self._refused = False
+        return self._obs(), {"stage": "write_type"}
+
+    def step(self, action: int):
+        action = int(action)
+        reward, terminated, info = 0.0, False, {}
+        if action == self._abstain: # justified refusal -> end episode
+            self._refused = True
+            terminated = True
+            reward = _ABSTAIN_REWARD
+            info = {"stage": "refused", "abstained": True,
+                    "note": "refusal beats an illegal plan; loses to a good legal one"}
+            self._stage += 1
+            return self._obs(), float(reward), True, False, info
+
+        if self._stage == 0: # choose WRITE TYPE
+            self._write_type = WRITE_TYPES[action % len(WRITE_TYPES)]
+            info = {"stage": "site", "chose_write_type": self._write_type}
+        elif self._stage == 1: # choose SITE
+            self._site = self.site_options()[action % self.n_sites]
+            info = {"stage": "writer", "chose_site": int(self._site)}
+        elif self._stage == 2: # choose WRITER family
+            self._writer = WRITER_FAMILIES[action % len(WRITER_FAMILIES)]
+            info = {"stage": "cargo", "chose_writer": self._writer,
+                    "writer_reachable": self._writer in self.writer_options()}
+        elif self._stage == 3: # choose CARGO bucket
+            self._cargo = CARGO_BUCKETS[action % len(CARGO_BUCKETS)]
+            info = {"stage": "delivery", "chose_cargo_bp": self._cargo}
+        elif self._stage == 4: # choose DELIVERY vehicle -> terminate
+            self._delivery = self.vehicles[action % len(self.vehicles)]
+            reward, info = self._verified_reward()
+            terminated = True
+            info = {"stage": "done", "chose_delivery": self._delivery, **info, **self.plan()}
+        self._stage += 1
+        return self._obs(), float(reward), bool(terminated), False, info
+
+    # ---- reward = legality gate x calibrated plan score ----------------------------------------
+    def _verified_reward(self) -> tuple[float, dict]:
+        from pen_stack.verify import verify
+        design = self._build_design()
+        v = verify(design)
+        site = self.cands.iloc[self._site]
+        base = (self.w["safety"] * float(site["safety"])
+                + self.w["durability"] * float(site["p_durable"])
+                + self.w["activity"] * float(self.activity.get(self._writer, 0.4)))
+        meta = {"legal": v.legal, "deferred": v.deferred, "confidence": v.confidence,
+                "violations": [x["rule_id"] for x in v.violations],
+                "soft_flags": [s["rule_id"] for s in v.soft_flags]}
+        if v.deferred: # unsupported/ambiguous write type -> a deterministic refusal
+            self._refused = True
+            return _ABSTAIN_REWARD, {**meta, "note": "router deferred (unsupported write type)"}
+        if not v.legal: # committed to an illegal plan -> worst outcome
+            self._legal = False
+            return _ILLEGAL_PENALTY, meta
+        self._legal = True
+        conf = v.confidence if v.confidence is not None else 0.5
+        reward = base * (0.5 + 0.5 * conf) - _SOFT_PENALTY * len(v.soft_flags)
+        if self._cargo is not None and self._cargo < self.cargo_bp:
+            reward -= _CARGO_SHORT_PENALTY
+        return float(reward), meta
+
+    def plan(self) -> dict:
+        return {"write_type": self._write_type,
+                "site": None if self._site is None else int(self._site),
+                "writer": self._writer, "cargo_bp": self._cargo, "delivery": self._delivery,
+                "intent": self.intent.value, "legal": self._legal, "refused": self._refused}
+
+
+# re-export the reference policies + rollout helpers (defined in policies.py) for backward-compatible imports
+from pen_stack.env.policies import ( # noqa: E402
+    compare_policies,
+    greedy_planner_policy,
+    random_policy,
+    rollout,
+)
+
+__all__ = ["WRITE_TYPES", "WRITER_FAMILIES", "CARGO_BUCKETS", "GenomeWritingEnv", "demo_candidates",
+           "delivery_vehicles", "writer_form", "random_policy", "greedy_planner_policy", "rollout",
+           "compare_policies"]

pen_stack/env/policies.py

@@ -0,0 +1,94 @@
+"""Reference policies + rollout for the genome-writing environment.
+
+Two reference policies run end-to-end in `GenomeWritingEnv`:
+
+* ``random_policy``, uniform over the (fixed) action space, including the reserved abstain action.
+* ``greedy_planner_policy``, the **deterministic optimum**: it reproduces the planner's choices stage by
+  stage and always assembles a *rule-legal* plan (a writer/cargo/delivery combination the verifier accepts),
+  so it is the reference an RL agent is compared against. **No RL superiority is claimed**, the env is an
+  interface + evaluation harness for a near-one-shot decision; ``greedy >= random`` is a sanity check, not a
+  result.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from pen_stack.env.genome_writing_env import (
+    CARGO_BUCKETS,
+    WRITE_TYPES,
+    WRITER_FAMILIES,
+    GenomeWritingEnv,
+    demo_candidates,
+    writer_form,
+)
+
+
+def random_policy(env: GenomeWritingEnv, obs, rng) -> int:
+    return int(rng.integers(0, env.action_space.n))
+
+
+def _best_delivery_index(env: GenomeWritingEnv, form: str, cargo: int) -> int:
+    """Smallest-capacity vehicle compatible with the writer's output form that fits the cargo (a legal,
+    efficient choice); falls back to a physical (no-capacity) compatible vehicle."""
+    from pen_stack.planner.delivery_vehicles import vehicle
+    finite, physical = [], []
+    for i, name in enumerate(env.vehicles):
+        veh = vehicle(name) or {}
+        if form not in veh.get("compatible_cargo_form", []):
+            continue
+        cap = veh.get("cargo_capacity_bp")
+        if cap is None:
+            physical.append(i)
+        elif cap >= cargo:
+            finite.append((cap, i))
+    if finite:
+        return min(finite)[1]
+    if physical:
+        return physical[0]
+    return 0
+
+
+def greedy_planner_policy(env: GenomeWritingEnv, obs, rng) -> int:
+    """The deterministic optimum at each stage: the supported write type, the best site by base score, its
+    highest-activity reachable writer, the smallest cargo bucket that fits, and a form-compatible vehicle."""
+    if env._stage == 0: # WRITE TYPE: insertion (fully supported)
+        return WRITE_TYPES.index("insertion")
+    if env._stage == 1: # SITE: best base score
+        scores = [(env.w["safety"] * float(r["safety"]) + env.w["durability"] * float(r["p_durable"]))
+                  for _, r in env.cands.iterrows()]
+        return int(np.argmax(scores))
+    if env._stage == 2: # WRITER: highest-activity reachable (prefer DNA)
+        reachable = env.writer_options()
+        dna = [f for f in reachable if writer_form(f) == "DNA"] or reachable
+        best = max(dna, key=lambda f: env.activity.get(f, 0.0))
+        return WRITER_FAMILIES.index(best)
+    if env._stage == 3: # CARGO: smallest bucket that fits the target
+        fits = [i for i, b in enumerate(CARGO_BUCKETS) if b >= env.cargo_bp] or [len(CARGO_BUCKETS) - 1]
+        return fits[0]
+    # DELIVERY: smallest-capacity vehicle compatible with the writer's output form
+    return _best_delivery_index(env, writer_form(env._writer), env._cargo or env.cargo_bp)
+
+
+def rollout(env: GenomeWritingEnv, policy, seed: int = 0) -> dict:
+    """Run one episode under `policy`; return the cumulative reward + the assembled plan."""
+    rng = np.random.default_rng(seed)
+    obs, _ = env.reset(seed=seed)
+    total, term, info = 0.0, False, {}
+    while not term:
+        a = policy(env, obs, rng)
+        obs, r, term, _trunc, info = env.step(a)
+        total += r
+    return {"reward": round(total, 4), "plan": env.plan(), "terminal_info": info}
+
+
+def compare_policies(seed: int = 0) -> dict:
+    """Run the random and greedy(planner) policies on the same env, the interface smoke + sanity check. The
+    greedy policy is the deterministic optimum and assembles a legal plan; RL is NOT claimed to beat it."""
+    rnd = rollout(GenomeWritingEnv(candidates=demo_candidates(n=8, seed=seed), seed=seed),
+                  random_policy, seed=seed)
+    grd = rollout(GenomeWritingEnv(candidates=demo_candidates(n=8, seed=seed), seed=seed),
+                  greedy_planner_policy, seed=seed)
+    return {"random": rnd, "greedy_planner": grd,
+            "greedy_at_least_random": bool(grd["reward"] >= rnd["reward"]),
+            "greedy_plan_legal": bool(grd["plan"]["legal"]),
+            "note": "interface only, greedy(planner) is the deterministic optimum; no RL superiority claimed."}

pen_stack/graph/__init__.py

@@ -0,0 +1,21 @@
+"""The living world-model knowledge graph.
+
+`pen_stack.graph` promotes the 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/graph/build.py

@@ -0,0 +1,133 @@
+"""Build the world-model knowledge graph from the curated tables.
+
+Parity-first (risk register): the graph is assembled from the SAME validated sources the 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 scope: 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"), "ontology": card.get("efo") or card.get("ontology"),
+            "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 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