Deploy 53117c1

Validation corpus, a specificity handoff, and the design record

Source: https://github.com/WINTER4000/turingDNA/commit/53117c103469b28cb1ec444c32e955243a998aa8

dee/core/compiler.py

@@ -430,6 +430,32 @@ CAPABILITY_NOTES = {
         "GUIDE-seq, CIRCLE-seq or an equivalent empirical assay."),
 }
 
+# What the specificity pass hands over when it cannot clear a guide itself.
+# A refusal that just stops is a shrug; a refusal that says exactly what to run
+# next is a handoff. These are the searches this deployment is NOT doing, named
+# precisely enough to be executed by someone who has the tools.
+SPECIFICITY_HANDOFF = {
+    "in_silico": [
+        ("Cas-OFFinder / CRISPRme", "genome-wide, mismatch- and bulge-tolerant "
+         "search over the WHOLE assembly, not only coding sequence. CRISPRme "
+         "additionally accounts for common variants, which matters when the "
+         "patient's own genome differs from the reference at an off-target."),
+    ],
+    "empirical": [
+        ("GUIDE-seq", "unbiased, cell-based detection of double-strand-break "
+         "capture sites."),
+        ("CIRCLE-seq / CHANGE-seq", "in vitro, high-sensitivity nomination of "
+         "candidate off-targets from purified genomic DNA."),
+        ("Targeted amplicon sequencing", "deep sequencing of the nominated "
+         "sites in the actual therapeutic cell product."),
+    ],
+    "note": (
+        "For a base editor the relevant off-target question is not only where "
+        "the nuclease cuts. Cas-independent deamination is not detected by a "
+        "DSB-capture assay at all, so a clean GUIDE-seq result does not, on "
+        "its own, clear a base editor."),
+}
+
 SCOPE = {
     "application": "Somatic therapeutic design only. Germline and embryo "
                    "editing are out of scope and refused.",
@@ -563,8 +589,19 @@ def compile_report(wt_allele: str, patient_allele: str, *,
     # ── 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.
+    #
+    # And it now HANDS OFF. A refusal that just stops is a shrug; one that
+    # names the exact searches this deployment is not doing is a work order
+    # somebody can act on. That difference is most of the value of admitting
+    # the gap in the first place.
+    spec_detail = CAPABILITY_NOTES["specificity"] + " Not cleared here — run: "
+    spec_detail += "; ".join(
+        f"{name} ({why.split('.')[0].lower()})"
+        for name, why in (SPECIFICITY_HANDOFF["in_silico"]
+                          + SPECIFICITY_HANDOFF["empirical"]))
+    spec_detail += ". " + SPECIFICITY_HANDOFF["note"]
     add("specificity", "warn" if can_check_specificity else "unavailable",
-        CAPABILITY_NOTES["specificity"])
+        spec_detail)
 
     # ── emit ────────────────────────────────────────────────────────────
     add("emit", "ok",
@@ -887,3 +924,145 @@ def plan_base_edit_strategies(window: str, target_offset: int,
             "choosing — a silent or intronic bystander in a regulatory "
             "element is exactly the case nothing else checks."))
     return out[:max_results], diags
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# The design record
+# ═══════════════════════════════════════════════════════════════════════
+# In a platform-IND world the deliverable is not a therapy — it is a design
+# and its complete justification, in a form a reviewer can audit and a third
+# party can reproduce. Today that document is assembled by hand, per patient,
+# by scientists. This emits it.
+#
+# Deterministic by construction: same inputs, byte-identical output. Nothing
+# here reads a clock or a random source, because a record that changes between
+# runs cannot be diffed, and a record that cannot be diffed cannot be audited.
+# The caller stamps time and provenance if it wants them.
+
+RECORD_VERSION = "1"
+
+
+def design_record(report: "CompileReport", *, variant: str = "",
+                  resolved: Optional[Dict[str, object]] = None,
+                  provenance: Optional[Dict[str, str]] = None) -> str:
+    """Render a compile report as a plain-text design record.
+
+    Plain text on purpose: it diffs, it pastes into an email or a lab
+    notebook, it survives every tool in the chain, and nothing about it can
+    silently re-render differently later.
+    """
+    L: List[str] = []
+    add = L.append
+
+    add("TURINGDNA THERAPEUTIC DESIGN RECORD")
+    add(f"record-version {RECORD_VERSION}")
+    add("=" * 72)
+    add("")
+    add("SCOPE")
+    for k in ("application", "status", "silent_on"):
+        add(f"  {k:<12} {report.scope.get(k, '')}")
+    add("")
+
+    if variant or resolved:
+        add("VARIANT")
+        if variant:
+            add(f"  notation     {variant}")
+        for key, label in (("gene", "gene"), ("transcript", "transcript"),
+                           ("chrom", "chromosome"), ("position", "position"),
+                           ("assembly", "assembly"), ("consequence", "consequence"),
+                           ("orientation", "allele orientation"),
+                           ("source", "resolved by")):
+            val = (resolved or {}).get(key)
+            if val:
+                add(f"  {label:<12} {val}")
+        if resolved:
+            add(f"  {'alleles':<12} wild-type {resolved.get('wt_base')} -> "
+                f"patient {resolved.get('patient_base')} (forward strand)")
+        add("")
+
+    corr = report.lesion.correction if report.lesion else None
+    if report.lesion:
+        add("LESION")
+        add(f"  kind         {report.lesion.kind}")
+        add(f"  size         {report.lesion.size}")
+        add(f"  route        {report.lesion.route}")
+        if corr:
+            add(f"  correction   {corr.sense_change} on the sense strand")
+            add(f"  chemistry    {corr.editor_family} writes {corr.editor_change} "
+                f"on the {corr.strand} strand")
+        add("")
+
+    add("PASSES")
+    for p in report.passes:
+        add(f"  [{p.status:<11}] {p.title}")
+        if p.detail:
+            for line in _wrap(p.detail, 68):
+                add(f"      {line}")
+        for d in p.diagnostics:
+            add(f"      - {d.level.upper()} {d.code}: {d.message}")
+            if d.remedy:
+                for line in _wrap(f"remedy: {d.remedy}", 62):
+                    add(f"        {line}")
+    add("")
+
+    if report.strategies:
+        add("STRATEGIES")
+        for s in report.strategies:
+            add(f"  #{s.rank} {s.editor_id} on the "
+                f"{'sense' if s.strand == '+' else 'antisense'} strand")
+            add(f"      spacer            {s.spacer}")
+            add(f"      PAM               {s.pam}")
+            add(f"      forward position  {s.position}")
+            add(f"      target at spacer  {s.target_spacer_pos} "
+                f"(editor activity {s.target_activity})")
+            add(f"      on-target score   {s.on_target_score}")
+            if not s.bystanders:
+                add("      bystanders        none in this guide's window")
+            else:
+                add(f"      bystanders        {len(s.bystanders)}")
+                for b in s.bystanders:
+                    d = ("not scored" if b.delta_ll is None
+                         else f"delta log-likelihood {b.delta_ll:+.4f}")
+                    add(f"        {b.label or (b.from_base + '>' + b.to_base)}"
+                        f"  spacer pos {b.spacer_pos}  {d}")
+        add("")
+
+    gaps = report.incomplete_because
+    add("COMPLETENESS")
+    add(f"  compiled     {'yes' if report.compiled else 'NO'}")
+    if gaps:
+        add("  NOT ESTABLISHED by this record:")
+        for g in gaps:
+            add(f"    - {g}")
+    else:
+        add("  every pass produced a result")
+    add("")
+
+    if provenance:
+        add("PROVENANCE")
+        for k in sorted(provenance):
+            add(f"  {k:<12} {provenance[k]}")
+        add("")
+
+    add("-" * 72)
+    add("This is a design record, not a clinical decision and not an approval.")
+    add("Predicted specificity is not measured specificity. Model-derived")
+    add("judgements are zero-shot and have no validated relationship to")
+    add("clinical outcome. Nothing here substitutes for the preclinical")
+    add("programme, and nothing here should reach a patient on its own.")
+    return "\n".join(L)
+
+
+def _wrap(text: str, width: int) -> List[str]:
+    """Tiny greedy wrapper — textwrap would do, but this keeps the record's
+    formatting identical across Python versions."""
+    words, line, out = str(text).split(), "", []
+    for w in words:
+        if line and len(line) + 1 + len(w) > width:
+            out.append(line)
+            line = w
+        else:
+            line = f"{line} {w}".strip()
+    if line:
+        out.append(line)
+    return out

dee/core/compiler_validation.py

@@ -0,0 +1,202 @@
+"""Check the compiler against landmark editing designs.
+
+The question anyone serious asks within two minutes is "how do you know it's
+right?", and "it is deterministic and well tested" is an engineering answer to
+a scientific question. This is the scientific answer: run the compiler against
+designs the field has already settled and show it arrives at the same verdict.
+
+THE CLAIM THIS SUPPORTS, STATED PRECISELY
+-----------------------------------------
+It reproduces **known-correct decisions**. It does NOT discover new biology,
+and the two must never be blurred — the first is defensible and the second
+would be a lie a reviewer could take apart in one question.
+
+TWO KINDS OF CASE, COUNTED SEPARATELY
+-------------------------------------
+`basis="chemistry"`   the expected verdict follows from the genetic code and
+                      the two base-editor chemistries. Anyone can re-derive
+                      it, so it needs no citation and counts as validation.
+
+`basis="literature"`  the expectation is a claim about what a real programme
+                      actually did. It requires a citation. Without one the
+                      case is reported UNVERIFIED and does **not** count as a
+                      pass — it is a named gap, which is more useful than a
+                      silent absence.
+
+That split is the honesty mechanism. "12 of 12 validated" means nothing if
+half were asserted from memory; here the report always carries both numbers
+and the unverified ones by name.
+
+Pure logic: no network, no GPU, no model. It runs in CI on every commit, so a
+change that breaks a landmark verdict fails the build rather than being
+noticed in a demo.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from dee.core import compiler as _compiler
+
+__all__ = ["CaseResult", "ValidationReport", "load_cases", "run_validation",
+           "report_to_dict"]
+
+CORPUS_PATH = (pathlib.Path(__file__).resolve().parent.parent
+               / "data" / "landmark_designs.json")
+
+
+@dataclass
+class CaseResult:
+    case_id: str
+    name: str
+    basis: str
+    status: str            # "pass" | "fail" | "unverified"
+    expected: Dict[str, Any] = field(default_factory=dict)
+    observed: Dict[str, Any] = field(default_factory=dict)
+    mismatches: List[str] = field(default_factory=list)
+    why: str = ""
+    citation: str = ""
+
+
+@dataclass
+class ValidationReport:
+    results: List[CaseResult]
+
+    @property
+    def chemistry_total(self) -> int:
+        return sum(1 for r in self.results if r.basis == "chemistry")
+
+    @property
+    def chemistry_passed(self) -> int:
+        return sum(1 for r in self.results
+                   if r.basis == "chemistry" and r.status == "pass")
+
+    @property
+    def unverified(self) -> List[str]:
+        return [r.name for r in self.results if r.status == "unverified"]
+
+    @property
+    def failures(self) -> List[CaseResult]:
+        return [r for r in self.results if r.status == "fail"]
+
+    @property
+    def headline(self) -> str:
+        """One sentence that cannot be misread as more than it is."""
+        n, tot = self.chemistry_passed, self.chemistry_total
+        base = (f"{n} of {tot} landmark decisions reproduced "
+                "(derivable from the genetic code and base-editor chemistry)")
+        if self.unverified:
+            base += (f"; {len(self.unverified)} further case(s) awaiting a "
+                     "citation and not counted")
+        return base + "."
+
+
+def load_cases(path: Optional[pathlib.Path] = None) -> List[Dict[str, Any]]:
+    p = path or CORPUS_PATH
+    if not p.exists():
+        return []
+    data = json.loads(p.read_text())
+    return [c for c in (data.get("cases") or []) if isinstance(c, dict)]
+
+
+def _expand_allele(value: Any) -> str:
+    """Alleles may be a literal string or {"repeat": "A", "times": 400}.
+
+    The compact form exists because a 400-base deletion is a legitimate case
+    and pasting 400 characters into JSON makes the corpus unreadable. It is
+    NOT a shorthand the compiler understands — an earlier corpus wrote "A400"
+    expecting it to mean 400 A's, and the compiler correctly read it as an
+    allele containing a digit and refused. The harness caught that, which is
+    the harness working.
+    """
+    if isinstance(value, dict):
+        base = str(value.get("repeat") or "")
+        times = int(value.get("times") or 0)
+        return base * times
+    return str(value or "")
+
+
+def _observe(case: Dict[str, Any]) -> Dict[str, Any]:
+    """Run the compiler on a case and flatten what it decided."""
+    call = _compiler.classify_lesion(_expand_allele(case.get("wt_base")),
+                                     _expand_allele(case.get("patient_base")))
+    corr = call.correction
+    return {
+        "compiles": call.compiles,
+        "route": call.route,
+        "editor_family": corr.editor_family if corr else None,
+        "strand": corr.strand if corr else None,
+        "diagnostics": [d.code for d in call.diagnostics],
+    }
+
+
+def _compare(expected: Dict[str, Any], observed: Dict[str, Any]) -> List[str]:
+    """Only the keys the case actually asserts. A case that says nothing about
+    strand is not failed for the strand."""
+    out: List[str] = []
+    for key in ("compiles", "route", "editor_family", "strand"):
+        if key in expected and observed.get(key) != expected[key]:
+            out.append(f"{key}: expected {expected[key]!r}, "
+                       f"got {observed.get(key)!r}")
+    want_diag = expected.get("diagnostic")
+    if want_diag and want_diag not in (observed.get("diagnostics") or []):
+        out.append(f"diagnostic {want_diag!r} not raised "
+                   f"(raised {observed.get('diagnostics')!r})")
+    return out
+
+
+def run_validation(cases: Optional[List[Dict[str, Any]]] = None
+                   ) -> ValidationReport:
+    """Every case, with literature cases short-circuited unless cited."""
+    results: List[CaseResult] = []
+    for case in (cases if cases is not None else load_cases()):
+        basis = str(case.get("basis") or "literature")
+        why = case.get("why")
+        why_text = " ".join(why) if isinstance(why, list) else str(why or "")
+        citation = str(case.get("citation") or "").strip()
+        expected = case.get("expect") or {}
+
+        # A literature claim without a citation is not evidence, and must not
+        # be run as though it were — an uncited expectation is just a guess
+        # with a filename.
+        if basis == "literature" and not citation:
+            results.append(CaseResult(
+                case_id=str(case.get("id") or ""), name=str(case.get("name") or ""),
+                basis=basis, status="unverified", expected=expected,
+                why=why_text, citation=citation))
+            continue
+
+        if not expected:
+            results.append(CaseResult(
+                case_id=str(case.get("id") or ""), name=str(case.get("name") or ""),
+                basis=basis, status="unverified", expected={},
+                why=why_text or "No expectation recorded.", citation=citation))
+            continue
+
+        observed = _observe(case)
+        mismatches = _compare(expected, observed)
+        results.append(CaseResult(
+            case_id=str(case.get("id") or ""), name=str(case.get("name") or ""),
+            basis=basis, status="pass" if not mismatches else "fail",
+            expected=expected, observed=observed, mismatches=mismatches,
+            why=why_text, citation=citation))
+    return ValidationReport(results)
+
+
+def report_to_dict(report: ValidationReport) -> Dict[str, Any]:
+    return {
+        "headline": report.headline,
+        "chemistry_passed": report.chemistry_passed,
+        "chemistry_total": report.chemistry_total,
+        "unverified": report.unverified,
+        "all_passed": not report.failures,
+        "cases": [
+            {"id": r.case_id, "name": r.name, "basis": r.basis,
+             "status": r.status, "expected": r.expected, "observed": r.observed,
+             "mismatches": r.mismatches, "why": r.why, "citation": r.citation}
+            for r in report.results
+        ],
+    }

dee/data/landmark_designs.json

@@ -0,0 +1,169 @@
+{
+  "_readme": [
+    "Landmark editing designs the compiler is checked against.",
+    "",
+    "TWO KINDS OF ENTRY, and the difference is the whole point:",
+    "",
+    "  basis = 'chemistry'  the expected verdict follows from the genetic code",
+    "                       and the two base-editor chemistries. It can be",
+    "                       asserted without citing anyone, because anyone can",
+    "                       re-derive it. These COUNT as validation.",
+    "",
+    "  basis = 'literature' the expected verdict is a claim about what a real",
+    "                       published or approved programme actually did. It",
+    "                       needs a citation. Until `citation` is filled in,",
+    "                       the runner reports the case as UNVERIFIED and it",
+    "                       does NOT count as a pass.",
+    "",
+    "An unverified entry is a to-do with a name, not a failure. The report",
+    "shows both numbers separately so 'validated' can never quietly include",
+    "cases nobody checked.",
+    "",
+    "Adding a literature case: fill `citation` with something a reader can",
+    "look up (DOI, PMID, or the trial/product name), and set the expectation",
+    "from the paper — never from memory."
+  ],
+
+  "cases": [
+    {
+      "id": "hbs-sickle-hbb",
+      "name": "HbS (sickle cell) — HBB Glu6Val",
+      "variant": "NM_000518.5:c.20A>T",
+      "locus": "GRCh38 chr11:5227002",
+      "wt_base": "T",
+      "patient_base": "A",
+      "basis": "chemistry",
+      "expect": {
+        "compiles": false,
+        "route": "prime_editing",
+        "diagnostic": "transversion_no_base_editor"
+      },
+      "why": [
+        "The HGVS is written on the transcript (minus) strand as A>T. On the",
+        "forward strand the reference base is T and the patient carries A.",
+        "T>A is a TRANSVERSION, and neither ABE (A>G) nor CBE (C>T) produces a",
+        "transversion on either strand — so no base editor can correct HbS.",
+        "The compiler must refuse and route to prime editing.",
+        "",
+        "This is also why the approved sickle-cell editing therapy targets the",
+        "BCL11A erythroid enhancer to re-induce fetal haemoglobin rather than",
+        "correcting the HBB mutation directly. That clinical fact is context,",
+        "not the assertion: the assertion here is purely the chemistry, which",
+        "anyone can re-derive from the reference sequence."
+      ],
+      "verified_note": "Coordinate and forward-strand alleles confirmed against Ensembl GRCh38 and the reference sequence at that position on 2026-08-12.",
+      "citation": ""
+    },
+    {
+      "id": "transition-abe-sense",
+      "name": "Generic G>A transition, sense strand",
+      "wt_base": "G",
+      "patient_base": "A",
+      "basis": "chemistry",
+      "expect": {
+        "compiles": true,
+        "route": "base_editing",
+        "editor_family": "ABE",
+        "strand": "sense"
+      },
+      "why": [
+        "The patient carries A where wild-type is G. Restoring G means writing",
+        "A>G, which is exactly what an adenine base editor does, on the sense",
+        "strand. No other chemistry applies."
+      ],
+      "citation": ""
+    },
+    {
+      "id": "transition-cbe-antisense",
+      "name": "Generic A>G transition, antisense strand",
+      "wt_base": "A",
+      "patient_base": "G",
+      "basis": "chemistry",
+      "expect": {
+        "compiles": true,
+        "route": "base_editing",
+        "editor_family": "CBE",
+        "strand": "antisense"
+      },
+      "why": [
+        "Restoring A from G is G>A on the sense strand. On the antisense strand",
+        "that position reads C and must become T — a cytosine base editor,",
+        "engaging the opposite strand. Getting this backwards designs a guide",
+        "against the wrong strand."
+      ],
+      "citation": ""
+    },
+    {
+      "id": "large-deletion-not-editable",
+      "name": "Multi-kilobase deletion",
+      "wt_base": { "repeat": "A", "times": 400 },
+      "patient_base": "",
+      "basis": "chemistry",
+      "expect": {
+        "compiles": false,
+        "route": "none",
+        "diagnostic": "lesion_too_large"
+      },
+      "why": [
+        "Base editors rewrite one base chemically and prime editing has a",
+        "practical size ceiling. A lesion of this size needs a different",
+        "modality entirely — integrase or recombinase-mediated insertion, or",
+        "gene addition — and the compiler must say so rather than returning a",
+        "guide."
+      ],
+      "citation": ""
+    },
+    {
+      "id": "small-insertion-prime-editing",
+      "name": "Three-base insertion",
+      "wt_base": "",
+      "patient_base": "ATG",
+      "basis": "chemistry",
+      "expect": {
+        "compiles": false,
+        "route": "prime_editing",
+        "diagnostic": "indel_not_base_editable"
+      },
+      "why": [
+        "Base editors do not add or remove bases. An insertion routes to prime",
+        "editing, which this compiler does not yet design — so it must refuse",
+        "rather than offer a base-editing guide that cannot install the change."
+      ],
+      "citation": ""
+    },
+
+    {
+      "id": "kj-cps1-personalised-base-edit",
+      "name": "First personalised in-vivo base-editing therapy (CPS1 deficiency)",
+      "basis": "literature",
+      "expect": {},
+      "why": [
+        "PENDING. The bespoke n-of-1 base-editing therapy dosed in an infant",
+        "with CPS1 deficiency is the single most important case to reproduce,",
+        "because it is the template for the whole personalised-editing model.",
+        "",
+        "Deliberately left unfilled: encoding the variant, the editor and the",
+        "guide from memory would be exactly the fabrication this corpus exists",
+        "to prevent. Fill `wt_base`/`patient_base`/`expect` from the primary",
+        "publication and add the DOI or PMID to `citation`."
+      ],
+      "citation": ""
+    },
+    {
+      "id": "bcl11a-enhancer-hbf-reinduction",
+      "name": "BCL11A erythroid enhancer disruption (fetal haemoglobin re-induction)",
+      "basis": "literature",
+      "expect": {},
+      "why": [
+        "PENDING. The approved sickle-cell / beta-thalassaemia editing therapy",
+        "does not correct a coding variant — it disrupts an enhancer. Worth",
+        "encoding because it exercises a different question entirely (does the",
+        "compiler reason about a REGULATORY target?) and because it is the",
+        "clinical counterpart to the HbS refusal above.",
+        "",
+        "Needs the enhancer coordinates and the guide from the primary source."
+      ],
+      "citation": ""
+    }
+  ]
+}

dee/server.py

@@ -3598,8 +3598,23 @@ def create_app() -> Flask:
 
         out = _compiler.report_to_dict(report)
         out["resolved"] = resolved
+        # The deliverable: a design and its complete justification, in a form
+        # that diffs and pastes. Deterministic — same inputs, same bytes.
+        out["record"] = _compiler.design_record(
+            report, variant=notation, resolved=resolved,
+            provenance={"engine": "TuringDNA compiler",
+                        "record": _compiler.RECORD_VERSION})
         return jsonify(out)
 
+    @app.get("/api/compiler/validation")
+    def compiler_validation() -> Response:
+        """Landmark designs the compiler is checked against. Public: the whole
+        value is that anyone can look at it, including the gaps."""
+        report = _compiler_validation.run_validation()
+        resp = jsonify(_compiler_validation.report_to_dict(report))
+        resp.headers["Cache-Control"] = "no-store, max-age=0"
+        return resp
+
     @app.get("/api/benchmarks")
     def benchmarks() -> Response:
         """The receipts — how well the engine's zero-shot ranking predicts
@@ -4318,6 +4333,7 @@ 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 compiler_validation as _compiler_validation
 from dee.core import variant_resolve as _variant_resolve
 from dee.core import dna_scoring as _dna_scoring
 

tests/test_compiler.py

@@ -512,3 +512,68 @@ def test_scores_attach_by_label():
         assert hit and all(b.delta_ll == -3.75 for b in hit)
         return
     pytest.skip("fixture produced no bystanders")
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# The design record — the actual deliverable
+# ═══════════════════════════════════════════════════════════════════════
+def test_the_record_is_deterministic():
+    """A record that changes between runs cannot be diffed, and one that
+    cannot be diffed cannot be audited."""
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    a = C.design_record(r, variant="NM_1:c.1G>A")
+    b = C.design_record(r, variant="NM_1:c.1G>A")
+    assert a == b and len(a) > 400
+
+
+def test_the_record_carries_the_scope_limits():
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    rec = C.design_record(r)
+    assert "Somatic" in rec and "Not IND-ready" in rec
+    assert "not a clinical decision" in rec
+    assert "Predicted specificity is not measured specificity" in rec
+
+
+def test_the_record_names_what_it_did_not_establish():
+    """The section that makes it a record rather than a certificate."""
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    rec = C.design_record(r)
+    assert "NOT ESTABLISHED by this record" in rec
+    assert "Assess specificity" in rec
+
+
+def test_a_refusal_produces_a_record_too():
+    """A refused design still deserves documentation — often more so."""
+    r = C.compile_report("A", "C")          # transversion
+    rec = C.design_record(r, variant="NM_1:c.1C>A")
+    assert "compiled     NO" in rec
+    assert "transversion_no_base_editor" in rec
+    assert "remedy:" in rec
+
+
+def test_bystander_scores_appear_in_the_record_and_unscored_says_so():
+    corr = C.classify_lesion("G", "A").correction
+    for off in range(len(HBB)):
+        if HBB[off] != "G":
+            continue
+        st, dg = C.plan_base_edit_strategies(HBB, off, corr)
+        if not any(s.bystanders for s in st):
+            continue
+        C.label_bystanders(HBB, st)
+        r = C.compile_report("G", "A", window=HBB, offset=off,
+                             strategies=st, enumerate_diags=dg)
+        rec = C.design_record(r)
+        assert "STRATEGIES" in rec and "bystanders" in rec
+        assert "not scored" in rec, "unscored must be stated, not omitted"
+        return
+    pytest.skip("fixture produced no bystanders")
+
+
+def test_the_specificity_pass_hands_off_instead_of_shrugging():
+    r = C.compile_report("G", "A", window=WINDOW, offset=0)
+    sp = _by_name(r)["specificity"]
+    assert "Cas-OFFinder" in sp.detail or "CRISPRme" in sp.detail
+    assert "GUIDE-seq" in sp.detail
+    assert "Cas-independent deamination" in sp.detail, (
+        "a base editor is not cleared by a DSB-capture assay, and the handoff "
+        "must say so")

tests/test_compiler_validation.py

@@ -0,0 +1,97 @@
+"""Landmark-design validation. This file guards the honesty mechanism.
+
+The number that matters is not "how many passed" but "how many passed that
+were checkable without trusting anyone's memory". A harness that lets an
+uncited claim count as validation is worse than no harness, because it
+launders a guess into a credential.
+"""
+import pytest
+
+from dee.core import compiler_validation as V
+
+
+def test_the_bundled_corpus_loads():
+    cases = V.load_cases()
+    assert cases, "the corpus must ship with the package"
+    assert all("id" in c and "basis" in c for c in cases)
+
+
+def test_every_chemistry_case_reproduces():
+    """If this fails, the compiler changed its verdict on a settled design."""
+    report = V.run_validation()
+    assert not report.failures, [
+        (f.name, f.mismatches) for f in report.failures]
+    assert report.chemistry_passed == report.chemistry_total
+    assert report.chemistry_total >= 5, "corpus should not silently shrink"
+
+
+def test_the_sickle_cell_case_is_a_refusal_and_stays_one():
+    """The anchor case. HbS is T>A on the forward strand — a transversion —
+    so no base editor can correct it. If this ever 'passes' as compilable,
+    something has broken very badly."""
+    report = V.run_validation()
+    hbs = next(r for r in report.results if r.case_id == "hbs-sickle-hbb")
+    assert hbs.status == "pass"
+    assert hbs.observed["compiles"] is False
+    assert hbs.observed["route"] == "prime_editing"
+    assert "transversion_no_base_editor" in hbs.observed["diagnostics"]
+
+
+def test_an_uncited_literature_case_is_unverified_not_passed():
+    """The mechanism. An expectation nobody can look up must never count."""
+    cases = [{
+        "id": "made-up", "name": "Uncited claim", "basis": "literature",
+        "wt_base": "G", "patient_base": "A",
+        "expect": {"compiles": True, "route": "base_editing"},
+        "citation": "",
+    }]
+    report = V.run_validation(cases)
+    assert report.results[0].status == "unverified"
+    assert report.chemistry_passed == 0
+    assert "Uncited claim" in report.unverified
+
+
+def test_a_cited_literature_case_is_actually_run():
+    cases = [{
+        "id": "cited", "name": "Cited claim", "basis": "literature",
+        "wt_base": "G", "patient_base": "A",
+        "expect": {"compiles": True, "route": "base_editing",
+                   "editor_family": "ABE"},
+        "citation": "PMID:00000000",
+    }]
+    assert V.run_validation(cases).results[0].status == "pass"
+
+
+def test_a_wrong_expectation_fails_loudly_with_the_delta():
+    cases = [{
+        "id": "wrong", "name": "Wrong", "basis": "chemistry",
+        "wt_base": "G", "patient_base": "A",
+        "expect": {"editor_family": "CBE"},        # it is ABE
+    }]
+    r = V.run_validation(cases).results[0]
+    assert r.status == "fail"
+    assert any("editor_family" in m and "ABE" in m for m in r.mismatches)
+
+
+def test_a_case_is_not_failed_for_something_it_never_asserted():
+    """Partial expectations are legitimate; only stated keys are checked."""
+    cases = [{
+        "id": "partial", "name": "Partial", "basis": "chemistry",
+        "wt_base": "G", "patient_base": "A",
+        "expect": {"compiles": True},              # says nothing about strand
+    }]
+    assert V.run_validation(cases).results[0].status == "pass"
+
+
+def test_the_headline_never_reads_as_more_than_it_is():
+    report = V.run_validation()
+    h = report.headline
+    assert "derivable from the genetic code" in h
+    if report.unverified:
+        assert "awaiting a citation and not counted" in h
+
+
+def test_unverified_cases_are_named_not_merely_counted():
+    """A gap with a name is a to-do; a gap as a number is a footnote."""
+    report = V.run_validation()
+    assert all(isinstance(n, str) and n for n in report.unverified)