Add FastAPI catalog backend (games/snapshots/diff) + tests

Modular-monolith backend over SQLAlchemy (SQLite by default, Postgres-ready
via DATABASE_URL). The full snapshot.json is stored verbatim; diffing reads it
back through the ams.diff engine, so the DB never mirrors the snapshot schema.

- ams.api.db/models/schemas/service : Game 1-N Snapshot, sha256-deduped upsert
- routes: POST/GET /games, POST/GET /snapshots (import, deduped), GET /diff
          (?old&new[&owner]) running compute_diff on stored snapshots, /health
- ams.api.importer : bulk CLI loader (python -m ams.api.importer --game ...)
- run: uvicorn ams.api.app:create_app --factory

11 tests pass (6 diff + 5 API via TestClient over the golden pair). Smoke-tested
live on uvicorn: import -> /snapshots -> /diff returns the BlooMoo deltas.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

ams/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI backend: catalog of games/engine versions + snapshot import + diff endpoint."""

ams/api/app.py

@@ -0,0 +1,30 @@
+"""FastAPI application factory.
+
+Run with uvicorn's factory mode (no import-time DB side effects):
+
+    uvicorn ams.api.app:create_app --factory --reload
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from .. import __version__
+from .db import configure, init_db
+from .routes import diff, games, snapshots
+
+
+def create_app(database_url: str | None = None) -> FastAPI:
+    configure(database_url)
+    init_db()
+
+    app = FastAPI(title="ams — engine surface catalog", version=__version__)
+    app.include_router(games.router)
+    app.include_router(snapshots.router)
+    app.include_router(diff.router)
+
+    @app.get("/health", tags=["meta"])
+    def health() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    return app

ams/api/db.py

@@ -0,0 +1,53 @@
+"""Database engine/session wiring. SQLite by default (zero setup), Postgres-ready via DATABASE_URL.
+
+The engine/session factory is process-global and (re)built by `configure()`, so tests can point it
+at a temporary database before creating the app.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+DEFAULT_URL = "sqlite:///./ams.db"
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+_engine = None
+_SessionLocal: sessionmaker | None = None
+
+
+def configure(url: str | None = None) -> None:
+    global _engine, _SessionLocal
+    url = url or os.environ.get("DATABASE_URL", DEFAULT_URL)
+    connect_args = {"check_same_thread": False} if url.startswith("sqlite") else {}
+    _engine = create_engine(url, connect_args=connect_args, future=True)
+    _SessionLocal = sessionmaker(bind=_engine, autoflush=False, expire_on_commit=False, class_=Session)
+
+
+def init_db() -> None:
+    from . import models  # noqa: F401  - register mappers before create_all
+    if _engine is None:
+        configure()
+    Base.metadata.create_all(_engine)
+
+
+def get_session() -> Session:
+    if _SessionLocal is None:
+        configure()
+    return _SessionLocal()
+
+
+def get_db() -> Iterator[Session]:
+    """FastAPI dependency yielding a request-scoped session."""
+    db = get_session()
+    try:
+        yield db
+    finally:
+        db.close()

ams/api/importer.py

@@ -0,0 +1,41 @@
+"""Bulk-import snapshot.json files straight into the DB (no HTTP server needed).
+
+    python -m ams.api.importer [--game "Reksio i UFO"] snapshots/*.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .db import get_session, init_db
+from .service import import_snapshot, looks_like_snapshot
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="ams-import", description="Import snapshots into the catalog DB.")
+    p.add_argument("files", nargs="+", help="snapshot.json files")
+    p.add_argument("--game", help="link all imported snapshots to this game (created if missing)")
+    args = p.parse_args(argv)
+
+    init_db()
+    db = get_session()
+    try:
+        for path in args.files:
+            with open(path, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            if not looks_like_snapshot(data):
+                print("[!] skip (not a snapshot): {0}".format(path))
+                continue
+            snap = import_snapshot(db, data, args.game)
+            print("[+] #{0} {1} [{2}/{3}] types={4} methods={5} events={6} fields={7}".format(
+                snap.id, snap.binary_name, snap.engine, snap.compiler,
+                snap.n_types, snap.n_methods, snap.n_events, snap.n_fields))
+    finally:
+        db.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ams/api/models.py

@@ -0,0 +1,51 @@
+"""ORM models: a Game has many Snapshots. The full snapshot.json is stored verbatim in `data`
+(JSON / JSONB); axis counts are denormalised for cheap listing. Diffing reads `data` back through
+the existing ams.diff engine, so the DB never has to mirror the snapshot schema."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import ForeignKey, JSON, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .db import Base
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Game(Base):
+    __tablename__ = "games"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String, unique=True, index=True)
+    notes: Mapped[str | None] = mapped_column(String, default=None)
+
+    snapshots: Mapped[list["Snapshot"]] = relationship(
+        back_populates="game", cascade="all, delete-orphan")
+
+
+class Snapshot(Base):
+    __tablename__ = "snapshots"
+    __table_args__ = (UniqueConstraint("sha256", name="uq_snapshot_sha256"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    game_id: Mapped[int | None] = mapped_column(ForeignKey("games.id"), default=None, index=True)
+
+    binary_name: Mapped[str] = mapped_column(String)
+    sha256: Mapped[str] = mapped_column(String, index=True)
+    engine: Mapped[str | None] = mapped_column(String, default=None)
+    compiler: Mapped[str | None] = mapped_column(String, default=None)
+    schema_version: Mapped[int | None] = mapped_column(default=None)
+
+    n_types: Mapped[int] = mapped_column(default=0)
+    n_methods: Mapped[int] = mapped_column(default=0)
+    n_events: Mapped[int] = mapped_column(default=0)
+    n_fields: Mapped[int] = mapped_column(default=0)
+
+    created_at: Mapped[datetime] = mapped_column(default=_utcnow)
+    data: Mapped[dict] = mapped_column(JSON)
+
+    game: Mapped["Game | None"] = relationship(back_populates="snapshots")

ams/api/routes/diff.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+from ...diff import compute_diff, filter_by_owner
+from ...snapshot import Snapshot
+from .. import models
+from ..db import get_db
+
+router = APIRouter(tags=["diff"])
+
+
+@router.get("/diff")
+def get_diff(
+    old: int = Query(..., description="older snapshot id"),
+    new: int = Query(..., description="newer snapshot id"),
+    owner: str | None = Query(None, description="restrict to one class, e.g. CMC_Animo"),
+    db: Session = Depends(get_db),
+) -> dict[str, Any]:
+    a = db.get(models.Snapshot, old)
+    b = db.get(models.Snapshot, new)
+    if a is None or b is None:
+        raise HTTPException(404, "snapshot not found")
+    diff = compute_diff(Snapshot(a.data), Snapshot(b.data))
+    if owner:
+        diff = filter_by_owner(diff, owner)
+    return diff

ams/api/routes/games.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from .. import models, schemas
+from ..db import get_db
+
+router = APIRouter(prefix="/games", tags=["games"])
+
+
+@router.post("", response_model=schemas.GameOut, status_code=201)
+def create_game(body: schemas.GameCreate, db: Session = Depends(get_db)) -> models.Game:
+    game = models.Game(name=body.name, notes=body.notes)
+    db.add(game)
+    try:
+        db.commit()
+    except IntegrityError:
+        db.rollback()
+        raise HTTPException(409, "game with that name already exists")
+    db.refresh(game)
+    return game
+
+
+@router.get("", response_model=list[schemas.GameOut])
+def list_games(db: Session = Depends(get_db)) -> list[models.Game]:
+    return list(db.scalars(select(models.Game).order_by(models.Game.name)))
+
+
+@router.get("/{game_id}", response_model=schemas.GameDetail)
+def get_game(game_id: int, db: Session = Depends(get_db)) -> models.Game:
+    game = db.get(models.Game, game_id)
+    if game is None:
+        raise HTTPException(404, "game not found")
+    return game

ams/api/routes/snapshots.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .. import models, schemas, service
+from ..db import get_db
+
+router = APIRouter(prefix="/snapshots", tags=["snapshots"])
+
+
+@router.post("", response_model=schemas.SnapshotOut, status_code=201)
+def create_snapshot(
+    data: dict[str, Any] = Body(..., description="a full engine-surface snapshot.json"),
+    game: str | None = Query(None, description="link to / create this game by name"),
+    db: Session = Depends(get_db),
+) -> models.Snapshot:
+    if not service.looks_like_snapshot(data):
+        raise HTTPException(422, "body is not an engine-surface snapshot (missing binary/types)")
+    return service.import_snapshot(db, data, game)
+
+
+@router.get("", response_model=list[schemas.SnapshotOut])
+def list_snapshots(
+    game_id: int | None = Query(None), db: Session = Depends(get_db)
+) -> list[models.Snapshot]:
+    q = select(models.Snapshot)
+    if game_id is not None:
+        q = q.where(models.Snapshot.game_id == game_id)
+    return list(db.scalars(q.order_by(models.Snapshot.id)))
+
+
+@router.get("/{snapshot_id}", response_model=schemas.SnapshotDetail)
+def get_snapshot(snapshot_id: int, db: Session = Depends(get_db)) -> models.Snapshot:
+    snap = db.get(models.Snapshot, snapshot_id)
+    if snap is None:
+        raise HTTPException(404, "snapshot not found")
+    return snap

ams/api/schemas.py

@@ -0,0 +1,43 @@
+"""Pydantic request/response models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class GameCreate(BaseModel):
+    name: str
+    notes: str | None = None
+
+
+class GameOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    name: str
+    notes: str | None = None
+
+
+class SnapshotOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    game_id: int | None
+    binary_name: str
+    sha256: str
+    engine: str | None
+    compiler: str | None
+    schema_version: int | None
+    n_types: int
+    n_methods: int
+    n_events: int
+    n_fields: int
+    created_at: datetime
+
+
+class SnapshotDetail(SnapshotOut):
+    data: dict
+
+
+class GameDetail(GameOut):
+    snapshots: list[SnapshotOut] = []

ams/api/service.py

@@ -0,0 +1,60 @@
+"""Business logic shared by the HTTP routes and the bulk importer."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from . import models
+
+
+def _content_sha(data: dict[str, Any]) -> str:
+    return hashlib.sha256(json.dumps(data, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def looks_like_snapshot(data: Any) -> bool:
+    return isinstance(data, dict) and "binary" in data and "types" in data
+
+
+def _apply_metadata(snap: models.Snapshot, data: dict[str, Any]) -> None:
+    binary = data.get("binary", {})
+    snap.binary_name = binary.get("name", "?")
+    snap.engine = binary.get("engine")
+    snap.compiler = binary.get("compiler")
+    snap.schema_version = data.get("schema_version")
+    snap.n_types = len(data.get("types", []))
+    snap.n_methods = len(data.get("methods", []))
+    snap.n_events = len(data.get("events", []))
+    snap.n_fields = len(data.get("fields", []))
+    snap.data = data
+
+
+def _get_or_create_game(db: Session, name: str) -> models.Game:
+    game = db.scalar(select(models.Game).where(models.Game.name == name))
+    if game is None:
+        game = models.Game(name=name)
+        db.add(game)
+        db.flush()
+    return game
+
+
+def import_snapshot(db: Session, data: dict[str, Any], game_name: str | None = None) -> models.Snapshot:
+    """Upsert a snapshot, deduped by the binary's sha256 (falling back to a content hash)."""
+    sha = data.get("binary", {}).get("sha256") or _content_sha(data)
+    snap = db.scalar(select(models.Snapshot).where(models.Snapshot.sha256 == sha))
+    game = _get_or_create_game(db, game_name) if game_name else None
+
+    if snap is None:
+        snap = models.Snapshot(sha256=sha)
+        db.add(snap)
+    _apply_metadata(snap, data)
+    if game is not None:
+        snap.game_id = game.id
+
+    db.commit()
+    db.refresh(snap)
+    return snap