fix: overhaul the platform skeleton, add a serverless deployment track

An end-to-end audit found the repo could not build, test or run as shipped. This
fixes every finding, then adds a Cloud Run track so the demo costs about £1/month
idle instead of ~£150.

CI (red on its first run)
- api: setuptools could not build the package (flat layout with app/ and alembic/)
- web: missing @types/node; `vitest run` exited 1 with no test files
- pipeline: the stub run needed a gitignored VCF, and no process had a stub block
- ruff pinned, mypy configured, DB tests on real Postgres (pgserver locally, service in CI)

ML serving (scores were meaningless)
- the registered model now carries its own feature engineering and returns predict_proba,
  so serving sends raw columns and cannot drift from training
- resolve by registry alias (stages are deprecated in MLflow 3) and record the real
  version; re-scoring upserts instead of failing on the unique constraint
- ClinVar labels parsed from VEP's lowercase terms

Pipeline
- exact ref/alt recovered from a CHROM_POS_REF_ALT VCF ID; loading is idempotent
- job status reaches running/failed/succeeded, so the UI stops polling dead jobs
- DATABASE_URL travels in the environment or a Nextflow secret, never on a command line
- VEP cache and plugins staged as inputs; the gcp profile runs tasks on Google Batch

Deployment
- the API serves /api (matching the ingress); the web app reads its API URL at runtime
- migrations run in an init container under a Postgres advisory lock
- terraform: custom VPC shared with Batch, private Cloud SQL, API enablement, Workload
  Identity bindings, Secret Manager, deletion protection
- serverless track, now the default: Cloud Run services scaling to zero, a Cloud Run job
  for the Nextflow driver, and Neon or Cloud SQL behind one DATABASE_URL secret. GKE and
  Argo remain, behind -var deploy_kubernetes=true. See docs/cloud.md.

Correctness and security
- 409 on duplicate sample names, 422 on bad paging, natural chromosome ordering, wider
  VEP text columns, enum dropped on downgrade, the sample's assembly actually used
- vcf_uri restricted to gs:// objects or files under the data root, blocking option injection
- CORS restricted to configured origins; `make down` no longer deletes volumes

Data
- docs/data.md records the peer-reviewed, openly licensed sources (GIAB HG002, ClinVar,
  gnomAD) with citations and an honest evaluation plan; `make data` fetches a chr22 slice

Verified: api 50 tests, ml 18, loader 16, web 12; ruff, mypy, svelte-check, terraform
validate and both kustomize overlays clean.

api/app/routers/jobs.py

@@ -1,9 +1,8 @@
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import APIRouter, HTTPException
 
-from app.db import get_session
+from app.db import SessionDep
 from app.models import Job
 from app.schemas import JobOut
 
@@ -11,7 +10,7 @@ router = APIRouter()
 
 
 @router.get("/{job_id}", response_model=JobOut)
-async def get_job(job_id: uuid.UUID, session: AsyncSession = Depends(get_session)):
+async def get_job(job_id: uuid.UUID, session: SessionDep):
     job = await session.get(Job, job_id)
     if job is None:
         raise HTTPException(404, "job not found")

api/app/routers/predictions.py

@@ -1,16 +1,22 @@
 import uuid
 
-from fastapi import APIRouter, Depends
-from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import APIRouter, HTTPException
 
-from app.db import get_session
+from app.db import SessionDep
+from app.models import Job, JobStatus
+from app.schemas import ScoreOut
 from app.services.scoring import score_job
 
 router = APIRouter()
 
 
-@router.post("/score/{job_id}")
-async def score(job_id: uuid.UUID, session: AsyncSession = Depends(get_session)) -> dict:
-    """Load the registered MLflow model and score every variant of a job."""
-    n = await score_job(job_id, session)
-    return {"job_id": str(job_id), "scored": n}
+@router.post("/score/{job_id}", response_model=ScoreOut)
+async def score(job_id: uuid.UUID, session: SessionDep) -> ScoreOut:
+    """Score every variant of a finished job with the model behind the registry alias."""
+    job = await session.get(Job, job_id)
+    if job is None:
+        raise HTTPException(404, "job not found")
+    if job.status != JobStatus.succeeded:
+        raise HTTPException(409, f"job is {job.status.value}; only succeeded jobs can be scored")
+    n, version = await score_job(job_id, session)
+    return ScoreOut(job_id=job_id, scored=n, model_version=version)

api/app/routers/samples.py

@@ -1,34 +1,39 @@
 import uuid
+from datetime import UTC, datetime
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, HTTPException, status
 from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.exc import IntegrityError
 
-from app.db import get_session
-from app.models import Job, Sample
+from app.db import SessionDep
+from app.models import Job, JobStatus, Sample
 from app.schemas import JobOut, SampleCreate, SampleOut
-from app.services.events import publish_vcf_uploaded
+from app.services import events
 
 router = APIRouter()
 
 
 @router.get("", response_model=list[SampleOut])
-async def list_samples(session: AsyncSession = Depends(get_session)):
+async def list_samples(session: SessionDep):
     result = await session.scalars(select(Sample).order_by(Sample.created_at.desc()))
     return result.all()
 
 
 @router.post("", response_model=SampleOut, status_code=status.HTTP_201_CREATED)
-async def create_sample(payload: SampleCreate, session: AsyncSession = Depends(get_session)):
+async def create_sample(payload: SampleCreate, session: SessionDep):
     sample = Sample(**payload.model_dump())
     session.add(sample)
-    await session.commit()
+    try:
+        await session.commit()
+    except IntegrityError:  # samples.name is unique
+        await session.rollback()
+        raise HTTPException(409, f"a sample named {payload.name!r} already exists") from None
     await session.refresh(sample)
     return sample
 
 
 @router.get("/{sample_id}/jobs", response_model=list[JobOut])
-async def list_jobs(sample_id: uuid.UUID, session: AsyncSession = Depends(get_session)):
+async def list_jobs(sample_id: uuid.UUID, session: SessionDep):
     result = await session.scalars(
         select(Job).where(Job.sample_id == sample_id).order_by(Job.created_at.desc())
     )
@@ -36,14 +41,21 @@ async def list_jobs(sample_id: uuid.UUID, session: AsyncSession = Depends(get_se
 
 
 @router.post("/{sample_id}/annotate", response_model=JobOut, status_code=status.HTTP_202_ACCEPTED)
-async def annotate(sample_id: uuid.UUID, session: AsyncSession = Depends(get_session)):
+async def annotate(sample_id: uuid.UUID, session: SessionDep):
     sample = await session.get(Sample, sample_id)
     if sample is None:
         raise HTTPException(404, "sample not found")
-    job = Job(sample_id=sample.id)
+    # Commit `running` before launching: a local run that dies instantly is marked failed by its
+    # watcher, and a later status write here would overwrite that.
+    job = Job(sample_id=sample.id, status=JobStatus.running)
     session.add(job)
     await session.commit()
+    try:
+        job.workflow_ref = await events.launch(job.id, sample.vcf_uri, sample.assembly)
+    except events.LaunchError as e:
+        job.status = JobStatus.failed
+        job.log = str(e)
+        job.finished_at = datetime.now(UTC)
+    await session.commit()
     await session.refresh(job)
-    # Emits to Pub/Sub in GCP; runs the Nextflow pipeline inline for local dev.
-    await publish_vcf_uploaded(job_id=job.id, vcf_uri=sample.vcf_uri)
     return job

api/app/routers/variants.py

@@ -1,28 +1,37 @@
 import uuid
 
-from fastapi import APIRouter, Depends, Query
-from sqlalchemy import func, select
-from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import APIRouter, Query
+from sqlalchemy import Integer, case, cast, func, select
 from sqlalchemy.orm import selectinload
 
-from app.db import get_session
+from app.db import SessionDep
 from app.models import Prediction, Variant
-from app.schemas import VariantPage
+from app.schemas import VariantOut, VariantPage
 
 router = APIRouter()
 
+# Karyotype order (1..22, X, Y, MT) instead of text order, where "10" sorts before "2".
+_chrom = func.regexp_replace(Variant.chrom, "^chr", "", "i")
+CHROM_ORDER = case(
+    (_chrom.regexp_match("^[0-9]+$"), cast(_chrom, Integer)),
+    (_chrom == "X", 23),
+    (_chrom == "Y", 24),
+    (_chrom.in_(["M", "MT"]), 25),
+    else_=26,
+)
+
 
 @router.get("", response_model=VariantPage)
 async def list_variants(
     job_id: uuid.UUID,
+    session: SessionDep,
     gene: str | None = None,
     impact: str | None = Query(None, pattern="^(HIGH|MODERATE|LOW|MODIFIER)$"),
     max_af: float | None = Query(None, ge=0, le=1),
     min_score: float | None = Query(None, ge=0, le=1),
-    limit: int = Query(50, le=500),
-    offset: int = 0,
-    session: AsyncSession = Depends(get_session),
-):
+    limit: int = Query(50, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+) -> VariantPage:
     stmt = select(Variant).where(Variant.job_id == job_id)
     if gene:
         stmt = stmt.where(Variant.gene == gene.upper())
@@ -31,13 +40,21 @@ async def list_variants(
     if max_af is not None:
         stmt = stmt.where((Variant.gnomad_af.is_(None)) | (Variant.gnomad_af <= max_af))
     if min_score is not None:
-        stmt = stmt.join(Prediction, Prediction.variant_id == Variant.id).where(Prediction.score >= min_score)
+        stmt = stmt.join(Prediction, Prediction.variant_id == Variant.id).where(
+            Prediction.score >= min_score
+        )
 
     total = await session.scalar(select(func.count()).select_from(stmt.subquery()))
     rows = await session.scalars(
         stmt.options(selectinload(Variant.prediction))
-        .order_by(Variant.chrom, Variant.pos)
+        # id breaks ties between split multiallelics at one position, keeping pages stable.
+        .order_by(CHROM_ORDER, Variant.chrom, Variant.pos, Variant.id)
         .limit(limit)
         .offset(offset)
     )
-    return VariantPage(items=rows.all(), total=total or 0, limit=limit, offset=offset)
+    return VariantPage(
+        items=[VariantOut.model_validate(v) for v in rows],
+        total=total or 0,
+        limit=limit,
+        offset=offset,
+    )