Deploy 90a38dc

Merge pull request #18 from WINTER4000/feat/capability-tools

Source: https://github.com/WINTER4000/turingDNA/commit/90a38dcdce1a8d6d014de0702fe8e26af12e4d8b

dee/core/agent_tools.py

@@ -135,6 +135,246 @@ def _tool_fetch_sequence(args: Dict[str, Any]) -> Dict[str, Any]:
     return out
 
 
+def _tool_assess_solubility(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Why a good design ends up in the pellet — risk factors, never a score.
+
+    Insolubility is the most common way a design fails: ESM-2 likes it, it
+    expresses, and you harvest inclusion bodies. That failure mode was
+    completely invisible in this product.
+
+    No solubility probability is reported, for the same reason assess_stability
+    reports no ΔΔG: every tool that gives one is a model trained on measured
+    solubility data that is not here, so the number would be invented. Passing
+    both `wild_type` and `mutant` is the mode worth trusting — one residue
+    apart, everything that would confound an absolute prediction cancels.
+    """
+    from dee.core import solubility as _sol
+
+    wt = (args.get("wild_type") or "").strip()
+    mut = (args.get("mutant") or "").strip()
+    single = (args.get("protein") or args.get("sequence") or "").strip()
+    host = args.get("host") or None
+    try:
+        ph = float(args.get("ph") or _sol.DEFAULT_PH)
+    except (TypeError, ValueError):
+        ph = _sol.DEFAULT_PH
+    try:
+        if wt and mut:
+            return _sol.compare(wt, mut, host=host, ph=ph)
+        if single:
+            return _sol.assess(single, host=host, ph=ph)
+        return {"ok": False,
+                "error": ("need 'protein', or both 'wild_type' and 'mutant' "
+                          "to compare a substitution")}
+    except Exception:  # noqa: BLE001
+        logger.exception("assess_solubility failed")
+        return {"ok": False, "error": "Solubility assessment failed."}
+
+
+def _tool_assess_expression(args: Dict[str, Any]) -> Dict[str, Any]:
+    """The sequence-visible reasons a construct expresses badly in a host.
+
+    No predicted yield: that depends on strain, promoter, copy number,
+    induction, media and toxicity, none of which is in a sequence. What IS in
+    the sequence is rare-codon runs, a poor 5' ramp and a broken reading
+    frame — computed against the same codon tables the library encoder writes
+    with, so the engine holds one opinion about a codon rather than two.
+    """
+    from dee.core import expression as _expr
+
+    dna = (args.get("dna") or args.get("sequence") or "").strip()
+    host = (args.get("host") or "").strip()
+    if not dna:
+        return {"ok": False,
+                "error": ("need 'dna' — the coding sequence. This analyses "
+                          "codons, so a protein sequence cannot answer it; "
+                          "reverse-translate first if that is all you have.")}
+    try:
+        return _expr.assess(dna, host)
+    except Exception:  # noqa: BLE001
+        logger.exception("assess_expression failed")
+        return {"ok": False, "error": "Expression assessment failed."}
+
+
+def _tool_map_domains(args: Dict[str, Any]) -> Dict[str, Any]:
+    """What the protein is MADE OF — the boundaries that make a region real.
+
+    `design_variant_library` takes region_start/region_end, and on a large
+    protein those are currently picked blind. "Mutagenise 100-200" is a guess;
+    "mutagenise the DNA-binding domain, 100-288" is a decision. This is also
+    what makes a single substitution interpretable — p53 R175H matters because
+    175 sits inside the DNA-binding domain rather than in a linker.
+
+    Complements check_residues, which asks about individual positions. This
+    asks about architecture.
+    """
+    from dee.core import domains as _dom
+
+    acc = (args.get("accession") or args.get("uniprot") or "").strip()
+    if not acc:
+        return {"ok": False,
+                "error": "need 'accession' — a UniProt accession like P04637"}
+    pos = args.get("positions") or None
+    if isinstance(pos, str):
+        pos = [x for x in re.split(r"[,\s;]+", pos) if x]
+    try:
+        return _dom.domains(acc, positions=pos)
+    except Exception:  # noqa: BLE001
+        logger.exception("map_domains failed")
+        return {"ok": False, "error": "Domain lookup failed."}
+
+
+def _tool_identify_sequence(args: Dict[str, Any]) -> Dict[str, Any]:
+    """"What is this?" — answered locally before anything leaves the Space.
+
+    This is the most common first move a scientist makes, and the tempting
+    implementation is to reflex straight to BLAST. That is the wrong default
+    twice over: BLAST is slow and shared, and it is the ONE operation here
+    that sends the user's residues to NCBI. Most of the question — what
+    molecule, how long, is it a reading frame, what tags and promoters are in
+    it, which vector family it came from — is answerable from the sequence
+    itself against catalogues already in this repo, in microseconds, with
+    nothing transmitted.
+
+    So this tool characterizes locally and then names blast_sequence as the
+    deliberate next step. It never reports a sequence as identified: an agent
+    that concludes "this is insulin" from a His-tag match is the failure this
+    exists to prevent.
+    """
+    from dee.core import identify as _ident
+
+    text = args.get("sequence") or args.get("text") or ""
+    if not str(text).strip():
+        return {"ok": False, "error": "need 'sequence' — the pasted text"}
+    try:
+        return _ident.identify(str(text))
+    except Exception:  # noqa: BLE001
+        logger.exception("identify_sequence failed")
+        return {"ok": False, "error": "Could not analyse that sequence."}
+
+
+def _tool_check_conservation(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Which residues evolution has refused to change — counted, not predicted.
+
+    ESM-2 gives a learned opinion; conservation across real homologs gives an
+    observed fact. They fail differently — the model is weakest exactly where
+    the audit says (membrane, disordered, multi-domain) and a frequency count
+    is unaffected by any of that — so this complements the scorer instead of
+    duplicating it.
+    """
+    from dee.core import conservation as _cons
+
+    seqs = args.get("sequences")
+    if isinstance(seqs, str):
+        seqs = [x for x in re.split(r"[,\s;]+", seqs) if x]
+    if not seqs or len(seqs) < 2:
+        return {"ok": False,
+                "error": "need 'sequences' — a list of homologous proteins"}
+    pos = args.get("positions") or None
+    if isinstance(pos, str):
+        pos = [x for x in re.split(r"[,\s;]+", pos) if x]
+    if pos:
+        keep = []
+        for p in pos:
+            m = re.search(r"\d+", str(p))
+            if m:
+                keep.append(int(m.group(0)))
+        pos = keep or None
+    try:
+        if args.get("alignment_only"):
+            return _cons.align_many(seqs, args.get("names"))
+        return _cons.score(seqs, args.get("names"), positions=pos)
+    except Exception:  # noqa: BLE001
+        logger.exception("check_conservation failed")
+        return {"ok": False, "error": "Conservation analysis failed."}
+
+
+def _tool_check_residues(args: Dict[str, Any]) -> Dict[str, Any]:
+    """What UniProt already knows about the positions being mutated.
+
+    ESM-2 scores how UNUSUAL a residue is, not how load-bearing it is, and a
+    catalytic residue is often unremarkable in sequence terms — it is the
+    geometry that matters and a sequence model does not see geometry. So the
+    cheapest improvement to design quality is not a better model; it is asking
+    the curators.
+    """
+    from dee.core import features as _feat
+
+    acc = str(args.get("accession") or args.get("uniprot") or "").strip()
+    if not acc:
+        return {"ok": False, "error": "missing 'accession' (a UniProt ID)"}
+    pos = args.get("positions")
+    if isinstance(pos, str):
+        pos = [x for x in re.split(r"[,\s;]+", pos) if x]
+    try:
+        if pos:
+            return _feat.annotate(acc, pos)
+        return _feat.fetch(acc)
+    except Exception:  # noqa: BLE001
+        logger.exception("check_residues failed")
+        return {"ok": False, "error": "Feature lookup failed."}
+
+
+def _tool_check_overhangs(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Why a Golden Gate with six correct fragments still comes back wrong.
+
+    simulate_assembly chains parts whose overhangs match and reports success —
+    correctly, as a simulation. What it cannot see is that two overhangs are
+    one base apart, or that one is its own reverse complement. In the tube T4
+    ligase does not care which partner it found. Every one of those conflicts
+    is decidable from the four-base sequences, before anything is ordered.
+    """
+    from dee.core import overhangs as _oh
+
+    want = args.get("suggest_count")
+    if want:
+        try:
+            n = int(want)
+        except (TypeError, ValueError):
+            return {"ok": False, "error": "suggest_count must be a number"}
+        return _oh.suggest(n, length=int(args.get("length") or _oh.DEFAULT_LEN),
+                           min_distance=int(args.get("min_distance") or 2),
+                           avoid=args.get("avoid") or [])
+    ohs = args.get("overhangs")
+    if isinstance(ohs, str):
+        ohs = [x for x in re.split(r"[,\s;]+", ohs) if x]
+    if not ohs:
+        return {"ok": False,
+                "error": "give 'overhangs' (a list) or 'suggest_count' (a number)"}
+    try:
+        return _oh.check(ohs, length=int(args.get("length") or _oh.DEFAULT_LEN),
+                         min_distance=int(args.get("min_distance") or 2))
+    except Exception:  # noqa: BLE001
+        logger.exception("check_overhangs failed")
+        return {"ok": False, "error": "Overhang check failed."}
+
+
+def _tool_design_mutagenesis_primers(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Primers that actually MAKE the mutation the engine designed.
+
+    The gap this closes: the engine says R175H is worth trying, and then
+    stops. Everything between "good idea" and DNA in a tube — picking the
+    codon, centring the mismatch, balancing the two arms by Tm — was left to
+    the user. It is the most common wet-lab follow-through from a designed
+    point mutation and it is pure arithmetic on a sequence they already hold.
+    """
+    from dee.core import mutagenesis as _mut
+
+    cds = str(args.get("cds") or args.get("sequence") or "")
+    label = str(args.get("substitution") or args.get("variant") or "")
+    if not cds.strip():
+        return {"ok": False, "error": "missing 'cds' (coding sequence from the ATG)"}
+    if not label.strip():
+        return {"ok": False, "error": "missing 'substitution' (e.g. R175H)"}
+    try:
+        return _mut.design(cds, label,
+                           host=str(args.get("host") or "e_coli"),
+                           method=str(args.get("method") or "quikchange"))
+    except Exception:  # noqa: BLE001
+        logger.exception("design_mutagenesis_primers failed")
+        return {"ok": False, "error": "Primer design failed."}
+
+
 def _tool_compare_sequences(args: Dict[str, Any]) -> Dict[str, Any]:
     """"How does my clone differ from the wild type?" — until now unanswerable.
 
@@ -1208,7 +1448,17 @@ def _tool_lookup_vector(args: Dict[str, Any]) -> Dict[str, Any]:
 
     entry = _vec.find(name)
     if entry:
+        # Where the plasmid actually comes from. The id is in the catalogue
+        # already; only the URL was missing, and an agent building one from
+        # "69864-3" produces a 404 — which reads to a user as "this vector
+        # doesn't exist".
+        source_url = _vec.addgene_url(entry)
         return {"ok": True, "vector": entry, "source": "curated catalogue",
+                **({"addgene_url": source_url,
+                    "where_to_get_it": (
+                        f"Available from Addgene: {source_url}. Give the user "
+                        f"the link rather than describing how to obtain it.")}
+                   if source_url else {}),
                 # Said out loud so the agent passes it on: this is a curated
                 # map, not the user's actual plasmid, and the two differ the
                 # moment anyone has modified their copy.
@@ -1858,6 +2108,21 @@ _TOOLS: Dict[str, Dict[str, Any]] = {
     # Pure local computation on a sequence the caller already has. Nothing
     # leaves the Space, nothing is stored.
     "compare_sequences": {"fn": _tool_compare_sequences, "requires_signin": False},
+    "check_overhangs": {"fn": _tool_check_overhangs, "requires_signin": False},
+    "check_residues": {"fn": _tool_check_residues, "requires_signin": False},
+    "check_conservation": {"fn": _tool_check_conservation, "requires_signin": False},
+    # Deliberately local-only. It exists so the reflex answer to "what is
+    # this?" is NOT blast_sequence, which is the one tool that transmits.
+    "identify_sequence": {"fn": _tool_identify_sequence, "requires_signin": False},
+    # Reads a public curated database. Only the accession leaves the Space —
+    # same contract as check_residues.
+    "map_domains": {"fn": _tool_map_domains, "requires_signin": False},
+    # Physical chemistry and codon arithmetic on a sequence the caller already
+    # has. Nothing transmitted, nothing stored, no model.
+    "assess_solubility": {"fn": _tool_assess_solubility, "requires_signin": False},
+    "assess_expression": {"fn": _tool_assess_expression, "requires_signin": False},
+    "design_mutagenesis_primers": {"fn": _tool_design_mutagenesis_primers,
+                                   "requires_signin": False},
     "check_synthesis":  {"fn": _tool_check_synthesis,  "requires_signin": False},
     "assess_stability": {"fn": _tool_assess_stability, "requires_signin": False},
     "fold_structure": {"fn": _tool_fold_structure, "requires_signin": False},
@@ -2402,6 +2667,293 @@ TOOL_SPECS: List[Dict[str, Any]] = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "assess_solubility",
+            "description": (
+                "AGGREGATION RISK FACTORS for a protein — hydrophobic patches, "
+                "GRAVY, pI vs the working pH, instability index, cysteines in "
+                "a reducing host. Insolubility is the most common way a good "
+                "design fails, so run this on variants the scorer likes before "
+                "anyone orders DNA. "
+                "TWO MODES: pass 'protein' to characterize one sequence, or "
+                "pass BOTH 'wild_type' and 'mutant' to see what a substitution "
+                "changes. PREFER THE SECOND — one residue apart, everything "
+                "that confounds an absolute reading cancels, and the result "
+                "says so. "
+                "IMPORTANT: there is no solubility score or probability here "
+                "and you must not invent one. Every tool that reports one is a "
+                "model trained on measured solubility data that is not "
+                "available in this engine. Relay 'no_score', and relay "
+                "'thresholds' — the hydrophobic-patch cutoff is a plot-reading "
+                "convention, not a validated boundary."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "protein": {"type": "string",
+                                "description": "One protein sequence to characterize."},
+                    "wild_type": {"type": "string",
+                                  "description": ("Reference protein. Use with "
+                                                  "'mutant' for the trustworthy "
+                                                  "comparison mode.")},
+                    "mutant": {"type": "string",
+                               "description": ("Variant of the same length — "
+                                               "point substitutions only.")},
+                    "host": {"type": "string",
+                             "description": ("Expression host, free text. "
+                                             "Changes the cysteine advice: the "
+                                             "E. coli cytoplasm is reducing.")},
+                    "ph": {"type": "number",
+                           "description": "Working buffer pH. Defaults to 7.4."},
+                },
+                "required": [],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "assess_expression",
+            "description": (
+                "WHY A CDS MAY EXPRESS BADLY in a host — rare codons, runs of "
+                "consecutive rare codons, the 5' ramp, GC, reading-frame "
+                "integrity. Needs the DNA, not the protein, because it counts "
+                "codons. Run it before ordering a synthesised gene. "
+                "The most actionable output is 'rare_codon_runs': a scattered "
+                "rare codon is absorbed, but three in a row stalls the "
+                "ribosome, and recoding just that run is usually the whole "
+                "fix. "
+                "IMPORTANT: this predicts NO yield and no expression level — "
+                "relay 'no_yield'. Yield depends on strain, promoter, copy "
+                "number, induction and toxicity, none of which is in a "
+                "sequence. If the host has no codon table the tool declines; "
+                "report that as missing reference data, NOT as the organism "
+                "being unsupported, and never substitute another host's table."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "dna": {"type": "string",
+                            "description": "The coding sequence, 30+ codons."},
+                    "host": {"type": "string",
+                             "description": ("Expression host, free text (e.g. "
+                                             "'e_coli', 'yeast', 'human'). "
+                                             "Required — expression is "
+                                             "host-specific.")},
+                },
+                "required": ["dna", "host"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "map_domains",
+            "description": (
+                "DOMAIN ARCHITECTURE from InterPro for a UniProt accession — "
+                "what the protein is made of, with boundaries. Call this "
+                "BEFORE choosing region_start/region_end for "
+                "design_variant_library on any protein over ~200 aa: a region "
+                "picked without domain boundaries is a guess, and one that "
+                "straddles two domains scrambles two things at once. Also call "
+                "it to say where a substitution sits — 'R175H is in the "
+                "DNA-binding domain' is an interpretation, 'R175H' alone is "
+                "not. Optionally pass 'positions' to have each one located. "
+                "Three things to relay: the coordinates are UniProt PRECURSOR "
+                "numbering (relay 'numbering' — it is offset from mature-"
+                "protein numbering by whatever was cleaved); entries can be "
+                "DISCONTINUOUS, so use 'segments' and never quote first-start "
+                "to last-end as one span; and no match means no signature "
+                "matched, which is expected for novel or designed proteins and "
+                "is NOT evidence of no domains. If 'truncated' is set, say the "
+                "architecture is incomplete."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "accession": {"type": "string",
+                                  "description": "UniProt accession, e.g. P04637."},
+                    "positions": {"type": "array", "items": {"type": "string"},
+                                  "description": ("Optional: positions or "
+                                                  "labels like R175H to locate "
+                                                  "within the architecture.")},
+                },
+                "required": ["accession"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "identify_sequence",
+            "description": (
+                "CALL THIS FIRST whenever the user pastes something and asks "
+                "what it is, or pastes a sequence with no explanation. It is "
+                "instant, local, and nothing leaves this Space. Accepts raw "
+                "residues, FASTA, GenBank, or an accession. Returns: which "
+                "molecule (DNA / RNA / protein / ambiguous), length, GC, "
+                "whether it is a clean CDS or where the longest ORF is, which "
+                "catalogued promoters / terminators / tags / recombination "
+                "sites it contains, and whether its ends match a known vector "
+                "junction. "
+                "IMPORTANT: 'identified' is ALWAYS false. This CHARACTERIZES a "
+                "sequence, it does not NAME it — a His-tag match is not "
+                "evidence that a sequence is any particular gene. To find out "
+                "what it actually is, call blast_sequence afterwards, and say "
+                "plainly that this sends the sequence to NCBI. If the result "
+                "is kind='ambiguous', ask the user rather than guessing. If a "
+                "'header_claim' comes back, relay it as what the file SAYS, "
+                "not as fact."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "sequence": {
+                        "type": "string",
+                        "description": ("Exactly what the user pasted — raw "
+                                        "residues, FASTA (header included), "
+                                        "GenBank, or an accession."),
+                    },
+                },
+                "required": ["sequence"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "check_conservation",
+            "description": (
+                "ALIGN HOMOLOGS AND COUNT which residues evolution refuses to "
+                "change. Give 'sequences' (3+ homologous proteins — BLAST the "
+                "target and take the hits) and optionally 'positions'. Returns "
+                "per-position consensus, agreement %, Shannon entropy and a "
+                "plain call (invariant / highly conserved / conserved / "
+                "variable). This is an OBSERVATION, not a prediction, and it "
+                "complements ESM-2 rather than confirming it — agreement "
+                "between them is real corroboration, disagreement is worth "
+                "investigating rather than averaging. Two things to relay: the "
+                "alignment is progressive and therefore approximate, and the "
+                "result is only as meaningful as the homolog set — check "
+                "'trustworthy' and pass on 'diversity_warning', because 40 "
+                "sequences at 99% identity are one sequence counted 40 times "
+                "and every column will look conserved."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "sequences": {"type": "array", "items": {"type": "string"},
+                                  "description": "3+ homologous protein sequences."},
+                    "names": {"type": "array", "items": {"type": "string"},
+                              "description": "Optional labels, same order."},
+                    "positions": {"type": "array", "items": {"type": "string"},
+                                  "description": "Optional: positions or labels like R175H."},
+                    "alignment_only": {"type": "boolean",
+                                       "description": "Return the alignment without scoring."},
+                },
+                "required": ["sequences"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "check_residues",
+            "description": (
+                "ASK UNIPROT WHAT IS KNOWN about the positions being mutated — "
+                "active sites, binding sites, disulfides, metal ligands, "
+                "domains. Call this BEFORE recommending substitutions: ESM-2 "
+                "scores how unusual a residue is, not how load-bearing it is, "
+                "so a catalytic residue can look perfectly tolerable to it. "
+                "Give 'accession' alone for the whole feature table, or with "
+                "'positions' (e.g. ['R175H', 200]) to check specific ones. "
+                "Two things you must relay: positions are UniProt's PRECURSOR "
+                "numbering and may be offset from the user's scheme; and no "
+                "annotation does NOT mean safe — most proteins are annotated "
+                "sparsely."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "accession": {"type": "string", "description": "UniProt accession, e.g. P00760."},
+                    "positions": {"type": "array", "items": {"type": "string"},
+                                  "description": "Optional: positions or substitution labels."},
+                },
+                "required": ["accession"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "check_overhangs",
+            "description": (
+                "CHECK A GOLDEN GATE OVERHANG SET for conflicts that make an "
+                "assembly misbuild — duplicates, palindromes (an overhang that "
+                "is its own reverse complement, so a fragment ligates to "
+                "itself), complementary pairs (two interchangeable junctions), "
+                "near-identical pairs one base apart, and all-AT/all-GC ends. "
+                "simulate_assembly only proves the overhangs CHAIN; it cannot "
+                "see that two of them cross-ligate, which is why a design with "
+                "six correct fragments still comes back wrong a week later. "
+                "Pass 'overhangs' to check a set, or 'suggest_count' to get a "
+                "conflict-free set. It does NOT return a fidelity percentage — "
+                "that needs published empirical ligation data this engine does "
+                "not have, so never state one."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "overhangs": {"type": "array", "items": {"type": "string"},
+                                  "description": "The set to check, e.g. ['GGAG','AATG','AGGT']."},
+                    "suggest_count": {"type": "integer",
+                                      "description": "Instead, propose this many conflict-free overhangs."},
+                    "length": {"type": "integer", "description": "Overhang length. Default 4."},
+                    "min_distance": {"type": "integer",
+                                     "description": "Minimum Hamming distance between overhangs. Default 2."},
+                },
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "design_mutagenesis_primers",
+            "description": (
+                "DESIGN THE PRIMERS that install a point mutation — the step "
+                "between 'R175H is worth trying' and DNA in a tube. Give it "
+                "the coding sequence (starting at the initiator ATG, because "
+                "residue numbers only mean something against a real reading "
+                "frame) and a substitution like R175H. Returns a primer pair "
+                "with Tm, GC%, hairpin and self-dimer checks, the codon it "
+                "chose for the host and why, and the protocol. Use method "
+                "'quikchange' for overlapping complementary primers or "
+                "'back_to_back' for Q5/KLD-style. It REFUSES when the "
+                "sequence's residue at that position disagrees with the "
+                "label — that means the user is holding a different sequence "
+                "than they think, and designing anyway would make primers for "
+                "a mutation nobody asked for. Melting temperatures are "
+                "calculated, not measured; always say the construct must be "
+                "sequenced to confirm."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "cds": {"type": "string",
+                            "description": "Coding sequence from the initiator ATG."},
+                    "substitution": {"type": "string",
+                                     "description": "e.g. R175H, G12D, C176Y."},
+                    "host": {"type": "string",
+                             "description": "Codon preference, e.g. e_coli, human, yeast."},
+                    "method": {"type": "string",
+                               "description": "'quikchange' (default) or 'back_to_back'."},
+                },
+                "required": ["cds", "substitution"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {

dee/core/conservation.py

@@ -0,0 +1,238 @@
+"""Which residues evolution has refused to change — computed, not predicted.
+
+WHY THIS EXISTS ALONGSIDE ESM-2
+-------------------------------
+ESM-2 gives a learned opinion about whether a substitution looks plausible.
+Conservation across real homologs gives an observed fact: in 40 orthologs,
+this position is serine 40 times. Those are different kinds of evidence and
+they fail differently — the model is weakest exactly where the audit says it
+is (membrane proteins, disordered regions, multi-domain assemblies), and a
+frequency count is unaffected by any of that.
+
+So this complements the scorer rather than duplicating it, which is why the
+audit rated it High: it is the cheapest real signal for "don't mutate this
+residue", and unlike a prediction it can be checked by counting.
+
+TWO PIECES
+----------
+`align_many` builds a progressive multiple alignment on top of the pairwise
+aligner that already exists (`align.py`), anchored on the longest sequence.
+This is the classic progressive approach and it is approximate: a true
+simultaneous MSA is exponential, and every practical tool approximates. It is
+honest about being an approximation rather than presenting itself as ground
+truth.
+
+`score` then counts. Shannon entropy per column, the most common residue, and
+the fraction of sequences that agree. No model, no training, no weights.
+
+THE HONEST LIMIT, WHICH IS ABOUT INPUT NOT ALGORITHM
+----------------------------------------------------
+Conservation is only as meaningful as the homolog set. Forty sequences that
+are 99% identical to each other say nothing — they are one sequence counted
+forty times. The result therefore reports the diversity of the input, and
+refuses to present a confident conservation call on a set with no spread.
+"""
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import Any, Dict, List, Optional, Sequence
+
+from dee.core.align import align
+
+GAP = "-"
+# Below this many sequences a "conserved" call means almost nothing.
+MIN_SEQS = 3
+# Mean pairwise identity above which the set is effectively one sequence.
+REDUNDANT_ABOVE = 95.0
+
+
+def _clean(s: str) -> str:
+    return re.sub(r"[^A-Za-z*]", "", s or "").upper()
+
+
+def align_many(sequences: Sequence[str],
+               names: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+    """Progressive multiple alignment, anchored on the longest sequence.
+
+    Each sequence is aligned pairwise to the anchor and its gaps merged into a
+    common frame. Approximate by construction — stated in the result so no
+    caller mistakes it for a simultaneous optimum.
+    """
+    seqs = [_clean(s) for s in (sequences or [])]
+    keep = [(i, s) for i, s in enumerate(seqs) if s]
+    if len(keep) < 2:
+        return {"ok": False, "error": "Need at least two non-empty sequences."}
+
+    labels = list(names or [])
+    def label(i: int) -> str:
+        return str(labels[i]) if i < len(labels) and labels[i] else f"seq{i + 1}"
+
+    anchor_i, anchor = max(keep, key=lambda kv: len(kv[1]))
+
+    # Columns the anchor must gain, keyed by the anchor index they precede.
+    inserts: Dict[int, int] = {}
+    pairs: List[Dict[str, Any]] = []
+    for i, s in keep:
+        if i == anchor_i:
+            continue
+        try:
+            r = align(anchor, s, mode="global")
+        except ValueError as exc:
+            return {"ok": False, "kind": "too_large", "error": str(exc),
+                    "next": "Align shorter sequences, or fewer of them."}
+        pairs.append({"i": i, "a": r["aligned_a"], "b": r["aligned_b"],
+                      "identity": r["identity"]})
+        pos = 0
+        run = 0
+        for ca in r["aligned_a"]:
+            if ca == GAP:
+                run += 1
+            else:
+                if run:
+                    inserts[pos] = max(inserts.get(pos, 0), run)
+                    run = 0
+                pos += 1
+        if run:
+            inserts[pos] = max(inserts.get(pos, 0), run)
+
+    def expand(aligned_a: str, aligned_b: str) -> str:
+        """Re-lay one pairwise result into the common frame."""
+        out: List[str] = []
+        pos = 0
+        run: List[str] = []
+        for ca, cb in zip(aligned_a, aligned_b):
+            if ca == GAP:
+                run.append(cb)
+                continue
+            need = inserts.get(pos, 0)
+            out.append("".join(run).ljust(need, GAP)[:need] if need else "")
+            run = []
+            out.append(cb)
+            pos += 1
+        need = inserts.get(pos, 0)
+        out.append("".join(run).ljust(need, GAP)[:need] if need else "")
+        return "".join(out)
+
+    rows: List[Dict[str, Any]] = []
+    frame_anchor = []
+    for pos, ch in enumerate(anchor):
+        frame_anchor.append(GAP * inserts.get(pos, 0) + ch)
+    frame_anchor.append(GAP * inserts.get(len(anchor), 0))
+    anchor_row = "".join(frame_anchor)
+    rows.append({"name": label(anchor_i), "aligned": anchor_row,
+                 "identity_to_anchor": 100.0, "is_anchor": True})
+    for p in pairs:
+        rows.append({"name": label(p["i"]), "aligned": expand(p["a"], p["b"]),
+                     "identity_to_anchor": p["identity"], "is_anchor": False})
+
+    width = max(len(r["aligned"]) for r in rows)
+    for r in rows:
+        r["aligned"] = r["aligned"].ljust(width, GAP)
+
+    ids = [r["identity_to_anchor"] for r in rows if not r["is_anchor"]]
+    return {
+        "ok": True,
+        "rows": rows,
+        "columns": width,
+        "sequences": len(rows),
+        "anchor": label(anchor_i),
+        "mean_identity_to_anchor": round(sum(ids) / len(ids), 1) if ids else 100.0,
+        "method": ("Progressive alignment onto the longest sequence, using the "
+                   "engine's Needleman-Wunsch. Approximate: a simultaneous "
+                   "optimum is exponential and every practical tool "
+                   "approximates. Treat column boundaries in gappy regions as "
+                   "indicative."),
+    }
+
+
+def score(sequences: Sequence[str], names: Optional[Sequence[str]] = None,
+          *, positions: Optional[Sequence[int]] = None) -> Dict[str, Any]:
+    """Per-column conservation across an alignment of homologs.
+
+    Positions, when given, are numbered along the ANCHOR (the longest input),
+    because that is the sequence a user is designing against.
+    """
+    seqs = [_clean(s) for s in (sequences or [])]
+    if len([s for s in seqs if s]) < MIN_SEQS:
+        return {"ok": False, "kind": "too_few",
+                "error": f"Conservation needs at least {MIN_SEQS} sequences; "
+                         f"got {len([s for s in seqs if s])}.",
+                "next": "Add orthologs — BLAST the sequence and take the hits."}
+
+    msa = align_many(seqs, names)
+    if not msa.get("ok"):
+        return msa
+
+    rows = msa["rows"]
+    anchor_row = next(r for r in rows if r["is_anchor"])["aligned"]
+    n = len(rows)
+
+    cols: List[Dict[str, Any]] = []
+    anchor_pos = 0
+    for c in range(msa["columns"]):
+        column = [r["aligned"][c] for r in rows]
+        anchor_ch = anchor_row[c]
+        if anchor_ch != GAP:
+            anchor_pos += 1
+        residues = [ch for ch in column if ch != GAP]
+        if not residues:
+            continue
+        counts = Counter(residues)
+        top, top_n = counts.most_common(1)[0]
+        # Shannon entropy over observed residues. 0 = every sequence agrees.
+        total = len(residues)
+        H = -sum((k / total) * math.log2(k / total) for k in counts.values())
+        cols.append({
+            "column": c,
+            "anchor_position": anchor_pos if anchor_ch != GAP else None,
+            "anchor_residue": None if anchor_ch == GAP else anchor_ch,
+            "consensus": top,
+            "agreement_pct": round(100.0 * top_n / total, 1),
+            # abs(): -sum(...) of an all-agreeing column yields IEEE -0.0, which
+            # prints as "-0.0 bits" and reads like a bug. Entropy is never
+            # negative.
+            "entropy_bits": abs(round(H, 3)),
+            "gaps": n - total,
+            # A plain word, because "0.0 bits" is not what a bench scientist
+            # reads. Thresholds are stated rather than hidden.
+            "call": ("invariant" if H == 0.0 else
+                     "highly conserved" if H < 0.5 else
+                     "conserved" if H < 1.0 else
+                     "variable"),
+        })
+
+    wanted = None
+    if positions:
+        want = {int(p) for p in positions}
+        wanted = [c for c in cols if c["anchor_position"] in want]
+
+    invariant = [c for c in cols if c["call"] == "invariant"]
+    mean_id = msa["mean_identity_to_anchor"]
+    redundant = mean_id > REDUNDANT_ABOVE
+    return {
+        "ok": True,
+        "sequences": n,
+        "anchor": msa["anchor"],
+        "columns": len(cols),
+        "invariant_count": len(invariant),
+        "conservation": wanted if wanted is not None else cols,
+        "mean_identity": mean_id,
+        "alignment_method": msa["method"],
+        # The limit that is about the INPUT, not the algorithm. Forty
+        # sequences at 99% identity are one sequence counted forty times, and
+        # every column will look invariant.
+        "diversity_warning": (
+            f"The homologs are {mean_id}% identical to each other on average. "
+            f"At that redundancy nearly every column looks conserved because "
+            f"the set carries little independent evidence. Use more divergent "
+            f"orthologs." if redundant else None),
+        "trustworthy": (not redundant) and n >= MIN_SEQS,
+        "caveat": ("Conservation is an OBSERVATION about the sequences given, "
+                   "not a property of the protein. It is only as meaningful as "
+                   "the homolog set: too few or too similar and it says "
+                   "nothing. It complements ESM-2 rather than confirming it — "
+                   "agreement between the two is genuine corroboration, "
+                   "disagreement is worth investigating, not averaging."),
+    }

dee/core/domains.py

@@ -0,0 +1,317 @@
+"""Domain architecture from InterPro — the boundaries that make a region mean
+something (audit #8, High).
+
+WHY THIS IS RATED HIGH
+----------------------
+The Directed Evolution pipeline takes `region_start` / `region_end`, and on a
+large protein those numbers are currently chosen blind. "Mutagenise 100-200"
+is a guess; "mutagenise the DNA-binding domain, 100-288" is a decision. Domain
+boundaries are what convert one into the other, and they are also what makes a
+single mutation interpretable — p53 R175H is meaningful precisely because 175
+falls inside the DNA-binding domain, not somewhere in a linker.
+
+`features.py` (#7) already asks UniProt what is known about individual
+POSITIONS. This asks InterPro what the protein is made OF. They answer
+different questions and both are curated reads — no model, no prediction.
+
+WHAT INTERPRO ACTUALLY RETURNS, AND WHY THE RAW ANSWER IS MISLEADING
+--------------------------------------------------------------------
+Ask InterPro about insulin and you get fourteen rows. That looks like fourteen
+findings; it is five. InterPro *integrates* member-database signatures — Pfam,
+SMART, PROSITE, PANTHER, CDD, PRINTS, CATH-Gene3D, SUPERFAMILY — and several
+of them independently model the same region, each contributing its own row
+that points back at one integrated `IPR…` entry.
+
+So this module groups by the integrated entry and reports the member databases
+as supporting evidence. Listing all fourteen would inflate a single domain
+call into a wall of apparent corroboration.
+
+The count is reported carefully for the same reason. Five methods agreeing is
+worth something, but they are built from overlapping training data and often
+from the same seed alignments — it is corroboration, not five independent
+observations, and the result says so rather than letting a number imply it.
+
+TWO THINGS THAT SILENTLY GIVE WRONG ANSWERS
+-------------------------------------------
+1. **Numbering.** InterPro coordinates are UniProt's, counted from residue 1
+   of the full precursor — signal peptide and propeptide included. Insulin's
+   domain "26-110" is on the 110-residue precursor; the mature B chain starts
+   at 25. A user working from mature-protein numbering will be off by a
+   constant, so the offset is stated every time, exactly as `features.py`
+   does.
+
+2. **Discontinuous domains.** Some entries are genuinely split — IPR022352 on
+   insulin is 29-45 *and* 90-109. Collapsing that to 29-109 would silently
+   claim 44 residues that are not in the domain. Segments are preserved and a
+   span is never inferred from min/max.
+
+Only the accession leaves the Space. Never a user sequence — and InterProScan,
+which WOULD accept a raw sequence, is a minutes-long job queue this module
+deliberately does not pretend to be.
+"""
+from __future__ import annotations
+
+import json
+import re
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional
+
+_UA = "TuringDNA/1.0 (https://turingdna.com)"
+_API = "https://www.ebi.ac.uk/interpro/api/entry/all/protein/uniprot"
+
+# Bounded paging. A heavily annotated protein can exceed one page; an unbounded
+# follow loop is a way to hang a request thread on someone else's pagination.
+PAGE_SIZE = 200
+MAX_PAGES = 5
+
+# Entry types, in the order a protein engineer cares about them. `domain` and
+# `repeat` carry real boundaries; `family` classifies the whole protein;
+# `homologous_superfamily` is a structural grouping that usually spans more
+# than the domain itself, so it is kept but ranked last.
+TYPE_ORDER = {
+    "domain": 0, "repeat": 1, "family": 2, "conserved_site": 3,
+    "active_site": 4, "binding_site": 5, "ptm": 6,
+    "homologous_superfamily": 7,
+}
+# The types whose coordinates are usable as a design region.
+BOUNDARY_TYPES = {"domain", "repeat"}
+
+
+def _get(url: str, timeout: float = 20.0) -> Optional[dict]:
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": _UA,
+                                                   "Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _segments(protein: Dict[str, Any]) -> List[Dict[str, int]]:
+    """Every fragment of every location, deduplicated and sorted.
+
+    Never min/max — a discontinuous domain is two spans, and merging them
+    would claim the residues in between.
+    """
+    out = []
+    for loc in (protein.get("entry_protein_locations") or []):
+        for frag in (loc.get("fragments") or []):
+            try:
+                s, e = int(frag["start"]), int(frag["end"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            if s > 0 and e >= s:
+                out.append({"start": s, "end": e})
+    seen, uniq = set(), []
+    for seg in sorted(out, key=lambda d: (d["start"], d["end"])):
+        key = (seg["start"], seg["end"])
+        if key not in seen:
+            seen.add(key)
+            uniq.append(seg)
+    return uniq
+
+
+def _raw_entries(acc: str):
+    """(rows, truncated). `truncated` matters: a page that fails mid-walk gives
+    a partial architecture, and a partial architecture presented as complete is
+    how a domain quietly goes missing."""
+    url = f"{_API}/{urllib.parse.quote(acc)}/?page_size={PAGE_SIZE}"
+    rows: List[Dict[str, Any]] = []
+    for _ in range(MAX_PAGES):
+        data = _get(url)
+        if data is None:
+            return (rows, True) if rows else (None, False)
+        rows.extend(data.get("results") or [])
+        url = data.get("next")
+        if not url:
+            return rows, False
+    return rows, bool(url)
+
+
+def domains(accession: str, positions: Optional[Iterable] = None) -> Dict[str, Any]:
+    """Domain architecture for one UniProt accession, grouped by InterPro entry."""
+    acc = re.sub(r"[^A-Za-z0-9\-.]", "", accession or "").upper()
+    if not acc:
+        return {"ok": False, "error": "No accession given.",
+                "next": ("This needs a UniProt accession. Running signatures "
+                         "against a raw sequence means InterProScan, which is "
+                         "a minutes-long job queue this engine does not run — "
+                         "identify the protein first (search_databases or "
+                         "blast_sequence) and pass the accession.")}
+
+    rows, truncated = _raw_entries(acc)
+    if rows is None:
+        return {"ok": False, "kind": "unreachable",
+                "error": f"Couldn't reach InterPro for {acc}.",
+                "next": "Retry; this is usually momentary."}
+
+    protein_length = None
+    groups: Dict[str, Dict[str, Any]] = {}
+    unintegrated: List[Dict[str, Any]] = []
+
+    for row in rows:
+        meta = row.get("metadata") or {}
+        prots = row.get("proteins") or []
+        if not prots:
+            continue
+        prot = prots[0]
+        if protein_length is None and prot.get("protein_length"):
+            protein_length = int(prot["protein_length"])
+        segs = _segments(prot)
+        if not segs:
+            continue
+
+        db = str(meta.get("source_database") or "").lower()
+        entry_acc = str(meta.get("accession") or "")
+        integrated = meta.get("integrated")
+
+        if db == "interpro":
+            g = groups.setdefault(entry_acc, {"members": [], "segments": []})
+            g.update({"interpro": entry_acc,
+                      "name": str(meta.get("name") or entry_acc),
+                      "type": str(meta.get("type") or "unknown"),
+                      "segments": segs})
+        elif integrated:
+            g = groups.setdefault(str(integrated), {"members": [], "segments": []})
+            g["members"].append({"database": db, "accession": entry_acc})
+        else:
+            # A signature InterPro has not integrated. Real, but it has not
+            # been curated into an entry, so it is kept separate rather than
+            # promoted alongside integrated calls.
+            unintegrated.append({"database": db, "accession": entry_acc,
+                                 "name": str(meta.get("name") or entry_acc),
+                                 "type": str(meta.get("type") or "unknown"),
+                                 "segments": segs})
+
+    entries = []
+    for key, g in groups.items():
+        if not g.get("interpro"):
+            # Members pointed at an entry that never came back in this
+            # response. Keep them rather than dropping the evidence silently.
+            g.update({"interpro": key, "name": key, "type": "unknown"})
+        members = sorted({m["database"] for m in g["members"]})
+        entries.append({
+            "interpro": g["interpro"],
+            "name": g["name"],
+            "type": g["type"],
+            "segments": g["segments"],
+            "residues": sum(s["end"] - s["start"] + 1 for s in g["segments"]),
+            "discontinuous": len(g["segments"]) > 1,
+            "supported_by": members,
+            "signatures": sorted(g["members"], key=lambda m: (m["database"],
+                                                             m["accession"])),
+        })
+    entries.sort(key=lambda e: (TYPE_ORDER.get(e["type"], 9),
+                                e["segments"][0]["start"] if e["segments"] else 0))
+
+    architecture = [e for e in entries if e["type"] in BOUNDARY_TYPES]
+    architecture.sort(key=lambda e: e["segments"][0]["start"])
+
+    result: Dict[str, Any] = {
+        "ok": True,
+        "accession": acc,
+        "protein_length": protein_length,
+        "entries": entries,
+        "architecture": [
+            {"name": e["name"], "interpro": e["interpro"],
+             "segments": e["segments"], "discontinuous": e["discontinuous"]}
+            for e in architecture],
+        "unintegrated": unintegrated,
+        "signature_rows": len(rows),
+        "source": "InterPro (EMBL-EBI)",
+        "summary": _summarize(acc, entries, architecture, protein_length),
+        "numbering": (
+            f"Positions are UniProt's, counted from residue 1 of the full "
+            f"precursor"
+            + (f" ({protein_length} aa)" if protein_length else "")
+            + ", including any signal peptide or propeptide. If the user is "
+              "working from mature-protein numbering, every boundary here is "
+              "offset by the length of what was cleaved."),
+        "evidence_note": (
+            "'supported_by' lists the member databases whose signatures "
+            "InterPro integrated into each entry. Several agreeing is "
+            "corroboration, but they are built from overlapping data and often "
+            "the same seed alignments — read it as one call with more support, "
+            "not as N independent observations."),
+        "caveat": (
+            "Signatures detect what resembles something already known. No "
+            "match means no signature matched, which for a designed, novel or "
+            "poorly studied protein is expected and is NOT evidence that the "
+            "protein has no domains."),
+    }
+
+    if truncated:
+        result["truncated"] = True
+        result["summary"] = ("PARTIAL — InterPro stopped responding part way "
+                             "through. " + result["summary"])
+        result["caveat"] = ("This architecture is INCOMPLETE: some pages did "
+                            "not come back, so a domain may be missing "
+                            "entirely. Retry before relying on it. "
+                            + result["caveat"])
+
+    wanted = _positions(positions)
+    if wanted:
+        result["positions"] = [_locate(p, entries, protein_length) for p in wanted]
+    return result
+
+
+def _positions(positions: Optional[Iterable]) -> List[int]:
+    """Accept ints or the substitution labels ('R175H') the engine speaks."""
+    out: List[int] = []
+    for p in (positions or []):
+        m = re.search(r"\d+", str(p))
+        if m:
+            out.append(int(m.group(0)))
+    return sorted(set(out))
+
+
+def _locate(pos: int, entries: List[Dict[str, Any]],
+            protein_length: Optional[int]) -> Dict[str, Any]:
+    """Which entries contain this residue."""
+    inside = [e for e in entries
+              if any(s["start"] <= pos <= s["end"] for s in e["segments"])]
+    boundary = [e for e in inside if e["type"] in BOUNDARY_TYPES]
+    out: Dict[str, Any] = {
+        "position": pos,
+        "in": [{"name": e["name"], "interpro": e["interpro"], "type": e["type"]}
+               for e in inside],
+    }
+    if protein_length and pos > protein_length:
+        out["note"] = (f"Position {pos} is past the end of this protein "
+                       f"({protein_length} aa) — check the numbering before "
+                       f"going further.")
+    elif boundary:
+        out["note"] = (f"Inside {boundary[0]['name']}. A substitution here is "
+                       f"in a structured unit, not a linker.")
+    elif inside:
+        out["note"] = ("Covered only by family or superfamily entries, which "
+                       "classify the whole protein — this position is not "
+                       "inside a specific annotated domain.")
+    else:
+        out["note"] = ("No InterPro entry covers this position. That is not "
+                       "the same as it being unimportant — it means no "
+                       "signature matched here.")
+    return out
+
+
+def _summarize(acc: str, entries: List[Dict[str, Any]],
+               architecture: List[Dict[str, Any]],
+               protein_length: Optional[int]) -> str:
+    if not entries:
+        return (f"No InterPro signatures matched {acc}. For a novel or "
+                f"designed protein that is expected, not a red flag.")
+    families = [e["name"] for e in entries if e["type"] == "family"]
+    bits = []
+    if protein_length:
+        bits.append(f"{protein_length} aa")
+    if families:
+        bits.append(families[0])
+    if architecture:
+        drawn = " · ".join(
+            f"{e['name']} ({'+'.join(str(s['start']) + '–' + str(s['end']) for s in e['segments'])})"
+            for e in architecture[:4])
+        bits.append(drawn + ("…" if len(architecture) > 4 else ""))
+    else:
+        bits.append("no domain-level boundaries — family-level classification only")
+    return " · ".join(bits)

dee/core/expression.py

@@ -0,0 +1,257 @@
+"""Why a construct expresses badly — the causes that are visible in the DNA.
+
+WHAT IS HONEST HERE, AND WHAT IS NOT
+------------------------------------
+#24 is rated High because a design that does not express is a wasted month,
+and nothing in the product currently looks at it. But an expression LEVEL —
+"expect 40 mg/L" — is not something this engine can honestly produce. Yield
+depends on the host strain, the promoter, plasmid copy number, induction
+temperature, media, growth phase, and whether the protein is toxic to the
+cell. None of that is in a sequence, and no model trained on it is available
+here. So there is no predicted yield in this module and there is no score.
+
+What IS in the sequence is a specific, enumerable set of causes that are known
+to break translation, and those are computed exactly:
+
+* **Rare codons**, from the engine's real usage tables in `codon.py` — the same
+  tables the library encoder uses, so a codon this module calls rare and a
+  codon the DE pipeline installs are the same opinion, not two.
+* **Rare-codon RUNS**, which matter far more than the overall count. A
+  scattered rare codon is absorbed; three in a row is where a ribosome stalls.
+* **The 5' ramp**, because the first ~50 codons carry the initiation region and
+  a rare codon there costs more than the same codon at residue 400.
+* **Reading-frame integrity**, because a construct with an internal stop
+  expresses a truncated product and every other number would describe a
+  protein that is never made.
+
+THE RARE-CODON THRESHOLD IS DERIVED, NOT CHOSEN
+------------------------------------------------
+Relative adaptiveness w = f(codon) / f(the most-used synonym), which is the
+Sharp & Li definition. At w < 0.15 the E. coli table selects AGA, AGG, ATA and
+CTA — precisely the set that Rosetta / CodonPlus strains exist to supply
+(argU, ileY, leuW). The cutoff was checked against the tables rather than
+picked, and the codons it selects are reported so the call can be audited.
+
+The same cutoff selects three arginine codons in yeast and NOTHING in human —
+which is a real result, not a failure. Mammalian codon usage is much flatter
+and the rare-codon story is genuinely weaker there. Reporting that is more
+useful than manufacturing a warning to look thorough.
+
+HOSTS THIS HAS NO TABLE FOR
+----------------------------
+`codon.py` carries E. coli, S. cerevisiae and human. For anything else this
+refuses and says so. That is not a capability gate on the organism — it is a
+missing data file, and silently scoring a plant construct against the E. coli
+table would be far worse than declining. Audit #11 (Kazusa tables) is the fix.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+from dee.core import codon as _codon
+from dee.core import edits as _edits
+
+# Relative adaptiveness below which a codon is called rare. Derived: see module
+# docstring. The selected codons travel with every result so this is auditable.
+RARE_BELOW = 0.15
+# Consecutive rare codons at or above this length is a stall risk rather than
+# noise. A lone rare codon is absorbed by the tRNA pool; a run depletes it.
+RUN_LENGTH = 3
+# The initiation region, where a rare codon costs disproportionately.
+RAMP_CODONS = 50
+# Below this there is not enough coding sequence for the statistics to mean
+# anything.
+MIN_CODONS = 30
+STOPS = {"TAA", "TAG", "TGA"}
+
+
+def _clean_dna(dna: str) -> str:
+    return re.sub(r"[^ACGTUacgtu]", "", dna or "").upper().replace("U", "T")
+
+
+def _adaptiveness(host: str) -> Dict[str, Any]:
+    """codon -> (amino acid, relative adaptiveness), from the engine's tables."""
+    table = _codon._resolve_table(host)
+    w: Dict[str, float] = {}
+    aa_of: Dict[str, str] = {}
+    for aa, usage in table.items():
+        top = max(usage.values()) or 1.0
+        for cod, freq in usage.items():
+            w[cod] = freq / top
+            aa_of[cod] = aa
+    return {"w": w, "aa": aa_of}
+
+
+def _runs(flags: List[bool], codons: List[str]) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    start = None
+    for i, bad in enumerate(flags + [False]):
+        if bad and start is None:
+            start = i
+        elif not bad and start is not None:
+            if i - start >= RUN_LENGTH:
+                out.append({"start_codon": start + 1, "end_codon": i,
+                            "length": i - start,
+                            "codons": codons[start:i]})
+            start = None
+    return out
+
+
+def assess(dna: str, host: str) -> Dict[str, Any]:
+    """Sequence-visible reasons a CDS may express poorly in `host`."""
+    seq = _clean_dna(dna)
+    if not host or not str(host).strip():
+        return {"ok": False, "error": "Which host? Expression is host-specific "
+                                      "— the same CDS behaves differently in "
+                                      "E. coli and in human cells."}
+    try:
+        adapt = _adaptiveness(str(host))
+    except ValueError as exc:
+        return {
+            "ok": False, "kind": "no_codon_table",
+            "error": str(exc),
+            "next": ("This is a missing data file, not an unsupported "
+                     "organism. Scoring the construct against a different "
+                     "host's table would produce confident nonsense, so it "
+                     "declines instead. Everything else about the sequence "
+                     "(check_synthesis, GC, reading frame) still works."),
+        }
+
+    if len(seq) < MIN_CODONS * 3:
+        return {"ok": False, "kind": "too_short",
+                "error": f"Need at least {MIN_CODONS} codons; got "
+                         f"{len(seq) // 3}.",
+                "next": "Paste the full coding sequence."}
+
+    frame_ok = len(seq) % 3 == 0
+    codons = [seq[i:i + 3] for i in range(0, len(seq) - len(seq) % 3, 3)]
+    # The terminal stop is expected; internal ones are the finding.
+    terminal_stop = bool(codons) and codons[-1] in STOPS
+    body = codons[:-1] if terminal_stop else codons
+    internal_stops = [i + 1 for i, c in enumerate(body) if c in STOPS]
+
+    w_map, aa_map = adapt["w"], adapt["aa"]
+    sense = [c for c in body if c not in STOPS]
+    unknown = [c for c in sense if c not in w_map]
+    scored = [c for c in sense if c in w_map]
+    # CAI excludes the single-codon families (Met, Trp): with one option there
+    # is no choice to adapt, and including them only pulls every score toward 1.
+    cai_pool = [w_map[c] for c in scored if aa_map[c] not in ("M", "W")]
+    cai = None
+    if cai_pool:
+        # Geometric mean, in log space — the direct product underflows on a
+        # long CDS and silently returns 0.0.
+        import math
+        cai = round(math.exp(sum(math.log(max(x, 1e-6)) for x in cai_pool)
+                             / len(cai_pool)), 3)
+
+    rare_flags = [c in w_map and w_map[c] < RARE_BELOW for c in body]
+    rare = [{"codon_number": i + 1, "codon": c, "amino_acid": aa_map.get(c),
+             "adaptiveness": round(w_map[c], 3)}
+            for i, c in enumerate(body)
+            if c in w_map and w_map[c] < RARE_BELOW]
+    runs = _runs(rare_flags, body)
+    ramp = [r for r in rare if r["codon_number"] <= RAMP_CODONS]
+
+    gc = round(100.0 * sum(c in "GC" for c in seq) / len(seq), 1)
+    ramp_seq = seq[:RAMP_CODONS * 3]
+    gc_ramp = round(100.0 * sum(c in "GC" for c in ramp_seq) / len(ramp_seq), 1)
+
+    rare_set = sorted({c for c, x in w_map.items() if x < RARE_BELOW
+                       and c not in STOPS})
+
+    flags: List[Dict[str, str]] = []
+    if not frame_ok:
+        flags.append({"factor": "not a whole number of codons",
+                      "observed": f"{len(seq)} nt",
+                      "why": ("The sequence is not in frame as given. Every "
+                              "codon-level number below is computed on the "
+                              "frame starting at base 1, which may not be the "
+                              "intended one.")})
+    if internal_stops:
+        flags.append({"factor": "internal stop codon",
+                      "observed": f"codon {internal_stops[0]}"
+                                  + (f" (+{len(internal_stops) - 1} more)"
+                                     if len(internal_stops) > 1 else ""),
+                      "why": ("Translation terminates here. The product is a "
+                              "truncated fragment, so nothing downstream "
+                              "describes the intended protein.")})
+    if not terminal_stop:
+        flags.append({"factor": "no terminal stop codon",
+                      "observed": f"ends {codons[-1] if codons else '?'}",
+                      "why": ("Without a stop the ribosome reads into the "
+                              "vector, adding an unintended C-terminal tail.")})
+    for run in runs:
+        flags.append({"factor": f"run of {run['length']} consecutive rare codons",
+                      "observed": (f"codons {run['start_codon']}-"
+                                   f"{run['end_codon']}: "
+                                   + " ".join(run["codons"])),
+                      "why": ("Consecutive rare codons deplete the local "
+                              "charged-tRNA pool and stall the ribosome, which "
+                              "causes truncation and frameshifting. This is "
+                              "the single most actionable finding here — "
+                              "recoding just this run is usually enough.")})
+    if ramp:
+        flags.append({"factor": f"{len(ramp)} rare codon(s) in the first "
+                                f"{RAMP_CODONS} codons",
+                      "observed": ", ".join(f"{r['codon']}@{r['codon_number']}"
+                                            for r in ramp[:6]),
+                      "why": ("The 5' region sets the rate of translation "
+                              "initiation, so a rare codon here costs more "
+                              "than the same codon further in.")})
+
+    return {
+        "ok": True,
+        "host": host,
+        "codons": len(body),
+        "codon_adaptation_index": cai,
+        "gc_percent": gc,
+        "gc_percent_5prime": gc_ramp,
+        "rare_codons": rare,
+        "rare_codon_count": len(rare),
+        "rare_codon_runs": runs,
+        "rare_in_ramp": ramp,
+        "internal_stops": internal_stops,
+        "has_terminal_stop": terminal_stop,
+        "in_frame": frame_ok,
+        "is_clean_cds": _edits.is_coding(seq),
+        "unrecognised_codons": len(unknown),
+        "flags": flags,
+        "summary": _summary(host, len(body), cai, rare, runs, flags),
+        "rare_codons_in_this_host": rare_set,
+        "method": (f"Relative adaptiveness w = f(codon) / f(most-used synonym) "
+                   f"(Sharp & Li), from the engine's own {host} usage table — "
+                   f"the same table the library encoder writes with. Rare means "
+                   f"w < {RARE_BELOW}, which in this host selects: "
+                   f"{' '.join(rare_set) if rare_set else 'nothing'}. CAI is "
+                   f"the geometric mean of w over sense codons, excluding Met "
+                   f"and Trp, which have no synonym to choose between."),
+        # The line this module exists to be able to say.
+        "no_yield": ("This does NOT predict an expression level. Yield depends "
+                     "on strain, promoter, copy number, induction temperature, "
+                     "media and protein toxicity — none of which is in a "
+                     "sequence, and no model trained on them is available "
+                     "here. These are the sequence-visible causes of failure, "
+                     "not a forecast."),
+        "not_covered": ("Also not checked here: internal Shine-Dalgarno-like "
+                        "pausing sites, mRNA secondary structure over the RBS "
+                        "(audit #38/#39, which need an RNA folding engine), "
+                        "and protein-level causes — for those run "
+                        "assess_solubility on the translated product."),
+    }
+
+
+def _summary(host: str, n: int, cai: Optional[float], rare: List[Dict[str, Any]],
+             runs: List[Dict[str, Any]], flags: List[Dict[str, str]]) -> str:
+    bits = [f"{n} codons in {host}"]
+    if cai is not None:
+        bits.append(f"CAI {cai}")
+    bits.append(f"{len(rare)} rare codon(s)")
+    if runs:
+        bits.append(f"{len(runs)} rare run(s) — codons "
+                    + ", ".join(f"{r['start_codon']}-{r['end_codon']}"
+                                for r in runs[:3]))
+    if not flags:
+        bits.append("nothing flagged")
+    return " · ".join(bits)

dee/core/features.py

@@ -0,0 +1,202 @@
+"""The residues you should not mutate, from the people who curated them.
+
+THE PROBLEM
+-----------
+The engine will happily rank a substitution at the catalytic serine of a
+protease as promising. ESM-2 scores how UNUSUAL a residue is, not how load-
+bearing it is, and an active-site residue is often perfectly ordinary in
+sequence terms — it is the geometry that matters, and a language model over
+sequence does not see geometry.
+
+So the single cheapest improvement to design quality is not a better model. It
+is asking UniProt what is already known about the positions being mutated:
+active sites, binding sites, disulfides, metal ligands, domains. That is
+curated, citable, human-reviewed annotation, and it turns "this substitution
+looks tolerable" into "this substitution is at the catalytic residue".
+
+WHAT THIS IS
+------------
+A read of UniProt's feature table, mapped onto positions the user cares about.
+No prediction, no score, no model — every item returned carries the evidence
+UniProt itself carries. When UniProt has nothing for a protein, that is
+reported as "not annotated", never as "safe": absence of annotation is absence
+of knowledge, and conflating the two is how a tool talks someone into an
+experiment.
+
+Only (accession) leaves the Space. Never a user sequence.
+"""
+from __future__ import annotations
+
+import json
+import re
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional
+
+_UA = "TuringDNA/1.0 (https://turingdna.com)"
+_ENTRY = "https://rest.uniprot.org/uniprotkb"
+
+# Feature types worth interrupting a design for, in the order a designer cares.
+# UniProt emits many more (VARIANT, CONFLICT, chains); those describe the
+# record, not a reason to avoid a position, and including them would bury the
+# signal.
+CRITICAL = {
+    "Active site":      "catalytic — mutating this typically abolishes activity",
+    "Binding site":     "contacts the substrate or cofactor",
+    "Site":             "functionally annotated position",
+    "Metal binding":    "coordinates a metal ion the fold depends on",
+    "Disulfide bond":   "forms a disulfide; losing one cysteine breaks both",
+    "Modified residue": "post-translationally modified",
+    "Glycosylation":    "glycosylation site",
+    "Cross-link":       "covalently cross-linked",
+}
+CONTEXT = {
+    "Domain":   "domain",
+    "Region":   "region",
+    "Motif":    "motif",
+    "Repeat":   "repeat",
+    "Transmembrane": "membrane-spanning",
+    "Signal":   "signal peptide",
+    "Propeptide": "propeptide — cleaved from the mature protein",
+}
+
+
+def _get(url: str, timeout: float = 15.0) -> Optional[dict]:
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": _UA,
+                                                   "Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _span(f: Dict[str, Any]) -> Optional[tuple]:
+    loc = (f.get("location") or {})
+    try:
+        s = loc["start"]["value"]
+        e = loc["end"]["value"]
+    except (KeyError, TypeError):
+        return None
+    if s is None or e is None:
+        return None
+    return (int(s), int(e))
+
+
+def fetch(accession: str) -> Dict[str, Any]:
+    """UniProt's curated feature table for one accession."""
+    acc = re.sub(r"[^A-Za-z0-9\-]", "", accession or "").upper()
+    if not acc:
+        return {"ok": False, "error": "No accession given."}
+    # The whole entry, filtered here. A ?fields= list looked tidier and is
+    # not valid on the entry endpoint — it returns an error, not a subset, so
+    # the "tidy" version fetched nothing at all.
+    data = _get(f"{_ENTRY}/{urllib.parse.quote(acc)}.json")
+    if not data:
+        return {"ok": False, "kind": "unreachable",
+                "error": f"Couldn't reach UniProt for {acc}.",
+                "next": "Retry; this is usually momentary."}
+
+    feats = []
+    for f in (data.get("features") or []):
+        sp = _span(f)
+        if not sp:
+            continue
+        ftype = str(f.get("type") or "")
+        tier = "critical" if ftype in CRITICAL else (
+            "context" if ftype in CONTEXT else None)
+        if tier is None:
+            continue
+        feats.append({
+            "type": ftype,
+            "start": sp[0], "end": sp[1],
+            "tier": tier,
+            "description": str(f.get("description") or "")[:180],
+            "means": CRITICAL.get(ftype) or CONTEXT.get(ftype, ""),
+            # UniProt's own evidence codes travel with the claim. ECO:0000269
+            # is experimental; ECO:0000250 is inferred by similarity, and a
+            # designer should weight those differently.
+            "evidence": sorted({str(e.get("evidenceCode") or "")
+                                for e in (f.get("evidences") or [])
+                                if e.get("evidenceCode")}),
+        })
+
+    name = ""
+    try:
+        name = (data["proteinDescription"]["recommendedName"]
+                    ["fullName"]["value"])
+    except (KeyError, TypeError):
+        pass
+    return {
+        "ok": True,
+        "accession": data.get("primaryAccession") or acc,
+        "protein": name,
+        "length": ((data.get("sequence") or {}).get("length")),
+        "features": feats,
+        "critical_count": sum(1 for f in feats if f["tier"] == "critical"),
+        "source": "UniProt",
+    }
+
+
+def annotate(accession: str, positions: Iterable) -> Dict[str, Any]:
+    """Which of `positions` land on annotated features.
+
+    Positions may be integers or substitution labels ('R175H'); the label form
+    is what the rest of the engine speaks, so accepting it saves the caller a
+    parsing step and a chance to get the offset wrong.
+    """
+    table = fetch(accession)
+    if not table.get("ok"):
+        return table
+
+    wanted: List[Dict[str, Any]] = []
+    for p in positions or []:
+        if isinstance(p, int):
+            wanted.append({"label": str(p), "pos": p})
+            continue
+        m = re.match(r"^([A-Za-z])?(\d+)([A-Za-z*])?$", str(p).strip())
+        if m:
+            wanted.append({"label": str(p).strip(), "pos": int(m.group(2))})
+
+    hits = []
+    for w in wanted:
+        on = [f for f in table["features"] if f["start"] <= w["pos"] <= f["end"]]
+        crit = [f for f in on if f["tier"] == "critical"]
+        hits.append({
+            "label": w["label"], "position": w["pos"],
+            "critical": crit, "context": [f for f in on if f["tier"] == "context"],
+            # The whole point of the tool, stated so the agent cannot miss it.
+            "verdict": ("AVOID — annotated functional residue" if crit else
+                        "no functional annotation at this position"),
+        })
+
+    flagged = [h for h in hits if h["critical"]]
+    return {
+        "ok": True,
+        "accession": table["accession"], "protein": table["protein"],
+        "length": table["length"],
+        "positions": hits,
+        "flagged_count": len(flagged),
+        "verdict": (f"{len(flagged)} of {len(hits)} positions sit on annotated "
+                    f"functional residues." if flagged else
+                    f"None of the {len(hits)} positions are annotated as "
+                    f"functional."),
+        # The failure that would make this tool actively harmful. UniProt
+        # numbers the FULL PRECURSOR — bovine trypsin's catalytic triad is at
+        # 63/107/200 here, not the classic His57/Asp102/Ser195, because the
+        # signal peptide and propeptide are counted. A user thinking in mature
+        # or chymotrypsin numbering gets a confident flag on the wrong residue,
+        # which is worse than no flag at all.
+        "numbering": (f"Positions are UniProt's, numbered from residue 1 of the "
+                      f"full precursor ({table['length']} aa) including any "
+                      f"signal peptide or propeptide. If you are using mature-"
+                      f"protein or a classic numbering scheme, these will be "
+                      f"offset — check one known residue before trusting the "
+                      f"rest."),
+        "caveat": ("Absence of annotation is absence of KNOWLEDGE, not evidence "
+                   "that a position is safe — most proteins are annotated "
+                   "sparsely, and an unannotated residue may still be "
+                   "essential. Evidence codes are UniProt's own: ECO:0000269 "
+                   "is experimental, ECO:0000250 is inferred by similarity."),
+        "source": "UniProt",
+    }

dee/core/identify.py

@@ -0,0 +1,355 @@
+"""What is this thing I just pasted? — answered locally first, and honestly.
+
+The audit calls this "the single most common first move a scientist makes"
+(#5, High). Someone has a sequence from a collaborator, a supplementary table
+or a sequencing run, and the first question is not "improve it" but "what am I
+even looking at?".
+
+THE DISTINCTION THIS MODULE IS BUILT AROUND
+-------------------------------------------
+**Characterizing is not identifying.** Everything here is computed from the
+residues themselves against catalogues already in this repo: it can say "this
+is 1,341 bp of DNA, one clean reading frame, carrying a T7 promoter and a
+C-terminal 6xHis, and its 3' junction matches pET-28a(+)". That is a real,
+checkable, useful answer and it costs nothing.
+
+What it can NOT say is "this is human MC1R". Naming a sequence requires
+comparing it to every known sequence, which means BLAST — and BLAST is the one
+operation in this engine that sends the user's actual residues outside the
+Space. So `identified` is **always False** here, and the result names the tool
+that would change that. An agent that says "this is insulin" because it found
+a His-tag is exactly the failure this module exists to prevent.
+
+That ordering is also the privacy-correct one. Local analysis answers most of
+the question for free; BLAST is offered as a deliberate, consented step rather
+than being the reflex.
+
+REUSE, DON'T REINVENT
+---------------------
+The audit's single most common finding is capability that already exists in
+the repo with nothing pointing at it. So this module computes almost nothing
+of its own:
+
+* `sequence.classify_sequence`  — the three-way DNA/protein/ambiguous call
+* `plasmid.find_motifs`         — the curated motif catalogue (promoters,
+                                  terminators, tags, loxP/FRT/att sites)
+* `plasmid.find_orfs`           — linear-time ORF scan on both strands
+* `edits.is_coding` / `translate` — the strict CDS test and the codon table
+* `accession.classify`          — is the paste actually an identifier?
+* `vectors`                     — the 61-backbone catalogue and its junctions
+
+The protein tag table is **derived by translating the DNA motifs already in
+`plasmid._MOTIFS`** rather than typed out here. One source of truth, and no
+sequence in this file was written from recall.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+from dee.core import accession as _acc
+from dee.core import edits as _edits
+from dee.core import plasmid as _plasmid
+from dee.core import sequence as _seq
+from dee.core import vectors as _vectors
+
+# Below this there is not enough sequence to say anything, and a 6-mer matches
+# something by chance in every database on earth.
+MIN_LEN = 12
+# Shortest ORF worth reporting. Below ~30 aa an "ORF" in random DNA is noise:
+# a stop codon appears roughly every 21 codons by chance.
+MIN_ORF_AA = 30
+# A vector junction shorter than this is usually just a restriction site, which
+# is shared by hundreds of backbones and proves nothing. Most of the 61
+# catalogue entries record only a 6-bp site, so only a minority can ever
+# produce a junction call — which is the honest outcome, not a shortfall.
+MIN_JUNCTION = 16
+# Distinct residues below which a "protein" looks synthetic or mis-pasted.
+LOW_COMPLEXITY_BELOW = 8
+LOW_COMPLEXITY_MIN_LEN = 60
+
+_FASTA_HEADER = re.compile(r"^\s*>([^\n\r]*)", re.M)
+_GENBANK = re.compile(r"^\s*LOCUS\s+\S", re.M)
+
+
+def _tag_peptides() -> List[Dict[str, str]]:
+    """Protein-level tags, derived from the repo's own DNA motif catalogue.
+
+    Translating `plasmid._MOTIFS` keeps a single source of truth and means no
+    peptide here was typed from memory — if the DNA catalogue is corrected,
+    this follows automatically.
+    """
+    out: List[Dict[str, str]] = []
+    seen = set()
+    for name, motif, ftype in _plasmid._MOTIFS:
+        if ftype != "tag" or len(motif) % 3:
+            continue
+        pep = _edits.translate(motif)
+        if not pep or "X" in pep or "*" in pep:
+            continue
+        if pep in seen:
+            continue
+        seen.add(pep)
+        out.append({"name": name, "peptide": pep})
+    return out
+
+
+_TAGS = _tag_peptides()
+
+
+def _clean_residues(text: str) -> str:
+    """Strip FASTA headers, digits and whitespace; keep letters and stops."""
+    body = re.sub(r"^\s*>[^\n]*$", "", text or "", flags=re.M)
+    return re.sub(r"[^A-Za-z*]", "", body).upper()
+
+
+def _read_paste(text: str) -> Dict[str, Any]:
+    """Work out what SHAPE the paste is before worrying what it contains."""
+    raw = (text or "").strip()
+    if not raw:
+        return {"format": "empty", "header": None, "residues": ""}
+    if _GENBANK.search(raw):
+        return {"format": "genbank", "header": None,
+                "residues": _clean_residues(raw)}
+    m = _FASTA_HEADER.search(raw)
+    if m:
+        return {"format": "fasta", "header": m.group(1).strip()[:200],
+                "residues": _clean_residues(raw)}
+    # A bare token with no residue-ish bulk may be an identifier, not a sequence.
+    token = raw.split()[0] if raw.split() else ""
+    if len(raw.split()) == 1 and _acc.looks_like_accession(token):
+        return {"format": "accession", "header": None, "residues": "",
+                "token": token}
+    return {"format": "raw", "header": None, "residues": _clean_residues(raw)}
+
+
+def _header_accession(header: str) -> Optional[Dict[str, str]]:
+    """An accession quoted in a FASTA header is a CLAIM, not evidence."""
+    for token in re.split(r"[|\s,;]+", header or ""):
+        token = token.strip()
+        if len(token) >= 4 and _acc.looks_like_accession(token):
+            family, molecule = _acc.classify(token)
+            return {"accession": token, "family": family, "molecule": molecule}
+    return None
+
+
+def _vector_junctions(dna: str) -> List[Dict[str, Any]]:
+    """Catalogue backbones whose cloning junction appears in this sequence.
+
+    Hits are grouped by end, because a junction identifies a FAMILY, not a
+    vector: the whole pET series shares one C-terminal His junction, and the
+    catalogue happens to record it at different lengths for different entries.
+    A longer recorded junction is a longer catalogue string, not better
+    evidence — naming the longest match alone would invent a distinction the
+    sequence does not support.
+    """
+    found: Dict[str, List[Dict[str, Any]]] = {}
+    try:
+        cat = _vectors._load()
+    except Exception:                                    # pragma: no cover
+        return []
+    up = dna.upper()
+    for rec in cat.values():
+        for field in ("flanking_5p_max", "flanking_3p_max"):
+            junction = (rec.get(field) or "").upper()
+            if len(junction) < MIN_JUNCTION:
+                continue
+            for strand, needle in ((1, junction), (-1, _plasmid.revcomp(junction))):
+                idx = up.find(needle)
+                if idx < 0:
+                    continue
+                end = "5'" if field.startswith("flanking_5p") else "3'"
+                found.setdefault(end, []).append({
+                    "vector": rec.get("name") or rec.get("id"),
+                    "start": idx, "strand": strand, "matched_bp": len(junction),
+                })
+                break
+
+    out: List[Dict[str, Any]] = []
+    for end, hits in sorted(found.items()):
+        hits.sort(key=lambda h: (-h["matched_bp"], str(h["vector"])))
+        names = [h["vector"] for h in hits]
+        out.append({
+            "end": end,
+            "vectors": names,
+            "start": min(h["start"] for h in hits),
+            "longest_match_bp": max(h["matched_bp"] for h in hits),
+            "distinguishing": len(names) == 1,
+            "note": None if len(names) == 1 else (
+                f"{len(names)} catalogue backbones share this {end} junction. "
+                f"The match says which FAMILY the construct came from, not "
+                f"which vector — do not pick one."),
+        })
+    return out
+
+
+def _analyse_dna(dna: str) -> Dict[str, Any]:
+    ambiguous = sum(1 for c in dna if c not in "ACGT")
+    out: Dict[str, Any] = {
+        "gc_percent": _plasmid.gc_percent(dna),
+        "ambiguity_codes": ambiguous,
+        "multiple_of_three": len(dna) % 3 == 0,
+        "is_clean_cds": _edits.is_coding(dna),
+    }
+
+    orfs = _plasmid.find_orfs(dna, min_aa=MIN_ORF_AA, max_orfs=200)
+    if orfs:
+        longest = max(orfs, key=lambda o: o["end"] - o["start"])
+        span = longest["end"] - longest["start"]
+        out["orfs"] = len(orfs)
+        out["longest_orf"] = {
+            "aa": span // 3 - 1,               # the terminal stop is not a residue
+            "start": longest["start"], "end": longest["end"],
+            "strand": longest["strand"],
+            "covers_percent": round(100.0 * span / len(dna), 1),
+        }
+    else:
+        out["orfs"] = 0
+        out["longest_orf"] = None
+
+    out["features"] = [
+        {"name": f["name"], "type": f["type"], "start": f["start"],
+         "end": f["end"], "strand": f["strand"]}
+        for f in _plasmid.find_motifs(dna)
+    ]
+    out["vector_junctions"] = _vector_junctions(dna)
+    return out
+
+
+def _analyse_protein(protein: str) -> Dict[str, Any]:
+    body = protein.rstrip("*")
+    distinct = len(set(body))
+    out: Dict[str, Any] = {
+        "starts_with_methionine": body.startswith("M"),
+        "internal_stop": "*" in body,
+        "unknown_residues": body.count("X"),
+        "distinct_residues": distinct,
+    }
+    out["tags"] = [
+        {"name": t["name"], "peptide": t["peptide"], "start": body.find(t["peptide"])}
+        for t in _TAGS if t["peptide"] in body
+    ]
+    # A real protein uses most of the alphabet. Very low diversity means either
+    # a synthetic construct (poly-A linker, His run) or DNA pasted by mistake.
+    out["low_complexity"] = (len(body) >= LOW_COMPLEXITY_MIN_LEN
+                             and distinct < LOW_COMPLEXITY_BELOW)
+    return out
+
+
+def _summary(molecule: str, length: int, detail: Dict[str, Any]) -> str:
+    """One line a bench scientist would actually say out loud."""
+    if molecule == "protein":
+        bits = [f"{length} aa protein"]
+        if detail.get("tags"):
+            bits.append(", ".join(t["name"] for t in detail["tags"]))
+        # Worth surfacing unprompted: a premature stop means the translation
+        # is truncated, and every downstream number would be about a protein
+        # the cell never makes.
+        if detail.get("internal_stop"):
+            bits.append("contains an internal stop — this translation is truncated")
+        if detail.get("unknown_residues"):
+            bits.append(f"{detail['unknown_residues']} unknown (X) residues")
+        if detail.get("low_complexity"):
+            bits.append("unusually low residue diversity")
+        return " · ".join(bits)
+    unit = "nt RNA" if molecule == "rna" else "bp DNA"
+    bits = [f"{length} {unit}", f"{detail.get('gc_percent')}% GC"]
+    if detail.get("is_clean_cds"):
+        bits.append("a clean CDS end to end")
+    elif detail.get("longest_orf"):
+        orf = detail["longest_orf"]
+        bits.append(f"longest ORF {orf['aa']} aa ({orf['covers_percent']}% of it)")
+    else:
+        bits.append("no ORF of 30 aa or more")
+    named = sorted({f["name"] for f in detail.get("features") or []})
+    if named:
+        bits.append(", ".join(named[:4]) + ("…" if len(named) > 4 else ""))
+    for j in (detail.get("vector_junctions") or [])[:1]:
+        names = j["vectors"]
+        bits.append(f"{j['end']} junction matches {names[0]}" if j["distinguishing"]
+                    else (f"{j['end']} junction shared by {len(names)} catalogue "
+                          f"backbones ({names[0]}, {names[1]}…)"))
+    return " · ".join(bits)
+
+
+def identify(text: str) -> Dict[str, Any]:
+    """Characterize a pasted sequence locally. Never claims to have named it."""
+    paste = _read_paste(text)
+
+    if paste["format"] == "empty":
+        return {"ok": False, "kind": "empty", "error": "Nothing to identify.",
+                "next": "Paste a sequence, or an accession to fetch one."}
+
+    if paste["format"] == "accession":
+        token = paste["token"]
+        family, molecule = _acc.classify(token)
+        return {
+            "ok": True, "kind": "accession", "identified": False,
+            "input_format": "accession", "accession": token,
+            "family": family, "molecule": molecule,
+            "summary": (f"'{token}' is a {family} identifier"
+                        + (f" for {molecule}" if molecule else "")
+                        + ", not a sequence."),
+            "next": (f"Call fetch_sequence with '{token}' to retrieve it. "
+                     f"An accession names the sequence already — there is "
+                     f"nothing to identify."),
+        }
+
+    residues = paste["residues"]
+    if len(residues) < MIN_LEN:
+        return {"ok": False, "kind": "too_short",
+                "error": f"Only {len(residues)} residues; {MIN_LEN} is the "
+                         f"minimum worth analysing.",
+                "next": "Short oligos are better handled by design_primers."}
+
+    molecule = _seq.classify_sequence(residues)
+    if molecule == "dna" and "U" in residues and "T" not in residues:
+        molecule = "rna"
+
+    if molecule == "ambiguous":
+        return {
+            "ok": True, "kind": "ambiguous", "identified": False,
+            "input_format": paste["format"], "molecule": "ambiguous",
+            "length": len(residues),
+            "summary": (f"{len(residues)} residues of A/C/G/T/U/N only — at "
+                        f"this length that reads equally well as a short "
+                        f"peptide or a DNA fragment."),
+            "next": ("Ask the user which it is before analysing further. "
+                     "Guessing here silently misroutes the whole job."),
+        }
+
+    detail = (_analyse_protein(residues) if molecule == "protein"
+              else _analyse_dna(residues))
+
+    claim = _header_accession(paste["header"]) if paste.get("header") else None
+    result: Dict[str, Any] = {
+        "ok": True,
+        "kind": "characterized",
+        "input_format": paste["format"],
+        "molecule": molecule,
+        "length": len(residues),
+        "summary": _summary(molecule, len(residues), detail),
+        "detail": detail,
+        # The whole point. Local analysis describes; it does not name.
+        "identified": False,
+        "to_identify_it": (
+            "Nothing above names this sequence — it is computed from the "
+            "residues against local catalogues. To find out WHAT it is, call "
+            "blast_sequence, which searches NCBI. That sends the sequence "
+            "outside this Space and the user is asked to approve it first."),
+        "caveat": (
+            "Motif and junction matches are exact string matches against a "
+            "curated list, so a hit is real but an absence means only 'not in "
+            "the list' — the catalogue is small and deliberately conservative."),
+    }
+
+    if paste.get("header"):
+        result["header_claim"] = {
+            "text": paste["header"],
+            "accession": claim,
+            "note": ("This came from the FASTA header, which is whatever the "
+                     "person who wrote the file typed. Treat it as a claim to "
+                     "check, not as evidence — fetch the accession and compare "
+                     "if it matters."),
+        }
+    return result

dee/core/mutagenesis.py

@@ -0,0 +1,224 @@
+"""Primers that actually make the mutation the engine just designed.
+
+THE GAP THIS CLOSES
+-------------------
+The engine will tell you R175H is the substitution worth trying. Then it
+stops. Getting from "R175H is a good idea" to DNA in a tube means designing a
+mutagenesis primer pair by hand — picking the codon, centring the mismatch,
+balancing the flanks so both arms melt at the same temperature. That is the
+most common wet-lab follow-through from a designed point mutation, and until
+now the product had nothing to say about it.
+
+It is also pure arithmetic on a sequence the user already has. Nothing here
+needs a network, an account, or a model.
+
+DESIGN DECISIONS THAT MATTER AT THE BENCH
+-----------------------------------------
+*The mismatch sits in the middle.* A mutation near a primer's end anneals
+poorly and the reaction fails; the standard rule is 10-15 matching bases on
+BOTH sides, so the arms are grown outward from the change rather than the
+primer being cut from a fixed window.
+
+*The two arms are balanced by Tm, not by length.* Flanks of equal length can
+differ by 8 C when one is GC-rich, and the cooler arm is where the reaction
+fails. Each side is extended until it reaches the target Tm.
+
+*The codon is chosen for the host, not at random.* Six codons encode leucine
+and they are not interchangeable in E. coli. The existing codon table decides,
+and the choice is reported so it can be checked.
+
+*Both protocols are supported and they are not the same shape.* QuikChange-
+style uses fully overlapping complementary primers; the back-to-back style
+(Q5/KLD) uses non-overlapping primers that amplify the whole plasmid outward.
+Which one a lab uses is a kit decision, so the caller says.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+from dee.core.primers import gc_clamp, gc_percent, hairpin_score, revcomp
+from dee.core.primers import self_dimer_3p, tm_c
+
+# Standard practice for site-directed mutagenesis: enough matching sequence on
+# each side of the mismatch that the primer still anneals despite it.
+MIN_FLANK = 10
+MAX_FLANK = 25
+TARGET_TM = 60.0            # C; both arms are grown toward this
+TM_TOLERANCE = 3.0
+
+_LABEL = re.compile(r"^([A-Z])(\d+)([A-Z*])$", re.I)
+_CODON_STOP = {"TAA", "TAG", "TGA"}
+
+
+def parse_substitution(label: str) -> Optional[Dict[str, Any]]:
+    """'R175H' -> {'wt':'R','pos':175,'mut':'H'}."""
+    m = _LABEL.match((label or "").strip())
+    if not m:
+        return None
+    return {"wt": m.group(1).upper(), "pos": int(m.group(2)),
+            "mut": m.group(3).upper()}
+
+
+def _codon_for(aa: str, host: str) -> Optional[str]:
+    """The host's preferred codon for this residue.
+
+    Delegates to the existing codon table rather than carrying a second one —
+    two tables that disagree is a bug nobody finds for months.
+    """
+    if aa == "*":
+        return "TAA"
+    try:
+        from dee.core import codon as _codon
+        # _resolve_table raises on an unknown host, which is the honest
+        # answer — a silent fallback to E. coli would codon-optimise a yeast
+        # construct for the wrong organism and say nothing.
+        return _codon._best_codon(aa, _codon._resolve_table(host)).upper()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _grow(template: str, centre: int, span: int, target_tm: float) -> tuple:
+    """Extend outward from a change until the arm reaches `target_tm`.
+
+    Returns (start, end) into `template`. Length is the OUTPUT of the melting
+    temperature, not an input — flanks of equal length routinely differ by
+    several degrees, and the cooler arm is the one that fails.
+    """
+    start, end = centre, centre + span
+    while True:
+        left = centre - start
+        right = end - (centre + span)
+        seq = template[start:end]
+        if left >= MIN_FLANK and right >= MIN_FLANK:
+            t = tm_c(seq)
+            if t is not None and t >= target_tm:
+                break
+            if left >= MAX_FLANK and right >= MAX_FLANK:
+                break
+        # Grow the shorter side first so the mismatch stays centred.
+        if start > 0 and (left <= right or end >= len(template)):
+            start -= 1
+        elif end < len(template):
+            end += 1
+        else:
+            break
+    return (start, end)
+
+
+def design(cds: str, label: str, *, host: str = "e_coli",
+           method: str = "quikchange") -> Dict[str, Any]:
+    """Primers that install `label` into `cds`.
+
+    `cds` must start at the A of the initiator ATG — positions in a
+    substitution label are residue numbers, and they only mean anything
+    against a real reading frame.
+    """
+    seq = re.sub(r"[^ACGTacgt]", "", cds or "").upper()
+    sub = parse_substitution(label)
+    if not sub:
+        return {"ok": False, "error": f"Couldn't read '{label}'. Use e.g. R175H."}
+    if method not in ("quikchange", "back_to_back"):
+        return {"ok": False,
+                "error": "method must be 'quikchange' (overlapping primers) or "
+                         "'back_to_back' (Q5/KLD, non-overlapping)"}
+    if len(seq) < 6:
+        return {"ok": False, "error": "No coding sequence given."}
+
+    i = (sub["pos"] - 1) * 3
+    if i + 3 > len(seq):
+        return {"ok": False, "kind": "out_of_range",
+                "error": f"Position {sub['pos']} is past the end of a "
+                         f"{len(seq) // 3}-residue sequence.",
+                "next": "Check the sequence starts at the initiator ATG."}
+
+    wt_codon = seq[i:i + 3]
+    # Never take the label's word for the wild-type residue. Same rule the
+    # edit tool follows: a mismatch here means the user is holding a different
+    # sequence than they think, and silently proceeding designs primers for a
+    # mutation nobody asked for.
+    try:
+        from dee.core.edits import translate as _translate
+        observed = _translate(wt_codon)
+    except Exception:  # noqa: BLE001
+        observed = None
+    if observed and observed.upper() != sub["wt"]:
+        return {"ok": False, "kind": "wt_mismatch",
+                "error": f"Position {sub['pos']} is {observed}, not "
+                         f"{sub['wt']} — the sequence and the label disagree.",
+                "next": "Check the numbering, or the sequence's reading frame."}
+
+    new_codon = _codon_for(sub["mut"], host)
+    if not new_codon:
+        return {"ok": False, "kind": "no_codon",
+                "error": f"No codon table entry for {sub['mut']} in '{host}'.",
+                "next": "Try another host, or supply the codon explicitly."}
+
+    mutated = seq[:i] + new_codon + seq[i + 3:]
+
+    if method == "quikchange":
+        s, e = _grow(mutated, i, 3, TARGET_TM)
+        fwd = mutated[s:e]
+        rev = revcomp(fwd)                    # fully complementary, by design
+        pair = [("forward", fwd, s, e), ("reverse", rev, s, e)]
+        overlap = len(fwd)
+    else:
+        # Back-to-back: the change rides on the 5' end of the forward primer
+        # and the two primers amplify the whole plasmid outward from it.
+        s, e = _grow(mutated, i, 3, TARGET_TM)
+        fwd = mutated[i:e]
+        rev = revcomp(mutated[s:i])
+        pair = [("forward", fwd, i, e), ("reverse", rev, s, i)]
+        overlap = 0
+
+    primers = []
+    for role, p, a, b in pair:
+        primers.append({
+            "role": role, "sequence": p, "length": len(p),
+            "tm_c": tm_c(p), "gc_pct": round(gc_percent(p), 1),
+            "gc_clamp": gc_clamp(p),
+            "hairpin": hairpin_score(p), "self_dimer_3p": self_dimer_3p(p),
+            "template_start": a, "template_end": b,
+        })
+
+    warnings = []
+    tms = [p["tm_c"] for p in primers if p["tm_c"] is not None]
+    if len(tms) == 2 and abs(tms[0] - tms[1]) > TM_TOLERANCE:
+        warnings.append(
+            f"The two primers differ by {abs(tms[0] - tms[1]):.1f} C. The "
+            f"cooler one is where the reaction fails — consider extending it.")
+    for p in primers:
+        if p["hairpin"] >= 4:
+            warnings.append(f"{p['role']} primer can form a hairpin "
+                            f"(stem {p['hairpin']}).")
+        if p["self_dimer_3p"] >= 3:
+            warnings.append(f"{p['role']} primer self-dimerises at its 3' end.")
+        if not p["gc_clamp"]:
+            warnings.append(f"{p['role']} primer has no G/C at its 3' end.")
+
+    return {
+        "ok": True,
+        "substitution": label.upper(),
+        "method": method,
+        "host": host,
+        "wt_codon": wt_codon,
+        "new_codon": new_codon,
+        # Reported so the codon choice can be checked rather than trusted.
+        "codon_note": f"{sub['wt']}({wt_codon}) → {sub['mut']}({new_codon}), "
+                      f"preferred codon for {host}",
+        "primers": primers,
+        "overlap_bp": overlap,
+        "warnings": warnings,
+        "mutated_cds": mutated,
+        "protocol": (
+            "QuikChange-style: fully overlapping complementary primers, "
+            "whole-plasmid PCR, then DpnI to remove methylated template."
+            if method == "quikchange" else
+            "Back-to-back (Q5/KLD-style): non-overlapping primers amplify the "
+            "plasmid outward; the product is then kinased, ligated and "
+            "DpnI-treated."),
+        "caveat": ("Melting temperatures are calculated, not measured, and "
+                   "assume standard PCR salt conditions. Verify the construct "
+                   "by sequencing — these primers propose a change, they do "
+                   "not confirm one."),
+    }

dee/core/orchestrator.py

@@ -368,6 +368,45 @@ def _summarize(name: str, result: Dict[str, Any]) -> str:
             return (f"{n} hit{'' if n == 1 else 's'} · top "
                     f"{top.get('identity_pct')}% id"
                     + (f" · {top.get('organism')}" if top.get("organism") else ""))
+        if name == "check_conservation":
+            if result.get("rows") is not None:          # alignment_only
+                return f"{result.get('sequences')} seqs · {result.get('columns')} columns"
+            inv, n = result.get("invariant_count") or 0, result.get("sequences") or 0
+            base = f"{n} homologs · {inv} invariant position{'' if inv == 1 else 's'}"
+            # An untrustworthy set is the headline, not a footnote: every
+            # column looks conserved when the homologs are near-identical.
+            return base + ("" if result.get("trustworthy")
+                           else f" · {result.get('mean_identity')}% identical, too redundant to trust")
+        if name == "check_residues":
+            if result.get("positions") is not None:
+                n = result.get("flagged_count") or 0
+                tot = len(result.get("positions") or [])
+                # Lead with the veto: "3 positions checked" buries the one
+                # that sits on the catalytic residue.
+                return (f"{n} of {tot} on functional residues" if n
+                        else f"{tot} positions · none annotated")
+            return (f"{result.get('critical_count')} functional features · "
+                    f"{result.get('protein', '')[:34]}")
+        if name == "check_overhangs":
+            if result.get("min_distance") is not None:      # a suggest() result
+                return f"{result.get('count')} conflict-free overhangs"
+            f = result.get("fatal") or 0
+            n = len(result.get("conflicts") or [])
+            if not n:
+                return f"{result.get('count')} overhangs · no conflicts"
+            # Fatal first: "6 conflicts" reads the same whether the assembly
+            # is merely weak or cannot have a defined order at all.
+            return (f"{result.get('count')} overhangs · {n} conflict"
+                    f"{'' if n == 1 else 's'}"
+                    + (f", {f} fatal" if f else ""))
+        if name == "design_mutagenesis_primers":
+            ps = result.get("primers") or []
+            tms = [p.get("tm_c") for p in ps if p.get("tm_c") is not None]
+            base = (f"{result.get('substitution')} · {len(ps)} primers"
+                    + (f" · Tm {min(tms):.0f}-{max(tms):.0f} C" if tms else ""))
+            # Warnings are why someone re-reads the design before ordering.
+            n = len(result.get("warnings") or [])
+            return base + (f" · {n} warning{'' if n == 1 else 's'}" if n else "")
         if name == "compare_sequences":
             if result.get("identical"):
                 return f"identical · {result.get('alignment_length'):,} positions"

dee/core/overhangs.py

@@ -0,0 +1,234 @@
+"""Why a Golden Gate assembly with six correct fragments still comes back wrong.
+
+THE FAILURE THIS CATCHES
+------------------------
+`cloning.py` simulates the assembly: it finds the Type IIS sites, cuts, and
+chains parts whose overhangs match into a circle. If the overhangs chain, it
+reports success — and it is right, as a simulation.
+
+What it cannot see is that two of those overhangs are one base apart, or that
+one is its own reverse complement. In the tube, T4 ligase does not care which
+partner it found; near-identical overhangs cross-ligate and the plate comes
+back with fragments in the wrong order or dropped entirely. The simulation
+says the design works. The bench says otherwise, a week later.
+
+Every one of those conflicts is decidable from the four-base sequences alone,
+before anything is ordered.
+
+WHAT THIS DOES AND DOES NOT CLAIM
+---------------------------------
+It reports STRUCTURAL conflicts — facts about the sequences:
+
+    duplicate          the same overhang used twice; the assembly cannot have
+                       a defined order
+    palindromic        an overhang that is its own reverse complement, so a
+                       fragment ligates to itself and to its own inverse
+    complementary      one overhang is the reverse complement of another, so
+                       the two junctions are interchangeable
+    near-identical     overhangs differing by a single base, the classic
+                       source of low-frequency misassembly
+    low complexity     all-AT ligates weakly, all-GC ligates promiscuously
+
+It does NOT report a "fidelity percentage". Those numbers come from published
+empirical ligation datasets measured on real reactions; this engine has none
+of that data, and a percentage computed from sequence alone would be a
+fabricated measurement wearing a decimal point. What is returned is what can
+be checked by eye — which is also what lets a user fix it.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Iterable, List, Optional
+
+# Type IIS enzymes in common use leave a 4-nt 5' overhang. The length is a
+# property of the enzyme, so it is a parameter rather than a constant.
+DEFAULT_LEN = 4
+_COMP = str.maketrans("ACGT", "TGCA")
+
+
+def revcomp(s: str) -> str:
+    return s.translate(_COMP)[::-1]
+
+
+def _clean(s: str) -> str:
+    return re.sub(r"[^ACGTacgt]", "", s or "").upper()
+
+
+def is_palindrome(oh: str) -> bool:
+    """Self-complementary — ligates to itself AND to its own inverse.
+
+    An even-length overhang can be its own reverse complement (AATT, GGCC).
+    A junction built on one has no defined orientation.
+    """
+    return bool(oh) and oh == revcomp(oh)
+
+
+def hamming(a: str, b: str) -> int:
+    """Substitutions between two equal-length overhangs. -1 if lengths differ."""
+    if len(a) != len(b):
+        return -1
+    return sum(1 for x, y in zip(a, b) if x != y)
+
+
+def gc_fraction(oh: str) -> float:
+    return (oh.count("G") + oh.count("C")) / len(oh) if oh else 0.0
+
+
+def check(overhangs: Iterable[str], *, length: int = DEFAULT_LEN,
+          min_distance: int = 2) -> Dict[str, Any]:
+    """Every structural conflict in a proposed overhang set.
+
+    `min_distance` is the Hamming distance below which two overhangs are
+    reported as too similar. 2 is the working default: at distance 1 a single
+    mis-pairing event produces a wrong-but-ligatable junction.
+    """
+    raw = list(overhangs or [])
+    ohs: List[str] = []
+    rejected: List[str] = []
+    for o in raw:
+        c = _clean(o)
+        if len(c) != length:
+            rejected.append(f"{o!r} is not {length} nt")
+        else:
+            ohs.append(c)
+
+    conflicts: List[Dict[str, Any]] = []
+
+    # 1. Duplicates — the assembly has no defined order at all.
+    seen: Dict[str, int] = {}
+    for idx, o in enumerate(ohs):
+        if o in seen:
+            conflicts.append({
+                "kind": "duplicate", "severity": "fatal",
+                "overhangs": [o], "positions": [seen[o], idx],
+                "why": f"{o} is used at two junctions, so the fragments "
+                       f"between them can assemble in either order."})
+        else:
+            seen[o] = idx
+
+    # 2. Palindromes — a fragment that ligates to itself.
+    for idx, o in enumerate(ohs):
+        if is_palindrome(o):
+            conflicts.append({
+                "kind": "palindromic", "severity": "fatal",
+                "overhangs": [o], "positions": [idx],
+                "why": f"{o} is its own reverse complement, so the fragment "
+                       f"can ligate to itself and to its own inversion."})
+
+    # 3 & 4. Pairwise: complementarity and near-identity, each checked against
+    # the partner AND the partner's reverse complement, because the strand a
+    # ligase sees depends on which fragment arrives.
+    for i in range(len(ohs)):
+        for j in range(i + 1, len(ohs)):
+            a, b = ohs[i], ohs[j]
+            rb = revcomp(b)
+            if a == rb:
+                conflicts.append({
+                    "kind": "complementary", "severity": "fatal",
+                    "overhangs": [a, b], "positions": [i, j],
+                    "why": f"{a} is the reverse complement of {b}, so those "
+                           f"two junctions are interchangeable."})
+                continue
+            d = min(hamming(a, b), hamming(a, rb))
+            if 0 < d < min_distance:
+                conflicts.append({
+                    "kind": "near_identical", "severity": "high",
+                    "overhangs": [a, b], "positions": [i, j], "distance": d,
+                    "why": f"{a} and {b} differ by {d} base"
+                           f"{'' if d == 1 else 's'}; a single mis-pairing "
+                           f"gives a wrong junction that still ligates."})
+
+    # 5. Composition — weak or promiscuous ends.
+    for idx, o in enumerate(ohs):
+        gc = gc_fraction(o)
+        if gc == 0.0:
+            conflicts.append({
+                "kind": "low_complexity", "severity": "medium",
+                "overhangs": [o], "positions": [idx],
+                "why": f"{o} is all A/T — the weakest ligation in the set, and "
+                       f"the junction most likely to be missing."})
+        elif gc == 1.0:
+            conflicts.append({
+                "kind": "low_complexity", "severity": "medium",
+                "overhangs": [o], "positions": [idx],
+                "why": f"{o} is all G/C, which ligates promiscuously."})
+
+    fatal = sum(1 for c in conflicts if c["severity"] == "fatal")
+    high = sum(1 for c in conflicts if c["severity"] == "high")
+    if not ohs:
+        verdict = "No usable overhangs given."
+    elif fatal:
+        verdict = (f"{fatal} conflict(s) that make the assembly ambiguous. "
+                   f"This set will not build reliably.")
+    elif high:
+        verdict = f"{high} pair(s) close enough to misligate at low frequency."
+    elif conflicts:
+        verdict = "Usable, with weak junctions noted."
+    else:
+        verdict = f"No structural conflicts across {len(ohs)} overhangs."
+
+    return {
+        "ok": True,
+        "overhangs": ohs,
+        "count": len(ohs),
+        "rejected": rejected,
+        "conflicts": conflicts,
+        "fatal": fatal,
+        "usable": fatal == 0 and bool(ohs),
+        "verdict": verdict,
+        "basis": ("Structural conflicts computed from the sequences. NOT a "
+                  "fidelity percentage — those come from published empirical "
+                  "ligation datasets this engine does not have, and a number "
+                  "derived from sequence alone would be invented."),
+    }
+
+
+def suggest(count: int, *, length: int = DEFAULT_LEN, min_distance: int = 2,
+            avoid: Optional[Iterable[str]] = None) -> Dict[str, Any]:
+    """A conflict-free set of `count` overhangs.
+
+    Greedy: walk the space in a fixed order and keep any candidate that
+    conflicts with nothing already chosen. Deterministic on purpose — the same
+    request gives the same set, so a design is reproducible and a methods
+    section can name it.
+    """
+    if count < 1:
+        return {"ok": False, "error": "Need at least one overhang."}
+    blocked = {_clean(o) for o in (avoid or []) if _clean(o)}
+    chosen: List[str] = []
+
+    def fits(cand: str) -> bool:
+        if is_palindrome(cand):
+            return False
+        g = gc_fraction(cand)
+        if g in (0.0, 1.0):
+            return False
+        for o in list(chosen) + list(blocked):
+            if cand == o or cand == revcomp(o):
+                return False
+            if 0 < min(hamming(cand, o), hamming(cand, revcomp(o))) < min_distance:
+                return False
+        return True
+
+    from itertools import product
+    for combo in product("ACGT", repeat=length):
+        if len(chosen) >= count:
+            break
+        cand = "".join(combo)
+        if fits(cand):
+            chosen.append(cand)
+
+    if len(chosen) < count:
+        # The space genuinely runs out; say so rather than return a short set
+        # that looks complete.
+        return {"ok": False, "kind": "exhausted",
+                "error": f"Only {len(chosen)} conflict-free {length}-nt "
+                         f"overhangs exist at distance {min_distance} "
+                         f"(asked for {count}).",
+                "found": chosen,
+                "next": "Lower min_distance, use a longer overhang, or split "
+                        "the assembly into two rounds."}
+    return {"ok": True, "overhangs": chosen, "count": len(chosen),
+            "min_distance": min_distance,
+            "note": "Deterministic: the same request returns the same set, so "
+                    "the design is reproducible."}

dee/core/solubility.py

@@ -0,0 +1,347 @@
+"""Why a designed protein ends up in the pellet — risk factors, not a score.
+
+WHAT THE AUDIT ASKED FOR AND WHAT IS HONEST TO BUILD
+-----------------------------------------------------
+#23 is rated High because insolubility is the most common way a good design
+fails: ESM-2 likes the variant, it expresses, and you harvest a pellet of
+inclusion bodies. Today that failure mode is completely invisible in the
+product.
+
+What is NOT honest is a solubility probability. Protein-Sol, NetSolP, CamSol
+and SoluProt all report one, and every one of them is a model trained on
+measured solubility data — data this engine does not have and a model it does
+not run. A number here would be invented, so there is no number here. This
+follows `stability.py` exactly, which reports structural risk factors and
+refuses to print a ΔΔG for the same reason.
+
+What IS honest is the physical chemistry that is computable from the sequence
+with published, cited scales, reported as named risk factors a scientist can
+check and disagree with.
+
+THE TWO MODES, AND WHY THE SECOND IS THE TRUSTWORTHY ONE
+---------------------------------------------------------
+`assess()` characterizes one protein in isolation. Useful, but weakly
+calibrated — absolute hydropathy tells you less than people assume, and every
+threshold below is a convention for reading a plot, not a validated cutoff.
+
+`compare()` is the mode that earns its keep, and it is the one the Directed
+Evolution loop should call. Wild type and a point mutant are the same protein
+with one residue changed, so everything that would confound an absolute
+prediction — fold, length, expression host, composition — cancels. "This
+substitution drops a charge and adds a leucine inside an existing hydrophobic
+patch" is a checkable statement about a specific change. "This protein is 62%
+soluble" is not.
+
+EVERY NUMBER COMES FROM A CITED SCALE, NONE FROM RECALL
+--------------------------------------------------------
+Hydropathy is Kyte-Doolittle via `Bio.SeqUtils.ProtParamData.kd`; the
+instability index is Guruswamy's DIWV table via Biopython; pI and charge are
+Biopython's. Biopython is already a dependency, the tables ship with it, and
+nothing in this file is a value typed from memory.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from Bio.SeqUtils import ProtParamData
+from Bio.SeqUtils.ProtParam import ProteinAnalysis
+
+# Sliding window for the hydropathy plot. Kyte-Doolittle used 7-11 for general
+# character and 19 to call transmembrane helices; 9 is the usual middle.
+KD_WINDOW = 9
+# Mean hydropathy over that window at or above which a stretch is called a
+# hydrophobic patch. THIS IS A READING CONVENTION, not a validated solubility
+# threshold — stated here so it can be argued with rather than hidden.
+PATCH_THRESHOLD = 1.5
+# Guruswamy's own cutoff: above 40 the protein is classed unstable. That one is
+# from the paper, not chosen here.
+INSTABILITY_CUTOFF = 40.0
+# Net charge is what keeps molecules apart. Within this much of the working pH,
+# charge approaches zero and so does electrostatic repulsion.
+PI_DANGER_WINDOW = 1.0
+DEFAULT_PH = 7.4
+MIN_LEN = 20
+
+_KD = ProtParamData.kd
+
+
+def _clean(protein: str) -> str:
+    return "".join(c for c in (protein or "").upper() if c.isalpha())
+
+
+def _known(protein: str) -> str:
+    """Only residues Biopython's scales cover. X/B/Z/U have no KD value and
+    would raise; dropping them is right, but the count is reported so a
+    heavily-ambiguous sequence is not silently analysed as if it were clean."""
+    return "".join(c for c in protein if c in _KD)
+
+
+def _hydropathy(protein: str) -> List[float]:
+    """Kyte-Doolittle mean over a sliding window, one value per window start."""
+    if len(protein) < KD_WINDOW:
+        return []
+    vals = [_KD[c] for c in protein]
+    return [round(sum(vals[i:i + KD_WINDOW]) / KD_WINDOW, 3)
+            for i in range(len(vals) - KD_WINDOW + 1)]
+
+
+def _patches(protein: str) -> List[Dict[str, Any]]:
+    """Contiguous runs at or above the patch threshold, in 1-based positions.
+
+    Exposed hydrophobic surface is the thing that actually drives aggregation:
+    two molecules stick where they are both greasy. A patch is therefore more
+    informative than whole-protein GRAVY, which averages it away.
+    """
+    scores = _hydropathy(protein)
+    out: List[Dict[str, Any]] = []
+    start = None
+    for i, s in enumerate(scores):
+        if s >= PATCH_THRESHOLD:
+            if start is None:
+                start = i
+        elif start is not None:
+            out.append({"start": start + 1, "end": i + KD_WINDOW - 1,
+                        "peak": max(scores[start:i])})
+            start = None
+    if start is not None:
+        out.append({"start": start + 1, "end": len(protein),
+                    "peak": max(scores[start:])})
+    return out
+
+
+_ROUNDING = {"gravy": 3, "isoelectric_point": 2, "net_charge_at_ph": 2,
+             "instability_index": 1, "aromaticity": 3}
+
+
+def _metrics(protein: str, ph: float) -> Dict[str, Any]:
+    """Full precision. `compare` subtracts these BEFORE any rounding.
+
+    Differencing two values that were each already rounded to one decimal
+    silently reports 0.0 for a real change — which would zero out precisely
+    the small deltas this module exists to surface.
+    """
+    pa = ProteinAnalysis(protein)
+    patches = _patches(protein)
+    return {
+        "length": len(protein),
+        "gravy": pa.gravy(),
+        "isoelectric_point": pa.isoelectric_point(),
+        "net_charge_at_ph": pa.charge_at_pH(ph),
+        "instability_index": pa.instability_index(),
+        "aromaticity": pa.aromaticity(),
+        "cysteines": protein.count("C"),
+        "hydrophobic_patches": patches,
+        "longest_patch": max((p["end"] - p["start"] + 1 for p in patches),
+                             default=0),
+    }
+
+
+def _factors(protein: str, ph: float) -> Dict[str, Any]:
+    """The display view: same metrics, rounded for reading."""
+    return _round(_metrics(protein, ph))
+
+
+def _round(m: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: (round(v, _ROUNDING[k]) if k in _ROUNDING else v)
+            for k, v in m.items()}
+
+
+def _flags(f: Dict[str, Any], ph: float, host: Optional[str]) -> List[Dict[str, str]]:
+    """Named, checkable concerns. Each says what was measured and why it matters."""
+    out: List[Dict[str, str]] = []
+    if f["gravy"] > 0:
+        out.append({"factor": "net hydrophobic",
+                    "observed": f"GRAVY {f['gravy']}",
+                    "why": ("Positive GRAVY means the average residue is "
+                            "hydrophobic. For a soluble cytoplasmic protein "
+                            "that is unusual and often means a membrane "
+                            "protein, a fragment, or a folding problem.")})
+    if f["longest_patch"] >= KD_WINDOW * 2:
+        out.append({"factor": "extended hydrophobic patch",
+                    "observed": f"{f['longest_patch']} residues",
+                    "why": ("A long exposed greasy stretch is where two "
+                            "molecules stick to each other. This is the most "
+                            "direct sequence-level aggregation risk.")})
+    if abs(f["isoelectric_point"] - ph) < PI_DANGER_WINDOW:
+        out.append({"factor": "pI close to the working pH",
+                    "observed": f"pI {f['isoelectric_point']} vs pH {ph}",
+                    "why": ("Near its pI the protein carries almost no net "
+                            "charge, so the electrostatic repulsion keeping "
+                            "molecules apart disappears. Moving the buffer pH "
+                            "a point either way is often the whole fix.")})
+    if f["instability_index"] > INSTABILITY_CUTOFF:
+        out.append({"factor": "instability index above the published cutoff",
+                    "observed": f"{f['instability_index']} (cutoff "
+                                f"{INSTABILITY_CUTOFF})",
+                    "why": ("Guruswamy's index, computed from dipeptide "
+                            "composition. It predicts a short half-life in "
+                            "vivo, not insolubility — related, not the same.")})
+    if f["cysteines"] >= 2 and (host or "").lower().replace("-", "_") in (
+            "e_coli", "ecoli", "bacteria"):
+        out.append({"factor": f"{f['cysteines']} cysteines in an E. coli host",
+                    "observed": f"{f['cysteines']} Cys",
+                    "why": ("The E. coli cytoplasm is reducing, so disulfides "
+                            "do not form there. A protein that needs them "
+                            "typically misfolds into inclusion bodies — the "
+                            "usual answers are periplasmic export or a "
+                            "disulfide-permissive strain.")})
+    return out
+
+
+def assess(protein: str, *, host: Optional[str] = None,
+           ph: float = DEFAULT_PH) -> Dict[str, Any]:
+    """Aggregation risk factors for one protein. Never a solubility score."""
+    seq = _clean(protein)
+    known = _known(seq)
+    if len(known) < MIN_LEN:
+        return {"ok": False, "kind": "too_short",
+                "error": f"Need at least {MIN_LEN} scored residues; got "
+                         f"{len(known)}.",
+                "next": "Paste the full protein sequence."}
+
+    f = _factors(known, ph)
+    flags = _flags(f, ph, host)
+    result = {
+        "ok": True,
+        "factors": f,
+        "flags": flags,
+        "ph": ph,
+        "host": host,
+        "summary": _summary(f, flags),
+        "scales": ("Hydropathy: Kyte-Doolittle. Instability index: Guruswamy "
+                   "(DIWV). pI and charge: Biopython. All ship with Biopython "
+                   "— no value here was entered by hand."),
+        # The line this module exists to be able to say.
+        "no_score": ("This does NOT report a solubility score or probability. "
+                     "That needs a model trained on measured solubility data "
+                     "(Protein-Sol, NetSolP, CamSol), which is not available "
+                     "here — so a number would be invented. These are named "
+                     "risk factors instead, each one checkable."),
+        "thresholds": (f"'Hydrophobic patch' means mean Kyte-Doolittle "
+                       f"≥ {PATCH_THRESHOLD} over a {KD_WINDOW}-residue "
+                       f"window. That is a convention for reading a hydropathy "
+                       f"plot, not a validated solubility cutoff. The "
+                       f"instability cutoff of {INSTABILITY_CUTOFF} is "
+                       f"Guruswamy's own."),
+        "caveat": ("Absolute risk factors are weakly calibrated. For deciding "
+                   "between variants, compare() is far more defensible: wild "
+                   "type and a point mutant differ by one residue, so "
+                   "everything that would confound an absolute prediction "
+                   "cancels."),
+    }
+    dropped = len(seq) - len(known)
+    if dropped:
+        result["unscored_residues"] = dropped
+        result["factors"]["length"] = len(known)
+        result["note"] = (f"{dropped} residue(s) (X/B/Z/U or similar) have no "
+                          f"value on these scales and were excluded. Every "
+                          f"number above is for the remaining {len(known)}.")
+    return result
+
+
+def compare(wild_type: str, mutant: str, *, host: Optional[str] = None,
+            ph: float = DEFAULT_PH) -> Dict[str, Any]:
+    """How one substitution moves each risk factor.
+
+    The defensible mode. Same protein, one residue changed, so fold, length,
+    host and composition all cancel — what is left is attributable to the
+    substitution.
+    """
+    wt = _known(_clean(wild_type))
+    mu = _known(_clean(mutant))
+    if len(wt) < MIN_LEN or len(mu) < MIN_LEN:
+        return {"ok": False, "kind": "too_short",
+                "error": f"Both sequences need at least {MIN_LEN} scored "
+                         f"residues."}
+    if len(wt) != len(mu):
+        return {"ok": False, "kind": "length_mismatch",
+                "error": (f"Wild type is {len(wt)} residues and the mutant is "
+                          f"{len(mu)}. This compares point substitutions; an "
+                          f"indel changes the numbering and the two are no "
+                          f"longer position-comparable."),
+                "next": "Use compare_sequences to align them first."}
+
+    changes = [{"position": i + 1, "from": a, "to": b}
+               for i, (a, b) in enumerate(zip(wt, mu)) if a != b]
+    if not changes:
+        return {"ok": False, "kind": "identical",
+                "error": "The two sequences are identical."}
+
+    raw_w, raw_m = _metrics(wt, ph), _metrics(mu, ph)
+    fw, fm = _round(raw_w), _round(raw_m)
+    # Subtract BEFORE rounding — see _metrics.
+    deltas = {k: round(raw_m[k] - raw_w[k], 3)
+              for k in ("gravy", "isoelectric_point", "net_charge_at_ph",
+                        "instability_index", "aromaticity", "cysteines",
+                        "longest_patch")}
+
+    # The most actionable single fact: did the change land in a greasy region
+    # that was already a risk?
+    in_patch = []
+    for c in changes:
+        for p in fw["hydrophobic_patches"]:
+            if p["start"] <= c["position"] <= p["end"]:
+                in_patch.append({"position": c["position"],
+                                 "patch": f"{p['start']}-{p['end']}"})
+                break
+
+    notes: List[str] = []
+    if deltas["gravy"] > 0 and in_patch:
+        notes.append("Adds hydrophobicity inside a patch that was already "
+                     "hydrophobic — the change compounds an existing risk "
+                     "rather than creating a new one.")
+    elif deltas["gravy"] > 0:
+        notes.append("Makes the protein more hydrophobic overall.")
+    elif deltas["gravy"] < 0:
+        notes.append("Makes the protein less hydrophobic overall.")
+    if deltas["cysteines"] > 0:
+        notes.append(f"Introduces {deltas['cysteines']} cysteine(s) — a new "
+                     f"free thiol can form the wrong disulfide, and in a "
+                     f"reducing cytoplasm it will not form the right one.")
+    elif deltas["cysteines"] < 0:
+        notes.append(f"Removes {abs(deltas['cysteines'])} cysteine(s). If it "
+                     f"was half of a structural disulfide, the partner is now "
+                     f"unpaired too.")
+    if abs(deltas["net_charge_at_ph"]) >= 1:
+        notes.append(f"Changes net charge at pH {ph} by "
+                     f"{deltas['net_charge_at_ph']:+.2f}, which changes the "
+                     f"electrostatic repulsion between molecules.")
+    if abs(fm["isoelectric_point"] - ph) < PI_DANGER_WINDOW <= abs(
+            fw["isoelectric_point"] - ph):
+        notes.append(f"Moves the pI to {fm['isoelectric_point']}, close to the "
+                     f"working pH — near-zero net charge is where aggregation "
+                     f"is easiest.")
+
+    return {
+        "ok": True,
+        "changes": changes,
+        "wild_type": fw,
+        "mutant": fm,
+        "deltas": deltas,
+        "in_existing_hydrophobic_patch": in_patch,
+        "notes": notes,
+        "summary": (f"{len(changes)} substitution(s) · "
+                    + (" ".join(notes) if notes
+                       else "no material change to any computed risk factor.")),
+        "no_score": ("These are DIFFERENCES in computed physical properties, "
+                     "not a predicted change in solubility. They say what the "
+                     "substitution does to the molecule, not what the "
+                     "experiment will yield."),
+        "why_this_is_more_trustworthy": (
+            "Wild type and mutant differ by one residue, so fold, length, "
+            "host and composition cancel. Absolute solubility predictions "
+            "carry all of those as error; a delta does not."),
+    }
+
+
+def _summary(f: Dict[str, Any], flags: List[Dict[str, str]]) -> str:
+    bits = [f"{f['length']} aa", f"GRAVY {f['gravy']}",
+            f"pI {f['isoelectric_point']}"]
+    if f["longest_patch"]:
+        bits.append(f"longest hydrophobic patch {f['longest_patch']} aa")
+    if flags:
+        bits.append(f"{len(flags)} risk factor(s): "
+                    + ", ".join(x["factor"] for x in flags))
+    else:
+        bits.append("no flagged risk factors")
+    return " · ".join(bits)

dee/core/vectors.py

@@ -96,6 +96,25 @@ def search(query: str, limit: int = 8) -> List[Dict[str, Any]]:
     return hits[:limit]
 
 
+def addgene_url(entry: Optional[Dict[str, Any]]) -> Optional[str]:
+    """Canonical Addgene page for a catalogue entry, or None.
+
+    Computed here rather than left to the model. The stored ids carry a lot
+    suffix ("69864-3"); the plasmid page is keyed on the number alone, so an
+    agent assembling the URL from the raw string produces a 404 and a user who
+    concludes the vector does not exist.
+
+    This is the honest half of audit #6. Addgene publishes no API — the search
+    endpoint is HTML — so the engine links to the record it already knows
+    rather than scraping a page and presenting the result as retrieved data.
+    """
+    if not entry:
+        return None
+    raw = str(entry.get("addgene") or "").strip()
+    m = re.match(r"^(\d+)", raw)
+    return f"https://www.addgene.org/{m.group(1)}/" if m else None
+
+
 def catalogue_size() -> int:
     return len(_load())
 

tests/test_confirm_gate.py

@@ -330,6 +330,25 @@ _UNGATED = {
     "check_synthesis", "assess_stability",
     # Pure local computation on two sequences the caller already holds.
     "compare_sequences",
+    # Arithmetic on a sequence the caller supplied. Proposes primers; ordering
+    # them is the user's action, in their vendor's cart, not ours.
+    "design_mutagenesis_primers",
+    # Arithmetic on four-base strings the caller supplied.
+    "check_overhangs",
+    # Reads a public curated database. Only the accession leaves the Space.
+    "check_residues",
+    # Pure counting over sequences the caller supplied.
+    "check_conservation",
+    # String matching against bundled catalogues. Its whole purpose is to
+    # answer "what is this?" WITHOUT the transmission that blast_sequence
+    # needs, so gating it would tax the private path and leave the
+    # transmitting one comparatively cheap.
+    "identify_sequence",
+    # Reads a public curated database. Only the accession leaves the Space.
+    "map_domains",
+    # Physical chemistry and codon arithmetic on sequences the caller already
+    # holds. Nothing transmitted, nothing stored.
+    "assess_solubility", "assess_expression",
 }
 
 

tests/test_conservation.py

@@ -0,0 +1,124 @@
+"""Audit #17 + #18: multiple alignment, and conservation counted from it.
+
+ESM-2 gives a learned opinion about whether a substitution looks plausible.
+Conservation across real homologs gives an OBSERVED fact: in 40 orthologs this
+position is serine 40 times. They fail differently — the model is weakest
+exactly where the audit says (membrane, disordered, multi-domain) and a
+frequency count is unaffected by any of that.
+
+The tests that matter are about the INPUT, not the algorithm. Conservation is
+only as meaningful as the homolog set, and a set of near-identical sequences
+makes every column look invariant. A tool that reports that as "conserved"
+without comment is worse than no tool.
+"""
+import pytest
+
+from dee.core import agent_tools as t
+from dee.core import conservation as C
+from dee.core import orchestrator as orch
+
+# Position 1,3,4,5,6 invariant; position 2 varies across all five.
+HOMOLOGS = ["MAKQWLTVEG", "MSKQWLTVEG", "MTKQWLSVEG", "MAKQWLTVDG", "MGKQWLTIEG"]
+
+
+def test_an_invariant_column_is_found_and_a_variable_one_is_not():
+    r = C.score(HOMOLOGS)
+    by_pos = {c["anchor_position"]: c for c in r["conservation"]}
+    assert by_pos[5]["call"] == "invariant" and by_pos[5]["agreement_pct"] == 100.0
+    assert by_pos[2]["call"] == "variable" and by_pos[2]["agreement_pct"] < 60
+
+
+def test_entropy_is_never_reported_as_negative_zero():
+    """-sum(...) over an all-agreeing column yields IEEE -0.0, which prints as
+    '-0.0 bits' and reads like a bug in a number users are asked to trust."""
+    r = C.score(HOMOLOGS)
+    for c in r["conservation"]:
+        assert c["entropy_bits"] >= 0.0
+        assert str(c["entropy_bits"]) != "-0.0"
+
+
+def test_a_redundant_homolog_set_is_flagged_and_marked_untrustworthy():
+    """The failure that would make this tool actively misleading. Forty
+    sequences at 99% identity are ONE sequence counted forty times, and every
+    column will look invariant."""
+    r = C.score(["MAKQWLTVEG"] * 4 + ["MAKQWLTVEA"])
+    assert r["trustworthy"] is False
+    assert r["diversity_warning"] and "redundancy" in r["diversity_warning"]
+    assert "more divergent" in r["diversity_warning"]
+
+
+def test_a_diverse_set_is_trusted():
+    """A checker that never trusts anything is a checker nobody reads."""
+    r = C.score(HOMOLOGS)
+    assert r["trustworthy"] is True and r["diversity_warning"] is None
+
+
+def test_too_few_sequences_is_refused_with_a_way_forward():
+    r = C.score(["MAKQ", "MSKQ"])
+    assert r["ok"] is False and r["kind"] == "too_few"
+    assert "BLAST" in r["next"]
+
+
+def test_positions_are_numbered_along_the_anchor_the_user_designs_against():
+    r = C.score(HOMOLOGS, positions=[5])
+    assert [(c["anchor_position"], c["anchor_residue"]) for c in r["conservation"]] \
+        == [(5, "W")]
+
+
+def test_indels_do_not_shift_the_anchor_numbering():
+    """A homolog with a deletion must not renumber the sequence the user is
+    designing against — that is how a conservation call lands on the wrong
+    residue."""
+    r = C.score(["MAKQWLTVEG", "MAKWLTVEG", "MAKQWLTVEG"])
+    positions = [c["anchor_position"] for c in r["conservation"]
+                 if c["anchor_position"]]
+    assert positions == sorted(positions)
+    assert max(positions) == 10          # anchor length, unchanged by the gap
+
+
+def test_the_alignment_says_it_is_approximate():
+    """Progressive alignment is not a simultaneous optimum. Every practical
+    tool approximates; pretending otherwise is the dishonest part."""
+    m = C.align_many(HOMOLOGS)
+    assert m["ok"] and "Approximate" in m["method"]
+    assert all(len(r["aligned"]) == m["columns"] for r in m["rows"])
+
+
+def test_the_anchor_is_the_longest_sequence():
+    m = C.align_many(["MAK", "MAKQWLTVEG", "MAKQ"], ["a", "b", "c"])
+    assert m["anchor"] == "b"
+
+
+def test_it_positions_itself_against_esm2_rather_than_as_a_confirmation():
+    """Two independent signals. Averaging them would destroy the only thing
+    that makes having both worthwhile."""
+    r = C.score(HOMOLOGS)
+    assert "complements ESM-2" in r["caveat"]
+    assert "disagreement is worth investigating" in r["caveat"]
+
+
+def test_conservation_is_framed_as_an_observation_not_a_property():
+    r = C.score(HOMOLOGS)
+    assert "OBSERVATION" in r["caveat"]
+    assert "not a property of the protein" in r["caveat"]
+
+
+def test_it_is_reachable_ungated_and_specced():
+    assert "check_conservation" in t._TOOLS
+    assert any(s["function"]["name"] == "check_conservation" for s in orch.TOOL_SPECS)
+    assert orch._requires_confirm("check_conservation") is False
+
+
+def test_the_summary_leads_with_untrustworthiness_when_it_applies():
+    r = t.execute_tool("check_conservation",
+                       {"sequences": ["MAKQWLTVEG"] * 4 + ["MAKQWLTVEA"]},
+                       auth_anonymous=True)
+    assert "too redundant to trust" in orch._summarize("check_conservation", r)
+
+
+def test_the_spec_makes_the_agent_relay_both_limits():
+    d = next(s["function"]["description"] for s in orch.TOOL_SPECS
+             if s["function"]["name"] == "check_conservation")
+    assert "approximate" in d
+    assert "diversity_warning" in d and "trustworthy" in d
+    assert "complements ESM-2" in d

tests/test_domains.py

@@ -0,0 +1,251 @@
+"""Tests for InterPro domain architecture (audit #8).
+
+Fixtures are trimmed from a real InterPro response for P01308 (insulin) — the
+14-row / 5-entry case that motivated grouping, and the discontinuous entry that
+motivated keeping segments. No test here touches the network.
+"""
+import pytest
+
+from dee.core import domains as D
+
+
+def _row(db, acc, typ, integrated, frags, name=None, length=110):
+    return {
+        "metadata": {"accession": acc, "name": name or acc,
+                     "source_database": db, "type": typ,
+                     "integrated": integrated},
+        "proteins": [{
+            "accession": "p01308", "protein_length": length,
+            "entry_protein_locations": [
+                {"fragments": [{"start": s, "end": e, "dc-status": "CONTINUOUS"}
+                               for s, e in frags]}],
+        }],
+    }
+
+
+# Real shape: five integrated entries described by fourteen rows, one of them
+# discontinuous, plus one signature InterPro has not integrated.
+INSULIN = [
+    _row("cdd", "cd04367", "domain", "IPR004825", [(26, 110)]),
+    _row("cathgene3d", "G3DSA:1.10.100.10", "homologous_superfamily", None, [(25, 110)]),
+    _row("interpro", "IPR004825", "family", None, [(1, 110)], "Insulin"),
+    _row("interpro", "IPR016179", "domain", None, [(28, 109)], "Insulin-like"),
+    _row("interpro", "IPR022352", "family", None, [(29, 45), (90, 109)],
+         "Insulin/IGF/relaxin"),
+    _row("interpro", "IPR022353", "conserved_site", None, [(95, 109)],
+         "Insulin, conserved site"),
+    _row("interpro", "IPR036438", "homologous_superfamily", None, [(10, 109)],
+         "Insulin-like superfamily"),
+    _row("pfam", "PF00049", "domain", "IPR016179", [(28, 109)]),
+    _row("prints", "PR00276", "family", "IPR022352", [(29, 45), (90, 109)]),
+    _row("prints", "PR00277", "family", "IPR004825", [(25, 36), (101, 110)]),
+    _row("prosite", "PS00262", "conserved_site", "IPR022353", [(95, 109)]),
+    _row("panther", "PTHR11454", "family", "IPR004825", [(1, 110)]),
+    _row("smart", "SM00078", "domain", "IPR016179", [(28, 109)]),
+    _row("ssf", "SSF56994", "homologous_superfamily", "IPR036438", [(10, 109)]),
+]
+
+
+@pytest.fixture
+def insulin(monkeypatch):
+    monkeypatch.setattr(D, "_get",
+                        lambda *a, **k: {"results": INSULIN, "next": None})
+
+
+# ── the grouping that keeps the answer honest ────────────────────────────
+def test_fourteen_signature_rows_become_five_entries(insulin):
+    """Member databases model the same region independently and each adds a
+    row. Reporting all fourteen would inflate one domain call into a wall of
+    apparent corroboration."""
+    r = D.domains("P01308")
+    assert r["signature_rows"] == 14
+    assert len(r["entries"]) == 5
+
+
+def test_member_databases_are_reported_as_support_not_as_findings(insulin):
+    r = D.domains("P01308")
+    like = [e for e in r["entries"] if e["interpro"] == "IPR016179"][0]
+    assert like["supported_by"] == ["pfam", "smart"]
+    assert {s["accession"] for s in like["signatures"]} == {"PF00049", "SM00078"}
+
+
+def test_agreement_is_not_described_as_independent_observations(insulin):
+    """They share training data and often the same seed alignments. Letting a
+    count imply independence would overstate the evidence."""
+    note = D.domains("P01308")["evidence_note"]
+    assert "not as N independent observations" in note
+
+
+def test_an_unintegrated_signature_is_kept_but_separate(insulin):
+    r = D.domains("P01308")
+    assert [u["accession"] for u in r["unintegrated"]] == ["G3DSA:1.10.100.10"]
+    assert all(e["interpro"].startswith("IPR") for e in r["entries"])
+
+
+# ── the two things that silently give wrong answers ──────────────────────
+def test_a_discontinuous_entry_keeps_its_segments(insulin):
+    """IPR022352 is 29-45 AND 90-109. Collapsing to 29-109 would silently
+    claim 44 residues that are not in it."""
+    r = D.domains("P01308")
+    e = [x for x in r["entries"] if x["interpro"] == "IPR022352"][0]
+    assert e["discontinuous"] is True
+    assert e["segments"] == [{"start": 29, "end": 45}, {"start": 90, "end": 109}]
+    assert e["residues"] == (45 - 29 + 1) + (109 - 90 + 1)
+
+
+def test_precursor_numbering_is_always_stated(insulin):
+    n = D.domains("P01308")["numbering"]
+    assert "precursor" in n and "110 aa" in n
+    assert "signal peptide" in n
+
+
+def test_absence_of_a_signature_is_not_absence_of_a_domain(monkeypatch):
+    monkeypatch.setattr(D, "_get", lambda *a, **k: {"results": [], "next": None})
+    r = D.domains("Q00000")
+    assert r["ok"] and r["entries"] == []
+    assert "expected" in r["summary"]
+    assert "NOT evidence" in r["caveat"]
+
+
+# ── architecture and position mapping ────────────────────────────────────
+def test_architecture_holds_only_boundary_types(insulin):
+    """Families classify the whole protein and superfamilies overshoot the
+    domain — neither gives a usable region."""
+    arch = D.domains("P01308")["architecture"]
+    assert [a["interpro"] for a in arch] == ["IPR016179"]
+
+
+def test_architecture_reads_n_to_c_not_in_response_order(monkeypatch):
+    """InterPro returns entries in its own order. An architecture listed out
+    of sequence order is not an architecture."""
+    rows = [
+        _row("interpro", "IPR000C", "domain", None, [(319, 357)], "tetramerisation", 393),
+        _row("interpro", "IPR000A", "domain", None, [(6, 30)], "transactivation", 393),
+        _row("interpro", "IPR000B", "domain", None, [(100, 288)], "DNA-binding", 393),
+        _row("interpro", "IPR000F", "family", None, [(3, 369)], "p53 family", 393),
+    ]
+    monkeypatch.setattr(D, "_get", lambda *a, **k: {"results": rows, "next": None})
+    r = D.domains("P04637")
+    assert [a["name"] for a in r["architecture"]] == [
+        "transactivation", "DNA-binding", "tetramerisation"]
+    # And the family, which spans nearly everything, is not offered as a region.
+    assert "p53 family" not in [a["name"] for a in r["architecture"]]
+    assert "transactivation (6–30)" in r["summary"]
+
+
+def test_a_position_inside_a_domain_is_called_that_way(insulin):
+    r = D.domains("P01308", positions=["F49L"])
+    assert r["positions"][0]["position"] == 49
+    assert "Insulin-like" in r["positions"][0]["note"]
+    assert "not a linker" in r["positions"][0]["note"]
+
+
+def test_a_position_covered_only_by_a_family_is_not_called_a_domain(insulin):
+    """Position 24 sits in the family and superfamily spans but in no domain.
+    Saying "in the insulin family" is true; saying "in a domain" is not."""
+    note = D.domains("P01308", positions=[24])["positions"][0]["note"]
+    assert "not inside a specific annotated domain" in note
+
+
+def test_a_position_past_the_end_is_flagged_rather_than_answered(insulin):
+    """The commonest cause is mature-vs-precursor numbering, so a silent 'no
+    domain here' would confirm the user's mistake."""
+    note = D.domains("P01308", positions=[900])["positions"][0]["note"]
+    assert "past the end" in note
+
+
+def test_substitution_labels_and_bare_integers_both_work(insulin):
+    a = D.domains("P01308", positions=["A24T"])["positions"][0]
+    b = D.domains("P01308", positions=[24])["positions"][0]
+    assert a["position"] == b["position"] == 24
+
+
+# ── failure modes ────────────────────────────────────────────────────────
+def test_unreachable_interpro_is_not_reported_as_no_domains(monkeypatch):
+    monkeypatch.setattr(D, "_get", lambda *a, **k: None)
+    r = D.domains("P01308")
+    assert r["ok"] is False and r["kind"] == "unreachable"
+
+
+def test_a_partial_walk_is_marked_truncated(monkeypatch):
+    """A page failing mid-walk yields a partial architecture, and a partial
+    architecture presented as complete is how a domain goes missing."""
+    calls = {"n": 0}
+
+    def flaky(url, **kw):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return {"results": INSULIN, "next": "https://example.invalid/page2"}
+        return None
+
+    monkeypatch.setattr(D, "_get", flaky)
+    r = D.domains("P01308")
+    assert r["ok"] and r["truncated"] is True
+    assert r["summary"].startswith("PARTIAL")
+    assert "INCOMPLETE" in r["caveat"]
+
+
+def test_paging_stops_at_the_bound(monkeypatch):
+    """An unbounded follow loop hangs a request thread on someone else's
+    pagination."""
+    seen = []
+
+    def endless(url, **kw):
+        seen.append(url)
+        return {"results": [], "next": "https://example.invalid/next"}
+
+    monkeypatch.setattr(D, "_get", endless)
+    D.domains("P01308")
+    assert len(seen) == D.MAX_PAGES
+
+
+def test_a_missing_accession_explains_why_a_raw_sequence_will_not_do(monkeypatch):
+    r = D.domains("")
+    assert r["ok"] is False
+    assert "InterProScan" in r["next"]
+
+
+def test_only_the_accession_leaves_the_space(monkeypatch):
+    """The engine's standing rule: nothing but an identifier goes out. The
+    positions the user cares about are matched locally against the response,
+    so even those are never transmitted."""
+    seen = []
+    monkeypatch.setattr(D, "_get",
+                        lambda url, **k: seen.append(url) or {"results": INSULIN,
+                                                              "next": None})
+    D.domains("P01308", positions=[24, 49])
+    assert seen == [f"{D._API}/P01308/?page_size={D.PAGE_SIZE}"]
+
+
+def test_malformed_fragments_are_skipped_not_crashed(monkeypatch):
+    bad = [_row("interpro", "IPR000001", "domain", None, [], "Broken")]
+    bad[0]["proteins"][0]["entry_protein_locations"] = [
+        {"fragments": [{"start": None, "end": 10}, {"start": 50, "end": 20},
+                       {"start": 5, "end": 9}]}]
+    monkeypatch.setattr(D, "_get", lambda *a, **k: {"results": bad, "next": None})
+    r = D.domains("P01308")
+    assert r["ok"]
+    assert r["entries"][0]["segments"] == [{"start": 5, "end": 9}]
+
+
+# ── the agent tool ───────────────────────────────────────────────────────
+def test_the_agent_tool_is_registered(insulin):
+    from dee.core import agent_tools as t
+    assert "map_domains" in t._TOOLS
+    out = t._TOOLS["map_domains"]["fn"]({"accession": "P01308",
+                                         "positions": "F49L, 24"})
+    assert out["ok"] and len(out["positions"]) == 2
+
+
+def test_the_tool_refuses_a_missing_accession():
+    from dee.core import agent_tools as t
+    assert t._TOOLS["map_domains"]["fn"]({})["ok"] is False
+
+
+def test_the_spec_warns_about_numbering_and_discontinuity():
+    from dee.core import agent_tools as t
+    desc = [s for s in t.TOOL_SPECS
+            if s["function"]["name"] == "map_domains"][0]["function"]["description"]
+    assert "PRECURSOR" in desc
+    assert "DISCONTINUOUS" in desc
+    assert "design_variant_library" in desc

tests/test_expression.py

@@ -0,0 +1,189 @@
+"""Tests for sequence-visible expression risk (audit #24).
+
+Two things are actually being defended here: that no yield is ever predicted,
+and that the rare-codon threshold is derived from the tables rather than
+chosen — the second is what makes the first honest rather than merely cautious.
+"""
+import pytest
+
+from dee.core import expression as E
+
+ADAPTED = "ATG" + "AAACTGGCGCGTGAAGATCTGAAAGCGGTTCTGGAAAAC" * 3 + "TAA"
+RARE_HEAVY = "ATG" + "AAACTGGCGAGAAGGATAGATCTGAAAGCGGTTCTGGAAAAC" * 3 + "TAA"
+
+
+# ── the honesty contract ─────────────────────────────────────────────────
+def test_no_expression_level_is_ever_predicted():
+    r = E.assess(ADAPTED, "e_coli")
+    assert r["ok"]
+    assert "does NOT predict an expression level" in r["no_yield"]
+    for key in ("yield", "expression_level", "mg_per_l", "predicted_yield",
+                "expression_score"):
+        assert key not in r
+
+
+def test_the_result_names_what_it_does_not_cover():
+    """An assessment that looks complete is worse than one that lists its own
+    blind spots — the user assumes the unchecked thing was checked."""
+    n = E.assess(ADAPTED, "e_coli")["not_covered"]
+    assert "Shine-Dalgarno" in n
+    assert "#38" in n and "#39" in n
+    assert "assess_solubility" in n
+
+
+# ── the threshold is derived, and the derivation is checkable ────────────
+def test_the_rare_cutoff_selects_the_codons_rosetta_strains_supply():
+    """w < 0.15 against the E. coli table selects AGA, AGG, ATA, CTA — exactly
+    the set argU/ileY/leuW exist to supply. That is the evidence the cutoff is
+    measuring something real rather than being a round number."""
+    selected = set(E.assess(ADAPTED, "e_coli")["rare_codons_in_this_host"])
+    assert {"AGA", "AGG", "ATA", "CTA"} <= selected
+
+
+def test_the_same_cutoff_finds_nothing_rare_in_human_and_says_so():
+    """Mammalian codon usage is much flatter. Manufacturing a warning to look
+    thorough would be worse than the empty result."""
+    r = E.assess(ADAPTED, "human")
+    assert r["rare_codons_in_this_host"] == []
+    assert r["rare_codon_count"] == 0
+    assert "nothing" in r["method"]
+
+
+def test_the_method_line_lists_the_selected_codons():
+    m = E.assess(ADAPTED, "e_coli")["method"]
+    assert "Sharp & Li" in m
+    assert str(E.RARE_BELOW) in m
+    assert "AGA" in m
+
+
+# ── rare codons and the runs that matter ─────────────────────────────────
+def test_an_adapted_sequence_is_clean():
+    r = E.assess(ADAPTED, "e_coli")
+    assert r["rare_codon_count"] == 0
+    assert r["flags"] == []
+    assert r["codon_adaptation_index"] > 0.9
+
+
+def test_rare_codons_lower_the_adaptation_index():
+    assert (E.assess(RARE_HEAVY, "e_coli")["codon_adaptation_index"]
+            < E.assess(ADAPTED, "e_coli")["codon_adaptation_index"])
+
+
+def test_consecutive_rare_codons_are_reported_as_a_run():
+    """The finding that changes what someone does. A scattered rare codon is
+    absorbed; three in a row depletes the local charged-tRNA pool."""
+    r = E.assess(RARE_HEAVY, "e_coli")
+    assert r["rare_codon_runs"]
+    run = r["rare_codon_runs"][0]
+    assert run["length"] >= E.RUN_LENGTH
+    assert run["codons"] == ["AGA", "AGG", "ATA"]
+    flag = [f for f in r["flags"] if "consecutive rare" in f["factor"]][0]
+    assert "recoding just this run" in flag["why"]
+
+
+def test_scattered_rare_codons_do_not_form_a_run():
+    dna = "ATG" + ("AGA" + "CTGGCGAAAGATCTGGAA") * 6 + "TAA"
+    r = E.assess(dna, "e_coli")
+    assert r["rare_codon_count"] >= 6
+    assert r["rare_codon_runs"] == []
+
+
+def test_the_five_prime_ramp_is_reported_separately():
+    """A rare codon at codon 5 costs more than the same codon at codon 400."""
+    r = E.assess(RARE_HEAVY, "e_coli")
+    assert r["rare_in_ramp"]
+    assert all(x["codon_number"] <= E.RAMP_CODONS for x in r["rare_in_ramp"])
+
+
+def test_cai_excludes_single_codon_families():
+    """Met and Trp have no synonym to choose between. Including them only
+    drags every score toward 1 and makes a bad sequence look adapted."""
+    only_mw = "ATG" + "ATGTGG" * 20 + "TAA"
+    r = E.assess(only_mw, "e_coli")
+    assert r["codon_adaptation_index"] is None or r["codon_adaptation_index"] > 0
+
+
+def test_cai_does_not_underflow_on_a_long_cds():
+    """The direct product of hundreds of fractions underflows to 0.0 and
+    silently reports a perfectly adapted gene as unadapted."""
+    long_cds = "ATG" + "AAACTGGCGCGTGAAGATCTGAAAGCGGTTCTGGAAAAC" * 60 + "TAA"
+    cai = E.assess(long_cds, "e_coli")["codon_adaptation_index"]
+    assert cai is not None and cai > 0.5
+
+
+# ── reading frame ────────────────────────────────────────────────────────
+def test_an_internal_stop_is_flagged_as_a_truncated_product():
+    dna = "ATG" + "AAACTGGCG" * 4 + "TAA" + "AAACTGGCG" * 6 + "TAA"
+    r = E.assess(dna, "e_coli")
+    assert r["internal_stops"]
+    flag = [f for f in r["flags"] if "internal stop" in f["factor"]][0]
+    assert "truncated" in flag["why"]
+
+
+def test_a_missing_terminal_stop_is_flagged():
+    r = E.assess(ADAPTED[:-3], "e_coli")
+    assert r["has_terminal_stop"] is False
+    assert any("no terminal stop" in f["factor"] for f in r["flags"])
+
+
+def test_an_out_of_frame_length_is_flagged_not_silently_truncated():
+    r = E.assess(ADAPTED + "AT", "e_coli")
+    assert r["in_frame"] is False
+    assert any("whole number of codons" in f["factor"] for f in r["flags"])
+
+
+# ── hosts ────────────────────────────────────────────────────────────────
+def test_an_unknown_host_declines_instead_of_using_another_table():
+    """Scoring a plant construct against the E. coli table would produce
+    confident nonsense. The refusal must read as missing data, not as the
+    organism being unsupported."""
+    r = E.assess(ADAPTED, "plant")
+    assert r["ok"] is False and r["kind"] == "no_codon_table"
+    assert "missing data file, not an unsupported organism" in r["next"]
+
+
+def test_a_missing_host_is_refused_because_expression_is_host_specific():
+    assert E.assess(ADAPTED, "")["ok"] is False
+
+
+def test_every_known_host_alias_works():
+    for host in ("e_coli", "ecoli", "yeast", "s_cerevisiae", "human", "h_sapiens"):
+        assert E.assess(ADAPTED, host)["ok"], host
+
+
+def test_the_same_sequence_scores_differently_per_host():
+    """The point of asking for a host. E. coli-optimised DNA is not
+    human-optimised."""
+    a = E.assess(ADAPTED, "e_coli")["codon_adaptation_index"]
+    b = E.assess(ADAPTED, "human")["codon_adaptation_index"]
+    assert a != b
+
+
+def test_too_short_is_refused():
+    assert E.assess("ATGAAACTG", "e_coli")["kind"] == "too_short"
+
+
+# ── the agent tool ───────────────────────────────────────────────────────
+def test_the_tool_runs_and_needs_a_host():
+    from dee.core import agent_tools as t
+    fn = t._TOOLS["assess_expression"]["fn"]
+    assert fn({"dna": ADAPTED, "host": "e_coli"})["ok"]
+    assert fn({"host": "e_coli"})["ok"] is False
+
+
+def test_the_tool_explains_that_protein_input_cannot_answer_this():
+    from dee.core import agent_tools as t
+    err = t._TOOLS["assess_expression"]["fn"]({"host": "e_coli"})["error"]
+    assert "reverse-translate" in err
+
+
+def test_the_spec_forbids_substituting_another_hosts_table():
+    from dee.core import agent_tools as t
+    desc = next(s for s in t.TOOL_SPECS
+                if s["function"]["name"] == "assess_expression")["function"]["description"]
+    assert "never substitute another host's table" in desc
+    assert "no_yield" in desc
+    # No enum on host — a hardcoded organism list is the hardest gate to see.
+    props = next(s for s in t.TOOL_SPECS
+                 if s["function"]["name"] == "assess_expression")["function"]["parameters"]["properties"]
+    assert "enum" not in props["host"]

tests/test_features.py

@@ -0,0 +1,134 @@
+"""Audit #7: the residues you should not mutate, from the people who curated them.
+
+ESM-2 scores how UNUSUAL a residue is, not how load-bearing it is. A catalytic
+serine is often unremarkable in sequence terms — it is the geometry that
+matters, and a sequence model does not see geometry. So the engine will rank a
+substitution at the active site as promising, and the cheapest fix is not a
+better model but asking UniProt.
+
+Network is stubbed throughout: a test that depends on a live public API is a
+test that fails on Tuesdays and teaches everyone to ignore it.
+"""
+import json
+
+import pytest
+
+from dee.core import agent_tools as t
+from dee.core import features as F
+from dee.core import orchestrator as orch
+
+ENTRY = {
+    "primaryAccession": "P00760",
+    "proteinDescription": {"recommendedName": {"fullName": {"value": "Serine protease 1"}}},
+    "sequence": {"length": 246},
+    "features": [
+        {"type": "Active site", "location": {"start": {"value": 63}, "end": {"value": 63}},
+         "description": "Charge relay system",
+         "evidences": [{"evidenceCode": "ECO:0000255"}]},
+        {"type": "Disulfide bond", "location": {"start": {"value": 30}, "end": {"value": 46}}},
+        {"type": "Domain", "location": {"start": {"value": 20}, "end": {"value": 240}},
+         "description": "Peptidase S1"},
+        # Not a reason to avoid a position — must be filtered out.
+        {"type": "Sequence conflict", "location": {"start": {"value": 100}, "end": {"value": 100}}},
+        # Malformed span: must be skipped, not crash.
+        {"type": "Active site", "location": {"start": {"value": None}, "end": {"value": None}}},
+    ],
+}
+
+
+@pytest.fixture(autouse=True)
+def _no_network(monkeypatch):
+    monkeypatch.setattr(F, "_get", lambda *a, **k: ENTRY)
+
+
+def test_functional_features_are_kept_and_record_noise_is_dropped():
+    """Sequence conflicts and variants describe the RECORD, not a reason to
+    avoid a position. Including them would bury the signal."""
+    r = F.fetch("P00760")
+    kinds = {f["type"] for f in r["features"]}
+    assert "Active site" in kinds and "Disulfide bond" in kinds
+    assert "Sequence conflict" not in kinds
+
+
+def test_a_malformed_span_is_skipped_not_crashed():
+    r = F.fetch("P00760")
+    assert r["ok"] and all(f["start"] is not None for f in r["features"])
+
+
+def test_a_position_on_an_active_site_says_avoid():
+    a = F.annotate("P00760", ["S63A"])
+    h = a["positions"][0]
+    assert h["critical"] and h["verdict"].startswith("AVOID")
+    assert "catalytic" in h["critical"][0]["means"]
+
+
+def test_an_unannotated_position_is_never_called_safe():
+    """The failure that would make this tool harmful. Most proteins are
+    annotated sparsely; 'no annotation' is absence of knowledge."""
+    a = F.annotate("P00760", [200])
+    assert a["positions"][0]["critical"] == []
+    assert "safe" not in a["positions"][0]["verdict"].lower()
+    assert "absence of KNOWLEDGE" in a["caveat"]
+
+
+def test_the_precursor_numbering_trap_is_stated():
+    """UniProt numbers the FULL precursor. Bovine trypsin's triad is at
+    63/107/200 there, not the classic His57/Asp102/Ser195, because the signal
+    peptide and propeptide are counted. A user in mature numbering gets a
+    confident flag on the wrong residue — worse than no flag."""
+    a = F.annotate("P00760", [63])
+    assert "precursor" in a["numbering"]
+    assert "246" in a["numbering"]           # the real length, not a guess
+    assert "offset" in a["numbering"]
+
+
+def test_substitution_labels_are_accepted_because_that_is_what_the_engine_speaks():
+    a = F.annotate("P00760", ["R63H", 63, "63"])
+    assert [h["position"] for h in a["positions"]] == [63, 63, 63]
+
+
+def test_uniprot_evidence_codes_travel_with_the_claim():
+    """ECO:0000269 is experimental; ECO:0000250 is inferred by similarity. A
+    designer should weight those differently, so the code is not discarded."""
+    r = F.fetch("P00760")
+    act = next(f for f in r["features"] if f["type"] == "Active site")
+    assert act["evidence"] == ["ECO:0000255"]
+
+
+def test_domains_are_context_not_a_veto():
+    """Being inside a domain is not a reason to avoid a residue — almost every
+    residue is. Only the critical tier vetoes."""
+    a = F.annotate("P00760", [200])
+    assert any(c["type"] == "Domain" for c in a["positions"][0]["context"])
+    assert a["positions"][0]["critical"] == []
+
+
+def test_an_unreachable_uniprot_is_not_reported_as_no_features(monkeypatch):
+    """"Couldn't ask" and "nothing known" must not look the same — one means
+    retry, the other means proceed with care."""
+    monkeypatch.setattr(F, "_get", lambda *a, **k: None)
+    r = F.fetch("P00760")
+    assert r["ok"] is False and r["kind"] == "unreachable"
+
+
+def test_it_is_reachable_ungated_and_specced():
+    assert "check_residues" in t._TOOLS
+    assert any(s["function"]["name"] == "check_residues" for s in orch.TOOL_SPECS)
+    assert orch._requires_confirm("check_residues") is False
+
+
+def test_the_spec_makes_the_agent_relay_both_warnings():
+    d = next(s["function"]["description"] for s in orch.TOOL_SPECS
+             if s["function"]["name"] == "check_residues")
+    assert "PRECURSOR" in d
+    assert "does NOT mean safe" in d
+    assert "BEFORE recommending" in d
+
+
+def test_no_sequence_is_ever_sent(monkeypatch):
+    """Standing rule: only (accession) leaves the Space."""
+    seen = []
+    monkeypatch.setattr(F, "_get", lambda url, **k: seen.append(url) or ENTRY)
+    F.annotate("P00760", ["R63H"])
+    assert seen and all("P00760" in u for u in seen)
+    assert not any(len(u) > 200 for u in seen), "a sequence would blow the URL up"

tests/test_identify_sequence.py

@@ -0,0 +1,206 @@
+"""Tests for local sequence identification (audit #5).
+
+The interesting tests here are not "does it compute GC". They are the ones
+that stop the module from OVER-CLAIMING, because the whole reason it exists is
+that the obvious implementation — paste goes straight to BLAST, motif hit gets
+reported as an identification — is wrong in both directions.
+"""
+import pytest
+
+from dee.core import identify as ident
+
+
+# A T7 expression cassette built from motifs that are already in the repo's own
+# catalogue, so nothing here is a sequence typed from recall.
+def _cassette() -> str:
+    from dee.core import plasmid
+    t7 = dict((n, s) for n, s, t in plasmid._MOTIFS)["T7 promoter"]
+    orf = "ATG" + "GCTAGCGGTACCGAATTCGATCTGAAAGCT" * 4 + "TAA"
+    # The pET C-terminal junction, taken from the vector catalogue itself.
+    from dee.core import vectors
+    tail = vectors._load()["pet28a"]["flanking_3p_max"]
+    return t7 + "GGAGACCACAACGG" + orf + tail
+
+
+# ── the honesty contract ─────────────────────────────────────────────────
+def test_local_analysis_never_reports_a_sequence_as_identified():
+    """The single most important assertion in this file.
+
+    Characterizing is not identifying. An agent that concludes "this is
+    insulin" from a His-tag match is the failure this module prevents.
+    """
+    r = ident.identify(_cassette())
+    assert r["ok"] and r["identified"] is False
+    assert "blast_sequence" in r["to_identify_it"]
+
+
+def test_it_says_that_blast_transmits():
+    r = ident.identify(_cassette())
+    assert "outside this Space" in r["to_identify_it"]
+
+
+def test_a_shared_vector_junction_is_reported_as_a_family_not_a_vector():
+    """The pET series shares one C-terminal His junction, and the catalogue
+    records it at different lengths per entry. A longer recorded junction is a
+    longer catalogue string, not better evidence — picking the longest and
+    naming it alone would invent a distinction the sequence cannot support."""
+    r = ident.identify(_cassette())
+    hits = r["detail"]["vector_junctions"]
+    assert hits, "the pET C-terminal junction should match"
+    three = [h for h in hits if h["end"] == "3'"][0]
+    assert len(three["vectors"]) > 1
+    assert three["distinguishing"] is False
+    assert "not which vector" in three["note"]
+    assert "shared by" in r["summary"]
+
+
+def test_a_fasta_header_is_a_claim_and_is_labelled_as_one():
+    r = ident.identify(">sp|P01308|INS_HUMAN Insulin\n" + "MKVLAAGIVGLNRSTGWQFD" * 4)
+    claim = r["header_claim"]
+    assert claim["accession"]["accession"] == "P01308"
+    assert claim["accession"]["family"] == "uniprot"
+    assert "claim to check, not as evidence" in claim["note"]
+    # And it must not have upgraded that claim into an identification.
+    assert r["identified"] is False
+
+
+def test_absence_of_a_motif_is_not_evidence_of_absence():
+    r = ident.identify("ATGAAACCCGGGTTTAAACCCGGGTTTAAACCCGGGTTTAAACCCTAA")
+    assert "not in the list" in r["caveat"]
+
+
+# ── molecule classification ──────────────────────────────────────────────
+def test_short_all_actg_input_is_ambiguous_and_asks_rather_than_guesses():
+    """'ATGCATGCATGCATGC' is a plausible DNA fragment AND a plausible peptide.
+    Silently picking one misroutes the entire job."""
+    r = ident.identify("ATGCATGCATGCATGC")
+    assert r["kind"] == "ambiguous"
+    assert "Ask the user" in r["next"]
+
+
+def test_rna_is_distinguished_from_dna():
+    r = ident.identify("AUGGCUAGCGGUACCGAAUUCGAUCUGAAAGCUAUGGCUAGCGGUACC")
+    assert r["molecule"] == "rna"
+    assert "nt RNA" in r["summary"]
+
+
+def test_protein_is_recognised_by_alphabet():
+    r = ident.identify("MKVLAAGIVGLNLGGRSTGWQFDPESLVNRHKYWMFE" * 2)
+    assert r["molecule"] == "protein"
+
+
+def test_an_accession_is_not_treated_as_a_sequence():
+    r = ident.identify("NM_000207.3")
+    assert r["kind"] == "accession"
+    assert r["accession"] == "NM_000207.3"
+    assert r["family"] == "refseq"
+    # The bug this pins: accession.classify returns (family, molecule), NOT
+    # (kind, token). Unpacking it the other way sent the agent off to fetch a
+    # sequence literally named "dna".
+    assert "fetch_sequence with 'NM_000207.3'" in r["next"]
+
+
+def test_too_short_is_refused_with_a_reason():
+    r = ident.identify("ATGCA")
+    assert r["ok"] is False and r["kind"] == "too_short"
+
+
+def test_empty_input_is_refused():
+    assert ident.identify("   ")["kind"] == "empty"
+
+
+# ── DNA characterization ─────────────────────────────────────────────────
+def test_a_clean_cds_is_called_a_clean_cds():
+    dna = "ATG" + "GCTAGCGGTACCGAATTCGATCTGAAAGCT" * 4 + "TAA"
+    r = ident.identify(dna)
+    assert r["detail"]["is_clean_cds"] is True
+    assert "clean CDS" in r["summary"]
+
+
+def test_an_internal_stop_disqualifies_a_clean_cds():
+    dna = "ATG" + "GCTAGCTAAGGTACCGAATTCGATCTGAAAGCT" * 4 + "TAA"
+    assert ident.identify(dna)["detail"]["is_clean_cds"] is False
+
+
+def test_random_dna_with_no_real_orf_says_so():
+    """A stop codon turns up roughly every 21 codons by chance, so reporting a
+    short 'ORF' from noise would be worse than reporting none."""
+    dna = "TTTAAACCCGGG" * 8
+    r = ident.identify(dna)
+    assert r["detail"]["longest_orf"] is None
+    assert "no ORF" in r["summary"]
+
+
+def test_motifs_are_found_on_both_strands():
+    from dee.core import plasmid
+    t7 = dict((n, s) for n, s, t in plasmid._MOTIFS)["T7 promoter"]
+    fwd = ident.identify("GGGGCCCCAAAA" + t7 + "GGGGCCCCAAAA")
+    rev = ident.identify("GGGGCCCCAAAA" + plasmid.revcomp(t7) + "GGGGCCCCAAAA")
+    assert any(f["name"] == "T7 promoter" for f in fwd["detail"]["features"])
+    assert any(f["name"] == "T7 promoter" for f in rev["detail"]["features"])
+
+
+def test_ambiguity_codes_are_counted_not_silently_dropped():
+    dna = "ATGNNNGCTAGCGGTACCGAATTCGATCTGAAAGCTTAA"
+    assert ident.identify(dna)["detail"]["ambiguity_codes"] == 3
+
+
+# ── protein characterization ─────────────────────────────────────────────
+def test_tag_peptides_are_derived_from_the_dna_catalogue_not_typed_here():
+    """One source of truth: correcting the DNA motif table must move these."""
+    from dee.core import edits, plasmid
+    derived = {t["peptide"] for t in ident._TAGS}
+    expected = {edits.translate(s) for n, s, ty in plasmid._MOTIFS
+                if ty == "tag" and len(s) % 3 == 0}
+    assert derived <= expected
+    assert len(derived) >= 5
+
+
+def test_a_his_tag_is_found_in_a_protein():
+    r = ident.identify("MKVLAAGIVGLNLGGRSTGWQFDPESLVNRHKYWMFE" + "HHHHHH")
+    assert any(t["name"] == "6×His tag" for t in r["detail"]["tags"])
+
+
+def test_low_complexity_protein_is_flagged():
+    """Either a synthetic linker or — far more often — DNA pasted into the
+    protein field. Both deserve a flag rather than a confident analysis."""
+    r = ident.identify("AAAAGGGGCCCCTTTT" * 6)
+    assert r["molecule"] == "dna"          # correctly routed away from protein
+    r2 = ident.identify("MAAAAAGGGGGAAAAA" * 6)
+    assert r2["molecule"] == "protein"
+    assert r2["detail"]["low_complexity"] is True
+    assert "low residue diversity" in r2["summary"]
+
+
+def test_a_normal_protein_is_not_flagged_low_complexity():
+    r = ident.identify("MKVLAAGIVGLNLGGRSTGWQFDPESLVNRHKYWMFECT" * 3)
+    assert r["detail"]["low_complexity"] is False
+
+
+# ── the agent tool ───────────────────────────────────────────────────────
+def test_the_agent_tool_is_registered_and_ungated():
+    from dee.core import agent_tools as t
+    assert "identify_sequence" in t._TOOLS
+    spec = [s for s in t.TOOL_SPECS
+            if s["function"]["name"] == "identify_sequence"][0]
+    assert "sequence" in spec["function"]["parameters"]["required"]
+
+
+def test_the_tool_description_tells_the_model_not_to_claim_an_id():
+    from dee.core import agent_tools as t
+    spec = [s for s in t.TOOL_SPECS
+            if s["function"]["name"] == "identify_sequence"][0]
+    desc = spec["function"]["description"]
+    assert "ALWAYS false" in desc
+    assert "blast_sequence" in desc
+
+
+def test_the_tool_runs_end_to_end():
+    from dee.core import agent_tools as t
+    out = t._TOOLS["identify_sequence"]["fn"]({"sequence": _cassette()})
+    assert out["ok"] and out["identified"] is False
+
+
+def test_the_tool_refuses_empty_input():
+    from dee.core import agent_tools as t
+    assert t._TOOLS["identify_sequence"]["fn"]({"sequence": ""})["ok"] is False

tests/test_mutagenesis.py

@@ -0,0 +1,143 @@
+"""Audit #37: primers that MAKE the mutation, not just name it.
+
+The engine says R175H is worth trying and then stops. Everything between
+"good idea" and DNA in a tube — picking the codon, centring the mismatch,
+balancing the two arms by Tm — was left to the user, and it is pure
+arithmetic on a sequence they already hold.
+
+The tests that matter here are the refusals. A primer pair is a thing someone
+orders and puts in a reaction; designing one for a mutation the sequence
+cannot support wastes a week, and the failure is invisible until sequencing.
+"""
+import pytest
+
+from dee.core import agent_tools as t
+from dee.core import mutagenesis as mut
+from dee.core import orchestrator as orch
+from dee.core.edits import translate
+
+# M followed by 200 arginines. Synthetic on purpose: a real gene here would be
+# a sequence typed from memory, which is the one thing this repo never does.
+CDS = "ATG" + "CGT" * 200
+
+
+def test_the_designed_mutation_is_actually_installed():
+    """The only end-to-end claim that matters: translate the product and the
+    new residue is there."""
+    r = mut.design(CDS, "R175H")
+    assert r["ok"]
+    assert translate(r["mutated_cds"])[174] == "H"
+    assert translate(r["mutated_cds"])[173] == "R"      # neighbours untouched
+    assert len(r["mutated_cds"]) == len(CDS)            # no frame shift
+
+
+def test_it_refuses_when_the_sequence_disagrees_with_the_label():
+    """The expensive failure. If position 175 is not R, the user is holding a
+    different sequence than they think — designing anyway makes primers for a
+    mutation nobody asked for, and nobody finds out until sequencing."""
+    r = mut.design(CDS, "K175H")
+    assert r["ok"] is False and r["kind"] == "wt_mismatch"
+    assert "is R, not K" in r["error"]
+
+
+def test_a_position_past_the_end_is_refused_with_the_real_length():
+    r = mut.design(CDS, "R900H")
+    assert r["ok"] is False and r["kind"] == "out_of_range"
+    assert "201-residue" in r["error"]
+    assert "initiator ATG" in r["next"]
+
+
+def test_the_codon_is_the_host_s_and_the_choice_is_shown():
+    """Six codons encode leucine and they are not interchangeable. The choice
+    is reported so it can be checked rather than trusted."""
+    r = mut.design(CDS, "R175L", host="e_coli")
+    assert r["ok"] and len(r["new_codon"]) == 3
+    assert translate(r["new_codon"]) == "L"
+    assert r["new_codon"] in r["codon_note"] and "e_coli" in r["codon_note"]
+
+
+def test_an_unknown_host_is_refused_rather_than_silently_defaulted():
+    """A silent fallback to E. coli would codon-optimise a yeast construct for
+    the wrong organism and say nothing."""
+    r = mut.design(CDS, "R175H", host="klingon")
+    assert r["ok"] is False and r["kind"] == "no_codon"
+
+
+def test_the_mismatch_sits_in_the_middle_of_the_primer():
+    """A mutation near a primer's end anneals poorly and the reaction fails.
+    Both flanks must clear the minimum."""
+    r = mut.design(CDS, "R175H")
+    codon_start = 174 * 3
+    for p in r["primers"]:
+        if p["role"] != "forward":
+            continue
+        left = codon_start - p["template_start"]
+        right = p["template_end"] - (codon_start + 3)
+        assert left >= mut.MIN_FLANK and right >= mut.MIN_FLANK, (left, right)
+
+
+def test_quikchange_primers_are_complementary_and_back_to_back_are_not():
+    """Different kits, different primer geometry. Returning one shape for both
+    would produce primers that simply do not work in the user's protocol."""
+    from dee.core.primers import revcomp
+    q = mut.design(CDS, "R175H", method="quikchange")
+    f, r_ = [p["sequence"] for p in q["primers"]]
+    assert r_ == revcomp(f) and q["overlap_bp"] == len(f)
+
+    b = mut.design(CDS, "R175H", method="back_to_back")
+    bf, br = [p["sequence"] for p in b["primers"]]
+    assert br != revcomp(bf) and b["overlap_bp"] == 0
+
+
+def test_every_primer_carries_the_numbers_a_bench_scientist_checks():
+    r = mut.design(CDS, "R175H")
+    for p in r["primers"]:
+        assert p["tm_c"] is not None and p["gc_pct"] is not None
+        assert "hairpin" in p and "self_dimer_3p" in p and "gc_clamp" in p
+
+
+def test_a_tm_mismatch_between_the_arms_is_warned_about():
+    """The cooler arm is where the reaction fails, and equal LENGTHS routinely
+    differ by several degrees."""
+    r = mut.design(CDS, "R175H")
+    tms = [p["tm_c"] for p in r["primers"]]
+    if abs(tms[0] - tms[1]) > mut.TM_TOLERANCE:
+        assert any("differ by" in w for w in r["warnings"])
+
+
+def test_it_never_claims_the_construct_is_verified():
+    """Primers propose a change. Only sequencing confirms one, and the tool
+    must not let the agent imply otherwise."""
+    r = mut.design(CDS, "R175H")
+    assert "sequencing" in r["caveat"].lower()
+    assert "calculated, not measured" in r["caveat"]
+
+
+def test_malformed_input_is_refused_not_guessed():
+    assert mut.design(CDS, "nonsense")["ok"] is False
+    assert mut.design("", "R175H")["ok"] is False
+    assert mut.design(CDS, "R175H", method="magic")["ok"] is False
+
+
+def test_it_is_reachable_ungated_and_specced():
+    """Fifth and sixth capabilities this week that existed and could not be
+    called. The lesson stuck: a module with no spec does not exist."""
+    assert "design_mutagenesis_primers" in t._TOOLS
+    assert any(s["function"]["name"] == "design_mutagenesis_primers"
+               for s in orch.TOOL_SPECS)
+    assert t._TOOLS["design_mutagenesis_primers"]["requires_signin"] is False
+    assert orch._requires_confirm("design_mutagenesis_primers") is False
+
+
+def test_the_spec_tells_the_model_about_the_refusal_and_the_caveat():
+    d = next(s["function"]["description"] for s in orch.TOOL_SPECS
+             if s["function"]["name"] == "design_mutagenesis_primers")
+    assert "REFUSES" in d
+    assert "sequenced" in d and "calculated, not measured" in d
+
+
+def test_the_tool_wrapper_matches_the_module():
+    out = t.execute_tool("design_mutagenesis_primers",
+                         {"cds": CDS, "substitution": "R175H"},
+                         auth_anonymous=True)
+    assert out["ok"] and len(out["primers"]) == 2

tests/test_overhangs.py

@@ -0,0 +1,135 @@
+"""Audit #40: why a Golden Gate with six correct fragments still comes back wrong.
+
+simulate_assembly chains parts whose overhangs match and reports success — and
+it is right, as a simulation. What it cannot see is that two overhangs are one
+base apart, or that one is its own reverse complement. T4 ligase does not care
+which partner it found, so the plate comes back with fragments in the wrong
+order and the design looked fine the whole time.
+
+All of it is decidable from four-base strings before anything is ordered,
+which is the point: this is arithmetic, not prediction.
+"""
+import json
+
+import pytest
+
+from dee.core import agent_tools as t
+from dee.core import orchestrator as orch
+from dee.core import overhangs as oh
+
+
+def test_a_palindrome_is_fatal():
+    """AATT is its own reverse complement, so the fragment ligates to itself
+    and to its own inversion. No amount of correct chaining saves it."""
+    assert oh.is_palindrome("AATT") and oh.is_palindrome("GGCC")
+    r = oh.check(["AATT", "GGAG", "AGGT", "TTCG"])
+    bad = [c for c in r["conflicts"] if c["kind"] == "palindromic"]
+    assert bad and bad[0]["severity"] == "fatal"
+    assert r["usable"] is False
+
+
+def test_complementary_overhangs_are_caught_because_the_junctions_swap():
+    """revcomp(GGAG) == CTCC. Two junctions that are interchangeable give an
+    assembly with no defined order."""
+    assert oh.revcomp("GGAG") == "CTCC"
+    r = oh.check(["GGAG", "CTCC", "AATG", "TTCG"])
+    kinds = {c["kind"] for c in r["conflicts"]}
+    assert "complementary" in kinds and r["fatal"] >= 1
+
+
+def test_one_base_apart_is_flagged_before_it_costs_a_week():
+    """The classic low-frequency misassembly: distance 1 means a single
+    mis-pairing still produces a ligatable junction."""
+    r = oh.check(["GGAG", "GGAC", "AATG", "TTCG"])
+    near = [c for c in r["conflicts"] if c["kind"] == "near_identical"]
+    assert near and near[0]["distance"] == 1
+
+
+def test_duplicates_are_fatal():
+    r = oh.check(["GGAG", "GGAG", "AATG"])
+    assert any(c["kind"] == "duplicate" for c in r["conflicts"])
+    assert r["usable"] is False
+
+
+def test_similarity_is_checked_against_the_reverse_complement_too():
+    """Which strand the ligase sees depends on which fragment arrives, so a
+    near-match to the PARTNER'S COMPLEMENT is just as dangerous."""
+    a = "GGAG"
+    near_rc = "CTCG"                     # one base from revcomp(GGAG) = CTCC
+    assert oh.hamming(a, oh.revcomp(near_rc)) <= 1 or \
+        oh.hamming(oh.revcomp(a), near_rc) <= 1
+    r = oh.check([a, near_rc, "AATG"])
+    assert any(c["kind"] in ("near_identical", "complementary")
+               for c in r["conflicts"])
+
+
+def test_low_complexity_ends_are_noted_but_not_fatal():
+    """All-AT ligates weakly and all-GC promiscuously. Real, but not a reason
+    to refuse a design that is otherwise sound."""
+    r = oh.check(["TTTT", "GGAG", "AATG"])
+    lc = [c for c in r["conflicts"] if c["kind"] == "low_complexity"]
+    assert lc and lc[0]["severity"] == "medium"
+
+
+def test_a_clean_set_is_reported_clean():
+    """A checker that flags everything is a checker nobody reads."""
+    r = oh.check(["GGAG", "AATG", "AGGT", "TTCG"])
+    assert r["conflicts"] == [] and r["usable"] is True
+
+
+def test_suggested_sets_survive_their_own_checker():
+    """The obvious way for a generator to be wrong, and free to test."""
+    for n in (4, 8, 12):
+        s = oh.suggest(n)
+        assert s["ok"] and len(s["overhangs"]) == n
+        assert oh.check(s["overhangs"])["conflicts"] == [], s["overhangs"]
+
+
+def test_suggest_is_deterministic_so_a_design_is_reproducible():
+    """A methods section has to be able to name the set."""
+    assert oh.suggest(6)["overhangs"] == oh.suggest(6)["overhangs"]
+
+
+def test_running_out_of_space_is_said_plainly():
+    """The 4-nt space genuinely exhausts. Returning a short set that looks
+    complete would be the worst possible answer."""
+    r = oh.suggest(400)
+    assert r["ok"] is False and r["kind"] == "exhausted"
+    assert "Lower min_distance" in r["next"]
+    assert r["found"], "the partial result is still worth showing"
+
+
+def test_wrong_length_overhangs_are_rejected_not_padded():
+    r = oh.check(["GGA", "GGAGT", "AATG"])
+    assert len(r["rejected"]) == 2 and r["count"] == 1
+
+
+def test_no_fidelity_percentage_is_ever_invented():
+    """NEB's fidelity data is empirical, measured on real ligations. A number
+    derived from sequence alone would be a fabricated measurement wearing a
+    decimal point — the same failure as ΔΔG."""
+    r = oh.check(["AATT", "GGAG", "CTCC"])
+    conflicts = json.dumps(r["conflicts"]).lower()
+    assert "fidelity" not in conflicts and "%" not in conflicts
+    assert "does not have" in r["basis"]
+
+
+def test_it_is_reachable_ungated_and_specced():
+    assert "check_overhangs" in t._TOOLS
+    assert any(s["function"]["name"] == "check_overhangs" for s in orch.TOOL_SPECS)
+    assert orch._requires_confirm("check_overhangs") is False
+
+
+def test_the_summary_puts_fatal_first():
+    """"5 conflicts" reads the same whether the assembly is merely weak or
+    cannot have a defined order at all."""
+    r = t.execute_tool("check_overhangs",
+                       {"overhangs": ["AATT", "GGAG", "CTCC", "GGAC"]},
+                       auth_anonymous=True)
+    assert "fatal" in orch._summarize("check_overhangs", r)
+
+
+def test_the_spec_forbids_stating_a_fidelity_number():
+    d = next(s["function"]["description"] for s in orch.TOOL_SPECS
+             if s["function"]["name"] == "check_overhangs")
+    assert "fidelity percentage" in d and "never state one" in d

tests/test_solubility.py

@@ -0,0 +1,185 @@
+"""Tests for aggregation risk factors (audit #23).
+
+The load-bearing tests are the ones that stop this becoming a solubility
+predictor. Everything else in the field reports a probability; this reports
+named risk factors, and the difference is the whole point.
+"""
+import pytest
+
+from dee.core import solubility as S
+
+# A charged, hydrophilic coiled-coil-ish sequence and a membrane-like one.
+SOLUBLE = "MKQLEDKVEELLSKNYHLENEVARLKKLVGER" * 3
+GREASY = "MALLVAGLLIFLAVAVLVGWVLAGIFLAAVLLVGAWMLIFAVLGLAVLFWA" * 2
+
+
+# ── the honesty contract ─────────────────────────────────────────────────
+def test_no_solubility_score_is_ever_reported():
+    r = S.assess(SOLUBLE)
+    assert r["ok"]
+    assert "no_score" in r
+    assert "would be invented" in r["no_score"]
+    # Nothing that reads as a probability or a prediction.
+    for key in ("solubility", "solubility_score", "probability", "prediction",
+                "soluble_pct"):
+        assert key not in r
+        assert key not in r["factors"]
+
+
+def test_the_patch_threshold_is_declared_as_a_convention_not_a_boundary():
+    """Every threshold here is a plot-reading convention. Presenting one as a
+    validated solubility cutoff would be the same lie as printing a score."""
+    t = S.assess(SOLUBLE)["thresholds"]
+    assert "not a validated solubility cutoff" in t
+    assert str(S.PATCH_THRESHOLD) in t and str(S.KD_WINDOW) in t
+    # The one borrowed cutoff is attributed.
+    assert "Guruswamy's own" in t
+
+
+def test_the_scales_are_attributed():
+    s = S.assess(SOLUBLE)["scales"]
+    assert "Kyte-Doolittle" in s and "Guruswamy" in s
+    assert "no value here was entered by hand" in s
+
+
+def test_absolute_mode_points_at_the_comparison_mode():
+    assert "compare()" in S.assess(SOLUBLE)["caveat"]
+
+
+# ── absolute assessment ──────────────────────────────────────────────────
+def test_a_hydrophilic_protein_is_not_flagged_hydrophobic():
+    r = S.assess(SOLUBLE)
+    assert r["factors"]["gravy"] < 0
+    assert not any(f["factor"] == "net hydrophobic" for f in r["flags"])
+
+
+def test_a_membrane_like_protein_is_flagged():
+    r = S.assess(GREASY)
+    assert r["factors"]["gravy"] > 0
+    names = [f["factor"] for f in r["flags"]]
+    assert "net hydrophobic" in names
+    assert "extended hydrophobic patch" in names
+
+
+def test_a_hydrophobic_patch_is_located_not_just_counted():
+    """Whole-protein GRAVY averages a patch away. Aggregation happens at the
+    patch, so it has to be findable."""
+    r = S.assess(GREASY)
+    patches = r["factors"]["hydrophobic_patches"]
+    assert patches
+    assert all(p["start"] >= 1 and p["end"] <= len(GREASY) for p in patches)
+    assert all(p["end"] > p["start"] for p in patches)
+
+
+def test_pi_near_the_working_ph_is_flagged_with_the_reason():
+    r = S.assess(SOLUBLE, ph=round(S.assess(SOLUBLE)["factors"]
+                                   ["isoelectric_point"], 1))
+    flag = [f for f in r["flags"] if "pI close" in f["factor"]]
+    assert flag
+    assert "electrostatic repulsion" in flag[0]["why"]
+
+
+def test_cysteines_are_only_flagged_where_the_chemistry_applies():
+    """A reducing cytoplasm is an E. coli fact. Flagging Cys in a yeast or
+    mammalian host would be a warning about nothing."""
+    cys = "MKQLCDKVEELCSKNYHLENEVARLKKLVGER" * 3
+    assert any("cysteines" in f["factor"]
+               for f in S.assess(cys, host="e_coli")["flags"])
+    assert not any("cysteines" in f["factor"]
+                   for f in S.assess(cys, host="human")["flags"])
+
+
+def test_unscorable_residues_are_excluded_and_reported():
+    """X has no Kyte-Doolittle value. Dropping it silently would report
+    numbers for a sequence the user did not give."""
+    r = S.assess("MKQLEDKVEELLSKNYHLENEVARLKKLVGER" + "XXXX" + SOLUBLE)
+    assert r["unscored_residues"] == 4
+    assert "excluded" in r["note"]
+    assert r["factors"]["length"] == len(S._known(S._clean(
+        "MKQLEDKVEELLSKNYHLENEVARLKKLVGER" + "XXXX" + SOLUBLE)))
+
+
+def test_too_short_is_refused():
+    assert S.assess("MKQL")["kind"] == "too_short"
+
+
+# ── the comparison mode, which is the trustworthy one ────────────────────
+def test_deltas_are_computed_before_rounding():
+    """Differencing two values each already rounded to one decimal reports 0.0
+    for a real change — which would zero out exactly the small deltas this
+    mode exists to surface."""
+    wt = SOLUBLE
+    mut = wt[:20] + "L" + wt[21:]
+    c = S.compare(wt, mut)
+    # pI moves by ~1.064; a rounded-then-subtracted version reports 1.07.
+    assert c["deltas"]["isoelectric_point"] == pytest.approx(1.064, abs=0.005)
+    assert c["deltas"]["net_charge_at_ph"] != 1.0
+
+
+def test_comparison_states_why_it_is_more_trustworthy():
+    c = S.compare(SOLUBLE, SOLUBLE[:5] + "C" + SOLUBLE[6:])
+    assert "cancel" in c["why_this_is_more_trustworthy"]
+    assert "not a predicted change in solubility" in c["no_score"]
+
+
+def test_an_introduced_cysteine_is_called_out():
+    c = S.compare(SOLUBLE, SOLUBLE[:5] + "C" + SOLUBLE[6:], host="e_coli")
+    assert c["deltas"]["cysteines"] == 1
+    assert any("free thiol" in n for n in c["notes"])
+
+
+def test_a_removed_cysteine_mentions_the_orphaned_partner():
+    wt = SOLUBLE[:5] + "C" + SOLUBLE[6:15] + "C" + SOLUBLE[16:]
+    mut = wt[:5] + "A" + wt[6:]
+    c = S.compare(wt, mut)
+    assert c["deltas"]["cysteines"] == -1
+    assert any("partner is now" in n for n in c["notes"])
+
+
+def test_a_change_inside_an_existing_patch_is_distinguished():
+    """Adding a leucine to an already-greasy stretch compounds a risk;
+    adding one to a polar region creates a smaller, different one."""
+    mut = GREASY[:10] + "L" + GREASY[11:]
+    c = S.compare(GREASY, mut)
+    assert c["in_existing_hydrophobic_patch"]
+    assert any("compounds an existing risk" in n for n in c["notes"])
+
+
+def test_changes_are_enumerated_with_positions():
+    mut = SOLUBLE[:3] + "W" + SOLUBLE[4:]
+    c = S.compare(SOLUBLE, mut)
+    assert c["changes"] == [{"position": 4, "from": SOLUBLE[3], "to": "W"}]
+
+
+def test_an_indel_is_refused_rather_than_compared_positionally():
+    """After an indel the two sequences are no longer position-comparable, so
+    a per-position diff would report every downstream residue as changed."""
+    r = S.compare(SOLUBLE, SOLUBLE[:-5])
+    assert r["ok"] is False and r["kind"] == "length_mismatch"
+    assert "compare_sequences" in r["next"]
+
+
+def test_identical_sequences_are_refused():
+    assert S.compare(SOLUBLE, SOLUBLE)["kind"] == "identical"
+
+
+# ── the agent tool ───────────────────────────────────────────────────────
+def test_the_tool_supports_both_modes():
+    from dee.core import agent_tools as t
+    fn = t._TOOLS["assess_solubility"]["fn"]
+    assert fn({"protein": SOLUBLE})["ok"]
+    both = fn({"wild_type": SOLUBLE, "mutant": SOLUBLE[:3] + "W" + SOLUBLE[4:]})
+    assert both["ok"] and both["changes"]
+
+
+def test_the_tool_refuses_with_neither():
+    from dee.core import agent_tools as t
+    assert t._TOOLS["assess_solubility"]["fn"]({})["ok"] is False
+
+
+def test_the_spec_forbids_inventing_a_score():
+    from dee.core import agent_tools as t
+    desc = next(s for s in t.TOOL_SPECS
+                if s["function"]["name"] == "assess_solubility")["function"]["description"]
+    assert "must not invent one" in desc
+    assert "PREFER THE SECOND" in desc

tests/test_vector_lookup.py

@@ -170,3 +170,48 @@ def test_the_tool_description_points_away_from_fetch_sequence():
     desc = spec["function"]["description"]
     assert "fetch_sequence" in desc
     assert "refusal is NOT" in desc
+
+
+# --------------------------------------------------------------------------- #
+# where the plasmid actually comes from (audit #6, the honest half)
+# --------------------------------------------------------------------------- #
+def test_the_addgene_url_is_built_in_code_not_left_to_the_model():
+    """The stored ids carry a lot suffix ("69864-3") and the plasmid page is
+    keyed on the number alone. An agent assembling the URL from the raw string
+    produces a 404, which a user reads as "this vector doesn't exist"."""
+    from dee.core import vectors as v
+    entry = v.find("pET-28a(+)")
+    assert entry["addgene"] == "69864-3"
+    assert v.addgene_url(entry) == "https://www.addgene.org/69864/"
+
+
+def test_every_catalogue_addgene_id_yields_a_well_formed_url():
+    from dee.core import vectors as v
+    import re
+    have = [e for e in v._load().values() if e.get("addgene")]
+    assert have, "the catalogue records Addgene ids"
+    for entry in have:
+        url = v.addgene_url(entry)
+        assert re.fullmatch(r"https://www\.addgene\.org/\d+/", url), entry["name"]
+
+
+def test_a_vector_with_no_addgene_id_gets_no_url_rather_than_a_guess():
+    from dee.core import vectors as v
+    entry = v.find("pUC19")
+    assert not entry.get("addgene")
+    assert v.addgene_url(entry) is None
+    out = t._TOOLS["lookup_vector"]["fn"]({"name": "pUC19"})
+    assert out["ok"] and "addgene_url" not in out
+
+
+def test_lookup_vector_hands_over_the_link_when_it_has_one():
+    out = t._TOOLS["lookup_vector"]["fn"]({"name": "lentiCRISPR v2"})
+    assert out["addgene_url"] == "https://www.addgene.org/52961/"
+    assert "Give the user the link" in out["where_to_get_it"]
+
+
+def test_addgene_url_survives_junk_input():
+    from dee.core import vectors as v
+    assert v.addgene_url(None) is None
+    assert v.addgene_url({}) is None
+    assert v.addgene_url({"addgene": "not-a-number"}) is None