factorforge-cds 3.2.6__tar.gz → 3.2.7__tar.gz

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.2.6
+Version: 3.2.7
 Summary: FactorForge - open-source CDS design and pre-synthesis sequence review engine 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.2.6 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.2.7 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/README.md

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

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/pyproject.toml

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

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/__init__.py

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

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/analysis/feasibility.py

@@ -14,14 +14,18 @@ from factorforge.analysis.metrics import (
 )
 
 
-# Defaults calibrated to nbenthamiana profile engine output distribution
-# (internal benchmark, n=49): avg CAI=0.76, avg GC=60.1% (range 55-71%).
-# DEFAULT_CAI_TARGET=0.82 aligns with industry practice (>0.8) and is achievable.
+# DEFAULT_CAI_TARGET=0.82 aligns with industry practice (>0.8) and is achievable
+# (internal benchmark, n=49, avg CAI=0.76).
+# DEFAULT_GC_LOW/HIGH = native genome-composition anchor for N. benthamiana CDS
+# (_analysis/025 STEP 2: 004 endogenous n=10 measured range 40-47%, cross-checked
+# against nbev11_cds_hc/all and qld183_v103 derived-asset GC ~42.8-43.1% and
+# external ground truth ~44%). NOT an empirically validated expression optimum —
+# this is a composition anchor, not a target to maximize toward.
 # Exported as named constants so tests/test_registry_production_sync.py can
 # strictly compare them against the registry (single source of truth).
 DEFAULT_CAI_TARGET: float = 0.82
-DEFAULT_GC_LOW: float = 55.0
-DEFAULT_GC_HIGH: float = 65.0
+DEFAULT_GC_LOW: float = 40.0
+DEFAULT_GC_HIGH: float = 47.0
 
 
 AA_TO_CODONS: dict[str, list[str]] = {}
@@ -116,7 +120,11 @@ def analyze_feasibility(
     if not protein:
         raise ValueError("protein_sequence must not be empty")
 
-    ranges = gc_ranges or [(55.0, 65.0), (50.0, 65.0), (40.0, 65.0)]
+    # Default exploration ranges: genome-grounded native anchor first, then
+    # progressively wider windows. (55.0, 65.0) is retained ONLY as an explicit
+    # non-native/high-GC option (matches legacy engine-output-calibrated band) —
+    # callers must opt in explicitly to it, it is not the production default.
+    ranges = gc_ranges or [(40.0, 47.0), (35.0, 50.0), (55.0, 65.0)]
     normalized_ranges = [
         (_normalize_gc_bound(low), _normalize_gc_bound(high)) for low, high in ranges
     ]

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/analysis/metrics.py

@@ -98,7 +98,10 @@ class CodonUsageTable:
 
 
 def _default_codon_table_path() -> Path:
-    return get_data_path() / "nbenthamiana_codons.json"
+    # Job 168 / v3.3.0 (_analysis/025): production default switched from the
+    # legacy Kazusa/SGN-derived table to the NbeV1.1 LAB-strain high-confidence
+    # derived table. See data/reference/active_codon_reference.json.
+    return get_data_path() / "profiles" / "nbev11_cds_hc_derived_codons.json"
 
 
 def load_codon_usage_table(path: Path | None = None) -> CodonUsageTable:

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/cli/main.py

@@ -164,8 +164,8 @@ def list_engines():
     type=click.Choice(["feasibility_best"], case_sensitive=False),
     help="DP objective",
 )
-@click.option("--gc-min", type=float, default=55.0, help="Minimum target GC percentage")
-@click.option("--gc-max", type=float, default=65.0, help="Maximum target GC percentage")
+@click.option("--gc-min", type=float, default=40.0, help="Minimum target GC percentage")
+@click.option("--gc-max", type=float, default=47.0, help="Maximum target GC percentage")
 @click.option("--template", "construct_template", help="Construct template name")
 @click.option("--output", "-o", help="Output file")
 @click.option("--format", "output_format", default="fasta", help="Output format (fasta, genbank)")

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/__init__.py

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

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/__init__.py

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

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/optimizer.py

@@ -20,7 +20,7 @@ class RuleBasedOptimizer(OptimizerEngine):
     """Profile-based rule optimization engine."""
 
     name = "Profile-based"
-    version = "3.2.6"
+    version = "3.2.7"
 
     def __init__(self, codon_table_path: str | None = None) -> None:
         """
@@ -122,12 +122,16 @@ class RuleBasedOptimizer(OptimizerEngine):
             cai = translator.calculate_cai(optimized_dna)
             gc = translator.calculate_gc_content(optimized_dna)
             score = calculate_composite_score(
-                cai=cai, gc=gc, sequence=optimized_dna, profile=profile_value
+                cai=cai, gc=gc, sequence=optimized_dna, profile=profile_value, host=host
             )
             candidates = [{"sequence": optimized_dna, "cai": cai, "gc": gc, "score": score}]
         else:
+            translate_kwargs = {
+                k: v for k, v in kwargs.items()
+                if k not in ("scan_mode", "scan_include", "scan_exclude")
+            }
             candidates = translator.generate_candidates(
-                processed_seq, profile=opt_profile, n=1, seed=seed
+                processed_seq, profile=opt_profile, n=1, seed=seed, **translate_kwargs
             )
             if not candidates:
                 raise ValueError("No candidates generated for input sequence.")

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/pipeline.py

@@ -192,7 +192,8 @@ class OptimizationPipeline:
             cai = translator.calculate_cai(optimized_dna)
             gc = translator.calculate_gc_content(optimized_dna)
             score = calculate_composite_score(
-                cai=cai, gc=gc, sequence=optimized_dna, profile=effective_profile
+                cai=cai, gc=gc, sequence=optimized_dna, profile=effective_profile,
+                host=effective_host,
             )
             candidate_metrics = {"cai": cai, "gc": gc, "score": score}
         else:
@@ -244,6 +245,7 @@ class OptimizationPipeline:
                     gc=candidate_metrics["gc"],
                     sequence=optimized_dna,
                     profile=effective_profile,
+                    host=effective_host,
                 )
                 logger.info(
                     f"Dinucleotide reduction [{dinu_fix['mode']}]: "

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/rules/reverse_translator.py

@@ -15,12 +15,16 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, cast
 
-from factorforge.engines.profile.scoring import GC_OPT_MID, calculate_composite_score
+from factorforge.engines.profile.scoring import (
+    calculate_composite_score,
+    resolve_host_gc_range,
+)
 from factorforge.engines.profile.utils import (
     build_aa_to_codons_map,
     calculate_gc,
     get_data_path,
     load_golden_set,
+    resolve_host_codon_table_path,
 )
 from factorforge.utils.exceptions import EmptyCandidateError
 
@@ -66,7 +70,7 @@ class ReverseTranslator:
         if codon_table_path is None:
             # Use centralized data path management
             data_dir = get_data_path()
-            codon_table_path = data_dir / f"{host}_codons.json"
+            codon_table_path = resolve_host_codon_table_path(host, data_dir)
 
         self.codon_table: dict[str, Any] = self._load_codon_table(codon_table_path)
         self.aa_to_codons: dict[str, list[tuple[str, float]]] = self._build_aa_to_codons_map()
@@ -370,10 +374,15 @@ class ReverseTranslator:
         Balanced profile: CAI first, GC balanced
 
         - Preferred codon ratio: 70%
-        - Target GC: 55-65% (internal benchmark: avg output 60.1%)
+        - Target GC: host composition band (nbenthamiana: 40-47%, native
+          genome-composition anchor; see _analysis/025 STEP 2 and
+          engines/profile/scoring.py GC_OPT_MIN/MAX. Not an empirically
+          validated expression optimum. Other hosts: resolve_host_gc_range()
+          default, unchanged from pre-v3.3.0 behavior.)
         """
-        target_gc_min = kwargs.get("target_gc_min", 55)
-        target_gc_max = kwargs.get("target_gc_max", 65)
+        _host_gc_min, _host_gc_max = resolve_host_gc_range(self.host)
+        target_gc_min = kwargs.get("target_gc_min", _host_gc_min)
+        target_gc_max = kwargs.get("target_gc_max", _host_gc_max)
         preferred_ratio = kwargs.get("preferred_ratio", 0.7)
         max_attempts = kwargs.get("max_gc_attempts", 10)
         if max_attempts < 1:
@@ -443,19 +452,19 @@ class ReverseTranslator:
         """GC-Target profile: drive global GC toward a configurable target.
 
         Targets the caller-supplied ``target_gc`` if provided, otherwise the
-        host-profile GC midpoint (GC_OPT_MID = 60% for N. benthamiana). To target
-        a lower GC (e.g. for specific vector requirements), pass target_gc explicitly.
+        active host's composition midpoint (resolve_host_gc_range(self.host);
+        43.5% for nbenthamiana since v3.3.0 / _analysis/025, 60.0% for other
+        hosts pending their own host-specific analysis). To target a different
+        GC (e.g. for specific vector requirements), pass target_gc explicitly.
 
         - GC constraint first
         - CAI may be sacrificed
         - Balance local window GC (50 bp)
-
-        TODO: GC_OPT_MID is currently a single N. benthamiana-calibrated constant.
-        When per-host GC profiles are added, source the default from the active host.
         """
         target_gc = kwargs.get("target_gc")
         if target_gc is None:
-            target_gc = GC_OPT_MID
+            _host_gc_min, _host_gc_max = resolve_host_gc_range(self.host)
+            target_gc = (_host_gc_min + _host_gc_max) / 2
 
         dna_seq: list[str] = []
 
@@ -507,9 +516,14 @@ class ReverseTranslator:
             raise ValueError("max_attempts must be >= 1")
         last_seq = ""
 
+        balanced_kwargs = {
+            k: v for k, v in kwargs.items() if k in ("target_gc_min", "target_gc_max", "max_gc_attempts")
+        }
+        balanced_kwargs["preferred_ratio"] = 0.6
+
         for attempt in range(max_attempts):
             # Start with Balanced strategy
-            dna_seq = self._balanced_translate(protein_seq, preferred_ratio=0.6)
+            dna_seq = self._balanced_translate(protein_seq, **balanced_kwargs)
             last_seq = dna_seq
 
             # Check restriction sites (forward + reverse complement)
@@ -710,6 +724,7 @@ class ReverseTranslator:
                 gc=gc,
                 sequence=dna_seq,
                 profile=profile.value,
+                host=self.host,
                 **kwargs,
             )
             return {"sequence": dna_seq, "cai": cai, "gc": gc, "score": score}

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/rules/rule_engine.py

@@ -358,10 +358,12 @@ class RuleEngine:
 
         This is a LOCAL synthesis/extreme-window guard (default 25-75% over a
         50 bp window), NOT the global GC target. Global GC is governed separately
-        by the scoring band (GC_OPT_MIN/MAX, ~55-65%) and the API/DP gc_min/gc_max
-        constraints. The wide 25-75% band intentionally flags only synthesis-hostile
-        local windows; narrowing it toward the global optimum would raise false
-        positives against the engine's own output distribution (internal benchmark: 55-71%).
+        by the scoring band (GC_OPT_MIN/MAX, native genome-composition anchor
+        ~40-47%, see _analysis/025 STEP 2) and the API/DP gc_min/gc_max
+        constraints. The wide 25-75% local band is an independent synthesis/
+        hairpin-risk guard (registry `gc_extreme_local_window`), not derived from
+        or coupled to the global GC target — narrowing it is a separate decision
+        from the global band retarget and is out of scope here.
 
         Args:
             seq: DNA sequence

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/scoring.py

@@ -12,16 +12,43 @@ from typing import Any
 logger = logging.getLogger(__name__)
 
 # GC band for N. benthamiana codon-optimized sequences.
-# Benchmark (internal, n=49): balanced profile output average GC% = 60.1%
-# (range 55-71%). The genome-wide average (~42%) reflects all genes, not the
-# high-expression codon table which exhibits 3rd-position GC bias.
-# These constants define the acceptable band — sequences within [GC_OPT_MIN, GC_OPT_MAX]
-# receive full GC score; outside the band the score decays linearly.
-GC_OPT_MIN = 55.0
-GC_OPT_MAX = 65.0
-GC_OPT_MID = 60.0  # kept for gc_target point-scoring and viral_delivery centering
+# Native genome-composition anchor (_analysis/025 STEP 2: 004 endogenous CDS
+# n=10 measured range 40-47%; cross-checked against nbev11_cds_hc/all and
+# qld183_v103 derived-asset GC ~42.8-43.1% and external ground truth ~44%).
+# NOT an empirically validated expression optimum — this is a composition
+# anchor, not a target to maximize toward. Sequences within [GC_OPT_MIN,
+# GC_OPT_MAX] receive full GC score; outside the band the score decays linearly.
+GC_OPT_MIN = 40.0
+GC_OPT_MAX = 47.0
+GC_OPT_MID = 43.5  # kept for gc_target point-scoring and viral_delivery centering
 GC_DECAY_WIDTH = 20.0  # percentage points outside band before score reaches 0.0
 
+# Job 168 / v3.3.0 (_analysis/025) scoped the genome-composition re-derivation
+# to N. benthamiana only. Other hosts (e.g. ntabacum/BY-2) keep the pre-v3.3.0
+# global default (55-65%, internal benchmark n=49 avg GC=60.1%) until they get
+# their own host-specific genome-composition analysis — they must NOT silently
+# inherit GC_OPT_MIN/MAX, which is an N.-benthamiana-specific anchor.
+GC_RANGE_DEFAULT: tuple[float, float] = (55.0, 65.0)
+GC_RANGES_BY_HOST: dict[str, tuple[float, float]] = {
+    "nbenthamiana": (GC_OPT_MIN, GC_OPT_MAX),
+}
+
+
+def resolve_host_gc_range(host: str | None) -> tuple[float, float]:
+    """Resolve the (gc_min, gc_max) composition band for a host.
+
+    nbenthamiana uses the _analysis/025 native genome-composition anchor.
+    Any other host (including unknown ones) keeps the pre-v3.3.0 global
+    default band until it gets its own host-specific analysis.
+    """
+    return GC_RANGES_BY_HOST.get(host or "nbenthamiana", GC_RANGE_DEFAULT)
+
+
+def resolve_host_gc_mid(host: str | None) -> float:
+    """Resolve the GC band midpoint for a host (see resolve_host_gc_range)."""
+    gc_min, gc_max = resolve_host_gc_range(host)
+    return (gc_min + gc_max) / 2
+
 # ViennaRNA availability cache
 _vienna_available: bool | None = None
 
@@ -45,7 +72,12 @@ class ScoringConfig:
     use_mfe: bool = True
 
     def __post_init__(self) -> None:
-        """Normalize weights to sum to 1.0."""
+        """Validate inputs, then normalize weights to sum to 1.0."""
+        for field_name in ("w_cai", "w_gc", "w_mfe", "w_dinuc", "w_syncodonlm"):
+            if getattr(self, field_name) < 0:
+                raise ValueError(f"{field_name} must be >= 0, got {getattr(self, field_name)}")
+        if self.gc_min > self.gc_max:
+            raise ValueError(f"gc_min ({self.gc_min}) must be <= gc_max ({self.gc_max})")
         self._normalize()
 
     def _normalize(self) -> None:
@@ -110,6 +142,20 @@ def _check_vienna_available() -> bool:
     return _vienna_available
 
 
+# 170-fix: ViennaRNA's RNA.fold() uses Zuker's MFE algorithm, O(n^3) time /
+# O(n^2) memory — there was previously no length guard anywhere in the
+# calculate_mfe() call chain, so a single request at/under the existing
+# public API length limits (5000aa/15000bp) could pin a CPU core for minutes
+# (algorithmic-complexity DoS, CWE-407; confirmed via faulthandler stack
+# traces + an isolated RNA.fold() timing curve: 1000nt ~2.2s, 2000nt ~9.8s,
+# 3000nt ~24.6s). calculate_mfe() is called twice per optimize() call
+# (once for scoring, once independently for compute_mfe_evidence()
+# provenance), so the real per-request cost is ~2x this curve. 1000nt
+# (~333aa) keeps worst-case cost to roughly 4-5s even with that doubling,
+# while still covering most realistic single-protein CDS design requests.
+MFE_MAX_SEQUENCE_LENGTH = 1000
+
+
 def calculate_mfe(sequence: str) -> float | None:
     """
     Calculate minimum free energy (MFE) using ViennaRNA.
@@ -118,11 +164,22 @@ def calculate_mfe(sequence: str) -> float | None:
         sequence: DNA or RNA sequence.
 
     Returns:
-        MFE in kcal/mol, or None if ViennaRNA is not available.
+        MFE in kcal/mol, or None if ViennaRNA is not available or the
+        sequence exceeds MFE_MAX_SEQUENCE_LENGTH.
     """
     if not _check_vienna_available():
         return None
 
+    if len(sequence) > MFE_MAX_SEQUENCE_LENGTH:
+        logger.warning(
+            "Sequence length (%d nt) exceeds MFE_MAX_SEQUENCE_LENGTH (%d nt); "
+            "skipping global MFE calculation to avoid an unbounded ViennaRNA "
+            "RNA.fold() runtime (O(n^3)). MFE scoring falls back to a neutral, "
+            "zero-weighted contribution for this candidate (170-fix).",
+            len(sequence), MFE_MAX_SEQUENCE_LENGTH,
+        )
+        return None
+
     try:
         import RNA
 
@@ -139,24 +196,34 @@ def normalize_mfe(mfe: float, seq_length: int) -> float:
     """
     Normalize MFE to 0-1 range where 1 = no structure (favorable).
 
-    Uses empirical scaling: MFE per nucleotide typically ranges from
-    -0.5 to 0.0 kcal/mol/nt for mRNA coding sequences.
+    Clamp range calibrated empirically in analysis 011
+    (eijex-workspace/_analysis/2026-06-26/011-mfe-clamp-calibration):
+    measured MFE/nt across 135 FactorForge outputs (N. benthamiana +
+    BY-2 hosts, 5 profiles) ranged -0.4064 to -0.1338 (combined 5th/95th
+    percentile -0.3839/-0.1760). The range below widens that empirical
+    percentile by a margin on both sides to avoid saturating ~10% of
+    future sequences at the score floor/ceiling.
 
     Args:
         mfe: Minimum free energy in kcal/mol.
         seq_length: Sequence length in nucleotides.
 
     Returns:
-        Normalized MFE score (0-1, higher = less structured = better for translation).
+        Normalized MFE score (0-1) under this computational normalization,
+        where a higher value represents a less negative whole-CDS MFE/nt.
+        This is a Tier-0 computational heuristic only (see
+        eijex-validationHub/docs/CLAIM_EVIDENCE_BENCHMARK_MODEL.md §4) — no
+        biological interpretation (translation efficiency, mRNA stability,
+        or expression outcome) is implied or validated.
     """
     if seq_length == 0:
         return 0.5
 
     mfe_per_nt = mfe / seq_length
-    # Clamp to expected range [-0.5, 0.0]
-    clamped = max(-0.5, min(0.0, mfe_per_nt))
-    # Map to [0, 1] where 0.0 kcal/mol/nt → 1.0 and -0.5 → 0.0
-    return 1.0 + (clamped / 0.5)
+    # Clamp to empirically calibrated range [-0.40, -0.15] (analysis 011)
+    clamped = max(-0.40, min(-0.15, mfe_per_nt))
+    # Map to [0, 1] where -0.15 kcal/mol/nt → 1.0 and -0.40 → 0.0
+    return (clamped + 0.40) / 0.25
 
 
 def gc_band_score(
@@ -210,6 +277,7 @@ def calculate_composite_score(
     sequence: str | None = None,
     config: ScoringConfig | None = None,
     profile: str | None = None,
+    host: str | None = None,
     **kwargs: Any,
 ) -> float:
     """Calculate multidimensional composite score.
@@ -238,7 +306,12 @@ def calculate_composite_score(
         profile_name = (profile or "balanced").lower()
         config = PROFILE_SCORING_CONFIGS.get(profile_name)
         if config is None:
-            config = PROFILE_SCORING_CONFIGS["balanced"]
+            supported = ", ".join(sorted(PROFILE_SCORING_CONFIGS))
+            raise ValueError(
+                f"Unknown profile: {profile_name}. Supported profiles: {supported}"
+            )
+        if "target_gc" in kwargs and profile_name != "gc_target":
+            raise ValueError("target_gc is only valid for the gc_target profile")
 
     # Component 1: CAI (already 0-1)
     cai_score = max(0.0, min(1.0, cai))
@@ -250,7 +323,15 @@ def calculate_composite_score(
         tgt = float(kwargs["target_gc"])
         gc_score = gc_band_score(gc, tgt - 5.0, tgt + 5.0, config.gc_decay_width)
     else:
-        gc_score = gc_band_score(gc, config.gc_min, config.gc_max, config.gc_decay_width)
+        gc_min, gc_max = config.gc_min, config.gc_max
+        # Profiles that haven't customized the band (still on the
+        # GC_OPT_MIN/MAX default) follow the active host's composition band.
+        # Profiles with an explicit band override (e.g. viral_delivery) keep
+        # it regardless of host — that override is profile-specific, not a
+        # host default.
+        if (gc_min, gc_max) == (GC_OPT_MIN, GC_OPT_MAX):
+            gc_min, gc_max = resolve_host_gc_range(host)
+        gc_score = gc_band_score(gc, gc_min, gc_max, config.gc_decay_width)
 
     # Component 3: MFE (optional)
     mfe_score = 0.5  # neutral default
@@ -336,6 +417,14 @@ def compute_mfe_evidence(
         reason = "MFE was not computed because no sequence was provided."
     elif not _check_vienna_available():
         reason = "MFE was not computed because ViennaRNA is unavailable in this environment."
+    elif len(sequence) > MFE_MAX_SEQUENCE_LENGTH:
+        # 170-fix: distinguish a deliberate length-based skip from an actual
+        # fold failure — the generic "computation failed" message below would
+        # otherwise mislead a caller into thinking something is broken.
+        reason = (
+            f"MFE was skipped because the sequence ({len(sequence)} nt) exceeds "
+            f"the {MFE_MAX_SEQUENCE_LENGTH} nt limit for global MFE folding."
+        )
     else:
         mfe_value = calculate_mfe(sequence)
         if mfe_value is None:

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge/engines/profile/utils.py

@@ -115,6 +115,23 @@ def calculate_dinucleotide_ratio(sequence: str, dinucleotide: str = "CG") -> flo
     return observed / expected
 
 
+# Job 168 / v3.3.0 (_analysis/025): host -> production-default codon table file
+# overrides. nbenthamiana moved from the legacy {host}_codons.json convention to
+# the NbeV1.1 LAB-strain derived table. See data/reference/active_codon_reference.json.
+# The legacy file itself (nbenthamiana_codons.json) is left untouched on disk for
+# historical benchmark replay (benchmarks/run_benchmark.py --codon-table-path).
+_HOST_CODON_TABLE_OVERRIDES: dict[str, str] = {
+    "nbenthamiana": "profiles/nbev11_cds_hc_derived_codons.json",
+}
+
+
+def resolve_host_codon_table_path(host: str, codon_tables_dir: Path) -> Path:
+    """Resolve the production-default codon table file path for a host."""
+    override = _HOST_CODON_TABLE_OVERRIDES.get(host)
+    filename = override or f"{host}_codons.json"
+    return codon_tables_dir / filename
+
+
 def load_codon_table(organism: str, codon_tables_dir: Path) -> dict[str, Any]:
     """Load codon usage table for organism.
 
@@ -128,8 +145,10 @@ def load_codon_table(organism: str, codon_tables_dir: Path) -> dict[str, Any]:
     Raises:
         FileNotFoundError: If codon table file not found.
     """
-    filename = organism if organism.endswith(".json") else f"{organism}_codons.json"
-    codon_table_path = codon_tables_dir / filename
+    if organism.endswith(".json"):
+        codon_table_path = codon_tables_dir / organism
+    else:
+        codon_table_path = resolve_host_codon_table_path(organism, codon_tables_dir)
 
     with open(codon_table_path, "r", encoding="utf-8") as handle:
         return cast(dict[str, Any], json.load(handle))

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/src/factorforge_cds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.2.6
+Version: 3.2.7
 Summary: FactorForge - open-source CDS design and pre-synthesis sequence review engine 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.2.6 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.2.7 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/tests/test_benchmark_codon_table_metadata.py

@@ -110,7 +110,38 @@ def test_smoke_summary_contains_codon_table_fields(tmp_path):
     ]:
         assert field in data, f"Missing codon table field in smoke summary JSON: {field}"
 
-    assert data["codon_table_id"] == "nbenthamiana_legacy_kazusa_sgn_v101"
+    # No --codon-table-path override ⇒ codon_table_id must reflect whichever
+    # asset is actually the current production default (Job 168 / v3.3.0,
+    # _analysis/025 — see data/reference/active_codon_reference.json), not a
+    # hardcoded legacy literal.
+    active_ref = json.loads(
+        (ROOT / "data" / "reference" / "active_codon_reference.json").read_text(encoding="utf-8")
+    )
+    assert data["codon_table_id"] == active_ref["active_codon_table_id"]
+
+
+def test_smoke_summary_contains_vienna_rna_active(tmp_path):
+    """Every future run must record whether ViennaRNA (and thus MFE-weighted
+    candidate selection) was active, per analysis 011's provenance-gap finding."""
+    from benchmarks.run_benchmark import run
+
+    out_csv = tmp_path / "results.csv"
+    out_md = tmp_path / "summary.md"
+    run(
+        dataset="synthetic",
+        mode="smoke",
+        out_csv=out_csv,
+        out_md=out_md,
+        proteins_fasta=ROOT / "tests" / "fixtures" / "small_proteins.fasta",
+        native_fasta=ROOT / "tests" / "fixtures" / "small_native_cds.fasta",
+    )
+    summary_json = tmp_path / "benchmark_summary.json"
+    data = json.loads(summary_json.read_text(encoding="utf-8"))
+    assert isinstance(data.get("vienna_rna_active"), bool), (
+        "vienna_rna_active must be a bool recording whether ViennaRNA was "
+        "available (and therefore could affect MFE-weighted candidate "
+        "selection) during this benchmark run"
+    )
 
 
 # --- raw FASTA / genome files must not be committed ---

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/tests/test_registry_production_sync.py

@@ -74,3 +74,59 @@ def test_aa_identity_policy_sync():
     # registry says identity must be 1.0 — passing case confirms
     ok = validate_cds_output("MKT", "ATGAAAACC")
     assert ok["passed"] and ok["aa_identity"] == registry_val
+
+
+# ── codon_reference source-of-truth sync (Job 168 / v3.3.0, _analysis/025) ────
+
+def test_codon_reference_active_sync_with_active_reference_file():
+    """registry's codon_reference.active block must match
+    data/reference/active_codon_reference.json (the file run_benchmark.py
+    reads at runtime) — both describe "what is the current production
+    default", and must not drift apart."""
+    import json
+    from pathlib import Path
+
+    root = Path(__file__).resolve().parents[1]
+    registry_active = _resolve("codon_reference.active")
+    active_ref = json.loads(
+        (root / "data" / "reference" / "active_codon_reference.json").read_text(encoding="utf-8")
+    )
+    assert registry_active["id"] == active_ref["active_codon_table_id"]
+    assert registry_active["asset_type"] == active_ref["active_asset_type"]
+    assert registry_active["codon_reference_contract_version"] == active_ref[
+        "codon_reference_contract_version"
+    ]
+    # active_codon_reference.json doesn't carry sha256 directly — cross-check
+    # via the file it points at instead.
+    import hashlib
+    table_path = root / active_ref["file"]
+    assert registry_active["sha256"] == hashlib.sha256(table_path.read_bytes()).hexdigest()
+
+
+def test_codon_reference_active_sync_with_v2_manifest():
+    """registry's codon_reference.active block must match the schema-conformant
+    v2 manifest file's facts (asset_type, sha256, source_status)."""
+    import json
+    from pathlib import Path
+
+    registry_active = _resolve("codon_reference.active")
+    manifest = json.loads(
+        (Path(__file__).resolve().parents[1] / "data" / "reference"
+         / "codon_table_manifest_nbev11_hc_v2.json").read_text(encoding="utf-8")
+    )
+    assert registry_active["id"] == manifest["codon_table_id"]
+    assert registry_active["sha256"] == manifest["sha256"]
+    assert registry_active["asset_type"] == manifest["asset_type"]
+    assert registry_active["source_status"] == manifest["source_status"]
+
+
+def test_codon_reference_active_table_sha256_matches_production_default():
+    """The sha256 recorded for the active codon_reference must match the
+    actual file the production engine resolves to by default."""
+    from factorforge.engines.profile.utils import get_data_path, resolve_host_codon_table_path
+    import hashlib
+
+    registry_active = _resolve("codon_reference.active")
+    resolved_path = resolve_host_codon_table_path("nbenthamiana", get_data_path())
+    actual_sha256 = hashlib.sha256(resolved_path.read_bytes()).hexdigest()
+    assert registry_active["sha256"] == actual_sha256

{factorforge_cds-3.2.6 → factorforge_cds-3.2.7}/tests/test_worked_example.py

@@ -61,7 +61,14 @@ def test_sfgfp_sequence_no_x_residues():
 # ---------------------------------------------------------------------------
 
 def test_run_example_deterministic():
-    """run_example.py (no --freeze) must exit 0 when frozen outputs exist."""
+    """run_example.py (no --freeze) must exit 0 when frozen outputs exist.
+
+    Job 168 / v3.3.0 (_analysis/025): this script is explicitly pinned to the
+    legacy v1 codon reference (GC 55-65%) regardless of the engine's current
+    production default, so this reproducibility check stays valid forever.
+    See run_example_v2_smoke.py / test_run_example_v2_smoke_succeeds for the
+    current-default (v2) path.
+    """
     result = subprocess.run(
         [sys.executable, str(EXAMPLE_DIR / "run_example.py")],
         capture_output=True,
@@ -74,6 +81,26 @@ def test_run_example_deterministic():
     assert "OK" in result.stdout, "expected 'OK' in output"
 
 
+def test_run_example_v2_smoke_succeeds():
+    """run_example_v2_smoke.py (current production default) must exit 0.
+
+    No frozen-output comparison — this only checks that the v2 path runs
+    end-to-end and reports correct provenance (Job 168 / v3.3.0, _analysis/025).
+    """
+    result = subprocess.run(
+        [sys.executable, str(EXAMPLE_DIR / "run_example_v2_smoke.py")],
+        capture_output=True,
+        text=True,
+        cwd=str(ROOT),
+    )
+    assert result.returncode == 0, (
+        f"run_example_v2_smoke.py exited {result.returncode}\n"
+        f"stdout:{result.stdout}\nstderr:{result.stderr}"
+    )
+    assert "OK" in result.stdout
+    assert "nbenthamiana_nbev11_hc_v2" in result.stdout
+
+
 # ---------------------------------------------------------------------------
 # TC3 — design_package.json claim boundary
 # ---------------------------------------------------------------------------