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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.3.1
+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.1 (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.1 → 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.1 (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.1 → factorforge_cds-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.3.1"
+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.1 → 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.1"
+__version__ = "3.4.0"
 __author__ = "Eijex"
 
 # Auto-register engines (safe when running from source tree)

{factorforge_cds-3.3.1 → factorforge_cds-3.4.0}/src/factorforge/analysis/feasibility.py

@@ -51,6 +51,7 @@ def _cai_from_log(log_sum: float, codon_count: int) -> float:
 def _candidate_summary(
     dna_sequence: str | None,
     codon_weights: dict[str, float],
+    cai_authority: dict[str, Any],
 ) -> dict[str, Any] | None:
     if dna_sequence is None:
         return None
@@ -59,6 +60,7 @@ def _candidate_summary(
     return {
         "dna_sequence": dna_sequence,
         "cai": calculate_cai(dna_sequence, codon_weights),
+        "cai_authority": dict(cai_authority),
         "gc": calculate_gc(dna_sequence),
         "first_region_gc": calculate_first_region_gc(dna_sequence),
         "gc_window_min": min(window_values) if window_values else 0.0,
@@ -66,6 +68,20 @@ def _candidate_summary(
     }
 
 
+def _build_cai_authority(codon_reference_id: str | None) -> dict[str, Any]:
+    if codon_reference_id is None:
+        return {
+            "reference_id": None,
+            "reference_role": "cai_evaluation",
+            "reference_relationship": "unresolved",
+        }
+    return {
+        "reference_id": codon_reference_id,
+        "reference_role": "cai_evaluation",
+        "reference_relationship": "same_as_generation_reference",
+    }
+
+
 def _best_gc_under_gc_range(
     states: dict[int, float],
     protein_length: int,
@@ -104,6 +120,7 @@ def analyze_feasibility(
     target_gc_low: float = DEFAULT_GC_LOW,
     target_gc_high: float = DEFAULT_GC_HIGH,
     gc_ranges: list[tuple[float, float]] | None = None,
+    codon_reference_id: str | None = None,
 ) -> dict[str, Any]:
     """Compute exact CAI/GC feasibility over synonymous codon choices.
 
@@ -160,6 +177,7 @@ def analyze_feasibility(
 
     protein_length = len(protein)
     total_bases = protein_length * 3
+    cai_authority = _build_cai_authority(codon_reference_id)
     best_any_gc = max(states, key=lambda gc_count: states[gc_count])
     best_any_log_sum = states[best_any_gc]
     best_any_sequence = _reconstruct_sequence(backrefs, best_any_gc)
@@ -180,7 +198,7 @@ def analyze_feasibility(
             range_results[key] = {
                 "feasible": True,
                 "max_cai": _cai_from_log(states[gc_count], protein_length),
-                "best_candidate": _candidate_summary(sequence, codon_weights),
+                "best_candidate": _candidate_summary(sequence, codon_weights, cai_authority),
             }
 
     target_cai_possible = (
@@ -192,8 +210,13 @@ def analyze_feasibility(
         "protein_length": protein_length,
         "minimum_possible_gc": (min_gc_count / total_bases) * 100.0,
         "maximum_possible_gc": (max_gc_count / total_bases) * 100.0,
+        "cai_authority": dict(cai_authority),
         "maximum_achievable_cai_without_gc": _cai_from_log(best_any_log_sum, protein_length),
-        "best_candidate_without_gc": _candidate_summary(best_any_sequence, codon_weights),
+        "best_candidate_without_gc": _candidate_summary(
+            best_any_sequence,
+            codon_weights,
+            cai_authority,
+        ),
         "ranges": range_results,
         "target": {
             "cai": target_cai,
@@ -206,7 +229,11 @@ def analyze_feasibility(
                 else None
             ),
             "best_candidate": (
-                _candidate_summary(_reconstruct_sequence(backrefs, target_gc_count), codon_weights)
+                _candidate_summary(
+                    _reconstruct_sequence(backrefs, target_gc_count),
+                    codon_weights,
+                    cai_authority,
+                )
                 if target_gc_count is not None
                 else None
             ),

{factorforge_cds-3.3.1 → factorforge_cds-3.4.0}/src/factorforge/cli/main.py

@@ -154,6 +154,7 @@ def _build_dp_result(
     gc_max: float,
     cai_target: float = DEFAULT_CAI_TARGET,
     codon_table_path: Path | None = None,
+    codon_reference_id: str | None = None,
 ):
     """Run the constraint-based DP feasibility engine for a single protein sequence."""
     if objective != "feasibility_best":
@@ -171,6 +172,7 @@ def _build_dp_result(
         target_cai=cai_target,
         target_gc_low=gc_min,
         target_gc_high=gc_max,
+        codon_reference_id=codon_reference_id,
     )
     best = result["target"]["best_candidate"]
     feasible = best is not None
@@ -222,7 +224,10 @@ def _format_profile_fasta(sequence_id: str, profile: str, result) -> str:
     cai = float(result.metrics.get("cai", 0.0))
     gc = float(result.metrics.get("gc_percent", result.metrics.get("gc_content", 0.0)))
     score = float(result.metrics.get("score", 0.0))
-    header = f">{sequence_id}|profile={profile}|cai={cai:.3f}|gc={gc:.2f}|score={score:.3f}"
+    header = (
+        f">{sequence_id}|engine=profile|profile={profile}|"
+        f"cai={cai:.3f}|gc={gc:.2f}|score={score:.3f}"
+    )
     return f"{header}\n{_wrap_sequence(result.sequence)}\n"
 
 
@@ -399,7 +404,10 @@ def optimize(
             if reference_table_path is not None:
                 from factorforge.engines.profile.optimizer import RuleBasedOptimizer
 
-                optimizer = RuleBasedOptimizer(codon_table_path=str(reference_table_path))
+                optimizer = RuleBasedOptimizer(
+                    codon_table_path=str(reference_table_path),
+                    generation_reference_id=reference_id,
+                )
             else:
                 optimizer = EngineRegistry.get("profile")
             profile_results = []
@@ -436,7 +444,10 @@ def optimize(
             if reference_table_path is not None and engine == "profile":
                 from factorforge.engines.profile.optimizer import RuleBasedOptimizer
 
-                optimizer = RuleBasedOptimizer(codon_table_path=str(reference_table_path))
+                optimizer = RuleBasedOptimizer(
+                    codon_table_path=str(reference_table_path),
+                    generation_reference_id=reference_id,
+                )
             else:
                 optimizer = EngineRegistry.get(engine)
             payload = [{"id": seq_id, "sequence": seq} for seq_id, seq in fasta_records]
@@ -465,14 +476,9 @@ def optimize(
             combined_fasta = []
             for idx, result in enumerate(results):
                 seq_id = payload[idx]["id"]
-                cai = result.metrics.get("cai", 0.0)
-                gc = result.metrics.get("gc_percent", result.metrics.get("gc_content", 0.0))
-                score = result.metrics.get("score", 0.0)
-                header = (
-                    f">{seq_id}|profile={profile}|cai={float(cai):.3f}|"
-                    f"gc={float(gc):.2f}|score={float(score):.3f}"
+                combined_fasta.append(
+                    _format_profile_fasta(seq_id, profile, result).rstrip()
                 )
-                combined_fasta.append(f"{header}\n{_wrap_sequence(result.sequence)}")
             out_content = "\n".join(combined_fasta) + "\n"
 
             if output:
@@ -497,6 +503,7 @@ def optimize(
                 gc_max=gc_max,
                 cai_target=cai_target,
                 codon_table_path=reference_table_path,
+                codon_reference_id=reference_id,
             )
             dna_sequence = best["dna_sequence"]
             cai = float(best["cai"])
@@ -566,7 +573,10 @@ def optimize(
             if reference_table_path is not None and engine == "profile":
                 from factorforge.engines.profile.optimizer import RuleBasedOptimizer
 
-                optimizer = RuleBasedOptimizer(codon_table_path=str(reference_table_path))
+                optimizer = RuleBasedOptimizer(
+                    codon_table_path=str(reference_table_path),
+                    generation_reference_id=reference_id,
+                )
             else:
                 optimizer = EngineRegistry.get(engine)
 

{factorforge_cds-3.3.1 → factorforge_cds-3.4.0}/src/factorforge/core/interfaces/optimizer.py

@@ -16,7 +16,7 @@ class OptimizationResult:
     def __init__(
         self,
         sequence: str,
-        metrics: dict[str, float],
+        metrics: dict[str, Any],
         metadata: dict[str, Any] | None = None,
     ) -> None:
         self.sequence = sequence

{factorforge_cds-3.3.1 → factorforge_cds-3.4.0}/src/factorforge/data/nbenthamiana_golden_set.json

@@ -1,6 +1,10 @@
 {
     "organism": "Nicotiana benthamiana",
+    "reference_id": "nbenthamiana_golden_set_v1",
+    "reference_role": "cai_evaluation",
+    "reference_version": "1",
     "source": "N. benthamiana high-expression CDS frequencies (70%, Kazusa CodonUsage DB / NCBI) blended with RNA-seq expression-weighted codon frequencies (30%, Grosse-Holz et al. 2018 Plant Biotechnology Journal; Prudhomme et al. 2024 Plant Biotechnology Journal / PRIDE PXD042916)",
+    "source_basis": "N. benthamiana high-expression CDS frequencies (70%, Kazusa CodonUsage DB / NCBI) blended with RNA-seq expression-weighted codon frequencies (30%, Grosse-Holz et al. 2018 Plant Biotechnology Journal; Prudhomme et al. 2024 Plant Biotechnology Journal / PRIDE PXD042916)",
     "description": "Codon usage frequencies weighted toward highly expressed N. benthamiana genes (RuBisCO, ribosomal proteins, histones). Used as CAI reference weights per Sharp & Li (1987). All source data is publicly available.",
     "blend_ratio": 0.7,
     "optimal_gc_content": 42.5,

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)