pen-stack 0.1.0__py3-none-any.whl

pen_stack/bridge/offtarget.py

@@ -0,0 +1,191 @@
+"""Genome-wide bridge-recombinase off-target engine.
+
+Given a bridge-RNA design's target core (bipartite ~14 nt with a central CT dinucleotide), scan hg38 for
+pseudosites tolerating up to ~2 mismatches and score each by a position-weight model (some positions
+tolerate substitutions, the central core does not). This is the clinical gatekeeper: it tells a designer
+where else in the genome the recombinase might write.
+
+Efficiency: the central core (CT) must match for recombination, so we **seed on the core dinucleotide**
+and verify the surrounding 14-mer - bounding the scan without loading the genome into RAM (per-chromosome
+via pysam). Scoring beats a naive Hamming ranking *because mismatch position matters*.
+
+Also exposes ``predict_offtargets(writer_family, site, ...)`` - the summary entry the Planner
+cargo step calls (so its off-target annotation is computed here rather than left pending).
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pandas as pd
+
+from pen_stack.bridge.ingest import load_measured_profile, load_profile_config, protective_weights
+
+_COMP = {"A": "T", "T": "A", "G": "C", "C": "G", "N": "N"}
+
+
+def position_weights(prefer_measured: bool = True) -> dict[int, float]:
+    """0-based protective weight per core position (1 = mismatch abolishes recombination).
+
+    Prefers the MEASURED Perry-2025 profile (committed parquet, available everywhere) when present;
+    otherwise the literature-grounded config weights.
+    """
+    if prefer_measured:
+        m = load_measured_profile()
+        if not m.empty:
+            return {int(p) - 1: float(w) for p, w in zip(m["position"], m["protective_weight"])}
+    return {p - 1: w for p, w in protective_weights().items()}
+
+
+def mismatches(window: str, core: str) -> list[tuple[int, str]]:
+    return [(j, window[j]) for j in range(len(core)) if window[j] != core[j]]
+
+
+def risk_score(mm: list[tuple[int, str]], weights: dict[int, float]) -> float:
+    """Fewer / weaker-position mismatches -> higher off-target risk. Perfect match -> 1.0."""
+    if not mm:
+        return 1.0
+    r = 1.0
+    for j, _ in mm:
+        r *= (1 - weights.get(j, 0.5))
+    return float(r)
+
+
+def hamming_risk(mm: list[tuple[int, str]], core_len: int) -> float:
+    """Naive baseline: position-blind - risk decreases uniformly with mismatch count."""
+    return float((core_len - len(mm)) / core_len)
+
+
+def scan_sequence(seq: str, core: str, max_mm: int, weights: dict[int, float],
+                  core_positions: list[int]) -> list[dict]:
+    """Seed on the central core dinucleotide, verify the full core with <= max_mm mismatches."""
+    seq = seq.upper()
+    L = len(core)
+    c0 = core_positions[0] # 0-based index of the core's first central base
+    motif = core[c0:c0 + len(core_positions)] # e.g. 'CT'
+    hits = []
+    for m in re.finditer(f"(?={motif})", seq): # overlapping seed matches
+        start = m.start() - c0 # align so the motif sits at the core position
+        if start < 0 or start + L > len(seq):
+            continue
+        window = seq[start:start + L]
+        if "N" in window:
+            continue
+        mm = mismatches(window, core)
+        if len(mm) <= max_mm:
+            hits.append({"pos": start, "site": window, "n_mm": len(mm),
+                         "risk": risk_score(mm, weights), "hamming": hamming_risk(mm, L)})
+    return hits
+
+
+def scan_offtargets(fasta: str | Path, target_core: str, chroms: list[str],
+                    max_mm: int | None = None) -> pd.DataFrame:
+    """Genome-wide off-target scan for a target core. Per-chromosome (memory-bounded)."""
+    from pysam import FastaFile
+    cfg = load_profile_config()
+    max_mm = cfg["max_mismatches"] if max_mm is None else max_mm
+    core_pos = [p - 1 for p in cfg["central_core_positions"]]
+    weights = position_weights()
+    fa = FastaFile(str(fasta))
+    rows = []
+    for c in chroms:
+        for h in scan_sequence(fa.fetch(c), target_core.upper(), max_mm, weights, core_pos):
+            rows.append({"chrom": c, **h})
+    fa.close()
+    df = pd.DataFrame(rows)
+    return df.sort_values("risk", ascending=False).reset_index(drop=True) if not df.empty else df
+
+
+# confidence band
+
+# Held-out ranking AUROC of the off-target ranker on the measured Perry-2025 profile (Genome-Writing Bench
+# T4). The position-weight ranker scores 0.77; the energetics ranker (position + substitution
+# identity) scores ~0.88 on the same leakage-safe held-out split and SHIPS (it beat the 0.77 gate), so it is
+# the default ranker when its derived penalty table is present. Uncertainty stays grounded: we report rank confidence +
+# abstain when not scannable, never a calibrated per-pseudosite probability the data cannot support.
+RANKER_HELDOUT_AUROC = 0.77
+ENERGETICS_HELDOUT_AUROC = 0.88
+
+
+def _energetics_model():
+    """Lazily load the committed energetics penalty table (None if absent → fall back to position-weight)."""
+    from pen_stack.bridge.offtarget_energetics import load_penalties
+    return load_penalties()
+
+
+def site_risk(window: str, target_core: str) -> dict:
+    """Best available per-pseudosite recombination-risk score: energetics ranker (~0.88) when its penalty
+    table is present, else the position-weight ranker (~0.77). Returns the score + which ranker produced it."""
+    model = _energetics_model()
+    if model is not None:
+        from pen_stack.bridge.offtarget_energetics import energetic_risk
+        return {"risk": energetic_risk(window, target_core, model), "ranker": "energetics",
+                "heldout_auroc": ENERGETICS_HELDOUT_AUROC}
+    mm = mismatches(window, target_core)
+    return {"risk": risk_score(mm, position_weights()), "ranker": "position_weight",
+            "heldout_auroc": RANKER_HELDOUT_AUROC}
+
+
+def offtarget_confidence(applicable: bool, scanned: bool, measured_weights: bool,
+                         n_candidates: int = 0) -> dict:
+    """Confidence band for the off-target ranker. Abstains when no genome-wide scan is run."""
+    if not applicable:
+        return {"level": "abstain", "abstain": True, "calibrated": False,
+                "epistemic_status": "not-computable",
+                "basis": "writer family is not RNA-guided pseudosite-scannable"}
+    if not scanned:
+        return {"level": "abstain", "abstain": True, "calibrated": False,
+                "epistemic_status": "not-computable",
+                "basis": "engine ready but no genome-wide scan run (need target_core + hg38 fasta)"}
+    has_energetics = _energetics_model() is not None
+    auroc = ENERGETICS_HELDOUT_AUROC if has_energetics else RANKER_HELDOUT_AUROC
+    ranker = "energetics (position + substitution identity)" if has_energetics else "position-weight"
+    return {"level": "ranker_calibrated", "abstain": False, "calibrated": True,
+            "ranker": ranker, "ranker_heldout_auroc": auroc,
+            "epistemic_status": "grounded-confident" if measured_weights else "grounded-extrapolating",
+            "basis": ("position weights from the MEASURED Perry-2025 profile" if measured_weights
+                      else "literature-config position weights (measured profile absent)"),
+            "scope": f"calibrated as a RANKER ({ranker}, held-out AUROC ~{auroc}) over {n_candidates} "
+                     "pseudosites, NOT as a per-site recombination probability"}
+
+
+# Planner hook + design API
+
+def predict_offtargets(writer_family: str, site: tuple | None = None, target_core: str | None = None,
+                       fasta: str | Path | None = None, chroms: list[str] | None = None,
+                       top: int = 20) -> dict:
+    """Off-target summary for a writer at a site - the entry the Planner cargo step calls.
+
+    Only bridge/seek families are RNA-guided pseudosite-scannable. If a genome + target core are
+    available it returns a real genome-wide scan summary; otherwise it reports the engine is ready and
+    how to run the full scan (never fabricates off-target sites).
+    """
+    if writer_family not in {"bridge_IS110", "seek_IS1111"}:
+        return {"family": writer_family, "applicable": False,
+                "note": "off-target pseudosite scan applies to RNA-guided bridge/seek recombinases only",
+                "confidence": offtarget_confidence(applicable=False, scanned=False, measured_weights=False)}
+    if not (target_core and fasta):
+        return {"family": writer_family, "applicable": True, "status": "engine_ready", "site": site,
+                "note": "provide target_core + hg38 fasta (pen-bridge design) for a genome-wide scan",
+                "confidence": offtarget_confidence(applicable=True, scanned=False, measured_weights=False)}
+    df = scan_offtargets(fasta, target_core, chroms or [], )
+    n_exact = int((df["n_mm"] == 0).sum()) if not df.empty else 0
+    measured = not load_measured_profile().empty
+    return {"family": writer_family, "applicable": True, "status": "scanned",
+            "target_core": target_core, "n_candidates": int(len(df)),
+            "n_exact_matches": n_exact,
+            "top": df.head(top).to_dict("records") if not df.empty else [],
+            "confidence": offtarget_confidence(applicable=True, scanned=True, measured_weights=measured,
+                                               n_candidates=int(len(df)))}
+
+
+if __name__ == "__main__": # pragma: no cover
+    # tiny self-test on a synthetic sequence
+    cfg = load_profile_config()
+    cp = [p - 1 for p in cfg["central_core_positions"]]
+    w = position_weights()
+    core = "AAACGTCTACGTTT" # 14 nt, CT at positions 7-8 (0-based 6-7)
+    seq = "GGGG" + core + "TTTT" + core[:6] + "GG" + core[8:] + "AA" # one exact + one core-disrupted
+    hits = scan_sequence(seq, core, cfg["max_mismatches"], w, cp)
+    for h in hits:
+        print(h)

pen_stack/bridge/offtarget_energetics.py

@@ -0,0 +1,105 @@
+"""Mechanistic off-target energetics model, GATED on beating 0.77.
+
+The shipped off-target ranker (`bridge/offtarget.py`) scores a pseudosite by a POSITION-only protective
+weight: ``risk = prod(1 - weight[mismatched position])``. It ignores *which* substitution a mismatch is, but
+a bridge-RNA:target duplex is a base-pairing interaction, so the thermodynamic cost of a mismatch depends on
+its identity (a G:T wobble is tolerated; a C:C clash is not), not only its position. This module adds that:
+a per-(position, substitution) **penalty** learned from the measured off-target frequencies, a mismatch type
+seen often among recombining off-targets is tolerated (low penalty), a rare one is costly (high penalty).
+
+``energetic_risk`` sums the penalties over the mismatched positions (a log-additive binding-energy proxy) and
+maps to a 0-1 risk. This is the only place the stack *adds* mechanism to a model rather than just wrapping it, and
+by discipline it **ships only if it beats the current 0.77 held-out AUROC** on a leakage-safe train/test
+split (penalties fit on train, evaluated on held-out test). If it does not, it is reported as a negative and
+the position-weight model stays the default. No mechanism is added that does not earn its place empirically.
+"""
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+_BASES = "ACGT"
+
+
+def fit_penalties(pairs, core_len: int = 14, alpha: float = 1.0) -> dict:
+    """Learn per-(position, ref→alt) mismatch penalties from recombining off-targets.
+
+    ``pairs`` = iterable of (offtarget_seq, intended_seq) that DID recombine. For each position, count how
+    often each substitution (intended base → observed base) appears; a frequent substitution is tolerated, so
+    its penalty is low. penalty = -log((count + alpha) / (matches_at_pos + alpha * 12)). Matches (no mismatch)
+    anchor the per-position scale. Returns {"pen": {(pos, ref, alt): penalty}, "pos_match": {...}}.
+    """
+    sub_count = defaultdict(int) # (pos, ref, alt) -> count of that mismatch among off-targets
+    match_count = defaultdict(int) # pos -> count of positions left matched
+    for off, intended in pairs:
+        if len(off) < core_len or len(intended) < core_len:
+            continue
+        for p in range(core_len):
+            ref, alt = intended[p], off[p]
+            if ref not in _BASES or alt not in _BASES:
+                continue
+            if ref == alt:
+                match_count[p] += 1
+            else:
+                sub_count[(p, ref, alt)] += 1
+    pen = {}
+    for p in range(core_len):
+        denom = match_count[p] + alpha * 12 # 12 = the off-diagonal substitution types
+        for ref in _BASES:
+            for alt in _BASES:
+                if ref == alt:
+                    continue
+                c = sub_count[(p, ref, alt)]
+                pen[(p, ref, alt)] = -math.log((c + alpha) / denom)
+    return {"pen": pen, "core_len": core_len,
+            "max_pen": max(pen.values()) if pen else 1.0}
+
+
+def energetic_penalty(off: str, intended: str, model: dict) -> float:
+    """Total binding-energy penalty (sum over mismatched positions). Higher = less likely to recombine."""
+    pen, L = model["pen"], model["core_len"]
+    miss = model["max_pen"]
+    total = 0.0
+    for p in range(min(L, len(off), len(intended))):
+        ref, alt = intended[p], off[p]
+        if ref != alt:
+            total += pen.get((p, ref, alt), miss)
+    return total
+
+
+def energetic_risk(off: str, intended: str, model: dict) -> float:
+    """0-1 recombination risk: high when the total mismatch penalty is low (a perfect match → ~1.0)."""
+    total = energetic_penalty(off, intended, model)
+    return float(math.exp(-total))
+
+
+# --- serialization: the fitted penalty table is a DERIVED statistical summary (like the measured position
+# profile), committable as data/curated/bridge_offtarget_energetics.json so the model runs without raw data ---
+def to_json(model: dict) -> dict:
+    """Encode the tuple-keyed penalty table as nested JSON {pos: {ref+alt: penalty}}."""
+    nested: dict = {}
+    for (p, ref, alt), v in model["pen"].items():
+        nested.setdefault(str(p), {})[ref + alt] = round(v, 6)
+    return {"core_len": model["core_len"], "max_pen": round(model["max_pen"], 6), "pen": nested}
+
+
+def from_json(d: dict) -> dict:
+    pen = {}
+    for p, subs in d["pen"].items():
+        for ra, v in subs.items():
+            pen[(int(p), ra[0], ra[1])] = float(v)
+    return {"pen": pen, "core_len": int(d["core_len"]), "max_pen": float(d["max_pen"])}
+
+
+def load_penalties(path=None) -> dict | None:
+    """Load the committed production penalty table (fit on all measured off-targets), or None if absent."""
+    import json
+    from pathlib import Path
+    if path is None:
+        try:
+            from pen_stack._resources import resource
+            path = resource("data/curated/bridge_offtarget_energetics.json")
+        except Exception: # noqa: BLE001 - not present in a bare wheel
+            return None
+    p = Path(path)
+    return from_json(json.loads(p.read_text(encoding="utf-8"))) if p.exists() else None

pen_stack/bridge/ortholog_screen.py

@@ -0,0 +1,73 @@
+"""72-system bridge-recombinase ortholog characterisation.
+
+EXPLORATORY, descriptive only. The Perry 2025 Table S1 lists 72 bridge-recombinase orthologs with their
+recombinase sequence, bRNA, donor and target, but it does NOT include a per-system human-cell activity
+value, so a supervised ortholog-activity *predictor* cannot be trained from the public tables. Instead we
+provide a descriptive characterisation: sequence-feature summaries and a similarity ranking to the
+one experimentally-validated standout (ISCro4). This is a *feature* (a way to organise the 72 systems),
+not a method, and must not be read as an activity prediction.
+
+N = 72 (small). Do not lean on this; it is a secondary, exploratory result with an explicit caveat.
+"""
+from __future__ import annotations
+
+from collections import Counter
+
+import pandas as pd
+
+_AA = "ACDEFGHIKLMNPQRSTVWY"
+
+
+def _kmer_vec(seq: str, k: int = 2) -> Counter:
+    seq = "".join(c for c in str(seq).upper() if c in _AA)
+    return Counter(seq[i:i + k] for i in range(len(seq) - k + 1))
+
+
+def _cosine(a: Counter, b: Counter) -> float:
+    keys = set(a) | set(b)
+    dot = sum(a[k] * b[k] for k in keys)
+    na = sum(v * v for v in a.values()) ** 0.5
+    nb = sum(v * v for v in b.values()) ** 0.5
+    return float(dot / (na * nb)) if na and nb else 0.0
+
+
+def characterise(reference: str = "ISCro4") -> pd.DataFrame:
+    """Describe the 72 orthologs: length + 2-mer cosine similarity to the reference (ISCro4). Empty if S1 absent."""
+    from pen_stack.bridge.ingest import load_screen
+    s1 = load_screen()
+    if s1.empty:
+        return pd.DataFrame()
+    s1 = s1.dropna(subset=["Recombinase_Sequence"]).copy()
+    s1["length_aa"] = s1["Recombinase_Sequence"].str.len()
+    ref_rows = s1[s1["Name"].astype(str) == reference]
+    if ref_rows.empty:
+        return s1[["Name", "length_aa"]].assign(similarity_to_ref=float("nan"), reference=reference)
+    ref_vec = _kmer_vec(ref_rows.iloc[0]["Recombinase_Sequence"])
+    s1["similarity_to_ref"] = s1["Recombinase_Sequence"].apply(lambda x: _cosine(_kmer_vec(x), ref_vec))
+    s1["reference"] = reference
+    return (s1[["Name", "length_aa", "similarity_to_ref", "reference"]]
+            .sort_values("similarity_to_ref", ascending=False).reset_index(drop=True))
+
+
+def summary(reference: str = "ISCro4") -> dict:
+    df = characterise(reference)
+    if df.empty:
+        return {"available": False, "note": "Perry 2025 Table S1 not present"}
+    return {
+        "available": True,
+        "exploratory": True,
+        "n_systems": int(len(df)),
+        "reference": reference,
+        "length_range_aa": [int(df["length_aa"].min()), int(df["length_aa"].max())],
+        "median_length_aa": int(df["length_aa"].median()),
+        "most_similar_to_ref": df[df["Name"].astype(str) != reference].head(5)[
+            ["Name", "similarity_to_ref"]].round(3).to_dict("records"),
+        "caveat": "DESCRIPTIVE ONLY. Table S1 has no per-system activity label, so this is NOT an activity "
+                  "predictor; it is a sequence-similarity organisation of the 72 systems relative to the one "
+                  "validated standout (ISCro4). N=72 (small). Do not interpret similarity as predicted activity.",
+    }
+
+
+if __name__ == "__main__": # pragma: no cover
+    import json
+    print(json.dumps(summary(), indent=2, default=str))

pen_stack/bridge/pipeline.py

@@ -0,0 +1,83 @@
+"""pen-bridge: design + assess a bridge-RNA.
+
+WRAPS the authoritative Arc BridgeRNADesigner (``bridgernadesigner``) - does not reimplement it - and adds
+the PEN-STACK layer on top: genome-wide off-target prediction, fold + cross-loop QC, and
+optional overlay with the safety layer (is an off-target in a dangerous locus?).
+
+Graceful: if ``bridgernadesigner`` is absent, off-target + cross-loop still run on the user-supplied
+target/donor cores; only the full scaffold sequence (for ViennaRNA folding) needs the designer.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from pen_stack.bridge.fold_qc import qc_verdict
+from pen_stack.bridge.offtarget import scan_offtargets
+
+# default hg38 locations (VM); overridable
+_HG38_CANDIDATES = [
+    Path.home() / "cast-bench" / "data" / "external" / "genomes" / "hg38.fa",
+    Path("/work/data/external/genomes/hg38.fa"),
+    Path("data/external/genomes/hg38.fa"),
+]
+
+
+def _hg38() -> Path | None:
+    import os
+    env = os.environ.get("PEN_HG38")
+    if env and Path(env).exists():
+        return Path(env)
+    return next((p for p in _HG38_CANDIDATES if p.exists()), None)
+
+
+def design_brna(target: str, donor: str, scaffold: str = "ISCro4_enhanced") -> dict:
+    """Call the wrapped Arc designer. Returns the bridge sequence + cores, or a graceful note."""
+    try:
+        from bridgernadesigner.run import design_bridge_rna
+    except Exception as e: # noqa: BLE001
+        return {"available": False, "target": target.upper(), "donor": donor.upper(),
+                "scaffold": scaffold, "note": f"bridgernadesigner not installed ({e}); pip install bridgernadesigner"}
+    brna = design_bridge_rna(target, donor, scaffold)
+    return {"available": True, "scaffold": scaffold, "target": brna.target, "donor": brna.donor,
+            "bridge_sequence": brna.bridge_sequence}
+
+
+def design_and_assess(target: str, donor: str, scaffold: str = "ISCro4_enhanced",
+                      chroms: list[str] | None = None, fasta: str | Path | None = None,
+                      ct: str | None = None, scan: bool = True) -> dict:
+    """End-to-end: design (wrapped) -> off-target + fold/cross-loop QC -> optional safety overlay."""
+    brna = design_brna(target, donor, scaffold)
+    tcore, dcore = brna["target"], brna["donor"]
+
+    qc = qc_verdict(tcore, dcore, brna.get("bridge_sequence"))
+
+    off = {"scanned": False}
+    if scan:
+        fa = Path(fasta) if fasta else _hg38()
+        if fa and fa.exists():
+            chroms = chroms or [f"chr{i}" for i in range(1, 23)] + ["chrX"]
+            df = scan_offtargets(fa, tcore, chroms)
+            if ct is not None:
+                df = annotate_with_safety(df, ct)
+            off = {"scanned": True, "n_candidates": int(len(df)),
+                   "n_exact": int((df["n_mm"] == 0).sum()) if not df.empty else 0,
+                   "table": df}
+        else:
+            off = {"scanned": False, "note": "hg38 fasta not found; set PEN_HG38 or pass fasta="}
+
+    return {"brna": brna, "offtargets": off, "qc": qc,
+            "disclaimer": "Decision-support only; predicted off-targets require experimental validation."}
+
+
+def annotate_with_safety(off_df, ct: str):
+    """Overlay each off-target with the safety score (is the off-target in a dangerous locus?)."""
+    if off_df.empty:
+        return off_df
+    try:
+        from pen_stack.atlas.crosslink import load_writability
+        wdf = load_writability(ct)[["chrom", "bin", "safety"]]
+        out = off_df.copy()
+        out["bin"] = (out["pos"] // 1000).astype(int)
+        return out.merge(wdf, on=["chrom", "bin"], how="left")
+    except Exception: # noqa: BLE001 - safety overlay is optional
+        return off_df

pen_stack/build/__init__.py

@@ -0,0 +1,16 @@
+"""pen_stack.build, the digital→physical bridge.
+
+Make designs executable and results ingestible, loop-ready and lab-optional, with safety wired in at the point
+where software reaches for the physical world: a cleared, legal design becomes a runnable protocol DRAFT
+carrying its immune-risk profile (refused outright if the safety gate flags it); a typed ingestion API
+returns experimental results as candidate evidence admitted only through the world-model gate; and a
+simulated lab runs the whole loop before any hardware exists. PEN-STACK emits protocols and ingests results, it
+does NOT run experiments.
+"""
+from __future__ import annotations
+
+from pen_stack.build.ingest import ResultSchemaError, ingest_result
+from pen_stack.build.protocol import ProtocolExportError, export_protocol
+from pen_stack.build.simlab import run_simulated
+
+__all__ = ["export_protocol", "ProtocolExportError", "ingest_result", "ResultSchemaError", "run_simulated"]

pen_stack/build/cloudlab.py

@@ -0,0 +1,74 @@
+"""Cloud-lab connector: safety-gated export -> a cloud-lab submission -> gated ingest.
+
+Bridges the build interface to a cloud lab (Ginkgo / Emerald / Strateos style). The HARD invariant: the
+biosecurity gate runs BEFORE any submission. A flagged or illegal design makes ``export_protocol`` raise, so no
+protocol is emitted and nothing hazardous can be submitted through the loop. Submission is mock / dry-run
+(the executable spec is the deliverable; a real wet run needs a partner and budget, the standing
+bottleneck, surfaced not hidden). A returned readout is ingested only through an explicit human-in-control gate
+(Level 3). Nothing is fabricated: a mock job carries a deterministic receipt, never a pretend measurement.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from pen_stack.build.protocol import ProtocolExportError, export_protocol
+
+# mock is the only provider WIRED (a local dry-run receipt). The named providers are recognised but route to the
+# mock path, since a real submission needs credentials + budget (disclosed, not faked).
+_PROVIDERS = {"mock", "ginkgo", "emerald", "strateos"}
+
+
+class CloudLabError(RuntimeError):
+    """Raised for a connector-level error (unknown provider, etc.). Safety refusals raise ProtocolExportError."""
+
+
+def _digest(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def submit(design: dict, experiment: dict, *, provider: str = "mock", target: str = "opentrons",
+           actor: str = "anonymous") -> dict[str, Any]:
+    """Safety-gate + export a protocol and submit it to a cloud lab (mock / dry-run).
+
+    HARD GATE: ``export_protocol`` refuses a flagged or illegal design (raises ``ProtocolExportError``); we let it
+    raise, so a hazardous design never reaches submission. Returns a mock job receipt for a cleared design.
+    """
+    if provider not in _PROVIDERS:
+        raise CloudLabError(f"unknown provider {provider!r}; choose from {sorted(_PROVIDERS)}")
+    protocol = export_protocol(design, experiment, target=target, actor=actor)  # biosecurity gate; may raise
+    sha = _digest(protocol)
+    return {
+        "provider": provider,
+        "dry_run": True,
+        "status": "submitted_mock",
+        "job_id": f"{provider}-{sha[:16]}",
+        "protocol_sha256": sha,
+        "protocol_preview": protocol[:400],
+        "biosecurity_gate": "passed (export not blocked)",
+        "autonomy_level": 3,
+        "human_in_control": True,
+        "note": ("mock / dry-run submission; a real cloud-lab run needs a partner + budget (the standing "
+                 "bottleneck). The executable protocol is the deliverable."),
+    }
+
+
+def submit_gated(design: dict, experiment: dict, **kw: Any) -> dict[str, Any]:
+    """Like :func:`submit`, but returns a STRUCTURED refusal instead of raising when the gate blocks the design,
+    so an agent can branch on it (``blocked == True``). A blocked design emits NO protocol."""
+    try:
+        return submit(design, experiment, **kw)
+    except ProtocolExportError as e:
+        return {"submitted": False, "blocked": True, "reason": str(e),
+                "biosecurity_gate": "blocked export (refused)", "human_in_control": True,
+                "note": "the biosecurity gate refused this design; nothing was submitted"}
+
+
+def ingest_readout(job_id: str, readout: dict, *, admitted_by: str | None = None) -> dict[str, Any]:
+    """Ingest a cloud-lab readout through the Level-3 human-in-control gate. Requires ``admitted_by`` (a human
+    approves belief admission); a readout with no approver is held, never auto-admitted. Never fabricated."""
+    if not admitted_by:
+        return {"job_id": job_id, "admitted": False, "held": True,
+                "note": "a human must admit this readout (Level-3 belief-admission gate); not auto-admitted"}
+    return {"job_id": job_id, "admitted": True, "admitted_by": admitted_by, "readout": readout,
+            "autonomy_level": 3, "human_in_control": True, "no_fabrication": True}

pen_stack/build/ingest.py

@@ -0,0 +1,47 @@
+"""Typed, gated result-ingestion API, the digital→physical bridge.
+
+An experimental result enters PEN-STACK as CANDIDATE evidence, never auto-merged: it is turned into a measured
+edge Candidate and quarantined. The ONLY path into the curated world-model is the gate (`gate_admit`) with
+automated checks AND explicit human approval, inheriting Principle 1 (no process auto-edits the world-model).
+Immune-measurement results can begin validating the proxies on a later pass.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pen_stack.graph.ingest import Candidate, gate_admit
+
+
+class ResultSchemaError(ValueError):
+    """Raised when an ingested result is missing required fields (assay / readout / provenance)."""
+
+
+def _validate_result_schema(result: dict) -> dict:
+    for k in ("assay", "readout", "provenance"):
+        if result.get(k) is None:
+            raise ResultSchemaError(f"result missing required field {k!r}")
+    prov = result["provenance"]
+    if not (prov.get("source") or prov.get("doi") or prov.get("europepmc")):
+        raise ResultSchemaError("result provenance must carry source / doi / europepmc id")
+    return result
+
+
+def _as_candidate(result: dict) -> Candidate:
+    """A measured outcome -> a quarantined measured EDGE candidate (design --measured_outcome--> outcome)."""
+    src = result.get("design_id", "design:anon")
+    payload = {"src": src, "dst": f"outcome:{result['assay']}", "etype": "measured_outcome",
+               "confidence": result.get("confidence"), "scope": result.get("scope"),
+               "readout": result["readout"], "units": result.get("units")}
+    return Candidate(kind="edge", payload=payload, provenance=result["provenance"], evidence="measured",
+                     note="ingested experimental result (quarantined; admit only via the gate)")
+
+
+def ingest_result(result: dict, *, admitted_by: str | None = None, graph: Any = None,
+                  approved: bool = False) -> Any:
+    """Validate + quarantine an experimental result as a measured Candidate. With `admitted_by` + a `graph` +
+    explicit `approved=True`, route it through the gate (the ONLY path into the curated world-model);
+    otherwise return the quarantined Candidate (never auto-merged)."""
+    cand = _as_candidate(_validate_result_schema(result))
+    if admitted_by is not None and graph is not None and approved:
+        return gate_admit(graph, cand, approved=True, admitted_by=admitted_by)
+    return cand # quarantined; no auto-edit of curated truth