Deploy 07ea2d8

Therapeutic compiler: lower a variant to an edit, or refuse and say why

Source: https://github.com/WINTER4000/turingDNA/commit/07ea2d8cfbde99036b0be78acd5954dc05976393

dee/core/compiler.py

@@ -0,0 +1,561 @@
+"""The therapeutic compiler — lower a pathogenic variant to an editing strategy.
+
+A compiler is not a pipeline with a nicer name. What makes this one is that it
+**refuses to compile** and says why. A tool that always returns a strategy for
+a patient's variant is a plausible-answer generator, and in this domain a
+plausible answer is worse than none: it is the kind of output that gets built
+on. "This is a 4 kb deletion; no base or prime editor addresses it" is the
+useful answer, and it is the one nobody ships.
+
+So the diagnostics below are the product. The strategies are what falls out
+when there are no errors.
+
+Same discipline as dee/core/edits.py ("REFUSE ON MISMATCH... a silent
+off-by-one here is not a bug report, it is a scientist ordering the wrong
+DNA"), applied one level up: here a silent wrong answer is a scientist
+designing the wrong therapy.
+
+SCOPE, enforced in code and not only in copy
+--------------------------------------------
+* **Somatic only.** Germline and embryo applications are refused outright
+  (:func:`compile_correction` raises on ``germline=True``). This is the line
+  the field draws and this module does not sit on it.
+* **Design and assessment, not a clinical decision.** The output is a design
+  record for humans to evaluate. It is not IND-ready, it does not clear a
+  strategy for use, and nothing here should reach a patient without the
+  ordinary preclinical program.
+* **Predicted specificity is not measured specificity.** Off-target search
+  narrows where to look. It does not replace GUIDE-seq / CIRCLE-seq or any
+  other empirical assay.
+* **Out of scope entirely:** immunogenicity, pharmacokinetics, dosing,
+  manufacturing, and delivery efficacy. The compiler is silent on all of
+  them rather than guessing.
+
+This module is PURE LOGIC — no network, no GPU, no model. Everything here is
+a deterministic consequence of the two alleles and the genetic code, which is
+why it can be tested exhaustively. Model-derived judgements (what a bystander
+edit *does*) live outside it and are attached later, clearly labelled as
+predictions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+__all__ = [
+    "Diagnostic", "Correction", "LesionCall",
+    "classify_lesion", "restores_wildtype", "compile_correction",
+    "GermlineRefused",
+]
+
+_COMPLEMENT = {"A": "T", "T": "A", "C": "G", "G": "C"}
+_BASES = frozenset("ACGT")
+
+# Base editors make exactly two chemistries. Everything downstream follows
+# from this and nothing else:
+#   ABE  adenine base editor   A -> G
+#   CBE  cytosine base editor  C -> T
+_ABE_CHANGE = ("A", "G")
+_CBE_CHANGE = ("C", "T")
+
+# Routing bounds for prime editing, NOT capability guarantees. Published PE
+# work spans a range that depends on the construct, the locus and the cell
+# type, so a hard biological limit would be a fiction. These are deliberately
+# conservative and are used only to decide "route to PE" vs "refuse" — a
+# lesion near the boundary gets a warning saying the call is marginal, not a
+# promise that it will work.
+PRIME_EDIT_INSERT_BOUND = 44
+PRIME_EDIT_DELETE_BOUND = 80
+
+
+class GermlineRefused(Exception):
+    """Raised for any germline or embryo request. Not a routing decision."""
+
+
+@dataclass
+class Diagnostic:
+    """One compiler message. `code` is stable; `message` is for humans.
+
+    `remedy` is the field that makes a refusal useful instead of merely
+    correct — it says what would have to change for this to compile.
+    """
+    level: str          # "error" | "warning" | "note"
+    code: str
+    message: str
+    remedy: str = ""
+
+    @property
+    def blocking(self) -> bool:
+        return self.level == "error"
+
+
+@dataclass
+class Correction:
+    """The change that restores wild-type, and which chemistry can make it.
+
+    `strand` matters and is the part most easily got wrong. A base editor
+    only ever writes A->G (ABE) or C->T (CBE) on the strand it engages. A
+    sense-strand T->C is therefore an ABE edit — on the ANTISENSE strand,
+    where that position reads A and must become G. Getting this backwards
+    designs a guide against the wrong strand, which fails silently in
+    silico and expensively at the bench.
+    """
+    wt_base: str
+    patient_base: str
+    sense_change: str        # what must happen on the sense strand, "T>C"
+    strand: str              # "sense" | "antisense" — where the editor works
+    editor_change: str       # what the editor actually writes, "A>G"
+    editor_family: str       # "ABE" | "CBE"
+
+
+@dataclass
+class LesionCall:
+    """What kind of lesion this is and what could address it."""
+    kind: str                # substitution | insertion | deletion | delins | identity
+    size: int                # bases changed (max of ref/alt length for delins)
+    is_transition: bool
+    correction: Optional[Correction]
+    route: str               # "base_editing" | "prime_editing" | "none"
+    diagnostics: List[Diagnostic] = field(default_factory=list)
+
+    @property
+    def compiles(self) -> bool:
+        return not any(d.blocking for d in self.diagnostics)
+
+    def errors(self) -> List[Diagnostic]:
+        return [d for d in self.diagnostics if d.blocking]
+
+
+def _clean_allele(value: str) -> str:
+    """Alleles arrive as '-', '', 'del', or real bases. Normalise to bases."""
+    v = "".join(str(value or "").split()).upper()
+    if v in ("-", ".", "DEL", "NONE", "NULL"):
+        return ""
+    return v
+
+
+def _is_transition(a: str, b: str) -> bool:
+    """A<->G or C<->T. Everything else is a transversion."""
+    return {a, b} in ({"A", "G"}, {"C", "T"})
+
+
+def _base_editor_for(wt: str, patient: str) -> Optional[Correction]:
+    """Which base editor, if any, restores `wt` from `patient`.
+
+    The whole derivation, because it is short and worth being able to check:
+
+        sense A->G   ABE reads A, writes G          -> ABE, sense
+        sense C->T   CBE reads C, writes T          -> CBE, sense
+        sense T->C   antisense reads A, writes G    -> ABE, antisense
+        sense G->A   antisense reads C, writes T    -> CBE, antisense
+
+    Every remaining substitution is a transversion (A<->C, A<->T, C<->G,
+    G<->T), and neither chemistry produces one on either strand. There is no
+    base-editing route to a transversion — that is a fact about the enzymes,
+    not a gap in this function.
+    """
+    change = (patient, wt)          # from the patient's base, back to wild-type
+    if change == _ABE_CHANGE:
+        return Correction(wt, patient, f"{patient}>{wt}", "sense", "A>G", "ABE")
+    if change == _CBE_CHANGE:
+        return Correction(wt, patient, f"{patient}>{wt}", "sense", "C>T", "CBE")
+
+    anti = (_COMPLEMENT[patient], _COMPLEMENT[wt])
+    if anti == _ABE_CHANGE:
+        return Correction(wt, patient, f"{patient}>{wt}", "antisense", "A>G", "ABE")
+    if anti == _CBE_CHANGE:
+        return Correction(wt, patient, f"{patient}>{wt}", "antisense", "C>T", "CBE")
+    return None
+
+
+def classify_lesion(wt_allele: str, patient_allele: str) -> LesionCall:
+    """Route a lesion to an editing chemistry, or refuse with a reason.
+
+    `wt_allele` is the reference/wild-type allele and `patient_allele` is what
+    the patient carries. Correction runs patient -> wild-type; passing them
+    the wrong way round designs an editor that installs the disease, so the
+    argument names are deliberately not `ref`/`alt` (which flip meaning
+    depending on whether you are reading a VCF or thinking about a therapy).
+    """
+    wt = _clean_allele(wt_allele)
+    pt = _clean_allele(patient_allele)
+    diags: List[Diagnostic] = []
+
+    bad = [b for b in (wt + pt) if b not in _BASES]
+    if bad:
+        diags.append(Diagnostic(
+            "error", "non_dna_allele",
+            f"Alleles must be A/C/G/T; got {sorted(set(bad))!r}.",
+            "Supply unambiguous bases. IUPAC ambiguity codes and amino-acid "
+            "letters are not alleles and cannot be routed."))
+        return LesionCall("invalid", 0, False, None, "none", diags)
+
+    if not wt and not pt:
+        diags.append(Diagnostic(
+            "error", "empty_alleles", "Both alleles are empty.",
+            "Give the wild-type and patient alleles for the position."))
+        return LesionCall("invalid", 0, False, None, "none", diags)
+
+    if wt == pt:
+        diags.append(Diagnostic(
+            "error", "no_lesion",
+            "Wild-type and patient alleles are identical — there is nothing "
+            "to correct.",
+            "Check the alleles are not swapped, and that the variant call is "
+            "against the intended reference."))
+        return LesionCall("identity", 0, False, None, "none", diags)
+
+    # ── substitution ────────────────────────────────────────────────────
+    if len(wt) == 1 and len(pt) == 1:
+        transition = _is_transition(wt, pt)
+        corr = _base_editor_for(wt, pt)
+        if corr is not None:
+            return LesionCall("substitution", 1, transition, corr,
+                              "base_editing", diags)
+        diags.append(Diagnostic(
+            "warning", "transversion_no_base_editor",
+            f"{pt}>{wt} is a transversion. No base editor makes this change "
+            "on either strand — ABE writes A>G and CBE writes C>T, and "
+            "neither produces a transversion.",
+            "Prime editing is the route for transversions. This platform "
+            "does not design pegRNAs yet, so the strategy stops here rather "
+            "than offering a guide that cannot install the change."))
+        diags.append(Diagnostic(
+            "error", "prime_editing_unavailable",
+            "Prime editing is required and is not implemented in this "
+            "compiler.",
+            "Design the pegRNA in a dedicated prime-editing tool; the "
+            "specificity and consequence passes here still apply to it."))
+        return LesionCall("substitution", 1, transition, None,
+                          "prime_editing", diags)
+
+    # ── indels and delins ───────────────────────────────────────────────
+    if not pt:
+        kind, size = "deletion", len(wt)
+        bound, what = PRIME_EDIT_DELETE_BOUND, "deletion"
+    elif not wt:
+        kind, size = "insertion", len(pt)
+        bound, what = PRIME_EDIT_INSERT_BOUND, "insertion"
+    else:
+        kind, size = "delins", max(len(wt), len(pt))
+        bound, what = PRIME_EDIT_INSERT_BOUND, "replacement"
+
+    diags.append(Diagnostic(
+        "note", "indel_not_base_editable",
+        f"A {size}-base {kind} cannot be corrected by base editing — base "
+        "editors rewrite one base chemically and do not add or remove any.",
+        "Prime editing is the route for indels of this size."))
+
+    if size > bound:
+        diags.append(Diagnostic(
+            "error", "lesion_too_large",
+            f"A {size}-base {what} is beyond what this compiler will route "
+            f"to prime editing (bound {bound}).",
+            "Larger lesions need a different modality — integrase or "
+            "recombinase-based insertion, or gene addition. Those are not "
+            "editing strategies and are outside this compiler."))
+        return LesionCall(kind, size, False, None, "none", diags)
+
+    if size > bound // 2:
+        diags.append(Diagnostic(
+            "warning", "lesion_near_bound",
+            f"A {size}-base {what} is large for prime editing; efficiency "
+            "falls off with edit size and varies by locus and cell type.",
+            "Treat the route as marginal and plan an empirical check early."))
+
+    diags.append(Diagnostic(
+        "error", "prime_editing_unavailable",
+        "Prime editing is required and is not implemented in this compiler.",
+        "Design the pegRNA in a dedicated prime-editing tool; the "
+        "specificity and consequence passes here still apply to it."))
+    return LesionCall(kind, size, False, None, "prime_editing", diags)
+
+
+def restores_wildtype(window: str, offset: int, corr: Correction) -> bool:
+    """The compiler's type-check: does applying `corr` actually give wild-type?
+
+    `window` is reference (wild-type) sequence and `offset` is the 0-based
+    index of the variant position within it. The patient's sequence is the
+    window with the patient's base substituted in; applying the correction
+    must return it to the reference exactly.
+
+    This exists because every other check in this module reasons about
+    ALLELES, and a position that has drifted by one still type-checks at the
+    allele level while pointing at the wrong base. Comparing whole sequences
+    catches that.
+    """
+    if not window or not (0 <= offset < len(window)):
+        return False
+    if window[offset] != corr.wt_base:
+        return False
+    patient_seq = window[:offset] + corr.patient_base + window[offset + 1:]
+    corrected = patient_seq[:offset] + corr.wt_base + patient_seq[offset + 1:]
+    return corrected == window
+
+
+def compile_correction(wt_allele: str, patient_allele: str, *,
+                       window: str = "", offset: int = -1,
+                       germline: bool = False) -> LesionCall:
+    """Front door. Classifies, then verifies against real sequence if given.
+
+    `germline=True` is refused rather than routed — see the module docstring.
+    It raises instead of returning a diagnostic because a refusal that a
+    caller can read past and keep going is not a refusal.
+    """
+    if germline:
+        raise GermlineRefused(
+            "This compiler designs somatic therapeutic edits only. Germline "
+            "and embryo editing are out of scope and are not routed here.")
+
+    call = classify_lesion(wt_allele, patient_allele)
+    if call.correction is None or not window:
+        return call
+
+    if offset < 0 or offset >= len(window):
+        call.diagnostics.append(Diagnostic(
+            "error", "offset_outside_window",
+            f"Variant offset {offset} is outside the {len(window)}-base "
+            "reference window.",
+            "Give the 0-based index of the variant within the window you "
+            "supplied."))
+        return call
+
+    observed = window[offset]
+    if observed != call.correction.wt_base:
+        # The single most valuable refusal in the module. Everything else is
+        # arithmetic on alleles; this is the check that catches a coordinate
+        # that is right by one, or a variant called on the other strand.
+        call.diagnostics.append(Diagnostic(
+            "error", "reference_mismatch",
+            f"The reference window has {observed!r} at offset {offset}, but "
+            f"the wild-type allele was given as {call.correction.wt_base!r}.",
+            "Refusing rather than editing a position the reference disagrees "
+            "about. Check the coordinate, the transcript, and whether the "
+            "variant was called on the opposite strand."))
+        return call
+
+    if not restores_wildtype(window, offset, call.correction):
+        call.diagnostics.append(Diagnostic(
+            "error", "correction_does_not_restore",
+            "Applying the correction does not reproduce the reference "
+            "sequence.",
+            "This is a compiler bug or a malformed window; do not proceed."))
+    return call
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# The pass pipeline
+# ═══════════════════════════════════════════════════════════════════════
+# A compiler shows its passes. This one shows the passes it CANNOT run and
+# why, which is the part that matters here: a therapeutic design tool that
+# quietly skips specificity analysis and prints a strategy is worse than one
+# that stops and says "the human off-target index does not cover intronic or
+# intergenic space, so I did not clear this guide".
+#
+# Every pass reports one of:
+#   ok           ran, nothing blocking
+#   warn         ran, with a caveat the designer must read
+#   error        ran, and refused
+#   unavailable  did NOT run, because this deployment cannot — with the reason
+#   skipped      did not run because an earlier pass already refused
+#
+# "unavailable" is deliberately distinct from "ok". Conflating them is how a
+# tool ends up implying it checked something it never looked at.
+
+PASS_ORDER: Tuple[Tuple[str, str], ...] = (
+    ("resolve",     "Resolve variant"),
+    ("classify",    "Classify lesion"),
+    ("verify",      "Verify against reference"),
+    ("enumerate",   "Enumerate strategies"),
+    ("consequence", "Assess edit consequence"),
+    ("specificity", "Assess specificity"),
+    ("emit",        "Emit design record"),
+)
+
+
+@dataclass
+class Pass:
+    name: str
+    title: str
+    status: str                 # ok | warn | error | unavailable | skipped
+    detail: str = ""
+    diagnostics: List[Diagnostic] = field(default_factory=list)
+
+
+@dataclass
+class CompileReport:
+    lesion: Optional[LesionCall]
+    passes: List[Pass]
+    scope: Dict[str, str]
+
+    @property
+    def compiled(self) -> bool:
+        """True only if every pass that RAN succeeded and none was skipped
+        for an upstream refusal. An 'unavailable' pass does not fail the
+        build, but it does mean the record is explicitly incomplete."""
+        return not any(p.status in ("error", "skipped") for p in self.passes)
+
+    @property
+    def incomplete_because(self) -> List[str]:
+        return [p.title for p in self.passes if p.status == "unavailable"]
+
+
+# What this deployment can and cannot do, stated once so the passes and the
+# UI cannot drift apart. Each entry is the honest reason a pass will report
+# `unavailable` — not a TODO, a disclosure.
+CAPABILITY_NOTES = {
+    "enumerate": (
+        "Guide enumeration for base editing runs here; prime-editing pegRNA "
+        "design does not exist in this platform, so any lesion routed to PE "
+        "stops before a strategy."),
+    "consequence": (
+        "Bystander consequence scoring uses a zero-shot genome model. It "
+        "ranks hypotheses about what an edit does; it has no validated "
+        "relationship to clinical outcome and does not substitute for a "
+        "functional assay."),
+    "specificity": (
+        "The human and mouse off-target index covers CODING SEQUENCE ONLY. "
+        "Intronic and intergenic off-targets sit outside it and are NOT "
+        "cleared here. For therapeutic work this pass does not replace "
+        "GUIDE-seq, CIRCLE-seq or an equivalent empirical assay."),
+}
+
+SCOPE = {
+    "application": "Somatic therapeutic design only. Germline and embryo "
+                   "editing are out of scope and refused.",
+    "status": "Design and assessment. Not IND-ready, not a clinical "
+              "decision, not a clearance of any strategy for use.",
+    "silent_on": "Immunogenicity, pharmacokinetics, dosing, manufacturing "
+                 "and delivery efficacy are not modelled and not reported.",
+}
+
+
+def compile_report(wt_allele: str, patient_allele: str, *,
+                   window: str = "", offset: int = -1,
+                   germline: bool = False,
+                   can_enumerate: bool = True,
+                   can_score_consequence: bool = False,
+                   can_check_specificity: bool = False) -> CompileReport:
+    """Run the passes and report every one, including those that could not run.
+
+    The three `can_*` flags are supplied by the caller from LIVE capability
+    checks (is the DNA model reachable, is an off-target index loaded), never
+    hardcoded — the same "availability must mean reachable" rule the rest of
+    this codebase learned the hard way. Defaulting the two model-backed passes
+    to False means a caller that forgets to check gets an honestly incomplete
+    record rather than a falsely complete one.
+    """
+    if germline:
+        raise GermlineRefused(
+            "This compiler designs somatic therapeutic edits only. Germline "
+            "and embryo editing are out of scope and are not routed here.")
+
+    passes: List[Pass] = []
+    titles = dict(PASS_ORDER)
+
+    def add(name, status, detail="", diags=None):
+        passes.append(Pass(name, titles[name], status, detail, diags or []))
+
+    # ── resolve ─────────────────────────────────────────────────────────
+    if window:
+        add("resolve", "ok",
+            f"{len(window)} nt of reference supplied; variant at offset {offset}.")
+    else:
+        add("resolve", "warn",
+            "No reference window supplied — the lesion can be classified from "
+            "alleles alone, but nothing can be checked against real sequence.")
+
+    # ── classify ────────────────────────────────────────────────────────
+    lesion = classify_lesion(wt_allele, patient_allele)
+    if lesion.errors():
+        add("classify", "error",
+            f"{lesion.kind} — no route.", lesion.diagnostics)
+        for name, _ in PASS_ORDER[2:]:
+            add(name, "skipped", "An earlier pass refused.")
+        return CompileReport(lesion, passes, dict(SCOPE))
+
+    corr = lesion.correction
+    add("classify", "warn" if any(d.level == "warning" for d in lesion.diagnostics) else "ok",
+        f"{lesion.kind}: {corr.sense_change} corrected by {corr.editor_family} "
+        f"on the {corr.strand} strand." if corr else lesion.kind,
+        lesion.diagnostics)
+
+    # ── verify ──────────────────────────────────────────────────────────
+    if window and corr:
+        verified = compile_correction(wt_allele, patient_allele,
+                                      window=window, offset=offset)
+        new = [d for d in verified.diagnostics if d not in lesion.diagnostics]
+        if verified.errors():
+            add("verify", "error", "Reference disagrees with the alleles.", new)
+            for name, _ in PASS_ORDER[3:]:
+                add(name, "skipped", "An earlier pass refused.")
+            return CompileReport(verified, passes, dict(SCOPE))
+        add("verify", "ok",
+            f"Reference has {corr.wt_base} at offset {offset}; the correction "
+            "reproduces it exactly.", new)
+        lesion = verified
+    else:
+        add("verify", "unavailable",
+            "No reference window, so the coordinate could not be checked. An "
+            "off-by-one still type-checks at the allele level.")
+
+    # ── enumerate ───────────────────────────────────────────────────────
+    if can_enumerate:
+        add("enumerate", "ok",
+            f"Base-editing guides can be enumerated for a {corr.editor_family} "
+            f"edit on the {corr.strand} strand.")
+    else:
+        add("enumerate", "unavailable", CAPABILITY_NOTES["enumerate"])
+
+    # ── consequence ─────────────────────────────────────────────────────
+    add("consequence", "ok" if can_score_consequence else "unavailable",
+        CAPABILITY_NOTES["consequence"])
+
+    # ── specificity ─────────────────────────────────────────────────────
+    # Always carries its caveat, even when it runs: a pass that reports "ok"
+    # on a coding-sequence-only index would read as a clean bill of health.
+    add("specificity", "warn" if can_check_specificity else "unavailable",
+        CAPABILITY_NOTES["specificity"])
+
+    # ── emit ────────────────────────────────────────────────────────────
+    add("emit", "ok",
+        "Design record assembled with every pass, its status, and the "
+        "reasons for anything not run.")
+
+    return CompileReport(lesion, passes, dict(SCOPE))
+
+
+def report_to_dict(report: CompileReport) -> Dict[str, object]:
+    """JSON shape for the API. Deliberately verbose: the record is the point,
+    so nothing is elided to make the payload tidy."""
+    def diag(d: Diagnostic):
+        return {"level": d.level, "code": d.code,
+                "message": d.message, "remedy": d.remedy}
+
+    lesion = report.lesion
+    corr = lesion.correction if lesion else None
+    return {
+        "compiled": report.compiled,
+        "incomplete_because": report.incomplete_because,
+        "scope": report.scope,
+        "lesion": {
+            "kind": lesion.kind,
+            "size": lesion.size,
+            "is_transition": lesion.is_transition,
+            "route": lesion.route,
+        } if lesion else None,
+        "correction": {
+            "wt_base": corr.wt_base,
+            "patient_base": corr.patient_base,
+            "sense_change": corr.sense_change,
+            "strand": corr.strand,
+            "editor_change": corr.editor_change,
+            "editor_family": corr.editor_family,
+        } if corr else None,
+        "passes": [
+            {"name": p.name, "title": p.title, "status": p.status,
+             "detail": p.detail, "diagnostics": [diag(d) for d in p.diagnostics]}
+            for p in report.passes
+        ],
+    }

dee/server.py

@@ -824,6 +824,7 @@ _RL_RULES = [
     # to fall back to. Tighter than every other tool bucket on purpose: this
     # limit is about the GPU bill, not about protecting a worker thread.
     ("/api/dna/generate",              (6,   60)),   # autoregressive — priciest
+    ("/api/compiler",                  (30,  60)),   # pure logic; probes DNA reach
     ("/api/dna",                       (12,  60)),
     ("/api/plasmid",                   (60,  60)),
     ("/api/ping",                      (60,  60)),   # dwell heartbeat — its own
@@ -872,6 +873,7 @@ _EVENT_KINDS = {
     "/api/de/round2":       "de_round2",
     "/api/dna/score":       "dna_score",
     "/api/dna/generate":    "dna_generate",
+    "/api/compiler/compile": "therapeutic_compile",
 }
 # Sort longest-prefix-first so the most specific rule matches.
 _RL_RULES.sort(key=lambda r: len(r[0]), reverse=True)
@@ -3410,6 +3412,54 @@ def create_app() -> Flask:
             }), 502
         return jsonify(result)
 
+    # ── Therapeutic compiler ─────────────────────────────────────────────
+    # Lowers a pathogenic variant to an editing strategy, or refuses with a
+    # diagnostic. See dee/core/compiler.py for the scope this operates in —
+    # somatic design and assessment only, never a clinical decision.
+    @app.post("/api/compiler/compile")
+    def compiler_compile() -> Response:
+        gate = _dna_signin_gate("compiler")
+        if gate is not None:
+            return gate
+
+        body = request.get_json(force=True, silent=True) or {}
+        wt = str(body.get("wt_allele") or "")
+        patient = str(body.get("patient_allele") or "")
+        window = "".join(str(body.get("window") or "").split()).upper()
+        try:
+            offset = int(body.get("offset", -1))
+        except (TypeError, ValueError):
+            return jsonify({"error": "offset must be an integer"}), 400
+
+        if not wt and not patient:
+            return jsonify({"error": "missing 'wt_allele' and 'patient_allele'"}), 400
+
+        # Capability comes from a LIVE probe, never a constant. A pass that
+        # cannot run must report `unavailable`, and the only way to know is to
+        # ask. Specificity stays off in this version on purpose: the human
+        # off-target index is coding-sequence only, so this endpoint does not
+        # claim to have cleared a guide it never checked outside coding space.
+        try:
+            can_score = bool(_dna_scoring.runnable("achilles"))
+        except Exception:  # noqa: BLE001 — capability must never break a compile
+            app.logger.debug("DNA capability probe failed", exc_info=True)
+            can_score = False
+
+        try:
+            report = _compiler.compile_report(
+                wt, patient, window=window, offset=offset,
+                germline=bool(body.get("germline")),
+                can_enumerate=True,
+                can_score_consequence=can_score,
+                can_check_specificity=False,
+            )
+        except _compiler.GermlineRefused as exc:
+            # 422, not 400: the request is well-formed and understood, and is
+            # being refused on scope. Distinct code so nothing retries it.
+            return jsonify({"error": str(exc), "kind": "out_of_scope"}), 422
+
+        return jsonify(_compiler.report_to_dict(report))
+
     @app.get("/api/benchmarks")
     def benchmarks() -> Response:
         """The receipts — how well the engine's zero-shot ranking predicts
@@ -4127,6 +4177,7 @@ _VALID_QUANT = {None, "", "none", "int8", "int4", "fp16", "bf16"}
 from dee.core import scoring as _scoring
 # DNA-level tiers (Evo 2, via Modal) — same "/api/models reports what's
 # actually runnable" contract, separate id-space (see the models() route).
+from dee.core import compiler as _compiler
 from dee.core import dna_scoring as _dna_scoring
 
 

dee/static/app.css

@@ -9814,3 +9814,150 @@ body.de-agent-run .dna-edit-actions { display: none; }
     .dna-meta, .dna-results-meta, .dna-scale-note,
     .dna-skipped-why, .dna-table th { font-size: 12px; }
 }
+
+/* ═══════════════════════════════════════════════════════════════════════
+   Therapeutic Compiler
+   The pass list is the hero. Passes light in sequence like a build log;
+   passes that did NOT run stay unlit and dashed, so a gap in the analysis
+   is something you SEE rather than something you have to read for.
+   ═══════════════════════════════════════════════════════════════════════ */
+
+.tc-scope {
+    display: flex; gap: 14px; align-items: flex-start;
+    padding: 14px 16px; margin-bottom: 18px;
+    border: 1px solid var(--line-strong); border-radius: var(--r-3);
+    background: var(--bg-raised);
+}
+.tc-scope-key {
+    font-size: 10.5px; letter-spacing: .1em; text-transform: uppercase;
+    color: var(--ink-faint); padding-top: 2px; flex-shrink: 0;
+}
+.tc-scope p { margin: 0; font-size: 12.5px; line-height: 1.6; color: var(--ink-soft); }
+
+.tc-alleles { display: flex; align-items: flex-end; gap: 14px; margin-bottom: 10px; }
+.tc-allele { display: flex; flex-direction: column; gap: 6px; }
+.tc-base, .tc-num {
+    font-family: var(--font-mono); font-size: 16px; text-align: center;
+    width: 130px; padding: 10px 12px;
+    border: 1px solid var(--line-strong); border-radius: var(--r-2);
+    background: var(--gray-0); color: var(--ink); text-transform: uppercase;
+}
+.tc-num { width: 130px; text-align: left; font-size: 13px; text-transform: none; }
+.tc-base:focus, .tc-num:focus { outline: none; border-color: var(--brand); }
+.tc-arrow { font-size: 18px; color: var(--ink-faint); padding-bottom: 12px; }
+
+.tc-actions { display: flex; gap: 10px; justify-content: flex-end; margin-top: 16px; flex-wrap: wrap; }
+
+/* ── verdict ── */
+.tc-verdict { padding: 14px 16px; border-radius: var(--r-3); margin-bottom: 16px; border-left: 3px solid var(--line-bold); background: var(--gray-1); }
+.tc-verdict.is-ok       { border-left-color: var(--success); }
+.tc-verdict.is-partial  { border-left-color: var(--warning); }
+.tc-verdict.is-refused  { border-left-color: var(--danger); }
+.tc-verdict-head { font-size: 15px; color: var(--ink-strong); font-weight: 600; }
+.tc-verdict-sub  { font-size: 12.5px; color: var(--ink-soft); margin-top: 4px; line-height: 1.5; }
+
+/* ── locus strip ── */
+.tc-locus { margin-bottom: 18px; }
+.tc-locus-row { display: flex; align-items: center; gap: 12px; overflow-x: auto; }
+.tc-locus-lbl { font-size: 10.5px; text-transform: uppercase; letter-spacing: .08em; color: var(--ink-faint); flex-shrink: 0; }
+.tc-seq { display: flex; gap: 1px; }
+.tc-b {
+    display: inline-flex; align-items: center; justify-content: center;
+    width: 20px; height: 26px; font-size: 13px; color: var(--ink-soft);
+    background: var(--gray-1); border-radius: 2px;
+}
+.tc-b--hit {
+    color: var(--on-ink); background: var(--danger);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--danger) 35%, transparent);
+    font-weight: 700;
+}
+.tc-locus-legend { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 10px; }
+.tc-chip {
+    font-size: 11.5px; padding: 3px 9px; border-radius: 999px;
+    border: 1px solid var(--line-strong); color: var(--ink-soft);
+}
+.tc-chip--pt { border-color: var(--danger); color: var(--danger); }
+.tc-chip--wt { border-color: var(--success); color: var(--success); }
+.tc-locus-note { font-size: 11.5px; color: var(--ink-faint); margin: 10px 0 0; line-height: 1.55; }
+
+/* ── the pass column ── */
+.tc-passes { list-style: none; margin: 0; padding: 0; position: relative; }
+/* the spine the passes hang from */
+.tc-passes::before {
+    content: ''; position: absolute; left: 11px; top: 12px; bottom: 12px;
+    width: 1px; background: var(--line);
+}
+.tc-pass {
+    position: relative; display: flex; gap: 14px; padding: 12px 0 12px 0;
+    opacity: 0; transform: translateY(4px);
+}
+.tc-pass.is-lit {
+    animation: tcLight .42s cubic-bezier(.2,.7,.3,1) forwards;
+    animation-delay: calc(var(--i) * 90ms);
+}
+@keyframes tcLight { to { opacity: 1; transform: none; } }
+@media (prefers-reduced-motion: reduce) {
+    .tc-pass, .tc-pass.is-lit { opacity: 1; transform: none; animation: none; }
+}
+
+.tc-pass-dot {
+    position: relative; z-index: 1; flex-shrink: 0;
+    width: 23px; height: 23px; border-radius: 50%;
+    display: inline-flex; align-items: center; justify-content: center;
+    font-size: 11px; border: 1px solid var(--line-strong);
+    background: var(--bg-card); color: var(--ink-faint);
+}
+.tc-pass--ok    .tc-pass-dot { border-color: var(--success); color: var(--success);
+                               box-shadow: 0 0 0 3px color-mix(in srgb, var(--success) 14%, transparent); }
+.tc-pass--warn  .tc-pass-dot { border-color: var(--warning); color: var(--warning);
+                               box-shadow: 0 0 0 3px color-mix(in srgb, var(--warning) 14%, transparent); }
+.tc-pass--error .tc-pass-dot { border-color: var(--danger); color: var(--danger);
+                               box-shadow: 0 0 0 3px color-mix(in srgb, var(--danger) 16%, transparent); }
+/* Unlit on purpose — dashed, no glow, dimmed. The visible hole. */
+.tc-pass--unavailable .tc-pass-dot,
+.tc-pass--skipped .tc-pass-dot { border-style: dashed; color: var(--ink-disabled); }
+.tc-pass--unavailable, .tc-pass--skipped { opacity: .62; }
+.tc-pass--unavailable.is-lit { animation-name: tcLightDim; }
+@keyframes tcLightDim { to { opacity: .62; transform: none; } }
+
+.tc-pass-body { min-width: 0; }
+.tc-pass-hd { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; }
+.tc-pass-title { font-size: 13.5px; color: var(--ink-strong); font-weight: 600; }
+.tc-pass-status {
+    font-size: 10.5px; text-transform: uppercase; letter-spacing: .07em;
+    color: var(--ink-faint);
+}
+.tc-pass--ok .tc-pass-status    { color: var(--success); }
+.tc-pass--warn .tc-pass-status  { color: var(--warning); }
+.tc-pass--error .tc-pass-status { color: var(--danger); }
+.tc-pass-detail { margin: 5px 0 0; font-size: 12.5px; line-height: 1.55; color: var(--ink-soft); }
+
+/* ── diagnostics ── */
+.tc-diags-hd {
+    font-size: 11px; text-transform: uppercase; letter-spacing: .08em;
+    color: var(--ink-faint); margin: 22px 0 10px;
+}
+.tc-diag {
+    padding: 11px 14px; border-radius: var(--r-2); margin-bottom: 9px;
+    border-left: 3px solid var(--line-bold); background: var(--gray-1);
+}
+.tc-diag--error   { border-left-color: var(--danger); }
+.tc-diag--warning { border-left-color: var(--warning); }
+.tc-diag--note    { border-left-color: var(--line-bold); }
+.tc-diag-top { display: flex; gap: 10px; align-items: baseline; flex-wrap: wrap; }
+.tc-diag-code { font-family: var(--font-mono); font-size: 11.5px; color: var(--ink); }
+.tc-diag-where { font-size: 10.5px; text-transform: uppercase; letter-spacing: .07em; color: var(--ink-faint); }
+.tc-diag-msg { margin: 6px 0 0; font-size: 12.5px; line-height: 1.55; color: var(--ink); }
+.tc-diag-remedy { margin: 6px 0 0; font-size: 12.5px; line-height: 1.55; color: var(--ink-soft); }
+
+@media (max-width: 720px) {
+    .tc-alleles { flex-direction: column; align-items: stretch; }
+    .tc-arrow { display: none; }
+    .tc-base, .tc-num { width: 100%; min-height: 44px; }
+    .tc-actions { flex-direction: column-reverse; }
+    .tc-actions button { width: 100%; min-height: 44px; }
+    .tc-scope { flex-direction: column; gap: 6px; }
+    .tc-b { width: 17px; height: 24px; font-size: 12px; }
+    .tc-scope p, .tc-pass-detail, .tc-diag-msg, .tc-diag-remedy,
+    .tc-locus-note, .tc-chip { font-size: 12px; }
+}

dee/static/app.js

@@ -392,7 +392,7 @@ renderGutter();
 // nav-rail peer anymore, it's what a session starts with.
 // 'dna' (Evo 2) sits next to 'design': DE designs at the protein level, DNA
 // Design at the nucleotide level. Same phase of the loop, different molecule.
-const ROUTES = ['mission', 'turing', 'structure', 'plasmid', 'design', 'dna', 'crispr', 'primers', 'docs'];
+const ROUTES = ['mission', 'turing', 'structure', 'plasmid', 'design', 'dna', 'compiler', 'crispr', 'primers', 'docs'];
 
 // ── UI mode flag (Mission-Control-+-Bench re-architecture, 2026-07-13) ──
 // 'bench' is now the default UI; ?ui=classic remains as a rollback escape
@@ -10314,6 +10314,7 @@ function runOracle(opts){
     const TOOLS = [
         { label: 'Evolve a sequence', hint: 'Directed evolution', route: 'design' },
         { label: 'Score a DNA change', hint: 'Promoters, splice sites, UTRs', route: 'dna' },
+        { label: 'Compile a variant correction', hint: 'Pathogenic variant \u2192 editing strategy', route: 'compiler' },
         { label: 'Build a plasmid', hint: 'Map & annotate a construct', route: 'plasmid' },
         { label: 'Design CRISPR guides', hint: 'Guides + specificity', route: 'crispr' },
         { label: 'Check primers', hint: 'Tm, dimers, specificity', route: 'primers' },
@@ -10955,7 +10956,7 @@ function runOracle(opts){
     // both are the Design phase, one at the protein level and one at the
     // nucleotide level. Bench is the DEFAULT UI — a route missing from this
     // list has a nav entry that goes nowhere.
-    const TAB_ROUTES = ['structure', 'design', 'dna', 'plasmid', 'crispr', 'primers'];
+    const TAB_ROUTES = ['structure', 'design', 'dna', 'plasmid', 'compiler', 'crispr', 'primers'];
     let current = null;   // { name, sub, phaseIdx, route }
 
     function el(id) { return document.getElementById(id); }
@@ -12275,3 +12276,203 @@ if (document.readyState === 'loading') {
         init();
     }
 }());
+
+
+// ═══════════════════════════════════════════════════════════════════════
+// Therapeutic Compiler
+// ═══════════════════════════════════════════════════════════════════════
+// Renders the pass list IN FULL, including passes that did not run. The
+// sequential reveal is not decoration: a build log arrives in order, and
+// seeing "Verify against reference" light up before "Assess specificity"
+// stays dark is the whole point. A tidy green column would imply checks
+// nobody performed.
+//
+// Status vocabulary, kept identical to dee/core/compiler.py so the two
+// cannot drift:
+//   ok | warn | error | unavailable | skipped
+// `unavailable` is deliberately NOT a failure and NOT a success — it is
+// "this deployment could not run this pass", drawn unlit.
+// ═══════════════════════════════════════════════════════════════════════
+(function () {
+    const $ = (id) => document.getElementById(id);
+    const esc = (s) => (typeof escapeHtml === 'function' ? escapeHtml(String(s)) : String(s));
+
+    // Illustrative windows, not patient data. The second one exists so the
+    // refusal path is one click away — it is the more informative demo.
+    const EX_OK = {
+        wt: 'G', patient: 'A', offset: 12,
+        window: 'CCTGAGGAGAAGGCTGCCGTCACCGCCCTGTGGGGCAAGGTGAACGTGGAT',
+    };
+    const EX_FAIL = {
+        wt: 'A', patient: 'C', offset: 12,
+        window: 'CCTGAGGAGAAGACTGCCGTCACCGCCCTGTGGGGCAAGGTGAACGTGGAT',
+    };
+
+    const ICON = {
+        ok: '✓', warn: '!', error: '✕',
+        unavailable: '—', skipped: '·',
+    };
+    const LABEL = {
+        ok: 'passed', warn: 'passed with caveat', error: 'refused',
+        unavailable: 'not run', skipped: 'skipped',
+    };
+
+    function setError(msg) {
+        const el = $('tcError');
+        if (!el) return;
+        if (!msg) { el.hidden = true; el.textContent = ''; return; }
+        el.hidden = false; el.textContent = msg;
+    }
+
+    function loadExample(ex) {
+        $('tcWt').value = ex.wt;
+        $('tcPatient').value = ex.patient;
+        $('tcWindow').value = ex.window;
+        $('tcOffset').value = ex.offset;
+        setError('');
+        $('tcResultCard').hidden = true;
+    }
+
+    // The locus strip — the variant in its actual sequence context, with the
+    // patient base and the wild-type base shown at the same position.
+    function renderLocus(win, offset, corr) {
+        const host = $('tcLocus');
+        if (!host) return;
+        if (!win || offset < 0 || offset >= win.length || !corr) { host.hidden = true; return; }
+        const span = 21;
+        const from = Math.max(0, offset - Math.floor(span / 2));
+        const to = Math.min(win.length, from + span);
+        let bases = '';
+        for (let i = from; i < to; i++) {
+            bases += (i === offset)
+                ? `<span class="tc-b tc-b--hit">${esc(win[i])}</span>`
+                : `<span class="tc-b">${esc(win[i])}</span>`;
+        }
+        host.hidden = false;
+        host.innerHTML =
+            `<div class="tc-locus-row"><span class="tc-locus-lbl">reference</span>`
+            + `<span class="tc-seq mono">${bases}</span></div>`
+            + `<div class="tc-locus-legend">`
+            + `<span class="tc-chip tc-chip--pt">patient ${esc(corr.patient_base)}</span>`
+            + `<span class="tc-chip tc-chip--wt">wild-type ${esc(corr.wt_base)}</span>`
+            + `<span class="tc-chip">${esc(corr.editor_family)} writes ${esc(corr.editor_change)}</span>`
+            + `<span class="tc-chip">${esc(corr.strand)} strand</span>`
+            + `</div>`
+            + `<p class="tc-locus-note">Showing ${to - from} nt around offset ${offset}. The editor engages `
+            + `the <strong>${esc(corr.strand)}</strong> strand — a base editor only ever writes A&rarr;G (ABE) `
+            + `or C&rarr;T (CBE), so the strand follows from the correction, not from preference.</p>`;
+    }
+
+    function renderVerdict(data) {
+        const el = $('tcVerdict');
+        if (!el) return;
+        const c = data.correction;
+        const gaps = data.incomplete_because || [];
+        let cls, head, sub;
+        if (data.compiled) {
+            cls = gaps.length ? 'is-partial' : 'is-ok';
+            head = c ? `${esc(c.editor_family)} &middot; ${esc(c.sense_change)} on the ${esc(c.strand)} strand`
+                     : 'Compiled';
+            sub = gaps.length
+                ? `Compiled, but the record is incomplete: ${gaps.map(esc).join(', ')} did not run.`
+                : 'Every pass ran and succeeded.';
+        } else {
+            cls = 'is-refused';
+            head = 'Did not compile';
+            sub = 'One or more passes refused. The diagnostics below say what would have to change.';
+        }
+        el.className = 'tc-verdict ' + cls;
+        el.innerHTML = `<div class="tc-verdict-head">${head}</div>`
+                     + `<div class="tc-verdict-sub">${esc(sub)}</div>`;
+    }
+
+    function renderPasses(passes) {
+        const host = $('tcPasses');
+        if (!host) return;
+        host.innerHTML = passes.map((p, i) => (
+            `<li class="tc-pass tc-pass--${esc(p.status)}" style="--i:${i}">`
+            + `<span class="tc-pass-dot" aria-hidden="true">${ICON[p.status] || ''}</span>`
+            + `<div class="tc-pass-body">`
+            + `<div class="tc-pass-hd"><span class="tc-pass-title">${esc(p.title)}</span>`
+            + `<span class="tc-pass-status">${esc(LABEL[p.status] || p.status)}</span></div>`
+            + (p.detail ? `<p class="tc-pass-detail">${esc(p.detail)}</p>` : '')
+            + `</div></li>`
+        )).join('');
+        // Re-trigger the stagger on every compile, not just the first.
+        host.querySelectorAll('.tc-pass').forEach((n) => {
+            n.classList.remove('is-lit');
+            // eslint-disable-next-line no-unused-expressions
+            n.offsetWidth;
+            n.classList.add('is-lit');
+        });
+    }
+
+    function renderDiags(passes) {
+        const host = $('tcDiags');
+        if (!host) return;
+        const all = [];
+        passes.forEach((p) => (p.diagnostics || []).forEach((d) => all.push([p.title, d])));
+        if (!all.length) { host.innerHTML = ''; return; }
+        host.innerHTML = '<h3 class="tc-diags-hd">Diagnostics</h3>' + all.map(([where, d]) => (
+            `<div class="tc-diag tc-diag--${esc(d.level)}">`
+            + `<div class="tc-diag-top"><code class="tc-diag-code">${esc(d.code)}</code>`
+            + `<span class="tc-diag-where">${esc(where)}</span></div>`
+            + `<p class="tc-diag-msg">${esc(d.message)}</p>`
+            + (d.remedy ? `<p class="tc-diag-remedy"><strong>What would change this:</strong> ${esc(d.remedy)}</p>` : '')
+            + `</div>`
+        )).join('');
+    }
+
+    async function run() {
+        setError('');
+        const wt = ($('tcWt').value || '').trim();
+        const patient = ($('tcPatient').value || '').trim();
+        if (!wt && !patient) { setError('Give at least one allele.'); return; }
+
+        const win = ($('tcWindow').value || '').replace(/\s+/g, '').toUpperCase();
+        const offset = parseInt($('tcOffset').value, 10);
+        const btn = $('tcRun');
+        btn.disabled = true;
+        try {
+            const res = await fetch('/api/compiler/compile', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    wt_allele: wt, patient_allele: patient,
+                    window: win, offset: isNaN(offset) ? -1 : offset,
+                }),
+            });
+            const data = await res.json();
+            if (!res.ok) {
+                if (data && data.kind === 'signin_required') {
+                    window.dispatchEvent(new Event('td:signin-required'));
+                    return;
+                }
+                throw new Error(data.error || 'The compiler could not run.');
+            }
+            renderVerdict(data);
+            renderLocus(win, isNaN(offset) ? -1 : offset, data.correction);
+            renderPasses(data.passes || []);
+            renderDiags(data.passes || []);
+            $('tcResultCard').hidden = false;
+        } catch (err) {
+            setError((err && err.message) || String(err));
+        } finally {
+            btn.disabled = false;
+        }
+    }
+
+    function init() {
+        if (!document.querySelector('[data-view="compiler"]')) return;
+        const on = (id, ev, fn) => { const el = $(id); if (el) el.addEventListener(ev, fn); };
+        on('tcRun', 'click', run);
+        on('tcExampleOk', 'click', () => loadExample(EX_OK));
+        on('tcExampleFail', 'click', () => loadExample(EX_FAIL));
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init);
+    } else {
+        init();
+    }
+}());

dee/static/index.html

@@ -112,7 +112,7 @@
     <!-- ?v= query bumps invalidate browser + iframe asset caches when app.css /
          app.js change. Bump these numbers whenever you ship a frontend update —
          without them, users keep getting the stale file for up to a week. -->
-    <link rel="stylesheet" href="/static/app.css?v=20260812-dna2" />
+    <link rel="stylesheet" href="/static/app.css?v=20260812-tc" />
     <!-- The work catalog + the draggable rail. Kept out of app.css so two new
          self-contained surfaces stay reviewable; every colour is an app.css
          token, so both themes work with nothing added. -->
@@ -316,6 +316,24 @@
                         <span class="nav-step-nm">Plasmid Editor</span>
                         <span class="nav-step-ph">Build</span>
                     </a>
+                    <!--
+                        Compiler sits BEFORE CRISPR in the Edit phase, because
+                        that is the real order of the work: decide what edit
+                        the variant needs, then design the guide that makes it.
+                        Same precedent as the two Design-phase tools — sharing
+                        a phase label is honest; inventing a phase is not.
+                    -->
+                    <a class="nav-item nav-step" href="#compiler" data-analytics="nav-compiler" title="Therapeutic Compiler">
+                        <span class="nav-icon" aria-hidden="true">
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+                                <path d="M4 6h6M4 12h6M4 18h6"/>
+                                <path d="M14 6h6M14 12h6M14 18h6"/>
+                                <path d="M11.2 4.6l1.6 2.8M11.2 19.4l1.6-2.8"/>
+                            </svg>
+                        </span>
+                        <span class="nav-step-nm">Therapeutic Compiler</span>
+                        <span class="nav-step-ph">Edit</span>
+                    </a>
                     <a class="nav-item nav-step" href="#crispr" data-analytics="nav-crispr" title="CRISPR">
                         <span class="nav-icon" aria-hidden="true">
                             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
@@ -1251,6 +1269,81 @@
                   </section>
               </section>
 
+              <!-- ═══════════════════════ Therapeutic Compiler ════════════════
+                   Lowers a pathogenic variant to an editing strategy — or
+                   refuses, with a diagnostic saying why. The refusals are the
+                   product: a tool that always returns a strategy for a
+                   patient's variant is a plausible-answer generator.
+
+                   The pass list is rendered in full, INCLUDING passes that
+                   could not run. An unlit pass is a visible hole in the
+                   analysis, which is the honest picture — the alternative is
+                   a tidy green column that implies checks nobody performed.
+                   ════════════════════════════════════════════════════════ -->
+              <section class="view view--compiler" data-view="compiler" hidden>
+                  <header class="view-head">
+                      <h1 class="view-title"><em>Therapeutic Compiler</em></h1>
+                      <p class="view-sub">Give it a pathogenic variant; it lowers that to an editing
+                          strategy through named passes, and stops at the first one that can't be
+                          satisfied. What it refuses to compile — and why — is the point.</p>
+                  </header>
+
+                  <div class="tc-scope" role="note">
+                      <span class="tc-scope-key">Scope</span>
+                      <p><strong>Somatic design and assessment only.</strong> Germline and embryo
+                          applications are refused in code, not just in copy. Output is a design record
+                          for humans to evaluate — it is not IND-ready, not a clinical decision, and not
+                          a clearance of any strategy for use. Immunogenicity, pharmacokinetics, dosing,
+                          manufacturing and delivery efficacy are not modelled and not reported.</p>
+                  </div>
+
+                  <section class="card tc-input-card">
+                      <div class="tc-alleles">
+                          <label class="tc-allele">
+                              <span class="field-label">Wild-type allele</span>
+                              <input id="tcWt" class="tc-base mono" maxlength="80" spellcheck="false" placeholder="G" />
+                          </label>
+                          <span class="tc-arrow" aria-hidden="true">←</span>
+                          <label class="tc-allele">
+                              <span class="field-label">Patient allele</span>
+                              <input id="tcPatient" class="tc-base mono" maxlength="80" spellcheck="false" placeholder="A" />
+                          </label>
+                      </div>
+                      <p class="field-hint">Correction runs <strong>patient → wild-type</strong>. Reversed,
+                          you would be designing an editor that installs the disease, so the two fields are
+                          named for what they are rather than ref/alt. Leave an allele empty for an
+                          insertion or deletion.</p>
+
+                      <label class="field-label" for="tcWindow">Reference window
+                          <span class="field-opt">· optional, strongly recommended</span></label>
+                      <p class="field-hint">Wild-type sequence around the variant. Without it the lesion can
+                          still be classified from alleles alone — but nothing is checked against real
+                          sequence, and an off-by-one coordinate still type-checks at the allele level.</p>
+                      <textarea id="tcWindow" class="dna-textarea mono" rows="3" spellcheck="false"
+                          placeholder="Paste wild-type DNA around the variant (A/C/G/T)…"></textarea>
+
+                      <label class="field-label" for="tcOffset">Variant offset in that window
+                          <span class="field-opt">· 0-based</span></label>
+                      <input id="tcOffset" class="tc-num mono" type="number" min="0" value="0" />
+
+                      <div class="tc-actions">
+                          <button class="ghost" type="button" id="tcExampleOk"
+                                  title="A transition — base-editable, compiles">Example that compiles</button>
+                          <button class="ghost" type="button" id="tcExampleFail"
+                                  title="A transversion — no base editor can make this change">Example that refuses</button>
+                          <button class="primary primary-lg" type="button" id="tcRun">Compile</button>
+                      </div>
+                      <div class="error-banner" id="tcError" hidden></div>
+                  </section>
+
+                  <section class="card tc-result-card" id="tcResultCard" hidden>
+                      <div class="tc-verdict" id="tcVerdict"></div>
+                      <div class="tc-locus" id="tcLocus" hidden></div>
+                      <ol class="tc-passes" id="tcPasses"></ol>
+                      <div class="tc-diags" id="tcDiags"></div>
+                  </section>
+              </section>
+
               <!-- ═════════════════════════════ CRISPR view (Cas9 knockout) ═══
                    Paste a gene → ranked SpCas9 sgRNAs with on-target
                    scoring. Sign-in gated server-side; anonymous users
@@ -2737,7 +2830,7 @@
     <!-- Cloning reference data must load before app.js so the Designer
          can read VECTORS / ENZYMES / CLONING_METHODS / TAGS / LINKERS. -->
     <script src="/static/cloning_db.js?v=20260530-ui-polish" defer></script>
-    <script src="/static/app.js?v=20260812-dna2" defer></script>
+    <script src="/static/app.js?v=20260812-tc" defer></script>
     <!-- The decision trace, BEFORE cockpit.js: applyEvent calls TDTrace.push
          on the very first event, and both are `defer`, so document order is
          load order. Loading it after would drop the opening events of a

tests/test_compiler.py

@@ -0,0 +1,273 @@
+"""The therapeutic compiler. The refusals are the product, so they are what
+this file spends its effort on.
+
+The substitution space is 12 ordered base pairs, so it is tested EXHAUSTIVELY
+rather than by example: every wild-type/patient combination is routed and the
+routing is checked against the two chemistries from first principles. A
+sampled test would have let a strand error through, and a strand error
+designs a guide against the wrong strand — silent in silico, expensive at the
+bench.
+"""
+import itertools
+
+import pytest
+
+from dee.core import compiler as C
+
+
+BASES = "ACGT"
+COMP = {"A": "T", "T": "A", "C": "G", "G": "C"}
+
+
+# ── the chemistry, restated independently of the implementation ─────────
+def _expected_family(wt, patient):
+    """Derived here from scratch so this is a real second opinion, not a
+    restatement of the module under test."""
+    if (patient, wt) == ("A", "G"):
+        return "ABE", "sense"
+    if (patient, wt) == ("C", "T"):
+        return "CBE", "sense"
+    if (COMP[patient], COMP[wt]) == ("A", "G"):
+        return "ABE", "antisense"
+    if (COMP[patient], COMP[wt]) == ("C", "T"):
+        return "CBE", "antisense"
+    return None, None
+
+
+@pytest.mark.parametrize("wt,patient",
+                         [(a, b) for a, b in itertools.product(BASES, BASES) if a != b])
+def test_every_substitution_routes_correctly(wt, patient):
+    call = C.classify_lesion(wt, patient)
+    fam, strand = _expected_family(wt, patient)
+    if fam is None:
+        assert call.correction is None, f"{patient}>{wt} is a transversion"
+        assert call.route == "prime_editing"
+        assert not call.compiles, "a transversion must not compile to a guide"
+    else:
+        assert call.correction is not None, f"{patient}>{wt} should be {fam}"
+        assert call.correction.editor_family == fam
+        assert call.correction.strand == strand
+        assert call.route == "base_editing"
+        assert call.compiles
+
+
+def test_the_four_base_editable_corrections_are_exactly_the_transitions():
+    """Transitions are base-editable, transversions are not. If this ever
+    reports more than four, a transversion has been mis-routed."""
+    editable = [(wt, pt) for wt, pt in itertools.product(BASES, BASES)
+                if wt != pt and C.classify_lesion(wt, pt).correction is not None]
+    assert len(editable) == 4
+    assert all(C.classify_lesion(wt, pt).is_transition for wt, pt in editable)
+
+
+def test_the_strand_derivation_a_reviewer_would_check_by_hand():
+    """Spelled out, because getting this backwards is the expensive error.
+
+    A patient carrying C where wild-type is T needs T restored. On the sense
+    strand that is C>T — a CBE edit. A patient carrying G where wild-type is
+    A needs A restored: sense G>A, which on the ANTISENSE strand reads C>T,
+    also CBE but engaging the other strand.
+    """
+    sense = C.classify_lesion("T", "C").correction
+    assert (sense.editor_family, sense.strand, sense.editor_change) == ("CBE", "sense", "C>T")
+
+    anti = C.classify_lesion("A", "G").correction
+    assert (anti.editor_family, anti.strand, anti.editor_change) == ("CBE", "antisense", "C>T")
+
+    sense_abe = C.classify_lesion("G", "A").correction
+    assert (sense_abe.editor_family, sense_abe.strand) == ("ABE", "sense")
+
+    anti_abe = C.classify_lesion("C", "T").correction
+    assert (anti_abe.editor_family, anti_abe.strand) == ("ABE", "antisense")
+
+
+# ── refusals ────────────────────────────────────────────────────────────
+def test_identical_alleles_are_refused_not_silently_compiled():
+    call = C.classify_lesion("A", "A")
+    assert not call.compiles
+    assert call.errors()[0].code == "no_lesion"
+    assert "swapped" in call.errors()[0].remedy
+
+
+def test_a_transversion_says_why_and_names_the_route_it_cannot_take():
+    call = C.classify_lesion("A", "C")          # correcting C>A
+    codes = [d.code for d in call.diagnostics]
+    assert "transversion_no_base_editor" in codes
+    assert "prime_editing_unavailable" in codes
+    msg = " ".join(d.message for d in call.diagnostics)
+    assert "ABE writes A>G" in msg and "CBE writes C>T" in msg
+
+
+def test_a_large_deletion_is_refused_and_points_somewhere_real():
+    call = C.classify_lesion("A" * 400, "")
+    assert not call.compiles
+    err = [d for d in call.errors() if d.code == "lesion_too_large"][0]
+    assert "400-base deletion" in err.message
+    assert "integrase" in err.remedy or "recombinase" in err.remedy
+
+
+def test_a_small_indel_routes_to_prime_editing_and_admits_we_lack_it():
+    call = C.classify_lesion("", "ATG")
+    assert call.kind == "insertion" and call.size == 3
+    assert call.route == "prime_editing"
+    assert not call.compiles, "we cannot design a pegRNA, so it must not compile"
+    assert any(d.code == "indel_not_base_editable" for d in call.diagnostics)
+
+
+def test_a_lesion_near_the_bound_is_flagged_marginal():
+    size = C.PRIME_EDIT_INSERT_BOUND // 2 + 2
+    call = C.classify_lesion("", "A" * size)
+    assert any(d.code == "lesion_near_bound" for d in call.diagnostics)
+
+
+def test_non_dna_alleles_are_refused():
+    for bad in ("N", "R", "Q", "5"):
+        call = C.classify_lesion("A", bad)
+        assert not call.compiles
+        assert call.errors()[0].code == "non_dna_allele"
+
+
+def test_ambiguity_codes_are_not_quietly_treated_as_bases():
+    """N is a real thing to receive from a VCF and must not route."""
+    assert C.classify_lesion("N", "A").errors()[0].code == "non_dna_allele"
+
+
+# ── verification against real sequence ──────────────────────────────────
+WINDOW = "GATTACAGATTACAGGCCTTAA"
+
+
+def test_it_verifies_the_reference_actually_has_the_wildtype_base():
+    off = WINDOW.index("G")                       # position 0, a G
+    call = C.compile_correction("G", "A", window=WINDOW, offset=off)
+    assert call.compiles
+
+
+def test_an_off_by_one_coordinate_is_caught_by_the_reference_check():
+    """The check that earns its keep: alleles alone still type-check when the
+    coordinate has drifted."""
+    off = 1                                        # WINDOW[1] is 'A', not 'G'
+    call = C.compile_correction("G", "A", window=WINDOW, offset=off)
+    assert not call.compiles
+    err = [d for d in call.errors() if d.code == "reference_mismatch"][0]
+    assert "'A'" in err.message
+    assert "opposite strand" in err.remedy
+
+
+def test_an_offset_outside_the_window_is_refused():
+    call = C.compile_correction("G", "A", window=WINDOW, offset=999)
+    assert not call.compiles
+    assert call.errors()[0].code == "offset_outside_window"
+
+
+def test_restores_wildtype_is_a_whole_sequence_comparison():
+    corr = C.classify_lesion("G", "A").correction
+    assert C.restores_wildtype(WINDOW, 0, corr)
+    assert not C.restores_wildtype(WINDOW, 1, corr)
+    assert not C.restores_wildtype("", 0, corr)
+
+
+# ── the scope boundary ──────────────────────────────────────────────────
+def test_germline_raises_rather_than_returning_a_diagnostic():
+    """A refusal a caller can read past and keep going is not a refusal."""
+    with pytest.raises(C.GermlineRefused):
+        C.compile_correction("G", "A", germline=True)
+
+
+def test_germline_is_refused_before_any_routing_happens():
+    """Even a perfectly compilable lesion must not be routed."""
+    with pytest.raises(C.GermlineRefused):
+        C.compile_correction("G", "A", window=WINDOW, offset=0, germline=True)
+
+
+# ── the direction of correction ─────────────────────────────────────────
+def test_arguments_are_wildtype_first_patient_second():
+    """Swapping these designs an editor that INSTALLS the disease. The two
+    orderings must not produce the same plan."""
+    a = C.classify_lesion("G", "A")               # patient A -> restore G
+    b = C.classify_lesion("A", "G")               # patient G -> restore A
+    assert a.correction.editor_family == "ABE"
+    assert b.correction.editor_family == "CBE"
+    assert a.correction.strand != b.correction.strand
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# The pass pipeline. The point of these is that a pass which did NOT run is
+# never reported as one that ran and passed.
+# ═══════════════════════════════════════════════════════════════════════
+def _by_name(report):
+    return {p.name: p for p in report.passes}
+
+
+def test_every_declared_pass_is_reported():
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    assert [p.name for p in r.passes] == [n for n, _ in C.PASS_ORDER]
+
+
+def test_unrunnable_passes_are_unavailable_not_ok():
+    """The whole honesty contract. Defaults are False so a caller that forgets
+    to check capability gets an incomplete record, not a falsely clean one."""
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    p = _by_name(r)
+    assert p["consequence"].status == "unavailable"
+    assert p["specificity"].status == "unavailable"
+    assert "Assess edit consequence" in r.incomplete_because
+    assert "Assess specificity" in r.incomplete_because
+
+
+def test_specificity_still_carries_its_caveat_when_it_runs():
+    """A coding-sequence-only index reporting a clean 'ok' would read as a
+    clean bill of health on a therapeutic guide. It must never say ok."""
+    r = C.compile_report("G", "A", window=WINDOW, offset=0,
+                         can_check_specificity=True)
+    spec = _by_name(r)["specificity"]
+    assert spec.status == "warn", "must not be reportable as unqualified ok"
+    assert "CODING SEQUENCE ONLY" in spec.detail
+    assert "GUIDE-seq" in spec.detail
+
+
+def test_consequence_pass_states_it_is_zero_shot_even_when_available():
+    r = C.compile_report("G", "A", window=WINDOW, offset=0,
+                         can_score_consequence=True)
+    d = _by_name(r)["consequence"].detail
+    assert "zero-shot" in d
+    assert "no validated relationship to clinical outcome" in d
+
+
+def test_a_refused_lesion_skips_the_rest_rather_than_reporting_ok():
+    r = C.compile_report("A", "C")        # transversion, no PE here
+    p = _by_name(r)
+    assert p["classify"].status == "error"
+    assert all(p[n].status == "skipped" for n in
+               ("verify", "enumerate", "consequence", "specificity", "emit"))
+    assert not r.compiled
+
+
+def test_a_reference_mismatch_stops_the_build():
+    r = C.compile_report("G", "A", window=WINDOW, offset=1)
+    p = _by_name(r)
+    assert p["verify"].status == "error"
+    assert p["enumerate"].status == "skipped"
+    assert not r.compiled
+
+
+def test_no_window_makes_verify_unavailable_and_says_why():
+    r = C.compile_report("G", "A")
+    v = _by_name(r)["verify"]
+    assert v.status == "unavailable"
+    assert "off-by-one" in v.detail
+
+
+def test_compiled_is_false_when_anything_was_skipped():
+    assert not C.compile_report("A", "A").compiled
+
+
+def test_scope_travels_with_every_report():
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    assert "Somatic" in r.scope["application"]
+    assert "Not IND-ready" in r.scope["status"]
+    assert "Immunogenicity" in r.scope["silent_on"]
+
+
+def test_compile_report_refuses_germline_before_running_any_pass():
+    with pytest.raises(C.GermlineRefused):
+        C.compile_report("G", "A", window=WINDOW, offset=0, germline=True)