factorforge-cds 3.3.2__tar.gz → 3.4.0__tar.gz

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.3.2
+Version: 3.4.0
 Summary: FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -93,7 +93,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.3.2 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.4.0 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/README.md

@@ -60,7 +60,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.3.2 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.4.0 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.3.2"
+version = "3.4.0"
 description = "FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge/__init__.py

@@ -4,7 +4,7 @@ FactorForge - Codon Optimization Platform
 profile: constraint-aware rule/profile engine
 """
 
-__version__ = "3.3.2"
+__version__ = "3.4.0"
 __author__ = "Eijex"
 
 # Auto-register engines (safe when running from source tree)

factorforge_cds-3.4.0/src/factorforge/design_review.py

@@ -0,0 +1,437 @@
+"""Deterministic CDS design-review parsing, criteria, and decision helpers."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime, timezone
+import hashlib
+import re
+from typing import Any, Literal
+
+from factorforge.analysis.metrics import (
+    STOP_CODONS,
+    calculate_cai,
+    calculate_gc,
+    calculate_gc_windows,
+    detect_forbidden_motifs,
+    translate_dna,
+)
+
+ConstraintMode = Literal["required", "preferred", "ignored"]
+AutomatedDecision = Literal["PASS", "CONDITIONAL_PASS", "FAIL"]
+
+MULTI_FASTA_ERROR = "Multiple FASTA records detected. Upload one sequence at a time."
+VALID_PROTEIN = frozenset("ACDEFGHIKLMNPQRSTVWY*")
+VALID_DNA = frozenset("ACGT")
+TYPE_IIS_SITES = {
+    "BsaI": ("GGTCTC", "GAGACC"),
+    "BsmBI/Esp3I": ("CGTCTC", "GAGACG"),
+    "SapI": ("GCTCTTC", "GAAGAGC"),
+}
+VALID_MODES = frozenset({"required", "preferred", "ignored"})
+VALID_DISPOSITIONS = frozenset(
+    {"accept", "accept_with_exception", "return_for_redesign", "reject"}
+)
+
+
+def _compact_sequence(value: str) -> str:
+    return re.sub(r"\s+", "", value).upper()
+
+
+def parse_sequence_input(raw: str) -> dict[str, Any]:
+    """Parse one plain sequence or one FASTA record and classify it explicitly."""
+    if not isinstance(raw, str) or not raw.strip():
+        raise ValueError("Sequence is required.")
+
+    lines = raw.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    nonempty = [line.strip() for line in lines if line.strip()]
+    headers = [index for index, line in enumerate(nonempty) if line.startswith(">")]
+    if len(headers) > 1:
+        raise ValueError(MULTI_FASTA_ERROR)
+    if headers and headers[0] != 0:
+        raise ValueError("FASTA header must be the first non-empty line.")
+
+    header = nonempty[0][1:].strip() if headers else None
+    sequence_lines = nonempty[1:] if headers else nonempty
+    sequence = _compact_sequence("".join(sequence_lines))
+    if not sequence:
+        raise ValueError("Sequence is required.")
+
+    characters = set(sequence)
+    if characters <= VALID_DNA:
+        return _build_cds_context(sequence, header)
+
+    invalid = characters - VALID_PROTEIN
+    if invalid:
+        raise ValueError(f"Invalid sequence characters: {', '.join(sorted(invalid))}.")
+    if "*" in sequence[:-1]:
+        raise ValueError("Protein input contains an internal stop marker.")
+
+    protein = sequence.rstrip("*")
+    if not protein:
+        raise ValueError("Protein sequence must contain at least one amino acid.")
+    return {
+        "input_type": "protein",
+        "normalized_sequence": sequence,
+        "optimization_sequence": protein,
+        "fasta_header": header,
+        "generation_allowed": True,
+        "message": (
+            "Protein sequence detected. FactorForge will reverse translate it into "
+            "a host-adapted coding sequence."
+        ),
+        "summary": {
+            "protein_length_aa": len(protein),
+            "terminal_stop_marker": sequence.endswith("*"),
+        },
+        "errors": [],
+        "warnings": [],
+    }
+
+
+def _build_cds_context(sequence: str, header: str | None) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    frame_valid = len(sequence) % 3 == 0
+    if not frame_valid:
+        errors.append("CDS length must be divisible by 3.")
+
+    codons = [sequence[index : index + 3] for index in range(0, len(sequence), 3)]
+    complete_codons = [codon for codon in codons if len(codon) == 3]
+    start_present = bool(complete_codons) and complete_codons[0] == "ATG"
+    terminal_stop_present = bool(complete_codons) and complete_codons[-1] in STOP_CODONS
+    internal_stops = [
+        index for index, codon in enumerate(complete_codons[:-1]) if codon in STOP_CODONS
+    ]
+    if internal_stops:
+        errors.append("CDS contains internal stop codon(s).")
+    if not start_present:
+        warnings.append("Start codon is absent.")
+    if not terminal_stop_present:
+        warnings.append("Terminal stop codon is absent.")
+
+    translated = translate_dna(sequence) if frame_valid else ""
+    protein = translated[:-1] if terminal_stop_present else translated
+    return {
+        "input_type": "cds",
+        "normalized_sequence": sequence,
+        "optimization_sequence": protein,
+        "fasta_header": header,
+        "generation_allowed": not errors,
+        "message": (
+            "DNA coding sequence detected. FactorForge will preserve the translated "
+            "protein while redesigning synonymous codons for the selected host and constraints."
+        ),
+        "summary": {
+            "cds_length_bp": len(sequence),
+            "codon_count": len(complete_codons),
+            "protein_length_aa": len(protein),
+            "gc_percent": round(calculate_gc(sequence), 1),
+            "frame_valid": frame_valid,
+            "start_codon_present": start_present,
+            "terminal_stop_present": terminal_stop_present,
+            "terminal_stop_codon": complete_codons[-1] if terminal_stop_present else None,
+            "internal_stop_count": len(internal_stops),
+        },
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
+def restore_cds_stop_policy(candidate: str, input_context: dict[str, Any]) -> str:
+    """Restore the original CDS terminal-stop policy to a generated candidate."""
+    sequence = _compact_sequence(candidate)
+    if input_context["input_type"] != "cds":
+        return sequence
+    stop = input_context["summary"]["terminal_stop_codon"]
+    translated = translate_dna(sequence)
+    if translated.endswith("*"):
+        sequence = sequence[:-3]
+    return sequence + (stop or "")
+
+
+def assert_pathway_invariants(
+    original_cds: str,
+    optimized_cds: str,
+    input_context: dict[str, Any],
+) -> None:
+    """Raise visibly when CDS length or translated-protein invariants regress."""
+    if input_context["input_type"] != "cds":
+        return
+    if len(original_cds) != len(optimized_cds):
+        raise ValueError(
+            "CDS invariant failed: optimized nucleotide length differs from the original."
+        )
+    original_protein = translate_dna(original_cds).rstrip("*")
+    optimized_protein = translate_dna(optimized_cds).rstrip("*")
+    if original_protein != optimized_protein:
+        raise ValueError("CDS invariant failed: translated protein was not preserved.")
+
+
+def default_acceptance_criteria(
+    gc_min: float = 40.0,
+    gc_max: float = 55.0,
+) -> dict[str, dict[str, Any]]:
+    return {
+        "cai": {"mode": "preferred", "minimum": 0.8},
+        "overall_gc": {"mode": "preferred", "minimum": gc_min, "maximum": gc_max},
+        "local_gc": {
+            "mode": "preferred",
+            "minimum": 30.0,
+            "maximum": 70.0,
+            "window_size": 60,
+        },
+        "type_iis": {
+            "mode": "required",
+            "enzymes": ["BsaI", "BsmBI/Esp3I", "SapI"],
+            "custom_sites": [],
+        },
+        "repeats": {"mode": "preferred", "minimum_length": 18, "maximum_count": 0},
+        "homopolymers": {"mode": "preferred", "maximum_length": 8},
+        "forbidden_motifs": {
+            "mode": "preferred",
+            "motifs": ["AATAAA", "GTAAGT", "ATTTA"],
+        },
+    }
+
+
+def normalize_acceptance_criteria(
+    value: dict[str, Any] | None,
+    *,
+    gc_min: float,
+    gc_max: float,
+) -> dict[str, dict[str, Any]]:
+    criteria = default_acceptance_criteria(gc_min, gc_max)
+    if value is None:
+        return criteria
+    if not isinstance(value, dict):
+        raise ValueError("acceptance_criteria must be an object.")
+    unknown = set(value) - set(criteria)
+    if unknown:
+        raise ValueError(f"Unknown acceptance criteria: {', '.join(sorted(unknown))}.")
+    for name, override in value.items():
+        if not isinstance(override, dict):
+            raise ValueError(f"acceptance_criteria.{name} must be an object.")
+        criteria[name].update(deepcopy(override))
+        mode = criteria[name].get("mode")
+        if mode not in VALID_MODES:
+            raise ValueError(
+                f"acceptance_criteria.{name}.mode must be required, preferred, or ignored."
+            )
+    _validate_criteria_ranges(criteria)
+    return criteria
+
+
+def _validate_criteria_ranges(criteria: dict[str, dict[str, Any]]) -> None:
+    for name in ("overall_gc", "local_gc"):
+        minimum = float(criteria[name]["minimum"])
+        maximum = float(criteria[name]["maximum"])
+        if not 0 <= minimum <= maximum <= 100:
+            raise ValueError(f"acceptance_criteria.{name} range must be within 0-100.")
+    cai_minimum = float(criteria["cai"]["minimum"])
+    if not 0 <= cai_minimum <= 1:
+        raise ValueError("acceptance_criteria.cai.minimum must be within 0-1.")
+    if int(criteria["local_gc"]["window_size"]) <= 0:
+        raise ValueError("acceptance_criteria.local_gc.window_size must be positive.")
+    if int(criteria["homopolymers"]["maximum_length"]) < 2:
+        raise ValueError("acceptance_criteria.homopolymers.maximum_length must be at least 2.")
+
+
+def _count_direct_repeats(sequence: str, minimum_length: int) -> int:
+    if len(sequence) < minimum_length * 2:
+        return 0
+    seen: set[str] = set()
+    repeated: set[str] = set()
+    for index in range(0, len(sequence) - minimum_length + 1):
+        motif = sequence[index : index + minimum_length]
+        if motif in seen:
+            repeated.add(motif)
+        seen.add(motif)
+    return len(repeated)
+
+
+def _longest_homopolymer(sequence: str) -> int:
+    return max((len(match.group(0)) for match in re.finditer(r"([ACGT])\1*", sequence)), default=0)
+
+
+def _type_iis_findings(
+    sequence: str,
+    criterion: dict[str, Any],
+) -> list[dict[str, Any]]:
+    findings: list[dict[str, Any]] = []
+    enabled = set(criterion.get("enzymes", []))
+    for enzyme, patterns in TYPE_IIS_SITES.items():
+        if enzyme not in enabled:
+            continue
+        for pattern in patterns:
+            start = sequence.find(pattern)
+            while start >= 0:
+                findings.append({"enzyme": enzyme, "site": pattern, "start": start})
+                start = sequence.find(pattern, start + 1)
+    for site in criterion.get("custom_sites", []):
+        if isinstance(site, dict):
+            name = str(site.get("name") or "Custom")
+            pattern = _compact_sequence(str(site.get("sequence") or ""))
+        else:
+            name = "Custom"
+            pattern = _compact_sequence(str(site))
+        if not pattern or set(pattern) - VALID_DNA:
+            continue
+        start = sequence.find(pattern)
+        while start >= 0:
+            findings.append({"enzyme": name, "site": pattern, "start": start})
+            start = sequence.find(pattern, start + 1)
+    return findings
+
+
+def evaluate_candidate(
+    sequence: str,
+    *,
+    cai: float,
+    criteria: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    """Evaluate one CDS against a normalized criteria snapshot."""
+    seq = _compact_sequence(sequence)
+    overall_gc = calculate_gc(seq)
+    local_rule = criteria["local_gc"]
+    windows = calculate_gc_windows(
+        seq,
+        window_size=int(local_rule["window_size"]),
+        step=max(1, int(local_rule["window_size"]) // 2),
+    )
+    local_values = [float(window["gc"]) for window in windows] or [overall_gc]
+    type_iis = _type_iis_findings(seq, criteria["type_iis"])
+    repeat_count = _count_direct_repeats(seq, int(criteria["repeats"]["minimum_length"]))
+    longest_homopolymer = _longest_homopolymer(seq)
+    motifs = detect_forbidden_motifs(seq, list(criteria["forbidden_motifs"].get("motifs", [])))
+
+    observations = {
+        "cai": (float(cai), float(criteria["cai"]["minimum"]), float(cai) >= float(criteria["cai"]["minimum"])),
+        "overall_gc": (
+            round(overall_gc, 1),
+            f"{float(criteria['overall_gc']['minimum']):g}-{float(criteria['overall_gc']['maximum']):g}%",
+            float(criteria["overall_gc"]["minimum"]) <= overall_gc <= float(criteria["overall_gc"]["maximum"]),
+        ),
+        "local_gc": (
+            f"{min(local_values):.1f}-{max(local_values):.1f}%",
+            f"{float(local_rule['minimum']):g}-{float(local_rule['maximum']):g}%",
+            min(local_values) >= float(local_rule["minimum"]) and max(local_values) <= float(local_rule["maximum"]),
+        ),
+        "type_iis": (len(type_iis), 0, not type_iis),
+        "repeats": (
+            repeat_count,
+            int(criteria["repeats"]["maximum_count"]),
+            repeat_count <= int(criteria["repeats"]["maximum_count"]),
+        ),
+        "homopolymers": (
+            longest_homopolymer,
+            int(criteria["homopolymers"]["maximum_length"]),
+            longest_homopolymer <= int(criteria["homopolymers"]["maximum_length"]),
+        ),
+        "forbidden_motifs": (len(motifs), 0, not motifs),
+    }
+
+    rows: list[dict[str, Any]] = []
+    required_failures = 0
+    preferred_warnings = 0
+    for name, (observed, threshold, passed) in observations.items():
+        mode: ConstraintMode = criteria[name]["mode"]
+        if mode == "ignored":
+            result = "IGNORED"
+        elif passed:
+            result = "PASS"
+        elif mode == "required":
+            result = "FAIL"
+            required_failures += 1
+        else:
+            result = "WARN"
+            preferred_warnings += 1
+        rows.append(
+            {
+                "criterion": name,
+                "mode": mode,
+                "observed": observed,
+                "threshold": threshold,
+                "result": result,
+            }
+        )
+
+    if required_failures:
+        decision: AutomatedDecision = "FAIL"
+    elif preferred_warnings:
+        decision = "CONDITIONAL_PASS"
+    else:
+        decision = "PASS"
+    failed_names = [
+        row["criterion"] for row in rows if row["result"] in {"FAIL", "WARN"}
+    ]
+    explanation = (
+        f"{', '.join(failed_names)} require review."
+        if failed_names
+        else "All active acceptance criteria passed."
+    )
+    return {
+        "automated_decision": decision,
+        "required_failure_count": required_failures,
+        "preferred_warning_count": preferred_warnings,
+        "explanation": explanation,
+        "criteria": rows,
+        "details": {
+            "type_iis_sites": type_iis,
+            "forbidden_motifs": motifs,
+            "local_gc_min": round(min(local_values), 1),
+            "local_gc_max": round(max(local_values), 1),
+            "repeat_count": repeat_count,
+            "longest_homopolymer": longest_homopolymer,
+        },
+    }
+
+
+def apply_reviewer_disposition(
+    automated_decision: AutomatedDecision,
+    value: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise ValueError("reviewer_disposition must be an object.")
+    disposition = str(value.get("disposition") or "").strip().lower()
+    if disposition not in VALID_DISPOSITIONS:
+        raise ValueError(
+            "reviewer_disposition.disposition must be accept, accept_with_exception, "
+            "return_for_redesign, or reject."
+        )
+    reason = str(value.get("reason") or "").strip()
+    accepting_failure = automated_decision == "FAIL" and disposition in {
+        "accept",
+        "accept_with_exception",
+    }
+    if accepting_failure and not reason:
+        raise ValueError("A written reason is required to accept an automated FAIL.")
+    final_state = {
+        "accept": "ACCEPTED",
+        "accept_with_exception": "ACCEPTED_WITH_EXCEPTION",
+        "return_for_redesign": "RETURNED_FOR_REDESIGN",
+        "reject": "REJECTED",
+    }[disposition]
+    if accepting_failure:
+        final_state = "MANUALLY_ACCEPTED"
+    return {
+        "disposition": disposition,
+        "reason": reason or None,
+        "timestamp": value.get("timestamp")
+        or datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "final_state": final_state,
+        "automated_decision": automated_decision,
+    }
+
+
+def build_result_identifier(input_sequence: str, criteria: dict[str, Any]) -> str:
+    payload = f"{input_sequence}|{repr(criteria)}".encode("utf-8")
+    return "ff-" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+def original_cai(sequence: str, codon_weights: dict[str, float]) -> float | None:
+    if not sequence or len(sequence) % 3:
+        return None
+    return calculate_cai(sequence, codon_weights)

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge/engines/__init__.py

@@ -13,7 +13,7 @@ def register_builtin_engines() -> None:
         "profile",
         RuleBasedOptimizer,
         metadata={
-            "version": "3.3.2",
+            "version": "3.4.0",
             "engine_type": "profile_rule_based",
             "role": "stable_profile_engine",
             "stable": True,

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge/engines/profile/__init__.py

@@ -5,7 +5,7 @@ Production system (2026)
 Plant-specific rule-based optimization
 """
 
-__version__ = "3.3.2"
+__version__ = "3.4.0"
 
 from .optimizer import RuleBasedOptimizer
 from .pipeline import OptimizationPipeline

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge/engines/profile/optimizer.py

@@ -6,6 +6,7 @@ import logging
 from typing import Any
 
 from factorforge.core.interfaces import OptimizationResult, OptimizerEngine
+from factorforge.analysis.metrics import translate_dna
 
 from .exporter import SequenceExporter
 from .rules.reverse_translator import OptimizationProfile, ReverseTranslator
@@ -20,7 +21,7 @@ class RuleBasedOptimizer(OptimizerEngine):
     """Profile-based rule optimization engine."""
 
     name = "Profile-based"
-    version = "3.3.2"
+    version = "3.4.0"
 
     def __init__(
         self,
@@ -124,9 +125,30 @@ class RuleBasedOptimizer(OptimizerEngine):
             translator = ReverseTranslator(host=host)
             rule_engine = RuleEngine(host=host)
 
-        # 3. Reverse-translate (pick the best candidate)
+        # 3. Optimize DNA/CDS through the translated protein, then restore the
+        # original terminal-stop policy.  DNA must never be treated as a
+        # protein string (300 bp must not become 300 aa / 900 bp).
         if seq_type == "dna":
-            optimized_dna = processed_seq
+            if len(processed_seq) % 3:
+                raise ValueError("DNA/CDS input length must be divisible by 3.")
+            translated = translate_dna(processed_seq)
+            if "*" in translated[:-1]:
+                raise ValueError("DNA/CDS input contains an internal stop codon.")
+            terminal_stop = processed_seq[-3:] if translated.endswith("*") else ""
+            protein = translated.rstrip("*")
+            generated = translator.generate_candidates(
+                protein, profile=opt_profile, n=1, seed=seed, **{
+                    k: v for k, v in kwargs.items()
+                    if k not in ("scan_mode", "scan_include", "scan_exclude")
+                }
+            )
+            if not generated:
+                raise ValueError("No candidates generated for DNA/CDS input.")
+            optimized_dna = generated[0]["sequence"] + terminal_stop
+            if len(optimized_dna) != len(processed_seq):
+                raise ValueError("CDS invariant failed: optimized nucleotide length differs.")
+            if translate_dna(optimized_dna).rstrip("*") != protein:
+                raise ValueError("CDS invariant failed: translated protein was not preserved.")
             cai = translator.calculate_cai(optimized_dna)
             gc = translator.calculate_gc_content(optimized_dna)
             score = calculate_composite_score(

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge/engines/profile/pipeline.py

@@ -189,8 +189,21 @@ class OptimizationPipeline:
 
         candidate_metrics: dict[str, Any]
         if seq_type == "dna":
-            optimized_dna = processed
-            expected_protein = translate_dna(processed).rstrip("*")
+            if len(processed) % 3:
+                raise ValueError("DNA/CDS input length must be divisible by 3.")
+            translated = translate_dna(processed)
+            if "*" in translated[:-1]:
+                raise ValueError("DNA/CDS input contains an internal stop codon.")
+            expected_protein = translated.rstrip("*")
+            terminal_stop = processed[-3:] if translated.endswith("*") else ""
+            generated = translator.generate_candidates(expected_protein, profile=opt_profile, n=1)
+            if not generated:
+                raise ValueError("No candidates generated for DNA/CDS input.")
+            optimized_dna = generated[0]["sequence"] + terminal_stop
+            if len(optimized_dna) != len(processed):
+                raise ValueError("CDS invariant failed: optimized nucleotide length differs.")
+            if translate_dna(optimized_dna).rstrip("*") != expected_protein:
+                raise ValueError("CDS invariant failed: translated protein was not preserved.")
             cai = translator.calculate_cai(optimized_dna)
             gc = translator.calculate_gc_content(optimized_dna)
             score = calculate_composite_score(

factorforge_cds-3.4.0/src/factorforge/review/__init__.py

@@ -0,0 +1,2 @@
+"""Compatibility package for FactorForge design-review helpers."""
+

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge/schemas/design_package.py

@@ -90,6 +90,30 @@ class WetLabFeedback(BaseModel):
     submissions: list[Any] = Field(default_factory=list)
 
 
+class ReviewerDisposition(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    disposition: Literal[
+        "accept", "accept_with_exception", "return_for_redesign", "reject"
+    ]
+    reason: Optional[str] = None
+    timestamp: str
+    final_state: str
+    automated_decision: Literal["PASS", "CONDITIONAL_PASS", "FAIL"]
+
+
+class AcceptanceCriteriaSnapshot(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    cai: dict[str, Any]
+    overall_gc: dict[str, Any]
+    local_gc: dict[str, Any]
+    type_iis: dict[str, Any]
+    repeats: dict[str, Any]
+    homopolymers: dict[str, Any]
+    forbidden_motifs: dict[str, Any]
+
+
 class ProteinRisk(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
@@ -114,3 +138,9 @@ class DesignPackage(BaseModel):
     provenance: Provenance
     wet_lab_feedback: WetLabFeedback = Field(default_factory=WetLabFeedback)
     protein_risk: Optional[ProteinRisk] = None
+    result_identifier: Optional[str] = None
+    input_type: Optional[Literal["cds", "protein"]] = None
+    input_summary: Optional[dict[str, Any]] = None
+    acceptance_criteria_snapshot: Optional[AcceptanceCriteriaSnapshot] = None
+    automated_decision: Optional[Literal["PASS", "CONDITIONAL_PASS", "FAIL"]] = None
+    reviewer_disposition: Optional[ReviewerDisposition] = None

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge_cds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.3.2
+Version: 3.4.0
 Summary: FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -93,7 +93,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.3.2 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.4.0 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.3.2 → factorforge_cds-3.4.0}/src/factorforge_cds.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/factorforge/__init__.py
 src/factorforge/__main__.py
 src/factorforge/database.py
+src/factorforge/design_review.py
 src/factorforge/validation_registry.py
 src/factorforge/validation_report.py
 src/factorforge/analysis/__init__.py
@@ -59,6 +60,7 @@ src/factorforge/protein_risk/sp_predict.py
 src/factorforge/protein_risk/tm_predict.py
 src/factorforge/registry/__init__.py
 src/factorforge/registry/registry_loader.py
+src/factorforge/review/__init__.py
 src/factorforge/schemas/__init__.py
 src/factorforge/schemas/design_package.py
 src/factorforge/schemas/design_package.schema.json
@@ -89,6 +91,7 @@ tests/test_database.py
 tests/test_design_package_schema.py
 tests/test_design_package_semantics.py
 tests/test_design_package_serialization.py
+tests/test_design_review.py
 tests/test_docs_consistency.py
 tests/test_fasta_io.py
 tests/test_gc_content.py

factorforge_cds-3.4.0/tests/test_design_review.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import pytest
+
+from factorforge.analysis.metrics import translate_dna
+from factorforge.design_review import (
+    apply_reviewer_disposition,
+    assert_pathway_invariants,
+    default_acceptance_criteria,
+    evaluate_candidate,
+    normalize_acceptance_criteria,
+    parse_sequence_input,
+    restore_cds_stop_policy,
+    original_cai,
+)
+from factorforge.analysis.metrics import load_codon_usage_table
+
+
+BALANCED_DNA = "ATG" + ("GCT" * 97) + "GAA" + "TAA"
+
+
+def test_plain_and_single_fasta_dna_are_normalized() -> None:
+    plain = parse_sequence_input(BALANCED_DNA.lower())
+    fasta = parse_sequence_input(f">fixture\n{BALANCED_DNA[:90]}\n{BALANCED_DNA[90:]}\n")
+
+    assert plain["normalized_sequence"] == BALANCED_DNA
+    assert fasta["normalized_sequence"] == BALANCED_DNA
+    assert fasta["fasta_header"] == "fixture"
+    assert fasta["input_type"] == "cds"
+
+
+def test_multifasta_is_rejected_without_concatenation() -> None:
+    with pytest.raises(ValueError, match="Multiple FASTA records detected"):
+        parse_sequence_input(">one\nATGGCTTAA\n>two\nATGGAATAA")
+
+
+def test_invalid_characters_and_frame_are_reported() -> None:
+    with pytest.raises(ValueError, match="Invalid sequence characters: B"):
+        parse_sequence_input("ATGBCC")
+
+    parsed = parse_sequence_input("ATGG")
+    assert parsed["input_type"] == "cds"
+    assert parsed["generation_allowed"] is False
+    assert parsed["summary"]["frame_valid"] is False
+
+
+def test_protein_is_classified_separately() -> None:
+    parsed = parse_sequence_input("MSKGEELFTGVV")
+    assert parsed["input_type"] == "protein"
+    assert parsed["summary"]["protein_length_aa"] == 12
+    assert "reverse translate" in parsed["message"]
+
+
+def test_300bp_cds_context_and_stop_policy_preserve_units() -> None:
+    parsed = parse_sequence_input(BALANCED_DNA)
+    candidate = restore_cds_stop_policy("ATG" + ("GCC" * 97) + "GAG", parsed)
+
+    assert len(BALANCED_DNA) == 300
+    assert parsed["summary"]["cds_length_bp"] == 300
+    assert parsed["summary"]["codon_count"] == 100
+    assert parsed["summary"]["protein_length_aa"] == 99
+    assert len(candidate) == 300
+    assert translate_dna(candidate).rstrip("*") == translate_dna(BALANCED_DNA).rstrip("*")
+    assert_pathway_invariants(BALANCED_DNA, candidate, parsed)
+
+
+def test_internal_stop_disables_generation() -> None:
+    parsed = parse_sequence_input("ATGGCTTAAGCTGAA")
+    assert parsed["generation_allowed"] is False
+    assert parsed["summary"]["internal_stop_count"] == 1
+
+
+def test_required_preferred_and_ignored_decisions() -> None:
+    sequence = "ATG" + ("GCT" * 30) + "GGTCTC" + ("GCT" * 10) + "TAA"
+    criteria = default_acceptance_criteria(0, 100)
+    required = evaluate_candidate(sequence, cai=0.9, criteria=criteria)
+    assert required["automated_decision"] == "FAIL"
+
+    criteria["type_iis"]["mode"] = "preferred"
+    preferred = evaluate_candidate(sequence, cai=0.9, criteria=criteria)
+    assert preferred["automated_decision"] == "CONDITIONAL_PASS"
+
+    criteria["type_iis"]["mode"] = "ignored"
+    criteria["local_gc"]["mode"] = "ignored"
+    criteria["repeats"]["mode"] = "ignored"
+    criteria["homopolymers"]["mode"] = "ignored"
+    criteria["forbidden_motifs"]["mode"] = "ignored"
+    ignored = evaluate_candidate(sequence, cai=0.9, criteria=criteria)
+    assert ignored["automated_decision"] == "PASS"
+
+
+def test_preferred_repeat_issue_is_conditional() -> None:
+    repeat = "ATGGCTGAACTGTTTGGT" * 2
+    criteria = default_acceptance_criteria(0, 100)
+    criteria["type_iis"]["mode"] = "ignored"
+    criteria["local_gc"]["mode"] = "ignored"
+    criteria["homopolymers"]["mode"] = "ignored"
+    criteria["forbidden_motifs"]["mode"] = "ignored"
+    result = evaluate_candidate(repeat, cai=0.9, criteria=criteria)
+    assert result["automated_decision"] == "CONDITIONAL_PASS"
+    assert result["preferred_warning_count"] >= 1
+
+
+def test_manual_acceptance_of_fail_requires_reason_and_retains_fail() -> None:
+    with pytest.raises(ValueError, match="written reason"):
+        apply_reviewer_disposition("FAIL", {"disposition": "accept_with_exception"})
+
+    result = apply_reviewer_disposition(
+        "FAIL",
+        {"disposition": "accept_with_exception", "reason": "Documented synthesis exception"},
+    )
+    assert result["final_state"] == "MANUALLY_ACCEPTED"
+    assert result["automated_decision"] == "FAIL"
+
+
+def test_criteria_validation_rejects_bad_mode() -> None:
+    with pytest.raises(ValueError, match="must be required"):
+        normalize_acceptance_criteria(
+            {"cai": {"mode": "blocking"}},
+            gc_min=40,
+            gc_max=55,
+        )
+
+
+def test_required_type_iis_sites_and_forbidden_fixture_are_visible() -> None:
+    fixture = "ATG" + "GGTCTC" + "CGTCTC" + "GCTCTTC" + "AATAAA" + ("A" * 10) + "TAA"
+    criteria = default_acceptance_criteria(0, 100)
+    result = evaluate_candidate(fixture, cai=0.9, criteria=criteria)
+    assert result["automated_decision"] == "FAIL"
+    assert len(result["details"]["type_iis_sites"]) >= 3
+    assert result["details"]["forbidden_motifs"]
+    assert result["details"]["longest_homopolymer"] >= 10
+
+
+def test_original_cai_is_calculated_from_the_active_reference() -> None:
+    table = load_codon_usage_table()
+    high = "ATG" + "GCC" * 4 + "TAA"
+    low = "ATG" + "GCT" * 4 + "TAA"
+    high_cai = original_cai(high, table.codon_weights)
+    low_cai = original_cai(low, table.codon_weights)
+    assert high_cai is not None and low_cai is not None
+    assert high_cai != low_cai
+
+
+def test_all_criteria_pass_returns_pass() -> None:
+    criteria = default_acceptance_criteria(0, 100)
+    for criterion in criteria.values():
+        criterion["mode"] = "ignored"
+    result = evaluate_candidate("ATGGCTGAA", cai=0.9, criteria=criteria)
+    assert result["automated_decision"] == "PASS"