factorforge-cds 3.5.4__tar.gz → 3.5.10__tar.gz

{factorforge_cds-3.5.4/src/factorforge_cds.egg-info → factorforge_cds-3.5.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorforge-cds
-Version: 3.5.4
+Version: 3.5.10
 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
@@ -22,6 +22,7 @@ Requires-Dist: pydantic>=2.0
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
 Requires-Dist: sqlalchemy>=2.0; extra == "postgres"
+Requires-Dist: eijex-db-core==0.1.2; extra == "postgres"
 Provides-Extra: dev
 Requires-Dist: jsonschema>=4.0; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
@@ -51,7 +52,7 @@ Dynamic: license-file
 
 FactorForge performs deterministic CDS design with CAI/GC metrics, PolyA-signal screening, and Golden Gate/MoClo-aware checks. It is positioned as a pre-synthesis review harness: it helps teams generate reproducible CDS candidates, inspect assembly-relevant sequence constraints, and package design metadata before downstream synthesis, cloning, or experimental review. Primary support: *N. benthamiana* (agroinfiltration). Experimental host context: Tobacco BY-2 (`--host by2`).
 
-FactorForge v3.5.4 uses independently versioned engines:
+FactorForge v3.5.10 uses independently versioned engines:
 
 | Generation | Engine | Version | Availability |
 |---|---|---:|---|
@@ -89,6 +90,12 @@ Or use the **[web app](https://factorforge.eijex.com)** — no installation requ
 
 ## Repository Structure
 
+Experimental codon-distribution and evidence-ledger modules in the development
+checkout are scaffolds, not a validated laboratory policy or active learned
+recommendation service. Computational checks do not establish synthesis readiness
+or biological performance. Private inputs and collaborator packages must remain
+outside public repositories and dashboards.
+
 The supported deterministic engines are the profile engine, stable DP v2, and
 the explicit DP v2.1.1 development candidate under:
 
@@ -127,7 +134,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.5.4 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.5.10 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 
@@ -143,7 +150,10 @@ FactorForge design, CLI, Python API, and file export do not require a database.
 PostgreSQL persistence is an explicit Eijex integration path for retaining shared
 campaign and candidate identities; it is not enabled by default.
 
-Install `pip install "factorforge-cds[postgres]"` only when using that integration.
+The extra pins `eijex-db-core==0.1.2`. Supply its approved wheel bundle using
+`pip install --find-links PATH_TO_BUNDLE "factorforge-cds[postgres]"`; the shared
+package is not assumed to have been published on PyPI. Standalone installation
+does not require it.
 The deployment must also provide a compatible `eijex-db-core` package and set
 `FACTORFORGE_DATABASE_URL`. FactorForge contains no default database credentials and
 does not silently fall back to another backend. See [Persistence](docs/persistence.md).
@@ -176,3 +186,40 @@ GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
 - **Eijex MCP** — [mcp.eijex.com](https://mcp.eijex.com)
 - **Lab** — [www.eijex.com](https://www.eijex.com)
 
+
+## Testing status
+
+The web UI now labels watermark as disabled and distinguishes the sequence-only baseline from experimental structure-conditioned testing. The local approved workflow supports explicit 1DP-only or paired 3DP mode. 3DP availability is local research testing; it is not a new public optimization endpoint or a biological-performance claim. See [web UI boundaries](web/README.md).
+
+## Direct 3DP browser testing (unreleased)
+
+The FactorForge form supports explicit 1DP/3DP selection. 3DP uploads a PDB/mmCIF file, selects chain and one-based file model order, and requires reviewed one-based protein positions. The selected observed chain must exactly match the complete protein; partial or homologous structures require the retained local reviewed mapping workflow. Direct requests use `/api/optimize` with `design_mode=paired_3dp` and `structure_context={content,format,chain,model,positions,positions_reviewed,target_adaptiveness,penalty_weight}`.
+
+Limits: 3–300 amino acids, structure content 250 KB, HTTP JSON body 1 MB. Both candidates use the configured codon reference, requested GC and canonical motif exclusions plus custom additions. Invalid inputs and infeasible candidates fail without a baseline fallback. Existing sequence-only settings and API requests remain supported. 3DP uses its explicit DP settings and does not apply Kozak, TpA, template or seed transformations. SOP checks are reported for both candidates; regeneration is manual and never silently changes mode. Watermark stays disabled.
+
+This is stateless computational testing, with no external service dependencies or remote database recording. Those existing integrations remain available for later operational use. The structure file is not retained in the response or browser history; normal design results may be retained in local browser history. Submit only public-safe inputs. Structural conformity metrics are codon-weight proxies, not folding/expression measurements. These source changes are not deployed or a new package release.
+
+## Current public policy UI (2026-10-12)
+
+Custom SOP management is paused. The built-in FactorForge default policy is applied; upload/export/preset/editing controls are hidden and disabled. Their code and previous browser configuration remain available for later reactivation through ENABLE_CUSTOM_SOP. Saved custom SOPs are ignored without deletion. 1DP/3DP mode selection and explicit structure inputs remain active. This supersedes the earlier public SOP upload/export instructions. Public API contracts are retained.
+
+### Scientific web observations
+
+Direct 1DP/3DP browser testing reports sense-CDS RNA motif scans and available initiation-window MFE in results, downloadable reports and local history. Structure confidence observations can suggest positions for explicit acceptance and review; unsupported inputs do not invent positions. These checks do not establish expression, yield or folding benefits. The default policy remains active and custom SOP management remains paused. See `docs/experimental-structure.md` for the API and measurement boundary.
+
+### Local reviewed structure file workflow
+
+`factorforge nbfold annotate` and `factorforge nbfold optimize` provide the experimental local Phase A/B workflow for exact-match structure files and an explicit user review manifest. See [NB-Fold documentation](docs/experimental-structure.md).
+
+Web structure handling now requires exact-match uploaded PDB/mmCIF coordinates and explicit reviewed positions. Automatic external folding, artificial structure/confidence fallback, and auto-approval are disabled. Structure metrics are synthetic reconstruction checks; independent public-structure/DSSP validation remains open.
+
+### Experimental human-reference prototype
+
+`factorforge.engines.stemcell_3dp.StemCell3DPOptimizer` is a local experimental interface using a generic human-frequency reference and provisional Eijex review criteria. It is not an MSC/iPSC-calibrated model or a laboratory-approved SOP. See [prototype boundaries](docs/model_cards/human-reference-prototype.md). It is not a new production web host.
+# Local research candidate: DP v2.2
+
+The opt-in Python `DPV220Optimizer` shares the v2.1.1 DP core and adds reviewed
+position penalties. The experimental generic-human adapter uses this core;
+existing plant web/NB-Fold routes retain their prior objective. See the
+[model card](docs/model_cards/dp_v2_2.md) for usage, relaxation reporting and
+engineering validation boundaries. This is not an expression or folding claim.

{factorforge_cds-3.5.4 → factorforge_cds-3.5.10}/README.md

@@ -14,7 +14,7 @@
 
 FactorForge performs deterministic CDS design with CAI/GC metrics, PolyA-signal screening, and Golden Gate/MoClo-aware checks. It is positioned as a pre-synthesis review harness: it helps teams generate reproducible CDS candidates, inspect assembly-relevant sequence constraints, and package design metadata before downstream synthesis, cloning, or experimental review. Primary support: *N. benthamiana* (agroinfiltration). Experimental host context: Tobacco BY-2 (`--host by2`).
 
-FactorForge v3.5.4 uses independently versioned engines:
+FactorForge v3.5.10 uses independently versioned engines:
 
 | Generation | Engine | Version | Availability |
 |---|---|---:|---|
@@ -52,6 +52,12 @@ Or use the **[web app](https://factorforge.eijex.com)** — no installation requ
 
 ## Repository Structure
 
+Experimental codon-distribution and evidence-ledger modules in the development
+checkout are scaffolds, not a validated laboratory policy or active learned
+recommendation service. Computational checks do not establish synthesis readiness
+or biological performance. Private inputs and collaborator packages must remain
+outside public repositories and dashboards.
+
 The supported deterministic engines are the profile engine, stable DP v2, and
 the explicit DP v2.1.1 development candidate under:
 
@@ -90,7 +96,7 @@ FactorForge outputs are **in-silico only** and have not been experimentally vali
 ## Citing
 
 ```
-FactorForge v3.5.4 (2026). Open-source constraint-based CDS design and sequence review.
+FactorForge v3.5.10 (2026). Open-source constraint-based CDS design and sequence review.
 Eijex. https://github.com/eijex/factorforge-cds
 ```
 
@@ -106,7 +112,10 @@ FactorForge design, CLI, Python API, and file export do not require a database.
 PostgreSQL persistence is an explicit Eijex integration path for retaining shared
 campaign and candidate identities; it is not enabled by default.
 
-Install `pip install "factorforge-cds[postgres]"` only when using that integration.
+The extra pins `eijex-db-core==0.1.2`. Supply its approved wheel bundle using
+`pip install --find-links PATH_TO_BUNDLE "factorforge-cds[postgres]"`; the shared
+package is not assumed to have been published on PyPI. Standalone installation
+does not require it.
 The deployment must also provide a compatible `eijex-db-core` package and set
 `FACTORFORGE_DATABASE_URL`. FactorForge contains no default database credentials and
 does not silently fall back to another backend. See [Persistence](docs/persistence.md).
@@ -139,3 +148,40 @@ GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).
 - **Eijex MCP** — [mcp.eijex.com](https://mcp.eijex.com)
 - **Lab** — [www.eijex.com](https://www.eijex.com)
 
+
+## Testing status
+
+The web UI now labels watermark as disabled and distinguishes the sequence-only baseline from experimental structure-conditioned testing. The local approved workflow supports explicit 1DP-only or paired 3DP mode. 3DP availability is local research testing; it is not a new public optimization endpoint or a biological-performance claim. See [web UI boundaries](web/README.md).
+
+## Direct 3DP browser testing (unreleased)
+
+The FactorForge form supports explicit 1DP/3DP selection. 3DP uploads a PDB/mmCIF file, selects chain and one-based file model order, and requires reviewed one-based protein positions. The selected observed chain must exactly match the complete protein; partial or homologous structures require the retained local reviewed mapping workflow. Direct requests use `/api/optimize` with `design_mode=paired_3dp` and `structure_context={content,format,chain,model,positions,positions_reviewed,target_adaptiveness,penalty_weight}`.
+
+Limits: 3–300 amino acids, structure content 250 KB, HTTP JSON body 1 MB. Both candidates use the configured codon reference, requested GC and canonical motif exclusions plus custom additions. Invalid inputs and infeasible candidates fail without a baseline fallback. Existing sequence-only settings and API requests remain supported. 3DP uses its explicit DP settings and does not apply Kozak, TpA, template or seed transformations. SOP checks are reported for both candidates; regeneration is manual and never silently changes mode. Watermark stays disabled.
+
+This is stateless computational testing, with no external service dependencies or remote database recording. Those existing integrations remain available for later operational use. The structure file is not retained in the response or browser history; normal design results may be retained in local browser history. Submit only public-safe inputs. Structural conformity metrics are codon-weight proxies, not folding/expression measurements. These source changes are not deployed or a new package release.
+
+## Current public policy UI (2026-10-12)
+
+Custom SOP management is paused. The built-in FactorForge default policy is applied; upload/export/preset/editing controls are hidden and disabled. Their code and previous browser configuration remain available for later reactivation through ENABLE_CUSTOM_SOP. Saved custom SOPs are ignored without deletion. 1DP/3DP mode selection and explicit structure inputs remain active. This supersedes the earlier public SOP upload/export instructions. Public API contracts are retained.
+
+### Scientific web observations
+
+Direct 1DP/3DP browser testing reports sense-CDS RNA motif scans and available initiation-window MFE in results, downloadable reports and local history. Structure confidence observations can suggest positions for explicit acceptance and review; unsupported inputs do not invent positions. These checks do not establish expression, yield or folding benefits. The default policy remains active and custom SOP management remains paused. See `docs/experimental-structure.md` for the API and measurement boundary.
+
+### Local reviewed structure file workflow
+
+`factorforge nbfold annotate` and `factorforge nbfold optimize` provide the experimental local Phase A/B workflow for exact-match structure files and an explicit user review manifest. See [NB-Fold documentation](docs/experimental-structure.md).
+
+Web structure handling now requires exact-match uploaded PDB/mmCIF coordinates and explicit reviewed positions. Automatic external folding, artificial structure/confidence fallback, and auto-approval are disabled. Structure metrics are synthetic reconstruction checks; independent public-structure/DSSP validation remains open.
+
+### Experimental human-reference prototype
+
+`factorforge.engines.stemcell_3dp.StemCell3DPOptimizer` is a local experimental interface using a generic human-frequency reference and provisional Eijex review criteria. It is not an MSC/iPSC-calibrated model or a laboratory-approved SOP. See [prototype boundaries](docs/model_cards/human-reference-prototype.md). It is not a new production web host.
+# Local research candidate: DP v2.2
+
+The opt-in Python `DPV220Optimizer` shares the v2.1.1 DP core and adds reviewed
+position penalties. The experimental generic-human adapter uses this core;
+existing plant web/NB-Fold routes retain their prior objective. See the
+[model card](docs/model_cards/dp_v2_2.md) for usage, relaxation reporting and
+engineering validation boundaries. This is not an expression or folding claim.

{factorforge_cds-3.5.4 → factorforge_cds-3.5.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorforge-cds"
-version = "3.5.4"
+version = "3.5.10"
 description = "FactorForge - open-source CDS design and pre-synthesis sequence review by Eijex."
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -30,6 +30,7 @@ dependencies = [
 postgres = [
     "psycopg2-binary>=2.9",
     "sqlalchemy>=2.0",
+    "eijex-db-core==0.1.2",
 ]
 dev = [
     "jsonschema>=4.0",

{factorforge_cds-3.5.4 → factorforge_cds-3.5.10}/src/factorforge/cli/main.py

@@ -7,18 +7,18 @@ Usage:
   factorforge list-engines
 """
 
-from pathlib import Path
 import hashlib
 import json
 import sys
+from pathlib import Path
 
 import click
 
 from factorforge import __version__
 from factorforge.analysis.feasibility import DEFAULT_CAI_TARGET
 from factorforge.engines import register_builtin_engines
-from factorforge.engines.registry import EngineRegistry
 from factorforge.engines.profile.utils import parse_fasta_records
+from factorforge.engines.registry import EngineRegistry
 
 register_builtin_engines()
 
@@ -710,7 +710,10 @@ def evaluate_model(model_id, train_snapshot, eval_snapshot, input_sequence):
     mock_train_seqs = ["ATGGCTAAATGGTAA", "ATGCGTACGTGCTAG"]
     mock_eval_seqs = ["ATGCCCGGGAAATTT"]
     
-    from factorforge.review.evaluation_integrity import DatasetLeakageAuditor, GenerationMemorizationAuditor
+    from factorforge.review.evaluation_integrity import (
+        DatasetLeakageAuditor,
+        GenerationMemorizationAuditor,
+    )
     
     # 2. Dataset Leakage Audit
     ds_auditor = DatasetLeakageAuditor(mock_train_seqs, mock_eval_seqs)
@@ -914,17 +917,22 @@ def audit(sequence_fasta, reference_codon_profile, exclude_region, output):
     Run generic sequence audit to report codon usage, CAI, GC, and AA distribution.
     """
     _configure_stdio()
-    from factorforge.engines.profile.utils import parse_fasta_records
-    from factorforge.analysis.metrics import (
-        load_codon_usage_table, calculate_cai, calculate_gc, codon_usage_profile, 
-        translate_dna, calculate_synonymous_entropy, calculate_max_synonymous_share,
-        calculate_reference_distance
-    )
-    from factorforge.engines.balanced_optimizer import STANDARD_GENETIC_CODE
-    
     import hashlib
     import json
     from pathlib import Path
+
+    from factorforge.analysis.metrics import (
+        calculate_cai,
+        calculate_gc,
+        calculate_max_synonymous_share,
+        calculate_reference_distance,
+        calculate_synonymous_entropy,
+        codon_usage_profile,
+        load_codon_usage_table,
+        translate_dna,
+    )
+    from factorforge.engines.balanced_optimizer import STANDARD_GENETIC_CODE
+    from factorforge.engines.profile.utils import parse_fasta_records
     
     fasta_records = parse_fasta_records(Path(sequence_fasta).read_text(encoding='utf-8'))
     if not fasta_records:
@@ -988,6 +996,13 @@ def audit(sequence_fasta, reference_codon_profile, exclude_region, output):
     else:
         click.echo(json.dumps(results, indent=2))
 
+
+from factorforge.nbfold.cli import nbfold_cli
+
+cli.add_command(nbfold_cli)
+
+
 if __name__ == "__main__":
     cli()
 
+

factorforge_cds-3.5.10/src/factorforge/closed_loop/__init__.py

@@ -0,0 +1,27 @@
+"""FactorForge Closed-Loop Codon Evidence Foundation Package."""
+
+from factorforge.closed_loop.contracts import (
+    ConstructRecord,
+    ConstructSetRecord,
+    ExperimentRecord,
+    MeasurementRecord,
+    PolicyRecord,
+)
+from factorforge.closed_loop.ledger import EvidenceLedger
+from factorforge.closed_loop.readiness import (
+    ModelRecommendationGate,
+    ReadinessEvaluator,
+    ReadinessStatus,
+)
+
+__all__ = [
+    "ConstructRecord",
+    "ConstructSetRecord",
+    "EvidenceLedger",
+    "ExperimentRecord",
+    "MeasurementRecord",
+    "ModelRecommendationGate",
+    "PolicyRecord",
+    "ReadinessEvaluator",
+    "ReadinessStatus",
+]

factorforge_cds-3.5.10/src/factorforge/closed_loop/contracts.py

@@ -0,0 +1,103 @@
+"""Data contracts and schemas for Closed-Loop DBTL Lineage."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class PolicyRecord(BaseModel):
+    """Metadata record of an approved codon distribution policy."""
+
+    policy_id: str
+    canonical_sha256: str
+    target_distribution: dict[str, dict[str, float]]
+    region_definition: str = "mature_chain"
+    feedback_source_id: str = "unspecified"
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+class ConstructRecord(BaseModel):
+    """Immutable sequence identity record for a designed construct."""
+
+    construct_id: str
+    cds_sha256: str
+    protein_sha256: str
+    chain: str  # "LC" or "HC"
+    watermark_pair_id: str
+    watermark_applied: bool
+    achieved_distribution: dict[str, dict[str, float]]
+    policy_id: str
+    engine_version: str = "FactorForge-v3.3.0"
+
+
+class ConstructSetRecord(BaseModel):
+    """Co-expressed pair of Light Chain and Heavy Chain constructs."""
+
+    construct_set_id: str
+    light_construct_id: str
+    heavy_construct_id: str
+    watermark_applied: bool
+    description: str = ""
+
+
+class ExperimentRecord(BaseModel):
+    """Wet-lab or benchmark experiment metadata."""
+
+    experiment_id: str
+    construct_set_id: str
+    host: str = "Nicotiana benthamiana"
+    expression_system: str = "Agroinfiltration (Transient Leaf Expression)"
+    batch_id: str
+    experiment_date: str
+    protocol_version: str = "unspecified"
+
+
+class MeasurementRecord(BaseModel):
+    """Single empirical or synthetic readout record."""
+
+    measurement_id: str
+    experiment_id: str
+    construct_set_id: str
+    biological_replicate_id: str
+    technical_replicate_id: str
+    measurement_type: str  # "protein_yield", "mrna_abundance", "functional_binding"
+    value: float | None
+    unit: str  # "mg/L", "relative_fold", "%"
+    qc_status: str = "PASS"  # "PASS", "FAIL", "FLAGGED"
+    is_synthetic: bool = (
+        False  # CRITICAL: If True, flagged as test_only and excluded from real training
+    )
+    tag: str = "empirical"
+    notes: str = ""
+    recorded_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    @model_validator(mode="after")
+    def validate_measurement(self):
+        if self.value is not None and not math.isfinite(self.value):
+            raise ValueError("Measurement value must be finite or null")
+        if self.is_synthetic:
+            self.tag = "test_only"
+        if self.qc_status not in {"PASS", "FAIL", "FLAGGED"}:
+            raise ValueError("Unknown QC status")
+        return self
+
+    @property
+    def record_hash(self) -> str:
+        payload = {
+            "measurement_id": self.measurement_id,
+            "experiment_id": self.experiment_id,
+            "construct_set_id": self.construct_set_id,
+            "biological_replicate_id": self.biological_replicate_id,
+            "technical_replicate_id": self.technical_replicate_id,
+            "measurement_type": self.measurement_type,
+            "value": self.value,
+            "unit": self.unit,
+            "is_synthetic": self.is_synthetic,
+        }
+        encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        return hashlib.sha256(encoded).hexdigest()

factorforge_cds-3.5.10/src/factorforge/closed_loop/ledger.py

@@ -0,0 +1,222 @@
+"""Append-only Evidence Ledger for ValidationHub / FactorForge closed loop."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from factorforge.closed_loop.contracts import (
+    ConstructRecord,
+    ConstructSetRecord,
+    ExperimentRecord,
+    MeasurementRecord,
+    PolicyRecord,
+)
+from factorforge.closed_loop.readiness import (
+    ReadinessEvaluator,
+    ReadinessReport,
+)
+
+
+class EvidenceLedger:
+    """Local file-based append-only registry storing closed-loop DBTL evidence."""
+
+    def __init__(self, ledger_dir: Path | None = None):
+        if ledger_dir is None:
+            ledger_dir = Path(__file__).resolve().parents[3] / "data" / "evidence_ledger"
+        self.ledger_dir = Path(ledger_dir)
+        self.ledger_dir.mkdir(parents=True, exist_ok=True)
+
+        self.policies_file = self.ledger_dir / "policies.jsonl"
+        self.constructs_file = self.ledger_dir / "constructs.jsonl"
+        self.construct_sets_file = self.ledger_dir / "construct_sets.jsonl"
+        self.experiments_file = self.ledger_dir / "experiments.jsonl"
+        self.measurements_file = self.ledger_dir / "measurements.jsonl"
+
+    def _append_jsonl(self, file_path: Path, record: dict):
+        identity_field = {
+            "policies.jsonl": "policy_id",
+            "constructs.jsonl": "construct_id",
+            "construct_sets.jsonl": "construct_set_id",
+            "experiments.jsonl": "experiment_id",
+            "measurements.jsonl": "measurement_id",
+        }[file_path.name]
+        for existing in self._read_jsonl(file_path):
+            if existing.get(identity_field) == record[identity_field]:
+                if existing == record:
+                    return  # Same record is idempotent, not another observation.
+                raise ValueError(
+                    "Conflicting identity; preserve the original and use an explicit new revision"
+                )
+        with open(file_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+    def _read_jsonl(self, file_path: Path) -> list[dict]:
+        if not file_path.exists():
+            return []
+        records = []
+        with open(file_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    records.append(json.loads(line))
+        return records
+
+    def register_policy(self, record: PolicyRecord):
+        self._append_jsonl(self.policies_file, record.model_dump())
+
+    def register_construct(self, record: ConstructRecord):
+        self._append_jsonl(self.constructs_file, record.model_dump())
+
+    def register_construct_set(self, record: ConstructSetRecord):
+        self._append_jsonl(self.construct_sets_file, record.model_dump())
+
+    def register_experiment(self, record: ExperimentRecord):
+        self._append_jsonl(self.experiments_file, record.model_dump())
+
+    def record_measurement(self, record: MeasurementRecord):
+        self._append_jsonl(self.measurements_file, record.model_dump())
+
+    def list_measurements(self, include_synthetic: bool = True) -> list[MeasurementRecord]:
+        raw = self._read_jsonl(self.measurements_file)
+        measurements = [MeasurementRecord(**r) for r in raw]
+        if not include_synthetic:
+            return [m for m in measurements if not m.is_synthetic]
+        return measurements
+
+    def get_readiness(self) -> ReadinessReport:
+        all_measurements = self.list_measurements(include_synthetic=True)
+        raw_experiments = self._read_jsonl(self.experiments_file)
+        experiments = {e["experiment_id"]: ExperimentRecord(**e) for e in raw_experiments}
+        all_measurements = [
+            m
+            if m.is_synthetic or self.verify_lineage(m.measurement_id)["lineage_intact"]
+            else m.model_copy(update={"qc_status": "FLAGGED"})
+            for m in all_measurements
+        ]
+        return ReadinessEvaluator.evaluate(all_measurements, experiments=experiments)
+
+    def verify_lineage(self, measurement_id: str) -> dict[str, object]:
+        """Verify unbroken provenance & referential consistency:
+        Measurement -> Experiment -> ConstructSet -> Construct -> Policy."""
+        measurements = {m["measurement_id"]: m for m in self._read_jsonl(self.measurements_file)}
+        experiments = {e["experiment_id"]: e for e in self._read_jsonl(self.experiments_file)}
+        construct_sets = {
+            s["construct_set_id"]: s for s in self._read_jsonl(self.construct_sets_file)
+        }
+        constructs = {c["construct_id"]: c for c in self._read_jsonl(self.constructs_file)}
+        policies = {p["policy_id"]: p for p in self._read_jsonl(self.policies_file)}
+
+        if measurement_id not in measurements:
+            raise KeyError(f"Measurement '{measurement_id}' not found in ledger")
+
+        m = measurements[measurement_id]
+        exp_id = m.get("experiment_id")
+        set_id = m.get("construct_set_id")
+
+        exp = experiments.get(exp_id)
+        cset = construct_sets.get(set_id)
+
+        lc_construct = constructs.get(cset.get("light_construct_id")) if cset else None
+        hc_construct = constructs.get(cset.get("heavy_construct_id")) if cset else None
+
+        policy_id = lc_construct.get("policy_id") if lc_construct else None
+        pol = policies.get(policy_id) if policy_id else None
+
+        violations: list[str] = []
+
+        # 1. Existence validations
+        if exp is None:
+            violations.append(f"Referenced experiment '{exp_id}' does not exist in ledger.")
+        if cset is None:
+            violations.append(f"Referenced construct_set '{set_id}' does not exist in ledger.")
+        if lc_construct is None:
+            violations.append("Referenced light chain construct does not exist in ledger.")
+        if hc_construct is None:
+            violations.append("Referenced heavy chain construct does not exist in ledger.")
+        if pol is None:
+            violations.append(f"Referenced policy '{policy_id}' does not exist in ledger.")
+
+        # 2. Referential integrity validations
+        if exp and cset and exp.get("construct_set_id") != set_id:
+            violations.append(
+                f"Referential mismatch: Measurement points to construct_set '{set_id}' "
+                f"but Experiment '{exp_id}' points to '{exp.get('construct_set_id')}'"
+            )
+
+        if lc_construct and hc_construct:
+            lc_pol = lc_construct.get("policy_id")
+            hc_pol = hc_construct.get("policy_id")
+            if lc_pol != hc_pol:
+                violations.append(
+                    f"Policy mismatch between chains: LC is linked to '{lc_pol}' but HC is linked to '{hc_pol}'"
+                )
+
+        lineage_intact = len(violations) == 0
+
+        return {
+            "measurement_id": measurement_id,
+            "lineage_intact": lineage_intact,
+            "violations": violations,
+            "is_synthetic": m.get("is_synthetic", False),
+            "experiment": exp,
+            "construct_set": cset,
+            "light_construct": lc_construct,
+            "heavy_construct": hc_construct,
+            "policy": pol,
+        }
+
+    def sync_to_gcs(
+        self,
+        bucket_name: str,
+        destination_folder: str = "validationhub/ledger_v0",
+        gcp_key_path: str | None = None,
+    ) -> dict[str, str]:
+        """Sync append-only ledger snapshot with atomic manifest to Google Cloud Storage."""
+        from google.cloud import storage
+
+        if gcp_key_path:
+            os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = gcp_key_path
+
+        client = storage.Client()
+        bucket = client.bucket(bucket_name)
+
+        # Generate atomic ledger manifest with SHA256 checksums
+        manifest_files = {}
+        target_files = [
+            self.policies_file,
+            self.constructs_file,
+            self.construct_sets_file,
+            self.experiments_file,
+            self.measurements_file,
+        ]
+
+        for file_path in target_files:
+            if file_path.exists():
+                content = file_path.read_bytes()
+                manifest_files[file_path.name] = {
+                    "sha256": hashlib.sha256(content).hexdigest(),
+                    "size_bytes": len(content),
+                }
+
+        manifest = {
+            "manifest_version": "0.2",
+            "snapshot_timestamp": datetime.now(timezone.utc).isoformat(),
+            "factorforge_version": "3.5.4",
+            "files": manifest_files,
+        }
+        manifest_file = self.ledger_dir / "ledger_manifest.json"
+        manifest_file.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+
+        uploaded = {}
+        for file_path in target_files + [manifest_file]:
+            if file_path.exists():
+                blob_name = f"{destination_folder}/{file_path.name}"
+                blob = bucket.blob(blob_name)
+                blob.upload_from_filename(str(file_path))
+                uploaded[file_path.name] = f"gs://{bucket_name}/{blob_name}"
+
+        return uploaded