M4: sync pull and push (E-31, E-32), audit writer and diff, FCM sender, push batching, scheduler, pruning, rotate-epoch

- src/sync/: pull with UNION ALL paging and cursor_ahead; push processing of SPEC §14.4.4 steps 1 to 12 in one
  BEGIN IMMEDIATE with a savepoint per mutation, LWW with delete-wins, tombstones, clock_skew, replay from
  sync_mutations, sync_batch for more than 3 notifiable changes; 90-day pruning.
- src/audit/: SqlAuditWriter and the §14.4.7 diff (now the default in AppState::new).
- src/push/: bounded PushHub (100, drop oldest), FCM HTTP v1 client with service-account JWT (RS256, jsonwebtoken
  on aws-lc-rs) and token cache, sender with 1/5/25 s retries and token clearing; disabled without credentials.
- src/tasks/: start installs push and spawns the 06:00 generation (and at start) and 04:00 pruning loops on the
  injectable clock.
- cli: rotate-epoch; serve uses into_make_service_with_connect_info; stale doc comments updated; /i/ empty code
  gets the HTML 404.
- tests: sync_api, push_fcm (local stub of Google's endpoints), scheduler_daily; skeleton routes test now asserts
  no route is 501.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TQd3pEP9UeN2uifbHknQ7B

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

@@ -1,15 +1,18 @@
-//! `kvitt-server` subcommands (SPEC §10.4, exhaustive): `serve`, `migrate` and `healthcheck` are implemented here
-//! by M2a; `bootstrap` and `pair-device` belong to M3, `rotate-epoch` to M4, and until then print
-//! `not implemented in M2a` and exit 2.
+//! `kvitt-server` subcommands (SPEC §10.4, exhaustive), all implemented: `serve`, `migrate` and `healthcheck` here,
+//! `bootstrap` and `pair-device` (M3) and `rotate-epoch` (M4) in their own files.
 
 pub mod bootstrap;
 pub mod healthcheck;
 pub mod pair_device;
 pub mod rotate_epoch;
 
+use std::net::SocketAddr;
 use std::process::ExitCode;
 use std::time::Duration;
 
+use axum::Router;
+use axum::extract::connect_info::IntoMakeServiceWithConnectInfo;
+
 use clap::{Parser, Subcommand};
 use tokio::net::TcpListener;
 use tokio::sync::Notify;
@@ -21,9 +24,6 @@ use crate::{AppState, db, router, tasks};
 /// How long `serve` lets in-flight requests finish after SIGTERM (SPEC §10.4).
 pub const SHUTDOWN_DRAIN: Duration = Duration::from_secs(10);
 
-/// Exit code of a subcommand that is not implemented yet.
-pub const EXIT_NOT_IMPLEMENTED: u8 = 2;
-
 #[derive(Debug, Parser)]
 #[command(
     name = "kvitt-server",
@@ -75,12 +75,6 @@ pub async fn run(command: Command, config: Config) -> ExitCode {
     }
 }
 
-/// Prints the M2a placeholder message and returns exit code 2.
-pub fn not_implemented(command: &str) -> ExitCode {
-    eprintln!("{command}: not implemented in M2a");
-    ExitCode::from(EXIT_NOT_IMPLEMENTED)
-}
-
 /// Opens (creating if needed) the data directory and the database, and runs the migrations.
 pub async fn open_database(config: &Config) -> Result<db::Db, AppError> {
     std::fs::create_dir_all(&config.data_dir).map_err(|e| {
@@ -100,15 +94,9 @@ async fn migrate(config: Config) -> Result<(), AppError> {
 
 async fn serve(config: Config) -> Result<(), AppError> {
     let pool = open_database(&config).await?;
-    if !config.fcm_credentials.exists() {
-        tracing::warn!(
-            path = %config.fcm_credentials.display(),
-            "FCM credentials file missing: push is disabled"
-        );
-    }
     let bind = config.bind;
-    let state = AppState::new(config, pool.clone());
-    tasks::start(state.clone()).await?;
+    // `tasks::start` installs the push queue (or logs once that push is disabled) and starts the scheduler.
+    let state = tasks::start(AppState::new(config, pool.clone())).await?;
 
     let listener = TcpListener::bind(bind)
         .await
@@ -120,7 +108,7 @@ async fn serve(config: Config) -> Result<(), AppError> {
         let shutdown = shutdown.clone();
         async move { shutdown.notified().await }
     };
-    let server = axum::serve(listener, router::router(state)).with_graceful_shutdown(graceful);
+    let server = axum::serve(listener, make_service(state)).with_graceful_shutdown(graceful);
     let mut server = tokio::spawn(async move { server.await });
 
     tokio::select! {
@@ -142,6 +130,12 @@ async fn serve(config: Config) -> Result<(), AppError> {
     }
 }
 
+/// The router as served: with the TCP peer address in `ConnectInfo<SocketAddr>`, which the rate limiter keys
+/// unauthenticated requests by (SPEC §8.6).
+pub fn make_service(state: AppState) -> IntoMakeServiceWithConnectInfo<Router, SocketAddr> {
+    router::router(state).into_make_service_with_connect_info::<SocketAddr>()
+}
+
 async fn finish(
     result: Result<std::io::Result<()>, tokio::task::JoinError>,
     pool: &db::Db,

server/crates/kvitt-server/src/cli/rotate_epoch.rs

@@ -1,11 +1,44 @@
-//! `kvitt-server rotate-epoch` (SPEC §10.9). M4 owns this file; until then it prints `not implemented in M2a` and
-//! exits 2.
+//! `kvitt-server rotate-epoch` (SPEC §10.4, §10.9 restore step 5, §14.4.8): sets `meta.sync_epoch` to a new
+//! `lower(hex(randomblob(16)))`, so phones detect the restore and re-push what they hold. Exit 0; 1 on a database
+//! error.
 
 use std::process::ExitCode;
 
 use crate::config::Config;
+use crate::db::{self, Db};
+use crate::error::AppError;
+
+/// Replaces the epoch and returns the new value.
+pub async fn rotate(db: &Db) -> Result<String, AppError> {
+    let mut tx = db::begin_immediate(db).await?;
+    let epoch: String = sqlx::query_scalar(
+        "UPDATE meta SET value = lower(hex(randomblob(16))) WHERE key = 'sync_epoch' RETURNING value",
+    )
+    .fetch_optional(&mut *tx)
+    .await?
+    .ok_or_else(|| AppError::internal("meta.sync_epoch is missing"))?;
+    tx.commit().await?;
+    Ok(epoch)
+}
 
 pub async fn run(config: &Config) -> ExitCode {
-    let _ = config;
-    super::not_implemented("rotate-epoch")
+    let result = async {
+        let pool = super::open_database(config).await?;
+        let epoch = rotate(&pool).await;
+        pool.close().await;
+        epoch
+    }
+    .await;
+    match result {
+        Ok(epoch) => {
+            tracing::info!("sync_epoch rotated");
+            println!("sync_epoch rotated: {epoch}");
+            ExitCode::SUCCESS
+        }
+        Err(e) => {
+            tracing::error!(error_code = e.code.as_str(), detail = %e.message, "rotate-epoch failed");
+            eprintln!("rotate-epoch: {e}");
+            ExitCode::FAILURE
+        }
+    }
 }