pen-stack 0.1.0__py3-none-any.whl

pen_stack/planner/multiplex.py

@@ -0,0 +1,110 @@
+"""Multiplex translocation-risk flag.
+
+For a multi-edit plan (2-5 edits), two simultaneous double-strand breaks (DSBs) at different loci can
+mis-join into a TRANSLOCATION. This is a classical, interpretable SCREEN - not a calibrated translocation
+predictor. We gather every edit's DSB sites (on-target + predicted off-targets, each with a cut probability),
+enumerate all site PAIRS exactly (cheap for 2-5 edits), and combine pairwise DSB-join probabilities into a
+`translocation_risk` in [0,1].
+
+Key property: **DSB-free writers (bridge / seek recombinases) contribute NO cut sites**, so a plan
+built from them carries ~zero translocation risk - which is the whole point of programmable recombinases.
+The flag is monotonic (more sites / higher cut prob / closer pairs -> higher risk) and reports its top pairs
+so a user can see WHY. A QUBO formulation is provided as a documented OPTIONAL baseline, off by default.
+"""
+from __future__ import annotations
+
+import math
+from itertools import combinations
+
+# writer families that cut DNA (DSB) vs DSB-free programmable recombinases / writers.
+_DSB_FREE = {"bridge_is110", "bridge_iscro4", "seek_is1111", "bridge", "seek", "pe_integrase",
+             "prime_editor", "recombinase"}
+_DEFAULT_ON_TARGET_CUT = 0.8 # nominal on-target cut efficiency for a DSB nuclease (documented prior)
+_INTRA_CHROM_LENGTH = 1.0e7 # bp decay length for intra-chromosomal join propensity (10 Mb)
+
+
+def is_dsb_free(family: str | None) -> bool:
+    return str(family or "").lower() in _DSB_FREE
+
+
+def cut_sites(edit: dict) -> list[dict]:
+    """DSB sites for one edit. DSB-free writers -> []. Otherwise on-target (+ off-targets if provided).
+
+    `edit` keys: family, chrom, pos (on-target); optional on_target_cut; optional offtargets=[{chrom,pos,
+    p_cut|risk}]. Off-target risk in [0,1] is used directly as a cut probability.
+    """
+    if is_dsb_free(edit.get("family")):
+        return []
+    sites = []
+    if edit.get("chrom") is not None and edit.get("pos") is not None:
+        sites.append({"chrom": edit["chrom"], "pos": int(edit["pos"]),
+                      "p_cut": float(edit.get("on_target_cut", _DEFAULT_ON_TARGET_CUT)),
+                      "kind": "on_target", "edit": edit.get("name")})
+    for ot in edit.get("offtargets", []) or []:
+        p = float(ot.get("p_cut", ot.get("risk", 0.0)))
+        if p > 0 and ot.get("chrom") is not None and ot.get("pos") is not None:
+            sites.append({"chrom": ot["chrom"], "pos": int(ot["pos"]), "p_cut": min(1.0, p),
+                          "kind": "off_target", "edit": edit.get("name")})
+    return sites
+
+
+def _join_factor(a: dict, b: dict) -> float:
+    """Propensity that two DSBs mis-join: 1.0 inter-chromosomal; distance-decayed intra-chromosomal."""
+    if a["chrom"] != b["chrom"]:
+        return 1.0
+    d = abs(a["pos"] - b["pos"])
+    return math.exp(-d / _INTRA_CHROM_LENGTH)
+
+
+def pairwise_risks(sites: list[dict]) -> list[dict]:
+    """Exact pairwise DSB-join probabilities for every unordered site pair (across and within edits)."""
+    out = []
+    for i, j in combinations(range(len(sites)), 2):
+        a, b = sites[i], sites[j]
+        jp = a["p_cut"] * b["p_cut"] * _join_factor(a, b)
+        out.append({"a": f"{a['edit']}:{a['kind']}@{a['chrom']}:{a['pos']}",
+                    "b": f"{b['edit']}:{b['kind']}@{b['chrom']}:{b['pos']}",
+                    "inter_chromosomal": a["chrom"] != b["chrom"], "join_prob": round(jp, 5)})
+    return sorted(out, key=lambda r: r["join_prob"], reverse=True)
+
+
+def translocation_risk(edits: list[dict], low: float = 0.05, moderate: float = 0.2,
+                       top_k: int = 5) -> dict:
+    """Aggregate translocation-risk flag for a multi-edit plan. risk = 1 - prod(1 - pairwise_join_prob).
+
+    Monotonic in every pairwise probability; interpretable via the top contributing pairs. A SCREEN, not a
+    calibrated predictor.
+    """
+    if not 2 <= len(edits) <= 5:
+        # still computes, but the flag is meant for multiplex (2-5 simultaneous edits)
+        note = "translocation risk is defined for multiplex plans (2-5 simultaneous edits)"
+    else:
+        note = None
+    sites = [s for e in edits for s in cut_sites(e)]
+    pairs = pairwise_risks(sites)
+    prod = 1.0
+    for p in pairs:
+        prod *= (1.0 - p["join_prob"])
+    risk = round(1.0 - prod, 5)
+    band = "low" if risk < low else ("moderate" if risk < moderate else "high")
+    n_dsb_free = sum(1 for e in edits if is_dsb_free(e.get("family")))
+    return {"translocation_risk": risk, "band": band, "n_edits": len(edits),
+            "n_cut_sites": len(sites), "n_pairs": len(pairs),
+            "n_dsb_free_edits": n_dsb_free,
+            "all_dsb_free": n_dsb_free == len(edits),
+            "top_pairs": pairs[:top_k],
+            "note": note,
+            "scope": "classical pairwise DSB-join SCREEN, not a calibrated translocation predictor; "
+                     "DSB-free recombinase plans carry ~zero risk by construction"}
+
+
+def qubo_baseline(edits: list[dict], variants_per_edit: dict[str, list[dict]] | None = None) -> dict:
+    """OPTIONAL, OFF BY DEFAULT - a documented QUBO baseline for selecting per-edit guide variants that
+    minimize total pairwise translocation risk. Returns the QUBO Q-matrix terms only; no solver is invoked
+    and this is NOT the recommended path (the exact pairwise screen above is exact for 2-5 edits). Provided
+    for completeness / external comparison, clearly labeled optional.
+    """
+    return {"enabled": False, "kind": "QUBO (optional baseline)",
+            "note": "exact pairwise enumeration is tractable and exact for 2-5 edits; the QUBO path is an "
+                    "optional baseline for large multiplex selection problems and is off by default.",
+            "n_variant_sets": len(variants_per_edit or {})}

pen_stack/planner/optimize.py

@@ -0,0 +1,278 @@
+"""Inverse-design optimiser with edit_intent.
+
+Given a goal (gene/locus, edit_intent, cargo, cell type), search destination x writer for the joint
+optimum of safety x durability x reachability x writer-activity, conditioned on an explicit
+``edit_intent``. The intent is *load-bearing*: its ``target_gene_sign`` decides whether hitting the
+named target gene/element is penalised (safe-harbour: avoid) or rewarded (knock-in / excision: intended)
+- so the same locus ranks high or low depending only on the stated goal.
+
+Components are retained on every candidate row; the score is a transparent linear combination read from
+``configs/intent_weights.yaml``. Reachability is a hard filter (Tier-1 high-confidence; Tier-2 candidate
+flagged). Writer activity comes from the Writer Atlas (measured human-cell axis per family).
+
+Inputs : writability atlas (safety/p_durable/reachable_tier1) + atlas.parquet.
+Outputs: ranked (writer, site) candidates with full component provenance.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import yaml
+
+_ROOT = Path(__file__).resolve().parents[2]
+_CFG = _ROOT / "configs" / "intent_weights.yaml"
+_ATLAS = _ROOT / "pen_stack" / "atlas" / "atlas.parquet"
+BIN_BP = 1000
+
+
+class EditIntent(str, Enum):
+    SAFE_HARBOUR = "safe_harbour_insertion"
+    LANDING_PAD = "landing_pad_insertion"
+    KNOCK_IN_DISRUPT = "knock_in_with_disruption"
+    HIGH_DURABILITY = "high_durability_insertion"
+    REG_EXCISION = "regulatory_element_excision"
+    REPEAT_EXCISION = "repeat_excision"
+
+    @classmethod
+    def _missing_(cls, value):  # backward-compat aliases so older callers / the earlier value still resolve
+        return {"regulatory_excision": cls.REG_EXCISION, "landing_pad": cls.LANDING_PAD}.get(str(value))
+
+
+@lru_cache(maxsize=1)
+def load_intent_weights(path: str | Path = _CFG) -> dict:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def writer_activity_by_family(atlas_path: str | Path = _ATLAS) -> dict:
+    """Per-family writer-activity proxy from the Writer Atlas curated cores (measured human-cell axis).
+
+    Falls back to readiness when S_HumanCell is missing. Used so the optimiser prefers writers that
+    actually work in human cells (e.g. bridge ISCro4) over weakly-active families.
+    """
+    atlas = pd.read_parquet(atlas_path)
+    core = atlas[atlas["entry_kind"] == "curated_core"] if "entry_kind" in atlas else atlas
+    act = {}
+    for fam, sub in core.groupby("family"):
+        r = sub.iloc[0]
+        a = r.get("S_HumanCell")
+        if a is None or pd.isna(a):
+            a = r.get("readiness", 0.5)
+        act[fam] = float(a) if pd.notna(a) else 0.5
+    return act
+
+
+def _best_writer(reachable_tier1: str, cargo_bp: int, atlas_caps: dict, activity: dict) -> tuple[str, float, bool]:
+    """Pick the best reachable writer that fits the cargo: (family, activity, cargo_ok)."""
+    fams = [f for f in str(reachable_tier1).split(";") if f]
+    best, best_act, best_ok = None, -1.0, False
+    for f in fams:
+        cap = atlas_caps.get(f)
+        ok = (cap is None) or (cargo_bp <= cap)
+        a = activity.get(f, 0.4)
+        # prefer cargo-fitting writers; among those, highest activity
+        rank = (1 if ok else 0, a)
+        if rank > (1 if best_ok else 0, best_act):
+            best, best_act, best_ok = f, a, ok
+    return best or (fams[0] if fams else "unknown"), best_act if best else 0.4, best_ok
+
+
+def score_candidates(cands: pd.DataFrame, intent: EditIntent | str, cargo_bp: int) -> pd.DataFrame:
+    """Score a candidate DataFrame (needs: safety, p_durable, reachable_tier1, on_target[bool]).
+
+    Adds: writer (family), writer_activity, cargo_ok, score, and the retained components.
+    """
+    intent = EditIntent(intent) if not isinstance(intent, EditIntent) else intent
+    cfg = load_intent_weights()
+    w = cfg["intents"][intent.value]
+    mag = float(cfg.get("on_target_magnitude", 1.0))
+
+    atlas = pd.read_parquet(_ATLAS)
+    caps = (atlas.dropna(subset=["cargo_capacity_bp"]).groupby("family")["cargo_capacity_bp"].max().to_dict())
+    activity = writer_activity_by_family()
+
+    out = cands.copy()
+    picks = out["reachable_tier1"].apply(lambda rt: _best_writer(rt, cargo_bp, caps, activity))
+    out["writer"] = [p[0] for p in picks]
+    out["writer_activity"] = [p[1] for p in picks]
+    out["cargo_ok"] = [p[2] for p in picks]
+
+    on_target = out.get("on_target", pd.Series(False, index=out.index)).astype(float)
+    base = (w["safety"] * out["safety"].astype(float)
+            + w["durability"] * out["p_durable"].astype(float)
+            + w["activity"] * out["writer_activity"].astype(float))
+    # target_gene_sign: +1 -> penalise on-target (avoid the gene); -1 -> reward on-target (hit the gene)
+    out["score"] = base - w["target_gene_sign"] * mag * on_target
+    # cargo that cannot be delivered by any reachable writer is penalised
+    out.loc[~out["cargo_ok"], "score"] -= 0.5
+    # HARD GENOTOXICITY GATE (every intent): a locus below the safety floor sits in the oncogene/essential-gene
+    # danger zone. Flag it (`genotoxic`) so the UI warns, and DEMOTE it below every safe site -- UNLESS it is the
+    # intended on-target of a gene-TARGETING intent (target_gene_sign < 0), where the user chose to hit this locus,
+    # so a warning (not a block) is correct. This stops a durability-first intent from top-ranking oncogene-adjacent
+    # sites as if they were fine.
+    floor = float(cfg.get("safety_floor", 0.5))
+    penalty = float(cfg.get("unsafe_penalty", 5.0))
+    unsafe = out["safety"].astype(float) < floor
+    out["genotoxic"] = unsafe
+    intended_hit = on_target.astype(bool) if w["target_gene_sign"] < 0 else pd.Series(False, index=out.index)
+    out["score"] = out["score"] - penalty * (unsafe & ~intended_hit).astype(float)
+    out["intent"] = intent.value
+    # Deterministic ranking: a stable sort with explicit tie-breakers, so tied scores (common when safety
+    # saturates) always resolve identically across runs - the default quicksort is NOT stable.
+    keys = ["score"] + [c for c in ("chrom", "bin", "gene") if c in out.columns]
+    asc = [False] + [True] * (len(keys) - 1)
+    return out.sort_values(keys, ascending=asc, kind="stable").reset_index(drop=True)
+
+
+# ---------------------------------------------------------------- plan-level confidence (uncertainty propagation)
+
+# Default per-axis conformal half-widths used when an explicit uncertainty calibration is not supplied. These are
+# documented placeholders, not magic numbers: ``durability`` is the widest because the durability signal is
+# the weakest (silenced-AUROC ~0.65); ``safety`` and ``activity`` are tighter. A caller that has run
+# the conformal calibration (validate/uncertainty_eval) passes the measured half-widths instead.
+DEFAULT_AXIS_HALF_WIDTHS = {"safety": 0.10, "durability": 0.15, "activity": 0.10}
+
+
+def _axis_intervals(row, half_widths: dict, ood_factor: float = 1.0) -> dict:
+    """Per-axis {point, lo, hi} for a candidate, intervals widened by the OOD factor."""
+    cols = {"safety": "safety", "durability": "p_durable", "activity": "writer_activity"}
+    out = {}
+    for axis, col in cols.items():
+        p = float(row[col]) if col in row and pd.notna(row[col]) else 0.5
+        h = float(half_widths.get(axis, 0.1)) * float(ood_factor)
+        out[axis] = {"point": p, "lo": max(0.0, p - h), "hi": min(1.0, p + h)}
+    return out
+
+
+def attach_uncertainty(scored: pd.DataFrame, intent: EditIntent | str,
+                       half_widths: dict | None = None, ood_factor=None,
+                       threshold: float = 0.5, abstain_below: float = 0.5) -> pd.DataFrame:
+    """Propagate per-axis conformal intervals into a plan-level confidence + epistemic status.
+
+    Additive: takes the output of :func:`score_candidates`/:func:`plan` and appends ``confidence``,
+    ``score_lo``/``score_hi`` (90% plan-score band), ``abstain`` and ``epistemic_status`` per plan, using
+    :func:`selective_prediction.propagate_plan_confidence` over the intent's axis weights. ``ood_factor`` may
+    be a scalar or a per-row sequence (from :class:`wgenome.ood.OODDetector.widen_factor`) so out-of-
+    distribution sites get wider bands and lower confidence - the grounded-confident vs grounded-
+    extrapolating distinction. Does not change the existing ranking columns.
+    """
+    from pen_stack.validate.selective_prediction import propagate_plan_confidence
+    intent = EditIntent(intent) if not isinstance(intent, EditIntent) else intent
+    w = load_intent_weights()["intents"][intent.value]
+    weights = {"safety": w["safety"], "durability": w["durability"], "activity": w["activity"]}
+    half_widths = half_widths or DEFAULT_AXIS_HALF_WIDTHS
+    out = scored.copy().reset_index(drop=True)
+    if ood_factor is None:
+        ood_factor = [1.0] * len(out)
+    elif np.isscalar(ood_factor):
+        ood_factor = [float(ood_factor)] * len(out)
+
+    conf, lo, hi, status, abst = [], [], [], [], []
+    for i, row in out.iterrows():
+        of = float(ood_factor[i])
+        axes = _axis_intervals(row, half_widths, of)
+        prop = propagate_plan_confidence(axes, weights, threshold=threshold)
+        c = prop["confidence"]
+        conf.append(round(c, 4))
+        lo.append(round(prop["lo"], 4))
+        hi.append(round(prop["hi"], 4))
+        is_abstain = bool(c < abstain_below)
+        abst.append(is_abstain)
+        if of >= 1.5:
+            status.append("grounded-extrapolating")
+        elif is_abstain:
+            status.append("not-computable")
+        else:
+            status.append("grounded-confident")
+    out["confidence"] = conf
+    out["score_lo"] = lo
+    out["score_hi"] = hi
+    out["abstain"] = abst
+    out["epistemic_status"] = status
+    return out
+
+
+def mechanistic_filter(reachable_tier1: str, site_seq: str, installed_att: bool = False) -> dict:
+    """Hard sequence-level reachability filter on a concrete site.
+
+    Given the WT-KB Tier-1 writer list (the ``reachable_tier1`` string) and the site's sequence, drop writers
+    whose required targeting element (PAM / core dinucleotide / att) is absent, a physically impossible
+    writer, site pairing is rejected. Returns the surviving family list + the rejections (with reasons). Called
+    by the Planner/agent only when a concrete site sequence is available; the bulk bin ranking is unchanged.
+    """
+    from pen_stack.planner.target_site import filter_reachable
+    fams = [f for f in str(reachable_tier1).split(";") if f]
+    res = filter_reachable(fams, site_seq, installed_att=installed_att)
+    res["reachable_str"] = ";".join(res["reachable"])
+    return res
+
+
+def gene_coords_path() -> Path:
+    """Locate gene_coords.parquet: packaged copy first (works in any container), then phase_1."""
+    for p in (_ROOT / "data" / "curated" / "gene_coords.parquet",
+              _ROOT.parent / "phase_1" / "app_data" / "gene_coords.parquet"):
+        if p.exists():
+            return p
+    return _ROOT / "data" / "curated" / "gene_coords.parquet"
+
+
+@lru_cache(maxsize=8)
+def _gene_coords(path: str | None = None) -> pd.DataFrame:
+    return pd.read_parquet(Path(path) if path else gene_coords_path())
+
+
+# Genomic safe-harbour *locus nicknames* are not HGNC gene symbols, so they are absent from gene_coords; map the
+# well-documented ones to their host gene so a user who types the common name still gets a plan. AAVS1 = intron 1
+# of PPP1R12C (19q13.42); H11/Hipp11 = an intron of EIF4ENIF1 (22q12). (CCR5, CLYBL, HPRT1 are real symbols.)
+_GSH_ALIASES = {"AAVS1": "PPP1R12C", "H11": "EIF4ENIF1", "HIPP11": "EIF4ENIF1"}
+
+
+def resolve_gene(gene: str) -> str:
+    """Map a safe-harbour locus nickname (e.g. AAVS1) to its HGNC host gene, and normalise a real symbol to the
+    exact casing stored in the coordinate table so 'lmo2' resolves like 'LMO2' (case-insensitive match). This
+    preserves legitimately mixed-case symbols (e.g. C1orf43) by returning the stored spelling, not a blind upper().
+    An unknown symbol -- or an absent coords table -- passes through with surrounding whitespace stripped."""
+    sym = _GSH_ALIASES.get(str(gene).strip().upper(), str(gene).strip())
+    try:
+        gc = _gene_coords()
+        hit = gc.loc[gc["gene"].str.upper() == sym.upper(), "gene"]
+        if len(hit):
+            return str(hit.iloc[0])
+    except Exception:  # noqa: BLE001 - coords table absent -> fall back to the stripped symbol
+        pass
+    return sym
+
+
+def gene_region(gene: str, flank_kb: int = 50) -> tuple[str, int, int] | None:
+    gc = _gene_coords()
+    g = gc[gc["gene"] == resolve_gene(gene)]
+    if g.empty:
+        return None
+    r = g.iloc[0]
+    return r["chrom"], max(0, int(r["start"]) - flank_kb * 1000), int(r["end"]) + flank_kb * 1000
+
+
+def plan(gene: str, intent: EditIntent | str, cargo_bp: int, writable_df: pd.DataFrame,
+         k: int = 10, flank_kb: int = 50) -> pd.DataFrame:
+    """Rank (writer, site) candidates near a gene for the given intent. Components retained."""
+    intent = EditIntent(intent) if not isinstance(intent, EditIntent) else intent
+    reg = gene_region(gene, flank_kb)
+    if reg is None:
+        return pd.DataFrame()
+    chrom, lo, hi = reg
+    sub = writable_df[(writable_df["chrom"] == chrom)
+                      & (writable_df["bin"].between(lo // BIN_BP, hi // BIN_BP))].copy()
+    if sub.empty:
+        return pd.DataFrame()
+    # on_target = bin overlaps the gene body (not just the flank)
+    g = _gene_coords()
+    gr = g[g["gene"] == resolve_gene(gene)].iloc[0]
+    sub["on_target"] = sub["bin"].between(int(gr["start"]) // BIN_BP, int(gr["end"]) // BIN_BP)
+    scored = score_candidates(sub, intent, cargo_bp)
+    cols = ["chrom", "bin", "writer", "safety", "p_durable", "writer_activity",
+            "on_target", "genotoxic", "cargo_ok", "reachable_tier1", "score", "intent"]
+    return scored[[c for c in cols if c in scored.columns]].head(k)

pen_stack/planner/pipeline.py

@@ -0,0 +1,87 @@
+"""End-to-end Write Planner.
+
+One call - ``plan_write(gene, intent, payload_bp, ct)`` - composes the inverse-design optimiser,
+cargo/donor design, and delivery recommendation into ranked, fully traceable plans. Every
+numeric field is tagged with the module/dataset that produced it (provenance), so nothing is asserted
+without a source. Heavy data (the writability atlas) is loaded lazily via the cross-link.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+import pandas as pd
+
+from pen_stack.planner.cargo import design_cargo
+from pen_stack.planner.delivery import recommend_delivery
+from pen_stack.planner.optimize import EditIntent, plan
+
+_ATLAS = Path(__file__).resolve().parents[1] / "atlas" / "atlas.parquet"
+BIN_BP = 1000
+
+
+@lru_cache(maxsize=1)
+def _writer_meta() -> dict:
+    """family -> {length_aa, cargo_capacity_bp, deliv_class, reachability_tier} from the Writer Atlas."""
+    atlas = pd.read_parquet(_ATLAS)
+    core = atlas[atlas["entry_kind"] == "curated_core"] if "entry_kind" in atlas else atlas
+    meta = {}
+    for fam, sub in core.groupby("family"):
+        r = sub.iloc[0]
+        meta[fam] = {
+            "length_aa": (int(r["length_aa"]) if pd.notna(r.get("length_aa")) else None),
+            "cargo_capacity_bp": (int(r["cargo_capacity_bp"]) if pd.notna(r.get("cargo_capacity_bp")) else None),
+            "deliv_class": r.get("deliv_class"),
+            "reachability_tier": r.get("reachability_tier"),
+        }
+    return meta
+
+
+def plan_write(gene: str, intent: EditIntent | str, payload_bp: int, ct: str = "k562",
+               k: int = 5, writable_df: pd.DataFrame | None = None) -> list[dict]:
+    """Return ranked, traceable write plans for a goal. Each plan = site + writer + cargo + delivery."""
+    if writable_df is None:
+        from pen_stack.atlas.crosslink import load_writability
+        writable_df = load_writability(ct)
+    cands = plan(gene, intent, payload_bp, writable_df, k=k)
+    meta = _writer_meta()
+    plans = []
+    for _, row in cands.iterrows():
+        fam = row["writer"]
+        wm = meta.get(fam, {})
+        writer_row = {"family": fam, "cargo_capacity_bp": wm.get("cargo_capacity_bp"),
+                      "deliv_class": wm.get("deliv_class")}
+        site = (row["chrom"], int(row["bin"]) * BIN_BP)
+        cargo = design_cargo(payload_bp, writer_row, site, ct)
+        eff_bp = (wm.get("length_aa") or 0) * 3
+        deliv = recommend_delivery(eff_bp, payload_bp, ct)
+        plans.append({
+            "gene": gene, "intent": EditIntent(intent).value if not isinstance(intent, EditIntent) else intent.value,
+            "site": {"chrom": row["chrom"], "bin": int(row["bin"]), "pos": site[1]},
+            "writer": fam,
+            "reachability_tier": wm.get("reachability_tier"),
+            "safety": round(float(row["safety"]), 4),
+            "durability": round(float(row["p_durable"]), 4),
+            "writer_activity": round(float(row["writer_activity"]), 4),
+            "on_target": bool(row["on_target"]),
+            "genotoxic": bool(row["genotoxic"]) if "genotoxic" in row else False,  # safety below the floor -> onco/essential zone
+            "score": round(float(row["score"]), 4),
+            "cargo": cargo,
+            "delivery": deliv,
+            "provenance": {
+                "safety": "wgenome.safety (LightGBM, COSMIC/DepMap/MLV)",
+                "durability": "wgenome.durability (TRIP conditional chromatin model)",
+                "writer_activity": "atlas.score.therapeutic (measured human-cell axis)",
+                "reachability": "atlas.crosslink (reachable_tier1 + WT-KB tier)",
+                "delivery": "planner.delivery (configs/delivery_rules.yaml)",
+                "offtargets": "planner.cargo (bridge engine)",
+            },
+            "disclaimer": "Decision-support only; not a clinical directive. Tier-2/3 reachability is candidate.",
+        })
+    return plans
+
+
+if __name__ == "__main__": # pragma: no cover
+    import json
+    ps = plan_write("TRAC", EditIntent.KNOCK_IN_DISRUPT, 2000, "k562", k=3)
+    print(json.dumps(ps[0], indent=2, default=str)[:1200])

pen_stack/planner/report.py

@@ -0,0 +1,26 @@
+"""Human-readable Write Planner report."""
+from __future__ import annotations
+
+
+def render_plan(p: dict) -> str:
+    s = p["site"]
+    lines = [
+        f"Write plan for {p['gene']} (intent: {p['intent']})",
+        f" Site : {s['chrom']}:{s['pos']:,} (bin {s['bin']}, on_target={p['on_target']})",
+        f" Writer : {p['writer']} [reachability {p['reachability_tier']}]",
+        f" Scores : safety {p['safety']} | durability {p['durability']} | "
+        f"writer-activity {p['writer_activity']} | score {p['score']}",
+        f" Cargo : payload {p['cargo']['payload_bp']} bp -> assembled {p['cargo']['assembled_bp']} bp "
+        f"(size_ok={p['cargo']['size_ok']}, codon-optimised, insulated)",
+        f" Delivery : {p['delivery']['delivery']} ({p['delivery']['rationale']})",
+    ]
+    if "offtargets" in p["cargo"]:
+        lines.append(f" Off-target : {p['cargo']['offtargets'].get('status', p['cargo']['offtargets'])}")
+    lines.append(f" Note : {p['disclaimer']}")
+    return "\n".join(lines)
+
+
+def render_plans(plans: list[dict]) -> str:
+    if not plans:
+        return "No plan found (gene not in the atlas, or no reachable site)."
+    return f"\n{'='*72}\n".join(f"[rank {i+1}]\n{render_plan(p)}" for i, p in enumerate(plans))

pen_stack/planner/router.py

@@ -0,0 +1,57 @@
+"""Write-type router.
+
+The earlier pipeline handled one workflow, single insertion. ``route(design)`` makes that the *insertion
+sub-graph* of a router that dispatches on ``write_type`` (insertion / excision / inversion / replacement /
+regulatory_rewrite / landing_pad_install / multiplex), selecting the relevant rule subset + steps per type.
+An unsupported or ambiguous write type **defers** (scope flag), it never guesses. Rarer types ship as
+legality/reachability coverage first (status `coverage_only`), stated.
+
+The router selects *which rules apply*; the solver still evaluates them. Routing + legality compose
+into the verifier.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.rules import Design, load_ruleset
+from pen_stack.rules.solver import evaluate, is_legal
+
+
+@lru_cache(maxsize=1)
+def load_write_types(path=None) -> dict:
+    p = resource("configs/write_types.yaml") if path is None else path
+    return yaml.safe_load(open(p, encoding="utf-8").read())["write_types"]
+
+
+def route(design: Design) -> dict:
+    """Dispatch a design to its write-type sub-graph. Unsupported/ambiguous -> deferred (scope flag)."""
+    wt = (design.write_type or "").strip()
+    table = load_write_types()
+    if wt not in table:
+        return {"write_type": wt, "supported": False, "deferred": True,
+                "reason": f"unsupported/ambiguous write type {wt!r}; supported: {sorted(table)}",
+                "rule_categories": [], "steps": []}
+    spec = table[wt]
+    return {"write_type": wt, "supported": True, "deferred": False,
+            "status": spec["status"], "rule_categories": spec["rule_categories"],
+            "steps": spec["steps"], "writer_classes": spec.get("writer_classes", []),
+            "coverage_only": spec["status"] == "coverage_only",
+            "scope_note": spec.get("scope_note"),
+            "description": spec["description"]}
+
+
+def route_and_evaluate(design: Design) -> dict:
+    """Route, then evaluate ONLY the routed rule categories against the design. Returns routing + legality."""
+    routing = route(design)
+    if routing["deferred"]:
+        return {"routing": routing, "legal": None, "deferred": True, "rule_results": []}
+    cats = set(routing["rule_categories"])
+    rs = load_ruleset()
+    sub = [r for r in rs.rules if r.category in cats]
+    from pen_stack.rules.schema import Ruleset
+    results = evaluate(design, Ruleset(version=rs.version, rules=sub))
+    return {"routing": routing, "legal": is_legal(results), "deferred": False,
+            "rule_results": [r.model_dump() for r in results]}

pen_stack/planner/seroprevalence_oracle.py

@@ -0,0 +1,92 @@
+"""Anti-vector neutralizing-antibody seroprevalence oracle.
+
+The last computable delivery-immunology axis: PRE-EXISTING humoral immunity (B-cell / neutralizing antibody)
+to a viral capsid. Unlike genotoxicity, capsid T-cell epitope load and innate sensing,
+this CANNOT be computed from sequence - it is the prevalence, in a population, of people who already carry
+NAbs against the vector from natural exposure. The grounding is published serosurvey DATA
+(configs/seroprevalence.yaml), curated as ranges with provenance.
+
+    preexisting_score = 1 - midpoint(seroprevalence_pct) / 100 # 1 = fewest patients excluded by NAb
+
+Answers through the OracleResult contract (output_kind="baseline"). Non-viral vehicles carry no foreign
+capsid -> no pre-existing ANTI-VECTOR humoral immunity (score 1.0 by mechanism). SCOPE: a POPULATION
+prevalence, NOT a given patient's NAb titer (a known-unknown); region/age/assay-dependent (a range, surfaced);
+the humoral (B-cell) axis only - distinct from the T-cell epitope load.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.oracles.schema import OracleResult, Provenance
+
+_SCOPE_CARD = "seroprevalence"
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict:
+    return yaml.safe_load(resource("configs/seroprevalence.yaml").read_text(encoding="utf-8"))
+
+
+def _all_dois() -> list[str]:
+    dois: set[str] = set()
+    for rec in (_table().get("serotypes") or {}).values():
+        dois.update(rec.get("dois", []) or [])
+    return sorted(dois)
+
+
+def _prov(**extra) -> Provenance:
+    return Provenance(model="anti_vector_seroprevalence", version=str(_table().get("version", "1.0")),
+                      source="cache", extra=extra)
+
+
+def seroprevalence_oracle(vehicle_name: str, serotype: str | None = None) -> OracleResult:
+    """Pre-existing anti-vector NAb seroprevalence for a vehicle (or an explicit serotype), as an OracleResult.
+
+    - viral vehicle (or serotype) with curated data -> preexisting_score = 1 - midpoint(seroprevalence)/100.
+    - non-viral vehicle -> 1.0 by mechanism (no foreign capsid).
+    - unknown vehicle / no curated serotype -> available=False (caller falls back to the documented tier).
+    Never fabricates a number."""
+    t = _table()
+    sero = t.get("serotypes") or {}
+    key = serotype or (t.get("vehicle_serotype") or {}).get(vehicle_name)
+
+    if key and key in sero:
+        rec = sero[key]
+        lo, hi = rec["nab_seroprevalence_pct"]
+        mid = (lo + hi) / 2.0
+        score = max(0.0, min(1.0, 1.0 - mid / 100.0))
+        return OracleResult(
+            oracle="genome",
+            value={"preexisting_score": round(score, 3), "serotype": key,
+                   "nab_seroprevalence_pct": [lo, hi], "midpoint_pct": mid, "dois": rec.get("dois", [])},
+            provenance=_prov(serotype=key, dois=rec.get("dois", [])), native_uncertainty=round((hi - lo) / 200.0, 4),
+            scope_card=_SCOPE_CARD, in_scope=True, extrapolating=False, output_kind="baseline", available=True,
+            note=(f"{key}: documented NAb seroprevalence {lo}-{hi}% (population); preexisting_score="
+                  f"1-midpoint/100={score:.3f}. " + (rec.get("note", "") + " " if rec.get("note") else "")
+                  + "A POPULATION prevalence, region/age/assay-dependent - NOT a given patient's NAb titer "
+                  "(a known-unknown)."))
+
+    if vehicle_name in (t.get("non_viral") or []):
+        return OracleResult(
+            oracle="genome",
+            value={"preexisting_score": 1.0, "serotype": None, "mechanism": "non-viral"},
+            provenance=_prov(), native_uncertainty=0.0, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note="non-viral vehicle: no foreign capsid -> no pre-existing ANTI-VECTOR humoral immunity (1.0). "
+                 "Anti-PEG immunity for LNP is an emerging, separate exception (not a vector seroprevalence).")
+
+    return OracleResult(oracle="genome", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                        in_scope=False, available=False, output_kind="baseline",
+                        note=f"no curated seroprevalence for {vehicle_name!r}; fall back to the documented "
+                             "preexisting_immunity tier.")
+
+
+def computed_preexisting_score(vehicle_name: str, serotype: str | None = None) -> tuple[float | None, OracleResult]:
+    """Convenience: (preexisting_score or None, full OracleResult). None when the oracle abstains. Never
+    fabricates."""
+    r = seroprevalence_oracle(vehicle_name, serotype)
+    val = (r.value or {}).get("preexisting_score") if (r.available and r.value) else None
+    return val, r