margin/simplify/.research/rust-core.md

Rust core plumbing (research, 2026-09-06)

What the four apps have in common below the features: library.rs, lib.rs, dto.rs, SQLite, logging, settings, filesystem helpers, error shapes, updates, async, and dependency versions. Everything here was read off disk. Google/OAuth, typesetting and spellcheck are other notes.

Sizes for reference: 2,190 Rust lines in Margin, 8,490 in Calendar, 5,365 in Docs, 45,884 in Mail. Mail's number includes 8,045 lines of tests.rs files; Calendar's includes 802.

The verdict first

Area	Apps that have it	How close, really	One crate?
lib.rs builder and menu	4	~120 lines per app verbatim identical	Yes, the biggest single win
Logging	1 (Mail)	three apps have nothing	Yes, and it fixes a real gap
Updates	1.5 (Margin, plus packaged_by in two)	Margin's updates.rs is already app-agnostic	Yes, cheap
SQLite	3	~100 duplicated lines out of ~8,500	Yes, small, for the two bugs it fixes
library.rs	4	5 identical lines, then four different files	No
dto.rs conventions	3	one convention, rigidly held, nothing to extract	No
Settings	1 (Mail)	the other three keep prefs in localStorage	No
Filesystem helpers	2.5	three genuinely different algorithms	No
Error types	4	already uniform, nothing to fix	No
Async	3	one shared idea (Sink), 12 lines	No

Three defects found on the way, listed at the end of the lib.rs section.

library.rs

Line counts: Margin 146, Calendar 9, Docs 9, Mail 54.

Calendar's and Docs' are byte-identical files (diff returns nothing): nine lines containing only app_data_dir. Mail's is that same function plus atomic_write and a test. Margin's is a different file that happens to share the name: BookSummary (margin library.rs:8-14), the four book commands, and app_data_dir at library.rs:49-53.

The genuinely shared part is five lines, identical in all four (margin library.rs:49-53, calendar library.rs:5-9, docs library.rs:5-9, mail library.rs:8-12):

pub fn app_data_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
    let dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
    Ok(dir)
}

It should move into whatever shared crate exists for other reasons. It is not a reason to create one. Everything else in Margin's library.rs is the book library and belongs to Margin.

lib.rs: the Tauri builder

Line counts: Margin 256, Calendar 354, Docs 365, Mail 475. 1,450 lines total.

Measured overlap: 73 distinct non-comment lines appear verbatim in all four files. Counting occurrences, that is 114 lines of Margin's lib.rs, 123 of Calendar's, 120 of Docs' and 124 of Mail's, which is 48%, 44%, 41% and 32% of each file's code lines. Excluding trivial brace lines it is still 73 to 81 lines each. Roughly 480 lines of duplicated boilerplate across the suite.

The identical blocks, in order:

main.rs. Six lines, identical in all four but for the crate name. Nothing to do here; Tauri requires it.

The builder prologue. Margin lib.rs:149-162, Calendar 250-263, Docs 250-266, Mail 253-268. generate_context! first, #[cfg_attr(mobile, allow(unused_mut))], then:

#[cfg(desktop)]
{
    builder = builder.plugin(tauri_plugin_process::init());
    if context.config().plugins.0.contains_key("updater") {
        builder = builder.plugin(tauri_plugin_updater::Builder::new().build());
    }
}

Verbatim four times. Two copies say so in a comment: Calendar lib.rs:248-249 and Mail lib.rs:251-252 both read "Ported from margin's lib.rs".

The menu scaffold. Menu::default(handle), the submenus collect, the find_submenu closure, the match find_submenu("File") with its prepend_items / SubmenuBuilder arms, the Edit and Help appends, the macOS app-submenu insert block and the non-macOS fallback. Margin lib.rs:46-60 and 62-93, Calendar 50-64 and 66-95, Docs 100-114 and 115-146, Mail 84-98 and 100-135. Pairwise diffs of the whole build_menu: Calendar against Mail is 49 differing lines out of 118 and 123. Margin against Calendar is 89. Docs is the outlier at 149 to 159, because it rebuilds the macOS app submenu from scratch rather than patching Tauri's default (the reasoning is at Docs lib.rs:164-176 and is good).

The menu event. Identical line in all four: app.emit("menu-action", event.id().0.as_str()).ok(); (Margin lib.rs:192, Calendar 308, Docs 318, Mail 341), inside an identical matches! guard over a list of ids.

show_main_window. Calendar lib.rs:227-234 and Mail lib.rs:184-191 have identical bodies.

packaged_by. Calendar lib.rs:239-244 and Mail lib.rs:196-201, identical including the doc comment, differing only in the env var name (MARGIN_CALENDAR_PACKAGED_BY vs MARGIN_MAIL_PACKAGED_BY).

build.rs. Margin's and Docs' are the three-line default. Calendar's and Mail's are byte-identical 29-line files with the same embed_credentials and the same comment.

Where they genuinely must differ

The menu contents (ids, labels, accelerators, which submenus get extra rows), the invoke_handler list, the manage calls and the body of setup, deep link registration (Calendar and Mail only), and the iOS viewport fix and Android consent-tab watcher (Calendar only, see below).

Three defects found while reading

Margin Mail cannot compile for mobile. #[cfg_attr(mobile, tauri::mobile_entry_point)] sits at lib.rs:203, directly above attach_account, not above pub fn run() at lib.rs:250. Separately, setup calls listen_for_redirects (lib.rs:307), stop_uikit_shrinking_the_viewport (lib.rs:310) and watch_for_the_consent_tab_closing (lib.rs:314) under cfg(mobile), cfg(target_os = "ios") and cfg(target_os = "android"). None of the three is defined anywhere in the crate; grep returns only the call sites. All three exist in Calendar (lib.rs:149-172, 185-199, 213-220) and were evidently meant to be ported with the rest. The iOS and Android dependency blocks are in Cargo.toml waiting for them.

Four apps, three close behaviours. Calendar and Mail prevent the close and hide the window (Calendar lib.rs:313-321, Mail 346-354), then restore it on RunEvent::Reopen. Margin lets the window be destroyed but calls api.prevent_exit() and rebuilds the window from config on Reopen (lib.rs:231-238, 241-256). Docs calls .run(context) directly at lib.rs:363, so it has no RunEvent closure and no CloseRequested handler anywhere in the crate: closing the window quits the app. For a suite that shares a design language this is the kind of thing that should have one answer, and a shared shell crate would force one.

Capability drift. Margin puts core:window:allow-destroy and allow-start-dragging in default.json, which applies on every platform; the other three put them in desktop.json. Docs additionally carries core:window:allow-toggle-maximize. Nothing is broken, but four hand-edited copies of the same two files will keep drifting.

What the crate would be

A margin-shell crate holding: the plugin prologue as fn desktop_plugins(builder, context), the menu scaffold as fn standard_menu(handle, spec: &MenuSpec) -> tauri::Result<Menu<R>> where MenuSpec names the File rows, the extra Edit and View rows and the Help rows, the menu-action forwarding, show_main_window, hide_on_close, packaged_by(env_var) and app_data_dir. Around 250 lines, deleting roughly 400 across the four apps, and it makes the close behaviour and the capability set one decision instead of four.

dto.rs and the IPC boundary

	Lines	Structs	Enums	rename_all = "camelCase"
Margin	no dto.rs	types inline in their modules	0	8 across the crate
Calendar	181	10	1	11
Docs	243	15	0	15
Mail	927	40	11	43

The three dto.rs files open with the same two-line header ("The IPC contract. Every type here has a matching declaration in src/ipc.ts. Both sides are frozen once written: implementation modules add bodies, not fields."). Margin has no dto.rs, but follows the same convention where it matters: BookSummary at library.rs:8-14 is #[derive(serde::Serialize)] with rename_all = "camelCase".

The convention is one convention and it is held rigidly: #[derive(Debug, Clone, Serialize, Deserialize)] plus #[serde(rename_all = "camelCase")] on every type; #[serde(default)] on patch and optional fields (9 in Margin, 55 in Calendar, 7 in Docs, 148 in Mail); Option<T> for absent rather than a sentinel; i64 epoch milliseconds for time; a string field with the legal values in a doc comment (/// idle | syncing | error) instead of an enum. #[serde(rename = ...)] appears exactly once in the whole suite (Calendar dto.rs:36, for self), and skip_serializing_if twice, both in Mail. Mail is the only app with real enums, all rename_all = "kebab-case".

Is there a macro or crate here? No. #[serde(rename_all = "camelCase")] is already the shortest spelling of the thing; a derive macro would save one line per struct and put a proc-macro crate in four build graphs. The duplication that costs something is on the other side: 65 structs across the three dto.rs files each have a hand-written TypeScript interface in src/ipc.ts with nothing checking that they agree, and the first 41 lines of Calendar's and Docs' ipc.ts are byte identical. That is a codegen question (ts-rs, tauri-specta) for the frontend note.

The one type that genuinely repeats is the progress status: Calendar SyncStatus (dto.rs:147-167), Docs IndexStatus (dto.rs:87-109), Mail SyncStatus (dto.rs:861-893). All three are phase: String with the states in a doc comment, error: Option<String>, message: Option<String>, progress counters, and a hand-written Default or idle() constructor. The common core is six lines. Similarly AuthEvent: Calendar dto.rs:172-181 and Mail dto.rs:898-910, where Mail's is Calendar's plus granted_scopes and missing_required. Worth putting in a shared crate that exists anyway. Not worth one on its own.

SQLite

Present in three. Calendar store/ is 1,351 lines (about 960 non-test). Docs index.rs is 1,771 lines of which only about 420 touch SQLite at all, the rest being fzy scoring, snippet windowing and markdown parsing. Mail is 6,222 non-test lines across db.rs, mirror/ and state/, plus two .sql schema files. Call it 8,500 lines of database code.

Genuinely duplicated: 80 to 120 lines. These are not three copies of one layer, they are three different databases in one house style. The specific overlaps:

• app_data_dir, as above.
• version(), byte-identical between Calendar store/schema.rs:130-136 and Mail mirror/schema.rs:127-135, and again modulo the state. prefix at Mail state/schema.rs:56-64.
• The meta upsert. Calendar store/write.rs:214-228, Mail mirror/write.rs:57-73, Docs' remember at index.rs:891-899. Four copies of one INSERT ... ON CONFLICT DO UPDATE.
• now_ms. Docs index.rs:905-910 and Mail mirror/write.rs:42-46 are identical; Calendar's store/write.rs:87-89 is the chrono equivalent.
• The placeholder helper: Docs placeholders (index.rs:901-903) and Mail holes (mirror/read.rs:898-900), same one-liner, different name and separator.
• The FTS5 tokenizer string unicode61 remove_diacritics 2, in Docs index.rs:119-122 and Mail mirror/mirror.sql:169-178.
• .map_err(|e| e.to_string()), 309 occurrences (Calendar 59, Docs 36, Mail 214). Not a function waiting to be extracted; a From impl waiting to be written.
• The migrate skeleton: read version, refuse if newer, return if equal, run the ladder, stamp.

Where they legitimately differ. Three connection ownership models, each correct for its app: Mutex<Connection> (Calendar store/mod.rs:17), Mutex<Option<Connection>> behind a writer thread and a OnceLock<Sender> (Docs index.rs:143-151), and Mutex<HashMap<String, Connection>> with one pair of ATTACHed files per account (Mail db.rs:31-38). Pragmas are the same three ideas delivered three ways: pragma_update calls (Calendar store/mod.rs:17-34), an execute_batch literal (Docs index.rs:208-221), an execute_batch with a formatted ATTACH (Mail db.rs:129-151). Version storage differs on a real decision: PRAGMA user_version in Docs (index.rs:229-248) against a meta row in Calendar and Mail. FTS5 is in two apps and everything above the tokenizer line differs: Docs ranks with bm25 and highlight (index.rs:1184-1188), Mail uses the index purely as a membership subquery (mirror/read.rs:234) under a query language with from: and has: operators (mirror/fts.rs:100-127).

Two defects. Mail has no transactions outside its two migrations: grepping the whole crate for unchecked_transaction, BEGIN IMMEDIATE, .transaction() and SAVEPOINT returns exactly three hits, two execute_batch("BEGIN;") in mirror/schema.rs:37 and state/schema.rs:33, and one SAVEPOINT in state/journal.rs:278. So apply_and_queue (mirror/mod.rs:167-205), which does N flag updates plus N outbox inserts, runs unwrapped. Separately, Calendar's migration ladder is if found < 1 { V1 } else if found < 2 { V2 } (store/schema.rs:115-120), an else if, which will not compose when V3 lands. Mail's sequential ifs (mirror/schema.rs:39-44) will.

Neither app uses prepare_cached anywhere. Mail's still_bodiless (mirror/read.rs:949-969) prepares inside a loop.

The crate. margin-sqlite, roughly 250 lines: open(path, pragmas), Tx and Savepoint RAII guards (Calendar's store/write.rs:62-85 is the right shape already and takes &Connection rather than &mut, which is exactly what Mail needs from inside Db::with), migrate(conn, &[&str], version_store, noun), meta_get/meta_set generic over the table name so Mail's state.meta works, holes(n), now_ms, and a From<rusqlite::Error> error type. Net deletion is maybe 150 lines. Do it for the two defects it fixes and for the busy timeout, which only Mail sets today (db.rs:129-151, 5s), not for the volume. Every schema, every read and every write stays per app.

Logging

Only Margin Mail logs. src-tauri/src/log.rs is 137 lines, 94 of them not tests.

The surface: CAP_BYTES = 256 * 1024 (log.rs:23), init(&Path) (:34) which sets a OnceLock<PathBuf> to dir.join("margin-mail.log"), path() (:38), note(who, line) (:45) which always eprintln!s and then, only if PATH is set, timestamps and appends under a process-wide Mutex<()>, trim (:55) which flattens newlines and cuts at 2,000 characters, and append (:65) which is not rotation but a keep-the-newest-half rewrite when the cap is exceeded. #[tauri::command] log_note (:90) is registered at lib.rs:361, and the webview is the heavier producer: src/ipc.ts:752-758 logs every rejected invoke, and src/main.tsx:21,24 catch window.onerror and unhandledrejection.

The design decision worth keeping: log.rs is told its directory rather than reaching for an AppHandle. db.rs:46 calls log::init(&data) from inside Db::open, so the engine still works under cargo test. Before that call, lines go to stderr, which under a Finder launch is nowhere.

The other three:

	eprintln!	println!	log crate	tracing	plugin-log	log file
Margin	0	0	no	no	no	none
Calendar	0	0	no	no	no	none
Docs	6	0	no	no	no	none
Mail	1 (inside log.rs)	3 (dead)	own module	no	no	margin-mail.log

Docs' six are lib.rs:270, lib.rs:278, index.rs:437, index.rs:596, watch.rs:210 and writingtools.rs:136, all going to /dev/null under a Finder launch. Margin and Calendar have nothing at all: when a Drive backup or a calendar sync fails, the string reaches the frontend and then the process forgets it.

This is the clearest shared-crate win in the whole audit. margin-log is init, note, path and the log_note command, about 100 lines, dependent only on chrono and std, with one thing to parameterise (the filename, derivable from the bundle identifier). Three apps gain the ability to answer "why did it fail" after the process has exited, which is the standing rule for this suite. Two things to fix while lifting: note discards the result of append, so a failed write is invisible, and it does blocking file I/O under a std::sync::Mutex from async contexts (sync/engine.rs:327, :363, :448, sync/hydrate.rs:276, google/gmail.rs:106). Bounded and infrequent, so not urgent, but do not copy it into three more apps unexamined. The frontend half (the .catch in ipc.ts plus the two handlers in main.tsx) is 15 more lines per app and catches most real failures.

Settings and persisted state

Only Mail has a settings layer in Rust. settings.rs is 479 lines (343 non-test): settings.json in the app data dir, a 25-field Settings struct at dto.rs:768, a hand-written defaults() (settings.rs:32), a genuine recursive JSON merge for settings_set(patch) (merge_into, settings.rs:234), an atomic write through library::atomic_write (settings.rs:221), and a deliberate refusal to reset on a malformed file (settings.rs:210, tested at :430). Mail also owns accounts.json, keymap.json and imap-trust.json in the same directory.

Where everyone else keeps configuration:

• Margin: localStorage, 16 keys. Per-project settings live inside the .margin book file, merged against TypeScript defaults at src/model/book.ts:212. Rust holds no settings; its one JSON file is backup.json (gdrive.rs:139), Drive bookkeeping.
• Calendar: localStorage, five keys. Its entire Settings screen edits one preference, week start day. No config file on disk in any format, and no atomic_write in the crate.
• Docs: localStorage, seventeen keys behind zustand stores. Rust owns roots.json (fs.rs:60,778), which is workspace state rather than settings, and the index database.

Not a crate. Lifting settings.rs means inventing a settings backend for three apps that do not have one and whose preferences currently live in the webview. That is a feature, not a refactor, and the 25-field struct cannot move regardless. If it is ever wanted, the reusable core is: read JSON, deep-merge a patch, atomic write, error rather than reset on a parse failure. About 60 lines.

One latent bug to fix in place: Settings has exactly one #[serde(default)] field (dto.rs:805, notifications). Every other field is required, so the next field added without one will fail to parse every existing install's settings.json and settings_get will error out. There is a regression test for the one field that has a default (settings.rs:389), but the pattern was not generalised.

Filesystem helpers

Four atomic_writes, three genuinely different algorithms, all of them write, fsync, rename and none of them fsyncing the parent directory, so on all four a crash can still lose the rename.

• Docs fs.rs:311-347 with helpers at :222-288. A per-path Arc<Mutex<()>> lock map so a debounced autosave cannot race Cmd+S; a copy of the original into the temp before truncating so macOS ACLs, Finder tags and the exec bit survive; a hidden collision-retried temp name (.{name}.{pid}-{seq}-{nanos:x}.tmp, 64 tries); four watch::note_self_write calls; and remove_file on both error paths.
• Margin project.rs:13-30. Adds .bak rotation. When backup is false it remove_files the target before the rename (project.rs:26), opening a window where the file does not exist. Leaves the temp behind on failure.
• Mail library.rs:19-33. Adds create_dir_all. Uses with_extension, which for a path with no extension produces a doubled dot. Leaves the temp behind on failure. No lock.
• write_private in Calendar google/secrets.rs:243-261 and Mail google/secrets.rs:245-263 is a fourth variant and the only byte-identical pair, 0o600. That one belongs to the Google note.

Do not share the general one. Sharing it either drops Docs' watcher integration and lock map or drags the file watcher into the shared crate. Each divergence is justified in a comment in its own file. Do fix the two real bugs listed above, in place.

Not everything even goes through it: Mail writes the mbox export straight to fs::File::create (exports.rs:99-104) and the attachment cache with plain fs::write (attachments.rs:279, :482).

Trash: Docs only. trash = "5", used at fs.rs:712-730 with DeleteMethod::NsFileManager on macOS chosen deliberately over the crate default to avoid an Apple event entitlement, and used again as the safe half of a cross-volume move (fs.rs:676-677). Margin's delete_book (library.rs:143) is a bare remove_file.

Path validation: Docs is the only app with a real gate. resolve rejects non-absolute paths and any Component::ParentDir, canonicalises the deepest existing ancestor and re-appends the tail; resolve_in_roots requires starts_with an open root; checked (fs.rs:212-214) is what every path-taking command calls, reads included. check_name (fs.rs:149-158) rejects empty, ., .., separators and NUL. Mail sidesteps the problem by never letting the frontend name a write target; its only sanitiser is free_path (attachments.rs:363-389), which maps separators to - and trims dots. Margin has none: project.rs:32-46 exposes read_file, write_file and write_bytes as commands taking an arbitrary absolute path from the webview with no checking at all. Its one validated path is the book id whitelist at library.rs:61-66. That is a finding for Margin, not an argument for a crate.

File watching: Docs only. notify 8, notify-debouncer-full 0.7 and ignore 0.4 appear in no other app. 300ms debounce (watch.rs:33), NoCache chosen over the file-id cache because on macOS the inode cache folds the two halves of a rename together (watch.rs:222-229), self-write suppression on a 2s window (watch.rs:55,70-71), one emit per event (watch.rs:147), and kind derived from a fresh symlink_metadata rather than trusted from FSEvents flags (watch.rs:402-429). One app watches files. There is nothing to share.

Error types

Already uniform, and there is nothing to fix. Every one of the 165 #[tauri::command]s across the four apps returns either a bare value or Result<T, String>, with zero exceptions (Margin 24, Calendar 13, Docs 38, Mail 90). Counts of -> Result<T, String> anywhere: 52, 94, 91, 485.

thiserror and anyhow are dependencies of none of the four. Every Display is hand-written. The custom enums are internal and never cross to the frontend: Calendar ApiError (google/api.rs:132, four variants), Mail ApiError (google/api.rs:184, seven), Mail ProviderError (provider/mod.rs:26), Mail Refused (imap/tls.rs:95). There are five impl From in the whole suite. The two ApiErrors look like the same type and are not: Calendar needs SyncTokenExpired and PreconditionFailed, Mail needs Unauthorized, InsufficientScope and Dropped, and even the shared four-line From<reqwest::Error> differs deliberately, with a comment in Mail explaining why Calendar's simpler classification would be wrong for a mail client waking from sleep.

A shared Result/Error shape would be churn. The one useful piece is the From<rusqlite::Error> that kills 309 .map_err(|e| e.to_string()), and that lives in the SQLite crate.

Updates

Margin's updates.rs is 90 lines and does three things: derive a channel from the merged plugin config plus a Mac App Store receipt probe, query Apple's lookup endpoint for a newer App Store version, and open macappstore://. It is almost entirely app-agnostic already. channel() reads handle.config().plugins.0 for "updater" and "appstore"; mas_receipt() walks current_exe() up two levels to _MASReceipt/receipt; appstore_latest() reads config().identifier and package_info().version. No product name, no bundle id, no endpoint is hardcoded. It would drop into any of the other three unchanged.

	Margin	Calendar	Docs	Mail
tauri-plugin-updater	yes	yes	yes	yes
Conditional registration	lib.rs:159	lib.rs:260	lib.rs:263	lib.rs:265
Channel concept	yes	no	no	no
App Store vs direct split	yes	no	no	no
packaged_by	no	lib.rs:239	no	lib.rs:196
Release pubkey	real	real	placeholder	placeholder

Docs and Mail both ship a literal REPLACE_WITH_... string as the updater pubkey in tauri.release.conf.json, and neither release workflow substitutes it (the workflows only set TAURI_SIGNING_PRIVATE_KEY). Neither app can ship a verifiable direct-download update today. All four release configs are 14 lines with an identical structure differing only in pubkey and repo slug.

Share it. updates.rs plus packaged_by is one 110-line module with one thing to parameterise, and even the env var name could be derived from the bundle identifier. Second cheapest win after logging.

Async

Margin has no tokio dependency at all. Docs declares tokio = { features = ["sync", "time"] } (Cargo.toml:34) and never uses it: grep for tokio:: in its src-tauri/src returns nothing. That line is a copy from a sibling and should go.

tauri::async_runtime::spawn is the house style in the three apps that spawn (Margin gdrive.rs:765, Calendar sync.rs:205 and five more, Mail badge.rs:88 and five more). Raw tokio::spawn appears only in Mail's IMAP autodiscovery fan-out (imap/discover.rs:69-72, :382-383, :419), which is safe because Tauri's runtime is tokio but leaves those tasks untracked by Tauri's shutdown. Docs uses no async runtime for background work at all: three std::thread::spawns (watch.rs:260, watch.rs:287, index.rs:203) and #[tauri::command(async)] on sync functions.

The two poll loops are the closest pair of non-trivial code in the suite and are still not the same. Calendar sync.rs:204-215 and Mail sync/mod.rs:374-386 share the skeleton, share FIRST_PASS_SECS = 2, and share a focused() helper that is character-for-character identical (Calendar sync.rs:218-223, Mail sync/mod.rs:388-392). They differ on the wake: Calendar awaits a tokio::sync::Notify with a timeout, so kick (sync.rs:238-242) can pull the next tick forward, and it listens on store-changed to catch a freshly connected account (sync.rs:197-202). Mail's is a bare sleep, and kick (sync/mod.rs:456-464) spawns a separate sync_now instead, relying on the running: AtomicBool re-entrancy guard (sync/engine.rs:74-84) to keep the two from overlapping. Both work. They are two answers, not one shared answer.

Nobody uses tokio::time::interval, CancellationToken, watch::channel, parking_lot or RwLock. Cancellation, where it exists, is a re-entrancy guard (Mail's AtomicBool, Calendar's tokio::sync::Mutex<()> with try_lock), a dropped stream (Mail attachments.rs:140-160), or a Weak (Docs watch.rs:200,262). The three debounce helpers (Docs watch.rs:376-387 and index.rs:451-464, Mail badge.rs:79-92) are three different things; there is nothing to lift.

Events: all four use the Emitter trait and app.emit(name, payload) broadcast. Nothing anywhere uses emit_to or emit_filter, which is fine while every app is single-window. Names are kebab-case and overlap heavily: menu-action in all four, store-changed, sync-progress and auth in Calendar and Mail, pdf-warnings in Margin and Docs. Docs is the only app defining them as constants on both sides (index.rs:42, watch.rs:26, src/ipc.ts:43-52).

The lock rule is applied consistently and is worth writing down as a guideline rather than a crate: std::sync::Mutex for SQLite behind a with(|conn| ...) closure, tokio::sync::Mutex for anything held across an .await. Stated explicitly at Calendar sync.rs:112-115 and Mail db.rs:12-15.

The Sink trait (Calendar sync.rs:68-78, Mail sync/mod.rs:230-266) is the one abstraction arrived at twice independently: status and changed methods, an AppSink { app: AppHandle } implementation, existing so a sync pass can be tested against a recorder. It is 12 lines and it belongs with the sync engine, which is not shared. No async crate.

Dependency drift

Agreed in all four and not worth a table row: tauri and tauri-build at 2, serde and serde_json at 1, base64 0.22, tauri-plugin-opener 2, objc2 0.6 and objc2-foundation 0.3. Also agreed where shared: sha2 0.10, rand 0.8, url 2, chrono 0.4, tempfile 3 (dev), harper-core =2.5.0, typst and typst-pdf 0.14.2, typst-as-lib 0.15.5, objc2-app-kit 0.3, objc2-ui-kit 0.3, block2 0.6, tauri-plugin-dialog and tauri-plugin-deep-link at 2.

Where they disagree, blank meaning the app does not have it:

Crate	Margin	Calendar	Docs	Mail
rusqlite		0.37	0.40	0.40
reqwest	0.12	0.12		0.13
chacha20poly1305		0.10		0.11
fontdb	0.23		0.23	0.24
tokio	none	1 (sync, time)	1 (unused)	1 (sync, time, net, io-util, rt)
tauri-plugin-process	2 (ungated)	2 (gated)	2 (gated)	2 (gated)
tauri-plugin-updater	2 (ungated)	2 (gated)	2 (gated)	2 (gated)

Resolved in the lockfiles: tauri is 2.11.3 in Margin and 2.11.5 in the other three; serde 1.0.228 vs 1.0.229; tokio 1.52.3 vs 1.53.1; libsqlite3-sys 0.35.0 (Calendar) vs 0.38.2 (Docs, Mail); wry 0.55.1 and objc2 0.6.4 everywhere. reqwest 0.12 and 0.13 are both in Margin's and Calendar's graphs already.

Four real drifts to close: rusqlite 0.37 in Calendar against 0.40 elsewhere, reqwest 0.12 against 0.13 in Mail, chacha20poly1305 0.10 against 0.11, fontdb 0.23 against 0.24. The last three matter because Calendar and Mail share a sealed-token format and Margin and Docs share a Typst pipeline; a version split inside a pair that is meant to be the same code is how the two copies quietly stop being the same code.

What to build, and the one obstacle

Build three crates:

1. margin-log, about 100 lines. init(dir, filename), note(who, line), path(), the log_note command. Highest value: three apps currently cannot answer why anything failed.
2. margin-shell, about 250 lines. The builder prologue, the menu scaffold behind a MenuSpec, the menu-action forwarding, show_main_window, hide_on_close, app_data_dir, packaged_by, and Margin's updates.rs unchanged. Deletes roughly 400 lines and forces one answer to the close-button question that currently has three.
3. margin-sqlite, about 250 lines. open with pragmas including a busy timeout, Tx and Savepoint, migrate, meta_get/meta_set, holes, now_ms, an error type. Deletes maybe 150 lines and fixes Mail's missing transactions and Calendar's non-composable ladder.

Do not build a settings crate, an error crate, a filesystem crate, an async crate or a DTO macro. For each of those, either only one app has the thing, or all four already do the same trivial thing in the same trivial way, or the apparent duplication dissolves on reading the divergences, every one of which is justified in a comment where it sits.

The obstacle is mechanical and is the same one repo-facts.md describes for margin-shared. These are four separate git repositories with no cargo workspace and no path dependencies between them, and Margin Mail has no remote at all and one scaffold commit under 123 uncommitted files. A Cargo path dependency walking out of one checkout into a sibling would fail on a fresh clone and in CI exactly as the npm one already does. Decide where the shared crates live, a fifth repository consumed by git tag or a monorepo, before writing a line of them.