Adds tools/DESKTOP_PHASE_PLAN.md: everything a fresh session needs with no prior context — current module shape, the exact commands that must stay green, pinned versions, the invariants (tracked ObjectBox model file, the objectbox-android / objectbox-java classpath rule, kapt and Compose Desktop plugin quirks), the traps already paid for, and the M2/M3/M4/M5 milestones with exit criteria. Every claim is checked against the working tree rather than remembered: the coupling inventory (per-file android.* import counts), the 8 DataStore keys, AesGcmFieldCipher's single getOrCreateKey() call, the portability of BackupCodec/EncryptedBackupCodec, and the pinned versions (Kotlin 2.0.21, AGP 8.7.2, Compose Multiplatform 1.7.3, ObjectBox 4.0.3). Open questions are marked as such rather than guessed — the JVM EXIF decoder and OS-keyring libraries are unverified, and the AGP/KMP friction around the composeApp conversion is called out as the least-known part of M4, with a fallback shape and a time-boxed decision rule.
13 KiB
Incido desktop track — phase plan (handoff brief)
Written at Phase 1 M1b so a fresh AI session (or human) can pick this up with
no prior context. Pairs with tools/DESKTOP_FEASIBILITY.md, which holds the
Phase-0 verdicts and the run logs behind each "done" claim below.
0. Read first
- Branch
spike/desktop-feasibility, HEAD5f45b09. Commits:8b66e82Phase-0 spike + findings,9fe4763M1a data layer,5f45b09M1b desktop shell. tools/DESKTOP_FEASIBILITY.md— Phase-0 verdicts (Q1–Q6, all PASS) plus M1a/M1b status with actual run output. Read it before touching anything.- Product decision already made: each platform owns its own library; the encrypted backup file is the only bridge to the phone. ObjectBox is single-writer — never put the DB in a synced folder, and do not design sync inside Phase 1.
1. Where things stand
:core:domain kotlin("jvm") pure domain + NoteRepository interface — unchanged, both consume it
:core:data androidLibrary src/main/kotlin = PLATFORM-NEUTRAL (shared)
src/androidMain/kotlin = Android seam implementations
:core:data-jvm kotlin("jvm")+kapt compiles core/data/src/main/kotlin via srcDir + objectbox-java/linux
:desktopApp Compose Multiplatform (jvm) — window, DesktopContainer, --data-dir/--self-test/--exit-after
:composeApp androidLibrary ALL UI / ViewModels / settings / security / backup (untouched so far)
:app android host (MainActivity + manifest)
:spike:* throwaway Phase-0 probes — delete after M4
Shared sources (compiled twice, once per platform):
entity/{NoteEntity,HashtagEntity,NoteHashtagCrossRef,NoteAttachmentEntity}.kt,
repository/NoteRepositoryImpl.kt, crypto/{FieldCipher,NoteCryptoService}.kt,
ImageOrientationNormalizer.kt. Nothing in core/data/src/main/kotlin may
import android.* — worth a CI grep.
Platform seams so far: ObjectBoxStore (same FQN in both modules — Context
on Android, File on desktop) and ImageOrientationNormalizer (Android real,
JVM NoOp until M4).
Commands that must stay green:
./gradlew :core:data-jvm:smoke # M1a: shared data layer on the JVM
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-smoke --self-test --exit-after 6"
./gradlew :spike:data-jvm:run --args="/tmp/incido-spike-db" # Phase-0 probes
./gradlew assembleDebug # Android — every single step
./gradlew :desktopApp:createDistributable # packaging (M5)
Versions that matter: Compose Multiplatform 1.7.3, AndroidX Compose BOM
2024.10.01, ObjectBox 4.0.3, DataStore 1.1.1, coroutines 1.9.0,
kotlinx-serialization 1.7.3, Kotlin 2.0.21, AGP 8.7.2, Gradle 8.10.2,
app version 0.4.2.0 (code 38).
2. Invariants (do not break)
assembleDebuggreen after every commit; Android behaviour must not change silently.core/data/objectbox-models/default.jsonis tracked (M1a fixed a real bug: it was gitignored, so a fresh clone regenerated UIDs).:core:dataand:core:data-jvmeach run their own codegen against a copy, and the generator must report "ID model file unchanged". If it says otherwise, stop — you are churning UIDs.objectbox-androidandobjectbox-javaship the sameio.objectbox.*classes and may never be on one classpath → sibling modules, never a shared module depending on both.ImageOrientationNormalizerstays a requiredNoteRepositoryImplconstructor parameter, so a platform that forgets it fails the build.- kapt on JVM/KMP modules:
apply(plugin = "org.jetbrains.kotlin.kapt"), notalias(libs.plugins.kotlinKapt)("already on classpath with unknown version"). - Compose Desktop: never apply
applicationexplicitly —compose.desktop { application { } }registersrunitself.
3. Traps already paid for (don't repay)
collectAsStaterenders the empty initial value on the first frame — assert on the flow, not on frame one.Dialogisandroidx.compose.ui.window.Dialog, not a material3 export.- CompositionLocals cannot be read inside
LaunchedEffect; capture them at composition time. MyObjectBoxgenerates intoorg.incido.data.entity, notorg.incido.data.BoxStore.getName()/getStoreDirectory()do not exist in the JVM runtime.- JVM DataStore: no
preferencesDataStore(name = …)extension and no publicPreferenceSerializer. UsePreferenceDataStoreFactory.create(corruptionHandler = ReplaceFileCorruptionHandler { emptyPreferences() }, produceFile = { File }); the handler lives inandroidx.datastore.core.handlers. Same keys, same.preferences_pbformat. material-icons-extended-desktopis a ~100 MB download; a first build can time out — retry rather than debug.jpackagecannot cross-compile; packaging needs per-OS runners.- PBKDF2 200k iterations ≈ 55 ms on desktop versus ~2 s on the phone.
- The jpackage launcher prints
pure virtual method calledon stderr when the app exits viaexitProcess; harmless.
4. M2 — the backup bridge (next up; the product's reason to exist)
Already portable, verified by reading the code: BackupCodec.kt and
EncryptedBackupCodec.kt have zero Android imports. BackupNote carries
content, createdAt, updatedAt, isFavorite, color, hashtags, noteType,
isTrashed, isDraft and attachments with full bytes (Base64). importSnapshot
is additive and forces id = 0. The only Android code in the path is
BackupManager's ContentResolver/Uri IO (167 LOC).
- New
:core:backup(kotlin("jvm")): moveBackupCodec.kt,EncryptedBackupCodec.kt,EncryptedKeyCodec.kt, and add aBackupBridgethat takesInputStream/OutputStreaminstead ofUri. Keep theorg.incido.compose.data.backuppackage names at first so the Android diff is only file moves; leaveBackupManagerin:composeAppas a thinUri → streamshim. - Desktop UI: "Import from file…" / "Export…" via
JFileChooser(or ComposeFileDesigner), writing the byte-identical format the phone imports. Reuse theBackupPreviewmetadata and the passphrase prompt forINCDBK1\0envelopes. - Add import dedupe. A second import currently duplicates every note.
Key on
(createdAt, updatedAt, sha256(content))— all three survive export on both platforms. Default "skip already imported" ON with an override, and keep the logic inBackupBridgeso Android benefits too. - Round-trip test both directions: create on phone → export (plain and encrypted) → copy the file → import on desktop; then export from desktop → import on phone. Check attachments, drafts, trashed, colours, note types.
- Measure worst-case memory and record, don't redesign: the whole JSON
including Base64 attachments is materialised as a
Stringon encode and decode. Streaming is aformatVersion = 2change in Phase 2.
Exit criteria: bidirectional lossless round-trip; importing twice adds nothing;
:core:backup compiles for both platforms; Android backup screens unchanged.
5. M3 — settings + at-rest encryption on desktop
Settings. Move SettingsRepository (116 LOC, 8 keys: theme_mode,
dynamic_color, security_enabled, encryption_enabled, pin_enabled,
use_biometric, auto_lock_timeout_minutes, block_screenshots) into a
shared module behind an injected DataStore<Preferences>; Android supplies the
Context-extension store, desktop uses PreferenceDataStoreFactory. Keep
snapshot()'s runBlocking for startup only. dynamic_color, use_biometric
and block_screenshots have no desktop equivalent — hide those rows, don't
fake them. Window size/state is new desktop-only state in its own store file.
Encryption. The seam is precisely known: AesGcmFieldCipher(keyProvider)
only ever calls keyProvider.getOrCreateKey(). Replace that with a
FieldKeyProvider interface (or () -> ByteArray), move AesGcmFieldCipher
into shared code, and keep the CipherHolder / NoteCryptoService /
EncryptionVerifier wiring — DesktopContainer already mirrors
AppContainer's construction order for exactly this reason.
Key sources on desktop: recovery-key import through EncryptedKeyCodec
(already proven byte-compatible with the phone; wrong passphrase →
AEADBadTagException), or a passphrase via PBKDF2 200k. Caching the key
between launches wants an OS-keyring library — none is in the catalog and the
candidates are unverified, so verify a library exists and works before
committing to it; otherwise fall back to a 0600 key file and state that
choice plainly. BiometricPrompt and FLAG_SECURE are not portable — don't
port them.
Exit criteria: an encrypted desktop library passes EncryptionVerifier's
trial-decrypt sweep, and a phone-exported recovery key decrypts a phone backup
on desktop.
6. M4 — composeApp → Compose Multiplatform (the big one)
Coupling inventory (files importing android.*, count = import count):
VoiceNoteSection.kt 8, NoteEditorScreen.kt 7, ObjectBoxKeyProvider.kt 4,
PassphraseDialog.kt 3, VoiceRecorder.kt 3, CarnetImporter.kt 2,
BackupManager.kt 2, and one each in RelativeTime.kt, ui/theme/Theme.kt,
NoteListScreen.kt, ImageViewerScreen.kt, IncidoApplication.kt,
di/AppContainer.kt, SettingsRepository.kt, SecurityManager.kt,
PinHasher.kt. Plus :app's MainActivity + manifest (share-sheet intake,
FileProvider, camera/mic/biometric permissions).
Scale: ~7,100 LOC UI + ~2,900 LOC non-UI, 4 ViewModels, 7 screens.
LocalContext has 7 call sites, viewModel() 6, and
ViewModelProvider/AndroidViewModelFactory are Android-only.
Order of attack:
- Try the in-place conversion:
:composeApp→kotlin("multiplatform")withandroidTarget()+jvm(),commonMain= today's sources. Smallest diff. Phase 0 already proved the theme layer (Color.kt/Type.kt/NoteColors.ktverbatim;Theme.ktminus dynamic-color andBuild.VERSION) and the Material3 surface set compile on desktop from one source set. - If AGP/KMP friction wins (resources,
Rclass, preview tooling, and the AndroidX-BOM-versus-compose.*-accessor split — genuinely the least-known part of this migration), fall back to extracting the UI into a new:ui-sharedKMP module consumed by:composeAppand:desktopApp. Same work, one extra module, smaller blast radius. Decide within a day of hitting friction; don't fight both shapes at once. - Port
expect/actualone seam at a time: theme (dynamicColor,Build.VERSION); the 7LocalContextsites → a small platform-context abstraction; relative time (DateUtils→ JVM formatting); clipboard (LocalClipboardManageris deprecated →LocalClipboard+ClipEntry, the same migration on both platforms); image decode (BitmapFactory→org.jetbrains.skia.Image.makeFromEncoded(bytes).toComposeImageBitmap()); EXIF (needs a JVM decoder — verify a library exists before committing to it); file intake (camera intent + share-sheet → drag-drop and picker). - ViewModels: prefer keeping them via multiplatform lifecycle artifacts (the
catalog already carries
org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose:2.8.4from the spike) — but verify the artifact set for Compose 1.7.3 first; plaincommonMainstate holders are a legitimate fallback for 4 ViewModels. - Deferred on desktop (hide the UI, don't stub it): voice recording, camera capture, share-sheet intake, biometrics.
- Then delete
spike/, its twosettings.gradle.ktsincludes and its catalog entries — the theme copies live there, and:desktopApp's two-pane stand-in inMain.ktgets replaced by the real screens.
Exit criteria: one shared UI codebase; Android visually unchanged
(assembleDebug + on-device smoke); desktop shows the real list, editor and
settings wearing Incido's theme.
7. M5 — packaging and integration
packageDistributionForCurrentOS per OS on a GitHub Actions matrix (no
cross-compiling); icons, .desktop entry, tray + single-instance, first-run
onboarding, and the first native-Wayland + HiDPI run — everything so far
ran under XWayland at density=1.0. Record the app-image size (Phase 0 measured
168 MB).
8. Phase 2 candidates
Streaming/chunked backup format (formatVersion = 2) driven by the M2 memory
number · voice notes on desktop (audio capture + Opus encoder) · camera and
share intake · OS-keyring caching everywhere · macOS/Windows GA · multi-window
and keyboard-shortcut polish · a sync RFC only if cross-device continuity
becomes a product goal (it is explicitly not a Phase 1 goal) · perf pass on a
multi-thousand-note library.
9. Rules of engagement
One milestone at a time, committed separately, each commit message naming the
verification command that passed. Update the "Phase 1 status" section of
tools/DESKTOP_FEASIBILITY.md with actual run output — that habit is what made
this handoff trustworthy. Never widen a seam silently: if a platform needs a new
abstraction, justify it in the commit message. Flag anything unverifiable
instead of assuming it works.
First actions for a new session: git log --oneline -6 → read
tools/DESKTOP_FEASIBILITY.md → run :core:data-jvm:smoke and the
:desktopApp:run … --self-test command above to confirm the tree matches this
description → start M2 task 1 (extract :core:backup).