Upload folder using huggingface_hub

.env.example

@@ -21,3 +21,12 @@ DEMO_MODE=false
 
 # Hugging Face CLI (optional — for `hf upload` deploys only, not read by the app)
 HF_TOKEN=
+
+# Real nf-core/sarek executors (all fail closed when disabled or incomplete)
+NGS_LOCAL_EXECUTION_ENABLED=false
+NGS_SLURM_EXECUTION_ENABLED=false
+NGS_AWS_BATCH_EXECUTION_ENABLED=false
+NGS_RUN_ROOT=/tmp/bionexus-ngs-runs
+NGS_AWS_REGION=
+NGS_AWS_BATCH_JOB_QUEUE=
+NGS_AWS_BATCH_JOB_DEFINITION=

NGS_PRODUCTION_EXECUTION.md

@@ -0,0 +1,50 @@
+# BioNexus production NGS execution
+
+BioNexus submits the pinned `nf-core/sarek` 3.10.0 command produced by the production validator. Production execution never falls back to the exploratory Python pipeline.
+
+## Shared requirements
+
+- Apply `migrations/011_ngs_production_runs.sql` to Supabase.
+- Configure authentication and the existing Supabase service credentials.
+- Stage the Sarek samplesheet, reference resources, optional WES BED, work directory and result directory where the selected executor can read them.
+- Provide a reviewed Nextflow configuration for SLURM and AWS Batch.
+- Keep the executor disabled until its preflight requirements are satisfied.
+
+## Local Docker, Apptainer or Singularity
+
+Run the API on the workstation that owns the staged paths. Install Java, Nextflow, and the selected container runtime, then set:
+
+```env
+NGS_LOCAL_EXECUTION_ENABLED=true
+NGS_RUN_ROOT=/durable/bionexus-ngs-runs
+```
+
+The detached worker writes its real Nextflow log and status under `NGS_RUN_ROOT/<run-id>/`. The output artifacts remain in the requested Sarek `--outdir`.
+
+## SLURM
+
+Run the API or a private execution service on a SLURM login/head node with `nextflow`, `java`, `sbatch`, and `sacct` on `PATH`. Samples, references, work and results must use shared cluster paths.
+
+```env
+NGS_SLURM_EXECUTION_ENABLED=true
+NGS_RUN_ROOT=/shared/bionexus/ngs-runs
+```
+
+Select the SLURM profile and provide the reviewed site-specific Nextflow configuration. BioNexus submits with `sbatch` and reads scheduler state with `sacct`.
+
+## AWS Batch
+
+Create an AWS Batch queue and a driver job definition whose image includes Java, Nextflow and the AWS permissions required to submit Sarek process jobs. Grant the BioNexus API role `batch:SubmitJob`, `batch:DescribeJobs`, S3 access to the staged inputs/results, and the appropriate job-role permissions.
+
+```env
+NGS_AWS_BATCH_EXECUTION_ENABLED=true
+NGS_AWS_REGION=ap-south-1
+NGS_AWS_BATCH_JOB_QUEUE=<queue-name-or-arn>
+NGS_AWS_BATCH_JOB_DEFINITION=<driver-job-definition-name-or-arn>
+```
+
+Use S3 input/result locations or mounts explicitly configured in the job definition. The artifact importer inventories the real S3 output prefix after the Batch job succeeds.
+
+## Scientific boundary
+
+Successful workflow execution is not clinical validation. BioNexus imports observed execution, MultiQC, alignment, variant, coverage, identity/contamination and provenance artifacts. Missing groups remain missing and keep the clinical gate closed.

app/config.py

@@ -32,6 +32,14 @@ class Settings:
     DEMO_MODE: bool = os.getenv("DEMO_MODE", "false").lower() in ("true", "1", "yes")
     CORS_ORIGIN: str = os.getenv("CORS_ORIGIN", "https://bioai-platform.vercel.app")
     SENTRY_DSN: str = os.getenv("SENTRY_DSN", "")
+    NGS_CLINICAL_EVIDENCE_HMAC_KEY: str = os.getenv("NGS_CLINICAL_EVIDENCE_HMAC_KEY", "")
+    NGS_LOCAL_EXECUTION_ENABLED: bool = os.getenv("NGS_LOCAL_EXECUTION_ENABLED", "false").lower() in ("true", "1", "yes")
+    NGS_SLURM_EXECUTION_ENABLED: bool = os.getenv("NGS_SLURM_EXECUTION_ENABLED", "false").lower() in ("true", "1", "yes")
+    NGS_AWS_BATCH_EXECUTION_ENABLED: bool = os.getenv("NGS_AWS_BATCH_EXECUTION_ENABLED", "false").lower() in ("true", "1", "yes")
+    NGS_RUN_ROOT: str = os.getenv("NGS_RUN_ROOT", "/tmp/bionexus-ngs-runs")
+    NGS_AWS_REGION: str = os.getenv("NGS_AWS_REGION", "")
+    NGS_AWS_BATCH_JOB_QUEUE: str = os.getenv("NGS_AWS_BATCH_JOB_QUEUE", "")
+    NGS_AWS_BATCH_JOB_DEFINITION: str = os.getenv("NGS_AWS_BATCH_JOB_DEFINITION", "")
 
 
 settings = Settings()

app/models/responses.py

@@ -1,5 +1,5 @@
-from pydantic import BaseModel
-from typing import Any, Optional
+from pydantic import BaseModel, Field
+from typing import Any, Literal, Optional
 
 
 class PipelineRunResponse(BaseModel):
@@ -38,3 +38,96 @@ class ProfileUpdateResponse(BaseModel):
 
 class ErrorResponse(BaseModel):
     detail: str
+
+
+class NgsProductionPlanRequest(BaseModel):
+    assay: Literal["WGS", "WES"]
+    sample_model: Literal["singleton", "cohort", "duo", "trio", "family"] = "singleton"
+    input_type: Literal["FASTQ", "BAM", "CRAM"] = "FASTQ"
+    start_step: Literal["mapping", "markduplicates", "variant_calling"] = "mapping"
+    samplesheet_path: str = Field(min_length=1)
+    outdir: str = Field(min_length=1)
+    genome: Literal["GRCh38", "GRCh37"] = "GRCh38"
+    execution_profile: Literal["docker", "singularity", "apptainer", "slurm", "awsbatch"] = "docker"
+    caller: Literal["haplotypecaller", "deepvariant"] = "haplotypecaller"
+    target_bed: Optional[str] = None
+    custom_config: Optional[str] = None
+    annotate_with_vep: bool = True
+    clinical_intent: bool = False
+
+
+class NgsProductionPlanResponse(BaseModel):
+    schema_version: str
+    workflow: dict[str, str]
+    state: Literal["PLANNED", "BLOCKED"]
+    ready_to_launch: bool
+    blockers: list[str]
+    warnings: list[str]
+    command_argv: list[str]
+    command_display: str
+    required_artifacts: list[dict[str, Any]]
+    provenance_requirements: list[str]
+    clinical_boundary: dict[str, Any]
+
+
+class NgsProductionSubmitResponse(BaseModel):
+    run_id: str
+    state: Literal["SUBMITTED", "BLOCKED"]
+    executor: Literal["local", "slurm", "awsbatch"]
+    executor_job_id: Optional[str] = None
+    message: str
+
+
+class NgsProductionRunResponse(BaseModel):
+    run_id: str
+    state: Literal["SUBMITTED", "PENDING", "RUNNING", "SUCCEEDED", "FAILED", "UNKNOWN"]
+    executor: Literal["local", "slurm", "awsbatch"]
+    executor_job_id: str
+    workflow: str
+    revision: str
+    outdir: str
+    submitted_at: str
+    updated_at: str
+    exit_code: Optional[int] = None
+    message: Optional[str] = None
+
+
+class NgsClinicalEvidenceRequest(BaseModel):
+    evidence_bundle_sha256: Optional[str] = None
+    evidence_signature: Optional[str] = None
+    assay_validation_id: Optional[str] = None
+    workflow_status: Literal["PLANNED", "COMPLETED", "FAILED"] = "PLANNED"
+    sarek_revision: Optional[str] = None
+    reference_build: Optional[Literal["GRCh38", "GRCh37"]] = None
+    reference_manifest_sha256: Optional[str] = None
+    samplesheet_sha256: Optional[str] = None
+    container_digests_complete: bool = False
+    complete_input_processed: bool = False
+    required_artifacts_present: bool = False
+    qc_pass: bool = False
+    sample_identity_pass: bool = False
+    contamination_pass: bool = False
+    sex_ploidy_reviewed: bool = False
+    truthset_name: Optional[str] = None
+    benchmark_protocol_id: Optional[str] = None
+    benchmark_acceptance_pass: bool = False
+    confident_regions_sha256: Optional[str] = None
+    same_sample_reference_regions: bool = False
+    snv_precision: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+    snv_recall: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+    indel_precision: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+    indel_recall: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+    human_reviewed: bool = False
+    reviewer_id: Optional[str] = None
+    release_signature_id: Optional[str] = None
+    unresolved_deviations: list[str] = Field(default_factory=list)
+
+
+class NgsClinicalEvidenceResponse(BaseModel):
+    schema_version: str
+    status: Literal["SOFTWARE_GATE_PASSED", "NOT_CLINICALLY_RELEASABLE"]
+    clinically_validated: Literal[False]
+    gates: list[dict[str, Any]]
+    missing_or_failed: list[str]
+    benchmark_summary: dict[str, Any]
+    disclaimer: str

app/ngs/contracts.py

@@ -86,6 +86,7 @@ class ThresholdRule:
     evaluate: Callable[[Any], QcStatus]
     expectation: Optional[str] = None
     optional: bool = False   # missing metric -> WARN (not FAIL); used for conditional sub-checks
+    missing_detail: Optional[str] = None
 
     def apply(self, value: Any, detail: Optional[str] = None) -> Metric:
         return Metric(
@@ -153,7 +154,7 @@ def apply_rules(rules: list[ThresholdRule], values: dict[str, Any]) -> list[Metr
         elif rule.optional:
             metrics.append(
                 Metric(name=rule.metric, value=None, status=QcStatus.WARN, expected=rule.expectation,
-                       detail="optional metric not evaluated (no reference data supplied)")
+                       detail=rule.missing_detail or "optional metric not evaluated (required evidence was not supplied)")
             )
         else:
             metrics.append(
@@ -227,6 +228,7 @@ class StageResult:
     qc: Optional[QcResult] = None
     decision: Decision = Decision.CONTINUE
     data: dict = field(default_factory=dict)   # stage-specific payload (parsed results)
+    evidence_level: str = "INTERNAL_COMPUTATION"
 
     def to_dict(self) -> dict:
         return {
@@ -241,6 +243,7 @@ class StageResult:
             "qc": self.qc.to_dict() if self.qc else None,
             "decision": self.decision.value,
             "data": self.data,
+            "evidence_level": self.evidence_level,
         }
 
 
@@ -269,6 +272,7 @@ class StageContract:
     fail_blocks: bool = True
     run: Optional[Callable[[dict, dict], tuple[dict, dict]]] = None
     expectation: Optional[str] = None
+    evidence_level: str = "INTERNAL_COMPUTATION"
 
     def resolve_rules(self, sample: dict) -> list[ThresholdRule]:
         if callable(self.rules):
@@ -302,6 +306,7 @@ def run_contract(contract: StageContract, sample: dict, stage_state: dict) -> St
         qc=qc,
         decision=qc.decision,
         data=data,
+        evidence_level=contract.evidence_level,
     )
 
 

app/ngs/execution.py

@@ -0,0 +1,265 @@
+"""Real nf-core/sarek executor adapters.
+
+No adapter falls back to the exploratory Python pipeline. Disabled or incomplete
+infrastructure is reported as unavailable before a job is accepted.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import uuid
+from urllib.parse import urlparse
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from app.config import settings
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _binary(name: str) -> bool:
+    return shutil.which(name) is not None
+
+
+def executor_capabilities() -> dict[str, Any]:
+    local_missing = [name for name in ("nextflow", "java") if not _binary(name)]
+    if not (_binary("docker") or _binary("singularity") or _binary("apptainer")):
+        local_missing.append("docker, singularity, or apptainer")
+    slurm_missing = [name for name in ("nextflow", "java", "sbatch", "sacct") if not _binary(name)]
+    aws_missing = [
+        name for name, value in (
+            ("NGS_AWS_REGION", settings.NGS_AWS_REGION),
+            ("NGS_AWS_BATCH_JOB_QUEUE", settings.NGS_AWS_BATCH_JOB_QUEUE),
+            ("NGS_AWS_BATCH_JOB_DEFINITION", settings.NGS_AWS_BATCH_JOB_DEFINITION),
+        ) if not value
+    ]
+    try:
+        import boto3  # noqa: F401
+    except ImportError:
+        aws_missing.append("boto3")
+    return {
+        "workflow": {"name": "nf-core/sarek", "revision": "3.10.0"},
+        "executors": {
+            "local": {
+                "available": settings.NGS_LOCAL_EXECUTION_ENABLED and not local_missing,
+                "enabled": settings.NGS_LOCAL_EXECUTION_ENABLED,
+                "missing": local_missing,
+                "requirements": ["Nextflow", "Java", "Docker/Apptainer/Singularity", "durable local result directory"],
+            },
+            "slurm": {
+                "available": settings.NGS_SLURM_EXECUTION_ENABLED and not slurm_missing,
+                "enabled": settings.NGS_SLURM_EXECUTION_ENABLED,
+                "missing": slurm_missing,
+                "requirements": ["Nextflow head node", "sbatch/sacct", "shared samplesheet/reference/work/result paths"],
+            },
+            "awsbatch": {
+                "available": settings.NGS_AWS_BATCH_EXECUTION_ENABLED and not aws_missing,
+                "enabled": settings.NGS_AWS_BATCH_EXECUTION_ENABLED,
+                "missing": aws_missing,
+                "requirements": ["AWS Batch queue", "Nextflow driver job definition", "IAM role", "S3 inputs/results"],
+            },
+        },
+        "fallback": None,
+        "note": "Production executors never fall back to the exploratory preview.",
+    }
+
+
+def _require(executor: str) -> None:
+    capability = executor_capabilities()["executors"][executor]
+    if not capability["available"]:
+        reasons = list(capability["missing"])
+        if not capability["enabled"]:
+            reasons.insert(0, f"NGS_{'AWS_BATCH' if executor == 'awsbatch' else executor.upper()}_EXECUTION_ENABLED")
+        raise RuntimeError("executor unavailable: " + ", ".join(reasons))
+
+
+def _run_dir(run_id: str) -> Path:
+    path = Path(settings.NGS_RUN_ROOT).resolve() / run_id
+    path.mkdir(parents=True, exist_ok=False)
+    return path
+
+
+def submit_run(executor: str, command_argv: list[str], outdir: str, user_id: str) -> dict[str, Any]:
+    if executor not in {"local", "slurm", "awsbatch"}:
+        raise ValueError(f"unsupported executor: {executor}")
+    _require(executor)
+    if executor == "local" and "-profile" in command_argv:
+        profile_index = command_argv.index("-profile") + 1
+        profile = command_argv[profile_index] if profile_index < len(command_argv) else ""
+        runtime = {"docker": "docker", "singularity": "singularity", "apptainer": "apptainer"}.get(profile)
+        if runtime and not _binary(runtime):
+            raise RuntimeError(f"executor unavailable: selected {runtime} runtime is not installed")
+    run_id = str(uuid.uuid4())
+    submitted_at = _now()
+
+    if executor == "local":
+        run_dir = _run_dir(run_id)
+        status_path = run_dir / "status.json"
+        log_path = run_dir / "nextflow.log"
+        worker_path = Path(__file__).with_name("nextflow_worker.py")
+        process = subprocess.Popen(
+            [sys.executable, str(worker_path), str(status_path), str(log_path), *command_argv],
+            cwd=str(run_dir), stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True,
+        )
+        executor_job_id = str(process.pid)
+    elif executor == "slurm":
+        run_dir = _run_dir(run_id)
+        script_path = run_dir / "launch.sh"
+        import shlex
+        script_path.write_text("#!/bin/sh\nset -eu\n" + shlex.join(command_argv) + "\n", encoding="utf-8")
+        script_path.chmod(0o700)
+        result = subprocess.run(["sbatch", "--parsable", str(script_path)], capture_output=True, text=True, timeout=30, check=True)
+        executor_job_id = result.stdout.strip().split(";")[0]
+    else:
+        import boto3
+        client = boto3.client("batch", region_name=settings.NGS_AWS_REGION)
+        response = client.submit_job(
+            jobName=f"bionexus-sarek-{run_id[:8]}",
+            jobQueue=settings.NGS_AWS_BATCH_JOB_QUEUE,
+            jobDefinition=settings.NGS_AWS_BATCH_JOB_DEFINITION,
+            containerOverrides={"command": command_argv, "environment": [{"name": "BIONEXUS_RUN_ID", "value": run_id}]},
+            tags={"BioNexusRunId": run_id, "Workflow": "nf-core-sarek-3.10.0"},
+        )
+        executor_job_id = response["jobId"]
+
+    record = {
+        "run_id": run_id, "state": "SUBMITTED", "executor": executor,
+        "executor_job_id": executor_job_id, "workflow": "nf-core/sarek", "revision": "3.10.0",
+        "outdir": outdir, "submitted_at": submitted_at, "updated_at": submitted_at,
+        "exit_code": None, "message": None, "user_id": user_id,
+    }
+    _persist_record(record)
+    return record
+
+
+def _record_path(run_id: str) -> Path:
+    root = Path(settings.NGS_RUN_ROOT).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    return root / f"{run_id}.json"
+
+
+def _persist_record(record: dict[str, Any]) -> None:
+    path = _record_path(record["run_id"])
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(record, sort_keys=True), encoding="utf-8")
+    temporary.replace(path)
+    try:
+        from app.services.supabase import get_supabase
+        get_supabase().table("ngs_production_runs").upsert(record, on_conflict="run_id").execute()
+    except Exception:
+        # The executor-local record keeps self-hosted operation functional; hosted
+        # deployments should apply migration 011 for durable cross-restart status.
+        pass
+
+
+def _load_record(run_id: str, user_id: str) -> dict[str, Any]:
+    if not run_id or any(char not in "0123456789abcdef-" for char in run_id.lower()):
+        raise FileNotFoundError(run_id)
+    try:
+        from app.services.supabase import get_supabase
+        rows = get_supabase().table("ngs_production_runs").select("*").eq("run_id", run_id).eq("user_id", user_id).execute().data
+        if rows:
+            return dict(rows[0])
+    except Exception:
+        pass
+    path = _record_path(run_id)
+    if not path.is_file():
+        raise FileNotFoundError(run_id)
+    record = json.loads(path.read_text(encoding="utf-8"))
+    if record.get("user_id") != user_id:
+        raise FileNotFoundError(run_id)
+    return record
+
+
+def get_run(run_id: str, user_id: str) -> dict[str, Any]:
+    record = _load_record(run_id, user_id)
+    executor = record["executor"]
+    try:
+        if executor == "local":
+            status_path = Path(settings.NGS_RUN_ROOT).resolve() / run_id / "status.json"
+            if status_path.is_file():
+                status = json.loads(status_path.read_text(encoding="utf-8"))
+                record.update({key: status.get(key) for key in ("state", "exit_code", "message")})
+        elif executor == "slurm":
+            result = subprocess.run(
+                ["sacct", "-j", record["executor_job_id"], "--noheader", "--parsable2", "--format=State,ExitCode"],
+                capture_output=True, text=True, timeout=20, check=True,
+            )
+            line = next((line for line in result.stdout.splitlines() if line.strip()), "")
+            raw_state, _, exit_code = line.partition("|")
+            record["state"] = _slurm_state(raw_state)
+            record["exit_code"] = int(exit_code.split(":")[0]) if exit_code else None
+        else:
+            import boto3
+            client = boto3.client("batch", region_name=settings.NGS_AWS_REGION)
+            jobs = client.describe_jobs(jobs=[record["executor_job_id"]]).get("jobs", [])
+            if jobs:
+                job = jobs[0]
+                record["state"] = _aws_state(job.get("status", "UNKNOWN"))
+                record["exit_code"] = job.get("container", {}).get("exitCode")
+                record["message"] = job.get("statusReason")
+    except Exception as exc:
+        record["message"] = f"Status refresh failed: {type(exc).__name__}"
+    record["updated_at"] = _now()
+    _persist_record(record)
+    return record
+
+
+def _slurm_state(state: str) -> str:
+    state = state.upper().split()[0] if state else "UNKNOWN"
+    if state in {"PENDING", "CONFIGURING"}: return "PENDING"
+    if state in {"RUNNING", "COMPLETING"}: return "RUNNING"
+    if state == "COMPLETED": return "SUCCEEDED"
+    if state in {"FAILED", "CANCELLED", "TIMEOUT", "OUT_OF_MEMORY", "NODE_FAIL"}: return "FAILED"
+    return "UNKNOWN"
+
+
+def _aws_state(state: str) -> str:
+    return {"SUBMITTED": "SUBMITTED", "PENDING": "PENDING", "RUNNABLE": "PENDING", "STARTING": "PENDING", "RUNNING": "RUNNING", "SUCCEEDED": "SUCCEEDED", "FAILED": "FAILED"}.get(state, "UNKNOWN")
+
+
+def artifact_manifest(run_id: str, user_id: str) -> dict[str, Any]:
+    """Inventory actual output objects; never synthesize missing artifact evidence."""
+    record = _load_record(run_id, user_id)
+    outdir = record["outdir"]
+    if outdir.startswith("s3://"):
+        parsed = urlparse(outdir)
+        import boto3
+        client = boto3.client("s3", region_name=settings.NGS_AWS_REGION or None)
+        paginator = client.get_paginator("list_objects_v2")
+        files = [
+            f"s3://{parsed.netloc}/{item['Key']}"
+            for page in paginator.paginate(Bucket=parsed.netloc, Prefix=parsed.path.lstrip("/"))
+            for item in page.get("Contents", [])
+        ]
+    else:
+        root = Path(outdir).resolve()
+        if not root.is_dir():
+            files = []
+        else:
+            files = [str(path) for path in root.rglob("*") if path.is_file()]
+
+    lower = {path: path.lower() for path in files}
+    groups = {
+        "execution": [path for path, value in lower.items() if "pipeline_info/execution_" in value],
+        "multiqc": [path for path, value in lower.items() if "multiqc" in value],
+        "alignment": [path for path, value in lower.items() if value.endswith((".bam", ".cram", ".bai", ".crai"))],
+        "small_variants": [path for path, value in lower.items() if value.endswith((".vcf.gz", ".vcf.gz.tbi", ".g.vcf.gz", ".g.vcf.gz.tbi"))],
+        "coverage": [path for path, value in lower.items() if "mosdepth" in value or "coverage" in value],
+        "identity_qc": [path for path, value in lower.items() if any(token in value for token in ("contamination", "fingerprint", "verifybamid", "sex"))],
+        "provenance": [path for path, value in lower.items() if value.endswith(("run_manifest.json", "checksums.sha256"))],
+    }
+    missing = [name for name, evidence in groups.items() if not evidence]
+    return {
+        "run_id": run_id, "workflow": record["workflow"], "revision": record["revision"],
+        "source": outdir, "observed_file_count": len(files), "groups": groups,
+        "required_groups_complete": not missing, "missing_groups": missing,
+        "claim": "Observed artifact inventory only; presence does not imply QC or clinical validity.",
+    }

app/ngs/nextflow_worker.py

@@ -0,0 +1,33 @@
+"""Detached local Nextflow process wrapper that leaves a durable status file."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _write(path: Path, state: str, exit_code: int | None = None, message: str | None = None) -> None:
+    path.write_text(json.dumps({"state": state, "exit_code": exit_code, "message": message, "updated_at": datetime.now(timezone.utc).isoformat()}), encoding="utf-8")
+
+
+def main() -> int:
+    if len(sys.argv) < 4:
+        return 2
+    status_path, log_path, command = Path(sys.argv[1]), Path(sys.argv[2]), sys.argv[3:]
+    _write(status_path, "RUNNING")
+    try:
+        with log_path.open("w", encoding="utf-8") as log:
+            completed = subprocess.run(command, stdout=log, stderr=subprocess.STDOUT, text=True, check=False)
+        state = "SUCCEEDED" if completed.returncode == 0 else "FAILED"
+        _write(status_path, state, completed.returncode, None if completed.returncode == 0 else "Nextflow exited non-zero; inspect nextflow.log")
+        return completed.returncode
+    except Exception as exc:
+        _write(status_path, "FAILED", None, f"{type(exc).__name__}: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

app/ngs/orchestrator.py

@@ -35,6 +35,58 @@ from app.ngs.contracts import (
 
 logger = logging.getLogger(__name__)
 
+BENCHMARK_REGISTRY = [
+    {
+        "id": "giab-hg002-v4.2.1",
+        "source": "NIST Genome in a Bottle",
+        "scope": "HG002 germline small variants within benchmark regions",
+        "comparison_method": "GA4GH hap.py or vcfeval, stratified by variant type and genome context",
+        "url": "https://www.nist.gov/programs-projects/genome-bottle",
+        "status": "NOT_EVALUATED",
+        "metrics": None,
+        "reason": "This run did not supply HG002 reads, the matching truth VCF and benchmark BED, or a GA4GH comparison report.",
+    },
+    {
+        "id": "precisionfda-truth-v2",
+        "source": "FDA precisionFDA Truth Challenge V2",
+        "scope": "HG002/HG003/HG004 variants, including difficult-to-map regions",
+        "comparison_method": "Challenge-compatible precision, recall and F1 by region and variant class",
+        "url": "https://precision.fda.gov/challenges/10/results",
+        "status": "NOT_EVALUATED",
+        "metrics": None,
+        "reason": "No challenge-compatible callset and stratified evaluation output were produced by this run.",
+    },
+    {
+        "id": "seqc-gse47774",
+        "source": "NCBI GEO / SEQC consortium",
+        "scope": "RNA-seq accuracy and reproducibility reference dataset GSE47774",
+        "comparison_method": "Expression accuracy, replicate correlation and differential-expression reproducibility",
+        "url": "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE47774",
+        "status": "NOT_APPLICABLE",
+        "metrics": None,
+        "reason": "This WGS/WES workflow does not produce RNA-seq expression estimates.",
+    },
+]
+
+PRODUCTION_REQUIREMENTS = [
+    {"id": "complete_input", "label": "Complete FASTQ ingestion", "required": True,
+     "detail": "All records processed; no preview cap or silent subsampling."},
+    {"id": "production_alignment", "label": "Production read alignment", "required": True,
+     "detail": "Executed BWA-MEM2/DRAGMAP or another validated aligner with command and version."},
+    {"id": "bam_artifacts", "label": "Indexed alignment artifacts", "required": True,
+     "detail": "Coordinate-sorted BAM/CRAM, index, flagstat, idxstats and alignment metrics."},
+    {"id": "recalibration", "label": "Reference-matched recalibration", "required": True,
+     "detail": "BQSR or a documented no-BQSR workflow using build-matched known sites."},
+    {"id": "production_calls", "label": "Production germline callset", "required": True,
+     "detail": "Caller-generated VCF/gVCF with genotype, DP, GQ, AD, filters and index."},
+    {"id": "sample_qc", "label": "Sample QC and identity", "required": True,
+     "detail": "Coverage, duplication, insert size, contamination, sex and concordance when applicable."},
+    {"id": "truth_benchmark", "label": "GIAB/GA4GH truth comparison", "required": True,
+     "detail": "hap.py/vcfeval precision, recall and F1 inside the matching benchmark BED, stratified by SNP/INDEL."},
+    {"id": "reproducibility", "label": "Reproducible execution record", "required": True,
+     "detail": "Reference/resource checksums, exact commands, pipeline revision and container digests."},
+]
+
 
 class Pipeline:
     """Runs an ordered list of StageContracts over a shared sample/state context."""
@@ -69,10 +121,19 @@ class Pipeline:
             self.results.append(stage_result)
 
             if stage_result.qc:
-                for m in stage_result.qc.metrics:
-                    if m.status == QcStatus.WARN:
+                unevaluated = stage_result.data.get("unevaluated")
+                if unevaluated:
+                    self.warnings.append(
+                        f"[{contract.step}] Not evaluated: {unevaluated}."
+                    )
+                elif contract.step != "final_gate":
+                    for metric in stage_result.qc.metrics:
+                        if metric.status != QcStatus.WARN or metric.value is None:
+                            continue
+                        expected = f"; expected {metric.expected}" if metric.expected else ""
+                        detail = f" — {metric.detail}" if metric.detail else ""
                         self.warnings.append(
-                            f"[{contract.step}] {m.name}: {m.value} ({m.expected})"
+                            f"[{contract.step}] {metric.name}: {metric.value}{expected}{detail}"
                         )
 
             if stage_result.decision == Decision.STOP:
@@ -117,12 +178,16 @@ class Pipeline:
             "inputs": files,
             "reference": reference,
             "tools": [
-                {"stage": r.step, "name": r.tool, "version": r.version}
+                {"stage": r.step, "implementation": r.tool, "version": r.version,
+                 "evidence_level": r.evidence_level}
                 for r in self.results
             ],
         }
 
     def report(self) -> dict:
+        surrogate_stages = [r.step for r in self.results if r.evidence_level == "SURROGATE"]
+        requirements = [{**item, "status": "MISSING", "evidence": None}
+                        for item in PRODUCTION_REQUIREMENTS]
         return {
             "pipeline": self.name,
             "pipeline_version": self.version,
@@ -132,6 +197,16 @@ class Pipeline:
             "warnings": self.warnings,
             "stages": [r.to_dict() for r in self.results],
             "provenance": self.provenance,
+            "validation": {
+                "claim": "NO_ACCURACY_CLAIM",
+                "analysis_grade": "EXPLORATORY_PREVIEW",
+                "research_ready": False,
+                "summary": "This internal sampled/surrogate workflow has not been validated against a public truth set.",
+                "same_or_better_supported": False,
+                "surrogate_stages": surrogate_stages,
+                "production_requirements": requirements,
+                "comparisons": BENCHMARK_REGISTRY,
+            },
         }
 
     def _overall_status(self) -> QcStatus:

app/ngs/portable_benchmark_report.json

@@ -0,0 +1,68 @@
+{
+  "benchmark": "bionexus-tiny-target-v1",
+  "classification": "SYNTHETIC_POSITIVE_CONTROL",
+  "status": "PASS",
+  "workflow_output_parity": true,
+  "biological_scope": "one heterozygous SNP in a 200 bp synthetic target",
+  "expected_call": {
+    "chrom": "chrTiny",
+    "pos": 50,
+    "ref": "C",
+    "alt": "G",
+    "genotype": "0/1",
+    "depth": 20,
+    "allelic_depth": "10,10"
+  },
+  "toolchain": {
+    "nextflow": "26.04.6",
+    "samtools": "1.24",
+    "bcftools": "1.24",
+    "filter": "QUAL>=20 && FORMAT/DP>=10"
+  },
+  "reports": [
+    {
+      "orchestrator": "Bio-Nexus direct",
+      "execution": "EXECUTED",
+      "normalized_sha256": "cefef322e336202da82549c1d5c09cf546a70b4aacfe9d1cc7e090a8aa23bbb1",
+      "tp": 1,
+      "fp": 0,
+      "fn": 0,
+      "precision": 1.0,
+      "recall": 1.0,
+      "f1": 1.0
+    },
+    {
+      "orchestrator": "Nextflow",
+      "execution": "EXECUTED",
+      "normalized_sha256": "cefef322e336202da82549c1d5c09cf546a70b4aacfe9d1cc7e090a8aa23bbb1",
+      "tp": 1,
+      "fp": 0,
+      "fn": 0,
+      "precision": 1.0,
+      "recall": 1.0,
+      "f1": 1.0
+    },
+    {
+      "orchestrator": "Galaxy wrapper command",
+      "execution": "EXECUTED_WITHOUT_GALAXY_SERVER",
+      "normalized_sha256": "cefef322e336202da82549c1d5c09cf546a70b4aacfe9d1cc7e090a8aa23bbb1",
+      "tp": 1,
+      "fp": 0,
+      "fn": 0,
+      "precision": 1.0,
+      "recall": 1.0,
+      "f1": 1.0
+    }
+  ],
+  "galaxy_validation": {
+    "wrapper_lint": "PASS",
+    "local_server_test": "NOT_COMPLETED",
+    "reason": "Galaxy 25.1 cloned, but its pinned dependency bootstrap was interrupted by proxy failures."
+  },
+  "limitations": [
+    "This validates deterministic workflow portability, not real-sample accuracy.",
+    "Only one synthetic heterozygous SNP in an easy 200 bp target is tested.",
+    "Indels, difficult regions, SVs, CNVs, contamination and annotation are not tested.",
+    "This does not establish parity with nf-core/sarek as a whole or a public Galaxy server."
+  ]
+}

app/ngs/production.py

@@ -0,0 +1,189 @@
+"""Production Sarek planning and fail-closed clinical software gates.
+
+This module does not execute Nextflow inside the request process. It emits an auditable,
+pinned launch contract for a durable compute worker and evaluates imported run evidence.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import shlex
+from typing import Any
+
+from app.models.responses import NgsClinicalEvidenceRequest, NgsProductionPlanRequest
+from app.config import settings
+
+SAREK_RELEASE = "3.10.0"
+SCHEMA_VERSION = "1.0"
+SHA256_RE = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+def _artifact(artifact_id: str, description: str, patterns: list[str]) -> dict[str, Any]:
+    return {"id": artifact_id, "required": True, "description": description, "patterns": patterns}
+
+
+REQUIRED_ARTIFACTS = [
+    _artifact("execution", "Nextflow execution reports from the actual run", ["pipeline_info/execution_trace*.txt", "pipeline_info/execution_report*.html", "pipeline_info/execution_timeline*.html"]),
+    _artifact("multiqc", "Aggregated Sarek QC report and parsed data", ["multiqc/multiqc_report.html", "multiqc/multiqc_data/"]),
+    _artifact("alignment", "Coordinate-sorted alignment and index", ["**/*.bam|**/*.cram", "**/*.bai|**/*.crai"]),
+    _artifact("small_variants", "Caller VCF/gVCF and tabix index", ["**/*.vcf.gz", "**/*.vcf.gz.tbi"]),
+    _artifact("coverage", "Assay-appropriate coverage metrics", ["reports/**/mosdepth*", "reports/**/coverage*"]),
+    _artifact("identity_qc", "Sample identity, contamination and sex/ploidy evidence", ["reports/**/*contamination*", "reports/**/*fingerprint*", "reports/**/*sex*"]),
+    _artifact("provenance", "Checksums and immutable workflow/resource identifiers", ["run_manifest.json", "checksums.sha256"]),
+]
+
+PROVENANCE_REQUIREMENTS = [
+    "nf-core/sarek revision and Nextflow version",
+    "container image digest for every executed process",
+    "input sample-sheet SHA-256 and input file checksums",
+    "reference FASTA, indexes, known-sites, target BED and annotation-cache checksums",
+    "complete command argument array, profile and custom configuration checksum",
+    "execution trace with process exit status and retry history",
+]
+
+
+def build_production_plan(request: NgsProductionPlanRequest) -> dict[str, Any]:
+    blockers: list[str] = []
+    warnings: list[str] = []
+    if request.assay == "WES" and not (request.target_bed or "").strip():
+        blockers.append("WES requires a reference-matched target BED.")
+    if request.execution_profile in {"slurm", "awsbatch"} and not (request.custom_config or "").strip():
+        blockers.append(f"{request.execution_profile} requires a reviewed Nextflow custom configuration.")
+    if request.input_type == "FASTQ" and request.start_step != "mapping":
+        blockers.append("FASTQ input must start at Sarek's mapping step.")
+    if request.input_type == "CRAM" and request.start_step == "mapping":
+        blockers.append("CRAM input must start at markduplicates or variant_calling and include its CRAI in the sample sheet.")
+    if request.input_type == "BAM" and request.start_step == "mapping":
+        warnings.append("BAM at the mapping step must be an unmapped BAM; prepared alignments should start at markduplicates or variant_calling with an index.")
+    if request.genome == "GRCh37":
+        warnings.append("GRCh37 resources must all use the same contig naming and bundle; hg19 resources are not interchangeable by label alone.")
+    if request.clinical_intent:
+        warnings.append("Clinical intent activates a fail-closed evidence gate; this launch plan alone cannot validate or authorize an assay.")
+    if request.sample_model != "singleton" and request.caller != "haplotypecaller":
+        warnings.append("The selected caller produces per-sample results here; joint germline calling is enabled only for HaplotypeCaller.")
+
+    profile = request.execution_profile
+    sarek_genome = {"GRCh38": "GATK.GRCh38", "GRCh37": "GATK.GRCh37"}[request.genome]
+    argv = [
+        "nextflow", "run", "nf-core/sarek", "-r", SAREK_RELEASE,
+        "-profile", profile,
+        "--input", request.samplesheet_path,
+        "--outdir", request.outdir,
+        "--genome", sarek_genome,
+        "--tools", f"{request.caller}{',vep' if request.annotate_with_vep else ''}",
+        "--step", request.start_step,
+    ]
+    if request.assay == "WES":
+        argv.extend(["--wes", "--intervals", request.target_bed or ""])
+    if request.custom_config:
+        argv.extend(["-c", request.custom_config])
+    if request.sample_model != "singleton" and request.caller == "haplotypecaller":
+        argv.append("--joint_germline")
+
+    ready = not blockers
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "workflow": {
+            "name": "nf-core/sarek",
+            "revision": SAREK_RELEASE,
+            "execution_engine": "Nextflow",
+            "assay": request.assay,
+            "sample_model": request.sample_model,
+            "input_type": request.input_type,
+            "start_step": request.start_step,
+        },
+        "state": "PLANNED" if ready else "BLOCKED",
+        "ready_to_launch": ready,
+        "blockers": blockers,
+        "warnings": warnings,
+        "command_argv": argv,
+        "command_display": shlex.join(argv),
+        "required_artifacts": REQUIRED_ARTIFACTS,
+        "provenance_requirements": PROVENANCE_REQUIREMENTS,
+        "clinical_boundary": {
+            "clinical_intent": request.clinical_intent,
+            "current_status": "NOT_CLINICALLY_RELEASABLE",
+            "reason": "No executed run evidence, assay-validation record, benchmark evidence or authorized review has been imported.",
+        },
+    }
+
+
+def _present(value: str | None) -> bool:
+    return bool(value and value.strip())
+
+
+def _sha256(value: str | None) -> bool:
+    return bool(value and SHA256_RE.fullmatch(value))
+
+
+def clinical_signature_payload(evidence: NgsClinicalEvidenceRequest) -> bytes:
+    """Canonical bytes signed by the trusted evidence-import service."""
+    if hasattr(evidence, "model_dump"):
+        payload = evidence.model_dump(mode="json", exclude={"evidence_signature"})
+    else:  # Pydantic v1 compatibility for older self-hosted deployments.
+        payload = evidence.dict(exclude={"evidence_signature"})
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _signature_verified(evidence: NgsClinicalEvidenceRequest) -> bool:
+    key = settings.NGS_CLINICAL_EVIDENCE_HMAC_KEY
+    if not key or not evidence.evidence_signature or not _sha256(evidence.evidence_bundle_sha256):
+        return False
+    expected = hmac.new(key.encode("utf-8"), clinical_signature_payload(evidence), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, evidence.evidence_signature)
+
+
+def evaluate_clinical_evidence(evidence: NgsClinicalEvidenceRequest) -> dict[str, Any]:
+    metrics_present = all(value is not None for value in (
+        evidence.snv_precision, evidence.snv_recall,
+        evidence.indel_precision, evidence.indel_recall,
+    ))
+    truth_is_external = _present(evidence.truthset_name) and "synthetic" not in evidence.truthset_name.lower()
+    review_complete = evidence.human_reviewed and _present(evidence.reviewer_id) and _present(evidence.release_signature_id)
+    signature_verified = _signature_verified(evidence)
+
+    checks: list[tuple[str, str, bool, str]] = [
+        ("evidence_signature", "Trusted evidence bundle signature verified", signature_verified, evidence.evidence_bundle_sha256 or "missing or unverified"),
+        ("assay_validation", "Validated assay record", _present(evidence.assay_validation_id), evidence.assay_validation_id or "missing"),
+        ("execution", "Pinned workflow completed", evidence.workflow_status == "COMPLETED" and _present(evidence.sarek_revision), f"{evidence.workflow_status}; revision={evidence.sarek_revision or 'missing'}"),
+        ("reference", "Reference and sample-sheet checksums", evidence.reference_build is not None and _sha256(evidence.reference_manifest_sha256) and _sha256(evidence.samplesheet_sha256), evidence.reference_build or "missing"),
+        ("containers", "Container digests captured", evidence.container_digests_complete, str(evidence.container_digests_complete)),
+        ("complete_input", "All input records processed", evidence.complete_input_processed, str(evidence.complete_input_processed)),
+        ("artifacts", "Required artifacts imported", evidence.required_artifacts_present, str(evidence.required_artifacts_present)),
+        ("qc", "Run QC passed", evidence.qc_pass, str(evidence.qc_pass)),
+        ("identity", "Sample identity passed", evidence.sample_identity_pass, str(evidence.sample_identity_pass)),
+        ("contamination", "Contamination gate passed", evidence.contamination_pass, str(evidence.contamination_pass)),
+        ("sex_ploidy", "Sex/ploidy reviewed", evidence.sex_ploidy_reviewed, str(evidence.sex_ploidy_reviewed)),
+        ("truth_benchmark", "External truth benchmark passed its approved protocol", bool(truth_is_external and _present(evidence.benchmark_protocol_id) and evidence.benchmark_acceptance_pass and _sha256(evidence.confident_regions_sha256) and evidence.same_sample_reference_regions and metrics_present), evidence.truthset_name or "missing"),
+        ("human_release", "Authorized human review and release signature", review_complete, evidence.reviewer_id or "missing"),
+        ("deviations", "No unresolved deviations", not evidence.unresolved_deviations, ", ".join(evidence.unresolved_deviations) or "none"),
+    ]
+    gates = [
+        {"id": gate_id, "label": label, "status": "PASS" if passed else "FAIL", "evidence": detail}
+        for gate_id, label, passed, detail in checks
+    ]
+    missing = [label for _gate_id, label, passed, _detail in checks if not passed]
+    passed = not missing
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "status": "SOFTWARE_GATE_PASSED" if passed else "NOT_CLINICALLY_RELEASABLE",
+        "clinically_validated": False,
+        "gates": gates,
+        "missing_or_failed": missing,
+        "benchmark_summary": {
+            "truthset": evidence.truthset_name,
+            "protocol_id": evidence.benchmark_protocol_id,
+            "same_sample_reference_regions": evidence.same_sample_reference_regions,
+            "acceptance_pass": evidence.benchmark_acceptance_pass,
+            "metrics": {
+                "snv_precision": evidence.snv_precision,
+                "snv_recall": evidence.snv_recall,
+                "indel_precision": evidence.indel_precision,
+                "indel_recall": evidence.indel_recall,
+            },
+        },
+        "disclaimer": "This is a software evidence gate, not clinical validation, accreditation, diagnosis or report authorization. Laboratory validation and jurisdiction-specific governance remain required.",
+    }

app/ngs/stages/stage10_identity.py

@@ -107,7 +107,7 @@ def _stage10_run(sample: dict, state: dict) -> tuple[dict, dict]:
     if records is None:
         return ({"error": "identity needs aligned reads",
                  "unevaluated": "no aligned reads"},
-                {"identity_checked": 0.0})   # WARN: cannot assert identity without alignment
+                {})
     eng = identity_engine(
         records,
         expected_gt=sample.get("expected_gt"),
@@ -120,16 +120,37 @@ def _stage10_run(sample: dict, state: dict) -> tuple[dict, dict]:
     # unevaluated (WARN) rather than silently passing or hard-failing the pipeline.
     if eng["concordance"] is None and eng["sex_match"] is None:
         eng["unevaluated"] = ("no expected genotype or sex supplied; sample identity not asserted")
-        return eng, {"identity_checked": 0.0}
+        eng["status"] = "NOT_EVALUATED"
+        return eng, {}
     metrics = {}
     if eng["concordance"] is not None:
         metrics["concordance_ok"] = eng["concordance"]
     if eng["sex_match"] is not None:
         metrics["sex_ok"] = 100.0 if eng["sex_match"] else 0.0
-    metrics["identity_checked"] = 100.0
     return eng, metrics
 
 
+def _identity_rules(sample: dict) -> list[ThresholdRule]:
+    rules: list[ThresholdRule] = []
+    if sample.get("expected_gt"):
+        rules.append(ThresholdRule(
+            name="concordance_ok", metric="concordance_ok",
+            evaluate=lambda v: _match_rule(v, 99.0), expectation=">= 99%",
+        ))
+    if sample.get("expected_sex"):
+        rules.append(ThresholdRule(
+            name="sex_ok", metric="sex_ok", evaluate=lambda v: _bool_rule(v),
+            expectation="matches declared sample sex",
+        ))
+    if not rules:
+        rules.append(ThresholdRule(
+            name="identity_evidence", metric="identity_evidence",
+            evaluate=lambda _v: QcStatus.PASS, optional=True,
+            missing_detail="Not evaluated: expected genotypes and declared sample sex were not supplied.",
+        ))
+    return rules
+
+
 def stage10_contract() -> StageContract:
     return StageContract(
         step="identity",
@@ -137,24 +158,12 @@ def stage10_contract() -> StageContract:
         version="0.1.0",
         inputs=["processed_bam", "expected_genotypes?", "expected_sex?"],
         outputs=["identity_report"],
-        rules=[
-            ThresholdRule(name="identity_checked", metric="identity_checked",
-                          evaluate=lambda v: _checked_rule(v)),
-            ThresholdRule(name="concordance_ok", metric="concordance_ok",
-                          evaluate=lambda v: _match_rule(v, 99.0), optional=True),
-            ThresholdRule(name="sex_ok", metric="sex_ok",
-                          evaluate=lambda v: _bool_rule(v), optional=True),
-        ],
+        rules=_identity_rules,
         fail_blocks=True,   # mislabeled/swapped sample stops the run
         run=_stage10_run,
     )
 
 
-def _checked_rule(v):
-    # 100 = a real check ran; 0 = unevaluated (WARN, not blocking)
-    return QcStatus.PASS if float(v) >= 100.0 else QcStatus.WARN
-
-
 def _match_rule(v, ok):
     try:
         v = float(v)
@@ -177,16 +186,13 @@ def run_identity(
     from app.ngs.contracts import apply_rules, QcResult
     eng = identity_engine(records, expected_gt, chr_x_depth, chr_y_depth, expected_sex)
     metrics = {}
-    if eng["concordance"] is None and eng["sex_match"] is None:
-        metrics["identity_checked"] = 0.0
-    else:
-        metrics["identity_checked"] = 100.0
     if eng["concordance"] is not None:
         metrics["concordance_ok"] = eng["concordance"]
     if eng["sex_match"] is not None:
         metrics["sex_ok"] = 100.0 if eng["sex_match"] else 0.0
     contract = stage10_contract()
-    result = QcResult.from_metrics(apply_rules(contract.resolve_rules({}), metrics),
+    sample = {"expected_gt": expected_gt, "expected_sex": expected_sex}
+    result = QcResult.from_metrics(apply_rules(contract.resolve_rules(sample), metrics),
                                    fail_blocks=True)
     return {
         "result": {"step": "identity", "qc": result.to_dict(),

app/ngs/stages/stage11_variant_calling.py

@@ -131,6 +131,7 @@ def stage11_contract() -> StageContract:
         rules=[],
         fail_blocks=False,
         run=_stage11_run,
+        evidence_level="SURROGATE",
     )
 
 

app/ngs/stages/stage14_filter.py

@@ -63,15 +63,14 @@ def filter_variants(variants: list[dict], max_af: float = 0.01) -> dict:
 
 
 def _stage14_run(sample: dict, state: dict) -> tuple[dict, dict]:
-    variants = state.get("variants", {}).get("qc", {}).get("variants") or \
-        state.get("variants", {}).get("normalized")
+    variants = state.get("variants", {}).get("qc", {}).get("variants")
     if variants is None:
-        return {"error": "filtering needs QC'd variants"}, {"candidate_frac": 0.0}
+        variants = state.get("variants", {}).get("normalized")
+    if variants is None:
+        return {"error": "filtering needs QC'd variants"}, {"filter_completed": 0.0}
     filtered = filter_variants(variants)
     state.setdefault("variants", {})["filtered"] = filtered
-    total = filtered["n_final"] + filtered["n_rejected"]
-    frac = filtered["n_final"] / total * 100.0 if total else 0.0
-    return filtered, {"candidate_frac": frac}
+    return filtered, {"filter_completed": 100.0}
 
 
 def stage14_contract() -> StageContract:
@@ -82,31 +81,29 @@ def stage14_contract() -> StageContract:
         inputs=["qc_variants"],
         outputs=["final_variants"],
         rules=[
-            ThresholdRule(name="candidate_frac", metric="candidate_frac",
-                          evaluate=lambda v: _range_rule(v, 0.1, 30.0)),
+            ThresholdRule(name="filter_completed", metric="filter_completed",
+                          evaluate=lambda v: _completed_rule(v), expectation="completed"),
         ],
         fail_blocks=False,
         run=_stage14_run,
     )
 
 
-def _range_rule(v, lo, hi):
+def _completed_rule(v):
     from app.ngs.contracts import QcStatus
     try:
         v = float(v)
     except (TypeError, ValueError):
         return QcStatus.FAIL
-    return QcStatus.PASS if lo <= v <= hi else QcStatus.WARN
+    return QcStatus.PASS if v >= 100.0 else QcStatus.FAIL
 
 
 def run_variant_filter(variants: list[dict], max_af: float = 0.01) -> dict:
     from app.ngs.contracts import apply_rules, QcResult
     filtered = filter_variants(variants, max_af=max_af)
-    total = filtered["n_final"] + filtered["n_rejected"]
-    frac = filtered["n_final"] / total * 100.0 if total else 0.0
     contract = stage14_contract()
     result = QcResult.from_metrics(
-        apply_rules(contract.resolve_rules({}), {"candidate_frac": frac}), fail_blocks=False)
+        apply_rules(contract.resolve_rules({}), {"filter_completed": 100.0}), fail_blocks=False)
     return {
         "result": {"step": "variant_filter", "qc": result.to_dict(),
                    "decision": result.decision.value,

app/ngs/stages/stage15_sv.py

@@ -123,6 +123,7 @@ def stage15_contract() -> StageContract:
         ],
         fail_blocks=False,
         run=_stage15_run,
+        evidence_level="SURROGATE",
     )
 
 

app/ngs/stages/stage16_cnv.py

@@ -132,6 +132,7 @@ def stage16_contract() -> StageContract:
         ],
         fail_blocks=False,
         run=_stage16_run,
+        evidence_level="SURROGATE",
     )
 
 

app/ngs/stages/stage17_annotation.py

@@ -155,15 +155,17 @@ def run_annotation(variants: list[dict], transcripts: list[dict]) -> dict:
 
 
 def _stage17_run(sample: dict, state: dict) -> tuple[dict, dict]:
-    variants = state.get("variants", {}).get("filtered", {}).get("final") or \
-        state.get("variants", {}).get("final")
+    variants = state.get("variants", {}).get("filtered", {}).get("final")
+    if variants is None:
+        variants = state.get("variants", {}).get("final")
     transcripts = sample.get("transcripts") or state.get("transcripts") or []
     if variants is None:
-        return {"error": "annotation needs final variants"}, {"annotate_frac": 0.0}
+        return {"error": "annotation needs final variants"}, {"annotation_completed": 0.0}
     report = run_annotation(variants, transcripts)
+    report["status"] = "NOT_APPLICABLE" if not variants else "COMPLETED"
+    report["n_input_variants"] = len(variants)
     state.setdefault("variants", {})["annotated"] = report
-    frac = report["n_annotated"] / len(variants) * 100.0 if variants else 100.0
-    return report, {"annotate_frac": frac}
+    return report, {"annotation_completed": 100.0}
 
 
 def stage17_contract() -> StageContract:
@@ -174,8 +176,8 @@ def stage17_contract() -> StageContract:
         inputs=["final_variants", "transcripts"],
         outputs=["annotated_variants"],
         rules=[
-            ThresholdRule(name="annotate_frac", metric="annotate_frac",
-                          evaluate=lambda v: _pct_rule(v, 90, 70)),
+            ThresholdRule(name="annotation_completed", metric="annotation_completed",
+                          evaluate=lambda v: _pct_rule(v, 100, 100), expectation="completed"),
         ],
         fail_blocks=False,
         run=_stage17_run,
@@ -197,10 +199,9 @@ def _pct_rule(v, ok, warn):
 def run_annotation_stage(variants: list[dict], transcripts: list[dict]) -> dict:
     from app.ngs.contracts import apply_rules, QcResult
     report = run_annotation(variants, transcripts)
-    frac = report["n_annotated"] / len(variants) * 100.0 if variants else 100.0
     contract = stage17_contract()
     result = QcResult.from_metrics(
-        apply_rules(contract.resolve_rules({}), {"annotate_frac": frac}), fail_blocks=False)
+        apply_rules(contract.resolve_rules({}), {"annotation_completed": 100.0}), fail_blocks=False)
     return {
         "result": {"step": "annotation", "qc": result.to_dict(),
                    "decision": result.decision.value, "data": report["summary"]},

app/ngs/stages/stage21_final_gate.py

@@ -75,19 +75,17 @@ def evaluate_gate(pipeline_report: dict) -> dict:
             f"{verdict}: {len(blocked)} blocking gate(s) failed"
             if blocked else
             (f"{verdict}: proceeding with {len(warners)} warning(s)"
-             if warners else "all {passed} pipeline stages passed")),
+             if warners else f"all {passed} pipeline stages passed")),
     }
 
 
 def _stage21_run(sample: dict, state: dict) -> tuple[dict, dict]:
     report = sample.get("pipeline_report") or state.get("pipeline_report")
     if report is None:
-        return {"error": "final gate needs the pipeline report"}, {"gate_ok": 100.0}
+        return {"error": "final gate needs the pipeline report"}, {"readiness_verdict": "NOT_ANALYSIS_READY"}
     gate = evaluate_gate(report)
     state.setdefault("final_gate", {})["result"] = gate
-    ok = 100.0 if gate["verdict"] == "ANALYSIS_READY" else (
-        60.0 if gate["verdict"] == "ANALYSIS_READY_WITH_WARNINGS" else 0.0)
-    return gate, {"gate_ok": ok}
+    return gate, {"readiness_verdict": gate["verdict"]}
 
 
 def stage21_contract() -> StageContract:
@@ -98,8 +96,11 @@ def stage21_contract() -> StageContract:
         inputs=["pipeline_report"],
         outputs=["readiness_verdict"],
         rules=[
-            ThresholdRule(name="gate_ok", metric="gate_ok",
-                          evaluate=lambda v: _gate_rule(v)),
+            ThresholdRule(
+                name="readiness_verdict", metric="readiness_verdict",
+                evaluate=lambda v: _gate_rule(v),
+                expectation="ANALYSIS_READY or ANALYSIS_READY_WITH_WARNINGS",
+            ),
         ],
         fail_blocks=True,   # a NOT_READY verdict stops the report from being finalised
         run=_stage21_run,
@@ -107,13 +108,9 @@ def stage21_contract() -> StageContract:
 
 
 def _gate_rule(v):
-    try:
-        v = float(v)
-    except (TypeError, ValueError):
-        return QcStatus.FAIL
-    if v >= 100.0:
+    if v == "ANALYSIS_READY":
         return QcStatus.PASS
-    if v >= 60.0:
+    if v == "ANALYSIS_READY_WITH_WARNINGS":
         return QcStatus.WARN
     return QcStatus.FAIL
 
@@ -121,10 +118,9 @@ def _gate_rule(v):
 def run_final_gate(pipeline_report: dict) -> dict:
     from app.ngs.contracts import apply_rules, QcResult
     gate = evaluate_gate(pipeline_report)
-    ok = 100.0 if gate["verdict"] == "ANALYSIS_READY" else (
-        60.0 if gate["verdict"] == "ANALYSIS_READY_WITH_WARNINGS" else 0.0)
     contract = stage21_contract()
-    result = QcResult.from_metrics(apply_rules(contract.resolve_rules({}), {"gate_ok": ok}),
+    result = QcResult.from_metrics(apply_rules(
+        contract.resolve_rules({}), {"readiness_verdict": gate["verdict"]}),
                                    fail_blocks=True)
     return {
         "result": {"step": "final_gate", "qc": result.to_dict(),

app/ngs/stages/stage4_reference.py

@@ -40,6 +40,23 @@ def _stage4_run(sample: dict, state: dict) -> tuple[dict, dict]:
     meta = sample.get("metadata") or {}
     annotation_build = sample.get("annotation_build") or meta.get("annotation_build")
 
+    if sample.get("synthetic_reference"):
+        ref = {
+            "id": "synthetic-positive-control",
+            "reference_kind": "SYNTHETIC",
+            "build": "NOT_APPLICABLE",
+            "requested_template": str(ref_id or "not specified"),
+            "description": "Deterministic reference generated from demonstration reads",
+            "species": "NOT_APPLICABLE",
+            "generated_for_this_run": True,
+            "bundled": False,
+            "artifacts": [{"name": "In-memory synthetic reference", "present": True}],
+            "build_compatible": "NOT_APPLICABLE",
+            "build_message": "Synthetic coordinates are not GRCh37/GRCh38 coordinates.",
+        }
+        state.setdefault("reference", {})["declared"] = ref
+        return ref, {"reference_resolved": 100.0, "build_compatible": 100.0}
+
     if not ref_id:
         return {"error": "no reference specified"}, {"reference_resolved": 0.0,
                                                      "build_compatible": 100.0}

app/ngs/stages/stage5_alignment.py

@@ -15,9 +15,6 @@ feeds Stage 6 (BAM processing), Stage 7 (alignment QC) and Stage 8 (coverage).
 
 from __future__ import annotations
 
-import os
-import shutil
-import subprocess
 from typing import Optional
 
 from app.ngs.contracts import QcStatus, StageContract, ThresholdRule
@@ -38,10 +35,6 @@ def choose_aligner(assay: str, read_length: Optional[int]) -> str:
     return "bwa-mem2"
 
 
-def _find_tool(name: str) -> Optional[str]:
-    return shutil.which(name)
-
-
 def _align_python(
     ref_seq: str,
     reads: list[tuple[str, str, str]],
@@ -59,21 +52,15 @@ def align(
 ) -> tuple[list[dict], dict]:
     """Align reads to a reference sequence. Returns (SAM records, meta).
 
-    External tools are used when available; otherwise the pure-Python fallback runs. The
-    selection and execution record both go into the provenance/meta so it's auditable.
+    This endpoint currently executes the platform's seed-based Python aligner. The recommended
+    production aligner is recorded separately and must never be represented as executed.
     """
     aligner = choose_aligner(assay, read_length)
-    used_external = False
-    tool = _find_tool(aligner)
-    if tool:
-        used_external = True
-        # Real BWA/STAR would consume FASTQ + reference FASTA; for the surrogate we still
-        # produce records from the Python aligner but record the intended external tool.
     records = _align_python(ref_seq, reads, ref_name=ref_name)
     return records, {
-        "aligner": aligner,
-        "aligner_available": bool(tool),
-        "executor": "external" if used_external else "python-fallback",
+        "recommended_production_aligner": aligner,
+        "executed_implementation": "bionexus-seed-aligner",
+        "executor": "python-surrogate",
         "reference": ref_name,
         "read_length": read_length,
         "aligned_reads": len(records),
@@ -102,7 +89,7 @@ def _stage5_run(sample: dict, state: dict) -> tuple[dict, dict]:
 def stage5_contract() -> StageContract:
     return StageContract(
         step="alignment",
-        tool="platform-aligner (bwa-mem2 / minimap2 / STAR)",
+        tool="bionexus-seed-aligner",
         version="0.1.0",
         inputs=["clean_fastq", "reference_sequence"],
         outputs=["aligned_reads"],
@@ -112,6 +99,7 @@ def stage5_contract() -> StageContract:
         ],
         fail_blocks=False,
         run=_stage5_run,
+        evidence_level="SURROGATE",
     )
 
 

app/ngs/stages/stage6_bam.py

@@ -104,6 +104,7 @@ def stage6_contract() -> StageContract:
         ],
         fail_blocks=False,   # high duplication is a WARN, not a stop (it can be filtered)
         run=_stage6_run,
+        evidence_level="SURROGATE",
     )
 
 

app/ngs/stages/stage8_coverage.py

@@ -156,12 +156,37 @@ def _stage8_run(sample: dict, state: dict) -> tuple[dict, dict]:
     eng = coverage_engine(records, ref_lengths, targets)
     state.setdefault("coverage", {})["engine"] = eng
     g = eng["genome"]
+    if sample.get("synthetic_reference") or sample.get("demonstration_data"):
+        return eng, {
+            "synthetic_reference_covered": g["coverage_1x"],
+            "synthetic_uniformity": g["uniformity"],
+        }
     return eng, {
         "coverage_ok": g["coverage_30x"],
         "uniformity_ok": g["uniformity"],
     }
 
 
+def _coverage_rules(sample: dict) -> list[ThresholdRule]:
+    if sample.get("synthetic_reference") or sample.get("demonstration_data"):
+        return [
+            ThresholdRule(
+                name="synthetic_reference_covered", metric="synthetic_reference_covered",
+                evaluate=lambda v: _pct_rule(v, 95, 80), expectation=">= 95% at 1x",
+            ),
+            ThresholdRule(
+                name="synthetic_uniformity", metric="synthetic_uniformity",
+                evaluate=lambda v: _pct_rule(v, 95, 80), expectation=">= 95%",
+            ),
+        ]
+    return [
+        ThresholdRule(name="coverage_ok", metric="coverage_ok",
+                      evaluate=lambda v: _pct_rule(v, 85, 60), expectation=">= 85% at 30x"),
+        ThresholdRule(name="uniformity_ok", metric="uniformity_ok",
+                      evaluate=lambda v: _pct_rule(v, 80, 60), expectation=">= 80%"),
+    ]
+
+
 def stage8_contract() -> StageContract:
     return StageContract(
         step="coverage",
@@ -169,12 +194,7 @@ def stage8_contract() -> StageContract:
         version="0.1.0",
         inputs=["processed_bam", "reference_lengths", "target_regions?"],
         outputs=["coverage_report"],
-        rules=[
-            ThresholdRule(name="coverage_ok", metric="coverage_ok",
-                          evaluate=lambda v: _pct_rule(v, 85, 60)),
-            ThresholdRule(name="uniformity_ok", metric="uniformity_ok",
-                          evaluate=lambda v: _pct_rule(v, 80, 60)),
-        ],
+        rules=_coverage_rules,
         fail_blocks=False,
         run=_stage8_run,
     )

app/ngs/stages/stage9_contamination.py

@@ -79,14 +79,14 @@ def _stage9_run(sample: dict, state: dict) -> tuple[dict, dict]:
     if records is None:
         return ({"error": "contamination needs aligned records",
                  "unevaluated": "no aligned reads"},
-                {"contam_checked": 0.0, "contam_ok": 100.0})
+                {})
     if not sites:
         return ({"unevaluated": "no SNP panel supplied; contamination not asserted",
-                 "contam_rate": 0.0},
-                {"contam_checked": 0.0, "contam_ok": 100.0})
+                 "contam_rate": None, "status": "NOT_EVALUATED"},
+                {})
     eng = contamination_engine(records, sites)
     state.setdefault("contamination", {})["engine"] = eng
-    return eng, {"contam_checked": 100.0, "contam_ok": round(100.0 - eng["contam_rate"], 3)}
+    return eng, {"contamination_pct": eng["contam_rate"]}
 
 
 def stage9_contract() -> StageContract:
@@ -97,30 +97,27 @@ def stage9_contract() -> StageContract:
         inputs=["processed_bam", "snp_sites"],
         outputs=["contamination_report"],
         rules=[
-            ThresholdRule(name="contam_checked", metric="contam_checked",
-                          evaluate=lambda v: _checked_rule(v)),
-            ThresholdRule(name="contam_ok", metric="contam_ok",
-                          evaluate=lambda v: _invert_pct_rule(v, 98.0, 95.0)),
+            ThresholdRule(
+                name="contamination_pct", metric="contamination_pct",
+                evaluate=lambda v: _contamination_rule(v), expectation="<= 2%",
+                optional=True,
+                missing_detail="Not evaluated: a reference-matched SNP panel was not supplied.",
+            ),
         ],
         fail_blocks=True,   # contamination FAIL blocks downstream variant calling
         run=_stage9_run,
+        evidence_level="SURROGATE",
     )
 
 
-def _checked_rule(v):
-    # 100 = a real SNP-panel check ran; 0 = unevaluated (WARN, not blocking)
-    return QcStatus.PASS if float(v) >= 100.0 else QcStatus.WARN
-
-
-def _invert_pct_rule(v, ok, warn):
-    # ok = min "purity" for PASS, warn = min for WARN; below warn -> FAIL
+def _contamination_rule(v):
     try:
         v = float(v)
     except (TypeError, ValueError):
         return QcStatus.FAIL
-    if v >= ok:
+    if v <= 2.0:
         return QcStatus.PASS
-    if v >= warn:
+    if v <= 5.0:
         return QcStatus.WARN
     return QcStatus.FAIL
 
@@ -131,8 +128,7 @@ def run_contamination(
 ) -> dict:
     from app.ngs.contracts import apply_rules, QcResult
     eng = contamination_engine(records, snp_sites)
-    metrics = {"contam_ok": round(100.0 - eng["contam_rate"], 3),
-               "contam_checked": 100.0 if snp_sites else 0.0}
+    metrics = {"contamination_pct": eng["contam_rate"]} if snp_sites else {}
     contract = stage9_contract()
     result = QcResult.from_metrics(apply_rules(contract.resolve_rules({}), metrics),
                                    fail_blocks=True)

app/routers/ngs_v2.py

@@ -16,17 +16,31 @@ import logging
 import os
 import random
 import tempfile
+import json
+from pathlib import Path
 from typing import Optional
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 
 from app.ngs.assays import AssayRouter
 from app.ngs.orchestrator import build_dag, wgs_wes_germline_stages
+from app.ngs.production import build_production_plan, evaluate_clinical_evidence
+from app.ngs.execution import artifact_manifest, executor_capabilities, get_run, submit_run
+from app.services.auth import require_user_id
 from app.ngs.visualization import build_visualization
+from app.models.responses import (
+    NgsClinicalEvidenceRequest,
+    NgsClinicalEvidenceResponse,
+    NgsProductionPlanRequest,
+    NgsProductionPlanResponse,
+    NgsProductionRunResponse,
+    NgsProductionSubmitResponse,
+)
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/ngs/v2", tags=["ngs-v2"])
+FASTQ_RECORD_CAP_PER_FILE = 2000
 
 _DETECTOR = AssayRouter()
 
@@ -101,7 +115,7 @@ class DetectRequest(BaseModel):
     metadata: dict = {}
 
 
-def _read_fastq(path: str, cap: int = 2000) -> list[tuple[str, str, str]]:
+def _read_fastq(path: str, cap: int = FASTQ_RECORD_CAP_PER_FILE) -> tuple[list[tuple[str, str, str]], bool]:
     if not os.path.isfile(path):
         raise HTTPException(status_code=400, detail=f"file not found: {path}")
     reads: list[tuple[str, str, str]] = []
@@ -118,9 +132,10 @@ def _read_fastq(path: str, cap: int = 2000) -> list[tuple[str, str, str]]:
                 if not name.startswith("@") or not plus.startswith("+"):
                     continue
                 reads.append((name[1:].split()[0], seq, qual))
+            truncated = bool(fh.readline())
     except Exception as exc:
         raise HTTPException(status_code=400, detail=f"failed to read {path}: {exc}")
-    return reads
+    return reads, truncated
 
 
 def _demo_sequence(rng: random.Random, length: int = 150) -> str:
@@ -196,7 +211,8 @@ def _detection(payload, files: Optional[list[str]] = None) -> dict:
 def list_stages():
     contracts = wgs_wes_germline_stages()
     return {"pipeline": "wgs-wes-germline", "stages": [
-        {"step": c.step, "tool": c.tool, "inputs": c.inputs, "outputs": c.outputs,
+        {"step": c.step, "operation": c.step.replace("_", " "), "implementation": c.tool,
+         "evidence_level": c.evidence_level, "inputs": c.inputs, "outputs": c.outputs,
          "fail_blocks": c.fail_blocks, "expectation": _STAGE_INTRO.get(c.step, "")}
         for c in contracts
     ]}
@@ -207,6 +223,66 @@ def list_demos():
     return {"demos": [{"id": key, **value} for key, value in _DEMO_PROFILES.items()]}
 
 
+@router.get("/benchmarks/portable")
+def portable_benchmark():
+    report_path = Path(__file__).resolve().parents[1] / "ngs" / "portable_benchmark_report.json"
+    with report_path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+@router.post("/production/plan", response_model=NgsProductionPlanResponse)
+def production_plan(payload: NgsProductionPlanRequest):
+    return build_production_plan(payload)
+
+
+@router.get("/production/capabilities")
+def production_capabilities():
+    return executor_capabilities()
+
+
+@router.post("/production/submit", response_model=NgsProductionSubmitResponse)
+def production_submit(payload: NgsProductionPlanRequest, user_id: str = Depends(require_user_id)):
+    plan = build_production_plan(payload)
+    if not plan["ready_to_launch"]:
+        raise HTTPException(status_code=422, detail={"message": "production launch contract is blocked", "blockers": plan["blockers"]})
+    executor = "awsbatch" if payload.execution_profile == "awsbatch" else "slurm" if payload.execution_profile == "slurm" else "local"
+    try:
+        run = submit_run(executor, plan["command_argv"], payload.outdir, user_id)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("Production Sarek submission failed")
+        raise HTTPException(status_code=502, detail=f"executor submission failed: {type(exc).__name__}") from exc
+    return {
+        "run_id": run["run_id"], "state": "SUBMITTED", "executor": executor,
+        "executor_job_id": run["executor_job_id"], "message": "Real nf-core/sarek run submitted; no exploratory fallback was used.",
+    }
+
+
+@router.get("/production/runs/{run_id}", response_model=NgsProductionRunResponse)
+def production_run_status(run_id: str, user_id: str = Depends(require_user_id)):
+    try:
+        return get_run(run_id, user_id)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail="production run not found") from exc
+
+
+@router.get("/production/runs/{run_id}/artifacts")
+def production_run_artifacts(run_id: str, user_id: str = Depends(require_user_id)):
+    try:
+        return artifact_manifest(run_id, user_id)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail="production run not found") from exc
+    except Exception as exc:
+        logger.exception("Production Sarek artifact import failed")
+        raise HTTPException(status_code=502, detail=f"artifact import failed: {type(exc).__name__}") from exc
+
+
+@router.post("/clinical/evaluate", response_model=NgsClinicalEvidenceResponse)
+def clinical_evidence(payload: NgsClinicalEvidenceRequest):
+    return evaluate_clinical_evidence(payload)
+
+
 @router.post("/detect")
 def detect(payload: DetectRequest):
     return _detection(payload)
@@ -222,9 +298,12 @@ def analyze(payload: AnalyzeRequest):
         raise HTTPException(status_code=400, detail="provide file_paths, fastq_url, or demo_profile")
 
     reads_all: dict[str, list[tuple[str, str, str]]] = {}
+    truncated_inputs: list[str] = []
     for f in files:
-        got = _read_fastq(f)
+        got, truncated = _read_fastq(f)
         reads_all[f] = got
+        if truncated:
+            truncated_inputs.append(os.path.basename(f))
         if not got:
             raise HTTPException(status_code=400, detail=f"no FASTQ records read from {f}")
 
@@ -233,6 +312,8 @@ def analyze(payload: AnalyzeRequest):
     assay = (payload.assay or demo_assay or detection["assay"] or "WGS").upper()
     if assay in ("UNKNOWN", ""):
         assay = "WGS"
+    if payload.demo_profile:
+        detection["sample_type"] = "synthetic-positive-control"
 
     combined_reads = [read for f in files for read in reads_all.get(f, [])]
     sample: dict = {
@@ -240,7 +321,11 @@ def analyze(payload: AnalyzeRequest):
         "reference": payload.reference or "grch38",
         "assay": assay,
         "sample_type": payload.sample_type or detection["sample_type"],
-        "metadata": {**(payload.metadata or {}), **({"demo_profile": payload.demo_profile} if payload.demo_profile else {})},
+        "metadata": {
+            **({"platform": "illumina-simulated"} if payload.demo_profile else {}),
+            **(payload.metadata or {}),
+            **({"demo_profile": payload.demo_profile} if payload.demo_profile else {}),
+        },
         "demonstration_data": bool(payload.demo_profile or (payload.metadata or {}).get("demonstration_data")),
         "synthetic_reference": bool(payload.synthetic_reference or payload.demo_profile),
         "reads": combined_reads,
@@ -252,15 +337,30 @@ def analyze(payload: AnalyzeRequest):
 
     pipe = build_dag(assay)
     report = pipe.run(sample)
+    report["validation"]["input_sampling"] = {
+        "mode": "SAMPLED_PREVIEW" if truncated_inputs else "COMPLETE_FOR_SUPPLIED_FILES",
+        "record_cap_per_file": FASTQ_RECORD_CAP_PER_FILE,
+        "truncated_files": truncated_inputs,
+        "all_records_processed": not truncated_inputs,
+    }
+    if truncated_inputs:
+        report["warnings"].append(
+            f"Only the first {FASTQ_RECORD_CAP_PER_FILE} records per FASTQ were analyzed; "
+            "this result is a sampled preview and cannot support whole-run QC or variant conclusions."
+        )
     return {
         "detection": detection,
         "requested": {
             "assay": assay,
-            "reference": sample["reference"],
+            "reference": "synthetic-positive-control" if use_synthetic_reference else sample["reference"],
+            "reference_template_requested": sample["reference"] if use_synthetic_reference else None,
             "synthetic_reference": use_synthetic_reference,
             "demo_profile": payload.demo_profile,
             "reads_loaded": {os.path.basename(f): len(reads_all[f]) for f in files},
             "reads_analyzed": len(combined_reads),
+            "record_cap_per_file": FASTQ_RECORD_CAP_PER_FILE,
+            "truncated_files": truncated_inputs,
+            "all_records_processed": not truncated_inputs,
         },
         "demo": demo,
         "pipeline": report,

app/routers/pipeline_v2.py

@@ -1,1108 +1,1108 @@
-"""
-In-memory pipeline v2 — runs BLAST → UniProt → MSA → Phylo → Domains → Interpretation
-in a background thread. Uses a thread-safe dict for job storage.
-"""
-
-import asyncio
-import logging
-import threading
-import uuid
-from datetime import datetime, timezone
-
-from fastapi import APIRouter, HTTPException, Depends, Request
-from pydantic import BaseModel, Field
-
-from app.config import settings
-from app.deps import limiter
-from app.services.rate_limit import check_daily_limit_pipelines
-from app.services.auth import get_user_id
-from app.services.supabase import get_supabase
-from app.integrations.ncbi import blast as ncbi_blast
-from app.integrations.ncbi.parser import parse_blast_xml
-from app.services.validators import validate_fasta
-from app.services.sequence_utils import detect_source_from_accession, map_refseq_to_uniprot, detect_sequence_type
-from app.services.blast_config import resolve_blast_params
-from app.services.identifier_resolution import resolve_to_uniprot
-from app.tools.ebi_msa import EBI_TOOLS, run_ebi_msa, run_ebi_msa_best_effort
-from app.tools.blast import BlastTool
-from app.tools.uniprot import UniprotTool
-from app.tools.pairwise_alignment import pairwise_align, VALID_MODES
-
-logger = logging.getLogger(__name__)
-router = APIRouter()
-
-_jobs: dict[str, dict] = {}
-_jobs_lock = threading.Lock()
-
-STEP_ORDER = ["blast", "uniprot", "msa", "phylo", "domains", "pathway_enrichment", "alphafold", "interpret"]
-
-
-def _get_job(job_id: str) -> dict | None:
-    with _jobs_lock:
-        return _jobs.get(job_id)
-
-
-def _is_real_uuid(job_id: str) -> bool:
-    try:
-        uuid.UUID(job_id)
-        return True
-    except (ValueError, AttributeError):
-        return False
-
-
-def _persist_v2_final(job_id: str, status: str, context: dict, error: str | None = None):
-    """Update the persisted wizard job row with the final status + full context."""
-    if not _is_real_uuid(job_id):
-        return
-    now = datetime.now(timezone.utc).isoformat()
-    payload = {
-        "status": status,
-        "progress_pct": 100,
-        "completed_at": now,
-        "context_json": context,
-        "error_message": error,
-    }
-    if error:
-        payload["error"] = error
-    try:
-        get_supabase().table("jobs").update(payload).eq("id", job_id).execute()
-    except Exception as e:
-        logger.warning("Could not update v2 job %s to Supabase: %s", job_id, e)
-
-
-def _persist_v2_job(job_id: str, payload: dict):
-    """Persist a wizard v2 job to Supabase (best-effort) so it shows up in
-    the user's job history and can be shared. Uses the service role key."""
-    try:
-        get_supabase().table("jobs").insert(payload).execute()
-    except Exception as e:
-        logger.warning("Could not persist v2 job %s to Supabase: %s", job_id, e)
-
-
-def _set_step_status(job_id: str, step: str, status: str, progress: int = 0, data: dict | None = None, error: str | None = None):
-    with _jobs_lock:
-        if job_id not in _jobs:
-            return
-        _jobs[job_id]["steps"][step] = {"status": status, "progress": progress, "data": data, "error": error}
-        if status == "running":
-            _jobs[job_id]["current_step"] = step
-
-
-def _set_job_failed(job_id: str, message: str):
-    with _jobs_lock:
-        if job_id in _jobs:
-            _jobs[job_id]["status"] = "failed"
-            _jobs[job_id]["error"] = message
-
-
-class PipelineV2RunRequest(BaseModel):
-    sequence: str = Field(..., min_length=6, description="Protein sequence (FASTA or raw)")
-    steps: list[str] = Field(default_factory=lambda: list(STEP_ORDER), description="Steps to run")
-    fast_mode: bool = Field(default=False, description="Use Swiss-Prot instead of nr for faster results")
-    database: str = Field("", description="BLAST database override")
-    program: str = Field("", description="BLAST program override")
-    max_hits: int = Field(100, description="Max BLAST hits to return")
-    query_accession: str = Field("", description="Optional query accession for display")
-    alignment_mode: str = Field("global", description="Alignment mode for the MSA step: 'global' (full-length) or 'local' (Smith-Waterman refinement of query vs top hit)")
-    parent_job_id: str | None = Field(None, description="Parent job ID for DAG branching")
-
-
-@router.post("/run")
-async def run_pipeline_v2(request: Request, req: PipelineV2RunRequest, user_id: str | None = Depends(get_user_id)):
-    validation = validate_fasta(req.sequence, "blast")
-    if not validation.valid:
-        raise HTTPException(status_code=400, detail=validation.error)
-
-    alignment_mode = req.alignment_mode.lower()
-    if alignment_mode not in VALID_MODES:
-        raise HTTPException(status_code=400, detail=f"alignment_mode must be one of {list(VALID_MODES)}, got {alignment_mode!r}")
-
-    seq = str(validation.sequences[0].seq).upper()
-    clean = "".join(c for c in seq if c.isalpha())
-
-    job_id = str(uuid.uuid4())
-    now = datetime.now(timezone.utc).isoformat()
-
-    requested = [s for s in req.steps if s in STEP_ORDER]
-    if not requested:
-        requested = list(STEP_ORDER)
-
-    steps_dict = {s: {"status": "pending", "progress": 0, "data": None, "error": None} for s in STEP_ORDER}
-
-    blast_params = {
-        "database": req.database,
-        "program": req.program,
-        "max_hits": req.max_hits,
-        "query_accession": req.query_accession,
-    }
-
-    with _jobs_lock:
-        _jobs[job_id] = {
-            "job_id": job_id,
-            "status": "running",
-            "current_step": None,
-            "steps": steps_dict,
-            "requested_steps": requested,
-            "sequence": clean,
-            "blast_params": blast_params,
-            "alignment_mode": alignment_mode,
-            "error": None,
-            "created_at": now,
-        }
-
-    # Best-effort persistence so wizard jobs appear in history and can be shared.
-    persist_payload = {
-        "id": job_id,
-        "user_id": user_id,
-        "tool": "wizard_v2",
-        "pipeline_type": "wizard_v2",
-        "query_preview": clean[:60],
-        "status": "running",
-        "progress_pct": 0,
-        "title": "Wizard pipeline",
-        "description": "Pipeline v2 wizard run",
-        "created_at": now,
-    }
-    if req.parent_job_id:
-        persist_payload["parent_job_id"] = req.parent_job_id
-    _persist_v2_job(job_id, persist_payload)
-
-    t = threading.Thread(
-        target=_run_pipeline,
-        args=(job_id, clean, requested),
-        kwargs={"fast_mode": req.fast_mode, "blast_params": blast_params, "alignment_mode": alignment_mode},
-        daemon=True,
-    )
-    t.start()
-
-    return {"job_id": job_id}
-
-
-@router.get("/status/{job_id}")
-async def get_pipeline_v2_status(job_id: str):
-    job = _get_job(job_id)
-    if not job:
-        raise HTTPException(status_code=404, detail="Job not found")
-    return job
-
-
-async def run_pipeline(
-    sequence: str,
-    organism: str = "Homo sapiens",
-    analysis_type: str = "comprehensive",
-    status_callback=None,
-    fast_mode: bool = False,
-    blast_params: dict | None = None,
-) -> dict:
-    """Public async entry point for the pipeline (used by pipeline_worker).
-
-    Creates a temporary in-memory job, runs the configured steps, and
-    returns the context dict with all results.
-    """
-    job_id = f"worker-{uuid.uuid4().hex[:12]}"
-    requested = list(STEP_ORDER)
-    steps_dict = {s: {"status": "pending", "progress": 0, "data": None, "error": None} for s in STEP_ORDER}
-
-    with _jobs_lock:
-        _jobs[job_id] = {
-            "job_id": job_id,
-            "status": "running",
-            "current_step": None,
-            "steps": steps_dict,
-            "requested_steps": requested,
-            "sequence": sequence,
-            "blast_params": blast_params or {},
-            "error": None,
-            "created_at": datetime.now(timezone.utc).isoformat(),
-        }
-
-    try:
-        await _execute(
-            job_id,
-            sequence,
-            requested,
-            status_callback=status_callback,
-            fast_mode=fast_mode,
-            blast_params=blast_params,
-        )
-    finally:
-        job = _get_job(job_id)
-        with _jobs_lock:
-            _jobs.pop(job_id, None)
-
-    if job and job.get("status") == "failed":
-        raise RuntimeError(job.get("error", "Pipeline failed"))
-
-    query_accession = ((blast_params or {}).get("query_accession") or "").strip()
-    context: dict = {
-        "sequence": sequence,
-        "length": len(sequence),
-        "query": {
-            "sequence": sequence,
-            "length": len(sequence),
-            "sequence_type": detect_sequence_type(sequence) or "protein",
-        },
-    }
-    if query_accession:
-        context["query"]["accession"] = query_accession
-    if job:
-        for step_name, step_info in job.get("steps", {}).items():
-            if step_info.get("data"):
-                context[step_name] = step_info["data"]
-    return context
-
-
-# ---------------------------------------------------------------------------
-# Background pipeline
-# ---------------------------------------------------------------------------
-
-def _run_pipeline(job_id: str, sequence: str, steps: list[str], fast_mode: bool = False, blast_params: dict | None = None, alignment_mode: str = "global"):
-    loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(loop)
-    try:
-        loop.run_until_complete(
-            _execute(job_id, sequence, steps, fast_mode=fast_mode, blast_params=blast_params, alignment_mode=alignment_mode)
-        )
-    except Exception as e:
-        logger.exception(f"[{job_id}] Unhandled pipeline error")
-        _set_job_failed(job_id, f"Pipeline error: {e}")
-    finally:
-        loop.close()
-        asyncio.set_event_loop(None)
-
-
-async def _execute(job_id: str, sequence: str, steps: list[str], status_callback=None, fast_mode: bool = False, blast_params: dict | None = None, alignment_mode: str = "global"):
-    context: dict = {
-        "sequence": sequence,
-        "length": len(sequence),
-        "query": {
-            "sequence": sequence,
-            "length": len(sequence),
-            "sequence_type": detect_sequence_type(sequence) or "protein",
-        },
-    }
-
-    _STEP_FRONTEND = {
-        "blast": "running",
-        "uniprot": "fetching_uniprot",
-        "msa": "running_msa",
-        "phylo": "running_msa",
-        "domains": "fetching_uniprot",
-        "pathway_enrichment": "pathway_enrichment",
-        "alphafold": "fetching_alphafold",
-        "interpret": "interpreting",
-    }
-
-    _failed_step = None
-    _failed_error = None
-
-    async def _notify(step_key: str):
-        if status_callback:
-            try:
-                await status_callback(_STEP_FRONTEND.get(step_key, "running"))
-            except Exception:
-                pass
-
-    def _mark(step_key: str, status: str, **kw):
-        _set_step_status(job_id, step_key, status, **kw)
-
-    def _fail(step_key: str, msg: str):
-        nonlocal _failed_step, _failed_error
-        _mark(step_key, "failed", error=msg)
-        _failed_step = step_key
-        _failed_error = msg
-
-    # ---- Step 1: BLAST (must run first) ----
-    denovo_mode = False
-    if "blast" in steps:
-        await _notify("blast")
-        _mark("blast", "running", progress=10)
-        result = await _run_blast(
-            sequence,
-            status_callback=status_callback,
-            fast_mode=fast_mode,
-            blast_params=blast_params,
-        )
-        zero_hits = result.get("count", 0) == 0
-        if zero_hits and (detect_sequence_type(sequence) or "protein") == "protein":
-            # Tier 6: no database match at all — characterize from sequence
-            # alone instead of failing the run (techspec.md §1).
-            denovo_mode = True
-            result["_note"] = "No BLAST hits found — switching to de novo characterization"
-            _mark("blast", "complete", progress=100, data=result)
-        else:
-            _mark("blast", "failed" if zero_hits else "complete", progress=100, data=result)
-            if zero_hits:
-                _failed_step = "blast"
-                _failed_error = result.get("error", "No BLAST hits found")
-        context["blast"] = result
-
-    if denovo_mode:
-        context["query"]["confidence"] = "de_novo"
-        await _run_denovo_steps(job_id, sequence, steps, _mark, context)
-        await _finalize_context(job_id, context)
-        with _jobs_lock:
-            if job_id in _jobs:
-                _jobs[job_id]["status"] = "complete"
-                _jobs[job_id]["context"] = context
-        _persist_v2_final(job_id, "complete", context)
-        return
-
-    # ---- Step 2: Fan-out — UniProt, MSA, Pathway run in parallel ----
-    #    They all only depend on BLAST results, not on each other.
-    blast_data = context.get("blast", {})
-    hits = (blast_data.get("hits") if isinstance(blast_data, dict) else []) or []
-    top_hit = blast_data.get("top_hit") if isinstance(blast_data, dict) else None
-
-    async def _do_uniprot():
-        candidates = ([top_hit] + hits[:5]) if top_hit else hits[:5]
-        last_result: dict | None = None
-        for idx, candidate in enumerate(candidates):
-            # Only the top candidate may trigger the expensive EBI sequence
-            # BLAST fallback — otherwise a pathological query could run it up
-            # to 6 times (up to ~3 min each).
-            last_result = await _run_uniprot(
-                candidate,
-                query_sequence=sequence,
-                try_sequence=idx == 0,
-            )
-            if "error" not in last_result:
-                return last_result
-        return last_result if last_result else {"error": "No BLAST hits for UniProt lookup"}
-
-    async def _do_msa():
-        if not hits:
-            return {"error": "No BLAST hits for MSA"}
-        return await _run_msa(sequence, hits, alignment_mode)
-
-    async def _do_pathway():
-        return await _run_pathway_enrichment(context)
-
-    fan_out = []
-    fan_names = []
-    if "uniprot" in steps and not _failed_step:
-        fan_out.append(_do_uniprot())
-        fan_names.append("uniprot")
-    if "msa" in steps and not _failed_step:
-        fan_out.append(_do_msa())
-        fan_names.append("msa")
-    if "pathway_enrichment" in steps and not _failed_step:
-        fan_out.append(_do_pathway())
-        fan_names.append("pathway_enrichment")
-
-    if fan_out:
-        # Notify for the first active step in the fan-out
-        await _notify(fan_names[0])
-        for name in fan_names:
-            _mark(name, "running", progress=10)
-
-        results = await asyncio.gather(*fan_out, return_exceptions=True)
-
-        for name, res in zip(fan_names, results):
-            if isinstance(res, Exception):
-                _fail(name, str(res)[:500])
-                continue
-
-            if name == "uniprot":
-                s = "complete" if "error" not in res else "failed"
-                _mark("uniprot", s, progress=100, data=res)
-                context["uniprot"] = res
-                if res.get("confidence"):
-                    context["query"]["confidence"] = res["confidence"]
-                if "error" in res:
-                    _failed_step = "uniprot"
-                    _failed_error = res["error"]
-
-            elif name == "msa":
-                s = "complete" if res.get("aln_fasta") else "failed"
-                _mark("msa", s, progress=100, data=res)
-                context["msa"] = res
-                if res.get("phylotree"):
-                    context.setdefault("phylo_data", {})["phylotree_newick"] = res["phylotree"]
-
-            elif name == "pathway_enrichment":
-                s = "complete" if res and res.get("pathways") else "failed"
-                _mark("pathway_enrichment", s, progress=100, data=res or {})
-                context["pathway_enrichment"] = res
-
-    # ---- Step 3: Phylo (instant — copies from MSA) ----
-    if "phylo" in steps and not _failed_step:
-        _mark("phylo", "running", progress=10)
-        newick = None
-        msa_data = context.get("msa", {})
-        if isinstance(msa_data, dict):
-            newick = msa_data.get("phylotree")
-        if not newick:
-            newick = context.get("phylo_data", {}).get("phylotree_newick")
-        if newick:
-            _mark("phylo", "complete", progress=100, data={"phylotree_newick": newick})
-            context["phylo"] = {"phylotree_newick": newick}
-        else:
-            _mark("phylo", "failed", error="No phylotree available from MSA")
-
-    # ---- Step 4: Domains + AlphaFold in parallel ----
-    # When UniProt resolution exhausted all tiers, these fall back to their
-    # sequence-only equivalents instead of being silently skipped (§1.2).
-    uniprot_data = context.get("uniprot", {})
-    accession = uniprot_data.get("accession") if isinstance(uniprot_data, dict) else None
-    resolved_uniprot = bool(uniprot_data.get("resolved_uniprot")) if isinstance(uniprot_data, dict) else False
-
-    post_uniprot = []
-    post_uniprot_names = []
-    if "domains" in steps and not _failed_step:
-        post_uniprot.append(
-            _run_domains_or_denovo(sequence, accession, resolved_uniprot)
-        )
-        post_uniprot_names.append("domains")
-    if "alphafold" in steps and not _failed_step:
-        post_uniprot.append(
-            _run_alphafold_or_esmfold(context, sequence, accession, resolved_uniprot)
-        )
-        post_uniprot_names.append("alphafold")
-
-    if post_uniprot:
-        await _notify(post_uniprot_names[0])
-        for name in post_uniprot_names:
-            _mark(name, "running", progress=10)
-
-        results2 = await asyncio.gather(*post_uniprot, return_exceptions=True)
-
-        for name, res in zip(post_uniprot_names, results2):
-            if isinstance(res, Exception):
-                _fail(name, str(res)[:500])
-                continue
-
-            if name == "domains":
-                s = "complete" if res.get("domains") is not None else "failed"
-                _mark("domains", s, progress=100, data=res)
-                context["domains"] = res
-            elif name == "alphafold":
-                s = "complete" if res else "failed"
-                _mark("alphafold", s, progress=100, data=res or {})
-                context["alphafold"] = res
-
-    # ---- Step 5: Interpret (needs all context) ----
-    if "interpret" in steps and not _failed_step:
-        await _notify("interpret")
-        _mark("interpret", "running", progress=10)
-        result = await _run_interpret(context)
-        s = "complete" if result.get("interpretation") else "failed"
-        _mark("interpret", s, progress=100, data=result)
-        context["interpret"] = result
-
-    # ---- Final status ----
-    if _failed_step and _failed_step in ("blast", "uniprot"):
-        with _jobs_lock:
-            if job_id in _jobs:
-                _jobs[job_id]["status"] = "failed"
-                _jobs[job_id]["error"] = f"Pipeline failed at {_failed_step}: {_failed_error}"
-        _persist_v2_final(job_id, "failed", context, error=f"Pipeline failed at {_failed_step}: {_failed_error}")
-    else:
-        await _finalize_context(job_id, context)
-        with _jobs_lock:
-            if job_id in _jobs:
-                _jobs[job_id]["status"] = "complete"
-                _jobs[job_id]["context"] = context
-        _persist_v2_final(job_id, "complete", context)
-
-
-async def _finalize_context(job_id: str, context: dict):
-    """Pre-persist hook: capture source pages (§3) + build the final report."""
-    user_id = None
-    with _jobs_lock:
-        entry = _jobs.get(job_id)
-        if entry:
-            user_id = entry.get("user_id")
-    try:
-        _capture_run_sources(job_id, context, user_id)
-    except Exception as e:  # captures must never break a run
-        logger.warning("[%s] page capture wiring failed: %s", job_id, e)
-    try:
-        from app.services.final_synthesis import synthesize
-
-        context["final_report"] = await synthesize(context)
-    except Exception as e:
-        logger.warning("[%s] final synthesis failed: %s", job_id, e)
-
-
-def _capture_run_sources(job_id: str, context: dict, user_id: str | None):
-    """Queue one page_captures row per external source this run queried."""
-    from app.services.page_capture import capture_bg
-
-    blast = context.get("blast") or {}
-    top_hit = blast.get("top_hit")
-    if top_hit and top_hit.get("accession"):
-        capture_bg(job_id, "ncbi", f"https://www.ncbi.nlm.nih.gov/protein/{top_hit['accession']}", user_id)
-
-    uniprot = context.get("uniprot") or {}
-    if uniprot.get("_de_novo"):
-        pass  # no external annotation source was queried in de novo mode
-    elif uniprot.get("accession"):
-        capture_bg(job_id, "uniprot", f"https://www.uniprot.org/uniprotkb/{uniprot['accession']}", user_id)
-        pdb_ids = uniprot.get("pdb_ids") or []
-        if pdb_ids:
-            capture_bg(job_id, "rcsb", f"https://www.rcsb.org/structure/{pdb_ids[0]}", user_id)
-
-    domains = context.get("domains") or {}
-    dom_list = domains.get("domains") or []
-    if dom_list and dom_list[0].get("accession"):
-        acc = dom_list[0]["accession"]
-        if str(acc).startswith("IPR"):
-            capture_bg(job_id, "interpro", f"https://www.ebi.ac.uk/interpro/entry/InterPro/{acc}", user_id)
-
-    af = context.get("alphafold") or {}
-    if af.get("structure_available") and af.get("source") != "esmfold" and uniprot.get("accession"):
-        capture_bg(job_id, "alphafold", f"https://alphafold.ebi.ac.uk/uniprot/{uniprot['accession']}", user_id)
-
-    pathway = context.get("pathway_enrichment") or {}
-    pw_list = (pathway.get("pathways") if isinstance(pathway, dict) else None) or []
-    if pw_list and pw_list[0].get("stId"):
-        # run_enrichment queries the Reactome projection API exclusively
-        capture_bg(
-            job_id, "reactome",
-            f"https://reactome.org/PathwayBrowser/#{pw_list[0]['stId']}",
-            user_id,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Step implementations
-# ---------------------------------------------------------------------------
-
-# NCBI database name → EBI ncbiblast database name. EBI has no direct "nr"
-# equivalent; uniprotkb is its closest comprehensive protein database.
-EBI_BLAST_DATABASE_MAP = {
-    "nr": "uniprotkb",
-    "swissprot": "uniprotkb_swissprot",
-    "pdb": "pdb",
-    "pdbaa": "pdb_nr",
-    "refseq_protein": "refseq_protein",
-    "env_nr": "env_nr",
-    "nt": "nt",
-    "refseq_rna": "refseq_rna",
-    "refseq_genomic": "refseq_genomic",
-    "est": "est",
-    "gss": "gss",
-}
-
-
-def _build_blast_result(
-    hits: list[dict],
-    *,
-    source: str,
-    database: str,
-    program: str,
-    seq_type: str,
-    query_accession: str,
-    query_length: int,
-    display_limit: int = 20,
-) -> dict:
-    """Normalize parsed hits (NCBI XML parser or EBI tool) into the pipeline's
-    canonical BLAST result shape consumed by the frontend."""
-    top_hit = hits[0] if hits else None
-    return {
-        "count": len(hits),
-        "source": source,
-        "database": database,
-        "program": program,
-        "query_sequence_type": seq_type,
-        "query_accession": query_accession,
-        "query_length": query_length,
-        "top_hit": {
-            "accession": top_hit["accession"],
-            "description": top_hit["description"],
-            "evalue": top_hit["evalue"],
-            "evalue_raw": str(top_hit["evalue"]),
-            "identity_pct": top_hit["identity_pct"],
-            "bit_score": top_hit["bit_score"],
-            "alignment_length": top_hit.get("alignment_length", 0),
-        } if top_hit else None,
-        "hits": [
-            {
-                "accession": h["accession"],
-                "description": h["description"],
-                "organism": h.get("organism", ""),
-                "evalue": h["evalue"],
-                "evalue_raw": str(h["evalue"]),
-                "identity_pct": h["identity_pct"],
-                "bit_score": h["bit_score"],
-                "alignment_length": h.get("alignment_length", 0),
-                "query_coverage_pct": round(h.get("alignment_length", 0) / query_length * 100, 1) if query_length > 0 else 0,
-                "hit_alignment": h.get("hit_alignment", ""),
-                "query_alignment": h.get("query_alignment", ""),
-                "midline": h.get("midline", ""),
-                "score": h.get("score", 0),
-                "positive": h.get("positive", 0),
-                "gaps": h.get("gaps", 0),
-                "query_from": h.get("query_from", 0),
-                "query_to": h.get("query_to", 0),
-                "hit_from": h.get("hit_from", 0),
-                "hit_to": h.get("hit_to", 0),
-            }
-            for h in hits[:display_limit]
-        ],
-    }
-
-
-async def _run_ebi_blast_fallback(
-    sequence: str,
-    program: str,
-    database: str,
-    seq_type: str,
-    max_hits: int,
-) -> dict | None:
-    """Run BLAST against EBI (uncached) and return a canonical result, or None
-    if the database has no EBI equivalent or EBI itself fails."""
-    ebi_database = EBI_BLAST_DATABASE_MAP.get(database)
-    if not ebi_database:
-        logger.warning("No EBI database equivalent for '%s' — skipping fallback", database)
-        return None
-    try:
-        result = await BlastTool().run_uncached({
-            "sequence": sequence,
-            "program": program,
-            "database": ebi_database,
-            "max_hits": max_hits,
-        })
-    except Exception as e:
-        logger.warning("EBI BLAST fallback failed: %s", e)
-        return None
-    if result.get("error") or not result.get("hits"):
-        logger.warning("EBI BLAST fallback returned no hits: %s", result.get("error", "empty"))
-        return None
-    query_length = len("".join(sequence.replace("\n", "").replace(" ", "").split("-")))
-    return _build_blast_result(
-        result["hits"],
-        source="ebi",
-        database=database,
-        program=program,
-        seq_type=seq_type,
-        query_accession="",
-        query_length=query_length,
-    )
-
-
-async def _run_blast(
-    sequence: str,
-    status_callback=None,
-    fast_mode: bool = False,
-    blast_params: dict | None = None,
-) -> dict:
-    blast_params = blast_params or {}
-    try:
-        program, database, seq_type = resolve_blast_params(
-            sequence,
-            program=blast_params.get("program"),
-            database=blast_params.get("database"),
-            fast_mode=fast_mode,
-        )
-    except ValueError as e:
-        logger.warning("BLAST param resolution failed: %s", e)
-        return {"error": str(e), "count": 0, "hits": []}
-
-    try:
-        max_hits = int(blast_params.get("max_hits") or 100)
-    except (TypeError, ValueError):
-        max_hits = 100
-    max_hits = max(5, min(max_hits, 100))
-    query_accession = (blast_params.get("query_accession") or "").strip()
-
-    if status_callback:
-        try:
-            await status_callback("submitted_to_ncbi")
-        except Exception:
-            pass
-
-    # EBI is fast & reliable (~30s) and returns UniProt accessions the rest of
-    # the pipeline consumes directly. NCBI chronically stalls (long WAITING
-    # even with an API key), so run EBI FIRST and fall back to NCBI.
-    ebi_result = await _run_ebi_blast_fallback(sequence, program, database, seq_type, max_hits)
-    if ebi_result is not None:
-        if status_callback:
-            try:
-                await status_callback("parsing")
-            except Exception:
-                pass
-        return ebi_result
-
-    # EBI unavailable for this database or failed — try NCBI before failing.
-    ncbi_error: str | None = None
-    results = await ncbi_blast.run_blast_with_retry(
-        sequence,
-        retries=2,
-        max_wait_seconds=600 if fast_mode else 900,
-        database=database,
-        program=program,
-        hitlist_size=max_hits,
-    )
-
-    if "error" not in results:
-        parsed = parse_blast_xml(results["raw"])
-        if "error" not in parsed:
-            if status_callback:
-                try:
-                    await status_callback("parsing")
-                except Exception:
-                    pass
-            hits = parsed.get("hits", [])[:max_hits]
-            return _build_blast_result(
-                hits,
-                source="ncbi",
-                database=database,
-                program=program,
-                seq_type=seq_type,
-                query_accession=query_accession,
-                query_length=parsed.get("query_length", 0),
-            )
-        ncbi_error = parsed["error"]
-    else:
-        ncbi_error = results["error"]
-
-    logger.warning("EBI BLAST unavailable and NCBI failed (%s)", ncbi_error)
-    return {"error": ncbi_error or "BLAST failed via EBI and NCBI", "count": 0, "hits": []}
-
-
-async def _run_uniprot(top_hit: dict, query_sequence: str | None = None, try_sequence: bool = True) -> dict:
-    accession = (top_hit.get("accession") or "").strip()
-    if not accession:
-        return {"error": "No accession"}
-    desc = (top_hit.get("description") or "").strip()
-    organism = (top_hit.get("organism") or "").strip()
-
-    # Resolve ANY BLAST-hit accession (RefSeq, GenBank, PDB, Ensembl, ...) to a
-    # UniProt accession via the strategy ladder in identifier_resolution:
-    #   direct -> xref search (fast) -> name search -> EBI sequence BLAST -> idmapping
-    # Exhausting all tiers returns an explicit unresolved/de_novo result (§1).
-    try:
-        resolved = await resolve_to_uniprot(
-            accession=accession,
-            sequence=query_sequence,
-            description=desc,
-            organism=organism or None,
-            try_sequence=try_sequence,
-        )
-    except Exception as e:
-        logger.warning("Identifier resolution failed for %s: %s", accession, e)
-        resolved = None
-
-    if not resolved or resolved.get("status") != "resolved":
-        logger.info("No UniProt mapping for %s, using BLAST data only", accession)
-        return {
-            "accession": accession,
-            "full_name": top_hit.get("description", ""),
-            "organism": top_hit.get("organism", ""),
-            "gene_names": [],
-            "functions": [],
-            "keywords": [],
-            "subcellular_locations": [],
-            "pdb_ids": [],
-            "go_terms": [],
-            "sequence": "",
-            "sequence_length": 0,
-            "features": [],
-            "resolution": {
-                "uniprot_accession": None,
-                "method": "de_novo",
-                "original_accession": accession,
-            },
-            "resolved_uniprot": False,
-            # BLAST-derived similarity is homolog-grade certainty at best (§1.1)
-            "confidence": "homolog",
-            "_note": f"No UniProt mapping found for {accession} — showing BLAST-derived data only",
-        }
-
-    uniprot_acc = resolved["accession"]
-    method = resolved["method"]
-
-    tool = UniprotTool()
-    result = await tool.run({"accession": uniprot_acc})
-    if "error" in result:
-        return {"error": result["error"]}
-
-    return {
-        "accession": result.get("accession", uniprot_acc),
-        "full_name": result.get("full_name", ""),
-        "organism": result.get("organism", ""),
-        "gene_names": result.get("gene_names", []),
-        "functions": result.get("functions", []),
-        "keywords": result.get("keywords", []),
-        "subcellular_locations": result.get("subcellular_locations", []),
-        "pdb_ids": result.get("pdb_ids", []),
-        "go_terms": result.get("go_terms", []),
-        "sequence": result.get("sequence", ""),
-        "sequence_length": result.get("sequence_length", 0),
-        "features": [
-            f for f in (result.get("features", []) or [])
-            if f.get("type") in ("ACTIVE_SITE", "BINDING", "MUTAGENESIS", "SITE", "MOD_RES")
-        ],
-        "resolution": {
-            "uniprot_accession": uniprot_acc,
-            "method": method,
-            "original_accession": accession,
-        },
-        "resolved_uniprot": True,
-        "confidence": resolved.get("confidence", "identified"),
-    }
-
-
-async def _run_msa(query_sequence: str, blast_hits: list, alignment_mode: str = "global") -> dict:
-    sequences = [("query", query_sequence)]
-
-    for hit in blast_hits[:5]:
-        acc = hit.get("accession", "")
-        hit_seq = hit.get("hit_alignment", "")
-
-        if acc:
-            source = detect_source_from_accession(acc)
-            mapped_acc = acc
-            if source == "ncbi":
-                mapped = await map_refseq_to_uniprot(acc)
-                if mapped:
-                    mapped_acc = mapped
-            try:
-                tool = UniprotTool()
-                ud = await tool.run({"accession": mapped_acc})
-                if "error" not in ud and ud.get("sequence"):
-                    clean_seq = "".join(c for c in ud["sequence"] if c.isalpha()).upper()
-                    if len(clean_seq) > 10:
-                        sequences.append((acc, clean_seq))
-                        continue
-            except Exception:
-                pass
-
-        if hit_seq:
-            clean = "".join(c for c in hit_seq if c.isalpha()).upper()
-            if len(clean) > 10:
-                sequences.append((f"{acc}_aln", clean))
-
-    if len(sequences) < 2:
-        return {"error": "Not enough sequences for MSA", "aln_fasta": None, "phylotree": None}
-
-    fasta_lines = []
-    for sid, sseq in sequences:
-        fasta_lines.append(f">{sid}")
-        for i in range(0, len(sseq), 80):
-            fasta_lines.append(sseq[i:i + 80])
-    fasta_str = "\n".join(fasta_lines)
-
-    try:
-        email = settings.NCBI_EMAIL or "bioflow@example.com"
-        seq_type = detect_sequence_type(query_sequence) or "protein"
-        stype = "protein" if seq_type == "protein" else "dna"
-        try:
-            # Try local MAFFT first (fast, no network dependency)
-            from app.tools.mafft_local import run_local_mafft
-            local_result = await asyncio.get_running_loop().run_in_executor(
-                None, run_local_mafft, fasta_str, "auto", 1, 300,
-            )
-            if local_result and local_result.get("aln_fasta"):
-                method = "mafft-local"
-                aln_fasta = local_result["aln_fasta"]
-                phylotree = ""
-            else:
-                raise ValueError("local MAFFT unavailable or returned empty")
-        except Exception:
-            try:
-                result = await run_ebi_msa_best_effort(
-                    sequence=fasta_str,
-                    stype=stype,
-                    email=email,
-                )
-                method = result["method"]
-                aln_fasta = result["aln_fasta"]
-                phylotree = result["phylotree"]
-            except Exception as e:
-                logger.warning("EBI MSA unavailable (%s) — using in-process fallback", e)
-                from app.tools.msa_fallback import progressive_msa
-                fallback = await asyncio.get_running_loop().run_in_executor(
-                    None, progressive_msa, sequences, stype
-                )
-                aln_fasta, phylotree = fallback
-                method = "in-process fallback"
-
-        payload = {
-            "aln_fasta": aln_fasta,
-            "phylotree": phylotree,
-            "sequence_count": len(sequences),
-            "alignment_mode": alignment_mode,
-            "method": method,
-            "_fallback": method != "clustalo",
-        }
-
-        # Local mode: refine query vs the best non-query sequence with an
-        # in-process Smith-Waterman alignment so the wizard can show which
-        # region actually matches (EBI MSA itself is always global).
-        if alignment_mode == "local" and len(sequences) > 1:
-            subject_id, subject_seq = sequences[1]
-            try:
-                payload["pairwise"] = pairwise_align(query_sequence, subject_seq, mode="local")
-                payload["pairwise_subject"] = subject_id
-            except Exception as e:
-                logger.warning("Local pairwise refinement failed: %s", e)
-
-        return payload
-
-    except Exception as e:
-        return {"error": str(e), "aln_fasta": None, "phylotree": None}
-
-
-async def _run_domains(accession: str) -> dict:
-    """Run domain analysis using the shared tool module (eliminates code duplication)."""
-    try:
-        from app.tools.domain_analysis import fetch_interpro_domains
-        return await fetch_interpro_domains(accession)
-    except Exception as e:
-        return {"error": str(e), "uniprot_accession": accession, "sequence_length": 0, "domains": []}
-
-
-async def _run_denovo_steps(job_id: str, sequence: str, steps: list[str], _mark, context: dict) -> None:
-    """Tier-6 branch (techspec.md §1): characterize from sequence alone.
-
-    Runs when BLAST finds no homolog at all. Composition/function hints land
-    in the uniprot slot (the annotation slot); MSA/phylo/pathways are marked
-    explicitly unavailable rather than left empty.
-    """
-    import asyncio as _asyncio
-    from app.services.de_novo import (
-        composition_stats, esmfold_structure, function_hints, interpro_sequence_search,
-    )
-
-    unavailable = "Unavailable for de novo sequences — no identified homolog"
-
-    async def _do_annotation():
-        bundle = {"_de_novo": True}
-        try:
-            bundle["composition"] = composition_stats(sequence)
-        except Exception as e:
-            bundle["composition"] = {"error": str(e)}
-        try:
-            bundle["function_hints"] = function_hints(sequence)
-        except Exception as e:
-            bundle["function_hints"] = {"error": str(e)}
-        return bundle
-
-    async def _do_domains():
-        try:
-            return await interpro_sequence_search(sequence)
-        except Exception as e:
-            logger.warning("De novo InterProScan failed: %s", e)
-            return {"error": str(e), "domains": [], "sequence_length": 0}
-
-    async def _do_structure():
-        try:
-            return await esmfold_structure(sequence)
-        except Exception as e:
-            logger.warning("De novo ESMFold failed: %s", e)
-            return {"structure_available": False, "source": "esmfold", "message": str(e)}
-
-    fan = []
-    names = []
-    if "uniprot" in steps:
-        fan.append(_do_annotation())
-        names.append("uniprot")
-    if "domains" in steps:
-        fan.append(_do_domains())
-        names.append("domains")
-    if "alphafold" in steps:
-        fan.append(_do_structure())
-        names.append("alphafold")
-
-    for name in names:
-        _mark(name, "running", progress=10)
-    results = await _asyncio.gather(*fan, return_exceptions=True)
-
-    for name, res in zip(names, results):
-        if isinstance(res, Exception):
-            _mark(name, "failed", error=str(res)[:500])
-            continue
-        ok = (
-            res.get("domains") is not None if name == "domains"
-            else res.get("structure_available") is True if name == "alphafold"
-            else True
-        )
-        _mark(name, "complete" if ok else "failed", progress=100,
-              data=res, error=None if ok else "Prediction returned nothing usable")
-        context[name] = res
-
-    # Annotation-database features have no de novo substitute — say so.
-    for name in ("msa", "phylo", "pathway_enrichment"):
-        if name in steps:
-            _mark(name, "failed", error=unavailable)
-
-
-async def _run_domains_or_denovo(sequence: str, accession: str | None, resolved_uniprot: bool) -> dict:
-    """Accession lookup when resolved; InterProScan sequence-search otherwise."""
-    if accession and resolved_uniprot:
-        return await _run_domains(accession)
-    from app.services.de_novo import interpro_sequence_search
-    try:
-        result = await interpro_sequence_search(sequence)
-        result["confidence"] = "de_novo"
-        return result
-    except Exception as e:
-        return {"error": str(e), "domains": [], "sequence_length": 0}
-
-
-async def _run_alphafold_or_esmfold(
-    context: dict, sequence: str, accession: str | None, resolved_uniprot: bool,
-) -> dict:
-    """AlphaFold DB lookup when resolved; ESMFold ab initio otherwise."""
-    if accession and resolved_uniprot:
-        result = await _run_alphafold(context)
-        return result or {}
-    from app.services.de_novo import esmfold_structure
-    try:
-        return await esmfold_structure(sequence)
-    except Exception as e:
-        return {"structure_available": False, "source": "esmfold", "message": str(e)}
-
-
-async def _run_pathway_enrichment(context: dict) -> dict | None:
-    gene_names = []
-    uniprot = context.get("uniprot", {})
-    if isinstance(uniprot, dict):
-        gene_names = uniprot.get("gene_names", [])[:20] if isinstance(uniprot.get("gene_names"), list) else []
-    if not gene_names:
-        blast_data = context.get("blast", {})
-        if isinstance(blast_data, dict):
-            for hit in (blast_data.get("hits") or [])[:10]:
-                words = (hit.get("description", "") or "").replace("(", " ").replace(")", " ").split()
-                for w in words:
-                    if w.isupper() and len(w) >= 2 and not w.startswith("OS="):
-                        gene_names.append(w)
-                        break
-    if not gene_names:
-        return None
-    try:
-        from app.services.pathway_enrichment import run_enrichment
-        result = await run_enrichment(gene_names)
-        return result
-    except Exception as e:
-        logger.warning(f"Pathway enrichment failed: {e}")
-        return None
-
-
-async def _run_alphafold(context: dict) -> dict | None:
-    uniprot_data = context.get("uniprot", {})
-    accession = uniprot_data.get("accession") if isinstance(uniprot_data, dict) else None
-    if not accession:
-        return None
-    try:
-        from app.tools.alphafold import AlphaFoldTool
-        result = await AlphaFoldTool().run({"uniprot_accession": accession})
-        return result
-    except Exception as e:
-        logger.warning(f"AlphaFold fetch failed for {accession}: {e}")
-        return {"structure_available": False, "message": str(e)}
-
-
-async def _run_interpret(context: dict) -> dict:
-    from app.ai.interpreter import interpret_text
-    prompt_context = {
-        "blast": context.get("blast", {}),
-        "uniprot": context.get("uniprot", {}),
-        "alphafold": context.get("alphafold", {}),
-        "pathway_enrichment": context.get("pathway_enrichment", {}),
-        "query_confidence": context.get("query", {}).get("confidence", "identified"),
-    }
-    return await interpret_text("protein_analysis", prompt_context)
+"""
+In-memory pipeline v2 — runs BLAST → UniProt → MSA → Phylo → Domains → Interpretation
+in a background thread. Uses a thread-safe dict for job storage.
+"""
+
+import asyncio
+import logging
+import threading
+import uuid
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, HTTPException, Depends, Request
+from pydantic import BaseModel, Field
+
+from app.config import settings
+from app.deps import limiter
+from app.services.rate_limit import check_daily_limit_pipelines
+from app.services.auth import get_user_id
+from app.services.supabase import get_supabase
+from app.integrations.ncbi import blast as ncbi_blast
+from app.integrations.ncbi.parser import parse_blast_xml
+from app.services.validators import validate_fasta
+from app.services.sequence_utils import detect_source_from_accession, map_refseq_to_uniprot, detect_sequence_type
+from app.services.blast_config import resolve_blast_params
+from app.services.identifier_resolution import resolve_to_uniprot
+from app.tools.ebi_msa import EBI_TOOLS, run_ebi_msa, run_ebi_msa_best_effort
+from app.tools.blast import BlastTool
+from app.tools.uniprot import UniprotTool
+from app.tools.pairwise_alignment import pairwise_align, VALID_MODES
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+_jobs: dict[str, dict] = {}
+_jobs_lock = threading.Lock()
+
+STEP_ORDER = ["blast", "uniprot", "msa", "phylo", "domains", "pathway_enrichment", "alphafold", "interpret"]
+
+
+def _get_job(job_id: str) -> dict | None:
+    with _jobs_lock:
+        return _jobs.get(job_id)
+
+
+def _is_real_uuid(job_id: str) -> bool:
+    try:
+        uuid.UUID(job_id)
+        return True
+    except (ValueError, AttributeError):
+        return False
+
+
+def _persist_v2_final(job_id: str, status: str, context: dict, error: str | None = None):
+    """Update the persisted wizard job row with the final status + full context."""
+    if not _is_real_uuid(job_id):
+        return
+    now = datetime.now(timezone.utc).isoformat()
+    payload = {
+        "status": status,
+        "progress_pct": 100,
+        "completed_at": now,
+        "context_json": context,
+        "error_message": error,
+    }
+    if error:
+        payload["error"] = error
+    try:
+        get_supabase().table("jobs").update(payload).eq("id", job_id).execute()
+    except Exception as e:
+        logger.warning("Could not update v2 job %s to Supabase: %s", job_id, e)
+
+
+def _persist_v2_job(job_id: str, payload: dict):
+    """Persist a wizard v2 job to Supabase (best-effort) so it shows up in
+    the user's job history and can be shared. Uses the service role key."""
+    try:
+        get_supabase().table("jobs").insert(payload).execute()
+    except Exception as e:
+        logger.warning("Could not persist v2 job %s to Supabase: %s", job_id, e)
+
+
+def _set_step_status(job_id: str, step: str, status: str, progress: int = 0, data: dict | None = None, error: str | None = None):
+    with _jobs_lock:
+        if job_id not in _jobs:
+            return
+        _jobs[job_id]["steps"][step] = {"status": status, "progress": progress, "data": data, "error": error}
+        if status == "running":
+            _jobs[job_id]["current_step"] = step
+
+
+def _set_job_failed(job_id: str, message: str):
+    with _jobs_lock:
+        if job_id in _jobs:
+            _jobs[job_id]["status"] = "failed"
+            _jobs[job_id]["error"] = message
+
+
+class PipelineV2RunRequest(BaseModel):
+    sequence: str = Field(..., min_length=6, description="Protein sequence (FASTA or raw)")
+    steps: list[str] = Field(default_factory=lambda: list(STEP_ORDER), description="Steps to run")
+    fast_mode: bool = Field(default=False, description="Use Swiss-Prot instead of nr for faster results")
+    database: str = Field("", description="BLAST database override")
+    program: str = Field("", description="BLAST program override")
+    max_hits: int = Field(100, description="Max BLAST hits to return")
+    query_accession: str = Field("", description="Optional query accession for display")
+    alignment_mode: str = Field("global", description="Alignment mode for the MSA step: 'global' (full-length) or 'local' (Smith-Waterman refinement of query vs top hit)")
+    parent_job_id: str | None = Field(None, description="Parent job ID for DAG branching")
+
+
+@router.post("/run")
+async def run_pipeline_v2(request: Request, req: PipelineV2RunRequest, user_id: str | None = Depends(get_user_id)):
+    validation = validate_fasta(req.sequence, "blast")
+    if not validation.valid:
+        raise HTTPException(status_code=400, detail=validation.error)
+
+    alignment_mode = req.alignment_mode.lower()
+    if alignment_mode not in VALID_MODES:
+        raise HTTPException(status_code=400, detail=f"alignment_mode must be one of {list(VALID_MODES)}, got {alignment_mode!r}")
+
+    seq = str(validation.sequences[0].seq).upper()
+    clean = "".join(c for c in seq if c.isalpha())
+
+    job_id = str(uuid.uuid4())
+    now = datetime.now(timezone.utc).isoformat()
+
+    requested = [s for s in req.steps if s in STEP_ORDER]
+    if not requested:
+        requested = list(STEP_ORDER)
+
+    steps_dict = {s: {"status": "pending", "progress": 0, "data": None, "error": None} for s in STEP_ORDER}
+
+    blast_params = {
+        "database": req.database,
+        "program": req.program,
+        "max_hits": req.max_hits,
+        "query_accession": req.query_accession,
+    }
+
+    with _jobs_lock:
+        _jobs[job_id] = {
+            "job_id": job_id,
+            "status": "running",
+            "current_step": None,
+            "steps": steps_dict,
+            "requested_steps": requested,
+            "sequence": clean,
+            "blast_params": blast_params,
+            "alignment_mode": alignment_mode,
+            "error": None,
+            "created_at": now,
+        }
+
+    # Best-effort persistence so wizard jobs appear in history and can be shared.
+    persist_payload = {
+        "id": job_id,
+        "user_id": user_id,
+        "tool": "wizard_v2",
+        "pipeline_type": "wizard_v2",
+        "query_preview": clean[:60],
+        "status": "running",
+        "progress_pct": 0,
+        "title": "Wizard pipeline",
+        "description": "Pipeline v2 wizard run",
+        "created_at": now,
+    }
+    if req.parent_job_id:
+        persist_payload["parent_job_id"] = req.parent_job_id
+    _persist_v2_job(job_id, persist_payload)
+
+    t = threading.Thread(
+        target=_run_pipeline,
+        args=(job_id, clean, requested),
+        kwargs={"fast_mode": req.fast_mode, "blast_params": blast_params, "alignment_mode": alignment_mode},
+        daemon=True,
+    )
+    t.start()
+
+    return {"job_id": job_id}
+
+
+@router.get("/status/{job_id}")
+async def get_pipeline_v2_status(job_id: str):
+    job = _get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return job
+
+
+async def run_pipeline(
+    sequence: str,
+    organism: str = "Homo sapiens",
+    analysis_type: str = "comprehensive",
+    status_callback=None,
+    fast_mode: bool = False,
+    blast_params: dict | None = None,
+) -> dict:
+    """Public async entry point for the pipeline (used by pipeline_worker).
+
+    Creates a temporary in-memory job, runs the configured steps, and
+    returns the context dict with all results.
+    """
+    job_id = f"worker-{uuid.uuid4().hex[:12]}"
+    requested = list(STEP_ORDER)
+    steps_dict = {s: {"status": "pending", "progress": 0, "data": None, "error": None} for s in STEP_ORDER}
+
+    with _jobs_lock:
+        _jobs[job_id] = {
+            "job_id": job_id,
+            "status": "running",
+            "current_step": None,
+            "steps": steps_dict,
+            "requested_steps": requested,
+            "sequence": sequence,
+            "blast_params": blast_params or {},
+            "error": None,
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+    try:
+        await _execute(
+            job_id,
+            sequence,
+            requested,
+            status_callback=status_callback,
+            fast_mode=fast_mode,
+            blast_params=blast_params,
+        )
+    finally:
+        job = _get_job(job_id)
+        with _jobs_lock:
+            _jobs.pop(job_id, None)
+
+    if job and job.get("status") == "failed":
+        raise RuntimeError(job.get("error", "Pipeline failed"))
+
+    query_accession = ((blast_params or {}).get("query_accession") or "").strip()
+    context: dict = {
+        "sequence": sequence,
+        "length": len(sequence),
+        "query": {
+            "sequence": sequence,
+            "length": len(sequence),
+            "sequence_type": detect_sequence_type(sequence) or "protein",
+        },
+    }
+    if query_accession:
+        context["query"]["accession"] = query_accession
+    if job:
+        for step_name, step_info in job.get("steps", {}).items():
+            if step_info.get("data"):
+                context[step_name] = step_info["data"]
+    return context
+
+
+# ---------------------------------------------------------------------------
+# Background pipeline
+# ---------------------------------------------------------------------------
+
+def _run_pipeline(job_id: str, sequence: str, steps: list[str], fast_mode: bool = False, blast_params: dict | None = None, alignment_mode: str = "global"):
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(
+            _execute(job_id, sequence, steps, fast_mode=fast_mode, blast_params=blast_params, alignment_mode=alignment_mode)
+        )
+    except Exception as e:
+        logger.exception(f"[{job_id}] Unhandled pipeline error")
+        _set_job_failed(job_id, f"Pipeline error: {e}")
+    finally:
+        loop.close()
+        asyncio.set_event_loop(None)
+
+
+async def _execute(job_id: str, sequence: str, steps: list[str], status_callback=None, fast_mode: bool = False, blast_params: dict | None = None, alignment_mode: str = "global"):
+    context: dict = {
+        "sequence": sequence,
+        "length": len(sequence),
+        "query": {
+            "sequence": sequence,
+            "length": len(sequence),
+            "sequence_type": detect_sequence_type(sequence) or "protein",
+        },
+    }
+
+    _STEP_FRONTEND = {
+        "blast": "running",
+        "uniprot": "fetching_uniprot",
+        "msa": "running_msa",
+        "phylo": "running_msa",
+        "domains": "fetching_uniprot",
+        "pathway_enrichment": "pathway_enrichment",
+        "alphafold": "fetching_alphafold",
+        "interpret": "interpreting",
+    }
+
+    _failed_step = None
+    _failed_error = None
+
+    async def _notify(step_key: str):
+        if status_callback:
+            try:
+                await status_callback(_STEP_FRONTEND.get(step_key, "running"))
+            except Exception:
+                pass
+
+    def _mark(step_key: str, status: str, **kw):
+        _set_step_status(job_id, step_key, status, **kw)
+
+    def _fail(step_key: str, msg: str):
+        nonlocal _failed_step, _failed_error
+        _mark(step_key, "failed", error=msg)
+        _failed_step = step_key
+        _failed_error = msg
+
+    # ---- Step 1: BLAST (must run first) ----
+    denovo_mode = False
+    if "blast" in steps:
+        await _notify("blast")
+        _mark("blast", "running", progress=10)
+        result = await _run_blast(
+            sequence,
+            status_callback=status_callback,
+            fast_mode=fast_mode,
+            blast_params=blast_params,
+        )
+        zero_hits = result.get("count", 0) == 0
+        if zero_hits and (detect_sequence_type(sequence) or "protein") == "protein":
+            # Tier 6: no database match at all — characterize from sequence
+            # alone instead of failing the run (techspec.md §1).
+            denovo_mode = True
+            result["_note"] = "No BLAST hits found — switching to de novo characterization"
+            _mark("blast", "complete", progress=100, data=result)
+        else:
+            _mark("blast", "failed" if zero_hits else "complete", progress=100, data=result)
+            if zero_hits:
+                _failed_step = "blast"
+                _failed_error = result.get("error", "No BLAST hits found")
+        context["blast"] = result
+
+    if denovo_mode:
+        context["query"]["confidence"] = "de_novo"
+        await _run_denovo_steps(job_id, sequence, steps, _mark, context)
+        await _finalize_context(job_id, context)
+        with _jobs_lock:
+            if job_id in _jobs:
+                _jobs[job_id]["status"] = "complete"
+                _jobs[job_id]["context"] = context
+        _persist_v2_final(job_id, "complete", context)
+        return
+
+    # ---- Step 2: Fan-out — UniProt, MSA, Pathway run in parallel ----
+    #    They all only depend on BLAST results, not on each other.
+    blast_data = context.get("blast", {})
+    hits = (blast_data.get("hits") if isinstance(blast_data, dict) else []) or []
+    top_hit = blast_data.get("top_hit") if isinstance(blast_data, dict) else None
+
+    async def _do_uniprot():
+        candidates = ([top_hit] + hits[:5]) if top_hit else hits[:5]
+        last_result: dict | None = None
+        for idx, candidate in enumerate(candidates):
+            # Only the top candidate may trigger the expensive EBI sequence
+            # BLAST fallback — otherwise a pathological query could run it up
+            # to 6 times (up to ~3 min each).
+            last_result = await _run_uniprot(
+                candidate,
+                query_sequence=sequence,
+                try_sequence=idx == 0,
+            )
+            if "error" not in last_result:
+                return last_result
+        return last_result if last_result else {"error": "No BLAST hits for UniProt lookup"}
+
+    async def _do_msa():
+        if not hits:
+            return {"error": "No BLAST hits for MSA"}
+        return await _run_msa(sequence, hits, alignment_mode)
+
+    async def _do_pathway():
+        return await _run_pathway_enrichment(context)
+
+    fan_out = []
+    fan_names = []
+    if "uniprot" in steps and not _failed_step:
+        fan_out.append(_do_uniprot())
+        fan_names.append("uniprot")
+    if "msa" in steps and not _failed_step:
+        fan_out.append(_do_msa())
+        fan_names.append("msa")
+    if "pathway_enrichment" in steps and not _failed_step:
+        fan_out.append(_do_pathway())
+        fan_names.append("pathway_enrichment")
+
+    if fan_out:
+        # Notify for the first active step in the fan-out
+        await _notify(fan_names[0])
+        for name in fan_names:
+            _mark(name, "running", progress=10)
+
+        results = await asyncio.gather(*fan_out, return_exceptions=True)
+
+        for name, res in zip(fan_names, results):
+            if isinstance(res, Exception):
+                _fail(name, str(res)[:500])
+                continue
+
+            if name == "uniprot":
+                s = "complete" if "error" not in res else "failed"
+                _mark("uniprot", s, progress=100, data=res)
+                context["uniprot"] = res
+                if res.get("confidence"):
+                    context["query"]["confidence"] = res["confidence"]
+                if "error" in res:
+                    _failed_step = "uniprot"
+                    _failed_error = res["error"]
+
+            elif name == "msa":
+                s = "complete" if res.get("aln_fasta") else "failed"
+                _mark("msa", s, progress=100, data=res)
+                context["msa"] = res
+                if res.get("phylotree"):
+                    context.setdefault("phylo_data", {})["phylotree_newick"] = res["phylotree"]
+
+            elif name == "pathway_enrichment":
+                s = "complete" if res and res.get("pathways") else "failed"
+                _mark("pathway_enrichment", s, progress=100, data=res or {})
+                context["pathway_enrichment"] = res
+
+    # ---- Step 3: Phylo (instant — copies from MSA) ----
+    if "phylo" in steps and not _failed_step:
+        _mark("phylo", "running", progress=10)
+        newick = None
+        msa_data = context.get("msa", {})
+        if isinstance(msa_data, dict):
+            newick = msa_data.get("phylotree")
+        if not newick:
+            newick = context.get("phylo_data", {}).get("phylotree_newick")
+        if newick:
+            _mark("phylo", "complete", progress=100, data={"phylotree_newick": newick})
+            context["phylo"] = {"phylotree_newick": newick}
+        else:
+            _mark("phylo", "failed", error="No phylotree available from MSA")
+
+    # ---- Step 4: Domains + AlphaFold in parallel ----
+    # When UniProt resolution exhausted all tiers, these fall back to their
+    # sequence-only equivalents instead of being silently skipped (§1.2).
+    uniprot_data = context.get("uniprot", {})
+    accession = uniprot_data.get("accession") if isinstance(uniprot_data, dict) else None
+    resolved_uniprot = bool(uniprot_data.get("resolved_uniprot")) if isinstance(uniprot_data, dict) else False
+
+    post_uniprot = []
+    post_uniprot_names = []
+    if "domains" in steps and not _failed_step:
+        post_uniprot.append(
+            _run_domains_or_denovo(sequence, accession, resolved_uniprot)
+        )
+        post_uniprot_names.append("domains")
+    if "alphafold" in steps and not _failed_step:
+        post_uniprot.append(
+            _run_alphafold_or_esmfold(context, sequence, accession, resolved_uniprot)
+        )
+        post_uniprot_names.append("alphafold")
+
+    if post_uniprot:
+        await _notify(post_uniprot_names[0])
+        for name in post_uniprot_names:
+            _mark(name, "running", progress=10)
+
+        results2 = await asyncio.gather(*post_uniprot, return_exceptions=True)
+
+        for name, res in zip(post_uniprot_names, results2):
+            if isinstance(res, Exception):
+                _fail(name, str(res)[:500])
+                continue
+
+            if name == "domains":
+                s = "complete" if res.get("domains") is not None else "failed"
+                _mark("domains", s, progress=100, data=res)
+                context["domains"] = res
+            elif name == "alphafold":
+                s = "complete" if res else "failed"
+                _mark("alphafold", s, progress=100, data=res or {})
+                context["alphafold"] = res
+
+    # ---- Step 5: Interpret (needs all context) ----
+    if "interpret" in steps and not _failed_step:
+        await _notify("interpret")
+        _mark("interpret", "running", progress=10)
+        result = await _run_interpret(context)
+        s = "complete" if result.get("interpretation") else "failed"
+        _mark("interpret", s, progress=100, data=result)
+        context["interpret"] = result
+
+    # ---- Final status ----
+    if _failed_step and _failed_step in ("blast", "uniprot"):
+        with _jobs_lock:
+            if job_id in _jobs:
+                _jobs[job_id]["status"] = "failed"
+                _jobs[job_id]["error"] = f"Pipeline failed at {_failed_step}: {_failed_error}"
+        _persist_v2_final(job_id, "failed", context, error=f"Pipeline failed at {_failed_step}: {_failed_error}")
+    else:
+        await _finalize_context(job_id, context)
+        with _jobs_lock:
+            if job_id in _jobs:
+                _jobs[job_id]["status"] = "complete"
+                _jobs[job_id]["context"] = context
+        _persist_v2_final(job_id, "complete", context)
+
+
+async def _finalize_context(job_id: str, context: dict):
+    """Pre-persist hook: capture source pages (§3) + build the final report."""
+    user_id = None
+    with _jobs_lock:
+        entry = _jobs.get(job_id)
+        if entry:
+            user_id = entry.get("user_id")
+    try:
+        _capture_run_sources(job_id, context, user_id)
+    except Exception as e:  # captures must never break a run
+        logger.warning("[%s] page capture wiring failed: %s", job_id, e)
+    try:
+        from app.services.final_synthesis import synthesize
+
+        context["final_report"] = await synthesize(context)
+    except Exception as e:
+        logger.warning("[%s] final synthesis failed: %s", job_id, e)
+
+
+def _capture_run_sources(job_id: str, context: dict, user_id: str | None):
+    """Queue one page_captures row per external source this run queried."""
+    from app.services.page_capture import capture_bg
+
+    blast = context.get("blast") or {}
+    top_hit = blast.get("top_hit")
+    if top_hit and top_hit.get("accession"):
+        capture_bg(job_id, "ncbi", f"https://www.ncbi.nlm.nih.gov/protein/{top_hit['accession']}", user_id)
+
+    uniprot = context.get("uniprot") or {}
+    if uniprot.get("_de_novo"):
+        pass  # no external annotation source was queried in de novo mode
+    elif uniprot.get("accession"):
+        capture_bg(job_id, "uniprot", f"https://www.uniprot.org/uniprotkb/{uniprot['accession']}", user_id)
+        pdb_ids = uniprot.get("pdb_ids") or []
+        if pdb_ids:
+            capture_bg(job_id, "rcsb", f"https://www.rcsb.org/structure/{pdb_ids[0]}", user_id)
+
+    domains = context.get("domains") or {}
+    dom_list = domains.get("domains") or []
+    if dom_list and dom_list[0].get("accession"):
+        acc = dom_list[0]["accession"]
+        if str(acc).startswith("IPR"):
+            capture_bg(job_id, "interpro", f"https://www.ebi.ac.uk/interpro/entry/InterPro/{acc}", user_id)
+
+    af = context.get("alphafold") or {}
+    if af.get("structure_available") and af.get("source") != "esmfold" and uniprot.get("accession"):
+        capture_bg(job_id, "alphafold", f"https://alphafold.ebi.ac.uk/uniprot/{uniprot['accession']}", user_id)
+
+    pathway = context.get("pathway_enrichment") or {}
+    pw_list = (pathway.get("pathways") if isinstance(pathway, dict) else None) or []
+    if pw_list and pw_list[0].get("stId"):
+        # run_enrichment queries the Reactome projection API exclusively
+        capture_bg(
+            job_id, "reactome",
+            f"https://reactome.org/PathwayBrowser/#{pw_list[0]['stId']}",
+            user_id,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Step implementations
+# ---------------------------------------------------------------------------
+
+# NCBI database name → EBI ncbiblast database name. EBI has no direct "nr"
+# equivalent; uniprotkb is its closest comprehensive protein database.
+EBI_BLAST_DATABASE_MAP = {
+    "nr": "uniprotkb",
+    "swissprot": "uniprotkb_swissprot",
+    "pdb": "pdb",
+    "pdbaa": "pdb_nr",
+    "refseq_protein": "refseq_protein",
+    "env_nr": "env_nr",
+    "nt": "nt",
+    "refseq_rna": "refseq_rna",
+    "refseq_genomic": "refseq_genomic",
+    "est": "est",
+    "gss": "gss",
+}
+
+
+def _build_blast_result(
+    hits: list[dict],
+    *,
+    source: str,
+    database: str,
+    program: str,
+    seq_type: str,
+    query_accession: str,
+    query_length: int,
+    display_limit: int = 20,
+) -> dict:
+    """Normalize parsed hits (NCBI XML parser or EBI tool) into the pipeline's
+    canonical BLAST result shape consumed by the frontend."""
+    top_hit = hits[0] if hits else None
+    return {
+        "count": len(hits),
+        "source": source,
+        "database": database,
+        "program": program,
+        "query_sequence_type": seq_type,
+        "query_accession": query_accession,
+        "query_length": query_length,
+        "top_hit": {
+            "accession": top_hit["accession"],
+            "description": top_hit["description"],
+            "evalue": top_hit["evalue"],
+            "evalue_raw": str(top_hit["evalue"]),
+            "identity_pct": top_hit["identity_pct"],
+            "bit_score": top_hit["bit_score"],
+            "alignment_length": top_hit.get("alignment_length", 0),
+        } if top_hit else None,
+        "hits": [
+            {
+                "accession": h["accession"],
+                "description": h["description"],
+                "organism": h.get("organism", ""),
+                "evalue": h["evalue"],
+                "evalue_raw": str(h["evalue"]),
+                "identity_pct": h["identity_pct"],
+                "bit_score": h["bit_score"],
+                "alignment_length": h.get("alignment_length", 0),
+                "query_coverage_pct": round(h.get("alignment_length", 0) / query_length * 100, 1) if query_length > 0 else 0,
+                "hit_alignment": h.get("hit_alignment", ""),
+                "query_alignment": h.get("query_alignment", ""),
+                "midline": h.get("midline", ""),
+                "score": h.get("score", 0),
+                "positive": h.get("positive", 0),
+                "gaps": h.get("gaps", 0),
+                "query_from": h.get("query_from", 0),
+                "query_to": h.get("query_to", 0),
+                "hit_from": h.get("hit_from", 0),
+                "hit_to": h.get("hit_to", 0),
+            }
+            for h in hits[:display_limit]
+        ],
+    }
+
+
+async def _run_ebi_blast_fallback(
+    sequence: str,
+    program: str,
+    database: str,
+    seq_type: str,
+    max_hits: int,
+) -> dict | None:
+    """Run BLAST against EBI (uncached) and return a canonical result, or None
+    if the database has no EBI equivalent or EBI itself fails."""
+    ebi_database = EBI_BLAST_DATABASE_MAP.get(database)
+    if not ebi_database:
+        logger.warning("No EBI database equivalent for '%s' — skipping fallback", database)
+        return None
+    try:
+        result = await BlastTool().run_uncached({
+            "sequence": sequence,
+            "program": program,
+            "database": ebi_database,
+            "max_hits": max_hits,
+        })
+    except Exception as e:
+        logger.warning("EBI BLAST fallback failed: %s", e)
+        return None
+    if result.get("error") or not result.get("hits"):
+        logger.warning("EBI BLAST fallback returned no hits: %s", result.get("error", "empty"))
+        return None
+    query_length = len("".join(sequence.replace("\n", "").replace(" ", "").split("-")))
+    return _build_blast_result(
+        result["hits"],
+        source="ebi",
+        database=database,
+        program=program,
+        seq_type=seq_type,
+        query_accession="",
+        query_length=query_length,
+    )
+
+
+async def _run_blast(
+    sequence: str,
+    status_callback=None,
+    fast_mode: bool = False,
+    blast_params: dict | None = None,
+) -> dict:
+    blast_params = blast_params or {}
+    try:
+        program, database, seq_type = resolve_blast_params(
+            sequence,
+            program=blast_params.get("program"),
+            database=blast_params.get("database"),
+            fast_mode=fast_mode,
+        )
+    except ValueError as e:
+        logger.warning("BLAST param resolution failed: %s", e)
+        return {"error": str(e), "count": 0, "hits": []}
+
+    try:
+        max_hits = int(blast_params.get("max_hits") or 100)
+    except (TypeError, ValueError):
+        max_hits = 100
+    max_hits = max(5, min(max_hits, 100))
+    query_accession = (blast_params.get("query_accession") or "").strip()
+
+    if status_callback:
+        try:
+            await status_callback("submitted_to_ncbi")
+        except Exception:
+            pass
+
+    # EBI is fast & reliable (~30s) and returns UniProt accessions the rest of
+    # the pipeline consumes directly. NCBI chronically stalls (long WAITING
+    # even with an API key), so run EBI FIRST and fall back to NCBI.
+    ebi_result = await _run_ebi_blast_fallback(sequence, program, database, seq_type, max_hits)
+    if ebi_result is not None:
+        if status_callback:
+            try:
+                await status_callback("parsing")
+            except Exception:
+                pass
+        return ebi_result
+
+    # EBI unavailable for this database or failed — try NCBI before failing.
+    ncbi_error: str | None = None
+    results = await ncbi_blast.run_blast_with_retry(
+        sequence,
+        retries=2,
+        max_wait_seconds=600 if fast_mode else 900,
+        database=database,
+        program=program,
+        hitlist_size=max_hits,
+    )
+
+    if "error" not in results:
+        parsed = parse_blast_xml(results["raw"])
+        if "error" not in parsed:
+            if status_callback:
+                try:
+                    await status_callback("parsing")
+                except Exception:
+                    pass
+            hits = parsed.get("hits", [])[:max_hits]
+            return _build_blast_result(
+                hits,
+                source="ncbi",
+                database=database,
+                program=program,
+                seq_type=seq_type,
+                query_accession=query_accession,
+                query_length=parsed.get("query_length", 0),
+            )
+        ncbi_error = parsed["error"]
+    else:
+        ncbi_error = results["error"]
+
+    logger.warning("EBI BLAST unavailable and NCBI failed (%s)", ncbi_error)
+    return {"error": ncbi_error or "BLAST failed via EBI and NCBI", "count": 0, "hits": []}
+
+
+async def _run_uniprot(top_hit: dict, query_sequence: str | None = None, try_sequence: bool = True) -> dict:
+    accession = (top_hit.get("accession") or "").strip()
+    if not accession:
+        return {"error": "No accession"}
+    desc = (top_hit.get("description") or "").strip()
+    organism = (top_hit.get("organism") or "").strip()
+
+    # Resolve ANY BLAST-hit accession (RefSeq, GenBank, PDB, Ensembl, ...) to a
+    # UniProt accession via the strategy ladder in identifier_resolution:
+    #   direct -> xref search (fast) -> name search -> EBI sequence BLAST -> idmapping
+    # Exhausting all tiers returns an explicit unresolved/de_novo result (§1).
+    try:
+        resolved = await resolve_to_uniprot(
+            accession=accession,
+            sequence=query_sequence,
+            description=desc,
+            organism=organism or None,
+            try_sequence=try_sequence,
+        )
+    except Exception as e:
+        logger.warning("Identifier resolution failed for %s: %s", accession, e)
+        resolved = None
+
+    if not resolved or resolved.get("status") != "resolved":
+        logger.info("No UniProt mapping for %s, using BLAST data only", accession)
+        return {
+            "accession": accession,
+            "full_name": top_hit.get("description", ""),
+            "organism": top_hit.get("organism", ""),
+            "gene_names": [],
+            "functions": [],
+            "keywords": [],
+            "subcellular_locations": [],
+            "pdb_ids": [],
+            "go_terms": [],
+            "sequence": "",
+            "sequence_length": 0,
+            "features": [],
+            "resolution": {
+                "uniprot_accession": None,
+                "method": "de_novo",
+                "original_accession": accession,
+            },
+            "resolved_uniprot": False,
+            # BLAST-derived similarity is homolog-grade certainty at best (§1.1)
+            "confidence": "homolog",
+            "_note": f"No UniProt mapping found for {accession} — showing BLAST-derived data only",
+        }
+
+    uniprot_acc = resolved["accession"]
+    method = resolved["method"]
+
+    tool = UniprotTool()
+    result = await tool.run({"accession": uniprot_acc})
+    if "error" in result:
+        return {"error": result["error"]}
+
+    return {
+        "accession": result.get("accession", uniprot_acc),
+        "full_name": result.get("full_name", ""),
+        "organism": result.get("organism", ""),
+        "gene_names": result.get("gene_names", []),
+        "functions": result.get("functions", []),
+        "keywords": result.get("keywords", []),
+        "subcellular_locations": result.get("subcellular_locations", []),
+        "pdb_ids": result.get("pdb_ids", []),
+        "go_terms": result.get("go_terms", []),
+        "sequence": result.get("sequence", ""),
+        "sequence_length": result.get("sequence_length", 0),
+        "features": [
+            f for f in (result.get("features", []) or [])
+            if f.get("type") in ("ACTIVE_SITE", "BINDING", "MUTAGENESIS", "SITE", "MOD_RES")
+        ],
+        "resolution": {
+            "uniprot_accession": uniprot_acc,
+            "method": method,
+            "original_accession": accession,
+        },
+        "resolved_uniprot": True,
+        "confidence": resolved.get("confidence", "identified"),
+    }
+
+
+async def _run_msa(query_sequence: str, blast_hits: list, alignment_mode: str = "global") -> dict:
+    sequences = [("query", query_sequence)]
+
+    for hit in blast_hits[:5]:
+        acc = hit.get("accession", "")
+        hit_seq = hit.get("hit_alignment", "")
+
+        if acc:
+            source = detect_source_from_accession(acc)
+            mapped_acc = acc
+            if source == "ncbi":
+                mapped = await map_refseq_to_uniprot(acc)
+                if mapped:
+                    mapped_acc = mapped
+            try:
+                tool = UniprotTool()
+                ud = await tool.run({"accession": mapped_acc})
+                if "error" not in ud and ud.get("sequence"):
+                    clean_seq = "".join(c for c in ud["sequence"] if c.isalpha()).upper()
+                    if len(clean_seq) > 10:
+                        sequences.append((acc, clean_seq))
+                        continue
+            except Exception:
+                pass
+
+        if hit_seq:
+            clean = "".join(c for c in hit_seq if c.isalpha()).upper()
+            if len(clean) > 10:
+                sequences.append((f"{acc}_aln", clean))
+
+    if len(sequences) < 2:
+        return {"error": "Not enough sequences for MSA", "aln_fasta": None, "phylotree": None}
+
+    fasta_lines = []
+    for sid, sseq in sequences:
+        fasta_lines.append(f">{sid}")
+        for i in range(0, len(sseq), 80):
+            fasta_lines.append(sseq[i:i + 80])
+    fasta_str = "\n".join(fasta_lines)
+
+    try:
+        email = settings.NCBI_EMAIL or "bioflow@example.com"
+        seq_type = detect_sequence_type(query_sequence) or "protein"
+        stype = "protein" if seq_type == "protein" else "dna"
+        try:
+            # Try local MAFFT first (fast, no network dependency)
+            from app.tools.mafft_local import run_local_mafft
+            local_result = await asyncio.get_running_loop().run_in_executor(
+                None, run_local_mafft, fasta_str, "auto", 1, 300,
+            )
+            if local_result and local_result.get("aln_fasta"):
+                method = "mafft-local"
+                aln_fasta = local_result["aln_fasta"]
+                phylotree = ""
+            else:
+                raise ValueError("local MAFFT unavailable or returned empty")
+        except Exception:
+            try:
+                result = await run_ebi_msa_best_effort(
+                    sequence=fasta_str,
+                    stype=stype,
+                    email=email,
+                )
+                method = result["method"]
+                aln_fasta = result["aln_fasta"]
+                phylotree = result["phylotree"]
+            except Exception as e:
+                logger.warning("EBI MSA unavailable (%s) — using in-process fallback", e)
+                from app.tools.msa_fallback import progressive_msa
+                fallback = await asyncio.get_running_loop().run_in_executor(
+                    None, progressive_msa, sequences, stype
+                )
+                aln_fasta, phylotree = fallback
+                method = "in-process fallback"
+
+        payload = {
+            "aln_fasta": aln_fasta,
+            "phylotree": phylotree,
+            "sequence_count": len(sequences),
+            "alignment_mode": alignment_mode,
+            "method": method,
+            "_fallback": method != "clustalo",
+        }
+
+        # Local mode: refine query vs the best non-query sequence with an
+        # in-process Smith-Waterman alignment so the wizard can show which
+        # region actually matches (EBI MSA itself is always global).
+        if alignment_mode == "local" and len(sequences) > 1:
+            subject_id, subject_seq = sequences[1]
+            try:
+                payload["pairwise"] = pairwise_align(query_sequence, subject_seq, mode="local")
+                payload["pairwise_subject"] = subject_id
+            except Exception as e:
+                logger.warning("Local pairwise refinement failed: %s", e)
+
+        return payload
+
+    except Exception as e:
+        return {"error": str(e), "aln_fasta": None, "phylotree": None}
+
+
+async def _run_domains(accession: str) -> dict:
+    """Run domain analysis using the shared tool module (eliminates code duplication)."""
+    try:
+        from app.tools.domain_analysis import fetch_interpro_domains
+        return await fetch_interpro_domains(accession)
+    except Exception as e:
+        return {"error": str(e), "uniprot_accession": accession, "sequence_length": 0, "domains": []}
+
+
+async def _run_denovo_steps(job_id: str, sequence: str, steps: list[str], _mark, context: dict) -> None:
+    """Tier-6 branch (techspec.md §1): characterize from sequence alone.
+
+    Runs when BLAST finds no homolog at all. Composition/function hints land
+    in the uniprot slot (the annotation slot); MSA/phylo/pathways are marked
+    explicitly unavailable rather than left empty.
+    """
+    import asyncio as _asyncio
+    from app.services.de_novo import (
+        composition_stats, esmfold_structure, function_hints, interpro_sequence_search,
+    )
+
+    unavailable = "Unavailable for de novo sequences — no identified homolog"
+
+    async def _do_annotation():
+        bundle = {"_de_novo": True}
+        try:
+            bundle["composition"] = composition_stats(sequence)
+        except Exception as e:
+            bundle["composition"] = {"error": str(e)}
+        try:
+            bundle["function_hints"] = function_hints(sequence)
+        except Exception as e:
+            bundle["function_hints"] = {"error": str(e)}
+        return bundle
+
+    async def _do_domains():
+        try:
+            return await interpro_sequence_search(sequence)
+        except Exception as e:
+            logger.warning("De novo InterProScan failed: %s", e)
+            return {"error": str(e), "domains": [], "sequence_length": 0}
+
+    async def _do_structure():
+        try:
+            return await esmfold_structure(sequence)
+        except Exception as e:
+            logger.warning("De novo ESMFold failed: %s", e)
+            return {"structure_available": False, "source": "esmfold", "message": str(e)}
+
+    fan = []
+    names = []
+    if "uniprot" in steps:
+        fan.append(_do_annotation())
+        names.append("uniprot")
+    if "domains" in steps:
+        fan.append(_do_domains())
+        names.append("domains")
+    if "alphafold" in steps:
+        fan.append(_do_structure())
+        names.append("alphafold")
+
+    for name in names:
+        _mark(name, "running", progress=10)
+    results = await _asyncio.gather(*fan, return_exceptions=True)
+
+    for name, res in zip(names, results):
+        if isinstance(res, Exception):
+            _mark(name, "failed", error=str(res)[:500])
+            continue
+        ok = (
+            res.get("domains") is not None if name == "domains"
+            else res.get("structure_available") is True if name == "alphafold"
+            else True
+        )
+        _mark(name, "complete" if ok else "failed", progress=100,
+              data=res, error=None if ok else "Prediction returned nothing usable")
+        context[name] = res
+
+    # Annotation-database features have no de novo substitute — say so.
+    for name in ("msa", "phylo", "pathway_enrichment"):
+        if name in steps:
+            _mark(name, "failed", error=unavailable)
+
+
+async def _run_domains_or_denovo(sequence: str, accession: str | None, resolved_uniprot: bool) -> dict:
+    """Accession lookup when resolved; InterProScan sequence-search otherwise."""
+    if accession and resolved_uniprot:
+        return await _run_domains(accession)
+    from app.services.de_novo import interpro_sequence_search
+    try:
+        result = await interpro_sequence_search(sequence)
+        result["confidence"] = "de_novo"
+        return result
+    except Exception as e:
+        return {"error": str(e), "domains": [], "sequence_length": 0}
+
+
+async def _run_alphafold_or_esmfold(
+    context: dict, sequence: str, accession: str | None, resolved_uniprot: bool,
+) -> dict:
+    """AlphaFold DB lookup when resolved; ESMFold ab initio otherwise."""
+    if accession and resolved_uniprot:
+        result = await _run_alphafold(context)
+        return result or {}
+    from app.services.de_novo import esmfold_structure
+    try:
+        return await esmfold_structure(sequence)
+    except Exception as e:
+        return {"structure_available": False, "source": "esmfold", "message": str(e)}
+
+
+async def _run_pathway_enrichment(context: dict) -> dict | None:
+    gene_names = []
+    uniprot = context.get("uniprot", {})
+    if isinstance(uniprot, dict):
+        gene_names = uniprot.get("gene_names", [])[:20] if isinstance(uniprot.get("gene_names"), list) else []
+    if not gene_names:
+        blast_data = context.get("blast", {})
+        if isinstance(blast_data, dict):
+            for hit in (blast_data.get("hits") or [])[:10]:
+                words = (hit.get("description", "") or "").replace("(", " ").replace(")", " ").split()
+                for w in words:
+                    if w.isupper() and len(w) >= 2 and not w.startswith("OS="):
+                        gene_names.append(w)
+                        break
+    if not gene_names:
+        return None
+    try:
+        from app.services.pathway_enrichment import run_enrichment
+        result = await run_enrichment(gene_names)
+        return result
+    except Exception as e:
+        logger.warning(f"Pathway enrichment failed: {e}")
+        return None
+
+
+async def _run_alphafold(context: dict) -> dict | None:
+    uniprot_data = context.get("uniprot", {})
+    accession = uniprot_data.get("accession") if isinstance(uniprot_data, dict) else None
+    if not accession:
+        return None
+    try:
+        from app.tools.alphafold import AlphaFoldTool
+        result = await AlphaFoldTool().run({"uniprot_accession": accession})
+        return result
+    except Exception as e:
+        logger.warning(f"AlphaFold fetch failed for {accession}: {e}")
+        return {"structure_available": False, "message": str(e)}
+
+
+async def _run_interpret(context: dict) -> dict:
+    from app.ai.interpreter import interpret_text
+    prompt_context = {
+        "blast": context.get("blast", {}),
+        "uniprot": context.get("uniprot", {}),
+        "alphafold": context.get("alphafold", {}),
+        "pathway_enrichment": context.get("pathway_enrichment", {}),
+        "query_confidence": context.get("query", {}).get("confidence", "identified"),
+    }
+    return await interpret_text("protein_analysis", prompt_context)

migrations/011_ngs_production_runs.sql

@@ -0,0 +1,26 @@
+-- Durable ownership and execution state for real nf-core/sarek runs.
+CREATE TABLE IF NOT EXISTS ngs_production_runs (
+  run_id uuid PRIMARY KEY,
+  user_id uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  state text NOT NULL CHECK (state IN ('SUBMITTED','PENDING','RUNNING','SUCCEEDED','FAILED','UNKNOWN')),
+  executor text NOT NULL CHECK (executor IN ('local','slurm','awsbatch')),
+  executor_job_id text NOT NULL,
+  workflow text NOT NULL,
+  revision text NOT NULL,
+  outdir text NOT NULL,
+  submitted_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  exit_code integer,
+  message text
+);
+
+CREATE INDEX IF NOT EXISTS idx_ngs_production_runs_user_updated
+  ON ngs_production_runs(user_id, updated_at DESC);
+
+ALTER TABLE ngs_production_runs ENABLE ROW LEVEL SECURITY;
+
+DO $$ BEGIN
+  CREATE POLICY "Users can view own production NGS runs"
+    ON ngs_production_runs FOR SELECT USING (auth.uid() = user_id);
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;

requirements.txt

@@ -21,3 +21,4 @@ pymol-open-source-whl>=3.2  # unofficial wheel of open-source PyMOL; provides th
 # dev / testing
 pytest>=7.0
 httpx>=0.24
+boto3>=1.35,<2

tests/test_ngs_platform.py

@@ -545,6 +545,15 @@ def test_reference_validation_resolves_grch38():
     assert out["summary"]["reference"]["build"] == "GRCh38"
 
 
+def test_synthetic_reference_never_claims_grch38_coordinates():
+    out = run_reference_validation({"reference": "grch38", "synthetic_reference": True})
+    reference = out["summary"]["reference"]
+    assert out["summary"]["status"] == "PASS"
+    assert reference["id"] == "synthetic-positive-control"
+    assert reference["build"] == "NOT_APPLICABLE"
+    assert reference["requested_template"] == "grch38"
+
+
 def test_reference_validation_mismatch_stops():
     # GRCh38 data against a GRCh37 annotation is a provenance error -> STOP.
     out = run_reference_validation({"reference": "grch38", "annotation_build": "GRCh37"})
@@ -623,7 +632,9 @@ def test_choose_aligner_by_assay():
 def test_alignment_run_and_mapping_ok():
     ref, reads = _make_ref_and_reads(ref_len=600, n_reads=20)
     out = run_alignment(reads[:20], ref, assay="WGS", read_length=30)
-    assert out["summary"]["meta"]["aligner"] == "bwa-mem2"
+    assert out["summary"]["meta"]["recommended_production_aligner"] == "bwa-mem2"
+    assert out["summary"]["meta"]["executed_implementation"] == "bionexus-seed-aligner"
+    assert out["summary"]["meta"]["executor"] == "python-surrogate"
     assert out["summary"]["decision"] != "STOP"
     assert out["summary"]["meta"]["mapped"] >= 18
     assert len(out["records"]) == 20

tests/test_ngs_production_execution.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from app.config import settings
+from app.ngs import execution
+
+
+def test_capabilities_never_offer_preview_fallback(monkeypatch):
+    monkeypatch.setattr(settings, "NGS_LOCAL_EXECUTION_ENABLED", False)
+    monkeypatch.setattr(settings, "NGS_SLURM_EXECUTION_ENABLED", False)
+    monkeypatch.setattr(settings, "NGS_AWS_BATCH_EXECUTION_ENABLED", False)
+    result = execution.executor_capabilities()
+    assert result["fallback"] is None
+    assert all(not item["available"] for item in result["executors"].values())
+    assert "never fall back" in result["note"]
+
+
+def test_disabled_executor_fails_closed(monkeypatch):
+    monkeypatch.setattr(settings, "NGS_LOCAL_EXECUTION_ENABLED", False)
+    try:
+        execution.submit_run("local", ["nextflow", "run", "nf-core/sarek"], "/results", "user-1")
+    except RuntimeError as exc:
+        assert "executor unavailable" in str(exc)
+    else:
+        raise AssertionError("disabled executor accepted a production run")
+
+
+def test_owned_run_record_round_trip(tmp_path, monkeypatch):
+    monkeypatch.setattr(settings, "NGS_RUN_ROOT", str(tmp_path))
+    monkeypatch.setattr("app.services.supabase.get_supabase", lambda: (_ for _ in ()).throw(RuntimeError("offline")))
+    record = {
+        "run_id": "11111111-1111-1111-1111-111111111111",
+        "state": "SUBMITTED", "executor": "local", "executor_job_id": "123",
+        "workflow": "nf-core/sarek", "revision": "3.10.0", "outdir": "/results",
+        "submitted_at": "2026-09-02T00:00:00+00:00", "updated_at": "2026-09-02T00:00:00+00:00",
+        "exit_code": None, "message": None, "user_id": "user-1",
+    }
+    execution._persist_record(record)
+    assert Path(tmp_path, f"{record['run_id']}.json").is_file()
+    assert execution._load_record(record["run_id"], "user-1")["workflow"] == "nf-core/sarek"
+    try:
+        execution._load_record(record["run_id"], "user-2")
+    except FileNotFoundError:
+        pass
+    else:
+        raise AssertionError("run record was visible to another user")

tests/test_ngs_v2_router.py

@@ -1,4 +1,6 @@
 import gzip
+import hashlib
+import hmac
 import os
 import random
 
@@ -7,6 +9,9 @@ from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
 from app.routers import ngs_v2
+from app.models.responses import NgsClinicalEvidenceRequest
+from app.ngs.production import clinical_signature_payload
+from app.config import settings
 
 
 @pytest.fixture(scope="module")
@@ -40,6 +45,167 @@ def test_stages_lists_contracts(client):
     assert len(steps) == 21
 
 
+def test_portable_benchmark_reports_scoped_execution_parity(client):
+    response = client.get("/api/ngs/v2/benchmarks/portable")
+    assert response.status_code == 200
+    report = response.json()
+    assert report["status"] == "PASS"
+    assert report["workflow_output_parity"] is True
+    assert report["expected_call"] == {
+        "chrom": "chrTiny", "pos": 50, "ref": "C", "alt": "G",
+        "genotype": "0/1", "depth": 20, "allelic_depth": "10,10",
+    }
+    assert len({row["normalized_sha256"] for row in report["reports"]}) == 1
+    assert all(row["f1"] == 1.0 for row in report["reports"])
+    galaxy = next(row for row in report["reports"] if row["orchestrator"].startswith("Galaxy"))
+    assert galaxy["execution"] == "EXECUTED_WITHOUT_GALAXY_SERVER"
+
+
+def test_production_capabilities_are_explicit_and_have_no_preview_fallback(client):
+    response = client.get("/api/ngs/v2/production/capabilities")
+    assert response.status_code == 200
+    body = response.json()
+    assert set(body["executors"]) == {"local", "slurm", "awsbatch"}
+    assert body["fallback"] is None
+    assert body["workflow"] == {"name": "nf-core/sarek", "revision": "3.10.0"}
+
+
+def test_clean_demo_uses_explicit_not_evaluated_states(client):
+    response = client.post("/api/ngs/v2/analyze", json={"demo_profile": "wgs-clean"})
+    assert response.status_code == 200
+    body = response.json()
+    stages = {stage["step"]: stage for stage in body["pipeline"]["stages"]}
+
+    assert body["requested"]["reference"] == "synthetic-positive-control"
+    assert body["requested"]["reference_template_requested"] == "grch38"
+    assert body["detection"]["sample_type"] == "synthetic-positive-control"
+    reference = body["pipeline"]["provenance"]["reference"]
+    assert reference["id"] == "synthetic-positive-control"
+    assert reference["reference_kind"] == "SYNTHETIC"
+    assert reference["build"] == "NOT_APPLICABLE"
+    assert reference["artifacts"] == [{"name": "In-memory synthetic reference", "present": True}]
+
+    assert stages["coverage"]["qc"]["status"] == "PASS"
+    assert stages["variant_filter"]["qc"]["status"] == "PASS"
+    assert stages["variant_filter"]["data"]["n_final"] == 0
+    assert stages["annotation"]["qc"]["status"] == "PASS"
+    assert stages["annotation"]["data"]["n_annotated"] == 0
+    assert stages["annotation"]["data"]["status"] == "NOT_APPLICABLE"
+    assert stages["contamination"]["data"]["status"] == "NOT_EVALUATED"
+    assert stages["contamination"]["qc"]["metrics"][0]["value"] is None
+    assert stages["identity"]["data"]["status"] == "NOT_EVALUATED"
+    assert len(stages["identity"]["qc"]["metrics"]) == 1
+    assert stages["final_gate"]["qc"]["metrics"][0]["value"] == "ANALYSIS_READY_WITH_WARNINGS"
+
+    warnings = body["pipeline"]["warnings"]
+    assert len(warnings) == 2
+    assert all("Not evaluated:" in warning for warning in warnings)
+    assert not any("(None)" in warning for warning in warnings)
+    assert not any(name in " ".join(warnings) for name in (
+        "contam_checked", "identity_checked", "candidate_frac", "gate_ok",
+    ))
+    assert all(tool["implementation"] for tool in body["pipeline"]["provenance"]["tools"])
+
+
+def test_production_plan_pins_sarek_and_emits_auditable_argv(client):
+    response = client.post("/api/ngs/v2/production/plan", json={
+        "assay": "WGS",
+        "sample_model": "trio",
+        "input_type": "FASTQ",
+        "samplesheet_path": "/staged/family.csv",
+        "outdir": "/results/family",
+        "genome": "GRCh38",
+        "execution_profile": "docker",
+        "caller": "haplotypecaller",
+        "clinical_intent": True,
+    })
+    assert response.status_code == 200
+    plan = response.json()
+    assert plan["ready_to_launch"] is True
+    assert plan["state"] == "PLANNED"
+    assert plan["workflow"]["name"] == "nf-core/sarek"
+    assert plan["workflow"]["revision"] == "3.10.0"
+    assert plan["command_argv"][:5] == ["nextflow", "run", "nf-core/sarek", "-r", "3.10.0"]
+    assert ["--genome", "GATK.GRCh38"] == plan["command_argv"][plan["command_argv"].index("--genome"):plan["command_argv"].index("--genome") + 2]
+    assert "--joint_germline" in plan["command_argv"]
+    assert plan["clinical_boundary"]["current_status"] == "NOT_CLINICALLY_RELEASABLE"
+    assert {item["id"] for item in plan["required_artifacts"]} >= {"execution", "multiqc", "alignment", "small_variants", "provenance"}
+
+
+def test_production_wes_and_remote_executor_fail_closed(client):
+    response = client.post("/api/ngs/v2/production/plan", json={
+        "assay": "WES",
+        "samplesheet_path": "/staged/case.csv",
+        "outdir": "/results/case",
+        "execution_profile": "slurm",
+    })
+    assert response.status_code == 200
+    plan = response.json()
+    assert plan["state"] == "BLOCKED"
+    assert plan["ready_to_launch"] is False
+    assert any("target BED" in item for item in plan["blockers"])
+    assert any("custom configuration" in item for item in plan["blockers"])
+
+
+def test_clinical_gate_rejects_claims_without_evidence(client):
+    response = client.post("/api/ngs/v2/clinical/evaluate", json={})
+    assert response.status_code == 200
+    result = response.json()
+    assert result["status"] == "NOT_CLINICALLY_RELEASABLE"
+    assert result["clinically_validated"] is False
+    assert result["missing_or_failed"]
+    signature_gate = next(gate for gate in result["gates"] if gate["id"] == "evidence_signature")
+    assert signature_gate["status"] == "FAIL"
+
+
+def test_clinical_gate_passes_only_complete_signed_external_evidence(client, monkeypatch):
+    sha = "a" * 64
+    payload = {
+        "evidence_bundle_sha256": "d" * 64,
+        "assay_validation_id": "VAL-WGS-2026-04",
+        "workflow_status": "COMPLETED",
+        "sarek_revision": "3.10.0",
+        "reference_build": "GRCh38",
+        "reference_manifest_sha256": sha,
+        "samplesheet_sha256": "b" * 64,
+        "container_digests_complete": True,
+        "complete_input_processed": True,
+        "required_artifacts_present": True,
+        "qc_pass": True,
+        "sample_identity_pass": True,
+        "contamination_pass": True,
+        "sex_ploidy_reviewed": True,
+        "truthset_name": "GIAB HG002 v4.2.1",
+        "benchmark_protocol_id": "SOP-BENCH-07",
+        "benchmark_acceptance_pass": True,
+        "confident_regions_sha256": "c" * 64,
+        "same_sample_reference_regions": True,
+        "snv_precision": 0.999,
+        "snv_recall": 0.998,
+        "indel_precision": 0.995,
+        "indel_recall": 0.994,
+        "human_reviewed": True,
+        "reviewer_id": "reviewer-17",
+        "release_signature_id": "sig-2026-09-01-001",
+    }
+    signing_key = "test-only-clinical-attestation-key"
+    monkeypatch.setattr(settings, "NGS_CLINICAL_EVIDENCE_HMAC_KEY", signing_key)
+    evidence = NgsClinicalEvidenceRequest(**payload)
+    payload["evidence_signature"] = hmac.new(
+        signing_key.encode("utf-8"), clinical_signature_payload(evidence), hashlib.sha256,
+    ).hexdigest()
+    response = client.post("/api/ngs/v2/clinical/evaluate", json=payload)
+    assert response.status_code == 200
+    result = response.json()
+    assert result["status"] == "SOFTWARE_GATE_PASSED"
+    assert result["clinically_validated"] is False
+    assert result["missing_or_failed"] == []
+
+    payload["truthset_name"] = "synthetic positive control"
+    rejected = client.post("/api/ngs/v2/clinical/evaluate", json=payload).json()
+    assert rejected["status"] == "NOT_CLINICALLY_RELEASABLE"
+
+
 def test_detect_returns_evidence(client, tmp_path):
     path, _ = _write_fastq(tmp_path, "HUM0001_R1.fastq.gz", 40)
     r = client.post("/api/ngs/v2/detect", json={"file_paths": [path]})
@@ -90,6 +256,34 @@ def test_analyze_runs_full_dag_through_final_gate(client, tmp_path):
     assert len(provenance["inputs"]) == 2
     assert all(item["checksum"]["algorithm"] == "md5" for item in provenance["inputs"])
     assert len(provenance["tools"]) == 21
+    assert all("implementation" in item for item in provenance["tools"])
+    assert all("evidence_level" in stage for stage in stages)
+
+    validation = body["pipeline"]["validation"]
+    assert validation["claim"] == "NO_ACCURACY_CLAIM"
+    assert validation["same_or_better_supported"] is False
+    assert len(validation["comparisons"]) >= 3
+    assert all(item["status"] != "EVALUATED" for item in validation["comparisons"])
+    assert all(item["metrics"] is None for item in validation["comparisons"])
+    assert validation["analysis_grade"] == "EXPLORATORY_PREVIEW"
+    assert validation["research_ready"] is False
+    assert all(item["status"] == "MISSING" for item in validation["production_requirements"])
+    assert body["requested"]["all_records_processed"] is True
+
+
+def test_analyze_discloses_fastq_sampling(client, tmp_path):
+    r1, _ = _write_fastq(tmp_path, "HG002_R1.fastq.gz", 2001, seed=21)
+    r2, _ = _write_fastq(tmp_path, "HG002_R2.fastq.gz", 2001, seed=22)
+    response = client.post("/api/ngs/v2/analyze", json={
+        "file_paths": [r1, r2], "reference": "grch38", "assay": "WGS",
+        "synthetic_reference": True,
+    })
+    assert response.status_code == 200
+    body = response.json()
+    assert body["requested"]["record_cap_per_file"] == 2000
+    assert body["requested"]["all_records_processed"] is False
+    assert sorted(body["requested"]["truncated_files"]) == ["HG002_R1.fastq.gz", "HG002_R2.fastq.gz"]
+    assert body["pipeline"]["validation"]["input_sampling"]["mode"] == "SAMPLED_PREVIEW"
 
 
 def test_analyze_emits_igv_tracks(client, tmp_path):