android: bind the core to Kotlin through uniffi (M12 step 4)

`android/ffi` is to Android what `desktop/src-tauri/src/commands/` is to the
desktop: a shim over the shared core holding no logic of its own. Third workspace
member, so the desktop lane's `cargo clippy --all-targets` compiles and lints it
— which until the Android lane lands (step 5) is the only thing that does.

Three decisions worth stating.

MIRRORED RECORDS, NOT DERIVES ON THE CORE. The core's model structs are serde
shapes contracted with the shared Vue frontend, and one of them holds a
serde_json::Value, which has no uniffi representation. Hanging uniffi derives on
them would couple two unrelated consumers to one definition. The cost of
mirroring is drift — an Android client quietly missing a field the desktop
gained — so every conversion destructures the core struct exhaustively. Add a
field to core::local::models::Note and this crate stops compiling until Android
is told what to do with it.

NoteEdit IS A LIST, NOT A STRUCT OF NULLABLE FIELDS. The store's patch format
distinguishes three states: leave alone, set, and clear to null. Kotlin cannot
express the third with a nullable field — `title = null` in a data class is
indistinguishable from `title` unset — so the editor could never clear a title.
Explicit Clear* variants say it out loud and give Kotlin a sealed class.

ASYNC IS TOKIO-BACKED, AND CANCELLATION ALREADY WORKED. Exported async methods
become Kotlin suspend functions. When a coroutine is cancelled uniffi drops the
future, and no async path in the core holds the store lock across an await —
a std MutexGuard isn't Send, so the compiler has been enforcing that all along.
A cancelled sync leaves the store consistent and simply hasn't stamped
last_sync_at, which is only written after both halves of a cycle succeed.

Also here:

  * core gains Db::conn(). Every consumer was writing
    `db.0.lock().map_err(|e| e.to_string())?` by hand, and worse, any helper
    returning the guard had to NAME rusqlite::Connection — which would have made
    rusqlite a dependency of a layer whose whole point is not knowing what the
    store is made of. Same trap as the update.rs test module in step 1.
  * The uniffi `cli` feature is gated behind our own `bindgen` feature. It drags
    in clap, askama and goblin for a three-line binary, and the desktop lane
    should not compile a code generator it never runs.
  * The bindgen binary lives in this workspace on purpose: generated bindings and
    the linked uniffi runtime are two halves of one ABI, and compiling the
    generator against the same dependency keeps them in step by construction.
    That is why ci-rust-android ships no uniffi-bindgen.

Tests cover the round trip the Android skeleton needs (open a store in a
directory that does not exist yet, write a note, read it back), that a body-only
note still has a display_title, that set and clear are genuinely different
edits, and that an unlinked app reports NotLinked rather than an error.

Known and deliberate: the workspace sets panic = "abort", so a panic crossing the
FFI aborts instead of arriving in Kotlin as an exception. Same behaviour the
desktop already has; noted in the crate header rather than silently changed.

Scribe #2733.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

android/ffi/src/lib.rs

@@ -0,0 +1,439 @@
+//! uniffi bindings: `thoughtsync-core` as seen from Kotlin.
+//!
+//! This crate is to Android what `desktop/src-tauri/src/commands/` is to the desktop
+//! — a thin shim over the shared core, holding no logic of its own. If something here
+//! starts making decisions about notes or sync, it belongs in the core where the
+//! desktop gets it too (Scribe note 2730).
+//!
+//! ## Shape
+//!
+//! One `ThoughtSync` object holds the store and the blob directory, mirroring how
+//! Tauri manages them as app state. Kotlin constructs it once, keeps it for the
+//! process lifetime, and calls methods on it.
+//!
+//! ## Async
+//!
+//! The sync engine is reqwest all the way down, so it needs a reactor. Async methods
+//! are exported with `async_runtime = "tokio"`, which uniffi turns into Kotlin
+//! `suspend` functions driven by a tokio runtime on the Rust side.
+//!
+//! Cancellation works, and not by accident: when a coroutine is cancelled uniffi
+//! drops the Rust future, and none of the core's async paths hold the store lock
+//! across an `await` — a `std::sync::MutexGuard` isn't `Send`, so the compiler has
+//! been enforcing that all along. A cancelled sync therefore leaves the store
+//! consistent; it simply hasn't stamped `last_sync_at`, which is only written after
+//! BOTH halves of a cycle succeed. The next cycle resumes from the stored cursor.
+//!
+//! ## A known consequence of the release profile
+//!
+//! The workspace sets `panic = "abort"` (Tauri's profile, for binary size). uniffi
+//! would otherwise catch a panic crossing the FFI boundary and raise it in Kotlin as
+//! an exception; with `abort` it takes the process down instead. That is the same
+//! behaviour the desktop already has, so no surface is worse off than another — but
+//! it is a deliberate cost, not an oversight. Revisit if a panic in the core ever
+//! turns out to be recoverable enough that a phone should survive it.
+
+pub mod models;
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use thoughtsync_core::local::{self, Db};
+use thoughtsync_core::sync::blobs::BlobStore;
+use thoughtsync_core::sync::{client, compat, engine, push, state};
+
+use models::{
+    patch_from, Identity, Note, NoteDraft, NoteEdit, NoteQuery, ProbeResult, RevokeOutcome,
+    SyncOutcome, SyncStatus,
+};
+
+uniffi::setup_scaffolding!();
+
+/// Everything that can go wrong, as a Kotlin exception.
+///
+/// The core reports failures as plain `String`s today, so most of them land in
+/// `Store` or `Network` by where they were raised rather than by a distinction the
+/// core actually draws. `NotLinked` is the exception and earns its own variant: it
+/// is the one failure that is a NORMAL state rather than a fault — an unlinked app is
+/// working exactly as intended — and the UI's response is to offer linking, not to
+/// show an error.
+#[derive(Debug, thiserror::Error, uniffi::Error)]
+pub enum CoreError {
+    /// No server is linked. Not a fault; the app is local-first and this is its
+    /// resting state.
+    #[error("this device isn't linked to a server")]
+    NotLinked,
+
+    /// The on-device store failed.
+    #[error("{message}")]
+    Store { message: String },
+
+    /// Talking to the server failed, or it refused.
+    #[error("{message}")]
+    Network { message: String },
+}
+
+impl CoreError {
+    fn store(e: impl std::fmt::Display) -> Self {
+        CoreError::Store {
+            message: e.to_string(),
+        }
+    }
+
+    fn network(e: impl std::fmt::Display) -> Self {
+        CoreError::Network {
+            message: e.to_string(),
+        }
+    }
+}
+
+/// The client handle: the on-device store plus the attachment directory beside it.
+///
+/// Held by Kotlin for the process lifetime. Both halves are `Send + Sync` — the store
+/// behind its mutex, the blob store being a path — which is what lets uniffi share
+/// one instance across coroutines.
+#[derive(uniffi::Object)]
+pub struct ThoughtSync {
+    db: Db,
+    blobs: BlobStore,
+}
+
+#[uniffi::export]
+impl ThoughtSync {
+    /// Open (creating on first run) the store under `data_dir`, and the attachment
+    /// directory beside it.
+    ///
+    /// `data_dir` comes from Kotlin because only Android knows where its app-private
+    /// storage is; the core must not guess at a platform path. The layout inside is
+    /// the core's business and matches the desktop's exactly — `thoughtsync.db` and
+    /// `blobs/` — so a store is readable by any client that opens it.
+    #[uniffi::constructor]
+    pub fn new(data_dir: String) -> Result<Arc<Self>, CoreError> {
+        let dir = PathBuf::from(data_dir);
+        std::fs::create_dir_all(&dir).map_err(CoreError::store)?;
+
+        let db = local::open(&dir.join("thoughtsync.db")).map_err(CoreError::store)?;
+        log::info!("local store ready — {}", local::summary(&db));
+
+        let blobs = BlobStore::new(dir.join("blobs")).map_err(CoreError::store)?;
+        Ok(Arc::new(ThoughtSync { db, blobs }))
+    }
+
+    /// A one-line count summary, for the boot log.
+    pub fn summary(&self) -> String {
+        local::summary(&self.db)
+    }
+
+    // ───────────────────────────────  notes  ───────────────────────────────
+
+    pub fn list_notes(&self, query: NoteQuery) -> Result<Vec<Note>, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        let notes = local::store::list_notes(&conn, &query.into()).map_err(CoreError::store)?;
+        Ok(notes.into_iter().map(Note::from).collect())
+    }
+
+    pub fn get_note(&self, id: String) -> Result<Note, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        local::store::get_note(&conn, &id)
+            .map(Note::from)
+            .map_err(CoreError::store)
+    }
+
+    pub fn create_note(&self, draft: NoteDraft) -> Result<Note, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        local::store::create_note(&conn, &draft.into())
+            .map(Note::from)
+            .map_err(CoreError::store)
+    }
+
+    /// Apply a batch of field edits. See `NoteEdit` for why this is a list rather
+    /// than a struct of nullable fields.
+    pub fn update_note(&self, id: String, edits: Vec<NoteEdit>) -> Result<Note, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        local::store::update_note(&conn, &id, &patch_from(edits))
+            .map(Note::from)
+            .map_err(CoreError::store)
+    }
+
+    pub fn trash_note(&self, id: String) -> Result<Note, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        local::store::trash(&conn, &id)
+            .map(Note::from)
+            .map_err(CoreError::store)
+    }
+
+    pub fn restore_note(&self, id: String) -> Result<Note, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        local::store::restore(&conn, &id)
+            .map(Note::from)
+            .map_err(CoreError::store)
+    }
+
+    // ───────────────────────────────  sync  ────────────────────────────────
+
+    pub fn sync_status(&self) -> Result<SyncStatus, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        state::status(&conn)
+            .map(SyncStatus::from)
+            .map_err(CoreError::store)
+    }
+
+    /// Whether anything is waiting to be sent — so the UI can show an honest
+    /// "unsynced changes" state without running a sync to find out.
+    pub fn has_pending(&self) -> Result<bool, CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        push::has_pending(&conn).map_err(CoreError::store)
+    }
+}
+
+/// Async methods, driven by a tokio runtime and surfaced to Kotlin as `suspend`
+/// functions. Split into its own impl block so the runtime attribute — and the fact
+/// that everything in here touches the network — is visible at a glance.
+#[uniffi::export(async_runtime = "tokio")]
+impl ThoughtSync {
+    /// Ask a server who it is, without committing to anything. Called as the user
+    /// finishes typing an address, so they see what answered before handing over
+    /// credentials.
+    pub async fn probe(&self, url: String) -> Result<ProbeResult, CoreError> {
+        client::probe(&url)
+            .await
+            .map(ProbeResult::from)
+            .map_err(CoreError::network)
+    }
+
+    /// Pair with a server using an email/password, minting a device token named for
+    /// this phone.
+    ///
+    /// The handshake runs FIRST, and an incompatible server aborts before any
+    /// credential is sent — an incompatible server is exactly the case where a later
+    /// failure would be hardest to attribute.
+    pub async fn link_with_password(
+        &self,
+        url: String,
+        email: String,
+        password: String,
+        device_name: String,
+    ) -> Result<Identity, CoreError> {
+        let probe = client::probe(&url).await.map_err(CoreError::network)?;
+        if let compat::Compatibility::Incompatible { reason, .. } = &probe.compatibility {
+            return Err(CoreError::Network {
+                message: reason.clone(),
+            });
+        }
+        let (token, identity) =
+            client::device_login(&probe.base_url, &email, &password, &device_name)
+                .await
+                .map_err(CoreError::network)?;
+        self.store_link(&probe.base_url, &token, probe.server.trash_retention_days)?;
+        Ok(identity.into())
+    }
+
+    /// Pair using a device token pasted from the web app — for anyone who would
+    /// rather not type a password into an app, or whose account is behind SSO.
+    ///
+    /// The token is verified before it is stored, so a copy/paste slip fails here
+    /// rather than at the next sync.
+    pub async fn link_with_token(&self, url: String, token: String) -> Result<Identity, CoreError> {
+        let probe = client::probe(&url).await.map_err(CoreError::network)?;
+        if let compat::Compatibility::Incompatible { reason, .. } = &probe.compatibility {
+            return Err(CoreError::Network {
+                message: reason.clone(),
+            });
+        }
+        let identity = client::fetch_identity(&probe.base_url, &token)
+            .await
+            .map_err(CoreError::network)?;
+        self.store_link(&probe.base_url, &token, probe.server.trash_retention_days)?;
+        Ok(identity.into())
+    }
+
+    /// Stop syncing, and retire this device's token on the server.
+    ///
+    /// The local half is unconditional. Someone unlinking because the phone is being
+    /// sold or handed on must not be held to it by a server that is offline or gone,
+    /// so the revoke is attempted first, its outcome returned for the UI to report
+    /// honestly, and the link cleared either way.
+    pub async fn unlink(&self) -> Result<RevokeOutcome, CoreError> {
+        // Read and release before the network call: a std MutexGuard isn't Send, so
+        // it cannot be held across an await, and holding the store through a
+        // round-trip would freeze every note operation in the UI.
+        let link = {
+            let conn = self.db.conn().map_err(CoreError::store)?;
+            let current = state::read(&conn).map_err(CoreError::store)?;
+            current.server_url.zip(current.device_token)
+        };
+        let revoked = match &link {
+            Some((base_url, token)) => client::revoke_self(base_url, token).await,
+            None => client::RevokeOutcome::Skipped,
+        };
+
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        state::clear_link(&conn).map_err(CoreError::store)?;
+        log::info!("unlinked from server (server-side token: {revoked:?})");
+        Ok(revoked.into())
+    }
+
+    /// Run one full sync: push local changes, then pull the server's.
+    ///
+    /// The only sync entry point, on purpose. Push and pull exist separately inside
+    /// the core, but offering a bare "pull" would let the UI overwrite unsent local
+    /// edits — the ordering isn't a suggestion, it's what keeps them.
+    pub async fn sync_now(&self) -> Result<SyncOutcome, CoreError> {
+        let (base_url, token) = self.credentials()?;
+        engine::run_cycle(&self.db, &self.blobs, &base_url, &token)
+            .await
+            .map(SyncOutcome::from)
+            .map_err(CoreError::network)
+    }
+}
+
+/// Helpers, deliberately NOT exported — uniffi only binds what an `#[uniffi::export]`
+/// block names, so these stay Rust-side.
+impl ThoughtSync {
+    /// The server URL + token, or the `NotLinked` state. Every networked call needs
+    /// exactly this, and none of them may hold the lock past it.
+    fn credentials(&self) -> Result<(String, String), CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        let current = state::read(&conn).map_err(CoreError::store)?;
+        match (current.server_url, current.device_token) {
+            (Some(url), Some(token)) => Ok((url, token)),
+            _ => Err(CoreError::NotLinked),
+        }
+    }
+
+    /// Persist a fresh link, adopting the server's retention window at the same time
+    /// so the Trash view stops counting down against this device's offline default
+    /// the moment it is no longer the policy in force.
+    fn store_link(
+        &self,
+        base_url: &str,
+        token: &str,
+        retention_days: Option<u32>,
+    ) -> Result<(), CoreError> {
+        let conn = self.db.conn().map_err(CoreError::store)?;
+        state::set_link(&conn, base_url, token).map_err(CoreError::store)?;
+        if let Some(days) = retention_days {
+            state::set_server_retention(&conn, days as i64).map_err(CoreError::store)?;
+        }
+        log::info!("linked to {base_url}");
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A scratch directory unique to this process and call.
+    ///
+    /// Process id + a counter rather than a uuid dependency: the FFI crate has no
+    /// business pulling one in to name a temp folder, and this is the same approach
+    /// the desktop's updater tests settled on.
+    fn scratch_dir() -> String {
+        use std::sync::atomic::{AtomicU32, Ordering};
+        static NEXT: AtomicU32 = AtomicU32::new(0);
+        let dir = std::env::temp_dir().join(format!(
+            "thoughtsync-ffi-{}-{}",
+            std::process::id(),
+            NEXT.fetch_add(1, Ordering::Relaxed)
+        ));
+        dir.to_string_lossy().into_owned()
+    }
+
+    fn draft(title: &str, body: &str) -> NoteDraft {
+        NoteDraft {
+            title: title.to_string(),
+            body: body.to_string(),
+            color: "default".to_string(),
+            kind: None,
+            items: None,
+        }
+    }
+
+    /// The round trip the Android skeleton has to make: open a store in a directory
+    /// that doesn't exist yet, write a note, read it back through the FFI types.
+    /// Proving it here means a failure on device is an Android problem, not a
+    /// binding problem.
+    #[test]
+    fn creates_a_store_and_round_trips_a_note() {
+        let dir = scratch_dir();
+        let app = ThoughtSync::new(dir.clone()).expect("a fresh data dir should open");
+
+        let created = app
+            .create_note(draft("Groceries", "milk"))
+            .expect("create should succeed");
+        assert_eq!(created.title.as_deref(), Some("Groceries"));
+        assert_eq!(created.body, "milk");
+
+        let fetched = app
+            .get_note(created.id.clone())
+            .expect("get should succeed");
+        assert_eq!(fetched.id, created.id);
+        assert_eq!(fetched.display_title, "Groceries");
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// A body-only note still has to be nameable — that is what `display_title` is
+    /// for, and the Android board relies on it exactly as the desktop does.
+    #[test]
+    fn body_only_notes_still_have_a_display_title() {
+        let dir = scratch_dir();
+        let app = ThoughtSync::new(dir.clone()).expect("a fresh data dir should open");
+
+        let created = app
+            .create_note(draft("", "just a thought"))
+            .expect("create should succeed");
+        assert_eq!(created.title, None);
+        assert_eq!(created.display_title, "just a thought");
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// Clearing a field and setting one are different edits, and the difference has
+    /// to survive the trip through the patch object.
+    #[test]
+    fn edits_can_both_set_and_clear_a_title() {
+        let dir = scratch_dir();
+        let app = ThoughtSync::new(dir.clone()).expect("a fresh data dir should open");
+        let note = app.create_note(draft("First", "body")).expect("create");
+
+        let renamed = app
+            .update_note(
+                note.id.clone(),
+                vec![NoteEdit::Title {
+                    value: "Second".to_string(),
+                }],
+            )
+            .expect("rename");
+        assert_eq!(renamed.title.as_deref(), Some("Second"));
+
+        let cleared = app
+            .update_note(note.id.clone(), vec![NoteEdit::ClearTitle])
+            .expect("clear");
+        assert_eq!(
+            cleared.title, None,
+            "ClearTitle must null the column, not set it to an empty string — the \
+             distinction is why NoteEdit is a list rather than a struct of options"
+        );
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    /// An unlinked app is a normal, working app. Asking it to sync is the one
+    /// failure that isn't a fault, and it has to arrive as `NotLinked` so the UI can
+    /// offer linking rather than show an error.
+    #[test]
+    fn syncing_unlinked_reports_not_linked() {
+        let dir = scratch_dir();
+        let app = ThoughtSync::new(dir.clone()).expect("a fresh data dir should open");
+
+        let status = app.sync_status().expect("status should read");
+        assert!(!status.linked);
+        assert_eq!(status.server_url, None);
+
+        assert!(matches!(app.credentials(), Err(CoreError::NotLinked)));
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}