factorforge-cds 3.1.7__tar.gz → 3.1.9__tar.gz

{factorforge_cds-3.1.7/src/factorforge_cds.egg-info → factorforge_cds-3.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.1.7
+Version: 3.1.9
 Summary: FactorForge - open-source constraint-based CDS design engine by Eijex.
 Author-email: Eijex <eijex.lab@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -107,7 +107,7 @@ FactorForge predictions are **in-silico only** and have not been experimentally
 ## Citing
 
 ```
-FactorForge v3.1.7 (2026). Open-source constraint-based CDS design engine.
+FactorForge v3.1.9 (2026). Open-source constraint-based CDS design engine.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/README.md

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

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.1.7"
+version = "3.1.9"
 description = "FactorForge - open-source constraint-based CDS design engine by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -56,6 +56,7 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 norecursedirs = ["archive"]
+pythonpath = ["src"]
 
 [tool.ruff]
 line-length = 100

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/__init__.py

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

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/analysis/feasibility.py

@@ -88,9 +88,9 @@ def _reconstruct_sequence(
 def analyze_feasibility(
     protein_sequence: str,
     codon_weights: dict[str, float],
-    target_cai: float = 0.92,
-    target_gc_low: float = 41.0,
-    target_gc_high: float = 44.0,
+    target_cai: float = 0.82,
+    target_gc_low: float = 55.0,
+    target_gc_high: float = 65.0,
     gc_ranges: list[tuple[float, float]] | None = None,
 ) -> dict[str, Any]:
     """Compute exact CAI/GC feasibility over synonymous codon choices.
@@ -98,12 +98,16 @@ def analyze_feasibility(
     The dynamic program keeps the best log-CAI sequence for each reachable
     global GC count. This is exact for global GC and CAI under the supplied
     codon weights.
+
+    Defaults calibrated to nbenthamiana profile engine output distribution
+    (analysis 004, n=49): avg CAI=0.76, avg GC=60.1% (range 55-71%).
+    target_cai=0.82 aligns with industry practice (>0.8) and is achievable.
     """
     protein = "".join(protein_sequence.upper().split()).rstrip("*")
     if not protein:
         raise ValueError("protein_sequence must not be empty")
 
-    ranges = gc_ranges or [(41.0, 44.0), (40.0, 50.0), (40.0, 55.0)]
+    ranges = gc_ranges or [(55.0, 65.0), (50.0, 65.0), (40.0, 65.0)]
     normalized_ranges = [
         (_normalize_gc_bound(low), _normalize_gc_bound(high)) for low, high in ranges
     ]

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/analysis/metrics.py

@@ -11,6 +11,12 @@ from typing import Any
 
 from factorforge.engines.profile.utils import get_data_path
 
+# Homopolymer thresholds — two distinct concerns, intentionally different values.
+# Expression stability: AT-rich runs ≥6 nt can resemble instability elements (ARE).
+# Synthesis/manufacturing: runs ≥8 nt are flagged by gene synthesis vendors as difficult.
+HOMOPOLYMER_EXPRESSION_WARN_NT = 6
+HOMOPOLYMER_SYNTHESIS_WARN_NT = 8
+
 
 STANDARD_GENETIC_CODE: dict[str, str] = {
     "TTT": "F",
@@ -271,6 +277,32 @@ def calculate_cai(sequence: str, codon_weights: dict[str, float]) -> float:
     return math.exp(log_sum / count) if count else 0.0
 
 
+def calculate_dinucleotide_score(
+    sequence: str,
+    cpg_weight: float = 0.0,
+    tpa_weight: float = 1.0,
+) -> float:
+    """Score dinucleotide avoidance.
+
+    Plant default: CpG inactive (cpg_weight=0.0), only TpA is penalized.
+    Mammalian opt-in: set cpg_weight=1.0 and tpa_weight=1.0 to penalize both.
+    """
+    from factorforge.engines.profile.utils import calculate_dinucleotide_ratio
+
+    if len(sequence) < 6:
+        return 1.0
+
+    total_weight = cpg_weight + tpa_weight
+    if total_weight == 0:
+        return 1.0
+
+    cpg_ratio = calculate_dinucleotide_ratio(sequence, "CG")
+    tpa_ratio = calculate_dinucleotide_ratio(sequence, "TA")
+    cpg_score = max(0.0, 1.0 - cpg_ratio / 2.0)
+    tpa_score = max(0.0, 1.0 - tpa_ratio / 2.0)
+    return (cpg_weight * cpg_score + tpa_weight * tpa_score) / total_weight
+
+
 def codon_usage_profile(sequence: str) -> dict[str, dict[str, float | int | str]]:
     """Return codon counts and frequencies for a DNA sequence."""
     codons = _codons(sequence)
@@ -286,8 +318,19 @@ def codon_usage_profile(sequence: str) -> dict[str, dict[str, float | int | str]
     return profile
 
 
-def detect_homopolymers(sequence: str, max_run: int = 6) -> list[dict[str, Any]]:
-    """Detect runs whose length is greater than or equal to max_run."""
+def detect_homopolymers(
+    sequence: str,
+    max_run: int = HOMOPOLYMER_EXPRESSION_WARN_NT,
+) -> list[dict[str, Any]]:
+    """Detect homopolymer runs for expression stability evaluation.
+
+    Uses HOMOPOLYMER_EXPRESSION_WARN_NT (default 6 nt) — AT-rich runs of this
+    length can resemble AU-rich instability elements (ARE) and affect mRNA
+    stability in plant expression systems.
+
+    For synthesis/manufacturing risk, see RuleEngine.scan_homopolymers()
+    which uses HOMOPOLYMER_SYNTHESIS_WARN_NT (8 nt).
+    """
     if max_run <= 1:
         raise ValueError("max_run must be > 1")
 
@@ -303,17 +346,27 @@ def detect_homopolymers(sequence: str, max_run: int = 6) -> list[dict[str, Any]]
             continue
         run_length = index - run_start
         if run_length >= max_run:
-            findings.append(
-                {"start": run_start, "end": index, "base": run_base, "length": run_length}
-            )
+            findings.append({
+                "start": run_start,
+                "end": index,
+                "base": run_base,
+                "length": run_length,
+                "context": "expression_stability",
+                "threshold_nt": max_run,
+            })
         run_base = base
         run_start = index
 
     run_length = len(seq) - run_start
     if run_length >= max_run:
-        findings.append(
-            {"start": run_start, "end": len(seq), "base": run_base, "length": run_length}
-        )
+        findings.append({
+            "start": run_start,
+            "end": len(seq),
+            "base": run_base,
+            "length": run_length,
+            "context": "expression_stability",
+            "threshold_nt": max_run,
+        })
     return findings
 
 

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/__init__.py

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

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/__init__.py

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

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/exporter.py

@@ -6,8 +6,10 @@ GenBank and FASTA export module (P0-5)
 from __future__ import annotations
 
 import hashlib
+import json
 from datetime import datetime
 from io import StringIO
+from pathlib import Path
 from typing import Any
 
 
@@ -25,6 +27,26 @@ class SequenceExporter:
         """Initialize"""
         pass
 
+    def host_species(self, metadata: dict[str, Any]) -> str:
+        """Resolve host species from feature_registry.json when possible."""
+        if metadata.get("organism"):
+            return str(metadata["organism"])
+
+        host = str(
+            metadata.get("host_profile") or metadata.get("host") or "nbenthamiana"
+        ).strip().lower()
+        host_aliases = {"ntabacum": "by2"}
+        registry_key = host_aliases.get(host, host)
+        registry_path = Path(__file__).resolve().parents[4] / "scripts" / "feature_registry.json"
+
+        try:
+            registry = json.loads(registry_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            registry = {}
+
+        species = registry.get("hosts", {}).get(registry_key, {}).get("species")
+        return str(species or "Nicotiana benthamiana")
+
     def generate_run_id(self, sequence: str, params: dict[str, Any]) -> str:
         """
         Generate a reproducible run_id
@@ -69,6 +91,7 @@ class SequenceExporter:
                 "run_id": "abc12345",
                 "timestamp": "2026-01-22T12:00:00",
                 "organism": "Nicotiana benthamiana",
+                "host_profile": "nbenthamiana",
                 "gene_name": "GFP",
                 "violations_fixed": [...],
                 "warnings": [...]
@@ -99,7 +122,7 @@ class SequenceExporter:
         run_id = metadata.get("run_id", self.generate_run_id(sequence, metadata))
         timestamp = metadata.get("timestamp", datetime.now().strftime("%Y%m%d"))
         gene_name = metadata.get("gene_name", "optimized_gene")
-        organism = metadata.get("organism", "Nicotiana benthamiana")
+        organism = self.host_species(metadata)
 
         # Build locus ID
         locus_id = f"PFORM_{run_id}_{timestamp}"
@@ -355,7 +378,7 @@ class SequenceExporter:
             "--- Optimization Settings ---",
             f"Profile: {metadata.get('profile', 'N/A')}",
             f"Assembly Standard: {metadata.get('assembly_standard', 'None')}",
-            f"Organism: {metadata.get('organism', 'Nicotiana benthamiana')}",
+            f"Organism: {self.host_species(metadata)}",
             "",
         ]
 

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/optimizer.py

@@ -9,7 +9,7 @@ from factorforge.core.interfaces import OptimizationResult, OptimizerEngine
 from .exporter import SequenceExporter
 from .rules.reverse_translator import OptimizationProfile, ReverseTranslator
 from .rules.rule_engine import RuleEngine
-from .scoring import calculate_composite_score
+from .scoring import calculate_composite_score, compute_mfe_evidence
 from .validator import InputValidator
 
 
@@ -17,7 +17,7 @@ class RuleBasedOptimizer(OptimizerEngine):
     """Profile-based rule optimization engine."""
 
     name = "Profile-based"
-    version = "3.1.7"
+    version = "3.1.9"
 
     def __init__(self) -> None:
         self.validator = InputValidator()
@@ -117,6 +117,10 @@ class RuleBasedOptimizer(OptimizerEngine):
             "score": candidates[0]["score"],
             "violations": sum(len(v) for v in scan_results.values()),
         }
+        # MFE provenance: expose whether MFE was actually computed so downstream
+        # artifacts (API response, Design Package) never report an uncomputed
+        # MFE as a misleading 0.0 (016 audit). Score value is unchanged.
+        metrics.update(compute_mfe_evidence(optimized_dna, profile=profile_value))
 
         return OptimizationResult(
             sequence=optimized_dna,

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/pipeline.py

@@ -18,9 +18,14 @@ from factorforge.engines.profile.rules.reverse_translator import (
     ReverseTranslator,
 )
 from factorforge.engines.profile.rules.rule_engine import RuleEngine
-from factorforge.engines.profile.scoring import calculate_composite_score
+from factorforge.engines.profile.scoring import (
+    calculate_composite_score,
+    compute_mfe_evidence,
+)
 from factorforge.engines.profile.validator import InputValidator
+from factorforge.analysis.metrics import translate_dna
 from factorforge.utils.construct_id import generate_construct_id
+from factorforge.utils.sequence_validator import validate_cds_output
 
 logger = logging.getLogger(__name__)
 
@@ -48,7 +53,15 @@ class PipelineResult:
             "optimization_profile": self.metadata.get("profile", ""),
             "cai_score": round(metrics.get("cai", 0.0), 4),
             "gc_content_pct": round(metrics.get("gc", 0.0), 2),
-            "mfe_kcal_mol": round(metrics.get("mfe", 0.0), 2),
+            # MFE provenance (016 audit): None when not computed (e.g. ViennaRNA
+            # unavailable) — never report an uncomputed MFE as a misleading 0.0.
+            "mfe_kcal_mol": (
+                round(metrics["mfe_kcal_mol"], 2)
+                if metrics.get("mfe_kcal_mol") is not None
+                else None
+            ),
+            "mfe_status": metrics.get("mfe_status", "not_computed"),
+            "mfe_used": metrics.get("mfe_used", False),
             "polya_signal_count": len(scan.get("polya", [])),
             "domestication_edits": len(dom.get("removed_sites", [])),
             "sequence_length_aa": len(self.sequence) // 3,
@@ -175,6 +188,7 @@ class OptimizationPipeline:
 
         if seq_type == "dna":
             optimized_dna = processed
+            expected_protein = translate_dna(processed).rstrip("*")
             cai = translator.calculate_cai(optimized_dna)
             gc = translator.calculate_gc_content(optimized_dna)
             score = calculate_composite_score(
@@ -182,6 +196,7 @@ class OptimizationPipeline:
             )
             candidate_metrics = {"cai": cai, "gc": gc, "score": score}
         else:
+            expected_protein = processed.rstrip("*")
             logger.debug(f"Generating candidates with profile: {opt_profile.value}")
             candidates = translator.generate_candidates(processed, profile=opt_profile, n=1)
             if not candidates:
@@ -251,7 +266,20 @@ class OptimizationPipeline:
 
         assembly_standard = kwargs.get("assembly_standard", "golden_gate")
         domestication = domesticator.domesticate(optimized_dna, standard=assembly_standard)
+        if not domestication.get("success", False):
+            unfixable = domestication.get("unfixable", [])
+            error = domestication.get("error")
+            detail = error or f"unfixable restriction sites: {unfixable}"
+            raise ValueError(f"Domestication failed for {assembly_standard}: {detail}")
+
         domesticated_sequence = domestication.get("domesticated_seq", optimized_dna)
+        final_validation = validate_cds_output(expected_protein, domesticated_sequence)
+        if not final_validation["passed"]:
+            raise ValueError(
+                "Final CDS validation failed: "
+                f"{final_validation['errors']} "
+                f"(aa_identity={final_validation['aa_identity']:.4f})"
+            )
 
         template_name = construct_template or self.construct_template
         if template_name:
@@ -269,6 +297,13 @@ class OptimizationPipeline:
             construct_record = None
             final_sequence = domesticated_sequence
 
+        # MFE provenance for the final output sequence (016 audit): record
+        # whether MFE was computed so export_features / Design Package never
+        # report an uncomputed MFE as 0.0.
+        candidate_metrics.update(
+            compute_mfe_evidence(domesticated_sequence, profile=effective_profile)
+        )
+
         metadata: dict[str, Any] = {
             "construct_id": generate_construct_id(),
             "profile": effective_profile,
@@ -278,6 +313,7 @@ class OptimizationPipeline:
             "validation": val_result,
             "scan_results": scan_results,
             "domestication": domestication,
+            "final_validation": final_validation,
             "metrics": candidate_metrics,
             "scan_mode": scan_mode,
         }

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/rules/reverse_translator.py

@@ -15,7 +15,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, cast
 
-from factorforge.engines.profile.scoring import calculate_composite_score
+from factorforge.engines.profile.scoring import GC_OPT_MID, calculate_composite_score
 from factorforge.engines.profile.utils import (
     build_aa_to_codons_map,
     calculate_gc,
@@ -440,14 +440,22 @@ class ReverseTranslator:
         return "".join(dna_seq)
 
     def _gc_target_translate(self, protein_seq: str, **kwargs: Any) -> str:
-        """
-        GC-Target profile: enforce GC% 42.5% ±2% (N. benthamiana optimal)
+        """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.
 
         - 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", 42.5)
+        target_gc = kwargs.get("target_gc")
+        if target_gc is None:
+            target_gc = GC_OPT_MID
 
         dna_seq: list[str] = []
 
@@ -477,11 +485,22 @@ class ReverseTranslator:
         return "".join(dna_seq)
 
     def _assembly_friendly_translate(self, protein_seq: str, **kwargs: Any) -> str:
-        """
-        Assembly-Friendly profile: avoid BsaI/BpiI
+        """Translate for Golden Gate / MoClo assembly compatibility.
+
+        Strategy:
+        - Starts from balanced codon selection (preferred_ratio=0.6)
+        - Retries up to max_attempts times until no BsaI/BpiI Type IIS
+          restriction sites remain in the CDS (forward + reverse complement)
+        - CAI trade-offs are accepted to achieve site-free sequences
 
-        - Golden Gate compatible
-        - CAI trade-offs allowed
+        Current scope:
+        - Supported: BsaI/BpiI site avoidance via stochastic retry
+        - Not yet implemented: local GC window uniformity scoring,
+          repeat-pattern penalties, synthesis vendor constraint profiles
+
+        Args:
+            protein_seq: Amino acid sequence.
+            max_attempts: Retry limit for site removal (default: 10).
         """
         max_attempts = kwargs.get("max_attempts", 10)
         if max_attempts < 1:
@@ -529,12 +548,17 @@ class ReverseTranslator:
         return self._apply_nterminal_ramp(dna_seq, protein_seq, ramp_codons=ramp_codons)
 
     def _apply_nterminal_ramp(self, dna_seq: str, protein_seq: str, ramp_codons: int = 50) -> str:
-        """
-        Apply N-terminal codon ramp for co-translational folding.
+        """Apply N-terminal codon ramp for co-translational folding.
 
         Replaces the first `ramp_codons` codons with lower-frequency synonymous
-        codons (bottom 50% by frequency) to slow the ribosome at the N-terminus.
-        Single-codon amino acids (Met, Trp) are left unchanged.
+        codons (bottom 25% by frequency; cutoff = 3*len//4) to slow the ribosome
+        at the N-terminus. Single-codon amino acids (Met, Trp) are left unchanged.
+
+        TODO: ramp profile is currently not in VALID_PROFILES (not publicly accessible).
+        Before re-enabling, revisit ramp_codons=50:
+        - Literature suggests 10–30 codons (Tuller et al. 2010, Chu et al. 2014).
+        - For short proteins, 50 codons can cover the entire CDS.
+        - Consider: ramp_len = min(30, max(10, int(protein_length * 0.15)))
 
         Args:
             dna_seq: Full-length DNA sequence.

{factorforge_cds-3.1.7 → factorforge_cds-3.1.9}/src/factorforge/engines/profile/rules/rule_engine.py

@@ -11,6 +11,7 @@ import math
 import re
 from typing import Any
 
+from factorforge.analysis.metrics import HOMOPOLYMER_SYNTHESIS_WARN_NT
 from factorforge.engines.profile.rules.reverse_translator import ReverseTranslator
 from factorforge.engines.profile.utils import (
     build_aa_to_codons_map,
@@ -246,24 +247,27 @@ class RuleEngine:
 
         return violations
 
-    def scan_homopolymers(self, seq: str, min_length: int = 8) -> list[dict[str, Any]]:
-        """
-        Detect 8+ homopolymers (synthesis risk)
+    def scan_homopolymers(
+        self, seq: str, min_length: int = HOMOPOLYMER_SYNTHESIS_WARN_NT
+    ) -> list[dict[str, Any]]:
+        """Detect homopolymer runs for synthesis/manufacturing risk evaluation.
 
-        Args:
-            seq: DNA sequence
-            min_length: Minimum length
+        Uses HOMOPOLYMER_SYNTHESIS_WARN_NT (default 8 nt) — the threshold at
+        which gene synthesis vendors flag homopolymers as difficult to synthesize
+        with high fidelity.
 
-        Returns:
-            List of violations
+        For expression stability risk (≥6 nt), see
+        factorforge.analysis.metrics.detect_homopolymers() which uses
+        HOMOPOLYMER_EXPRESSION_WARN_NT.
 
-        Raises:
-            None.
+        Args:
+            seq: DNA sequence
+            min_length: Minimum run length to flag (default: HOMOPOLYMER_SYNTHESIS_WARN_NT)
 
         Examples:
             >>> engine = RuleEngine()
             >>> engine.scan_homopolymers("AAAAAAAA", min_length=8)
-            [{'type': 'homopolymer', ...}]
+            [{'type': 'homopolymer', 'context': 'synthesis', ...}]
         """
         violations: list[dict[str, Any]] = []
 
@@ -280,16 +284,16 @@ class RuleEngine:
                 while idx + actual_length < len(seq) and seq[idx + actual_length] == base:
                     actual_length += 1
 
-                violations.append(
-                    {
-                        "type": "homopolymer",
-                        "base": base,
-                        "position": idx,
-                        "length": actual_length,
-                        "sequence": base * actual_length,
-                        "severity": "high" if actual_length >= 10 else "medium",
-                    }
-                )
+                violations.append({
+                    "type": "homopolymer",
+                    "context": "synthesis",
+                    "threshold_nt": min_length,
+                    "base": base,
+                    "position": idx,
+                    "length": actual_length,
+                    "sequence": base * actual_length,
+                    "severity": "high" if actual_length >= 10 else "medium",
+                })
                 pos = idx + actual_length
 
         return violations
@@ -350,13 +354,20 @@ class RuleEngine:
         max_gc: float = 75,
     ) -> list[dict[str, Any]]:
         """
-        Detect extreme GC regions
+        Detect extreme GC regions in a sliding local window.
+
+        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 (analysis 004: 55-71%).
 
         Args:
             seq: DNA sequence
             window: Window size (bp)
-            min_gc: Minimum GC% threshold
-            max_gc: Maximum GC% threshold
+            min_gc: Minimum local GC% threshold (synthesis guard, not global target)
+            max_gc: Maximum local GC% threshold (synthesis guard, not global target)
 
         Returns:
             List of violations