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/tests/test_annotate.py

@@ -0,0 +1,126 @@
+import uuid
+from typing import Any
+
+import pytest
+from httpx import AsyncClient
+
+from app.config import settings
+from app.services import events
+
+
+async def new_sample(client: AsyncClient) -> str:
+    r = await client.post(
+        "/api/samples",
+        json={"name": f"s-{uuid.uuid4()}", "vcf_uri": "gs://bucket/x.vcf.gz", "assembly": "GRCh37"},
+    )
+    assert r.status_code == 201, r.text
+    return r.json()["id"]
+
+
+@pytest.mark.usefixtures("db")
+async def test_local_without_nextflow_fails_fast_with_instructions(
+    client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(settings, "pubsub_topic", None)
+    monkeypatch.setattr(events.shutil, "which", lambda _: None)
+    sample_id = await new_sample(client)
+
+    r = await client.post(f"/api/samples/{sample_id}/annotate")
+    assert r.status_code == 202
+    job = r.json()
+    assert job["status"] == "failed"
+    assert "make annotate" in job["log"]
+    assert job["finished_at"] is not None
+
+
+class FakeProcess:
+    def __init__(self, returncode: int, stderr: bytes) -> None:
+        self.returncode = returncode
+        self._stderr = stderr
+        self.pid = 4242
+
+    async def communicate(self) -> tuple[bytes, bytes]:
+        return b"", self._stderr
+
+
+@pytest.mark.usefixtures("db")
+async def test_local_run_is_watched_and_a_crash_marks_the_job_failed(
+    client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(settings, "pubsub_topic", None)
+    monkeypatch.setattr(events.shutil, "which", lambda _: "/usr/bin/nextflow")
+    launched: dict[str, Any] = {}
+
+    async def fake_exec(*cmd: str, **kw: Any) -> FakeProcess:
+        launched["cmd"], launched["env"] = cmd, kw["env"]
+        return FakeProcess(1, b"ERROR ~ VEP cache not found")
+
+    monkeypatch.setattr(events.asyncio, "create_subprocess_exec", fake_exec)
+    sample_id = await new_sample(client)
+
+    r = await client.post(f"/api/samples/{sample_id}/annotate")
+    assert r.status_code == 202
+    await events.drain()
+
+    job = (await client.get(f"/api/jobs/{r.json()['id']}")).json()
+    assert job["status"] == "failed"
+    assert "VEP cache not found" in job["log"]
+    # The DB password travels in the environment, never on the command line.
+    assert settings.database_url not in " ".join(launched["cmd"])
+    assert launched["env"]["DATABASE_URL"] == settings.database_url
+    assert launched["cmd"][launched["cmd"].index("--assembly") + 1] == "GRCh37"
+
+
+class FakeFuture:
+    def __init__(self, result: str | Exception) -> None:
+        self._result = result
+
+    def result(self, timeout: float | None = None) -> str:
+        if isinstance(self._result, Exception):
+            raise self._result
+        return self._result
+
+
+class FakePublisher:
+    def __init__(self, result: str | Exception) -> None:
+        self.result = result
+        self.published: list[tuple[str, bytes]] = []
+
+    def topic_path(self, project: str, topic: str) -> str:
+        return f"projects/{project}/topics/{topic}"
+
+    def publish(self, topic: str, data: bytes) -> FakeFuture:
+        self.published.append((topic, data))
+        return FakeFuture(self.result)
+
+
+@pytest.mark.usefixtures("db")
+async def test_pubsub_publishes_to_the_full_topic_path(
+    client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    publisher = FakePublisher("msg-123")
+    monkeypatch.setattr(settings, "pubsub_topic", "vcf-uploaded")
+    monkeypatch.setattr(settings, "gcp_project", "my-proj")
+    monkeypatch.setattr(events, "_publisher", lambda: publisher)
+    sample_id = await new_sample(client)
+
+    r = await client.post(f"/api/samples/{sample_id}/annotate")
+    job = r.json()
+    assert (job["status"], job["workflow_ref"]) == ("running", "pubsub:msg-123")
+    [(topic, data)] = publisher.published
+    assert topic == "projects/my-proj/topics/vcf-uploaded"
+    assert b'"assembly": "GRCh37"' in data and job["id"].encode() in data
+
+
+@pytest.mark.usefixtures("db")
+async def test_pubsub_failure_marks_the_job_failed(
+    client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(settings, "pubsub_topic", "vcf-uploaded")
+    monkeypatch.setattr(settings, "gcp_project", "my-proj")
+    monkeypatch.setattr(events, "_publisher", lambda: FakePublisher(RuntimeError("403 denied")))
+    sample_id = await new_sample(client)
+
+    job = (await client.post(f"/api/samples/{sample_id}/annotate")).json()
+    assert job["status"] == "failed"
+    assert "403 denied" in job["log"]