M2a: server workspace, kvitt-domain, skeleton routes, OpenAPI match, Dockerfile

Cargo workspace (kvitt-domain, kvitt-server, kvitt-import), Rust 1.99.1 pinned.
kvitt-domain passes every Rust vector and adds next_occurrence_date (D-015).
kvitt-server: config, SQLite pool (WAL, §8.9 pragmas), migration 0001 identical to
the contract schema, error type for all 25 codes, auth extractor and protocol
layer, all 33 routes (E-1/E-2 implemented, the rest 501), utoipa document equal
to contracts/openapi.yaml, seams for M3/M4/M9, serve/migrate/healthcheck.

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

server/crates/kvitt-server/src/db/mod.rs

@@ -0,0 +1,24 @@
+//! Database access: the pool (SPEC §8.9 pragmas), migrations (SPEC §14.1) and the `server_version` sequence.
+
+pub mod pool;
+pub mod sequence;
+
+pub use pool::{Db, begin_immediate, connect};
+pub use sequence::next_server_version;
+
+/// The schema version the embedded migrations produce (`meta.schema_version`, SPEC §14.1).
+pub const SCHEMA_VERSION: i64 = 1;
+
+/// The embedded migrations of `migrations/` (`0001_init.sql` is byte-identical to `contracts/schema/server-v1.sql`).
+pub static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("./migrations");
+
+/// Runs every pending migration.
+pub async fn migrate(db: &Db) -> Result<(), crate::error::AppError> {
+    MIGRATOR.run(db).await?;
+    Ok(())
+}
+
+/// `SELECT 1` (the health check of SPEC §14.3.4 E-1).
+pub async fn ping(db: &Db) -> Result<(), sqlx::Error> {
+    sqlx::query("SELECT 1").execute(db).await.map(|_| ())
+}

server/crates/kvitt-server/src/db/pool.rs

@@ -0,0 +1,45 @@
+//! The SQLite pool. Every connection sets `foreign_keys = ON`, `journal_mode = WAL`, `synchronous = NORMAL` and
+//! `busy_timeout = 5000` (SPEC §8.9).
+
+use std::path::Path;
+use std::time::Duration;
+
+use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions, SqliteSynchronous};
+use sqlx::{Sqlite, SqlitePool, Transaction};
+
+use crate::error::AppError;
+
+/// The pool type used everywhere.
+pub type Db = SqlitePool;
+
+/// `busy_timeout` (SPEC §8.9).
+pub const BUSY_TIMEOUT: Duration = Duration::from_millis(5000);
+
+/// At most this many connections; two users and one writer at a time need few.
+const MAX_CONNECTIONS: u32 = 4;
+
+/// The connect options for the database file at `path` (created if missing).
+pub fn options(path: &Path) -> SqliteConnectOptions {
+    SqliteConnectOptions::new()
+        .filename(path)
+        .create_if_missing(true)
+        .foreign_keys(true)
+        .journal_mode(SqliteJournalMode::Wal)
+        .synchronous(SqliteSynchronous::Normal)
+        .busy_timeout(BUSY_TIMEOUT)
+}
+
+/// Opens the pool for the database file at `path`. The parent directory must exist.
+pub async fn connect(path: &Path) -> Result<Db, AppError> {
+    let pool = SqlitePoolOptions::new()
+        .max_connections(MAX_CONNECTIONS)
+        .acquire_timeout(BUSY_TIMEOUT)
+        .connect_with(options(path))
+        .await?;
+    Ok(pool)
+}
+
+/// Starts a write transaction with `BEGIN IMMEDIATE` (SPEC §14.1: every write transaction does).
+pub async fn begin_immediate(db: &Db) -> Result<Transaction<'static, Sqlite>, AppError> {
+    Ok(db.begin_with("BEGIN IMMEDIATE").await?)
+}

server/crates/kvitt-server/src/db/sequence.rs

@@ -0,0 +1,24 @@
+//! The global `server_version` sequence (SPEC §14.1, §5.2).
+
+use sqlx::SqliteConnection;
+
+use crate::error::AppError;
+
+/// Takes the next `server_version`. Must run inside a `BEGIN IMMEDIATE` transaction (see
+/// [`crate::db::begin_immediate`]) so versions commit in order.
+pub async fn next_server_version(conn: &mut SqliteConnection) -> Result<i64, AppError> {
+    let value: i64 = sqlx::query_scalar(
+        "UPDATE sync_sequence SET value = value + 1 WHERE id = 1 RETURNING value",
+    )
+    .fetch_one(conn)
+    .await?;
+    Ok(value)
+}
+
+/// The current value of the sequence (the highest `server_version` handed out).
+pub async fn current_server_version(conn: &mut SqliteConnection) -> Result<i64, AppError> {
+    let value: i64 = sqlx::query_scalar("SELECT value FROM sync_sequence WHERE id = 1")
+        .fetch_one(conn)
+        .await?;
+    Ok(value)
+}