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/audit/diff.rs

@@ -0,0 +1,229 @@
+//! The audit field diff of SPEC §14.4.7, computed from the wire objects (`Expense`, `Settlement` as JSON) before and
+//! after a change.
+
+use serde_json::Value;
+
+use crate::wire::{AuditAction, AuditChange, EntityType};
+
+/// Diff fields of an expense, in the order of the SPEC §14.4.7 table.
+pub const EXPENSE_FIELDS: [&str; 9] = [
+    "account_id",
+    "category_id",
+    "payer_user_id",
+    "amount_ore",
+    "description",
+    "notes",
+    "expense_date",
+    "split_mode",
+    "splits",
+];
+
+/// Diff fields of a settlement, in the order of the SPEC §14.4.7 table.
+pub const SETTLEMENT_FIELDS: [&str; 6] = [
+    "from_user_id",
+    "to_user_id",
+    "amount_ore",
+    "settlement_date",
+    "note",
+    "allocations",
+];
+
+/// The field of a `delete` change (both entity types).
+pub const DELETED_AT: &str = "deleted_at";
+
+/// The diff fields of `entity_type`, in table order.
+pub fn fields(entity_type: EntityType) -> &'static [&'static str] {
+    match entity_type {
+        EntityType::Expense => &EXPENSE_FIELDS,
+        EntityType::Settlement => &SETTLEMENT_FIELDS,
+    }
+}
+
+/// The value of `field` in `object` in its diff form: arrays `splits` sorted by `user_id` and `allocations` by
+/// `account_id` (SPEC §14.4.7); a missing field is `null`.
+pub fn value_of(object: &Value, field: &str) -> Value {
+    let value = object.get(field).cloned().unwrap_or(Value::Null);
+    let sort_key = match field {
+        "splits" => "user_id",
+        "allocations" => "account_id",
+        _ => return value,
+    };
+    match value {
+        Value::Array(mut items) => {
+            items.sort_by(|a, b| {
+                let ka = a.get(sort_key).and_then(Value::as_str).unwrap_or("");
+                let kb = b.get(sort_key).and_then(Value::as_str).unwrap_or("");
+                ka.cmp(kb)
+            });
+            Value::Array(items)
+        }
+        other => other,
+    }
+}
+
+/// The `changes` of one audit entry (SPEC §14.4.7):
+///
+/// * `create`: one change per diff field, `old` null, in table order (`before` is ignored);
+/// * `update`: one change per diff field whose JSON value differs, in table order;
+/// * `delete`: exactly the `deleted_at` change.
+pub fn changes(
+    entity_type: EntityType,
+    action: AuditAction,
+    before: Option<&Value>,
+    after: &Value,
+) -> Vec<AuditChange> {
+    let null = Value::Null;
+    match action {
+        AuditAction::Create => fields(entity_type)
+            .iter()
+            .map(|field| AuditChange {
+                field: (*field).to_owned(),
+                old: Value::Null,
+                new: value_of(after, field),
+            })
+            .collect(),
+        AuditAction::Update => {
+            let before = before.unwrap_or(&null);
+            fields(entity_type)
+                .iter()
+                .filter_map(|field| {
+                    let old = value_of(before, field);
+                    let new = value_of(after, field);
+                    (old != new).then(|| AuditChange {
+                        field: (*field).to_owned(),
+                        old,
+                        new,
+                    })
+                })
+                .collect()
+        }
+        AuditAction::Delete => vec![AuditChange {
+            field: DELETED_AT.to_owned(),
+            old: before.map_or(Value::Null, |b| value_of(b, DELETED_AT)),
+            new: value_of(after, DELETED_AT),
+        }],
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    fn expense() -> Value {
+        json!({
+            "id": "e", "account_id": "a1", "category_id": "c1", "amount_ore": 41200, "description": "ICA Maxi",
+            "notes": "", "expense_date": "2026-10-16", "payer_user_id": "u1", "split_mode": "default",
+            "splits": [
+                {"user_id": "u2", "share_ore": 20600, "share_bp": 5000},
+                {"user_id": "u1", "share_ore": 20600, "share_bp": 5000}
+            ],
+            "recurring_template_id": null, "recurring_period": null, "created_by_user_id": "u1",
+            "updated_by_user_id": "u1", "created_at": "t", "updated_at": "t", "deleted_at": null, "server_version": 9
+        })
+    }
+
+    fn settlement() -> Value {
+        json!({
+            "id": "s", "from_user_id": "u2", "to_user_id": "u1", "amount_ore": 50000, "settlement_date": "2026-10-16",
+            "note": "", "allocations": [
+                {"account_id": "a2", "amount_ore": 20000}, {"account_id": "a1", "amount_ore": 30000}
+            ],
+            "created_by_user_id": "u2", "updated_by_user_id": "u2", "created_at": "t", "updated_at": "t",
+            "deleted_at": null, "server_version": 9
+        })
+    }
+
+    #[test]
+    fn create_lists_every_field_in_table_order_with_old_null() {
+        let c = changes(EntityType::Expense, AuditAction::Create, None, &expense());
+        let names: Vec<_> = c.iter().map(|c| c.field.as_str()).collect();
+        assert_eq!(names, EXPENSE_FIELDS);
+        assert!(c.iter().all(|c| c.old.is_null()));
+        assert_eq!(c[3].new, json!(41200));
+        // Splits sorted by user_id.
+        assert_eq!(c[8].new[0]["user_id"], "u1");
+        let c = changes(
+            EntityType::Settlement,
+            AuditAction::Create,
+            None,
+            &settlement(),
+        );
+        let names: Vec<_> = c.iter().map(|c| c.field.as_str()).collect();
+        assert_eq!(names, SETTLEMENT_FIELDS);
+        assert_eq!(c[5].new[0]["account_id"], "a1");
+        assert!(!names.contains(&"deleted_at"));
+    }
+
+    #[test]
+    fn update_lists_only_differing_fields_in_table_order() {
+        let before = expense();
+        let mut after = expense();
+        after["notes"] = json!("x");
+        after["amount_ore"] = json!(41300);
+        after["splits"][0]["share_ore"] = json!(20700);
+        // Not diff fields: ignored.
+        after["updated_at"] = json!("t2");
+        after["server_version"] = json!(10);
+        let c = changes(
+            EntityType::Expense,
+            AuditAction::Update,
+            Some(&before),
+            &after,
+        );
+        let names: Vec<_> = c.iter().map(|c| c.field.as_str()).collect();
+        assert_eq!(names, ["amount_ore", "notes", "splits"]);
+        assert_eq!(c[0].old, json!(41200));
+        assert_eq!(c[0].new, json!(41300));
+        assert_eq!(c[1].old, json!(""));
+    }
+
+    #[test]
+    fn update_ignores_array_order_and_detects_nothing_for_equal_rows() {
+        let before = settlement();
+        let mut after = settlement();
+        after["allocations"] = json!([
+            {"account_id": "a1", "amount_ore": 30000}, {"account_id": "a2", "amount_ore": 20000}
+        ]);
+        assert!(
+            changes(
+                EntityType::Settlement,
+                AuditAction::Update,
+                Some(&before),
+                &after
+            )
+            .is_empty()
+        );
+        after["note"] = json!("Swish");
+        let c = changes(
+            EntityType::Settlement,
+            AuditAction::Update,
+            Some(&before),
+            &after,
+        );
+        assert_eq!(c.len(), 1);
+        assert_eq!(
+            (c[0].field.as_str(), &c[0].old, &c[0].new),
+            ("note", &json!(""), &json!("Swish"))
+        );
+    }
+
+    #[test]
+    fn delete_is_exactly_the_deleted_at_change() {
+        let before = expense();
+        let mut after = expense();
+        after["deleted_at"] = json!("2026-10-17T08:00:00.000Z");
+        after["notes"] = json!("ignored");
+        let c = changes(
+            EntityType::Expense,
+            AuditAction::Delete,
+            Some(&before),
+            &after,
+        );
+        assert_eq!(
+            serde_json::to_value(&c).unwrap(),
+            json!([{"field": "deleted_at", "old": null, "new": "2026-10-17T08:00:00.000Z"}])
+        );
+    }
+}

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

@@ -1,5 +1,5 @@
-//! The audit log seam (SPEC §14.4.7). M2a defines the trait and a no-op; M4 owns `src/audit/**` and replaces the
-//! implementation with one that computes the field diff and inserts the `audit_log` row.
+//! The audit log (SPEC §14.4.7, FR-12). M2a defined the trait; M4 owns `src/audit/**` and implements it with
+//! [`SqlAuditWriter`], which computes the field diff ([`diff::changes`]) and inserts the `audit_log` row.
 //!
 //! Callers (sync push in M4, recurring generation in E-28 and the scheduler, the importer in M9) call
 //! [`AuditWriter::write`] inside their own `BEGIN IMMEDIATE` transaction, passing the wire object before and after
@@ -12,9 +12,12 @@ use std::pin::Pin;
 use sqlx::SqliteConnection;
 use uuid::Uuid;
 
+use crate::db;
 use crate::error::AppError;
 use crate::wire::{AuditAction, AuditSource, EntityType};
 
+pub mod diff;
+
 /// A boxed, sendable future (object-safe async trait methods).
 pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
 
@@ -48,16 +51,45 @@ pub trait AuditWriter: Send + Sync + 'static {
     ) -> BoxFuture<'a, Result<Uuid, AppError>>;
 }
 
-/// Writes nothing. Used until M4 lands its writer.
+/// The real writer: derives `changes` per SPEC §14.4.7 and appends one `audit_log` row (never updated or deleted,
+/// AC-12.1) with a UUIDv7 id and a `server_version` taken on the caller's transaction.
 #[derive(Debug, Clone, Copy, Default)]
-pub struct NoopAuditWriter;
+pub struct SqlAuditWriter;
 
-impl AuditWriter for NoopAuditWriter {
+impl AuditWriter for SqlAuditWriter {
     fn write<'a>(
         &'a self,
-        _conn: &'a mut SqliteConnection,
-        _event: AuditEvent,
+        conn: &'a mut SqliteConnection,
+        event: AuditEvent,
     ) -> BoxFuture<'a, Result<Uuid, AppError>> {
-        Box::pin(async { Ok(Uuid::now_v7()) })
+        Box::pin(async move {
+            let changes = diff::changes(
+                event.entity_type,
+                event.action,
+                event.before.as_ref(),
+                &event.after,
+            );
+            let changes_json = serde_json::to_string(&changes).map_err(AppError::internal)?;
+            let id = Uuid::now_v7();
+            let version = db::next_server_version(&mut *conn).await?;
+            sqlx::query(
+                "INSERT INTO audit_log (id, entity_type, entity_id, action, source, actor_user_id, actor_device_id, \
+                 client_at, server_at, changes, server_version) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            )
+            .bind(id.to_string())
+            .bind(event.entity_type.as_str())
+            .bind(event.entity_id.to_string())
+            .bind(event.action.as_str())
+            .bind(event.source.as_str())
+            .bind(event.actor_user_id.to_string())
+            .bind(event.actor_device_id.map(|d| d.to_string()))
+            .bind(&event.client_at)
+            .bind(&event.server_at)
+            .bind(changes_json)
+            .bind(version)
+            .execute(&mut *conn)
+            .await?;
+            Ok(id)
+        })
     }
 }