pen-stack 0.1.0__py3-none-any.whl

pen_stack/twin/data/position_effect.py

@@ -0,0 +1,245 @@
+"""Position-effect / expression supervision, the unified table.
+
+ONE schema over the scattered human/mouse position-effect datasets, so a single learned cassette x context
+model (`twin.position_effect.PositionEffectModel`) can be trained and a held-out-cell-type benchmark
+(`benchmarks/position_effect/`, TPE-Bench) can be sealed. Wrap, do not rebuild: TRIP supervision is the same
+table the durability head already uses; this module just unifies it with the other sources and adds the
+cassette identity + cross-dataset normalization + leakage-controlled splits.
+
+NO FABRICATION. Each dataset is registered with its verified accession/DOI and a loader. A dataset whose raw
+data is not present is reported `available=False` (an "not fetched"), never silently imputed. The only
+dataset wired live is **TRIP** (Akhtar 2013, on the VM + pulled locally); the additional human
+position-effect sources (PatchMPRA, MPIRE, lentiMPRA, Leemans) are registered with their accessions and a
+loader contract, and become available when their raw data is fetched, the cross-cell-type *transfer* claim is
+explicitly gated on that acquisition (documented, not asserted).
+
+Canonical schema (one row = one integrated reporter / element measurement):
+    dataset, organism, cell_type, chrom, pos, cassette, expression_raw, expression_z, silenced, <features...>
+`expression_z` is z-scored WITHIN (dataset x cassette) so a promoter's strength does not leak across datasets
+and the model learns the *context* effect on a comparable scale.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+import pandas as pd
+
+from pen_stack._resources import project_root
+
+# canonical chromatin context features (subset present per dataset; missing -> excluded, never imputed silently)
+FEATURE_COLS = ["atac", "dnase", "H3K27ac", "H3K4me1", "H3K4me3", "H3K9me3", "H3K27me3", "H3K36me3"]
+
+SCHEMA = ["dataset", "organism", "cell_type", "chrom", "pos", "cassette",
+          "expression_raw", "expression_z", "silenced"]
+
+
+# dataset registry with verified accessions/DOIs for each source dataset
+@dataclass
+class Dataset:
+    name: str
+    citation: str
+    doi: str
+    accession: str
+    organism: str
+    cell_types: tuple[str, ...]
+    role: str # "position_effect" (locus->expr) | "cassette_activity" (CRE/MPRA)
+    loader: Callable[[Path], pd.DataFrame] | None = None
+    note: str = ""
+    _rel: str = "" # repo-relative raw path the loader reads (for availability check)
+
+    def available(self, root: Path | None = None) -> bool:
+        if self.loader is None or not self._rel:
+            return False
+        root = root or project_root()
+        return (root / self._rel).exists()
+
+
+def _load_trip(root: Path) -> pd.DataFrame:
+    """TRIP (Akhtar 2013) mESC integrations + mES chromatin marks -> canonical schema.
+
+    The parquet is the same `trip_with_chromatin.parquet` the durability head trains on (chrom, pos, promoter,
+    expression [log2], silenced, + 5 histone marks). cassette = promoter; cell_type = mESC.
+    """
+    path = root / "data/external/trip/trip_with_chromatin.parquet"
+    df = pd.read_parquet(path)
+    marks = [c for c in FEATURE_COLS if c in df.columns]
+    out = pd.DataFrame({
+        "dataset": "TRIP_Akhtar2013",
+        "organism": "mouse",
+        "cell_type": "mESC",
+        "chrom": df["chrom"].astype(str),
+        "pos": df["pos"].astype("int64"),
+        "cassette": df["promoter"].astype(str),
+        "expression_raw": df["expression"].astype(float),
+        "silenced": df["silenced"].astype(bool),
+    })
+    for m in marks:
+        out[m] = df[m].astype(float)
+    return out
+
+
+def _load_leemans(root: Path) -> pd.DataFrame:
+    """Leemans 2019 human K562 TRIP integrations + K562 chromatin marks -> canonical schema.
+
+    The parquet (chrom, pos, promoter, expression [log], silenced, + chromatin marks present in K562) is the
+    fetched Leemans position-effect table: per-barcode coordinates from the Cell supplement Dataset S2 joined
+    to the van Steensel feature set. cassette = promoter; cell_type = K562. This is the human-cell-type
+    supervision that flips the cross-cell-type transfer axis from data-gated to fetched.
+    """
+    path = root / "data/external/leemans/leemans_k562_position_effect.parquet"
+    df = pd.read_parquet(path)
+    marks = [c for c in FEATURE_COLS if c in df.columns]
+    out = pd.DataFrame({
+        "dataset": "Leemans2019",
+        "organism": "human",
+        "cell_type": "K562",
+        "chrom": df["chrom"].astype(str),
+        "pos": df["pos"].astype("int64"),
+        "cassette": df["promoter"].astype(str),
+        "expression_raw": df["expression"].astype(float),
+        "silenced": df["silenced"].astype(bool),
+    })
+    for m in marks:
+        out[m] = df[m].astype(float)
+    return out
+
+
+def _loader_not_fetched(name: str, accession: str) -> Callable[[Path], pd.DataFrame]:
+    def _raise(_root: Path) -> pd.DataFrame:
+        raise FileNotFoundError(
+            f"{name}: raw data not fetched (accession {accession}). Wires TRIP only; this source is "
+            f"registered with its accession + loader contract and becomes available once fetched. The "
+            f"cross-cell-type transfer claim is gated on this acquisition (not asserted).")
+    return _raise
+
+
+DATASETS: dict[str, Dataset] = {
+    "TRIP_Akhtar2013": Dataset(
+        name="TRIP_Akhtar2013",
+        citation="Akhtar et al., Cell 2013 (thousands of reporters integrated in parallel)",
+        doi="10.1016/j.cell.2013.07.018",
+        accession="GEO GSE49806 (tetO) + GSE49807 (mPGK); trip.nki.nl",
+        organism="mouse", cell_types=("mESC",), role="position_effect",
+        loader=_load_trip, _rel="data/external/trip/trip_with_chromatin.parquet",
+        note="position effect on an integrated cassette, the writing-relevant supervision (LIVE)."),
+    "PatchMPRA_Maricque2019": Dataset(
+        name="PatchMPRA_Maricque2019",
+        citation="Maricque, Chaudhari & Cohen, Nat Biotechnol 2019 (genomically integrated MPRA)",
+        doi="10.1038/nbt.4285", accession="GEO (per paper)",
+        organism="mouse", cell_types=("mESC",), role="position_effect",
+        loader=_loader_not_fetched("PatchMPRA_Maricque2019", "10.1038/nbt.4285"),
+        note="cassette x context separability evidence (data-gated)."),
+    "MPIRE_Hong2024": Dataset(
+        name="MPIRE_Hong2024",
+        citation="Hong et al., Nat Commun 2024 (massively parallel insulator-activity MPRA)",
+        doi="10.1038/s41467-024-52599-6", accession="GEO GSE223403; github.com/claricehong/MPIRE_insulators",
+        organism="human", cell_types=("K562",), role="position_effect",
+        loader=_loader_not_fetched("MPIRE_Hong2024", "GSE223403"),
+        note="human K562 position/insulator context (data-gated)."),
+    "lentiMPRA_Agarwal2025": Dataset(
+        name="lentiMPRA_Agarwal2025",
+        citation="Agarwal et al., Nature 639:411-420 (2025) (~680k regulatory elements)",
+        doi="10.1038/s41586-024-08430-9", accession="ENCODE portal + GEO; bioRxiv 2023.03.05.531189",
+        organism="human", cell_types=("HepG2", "K562", "WTC11"), role="cassette_activity",
+        loader=_loader_not_fetched("lentiMPRA_Agarwal2025", "10.1038/s41586-024-08430-9"),
+        note="cassette/CRE activity supervision across 3 human cell types (data-gated)."),
+    "Leemans2019": Dataset(
+        name="Leemans2019",
+        citation="Leemans et al., Cell 2019 (promoter-intrinsic + local chromatin determine repression in LADs)",
+        doi="10.1016/j.cell.2019.03.009", accession="GEO (per paper); van Steensel lab",
+        organism="human", cell_types=("K562",), role="position_effect",
+        loader=_load_leemans, _rel="data/external/leemans/leemans_k562_position_effect.parquet",
+        note="human K562 LAD-repression position effect (LIVE: fetched via P2 -- coordinates from the "
+             "Cell supplement Dataset S2 joined to the van Steensel feature set)."),
+}
+
+
+def available_datasets(root: Path | None = None) -> list[str]:
+    root = root or project_root()
+    return [k for k, d in DATASETS.items() if d.available(root)]
+
+
+# normalization + loader
+def normalize_within(df: pd.DataFrame, by=("dataset", "cassette"), col: str = "expression_raw",
+                     out: str = "expression_z") -> pd.DataFrame:
+    """z-score expression within each (dataset x cassette) group, so a cassette's intrinsic strength does not
+    leak across datasets and the model is supervised on the *context* deviation on a comparable scale. A
+    singleton/zero-variance group maps to 0.0 (no spurious scale)."""
+    df = df.copy()
+    def _z(s: pd.Series) -> pd.Series:
+        sd = s.std(ddof=0)
+        return (s - s.mean()) / sd if sd and sd > 1e-12 else pd.Series(0.0, index=s.index)
+    df[out] = df.groupby(list(by))[col].transform(_z)
+    return df
+
+
+def load_position_effect(datasets: list[str] | None = None, root: Path | None = None,
+                         require: bool = False) -> pd.DataFrame:
+    """Unified position-effect table. Loads every AVAILABLE registered dataset (or the named subset),
+    concatenates to the canonical schema, and z-normalizes expression within (dataset x cassette).
+
+    `require=True` raises if a requested dataset is unavailable; default skips unavailable ones (logging the
+    skip in the returned frame's `.attrs['skipped']`), clear about what is and is not in the table.
+    """
+    root = root or project_root()
+    names = datasets or list(DATASETS)
+    frames, skipped = [], []
+    for name in names:
+        d = DATASETS[name]
+        if not d.available(root):
+            skipped.append(name)
+            if require:
+                d.loader(root) # raise the informative FileNotFoundError
+            continue
+        frames.append(d.loader(root))
+    if not frames:
+        raise FileNotFoundError(
+            f"no position-effect dataset available under {root}. Available registry: {list(DATASETS)}; "
+            f"skipped (not fetched): {skipped}. Pull TRIP via scratch/v67_pull_trip.py or set PEN_STACK_HOME.")
+    df = pd.concat(frames, ignore_index=True)
+    df = normalize_within(df)
+    df.attrs["skipped"] = skipped
+    df.attrs["datasets"] = [f["dataset"].iloc[0] for f in frames]
+    # reorder: schema first, then whatever feature columns are present
+    feats = [c for c in FEATURE_COLS if c in df.columns]
+    return df[[c for c in SCHEMA if c in df.columns] + feats]
+
+
+# leakage-controlled splits
+def blocked_splits(df: pd.DataFrame, n_splits: int = 5, group: str = "chrom",
+                   seed: int = 20260619) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Domain-blocked CV: no `group` (default chromosome) value appears in both train and test of a fold,
+    the leakage control the position-effect task needs (nearby integrations share chromatin)."""
+    from sklearn.model_selection import GroupKFold
+    g = df[group].astype("category").cat.codes.to_numpy()
+    k = min(n_splits, len(np.unique(g)))
+    return list(GroupKFold(n_splits=k).split(df, groups=g))
+
+
+def heldout_celltype_splits(df: pd.DataFrame) -> list[tuple[str, np.ndarray, np.ndarray]]:
+    """Leave-one-cell-type-out: train on all but one cell type, test on the held-out one. This is the headline
+    transfer evaluation. With a single available cell type it returns [] and the caller reports the transfer
+    axis as data-gated, never a fabricated transfer number."""
+    cts = sorted(df["cell_type"].unique())
+    if len(cts) < 2:
+        return []
+    out = []
+    idx = np.arange(len(df))
+    for ct in cts:
+        te = idx[df["cell_type"].to_numpy() == ct]
+        tr = idx[df["cell_type"].to_numpy() != ct]
+        out.append((ct, tr, te))
+    return out
+
+
+def leakage_report(df: pd.DataFrame, splits: list[tuple[np.ndarray, np.ndarray]],
+                   group: str = "chrom") -> dict:
+    """Verify no `group` value is co-located across the train/test of any fold (the split's integrity claim)."""
+    bad = 0
+    for tr, te in splits:
+        if set(df.iloc[tr][group]) & set(df.iloc[te][group]):
+            bad += 1
+    return {"n_folds": len(splits), "folds_with_leakage": bad, "clean": bad == 0, "group": group}

pen_stack/twin/mechanistic.py

@@ -0,0 +1,147 @@
+"""Mechanistic simulation where computable.
+
+Computes the consequences MECHANISM allows, steady-state cassette expression in a chromatin context, and
+nothing more. Physics where computable; explicitly NOT a phenotype, NOT in-vivo behaviour, NOT durability beyond
+the steady state. Assumptions and scope flags travel with every output.
+
+The promoter palette is a comprehensive, literature-cited table (configs/expression/promoters.yaml,
+~25 constitutive + tissue-specific promoters) and the cassette carries an MODIFIER profile (WPRE, intron,
+polyA, Kozak, codon-optimization, CpG-silencing, configs/expression/modifiers.yaml). Modifier effects are
+transgene-dependent PRIORS, so they are reported as a bounded uplift RANGE with wide uncertainty, never folded
+into the [0,1] base score as a point estimate. Absolute titer / % of normal stays a known-unknown.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+# legacy default keys kept for backward compatibility (earlier designs used these names directly).
+_LEGACY_STRENGTH = {"ef1a": 1.0, "cag": 1.0, "cmv": 0.9, "pgk": 0.6, "ubc": 0.5,
+                    "endogenous": 0.4, "minimal": 0.2}
+
+
+@lru_cache(maxsize=1)
+def _palette() -> dict:
+    """Flatten the comprehensive promoter palette (constitutive + tissue-specific) to {name: entry}."""
+    try:
+        cfg = yaml.safe_load(resource("configs/expression/promoters.yaml").read_text(encoding="utf-8"))
+    except Exception: # noqa: BLE001 - config absent (shouldn't happen) -> legacy table only
+        return {}
+    out: dict = {}
+    for group in ("constitutive", "tissue_specific"):
+        for name, e in (cfg.get(group) or {}).items():
+            out[name] = e
+    out["_default"] = cfg.get("default_strength", 0.5)
+    return out
+
+
+@lru_cache(maxsize=1)
+def _modifiers() -> dict:
+    try:
+        return yaml.safe_load(resource("configs/expression/modifiers.yaml").read_text(encoding="utf-8"))
+    except Exception: # noqa: BLE001
+        return {"modifiers": {}, "composition": {"max_total_uplift": 4.0}}
+
+
+def promoter_palette() -> list[dict]:
+    """The selectable promoter palette (constitutive + tissue-specific), each with its literature strength,
+    context and citation. Surfaced so the Twin can offer a promoter selector, the mechanistic relative-expression
+    estimate reacts to the chosen promoter (it defaults to 0.5 when none is picked)."""
+    try:
+        cfg = yaml.safe_load(resource("configs/expression/promoters.yaml").read_text(encoding="utf-8"))
+    except Exception: # noqa: BLE001
+        return []
+    out: list[dict] = []
+    for group in ("constitutive", "tissue_specific"):
+        for name, e in (cfg.get(group) or {}).items():
+            if isinstance(e, dict):
+                out.append({"name": name, "strength": e.get("strength"), "context": e.get("context"),
+                            "citation": e.get("citation"), "group": group})
+    return out
+
+
+def promoter_info(name: str) -> dict:
+    """The cited palette entry for a promoter (strength + context + assay + citation), or a labelled default.
+
+    A name the palette does not carry is never scored as though it were a real promoter: the returned entry marks
+    ``recognized=False`` and echoes the requested name, so a typo is distinguishable from choosing no promoter at
+    all (both fall back to the neutral default strength, but only one is a caller mistake)."""
+    pal = _palette()
+    key = str(name or "").strip().lower()
+    if key in pal:
+        return {**pal[key], "recognized": True}
+    if key in _LEGACY_STRENGTH:
+        return {"strength": _LEGACY_STRENGTH[key], "context": "ubiquitous", "confidence": "legacy",
+                "recognized": True}
+    return {"strength": pal.get("_default", 0.5), "context": "unknown", "confidence": "default",
+            "recognized": False, "requested_promoter": (str(name).strip() or None) if name else None}
+
+
+def _promoter_strength(design: dict) -> tuple[float, dict]:
+    p = design.get("promoter")
+    if isinstance(p, dict) and p.get("strength") is not None:
+        return float(p["strength"]), {"context": p.get("context", "supplied"), "confidence": "supplied"}
+    name = p if isinstance(p, str) else str(p or "")
+    info = promoter_info(name)
+    return float(info.get("strength", 0.5)), info
+
+
+def _modifier_profile(design: dict) -> dict:
+    """A bounded modifier uplift RANGE from the cassette's cis-elements. NOT a point multiplier and NOT
+    folded into the [0,1] base, modifier effects are transgene/context-dependent priors with wide uncertainty."""
+    mods = _modifiers().get("modifiers", {})
+    cap = float(_modifiers().get("composition", {}).get("max_total_uplift", 4.0))
+    applied, hi = [], 1.0 # lower bound stays 1.0: a modifier may do nothing for THIS transgene
+    for key, present in (("wpre", design.get("wpre")), ("intron", design.get("intron"))):
+        if present and key in mods:
+            hi *= float(mods[key].get("present_fold", [1.0, 1.0])[1])
+            applied.append(key)
+    if design.get("codon_optimized") and "codon_optimization" in mods:
+        hi *= float(mods["codon_optimization"].get("optimized_fold", [1.0, 1.0])[1])
+        applied.append("codon_optimization")
+    cpg_flag = bool(design.get("high_cpg") or (design.get("cpg_oe") is not None and float(design.get("cpg_oe")) > 0.6))
+    if cpg_flag:
+        applied.append("cpg_silencing(down)")
+    lo, hi = 1.0, round(min(hi, cap), 2)
+    return {
+        "applied": applied,
+        "estimated_uplift_range": [round(lo, 2), round(hi, 2)],
+        "direction_note": ("net uplift expected (transgene-dependent)" if hi > 1.0 else "no modifier signal"),
+        "cpg_silencing_risk": bool(cpg_flag),
+        "caveat": "modifier effects are transgene/cell/construct-dependent PRIORS (e.g. an intron is ~20x for one "
+                  "transgene, ~3x for another), a bounded range, not a measured multiplier for THIS construct.",
+        "source": "configs/expression/modifiers.yaml (literature priors)",
+    }
+
+
+def cassette_expression(design: dict, chromatin_ctx: dict) -> dict:
+    """Computable steady-state RELATIVE expression from an integrated cassette: promoter_strength x copy_number x
+    accessibility (base, [0,1]-relative), PLUS an bounded modifier uplift range. NOT a phenotype, NOT an
+    absolute titer."""
+    p, pinfo = _promoter_strength(design)
+    cn = float(design.get("copy_number", 1) or 1)
+    acc = float(chromatin_ctx.get("accessibility", 1.0) if chromatin_ctx else 1.0)
+    rel = p * cn * acc
+    flags = ["episomal_durability_unknown", "phenotype_not_modeled"]
+    # context scope: a promoter that silences (CMV, SFFV in stem cells) is flagged, not silently trusted.
+    if str(pinfo.get("context", "")).startswith("variable") or "SILENCE" in str(pinfo.get("note", "")).upper():
+        flags.append("promoter_context_variable_or_silencing")
+    # a named promoter the palette does not carry falls back to the neutral default: say so rather than let a typo
+    # read as a scored, cited promoter.
+    if pinfo.get("recognized") is False and pinfo.get("requested_promoter"):
+        flags.append("promoter_not_in_palette_neutral_default_used")
+    return {
+        "relative_expression": round(rel, 4),
+        "units": "relative (dimensionless)",
+        "modifier_profile": _modifier_profile(design),
+        "assumptions": ["steady-state", "no silencing dynamics modeled", "linear copy scaling",
+                        "promoter strength is an ordinal literature prior (context-dependent)"],
+        "scope_flags": flags,
+        "provenance": {"promoter_strength": p, "promoter_context": pinfo.get("context"),
+                       "promoter_recognized": pinfo.get("recognized", True),
+                       "promoter_citation": pinfo.get("citation"), "copy_number": cn, "accessibility": acc,
+                       "source": "twin.mechanistic (closed-form steady state + literature promoter palette)"},
+    }

pen_stack/twin/outcome.py

@@ -0,0 +1,132 @@
+"""Write-outcome prediction, the digital twin.
+
+Fuses what MECHANISM computes (cassette expression), what an IN-DISTRIBUTION virtual-cell model supports
+(deferred/cache-replayed, OOD-gated), and the IMMUNE profile (sourced, never invented) into a single
+prediction with an interval that WIDENS under OOD and an explicit boundary at phenotype. The twin is a
+hypothesis engine: every output is a CANDIDATE with an interval; phenotype, in-vivo behaviour, immunogenicity
+magnitude, and durability beyond the computable stay scope-flagged.
+"""
+from __future__ import annotations
+
+_BASE_HALF_WIDTH = 0.20 # heuristic band on the fused estimate (NOT a trained conformal interval)
+_OOD_INFLATION = 1.6 # OOD widens the interval rather than over-trusting an extrapolating model
+
+
+def _chromatin(cell_state: str, design: dict) -> dict:
+    """Chromatin context for the mechanistic model. Uses a supplied accessibility if present, else neutral 1.0
+    (and flags that a full epigenome was not supplied)."""
+    acc = design.get("accessibility")
+    if acc is None and isinstance(design.get("chromatin_ctx"), dict):
+        acc = design["chromatin_ctx"].get("accessibility")
+    return {"accessibility": float(acc) if acc is not None else 1.0,
+            "accessibility_supplied": acc is not None}
+
+
+def _as_perturbation(design: dict) -> dict:
+    return {"kind": design.get("perturbation_kind") or "genetic",
+            "target": design.get("gene"), "write_type": design.get("write_type")}
+
+
+def _in_vivo(design: dict) -> bool:
+    veh = design.get("delivery_vehicle")
+    if not veh:
+        return False
+    from pen_stack.planner.delivery_vehicles import vehicle as _veh
+    return bool((_veh(veh) or {}).get("in_vivo"))
+
+
+def predict_outcome(design: dict, cell_state: str) -> dict:
+    from pen_stack.oracles.vcell import predict_response
+    from pen_stack.twin.mechanistic import cassette_expression
+    from pen_stack.twin.position_effect import predict_stage_h
+
+    mech = cassette_expression(design, _chromatin(cell_state, design))
+    # When a chromatin CONTEXT is supplied and the trained artifact is present, the learned, TRAINED-CONFORMAL
+    # position-effect model serves (interval + p_silenced + OOD widening). Without a
+    # context (or the artifact) this is None and the closed-form heuristic below stands, backward compatible.
+    learned = predict_stage_h(design, cell_type=cell_state)
+    vc = predict_response(cell_state, _as_perturbation(design), model="state")
+    imm = None
+    if design.get("delivery_vehicle"):
+        from pen_stack.planner.immune_profile import immune_profile
+        imm = immune_profile(design)
+
+    # fuse: the computable mechanistic estimate is the backbone; the VC model adds an in-distribution response
+    # estimate ONLY when available (deferred backend -> None, never fabricated).
+    est = mech["relative_expression"]
+    vc_value = vc.value if (vc.available and not vc.extrapolating and vc.value) else None
+
+    scope = list(mech["scope_flags"]) + ["in_vivo_magnitude_unknown"]
+    if vc.extrapolating:
+        scope.append("vcell_OOD")
+
+    # in-vivo durability MAY be conditioned on pre-existing NAb (the GROUNDED immune axis; no invented numbers)
+    conditioned_note = None
+    if imm is not None and _in_vivo(design):
+        nab = (imm.get("axes", {}).get("preexisting_nab") or {})
+        if nab.get("in_scope") and nab.get("value") is not None:
+            est = round(est * float(nab["value"]), 4) # higher NAb score = less pre-existing immunity
+            conditioned_note = f"in-vivo durability conditioned on grounded pre-existing NAb axis ({nab['value']})"
+
+    half = _BASE_HALF_WIDTH * (_OOD_INFLATION if vc.extrapolating else 1.0)
+    lo, hi = round(max(0.0, est - half), 4), round(est + half, 4)
+
+    # cargo-capacity feasibility: relative expression is PER-COPY and independent of cargo size (correct science),
+    # but a cargo that overflows the vehicle cannot be delivered as specified, surface it so a (say) 50 kb AAV
+    # cargo is not silently read as a buildable design. The capacity RULE + its repair live in Verify/legality.
+    feasibility = {"buildable": True}
+    veh = design.get("delivery_vehicle") or design.get("vehicle")
+    cargo_bp = design.get("cargo_bp")
+    if cargo_bp is not None and int(cargo_bp) <= 0:
+        # a non-positive cargo size is not a buildable construct, flag it rather than silently reporting
+        # buildable:True (tester finding: cargo_bp=0 was accepted as buildable).
+        feasibility = {"buildable": False, "cargo_bp": int(cargo_bp),
+                       "reason": f"cargo size {int(cargo_bp)} bp is not a buildable construct (must be >= 1 bp)."}
+        scope.append("cargo_size_nonpositive")
+    elif veh and cargo_bp is not None:
+        from pen_stack.planner.delivery_vehicles import vehicle as _veh
+        cap = (_veh(veh) or {}).get("cargo_capacity_bp")
+        if cap is not None and int(cargo_bp) > int(cap):
+            feasibility = {"buildable": False, "cargo_bp": int(cargo_bp), "vehicle": veh, "capacity_bp": int(cap),
+                           "reason": (f"cargo {int(cargo_bp)} bp exceeds {veh} capacity {int(cap)} bp, not "
+                                      "deliverable as specified. Relative expression is per-copy (independent of "
+                                      "cargo size), so this estimate is for a construct that cannot be built as-is; "
+                                      "see Verify / legality for the capacity rule and its repair.")}
+            scope.append("cargo_exceeds_vehicle_capacity")
+
+    predicted = {"relative_expression": est, "vcell_response": vc_value, "units": mech["units"]}
+    interval_kind = ("heuristic band (widens under OOD); NOT a trained conformal interval - no public "
+                     "perturbation-outcome calibration set (Arc VCC: models do not yet beat naive baselines)")
+    if learned is not None:
+        # the learned model serves: surface its trained-conformal value + a relative rescale alongside the
+        # mechanistic estimate; the mechanistic `interval` is retained for the relative-scale contract.
+        predicted["relative_expression_learned"] = learned.get("relative_expression_learned")
+        predicted["learned_log2_expression"] = learned.get("predicted_log2_expression")
+        interval_kind = ("trained-conformal: see position_effect.interval_log2 (split-conformal on TRIP "
+                         "supervision, OOD-widened). Mechanistic relative interval retained below.")
+        scope = scope + ["stage_h_learned_trained_conformal"]
+
+    return {
+        "predicted_outcome": predicted,
+        "interval": [lo, hi],
+        "interval_kind": interval_kind,
+        "feasibility": feasibility, # cargo-vs-vehicle capacity: is this construct buildable as specified?
+        # the mechanistic top-level is promoter x copy-number x accessibility x pre-existing-NAb; accessibility is
+        # neutral (1.0) here because no cell-type chromatin track is mounted, so it is deliberately CELL-TYPE-AGNOSTIC
+        #, the cell-type-specific position effect is the learned position-effect head (`position_effect`), not this number.
+        "relative_expression_basis": ("promoter strength x copy number x accessibility (neutral 1.0, cell-type "
+                                      "position effect is the learned position-effect head, not the mechanistic top-level)"
+                                      + (" x pre-existing-NAb" if conditioned_note else "")),
+        "position_effect": learned, # learned trained-conformal block (or None)
+        "stage_h_mode": "learned_trained_conformal" if learned is not None else "heuristic",
+        "immune_outcome": imm, # immune profile (or None if no vehicle)
+        "extrapolating": bool(vc.extrapolating),
+        "conditioned_on_preexisting_nab": conditioned_note,
+        "scope_flags": scope,
+        "provenance": {"mechanistic": mech["assumptions"], "vcell": vc.provenance.model_dump()
+                       if hasattr(vc.provenance, "model_dump") else str(vc.provenance),
+                       "immune": "profile" if imm is not None else None,
+                       "position_effect": (learned["provenance"] if learned else None)},
+        "output_kind": "candidate",
+        "no_fabrication": True,
+    }