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/alembic/env.py

@@ -2,8 +2,8 @@ import asyncio
 from logging.config import fileConfig
 
 from alembic import context
-from sqlalchemy.ext.asyncio import async_engine_from_config
 from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
 
 from app.config import settings
 from app.models import Base
@@ -14,10 +14,15 @@ if config.config_file_name:
     fileConfig(config.config_file_name)
 target_metadata = Base.metadata
 
+# Arbitrary constant shared by every `alembic upgrade` (one per API replica's init container).
+MIGRATION_LOCK_ID = 72150001
+
 
 def run_migrations(connection):
     context.configure(connection=connection, target_metadata=target_metadata)
     with context.begin_transaction():
+        # Held until this transaction commits; a concurrent run waits, then finds nothing to do.
+        connection.exec_driver_sql(f"SELECT pg_advisory_xact_lock({MIGRATION_LOCK_ID})")
         context.run_migrations()
 
 
@@ -27,6 +32,22 @@ async def run_async():
     )
     async with engine.connect() as conn:
         await conn.run_sync(run_migrations)
+    await engine.dispose()
 
 
-asyncio.run(run_async())
+def run_offline():
+    """`alembic upgrade head --sql`: emit the SQL instead of running it."""
+    context.configure(
+        url=settings.database_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_offline()
+else:
+    asyncio.run(run_async())

api/alembic/versions/5f2c8e1b9d04_widen_vep_text_columns.py

@@ -0,0 +1,34 @@
+"""widen VEP text columns
+
+VEP joins multiple consequences with "&" and co-located ClinVar significances with ",", which
+overflowed VARCHAR(120) and aborted the whole load transaction.
+
+Revision ID: 5f2c8e1b9d04
+Revises: a3e9ead256a5
+Create Date: 2026-09-11 18:00:00.000000
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = '5f2c8e1b9d04'
+down_revision: str | None = 'a3e9ead256a5'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+COLUMNS = ('consequence', 'clinvar_sig')
+
+
+def upgrade() -> None:
+    for column in COLUMNS:
+        op.alter_column('variants', column, type_=sa.Text(), existing_type=sa.String(length=120))
+
+
+def downgrade() -> None:
+    for column in COLUMNS:
+        op.alter_column(
+            'variants', column, type_=sa.String(length=120), existing_type=sa.Text(),
+            postgresql_using=f'left({column}, 120)',
+        )

api/alembic/versions/a3e9ead256a5_initial_schema.py

@@ -5,17 +5,17 @@ Revises:
 Create Date: 2026-09-11 15:36:04.335440
 
 """
-from typing import Sequence, Union
+from collections.abc import Sequence
 
-from alembic import op
 import sqlalchemy as sa
+from alembic import op
 from sqlalchemy.dialects import postgresql
 
 # revision identifiers, used by Alembic.
 revision: str = 'a3e9ead256a5'
-down_revision: Union[str, None] = None
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
 
 
 def upgrade() -> None:
@@ -87,4 +87,7 @@ def downgrade() -> None:
     op.drop_table('variants')
     op.drop_table('jobs')
     op.drop_table('samples')
-    # ### end Alembic commands ###
+    # ### end Alembic commands ###
+    # Autogenerate does not drop the type created by sa.Enum; without this, upgrading again
+    # fails with "type jobstatus already exists".
+    sa.Enum(name='jobstatus').drop(op.get_bind(), checkfirst=True)