Seeds 3000 notes against the real streaming UI (279 ms total, ~0.09 ms/note), fresh observeAll 70 ms, favorite toggle 1 ms, reopen first non-empty emission 89 ms; only 4 RENDER lines during the seed (size-keyed emission coalesces). The multi-thousand-note unknown from the Phase-0 recommendation closes: desktop perf is a non-event at 3000 notes. §7 marked DONE + handoff "first actions" rewritten for post-M5 sessions (four pending-MANUAL checks listed). Verify: :desktopApp:run --args="--data-dir /tmp/incido-perf --perf-smoke --exit-after 150" (PERF seed 3000/279ms, rc 0) then --perf-verify same dir (reopen 89 ms, rc 0); :desktopApp:createDistributable + image --self-test rc=0; --keys-smoke KEYS ALL-OK; :core:data-jvm:smoke M1a PASS; assembleDebug SUCCESSFUL.
1018 lines
55 KiB
Markdown
1018 lines
55 KiB
Markdown
# Desktop feasibility spike (Phase 0) — findings
|
||
|
||
> The forward plan — remaining Phase-1 milestones, invariants and traps —
|
||
> lives in `tools/DESKTOP_PHASE_PLAN.md`, written as a cold-start handoff.
|
||
|
||
Branch `spike/desktop-feasibility`. Throwaway code lives in `spike/` and is
|
||
**not** wired into the Android build: `settings.gradle.kts` only gained two
|
||
`include()` lines and `gradle/libs.versions.toml` four entries. Nothing under
|
||
`app/`, `core/` or `composeApp/` was touched.
|
||
|
||
Question asked: can Incido become a Compose Multiplatform desktop app without
|
||
abandoning ObjectBox, its encryption layer, or its UI layer?
|
||
|
||
## Verdict
|
||
|
||
| # | Question | Verdict | Evidence |
|
||
|---|---|---|---|
|
||
| Q1 | Compose Multiplatform window builds + renders on KDE/Wayland | **PASS** | `:spike:compose-jvm:run` opened a window; `WINDOW-READY density=1.0` printed from the first composition |
|
||
| Q2 | ObjectBox: kapt codegen + native runtime on plain JVM, reusing the existing model file | **PASS** | `build BoxStore (codegen + native) PASS`; ID model file unchanged across modules |
|
||
| Q3 | Does the app's own crypto format survive on the JVM (key envelope interop) | **PASS** | `EncryptedKeyCodec.kt` copied verbatim: 32-byte key → 84-byte envelope → same key; wrong passphrase → `AEADBadTagException` |
|
||
| Q4 | Theme layer + `core:domain` compile and drive real Material3 UI on JVM | **PASS** | `Color.kt`/`Type.kt`/`NoteColors.kt` copied verbatim; only 2 Android-only lines removed from `Theme.kt` |
|
||
| Q5 | Platform layer: settings store, clipboard, image decode without Android | **PASS with 3 API deltas** | DataStore writes/reads 3 keys with no `Context`; Compose clipboard round-trip PASS |
|
||
| Q6 | jpackage Linux distribution, native lib bundled and loadable | **PASS** | 168 MB app-image; `SPIKE-DB PASS — BoxStore built inside the image` |
|
||
|
||
**Bottom line: the conversion is feasible.** No blocker found. Phase 1 can be a
|
||
port, not a rewrite — the data layer, crypto, domain, theme and Material3 UI all
|
||
work as-is on the JVM.
|
||
|
||
## Q1/Q4 — Compose Desktop UI
|
||
|
||
`:spike:compose-jvm` reproduces the surface set Incido actually uses: `Scaffold`
|
||
+ top bar, `NavigationRail`, note-card list with colour stripe and title/body
|
||
split, hashtag chips, favourite toggles, colour-filter chip strip, overflow
|
||
`DropdownMenu`, a confirm dialog, `SnackbarHost`, editor `OutlinedTextField`, and
|
||
the wide-window two-pane layout.
|
||
|
||
Run log (KDE Plasma, Wayland session, XWayland AWT):
|
||
|
||
```
|
||
AWT toolkit : sun.awt.X11.XToolkit
|
||
Skiko : Library resolved
|
||
WINDOW-READY density=1.0 notes=6 — first composition succeeded
|
||
clipboard : PASS (read back: incido-spike-clipboard)
|
||
```
|
||
|
||
No GL workarounds were needed (`-Dskiko.renderingApi=software` unused). Density
|
||
was 1.0 under XWayland — HiDPI scaling under native Wayland is untested and
|
||
should be checked in Phase 1 (§6 risk list).
|
||
|
||
Three real API deltas found while porting the UI, all mechanical:
|
||
|
||
1. `Dialog` is `androidx.compose.ui.window.Dialog`, not a material3 export
|
||
(material3 ships `AlertDialog`/`BasicAlertDialog`). Incido's dialogs use
|
||
`AlertDialog`, so this only bites hand-rolled overlays.
|
||
2. CompositionLocals cannot be read inside `LaunchedEffect` — `LocalDensity.current`
|
||
had to be captured at composition time. Same rule applies on Android; the
|
||
spike just happened to be the first place it was violated.
|
||
3. `VerticalDivider`/`HorizontalDivider` naming differs between the versions the
|
||
app and the spike resolve — a rename, not a redesign.
|
||
|
||
## Q2 — ObjectBox on the JVM
|
||
|
||
`spike/data-jvm` applies `org.jetbrains.kotlin.kapt`, points
|
||
`objectbox-plugin.json`-equivalent config at a **copy** of the app's
|
||
`objectbox-models/default.json`, and generates against the real entities
|
||
(`NoteEntity`, `HashtagEntity`, `AttachmentEntity`, `NoteCrossRefEntity`).
|
||
|
||
```
|
||
build BoxStore (codegen + native) PASS — native lib loaded
|
||
put NoteEntity (plaintext row) PASS — id=1
|
||
put NoteEntity (cipherVersion=1) PASS — id=2
|
||
blob round-trip integrity PASS — 4096 bytes identical
|
||
close + reopen same directory PASS — notes=2 hashtags=1
|
||
```
|
||
|
||
The generator printed **"ID model file unchanged"**, so generating in a second
|
||
module does not churn UIDs — the property that makes a shared-source Phase 1
|
||
(option B, sibling modules over a common `kotlin()` source set) safe. A desktop
|
||
build can open the same `.objectbox` file the Android app writes.
|
||
|
||
Gotchas recorded for Phase 1:
|
||
|
||
* Apply kapt with `apply(plugin = "org.jetbrains.kotlin.kapt")`; the
|
||
`alias(libs.plugins.kotlinKapt)` form fails with "already on classpath with
|
||
unknown version".
|
||
* kapt logs `W: Kapt currently doesn't support language version 2.0+` and falls
|
||
back to 1.9 for the generated code. Harmless, but expect it.
|
||
* The generator emits `MyObjectBox` into the **entity package**
|
||
(`org.incido.data.entity`), not `org.incido.data`.
|
||
* Resolved versions: `objectbox-java/kotlin/linux 4.0.3`, runtime reports
|
||
`4.0.2-2024-10-15`. `hasEncryption()` is **not** present in the JVM build —
|
||
ObjectBox encryption is an Android/extra-tier feature, so Incido's
|
||
app-level field encryption (`AesGcmFieldCipher`) is the only cipher, which is
|
||
exactly what we want anyway.
|
||
|
||
## Q3/Q5b — Crypto portability
|
||
|
||
`EncryptedKeyCodec.kt` was copied in **unmodified** (it imports only
|
||
`javax.crypto` + `java.security`) and exercised end-to-end:
|
||
|
||
```
|
||
recovery-key envelope (real codec) PASS — envelope=84 bytes, 32-byte key round-tripped
|
||
wrong passphrase is rejected PASS — rejected with AEADBadTagException
|
||
AES-256-GCM field cipher layout PASS — 4KB ok; 500 encrypts in 81 ms
|
||
PBKDF2 200k cost (per unlock) PASS — samples=[53, 56] ms per unlock on this CPU
|
||
```
|
||
|
||
Consequences for Phase 1:
|
||
|
||
* A recovery key exported from the phone opens encrypted notes on desktop with
|
||
**zero format changes** — same magic header, same PBKDF2 parameters, same
|
||
envelope. Backup/restore interop between platforms comes for free.
|
||
* `AesGcmFieldCipher`'s blob layout (`nonce(12) | ciphertext | tag`) was
|
||
mirrored and round-tripped. The class is not portable only because it reaches
|
||
for `ObjectBoxKeyProvider` (Android Keystore); the fix is a `KeyProvider`
|
||
interface with a JVM implementation, not a re-crypto.
|
||
* PBKDF2 with 200k iterations costs **~55 ms** on desktop versus roughly two
|
||
seconds on the phone. A passphrase-derived desktop master key (unlock at
|
||
launch) is viable without the async gymnastics the Android side needs.
|
||
* Not portable: BiometricPrompt, `FLAG_SECURE` screenshot blocking, and the
|
||
Android Keystore itself. Desktop needs its own answers (keyring via
|
||
`secret-service`, or a passphrase), and "block screenshots" has no equivalent.
|
||
|
||
## Q5a — Settings without a Context
|
||
|
||
```
|
||
data dir — would be /home/nick/.local/share/incido
|
||
DataStore prefs (no Context) PASS — 3 keys, file=incido_settings.preferences_pb (73 bytes)
|
||
```
|
||
|
||
API delta worth knowing before Phase 1: the multiplatform artifact
|
||
`androidx.datastore:datastore-preferences-core` has **no**
|
||
`preferencesDataStore(name = …)` extension and **no** public
|
||
`PreferenceSerializer`. The JVM entry point is
|
||
`PreferenceDataStoreFactory.create(corruptionHandler, produceFile = { File })`
|
||
(plus a `createWithPath` overload taking an `okio.Path`), and the corruption
|
||
handler lives in `androidx.datastore.core.handlers`. Keys and the
|
||
`.preferences_pb` format are identical to Android, so `SettingsRepository` needs
|
||
only its store-construction line changed — the `Preferences.Key` definitions and
|
||
all read/write logic port verbatim.
|
||
|
||
Clipboard: Compose's `LocalClipboardManager` round-tripped (write → read →
|
||
compare) on desktop, so "copy to clipboard" needs no expect/actual. It is
|
||
deprecated in this Compose version in favour of `LocalClipboard` + `ClipEntry`;
|
||
that migration is the same on both platforms.
|
||
|
||
Image decode: the spike decodes attachment bytes via
|
||
`org.jetbrains.skia.Image.makeFromEncoded(bytes).toComposeImageBitmap()` — the
|
||
desktop replacement for `BitmapFactory.decodeByteArray`. Compiling code path;
|
||
runtime decode only runs when `--image <file>` is passed.
|
||
|
||
## Q6 — Packaging
|
||
|
||
```
|
||
./gradlew :spike:compose-jvm:createDistributable → 168 MB app-image
|
||
SPIKE-DB PASS — BoxStore built inside the image, notes=0
|
||
```
|
||
|
||
`jpackage` built a self-contained Linux app-image (bundled jlink runtime) with no
|
||
extra host tooling — no FUSE, no `rpmbuild`, no Docker. `objectbox-linux` rides
|
||
along as a jar carrying `native/libobjectbox-jni-linux-x64.so` (2.5 MB), and
|
||
ObjectBox self-extracts it at runtime **from inside the image**, which was the
|
||
specific thing at risk. `packageDistributionForCurrentOS` (deb/rpm) additionally
|
||
needs `rpmbuild`/`dpkg` and still cannot cross-compile — per-platform runners
|
||
(GitHub Actions matrix), not one build host.
|
||
|
||
Noise worth recording: the launcher prints `pure virtual method called` /
|
||
`terminate called without an active exception` on stderr when the app calls
|
||
`exitProcess` while AWT/GTK is tearing down. Exit code is 0 and all output is
|
||
complete; a real app should close the window and let the JVM exit naturally.
|
||
|
||
## Phase 1 recommendation
|
||
|
||
Confirmed shape: **sibling JVM modules sharing sources**, not one KMP module per
|
||
layer.
|
||
|
||
1. `core:domain` is already JVM-clean — convert it first (multiplatform, or keep
|
||
it `kotlin("jvm")` and consume it from both targets). Zero code changes.
|
||
2. Keep ObjectBox entities + generated code in one JVM-consumable module and add
|
||
the spike-proven deps (`objectbox-java`, `objectbox-kotlin`,
|
||
`objectbox-linux`); Android keeps `objectbox-android`. The model file is the
|
||
shared contract — never regenerate UIDs.
|
||
3. Extract a `KeyProvider` interface so `AesGcmFieldCipher` becomes portable:
|
||
Android Keystore on one side, keyring/passphrase on the other.
|
||
4. Put `SettingsRepository`'s store construction behind an injected
|
||
`DataStore<Preferences>` factory (expect/actual if the code moves to common).
|
||
5. UI: budget ~15 files of real `android.*` coupling (context/resources,
|
||
`Build.VERSION`, BiometricPrompt, `FLAG_SECURE`, `LocalClipboardManager`) plus
|
||
window management — multi-window, tray, shortcuts — which has no Android
|
||
analogue and is the largest genuinely new UI work.
|
||
6. Compose Multiplatform 1.7.3 works but is behind. Decide in Phase 1 whether to
|
||
move the app to 1.8.x first; the spike proves feasibility on the pinned
|
||
version, not that 1.7.3 is the right target.
|
||
|
||
Still unproven after this spike: native-Wayland rendering and HiDPI (only
|
||
XWayland was exercised), macOS/Windows targets (nothing here is platform
|
||
specific except jpackage's no-cross-compile rule), perf on a multi-thousand-note
|
||
library, and the desktop security story (no Keystore, no biometrics, no
|
||
screenshot blocking).
|
||
|
||
## Re-running the spike
|
||
|
||
```bash
|
||
./gradlew :spike:data-jvm:run --args="/tmp/incido-spike-db" # S1 + S4 (Q2, Q3, Q5a/b)
|
||
./gradlew :spike:compose-jvm:run --args="--exit-after 6" # S2 (Q1, Q4, clipboard)
|
||
./gradlew :spike:compose-jvm:run --args="--image /path/x.png" # attachment decode
|
||
./gradlew :spike:compose-jvm:createDistributable # S5 (Q6)
|
||
spike/compose-jvm/build/compose/binaries/main/app/incido-spike/bin/incido-spike \
|
||
--probe-db --exit-after 4 # ObjectBox inside the image
|
||
```
|
||
|
||
`spike/` is meant to be deleted once Phase 1 lands; keep this file.
|
||
|
||
## Phase 1 status (same branch)
|
||
|
||
**M1a — platform-neutral data layer: DONE.** `:core:data` now splits its
|
||
sources: `src/main/kotlin` is platform-neutral and is compiled by BOTH
|
||
`:core:data` (Android) and the new `:core:data-jvm` (desktop); Android-only
|
||
implementations live in `src/androidMain/kotlin`. Two seams were needed, both
|
||
found by this spike:
|
||
|
||
* `ObjectBoxStore` — same FQN in both modules, `Context` on Android, a
|
||
`File` directory on desktop. The modules are never on one classpath, which is
|
||
also what keeps `objectbox-android` and `objectbox-java` (same
|
||
`io.objectbox.*` classes) from colliding.
|
||
* `ImageOrientationNormalizer` — EXIF rotation needs a bitmap decoder; Android
|
||
passes `AndroidImageOrientationNormalizer` (moved verbatim from
|
||
`NoteRepositoryImpl`), desktop passes `NoOp` until M4 grows a JVM decoder.
|
||
|
||
`./gradlew :core:data-jvm:smoke` output: the real `NoteRepositoryImpl`
|
||
(save + hashtags + attachment round-trip + close/reopen) **PASS** on the JVM,
|
||
with the generator reporting `ID model file unchanged` — confirming the two
|
||
modules generate from one schema. `assembleDebug` stays green.
|
||
|
||
Also fixed while here: `.gitignore` had `**/objectbox-models/`, which meant the
|
||
schema contract was **not in version control** — a fresh clone regenerated
|
||
UIDs. `default.json` is now tracked (everything else in that directory stays
|
||
ignored). This matters more now that two modules generate against it.
|
||
|
||
**M1b — desktop shell over the real repository: DONE.** New `:desktopApp`
|
||
(Compose Multiplatform, `compose.desktop` DSL, no explicit `application`
|
||
plugin — see the spike finding). `DesktopContainer` mirrors Android's
|
||
`AppContainer` construction order and owns its own library at
|
||
`$XDG_DATA_HOME/incido`; `--data-dir` opens any other library.
|
||
|
||
Verified headlessly (`--self-test` drives the same repository calls the "+"
|
||
button and the star make, `--exit-after` auto-closes):
|
||
|
||
```
|
||
library : /tmp/incido-desktop-smoke # written by :core:data-jvm:smoke
|
||
RENDER notes=0 selected=null # first frame (collectAsState initial)
|
||
RENDER notes=1 selected=1 # ObjectBox flow delivered
|
||
SELFTEST wrote note id=2 # write path through the UI's calls
|
||
RENDER notes=2 selected=2 # and it came back through the flow
|
||
--- reopen ---
|
||
RENDER notes=2 selected=2 # persisted
|
||
```
|
||
|
||
Two things that run proves beyond what the spike did: the desktop build reads a
|
||
library written by a *different* module's generated `MyObjectBox` (one schema,
|
||
two codegens), and ObjectBox's reactive flow feeds a Compose Desktop
|
||
composition. Note the first frame is always the empty initial value — anything
|
||
asserting on note counts must wait for the flow, not the first composition.
|
||
|
||
Still synthetic in this build: the theme (Material 3 defaults, not Incido's)
|
||
and the screens (this is a two-pane stand-in). Both are replaced by the M4
|
||
`composeApp` commonMain conversion. Not yet wired: settings, encryption (M3),
|
||
backups (M2), packaging (M5).
|
||
|
||
**M2 task 1 — extract `:core:backup`: DONE.** New plain-`kotlin("jvm")`
|
||
module holding `BackupCodec.kt`, `EncryptedBackupCodec.kt` and
|
||
`EncryptedKeyCodec.kt` (`git mv` — the Android diff is the three moves plus
|
||
one dependency line) and a new `BackupBridge`: the four `BackupManager`
|
||
operations re-expressed over `InputStream`/`OutputStream` instead of `Uri`.
|
||
The package name `org.incido.compose.data.backup` was kept on purpose, so no
|
||
consumer import changed; `BackupManager` stays in `:composeApp` as a thin
|
||
`Uri → stream` SAF shim with an identical public API (`BackupPreview` moved
|
||
to the bridge file, same package). Dedupe is task 3, desktop picker UI is
|
||
task 2 — deliberately not here.
|
||
|
||
Verification (all after the move, from a clean state):
|
||
|
||
```
|
||
./gradlew :core:backup:build BUILD SUCCESSFUL (serializers generated in the new module)
|
||
./gradlew assembleDebug BUILD SUCCESSFUL — Android unchanged
|
||
./gradlew :core:data-jvm:smoke RESULT: M1a PASS — the shared data layer runs on the JVM
|
||
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-smoke --self-test --exit-after 6"
|
||
SELFTEST wrote note id=1 → RENDER notes=1 selected=1
|
||
./gradlew :spike:data-jvm:run … recovery-key envelope (real codec) PASS — 84-byte envelope,
|
||
32-byte key round-tripped; wrong passphrase → AEADBadTagException
|
||
```
|
||
|
||
Housekeeping found on the way: `:core:data-jvm:smoke` does not clear
|
||
`build/data-jvm-smoke/`, and the script asserts on a fresh library — a
|
||
second consecutive run fails with "expected 1 note, got 2". Run it against
|
||
a deleted directory (worth fixing in a later milestone).
|
||
|
||
**M2 — real-data round-trip probe + import-timestamp fix: DONE.** New
|
||
`./gradlew :core:data-jvm:backupSmoke --args="<export.incido.json> [libDir]"`
|
||
feeds a **real** phone export (27 notes, 1 attachment, 14 orphan tags,
|
||
TASK_LIST+TEXT, colors, 1 favourite — file kept out of the repo, it's user
|
||
data) through the bridge on the JVM: preview → import into a fresh library
|
||
→ re-export and compare every field the format claims to preserve →
|
||
encrypted envelope export (wrong passphrase → `null` preview) → import of
|
||
the envelope into a second library with attachment-byte equality.
|
||
|
||
The probe immediately caught a **pre-existing Android bug**: `upsert` /
|
||
`saveNoteWithHashtags` overwrote `createdAt` AND `updatedAt` with "now"
|
||
for every insert, so even the phone's own import re-stamped the whole
|
||
library — silently breaking the `(createdAt, updatedAt, sha256(content))`
|
||
dedupe key M2 task 3 is built on. Fixed in the shared repository: a
|
||
caller-supplied non-zero timestamp is honoured, `0` still means "now"
|
||
(the Android editor already stamps both fields itself, verified at its two
|
||
`Note(…)` sites — so only the import path changes). Same for
|
||
`addAttachment`, which now takes `createdAt: Long = 0L` and
|
||
`importSnapshot` passes the phone's value through.
|
||
|
||
```
|
||
preview (plain, no passphrase) PASS — notes=27 attachments=1 app=0.4.0.0
|
||
import into fresh JVM library PASS — imported 27 notes, all readable back through the flow
|
||
re-export plain == original PASS — all 27 notes + 1 attachments identical
|
||
(content/times/fav/color/type/trash/draft/tags/bytes)
|
||
encrypted export + wrong-pw reject PASS — envelope=366739B, wrong passphrase → null
|
||
import encrypted into 2nd library PASS — attachment 260121B byte-identical to the phone's
|
||
RESULT: M2 round-trip PASS
|
||
```
|
||
|
||
Still open from the probe: `importSnapshot` never recreates *orphaned*
|
||
hashtag rows (the export carries them, the import ignores them) —
|
||
pre-existing on Android, noted for task 3. After the fix, full suite green:
|
||
`assembleDebug`, `:core:data-jvm:smoke`, desktop `--self-test`,
|
||
`:spike:data-jvm:run` — and the ObjectBox generator kept printing
|
||
`ID model file unchanged`.
|
||
|
||
**M2 task 2 — desktop Import/Export UI: DONE.** `:desktopApp` gained the
|
||
`:core:backup` dependency, a top-bar overflow menu (Import from file… /
|
||
Export plain / Export encrypted, `BackupActions.kt`) with Material3
|
||
passphrase + confirm dialogs, and AWT `FileDialog` (native GTK under
|
||
XWayland) driven on the IO dispatcher. Every flow ends in the same
|
||
`BackupBridge` calls the Android shim makes — the format is shared by
|
||
construction. The confirm dialog reuses `BackupPreview` counts and plainly
|
||
states that duplicates persist until task 3.
|
||
|
||
Scripted verification (`--backup-import/--backup-export`, the same bridge
|
||
calls as the menu, no dialog clicking):
|
||
|
||
```
|
||
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-m2-import4 --backup-import <real phone export> --backup-export /tmp/m2t4-exp.json --exit-after 8"
|
||
BACKUP preview notes=27 attachments=1 app=0.4.0.0
|
||
BACKUP imported=27 (same calls as the Import… menu)
|
||
RENDER notes=27 selected=1
|
||
BACKUP exported=27 notes to /tmp/m2t4-exp.json → exits cleanly
|
||
|
||
:core:data-jvm:backupSmoke on the DESKTOP-written file: all PASS
|
||
python cross-check phone file vs desktop export: notes (createdAt,
|
||
updatedAt, content) identical = True; attachment Base64 identical = True
|
||
```
|
||
|
||
That closes the **phone → desktop → phone half of task 4** for plain
|
||
format: byte-identical notes + attachment through the real app. Remaining
|
||
task 4 items: encrypted file in each direction via the UI, and the
|
||
phone-side re-import check on a device.
|
||
|
||
One anomaly worth recording: the very first scripted run hung post-export
|
||
(no thread dump obtainable; ~0.8% CPU, idle). Three subsequent identical
|
||
runs exited in 10s; the classic `--self-test --exit-after` path was also
|
||
re-verified green. Unreproduced — keep an eye on it during M5 (the trap
|
||
list already has an exit-time AWT/`exitProcess` quirk).
|
||
|
||
Full suite green after the change: `assembleDebug`, `:core:data-jvm:smoke`,
|
||
`backupSmoke`, `:desktopApp:run --self-test`.
|
||
|
||
**M2 task 3 — import dedupe: DONE.** `BackupBridge.import` now skips notes
|
||
whose `(createdAt, updatedAt, sha256(content))` key already exists in the
|
||
library (default ON, `skipExisting = false` overrides), and returns
|
||
`ImportSummary(imported, skipped)` instead of a bare count. The existing
|
||
keys are snapshotted BEFORE the import, so two genuinely identical notes
|
||
inside one file still import into a fresh library — only a second import
|
||
of the same file adds nothing (matches the §4 wording exactly). Keys
|
||
include trashed notes, so restoring around the trash can't duplicate.
|
||
`BackupManager.import` (Android shim) passes the flag through and returns
|
||
the summary; `SettingsViewModel`'s snackbar gained the skip count (one
|
||
line — the screen layouts are untouched). The desktop confirm dialog
|
||
replaced its "duplicates persist" warning with a working
|
||
"Skip notes that are already here" checkbox (default ON); the export
|
||
format did not change (`formatVersion` stays 1).
|
||
|
||
```
|
||
backupSmoke new step: re-import skipped=27; override added 27 (store=54) PASS
|
||
:desktopApp:run --backup-import <real export> --backup-export … --exit-after 8
|
||
BACKUP imported=27 skipped=0 → exported=27 → reimport imported=0 skipped=27
|
||
```
|
||
|
||
Known limitation (by design, per plan): attachments are not part of the
|
||
key — two notes with identical text AND timestamps but different
|
||
attachments dedupe as one. Phone side: second import now says
|
||
"Imported 0 note(s), skipped 27 already imported." — device smoke still
|
||
pending with the rest of task 4.
|
||
|
||
Full suite green: `backupSmoke` (9 steps incl. dedupe), `assembleDebug`,
|
||
`:core:data-jvm:smoke`, scripted desktop run (clean exit),
|
||
`:desktopApp:run --self-test`.
|
||
|
||
**M2 task 4 (desktop leg) — encrypted round-trip via the app: DONE.**
|
||
New scripted flags `--backup-export-enc <path>` + `--backup-passphrase
|
||
<pw>` drive the passphrase dialogs' exact call chain headlessly:
|
||
`exportEncrypted` writes a real ICDBKP1 envelope, and importing it back
|
||
exercises `preview(stream, pw)` → `import(stream, pw)` → wrong-passphrase
|
||
preview → deduped re-import, in fresh libraries across two launches:
|
||
|
||
```
|
||
run A: plain import 27 → reimport skipped=27 → exported-enc=27 (magic=ICDBKP1 ok)
|
||
run B: preview encrypted=true → imported=27 → wrong-pw preview=null (rejected)
|
||
→ reimport imported=0 skipped=27
|
||
```
|
||
|
||
Caught while writing it: `EncryptedBackupCodec` zeroes the passphrase
|
||
`CharArray` it consumes — **both in `encrypt` AND `decrypt`** — so every
|
||
call needs a fresh array. The UI already complies (dialogs re-derive
|
||
`toCharArray()` per call); the scripted block initially reused one array
|
||
and died on the second decrypt with `AEADBadTagException`. Worth
|
||
remembering for the phone device pass and any future caller: treat the
|
||
passphrase array as single-use fuel. The envelope desktop produces is
|
||
byte-format-identical to the phone's because both sides now compile the
|
||
same `:core:backup` codec — the remaining proof for task 4 is the
|
||
on-device leg (Waydroid: phone re-imports a desktop-made encrypted file
|
||
+ dedupe snackbar), tracked as M2 task 4b.
|
||
|
||
**M2 task 5 — export memory: MEASURED, recorded, no redesign (per plan).**
|
||
New `:core:data-jvm:backupMemory` probe synthesizes worst-case ObjectBox
|
||
libraries (fixed seed) and samples heap-used at 1 ms while
|
||
`BackupBridge.exportPlain` — the phone's own export path — runs:
|
||
|
||
```
|
||
heap ceiling : 2048 MB
|
||
phone-at-gate (20 notes, 3 att x 8 MB) | data≈ 24 MB → 520 ms | peak 230 MB (+219) | file 32 MB
|
||
many notes (2000 notes, no att) | data≈ 2 MB → 205 ms | peak 140 MB (+104) | file 3 MB
|
||
phone-heavy (100 notes, 10 att x 8 MB)| data≈ 80 MB → 1100 ms | peak 777 MB (+765) | file 106 MB
|
||
watch tier (200 notes, 40 att x 8 MB)| data≈320 MB → OutOfMemoryError at -Xmx2g
|
||
process peak RSS (VmHWM): 1707 MB
|
||
```
|
||
|
||
Findings:
|
||
- **Attachments, not note count, drive memory.** 2000 text notes cost
|
||
140 MB peak — trivial. Export allocation runs ~9–10x attachment bytes
|
||
(store load → base64 String → UTF-8 bytes → JsonElement tree ≈ four
|
||
live copies plus serializer churn).
|
||
- The plan's >250 MB gate trips at ≈25–30 MB of attachments. The phone
|
||
declares no `largeHeap`, so its default (~192–256 MB) heap OOMs around
|
||
the same point — a **pre-existing Android limitation**, unchanged by
|
||
Phase 1 (the bridge moved the code, not its memory profile).
|
||
- Real-world headroom: the user's actual library exports at 366 KB
|
||
(27 notes + one 260 KB attachment) → peak well under 50 MB. Roughly
|
||
1000x headroom before the gate.
|
||
- Bonus finding: a ~1.6 GB attachment library first dies in **ObjectBox
|
||
JVM** (`DbFullException` — objectbox-java caps DB size), not in the
|
||
bridge. The phone's objectbox-android has its own ceiling; irrelevant
|
||
at current scales.
|
||
|
||
Verdict: record, don't redesign (plan wording honoured). The streaming
|
||
formatVersion=2 idea stays parked for Phase 2 and becomes *required*
|
||
iff attachment libraries approach ~25 MB.
|
||
|
||
**M2 task 4b — on-device encrypted round-trip (Waydroid): DONE, one real
|
||
bug caught and fixed.** Manual UI pass on the Waydroid phone emulator
|
||
(rig + capture recipe in `tools/WAYDROID_TESTING.md`, injector in
|
||
`tools/inject2.c`). Phone exports encrypted, then re-imports the same
|
||
file through the real UI:
|
||
|
||
```
|
||
export: Settings → Export to file… → Encrypted → passphrase → Encrypt &
|
||
export → SAF SAVE → snackbar "Encrypted backup exported. Store
|
||
the passphrase safely." (file lands 2.77 kB, magic ICDBKP1)
|
||
import: Import from file… → picker shows the .incido.json → app sniffs
|
||
the magic → "Decrypt backup" single-field sheet → correct pw →
|
||
preview "4 note(s) / 0 attachment(s) / Exported from v0.4.2.0 /
|
||
Oct 5, 2026" → Import →
|
||
snackbar "Imported 0 note(s), skipped 4 already imported."
|
||
```
|
||
|
||
**The bug:** the encrypted import silently did nothing — the confirm
|
||
dialog closed but no import ran and no snackbar ever appeared.
|
||
`PassphraseDialog.onConfirm` runs a shared preamble that clears all four
|
||
URI slots (`pendingImportUri = null`, SettingsScreen.kt:383) *before*
|
||
routing on mode; the IMPORT branch previews from a local copy but never
|
||
re-arms the slot, so the confirm dialog's Import button read
|
||
`pendingImportUri == null` and skipped the whole `viewModel.import`
|
||
call. Plain-JSON imports never pass through the passphrase dialog, so
|
||
M2.1–M2.5 could not catch this — exactly why the device leg existed.
|
||
Fix: the IMPORT branch re-arms `pendingImportUri = importUri` before
|
||
launching the preview; wrong-passphrase and dismiss paths still null it
|
||
(and zero the retained chars). Verified fixed on-device with the
|
||
dedupe snackbar above.
|
||
|
||
Device-run notes (cost hours; recorded for M3's manual passes): taps
|
||
map 1:1 to screenshot pixels; TextButtons ignore Enter until Tab moves
|
||
focus onto them (keyboard nav is the reliable path); snackbars expire
|
||
before a 3 s-delayed screenshot — burst-capture spectacle at 1 s
|
||
intervals; `waydroid shell` needs sudo, but `waydroid app install` and
|
||
`pkill -f org.incido.app` from the host need none.
|
||
|
||
**M3.1 — `:core:settings`: DONE.** `UserSettings` + `SettingsRepository`
|
||
moved to a plain `kotlin("jvm")` module with package
|
||
`org.incido.compose.data.settings` kept, so the Android diff is two
|
||
constructor lines + one new provider file (`AndroidSettingsStore.kt` —
|
||
the `preferencesDataStore(name = "incido_settings")` Context extension,
|
||
moved verbatim). The repository now takes an **injected**
|
||
`DataStore<Preferences>`; the desktop creates the identical format with
|
||
`PreferenceDataStoreFactory.create(corruptionHandler, produceFile)`
|
||
(the Phase-0 API delta). `:app` gained `implementation(":core:settings")`
|
||
— MainActivity reads `userSettingsFlow` and the type moved with the
|
||
class, same reason `:core:domain` is there. `snapshot()`'s `runBlocking`
|
||
kept for startup-only use. `dynamic_color` / `use_biometric` /
|
||
`block_screenshots` ride in the file but have no desktop UI (hidden,
|
||
not faked). Verified: `assembleDebug` + `:desktopApp:run … --self-test`
|
||
+ `:core:data-jvm:smoke` green.
|
||
|
||
**M3.2 — cipher seam: DONE.** `AesGcmFieldCipher` moved into
|
||
`core/data/src/main/kotlin/…/crypto/` (compiled by BOTH modules) behind
|
||
new `fun interface FieldKeyProvider { getOrCreateKey(): ByteArray }`;
|
||
`EncryptionVerifier` (pure coroutines) moved with it. Android passes
|
||
`objectBoxKeyProvider::getOrCreateKey` (SAM). Verified: `assembleDebug`
|
||
+ desktop self-test green.
|
||
|
||
**M3.3 — desktop key + wiring + UI: DONE.** `DesktopKeyProvider`: the
|
||
32-byte key in `field.key` (temp+atomic-move, `0600` POSIX perms —
|
||
visible as `-rw-------` in every `ls` below). KEYRING STATUS, STATED
|
||
PLAINLY: no keyring library is in the catalog and no candidate was
|
||
verified on this stack, so the plan's fallback (file + `0600`) stands;
|
||
revisit in Phase 2 with `secret-service` behind a real test.
|
||
`DesktopContainer` now mirrors `AppContainer` completely — settings →
|
||
cipher auto-install (`isEncryptionActive` AND key on disk) BEFORE the
|
||
repository → `NoteCryptoService` → `EncryptionVerifier.checkNow()`.
|
||
`SecurityActions` menu: theme cycle (real shared `theme_mode` key —
|
||
Material3 switches via `colorScheme`, there is no `darkTheme` param),
|
||
encrypt/decrypt toggle (Android's enable/disable call order), recovery
|
||
key import/export (with Android's overwrite-warning gate); no dynamic
|
||
color, no biometrics, no screenshot blocking, no PIN — desktop hides
|
||
all four. Window geometry → its own `incido_window.preferences_pb`
|
||
(position deliberately not stored; KWin owns placement). Scripted legs
|
||
(`--crypto-self-test` / separate-process `--crypto-reopen`):
|
||
|
||
```
|
||
=== leg A: enable === (fresh /tmp/incido-desktop-crypto)
|
||
probe note written PASS id=1
|
||
encrypt sweep flipped rows PASS
|
||
verifier trial-decrypt sweep PASS verified=1 failed=0
|
||
repository decrypts transparently PASS notes=1
|
||
wrong key rejected (AEAD tag) PASS failed=1
|
||
recovery envelope (INCKEY1) PASS len=84
|
||
wrong passphrase rejected PASS
|
||
envelope carries library key PASS
|
||
CRYPTO LEG-A PASS (library left encrypted for leg B)
|
||
|
||
=== leg B: reopen (separate process = the real relaunch) ===
|
||
settings survived restart PASS
|
||
cipher auto-installed PASS
|
||
reopen verifier sweep all-ok PASS verified=1 failed=0
|
||
decrypt sweep reverses it PASS
|
||
CRYPTO LEG-B PASS
|
||
```
|
||
|
||
**M3.4 — recovery-key envelope file legs: DONE (desktop side).**
|
||
`--key-export` / `--key-import` drive the menu's exact codec calls
|
||
headlessly — export from one library, import into a FRESH one:
|
||
|
||
```
|
||
KEYENV exported=84B to /tmp/incido-recovery-key.incidokey (magic=INCKEY1 ok)
|
||
KEYENV import ok wrong-pw=rejected verify verified=0 failed=0
|
||
KEYENV import FAILED: AEADBadTagException: Tag mismatch! (wrong passphrase)
|
||
-rw------- 1 nick nick 32 … /tmp/incido-key-dst/field.key (imported key is 0600)
|
||
```
|
||
|
||
**M3 exit criteria:** (1) "an encrypted desktop library passes
|
||
`EncryptionVerifier`'s trial-decrypt sweep" — **met**, leg A step 3 +
|
||
leg B (auto-install + full-library sweep on relaunch). (2) "a
|
||
phone-exported recovery key decrypts … on desktop" — **met at format
|
||
level** (one shared `EncryptedKeyCodec` source compiled into both
|
||
platforms; 84-byte envelope, wrong-pw AEAD rejection, byte-identical
|
||
key — above); the **physical phone leg is the one item pending**: the
|
||
Waydroid container was FROZEN at session end and starting it is
|
||
sudo-gated, so the phone→desktop `Settings → Export recovery key` run
|
||
could not be executed here. Recipe for it (≈15 min with a live
|
||
container, mirrors the M2.4b pass): enable encryption on the phone →
|
||
export the recovery key to a shared-storage file → copy to host →
|
||
`./gradlew :desktopApp:run --args="--data-dir /tmp/incido-phonekey
|
||
--backup-import <phone-backup.incido.json> --key-import
|
||
<recovery.incidokey> --crypto-passphrase <pw> --exit-after 25"` →
|
||
enable encryption in that library → every imported note earns the badge.
|
||
|
||
Honesty notes: (a) intermittent XWayland window flakiness struck this
|
||
session's scripted runs three times — a startup wedge (never reached
|
||
first composition) and two teardown wedges (all output flushed, never
|
||
reached `exitApplication`); every occurrence passed cleanly on rerun,
|
||
none touched the data paths, and the first predates all M3 code, so it
|
||
is environmental (likely compositor power state after long uptime), not
|
||
a regression. Scripted verification should retry once before believing
|
||
a hang;
|
||
(b) `field.key` protects at-rest notes only against someone reading the
|
||
files — it cannot gate app opening (no desktop lock is wired; PIN gating
|
||
is deferred); (c) the PBKDF2 recovery path costs ~55 ms per unlock here,
|
||
so desktop may skip Android's async key handling for good.
|
||
|
||
**M4.1 — `:composeApp` in-place → Kotlin Multiplatform: DONE (build
|
||
shape).** Plan §6.1 step 1 attempted — and it holds: no `:ui-shared`
|
||
fallback needed so far. `kotlin("multiplatform")` with
|
||
`androidTarget()` + `jvm()`; every still-Android file moved
|
||
UNMODIFIED into `androidMain` (git recorded pure renames — the
|
||
Android behaviour diff is zero by construction), and `commonMain`
|
||
starts with only what compiles for both targets today (theme
|
||
Color/Type, PasswordPolicy, ReleaseNotes, LinkedShareComposer) behind
|
||
two expect/actual seams — `platformDynamicColorScheme` (Android
|
||
actual = the verbatim API-31 branch, JVM actual = null) and
|
||
`relativeTimestamp` (Android actual = `DateUtils` verbatim, JVM
|
||
actual = `java.time` approximation, English-only until follow-up).
|
||
Deferred with reasons in the build file: `:core:domain` converts
|
||
first in M4.2 (it is still `kotlin("jvm")`, so `NoteColors.kt` can't
|
||
be common yet); screens/ViewModels/`AppContainer` move with the M4.3
|
||
container seam.
|
||
|
||
New friction paid into §2/§3 on the way (all fixed in-tree):
|
||
`kotlinMultiplatform` must be registered at the ROOT `apply false`
|
||
like the other markers (sibling markers put KGP on the classpath —
|
||
the §2.5 kapt error again); KMP handlers need
|
||
`project.dependencies.platform(…)` for BOMs and no
|
||
`debugImplementation` accessor; `ColorScheme` is
|
||
`androidx.compose.material3.ColorScheme` (ships inside
|
||
material3-desktop — no extra artifact); AGP 8.7.2 > KGP-tested 8.5
|
||
is warning-only.
|
||
|
||
```
|
||
./gradlew :composeApp:compileKotlinJvm BUILD SUCCESSFUL
|
||
./gradlew assembleDebug BUILD SUCCESSFUL (106 tasks)
|
||
./gradlew :core:data-jvm:smoke RESULT: M1a PASS
|
||
./gradlew :desktopApp:run … --self-test SELFTEST wrote note id=1
|
||
git status core/**/objectbox-models clean — ID model file unchanged
|
||
```
|
||
|
||
Also this session: the full §1 verification gate re-ran green before
|
||
M4 began — including both M3 crypto legs (`leg-A ALL-OK`, `LEG-B
|
||
PASS` in separate processes). One leg-A teardown wedge reproduced
|
||
(documented environmental behaviour): every PASS line had flushed,
|
||
`exitApplication` never arrived; killed, leg B verified the encrypted
|
||
library intact and passed anyway.
|
||
|
||
**M4.2 — `:core:domain` → multiplatform: DONE.** Phase-0
|
||
recommendation #1 ("convert it first; zero code changes") — the plain
|
||
`kotlin("jvm")` deploy was the gate blocking `commonMain` access.
|
||
`androidTarget()` + `jvm()`, sources moved untouched (pure renames),
|
||
coroutines `implementation → api` (Flow is in the public interfaces),
|
||
AGP plugin + namespace added, no manifest needed. Consumers unchanged
|
||
by design — plain-JVM (`:core:data-jvm`, `:desktopApp`) and AGP
|
||
(`:core:data`, `:app`) both resolve through variant metadata.
|
||
`NoteColors.kt` then became the first shared UI-layer file with a
|
||
domain dependency (`api(project(":core:domain"))` in composeApp
|
||
commonMain).
|
||
|
||
```
|
||
./gradlew assembleDebug :composeApp:compileKotlinJvm :core:data-jvm:smoke
|
||
BUILD SUCCESSFUL — RESULT: M1a PASS (one run, all consumers)
|
||
./gradlew :desktopApp:run … --self-test SELFTEST wrote note id=1
|
||
```
|
||
|
||
**M4.3 — container seam: DONE.** `AppGraph` in
|
||
`commonMain` (`noteRepository` + `settingsRepository` +
|
||
`encryptionBadge`) with `LocalAppGraph`/`requireAppGraph`; both
|
||
containers implement the face. Three commits:
|
||
|
||
- **M4.3a** — `:core:settings` → multiplatform (verbatim M4.2 playbook,
|
||
pure renames). One honest new seam: `runBlocking` has no commonMain
|
||
declaration, so `snapshot()` goes through an internal expect/actual
|
||
`blockingFirst` — identical two-liner actuals (both targets JVM).
|
||
- **M4.3b** — the §6.4 "verify the artifact set" answer is **GREEN,
|
||
no state-holder fallback needed**: `org.jetbrains.androidx.lifecycle:
|
||
2.8.4` is the same coordinate set `androidMain` has resolved since
|
||
M4.1 (assembleDebug coexists with the AndroidX BOM) and the desktop
|
||
runtime already carried matching `-desktop` jars — so ViewModels
|
||
move with their `androidx.lifecycle.*` imports UNCHANGED.
|
||
`DrawerViewModel` led; `AppContainer : AppGraph` + `IncidoApp`
|
||
provides `LocalAppGraph` at the root.
|
||
- **M4.3c** — `NoteListViewModel` + `NoteEditorViewModel` (UiStates +
|
||
`SharedImage`) in commonMain. The editor VM's four
|
||
`withContext(Dispatchers.IO)` became `withContext(ioDispatcher)` —
|
||
internal expect/actual, actual literally `Dispatchers.IO` on both
|
||
targets. `EncryptionBadge`/`LibraryVerification` mirror `:core:data`'s
|
||
`EncryptionVerification` because :core:data is an androidLibrary and
|
||
must stay invisible to commonMain (§2.3 ObjectBox classpath rule);
|
||
each container maps the real verifier 1:1 at its own seam.
|
||
`SettingsViewModel` stayed in androidMain — the graph was NOT widened
|
||
around SecurityManager/Keystore/Uri-IO/CarnetImporter; those screens
|
||
read a small `LocalAndroidContainer`. APPLICATION_KEY +
|
||
`IncidoApplication` are gone from all four ViewModels and all six
|
||
screen call-sites (drawer/list/editor/settings/pin-setup/pin-change).
|
||
**Exit proof: `DesktopContainer : AppGraph`**, compiler-checked via
|
||
`:desktopApp` → `:composeApp` (jvm variant); `repository` renamed
|
||
`noteRepository`. Stand-in UI unchanged (M4.5 hosts the real screens).
|
||
|
||
```
|
||
§1 gate re-run first, all green:
|
||
:core:data-jvm:smoke RESULT: M1a PASS
|
||
:desktopApp:run … --self-test SELFTEST id=1 → RENDER notes=1
|
||
(first attempt hit the documented teardown wedge AFTER all PASS
|
||
lines — killed, rerun exited 0; see new §3 trap below)
|
||
:spike:data-jvm:run RESULT: S1 PASS — incl. envelope
|
||
84 B round-trip, PBKDF2 [50, 50] ms
|
||
assembleDebug BUILD SUCCESSFUL (134 tasks)
|
||
:desktopApp:createDistributable BUILD SUCCESSFUL — 169 MB image
|
||
crypto legs, separate processes 9×PASS + leg-A ALL-OK → LEG-B PASS
|
||
objectbox-models clean; default.json tracked,
|
||
not ignored (ls-files + check-ignore)
|
||
|
||
M4.3 suite per commit:
|
||
./gradlew assembleDebug :composeApp:compileKotlinJvm :desktopApp:build
|
||
BUILD SUCCESSFUL (the AppGraph exit proof compiles here)
|
||
:desktopApp:run … --self-test SELFTEST id=1 → RENDER notes=1 selected=1, clean exit
|
||
:core:data-jvm:smoke RESULT: M1a PASS
|
||
crypto legs (post-refactor) leg-A ALL-OK → LEG-B ALL-OK
|
||
```
|
||
|
||
**Next up: M4.4** — the screens: port the §6.3 seams one at a time
|
||
(theme `dynamicColor`/`Build.VERSION` remaining sites; the seven
|
||
`LocalContext` sites → platform-context abstraction; clipboard
|
||
`LocalClipboardManager` → `LocalClipboard` + `ClipEntry` on BOTH
|
||
platforms; image decode `BitmapFactory` →
|
||
`skia.Image.makeFromEncoded(bytes).toComposeImageBitmap()`; EXIF —
|
||
**verify a JVM decoder exists before committing**; file intake →
|
||
drag-drop + picker). Deferred/hide-UI: voice recording, camera,
|
||
share-sheet, biometrics (§6.5). ViewModels are already common, so
|
||
each screen moves once its own android.* seam is solved. M4.5 then
|
||
hosts the real screens in `:desktopApp` (replacing Main.kt's
|
||
stand-in) and deletes `spike/` (§6.6).
|
||
|
||
**M4.4 — the screens: DONE.** Each screen moved once its own seam was
|
||
solved; every seam landed as expect/actual with the Android code kept
|
||
verbatim in `androidMain` (the §6.3 discipline, one seam per commit):
|
||
|
||
- **M4.4a** — first screens (list + drawer) to commonMain.
|
||
- **M4.4b** — `ImageDecode.kt` (`decodeImageBytes`: skia
|
||
`Image.makeFromEncoded` on both targets — the BitmapFactory replacement);
|
||
`ImageViewerScreen` + card thumbnails moved. `ioDispatcher` seam.
|
||
- **M4.4c** — `NoteEditorScreen` (the big one) to commonMain behind the
|
||
**EditorIntake** seam (`rememberEditorIntake`): the Android actual is
|
||
the verbatim launcher code (camera + permission chain, SAF picker,
|
||
RECORD_AUDIO dance, FileProvider/ACTION_VIEW open, Toasts); the JVM
|
||
actual answers with AWT FileDialog + `Desktop.open` and reports
|
||
`supportsCamera/supportsVoice = false`, so the editor HIDES those
|
||
buttons (§6.5 — hidden, not stubbed). `VoiceNoteSlot` (Android renders
|
||
the untouched recorder; JVM renders nothing). `PlatformBackHandler`
|
||
(activity-compose on Android; no-op on desktop — Esc routing is M5).
|
||
The editor's `securityManager` param became a neutral
|
||
`beginExternalActivity: (() -> Unit)?`.
|
||
- **M4.4d** — the platform-neutral settings sections (Appearance /
|
||
Backup / About + `SettingsSection/Toggle/Row`) to commonMain. Design
|
||
call recorded: full commonization of the 1026-LOC SettingsScreen buys
|
||
nothing — SecuritySection is BiometricPrompt + PIN state machines;
|
||
each platform keeps its plumbing, both share the UI vocabulary. Two
|
||
callbacks went nullable to HIDE platform-incapable rows (dynamic color,
|
||
Carnet importer). Made PUBLIC in M4.5a (desktopApp is a separate module).
|
||
- **M4.4e** — the §6.3 EXIF row's "verify a JVM decoder exists" gate:
|
||
metadata-extractor 2.19.0 (first Maven Central pull of the phase) +
|
||
`JvmImageOrientationNormalizer` (BufferedImage rotate, ImageIO JPEG
|
||
@0.92) — same store-time bake contract as Android. `:core:data-jvm:orientationSmoke`
|
||
hand-splices an APP1 Orientation=6 JPEG and asserts pixels rotate
|
||
(4x2→2x4), passthroughs hold, output is flag-free. `RESULT: M4.4e PASS`.
|
||
|
||
**M4.5 — real screens hosted; spike deleted: DONE.**
|
||
|
||
- **M4.5a** — `DesktopSettingsScreen` composes the M4.4d sections +
|
||
desktop Encryption rows. The M2/M3 flows were SPLIT, not copied:
|
||
`BackupFlows`/`SecurityKeyFlows`/`toggleDesktopEncryption` own pick +
|
||
bridge + dialogs; the settings buttons drive the exact M2-proved code.
|
||
`--settings-smoke` composes it headlessly.
|
||
- **M4.5b** — `DesktopShell`: **the app's own NoteListScreen,
|
||
IncidoDrawer and NoteEditorScreen run on the desktop** over
|
||
`LocalAppGraph provides DesktopContainer`, themed by the shared
|
||
`IncidoTheme`. App.kt's NavHost reduces to three pieces of state. The
|
||
`--editor-smoke` leg closed the last M4 unknown: JetBrains lifecycle's
|
||
fallback ViewModelStoreOwner means `viewModel(factory=…)` just works
|
||
on the JVM. The M1b stand-in UI and the M2/M3 menu skins are deleted.
|
||
- **§6.6** — `spike/data-jvm` + `spike/compose-jvm` removed from the
|
||
build (their findings all have permanent homes now).
|
||
|
||
Harness note for the smoke legs: the FIRST `:desktopApp:run` after a code
|
||
change sometimes rides out the `timeout` because the same invocation
|
||
rebuilds the jar first; warm re-runs auto-exit 0. Not a teardown wedge —
|
||
the app prints its legs and exits in ~20 s.
|
||
|
||
```
|
||
M4.4/M4.5 suite (per commit; final run this entry):
|
||
./gradlew assembleDebug :desktopApp:build BUILD SUCCESSFUL
|
||
:composeApp:compileKotlinJvm + compileDebugKotlinAndroid SUCCESSFUL
|
||
:desktopApp:run … --self-test SELFTEST id=1 → RENDER, exit 0
|
||
:desktopApp:run … --settings-smoke SETTINGS shown, exit 0
|
||
:desktopApp:run … --editor-smoke EDITOR shown, exit 0
|
||
:core:data-jvm:smoke RESULT: M1a PASS
|
||
:core:data-jvm:orientationSmoke RESULT: M4.4e PASS (5/5)
|
||
objectbox-models clean
|
||
```
|
||
|
||
**Next up: M5** — desktop polish: Esc/back routing through
|
||
`PlatformBackHandler` (editor discard prompt), keyboard shortcuts,
|
||
window/menu integration, packaging (`createDistributable` re-verify +
|
||
the M4.3d artifact notes), and the §9 perf pass on the real screens.
|
||
|
||
**§1 gate re-run this session: GREEN** (fresh dirs; the two crypto legs
|
||
as SEPARATE processes; spike probes correctly absent — deleted in
|
||
M4.5c):
|
||
|
||
```
|
||
:core:data-jvm:smoke RESULT: M1a PASS, exit 0
|
||
:desktopApp:run … --self-test SELFTEST id=1 → RENDER, exit 0
|
||
assembleDebug BUILD SUCCESSFUL, exit 0
|
||
crypto leg A (own process) leg-A ALL-OK (9×PASS), exit 0
|
||
crypto leg B (own process) LEG-B PASS, leg-B ALL-OK, exit 0
|
||
```
|
||
|
||
**M5.1 — Esc routing + keyboard shortcuts: DONE.**
|
||
|
||
- `PlatformBackHandler`'s JVM actual is no longer a no-op:
|
||
`PlatformBackStack` + `LocalPlatformBackStack` (composeApp jvmMain).
|
||
Entries are position-stable (remembered object, callback slot
|
||
refreshed per composition) so a lower screen's recomposition can never
|
||
jump above the editor. `dispatchBack()` runs the topmost ENABLED
|
||
entry, false = unconsumed so Esc still reaches popups.
|
||
- `Main.kt` provides the stack and drains it from
|
||
`Window(onPreviewKeyEvent)` on Esc (logs `esc(captured)` for manual
|
||
verification). **The editor changed zero lines** — its commonMain
|
||
`BackHandler { tryClose() }` rides the seam, so desktop Esc gets the
|
||
draft flush + "Discard changes?" prompt exactly like Android.
|
||
- `DesktopShell` registers Esc for drawer + settings; shortcuts **Ctrl+N**
|
||
(new note) and **Ctrl+comma** (settings) go on `onPreviewKeyEvent` —
|
||
preview phase wins over focused text fields.
|
||
- New `--keys-smoke` leg drives the window's exact dispatch
|
||
(`dispatchBack`) headlessly: clean-editor Esc closes, nothing-enabled
|
||
does NOT consume, settings Esc closes. One fix en route: the KEYS-leg
|
||
settings mirror needed `LaunchedEffect(showSettings)` sync or leg (c)
|
||
read a stale mirror.
|
||
- **Pending-manual:** real keypresses could not be verified headless —
|
||
KWin under Wayland does not deliver xdotool XTEST events to the
|
||
XWayland window (focus probes confirmed the app HAS focus; zero
|
||
events arrived). One real Esc + Ctrl+N at the desk is the outstanding
|
||
check; `esc(captured)` logs on the console when it works.
|
||
|
||
```
|
||
M5.1 suite:
|
||
assembleDebug :composeApp:compileKotlinJvm :desktopApp:build BUILD SUCCESSFUL
|
||
:desktopApp:run … --keys-smoke KEYS ALL-OK (editor/no-consume/settings 3×PASS), exit 0
|
||
:desktopApp:run … --self-test SELFTEST id=1, exit 0
|
||
:desktopApp:run … --settings-smoke SETTINGS shown, exit 0
|
||
:desktopApp:run … --editor-smoke EDITOR shown, exit 0
|
||
:core:data-jvm:smoke RESULT: M1a PASS
|
||
```
|
||
|
||
**Next up: M5.2** — tray + single-instance + first-run onboarding.
|
||
|
||
**M5.2 — tray + single-instance + first-run onboarding: DONE.**
|
||
|
||
- **Single instance:** `SingleInstanceLock` claims an OS `FileLock` on
|
||
`<dataDir>/incido.lock` BEFORE the container opens the library. A
|
||
second launch prints `INSTANCE another Incido already owns …` and
|
||
exits 0. Bonus: this converts the §3 "wedged AWT child holds the
|
||
ObjectBox lock" trap into that same clean message. OS locks die with
|
||
the process, so `kill -9` needs no cleanup — a pid file would.
|
||
- **Tray:** `Tray` sits directly in `application {}` (it is an
|
||
*ApplicationScope* extension, NOT callable from window content — and
|
||
its params are icon/state/tooltip/menu only, no onClick; menu items
|
||
are capitalized `Item(…)`/`Separator()`). Show = unminimize, Quit =
|
||
exitApplication. Closing the window still quits (no hide-to-tray —
|
||
keeps exit semantics and every harness leg). Guarded
|
||
`!headless && SystemTray.isSupported()`; scripted legs never attach.
|
||
`TRAY attached` proven live under KDE.
|
||
- **Onboarding:** first-run dialog (window.Dialog per the §3 trap) says
|
||
where the library lives and that the backup file is the phone bridge.
|
||
Gate = `onboarded_v1` flag in the desktop-only window store; dismiss
|
||
writes it; scripted legs skip it. `--onboarding-smoke` (fresh dir:
|
||
shown + flag persisted) and `--onboarding-verify` (same dir: not
|
||
shown) close both directions.
|
||
- **New §3 trap paid:** Compose 1.7.3 `Window` goes AMBIGUOUS between
|
||
its two overloads when the `iconBitmap` arg is passed ("cannot infer
|
||
type" on an unrelated lambda param). Window/taskbar icon therefore
|
||
comes from the distribution icon (M5.3).
|
||
|
||
```
|
||
M5.2 suite:
|
||
second launch, same dir INSTANCE … this copy exits (exit 0)
|
||
:desktopApp:run (interactive-style) TRAY attached (live KDE SNI)
|
||
:desktopApp:run … --onboarding-smoke shown=true PASS, flag-persisted=true PASS
|
||
:desktopApp:run … --onboarding-verify shown=false PASS (gate respected)
|
||
:desktopApp:run … --keys-smoke KEYS ALL-OK (regression)
|
||
:desktopApp:run … --self-test SELFTEST id=1
|
||
:core:data-jvm:smoke RESULT: M1a PASS
|
||
assembleDebug BUILD SUCCESSFUL
|
||
```
|
||
|
||
**Next up: M5.3** — packaging: version wired to versionName, icons,
|
||
`.desktop` entry, createDistributable re-verify + size, Wayland/HiDPI
|
||
verdict.
|
||
|
||
**M5.3 — packaging: DONE.**
|
||
|
||
- **Version wiring:** `packageVersion` now DERIVED — desktopApp's build
|
||
script regexes `versionName` out of `app/build.gradle.kts` (the
|
||
validator-protected source of truth) and maps 0.4.2.0 → 0.4.2 for
|
||
jpackage (4th segment lives in the tag, like the APK flow).
|
||
`:desktopApp:printPackageVersion` prints `PACKAGE-VERSION 0.4.2`.
|
||
- **Icons/.desktop:** `packaging/icon.png` (1024, from
|
||
`incido_flat_icon.png`) + `packaging/incido.desktop` template
|
||
(@PREFIX@ substitution; StartupWMClass=incido). API delta found: the
|
||
1.7.3 Compose DSL has NO `iconFile` property — the .desktop template
|
||
(app-image) and the CI install step (deb) are the icon vehicles.
|
||
- **The image run found a REAL packaging bug:** `NoClassDefFoundError:
|
||
sun/misc/Unsafe` from DataStore's bundled protobuf — the jlink runtime
|
||
lacked `jdk.unsupported` (invisible under the full JDK that
|
||
`:desktopApp:run` uses; the spike never hit it because it had no
|
||
DataStore). Fixed with `modules.add("jdk.unsupported")`. **New §3
|
||
trap: any new JVM module a dependency secretly needs only shows up
|
||
inside the image — smoke the image, not just the run task.**
|
||
- **createDistributable re-verified:** BUILD SUCCESSFUL, app-image
|
||
**171 MB** (168 → 169 → 171 MB across the phase: metadata-extractor +
|
||
M5 code); `bin/incido --data-dir … --self-test --exit-after 6`
|
||
INSIDE the image: `SELFTEST wrote note id=1 → RENDER notes=1`, rc=0.
|
||
- **HiDPI verdict:** `-Dsun.java2d.uiScale=2.0` (via `JAVA_TOOL_OPTIONS`,
|
||
respected by the jpackage launcher) doubles the requested window
|
||
geometry — 1090x730 → clamped at 1920x1016 by the screen (requested
|
||
2180px-wide; the compositor's cap PROVES the scale applied). Font
|
||
crispness at scale not machine-verified; that part is pending-manual.
|
||
- **Native-Wayland verdict:** A probe compiled+run on BOTH installed
|
||
JDKs (Arch 17.0.20.1 and 27) with `WAYLAND_DISPLAY=wayland-0`
|
||
present resolves `sun.awt.X11.XToolkit` either way — this stack has no
|
||
native-Wayland AWT backend; skiko stays on XWayland. Real fix =
|
||
bundling JetBrains Runtime (Wayland-capable) in the distribution →
|
||
Phase 2 (needs Compose ≥1.8 `runtimeDirs` work + a JBR to verify
|
||
against).
|
||
|
||
```
|
||
M5.3 suite:
|
||
:desktopApp:printPackageVersion PACKAGE-VERSION 0.4.2
|
||
:desktopApp:createDistributable BUILD SUCCESSFUL — 171 MB image
|
||
image bin/incido … --self-test SELFTEST id=1 → RENDER notes=1, rc=0
|
||
(pre-fix image run) NoClassDefFoundError sun/misc/Unsafe → fixed
|
||
uiScale 1 vs 2 window geometry 1090x730 → 1920x1016 (clamp) = scaling applied
|
||
AwtProbe on JDK17 / JDK27 (Wayland env) both sun.awt.X11.XToolkit (no native Wayland here)
|
||
:desktopApp:run … --keys-smoke KEYS ALL-OK
|
||
:core:data-jvm:smoke RESULT: M1a PASS
|
||
assembleDebug BUILD SUCCESSFUL
|
||
```
|
||
|
||
**Next up: M5.4** — CI packaging job on the Gitea runner.
|
||
|
||
**M5.4 — CI packaging job: DONE (pending one real tag run).**
|
||
|
||
- `.gitea/workflows/desktop-release.yml`: tag push `v*.*.*` +
|
||
workflow_dispatch retry path (same rationale comment as release.yml),
|
||
on the Linux self-hosted runner only — jpackage can't cross-compile
|
||
and §8 defers macOS/Windows GA to Phase 2 (job stubs left as commented
|
||
shape). This forge is Gitea, so "GitHub Actions matrix" §7 means the
|
||
instance's own runners; macOS/Windows need their own hosts + labels.
|
||
- Job: `createDistributable` + `printPackageVersion` → **image smoke**
|
||
(`xvfb-run bin/incido --self-test`, SKIPPED-with-message if no xvfb —
|
||
recorded, never faked) → `packageDeb` only when `dpkg` exists (deb
|
||
failure degrades to a recorded skip; the app-image still ships) →
|
||
tar.gz bundle including `packaging/incido.desktop` + `icon.png` →
|
||
attach to the release via the same Gitea API + retry-and-verify
|
||
pattern release.yml uses (Cloudflare 524 lesson reused).
|
||
- Local verification possible without pushing a tag: YAML parses (jobs/
|
||
steps listed above), `packageDeb`/`createDistributable`/
|
||
`printPackageVersion` all exist as tasks, and their local runs are
|
||
green from M5.3. **First real tag run is the remaining live check.**
|
||
- `.gitignore`: root `libobjectbox-jni-linux-x64.so` — ObjectBox's
|
||
self-extraction drops it at the process CWD during gradle runs; the
|
||
tracked natives stay in `desktopApp/` + `core/data-jvm/`.
|
||
|
||
**Next up: M5.5** — §9 perf pass on the real screens.
|
||
|
||
**M5.5 — perf pass on the real screens: DONE.**
|
||
|
||
New `--perf-smoke` (fresh dir) / `--perf-verify` (reopen the same dir)
|
||
legs run against the REAL screens with the window composed and the list
|
||
streaming — recomposition pressure is part of the measurement, not a
|
||
separate microbench. Numbers on this dev box (Arch, Ryzen, no
|
||
encryption — the field-cipher leg would add the M3-proved ~55 ms PBKDF2
|
||
once per unlock, not per note):
|
||
|
||
```
|
||
--perf-smoke seed notes=3000 total=279ms per-note=0ms (UI streaming throughout)
|
||
--perf-smoke fresh observeAll notes=3000 in 70ms
|
||
--perf-smoke favorite toggle write 1ms
|
||
--perf-verify reopen first non-empty emission notes=3000 in 89ms
|
||
RENDER lines during the whole seed: 4 (size-keyed emission coalesces —
|
||
no per-save recomposition storm)
|
||
exit codes 0, clean --exit-after teardown both legs
|
||
```
|
||
|
||
Verdict: a multi-thousand-note library is a non-event on desktop — the
|
||
ObjectBox queries, flow emission and LazyColumn all stay far under a
|
||
frame budget at 3000. The §8 "perf on a multi-thousand-note library"
|
||
unknown is CLOSED.
|
||
|
||
**M5 — PACKAGING AND INTEGRATION: DONE** (sub-milestones M5.1–M5.5
|
||
above, one commit each). Remaining pending-MANUAL items, all recorded
|
||
where they arose:
|
||
1. One real Esc / Ctrl+N keypress at the desk (`esc(captured)` logs —
|
||
Wayland blocks headless injection).
|
||
2. HiDPI font crispness eyeball at `uiScale=2` (geometry scaling proven).
|
||
3. First real tag run of `desktop-release.yml` (job steps verified
|
||
locally piecewise).
|
||
4. Carried from M3: the physical phone→desktop recovery-key leg.
|
||
|
||
**Next up: Phase 2 selection (§8)** — streaming backup formatVersion 2
|
||
driven by the seed numbers above, voice notes on desktop, OS-keyring
|
||
caching, JBR bundling for native Wayland, macOS/Windows GA.
|
||
|
||
|
||
|
||
|
||
|
||
|