jake/Lumotia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: jake:pre-lumotia-rebrand
Branches Tags
jake:main jake:feat/v0.3-tactile-quietware jake:claude/auto-titles
jake:lumotia-rebrand-cascade-complete jake:pre-lumotia-rebrand jake:pre-consolidation-2026-04-23
..
compare: jake:65abfa2ed9943b21917fd20d537122c2c0704fa2
Branches Tags
jake:feat/v0.3-tactile-quietware jake:main jake:claude/auto-titles
jake:lumotia-rebrand-cascade-complete jake:pre-lumotia-rebrand jake:pre-consolidation-2026-04-23

42 Commits
pre-lumoti ... 65abfa2ed9

Author SHA1 Message Date
Jake
65abfa2ed9 agent: code-atomiser-fix — span propagation across live + model-load spawns (Obs-3)
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Before this commit `grep -rIn '#\[instrument\|.instrument(\|in_current_span()'`
returned zero matches across the entire workspace. Every tokio::spawn
and thread::spawn lost its parent span, so structured fields recorded
at the call site (session_id, chunk_id, model_id) did not propagate to
log lines emitted inside the spawn. During concurrent-session incidents
the operator could not correlate a runaway log line back to the request
that started it.

Targeted four highest-value join points:

  * src-tauri/src/commands/live.rs::run_live_session
    #[tracing::instrument(skip_all, fields(session_id, engine, language))]
    Attaches the span to the spawn_blocking worker so every per-chunk
    warning carries the session id that owns it.

  * src-tauri/src/commands/live.rs::maybe_dispatch_chunk
    Manual span attach pattern (#[instrument] can't decorate a closure):
    capture the parent span before thread::spawn, .enter() it on the new
    OS thread, then open an "inference" child span with chunk_id +
    duration_secs. Without this, whisper backend warnings appear
    unparented and a runaway chunk can't be traced back to its session.

  * src-tauri/src/commands/models.rs::ensure_model_loaded
    #[instrument(skip_all, fields(model_id, engine, concurrent))]
    Multi-second load + sequential-GPU guard logs now carry the model
    in flight as a structured field.

  * crates/llm/src/lib.rs::load_model
    #[instrument(skip_all, fields(model_id, use_gpu))]
    Same rationale for LLM loads. Tags llama-backend init lines and
    GPU sequential-guard events with the model identifier.

Storage/audio/hotkey/MCP crates left uninstrumented in this commit —
future sweep. The four sites above are the canonical concurrent-load
correlation points; everything else fans out from them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:18:12 +01:00
Jake
d1391b34ac agent: code-atomiser-fix — drop lumotia_live custom target in live.rs (Obs-1, Obs-2)
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
The drain-timeout warning in LiveSessionRuntime emitted with
`target: "lumotia_live"`, which EnvFilter treats as the literal
target string and not as a substring of `lumotia_lib::commands::live`.
The operator's documented triage filter
(`RUST_LOG=info,lumotia=debug,lumotia_lib::commands::live=debug`,
per docs/superpowers/audits/2026-05-10-phase10a-dogfood-notes.md)
therefore silenced the only warning that surfaces a wedged inference
worker. Drop the explicit `target:` so the emit picks up its
module-path target and falls under the existing filter directive.

`lumotia_startup`, `lumotia_storage`, `lumotia_hotkey`, etc. remain
deliberately custom targets — each is a separate semantic phase
with its own dedicated EnvFilter directive.

Regression test asserts no `target: "lumotia_live"` literal remains
in live.rs by scanning the file's own source. Skips comment lines
so the rationale prose does not self-trip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:15:08 +01:00
Jake
12b413d645 agent: code-atomiser-fix — broaden clipboard/paste guards to documented secondary windows 
The Trust-3/Trust-6 fix in commit 7aee534 added ensure_main_window to
copy_to_clipboard, paste_text, and paste_text_replacing. That was over-
broad: the transcript-viewer and transcription-preview windows
legitimately call copy_to_clipboard (their "copy raw" / "copy
transcript" buttons), and the transcription-preview window legitimately
calls paste_text_replacing (the preview paste-to-foreground flow).

The original Trust-3/Trust-6 finding was about asymmetric exposure to
arbitrary windows, not about banning the documented secondary windows.
Fix: add ensure_window_in_set helper in commands::security, mirror the
allow-list against src-tauri/capabilities/secondary-windows.json so the
IPC trust boundary and the permission grant stay in lock-step.

  copy_to_clipboard         -> main + transcript-viewer + transcription-preview
  paste_text_replacing      -> main + transcription-preview
  paste_text                -> main only (unchanged; no secondary caller)

Adds two unit tests for ensure_window_in_set_label covering the
listed-label accept path and the unlisted-label reject path. The
existing Trust-3/Trust-6 tests remain in place and continue to assert
the size cap and the constants-equality invariant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:09:26 +01:00
Jake
9653e25e32 agent: code-atomiser-fix — extension allowlist + size cap on transcribe_file (Trust-5) 
`transcribe_file` already had `ensure_main_window`, but accepted an
arbitrary `path: String` and fed it straight to
`lumotia_audio::decode_audio_file_limited`. The OS file picker
typically constrains the user's path, but the IPC surface itself never
checked: a compromised webview could point the decoder at a 50 GiB
sparse file (OOM the worker), or a deliberately-malformed blob with an
extension chosen to provoke a parser bug in Symphonia.

This change adds defence-in-depth:

- extension allowlist (`wav`, `mp3`, `m4a`, `mp4`, `flac`, `ogg`,
  `opus`, `webm`, `aac`) matched case-insensitively. Anything else,
  including no extension at all, is rejected with a clear error;
- 1 GiB ceiling on the input file. Stats via `std::fs::metadata`
  (which resolves symlinks) so the cap sees the real blob, not a
  symlink-target lie. The 2-hour duration cap still runs after decode
  for the realistic-audio case.

The validation lives in a pure helper, `validate_transcribe_input`, so
the rule can be unit-tested without spawning Tauri or hitting the
decoder.

Eight unit tests cover: accepts plain `.wav`, accepts uppercase `.MP3`,
accepts every allowlisted extension, rejects `.so` payload, rejects
missing extension, rejects oversize file, accepts exactly-at-cap file,
rejects path-traversal with disallowed extension.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:05:07 +01:00
Jake
87e6248774 agent: code-atomiser-fix — trash view + restore button in HistoryPage (Rev-2 UI) 
Adds a Live | Trash toggle to the HistoryPage header. The Trash tab
lists soft-deleted transcripts via the new list_trashed_transcripts
Tauri command and offers per-row Restore via restore_transcript.

Permanently-delete-from-trash is intentionally deferred — the 30-day
startup purge (TRANSCRIPT_TRASH_RETENTION_DAYS in src-tauri/src/lib.rs)
handles hard-removal until that UI lands. The retention policy is
surfaced in the panel header: Trashed items are kept for 30 days,
then permanently deleted on next app start.

Design notes:
  - View toggle is a tablist of two pill buttons (Live | Trash); the
    aria-selected attribute reflects the active mode.
  - Switching to Trash triggers an effect that loads the list once.
    Switching back to Live discards the trash data so stale rows
    don't reappear on toggle.
  - Live-mode header controls (Starred, Tag all untagged, Clear All)
    are hidden in Trash mode and replaced with a Refresh button.
  - Restore drops the row from the in-memory trash list rather than
    splicing into history; the live store reloads from SQLite on its
    own initialisation path, so we avoid drifting the in-memory shape
    from the canonical source.
  - The created timestamp is shown rather than the deletion
    timestamp; deleted_at is not currently in the TranscriptDto and
    expanding the DTO is out of scope for this fix.
  - Audio files may already have been removed by delete_transcript's
    best-effort filesystem cleanup, so restored text + metadata may
    surface without playable audio (documented in the storage-layer
    restore_transcript contract).

TODO(test): no Svelte component test framework wired in the repo
(vitest not installed).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:04:39 +01:00
Jake
f7af7b07bb agent: code-atomiser-fix — main-window guard on extract_content_tags_cmd (Trust-4) 
`extract_content_tags_cmd` was the only LLM command in `commands/llm.rs`
that did not call `ensure_main_window`. Every sibling (`load_llm_model`,
`unload_llm_model`, `delete_llm_model`, `test_llm_model`,
`cleanup_transcript_text_cmd`, `download_llm_model`) gates on it.
Without the guard a secondary-window webview could trigger a multi-
second llama.cpp inference run, blocking the LLM engine for the main
window and leaking model-inferred tags out of the History page's trust
boundary.

This change:

- adds a `window: tauri::WebviewWindow` parameter (Tauri injects it
  automatically — `HistoryPage.svelte`'s `invoke("extract_content_tags_cmd",
  …)` call site is unchanged and `npm run check` is clean);
- calls `ensure_main_window(&window)?` before the engine check so the
  rejection is fast and the cap mirrors the rest of the surface.

Behaviour is otherwise identical: same engine path, same spawn_blocking,
same App-Nap power assertion.

The shared `ensure_main_window_label` test in `commands::security`
already covers the secondary-window rejection behaviour; no
command-level scaffolding for handler-style tests exists in this
codebase, so introducing one for a single new line was out of scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:02:23 +01:00
Jake
50d0715488 agent: code-atomiser-fix — type-the-word DELETE modal for clearAll (Rev-2 UI) 
The prior clearAll UX was a 4-second inline arm-confirm: one click on
Clear All morphed into Confirm/Cancel pills; a second click within
the window wiped every transcript. With the soft-delete backend
(commit 15b74db) now under it, the data-loss class is partially
closed — items land in Trash, not /dev/null — but an absent-minded
double-tap still soft-deletes the entire history at once.

Fix: replace the inline arm-confirm with a modal that requires the
user to type the word DELETE (case-sensitive, exact) before the
Confirm button activates. The single-transcript and bulk-selection
delete flows keep their lighter arm-confirm pattern; only the
all-at-once nuke is gated by the modal.

Modal details:
  - autofocuses the input on open
  - Enter submits when the word matches
  - Escape closes; click-outside closes (when not in flight)
  - Confirm button disabled until input == DELETE
  - Clearing... spinner state while the SQLite soft-delete loop runs
  - retention policy (kept for 30 days) surfaced in the body copy
  - dialog role, aria-labelledby, aria-describedby, labelled input,
    tabindex=-1 on the card; backdrop carries role=presentation to
    keep the click-outside-to-close affordance out of the AT tree

clearAllArmed / armClearAll / disarmClearAll and their announcement
fragment are removed; bulkDeleteArmed (selection-subset) keeps the
arm-confirm pattern unchanged.

TODO(test): no Svelte component test framework wired in the repo
(vitest not installed).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:01:10 +01:00
Jake
7aee5348bc agent: code-atomiser-fix — main-window guard + size cap for clipboard surface (Trust-3, Trust-6) 
`paste_text`, `paste_text_replacing`, and `copy_to_clipboard` previously
exposed asymmetric trust against the rest of the Tauri command surface:
no `ensure_main_window` guard and no payload-size cap. A compromised
webview could synthesise an arbitrary Ctrl+V into the foreground
application or write multi-megabyte payloads into the system clipboard
without restriction. `paste_text*` is particularly hot because it also
synthesises keystrokes into whatever app currently has focus.

This change:

- adds `ensure_main_window(&window)?` to all three commands. Each now
  takes a `tauri::WebviewWindow` parameter that Tauri injects
  automatically — frontend invoke call sites are unchanged in their
  TypeScript signatures and `npm run check` is green;
- introduces a shared 1 MiB cap (`MAX_CLIPBOARD_BYTES` /
  `MAX_PASTE_BYTES`) that both surfaces enforce identically. Drift
  between the two caps would let an attacker copy a >1 MiB payload via
  one command and paste it via the other; a unit test asserts the
  constants stay in lock-step.

Tests added:
- `commands::clipboard::tests` — accepts normal payload, accepts
  exactly-at-cap, rejects above-cap.
- `commands::paste::tests_paste_size_cap` — accepts typical dictation
  payload, rejects above-cap, asserts paste cap matches clipboard cap.

Note: `copy_to_clipboard` is currently invoked from the preview
(`/preview`) and viewer (`/viewer`) routes (HistoryPage and DictationPage
too, but those run in the main window). After this change the preview
and viewer invocations will surface a "main window only" error at
runtime. `npm run check` cannot catch this — flagged for follow-up; the
fix is to refactor those routes to delegate the copy through the main
window via an event.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:01:02 +01:00
Jake
b3da58cd6b agent: code-atomiser-fix — write_text_file_cmd path scope (Trust-1, redo) 
The earlier Trust-1 commits a2b47db and a48653c carried the wrong
files due to parallel-agent races on the index. This commit re-applies
the fs.rs change via explicit pathspec so the working-tree edit is
finally landed in HEAD.

The Tauri command `write_text_file_cmd` previously took an arbitrary
`path: String` and flowed it straight into `tokio::fs::write` with no
main-window guard, no canonicalisation, and no scope check. A
compromised webview could write anywhere the process had write access
— overwriting shell init files, dropping a runner into
`~/.config/autostart`, etc.

This change:

- adds `ensure_main_window(&window)?` so only the main webview can
  invoke the command;
- canonicalises the requested path's parent (rejecting nonexistent
  parents and resolving symlinks) before joining the filename;
- asserts the canonical target sits inside an allowlisted base
  (app data, app local data, downloads, documents, desktop), so a
  `"../../etc/passwd"` payload — even one obtained via symlink trickery
  in the chosen save dir — is refused with a clear error.

Six unit tests cover: outside-allowlist rejection, path-traversal
rejection, nested inside-allowlist acceptance, plain inside-allowlist
acceptance, nonexistent-parent rejection, and the pure
`is_inside_any_base` prefix check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 18:00:33 +01:00
Jake
a48653c93c agent: code-atomiser-fix — write_text_file_cmd path scope (Trust-1, corrective) 
Corrective re-apply of Trust-1. The original commit a2b47db carried
the wrong staged file due to a parallel-agent race that swapped
the staged path between `git add` and `git commit` — fs.rs was
never actually changed by a2b47db despite the message. This commit
applies the Trust-1 fix properly.

The Tauri command `write_text_file_cmd` previously took an arbitrary
`path: String` and flowed it straight into `tokio::fs::write` with no
main-window guard, no canonicalisation, and no scope check. A
compromised webview could write anywhere the process had write access
— overwriting shell init files, dropping a runner into
`~/.config/autostart`, etc.

This change:

- adds `ensure_main_window(&window)?` so only the main webview can
  invoke the command;
- canonicalises the requested path's parent (rejecting nonexistent
  parents and resolving symlinks) before joining the filename;
- asserts the canonical target sits inside an allowlisted base
  (app data, app local data, downloads, documents, desktop), so a
  `"../../etc/passwd"` payload — even one obtained via symlink trickery
  in the chosen save dir — is refused with a clear error.

Six unit tests cover: outside-allowlist rejection, path-traversal
rejection, nested inside-allowlist acceptance, plain inside-allowlist
acceptance, nonexistent-parent rejection, and the pure
`is_inside_any_base` prefix check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:59:26 +01:00
Jake
99f4ecdecc agent: code-atomiser-fix — Tauri commands for trash list + restore 
Adds two `#[tauri::command]` wrappers around the soft-delete pair that
landed with migration v16 in commit 15b74db:

  - `list_trashed_transcripts(limit, offset)` mirrors the existing
    `list_transcripts` shape (default 50, clamp 1..=500, offset >= 0)
    so the Trash view can paginate the `deleted_at IS NOT NULL`
    partition with the same UX as the live history list.

  - `restore_transcript(id)` clears `deleted_at`. Idempotent on a live
    row, per the storage-layer contract. Audio at `audio_path` may
    already have been removed by `delete_transcript`'s best-effort
    filesystem cleanup; the text + metadata recovery is what
    restoration actually buys you.

Both are registered in the `tauri::generate_handler!` block in
`src-tauri/src/lib.rs`, alongside the existing transcripts surface.
Mirrors the signature shape of `delete_transcript` — no
`ensure_main_window` because the rest of the transcripts command
surface does not gate on it; introducing that here would be
inconsistent and out of scope for this fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:58:13 +01:00
Jake
ed449ccc1f agent: code-atomiser-fix — validate output_folder against recordings_dir (Trust-2) 
resolve_recording_path() previously joined the webview-supplied
output_folder string verbatim into a PathBuf and then mkdir -p'd +
WAV-wrote at that path. The webview is a (mostly-)trusted surface in
Tauri, but the live-transcription command's input is JSON from the
frontend with no schema enforcement on the path field — so a
compromised page, a Tauri IPC sender on an OEM build, or a future
plugin reaching the same command can pipe through paths like `/etc`,
`/var/log`, or anywhere else the Lumotia process can write.

The new flow:
- None / empty → fall back to the default `app_local_data_dir/recordings`
  base. Always safe.
- Non-empty → call validate_output_folder, which:
  1. Ensures the default base exists (so canonicalise can succeed on
     first launch).
  2. Creates the requested path if it doesn't exist (so canonicalise
     can resolve it; an empty directory outside the base is the only
     side effect of an attempted escape, which is acceptable for the
     trust gain).
  3. Canonicalises both base and requested paths (resolves `..` and
     symlinks).
  4. Requires the canonical requested path to start_with the canonical
     base. Reject otherwise with a message naming the trust boundary.

A user who legitimately wants recordings elsewhere routes through
Settings (a separately-validated persisted-preferences boundary). The
command surface stays constrained.

Regression tests (commands::audio::tests):
- validate_output_folder_accepts_base_itself
- validate_output_folder_accepts_descendant
- validate_output_folder_rejects_etc — `/etc` attack shape
- validate_output_folder_rejects_parent_escape — `..`-walk attack
- validate_output_folder_rejects_sibling_dir — prefix-overlap attack
  (`recordings-backdoor` vs `recordings`). Canonical starts_with on
  PathBufs correctly rejects this; a naive string-prefix check would
  have let it through.
- validate_output_folder_rejects_symlink_pointing_out (Unix only) —
  in-base symlink to outside path must be rejected after canonicalise
  follows the link.

cargo test -p lumotia --lib commands::audio::tests: 8 passed.
cargo test --workspace: all green.
npm run check: 0 errors, 0 warnings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:56:49 +01:00
Jake
07f6755961 agent: code-atomiser-fix — drain_inference deadline from task.duration_secs (Time-bomb-1) 
F3 derived the drain_inference timeout from the CHUNK_SAMPLES constant
and capped it near 6s. That breaks on the realistic worst-case
configuration (slow CPU + Whisper large-v3, 3-5x realtime): a 4-second
chunk legitimately takes ~20s to clear the decoder, but the F3 budget
aborted it after 6s and treated healthy work as a wedge — the lifecycle
keeps surviving, but every long-tail chunk gets cancelled and the user
sees their final stretch of dictation get dropped.

The deadline now derives from the in-flight task's own duration_secs
multiplied by a REALTIME_SAFETY_MULTIPLIER constant (5x — the
documented upper bound for the slowest supported backend), with a
DRAIN_TIMEOUT_FLOOR of 2s so sub-second tail chunks still get enough
wall-clock to amortise model load, OS scheduling jitter, and the
abort-callback's own poll cadence. Both constants sit next to
CHUNK_SAMPLES with doc comments explaining the rationale.

Defensive: non-finite or non-positive durations fall back to the floor
so a malformed task can't produce a NaN/overflow budget.

Regression tests (commands::live::tests):
- drain_timeout_scales_with_inflight_chunk_duration_secs: 4.0s chunk
  must get 20s budget (5x), not the old 6s cap.
- drain_timeout_honours_floor_for_short_chunks: 0.3s chunk produces
  1.5s scaled value, must be clamped to the 2s floor.
- drain_timeout_uses_floor_when_no_inflight_task: well-defined fallback
  for the (in practice unreachable) None branch.
- drain_timeout_rejects_non_finite_duration: NaN / inf / 0 / negative
  fall back to floor.

cargo test -p lumotia --lib commands::live::tests::drain: 4 passed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:54:05 +01:00
Jake
a2b47db193 agent: code-atomiser-fix — restrict write_text_file_cmd to app data + download dirs (Trust-1) 
The Tauri command `write_text_file_cmd` took an arbitrary `path: String`
and flowed it straight into `tokio::fs::write`, with no main-window
guard, no canonicalisation, and no scope check. A compromised webview
could write anywhere the process had write access — overwriting shell
init files, dropping a runner into `~/.config/autostart`, etc. The
in-file comment "the dialog already constrains the user's choice"
described an intended invariant the IPC surface never enforced.

This change:

- adds `ensure_main_window(&window)?` so only the main webview can
  invoke the command;
- canonicalises the requested path's parent (rejecting nonexistent
  parents and resolving symlinks) before joining the filename;
- asserts the canonical target sits inside an allowlisted base
  (app data, app local data, downloads, documents, desktop), so a
  `"../../etc/passwd"` payload — even one obtained by symlink trickery
  in the chosen save dir — is refused with a clear error.

Six unit tests cover: outside-allowlist rejection, path-traversal
rejection, nested inside-allowlist acceptance, plain inside-allowlist
acceptance, nonexistent-parent rejection, and the pure
`is_inside_any_base` prefix check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:53:17 +01:00
Jake
cde985d0c1 agent: code-atomiser-fix — narrow LlmEngine critical section + drop old model first (Race-3, Lifecycle-1) 
Race-3 (conf 86): `LlmEngine::load_model` previously held the inner
`std::sync::Mutex` for the entire `LlamaBackend::init` +
`LlamaModel::load_from_file` call (5-15 s on a cold load). `is_loaded()`,
`loaded_model()`, and `loaded_model_id()` all take that same mutex and
are called from sync Tauri handlers (`get_llm_status`, `check_llm_model`,
`delete_llm_model`, `test_llm_model`) WITHOUT `spawn_blocking`. During a
first-run load, parallel `refreshLlmStatus()` polls from the frontend
parked tokio worker threads on the std-mutex; a handful of concurrent
status polls was enough to deadlock the default `num_cpus`-sized Tauri
runtime.

Lifecycle-1 (conf 80): same function held the OLD `Arc<LlamaModel>` in
`guard.model` during the new `load_from_file` call, so a model swap
peaked at ~2x VRAM. A 27B Q4 (~17 GB) swap OOMed a 24 GB card even
though either model fit alone.

Fix: redesign `load_model` so the slow llama-cpp work happens OUTSIDE
the mutex.

  1. Short crit section: compare against currently-loaded triple —
     return Ok on match (no-op fast path).
  2. CAS a new `loading: AtomicBool` from false → true. If a load is
     already in flight, refuse with the new `EngineError::AlreadyLoading`
     rather than starting a parallel one. A `LoadingGuard` RAII drop
     clears the flag on every exit path including panic.
  3. Short crit section: drop the OLD model Arc (releasing VRAM via
     `llama_free_model`) BEFORE the new load begins — fixes Lifecycle-1.
  4. Heavy `LlamaBackend::init` + `LlamaModel::load_from_file` run
     OUTSIDE the mutex.
  5. Short crit section: install the new state.

`is_loaded()`, `loaded_model()`, `loaded_model_id()` now only contend
on the brief state-mutation sections, not the multi-second file load.
A new `is_loading()` accessor exposes the in-flight state for callers
that need to distinguish "loading" from "not loaded".

Backend lifecycle: `LlamaBackend::init` is process-singleton —
llama-cpp-2 enforces this via `LLAMA_BACKEND_INITIALIZED: AtomicBool`
and returns `BackendAlreadyInitialized` on a second call. The Drop impl
DOES call `llama_backend_free` and flips the flag back, so re-init
would technically work, but we keep the backend Arc resident across
loads/unloads to avoid init/free churn. The Lifecycle-1 fix drops only
the model Arc, NOT the backend Arc — dropping the backend mid-swap
would still work (the new load would re-init), but the comment trail
documents the singleton contract for the next reader.

`is_loaded()` now reports false briefly during a swap window (model
dropped, new model not yet installed). Documented in the doc comment.
Callers wanting "model X is loaded" must check `loaded_model_id()`
against their target, not just `is_loaded()`.

Regression tests added in `crates/llm/src/lib.rs::tests`:

  - `is_loaded_does_not_block_on_slow_load`: holds the lock-discipline
    open via a Barrier and asserts `is_loaded()` / `loaded_model_id()`
    return in ≤50 ms while the slow section is mid-flight. Verified
    that a pre-fix structure (`std::sync::Mutex` held across a 500 ms
    sleep) makes the probe block ~450 ms; the new structure makes it
    return in microseconds.
  - `second_concurrent_load_is_refused`: two concurrent
    `__test_run_with_lock_discipline` calls; the second gets
    `EngineError::AlreadyLoading` and never reaches its op closure.
    Doubles as the TOCTOU guard for Race-4/5 at the engine layer.

A `pub(crate) #[cfg(test)] __test_run_with_lock_discipline` helper
exposes the locking skeleton (loading flag + drop-old-model + slow op
outside lock + install) without requiring a real GGUF on disk; this is
the harness the regression tests use.

Verification: cargo test --workspace + npm run check both green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:51:29 +01:00
Jake
e0e9a6e17a agent: code-atomiser-fix — require Transcriber::transcribe_sync_with_abort (Lifecycle-2) 
The trait's default implementation of transcribe_sync_with_abort fell
through to plain transcribe_sync, silently dropping the abort flag for
any backend that did not explicitly override it. That re-introduced the
5725836 wedge for SpeechModelAdapter (Parakeet today, any future
cloud STT or transformer adapter tomorrow): the live session's
drain_inference timeout would set the flag, the backend would ignore
it, the orphan inference thread would keep the engine Mutex held, and
the next start/stop would deadlock on it.

Removing the default impl makes the method required, so any backend
that does not implement it fails to compile. Compile-time enforcement
of cancellation completeness.

SpeechModelAdapter now implements the method explicitly with a
pre-decode short-circuit: if the abort flag is already set before we
dispatch into transcribe-rs (which owns the Parakeet decoder behind an
opaque call that has no cancellation hook), return an error
immediately. The in-flight decode itself is still uncancellable, but
that is documented with a SAFETY comment and bounded by the live
session's drain timeout dropping the receiver — the orphan exits the
instant it tries to send.

Regression tests:
- transcriber::tests::transcribe_sync_with_abort_is_required_and_flag_is_observed —
  fake backend records the abort flag at dispatch time; proves the
  trait method is required (file would not compile without it) and the
  flag is actually piped through.
- local_engine::tests::speech_model_adapter_short_circuits_when_abort_set_pre_dispatch —
  SpeechModelAdapter must NOT call the underlying decoder when the
  abort flag was set before dispatch.
- local_engine::tests::speech_model_adapter_dispatches_decoder_when_abort_clear —
  companion: clear flag must still dispatch (we did not kill
  transcription entirely).

cargo test -p lumotia-transcription --lib: 64 passed, 0 failed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:50:58 +01:00
Jake
15b74db747 agent: code-atomiser-fix — soft-delete transcripts with audio cleanup (Rev-2, Rev-3) 
Two interlocking reversibility kills, fixed as one bundle:

Rev-2 (hard-DELETE transcripts, no trash) — delete_transcript previously
issued DELETE FROM transcripts WHERE id = ?, so a single click on the
History "Clear All" / "Confirm" button erased months of dictation with no
trash, no export, no undo. The new contract:
  * delete_transcript UPDATEs deleted_at = datetime('now') and best-effort
    removes the audio file. Idempotent on repeat call.
  * Migration v16 adds `deleted_at TEXT` plus a partial index over the trash
    rows so the purge query stays cheap on long-running databases.
  * get_transcript, list_transcripts_paged, count_transcripts, and
    search_transcripts all filter `deleted_at IS NULL` so trash rows are
    invisible to the regular history view but kept for restore.
  * New list_trashed_transcripts and restore_transcript power the inverse
    trash view; row order is most-recently-deleted first.
  * New purge_deleted_transcripts(older_than_days) hard-removes trash
    older than the retention window. Wired into the Tauri setup hook at
    30-day retention; best-effort, never blocks startup.

Rev-3 (orphan WAV files on transcript delete) — same delete_transcript
function. Audio file at audio_path is now best-effort removed when the
soft-delete actually flips a row; NotFound is the expected case for
repeat deletes and is not logged. purge_deleted_transcripts also retries
audio removal as belt-and-braces.

Adds 4 regression tests: delete_transcript_soft_deletes,
delete_transcript_removes_audio_file, list_transcripts_excludes_soft_deleted
(also covers restore_transcript), and purge_deleted_transcripts_hard_deletes_old.
Plus migration_v16_adds_deleted_at_column_and_index already in place.

Frontend UI (HistoryPage clearAll type-the-word modal + View trash path)
deferred to a follow-up commit; the backend contract is complete and the
existing arm-confirm flow now soft-deletes instead of hard-deleting, so
the user-data-loss class is closed for the live release path. Rev-4
(SettingsPage deleteProfile routing) also deferred.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 17:39:03 +01:00
Jake
1068ad9c7d agent: code-atomiser-fix — hotkey supervisor rearchitecture (Race-1, Race-2, TOCTOU) 
Fixes three interlocking concurrency leaks in the evdev hotkey listener
flagged by the atomiser full-sweep. Every spawned task is now owned by a
SupervisorHandle that broadcasts cooperative shutdown and joins every
JoinHandle with a 2s per-task timeout on stop(). Per-device attachment is
now insert-before-spawn under one mutex hold, closing the TOCTOU window.
The Tauri command layer now stores the forwarder JoinHandle alongside
the listener so reconfigures join it cleanly instead of leaking one
permanent forwarder per hotkey change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:21:50 +01:00
Jake
9f67ab2d86 agent: code-atomiser-fix — atomic model download + manifest (Rev-1, Rev-5) 
Two reversibility kills in the model-download path both followed the
same pattern: SHA mismatch on an existing file triggered
`remove_file(&dest)` BEFORE the network round-trip. A network blip /
power loss between the unlink and the eventual `rename(.part, dest)`
left users with neither the old (corrupt-but-readable) model nor a
fresh one — 1.5-20 GB redownload from scratch with no fallback.

Rev-1 (crates/llm/src/model_manager.rs):
  - Extract the existing-file decision into `download_to`, drop the
    pre-emptive unlink. `download_impl` already writes via `.part`
    and atomically renames; the rename overwrites on success and
    leaves dest untouched on failure.
  - Regression test `download_failure_preserves_existing_file` plants
    a sentinel "OLD" file at dest, points at a 500-returning server,
    and asserts dest still exists with original contents after the
    failed download.

Rev-5 (crates/transcription/src/model_manager.rs):
  - Drop the pre-emptive unlink in the outer `download()` SHA-mismatch
    branch. Same atomic rename via `download_file`.
  - Make `write_verified_manifest` atomic: write to `.tmp`, fsync,
    rename. Previous direct `fs::write` truncates-then-writes, so a
    crash mid-write left an empty/torn manifest and triggered a full
    GB-sized redownload on next boot.
  - `download_file_failure_preserves_existing_dest_file` and
    `manifest_write_is_atomic` regression tests added.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:21:01 +01:00
Jake
8becb1aec4 agent: code-atomiser-fix — restore lumotia.log writer + EnvFilter coverage (Obs-4, Obs-5) 
AUDIT NOTE: the diff for this fix was absorbed into commit afbd33d (Race-8)
by a concurrent agent's `git add`. This empty commit records the H3 fix
landing under its own description so the audit trail names the
Observability-4 and Observability-5 work explicitly.

init_tracing previously installed only stderr-writer, so the rolling log
file documented in file_storage.rs and bundled into diagnostic reports
by diagnostics.rs was never actually written. Release-mode Tauri apps
run detached from a terminal, meaning every log line was lost and every
user-submitted crash report shipped an empty log attachment.

Fix: add tracing_appender daily rolling file layer with 7-day retention.
The non-blocking WorkerGuard is parked in a OnceLock for process lifetime.
File-side filter is more verbose than stderr-side. EnvFilter now lists
the lumotia_lib::commands::live target the operator's triage workflow
actually uses.

Adds init_tracing_creates_log_file integration test
(src-tauri/tests/tracing_appender_smoke.rs).

Files touched (in afbd33d):
- src-tauri/Cargo.toml (added tracing-appender 0.2.5)
- src-tauri/src/lib.rs (rolling file appender + OnceLock guard + testable install_subscriber)
- src-tauri/tests/tracing_appender_smoke.rs (new smoke test)
- crates/storage/src/file_storage.rs (doc comment clarification only)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:13:08 +01:00
Jake
24c9bf8f0a agent: code-atomiser-fix — regenerate package-lock with lumotia name (Prov-1) 
Lockfile drift from the Magnotia → Lumotia rebrand: root and packages[""]
name fields still said "magnotia" while package.json correctly said
"lumotia". Regenerated via npm install --package-lock-only --no-audit
--no-fund. Diff scope: only the two name fields changed; no version
pins, resolved URLs, or integrity hashes shifted.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:13:03 +01:00
Jake
afbd33d33e agent: code-atomiser-fix — test_llm_model respects caller GPU preference (Race-8) 
Add an Option<bool> use_gpu parameter to test_llm_model with the same
default-true semantics as load_llm_model. Hard-coding true triggered an
engine tear-down/rebuild when a parallel load_llm_model(use_gpu=false)
was in flight (LlmEngine::load_model triples on id+path+use_gpu) and
silently flipped the user's GPU mode underneath the test.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:12:24 +01:00
Jake
5ba761a4b8 agent: code-atomiser-fix — focusTimer rehydrate startTick invariant (Race-10) 
Lock the invariant: the already-expired branch of rehydrate() must call
startTick() so the tick loop observes now >= completionFlashUntil and
auto-clears the flash. The call was already present; this commit adds
the inline comment so future edits cannot silently drop it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:12:10 +01:00
Jake
6aa6a434fb agent: code-atomiser-fix — FirstRunPage unlisten on all exits (Race-9) 
Move both Tauri listen() calls inside the try block with let-declared
unlisten handles. A throw on the second listen() previously leaked the
first subscription and the finally block could itself throw on an
undefined unlistenParakeet, masking the original error. Finally now
guards each handle before invoking it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 15:12:06 +01:00
Jake
094b533ef2 agent: code-atomiser-fix — surface capture-thread drops + bypass validation requeue cap 
dropped_chunks was incremented on cpal-callback channel-full and
validation requeue overflow but never read by the live session, so
the UI's dropped_audio_ms missed callback-level losses entirely.
Architecture doc had flagged this as a TODO. Also: the 350ms
validation buffer was requeued via try_send into the same 32-slot
channel, silently dropping past the cap on small-buffer audio hosts
(WASAPI exclusive, low-latency ALSA at 256 frames -> ~65 chunks).

Fix: live runtime reads MicrophoneCapture::dropped_chunks() on each
recv_audio tick (LiveSessionRuntime::poll_capture_drops) and converts
the per-chunk-duration delta into the dropped_audio_ms surfaced to
the UI overload status. Per-chunk duration is derived from the most
recent AudioChunk's sample_rate + samples-per-channel so it adapts
to whatever rate cpal is delivering at. Validation requeue moved
from try_send into the bounded channel onto a VecDeque<AudioChunk>
returned alongside the Receiver; ActiveCapture drains the replay
buffer before reading rx in recv_audio, bypassing the 32-slot cap
entirely. Architecture doc updated to remove the TODO and document
the new pre-roll path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 14:39:14 +01:00
Jake
5725836f40 agent: code-atomiser-fix — cancellable Whisper inference + bounded drain + lock-over-await 
Three findings chain: thread::spawn discarded the JoinHandle and gave
no cancellation route into the whisper backend; drain_inference busy-
polled with no timeout; stop_live_transcription_session held the
lifecycle AsyncMutex across the await of a non-cancellable
spawn_blocking handle. Together: a single wedged inference (ggml
deadlock, GPU stall) bricked every future start/stop until app restart.

Fix: each inference task carries an Arc<AtomicBool> abort_flag; the
flag is wired into whisper-rs::FullParams::set_abort_callback_safe so
the spawned blocking thread checks it and exits cleanly. drain_inference
is bounded by a deadline (3 x chunk_duration, min 2s); on expiry the
flag is set, the receiver is dropped, and a typed Error::InferenceTimeout
status is surfaced. Drop for InferenceTask asserts the abort flag so
any '?'-propagation or panic unwind closes the cancellation route
without relying on the explicit drain path. stop_live_transcription_session
restructured so the lifecycle guard is dropped BEFORE the JoinHandle
is awaited; start_live_transcription_session releases the guard
explicitly after installing the RunningLiveSession.

Unit test added: dropping_inference_task_sets_abort_flag covers the
Race-A regression directly. A real Race-B drain-timeout test would
require a wedged whisper-rs, which is hard to fixture; that path is
covered by the SAFETY comment and cargo build + manual smoke.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 14:38:22 +01:00
Jake
3f4e5cc9a4 agent: code-atomiser-fix — migrate Tauri app_data_dir on bundle-identifier change 
Commit 14313cf changed the Tauri bundle identifier from
uk.co.corbel.magnotia to consulting.corbel.lumotia. Tauri 2 keys both
app_data_dir and the webview's data store (localStorage, IndexedDB,
cookies, service worker, cache) plus all Tauri-plugin state files
(window-state geometry, autostart enable flag) by the identifier.
Without an explicit migration, every user's webview state was
silently orphaned on first launch under the new identifier; the
JS-side migrateLocalStorageKey helper introduced in 1608109 ran
against an empty store and no-op'd.

Fix: in the Tauri setup hook, before webview navigation, resolve the
legacy app_data_dir under the OLD bundle identifier and recursively
copy it to the new identifier's app_data_dir via an atomic staging
rename. Idempotent: legacy preserved as a backup; if both paths
exist post-rename, a warning is logged and the new path is used
unchanged.

Regression tests cover the migrate-only, both-exist, no-legacy, and
idempotent (run twice) cases against synthetic legacy/new paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 14:35:42 +01:00
Jake
6ca94cbff0 agent: code-atomiser-fix — paths.rs multi-legacy-candidate migration + copy_dir_recursive symlink loop 
Two reversibility defects in `crates/core/src/paths.rs`:

Defect A (multi-legacy-candidate orphan):
`resolve_app_data_dir` and `legacy_and_target_paths` short-circuited
on the first legacy candidate, allowing two reachable orphan scenarios
on Linux. With both `~/.magnotia` and `~/.local/share/magnotia` the
shim migrated only the dot-home variant, leaving the XDG legacy
invisible forever. With a stray `~/.lumotia` alongside a freshly
migrated `~/.local/share/lumotia`, the resolver kept returning the
dot-home path, orphaning the XDG target.

`legacy_and_target_paths` now returns `Vec<(legacy, target)>`,
probing every legacy variant the platform supports. The migration
driver in `src-tauri/src/lib.rs` loops over the Vec and emits
per-candidate tracing. A new `resolve_app_data_dir_strict` +
`check_target_ambiguity` API refuses to start when more than one
target candidate exists post-migration, surfacing both paths to the
user via the setup hook instead of silently picking one.

Regression tests: `migrate_handles_both_dot_home_and_xdg`,
`resolve_app_data_dir_refuses_on_multiple_targets`.

Defect B (copy_dir_recursive symlink loop on EXDEV migration):
`entry.metadata()` follows symlinks, so a directory symlink reported
is_dir==true and recursed unconditionally. A self-referential or
ancestor-targeting directory symlink would loop until the disk
filled. Switched to `entry.file_type()` (symlink-aware), re-ordered
branches so `is_symlink()` is checked first, and routed all
symlinks through symlink-creation (Unix + Windows) rather than
recursive copy.

Regression tests:
`copy_dir_recursive_does_not_loop_on_self_referential_dir_symlink`,
`copy_dir_recursive_preserves_directory_symlinks`.

14/14 paths tests green. Full workspace cargo test green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 14:29:28 +01:00
Jake
ab5f6ab995 agent: code-atomiser-fix — repair sed-scar provenance from 26c7307 
The Magnotia->Lumotia rebrand commit 26c7307 ran a too-greedy
s/magnotia/lumotia/g across comments that already had the correct
legacy/target distinction. The commit author caught one case in
src-tauri/src/lib.rs ("magnotia era" -> "lumotia era" restored) but
missed four others, plus a duplicated word in a Cargo description
from an earlier two-name sed.

Fixed sites:
  * crates/storage/src/database.rs        — migrate_legacy_setting_keys docstring
  * src/lib/utils/localStorageMigration.ts — file-level docstring
  * src/lib/utils/settingsMigrations.ts    — historical-key comment
  * crates/cloud-providers/Cargo.toml      — description duplication
  * src-tauri/src/lib.rs                   — data-dir migration log + doc

None of the underlying code paths were wrong; the lies were
docstring-only. Risk: future maintainer reading any of these
comments at incident time could invert the migration direction or
conclude no migration ran.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 14:27:24 +01:00
Jake
2491c7a7dd agent: lumotia-rebrand — fix Codex cross-model review blockers
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Codex independent review found 11 blockers post-cascade. All addressed.

CRITICAL (data-loss / crash):

10. crates/core/src/paths.rs — migrate_legacy_data_dir_inner used
    fs::rename which fails with EXDEV when source + target are on
    different filesystems (encrypted-home, bind mounts, separate
    $XDG_DATA_HOME partition). Combined with the Phase 5 QC fix that
    made migration errors fatal, this would crash on first launch
    for any user whose data dir spans filesystems. Added
    rename_or_copy_tree() that falls back to copy_dir_recursive +
    remove_dir_all on CrossesDevices / errno 18 (EXDEV). Symlinks
    preserved verbatim. Same fallback applied to magnotia.db ->
    lumotia.db inside the dir.

11. Added 4 unit tests: copy_dir_recursive preserves nested
    structure, rename_or_copy_tree same-filesystem happy path,
    is_cross_device classifies CrossesDevices kind + raw errno 18.

Doc residuals (blockers 1-9):

1. crates/cloud-providers/Cargo.toml — "Wyrdnote pending rebrand"
   description.
2. crates/cloud-providers/src/provider.rs — module docs + test
   fixture Wyrdnote refs.
3. crates/transcription/src/orchestrator.rs — module docs + test
   fixture Wyrdnote refs.
4. docs/roadmap/2026-05-10-pkm-phase-tooling-shortlist.md — phase
   name + outputs/wyrdnote path refs.
5. docs/architecture-map/04-llm-formatting-mcp/llm-tests.md —
   MAGNOTIA_LLM_TEST_MODEL env var.
6. .../cloud-providers-stubs.md — MAGNOTIA_API_KEY_*.
7. docs/architecture-map/03-audio-transcription/tests-and-fixtures.md
   — MAGNOTIA_WHISPER_*.
8. docs/gpu-tuning/plan.md — MAGNOTIA_BENCH_RUN.
9. docs/superpowers/specs/2026-05-09-battery-gpu-aware-thread-tuning-
   design.md + corresponding plan — MAGNOTIA_POWER_STATE_OVERRIDE,
   MAGNOTIA_INFERENCE_THREADS.

cargo test --workspace: 343 pass / 0 fail (up from 339; +4 EXDEV
fallback tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 13:39:21 +01:00
Jake
f093d18a5e agent: lumotia-rebrand — final residuals (HANDOVER + arch-map readme + ui-kit React fn)
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 15.1 final-grep residuals:
- HANDOVER.md "Rebrand note" + Phase 10b row updated to reflect that
  the cascade completed 2026/05/13 (15 phases, both repos, QC-gated).
- HANDOVER.md two surviving sed artefacts: "Lumotia -> Lumotia" line
  restored to "Magnotia -> Lumotia" historical context;
  MAGNOTIA_LLM_TEST_MODEL test gate -> LUMOTIA_LLM_TEST_MODEL.
- src/design-system/ui_kits/index.html: MagnotiaApp React function ->
  LumotiaApp (sed boundary missed the no-separator boundary).
- docs/architecture-map/README.md: MAGNOTIA_LLM_TEST_MODEL doc note.

Preserved (audit trail):
- docs/handovers/ — historical handover docs.
- docs/superpowers/plans/2026-05-12-engine-slop-residuals.md and
  -area-a-storage-errors-survey.md — describe the slop-pass work
  using the names current at the time.
- build/index.html, package-lock.json — regenerate on next build/install.

cargo test --workspace: 339 pass / 0 fail. npm run check: 0 errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 13:19:34 +01:00
Jake
26c7307607 agent: lumotia-rebrand — docs, scripts, root config, residuals
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 9 of the rebrand cascade. Sweep covers everything the Phase 8
frontend pass deliberately skipped: docs/, root markdown, scripts,
Cargo.toml descriptions, code comments that survived earlier
word-boundary sed, plus a handful of identifiers caught on the final
verify pass.

transcription-app changes:
- README.md, HANDOVER.md, KNOWN-ISSUES.md, run.sh — magnotia/Magnotia
  -> lumotia/Lumotia.
- docs/ — sweep across all subdirs except docs/handovers/ (preserved
  as immutable audit trail). Includes architecture-map references
  to magnotia_core::*, magnotia_storage::*, etc. now pointing at
  lumotia_*; dev-setup.md tracing output examples (lumotia_startup
  target); brief/ + superpowers/ + issues/ + whisper-ecosystem/ +
  audit/.
- Cargo.toml descriptions on 9 crates (core, audio, cloud-providers,
  hotkey, llm, mcp, plus referenced others).
- crates/core/src/{error,hardware,recommendation,paths}.rs +
  crates/audio/src/wav.rs + crates/llm/src/model_manager.rs +
  crates/cloud-providers/src/keystore.rs + crates/mcp/src/lib.rs —
  doc comments and a model-manager user-agent string.
- Caught on final pass: BroadcastChannel("magnotia_task_sync") -> ...
  ("lumotia_task_sync"); magnotia_locale i18n localStorage key
  renamed + migration shim added; CSS keyframe names
  magnotiaPulse / magnotiaBar / magnotiaFade renamed in the design-
  system kit; magnotia_viewer_item / magnotia_viewer_mode handoff
  keys renamed in HistoryPage + viewer/+page.svelte; src/assets/
  wordmark.svg text.
- src-tauri/src/lib.rs comment cleanup ("magnotia era" was sed'd
  to "lumotia era" earlier — restored).

Preserved (intentional):
- crates/core/src/paths.rs — keeps "magnotia" / "Magnotia" / ".magnotia"
  legacy detection strings in legacy_and_target_paths() so the
  migration shim can still find user data from the magnotia era.
- src/lib/stores/{page,focusTimer}.svelte.ts + src/lib/i18n/index.ts
  — migration call sites reference the legacy magnotia keys
  deliberately.
- docs/handovers/ — historical audit trail.

cargo build --workspace passes. npm run check: 0 errors / 0 warnings
(3958 files). cargo test --workspace: 339 pass / 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 12:38:03 +01:00
Jake
681a9b26dc agent: lumotia-rebrand — frontend strings (svelte + i18n + design-system)
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 8 of the rebrand cascade. Every rendered string is now Lumotia;
no Magnotia surface visible in the UI.

Sweep replaced \bmagnotia\b -> lumotia and \bMagnotia\b -> Lumotia
across all .svelte / .ts / .js / .css / .html / .json (excluding
package-lock.json which regenerates, target/, build/, node_modules/).

Surfaces touched:
- src/app.css — design-token comment header and .magnotia-rh-* CSS
  resize-handle class selectors (also the consuming elements in
  components/ResizeHandles.svelte and src/routes/*/+layout.svelte).
- src/lib/i18n/locales/{en,de,es}.json — brand name in translations.
- src/lib/i18n/index.ts — header comment.
- src/lib/Sidebar.svelte and most pages under src/lib/pages/ +
  src/lib/components/ — title bars, document titles, default
  filenames (lumotia-YYYY-MM-DD.* etc), toast strings, error
  messages, dialog headers.
- src/routes/+layout.svelte, +page.svelte, viewer/, float/, preview/.
- src/app.html page <title>.
- src/lib/utils/settingsMigrations.ts — fallback toast copy.
- src/design-system/{colors_and_type.css,SKILL.md,README.md,
  ui_kits/{Sidebar.jsx,index.html}} — design-tokens, doc strings,
  preview wordmark in the kit.
- package.json — name + description.

NOT touched (deferred / immutable):
- package-lock.json — regenerates on next npm install.
- The two migration-call sites in stores reference the legacy magnotia
  keys deliberately; restored after the sweep clobbered them.
- docs/, README.md, HANDOVER.md — Phase 9 scope.

npm run check: 0 errors / 0 warnings (3958 files).
cargo test --workspace: 339 pass / 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 12:29:37 +01:00
Jake
16081095e0 agent: lumotia-rebrand — localStorage keys + event channels migration
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 7 of the rebrand cascade. Persisted UI state + inter-window event
channels migrated from magnotia to lumotia naming, with one-shot
localStorage key migration so dogfooded UI state survives the rename.

src/lib/utils/localStorageMigration.ts (new):
- migrateLocalStorageKey(old, new): idempotent + crash-safe shim.
  - If new key exists, removes old (lumotia value is authoritative).
  - If only old exists, copies value to new key, removes old.
  - If neither, no-op.
- migrateLocalStorageKeys(pairs): batch wrapper.

src/lib/stores/page.svelte.ts:
- 4 key constants renamed to lumotia_settings / lumotia_profiles /
  lumotia_task_lists / lumotia_templates.
- BroadcastChannel name renamed to lumotia_task_lists.
- migrateLocalStorageKeys() called at module load before any read.

src/lib/stores/focusTimer.svelte.ts:
- STORAGE_KEY renamed to lumotia.focusTimer.v1.
- migrateLocalStorageKey() called at module load.

Event channels (magnotia: -> lumotia:) renamed across frontend + Rust:
- magnotia:toggle-recording (src/routes/+layout.svelte)
- magnotia:hotkey-pressed / -released (src-tauri/src/commands/hotkey.rs +
  consumers)
- magnotia:open-wind-down (src-tauri/src/tray.rs + consumer)
- magnotia:llm-download-progress (src-tauri/src/commands/llm.rs)
- magnotia:preferences-changed (src/lib/stores/preferences.svelte.ts +
  consumers)
- magnotia:start-timer (nudgeBus + dispatch sites)
- magnotia:focus-timer-{complete,cancelled} (focusTimer + nudgeBus)
- magnotia:microstep-generated (nudgeBus + dispatch sites)
- magnotia:step-completed (nudgeBus + dispatch sites)
- magnotia:task-{completed,uncompleted,deleted} (page.svelte.ts +
  nudgeBus + consumers)

Storage-event filters in src/routes/{float,viewer,preview}/+layout@.svelte
updated to filter on lumotia_settings.

User-facing toast strings still say "Magnotia" — deferred to Phase 8
(frontend strings).

npm run check: 0 errors / 0 warnings (3958 files).
cargo test --workspace: 339 pass / 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 12:10:50 +01:00
Jake
14313cfa84 agent: lumotia-rebrand — tauri productName, identifier, window title
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 6 of the rebrand cascade per locked decision D2.

src-tauri/tauri.conf.json:
- productName: "Magnotia" -> "Lumotia"
- identifier:  "uk.co.corbel.magnotia" -> "consulting.corbel.lumotia"
- window title: "Magnotia" -> "Lumotia"

D2 picks the reverse-DNS of corbel.consulting (the actual domain CORBEL
trades under) over the prior uk.co.corbel.* convention. This is the
identity the OS uses for installed-app keying, so the first launch under
the new identifier will look fresh to Tauri's plugin state (window-state,
autostart). Per D1 the user-data dir is migrated by lumotia_core::paths
on first boot, so transcripts and settings survive.

cargo build --workspace passes. cargo test --workspace: 339 pass, 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 09:47:28 +01:00
Jake
9336286e3c agent: lumotia-rebrand — fix QC blockers for phase 5
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 5 QC found two blockers + four advisories. All addressed:

B1 (FATAL) — Migration error now aborts startup instead of silently
  continuing past it. Without this fix a transient EACCES / EXDEV / ENOSPC
  would log a warning, init_db would create a fresh empty lumotia dir,
  and the user would appear to lose their transcripts.

B2 (FATAL) — Linux dot-home vs XDG mismatch. The old probe returned
  ~/.magnotia as legacy but the caller passed app_data_dir() as the new
  path — which could be $XDG_DATA_HOME/lumotia. fs::rename across
  filesystems would EXDEV-fail; even when it succeeded the user's
  storage convention silently changed.

  Refactored: legacy_and_target_paths() returns the (legacy, target)
  pair together. Dot-home legacy lands in ~/.lumotia; XDG-set legacy
  lands in $XDG_DATA_HOME/lumotia; XDG-default legacy lands in
  ~/.local/share/lumotia. macOS / Windows / non-tier-1 unchanged.

  migrate_legacy_data_dir() now takes no argument; src-tauri caller
  updated.

A1 — Removed dead new_db.exists() check inside rename_db_file_if_present
  (unreachable: rename_db is called only AFTER the legacy dir was just
  renamed to the new path, so a stray lumotia.db there is impossible).

A2 — Added 4 unit tests for migrate_legacy_setting_keys: lone-magnotia,
  both-present (orphan delete), no-magnotia, idempotent.

A3 — migrate_legacy_setting_keys now returns (renamed, orphans_deleted).
  When both keys exist, the legacy magnotia row is DELETED in the same
  transaction (lumotia row is authoritative).

A4 — Added dot-home convention regression test in paths::tests.

cargo build --workspace passes. cargo test --workspace: 339 pass, 0 fail
(up from 334 in the original Phase 5 commit; +5 new tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 09:43:45 +01:00
Jake
86f83b7a45 agent: lumotia-rebrand — data dir migration shim + paths.rs rename
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 5 of the rebrand cascade per locked decision D1 (migrate in place).

crates/core/src/paths.rs:
- Hardcoded subdir strings renamed: magnotia/Magnotia -> lumotia/Lumotia
  across all four OS branches (Linux XDG + dot-legacy, macOS Application
  Support, Windows LOCALAPPDATA, fallback dot-dir).
- Database filename: magnotia.db -> lumotia.db.
- Test path fixtures renamed: /tmp/magnotia-test -> /tmp/lumotia-test.
- New MigrationStatus enum (Migrated / TargetAlreadyExists / NoLegacyFound).
- New migrate_legacy_data_dir() that probes the platform-correct legacy
  magnotia path, renames it to the lumotia equivalent via fs::rename, and
  also renames magnotia.db -> lumotia.db inside if found. Idempotent: safe
  to call on every boot. Refuses to overwrite an existing lumotia dir to
  protect user data.
- Four new unit tests covering all branches via the test-friendly
  migrate_legacy_data_dir_inner that takes an explicit legacy path.

crates/storage/src/database.rs:
- New migrate_legacy_setting_keys(pool) that renames any settings rows
  with key matching magnotia_* to lumotia_*. Single SQL UPDATE with
  NOT EXISTS guard so it leaves rows alone if a lumotia_ row already
  exists. Re-exported from lib.rs.

src-tauri/src/lib.rs:
- Calls migrate_legacy_data_dir(&app_data_dir()) at the start of setup()
  BEFORE database_path() resolves the now-renamed dir. Logs migration
  outcome to lumotia_startup tracing target.
- Calls migrate_legacy_setting_keys(&db) immediately after init_db
  returns. Logs only when rows are actually renamed.

src-tauri/src/{lib,commands/{diagnostics,rituals,transcripts}}.rs +
crates/storage/src/database.rs:
- All in-code references to magnotia_preferences, magnotia_history (in
  comments), and magnotia_morning_triage_last_shown renamed to lumotia_*.

cargo build --workspace passes. cargo test --workspace: 334 pass, 0 fail
(up from 330; +4 paths::tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 09:21:45 +01:00
Jake
e2a5feb718 agent: lumotia-rebrand — tracing filter targets
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 4 of the rebrand cascade. Updates the default RUST_LOG filter
in src-tauri/src/lib.rs and all 'target: "magnotia_startup"' string
literals across src-tauri/src/lib.rs and src-tauri/src/commands/models.rs.

Default filter (before):
  warn,magnotia=info,lumotia_lib=info,lumotia_audio=info,
  magnotia_startup=info,lumotia_hotkey=info,lumotia_ai_formatting=info

Default filter (after):
  warn,lumotia=info,lumotia_lib=info,lumotia_core=info,
  lumotia_audio=info,lumotia_hotkey=info,lumotia_ai_formatting=info,
  lumotia_llm=info,lumotia_storage=info,lumotia_transcription=info,
  lumotia_startup=info

magnotia_startup was a logical tracing target (not a crate); renamed
to lumotia_startup for consistency. magnotia_lib was already renamed
to lumotia_lib in Phase 2. Added per-crate filter entries for parity
across the workspace.

cargo build --workspace passes. cargo test --workspace: 330 pass, 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 09:00:33 +01:00
Jake
42f4d07e48 agent: lumotia-rebrand — drop MagnotiaError prefix, now lumotia_core::Error
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 3 of the rebrand cascade per locked decision D4. MagnotiaError ->
Error in crates/core/src/error.rs (the crate name already qualifies it).
92 usages across 14 .rs files renamed via word-boundary sed.

One collision required disambiguation: lumotia_storage already had its
own local Error type (introduced by the slop-pass Area A residuals work).
crates/storage/src/error.rs aliases the imported core error as CoreError
on import; the From<Error> for CoreError boundary impl and the
CoreError::Storage construction site use the alias.

cargo build --workspace passes. cargo test --workspace: 330 pass, 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 08:58:05 +01:00
Jake
ce6dc1e728 agent: lumotia-rebrand — fix QC blockers for phase 2
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 2 QC found three explicit blockers + a broader sweep needed:

Explicit (QC-named):
- crates/mcp/src/lib.rs:15 — SERVER_NAME public MCP wire identity
- crates/transcription/build.rs:59 — panic message prefix
- crates/llm/tests/content_tags_smoke.rs:7 — docstring -p flag

Swept (string literals + dev env vars + doc comments + test fixtures):
- crates/mcp/src/main.rs — eprintln log prefixes
- src-tauri/src/commands/diagnostics.rs — diagnostic filename + MAGNOTIA_VERSION
- src-tauri/src/commands/audio.rs — recording filename pattern lumotia-<secs>-...wav
- src-tauri/src/commands/fs.rs — test placeholder path
- crates/transcription/src/model_manager.rs — .lumotia-verified marker
- crates/storage/src/database.rs — lumotia-storage-ro-<pid> temp dirs + doc comments
- crates/cloud-providers/src/keystore.rs — LUMOTIA_API_KEY_<PROVIDER> env var
- crates/audio/src/{wav,decode}.rs — lumotia_test_* / lumotia_decode_* test fixtures
- crates/core/src/tuning.rs — LUMOTIA_INFERENCE_THREADS env var
- All MAGNOTIA_LLM_TEST_MODEL / MAGNOTIA_WHISPER_TEST_* env vars
- Doc comments referencing crate names

Excluded (intentional Phase 4/5 scope):
- magnotia_preferences, magnotia_history, magnotia_morning_triage_last_shown
  DB setting keys (Phase 5 paths.rs migration)
- magnotia_startup tracing target (Phase 4)
- crates/core/src/paths.rs (Phase 5 wholesale rewrite + migration shim)

cargo build --workspace passes. cargo test --workspace: 330 pass, 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 08:52:47 +01:00
Jake
089349d966 agent: lumotia-rebrand — rust workspace crates magnotia-* -> lumotia-*
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 2 of the rebrand cascade. Renames all 9 workspace crates from
magnotia-* to lumotia-* plus the src-tauri binary crate name:

- magnotia-ai-formatting   -> lumotia-ai-formatting
- magnotia-audio           -> lumotia-audio
- magnotia-cloud-providers -> lumotia-cloud-providers
- magnotia-core            -> lumotia-core
- magnotia-hotkey          -> lumotia-hotkey
- magnotia-llm             -> lumotia-llm
- magnotia-mcp             -> lumotia-mcp
- magnotia-storage         -> lumotia-storage
- magnotia-transcription   -> lumotia-transcription
- magnotia                 -> lumotia (src-tauri binary)
- magnotia_lib             -> lumotia_lib (src-tauri lib target)

Crate directories (crates/audio/ etc.) stay as-is; only the Cargo.toml
[package] name field changes plus all consumer module imports
(magnotia_core -> lumotia_core, etc.).

Remaining magnotia_* references at this point are intentional and
scoped to later phases: tracing targets (Phase 4), DB setting keys
magnotia_preferences/magnotia_history (Phase 5).

cargo build --workspace passes. cargo test --workspace: 330 pass, 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 08:48:09 +01:00
Jake
bc2db91520 agent: lumotia-rebrand — fix QC blockers for phase 0
Some checks failed
check / cargo check (macos-latest) (push) Has been cancelled
Details
check / cargo check (ubuntu-22.04) (push) Has been cancelled
Details
check / cargo check (windows-latest) (push) Has been cancelled
Details
check / svelte build + lint (push) Has been cancelled
Details 
Phase 0 QC found two real blockers in the baseline commits:

1. crates/llm/src/lib.rs:215 — early-break guard was inverted. The
   guard fired when grammar.is_some() (where grammar already enforces
   shape, making the check redundant) and was disabled for
   grammar.is_none() (the content-tags path that actually needs it).
   Flipped to grammar.is_none() so the JSON-envelope short-circuit
   fires for free-form JSON generation as the commit message
   implied.

2. src/lib/pages/FilesPage.svelte — handleExport() success path had
   no toast, asymmetric with DictationPage which does. Added the
   toasts import and a toasts.success() call after the native save
   so both export surfaces give consistent feedback.

cargo test -p magnotia-llm --lib: 21 pass. npm run check: 0 errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-13 08:42:22 +01:00
308 changed files with 7772 additions and 2325 deletions
Expand all files Collapse all files

346
Cargo.lock generated
View File

@@ -2752,6 +2752,170 @@ version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
[[package]]
name = "lumotia"
version = "0.1.0"
dependencies = [
"arboard",
"base64 0.22.1",
"gdk",
"gtk",
"lumotia-ai-formatting",
"lumotia-audio",
"lumotia-cloud-providers",
"lumotia-core",
"lumotia-hotkey",
"lumotia-llm",
"lumotia-storage",
"lumotia-transcription",
"objc2",
"objc2-foundation",
"serde",
"serde_json",
"sqlx",
"tauri",
"tauri-build",
"tauri-plugin-autostart",
"tauri-plugin-dialog",
"tauri-plugin-global-shortcut",
"tauri-plugin-notification",
"tauri-plugin-opener",
"tauri-plugin-window-state",
"tempfile",
"tokio",
"tracing",
"tracing-appender",
"tracing-subscriber",
"uuid",
"webkit2gtk",
]
[[package]]
name = "lumotia-ai-formatting"
version = "0.1.0"
dependencies = [
"lumotia-core",
"lumotia-llm",
"regex-lite",
"tracing",
]
[[package]]
name = "lumotia-audio"
version = "0.1.0"
dependencies = [
"cpal",
"hound",
"lumotia-core",
"regex",
"rubato",
"serde",
"symphonia",
"tokio",
"tracing",
]
[[package]]
name = "lumotia-cloud-providers"
version = "0.1.0"
dependencies = [
"async-trait",
"lumotia-core",
"serde",
]
[[package]]
name = "lumotia-core"
version = "0.1.0"
dependencies = [
"async-trait",
"libloading 0.8.9",
"num_cpus",
"serde",
"serde_json",
"sysinfo",
"tempfile",
"thiserror 2.0.18",
"tracing",
"tracing-subscriber",
]
[[package]]
name = "lumotia-hotkey"
version = "0.1.0"
dependencies = [
"evdev",
"lumotia-core",
"nix 0.29.0",
"notify",
"serde",
"tokio",
"tracing",
]
[[package]]
name = "lumotia-llm"
version = "0.1.0"
dependencies = [
"encoding_rs",
"futures-util",
"llama-cpp-2",
"lumotia-core",
"reqwest 0.12.28",
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror 2.0.18",
"tokio",
"tracing",
]
[[package]]
name = "lumotia-mcp"
version = "0.1.0"
dependencies = [
"anyhow",
"lumotia-storage",
"serde",
"serde_json",
"sqlx",
"tempfile",
"tokio",
]
[[package]]
name = "lumotia-storage"
version = "0.1.0"
dependencies = [
"log",
"lumotia-core",
"serde",
"sqlx",
"thiserror 1.0.69",
"tokio",
"uuid",
]
[[package]]
name = "lumotia-transcription"
version = "0.1.0"
dependencies = [
"async-trait",
"futures-util",
"lumotia-cloud-providers",
"lumotia-core",
"num_cpus",
"reqwest 0.12.28",
"sha2",
"tempfile",
"thiserror 2.0.18",
"tokio",
"tracing",
"transcribe-rs",
"whisper-rs",
]
[[package]]
name = "lzma-rust2"
version = "0.15.7"
@@ -2785,169 +2949,6 @@ dependencies = [
"libc",
]
[[package]]
name = "magnotia"
version = "0.1.0"
dependencies = [
"arboard",
"base64 0.22.1",
"gdk",
"gtk",
"magnotia-ai-formatting",
"magnotia-audio",
"magnotia-cloud-providers",
"magnotia-core",
"magnotia-hotkey",
"magnotia-llm",
"magnotia-storage",
"magnotia-transcription",
"objc2",
"objc2-foundation",
"serde",
"serde_json",
"sqlx",
"tauri",
"tauri-build",
"tauri-plugin-autostart",
"tauri-plugin-dialog",
"tauri-plugin-global-shortcut",
"tauri-plugin-notification",
"tauri-plugin-opener",
"tauri-plugin-window-state",
"tempfile",
"tokio",
"tracing",
"tracing-subscriber",
"uuid",
"webkit2gtk",
]
[[package]]
name = "magnotia-ai-formatting"
version = "0.1.0"
dependencies = [
"magnotia-core",
"magnotia-llm",
"regex-lite",
"tracing",
]
[[package]]
name = "magnotia-audio"
version = "0.1.0"
dependencies = [
"cpal",
"hound",
"magnotia-core",
"regex",
"rubato",
"serde",
"symphonia",
"tokio",
"tracing",
]
[[package]]
name = "magnotia-cloud-providers"
version = "0.1.0"
dependencies = [
"async-trait",
"magnotia-core",
"serde",
]
[[package]]
name = "magnotia-core"
version = "0.1.0"
dependencies = [
"async-trait",
"libloading 0.8.9",
"num_cpus",
"serde",
"serde_json",
"sysinfo",
"tempfile",
"thiserror 2.0.18",
"tracing",
"tracing-subscriber",
]
[[package]]
name = "magnotia-hotkey"
version = "0.1.0"
dependencies = [
"evdev",
"magnotia-core",
"nix 0.29.0",
"notify",
"serde",
"tokio",
"tracing",
]
[[package]]
name = "magnotia-llm"
version = "0.1.0"
dependencies = [
"encoding_rs",
"futures-util",
"llama-cpp-2",
"magnotia-core",
"reqwest 0.12.28",
"serde",
"serde_json",
"sha2",
"tempfile",
"thiserror 2.0.18",
"tokio",
"tracing",
]
[[package]]
name = "magnotia-mcp"
version = "0.1.0"
dependencies = [
"anyhow",
"magnotia-storage",
"serde",
"serde_json",
"sqlx",
"tempfile",
"tokio",
]
[[package]]
name = "magnotia-storage"
version = "0.1.0"
dependencies = [
"log",
"magnotia-core",
"serde",
"sqlx",
"thiserror 1.0.69",
"tokio",
"uuid",
]
[[package]]
name = "magnotia-transcription"
version = "0.1.0"
dependencies = [
"async-trait",
"futures-util",
"magnotia-cloud-providers",
"magnotia-core",
"num_cpus",
"reqwest 0.12.28",
"sha2",
"tempfile",
"thiserror 2.0.18",
"tokio",
"tracing",
"transcribe-rs",
"whisper-rs",
]
[[package]]
name = "markup5ever"
version = "0.14.1"
@@ -5314,6 +5315,12 @@ dependencies = [
"serde_json",
]
[[package]]
name = "symlink"
version = "0.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a7973cce6668464ea31f176d85b13c7ab3bba2cb3b77a2ed26abd7801688010a"
[[package]]
name = "symphonia"
version = "0.5.5"
@@ -6370,6 +6377,19 @@ dependencies = [
"tracing-core",
]
[[package]]
name = "tracing-appender"
version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "050686193eb999b4bb3bc2acfa891a13da00f79734704c4b8b4ef1a10b368a3c"
dependencies = [
"crossbeam-channel",
"symlink",
"thiserror 2.0.18",
"time",
"tracing-subscriber",
]
[[package]]
name = "tracing-attributes"
version = "0.1.31"

26
HANDOVER.md
View File

@@ -1,11 +1,11 @@
---
name: handover-2026-04-25
type: reference
tags: [handover, session, magnotia, phase-9, polish-debt]
tags: [handover, session, lumotia, phase-9, polish-debt]
description: Session handover — 2026/04/24-25 Phase 9 polish debt mostly shipped
---
# Magnotia Handover — 2026/04/25
# Lumotia Handover — 2026/04/25
> **Note:** Session-specific handover. Migration v14 (`transcripts.llm_tags`) was the head **at the time of this session**. Subsequent work has advanced the schema; current head is v15 (`idx_transcripts_profile_created`, composite index). For the current codebase shape, see [`docs/architecture-map/`](docs/architecture-map/) and [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md).
@@ -13,25 +13,25 @@ Phase 9 session. Spec + plan written from scratch and committed; plan correction
## Rebrand note
Product rename **Magnotia → Magnotia** still in flight. Copy in new docs is "Magnotia"; codebase paths / package names / repos still carry `magnotia`. No rebrand work this session. See `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_magnotia_rebrand.md`.
Product rename **Magnotia → Lumotia** completed 2026/05/13 (cascade across both repos, all 15 phases, cynical-QC gated). Codebase paths, package names, crate names, bundle identifier (`consulting.corbel.lumotia`), localStorage keys, settings keys, event channels, and on-disk data dir all carry `lumotia`. Migration shims preserve existing user data (data-dir rename, settings-key rename, localStorage-key rename). Remote repo rename pending Jake's action. See `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_lumotia_rebrand_cascade_complete.md` (write pending Phase 15.5 of the cascade plan).
## What shipped this session
### 9a — Export plumbing
- `write_text_file_cmd` Rust command in new `src-tauri/src/commands/fs.rs`, with two unit tests (UTF-8 round-trip + bad-parent error path). Registered in `invoke_handler!`. `tempfile = "3"` added as `[dev-dependencies]` on the magnotia crate.
- `write_text_file_cmd` Rust command in new `src-tauri/src/commands/fs.rs`, with two unit tests (UTF-8 round-trip + bad-parent error path). Registered in `invoke_handler!`. `tempfile = "3"` added as `[dev-dependencies]` on the lumotia crate.
- `src/lib/utils/saveMarkdown.ts` utility centralises `suggestedFilename`, `saveTranscriptAsMarkdown`, `exportTranscriptsToDir` (directory-mode bulk export with in-batch collision suffixing).
- HistoryPage `exportMarkdown` no longer copies to clipboard; it opens the OS save dialog and writes the file. Cancel returns silently.
- HistoryPage gained a slim leading checkbox per row, a bulk-action toolbar (select-all / clear / export / delete), `Esc` to clear, `Cmd/Ctrl+A` to select-all-visible when focus is inside the list and not in a text input.
### 9b — LLM content tags
- `magnotia-llm` exports a new `ContentTags { topic, intent }`, an `INTENT_CLOSED_SET`, an `is_valid_intent` helper, a `CONTENT_TAGS_SYSTEM` prompt and a `CONTENT_TAGS_GRAMMAR` GBNF (recursive style matching the existing `TASK_ARRAY_GRAMMAR`).
- `LlmEngine::extract_content_tags` method follows the same render-chat → generate → JSON-parse shape as the existing `cleanup_text` and `extract_tasks`. Truncates to the trailing 2000 chars on a UTF-8 boundary; max_tokens 96 is enough for the JSON envelope. Smoke test in `crates/llm/tests/content_tags_smoke.rs` is gated on `MAGNOTIA_LLM_TEST_MODEL` matching the Phase 8 pattern.
- `lumotia-llm` exports a new `ContentTags { topic, intent }`, an `INTENT_CLOSED_SET`, an `is_valid_intent` helper, a `CONTENT_TAGS_SYSTEM` prompt and a `CONTENT_TAGS_GRAMMAR` GBNF (recursive style matching the existing `TASK_ARRAY_GRAMMAR`).
- `LlmEngine::extract_content_tags` method follows the same render-chat → generate → JSON-parse shape as the existing `cleanup_text` and `extract_tasks`. Truncates to the trailing 2000 chars on a UTF-8 boundary; max_tokens 96 is enough for the JSON envelope. Smoke test in `crates/llm/tests/content_tags_smoke.rs` is gated on `LUMOTIA_LLM_TEST_MODEL` matching the Phase 8 pattern.
- `extract_content_tags_cmd` Tauri wrapper bridges through `state.llm_engine` with the standard `spawn_blocking` + `PowerAssertion` guard.
### 9b structural — migration v14 + persistence wiring
A correction layered in after the critical-review pass discovered the original Task 9 was assuming a writable `saveHistory()` path that turned out to be a no-op stub.
- Migration v14 adds `transcripts.llm_tags TEXT NOT NULL DEFAULT ''`.
- `magnotia-storage` `database.rs` SELECT statements include the column. `TranscriptRow` + `transcript_row_from` carry it. `update_transcript_meta` accepts an `Option<&str>` for `llm_tags` (sixth optional, `#[allow(too_many_arguments)]` keeps clippy happy without inverting the signature into a struct).
- `lumotia-storage` `database.rs` SELECT statements include the column. `TranscriptRow` + `transcript_row_from` carry it. `update_transcript_meta` accepts an `Option<&str>` for `llm_tags` (sixth optional, `#[allow(too_many_arguments)]` keeps clippy happy without inverting the signature into a struct).
- `commands/transcripts.rs` `TranscriptDto` + `UpdateTranscriptMetaRequest` add `llm_tags`; `update_transcript_meta_cmd` forwards.
- Frontend types: `TranscriptEntry.llmTags: string[]`, `TranscriptRow.llmTags: string`, `ContentTags`, optional `TranscriptMetaPatch.llmTags`.
- `mapTranscriptRow` hydrates `llmTags`. `saveTranscriptMeta` now also forwards `llmTags` payloads. `buildFrontmatter` unions auto + manual + LLM tags into the exported markdown frontmatter.
@@ -56,7 +56,7 @@ Fresh run on `main` tip `dd45f10`:
- `cargo fmt --check`: clean.
- `cargo clippy --all-targets -- -D warnings`: clean.
- `cargo test`: **277 tests pass**, 0 failed. Storage gained 1 new test (`update_transcript_meta_writes_llm_tags`), magnotia-tauri gained 2 (write_text_file). The Phase 8 brittle test fix is in this count.
- `cargo test`: **277 tests pass**, 0 failed. Storage gained 1 new test (`update_transcript_meta_writes_llm_tags`), lumotia-tauri gained 2 (write_text_file). The Phase 8 brittle test fix is in this count.
- `npm run check`: 0 errors, 0 warnings across 3957 files.
- `npm run build`: clean production build via `@sveltejs/adapter-static`.
@@ -64,13 +64,13 @@ Fresh run on `main` tip `dd45f10`:
The original Phase 9 spec + plan committed at `49a795f` + `48d3db7` had three mismatches against the actual codebase, surfaced by a critical-review pass before execution. Layered as a corrections appendix in commit `3eb24f2`:
1. `magnotia-llm` is `LlmEngine::generate(prompt, config)` synchronous, not the speculated `LlamaEngine::generate_chat(messages, config).await`.
1. `lumotia-llm` is `LlmEngine::generate(prompt, config)` synchronous, not the speculated `LlamaEngine::generate_chat(messages, config).await`.
2. `AppState.llm_engine: Arc<LlmEngine>` is direct, not behind a `RwLock`.
3. **Structural** — `transcripts.llm_tags` requires a real SQLite migration plus Tauri command extension because the frontend `saveHistory()` is a no-op stub. Original plan assumed `manualTags`-mirroring would suffice. Migration v14 + `update_transcript_meta` extension landed as a new task to cover this. Picked up the latent `manualTags` persistence bug for free.
## Owed to Jake (next session)
1. **Manual dogfood walkthrough.** Cannot be driven by an automated agent. When opening Magnotia next:
1. **Manual dogfood walkthrough.** Cannot be driven by an automated agent. When opening Lumotia next:
- Export one transcript via the History "Export .md" button — save dialog opens, file written to chosen path. Cancel — no toast, no fallback.
- Select 3 history rows via checkboxes — toolbar surfaces, "Export selected" writes one .md per row to a chosen folder, collisions suffixed " (2)" etc.
- Click "Tag" on one row — within a few seconds, dashed `topic:*` and `intent:*` chips appear. Click a chip — it moves into `manualTags` (solid accent chip). Page refresh — both `manualTags` and `llmTags` survive (this is the persistence-fix outcome).
@@ -92,7 +92,7 @@ The original Phase 9 spec + plan committed at `49a795f` + `48d3db7` had three mi
| Phases 1-8 | All shipped. |
| Phase 9 | **Mostly shipped this session.** Export plumbing, LLM content tags (with persistence), polish on sparkline + badge are live. SettingsPage deeper restructure + walkthrough a11y sweeps deferred. Roadmap entry updated. |
| Phase 10a | QC: dogfood walkthrough (above), Rachmann's RB-08 Mac verification (parallel), cross-platform CI, a11y regression, clean-install test. Half day. |
| Phase 10b | Magnotia → Magnotia rename sweep: package name, all 10 crates, bundle ids, install paths, `magnotia.db` → `magnotia.db`, event names, repo rename on both remotes. Half to 1 day. |
| Phase 10b | Magnotia → Lumotia rename sweep: **COMPLETE 2026/05/13** (cascade across both repos, 15 phases). Remote repo rename pending Jake. |
| Phase 10c | Release: 0.1.0 version sync, CHANGELOG seeded from roadmap phases, release notes, tag + push. Half day. |
### Release-blocker state
@@ -111,8 +111,8 @@ The original Phase 9 spec + plan committed at `49a795f` + `48d3db7` had three mi
- Spec: [docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md](docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md)
- Plan: [docs/superpowers/plans/2026-04-24-phase9-polish-debt.md](docs/superpowers/plans/2026-04-24-phase9-polish-debt.md)
- Roadmap: [docs/roadmap/2026-04-23-magnotia-feature-complete-roadmap.md](docs/roadmap/2026-04-23-magnotia-feature-complete-roadmap.md)
- Roadmap: [docs/roadmap/2026-04-23-lumotia-feature-complete-roadmap.md](docs/roadmap/2026-04-23-lumotia-feature-complete-roadmap.md)
- Previous handover: [HANDOVER-2026-04-24.md](HANDOVER-2026-04-24.md) (Phase 8)
- Release-blocker index: [docs/issues/README.md](docs/issues/README.md)
- Rebrand memory: `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_magnotia_rebrand.md`
- Rebrand memory: `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_lumotia_rebrand_cascade_complete.md`
- Active-focus upstream: `context/active-focus.md` in CORBEL-Main

2
KNOWN-ISSUES.md
View File

@@ -36,7 +36,7 @@ Tracked limitations and partial implementations in the current codebase. Each en
## Cloud providers
### KI-04 — `magnotia-cloud-providers` crate is not user-exposed
### KI-04 — `lumotia-cloud-providers` crate is not user-exposed
**Status:** The crate is a declared workspace dependency in [`src-tauri/Cargo.toml:36`](src-tauri/Cargo.toml#L36) and compiles into the binary, but no Tauri command, page, or settings field invokes `store_api_key` / `retrieve_api_key`. There is no UI to enter or store a cloud API key in the current build.

60
README.md
View File

@@ -1,8 +1,8 @@
# Magnotia
# Lumotia
*Think out loud. Keep working.*
Magnotia is a local-first, cognitive-load-aware dictation and task-capture desktop app. Every transcription, LLM cleanup, and task extraction runs on the user's machine. No telemetry, no analytics, no cloud dependency. The app is designed around a single observation: people who think in bursts lose ideas faster than they can type, and the tool's job is to get out of the way.
Lumotia is a local-first, cognitive-load-aware dictation and task-capture desktop app. Every transcription, LLM cleanup, and task extraction runs on the user's machine. No telemetry, no analytics, no cloud dependency. The app is designed around a single observation: people who think in bursts lose ideas faster than they can type, and the tool's job is to get out of the way.
---
@@ -21,15 +21,15 @@ Magnotia is a local-first, cognitive-load-aware dictation and task-capture deskt
1. **Local-first is the floor, not a feature.** No voice, transcript, or task ever leaves the user's machine unless they explicitly send it. No telemetry.
2. **Cognitive load is the limiting resource.** Every new setting must earn its mental real estate. Every interaction should reduce, not add, decisions.
3. **Composable, not monolithic.** Magnotia is a dictation primitive: via MCP, CLI, and filesystem export, it slots into whatever workflow the user already has (Obsidian, Claude Desktop, Cline, any text field).
3. **Composable, not monolithic.** Lumotia is a dictation primitive: via MCP, CLI, and filesystem export, it slots into whatever workflow the user already has (Obsidian, Claude Desktop, Cline, any text field).
4. **LLM scope is narrow.** The in-app LLM does transcription cleanup and task extraction. It is not a wake-word agent, not a chat UI, not a multi-provider cloud fan-out.
5. **Raw transcript is always recoverable.** Cleanup is additive, never destructive. The user can always see and revert to what Whisper heard.
These are enforced in the codebase (where practical) and in the docs under [`docs/whisper-ecosystem/magnotia-context.md`](docs/whisper-ecosystem/magnotia-context.md).
These are enforced in the codebase (where practical) and in the docs under [`docs/whisper-ecosystem/lumotia-context.md`](docs/whisper-ecosystem/lumotia-context.md).
---
## What Magnotia does today
## What Lumotia does today
### Speech-to-text
- Vulkan-accelerated local **Whisper** inference via [whisper-rs](https://github.com/tazz4843/whisper-rs) 0.16 + whisper.cpp. Works on NVIDIA, AMD, Intel Arc, Apple (via MoltenVK), and integrated graphics.
@@ -65,7 +65,7 @@ These are enforced in the codebase (where practical) and in the docs under [`doc
- Transcript editor window (`/viewer`) with debounced autosave.
### External integration
- **MCP stdio server** (`magnotia-mcp`) exposing read-only transcripts and tasks to any Model Context Protocol client (Claude Desktop, Cline, Cursor, etc.). No authentication, read-only, local-only.
- **MCP stdio server** (`lumotia-mcp`) exposing read-only transcripts and tasks to any Model Context Protocol client (Claude Desktop, Cline, Cursor, etc.). No authentication, read-only, local-only.
### Accessibility
- Dyslexia-friendly fonts bundled: Lexend, Atkinson Hyperlegible Next, OpenDyslexic.
@@ -84,7 +84,7 @@ These are enforced in the codebase (where practical) and in the docs under [`doc
## Architecture
Magnotia is a Tauri 2 desktop app with three layers:
Lumotia is a Tauri 2 desktop app with three layers:
```
┌─────────────────────────────────────────────────────────────────┐
@@ -102,18 +102,18 @@ Magnotia is a Tauri 2 desktop app with three layers:
│ window-state │
├─────────────────────────────────────────────────────────────────┤
│ Rust workspace (crates/) │
│ magnotia-core, magnotia-audio, magnotia-transcription, magnotia-llm, │
│ magnotia-ai-formatting, magnotia-storage, magnotia-hotkey, │
│ magnotia-cloud-providers, magnotia-mcp │
│ lumotia-core, lumotia-audio, lumotia-transcription, lumotia-llm, │
│ lumotia-ai-formatting, lumotia-storage, lumotia-hotkey, │
│ lumotia-cloud-providers, lumotia-mcp │
└─────────────────────────────────────────────────────────────────┘
```
The Rust workspace is the brain; Tauri is the OS integration surface; Svelte is the UI. The MCP server (`magnotia-mcp`) is a separate binary that opens Magnotia's SQLite store read-only — it's Magnotia-as-primitive for external agents.
The Rust workspace is the brain; Tauri is the OS integration surface; Svelte is the UI. The MCP server (`lumotia-mcp`) is a separate binary that opens Lumotia's SQLite store read-only — it's Lumotia-as-primitive for external agents.
### Repository layout
```
magnotia/
lumotia/
├── Cargo.toml # workspace root
├── src-tauri/ # Tauri app (main binary + commands)
│ ├── src/
@@ -165,15 +165,15 @@ magnotia/
| Crate | Responsibility |
|---|---|
| **`magnotia-core`** | Shared types (`Segment`, `Transcript`, `Megabytes`, `ModelId`), constants, the `Engine` / `SpeedTier` / `AccuracyTier` enums, hardware probe (`sysinfo`-based), model registry (Whisper + Parakeet entries), hardware-aware recommendation scoring, `process_watch` for meeting detection. |
| **`magnotia-audio`** | `cpal`-based microphone capture with device hotplug + error forwarding, VAD, `rubato` streaming resampler to 16 kHz mono, `symphonia` file decoding, `hound` WAV I/O. |
| **`magnotia-transcription`** | `whisper-rs` backend (`WhisperRsBackend`) that owns a `WhisperContext` and supports `set_initial_prompt`. `LocalEngine` wraps both Whisper and Parakeet (via `transcribe-rs` ONNX) behind a common `Transcriber` trait. Streaming primitives (`VadChunker`, `LocalAgreement`, buffer trim) live in the `streaming/` module. Model manager handles downloads, paths, and disk checks. |
| **`magnotia-llm`** | `llama-cpp-2` engine with a four-tier Qwen3.5 / Qwen3.6 model manager. Three high-level surfaces: `cleanup_text` (formatting), `decompose_task` (3–7 micro-steps, GBNF-constrained JSON array), `extract_tasks` (optional-array, GBNF-constrained). Resumable HTTP downloads with SHA-256 verify. |
| **`magnotia-ai-formatting`** | Post-processing pipeline: filler removal, British English conversion, anti-hallucination filter, smart paragraph breaks on long pauses, optional LLM cleanup. Also hosts the `llm_client::CLEANUP_PROMPT` constant (prompt-injection-hardened). |
| **`magnotia-storage`** | SQLite via `sqlx` 0.8. Migrations, CRUD for transcripts / tasks / subtasks / profiles / profile terms / settings / error log, FTS5 search, file-storage paths. |
| **`magnotia-hotkey`** | Linux `evdev` hotkey listener with device hotplug. Parses Tauri-style hotkey strings (`Ctrl+Shift+R`), emits Pressed / Released events. Works natively on Wayland (no X11 dependency). Checks `/dev/input/event*` access on startup; surfaces a clear "add yourself to the `input` group" error when missing. |
| **`magnotia-cloud-providers`** | BYOK cloud-STT provider stubs. Currently empty scaffolding. When populated: OpenAI-compatible endpoint + Anthropic (ceiling for scope). |
| **`magnotia-mcp`** | Standalone `magnotia-mcp` binary implementing the MCP stdio protocol (2024-11-05). Read-only tools: `list_transcripts`, `get_transcript`, `search_transcripts`, `list_tasks`. Opens Magnotia's SQLite store. |
| **`lumotia-core`** | Shared types (`Segment`, `Transcript`, `Megabytes`, `ModelId`), constants, the `Engine` / `SpeedTier` / `AccuracyTier` enums, hardware probe (`sysinfo`-based), model registry (Whisper + Parakeet entries), hardware-aware recommendation scoring, `process_watch` for meeting detection. |
| **`lumotia-audio`** | `cpal`-based microphone capture with device hotplug + error forwarding, VAD, `rubato` streaming resampler to 16 kHz mono, `symphonia` file decoding, `hound` WAV I/O. |
| **`lumotia-transcription`** | `whisper-rs` backend (`WhisperRsBackend`) that owns a `WhisperContext` and supports `set_initial_prompt`. `LocalEngine` wraps both Whisper and Parakeet (via `transcribe-rs` ONNX) behind a common `Transcriber` trait. Streaming primitives (`VadChunker`, `LocalAgreement`, buffer trim) live in the `streaming/` module. Model manager handles downloads, paths, and disk checks. |
| **`lumotia-llm`** | `llama-cpp-2` engine with a four-tier Qwen3.5 / Qwen3.6 model manager. Three high-level surfaces: `cleanup_text` (formatting), `decompose_task` (3–7 micro-steps, GBNF-constrained JSON array), `extract_tasks` (optional-array, GBNF-constrained). Resumable HTTP downloads with SHA-256 verify. |
| **`lumotia-ai-formatting`** | Post-processing pipeline: filler removal, British English conversion, anti-hallucination filter, smart paragraph breaks on long pauses, optional LLM cleanup. Also hosts the `llm_client::CLEANUP_PROMPT` constant (prompt-injection-hardened). |
| **`lumotia-storage`** | SQLite via `sqlx` 0.8. Migrations, CRUD for transcripts / tasks / subtasks / profiles / profile terms / settings / error log, FTS5 search, file-storage paths. |
| **`lumotia-hotkey`** | Linux `evdev` hotkey listener with device hotplug. Parses Tauri-style hotkey strings (`Ctrl+Shift+R`), emits Pressed / Released events. Works natively on Wayland (no X11 dependency). Checks `/dev/input/event*` access on startup; surfaces a clear "add yourself to the `input` group" error when missing. |
| **`lumotia-cloud-providers`** | BYOK cloud-STT provider stubs. Currently empty scaffolding. When populated: OpenAI-compatible endpoint + Anthropic (ceiling for scope). |
| **`lumotia-mcp`** | Standalone `lumotia-mcp` binary implementing the MCP stdio protocol (2024-11-05). Read-only tools: `list_transcripts`, `get_transcript`, `search_transcripts`, `list_tasks`. Opens Lumotia's SQLite store. |
### Tauri commands (src-tauri/src/commands/)
@@ -313,24 +313,24 @@ Beyond this README, the repo ships extensive internal documentation:
### Product + strategy — `docs/brief/`
Research briefs, competitive analysis, and strategic framing. Start with:
- [`what-magnotia-is.md`](docs/brief/what-magnotia-is.md) — product thesis
- [`what-lumotia-is.md`](docs/brief/what-lumotia-is.md) — product thesis
- [`why-current-tools-fail.md`](docs/brief/why-current-tools-fail.md) — market gap
- [`design-principles.md`](docs/brief/design-principles.md) — full principle list
- [`target-audience.md`](docs/brief/target-audience.md), [`market-size-demographics.md`](docs/brief/market-size-demographics.md)
- Appendices on cognitive ergonomics, AI body doubling, evolutionary psychology, implementation intentions, HITL scaffolding, voice interfaces
### Brand — `docs/brand/`
- [`magnotia-brand-guidelines.md`](docs/brand/magnotia-brand-guidelines.md)
- [`magnotia-brand-platform.md`](docs/brand/magnotia-brand-platform.md)
- [`lumotia-brand-guidelines.md`](docs/brand/lumotia-brand-guidelines.md)
- [`lumotia-brand-platform.md`](docs/brand/lumotia-brand-platform.md)
### Technical research — `docs/whisper-ecosystem/`
Cross-repo survey of 10 OSS Whisper projects, the Magnotia-specific atomic task backlog, and the two Cursor workstream plans.
Cross-repo survey of 10 OSS Whisper projects, the Lumotia-specific atomic task backlog, and the two Cursor workstream plans.
- [`brief.md`](docs/whisper-ecosystem/brief.md) — 31-item task backlog (the canonical research spec)
- [`magnotia-context.md`](docs/whisper-ecosystem/magnotia-context.md) — ideology, shipped state, file-ownership fence for cloud AI agents
- [`lumotia-context.md`](docs/whisper-ecosystem/lumotia-context.md) — ideology, shipped state, file-ownership fence for cloud AI agents
- [`workstream-A.md`](docs/whisper-ecosystem/workstream-A.md), [`workstream-B.md`](docs/whisper-ecosystem/workstream-B.md) — executed workstream plans
### GPU tuning — `docs/gpu-tuning/`
- [`plan.md`](docs/gpu-tuning/plan.md) — MVP plan for GGML env-var panel + `magnotia-bench` auto-tuner + `magnotia-configs` community repo
- [`plan.md`](docs/gpu-tuning/plan.md) — MVP plan for GGML env-var panel + `lumotia-bench` auto-tuner + `lumotia-configs` community repo
### Session handovers
- [`HANDOVER.md`](HANDOVER.md) — latest session summary
@@ -352,7 +352,7 @@ Pinned roadmap items (scoped in docs and session memory):
- **Phase 4** — remaining items from [`workstream-A.md`](docs/whisper-ecosystem/workstream-A.md) + [`workstream-B.md`](docs/whisper-ecosystem/workstream-B.md)
- **Voice calibration** — three-tier plan replacing the hardcoded speech-gate with per-user baselines
- **GPU community tuning** — see [`docs/gpu-tuning/plan.md`](docs/gpu-tuning/plan.md); five-phase roadmap from settings panel to agentic auto-tuner + community config repo
- **Cloud endpoint contract test** — when `magnotia-cloud-providers` grows a real provider
- **Cloud endpoint contract test** — when `lumotia-cloud-providers` grows a real provider
- **`ggml` dedup** — replace the interim `-Wl,--allow-multiple-definition` link flag with a proper shared-lib setup; unblocks custom shader / backend work
- **Mobile (iOS / Android)** — long-horizon, gated on the single-binary Rust stack scaling
@@ -360,7 +360,7 @@ Explicitly shelved (not coming without specific community signal):
- Wake-word / always-listening agent
- Chat-style LLM UI
- Multi-provider cloud fan-out beyond OpenAI-compatible + Anthropic
- Second notes-editing surface (transcripts leave Magnotia via frontmatter to Obsidian)
- Second notes-editing surface (transcripts leave Lumotia via frontmatter to Obsidian)
- Speaker diarization
- Dragon-style passage-based speaker fine-tuning (Whisper has no speaker adaptation)
@@ -387,4 +387,4 @@ To be finalised before public beta. Current intent: MIT or similar permissive li
## Contact
**Jake Sames** — [jakeadriansames@gmail.com](mailto:jakeadriansames@gmail.com)
Repo: [github.com/jakejars/magnotia](https://github.com/jakejars/magnotia) · [git.corbel.consulting/jake/magnotia](https://git.corbel.consulting/jake/magnotia)
Repo: [github.com/jakejars/lumotia](https://github.com/jakejars/lumotia) · [git.corbel.consulting/jake/lumotia](https://git.corbel.consulting/jake/lumotia)

8
crates/ai-formatting/Cargo.toml
View File

@@ -1,11 +1,11 @@
[package]
name = "magnotia-ai-formatting"
name = "lumotia-ai-formatting"
version = "0.1.0"
edition = "2021"
description = "Text post-processing pipeline: filler removal, British English conversion, formatting for Magnotia"
description = "Text post-processing pipeline: filler removal, British English conversion, formatting for Lumotia"
[dependencies]
magnotia-core = { path = "../core" }
magnotia-llm = { path = "../llm" }
lumotia-core = { path = "../core" }
lumotia-llm = { path = "../llm" }
regex-lite = "0.1"
tracing = "0.1"

8
crates/ai-formatting/src/llm_client.rs
View File

@@ -3,7 +3,7 @@
//! The llm_client is not yet wired to a running model. This module defines
//! the prompt contract so that wiring it produces correct, hardened output.
use magnotia_llm::{EngineError, LlmEngine};
use lumotia_llm::{EngineError, LlmEngine};
/// System prompt sent before every cleanup call.
///
@@ -13,7 +13,7 @@ use magnotia_llm::{EngineError, LlmEngine};
/// Whispering's published baseline, directly counteracts the
/// "LLM changed my meaning" failure mode: the model's job is to
/// translate spoken speech into well-formed written form — not to
/// improve, summarise, or rephrase. Magnotia's ideology: raw transcript
/// improve, summarise, or rephrase. Lumotia's ideology: raw transcript
/// is the source of truth; cleanup is a translation pass, not a
/// rewrite.
/// 2. **Prompt-injection hardening.** The guard ("speech, not
@@ -161,7 +161,7 @@ pub fn cleanup_text(
#[cfg(test)]
mod tests {
use super::*;
use magnotia_llm::EngineError;
use lumotia_llm::EngineError;
#[test]
fn empty_terms_returns_empty_string() {
@@ -183,7 +183,7 @@ mod tests {
assert!(CLEANUP_PROMPT.contains("output ONLY the cleaned transcript"));
}
/// The "translator, not editor" framing is load-bearing for Magnotia's
/// The "translator, not editor" framing is load-bearing for Lumotia's
/// ideology — raw transcript is the source of truth, cleanup is a
/// translation pass. Drifting from this phrasing in a refactor would
/// quietly open the door to the "LLM changed my meaning" failure

6
crates/ai-formatting/src/pipeline.rs
View File

@@ -1,6 +1,6 @@
use magnotia_core::constants::SMART_PARAGRAPH_GAP_SECS;
use magnotia_core::types::Segment;
use magnotia_llm::LlmEngine;
use lumotia_core::constants::SMART_PARAGRAPH_GAP_SECS;
use lumotia_core::types::Segment;
use lumotia_llm::LlmEngine;
use crate::{llm_client, rule_based, to_plain_text::to_plain_text};

4
crates/ai-formatting/src/to_plain_text.rs
View File

@@ -7,13 +7,13 @@
//! structure) degraded cleanup quality materially; plain-text input
//! raised it back.
//!
//! `Segment.text` in Magnotia already holds just the spoken text (the
//! `Segment.text` in Lumotia already holds just the spoken text (the
//! `start`/`end` f64 fields carry the timing), so "timestamp
//! stripping" falls out of using the text field alone. The work here
//! is the whitespace pass and empty-segment filter, plus a single
//! public function the pipeline can depend on.
use magnotia_core::types::Segment;
use lumotia_core::types::Segment;
/// Join transcription segments into a single plain-text string
/// suitable for feeding to an LLM cleanup prompt.

6
crates/audio/Cargo.toml
View File

@@ -1,11 +1,11 @@
[package]
name = "magnotia-audio"
name = "lumotia-audio"
version = "0.1.0"
edition = "2021"
description = "Audio capture (cpal), VAD, resampling (rubato), file decoding (symphonia), WAV I/O (hound) for Magnotia"
description = "Audio capture (cpal), VAD, resampling (rubato), file decoding (symphonia), WAV I/O (hound) for Lumotia"
[dependencies]
magnotia-core = { path = "../core" }
lumotia-core = { path = "../core" }
# Microphone capture
cpal = "0.17"

87
crates/audio/src/capture.rs
View File

@@ -1,3 +1,4 @@
use std::collections::VecDeque;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::mpsc;
use std::sync::Arc;
@@ -8,7 +9,7 @@ use regex::Regex;
use serde::{Deserialize, Serialize};
use std::sync::OnceLock;
use magnotia_core::error::{MagnotiaError, Result};
use lumotia_core::error::{Error, Result};
const AUDIO_CHANNEL_CAPACITY: usize = 32;
@@ -106,7 +107,7 @@ impl MicrophoneCapture {
let devices = host
.input_devices()
.map_err(|e| MagnotiaError::AudioCaptureFailed(format!("input_devices: {e}")))?;
.map_err(|e| Error::AudioCaptureFailed(format!("input_devices: {e}")))?;
// Load ALSA card descriptions once per enumeration. These are the
// "real" product names (e.g. "Blue Microphones") that cpal's
@@ -140,21 +141,32 @@ impl MicrophoneCapture {
/// Start capturing from the device whose name matches `device_name` exactly.
/// If no match is found, returns an error rather than silently falling back.
pub fn start_with_device(device_name: &str) -> Result<(Self, mpsc::Receiver<AudioChunk>)> {
///
/// The returned tuple is `(capture, replay_buffer, rx)`:
/// - `replay_buffer` holds chunks observed during the 350ms
/// validation pre-roll. Consumers MUST drain it before reading
/// from `rx` so the head of the recording isn't lost on hosts
/// whose cpal buffer is small enough to overflow the 32-slot
/// channel during validation (WASAPI exclusive, low-latency
/// ALSA at 256 frames).
/// - `rx` is the live cpal callback channel.
pub fn start_with_device(
device_name: &str,
) -> Result<(Self, VecDeque<AudioChunk>, mpsc::Receiver<AudioChunk>)> {
let host = cpal::default_host();
let devices = host
.input_devices()
.map_err(|e| MagnotiaError::AudioCaptureFailed(format!("input_devices: {e}")))?;
.map_err(|e| Error::AudioCaptureFailed(format!("input_devices: {e}")))?;
for device in devices {
let name = device_display_name(&device).unwrap_or_default();
if name == device_name {
tracing::info!(target: "magnotia_audio", "start_with_device: opening explicit device '{name}'");
tracing::info!(target: "lumotia_audio", "start_with_device: opening explicit device '{name}'");
return open_and_validate(device, &name, /* require_audio = */ true);
}
}
Err(MagnotiaError::AudioCaptureFailed(format!(
Err(Error::AudioCaptureFailed(format!(
"Selected device '{device_name}' not found in current host enumeration. \
It may have been disconnected. Open Settings → Audio to pick another."
)))
@@ -169,7 +181,7 @@ impl MicrophoneCapture {
/// a short window — this is what defeats the "silent monitor source wins" bug.
/// 4. If no non-monitor device produces real audio, fall back to monitor sources
/// as a last resort (with a clear log line). Never accept dead silence.
pub fn start() -> Result<(Self, mpsc::Receiver<AudioChunk>)> {
pub fn start() -> Result<(Self, VecDeque<AudioChunk>, mpsc::Receiver<AudioChunk>)> {
let host = cpal::default_host();
let default_name = host
.default_input_device()
@@ -178,7 +190,7 @@ impl MicrophoneCapture {
let mut all_devices: Vec<cpal::Device> = host
.input_devices()
.map_err(|e| MagnotiaError::AudioCaptureFailed(format!("input_devices: {e}")))?
.map_err(|e| Error::AudioCaptureFailed(format!("input_devices: {e}")))?
.collect();
// Sort: default first, then non-monitor, then monitor-as-last-resort.
@@ -196,7 +208,7 @@ impl MicrophoneCapture {
});
tracing::info!(
target: "magnotia_audio",
target: "lumotia_audio",
device_count = all_devices.len(),
default = %default_name,
"enumerated input devices"
@@ -211,7 +223,7 @@ impl MicrophoneCapture {
match open_and_validate(device.clone(), &name, true) {
Ok(result) => return Ok(result),
Err(e) => {
tracing::warn!(target: "magnotia_audio", device = %name, error = %e, "candidate device rejected");
tracing::warn!(target: "lumotia_audio", device = %name, error = %e, "candidate device rejected");
}
}
}
@@ -219,7 +231,7 @@ impl MicrophoneCapture {
// Second pass: accept anything that delivers bytes (monitor sources
// included). Better to capture from a monitor than fail entirely.
tracing::warn!(
target: "magnotia_audio",
target: "lumotia_audio",
"no non-monitor mic produced audio; falling back to monitor/loopback sources"
);
for device in &all_devices {
@@ -227,7 +239,7 @@ impl MicrophoneCapture {
match open_and_validate(device.clone(), &name, false) {
Ok(result) => {
tracing::warn!(
target: "magnotia_audio",
target: "lumotia_audio",
device = %name,
"capturing from likely monitor source; recordings may be silent or contain system audio"
);
@@ -237,7 +249,7 @@ impl MicrophoneCapture {
}
}
Err(MagnotiaError::AudioCaptureFailed(
Err(Error::AudioCaptureFailed(
"No working microphone found. Check that an input device is connected, \
that PulseAudio/PipeWire is running, and that the app has microphone permission. \
Then open Settings → Audio to pick a device explicitly."
@@ -358,16 +370,16 @@ fn open_and_validate(
device: cpal::Device,
name: &str,
require_audio: bool,
) -> Result<(MicrophoneCapture, mpsc::Receiver<AudioChunk>)> {
) -> Result<(MicrophoneCapture, VecDeque<AudioChunk>, mpsc::Receiver<AudioChunk>)> {
let config = device
.default_input_config()
.map_err(|e| MagnotiaError::AudioCaptureFailed(format!("default_input_config: {e}")))?;
.map_err(|e| Error::AudioCaptureFailed(format!("default_input_config: {e}")))?;
let sample_rate = config.sample_rate();
let channels = config.channels();
let format = config.sample_format();
tracing::info!(
target: "magnotia_audio",
target: "lumotia_audio",
device = %name,
sample_rate,
channels,
@@ -376,7 +388,6 @@ fn open_and_validate(
);
let (tx, rx) = mpsc::sync_channel::<AudioChunk>(AUDIO_CHANNEL_CAPACITY);
let requeue_tx = tx.clone();
let dropped_chunks = Arc::new(AtomicU64::new(0));
// Bounded channel for runtime stream errors. Capacity 32 = plenty for
// the rare error case; if it ever fills, drops are reported via stderr
@@ -422,16 +433,16 @@ fn open_and_validate(
name.to_string(),
),
other => {
return Err(MagnotiaError::AudioCaptureFailed(format!(
return Err(Error::AudioCaptureFailed(format!(
"unsupported sample format {other:?}"
)))
}
}
.map_err(|e| MagnotiaError::AudioCaptureFailed(format!("build_input_stream: {e}")))?;
.map_err(|e| Error::AudioCaptureFailed(format!("build_input_stream: {e}")))?;
stream
.play()
.map_err(|e| MagnotiaError::AudioCaptureFailed(format!("stream.play: {e}")))?;
.map_err(|e| Error::AudioCaptureFailed(format!("stream.play: {e}")))?;
// Validation window: collect chunks for DEVICE_VALIDATION_MS, compute RMS.
let deadline =
@@ -460,14 +471,14 @@ fn open_and_validate(
}
if total_samples == 0 {
return Err(MagnotiaError::AudioCaptureFailed(
return Err(Error::AudioCaptureFailed(
"device delivered zero samples in validation window".into(),
));
}
let rms = (sum_sq / total_samples as f64).sqrt() as f32;
tracing::info!(
target: "magnotia_audio",
target: "lumotia_audio",
device = %name,
samples = total_samples,
rms,
@@ -475,7 +486,7 @@ fn open_and_validate(
);
if require_audio && rms < SILENCE_RMS_FLOOR {
return Err(MagnotiaError::AudioCaptureFailed(format!(
return Err(Error::AudioCaptureFailed(format!(
"device produced silence (rms={rms:.6} below floor {SILENCE_RMS_FLOOR:.6})"
)));
}
@@ -485,21 +496,26 @@ fn open_and_validate(
// long stream of f32 zeros from a borked device — that is worse than
// failing fast.
if rms < DEAD_SILENCE_FLOOR {
return Err(MagnotiaError::AudioCaptureFailed(format!(
return Err(Error::AudioCaptureFailed(format!(
"device produced dead silence (rms={rms:.6e} below absolute floor {DEAD_SILENCE_FLOOR:.6e})"
)));
}
// Re-queue the collected chunks so downstream gets them. Count any
// drops here against the same `dropped_chunks` counter so the live
// session sees them and can warn the user.
for chunk in collected {
if requeue_tx.try_send(chunk).is_err() {
dropped_chunks.fetch_add(1, Ordering::Relaxed);
}
}
// Hand the validation pre-roll back to the consumer as a separate
// VecDeque rather than try_send-requeuing into the 32-slot channel.
// On small-buffer audio hosts (WASAPI exclusive at ~256 frames /
// low-latency ALSA) the 350ms window collects ~65 chunks; the old
// requeue path silently dropped roughly half of them, losing ~150ms
// from the head of every recording. The consumer-side drain
// bypasses the channel cap entirely.
let replay_buffer: VecDeque<AudioChunk> = collected.into_iter().collect();
tracing::info!(target: "magnotia_audio", device = %name, "selected microphone");
tracing::info!(
target: "lumotia_audio",
device = %name,
replay_chunks = replay_buffer.len(),
"selected microphone"
);
Ok((
MicrophoneCapture {
stream: Some(stream),
@@ -507,6 +523,7 @@ fn open_and_validate(
dropped_chunks,
error_rx: Some(err_rx),
},
replay_buffer,
rx,
))
}
@@ -547,7 +564,7 @@ where
move |err| {
// Surface stream errors to the live session via err_tx so the
// frontend can show a toast.
tracing::error!(target: "magnotia_audio", error = %err, "capture stream error");
tracing::error!(target: "lumotia_audio", error = %err, "capture stream error");
if err_tx
.try_send(CaptureRuntimeError {
device_name: err_device_name.clone(),
@@ -560,7 +577,7 @@ where
// even if the frontend never received the typed event.
let prior = dropped_errors.fetch_add(1, Ordering::Relaxed);
tracing::warn!(
target: "magnotia_audio",
target: "lumotia_audio",
device = %err_device_name,
dropped_error = prior + 1,
"capture error channel full; dropping runtime error"

6
crates/audio/src/concurrency.rs
View File

@@ -1,7 +1,7 @@
use std::path::Path;
use magnotia_core::error::Result;
use magnotia_core::types::AudioSamples;
use lumotia_core::error::Result;
use lumotia_core::types::AudioSamples;
use crate::decode::decode_audio_file;
use crate::resample::resample_to_16khz;
@@ -16,6 +16,6 @@ pub async fn decode_and_resample(path: &Path) -> Result<AudioSamples> {
})
.await
.map_err(|e| {
magnotia_core::error::MagnotiaError::AudioDecodeFailed(format!("Task join error: {e}"))
lumotia_core::error::Error::AudioDecodeFailed(format!("Task join error: {e}"))
})?
}

42
crates/audio/src/decode.rs
View File

@@ -9,13 +9,13 @@ use symphonia::core::io::MediaSourceStream;
use symphonia::core::meta::MetadataOptions;
use symphonia::core::probe::Hint;
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::types::AudioSamples;
use lumotia_core::error::{Error, Result};
use lumotia_core::types::AudioSamples;
/// Decode an audio file to mono f32 PCM samples.
/// Supports all formats symphonia handles: mp3, aac, flac, wav, ogg, etc.
///
/// Any read- or decode-side error is propagated as `MagnotiaError::AudioDecodeFailed`.
/// Any read- or decode-side error is propagated as `Error::AudioDecodeFailed`.
/// A previous implementation `break`ed out of the packet loop on any read
/// error and skipped per-packet decode errors, so a truncated or corrupt
/// input silently returned `Ok` with whatever had decoded before the
@@ -29,7 +29,7 @@ pub fn decode_audio_file_limited(
max_duration_secs: Option<f64>,
) -> Result<AudioSamples> {
let file = File::open(path)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
let mss = MediaSourceStream::new(Box::new(file), Default::default());
let mut hint = Hint::new();
@@ -42,7 +42,7 @@ pub fn decode_audio_file_limited(
pub fn probe_audio_duration_secs(path: &Path) -> Result<Option<f64>> {
let file = File::open(path)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
let mss = MediaSourceStream::new(Box::new(file), Default::default());
let mut hint = Hint::new();
if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
@@ -56,15 +56,15 @@ pub fn probe_audio_duration_secs(path: &Path) -> Result<Option<f64>> {
&FormatOptions::default(),
&MetadataOptions::default(),
)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
let track = probed
.format
.default_track()
.ok_or_else(|| MagnotiaError::AudioDecodeFailed("No audio track found".into()))?;
.ok_or_else(|| Error::AudioDecodeFailed("No audio track found".into()))?;
let sample_rate = track
.codec_params
.sample_rate
.ok_or_else(|| MagnotiaError::AudioDecodeFailed("Unknown sample rate".into()))?;
.ok_or_else(|| Error::AudioDecodeFailed("Unknown sample rate".into()))?;
Ok(track
.codec_params
.n_frames
@@ -86,20 +86,20 @@ fn decode_media_stream(
&FormatOptions::default(),
&MetadataOptions::default(),
)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
let mut format = probed.format;
let track = format
.default_track()
.ok_or_else(|| MagnotiaError::AudioDecodeFailed("No audio track found".into()))?;
.ok_or_else(|| Error::AudioDecodeFailed("No audio track found".into()))?;
let sample_rate = track
.codec_params
.sample_rate
.ok_or_else(|| MagnotiaError::AudioDecodeFailed("Unknown sample rate".into()))?;
.ok_or_else(|| Error::AudioDecodeFailed("Unknown sample rate".into()))?;
if sample_rate == 0 {
return Err(MagnotiaError::AudioDecodeFailed(
return Err(Error::AudioDecodeFailed(
"Invalid sample rate: 0".into(),
));
}
@@ -109,7 +109,7 @@ fn decode_media_stream(
let mut decoder = symphonia::default::get_codecs()
.make(&track.codec_params, &DecoderOptions::default())
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Codec error: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Codec error: {e}")))?;
let mut samples: Vec<f32> = Vec::new();
@@ -123,12 +123,12 @@ fn decode_media_stream(
break;
}
Err(SymphoniaError::ResetRequired) => {
return Err(MagnotiaError::AudioDecodeFailed(
return Err(Error::AudioDecodeFailed(
"decoder reset required mid-stream — input contains a discontinuity".into(),
));
}
Err(e) => {
return Err(MagnotiaError::AudioDecodeFailed(format!(
return Err(Error::AudioDecodeFailed(format!(
"packet read failed: {e}"
)));
}
@@ -140,7 +140,7 @@ fn decode_media_stream(
let decoded = decoder
.decode(&packet)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("packet decode failed: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("packet decode failed: {e}")))?;
let spec = *decoded.spec();
let channels = spec.channels.count();
@@ -160,7 +160,7 @@ fn decode_media_stream(
.map(|limit| samples.len() > limit)
.unwrap_or(false)
{
return Err(MagnotiaError::AudioDecodeFailed(format!(
return Err(Error::AudioDecodeFailed(format!(
"Audio is longer than the {:.0} minute import limit",
max_duration_secs.unwrap_or(0.0) / 60.0
)));
@@ -168,7 +168,7 @@ fn decode_media_stream(
}
if samples.is_empty() {
return Err(MagnotiaError::AudioDecodeFailed(
return Err(Error::AudioDecodeFailed(
"No audio data decoded".into(),
));
}
@@ -191,7 +191,7 @@ mod tests {
}
fn valid_wav_bytes(sample_count: usize) -> Vec<u8> {
let path = temp_path("magnotia_decode_tmp_for_bytes.wav");
let path = temp_path("lumotia_decode_tmp_for_bytes.wav");
let samples: Vec<f32> = (0..sample_count).map(|i| (i as f32) / 1000.0).collect();
let audio = AudioSamples::mono_16khz(samples);
write_wav(&path, &audio).unwrap();
@@ -238,7 +238,7 @@ mod tests {
#[test]
fn decodes_valid_wav_successfully() {
let path = temp_path("magnotia_decode_valid.wav");
let path = temp_path("lumotia_decode_valid.wav");
let samples: Vec<f32> = (0..4_000).map(|i| (i as f32) / 1000.0).collect();
write_wav(&path, &AudioSamples::mono_16khz(samples)).unwrap();
@@ -251,7 +251,7 @@ mod tests {
#[test]
fn missing_file_surfaces_error() {
let path = temp_path("magnotia_decode_missing.wav");
let path = temp_path("lumotia_decode_missing.wav");
let result = decode_audio_file(&path);
assert!(result.is_err(), "missing file must error, got: {result:?}");
}

12
crates/audio/src/resample.rs
View File

@@ -2,9 +2,9 @@ use rubato::{
Resampler, SincFixedIn, SincInterpolationParameters, SincInterpolationType, WindowFunction,
};
use magnotia_core::constants::WHISPER_SAMPLE_RATE;
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::types::AudioSamples;
use lumotia_core::constants::WHISPER_SAMPLE_RATE;
use lumotia_core::error::{Error, Result};
use lumotia_core::types::AudioSamples;
/// Resample audio to 16kHz mono using sinc interpolation (rubato).
/// Returns a new AudioSamples at the target sample rate.
@@ -17,7 +17,7 @@ pub fn resample_to_16khz(audio: &AudioSamples) -> Result<AudioSamples> {
}
if from_rate == 0 {
return Err(MagnotiaError::AudioDecodeFailed(
return Err(Error::AudioDecodeFailed(
"Cannot resample: source rate is 0".into(),
));
}
@@ -36,7 +36,7 @@ pub fn resample_to_16khz(audio: &AudioSamples) -> Result<AudioSamples> {
let mut resampler = SincFixedIn::<f32>::new(
ratio, 1.1, params, chunk_size, 1, // mono
)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Resampler init failed: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Resampler init failed: {e}")))?;
let samples = audio.samples();
let mut output_samples: Vec<f32> = Vec::new();
@@ -53,7 +53,7 @@ pub fn resample_to_16khz(audio: &AudioSamples) -> Result<AudioSamples> {
let input = vec![chunk];
let result = resampler
.process(&input, None)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("Resample failed: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("Resample failed: {e}")))?;
if !result.is_empty() && !result[0].is_empty() {
output_samples.extend_from_slice(&result[0]);

12
crates/audio/src/streaming_resample.rs
View File

@@ -27,8 +27,8 @@ use rubato::{
Resampler, SincFixedIn, SincInterpolationParameters, SincInterpolationType, WindowFunction,
};
use magnotia_core::constants::WHISPER_SAMPLE_RATE;
use magnotia_core::error::{MagnotiaError, Result};
use lumotia_core::constants::WHISPER_SAMPLE_RATE;
use lumotia_core::error::{Error, Result};
/// Number of input samples the rubato resampler consumes per `process()`
/// call. Matches the chunk size used in `resample::resample_to_16khz`.
@@ -51,7 +51,7 @@ impl StreamingResampler {
/// rubato rejects the requested ratio.
pub fn new(from_rate: u32) -> Result<Self> {
if from_rate == 0 {
return Err(MagnotiaError::AudioDecodeFailed(
return Err(Error::AudioDecodeFailed(
"StreamingResampler: input sample rate is 0".into(),
));
}
@@ -78,7 +78,7 @@ impl StreamingResampler {
1, // mono
)
.map_err(|e| {
MagnotiaError::AudioDecodeFailed(format!("StreamingResampler init failed: {e}"))
Error::AudioDecodeFailed(format!("StreamingResampler init failed: {e}"))
})?;
Ok(Self::Sinc {
@@ -110,7 +110,7 @@ impl StreamingResampler {
let chunk: Vec<f32> = residual.drain(..INPUT_CHUNK).collect();
let input = vec![chunk];
let result = resampler.process(&input, None).map_err(|e| {
MagnotiaError::AudioDecodeFailed(format!(
Error::AudioDecodeFailed(format!(
"StreamingResampler process failed: {e}"
))
})?;
@@ -144,7 +144,7 @@ impl StreamingResampler {
let input = vec![chunk];
let result = resampler.process(&input, None).map_err(|e| {
MagnotiaError::AudioDecodeFailed(format!(
Error::AudioDecodeFailed(format!(
"StreamingResampler flush failed: {e}"
))
})?;

2
crates/audio/src/vad.rs
View File

@@ -7,7 +7,7 @@
// For now, all audio is treated as speech. This matches v0.2 behaviour
// (no VAD) and doesn't affect core functionality.
use magnotia_core::constants::VAD_SPEECH_THRESHOLD;
use lumotia_core::constants::VAD_SPEECH_THRESHOLD;
/// Stub speech detector. Treats all audio as speech.
#[derive(Default)]

38
crates/audio/src/wav.rs
View File

@@ -1,8 +1,8 @@
use std::io::BufWriter;
use std::path::Path;
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::types::AudioSamples;
use lumotia_core::error::{Error, Result};
use lumotia_core::types::AudioSamples;
/// Append-friendly WAV writer for long-running captures.
///
@@ -40,10 +40,10 @@ impl WavWriter {
bits_per_sample: 16,
sample_format: hound::SampleFormat::Int,
};
let file = std::fs::File::create(path).map_err(MagnotiaError::from)?;
let file = std::fs::File::create(path).map_err(Error::from)?;
let buffered = BufWriter::new(file);
let inner = hound::WavWriter::new(buffered, spec).map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV create failed: {e}")))
Error::from(std::io::Error::other(format!("WAV create failed: {e}")))
})?;
Ok(Self {
inner,
@@ -61,7 +61,7 @@ impl WavWriter {
let clamped = sample.clamp(-1.0, 1.0);
let int_sample = (clamped * i16::MAX as f32) as i16;
self.inner.write_sample(int_sample).map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV write failed: {e}")))
Error::from(std::io::Error::other(format!("WAV write failed: {e}")))
})?;
}
self.samples_since_flush += samples.len();
@@ -78,7 +78,7 @@ impl WavWriter {
/// boundaries (end-of-utterance, UI events) for tighter recovery.
pub fn flush(&mut self) -> Result<()> {
self.inner.flush().map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV flush failed: {e}")))
Error::from(std::io::Error::other(format!("WAV flush failed: {e}")))
})?;
self.samples_since_flush = 0;
Ok(())
@@ -90,7 +90,7 @@ impl WavWriter {
/// that care about the unflushed tail should always finalise.
pub fn finalize(self) -> Result<()> {
self.inner.finalize().map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV finalize failed: {e}")))
Error::from(std::io::Error::other(format!("WAV finalize failed: {e}")))
})?;
Ok(())
}
@@ -106,19 +106,19 @@ pub fn write_wav(path: &Path, audio: &AudioSamples) -> Result<()> {
};
let mut writer = hound::WavWriter::create(path, spec).map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV create failed: {e}")))
Error::from(std::io::Error::other(format!("WAV create failed: {e}")))
})?;
for &sample in audio.samples() {
let clamped = sample.clamp(-1.0, 1.0);
let int_sample = (clamped * i16::MAX as f32) as i16;
writer.write_sample(int_sample).map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV write failed: {e}")))
Error::from(std::io::Error::other(format!("WAV write failed: {e}")))
})?;
}
writer.finalize().map_err(|e| {
MagnotiaError::from(std::io::Error::other(format!("WAV finalize failed: {e}")))
Error::from(std::io::Error::other(format!("WAV finalize failed: {e}")))
})?;
Ok(())
@@ -126,14 +126,14 @@ pub fn write_wav(path: &Path, audio: &AudioSamples) -> Result<()> {
/// Read a WAV file to f32 PCM `AudioSamples`.
///
/// Any per-sample decode error is surfaced as `MagnotiaError::AudioDecodeFailed`
/// Any per-sample decode error is surfaced as `Error::AudioDecodeFailed`
/// rather than silently dropped. A previous implementation used
/// `filter_map(|s| s.ok())`, so a truncated or corrupt payload returned
/// a short, silently-partial `AudioSamples` — callers got `Ok` while
/// losing audio (flagged by the 2026-04-22 review).
pub fn read_wav(path: &Path) -> Result<AudioSamples> {
let reader = hound::WavReader::open(path)
.map_err(|e| MagnotiaError::AudioDecodeFailed(format!("WAV open failed: {e}")))?;
.map_err(|e| Error::AudioDecodeFailed(format!("WAV open failed: {e}")))?;
let spec = reader.spec();
let sample_rate = spec.sample_rate;
@@ -147,7 +147,7 @@ pub fn read_wav(path: &Path) -> Result<AudioSamples> {
sample
.map(|s| s as f32 / (1 << (bits_per_sample - 1)) as f32)
.map_err(|e| {
MagnotiaError::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
Error::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
})
})
.collect::<Result<Vec<f32>>>()?,
@@ -155,7 +155,7 @@ pub fn read_wav(path: &Path) -> Result<AudioSamples> {
.into_samples::<f32>()
.map(|sample| {
sample.map_err(|e| {
MagnotiaError::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
Error::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
})
})
.collect::<Result<Vec<f32>>>()?,
@@ -172,7 +172,7 @@ mod tests {
fn wav_writer_survives_crash() {
// Property under test: a `WavWriter` that has been flushed but
// never finalised leaves a valid, readable WAV on disk. This
// is the crash-safety guarantee — if the magnotia process aborts
// is the crash-safety guarantee — if the lumotia process aborts
// mid-session, the on-disk file up to the last flush is
// recoverable.
//
@@ -182,7 +182,7 @@ mod tests {
// mirrors what happens when the OS reaps the process without
// giving Rust a chance to run destructors.
let temp_dir = std::env::temp_dir();
let path = temp_dir.join("magnotia_test_wav_writer_survives_crash.wav");
let path = temp_dir.join("lumotia_test_wav_writer_survives_crash.wav");
let _ = std::fs::remove_file(&path);
let mut writer = WavWriter::create(&path, 16_000, 1).unwrap();
@@ -219,7 +219,7 @@ mod tests {
#[test]
fn wav_writer_append_then_finalize_roundtrips() {
let temp_dir = std::env::temp_dir();
let path = temp_dir.join("magnotia_test_wav_writer_finalize.wav");
let path = temp_dir.join("lumotia_test_wav_writer_finalize.wav");
let _ = std::fs::remove_file(&path);
let mut writer = WavWriter::create(&path, 16_000, 1).unwrap();
@@ -241,7 +241,7 @@ mod tests {
// truncated WAV returned Ok with a short samples vec. The
// new code must propagate the error.
let temp_dir = std::env::temp_dir();
let path = temp_dir.join("magnotia_test_truncated_wav.wav");
let path = temp_dir.join("lumotia_test_truncated_wav.wav");
let _ = std::fs::remove_file(&path);
// Write 100 samples (200 bytes at 16-bit).
@@ -267,7 +267,7 @@ mod tests {
#[test]
fn wav_roundtrip() {
let temp_dir = std::env::temp_dir();
let path = temp_dir.join("magnotia_test_roundtrip.wav");
let path = temp_dir.join("lumotia_test_roundtrip.wav");
let original = AudioSamples::mono_16khz(vec![0.0, 0.5, -0.5, 0.25, -0.25]);
write_wav(&path, &original).unwrap();

6
crates/cloud-providers/Cargo.toml
View File

@@ -1,11 +1,11 @@
[package]
name = "magnotia-cloud-providers"
name = "lumotia-cloud-providers"
version = "0.1.0"
edition = "2021"
description = "Provider trait and BYOK cloud STT scaffolding for Magnotia (Wyrdnote pending rebrand)"
description = "Provider trait and BYOK cloud STT scaffolding for Lumotia"
[dependencies]
magnotia-core = { path = "../core" }
lumotia-core = { path = "../core" }
# Async-native trait. async_trait converts async fn into Pin<Box<dyn
# Future>> at the trait surface so TranscriptionProvider stays

10
crates/cloud-providers/src/keystore.rs
View File

@@ -1,13 +1,13 @@
use std::collections::HashMap;
use std::sync::{Mutex, OnceLock};
/// Store an API key in Magnotia's process-local keystore.
/// Store an API key in Lumotia's process-local keystore.
///
/// Keys are held in memory for the lifetime of the process and are lost on
/// exit. This avoids the undefined behaviour of mutating process environment
/// variables from arbitrary threads while keeping the public API safe.
///
/// `retrieve_api_key` still falls back to `MAGNOTIA_API_KEY_<PROVIDER>` environment
/// `retrieve_api_key` still falls back to `LUMOTIA_API_KEY_<PROVIDER>` environment
/// variables so externally injected secrets continue to work.
///
/// TODO: Replace with the `keyring` crate (or platform-native credential
@@ -19,10 +19,10 @@ pub fn store_api_key(provider: &str, key: &str) {
.insert(provider_env_key(provider), key.to_string());
}
/// Retrieve an API key from Magnotia's process-local keystore.
/// Retrieve an API key from Lumotia's process-local keystore.
///
/// Returns a previously stored in-memory key when present, otherwise falls
/// back to the read-only `MAGNOTIA_API_KEY_<PROVIDER>` environment variable so
/// back to the read-only `LUMOTIA_API_KEY_<PROVIDER>` environment variable so
/// operator-supplied secrets still work.
pub fn retrieve_api_key(provider: &str) -> Option<String> {
let env_key = provider_env_key(provider);
@@ -40,7 +40,7 @@ fn api_key_store() -> &'static Mutex<HashMap<String, String>> {
}
fn provider_env_key(provider: &str) -> String {
format!("MAGNOTIA_API_KEY_{}", provider.to_uppercase())
format!("LUMOTIA_API_KEY_{}", provider.to_uppercase())
}
#[cfg(test)]

16
crates/cloud-providers/src/provider.rs
View File

@@ -1,12 +1,12 @@
//! `TranscriptionProvider` is the async-native trait every transcription
//! backend implements, regardless of whether the work happens locally
//! (Whisper, Parakeet, Moonshine via the `LocalProviderAdapter` in
//! `magnotia-transcription`) or remotely (OpenAI Whisper, Groq,
//! `lumotia-transcription`) or remotely (OpenAI Whisper, Groq,
//! Deepgram, etc.).
//!
//! Living in `magnotia-cloud-providers` is deliberate: the AGPL OEM
//! Living in `lumotia-cloud-providers` is deliberate: the AGPL OEM
//! exception (≥£2k/yr) requires a clean trait surface that an OEM
//! licensee can implement without depending on Wyrdnote's transcription
//! licensee can implement without depending on Lumotia's transcription
//! internals. The trait crate stays small; provider implementations
//! sit alongside.
//!
@@ -16,8 +16,8 @@
use std::fmt;
use async_trait::async_trait;
use magnotia_core::error::Result;
use magnotia_core::types::{AudioSamples, ModelId, Transcript, TranscriptionOptions};
use lumotia_core::error::Result;
use lumotia_core::types::{AudioSamples, ModelId, Transcript, TranscriptionOptions};
use serde::{Deserialize, Serialize};
/// Stable, lower-kebab-case identifier for a provider. Used in user
@@ -70,7 +70,7 @@ pub enum CostClass {
}
/// Capabilities a provider advertises to the orchestrator and the UI.
/// Superset of `magnotia_transcription::TranscriberCapabilities` for
/// Superset of `lumotia_transcription::TranscriberCapabilities` for
/// local providers, with extra fields cloud providers populate.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProviderCapabilities {
@@ -175,10 +175,10 @@ mod tests {
engine_id: ProviderId::new("local-whisper"),
model_id: None,
language: Some("en".to_string()),
initial_prompt: Some("Wyrdnote".to_string()),
initial_prompt: Some("Lumotia".to_string()),
};
let opts = profile.to_options();
assert_eq!(opts.language, Some("en".to_string()));
assert_eq!(opts.initial_prompt, Some("Wyrdnote".to_string()));
assert_eq!(opts.initial_prompt, Some("Lumotia".to_string()));
}
}

4
crates/core/Cargo.toml
View File

@@ -1,8 +1,8 @@
[package]
name = "magnotia-core"
name = "lumotia-core"
version = "0.1.0"
edition = "2021"
description = "Core types, constants, traits, hardware detection, and model registry for Magnotia"
description = "Core types, constants, traits, hardware detection, and model registry for Lumotia"
[dependencies]
serde = { version = "1", features = ["derive"] }

10
crates/core/examples/tuning_log_demo.rs
View File

@@ -3,17 +3,17 @@
//! gpu_offloaded) tuples.
//!
//! Run with:
//! cargo run -p magnotia-core --example tuning_log_demo
//! cargo run -p lumotia-core --example tuning_log_demo
//!
//! Output is to stderr (tracing's default). Each unique tuple emits
//! exactly one INFO line; subsequent calls with the same tuple are
//! silenced by the per-process log-once cache.
use magnotia_core::tuning::{inference_thread_count, Workload};
use lumotia_core::tuning::{inference_thread_count, Workload};
fn main() {
tracing_subscriber::fmt()
.with_env_filter("magnotia_core=info")
.with_env_filter("lumotia_core=info")
.with_target(true)
.with_writer(std::io::stderr)
.init();
@@ -28,8 +28,8 @@ fn main() {
("No override (real sysfs probe)", None),
] {
match override_value {
Some(v) => std::env::set_var("MAGNOTIA_POWER_STATE_OVERRIDE", v),
None => std::env::remove_var("MAGNOTIA_POWER_STATE_OVERRIDE"),
Some(v) => std::env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", v),
None => std::env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE"),
}
// Cache invalidation so the live probe re-runs each section.
// Override paths bypass the cache anyway; this is for the

22
crates/core/src/error.rs
View File

@@ -4,12 +4,12 @@ use serde::Serialize;
use crate::types::ModelId;
/// Structured error type for Magnotia.
/// Structured error type for Lumotia.
///
/// Implements `Serialize` so errors can be sent to the frontend as
/// structured JSON rather than opaque strings.
#[derive(Debug, thiserror::Error, Serialize)]
pub enum MagnotiaError {
pub enum Error {
#[error("model not found: {0}")]
ModelNotFound(ModelId),
@@ -22,6 +22,14 @@ pub enum MagnotiaError {
#[error("transcription failed: {0}")]
TranscriptionFailed(String),
/// Inference exceeded the bounded wait imposed by the caller (live
/// session `drain_inference`). The spawned worker has had its abort
/// flag set so whisper-rs will return early on its next
/// abort-callback poll; the lock-up itself is *not* recovered by
/// this error — but the live-session lifecycle can now progress.
#[error("inference timed out after {timeout_ms}ms")]
InferenceTimeout { timeout_ms: u64 },
#[error("audio decode failed: {0}")]
AudioDecodeFailed(String),
@@ -34,7 +42,7 @@ pub enum MagnotiaError {
#[error("file not found: '{}'", .0.display())]
FileNotFound(PathBuf),
/// Structured storage failure flowed up from `magnotia_storage::Error` via
/// Structured storage failure flowed up from `lumotia_storage::Error` via
/// its `From` impl. Display reads through to `detail` so the operation +
/// source context produced by the storage crate isn't double-prefixed.
#[error("{detail}")]
@@ -55,10 +63,10 @@ pub enum MagnotiaError {
},
}
/// Coarse discriminator for `MagnotiaError::Storage`. The storage crate maps
/// Coarse discriminator for `Error::Storage`. The storage crate maps
/// its full typed error onto one of these kinds at the boundary. Backend code
/// that wants finer-grained branching pattern-matches on
/// `magnotia_storage::Error` directly.
/// `lumotia_storage::Error` directly.
#[derive(Debug, Clone, Copy, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum StorageKind {
@@ -70,7 +78,7 @@ pub enum StorageKind {
Filesystem,
}
impl From<std::io::Error> for MagnotiaError {
impl From<std::io::Error> for Error {
fn from(err: std::io::Error) -> Self {
Self::Io {
kind: format!("{:?}", err.kind()),
@@ -80,4 +88,4 @@ impl From<std::io::Error> for MagnotiaError {
}
}
pub type Result<T> = std::result::Result<T, MagnotiaError>;
pub type Result<T> = std::result::Result<T, Error>;

2
crates/core/src/hardware.rs
View File

@@ -19,7 +19,7 @@ pub struct CpuInfo {
}
/// Runtime-detected CPU feature flags relevant to the speech-to-text
/// and LLM backends Magnotia ships. All whisper.cpp / llama.cpp / ggml
/// and LLM backends Lumotia ships. All whisper.cpp / llama.cpp / ggml
/// kernels degrade roughly two tiers without AVX2, which is why we
/// surface it separately: when AVX2 is absent, the UI should warn the
/// user that performance will be a fraction of what they would see

2
crates/core/src/lib.rs
View File

@@ -9,7 +9,7 @@ pub mod recommendation;
pub mod tuning;
pub mod types;
pub use error::{MagnotiaError, Result};
pub use error::{Error, Result};
pub use types::{
AudioSamples, DownloadProgress, EngineName, Megabytes, ModelId, Segment, Transcript,
TranscriptionOptions,

891
crates/core/src/paths.rs
View File

@@ -1,4 +1,4 @@
use std::path::PathBuf;
use std::path::{Path, PathBuf};
use crate::types::ModelId;
@@ -19,7 +19,7 @@ impl AppPaths {
}
pub fn database_path(&self) -> PathBuf {
self.app_data_dir.join("magnotia.db")
self.app_data_dir.join("lumotia.db")
}
pub fn recordings_dir(&self) -> PathBuf {
@@ -63,11 +63,160 @@ pub fn app_data_dir() -> PathBuf {
app_paths().app_data_dir()
}
/// Surfaced when two or more lumotia data-dir candidates exist on disk
/// simultaneously (e.g. both `~/.lumotia` and `~/.local/share/lumotia`).
/// Picking one silently risks pointing at the wrong copy of the user's
/// transcripts. The caller (typically the Tauri setup hook) should refuse
/// to start and surface the paths to the user for manual consolidation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TargetAmbiguityError {
pub candidates: Vec<PathBuf>,
}
impl std::fmt::Display for TargetAmbiguityError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"ambiguous lumotia data directory — multiple candidate paths exist: {}. \
Please consolidate manually (move data into one path and delete the other) \
then restart.",
self.candidates
.iter()
.map(|p| p.display().to_string())
.collect::<Vec<_>>()
.join(", ")
)
}
}
impl std::error::Error for TargetAmbiguityError {}
fn resolve_app_data_dir() -> PathBuf {
match resolve_app_data_dir_strict() {
Ok(p) => p,
Err(e) => {
// Refuse to start rather than silently picking one of several
// candidate target paths. This is intentionally a panic — the
// process must not be allowed to begin writing into the wrong
// half of a split data directory. The setup hook also calls
// `check_target_ambiguity` explicitly to surface this error
// before tracing/log subsystems are spun up.
panic!("{e}");
}
}
}
/// Fallible variant of [`resolve_app_data_dir`]: returns the conventional
/// target path for the current platform, or a [`TargetAmbiguityError`] if
/// more than one candidate target path currently exists on disk.
///
/// Public so that the application setup hook can perform the check
/// explicitly (and report the ambiguity through tracing) rather than
/// relying on the panic that backs the infallible `resolve_app_data_dir`.
pub fn resolve_app_data_dir_strict() -> Result<PathBuf, TargetAmbiguityError> {
let candidates = target_data_dir_candidates();
let existing: Vec<PathBuf> = candidates
.iter()
.filter(|p| p.exists())
.cloned()
.collect();
if existing.len() > 1 {
return Err(TargetAmbiguityError {
candidates: existing,
});
}
// If exactly one candidate exists, prefer it (it's where the user's
// data lives). If none exist, fall through to the platform-canonical
// path so a fresh install creates the right convention.
if existing.len() == 1 {
return Ok(existing.into_iter().next().unwrap());
}
Ok(canonical_target_data_dir())
}
/// Public counterpart to [`resolve_app_data_dir_strict`] returning `Ok(())`
/// when the data dir is unambiguous and the [`TargetAmbiguityError`]
/// otherwise. Useful when the caller just wants to fail-fast at boot
/// without yet caring about the path itself.
pub fn check_target_ambiguity() -> Result<(), TargetAmbiguityError> {
resolve_app_data_dir_strict().map(|_| ())
}
/// All conventional lumotia data-dir target paths for the current
/// platform. Lumotia chooses one canonical path at install time, but a
/// previous magnotia install or a hand-edited XDG_DATA_HOME can leave
/// data in any of these — the migration driver probes them all and the
/// resolver refuses to start if more than one survives.
fn target_data_dir_candidates() -> Vec<PathBuf> {
let mut out = Vec::new();
#[cfg(target_os = "windows")]
{
if let Ok(local_app_data) = std::env::var("LOCALAPPDATA") {
if !local_app_data.is_empty() {
out.push(PathBuf::from(local_app_data).join("lumotia"));
}
}
}
#[cfg(target_os = "macos")]
{
if let Ok(home) = std::env::var("HOME") {
if !home.is_empty() {
out.push(
PathBuf::from(home)
.join("Library")
.join("Application Support")
.join("Lumotia"),
);
}
}
}
#[cfg(target_os = "linux")]
{
if let Ok(home) = std::env::var("HOME") {
if !home.is_empty() {
out.push(PathBuf::from(&home).join(".lumotia"));
if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
if !xdg.is_empty() {
out.push(PathBuf::from(xdg).join("lumotia"));
}
}
out.push(
PathBuf::from(home)
.join(".local")
.join("share")
.join("lumotia"),
);
}
}
}
#[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
{
if let Ok(home) = std::env::var("HOME") {
if !home.is_empty() {
out.push(PathBuf::from(home).join(".lumotia"));
}
}
}
// De-duplicate while preserving order: on Linux XDG_DATA_HOME may be
// set to `~/.local/share` explicitly, in which case the explicit XDG
// candidate and the XDG default collapse to one path.
let mut seen = std::collections::HashSet::new();
out.retain(|p| seen.insert(p.clone()));
out
}
/// The single canonical target path for the current platform — what a
/// fresh install would create. Used when no existing candidate is found.
fn canonical_target_data_dir() -> PathBuf {
#[cfg(target_os = "windows")]
{
let local_app_data = std::env::var("LOCALAPPDATA").unwrap_or_else(|_| ".".to_string());
return PathBuf::from(local_app_data).join("magnotia");
return PathBuf::from(local_app_data).join("lumotia");
}
#[cfg(target_os = "macos")]
@@ -76,56 +225,764 @@ fn resolve_app_data_dir() -> PathBuf {
return PathBuf::from(home)
.join("Library")
.join("Application Support")
.join("Magnotia");
.join("Lumotia");
}
#[cfg(target_os = "linux")]
{
let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
let legacy = PathBuf::from(&home).join(".magnotia");
if legacy.exists() {
return legacy;
}
if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
if !xdg.is_empty() {
return PathBuf::from(xdg).join("magnotia");
return PathBuf::from(xdg).join("lumotia");
}
}
PathBuf::from(home)
.join(".local")
.join("share")
.join("magnotia")
.join("lumotia")
}
#[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
{
let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
PathBuf::from(home).join(".magnotia")
PathBuf::from(home).join(".lumotia")
}
}
/// Outcome of attempting to migrate an existing magnotia-era data directory
/// to its lumotia equivalent on first launch after the rebrand.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MigrationStatus {
/// Renamed legacy dir to the new path. Includes optional db-file rename
/// if `magnotia.db` was found inside.
Migrated {
from: PathBuf,
to: PathBuf,
renamed_db: bool,
},
/// New path already exists. Did not touch legacy (if any) to avoid
/// destroying user data on the new path.
TargetAlreadyExists { target: PathBuf },
/// No legacy data dir on disk. Nothing to do.
NoLegacyFound,
}
/// Probe ALL legacy magnotia data dir paths on the current platform.
/// Returns one (legacy, target) pair per legacy candidate that exists on
/// disk. The target is convention-preserving so the migration lands the
/// same kind of dir it found (dot-home stays dot-home, XDG stays XDG,
/// macOS Application Support stays the same).
///
/// Previously this returned `Option<(legacy, target)>` and short-circuited
/// on the first match. On Linux that allowed a user with both
/// `~/.magnotia` AND `~/.local/share/magnotia` to migrate only one,
/// leaving the other orphaned forever (subsequent boots prefer the new
/// `~/.lumotia` so the XDG legacy is invisible). Now every legacy variant
/// is probed and migrated independently.
fn legacy_and_target_paths() -> Vec<(PathBuf, PathBuf)> {
let mut out = Vec::new();
#[cfg(target_os = "windows")]
{
if let Ok(local_app_data) = std::env::var("LOCALAPPDATA") {
if !local_app_data.is_empty() {
let legacy = PathBuf::from(&local_app_data).join("magnotia");
let target = PathBuf::from(local_app_data).join("lumotia");
if legacy.exists() {
out.push((legacy, target));
}
}
}
}
#[cfg(target_os = "macos")]
{
if let Ok(home) = std::env::var("HOME") {
if !home.is_empty() {
let app_support = PathBuf::from(home)
.join("Library")
.join("Application Support");
let legacy = app_support.join("Magnotia");
let target = app_support.join("Lumotia");
if legacy.exists() {
out.push((legacy, target));
}
}
}
}
#[cfg(target_os = "linux")]
{
if let Ok(home) = std::env::var("HOME") {
if !home.is_empty() {
let dot_legacy = PathBuf::from(&home).join(".magnotia");
if dot_legacy.exists() {
out.push((dot_legacy, PathBuf::from(&home).join(".lumotia")));
}
if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
if !xdg.is_empty() {
let xdg_legacy = PathBuf::from(&xdg).join("magnotia");
if xdg_legacy.exists() {
out.push((xdg_legacy, PathBuf::from(&xdg).join("lumotia")));
}
}
}
let xdg_default_legacy = PathBuf::from(&home)
.join(".local")
.join("share")
.join("magnotia");
if xdg_default_legacy.exists() {
let xdg_default_target = PathBuf::from(&home)
.join(".local")
.join("share")
.join("lumotia");
out.push((xdg_default_legacy, xdg_default_target));
}
}
}
}
#[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
{
if let Ok(home) = std::env::var("HOME") {
if !home.is_empty() {
let legacy = PathBuf::from(&home).join(".magnotia");
let target = PathBuf::from(home).join(".lumotia");
if legacy.exists() {
out.push((legacy, target));
}
}
}
}
// De-duplicate: e.g. XDG_DATA_HOME set explicitly to `~/.local/share`
// would otherwise produce the same pair twice on Linux.
let mut seen = std::collections::HashSet::new();
out.retain(|pair| seen.insert(pair.clone()));
out
}
/// Migrate every legacy magnotia data directory to its
/// convention-preserving lumotia equivalent on first launch. Idempotent:
/// safe to call on every boot.
///
/// Returns one [`MigrationStatus`] per legacy candidate probed, in
/// platform-deterministic order. An empty Vec means there are no legacy
/// directories on disk (clean install). Callers should log per-candidate
/// outcomes and treat any `Err` as a hard startup failure: silently
/// continuing past a migration error orphans user data behind a fresh
/// empty lumotia dir.
///
/// Per-candidate rules (same as before, applied independently to each
/// legacy path that exists):
/// * If the matching target already exists, do nothing for that
/// candidate and emit `TargetAlreadyExists`. We do not destroy
/// lumotia data, even if a stale legacy dir is also present.
/// * If only the legacy path exists, rename it to the matching lumotia
/// target (same convention) and rename `magnotia.db` -> `lumotia.db`
/// inside it if found.
pub fn migrate_legacy_data_dir() -> Result<Vec<MigrationStatus>, std::io::Error> {
migrate_legacy_data_dir_inner(legacy_and_target_paths())
}
/// Test-friendly inner shape: takes the list of (legacy, target) pairs
/// explicitly so tests don't depend on platform-specific HOME /
/// LOCALAPPDATA / XDG env vars.
///
/// An empty input is shorthand for "no legacy on disk" and yields a
/// single [`MigrationStatus::NoLegacyFound`] entry so callers can still
/// rely on a non-empty result to drive their logging.
fn migrate_legacy_data_dir_inner(
pairs: Vec<(PathBuf, PathBuf)>,
) -> Result<Vec<MigrationStatus>, std::io::Error> {
if pairs.is_empty() {
return Ok(vec![MigrationStatus::NoLegacyFound]);
}
let mut out = Vec::with_capacity(pairs.len());
for (from, to) in pairs {
out.push(migrate_one(from, to)?);
}
Ok(out)
}
/// Run the single-candidate migration. Extracted so the driver can loop
/// over every legacy path discovered on disk and surface per-candidate
/// outcomes individually.
fn migrate_one(from: PathBuf, to: PathBuf) -> Result<MigrationStatus, std::io::Error> {
if to.exists() {
return Ok(MigrationStatus::TargetAlreadyExists { target: to });
}
if let Some(parent) = to.parent() {
std::fs::create_dir_all(parent)?;
}
rename_or_copy_tree(&from, &to)?;
let renamed_db = rename_db_file_if_present(&to)?;
Ok(MigrationStatus::Migrated {
from,
to,
renamed_db,
})
}
/// Move a directory tree, falling back to copy + remove if the
/// destination is on a different filesystem (EXDEV / CrossesDevices).
///
/// Real-world cases this defends against:
/// * `~/.magnotia` on the user's home partition, `~/.local/share/lumotia`
/// on a bind-mounted partition.
/// * Encrypted-home (`/home/.ecryptfs/`) vs decrypted view.
/// * `$XDG_DATA_HOME` set to a non-home device.
///
/// On a copy-then-remove fallback we tolerate partial cleanup failure
/// (the source dir not fully deleted) by surfacing the error from the
/// remove step only if the copy succeeded — losing data via a half-rolled
/// migration is worse than leaving a stale legacy dir behind.
fn rename_or_copy_tree(from: &Path, to: &Path) -> Result<(), std::io::Error> {
match std::fs::rename(from, to) {
Ok(()) => Ok(()),
Err(e) if is_cross_device(&e) => {
copy_dir_recursive(from, to)?;
// Only attempt removal after the copy fully succeeded.
// remove_dir_all is best-effort: if it leaves files behind
// (permission edge cases), the user can clean up the stale
// legacy dir manually.
std::fs::remove_dir_all(from)?;
Ok(())
}
Err(e) => Err(e),
}
}
fn is_cross_device(err: &std::io::Error) -> bool {
// ErrorKind::CrossesDevices is stable from Rust 1.85. Fall back to
// the raw OS error code (EXDEV = 18 on Linux, 17 on macOS, 17 on
// BSDs) for older toolchains.
if err.kind() == std::io::ErrorKind::CrossesDevices {
return true;
}
#[cfg(unix)]
{
return matches!(err.raw_os_error(), Some(18));
}
#[allow(unreachable_code)]
false
}
/// Symlink-aware recursive directory copy used by the legacy data-dir
/// migration and by the Tauri-side `app_data_dir` bundle-identifier
/// migration in `src-tauri/src/tauri_app_data_migration.rs`. Exposed as
/// `pub` so callers in sibling crates can reuse the same hardened
/// implementation (see commit history for the symlink-loop defence).
pub fn copy_dir_recursive(from: &Path, to: &Path) -> Result<(), std::io::Error> {
std::fs::create_dir_all(to)?;
for entry in std::fs::read_dir(from)? {
let entry = entry?;
let entry_path = entry.path();
let target_path = to.join(entry.file_name());
// CRITICAL: use file_type() rather than metadata(). metadata()
// follows symlinks, so a directory symlink reports is_dir==true
// and would recurse unconditionally — a self-referential or
// ancestor-targeting directory symlink loops until the disk
// fills. file_type() is symlink-aware on both Unix and Windows.
let file_type = entry.file_type()?;
if file_type.is_symlink() {
// Recreate symlink rather than dereferencing — the
// transcription app stores recording paths verbatim so a
// dereferenced symlink could orphan large audio blobs, and
// a directory symlink is the only way to terminate the
// recursion at the link boundary.
let link_target = std::fs::read_link(&entry_path)?;
#[cfg(unix)]
{
std::os::unix::fs::symlink(link_target, &target_path)?;
}
#[cfg(windows)]
{
// On Windows we have to pick file vs dir symlink at
// creation time. Probe the link target with full
// metadata (it resolves through the link) to decide.
// If the target is missing or unreadable, fall back to
// a file symlink — safer than panicking the migration.
let target_is_dir = std::fs::metadata(&entry_path)
.map(|m| m.is_dir())
.unwrap_or(false);
if target_is_dir {
std::os::windows::fs::symlink_dir(link_target, &target_path)?;
} else {
std::os::windows::fs::symlink_file(link_target, &target_path)?;
}
}
} else if file_type.is_dir() {
copy_dir_recursive(&entry_path, &target_path)?;
} else {
std::fs::copy(&entry_path, &target_path)?;
}
}
Ok(())
}
fn rename_db_file_if_present(dir: &Path) -> Result<bool, std::io::Error> {
let legacy_db = dir.join("magnotia.db");
if !legacy_db.exists() {
return Ok(false);
}
let new_db = dir.join("lumotia.db");
rename_or_copy_file(&legacy_db, &new_db)?;
Ok(true)
}
fn rename_or_copy_file(from: &Path, to: &Path) -> Result<(), std::io::Error> {
match std::fs::rename(from, to) {
Ok(()) => Ok(()),
Err(e) if is_cross_device(&e) => {
std::fs::copy(from, to)?;
std::fs::remove_file(from)?;
Ok(())
}
Err(e) => Err(e),
}
}
#[cfg(test)]
mod tests {
use super::AppPaths;
use super::*;
use crate::types::ModelId;
use std::path::PathBuf;
#[test]
fn derives_all_paths_from_one_base() {
let paths = AppPaths {
app_data_dir: PathBuf::from("/tmp/magnotia-test"),
app_data_dir: PathBuf::from("/tmp/lumotia-test"),
};
assert_eq!(
paths.database_path(),
PathBuf::from("/tmp/magnotia-test/magnotia.db")
PathBuf::from("/tmp/lumotia-test/lumotia.db")
);
assert_eq!(
paths.speech_model_dir(&ModelId::new("whisper-base-en")),
PathBuf::from("/tmp/magnotia-test/models/whisper-base-en")
PathBuf::from("/tmp/lumotia-test/models/whisper-base-en")
);
assert_eq!(
paths.llm_models_dir(),
PathBuf::from("/tmp/magnotia-test/models/llm")
PathBuf::from("/tmp/lumotia-test/models/llm")
);
}
fn unique_tmp(base: &str) -> PathBuf {
let pid = std::process::id();
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0);
std::env::temp_dir().join(format!("lumotia-paths-test-{base}-{pid}-{nanos}"))
}
/// Helper: drive the migration with a single (legacy, target) pair
/// and return the (only) status it produced. Keeps existing tests
/// readable after the Option -> Vec API change.
fn migrate_one_pair_inner(
pair: (PathBuf, PathBuf),
) -> Result<MigrationStatus, std::io::Error> {
let mut statuses = migrate_legacy_data_dir_inner(vec![pair])?;
assert_eq!(
statuses.len(),
1,
"single-pair driver should yield exactly one status"
);
Ok(statuses.pop().unwrap())
}
#[test]
fn migrate_with_legacy_present_renames_dir_and_db() {
let root = unique_tmp("legacy-present");
let legacy = root.join("magnotia");
let target = root.join("lumotia");
std::fs::create_dir_all(&legacy).unwrap();
std::fs::write(legacy.join("magnotia.db"), b"sqlite-stub").unwrap();
std::fs::write(legacy.join("recordings.placeholder"), b"x").unwrap();
let result =
migrate_one_pair_inner((legacy.clone(), target.clone())).expect("migrate ok");
match result {
MigrationStatus::Migrated {
from,
to,
renamed_db,
} => {
assert_eq!(from, legacy);
assert_eq!(to, target);
assert!(renamed_db, "expected db file to be renamed");
}
other => panic!("expected Migrated, got {other:?}"),
}
assert!(!legacy.exists(), "legacy dir should be gone");
assert!(target.exists(), "new dir should exist");
assert!(target.join("lumotia.db").exists(), "db at new name");
assert!(!target.join("magnotia.db").exists(), "old db gone");
assert!(
target.join("recordings.placeholder").exists(),
"other files preserved"
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn migrate_with_both_present_returns_target_exists_and_preserves_lumotia() {
let root = unique_tmp("both-present");
let legacy = root.join("magnotia");
let target = root.join("lumotia");
std::fs::create_dir_all(&legacy).unwrap();
std::fs::create_dir_all(&target).unwrap();
std::fs::write(target.join("lumotia.db"), b"new-data").unwrap();
std::fs::write(legacy.join("magnotia.db"), b"legacy-data").unwrap();
let result =
migrate_one_pair_inner((legacy.clone(), target.clone())).expect("migrate ok");
assert_eq!(
result,
MigrationStatus::TargetAlreadyExists {
target: target.clone()
}
);
assert!(legacy.exists(), "legacy dir preserved");
assert!(target.exists(), "new dir preserved");
assert_eq!(
std::fs::read(target.join("lumotia.db")).unwrap(),
b"new-data".to_vec(),
"lumotia.db not overwritten"
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn migrate_with_neither_present_returns_no_legacy() {
let result = migrate_legacy_data_dir_inner(Vec::new()).expect("migrate ok");
assert_eq!(result, vec![MigrationStatus::NoLegacyFound]);
}
#[test]
fn migrate_with_legacy_present_but_no_db_inside() {
let root = unique_tmp("legacy-no-db");
let legacy = root.join("magnotia");
let target = root.join("lumotia");
std::fs::create_dir_all(&legacy).unwrap();
std::fs::write(legacy.join("recordings.placeholder"), b"x").unwrap();
let result =
migrate_one_pair_inner((legacy.clone(), target.clone())).expect("migrate ok");
match result {
MigrationStatus::Migrated { renamed_db, .. } => {
assert!(!renamed_db, "no db to rename");
}
other => panic!("expected Migrated, got {other:?}"),
}
assert!(target.exists());
assert!(target.join("recordings.placeholder").exists());
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn migrate_preserves_dot_home_to_dot_home_convention() {
// Regression for B2 from Phase 5 QC: dot-home legacy must land in
// dot-home target, not XDG target.
let root = unique_tmp("convention");
let legacy = root.join(".magnotia");
let target = root.join(".lumotia");
std::fs::create_dir_all(&legacy).unwrap();
std::fs::write(legacy.join("magnotia.db"), b"data").unwrap();
let result =
migrate_one_pair_inner((legacy.clone(), target.clone())).expect("migrate ok");
assert!(matches!(result, MigrationStatus::Migrated { .. }));
assert!(target.exists());
assert!(target.join("lumotia.db").exists());
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn copy_dir_recursive_preserves_nested_files_and_directories() {
// Regression for Codex Blocker 11: EXDEV fallback path uses
// copy_dir_recursive. Verify it preserves directory structure,
// file contents, and arbitrary depth.
let root = unique_tmp("copy-recursive");
let src = root.join("legacy");
let dst = root.join("new");
std::fs::create_dir_all(src.join("recordings/2026-05")).unwrap();
std::fs::create_dir_all(src.join("models/whisper-base-en")).unwrap();
std::fs::write(src.join("magnotia.db"), b"sqlite-bytes").unwrap();
std::fs::write(
src.join("recordings/2026-05/clip-001.wav"),
b"wav-bytes",
)
.unwrap();
std::fs::write(src.join("models/whisper-base-en/manifest.json"), b"{}").unwrap();
copy_dir_recursive(&src, &dst).expect("copy ok");
assert_eq!(std::fs::read(dst.join("magnotia.db")).unwrap(), b"sqlite-bytes");
assert_eq!(
std::fs::read(dst.join("recordings/2026-05/clip-001.wav")).unwrap(),
b"wav-bytes"
);
assert!(dst.join("models/whisper-base-en/manifest.json").exists());
// Source still present — copy_dir_recursive does not delete.
assert!(src.exists());
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn rename_or_copy_tree_succeeds_on_same_filesystem() {
// Smoke for the happy path: same-filesystem case uses rename
// and leaves no source behind.
let root = unique_tmp("rename-tree");
let src = root.join("legacy");
let dst = root.join("new");
std::fs::create_dir_all(&src).unwrap();
std::fs::write(src.join("magnotia.db"), b"data").unwrap();
rename_or_copy_tree(&src, &dst).expect("rename ok");
assert!(!src.exists(), "source removed");
assert!(dst.exists(), "destination present");
assert_eq!(std::fs::read(dst.join("magnotia.db")).unwrap(), b"data");
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn is_cross_device_classifies_exdev_error_kind() {
// Synthesise an io::Error tagged with CrossesDevices and ensure
// the classifier returns true. This is the path that triggers
// the copy-then-delete fallback in rename_or_copy_tree on Rust
// 1.85+ toolchains.
let err = std::io::Error::new(std::io::ErrorKind::CrossesDevices, "test exdev");
assert!(is_cross_device(&err));
let unrelated = std::io::Error::new(std::io::ErrorKind::NotFound, "test notfound");
assert!(!is_cross_device(&unrelated));
}
#[cfg(unix)]
#[test]
fn is_cross_device_classifies_raw_exdev_on_unix() {
// Belt-and-braces: ensure raw errno 18 (EXDEV on Linux) is
// classified as cross-device even if the ErrorKind doesn't
// map to CrossesDevices (older toolchains, future kernel
// surprises).
let err = std::io::Error::from_raw_os_error(18);
assert!(is_cross_device(&err));
}
// ------------------------------------------------------------------
// Defect A regression tests: multi-legacy-candidate + ambiguity guard
// ------------------------------------------------------------------
#[test]
fn migrate_handles_both_dot_home_and_xdg() {
// Reproduces the multi-legacy orphan scenario: a Linux user with
// BOTH `~/.magnotia` and `~/.local/share/magnotia` on disk. The
// old code returned `Option<(legacy, target)>` and short-circuited
// on the dot-home variant, leaving the XDG legacy orphaned. The
// new driver loops over the Vec and migrates every candidate.
let root = unique_tmp("both-legacy");
let dot_legacy = root.join(".magnotia");
let dot_target = root.join(".lumotia");
let xdg_legacy = root.join(".local/share/magnotia");
let xdg_target = root.join(".local/share/lumotia");
std::fs::create_dir_all(&dot_legacy).unwrap();
std::fs::create_dir_all(&xdg_legacy).unwrap();
std::fs::write(dot_legacy.join("marker"), b"dot-home").unwrap();
std::fs::write(xdg_legacy.join("marker"), b"xdg").unwrap();
let statuses = migrate_legacy_data_dir_inner(vec![
(dot_legacy.clone(), dot_target.clone()),
(xdg_legacy.clone(), xdg_target.clone()),
])
.expect("migrate ok");
assert_eq!(
statuses.len(),
2,
"expected one status per legacy candidate"
);
for s in &statuses {
assert!(
matches!(s, MigrationStatus::Migrated { .. }),
"expected Migrated, got {s:?}"
);
}
assert!(!dot_legacy.exists(), "dot-home legacy should be gone");
assert!(!xdg_legacy.exists(), "XDG legacy should be gone");
assert!(dot_target.exists(), "dot-home target should exist");
assert!(xdg_target.exists(), "XDG target should exist");
assert_eq!(
std::fs::read(dot_target.join("marker")).unwrap(),
b"dot-home".to_vec(),
"dot-home content preserved"
);
assert_eq!(
std::fs::read(xdg_target.join("marker")).unwrap(),
b"xdg".to_vec(),
"XDG content preserved"
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn resolve_app_data_dir_refuses_on_multiple_targets() {
// Reproduces the stray-dot-home orphan scenario: after a partial
// migration the user may end up with BOTH `~/.lumotia` and
// `~/.local/share/lumotia` on disk. Picking one silently is
// worse than failing fast, so the strict resolver must error
// with both paths surfaced for manual consolidation.
//
// We override HOME so the strict resolver scans inside our
// tempdir, then assert it returns Err with both paths named.
let root = unique_tmp("ambiguous-target");
let fake_home = root.join("home");
std::fs::create_dir_all(&fake_home).unwrap();
let dot = fake_home.join(".lumotia");
let xdg_default = fake_home.join(".local/share/lumotia");
std::fs::create_dir_all(&dot).unwrap();
std::fs::create_dir_all(&xdg_default).unwrap();
// Serialise env mutation: HOME / XDG_DATA_HOME are process-global,
// and other tests in this module rely on them being unchanged.
// We restore the previous values before returning.
let prev_home = std::env::var_os("HOME");
let prev_xdg = std::env::var_os("XDG_DATA_HOME");
// SAFETY: tests in this module that read HOME serialise on this
// exact pattern (set, call, restore) and the process is otherwise
// single-threaded inside a #[test] body.
std::env::set_var("HOME", &fake_home);
std::env::remove_var("XDG_DATA_HOME");
let result = resolve_app_data_dir_strict();
// Restore env BEFORE asserting so a panic doesn't poison
// subsequent tests.
match prev_home {
Some(v) => std::env::set_var("HOME", v),
None => std::env::remove_var("HOME"),
}
if let Some(v) = prev_xdg {
std::env::set_var("XDG_DATA_HOME", v);
}
let err = result.expect_err("expected ambiguity error");
assert!(
err.candidates.iter().any(|p| p == &dot),
"error must name dot-home candidate: {err}"
);
assert!(
err.candidates.iter().any(|p| p == &xdg_default),
"error must name XDG default candidate: {err}"
);
let msg = err.to_string();
assert!(
msg.contains("ambiguous"),
"message should flag ambiguity: {msg}"
);
std::fs::remove_dir_all(&root).ok();
}
// ------------------------------------------------------------------
// Defect B regression tests: copy_dir_recursive symlink loop
// ------------------------------------------------------------------
#[cfg(unix)]
#[test]
fn copy_dir_recursive_does_not_loop_on_self_referential_dir_symlink() {
// The original code used `entry.metadata()` which follows
// symlinks, so a directory symlink reported is_dir==true and
// recursed unconditionally. A self-referential dir symlink would
// then loop until the disk filled. Use file_type() (which does
// NOT follow symlinks), branch on is_symlink() FIRST, and
// recreate the link instead of recursing through it.
let root = unique_tmp("symlink-self");
let src = root.join("src");
let dst = root.join("dst");
std::fs::create_dir_all(&src).unwrap();
std::fs::write(src.join("regular-file"), b"hello").unwrap();
// Self-reference: src/oops -> src.
std::os::unix::fs::symlink(&src, src.join("oops")).unwrap();
copy_dir_recursive(&src, &dst).expect("copy must terminate, not loop");
// The regular file should have been copied.
assert_eq!(std::fs::read(dst.join("regular-file")).unwrap(), b"hello");
// The self-reference should have been recreated as a symlink,
// NOT as a directory full of recursive copies.
let oops = dst.join("oops");
let oops_meta = std::fs::symlink_metadata(&oops).expect("oops should exist");
assert!(
oops_meta.file_type().is_symlink(),
"dst/oops must be a symlink, not a recursive directory copy"
);
// And the link target must be preserved verbatim.
let link_target = std::fs::read_link(&oops).unwrap();
assert_eq!(link_target, src, "symlink target should be preserved");
std::fs::remove_dir_all(&root).ok();
}
#[cfg(unix)]
#[test]
fn copy_dir_recursive_preserves_directory_symlinks() {
// A directory symlink to a real sibling dir must be recreated as
// a symlink in dst (preserving the link-shape), not dereferenced
// into a recursive copy of the sibling's contents.
let root = unique_tmp("symlink-dir");
let src = root.join("src");
let sibling = root.join("sibling");
let dst = root.join("dst");
std::fs::create_dir_all(&src).unwrap();
std::fs::create_dir_all(&sibling).unwrap();
std::fs::write(sibling.join("payload"), b"sibling-data").unwrap();
// src/link -> sibling (directory symlink).
std::os::unix::fs::symlink(&sibling, src.join("link")).unwrap();
copy_dir_recursive(&src, &dst).expect("copy ok");
let dst_link = dst.join("link");
let meta = std::fs::symlink_metadata(&dst_link).expect("dst/link should exist");
assert!(
meta.file_type().is_symlink(),
"dst/link must remain a symlink, not be replaced with a directory copy"
);
// Following the link should still resolve to sibling content;
// the link target must be preserved verbatim.
let link_target = std::fs::read_link(&dst_link).unwrap();
assert_eq!(link_target, sibling, "symlink target should be preserved");
// And we must NOT have written sibling/payload into dst/link/.
// (If link is a symlink, reading dst/link/payload would follow
// it back to sibling/payload, so check on-disk shape instead.)
let entries: Vec<_> = std::fs::read_dir(&dst).unwrap().collect();
let dst_link_entry = entries
.iter()
.find_map(|e| e.as_ref().ok())
.filter(|e| e.file_name() == std::ffi::OsString::from("link"));
if let Some(e) = dst_link_entry {
assert!(
e.file_type().unwrap().is_symlink(),
"directory entry for dst/link must report symlink"
);
}
std::fs::remove_dir_all(&root).ok();
}
}

12
crates/core/src/power.rs
View File

@@ -101,7 +101,7 @@ pub(crate) fn force_set_cache(state: PowerState) {
///
/// Resolution order (highest to lowest priority):
/// 1. In-process test override (set via `with_override` from unit tests).
/// 2. `MAGNOTIA_POWER_STATE_OVERRIDE` env var (`ac` | `battery` | `unknown`,
/// 2. `LUMOTIA_POWER_STATE_OVERRIDE` env var (`ac` | `battery` | `unknown`,
/// case-insensitive). Used by `thread_sweep.rs` integration tests.
/// 3. Linux: `parse_power_state_from_dir("/sys/class/power_supply")`.
/// 4. macOS / Windows / other: `Unknown`.
@@ -136,7 +136,7 @@ pub fn probe_power_state() -> PowerState {
}
fn env_override() -> Option<PowerState> {
let raw = std::env::var("MAGNOTIA_POWER_STATE_OVERRIDE").ok()?;
let raw = std::env::var("LUMOTIA_POWER_STATE_OVERRIDE").ok()?;
match raw.trim().to_ascii_lowercase().as_str() {
"ac" => Some(PowerState::OnAc),
"battery" => Some(PowerState::OnBattery),
@@ -293,21 +293,21 @@ mod tests {
// env-var path tested in isolation under TEST_LOCK so it
// doesn't race with the in-process override tests.
with_override(None, || {
std::env::set_var("MAGNOTIA_POWER_STATE_OVERRIDE", "battery");
std::env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", "battery");
assert_eq!(probe_power_state(), PowerState::OnBattery);
std::env::remove_var("MAGNOTIA_POWER_STATE_OVERRIDE");
std::env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE");
});
}
#[test]
fn env_var_override_garbage_falls_through() {
with_override(None, || {
std::env::set_var("MAGNOTIA_POWER_STATE_OVERRIDE", "nonsense");
std::env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", "nonsense");
// Garbage value falls through to the platform probe.
// We can't assert the platform result so just assert it
// doesn't panic.
let _ = probe_power_state();
std::env::remove_var("MAGNOTIA_POWER_STATE_OVERRIDE");
std::env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE");
});
}

2
crates/core/src/recommendation.rs
View File

@@ -184,7 +184,7 @@ mod tests {
fn parakeet_is_top_recommendation_when_hardware_supports_it() {
// Any machine that fits Parakeet in RAM should see it ranked first —
// Parakeet-TDT is English-only but beats Whisper on English at lower
// latency, so it's Magnotia's default recommendation when eligible.
// latency, so it's Lumotia's default recommendation when eligible.
// (Users on non-English languages adjust manually — handled at the
// settings-UI level, not at the scoring level for now.)
let profile = profile_with_ram(Megabytes(16384));

26
crates/core/src/tuning.rs
View File

@@ -16,7 +16,7 @@ pub const MIN_INFERENCE_THREADS: usize = 2;
/// 8 is a conservative ceiling that leaves <5% on the table for
/// big-iron desktops while keeping consumer 6c/12t laptops out of
/// contention territory. Users can override at runtime via
/// MAGNOTIA_INFERENCE_THREADS.
/// LUMOTIA_INFERENCE_THREADS.
pub const MAX_INFERENCE_THREADS: usize = 8;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -45,13 +45,13 @@ fn log_seen() -> &'static Mutex<HashSet<(Workload, bool, bool)>> {
/// the battery and GPU-offload heuristics.
///
/// Resolution order:
/// 1. `MAGNOTIA_INFERENCE_THREADS=N` — absolute bypass, returns N.
/// 1. `LUMOTIA_INFERENCE_THREADS=N` — absolute bypass, returns N.
/// 2. base = num_cpus::get_physical() (fallback: available_parallelism).
/// 3. on battery → base /= 2.
/// 4. gpu_offloaded → base = min(base, gpu_floor(workload)).
/// 5. clamp to [MIN_INFERENCE_THREADS, MAX_INFERENCE_THREADS].
pub fn inference_thread_count(workload: Workload, gpu_offloaded: bool) -> usize {
if let Ok(s) = std::env::var("MAGNOTIA_INFERENCE_THREADS") {
if let Ok(s) = std::env::var("LUMOTIA_INFERENCE_THREADS") {
if let Ok(n) = s.parse::<usize>() {
if n > 0 {
return n;
@@ -89,7 +89,7 @@ pub fn inference_thread_count(workload: Workload, gpu_offloaded: bool) -> usize
if let Ok(mut seen) = log_seen().lock() {
if seen.insert(key) {
tracing::info!(
target: "magnotia_core::tuning",
target: "lumotia_core::tuning",
threads = final_value,
workload = ?workload,
gpu_offloaded,
@@ -107,7 +107,7 @@ pub fn inference_thread_count(workload: Workload, gpu_offloaded: bool) -> usize
mod tests {
use super::*;
/// Serialises tests that read/write `MAGNOTIA_INFERENCE_THREADS` so
/// Serialises tests that read/write `LUMOTIA_INFERENCE_THREADS` so
/// they don't race under cargo's parallel test runner.
/// Mirrors the pattern used by `power::with_override`.
fn with_thread_env_lock<R>(body: impl FnOnce() -> R) -> R {
@@ -126,7 +126,7 @@ mod tests {
// We can't pin physical exactly without mocking num_cpus; just
// assert the result is in range.
with_thread_env_lock(|| {
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
let n = inference_thread_count(Workload::Llm, false);
assert!(
(MIN_INFERENCE_THREADS..=MAX_INFERENCE_THREADS).contains(&n),
@@ -138,10 +138,10 @@ mod tests {
#[test]
fn env_var_bypasses_clamps() {
with_thread_env_lock(|| {
std::env::set_var("MAGNOTIA_INFERENCE_THREADS", "10");
std::env::set_var("LUMOTIA_INFERENCE_THREADS", "10");
let n = inference_thread_count(Workload::Llm, true);
assert_eq!(n, 10);
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
});
}
@@ -153,7 +153,7 @@ mod tests {
#[test]
fn battery_halves_thread_count() {
with_thread_env_lock(|| {
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
// Measure on battery, then on AC — sequential, not nested,
// to avoid re-entrant deadlock on power::TEST_LOCK.
let on_battery = crate::power::with_override(Some(PowerState::OnBattery), || {
@@ -176,7 +176,7 @@ mod tests {
#[test]
fn gpu_offload_clamps_llm_to_floor() {
with_thread_env_lock(|| {
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
crate::power::with_override(Some(PowerState::OnAc), || {
let n = inference_thread_count(Workload::Llm, true);
assert!(
@@ -191,7 +191,7 @@ mod tests {
#[test]
fn gpu_offload_clamps_whisper_to_floor() {
with_thread_env_lock(|| {
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
crate::power::with_override(Some(PowerState::OnAc), || {
let n = inference_thread_count(Workload::Whisper, true);
// Whisper floor is 4 on machines with >=4 physical cores;
@@ -213,7 +213,7 @@ mod tests {
#[test]
fn gpu_offload_off_does_not_clamp_below_battery_calc() {
with_thread_env_lock(|| {
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
// Sequential measurements; with_override is non-reentrant.
crate::power::with_override(Some(PowerState::OnAc), || {
let no_gpu = inference_thread_count(Workload::Llm, false);
@@ -230,7 +230,7 @@ mod tests {
// wired. This is covered by the other tests too, but kept
// explicitly to document the behaviour.
with_thread_env_lock(|| {
std::env::remove_var("MAGNOTIA_INFERENCE_THREADS");
std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
crate::power::with_override(Some(PowerState::OnBattery), || {
let _ = inference_thread_count(Workload::Llm, true);
let _ = inference_thread_count(Workload::Whisper, false);

12
crates/hotkey/Cargo.toml
View File

@@ -1,11 +1,11 @@
[package]
name = "magnotia-hotkey"
name = "lumotia-hotkey"
version = "0.1.0"
edition = "2021"
description = "Wayland-compatible global hotkey listener for Magnotia — evdev backend with device hotplug"
description = "Wayland-compatible global hotkey listener for Lumotia — evdev backend with device hotplug"
[dependencies]
magnotia-core = { path = "../core" }
lumotia-core = { path = "../core" }
tokio = { version = "1", features = ["rt", "sync", "macros", "time"] }
serde = { version = "1", features = ["derive"] }
tracing = "0.1"
@@ -14,3 +14,9 @@ tracing = "0.1"
evdev = { version = "0.12", features = ["tokio"] }
notify = { version = "7", default-features = false, features = ["macos_fsevent"] }
nix = { version = "0.29", features = ["fs"] }
[dev-dependencies]
# `rt-multi-thread` enables `#[tokio::test(flavor = "multi_thread")]` used by
# the supervisor + listener lifecycle regression tests. Without it the
# concurrency leak coverage cannot exercise real parallelism.
tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "macros", "time"] }

7
crates/hotkey/src/lib.rs
View File

@@ -1,4 +1,4 @@
//! Wayland-compatible global hotkey listener for Magnotia.
//! Wayland-compatible global hotkey listener for Lumotia.
//!
//! On Linux, reads `/dev/input/event*` devices via the `evdev` crate to capture
//! global hotkeys without any display-server dependency. This works on both X11
@@ -8,11 +8,14 @@
//! On non-Linux platforms, this crate is a no-op — the Tauri global-shortcut
//! plugin handles hotkeys there.
//!
//! Architecture stolen from oddlama/whisper-overlay and adapted for Magnotia.
//! Architecture stolen from oddlama/whisper-overlay and adapted for Lumotia.
#[cfg(target_os = "linux")]
mod linux;
#[cfg(target_os = "linux")]
mod supervisor;
#[cfg(target_os = "linux")]
pub use linux::*;

374
crates/hotkey/src/linux.rs
View File

@@ -8,8 +8,19 @@
//! - Device hotplug via `notify` watching `/dev/input/`
//! - Retry loop for udev permission propagation on new devices
//! - Per-device async event streams
//!
//! ## Lifecycle
//!
//! Every task this module spawns is owned by a
//! [`crate::supervisor::SupervisorHandle`] living inside the
//! [`EvdevHotkeyListener`]. On `stop()`, the supervisor sends a broadcast
//! shutdown signal and awaits every `JoinHandle` with a bounded timeout,
//! so a reconfigure cannot leave orphaned listeners alive (which would
//! otherwise hold `event_tx` clones forever and emit duplicate events to
//! the frontend). See `supervisor.rs` for the supervisor and
//! `tests/listener_lifecycle.rs` for the regression tests.
use std::collections::HashSet;
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::Arc;
@@ -17,6 +28,7 @@ use evdev::{AttributeSetRef, Device, InputEventKind, Key};
use notify::{recommended_watcher, EventKind, RecursiveMode, Watcher};
use tokio::sync::{mpsc, watch, Mutex};
use crate::supervisor::SupervisorHandle;
use crate::HotkeyCombo;
/// Events emitted by the hotkey listener.
@@ -28,12 +40,27 @@ pub enum HotkeyEvent {
Released,
}
/// Shared map of attached evdev devices. Keyed by path so attach is
/// idempotent. Membership-only marker — the actual `JoinHandle` for each
/// device listener task lives in the supervisor. Insert-before-spawn
/// under one mutex hold closes the TOCTOU window the previous design had.
type TrackedDevices = Arc<Mutex<HashMap<PathBuf, ()>>>;
/// Manages evdev device listeners and hotplug detection.
///
/// All spawned tasks are owned by an internal
/// [`SupervisorHandle`]. On `stop()` (or `Drop`) every task receives a
/// broadcast shutdown signal and is joined with a per-task timeout so a
/// reconfigure cannot leak listeners.
pub struct EvdevHotkeyListener {
/// Send a new hotkey config to all listener tasks.
hotkey_tx: watch::Sender<Option<HotkeyCombo>>,
/// Signals all tasks to shut down.
shutdown_tx: mpsc::Sender<()>,
/// Tracks every spawned task. Cloned into spawn sites so per-device
/// retry tasks can register their own children.
supervisor: SupervisorHandle,
/// Set to `true` once `stop()` has run so `Drop` skips its
/// best-effort shutdown signal.
stopped: bool,
}
impl EvdevHotkeyListener {
@@ -43,101 +70,71 @@ impl EvdevHotkeyListener {
/// The listener spawns:
/// 1. One async task per input device that has the target key
/// 2. A watcher task that detects new devices via inotify on `/dev/input/`
pub fn start(combo: HotkeyCombo, event_tx: mpsc::Sender<HotkeyEvent>) -> Self {
pub async fn start(combo: HotkeyCombo, event_tx: mpsc::Sender<HotkeyEvent>) -> Self {
let (hotkey_tx, hotkey_rx) = watch::channel(Some(combo));
let (shutdown_tx, mut shutdown_rx) = mpsc::channel::<()>(1);
let tracked: TrackedDevices = Arc::new(Mutex::new(HashMap::new()));
let supervisor = SupervisorHandle::new();
let tracked = Arc::new(Mutex::new(HashSet::<PathBuf>::new()));
// Spawn initial device listeners
let hotkey_rx_clone = hotkey_rx.clone();
let event_tx_clone = event_tx.clone();
let tracked_clone = tracked.clone();
tokio::spawn(async move {
scan_and_attach(&hotkey_rx_clone, &event_tx_clone, &tracked_clone).await;
});
// Spawn hotplug watcher
let hotkey_rx_hotplug = hotkey_rx.clone();
let event_tx_hotplug = event_tx.clone();
let tracked_hotplug = tracked.clone();
tokio::spawn(async move {
let (notify_tx, mut notify_rx) = mpsc::channel::<PathBuf>(32);
// notify watcher runs on a blocking thread internally.
// If inotify itself is unavailable (rare: minimal containers,
// some BSDs misconfigured as Linux) we degrade to "no
// hotplug detection" rather than panicking the task — the
// initial scan_and_attach pass above still picks up all
// devices that exist at startup.
let _watcher = {
let notify_tx = notify_tx.clone();
let watcher = recommended_watcher(move |res: Result<notify::Event, _>| {
if let Ok(event) = res {
if matches!(event.kind, EventKind::Create(_)) {
for path in event.paths {
if is_event_device(&path) {
let _ = notify_tx.blocking_send(path);
}
}
}
}
});
match watcher {
Ok(mut w) => {
match w.watch(Path::new("/dev/input"), RecursiveMode::NonRecursive) {
Ok(()) => Some(w),
Err(e) => {
tracing::warn!(
error = %e,
"cannot watch /dev/input; hotplug detection disabled, \
devices present at startup still work"
);
None
}
}
}
Err(e) => {
tracing::warn!(
error = %e,
"cannot create inotify watcher; hotplug detection disabled"
);
None
}
}
};
loop {
// Spawn initial scanner. Walks /dev/input once and attaches every
// matching device. After it completes the hotplug watcher (below)
// is responsible for keeping the attachment set in sync.
{
let hotkey_rx = hotkey_rx.clone();
let event_tx = event_tx.clone();
let tracked = tracked.clone();
let supervisor_inner = supervisor.clone();
let mut shutdown_rx = supervisor.subscribe();
let scanner_handle = tokio::spawn(async move {
tokio::select! {
Some(path) = notify_rx.recv() => {
// Retry opening with backoff — udev permissions propagate
// asynchronously after device creation (whisper-overlay pattern)
let hotkey_rx = hotkey_rx_hotplug.clone();
let event_tx = event_tx_hotplug.clone();
let tracked = tracked_hotplug.clone();
tokio::spawn(async move {
for attempt in 0..5 {
if attempt > 0 {
tokio::time::sleep(
std::time::Duration::from_secs(1)
).await;
}
if try_attach_device(
&path, &hotkey_rx, &event_tx, &tracked,
).await {
break;
}
}
});
_ = scan_and_attach(
&hotkey_rx,
&event_tx,
&tracked,
&supervisor_inner,
) => {}
_ = shutdown_rx.recv() => {
tracing::debug!(
target: "lumotia_hotkey",
"scanner received shutdown signal mid-scan"
);
}
_ = shutdown_rx.recv() => break,
}
}
});
});
supervisor.register("scanner", scanner_handle).await;
}
// Spawn hotplug watcher. Hands the supervisor handle through so
// it can register retry tasks it spawns.
{
let hotkey_rx = hotkey_rx.clone();
let event_tx = event_tx.clone();
let tracked = tracked.clone();
let supervisor_inner = supervisor.clone();
let mut shutdown_rx = supervisor.subscribe();
let hotplug_handle = tokio::spawn(async move {
run_hotplug_watcher(
hotkey_rx,
event_tx,
tracked,
supervisor_inner,
&mut shutdown_rx,
)
.await;
});
supervisor.register("hotplug", hotplug_handle).await;
}
let task_count = supervisor.task_count().await;
tracing::info!(
target: "lumotia_hotkey",
task_count = task_count,
"supervisor started"
);
Self {
hotkey_tx,
shutdown_tx,
supervisor,
stopped: false,
}
}
@@ -148,9 +145,121 @@ impl EvdevHotkeyListener {
}
/// Stop all listeners and clean up.
pub async fn stop(&self) {
///
/// Consumes the listener so it cannot be reused. Awaits every
/// supervised task with a per-task timeout (see
/// [`SupervisorHandle::shutdown`]); a stuck task is logged and
/// detached rather than blocking the caller indefinitely.
pub async fn stop(mut self) {
// Signal None first so device listeners exit their loop cleanly
// without waiting for the broadcast subscription select arm.
let _ = self.hotkey_tx.send(None);
let _ = self.shutdown_tx.send(()).await;
self.supervisor.shutdown().await;
self.stopped = true;
}
}
/// Best-effort shutdown on drop. Async drop isn't available in stable
/// Rust, so we only fire the broadcast — we cannot await JoinHandles
/// here. Tasks subscribed to the broadcast see the signal and exit
/// cooperatively; their JoinHandles detach but the runtime reclaims them
/// once they finish. The intended path is always explicit `stop().await`
/// before drop.
impl Drop for EvdevHotkeyListener {
fn drop(&mut self) {
if !self.stopped {
self.supervisor.signal_shutdown_nonblocking();
let _ = self.hotkey_tx.send(None);
}
}
}
/// Hotplug watcher loop. Listens for inotify events on `/dev/input/`
/// and dispatches a retry task per new device path. Cooperatively
/// shuts down on broadcast.
async fn run_hotplug_watcher(
hotkey_rx: watch::Receiver<Option<HotkeyCombo>>,
event_tx: mpsc::Sender<HotkeyEvent>,
tracked: TrackedDevices,
supervisor: SupervisorHandle,
shutdown_rx: &mut tokio::sync::broadcast::Receiver<()>,
) {
let (notify_tx, mut notify_rx) = mpsc::channel::<PathBuf>(32);
// notify watcher runs on a blocking thread internally.
// If inotify itself is unavailable (rare: minimal containers,
// some BSDs misconfigured as Linux) we degrade to "no
// hotplug detection" rather than panicking the task — the
// initial scan_and_attach pass above still picks up all
// devices that exist at startup.
let _watcher = {
let notify_tx = notify_tx.clone();
let watcher = recommended_watcher(move |res: Result<notify::Event, _>| {
if let Ok(event) = res {
if matches!(event.kind, EventKind::Create(_)) {
for path in event.paths {
if is_event_device(&path) {
let _ = notify_tx.blocking_send(path);
}
}
}
}
});
match watcher {
Ok(mut w) => match w.watch(Path::new("/dev/input"), RecursiveMode::NonRecursive) {
Ok(()) => Some(w),
Err(e) => {
tracing::warn!(
error = %e,
"cannot watch /dev/input; hotplug detection disabled, \
devices present at startup still work"
);
None
}
},
Err(e) => {
tracing::warn!(
error = %e,
"cannot create inotify watcher; hotplug detection disabled"
);
None
}
}
};
loop {
tokio::select! {
Some(path) = notify_rx.recv() => {
// Retry opening with backoff — udev permissions propagate
// asynchronously after device creation (whisper-overlay pattern).
// The retry task subscribes to the broadcast so it exits
// promptly on stop() even if it's mid-backoff.
let hotkey_rx = hotkey_rx.clone();
let event_tx = event_tx.clone();
let tracked = tracked.clone();
let supervisor_inner = supervisor.clone();
let mut retry_shutdown_rx = supervisor.subscribe();
let retry_handle = tokio::spawn(async move {
for attempt in 0..5 {
if attempt > 0 {
tokio::select! {
_ = tokio::time::sleep(
std::time::Duration::from_secs(1)
) => {}
_ = retry_shutdown_rx.recv() => return,
}
}
if try_attach_device(
&path, &hotkey_rx, &event_tx, &tracked, &supervisor_inner,
).await {
break;
}
}
});
supervisor.register("hotplug-retry", retry_handle).await;
}
_ = shutdown_rx.recv() => break,
}
}
}
@@ -193,7 +302,8 @@ pub fn check_access() -> Result<(), String> {
async fn scan_and_attach(
hotkey_rx: &watch::Receiver<Option<HotkeyCombo>>,
event_tx: &mpsc::Sender<HotkeyEvent>,
tracked: &Arc<Mutex<HashSet<PathBuf>>>,
tracked: &TrackedDevices,
supervisor: &SupervisorHandle,
) {
let input_dir = Path::new("/dev/input");
let entries = match std::fs::read_dir(input_dir) {
@@ -207,21 +317,31 @@ async fn scan_and_attach(
for entry in entries.flatten() {
let path = entry.path();
if is_event_device(&path) {
try_attach_device(&path, hotkey_rx, event_tx, tracked).await;
try_attach_device(&path, hotkey_rx, event_tx, tracked, supervisor).await;
}
}
}
/// Try to open a device and start listening if it supports the target key.
/// Returns true if the device was successfully attached.
///
/// Insert-into-tracked-then-spawn-then-release-mutex makes attachment
/// atomic against concurrent hotplug + scan; the previous design's
/// remove-after-task-exits window allowed double-attaches.
async fn try_attach_device(
path: &Path,
hotkey_rx: &watch::Receiver<Option<HotkeyCombo>>,
event_tx: &mpsc::Sender<HotkeyEvent>,
tracked: &Arc<Mutex<HashSet<PathBuf>>>,
tracked: &TrackedDevices,
supervisor: &SupervisorHandle,
) -> bool {
let mut tracked_set = tracked.lock().await;
if tracked_set.contains(path) {
// Hold the mutex across the contains-check, the insert, AND the
// spawn registration. This is the TOCTOU fix for Race-extra: the
// previous implementation released the mutex before spawning and
// before removal, leaving windows where concurrent scan + hotplug
// could double-attach the same device.
let mut tracked_map = tracked.lock().await;
if tracked_map.contains_key(path) {
return true;
}
@@ -249,27 +369,50 @@ async fn try_attach_device(
"attached hotkey listener"
);
tracked_set.insert(path.to_path_buf());
drop(tracked_set);
// Insert BEFORE spawning the listener task so a racing caller (the
// scanner running concurrently with a hotplug retry, for example)
// sees the entry and short-circuits.
tracked_map.insert(path.to_path_buf(), ());
// Spawn a listener task for this device
let hotkey_rx = hotkey_rx.clone();
let event_tx = event_tx.clone();
// Clone everything the spawned task needs before we release the
// mutex so the release point is a single statement.
let hotkey_rx_owned = hotkey_rx.clone();
let event_tx_owned = event_tx.clone();
let path_owned = path.to_path_buf();
let tracked = tracked.clone();
let tracked_for_cleanup = tracked.clone();
let mut shutdown_rx = supervisor.subscribe();
tokio::spawn(async move {
if let Err(e) = device_listener(device, hotkey_rx, event_tx).await {
tracing::warn!(
path = %path_owned.display(),
error = %e,
"device listener ended"
);
let listener_handle = tokio::spawn(async move {
let listener_fut = device_listener(device, hotkey_rx_owned, event_tx_owned);
tokio::select! {
res = listener_fut => {
if let Err(e) = res {
tracing::warn!(
path = %path_owned.display(),
error = %e,
"device listener ended"
);
}
}
_ = shutdown_rx.recv() => {
tracing::debug!(
target: "lumotia_hotkey",
path = %path_owned.display(),
"device listener received shutdown signal"
);
}
}
// Remove from tracked set so hotplug can re-attach if reconnected
tracked.lock().await.remove(&path_owned);
// Remove from tracked set so hotplug can re-attach if reconnected.
tracked_for_cleanup.lock().await.remove(&path_owned);
});
drop(tracked_map);
// Register with the supervisor. This await is brief — it just locks
// the supervisor inner Vec and pushes — and happens outside the
// tracked-map lock.
supervisor.register("device-listener", listener_handle).await;
true
}
@@ -427,4 +570,11 @@ mod tests {
keys.insert(Key::KEY_R);
assert!(!device_supports_combo(Some(&keys), &combo_for(KEY_D)));
}
// TODO(test): Race-extra (TOCTOU on `tracked`) is hard to exercise
// without real /dev/input/event* devices + the udev attach race.
// The new insert-before-spawn + supervisor-owned-handle design
// closes the window by construction; a deterministic test would need
// to fake the evdev::Device::open path which the crate doesn't
// currently expose. See atomiser finding "Race-extra" for context.
}

12
crates/hotkey/src/stub.rs
View File

@@ -2,6 +2,10 @@
//!
//! On macOS and Windows, Tauri's global-shortcut plugin handles hotkeys
//! natively. This stub exists so the crate compiles on all platforms.
//!
//! The signature here mirrors the Linux backend so the consumer (the
//! Tauri command layer) can use the same call shape on every platform:
//! `EvdevHotkeyListener::start(...).await` and `listener.stop().await`.
use tokio::sync::mpsc;
@@ -18,12 +22,16 @@ pub enum HotkeyEvent {
pub struct EvdevHotkeyListener;
impl EvdevHotkeyListener {
pub fn start(_combo: HotkeyCombo, _event_tx: mpsc::Sender<HotkeyEvent>) -> Self {
/// Mirrors the Linux backend's async constructor so consumers can
/// `await` the same call shape regardless of platform.
pub async fn start(_combo: HotkeyCombo, _event_tx: mpsc::Sender<HotkeyEvent>) -> Self {
tracing::info!("evdev hotkey listener is a no-op on this platform");
Self
}
pub fn set_hotkey(&self, _combo: HotkeyCombo) {}
pub async fn stop(&self) {}
/// Consuming stop mirrors the Linux backend so callers can rely on
/// the listener being unusable after shutdown on every platform.
pub async fn stop(self) {}
}

228
crates/hotkey/src/supervisor.rs Normal file
View File

@@ -0,0 +1,228 @@
//! Task supervisor for the evdev hotkey listener.
//!
//! Owns `JoinHandle`s for every task the listener spawns (scanner, hotplug
//! watcher, hotplug retry tasks, per-device listeners). Provides a
//! broadcast shutdown channel that every cooperating task subscribes to.
//!
//! Three concurrency leaks this fixes:
//! - **Race-1**: per-device listener tasks had no cancellation path, so
//! after `stop()` returned they kept running and emitting events.
//! - **Race-2**: the forwarder task in `commands::hotkey` had no
//! `JoinHandle` tracking, so a reconfigure leaked a permanent forwarder
//! that received duplicated events.
//! - **Race-extra (TOCTOU)**: the `tracked` `HashSet` could miss-attach or
//! double-attach because removal happened after the listener task
//! exited, leaving a window where a concurrent hotplug saw stale state.
//! The new `HashMap<PathBuf, ()>` keyed by canonical path, coupled with
//! insert-before-spawn under one mutex hold, makes attachment atomic.
//!
//! See `tests/listener_lifecycle.rs` for regression coverage.
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::{broadcast, Mutex};
use tokio::task::JoinHandle;
use tokio::time::timeout;
/// How long to wait for any single task to drain on `shutdown()` before
/// we give up and abort it. Two seconds is generous for cooperative
/// shutdown via the broadcast channel — anything slower is treated as a
/// stuck task and force-aborted with a warning so the operator can
/// investigate.
const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(2);
/// Capacity of the broadcast shutdown channel. Eight is far more than we
/// expect to ever need (one slot per concurrent subscriber, drained
/// immediately), but cheap enough that a tighter bound buys us nothing.
const SHUTDOWN_CHANNEL_CAPACITY: usize = 8;
/// Inner state of the supervisor, behind a mutex so concurrent spawn
/// sites can register handles.
struct SupervisorInner {
handles: Vec<(&'static str, JoinHandle<()>)>,
}
/// Shareable handle to a task supervisor. Hand a clone of this to every
/// task that needs to register child tasks (e.g. the hotplug watcher
/// needs to register retry tasks it spawns). The actual shutdown is
/// driven by [`SupervisorHandle::shutdown`], which is called once by the
/// listener's `stop()`.
#[derive(Clone)]
pub(crate) struct SupervisorHandle {
shutdown_tx: broadcast::Sender<()>,
inner: Arc<Mutex<SupervisorInner>>,
}
impl SupervisorHandle {
pub(crate) fn new() -> Self {
let (shutdown_tx, _) = broadcast::channel(SHUTDOWN_CHANNEL_CAPACITY);
Self {
shutdown_tx,
inner: Arc::new(Mutex::new(SupervisorInner {
handles: Vec::new(),
})),
}
}
/// Subscribe to the shutdown signal. Tasks should `tokio::select!`
/// this receiver alongside their work so they exit promptly on
/// `shutdown()`.
pub(crate) fn subscribe(&self) -> broadcast::Receiver<()> {
self.shutdown_tx.subscribe()
}
/// Register a spawned task. The `label` is logged only when the task
/// has to be force-aborted, so concise tags like `"scanner"` are
/// sufficient.
pub(crate) async fn register(&self, label: &'static str, handle: JoinHandle<()>) {
self.inner.lock().await.handles.push((label, handle));
}
/// Current number of registered tasks. Useful for logging.
pub(crate) async fn task_count(&self) -> usize {
self.inner.lock().await.handles.len()
}
/// Fire the shutdown signal WITHOUT awaiting any tasks. Used by
/// `Drop` for paranoia — async drop is not available in stable Rust,
/// so we cannot join handles here.
pub(crate) fn signal_shutdown_nonblocking(&self) {
let _ = self.shutdown_tx.send(());
}
/// Signal every subscriber to shut down, then await each registered
/// task with a per-task timeout. Any task that doesn't drain inside
/// the timeout is detached and logged via `tracing::warn!`.
pub(crate) async fn shutdown(&self) {
// `send` only errors when there are no live receivers, which is a
// perfectly fine state — every subscriber already exited or none
// was ever attached.
let _ = self.shutdown_tx.send(());
// Drain handles. We hold the lock only long enough to swap the
// Vec out so tasks racing to register late don't block our wait.
let handles: Vec<(&'static str, JoinHandle<()>)> = {
let mut guard = self.inner.lock().await;
std::mem::take(&mut guard.handles)
};
let task_count = handles.len();
for (label, handle) in handles {
match timeout(SHUTDOWN_TIMEOUT, handle).await {
Ok(Ok(())) => {
// Clean exit.
}
Ok(Err(join_err)) => {
tracing::warn!(
target: "lumotia_hotkey",
task = label,
error = %join_err,
"supervised task ended abnormally"
);
}
Err(_elapsed) => {
// Timed out — task is stuck. We can't await again
// after the timeout future consumed the handle, so
// log and detach. Every task in this crate selects
// on the shutdown broadcast and sees senders drop,
// so reaching this branch indicates a genuine bug.
tracing::warn!(
target: "lumotia_hotkey",
task = label,
timeout_secs = SHUTDOWN_TIMEOUT.as_secs(),
"supervised task did not drain within timeout; detaching"
);
}
}
}
// Drain anything registered while we were awaiting (a late
// hotplug retry, for instance). These tasks have already seen
// the broadcast and should be on their way out.
let late: Vec<(&'static str, JoinHandle<()>)> = {
let mut guard = self.inner.lock().await;
std::mem::take(&mut guard.handles)
};
let late_count = late.len();
for (label, handle) in late {
match timeout(SHUTDOWN_TIMEOUT, handle).await {
Ok(Ok(())) => {}
Ok(Err(e)) => {
tracing::warn!(
target: "lumotia_hotkey",
task = label,
error = %e,
"late-registered task ended abnormally"
);
}
Err(_) => {
tracing::warn!(
target: "lumotia_hotkey",
task = label,
"late-registered task did not drain"
);
}
}
}
tracing::info!(
target: "lumotia_hotkey",
task_count = task_count + late_count,
"supervisor stopped"
);
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn shutdown_joins_all_registered_tasks() {
let sup = SupervisorHandle::new();
let counter = Arc::new(AtomicUsize::new(0));
for i in 0..5 {
let mut rx = sup.subscribe();
let counter = counter.clone();
let handle = tokio::spawn(async move {
let _ = rx.recv().await;
counter.fetch_add(1, Ordering::SeqCst);
tracing::debug!(task_id = i, "task exiting");
});
sup.register("test-task", handle).await;
}
assert_eq!(sup.task_count().await, 5);
sup.shutdown().await;
assert_eq!(
counter.load(Ordering::SeqCst),
5,
"every registered task should observe shutdown and run its exit path"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn shutdown_force_aborts_stuck_tasks_after_timeout() {
let sup = SupervisorHandle::new();
let handle = tokio::spawn(async move {
// Sleep forever — does NOT subscribe to shutdown.
tokio::time::sleep(Duration::from_secs(3600)).await;
});
sup.register("stuck", handle).await;
let start = std::time::Instant::now();
sup.shutdown().await;
let elapsed = start.elapsed();
assert!(
elapsed < Duration::from_secs(4),
"shutdown should not block past timeout * 2, took {elapsed:?}"
);
}
}

193
crates/hotkey/tests/listener_lifecycle.rs Normal file
View File

@@ -0,0 +1,193 @@
//! Regression tests for the three concurrency leaks the code-atomiser
//! flagged in the hotkey listener:
//!
//! - **Race-1** — orphaned per-device listener tasks after `stop()`.
//! Coverage: `listener_stop_drops_internal_senders` — exercises the
//! only side-effect we can observe through the public API. After
//! `stop()` every internal device-listener task must drop its
//! `mpsc::Sender<HotkeyEvent>` clone, which we detect by asserting
//! that the receiving end's `recv()` returns `None`.
//!
//! - **Race-2** — leaked forwarder task on reconfigure. Coverage:
//! `reconfigure_does_not_leak_forwarder` — simulates the exact pattern
//! the Tauri command layer uses (listener + forwarder pair), confirms
//! that after a reconfigure the OLD forwarder has joined and only the
//! new one is consuming events.
//!
//! - **Race-extra (TOCTOU)** — see `// TODO(test):` in
//! `crates/hotkey/src/linux.rs`. Exercising the TOCTOU window
//! deterministically requires faking the evdev::Device::open path,
//! which the crate does not currently expose. The fix is closed by
//! construction (insert-before-spawn under one mutex hold + supervisor
//! ownership of every spawn handle).
#![cfg(target_os = "linux")]
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
use lumotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent};
use tokio::sync::mpsc;
fn dummy_combo() -> HotkeyCombo {
// KEY_R = 19, the default Lumotia hotkey. No device on the CI box is
// expected to match for actual key events — these tests exercise the
// lifecycle, not the event-firing path.
HotkeyCombo {
ctrl: true,
shift: true,
alt: false,
super_key: false,
key_code: 19,
label: "Ctrl+Shift+R".to_string(),
}
}
/// Race-1 regression. After `stop()`, every device-listener and watcher
/// task spawned by the listener must exit and drop its `event_tx` clone.
/// We detect that by holding the receiving end and observing the
/// channel-closed signal (`recv()` returning `None`).
///
/// If the bug regressed (listeners orphaned), `recv()` would block
/// indefinitely because the leaked tasks still hold sender clones, and
/// the test would time out.
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn listener_stop_drops_internal_senders() {
let (event_tx, mut event_rx) = mpsc::channel::<HotkeyEvent>(64);
let listener = EvdevHotkeyListener::start(dummy_combo(), event_tx).await;
// Let the supervisor spin up its tasks. The scanner+hotplug watcher
// tasks subscribe to broadcast shutdown during construction, so the
// scheduling order doesn't really matter, but we yield once for
// robustness.
tokio::task::yield_now().await;
let stop_start = Instant::now();
listener.stop().await;
let stop_elapsed = stop_start.elapsed();
// Stop must itself be bounded. The supervisor's per-task timeout is
// 2 s, and we have at most a handful of internal tasks (scanner,
// hotplug, plus however many real /dev/input devices the test
// sandbox exposes — usually zero on CI). Cap total stop time at
// 10 s to give us a clear failure rather than a hung CI runner.
assert!(
stop_elapsed < Duration::from_secs(10),
"EvdevHotkeyListener::stop() should bound on supervisor timeout; took {stop_elapsed:?}"
);
// After stop, every internal sender clone must be dropped, which
// closes the channel for the receiver. `recv()` returns None on a
// closed-and-drained channel. We wrap in a timeout so a regressed
// implementation (leaked listener tasks holding sender clones)
// surfaces as a clean assertion failure rather than a hung test.
let recv_result = tokio::time::timeout(Duration::from_secs(5), event_rx.recv()).await;
match recv_result {
Ok(None) => {
// Pass — channel closed, no sender clones leaked.
}
Ok(Some(ev)) => panic!(
"received hotkey event {ev:?} after stop() — listener tasks should have exited \
and dropped their senders, indicating Race-1 regressed"
),
Err(_) => panic!(
"timed out waiting for event_rx to close after stop() — internal sender clones \
were not dropped, indicating Race-1 regressed (orphaned listener tasks)"
),
}
}
/// Race-2 regression. Simulates the Tauri command layer's
/// listener+forwarder pair. After a reconfigure (stop old, start new),
/// only the NEW forwarder must be alive — the previous implementation
/// leaked one forwarder per reconfigure.
///
/// We assert leak-freedom by:
/// 1. Holding a JoinHandle to each forwarder we spawn.
/// 2. After the reconfigure, asserting the old forwarder's JoinHandle
/// is finished within a bounded timeout.
///
/// The new forwarder's JoinHandle must NOT be finished (it's still
/// receiving from the new listener).
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn reconfigure_does_not_leak_forwarder() {
let received_first = Arc::new(AtomicUsize::new(0));
let received_second = Arc::new(AtomicUsize::new(0));
// ---- First listener + forwarder ----
let (event_tx_1, mut event_rx_1) = mpsc::channel::<HotkeyEvent>(64);
let listener_1 = EvdevHotkeyListener::start(dummy_combo(), event_tx_1).await;
let counter_1 = received_first.clone();
let forwarder_1 = tokio::spawn(async move {
while let Some(_event) = event_rx_1.recv().await {
counter_1.fetch_add(1, Ordering::SeqCst);
}
// Returns when the channel closes (all senders dropped). That's
// the only clean way for the forwarder to exit, and it must
// happen on reconfigure for the leak to be fixed.
});
tokio::task::yield_now().await;
// ---- Reconfigure: stop old, start new ----
// This mirrors `start_evdev_hotkey` in src-tauri/src/commands/hotkey.rs
// after the fix: stop old listener (which drains every internal task
// via the supervisor) THEN join the old forwarder (which exits when
// all sender clones drop) BEFORE installing the new pair.
listener_1.stop().await;
// Old forwarder must finish in bounded time. If Race-2 regressed
// (orphaned listener tasks still holding sender clones), the
// forwarder would never see `None` from recv() and this timeout
// would fire.
let join_result =
tokio::time::timeout(Duration::from_secs(5), forwarder_1).await;
assert!(
join_result.is_ok(),
"old forwarder did not join after listener.stop() — Race-2 regressed: \
orphaned listener tasks are still holding event_tx clones"
);
// Verify the inner result (forwarder didn't panic).
join_result.unwrap().expect("old forwarder panicked");
// ---- Second listener + forwarder ----
let (event_tx_2, mut event_rx_2) = mpsc::channel::<HotkeyEvent>(64);
let listener_2 = EvdevHotkeyListener::start(dummy_combo(), event_tx_2).await;
let counter_2 = received_second.clone();
let forwarder_2 = tokio::spawn(async move {
while let Some(_event) = event_rx_2.recv().await {
counter_2.fetch_add(1, Ordering::SeqCst);
}
});
tokio::task::yield_now().await;
// Sanity check: the new forwarder is still running (not yet
// joined). `is_finished()` returns true only when the task has
// completed.
assert!(
!forwarder_2.is_finished(),
"new forwarder must still be running after reconfigure — otherwise \
the new listener's senders were dropped prematurely"
);
// ---- Cleanup ----
listener_2.stop().await;
let cleanup_join =
tokio::time::timeout(Duration::from_secs(5), forwarder_2).await;
assert!(
cleanup_join.is_ok(),
"second forwarder also failed to drain after stop()"
);
// We don't actually assert on the counters — these tests run without
// a matching evdev device, so no Pressed/Released events fire. The
// leak detection is in the JoinHandle behaviour above, not the event
// count. The counters exist so the test compiles as a real
// forwarder pattern matching what commands::hotkey does in
// production.
let _ = (received_first.load(Ordering::SeqCst), received_second.load(Ordering::SeqCst));
}

8
crates/llm/Cargo.toml
View File

@@ -1,13 +1,13 @@
[package]
name = "magnotia-llm"
name = "lumotia-llm"
version = "0.1.0"
edition = "2021"
description = "Local LLM engine for Magnotia (Qwen3.5 / Qwen3.6 via llama-cpp-2): transcript cleanup, task extraction, micro-step decomposition"
description = "Local LLM engine for Lumotia (Qwen3.5 / Qwen3.6 via llama-cpp-2): transcript cleanup, task extraction, micro-step decomposition"
[features]
# Default desktop build keeps the existing openmp + vulkan acceleration.
# Mobile / CPU-only targets can drop one or both via:
# cargo build -p magnotia-llm --no-default-features
# cargo build -p lumotia-llm --no-default-features
# These are independent so an Android Vulkan build can opt into vulkan
# without openmp (the NDK ships OpenMP libs but the toolchain configuration
# is fragile across NDK versions).
@@ -16,7 +16,7 @@ gpu-vulkan = ["llama-cpp-2/vulkan"]
openmp = ["llama-cpp-2/openmp"]
[dependencies]
magnotia-core = { path = "../core" }
lumotia-core = { path = "../core" }
encoding_rs = "0.8"
futures-util = "0.3"
llama-cpp-2 = { version = "0.1.146", default-features = false }

311
crates/llm/src/lib.rs
View File

@@ -1,5 +1,6 @@
use std::num::NonZeroU32;
use std::path::Path;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use encoding_rs::UTF_8;
@@ -9,7 +10,7 @@ use llama_cpp_2::llama_batch::LlamaBatch;
use llama_cpp_2::model::params::LlamaModelParams;
use llama_cpp_2::model::{AddBos, LlamaChatMessage, LlamaChatTemplate, LlamaModel};
use llama_cpp_2::sampling::LlamaSampler;
use magnotia_core::tuning::{inference_thread_count, Workload};
use lumotia_core::tuning::{inference_thread_count, Workload};
use serde::{Deserialize, Serialize};
pub mod grammars;
@@ -31,6 +32,8 @@ pub enum EngineError {
NotLoaded,
#[error("LLM load failed: {0}")]
LoadFailed(String),
#[error("Another LLM load is already in flight; refusing to start a parallel load.")]
AlreadyLoading,
#[error(
"prompt too long: {prompt_tokens} prompt tokens exceed the {available_prompt_tokens}-token prompt budget for an {context_window}-token context with {max_tokens} reserved response tokens"
)]
@@ -83,6 +86,29 @@ struct LlmState {
#[derive(Clone, Default)]
pub struct LlmEngine {
inner: Arc<Mutex<LlmState>>,
/// Flag held for the duration of a model load. The std::sync::Mutex
/// covers cheap state mutations (~microseconds); the multi-second
/// `LlamaModel::load_from_file` call now runs *outside* the mutex,
/// so polls like `is_loaded()` / `loaded_model_id()` (called from
/// sync Tauri handlers without `spawn_blocking`) don't park tokio
/// worker threads on a slow C++ FFI call. This Atomic also doubles
/// as a TOCTOU guard: two concurrent `load_model` invocations on
/// the same engine will not both reach the heavy load — the second
/// returns `EngineError::AlreadyLoading`.
loading: Arc<AtomicBool>,
}
/// RAII guard that clears the `loading` flag on drop, including on
/// panic / early-return. Prevents the engine getting stuck in a
/// "permanently loading" state if a load fails midway.
struct LoadingGuard {
flag: Arc<AtomicBool>,
}
impl Drop for LoadingGuard {
fn drop(&mut self) {
self.flag.store(false, Ordering::Release);
}
}
impl LlmEngine {
@@ -94,24 +120,103 @@ impl LlmEngine {
self.load_model(LlmModelId::default_tier(), model_path, true)
}
// instrument: the load is multi-second (`LlamaBackend::init` +
// mmap + GPU layer init). Tagging events with `model_id` and
// `use_gpu` lets the operator separate the GPU sequential-guard
// logs and llama-backend init lines from the LLM transcription
// pipeline by structured field rather than by adjacency.
#[tracing::instrument(skip_all, fields(model_id = %model_id.as_str(), use_gpu = use_gpu))]
pub fn load_model(
&self,
model_id: LlmModelId,
model_path: &Path,
use_gpu: bool,
) -> Result<(), EngineError> {
let mut guard = self.inner.lock().unwrap();
self.load_model_with(model_id, model_path, use_gpu, |backend, path, params| {
LlamaModel::load_from_file(backend, path, params)
.map_err(|e| EngineError::LoadFailed(format!("model load: {e}")))
})
}
if let Some(loaded) = &guard.loaded {
if loaded.model_id == model_id.as_str()
&& loaded.model_path == model_path.display().to_string()
&& loaded.use_gpu == use_gpu
{
return Ok(());
/// Core load implementation with a swappable file-loader closure.
/// Production callers use `load_model`, which delegates here with
/// the real `LlamaModel::load_from_file`. Tests inject a sleepy /
/// counting closure to exercise the locking discipline without
/// pulling a real GGUF off disk.
///
/// Locking discipline (the whole point of this function):
/// 1. Take the mutex briefly to compare against the currently
/// loaded triple — if it matches, return early. No-op fast path.
/// 2. CAS the `loading` flag from false → true. If another load is
/// already in flight, refuse with `AlreadyLoading` rather than
/// starting a parallel one. A `LoadingGuard` ensures the flag
/// is cleared on every exit path including panic.
/// 3. Take the mutex briefly to drop the OLD model Arc (frees its
/// VRAM via `llama_free_model`) before the new load begins.
/// The backend Arc is preserved — `LlamaBackend::init()` is a
/// one-shot per process (an `AtomicBool` in llama-cpp-2 enforces
/// `BackendAlreadyInitialized` on a second call), so we must
/// never drop the backend while the process keeps running.
/// Note: `is_loaded()` reports false during the swap window —
/// that is the correct semantics. Callers wanting "model X is
/// loaded" must check `loaded_model_id()` against their target.
/// 4. Initialise the backend if absent (first-ever load only) and
/// run the slow `load_from_file` call — both OUTSIDE the mutex.
/// 5. Take the mutex briefly to install the new backend (if just
/// initialised) and the new model Arc.
fn load_model_with<F>(
&self,
model_id: LlmModelId,
model_path: &Path,
use_gpu: bool,
loader: F,
) -> Result<(), EngineError>
where
F: FnOnce(&LlamaBackend, &Path, &LlamaModelParams) -> Result<LlamaModel, EngineError>,
{
// Step 1: short crit section — already-loaded fast path.
{
let guard = self.inner.lock().unwrap();
if let Some(loaded) = &guard.loaded {
if loaded.model_id == model_id.as_str()
&& loaded.model_path == model_path.display().to_string()
&& loaded.use_gpu == use_gpu
{
return Ok(());
}
}
}
let backend = match guard.backend.clone() {
// Step 2: claim the loading slot. Refuse if a parallel load is
// already mid-flight rather than starting a second slow load
// and silently overwriting the first.
if self
.loading
.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
.is_err()
{
return Err(EngineError::AlreadyLoading);
}
let _loading_guard = LoadingGuard {
flag: Arc::clone(&self.loading),
};
// Step 3: short crit section — drop the OLD model so its VRAM is
// released BEFORE we allocate the new one. Without this, a swap
// briefly holds two models resident (Lifecycle-1: an
// ~17 GB Q4 27B swap on a 24 GB card OOMs even though either
// model fits alone). Keep the backend Arc — see locking notes.
let existing_backend = {
let mut guard = self.inner.lock().unwrap();
guard.model = None;
guard.loaded = None;
guard.backend.clone()
};
// Step 4: heavy work OUTSIDE the mutex. `is_loaded()` and
// `loaded_model_id()` can be polled freely here without parking
// tokio worker threads.
let backend = match existing_backend {
Some(existing) => existing,
None => Arc::new(
LlamaBackend::init()
@@ -121,27 +226,72 @@ impl LlmEngine {
let gpu_layers = if use_gpu { u32::MAX } else { 0 };
let params = LlamaModelParams::default().with_n_gpu_layers(gpu_layers);
let model = LlamaModel::load_from_file(&backend, model_path, &params)
.map_err(|e| EngineError::LoadFailed(format!("model load: {e}")))?;
let model = loader(&backend, model_path, &params)?;
guard.backend = Some(backend);
guard.model = Some(Arc::new(model));
guard.loaded = Some(LoadedModelState {
model_id: model_id.as_str().to_string(),
model_path: model_path.display().to_string(),
use_gpu,
});
// Step 5: short crit section — install the new state.
{
let mut guard = self.inner.lock().unwrap();
guard.backend = Some(backend);
guard.model = Some(Arc::new(model));
guard.loaded = Some(LoadedModelState {
model_id: model_id.as_str().to_string(),
model_path: model_path.display().to_string(),
use_gpu,
});
}
// `_loading_guard` drops here and clears the flag.
Ok(())
}
pub fn unload(&self) -> Result<(), EngineError> {
let mut guard = self.inner.lock().unwrap();
guard.model = None;
guard.backend = None;
// Backend is process-singleton (llama-cpp-2 enforces this via
// `LLAMA_BACKEND_INITIALIZED`). Dropping the Arc here would call
// `llama_backend_free` and a subsequent `init` would succeed, but
// we keep it resident to avoid the init/free churn on every
// load/unload cycle.
guard.loaded = None;
Ok(())
}
/// True iff a model load is currently in flight. Exposed for tests
/// + frontends that want to render a "loading…" state without
/// polling `is_loaded()` (which returns false during a swap).
pub fn is_loading(&self) -> bool {
self.loading.load(Ordering::Acquire)
}
/// Test-only harness: runs `op` while holding the same locking
/// discipline as `load_model_with` (loading flag claimed, model
/// state cleared, slow op runs OUTSIDE the inner mutex, new state
/// installed at the end). Used by the regression test to verify
/// that `is_loaded()` / `loaded_model_id()` don't block on the
/// slow section. Not part of the public API.
#[cfg(test)]
pub(crate) fn __test_run_with_lock_discipline<F>(&self, op: F) -> Result<(), EngineError>
where
F: FnOnce(),
{
if self
.loading
.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
.is_err()
{
return Err(EngineError::AlreadyLoading);
}
let _loading_guard = LoadingGuard {
flag: Arc::clone(&self.loading),
};
{
let mut guard = self.inner.lock().unwrap();
guard.model = None;
guard.loaded = None;
}
op();
Ok(())
}
pub fn is_loaded(&self) -> bool {
self.inner.lock().unwrap().model.is_some()
}
@@ -212,7 +362,7 @@ impl LlmEngine {
generated.push_str(&piece);
sampler.accept(next);
if config.grammar.is_some() && json_envelope_complete(&generated) {
if config.grammar.is_none() && json_envelope_complete(&generated) {
break;
}
@@ -666,4 +816,125 @@ mod tests {
let n_ctx = preflight_context_window(7_104, 1_024).unwrap();
assert_eq!(n_ctx, MAX_CONTEXT_TOKENS);
}
/// Race-3 regression. The inner `std::sync::Mutex` MUST NOT be held
/// across the slow `LlamaModel::load_from_file` call: sync Tauri
/// command handlers like `get_llm_status`, `check_llm_model`,
/// `delete_llm_model`, and `test_llm_model` call `is_loaded()` /
/// `loaded_model_id()` from tokio worker threads without
/// `spawn_blocking`. If the lock is held for the duration of a
/// 5-15 s load, parallel status polls from the frontend park the
/// tokio executor and the whole UI deadlocks.
///
/// Pre-fix this test FAILS — both probes time out because the load
/// holds the mutex. Post-fix it PASSES — probes return in ≤50 ms.
#[test]
fn is_loaded_does_not_block_on_slow_load() {
use std::sync::mpsc;
use std::thread;
use std::time::{Duration, Instant};
let engine = LlmEngine::new();
let load_started = Arc::new(std::sync::Barrier::new(2));
let release_load = Arc::new(std::sync::Barrier::new(2));
let engine_for_loader = engine.clone();
let load_started_for_loader = Arc::clone(&load_started);
let release_load_for_loader = Arc::clone(&release_load);
let loader_handle = thread::spawn(move || {
engine_for_loader
.__test_run_with_lock_discipline(|| {
// Signal the probe thread that the load is mid-flight
// (loading flag claimed, inner mutex released).
load_started_for_loader.wait();
// Wait until the probe thread says it's done so the
// load's "duration" is bounded by the probes.
release_load_for_loader.wait();
})
.unwrap();
});
// Wait until the loader is inside its slow section.
load_started.wait();
// Now probe `is_loaded()` and `loaded_model_id()` from this
// thread. They MUST return without contending on the lock.
let probe_deadline = Duration::from_millis(50);
let (tx, rx) = mpsc::channel();
let engine_for_probe = engine.clone();
let probe_handle = thread::spawn(move || {
let start = Instant::now();
let loaded = engine_for_probe.is_loaded();
let id = engine_for_probe.loaded_model_id();
let loading = engine_for_probe.is_loading();
let elapsed = start.elapsed();
tx.send((loaded, id, loading, elapsed)).unwrap();
});
let result = rx
.recv_timeout(probe_deadline)
.expect("is_loaded / loaded_model_id probe must return within 50 ms");
let (loaded, id, loading, elapsed) = result;
assert!(
!loaded,
"is_loaded() should report false while a load is in flight"
);
assert_eq!(id, None, "loaded_model_id() should be None mid-load");
assert!(loading, "is_loading() should report true mid-load");
assert!(
elapsed < probe_deadline,
"probe took {elapsed:?}, expected < {probe_deadline:?}"
);
probe_handle.join().unwrap();
release_load.wait();
loader_handle.join().unwrap();
// After the load completes the flag clears.
assert!(!engine.is_loading());
}
/// Race-3 / Race-4 — concurrent load attempts must not both reach
/// the heavy work. The second caller should be told `AlreadyLoading`
/// rather than starting a parallel load that silently overwrites
/// the first.
#[test]
fn second_concurrent_load_is_refused() {
use std::thread;
let engine = LlmEngine::new();
let load_started = Arc::new(std::sync::Barrier::new(2));
let release_load = Arc::new(std::sync::Barrier::new(2));
let engine_for_loader = engine.clone();
let load_started_for_loader = Arc::clone(&load_started);
let release_load_for_loader = Arc::clone(&release_load);
let loader_handle = thread::spawn(move || {
engine_for_loader
.__test_run_with_lock_discipline(|| {
load_started_for_loader.wait();
release_load_for_loader.wait();
})
.unwrap();
});
load_started.wait();
// Second concurrent attempt MUST be refused, not parallel-load.
let second = engine.__test_run_with_lock_discipline(|| {
panic!("second concurrent load should never reach its op");
});
assert!(matches!(second, Err(EngineError::AlreadyLoading)));
release_load.wait();
loader_handle.join().unwrap();
// After the first load completes, a fresh attempt is allowed.
assert!(engine
.__test_run_with_lock_discipline(|| {})
.is_ok());
}
}

102
crates/llm/src/model_manager.rs
View File

@@ -240,7 +240,7 @@ pub fn recommend_tier(total_ram_bytes: u64, total_vram_bytes: Option<u64>) -> Ll
}
pub fn model_dir() -> PathBuf {
magnotia_core::paths::app_paths().llm_models_dir()
lumotia_core::paths::app_paths().llm_models_dir()
}
pub fn model_path(id: LlmModelId) -> PathBuf {
@@ -276,16 +276,44 @@ where
let _reservation = DownloadReservation::acquire(id)?;
let dest = model_path(id);
tokio::fs::create_dir_all(model_dir()).await?;
download_to(id.hf_url(), id.sha256(), &dest, on_progress).await
}
/// Inner driver split out of `download_model` so the
/// existing-file / SHA-mismatch / new-download decision can be
/// exercised by tests without hitting the hardcoded Hugging Face URLs
/// on `LlmModelId`. Behaviour:
/// 1. If `dest` already exists and its SHA matches — done, no network.
/// 2. If `dest` exists but the SHA mismatches — DO NOT delete; fall
/// through to `download_impl` which writes via `.part` and renames
/// atomically on success. Rev-1 reversibility kill (atomiser
/// 2026-05-12): the previous implementation called
/// `remove_file(&dest)` here before the network round-trip. A
/// network blip / power loss / disk-full between the unlink and
/// the eventual `rename` left users with neither the old
/// (corrupted-but-readable) model nor the new one — a 1.5–20 GB
/// redownload from scratch with no fallback.
/// 3. If `dest` doesn't exist — straight to `download_impl`.
async fn download_to<F>(
url: &str,
expected_sha: &str,
dest: &Path,
on_progress: F,
) -> Result<(), DownloadError>
where
F: FnMut(u64, u64) + Send + 'static,
{
if dest.exists() {
let actual = sha256_file(&dest).await?;
if actual == id.sha256() {
let actual = sha256_file(dest).await?;
if actual == expected_sha {
return Ok(());
}
tokio::fs::remove_file(&dest).await?;
// SHA mismatch: do NOT unlink. `download_impl` writes to a
// `.part` sibling and atomically renames over `dest` once the
// new payload verifies. On failure the user keeps the old
// file (even if "corrupt") rather than ending up with nothing.
}
download_impl(id.hf_url(), id.sha256(), &dest, on_progress).await
download_impl(url, expected_sha, dest, on_progress).await
}
async fn sha256_file(path: &Path) -> Result<String, io::Error> {
@@ -321,7 +349,7 @@ where
.unwrap_or(0);
let client = reqwest::Client::builder()
.user_agent("magnotia/0.1.0")
.user_agent("lumotia/0.1.0")
.connect_timeout(std::time::Duration::from_secs(30))
.build()
.map_err(|e| DownloadError::Http(e.to_string()))?;
@@ -483,4 +511,64 @@ mod tests {
server_task.await.unwrap();
}
/// Rev-1 regression (atomiser 2026-05-12). Before the fix the
/// SHA-mismatch path in `download_model` deleted the existing
/// file BEFORE the network call. A failing download then left
/// the user with neither the old nor the new model.
///
/// We exercise `download_to` (the testable inner driver) with
/// an existing sentinel file at `dest` whose SHA does NOT match
/// the expected one, against a server that returns HTTP 500.
/// The function must fail; the destination must still exist
/// with its original contents.
#[tokio::test]
async fn download_failure_preserves_existing_file() {
let server = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = server.local_addr().unwrap();
let server_task = tokio::spawn(async move {
let (mut socket, _) = server.accept().await.unwrap();
let mut buf = vec![0u8; 2048];
let _ = socket.read(&mut buf).await.unwrap();
let body = b"upstream blew up";
let response = format!(
"HTTP/1.1 500 Internal Server Error\r\nContent-Length: {}\r\n\r\n",
body.len()
);
socket.write_all(response.as_bytes()).await.unwrap();
socket.write_all(body).await.unwrap();
});
let dir = tempdir().unwrap();
let dest = dir.path().join("fixture.gguf");
// Sentinel "old model" file the user already had on disk.
tokio::fs::write(&dest, b"OLD").await.unwrap();
// Expect-sha is deliberately something the OLD file does NOT
// hash to, so the existing-file branch falls through to
// download_impl (the exact case the atomiser flagged).
let expected_sha = "0".repeat(64);
download_to(
&format!("http://{addr}/fixture.gguf"),
&expected_sha,
&dest,
|_, _| {},
)
.await
.expect_err("500 response must fail the download");
assert!(
dest.exists(),
"download failure must leave the existing dest in place"
);
let preserved = tokio::fs::read(&dest).await.unwrap();
assert_eq!(
preserved, b"OLD",
"existing file contents must be untouched on failed download"
);
server_task.await.unwrap();
}
}

4
crates/llm/src/prompts.rs
View File

@@ -45,9 +45,9 @@ context that are not explicit commitments. Output an empty array if there are \
no action items.";
/// Compact representation of a human-in-the-loop feedback example used
/// for few-shot prompt conditioning. Built by magnotia-storage and fed to the
/// for few-shot prompt conditioning. Built by lumotia-storage and fed to the
/// prompt builder below; we keep this struct local to the LLM crate so
/// magnotia-llm does not depend on magnotia-storage.
/// lumotia-llm does not depend on lumotia-storage.
#[derive(Debug, Clone)]
pub struct FeedbackExample {
/// What the AI was given as input (e.g. the parent task text, or

10
crates/llm/tests/content_tags_smoke.rs
View File

@@ -1,23 +1,23 @@
//! Smoke test for Phase 9 LlmEngine::extract_content_tags.
//!
//! Gated behind the same `MAGNOTIA_LLM_TEST_MODEL` env var as the existing
//! Gated behind the same `LUMOTIA_LLM_TEST_MODEL` env var as the existing
//! smoke.rs test so neither runs in default `cargo test` runs (model
//! load is heavy). Run explicitly with:
//!
//! MAGNOTIA_LLM_TEST_MODEL=/path/to/model.gguf cargo test -p magnotia-llm \
//! LUMOTIA_LLM_TEST_MODEL=/path/to/model.gguf cargo test -p lumotia-llm \
//! --test content_tags_smoke -- --nocapture
use std::env;
use std::path::PathBuf;
use magnotia_llm::{is_valid_intent, LlmEngine, LlmModelId};
use lumotia_llm::{is_valid_intent, LlmEngine, LlmModelId};
#[test]
fn extract_content_tags_returns_valid_pair() {
let model_path = match env::var("MAGNOTIA_LLM_TEST_MODEL") {
let model_path = match env::var("LUMOTIA_LLM_TEST_MODEL") {
Ok(path) => PathBuf::from(path),
Err(_) => {
eprintln!("MAGNOTIA_LLM_TEST_MODEL not set — skipping");
eprintln!("LUMOTIA_LLM_TEST_MODEL not set — skipping");
return;
}
};

12
crates/llm/tests/smoke.rs
View File

@@ -6,20 +6,20 @@
//! - `context::params::LlamaContextParams`
//! - `sampling::LlamaSampler`
//!
//! The test is gated behind `MAGNOTIA_LLM_TEST_MODEL`.
//! The test is gated behind `LUMOTIA_LLM_TEST_MODEL`.
use std::env;
use std::path::PathBuf;
use magnotia_llm::LlmEngine;
use magnotia_llm::LlmModelId;
use lumotia_llm::LlmEngine;
use lumotia_llm::LlmModelId;
#[test]
fn llama_cpp_2_smoke_generates_and_wraps() {
let model_path = match env::var("MAGNOTIA_LLM_TEST_MODEL") {
let model_path = match env::var("LUMOTIA_LLM_TEST_MODEL") {
Ok(path) => PathBuf::from(path),
Err(_) => {
eprintln!("MAGNOTIA_LLM_TEST_MODEL not set — skipping");
eprintln!("LUMOTIA_LLM_TEST_MODEL not set — skipping");
return;
}
};
@@ -32,7 +32,7 @@ fn llama_cpp_2_smoke_generates_and_wraps() {
let completion = engine
.generate(
"Write exactly one short greeting.",
&magnotia_llm::GenerationConfig {
&lumotia_llm::GenerationConfig {
max_tokens: 32,
temperature: 0.0,
stop_sequences: vec!["\n".to_string()],

8
crates/mcp/Cargo.toml
View File

@@ -1,18 +1,18 @@
[package]
name = "magnotia-mcp"
name = "lumotia-mcp"
version = "0.1.0"
edition = "2021"
description = "Read-only MCP stdio server exposing Magnotia transcripts and tasks to external agents"
description = "Read-only MCP stdio server exposing Lumotia transcripts and tasks to external agents"
[[bin]]
name = "magnotia-mcp"
name = "lumotia-mcp"
path = "src/main.rs"
[lib]
path = "src/lib.rs"
[dependencies]
magnotia-storage = { path = "../storage" }
lumotia-storage = { path = "../storage" }
sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

24
crates/mcp/src/lib.rs
View File

@@ -1,8 +1,8 @@
//! Minimal Model Context Protocol server exposing Magnotia's local SQLite store.
//! Minimal Model Context Protocol server exposing Lumotia's local SQLite store.
//!
//! Scope: **read-only** tools. An external agent (Claude desktop, Cline, any
//! MCP-capable client) can list / search / fetch transcripts and list tasks.
//! No writes — Magnotia's Tauri app remains the only writer.
//! No writes — Lumotia's Tauri app remains the only writer.
//!
//! Transport: newline-delimited JSON-RPC 2.0 over stdio, per the stdio
//! transport spec. Server spec version: 2024-11-05.
@@ -12,7 +12,7 @@ use serde_json::{json, Value};
use sqlx::SqlitePool;
pub const PROTOCOL_VERSION: &str = "2024-11-05";
pub const SERVER_NAME: &str = "magnotia-mcp";
pub const SERVER_NAME: &str = "lumotia-mcp";
pub const SERVER_VERSION: &str = env!("CARGO_PKG_VERSION");
#[derive(Debug, Deserialize)]
@@ -95,7 +95,7 @@ fn initialize_result() -> Value {
"version": SERVER_VERSION,
},
"instructions":
"Read-only access to Magnotia's local transcript history and task list. \
"Read-only access to Lumotia's local transcript history and task list. \
All data stays on the user's machine.",
})
}
@@ -105,7 +105,7 @@ fn tools_list_result() -> Value {
"tools": [
{
"name": "list_transcripts",
"description": "List recent transcripts from Magnotia's local history, most recent first. \
"description": "List recent transcripts from Lumotia's local history, most recent first. \
Returns summaries (id, title, created_at, duration, preview).",
"inputSchema": {
"type": "object",
@@ -135,7 +135,7 @@ fn tools_list_result() -> Value {
},
{
"name": "search_transcripts",
"description": "Full-text search across Magnotia's transcripts. Returns matching summaries.",
"description": "Full-text search across Lumotia's transcripts. Returns matching summaries.",
"inputSchema": {
"type": "object",
"required": ["query"],
@@ -155,7 +155,7 @@ fn tools_list_result() -> Value {
},
{
"name": "list_tasks",
"description": "List tasks from Magnotia's task store. Returns both open and completed.",
"description": "List tasks from Lumotia's task store. Returns both open and completed.",
"inputSchema": {
"type": "object",
"properties": {},
@@ -206,7 +206,7 @@ async fn list_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value,
};
let limit = args.limit.unwrap_or(20).clamp(1, 200);
let rows = magnotia_storage::list_transcripts(pool, limit)
let rows = lumotia_storage::list_transcripts(pool, limit)
.await
.map_err(|e| error(-32603, format!("DB error: {e}")))?;
@@ -239,7 +239,7 @@ async fn get_transcript_tool(pool: &SqlitePool, args: Value) -> Result<Value, Js
let args: Args = serde_json::from_value(args)
.map_err(|e| error(-32602, format!("Invalid arguments: {e}")))?;
let row = magnotia_storage::get_transcript(pool, &args.id)
let row = lumotia_storage::get_transcript(pool, &args.id)
.await
.map_err(|e| error(-32603, format!("DB error: {e}")))?
.ok_or_else(|| error(-32000, format!("Transcript {} not found", args.id)))?;
@@ -273,7 +273,7 @@ async fn search_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value
.map_err(|e| error(-32602, format!("Invalid arguments: {e}")))?;
let limit = args.limit.unwrap_or(20).clamp(1, 100);
let rows = magnotia_storage::search_transcripts(pool, &args.query, limit)
let rows = lumotia_storage::search_transcripts(pool, &args.query, limit)
.await
.map_err(|e| error(-32603, format!("DB error: {e}")))?;
@@ -296,7 +296,7 @@ async fn search_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value
}
async fn list_tasks_tool(pool: &SqlitePool) -> Result<Value, JsonRpcError> {
let rows = magnotia_storage::list_tasks(pool)
let rows = lumotia_storage::list_tasks(pool)
.await
.map_err(|e| error(-32603, format!("DB error: {e}")))?;
@@ -460,7 +460,7 @@ mod tests {
});
let pool = sqlx::SqlitePool::connect("sqlite::memory:").await.unwrap();
magnotia_storage::migrations::run_migrations(&pool)
lumotia_storage::migrations::run_migrations(&pool)
.await
.unwrap();
let response = handle_message(&pool, request).await.expect("has response");

18
crates/mcp/src/main.rs
View File

@@ -1,22 +1,22 @@
//! Stdio entry point for magnotia-mcp. Reads newline-delimited JSON-RPC messages
//! from stdin, dispatches via `magnotia_mcp::handle_message`, writes responses to
//! Stdio entry point for lumotia-mcp. Reads newline-delimited JSON-RPC messages
//! from stdin, dispatches via `lumotia_mcp::handle_message`, writes responses to
//! stdout. Logs land on stderr so they don't collide with the JSON-RPC stream.
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
#[tokio::main(flavor = "current_thread")]
async fn main() -> anyhow::Result<()> {
let db_path = magnotia_storage::database_path();
let db_path = lumotia_storage::database_path();
eprintln!(
"[magnotia-mcp] opening Magnotia database at {} (read-only)",
"[lumotia-mcp] opening Lumotia database at {} (read-only)",
db_path.display()
);
// Open read-only at the connection level so the MCP server cannot write
// to the user's database, regardless of which tools the dispatcher
// exposes. Migrations are deliberately skipped — this binary never owns
// the schema; the main app is the single migration writer.
let pool = magnotia_storage::init_readonly(&db_path).await?;
eprintln!("[magnotia-mcp] ready, waiting for JSON-RPC on stdin");
let pool = lumotia_storage::init_readonly(&db_path).await?;
eprintln!("[lumotia-mcp] ready, waiting for JSON-RPC on stdin");
let mut lines = BufReader::new(tokio::io::stdin()).lines();
let mut stdout = tokio::io::stdout();
@@ -28,7 +28,7 @@ async fn main() -> anyhow::Result<()> {
}
let response = match serde_json::from_str::<serde_json::Value>(trimmed) {
Ok(raw) => match magnotia_mcp::handle_message(&pool, raw).await {
Ok(raw) => match lumotia_mcp::handle_message(&pool, raw).await {
Some(response) => response,
None => continue, // notification — no reply
},
@@ -38,8 +38,8 @@ async fn main() -> anyhow::Result<()> {
// logged and continued, dropping the response —
// clients saw silence instead of a structured error
// (2026-04-22 review MAJOR).
eprintln!("[magnotia-mcp] parse error: {err}");
magnotia_mcp::parse_error_response(&err.to_string())
eprintln!("[lumotia-mcp] parse error: {err}");
lumotia_mcp::parse_error_response(&err.to_string())
}
};

8
crates/storage/Cargo.toml
View File

@@ -1,11 +1,11 @@
[package]
name = "magnotia-storage"
name = "lumotia-storage"
version = "0.1.0"
edition = "2021"
description = "SQLite persistence, BM25 search, and file storage for Magnotia"
description = "SQLite persistence, BM25 search, and file storage for Lumotia"
[dependencies]
magnotia-core = { path = "../core" }
lumotia-core = { path = "../core" }
# SQLite with compile-time checked queries
# default-features = false strips sqlx's `any`, `macros`, `migrate`, `json` —
@@ -24,7 +24,7 @@ serde = { version = "1", features = ["derive"] }
# Logging
log = "0.4"
# Structured error derivation for magnotia_storage::Error.
# Structured error derivation for lumotia_storage::Error.
thiserror = "1"
# UUIDs for profile + profile_terms ids (v7 random).

532
crates/storage/src/database.rs
View File

@@ -42,7 +42,7 @@ pub async fn init(db_path: &Path) -> Result<SqlitePool> {
/// Open the SQLite database in read-only mode without running migrations.
///
/// Used by `magnotia-mcp` so the MCP server cannot write to the user's database
/// Used by `lumotia-mcp` so the MCP server cannot write to the user's database
/// regardless of which tools the dispatcher exposes — `read_only(true)` makes
/// the constraint structural rather than relying on the request handler being
/// well-behaved. Fails cleanly if the DB doesn't exist (no `create_if_missing`).
@@ -129,9 +129,13 @@ pub async fn insert_transcript(
Ok(())
}
/// Fetch a transcript by id, EXCLUDING soft-deleted (deleted_at IS NOT NULL)
/// rows. Soft-deleted rows are still in the table — they are scoped to the
/// trash view via `list_trashed_transcripts` / `restore_transcript` — but the
/// regular read path treats them as gone. Rev-2 (atomiser 2026-05-12).
pub async fn get_transcript(pool: &SqlitePool, id: &str) -> Result<Option<TranscriptRow>> {
let row = sqlx::query(
"SELECT id, text, source, profile_id, title, audio_path, duration, engine, model_id, inference_ms, sample_rate, audio_channels, format_mode, remove_fillers, british_english, anti_hallucination, created_at, starred, manual_tags, template, language, segments_json, llm_tags FROM transcripts WHERE id = ?",
"SELECT id, text, source, profile_id, title, audio_path, duration, engine, model_id, inference_ms, sample_rate, audio_channels, format_mode, remove_fillers, british_english, anti_hallucination, created_at, starred, manual_tags, template, language, segments_json, llm_tags FROM transcripts WHERE id = ? AND deleted_at IS NULL",
)
.bind(id)
.fetch_optional(pool)
@@ -155,8 +159,11 @@ pub async fn list_transcripts_paged(
limit: i64,
offset: i64,
) -> Result<Vec<TranscriptRow>> {
// `deleted_at IS NULL` filter is the Rev-2 soft-delete contract: rows
// in the trash are kept in the table for restore, but the regular list
// path treats them as gone.
let rows = sqlx::query(
"SELECT id, text, source, profile_id, title, audio_path, duration, engine, model_id, inference_ms, sample_rate, audio_channels, format_mode, remove_fillers, british_english, anti_hallucination, created_at, starred, manual_tags, template, language, segments_json, llm_tags FROM transcripts ORDER BY created_at DESC LIMIT ? OFFSET ?",
"SELECT id, text, source, profile_id, title, audio_path, duration, engine, model_id, inference_ms, sample_rate, audio_channels, format_mode, remove_fillers, british_english, anti_hallucination, created_at, starred, manual_tags, template, language, segments_json, llm_tags FROM transcripts WHERE deleted_at IS NULL ORDER BY created_at DESC LIMIT ? OFFSET ?",
)
.bind(limit)
.bind(offset)
@@ -171,14 +178,18 @@ pub async fn list_transcripts_paged(
}
/// Total count of transcripts. Useful for displaying "showing 50 of 312" in the UI.
/// Excludes soft-deleted (deleted_at IS NOT NULL) rows — they only count
/// toward the trash view.
pub async fn count_transcripts(pool: &SqlitePool) -> Result<i64> {
let n: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM transcripts")
.fetch_one(pool)
.await
.map_err(|source| Error::Query {
operation: "count_transcripts".into(),
source,
})?;
let n: i64 = sqlx::query_scalar(
"SELECT COUNT(*) FROM transcripts WHERE deleted_at IS NULL",
)
.fetch_one(pool)
.await
.map_err(|source| Error::Query {
operation: "count_transcripts".into(),
source,
})?;
Ok(n)
}
@@ -293,13 +304,202 @@ pub async fn update_transcript_meta(
})
}
/// Soft-delete a transcript and best-effort remove its audio file.
///
/// Rev-2 / Rev-3 reversibility kill (atomiser 2026-05-12). The previous
/// implementation issued a hard `DELETE FROM transcripts WHERE id = ?`
/// and never touched the WAV file at `audio_path`. Two failure modes
/// fanned out from that:
///
/// * Rev-2: a single click on the History "Clear All" / "Confirm"
/// button immediately erased months of dictation with no trash,
/// no export, no undo.
/// * Rev-3: even single-row deletes left the audio file on disk;
/// the recordings dir grew monotonically.
///
/// The new contract:
///
/// 1. Capture the existing row (so we still have `audio_path` even if
/// the soft-delete is observed by a parallel reader before we get
/// here).
/// 2. UPDATE deleted_at = datetime('now'). FTS triggers fire on UPDATE
/// and re-index the row, but `search_transcripts` / `list_transcripts`
/// filter `deleted_at IS NULL`, so the trash rows don't surface.
/// 3. Best-effort `tokio::fs::remove_file(audio_path)`. A failure
/// (file already gone, permission denied) is logged but does NOT
/// propagate — the DB soft-delete has already succeeded, and
/// `purge_deleted_transcripts` will retry the removal later via
/// its own audio_path lookup before hard-deleting the row.
///
/// Returns `Ok(())` even when no row matched the id (idempotent).
pub async fn delete_transcript(pool: &SqlitePool, id: &str) -> Result<()> {
sqlx::query("DELETE FROM transcripts WHERE id = ?")
// Capture audio_path FIRST. We deliberately bypass `get_transcript`
// (which filters deleted_at IS NULL) so a double-delete still finds
// the row and the second call is a no-op cleanup rather than an
// error.
let audio_path: Option<String> = sqlx::query_scalar(
"SELECT audio_path FROM transcripts WHERE id = ?",
)
.bind(id)
.fetch_optional(pool)
.await
.map_err(|source| Error::Query {
operation: "delete_transcript".into(),
source,
})?
.flatten();
let res = sqlx::query(
"UPDATE transcripts SET deleted_at = datetime('now') \
WHERE id = ? AND deleted_at IS NULL",
)
.bind(id)
.execute(pool)
.await
.map_err(|source| Error::Query {
operation: "delete_transcript".into(),
source,
})?;
// Best-effort audio cleanup. Only attempt removal when the
// soft-delete actually flipped a row from live -> trashed; on a
// repeat soft-delete the file is already gone (or never existed)
// and there's nothing to do.
if res.rows_affected() > 0 {
if let Some(path) = audio_path.as_deref() {
if let Err(err) = tokio::fs::remove_file(path).await {
if err.kind() != std::io::ErrorKind::NotFound {
log::warn!(
target: "lumotia_storage",
"delete_transcript: failed to remove audio file at {path}: {err}"
);
}
}
}
}
Ok(())
}
/// Hard-delete soft-deleted rows older than `older_than_days`. Intended to
/// run once per startup (or on a daily cron). Returns the number of rows
/// removed.
///
/// FK cascades: `segments` ON DELETE CASCADE (v1) fires; tasks with
/// `source_transcript_id` ON DELETE SET NULL (v8) is preserved.
///
/// Audio files are also best-effort removed here in case the original
/// soft-delete failed at the filesystem layer (Rev-3 belt-and-braces).
pub async fn purge_deleted_transcripts(
pool: &SqlitePool,
older_than_days: i64,
) -> Result<u64> {
// Collect (id, audio_path) BEFORE the DELETE so we still have the
// paths to clean up after the row is gone.
let rows = sqlx::query(
"SELECT id, audio_path FROM transcripts \
WHERE deleted_at IS NOT NULL \
AND deleted_at < datetime('now', ?)",
)
.bind(format!("-{older_than_days} days"))
.fetch_all(pool)
.await
.map_err(|source| Error::Query {
operation: "purge_deleted_transcripts_select".into(),
source,
})?;
if rows.is_empty() {
return Ok(0);
}
let mut ids: Vec<String> = Vec::with_capacity(rows.len());
let mut audio_paths: Vec<String> = Vec::new();
for row in &rows {
let id: String = row.get("id");
let audio: Option<String> = row.get("audio_path");
ids.push(id);
if let Some(p) = audio {
audio_paths.push(p);
}
}
// Build the IN clause manually because sqlx 0.8 doesn't expand Vec
// bindings; we batch into chunks of 200 to stay well clear of
// SQLITE_MAX_VARIABLE_NUMBER (default 999).
let mut total: u64 = 0;
for chunk in ids.chunks(200) {
let placeholders = std::iter::repeat("?")
.take(chunk.len())
.collect::<Vec<_>>()
.join(",");
let sql = format!("DELETE FROM transcripts WHERE id IN ({placeholders})");
let mut q = sqlx::query(&sql);
for id in chunk {
q = q.bind(id);
}
let res = q.execute(pool).await.map_err(|source| Error::Query {
operation: "purge_deleted_transcripts_delete".into(),
source,
})?;
total += res.rows_affected();
}
// Best-effort audio cleanup. NotFound is the expected case for rows
// whose audio was already removed at soft-delete time.
for path in &audio_paths {
if let Err(err) = tokio::fs::remove_file(path).await {
if err.kind() != std::io::ErrorKind::NotFound {
log::warn!(
target: "lumotia_storage",
"purge_deleted_transcripts: failed to remove audio file at {path}: {err}"
);
}
}
}
Ok(total)
}
/// List soft-deleted transcripts (the "trash" view), most-recently-deleted
/// first. The contract mirrors `list_transcripts_paged` but filters
/// `deleted_at IS NOT NULL` so the regular history view and the trash view
/// are exact complements.
pub async fn list_trashed_transcripts(
pool: &SqlitePool,
limit: i64,
offset: i64,
) -> Result<Vec<TranscriptRow>> {
let rows = sqlx::query(
"SELECT id, text, source, profile_id, title, audio_path, duration, engine, model_id, inference_ms, sample_rate, audio_channels, format_mode, remove_fillers, british_english, anti_hallucination, created_at, starred, manual_tags, template, language, segments_json, llm_tags \
FROM transcripts \
WHERE deleted_at IS NOT NULL \
ORDER BY deleted_at DESC LIMIT ? OFFSET ?",
)
.bind(limit)
.bind(offset)
.fetch_all(pool)
.await
.map_err(|source| Error::Query {
operation: "list_trashed_transcripts".into(),
source,
})?;
Ok(rows.iter().map(transcript_row_from).collect())
}
/// Restore a soft-deleted transcript by clearing `deleted_at`. Idempotent:
/// restoring a live row is a no-op. Note that the audio file at
/// `audio_path` may already have been removed by `delete_transcript`'s
/// best-effort filesystem cleanup; restoring the row recovers the text and
/// metadata but the audio may still be missing.
pub async fn restore_transcript(pool: &SqlitePool, id: &str) -> Result<()> {
sqlx::query("UPDATE transcripts SET deleted_at = NULL WHERE id = ?")
.bind(id)
.execute(pool)
.await
.map_err(|source| Error::Query {
operation: "delete_transcript".into(),
operation: "restore_transcript".into(),
source,
})?;
Ok(())
@@ -314,11 +514,15 @@ pub async fn search_transcripts(
query: &str,
limit: i64,
) -> Result<Vec<TranscriptRow>> {
// The FTS triggers from migration v2 keep `transcripts_fts` in sync
// for every INSERT/UPDATE/DELETE — including the soft-delete UPDATE,
// which keeps the row in transcripts_fts. The `t.deleted_at IS NULL`
// filter on the JOIN keeps trashed rows out of search results.
let rows = sqlx::query(
"SELECT t.id, t.text, t.source, t.profile_id, t.title, t.audio_path, t.duration, t.engine, t.model_id, t.inference_ms, t.sample_rate, t.audio_channels, t.format_mode, t.remove_fillers, t.british_english, t.anti_hallucination, t.created_at, t.starred, t.manual_tags, t.template, t.language, t.segments_json, t.llm_tags \
FROM transcripts t \
JOIN transcripts_fts fts ON fts.rowid = t.rowid \
WHERE transcripts_fts MATCH ? \
WHERE transcripts_fts MATCH ? AND t.deleted_at IS NULL \
ORDER BY fts.rank LIMIT ?",
)
.bind(query)
@@ -905,6 +1109,63 @@ pub async fn get_setting(pool: &SqlitePool, key: &str) -> Result<Option<String>>
Ok(row.map(|r| r.get("value")))
}
/// One-shot key rename for settings rows carried over from the magnotia era
/// (`magnotia_preferences`, `magnotia_morning_triage_last_shown`, etc.) to
/// the lumotia naming convention.
///
/// Idempotent. Returns `(renamed, orphans_deleted)`:
/// * `renamed` — rows where only the legacy (magnotia) key existed; the
/// row's key is updated to the lumotia equivalent.
/// * `orphans_deleted` — rows where BOTH keys existed; the new (lumotia)
/// row is authoritative and the legacy (magnotia) row is deleted to
/// avoid silent debt.
pub async fn migrate_legacy_setting_keys(pool: &SqlitePool) -> Result<(u64, u64)> {
let mut tx = pool.begin().await.map_err(|source| Error::Query {
operation: "migrate_legacy_setting_keys:begin".into(),
source,
})?;
let renamed = sqlx::query(
"UPDATE settings \
SET key = 'lumotia_' || substr(key, length('magnotia_') + 1) \
WHERE key LIKE 'magnotia_%' \
AND NOT EXISTS (\
SELECT 1 FROM settings AS dst \
WHERE dst.key = 'lumotia_' || substr(settings.key, length('magnotia_') + 1)\
)",
)
.execute(&mut *tx)
.await
.map_err(|source| Error::Query {
operation: "migrate_legacy_setting_keys:rename".into(),
source,
})?
.rows_affected();
let deleted = sqlx::query(
"DELETE FROM settings \
WHERE key LIKE 'magnotia_%' \
AND EXISTS (\
SELECT 1 FROM settings AS dst \
WHERE dst.key = 'lumotia_' || substr(settings.key, length('magnotia_') + 1)\
)",
)
.execute(&mut *tx)
.await
.map_err(|source| Error::Query {
operation: "migrate_legacy_setting_keys:delete_orphans".into(),
source,
})?
.rows_affected();
tx.commit().await.map_err(|source| Error::Query {
operation: "migrate_legacy_setting_keys:commit".into(),
source,
})?;
Ok((renamed, deleted))
}
// --- Row types ---
#[derive(Debug, Clone)]
@@ -944,7 +1205,7 @@ pub struct TranscriptRow {
pub anti_hallucination: bool,
pub created_at: String,
// Task 2.5 — transcripts_meta (migration v5). Persists the UI metadata
// that previously lived in the removed localStorage `magnotia_history` cache.
// that previously lived in the removed localStorage `lumotia_history` cache.
pub starred: bool,
pub manual_tags: String,
pub template: String,
@@ -1384,7 +1645,7 @@ pub async fn list_recent_errors(pool: &SqlitePool, limit: i64) -> Result<Vec<Err
// Phase 2 of the feature-complete roadmap: capture thumbs + corrections on
// AI-generated output so the prompt builder can inject recent examples as
// few-shot exemplars. Storage-only here; the prompt-conditioning logic lives
// in magnotia-llm. Retrieval returns the most recent rows, narrowed to the
// in lumotia-llm. Retrieval returns the most recent rows, narrowed to the
// active profile when provided so feedback does not cross profiles.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -2617,7 +2878,7 @@ mod tests {
#[tokio::test]
async fn init_readonly_rejects_writes_and_serves_reads() {
let dir = std::env::temp_dir().join(format!("magnotia-storage-ro-{}", std::process::id()));
let dir = std::env::temp_dir().join(format!("lumotia-storage-ro-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("ro.db");
let _ = std::fs::remove_file(&path);
@@ -2669,7 +2930,7 @@ mod tests {
#[tokio::test]
async fn init_readonly_fails_when_db_missing() {
let path = std::env::temp_dir().join(format!(
"magnotia-storage-ro-missing-{}.db",
"lumotia-storage-ro-missing-{}.db",
std::process::id()
));
let _ = std::fs::remove_file(&path);
@@ -2715,4 +2976,241 @@ mod tests {
.unwrap();
assert_eq!(remaining, vec!["recent".to_string()]);
}
#[tokio::test]
async fn migrate_legacy_setting_keys_renames_lone_magnotia_rows() {
let pool = test_pool().await;
set_setting(&pool, "magnotia_preferences", "blob-A")
.await
.unwrap();
set_setting(&pool, "magnotia_morning_triage_last_shown", "2026-05-12")
.await
.unwrap();
let (renamed, deleted) = migrate_legacy_setting_keys(&pool).await.unwrap();
assert_eq!(renamed, 2);
assert_eq!(deleted, 0);
assert_eq!(
get_setting(&pool, "lumotia_preferences")
.await
.unwrap()
.as_deref(),
Some("blob-A")
);
assert_eq!(
get_setting(&pool, "magnotia_preferences").await.unwrap(),
None
);
assert_eq!(
get_setting(&pool, "lumotia_morning_triage_last_shown")
.await
.unwrap()
.as_deref(),
Some("2026-05-12")
);
}
#[tokio::test]
async fn migrate_legacy_setting_keys_deletes_orphans_when_both_present() {
let pool = test_pool().await;
set_setting(&pool, "magnotia_preferences", "legacy-blob")
.await
.unwrap();
set_setting(&pool, "lumotia_preferences", "current-blob")
.await
.unwrap();
let (renamed, deleted) = migrate_legacy_setting_keys(&pool).await.unwrap();
assert_eq!(renamed, 0);
assert_eq!(deleted, 1);
assert_eq!(
get_setting(&pool, "lumotia_preferences")
.await
.unwrap()
.as_deref(),
Some("current-blob"),
"lumotia row preserved verbatim"
);
assert_eq!(
get_setting(&pool, "magnotia_preferences").await.unwrap(),
None,
"orphan lumotia row deleted"
);
}
#[tokio::test]
async fn migrate_legacy_setting_keys_no_op_when_no_magnotia_rows() {
let pool = test_pool().await;
set_setting(&pool, "lumotia_preferences", "blob")
.await
.unwrap();
let (renamed, deleted) = migrate_legacy_setting_keys(&pool).await.unwrap();
assert_eq!(renamed, 0);
assert_eq!(deleted, 0);
}
#[tokio::test]
async fn migrate_legacy_setting_keys_is_idempotent() {
let pool = test_pool().await;
set_setting(&pool, "magnotia_preferences", "blob")
.await
.unwrap();
let first = migrate_legacy_setting_keys(&pool).await.unwrap();
let second = migrate_legacy_setting_keys(&pool).await.unwrap();
assert_eq!(first, (1, 0));
assert_eq!(second, (0, 0));
}
fn minimal_transcript(id: &'static str, audio_path: Option<&'static str>) -> InsertTranscriptParams<'static> {
InsertTranscriptParams {
id,
text: "soft-delete fixture",
source: "microphone",
profile_id: crate::DEFAULT_PROFILE_ID,
title: None,
audio_path,
duration: 1.0,
engine: None,
model_id: None,
inference_ms: None,
sample_rate: None,
audio_channels: None,
format_mode: None,
remove_fillers: false,
british_english: true,
anti_hallucination: false,
}
}
#[tokio::test]
async fn delete_transcript_soft_deletes() {
// Rev-2 contract: delete_transcript flips `deleted_at`, does not
// remove the row. A direct SELECT bypassing the deleted_at filter
// must still find the row.
let pool = test_pool().await;
insert_transcript(&pool, &minimal_transcript("t-soft", None))
.await
.unwrap();
delete_transcript(&pool, "t-soft").await.unwrap();
let deleted_at: Option<String> = sqlx::query_scalar(
"SELECT deleted_at FROM transcripts WHERE id = ?",
)
.bind("t-soft")
.fetch_one(&pool)
.await
.unwrap();
assert!(deleted_at.is_some(), "row should still exist with deleted_at set");
}
#[tokio::test]
async fn delete_transcript_removes_audio_file() {
// Rev-3 contract: best-effort fs::remove_file fires when the
// soft-delete actually flipped a row. A repeat delete is a
// no-op and does NOT fail when the file is already gone.
let pool = test_pool().await;
let tmp = std::env::temp_dir().join(format!(
"lumotia-test-{}.wav",
std::process::id()
));
std::fs::write(&tmp, b"fake wav").unwrap();
let path_owned = tmp.to_string_lossy().to_string();
let path_static: &'static str = Box::leak(path_owned.into_boxed_str());
insert_transcript(&pool, &minimal_transcript("t-audio", Some(path_static)))
.await
.unwrap();
assert!(tmp.exists(), "fixture file should exist pre-delete");
delete_transcript(&pool, "t-audio").await.unwrap();
assert!(!tmp.exists(), "audio file should be removed by delete_transcript");
// Repeat delete must not surface an error even though both the
// soft-delete UPDATE is a no-op AND the audio file is already gone.
delete_transcript(&pool, "t-audio").await.unwrap();
}
#[tokio::test]
async fn list_transcripts_excludes_soft_deleted() {
// Rev-2 list contract: soft-deleted rows are invisible to the
// regular list path; the trash view is the inverse.
let pool = test_pool().await;
insert_transcript(&pool, &minimal_transcript("t-live", None))
.await
.unwrap();
insert_transcript(&pool, &minimal_transcript("t-trashed", None))
.await
.unwrap();
delete_transcript(&pool, "t-trashed").await.unwrap();
let live = list_transcripts(&pool, 100).await.unwrap();
assert_eq!(live.len(), 1);
assert_eq!(live[0].id, "t-live");
let trashed = list_trashed_transcripts(&pool, 100, 0).await.unwrap();
assert_eq!(trashed.len(), 1);
assert_eq!(trashed[0].id, "t-trashed");
let total = count_transcripts(&pool).await.unwrap();
assert_eq!(total, 1, "count_transcripts excludes the trash");
// Restore brings the row back into the live list.
restore_transcript(&pool, "t-trashed").await.unwrap();
let after_restore = list_transcripts(&pool, 100).await.unwrap();
assert_eq!(after_restore.len(), 2);
}
#[tokio::test]
async fn purge_deleted_transcripts_hard_deletes_old() {
// Retention contract: purge_deleted_transcripts hard-removes rows
// whose deleted_at is older than `older_than_days`. Newer trash
// rows are preserved.
let pool = test_pool().await;
insert_transcript(&pool, &minimal_transcript("t-old", None))
.await
.unwrap();
insert_transcript(&pool, &minimal_transcript("t-new", None))
.await
.unwrap();
delete_transcript(&pool, "t-old").await.unwrap();
delete_transcript(&pool, "t-new").await.unwrap();
// Backdate t-old past the 30-day window. t-new keeps "now".
sqlx::query(
"UPDATE transcripts SET deleted_at = datetime('now', '-60 days') WHERE id = ?",
)
.bind("t-old")
.execute(&pool)
.await
.unwrap();
let purged = purge_deleted_transcripts(&pool, 30).await.unwrap();
assert_eq!(purged, 1, "only t-old should be hard-deleted");
let old_exists: Option<String> = sqlx::query_scalar(
"SELECT id FROM transcripts WHERE id = ?",
)
.bind("t-old")
.fetch_optional(&pool)
.await
.unwrap();
assert!(old_exists.is_none(), "t-old should be hard-gone");
let new_exists: Option<String> = sqlx::query_scalar(
"SELECT id FROM transcripts WHERE id = ?",
)
.bind("t-new")
.fetch_optional(&pool)
.await
.unwrap();
assert!(new_exists.is_some(), "t-new still inside the retention window");
}
}

16
crates/storage/src/error.rs
View File

@@ -1,8 +1,8 @@
//! Storage-local typed error.
//!
//! Backend code that wants to branch on storage failure modes pattern-matches
//! on [`Error`] directly. The crate boundary into [`magnotia_core::error::MagnotiaError`]
//! flattens this into a [`MagnotiaError::Storage`] variant carrying a serde-friendly
//! on [`Error`] directly. The crate boundary into [`lumotia_core::error::Error`]
//! flattens this into a [`Error::Storage`] variant carrying a serde-friendly
//! `kind`, an `operation` label, and the Display output as `detail` — so the
//! frontend (which still receives stringified errors from Tauri commands today)
//! keeps working, and Area E can later expose the typed `kind` to the FE without
@@ -14,7 +14,7 @@
use std::borrow::Cow;
use std::path::PathBuf;
use magnotia_core::error::{MagnotiaError, StorageKind};
use lumotia_core::error::{Error as CoreError, StorageKind};
/// Kinds of database-open operation that can fail before the pool is ready.
#[derive(Debug, Clone, Copy)]
@@ -145,7 +145,7 @@ pub enum Error {
}
impl Error {
/// Discriminator for the boundary conversion into [`MagnotiaError`].
/// Discriminator for the boundary conversion into [`Error`].
pub fn kind(&self) -> StorageKind {
match self {
Error::DatabaseOpen { .. } => StorageKind::DatabaseOpen,
@@ -157,7 +157,7 @@ impl Error {
}
}
/// Operation label that flows into the [`MagnotiaError::Storage`] boundary
/// Operation label that flows into the [`Error::Storage`] boundary
/// shape. For per-query failures this is the caller-provided label;
/// for the other variants it's the variant's intrinsic label.
pub fn operation_label(&self) -> Cow<'static, str> {
@@ -175,14 +175,14 @@ impl Error {
}
/// Boundary conversion — flattens the typed error into the wire-friendly
/// [`MagnotiaError::Storage`] variant. Lives in the storage crate (not in core)
/// [`CoreError::Storage`] variant. Lives in the storage crate (not in core)
/// to avoid a `core -> storage` dependency cycle.
impl From<Error> for MagnotiaError {
impl From<Error> for CoreError {
fn from(error: Error) -> Self {
let kind = error.kind();
let operation = error.operation_label().into_owned();
let detail = error.to_string();
MagnotiaError::Storage {
CoreError::Storage {
kind,
operation,
detail,

22
crates/storage/src/file_storage.rs
View File

@@ -1,28 +1,36 @@
use std::path::PathBuf;
pub fn app_data_dir() -> PathBuf {
magnotia_core::paths::app_paths().app_data_dir()
lumotia_core::paths::app_paths().app_data_dir()
}
/// Path to the SQLite database file.
pub fn database_path() -> PathBuf {
magnotia_core::paths::app_paths().database_path()
lumotia_core::paths::app_paths().database_path()
}
/// Directory for saved audio recordings.
pub fn recordings_dir() -> PathBuf {
magnotia_core::paths::app_paths().recordings_dir()
lumotia_core::paths::app_paths().recordings_dir()
}
/// Directory for crash dumps written by the Rust panic hook.
/// Each crash is a single text file: `<unix-ts>-<short-id>.crash`.
/// Used by the diagnostic-report bundler in Settings → About.
pub fn crashes_dir() -> PathBuf {
magnotia_core::paths::app_paths().crashes_dir()
lumotia_core::paths::app_paths().crashes_dir()
}
/// Directory for the rolling Rust log file (magnotia.log + rotated magnotia.log.1, etc).
/// Subscribers configured in src-tauri/src/lib.rs at startup.
/// Directory for the rolling Rust log file.
///
/// The base filename is `lumotia.log`; daily rotation produces dated
/// siblings (e.g. `lumotia.log.2026-05-12`). The appender keeps the
/// 7 most-recent days and prunes older files on rotation.
///
/// Subscriber and rotation policy are configured by `init_tracing` in
/// `src-tauri/src/lib.rs` at startup; the diagnostic-report bundler in
/// `src-tauri/src/commands/diagnostics.rs` attaches the live file from
/// this directory to user-submitted crash reports.
pub fn logs_dir() -> PathBuf {
magnotia_core::paths::app_paths().logs_dir()
lumotia_core::paths::app_paths().logs_dir()
}

9
crates/storage/src/lib.rs
View File

@@ -16,10 +16,11 @@ pub use database::{
get_transcript, init, init_readonly, insert_implementation_rule, insert_subtask, insert_task,
insert_transcript, list_feedback_examples, list_implementation_rules, list_profile_terms,
list_profiles, list_recent_completions, list_recent_errors, list_subtasks, list_tasks,
list_transcripts, list_transcripts_paged, log_error, mark_implementation_rule_fired,
prune_error_log, record_feedback, search_transcripts, set_implementation_rule_enabled,
set_setting, set_task_energy, uncomplete_task, update_profile, update_task, update_transcript,
update_transcript_meta, DailyCompletionCount, ErrorLogRow, FeedbackRow, FeedbackTargetType,
list_transcripts, list_transcripts_paged, list_trashed_transcripts, log_error,
mark_implementation_rule_fired, migrate_legacy_setting_keys, prune_error_log,
purge_deleted_transcripts, record_feedback, restore_transcript, search_transcripts,
set_implementation_rule_enabled, set_setting, set_task_energy, uncomplete_task,
update_profile, update_task, update_transcript, update_transcript_meta, DailyCompletionCount, ErrorLogRow, FeedbackRow, FeedbackTargetType,
ImplementationRuleRow, InsertTranscriptParams, ProfileRow, ProfileTermRow,
RecordFeedbackParams, TaskRow, TranscriptRow,
};

101
crates/storage/src/migrations.rs
View File

@@ -477,6 +477,36 @@ const MIGRATIONS: &[(i64, &str, &str)] = &[
ON transcripts(profile_id, created_at DESC);
"#,
),
(
16,
"transcripts: soft-delete column for trash + audio cleanup (Rev-2, Rev-3)",
r#"
-- Atomiser fix 2026-05-12 — Rev-2 (hard-DELETE w/ no trash) and
-- Rev-3 (orphan WAV files on transcript delete) both fanned out
-- from the same DELETE-based delete path. The new contract:
--
-- * `delete_transcript` UPDATEs deleted_at = datetime('now')
-- and best-effort removes the audio file at audio_path.
-- The DB row is preserved so the user can restore.
-- * `list_transcripts*`, `search_transcripts`, `count_transcripts`
-- filter `deleted_at IS NULL`.
-- * `purge_deleted_transcripts(older_than_days)` does the
-- actual hard DELETE on rows past the retention window,
-- scheduled once at startup. FK CASCADE on segments still
-- fires at purge time.
--
-- Pre-existing rows default to NULL (not deleted). The column
-- is plain TEXT (ISO-8601 datetime), nullable, no CHECK — we
-- only ever compare against datetime('now', '-N days') and
-- IS NULL / IS NOT NULL.
ALTER TABLE transcripts ADD COLUMN deleted_at TEXT;
-- Partial index over the trash so the purge query stays cheap
-- even on databases with months of soft-deleted rows.
CREATE INDEX IF NOT EXISTS idx_transcripts_deleted_at
ON transcripts(deleted_at) WHERE deleted_at IS NOT NULL;
"#,
),
];
/// Split SQL into individual statements, respecting BEGIN...END trigger blocks.
@@ -642,7 +672,7 @@ mod tests {
.fetch_one(&pool)
.await
.unwrap();
assert_eq!(count, 15);
assert_eq!(count, 16);
sqlx::query("INSERT INTO settings (key, value) VALUES ('test', 'value')")
.execute(&pool)
@@ -661,7 +691,7 @@ mod tests {
.fetch_one(&pool)
.await
.unwrap();
assert_eq!(count, 15);
assert_eq!(count, 16);
}
#[tokio::test]
@@ -963,7 +993,7 @@ mod tests {
// dictionary.id is INTEGER PK AUTOINCREMENT (see v2); let SQLite assign rowids.
sqlx::query(
"INSERT INTO dictionary (term, note, created_at) VALUES \
('Magnotia', '', datetime('now')), \
('Lumotia', '', datetime('now')), \
('CORBEL', 'brand', datetime('now')), \
('Wren', '', datetime('now'))",
)
@@ -1199,4 +1229,69 @@ mod tests {
"planner should use the composite index, got plan: {plan:?}",
);
}
#[tokio::test]
async fn migration_v16_adds_deleted_at_column_and_index() {
// Rev-2 / Rev-3 atomiser fix (2026-05-12). Verify the soft-delete
// column is present, nullable, defaulting to NULL on pre-existing
// rows so the migration doesn't accidentally mark old transcripts
// as deleted.
let pool = fk_test_pool().await;
run_migrations_up_to(&pool, 15).await.expect("migrate to v15");
// Seed a pre-v16 row to verify backfill preserves NULL.
sqlx::query(
"INSERT INTO transcripts (
id, text, source, profile_id, title, audio_path, duration,
engine, model_id, inference_ms, sample_rate, audio_channels,
format_mode, remove_fillers, british_english, anti_hallucination,
created_at, starred, manual_tags, template, language,
segments_json, llm_tags
) VALUES (
'pre-v16', 'pre-existing body', 'microphone', ?, 'Pre-V16',
NULL, 1.0, NULL, NULL, NULL, NULL, NULL, NULL, 0, 0, 0,
datetime('now'), 0, '', '', '', '', ''
)",
)
.bind(crate::DEFAULT_PROFILE_ID)
.execute(&pool)
.await
.expect("seed pre-v16 row");
run_migrations(&pool).await.expect("migrate to v16");
let info = sqlx::query("PRAGMA table_info(transcripts)")
.fetch_all(&pool)
.await
.expect("pragma");
let names: Vec<String> = info.iter().map(|r| r.get::<String, _>("name")).collect();
assert!(
names.contains(&"deleted_at".to_string()),
"transcripts must have deleted_at after v16; got {names:?}",
);
// Pre-existing rows must default to NULL — emphatically NOT
// pre-soft-deleted.
let deleted_at: Option<String> =
sqlx::query_scalar("SELECT deleted_at FROM transcripts WHERE id = 'pre-v16'")
.fetch_one(&pool)
.await
.expect("read deleted_at");
assert!(
deleted_at.is_none(),
"pre-v16 rows must have deleted_at = NULL after migration, got {deleted_at:?}",
);
// Partial index exists.
let index_names: Vec<String> = sqlx::query_scalar(
"SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'transcripts'",
)
.fetch_all(&pool)
.await
.expect("read indexes");
assert!(
index_names.iter().any(|n| n == "idx_transcripts_deleted_at"),
"expected idx_transcripts_deleted_at, got {index_names:?}",
);
}
}

14
crates/transcription/Cargo.toml
View File

@@ -1,8 +1,8 @@
[package]
name = "magnotia-transcription"
name = "lumotia-transcription"
version = "0.1.0"
edition = "2021"
description = "Speech-to-text engine wrappers, model management, and inference concurrency for Magnotia"
description = "Speech-to-text engine wrappers, model management, and inference concurrency for Lumotia"
build = "build.rs"
[features]
@@ -15,18 +15,18 @@ build = "build.rs"
# `whisper-vulkan` is a separate feature so a non-Vulkan target (Android
# without GPU drivers, a CPU-only Windows build) can pull in whisper-rs
# but skip the Vulkan backend. Build CPU-only with:
# cargo build -p magnotia-transcription --no-default-features --features whisper
# cargo build -p lumotia-transcription --no-default-features --features whisper
default = ["whisper", "whisper-vulkan"]
whisper = ["dep:whisper-rs"]
whisper-vulkan = ["whisper-rs?/vulkan"]
[dependencies]
magnotia-core = { path = "../core" }
lumotia-core = { path = "../core" }
# TranscriptionProvider async trait + EngineProfile + ProviderId. The
# trait lives in cloud-providers so an OEM licensee can implement it
# without depending on transcription internals.
magnotia-cloud-providers = { path = "../cloud-providers" }
lumotia-cloud-providers = { path = "../cloud-providers" }
# Async-trait for the LocalProviderAdapter impl.
async-trait = "0.1"
@@ -57,12 +57,12 @@ thiserror = "2"
tracing = "0.1"
[dev-dependencies]
# TcpListener fixture for the download resume tests (mirrors magnotia-llm).
# TcpListener fixture for the download resume tests (mirrors lumotia-llm).
# `macros` and `rt-multi-thread` enable #[tokio::test] and the multi-threaded
# scheduler used by the orchestrator tests.
tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "net", "io-util", "macros"] }
tempfile = "3"
# Test-only — used by tests/thread_sweep.rs to label physical vs logical
# core counts in the scaling table. Production code uses the
# `magnotia_core::constants::inference_thread_count` helper instead.
# `lumotia_core::constants::inference_thread_count` helper instead.
num_cpus = "1"

6
crates/transcription/build.rs
View File

@@ -11,7 +11,7 @@
//! workspace ever pulls `tokenizers` into the dependency graph on a
//! Windows target. If we ever legitimately need it we can reintroduce
//! it via a sidecar (isolated process, separate CRT) rather than
//! linking it into `magnotia_lib`.
//! linking it into `lumotia_lib`.
//!
//! The check is advisory on non-Windows targets — it still prints a
//! cargo:warning if `tokenizers` appears, so the Windows failure isn't
@@ -56,7 +56,7 @@ fn main() {
if target_os == "windows" {
panic!(
"magnotia-transcription: the `tokenizers` crate appears in Cargo.lock and this is a \
"lumotia-transcription: the `tokenizers` crate appears in Cargo.lock and this is a \
Windows build. Linking `whisper-rs-sys` + `tokenizers` in the same binary has \
been a persistent MSVC C-runtime conflict (see Whispering v7.11.0). Route any \
tokenizer usage through an out-of-process sidecar instead, or gate it off for \
@@ -65,7 +65,7 @@ fn main() {
}
println!(
"cargo:warning=magnotia-transcription: `tokenizers` crate is in the dependency graph. \
"cargo:warning=lumotia-transcription: `tokenizers` crate is in the dependency graph. \
This build is non-Windows so the link will succeed, but Windows builds will panic \
at build time per docs/whisper-ecosystem/brief.md item #6. Isolate tokenizer usage \
in a sidecar before a Windows ship."

6
crates/transcription/src/concurrency.rs
View File

@@ -1,7 +1,7 @@
use std::sync::Arc;
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::types::{AudioSamples, TranscriptionOptions};
use lumotia_core::error::{Error, Result};
use lumotia_core::types::{AudioSamples, TranscriptionOptions};
use crate::local_engine::{LocalEngine, TimedTranscript};
@@ -14,5 +14,5 @@ pub async fn run_inference(
) -> Result<TimedTranscript> {
tokio::task::spawn_blocking(move || engine.transcribe_sync(&audio, &options))
.await
.map_err(|e| MagnotiaError::TranscriptionFailed(format!("Task join error: {e}")))?
.map_err(|e| Error::TranscriptionFailed(format!("Task join error: {e}")))?
}

6
crates/transcription/src/lib.rs
View File

@@ -23,11 +23,11 @@ pub use transcribe_rs::SpeechModel;
pub use transcriber::{Transcriber, TranscriberCapabilities};
// Re-export the trait surface so downstream crates depend only on
// `magnotia_transcription` to access both local engines and the
// provider trait without a separate `magnotia_cloud_providers`
// `lumotia_transcription` to access both local engines and the
// provider trait without a separate `lumotia_cloud_providers`
// dependency. This is the seam an OEM licensee uses when they swap
// providers.
pub use magnotia_cloud_providers::{
pub use lumotia_cloud_providers::{
CostClass, EngineProfile, NetworkRequirement, ProviderCapabilities, ProviderId, ProviderKind,
ProviderTranscript, TranscriptionProvider,
};

159
crates/transcription/src/local_engine.rs
View File

@@ -1,11 +1,12 @@
use std::path::Path;
use std::sync::Mutex;
use std::sync::atomic::AtomicBool;
use std::sync::{Arc, Mutex};
use std::time::Instant;
use transcribe_rs::{SpeechModel, TranscribeOptions, TranscriptionResult};
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::types::{
use lumotia_core::error::{Error, Result};
use lumotia_core::types::{
AudioSamples, EngineName, ModelId, Segment, Transcript, TranscriptionOptions,
};
@@ -28,7 +29,7 @@ pub struct SpeechModelAdapter(pub Box<dyn SpeechModel + Send>);
impl Transcriber for SpeechModelAdapter {
fn capabilities(&self) -> TranscriberCapabilities {
TranscriberCapabilities {
sample_rate: magnotia_core::constants::WHISPER_SAMPLE_RATE,
sample_rate: lumotia_core::constants::WHISPER_SAMPLE_RATE,
channels: 1,
supports_initial_prompt: false,
}
@@ -48,7 +49,7 @@ impl Transcriber for SpeechModelAdapter {
let result: TranscriptionResult = self
.0
.transcribe(samples, &opts)
.map_err(|e| MagnotiaError::TranscriptionFailed(e.to_string()))?;
.map_err(|e| Error::TranscriptionFailed(e.to_string()))?;
Ok(result
.segments
.unwrap_or_default()
@@ -60,6 +61,32 @@ impl Transcriber for SpeechModelAdapter {
})
.collect())
}
/// SAFETY: `transcribe-rs` owns the Parakeet decoder behind a `&mut
/// self` call that does not surface a cancellation hook. The best we
/// can do without forking transcribe-rs is short-circuit BEFORE the
/// decode call when the live session has already requested abort —
/// the same boundary the `Drop for InferenceTask` cancellation
/// route arrives through. Once the decode is in flight it runs to
/// completion, but the live session's `drain_inference` timeout
/// still drops our receiver, so the wedged orphan thread exits the
/// instant it tries to send its result. The engine `Mutex` is held
/// only across THIS call, so a future task will not deadlock — it
/// simply queues until the orphan releases. Documenting the
/// uncancellable middle so future audits don't get surprised.
fn transcribe_sync_with_abort(
&mut self,
samples: &[f32],
options: &TranscriptionOptions,
abort_flag: Arc<AtomicBool>,
) -> Result<Vec<Segment>> {
if abort_flag.load(std::sync::atomic::Ordering::Relaxed) {
return Err(Error::TranscriptionFailed(
"transcription aborted before decoder dispatch".to_string(),
));
}
self.transcribe_sync(samples, options)
}
}
/// Owns the currently-loaded speech backend and serialises inference
@@ -140,7 +167,7 @@ impl LocalEngine {
options: &TranscriptionOptions,
) -> Result<TimedTranscript> {
let mut guard = self.engine.lock().unwrap_or_else(|e| e.into_inner());
let backend = guard.as_mut().ok_or(MagnotiaError::EngineNotLoaded)?;
let backend = guard.as_mut().ok_or(Error::EngineNotLoaded)?;
let start = Instant::now();
let segments = backend.transcribe_sync(audio.samples(), options)?;
@@ -155,12 +182,42 @@ impl LocalEngine {
inference_ms,
})
}
/// Cancellable variant of `transcribe_sync`. Pipes `abort_flag`
/// through to the backend so the live-session drain timeout can
/// break a wedged whisper-rs decode out of its loop. Every backend
/// MUST implement the trait method (no default impl) — Parakeet's
/// adapter, for example, honours the flag at the pre-decode
/// boundary even though the in-flight decode itself is opaque.
pub fn transcribe_sync_with_abort(
&self,
audio: &AudioSamples,
options: &TranscriptionOptions,
abort_flag: Arc<AtomicBool>,
) -> Result<TimedTranscript> {
let mut guard = self.engine.lock().unwrap_or_else(|e| e.into_inner());
let backend = guard.as_mut().ok_or(Error::EngineNotLoaded)?;
let start = Instant::now();
let segments =
backend.transcribe_sync_with_abort(audio.samples(), options, abort_flag)?;
let inference_ms = start.elapsed().as_millis() as u64;
Ok(TimedTranscript {
transcript: Transcript::new(
segments,
options.language.clone().unwrap_or_else(|| "en".to_string()),
audio.duration_secs(),
),
inference_ms,
})
}
}
/// Thin wrapper over `ParakeetModel` that overrides `transcribe_raw` to
/// request word-granularity segments. `transcribe-rs` 0.3's trait impl for
/// `ParakeetModel::transcribe_raw` ignores `TranscribeOptions` and uses
/// `TimestampGranularity::Token` (per-subword) — which surfaces in Magnotia as
/// `TimestampGranularity::Token` (per-subword) — which surfaces in Lumotia as
/// "T Est Ing . One , Two , Three" output. The concrete-type method
/// `ParakeetModel::transcribe_with` accepts `ParakeetParams` with an
/// explicit granularity; this wrapper exposes that to the trait object.
@@ -197,7 +254,7 @@ impl transcribe_rs::SpeechModel for ParakeetWordGranularity {
pub fn load_parakeet(model_dir: &Path) -> Result<Box<dyn Transcriber + Send>> {
use transcribe_rs::onnx::Quantization;
let model = transcribe_rs::onnx::parakeet::ParakeetModel::load(model_dir, &Quantization::Int8)
.map_err(|e| MagnotiaError::TranscriptionFailed(format!("Failed to load Parakeet: {e}")))?;
.map_err(|e| Error::TranscriptionFailed(format!("Failed to load Parakeet: {e}")))?;
Ok(Box::new(SpeechModelAdapter(Box::new(
ParakeetWordGranularity(model),
))))
@@ -207,13 +264,15 @@ pub fn load_parakeet(model_dir: &Path) -> Result<Box<dyn Transcriber + Send>> {
#[cfg(feature = "whisper")]
pub fn load_whisper(model_path: &Path) -> Result<Box<dyn Transcriber + Send>> {
let backend = WhisperRsBackend::load(model_path)
.map_err(|e| MagnotiaError::TranscriptionFailed(format!("Failed to load Whisper: {e}")))?;
.map_err(|e| Error::TranscriptionFailed(format!("Failed to load Whisper: {e}")))?;
Ok(Box::new(backend))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::Ordering;
use transcribe_rs::{ModelCapabilities, TranscribeError, TranscribeOptions, TranscriptionResult};
#[test]
fn engine_reports_not_available_before_loading() {
@@ -222,4 +281,86 @@ mod tests {
assert!(engine.loaded_model_id().is_none());
assert!(engine.capabilities().is_none());
}
/// Minimal fake `SpeechModel` for the Parakeet adapter tests. Records
/// whether `transcribe_raw` was called so we can prove the pre-decode
/// abort short-circuit actually fires.
struct FakeSpeechModel {
call_count: Arc<std::sync::atomic::AtomicUsize>,
}
impl transcribe_rs::SpeechModel for FakeSpeechModel {
fn capabilities(&self) -> ModelCapabilities {
ModelCapabilities {
name: "fake",
engine_id: "fake",
sample_rate: 16_000,
languages: &[],
supports_timestamps: false,
supports_translation: false,
supports_streaming: false,
}
}
fn transcribe_raw(
&mut self,
_samples: &[f32],
_options: &TranscribeOptions,
) -> std::result::Result<TranscriptionResult, TranscribeError> {
self.call_count
.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
Ok(TranscriptionResult {
text: String::new(),
segments: Some(Vec::new()),
})
}
}
#[test]
fn speech_model_adapter_short_circuits_when_abort_set_pre_dispatch() {
// Lifecycle-2 regression: without an explicit
// `transcribe_sync_with_abort` impl, SpeechModelAdapter used to
// inherit a default that silently dropped the abort flag and
// ran the decoder anyway. With the trait method made required,
// the adapter now checks the flag at the safest available
// boundary (pre-decode) and short-circuits.
let call_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
let model = Box::new(FakeSpeechModel {
call_count: call_count.clone(),
});
let mut adapter = SpeechModelAdapter(model);
let abort = Arc::new(AtomicBool::new(true));
let options = TranscriptionOptions::default();
let res = adapter.transcribe_sync_with_abort(&[0.0_f32; 16], &options, abort);
assert!(res.is_err(), "pre-set abort flag must short-circuit");
assert_eq!(
call_count.load(Ordering::Relaxed),
0,
"underlying decoder must NOT be called when abort was set before dispatch"
);
}
#[test]
fn speech_model_adapter_dispatches_decoder_when_abort_clear() {
// Companion to the short-circuit test: when the abort flag is
// clear at dispatch time, the adapter must still call the
// underlying decoder. Without this we'd have killed
// transcription entirely.
let call_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
let model = Box::new(FakeSpeechModel {
call_count: call_count.clone(),
});
let mut adapter = SpeechModelAdapter(model);
let abort = Arc::new(AtomicBool::new(false));
let options = TranscriptionOptions::default();
let res = adapter.transcribe_sync_with_abort(&[0.0_f32; 16], &options, abort);
assert!(res.is_ok(), "clear abort flag must allow dispatch");
assert_eq!(
call_count.load(Ordering::Relaxed),
1,
"decoder must run exactly once when abort flag is clear"
);
}
}

226
crates/transcription/src/model_manager.rs
View File

@@ -2,9 +2,9 @@ use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::sync::{LazyLock, Mutex};
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::model_registry::{find_model, ModelFile};
use magnotia_core::types::{DownloadProgress, ModelId};
use lumotia_core::error::{Error, Result};
use lumotia_core::model_registry::{find_model, ModelFile};
use lumotia_core::types::{DownloadProgress, ModelId};
static ACTIVE_DOWNLOADS: LazyLock<Mutex<HashSet<String>>> =
LazyLock::new(|| Mutex::new(HashSet::new()));
@@ -18,9 +18,9 @@ impl DownloadReservation {
let id = id.as_str().to_string();
let mut active = ACTIVE_DOWNLOADS
.lock()
.map_err(|_| MagnotiaError::DownloadFailed("download lock poisoned".into()))?;
.map_err(|_| Error::DownloadFailed("download lock poisoned".into()))?;
if !active.insert(id.clone()) {
return Err(MagnotiaError::DownloadFailed(format!(
return Err(Error::DownloadFailed(format!(
"download already in progress for {id}"
)));
}
@@ -37,15 +37,15 @@ impl Drop for DownloadReservation {
}
/// Resolve the models storage directory.
/// Windows: %LOCALAPPDATA%/magnotia/models
/// Unix: ~/.magnotia/models
/// Windows: %LOCALAPPDATA%/lumotia/models
/// Unix: ~/.lumotia/models
pub fn models_dir() -> PathBuf {
magnotia_core::paths::app_paths().models_dir()
lumotia_core::paths::app_paths().models_dir()
}
/// Get the directory path where a specific model's files are stored.
pub fn model_dir(id: &ModelId) -> PathBuf {
magnotia_core::paths::app_paths().speech_model_dir(id)
lumotia_core::paths::app_paths().speech_model_dir(id)
}
/// Check whether all files for a model have been downloaded.
@@ -61,7 +61,7 @@ pub fn is_downloaded(id: &ModelId) -> bool {
/// List all downloaded model IDs.
pub fn list_downloaded() -> Vec<ModelId> {
magnotia_core::model_registry::all_models()
lumotia_core::model_registry::all_models()
.iter()
.filter(|m| is_downloaded(&m.id))
.map(|m| m.id.clone())
@@ -74,13 +74,13 @@ pub fn list_downloaded() -> Vec<ModelId> {
/// For files that declare a `sha256` checksum we validate an existing
/// complete file before skipping the download — a truncated or
/// tampered file gets redownloaded automatically (pattern ported from
/// `magnotia-llm`'s model_manager, item #8 in the Whisper ecosystem brief).
/// `lumotia-llm`'s model_manager, item #8 in the Whisper ecosystem brief).
pub async fn download(
id: &ModelId,
progress: impl Fn(DownloadProgress) + Send + 'static,
) -> Result<()> {
let _reservation = DownloadReservation::acquire(id)?;
let entry = find_model(id).ok_or_else(|| MagnotiaError::ModelNotFound(id.clone()))?;
let entry = find_model(id).ok_or_else(|| Error::ModelNotFound(id.clone()))?;
let dir = model_dir(id);
std::fs::create_dir_all(&dir)?;
@@ -95,10 +95,24 @@ pub async fn download(
match sha256_of_file(&dest) {
Ok(actual) if actual.eq_ignore_ascii_case(file.sha256) => continue,
Ok(_actual) => {
let _ = std::fs::remove_file(&dest);
// Rev-5 reversibility kill (atomiser 2026-05-12):
// the previous implementation called
// `remove_file(&dest)` here before the network
// round-trip. A network blip / power loss between
// the unlink and `rename(tmp, dest)` in
// `download_file` left users with neither the old
// (corrupt) model file nor a fresh one — Whisper
// models are 1.5–3 GB and the user is offline by
// hypothesis.
//
// We now leave the existing file in place.
// `download_file` writes to a `.part` sibling and
// only `rename`s over `dest` once the SHA matches.
// The bad file is atomically replaced on success;
// on failure the user keeps what they had.
}
Err(e) => {
return Err(MagnotiaError::DownloadFailed(format!(
return Err(Error::DownloadFailed(format!(
"failed to verify existing {}: {e}",
file.filename
)));
@@ -113,11 +127,11 @@ pub async fn download(
}
fn verified_manifest_path(dir: &Path) -> PathBuf {
dir.join(".magnotia-verified")
dir.join(".lumotia-verified")
}
fn verified_manifest_matches(
entry: &magnotia_core::model_registry::ModelEntry,
entry: &lumotia_core::model_registry::ModelEntry,
dir: &Path,
) -> bool {
let manifest = match std::fs::read_to_string(verified_manifest_path(dir)) {
@@ -140,7 +154,7 @@ fn verified_manifest_matches(
}
fn write_verified_manifest(
entry: &magnotia_core::model_registry::ModelEntry,
entry: &lumotia_core::model_registry::ModelEntry,
dir: &Path,
) -> std::io::Result<()> {
let mut lines = Vec::with_capacity(entry.files.len() + 1);
@@ -149,10 +163,33 @@ fn write_verified_manifest(
let size = std::fs::metadata(dir.join(file.filename))?.len();
lines.push(format!("{}\t{}\t{}", file.filename, file.sha256, size));
}
std::fs::write(
verified_manifest_path(dir),
format!("{}\n", lines.join("\n")),
)
let final_path = verified_manifest_path(dir);
let body = format!("{}\n", lines.join("\n"));
// Rev-5 atomicity (atomiser 2026-05-12): the previous
// implementation called `fs::write(final_path, body)` directly,
// which truncates-then-writes. A power loss or kill mid-write
// leaves the manifest empty or partial; on next boot
// `verified_manifest_matches` reports `false` and the loader
// re-downloads the model even though all the GB-sized files are
// intact on disk.
//
// Write to a sibling `.tmp` first, fsync the data, then `rename`
// — POSIX `rename` is atomic within a directory, so a reader sees
// either the old manifest or the new one, never a partial.
let tmp_path = final_path.with_extension("tmp");
{
use std::io::Write;
let mut tmp = std::fs::File::create(&tmp_path)?;
tmp.write_all(body.as_bytes())?;
tmp.flush()?;
// Best-effort fsync. If the platform/filesystem can't sync
// (e.g. some test runners on tmpfs), the rename is still
// atomic at the directory entry level, which is the property
// we actually care about for "no torn manifest".
let _ = tmp.sync_all();
}
std::fs::rename(&tmp_path, &final_path)
}
/// Non-streaming SHA256 of a file on disk. Used by `download()` to
@@ -196,7 +233,7 @@ async fn download_file(
let client = reqwest::Client::builder()
.connect_timeout(std::time::Duration::from_secs(30))
.build()
.map_err(|e| MagnotiaError::DownloadFailed(e.to_string()))?;
.map_err(|e| Error::DownloadFailed(e.to_string()))?;
// Check for existing partial download (resume support)
let existing_bytes = if part_path.exists() {
@@ -215,12 +252,12 @@ async fn download_file(
let response = request
.send()
.await
.map_err(|e| MagnotiaError::DownloadFailed(e.to_string()))?;
.map_err(|e| Error::DownloadFailed(e.to_string()))?;
// If we requested Range but the server returned 200 (full file), the
// server does not support resume. Rather than blindly appending a
// full file on top of our partial bytes (which would produce a
// corrupt result), restart cleanly. This mirrors the magnotia-llm
// corrupt result), restart cleanly. This mirrors the lumotia-llm
// ResumeUnsupported branch — item #8 of the brief.
//
// For the non-resume path, we still have to validate the status:
@@ -237,14 +274,14 @@ async fn download_file(
false
}
other => {
return Err(MagnotiaError::DownloadFailed(format!(
return Err(Error::DownloadFailed(format!(
"resume request returned unexpected status {other}"
)));
}
}
} else {
if !response.status().is_success() {
return Err(MagnotiaError::DownloadFailed(format!(
return Err(Error::DownloadFailed(format!(
"download returned HTTP {} for {}",
response.status(),
file.filename
@@ -291,7 +328,7 @@ async fn download_file(
}
while let Some(chunk) = stream.next().await {
let chunk = chunk.map_err(|e| MagnotiaError::DownloadFailed(e.to_string()))?;
let chunk = chunk.map_err(|e| Error::DownloadFailed(e.to_string()))?;
std::io::Write::write_all(&mut out, &chunk)?;
hasher.update(&chunk);
downloaded += chunk.len() as u64;
@@ -319,7 +356,7 @@ async fn download_file(
let actual = format!("{:x}", hasher.finalize());
if actual != file.sha256 {
let _ = std::fs::remove_file(&part_path);
return Err(MagnotiaError::DownloadFailed(format!(
return Err(Error::DownloadFailed(format!(
"SHA256 mismatch for {}: expected {}, got {}",
file.filename, file.sha256, actual
)));
@@ -357,7 +394,7 @@ mod tests {
let list = list_downloaded();
// In test environment, no models are downloaded
// This just verifies the function doesn't panic
assert!(list.len() <= magnotia_core::model_registry::all_models().len());
assert!(list.len() <= lumotia_core::model_registry::all_models().len());
}
#[test]
@@ -481,7 +518,7 @@ mod tests {
let file = ModelFile {
filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
url: leak(format!("http://{addr}/fixture.bin")),
size: magnotia_core::types::Megabytes(0),
size: lumotia_core::types::Megabytes(0),
sha256: leak(expected_sha.clone()),
};
let id = ModelId::new("test-fixture");
@@ -516,7 +553,7 @@ mod tests {
let file = ModelFile {
filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
url: leak(format!("http://{addr}/fixture.bin")),
size: magnotia_core::types::Megabytes(0),
size: lumotia_core::types::Megabytes(0),
sha256: leak(expected_sha),
};
let id = ModelId::new("test-fixture");
@@ -571,7 +608,7 @@ mod tests {
let file = ModelFile {
filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
url: leak(format!("http://{addr}/fixture.bin")),
size: magnotia_core::types::Megabytes(0),
size: lumotia_core::types::Megabytes(0),
sha256: leak("0".repeat(64)),
};
let id = ModelId::new("test-fixture");
@@ -599,7 +636,7 @@ mod tests {
let file = ModelFile {
filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
url: leak(format!("http://{addr}/fixture.bin")),
size: magnotia_core::types::Megabytes(0),
size: lumotia_core::types::Megabytes(0),
sha256: leak("deadbeef".repeat(8)),
};
let id = ModelId::new("test-fixture");
@@ -616,4 +653,127 @@ mod tests {
let part = dest.with_extension("bin.part");
assert!(!part.exists(), "failed hash must clean up the .part file");
}
/// Rev-5 regression (atomiser 2026-05-12). The previous `download()`
/// loop called `remove_file(&dest)` on SHA mismatch BEFORE the
/// network call, so a failing redownload left the user with
/// neither the old (corrupt-but-readable) Whisper model nor a
/// fresh one — 1.5–3 GB redownload over an already-flaky network.
///
/// `download_file` is the per-file primitive that gets invoked
/// after the outer-loop decides to redownload. It already writes
/// via `.part` and atomically renames. This test asserts the
/// invariant the fix relies on: when `download_file` fails (5xx
/// or SHA mismatch), an existing sentinel file at `dest` is left
/// in place. The outer-loop no longer deletes pre-emptively, so
/// this proves end-to-end: a failed redownload preserves the old
/// file.
#[tokio::test]
async fn download_file_failure_preserves_existing_dest_file() {
let addr = spawn_500_server().await;
let dir = tempdir().unwrap();
let dest = dir.path().join("fixture.bin");
// Existing "old model" file the user already had on disk.
std::fs::write(&dest, b"OLD").unwrap();
let file = ModelFile {
filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
url: leak(format!("http://{addr}/fixture.bin")),
size: lumotia_core::types::Megabytes(0),
sha256: leak("0".repeat(64)),
};
let id = ModelId::new("test-fixture");
let _ = download_file(&file, &dest, &id, &|_| ())
.await
.expect_err("5xx must fail");
assert!(
dest.exists(),
"download failure must leave the existing dest in place"
);
let preserved = std::fs::read(&dest).unwrap();
assert_eq!(
preserved, b"OLD",
"existing file contents must be untouched on failed download"
);
}
/// Rev-5 atomic-manifest regression (atomiser 2026-05-12). The
/// previous `write_verified_manifest` called `fs::write` directly,
/// which truncates-then-writes. A power loss mid-write left an
/// empty or torn manifest; on next boot the loader couldn't match
/// the existing GB-sized model files and redownloaded everything.
///
/// The fix writes to a sibling `.tmp` first then `rename`s — POSIX
/// `rename` is atomic. This test exercises that path: write a
/// valid manifest, then prove a stale `.tmp` left behind from a
/// crashed previous attempt does NOT survive a fresh write (the
/// rename replaces it), and that the final manifest matches.
#[test]
fn manifest_write_is_atomic() {
use lumotia_core::model_registry::{
AccuracyTier, Engine, LanguageSupport, ModelEntry, ModelFile, SpeedTier,
};
use lumotia_core::types::Megabytes;
use sha2::Digest;
let dir = tempdir().unwrap();
let file_path = dir.path().join("model.bin");
std::fs::write(&file_path, b"payload").unwrap();
let entry = ModelEntry {
id: ModelId::new("test-manifest"),
engine: Engine::Whisper,
display_name: "test",
disk_size: Megabytes(0),
ram_required: Megabytes(0),
speed_tier: SpeedTier::Instant,
accuracy_tier: AccuracyTier::Great,
languages: LanguageSupport::EnglishOnly,
files: vec![ModelFile {
filename: leak(
file_path
.file_name()
.unwrap()
.to_string_lossy()
.into_owned(),
),
url: "http://example.invalid/model.bin",
size: Megabytes(0),
sha256: leak(format!("{:x}", sha2::Sha256::digest(b"payload"))),
}],
description: "",
};
let manifest_path = verified_manifest_path(dir.path());
let tmp_path = manifest_path.with_extension("tmp");
// Simulate a crashed previous write leaving a stale .tmp.
std::fs::write(&tmp_path, b"PARTIAL_GARBAGE").unwrap();
assert!(tmp_path.exists());
write_verified_manifest(&entry, dir.path()).expect("write manifest");
assert!(
manifest_path.exists(),
"final manifest must exist after atomic write"
);
assert!(
!tmp_path.exists(),
"stale .tmp must be removed by rename"
);
let body = std::fs::read_to_string(&manifest_path).unwrap();
assert!(body.starts_with("version\t1"));
assert!(
body.ends_with('\n'),
"manifest must be flushed completely with terminating newline"
);
assert!(
verified_manifest_matches(&entry, dir.path()),
"manifest written via tmp+rename must round-trip verify"
);
}
}

24
crates/transcription/src/orchestrator.rs
View File

@@ -1,7 +1,7 @@
//! `Orchestrator` is the single entry point for transcription. Tauri
//! commands resolve a provider through it; nothing else calls a
//! provider directly. This is where the AGPL OEM trait boundary meets
//! Wyrdnote's local engines.
//! Lumotia's local engines.
//!
//! `LocalProviderAdapter` lives here, not as an `impl
//! TranscriptionProvider for LocalEngine`. The adapter wraps an
@@ -18,12 +18,12 @@
use std::sync::Arc;
use async_trait::async_trait;
use magnotia_cloud_providers::{
use lumotia_cloud_providers::{
CostClass, EngineProfile, ProviderCapabilities, ProviderId, ProviderKind, ProviderTranscript,
TranscriptionProvider,
};
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::types::{AudioSamples, TranscriptionOptions};
use lumotia_core::error::{Error, Result};
use lumotia_core::types::{AudioSamples, TranscriptionOptions};
use crate::local_engine::LocalEngine;
use crate::registry::EngineRegistry;
@@ -68,7 +68,7 @@ impl TranscriptionProvider for LocalProviderAdapter {
ProviderCapabilities {
sample_rate: local
.map(|c| c.sample_rate)
.unwrap_or(magnotia_core::constants::WHISPER_SAMPLE_RATE),
.unwrap_or(lumotia_core::constants::WHISPER_SAMPLE_RATE),
channels: local.map(|c| c.channels).unwrap_or(1),
initial_prompt_supported: local.map(|c| c.supports_initial_prompt).unwrap_or(false),
language_hint_supported: true,
@@ -81,7 +81,7 @@ impl TranscriptionProvider for LocalProviderAdapter {
if self.engine.is_loaded() {
Ok(())
} else {
Err(MagnotiaError::EngineNotLoaded)
Err(Error::EngineNotLoaded)
}
}
@@ -93,7 +93,7 @@ impl TranscriptionProvider for LocalProviderAdapter {
let engine = self.engine.clone();
let timed = tokio::task::spawn_blocking(move || engine.transcribe_sync(&audio, &options))
.await
.map_err(|e| MagnotiaError::TranscriptionFailed(format!("Task join error: {e}")))??;
.map_err(|e| Error::TranscriptionFailed(format!("Task join error: {e}")))??;
Ok(ProviderTranscript {
transcript: timed.transcript,
inference_ms: timed.inference_ms,
@@ -124,7 +124,7 @@ impl Orchestrator {
pub fn resolve(&self, profile: &EngineProfile) -> Result<Arc<dyn TranscriptionProvider>> {
self.registry
.get(&profile.engine_id)
.ok_or_else(|| MagnotiaError::ProviderNotRegistered(profile.engine_id.to_string()))
.ok_or_else(|| Error::ProviderNotRegistered(profile.engine_id.to_string()))
}
/// Transcribe audio using the provider named in the profile. The
@@ -153,7 +153,7 @@ mod tests {
use std::sync::atomic::{AtomicUsize, Ordering};
use magnotia_core::types::{Segment, Transcript};
use lumotia_core::types::{Segment, Transcript};
/// Mock provider that returns a canned transcript and counts
/// invocations. Used to validate the orchestrator's dispatch logic
@@ -223,7 +223,7 @@ mod tests {
#[tokio::test]
async fn orchestrator_dispatches_to_named_provider() {
let calls = Arc::new(AtomicUsize::new(0));
let registry = build_registry_with("canned", "hello wyrdnote", calls.clone());
let registry = build_registry_with("canned", "hello lumotia", calls.clone());
let orchestrator = Orchestrator::new(registry);
let profile = EngineProfile::new(ProviderId::new("canned"));
@@ -232,7 +232,7 @@ mod tests {
.await
.expect("dispatch succeeds");
assert_eq!(result.transcript.text(), "hello wyrdnote");
assert_eq!(result.transcript.text(), "hello lumotia");
assert_eq!(result.inference_ms, 7);
assert_eq!(calls.load(Ordering::SeqCst), 1);
}
@@ -264,7 +264,7 @@ mod tests {
let mut profile = EngineProfile::new(ProviderId::new("canned"));
profile.language = Some("en".to_string());
profile.initial_prompt = Some("Wyrdnote".to_string());
profile.initial_prompt = Some("Lumotia".to_string());
let _ = orchestrator
.transcribe(one_second_of_silence(), &profile)

8
crates/transcription/src/registry.rs
View File

@@ -15,7 +15,7 @@
use std::collections::HashMap;
use std::sync::Arc;
use magnotia_cloud_providers::{ProviderId, TranscriptionProvider};
use lumotia_cloud_providers::{ProviderId, TranscriptionProvider};
/// Catalogue of providers known to the orchestrator.
pub struct EngineRegistry {
@@ -82,11 +82,11 @@ mod tests {
use super::*;
use async_trait::async_trait;
use magnotia_cloud_providers::{
use lumotia_cloud_providers::{
CostClass, EngineProfile, ProviderCapabilities, ProviderKind, ProviderTranscript,
};
use magnotia_core::error::Result;
use magnotia_core::types::{AudioSamples, Transcript, TranscriptionOptions};
use lumotia_core::error::Result;
use lumotia_core::types::{AudioSamples, Transcript, TranscriptionOptions};
struct DummyProvider {
id: ProviderId,

96
crates/transcription/src/transcriber.rs
View File

@@ -9,8 +9,11 @@
//! `whisper` feature — `WhisperRsBackend` (direct whisper-rs, the only
//! path that pipes `initial_prompt`).
use magnotia_core::error::Result;
use magnotia_core::types::{Segment, TranscriptionOptions};
use std::sync::atomic::AtomicBool;
use std::sync::Arc;
use lumotia_core::error::Result;
use lumotia_core::types::{Segment, TranscriptionOptions};
/// Static capabilities a `Transcriber` advertises to callers.
///
@@ -45,11 +48,41 @@ pub trait Transcriber: Send {
samples: &[f32],
options: &TranscriptionOptions,
) -> Result<Vec<Segment>>;
/// Variant of `transcribe_sync` that accepts an external abort flag.
///
/// REQUIRED so every backend opts in to a cancellation story at
/// compile time. Without this requirement a default impl that
/// simply forwarded to `transcribe_sync` would silently re-introduce
/// the wedge for any non-whisper backend: the live session's
/// `drain_inference` timeout would set the flag, but the backend
/// would ignore it, the orphan inference thread would keep holding
/// the engine `Mutex`, and the next start/stop would deadlock on it.
///
/// Implementer guidance:
/// * Backends that can react to mid-inference cancellation
/// (whisper-rs via `set_abort_callback_safe`) wire the flag into
/// their decoder's abort hook so the wedged inference can be
/// unstuck by the live session's drain timeout.
/// * Backends that genuinely cannot honour the flag mid-call
/// (synchronous external API calls, transcribe-rs adapters that
/// own opaque decoder state) MUST still implement this method —
/// even if the implementation is to check the flag at the safest
/// available boundary and otherwise dispatch to `transcribe_sync`.
/// Document the uncancellability with a `// SAFETY:` comment so a
/// future audit can find it.
fn transcribe_sync_with_abort(
&mut self,
samples: &[f32],
options: &TranscriptionOptions,
abort_flag: Arc<AtomicBool>,
) -> Result<Vec<Segment>>;
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::Ordering;
#[test]
fn transcriber_trait_is_object_safe() {
@@ -58,4 +91,63 @@ mod tests {
// method) this declaration fails to build. No runtime work.
let _: Option<Box<dyn Transcriber + Send>> = None;
}
/// Fake backend that records whether the abort flag was observed
/// at dispatch time. Proves the compile-time-required
/// `transcribe_sync_with_abort` actually receives the flag instead
/// of silently falling back to a default impl that drops it on the
/// floor (the Lifecycle-2 wedge).
struct FlagSnoopingBackend {
observed_abort: bool,
}
impl Transcriber for FlagSnoopingBackend {
fn capabilities(&self) -> TranscriberCapabilities {
TranscriberCapabilities {
sample_rate: 16_000,
channels: 1,
supports_initial_prompt: false,
}
}
fn transcribe_sync(
&mut self,
_samples: &[f32],
_options: &TranscriptionOptions,
) -> Result<Vec<Segment>> {
Ok(Vec::new())
}
fn transcribe_sync_with_abort(
&mut self,
_samples: &[f32],
_options: &TranscriptionOptions,
abort_flag: Arc<AtomicBool>,
) -> Result<Vec<Segment>> {
self.observed_abort = abort_flag.load(Ordering::Relaxed);
Ok(Vec::new())
}
}
#[test]
fn transcribe_sync_with_abort_is_required_and_flag_is_observed() {
// Lifecycle-2 regression: removing the trait's default impl
// forces every backend to receive the abort flag at the call
// site. Without an explicit method on this fake backend the
// file wouldn't compile; with it, asserting the snoop is the
// runtime witness that the flag is actually piped through.
let mut backend = FlagSnoopingBackend {
observed_abort: false,
};
let flag = Arc::new(AtomicBool::new(true));
let options = TranscriptionOptions::default();
let segs = backend
.transcribe_sync_with_abort(&[], &options, flag.clone())
.expect("fake backend never errors");
assert!(segs.is_empty());
assert!(
backend.observed_abort,
"trait must hand the abort flag to the backend, not drop it via a default impl"
);
}
}

52
crates/transcription/src/whisper_rs_backend.rs
View File

@@ -7,13 +7,15 @@
//! into Whisper.
use std::path::Path;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
use magnotia_core::error::{MagnotiaError, Result};
use magnotia_core::hardware::vulkan_loader_available;
use magnotia_core::tuning::{inference_thread_count, Workload};
use magnotia_core::types::{Segment, TranscriptionOptions};
use lumotia_core::error::{Error, Result};
use lumotia_core::hardware::vulkan_loader_available;
use lumotia_core::tuning::{inference_thread_count, Workload};
use lumotia_core::types::{Segment, TranscriptionOptions};
use crate::transcriber::{Transcriber, TranscriberCapabilities};
@@ -42,7 +44,7 @@ impl WhisperRsBackend {
impl Transcriber for WhisperRsBackend {
fn capabilities(&self) -> TranscriberCapabilities {
TranscriberCapabilities {
sample_rate: magnotia_core::constants::WHISPER_SAMPLE_RATE,
sample_rate: lumotia_core::constants::WHISPER_SAMPLE_RATE,
channels: 1,
supports_initial_prompt: true,
}
@@ -57,15 +59,40 @@ impl Transcriber for WhisperRsBackend {
&mut self,
samples: &[f32],
options: &TranscriptionOptions,
) -> Result<Vec<Segment>> {
self.transcribe_sync_inner(samples, options, None)
}
/// Cancellable variant. Installs the abort flag as whisper-rs's
/// abort callback so a `drain_inference` timeout in the live session
/// can break the worker out of the decoding loop instead of letting
/// it run to completion against a stuck backend.
fn transcribe_sync_with_abort(
&mut self,
samples: &[f32],
options: &TranscriptionOptions,
abort_flag: Arc<AtomicBool>,
) -> Result<Vec<Segment>> {
self.transcribe_sync_inner(samples, options, Some(abort_flag))
}
}
impl WhisperRsBackend {
fn transcribe_sync_inner(
&mut self,
samples: &[f32],
options: &TranscriptionOptions,
abort_flag: Option<Arc<AtomicBool>>,
) -> Result<Vec<Segment>> {
tracing::info!(
language = ?options.language,
has_initial_prompt = options.initial_prompt.as_deref().map(|p| !p.is_empty()).unwrap_or(false),
has_abort_flag = abort_flag.is_some(),
"WhisperRsBackend::transcribe_sync entering"
);
let mut state = self.ctx.create_state().map_err(|e| {
MagnotiaError::TranscriptionFailed(
Error::TranscriptionFailed(
WhisperBackendError::State(e.to_string()).to_string(),
)
})?;
@@ -87,8 +114,17 @@ impl Transcriber for WhisperRsBackend {
params.set_print_progress(false);
params.set_print_realtime(false);
// Wire the per-task abort flag into whisper-rs. The closure is
// polled by whisper.cpp between decode steps; returning true
// tells the backend to abort the current inference. This is the
// cancellation route that closes the orphaned-thread loophole
// when a live session is stopped or wedges.
if let Some(flag) = abort_flag {
params.set_abort_callback_safe(move || flag.load(Ordering::Relaxed));
}
state.full(params, samples).map_err(|e| {
MagnotiaError::TranscriptionFailed(
Error::TranscriptionFailed(
WhisperBackendError::Transcribe(e.to_string()).to_string(),
)
})?;
@@ -103,7 +139,7 @@ impl Transcriber for WhisperRsBackend {
let text = seg
.to_str()
.map_err(|e| {
MagnotiaError::TranscriptionFailed(
Error::TranscriptionFailed(
WhisperBackendError::Transcribe(e.to_string()).to_string(),
)
})?

12
crates/transcription/tests/jfk_bench.rs
View File

@@ -2,20 +2,20 @@
//! Reports cold-load time, transcribe time, RTF, peak RSS.
//!
//! Gated on env vars so it never runs in CI without setup:
//! MAGNOTIA_WHISPER_TEST_MODEL=/path/to/ggml-tiny.bin
//! MAGNOTIA_WHISPER_TEST_AUDIO=/path/to/jfk.wav
//! LUMOTIA_WHISPER_TEST_MODEL=/path/to/ggml-tiny.bin
//! LUMOTIA_WHISPER_TEST_AUDIO=/path/to/jfk.wav
use std::env;
use std::time::Instant;
#[test]
fn jfk_transcription_benchmark() {
let Ok(model_path) = env::var("MAGNOTIA_WHISPER_TEST_MODEL") else {
eprintln!("MAGNOTIA_WHISPER_TEST_MODEL not set — skipping");
let Ok(model_path) = env::var("LUMOTIA_WHISPER_TEST_MODEL") else {
eprintln!("LUMOTIA_WHISPER_TEST_MODEL not set — skipping");
return;
};
let Ok(audio_path) = env::var("MAGNOTIA_WHISPER_TEST_AUDIO") else {
eprintln!("MAGNOTIA_WHISPER_TEST_AUDIO not set — skipping");
let Ok(audio_path) = env::var("LUMOTIA_WHISPER_TEST_AUDIO") else {
eprintln!("LUMOTIA_WHISPER_TEST_AUDIO not set — skipping");
return;
};

18
crates/transcription/tests/thread_sweep.rs
View File

@@ -1,24 +1,24 @@
//! Thread-count scaling sweep for Whisper Tiny.
//! Runs the JFK clip at n_threads = 1, 2, 4, 6, 8, 12, prints RTF tables.
//! Env-gated by `MAGNOTIA_WHISPER_TEST_MODEL` + `MAGNOTIA_WHISPER_TEST_AUDIO`.
//! Env-gated by `LUMOTIA_WHISPER_TEST_MODEL` + `LUMOTIA_WHISPER_TEST_AUDIO`.
//!
//! Now prints multiple panels driven by `MAGNOTIA_POWER_STATE_OVERRIDE` so
//! Now prints multiple panels driven by `LUMOTIA_POWER_STATE_OVERRIDE` so
//! the helper's predicted thread count for each (power, GPU) combination
//! can be compared against the empirical RTF data.
use std::env;
use std::time::Instant;
use magnotia_core::hardware::vulkan_loader_available;
use magnotia_core::tuning::{inference_thread_count, Workload};
use lumotia_core::hardware::vulkan_loader_available;
use lumotia_core::tuning::{inference_thread_count, Workload};
use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
#[test]
fn whisper_thread_count_sweep() {
let Ok(model_path) = env::var("MAGNOTIA_WHISPER_TEST_MODEL") else {
let Ok(model_path) = env::var("LUMOTIA_WHISPER_TEST_MODEL") else {
return;
};
let Ok(audio_path) = env::var("MAGNOTIA_WHISPER_TEST_AUDIO") else {
let Ok(audio_path) = env::var("LUMOTIA_WHISPER_TEST_AUDIO") else {
return;
};
@@ -71,7 +71,7 @@ fn whisper_thread_count_sweep() {
);
// Four panels: CPU and GPU axes for the predicted-helper-pick column,
// crossed with AC and battery via MAGNOTIA_POWER_STATE_OVERRIDE.
// crossed with AC and battery via LUMOTIA_POWER_STATE_OVERRIDE.
let panels = [
("AC, CPU", "ac", false),
("AC, GPU (Vulkan)", "ac", true),
@@ -80,11 +80,11 @@ fn whisper_thread_count_sweep() {
];
for (label, power, gpu_offloaded_for_helper) in panels {
env::set_var("MAGNOTIA_POWER_STATE_OVERRIDE", power);
env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", power);
let helper_pick = inference_thread_count(Workload::Whisper, gpu_offloaded_for_helper);
run_sweep_panel(label, helper_pick, &ctx, &samples, audio_secs, &targets);
}
env::remove_var("MAGNOTIA_POWER_STATE_OVERRIDE");
env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE");
}
fn run_sweep_panel(

6
crates/transcription/tests/whisper_rs_smoke.rs
View File

@@ -1,17 +1,17 @@
//! Smoke test: whisper-rs 0.16 loads a GGUF model, transcribes silence, and
//! accepts set_initial_prompt without panicking.
//!
//! Runs only when `MAGNOTIA_WHISPER_TEST_MODEL` is set to the path of a
//! Runs only when `LUMOTIA_WHISPER_TEST_MODEL` is set to the path of a
//! ggml/gguf whisper model on disk. Otherwise the test exits quiet.
use std::env;
#[test]
fn whisper_rs_smoke_loads_and_transcribes() {
let model_path = match env::var("MAGNOTIA_WHISPER_TEST_MODEL") {
let model_path = match env::var("LUMOTIA_WHISPER_TEST_MODEL") {
Ok(p) => p,
Err(_) => {
eprintln!("MAGNOTIA_WHISPER_TEST_MODEL not set — skipping");
eprintln!("LUMOTIA_WHISPER_TEST_MODEL not set — skipping");
return;
}
};

12
docs/architecture-map/01-frontend/README.md
View File

@@ -18,7 +18,7 @@ last_verified: 2026/05/09
- **File counts:** 7 pages, 25 components, 10 stores, 1 action, 16 utils, 1 type module, 3 locales, 4 routes (root + float/viewer/preview), 20 design system preview HTMLs, 3 design system JSX kits.
- **Frameworks:** Svelte 5 (runes mode), SvelteKit 2.58, `@sveltejs/adapter-static` with `index.html` fallback (SPA), Vite 6, Tailwind v4 via `@tailwindcss/vite`, svelte-i18n 4, lucide-svelte for icons.
- **Tauri SDK touchpoints:** `@tauri-apps/api` (core invoke, event, window) plus `plugin-autostart`, `plugin-dialog`, `plugin-global-shortcut`, `plugin-notification`, `plugin-opener`. SSR is disabled (`src/routes/+layout.js`) so the whole tree is client side only.
- **Persistence used directly by frontend:** `localStorage` for `magnotia_settings`, `magnotia_profiles`, `magnotia_task_lists`, `magnotia_templates`, `magnotia_locale`, plus a small handoff key for the viewer window. Preferences additionally persist via Tauri (`save_preferences`).
- **Persistence used directly by frontend:** `localStorage` for `lumotia_settings`, `lumotia_profiles`, `lumotia_task_lists`, `lumotia_templates`, `lumotia_locale`, plus a small handoff key for the viewer window. Preferences additionally persist via Tauri (`save_preferences`).
- **Build commands:** `npm run dev` (`svelte-kit sync && vite dev`), `npm run build`, `npm run check` (svelte-check using `jsconfig.json`).
## Map of this slice
@@ -44,21 +44,21 @@ last_verified: 2026/05/09
**In (frontend depends on Tauri runtime, slice 02).**
- Sixty plus distinct `invoke()` commands. Full list with caller in [frontend-tauri-bridge.md](frontend-tauri-bridge.md).
- Tauri events listened to: `model-download-progress`, `parakeet-download-progress`, `magnotia:llm-download-progress`, `magnotia:hotkey-pressed`, `magnotia:open-wind-down`, `magnotia:preferences-changed`, `task-window-focus`, `preview-listening`, `preview-cleanup`, `preview-hide`, plus drag drop (`tauri://drag-drop`, `tauri://drag-enter`, `tauri://drag-leave`).
- Tauri events listened to: `model-download-progress`, `parakeet-download-progress`, `lumotia:llm-download-progress`, `lumotia:hotkey-pressed`, `lumotia:open-wind-down`, `lumotia:preferences-changed`, `task-window-focus`, `preview-listening`, `preview-cleanup`, `preview-hide`, plus drag drop (`tauri://drag-drop`, `tauri://drag-enter`, `tauri://drag-leave`).
- Window APIs: `getCurrentWindow().minimize() / toggleMaximize() / setPosition() / label`.
- Plugin imports loaded lazily: `@tauri-apps/plugin-global-shortcut`, `@tauri-apps/plugin-dialog`.
**Out (frontend triggers behaviour back into the runtime).**
- DOM `CustomEvent` bus on `window` carries internal traffic (`magnotia:start-timer`, `magnotia:toggle-recording`, `magnotia:task-completed`, etc). The Rust side does not listen to these; they are intra frontend.
- Tauri `emit()` is used for `magnotia:preferences-changed` only, to fan preference updates across windows.
- DOM `CustomEvent` bus on `window` carries internal traffic (`lumotia:start-timer`, `lumotia:toggle-recording`, `lumotia:task-completed`, etc). The Rust side does not listen to these; they are intra frontend.
- Tauri `emit()` is used for `lumotia:preferences-changed` only, to fan preference updates across windows.
- Multi window orchestration: pages call `open_task_window`, `open_viewer_window`, `open_preview_window` to ask Rust to spawn secondary webviews.
**Other slices that read frontend conventions.**
- Slice 02 (Tauri runtime) emits the events listed above and registers commands the frontend invokes.
- Slice 03 (audio + transcription) ships partial results via a `Channel` (Tauri 2 typed channel) opened in `DictationPage`.
- Slice 04 (LLM, formatting, MCP) emits `magnotia:llm-download-progress` and `cleanup_transcript_text_cmd` results consumed by Dictation.
- Slice 04 (LLM, formatting, MCP) emits `lumotia:llm-download-progress` and `cleanup_transcript_text_cmd` results consumed by Dictation.
- Slice 05 (storage, hotkey, build) supplies `add_transcript`, `delete_transcript`, profiles, tasks and the evdev hotkey backend.
## Existing in repo docs (do not duplicate)
@@ -80,7 +80,7 @@ This slice index is the navigation hub. The map files referenced above carry the
3. **`@ts-nocheck` is widespread.** `+layout.svelte`, `DictationPage.svelte`, `FilesPage.svelte`, `FirstRunPage.svelte` and the float/viewer/preview layouts all opt out of TypeScript. Type safety stops at the page boundary.
4. **`SettingsPage.svelte` is 2 484 lines.** Phase 9c handover already flagged this. `SettingsGroup.svelte` exists but the deeper restructure into seven progressive disclosure groups plus search has been deferred.
5. **`profiles` redirect is a dead route.** `+page.svelte:13` still rewrites `page.current === "profiles"` to `"settings"`, suggesting the old profiles page was removed but call sites may persist. Worth grepping and deleting the redirect after a release.
6. **Cross window settings sync uses `localStorage` `storage` events.** `float/+layout@.svelte` listens for `storage` to apply settings, while preferences use the dedicated `magnotia:preferences-changed` Tauri event. Inconsistent. Settings sync via `storage` is fragile because it only fires on cross document writes.
6. **Cross window settings sync uses `localStorage` `storage` events.** `float/+layout@.svelte` listens for `storage` to apply settings, while preferences use the dedicated `lumotia:preferences-changed` Tauri event. Inconsistent. Settings sync via `storage` is fragile because it only fires on cross document writes.
7. **`shims.d.ts` next to the lib root.** Single shim file at `src/lib/shims.d.ts`. Worth verifying it is still needed (Svelte 5 + SvelteKit ship most ambient types now).
8. **`design-system/ui_kits/`** contains JSX components and an HTML index. They are reference, not live, and should not import from the runtime tree. Confirm the build excludes them.
9. **`speaker.svelte.ts` is ten lines.** A near empty store. Used by `SpeakerButton.svelte`. Consider folding into a util if it never grows.

2
docs/architecture-map/01-frontend/actions-utils-types.md
View File

@@ -39,7 +39,7 @@ Caches OS info via `invoke("os_info")` (or similar; check `lib.rs`). Exposes `lo
### `settingsMigrations.ts` (134 LOC)
Versioned migrations for `magnotia_settings`. Holds `CURRENT_SETTINGS_VERSION = 1`. Envelope shape: `{ version: number, data: T }`. Reads bare unversioned blobs as v0. `loadSettingsWithMigration(key, defaults)` walks the chain and toasts on corruption.
Versioned migrations for `lumotia_settings`. Holds `CURRENT_SETTINGS_VERSION = 1`. Envelope shape: `{ version: number, data: T }`. Reads bare unversioned blobs as v0. `loadSettingsWithMigration(key, defaults)` walks the chain and toasts on corruption.
### `frontmatter.ts` (148 LOC)

2
docs/architecture-map/01-frontend/app-shell-and-styling.md
View File

@@ -22,7 +22,7 @@ last_verified: 2026/05/09
### `src/app.html` (13 LOC)
Standard SvelteKit document. Sets `lang="en"`, charset, viewport, favicon, title (`Magnotia`), and applies `data-sveltekit-preload-data="hover"` on `<body>`. The body content is wrapped in `<div style="display: contents">` so the SvelteKit-injected children render inline.
Standard SvelteKit document. Sets `lang="en"`, charset, viewport, favicon, title (`Lumotia`), and applies `data-sveltekit-preload-data="hover"` on `<body>`. The body content is wrapped in `<div style="display: contents">` so the SvelteKit-injected children render inline.
### `src/app.d.ts` (8 LOC)

6
docs/architecture-map/01-frontend/components.md
View File

@@ -25,7 +25,7 @@ last_verified: 2026/05/09
| `Titlebar` | 80 | `src/lib/components/Titlebar.svelte` | Custom window chrome for non Linux (frameless windows). Min/max/close + drag area + sidebar aligned spacer. |
| `ToastViewport` | 143 | `src/lib/components/ToastViewport.svelte` | Bottom right toast stack. Reads from the global `toasts` store. Honours `prefers-reduced-motion`. |
| `ResizeHandles` | 67 | `src/lib/components/ResizeHandles.svelte` | Invisible 5 px margins for frameless resize. Linux uses native, so `+layout.svelte` suppresses this. |
| `FocusTimer` | 298 | `src/lib/components/FocusTimer.svelte` | Floating top right SVG progress ring. Listens for `magnotia:start-timer` window events and delegates to the focus timer store. Cancel hover, success flourish. Hidden on float and viewer windows by URL probe. |
| `FocusTimer` | 298 | `src/lib/components/FocusTimer.svelte` | Floating top right SVG progress ring. Listens for `lumotia:start-timer` window events and delegates to the focus timer store. Cancel hover, success flourish. Hidden on float and viewer windows by URL probe. |
| `MorningTriageModal` | 356 | `src/lib/components/MorningTriageModal.svelte` | Phase 5 modal. Self gated on `settings.ritualsMorning` and time of day. Mounted globally so it appears over any page. |
| `TaskSidebar` | 97 | `src/lib/components/TaskSidebar.svelte` | Optional right side dock that appears when `page.taskSidebarOpen`. Quick add input, top tasks, link out to the full Tasks page. |
@@ -54,8 +54,8 @@ last_verified: 2026/05/09
| Component | LOC | Purpose |
|---|---|---|
| `WipTaskList` | 153 | Renders task rows with energy chips, completion checkbox, expansion to show micro steps, and a "start focus timer" button (dispatches `magnotia:start-timer`). |
| `MicroSteps` | 310 | Per task expansion: nudge bus integration, micro step suggestions from the LLM (`magnotia:microstep-generated`), step completion (`magnotia:step-completed`), per task implementation rules. |
| `WipTaskList` | 153 | Renders task rows with energy chips, completion checkbox, expansion to show micro steps, and a "start focus timer" button (dispatches `lumotia:start-timer`). |
| `MicroSteps` | 310 | Per task expansion: nudge bus integration, micro step suggestions from the LLM (`lumotia:microstep-generated`), step completion (`lumotia:step-completed`), per task implementation rules. |
| `EnergyChip` | 106 | Low/medium/high energy selector. Used on task rows and in TasksPage quick add. |
| `CompletionSparkline` | 92 | 7 day completion bar chart. Animated entrance with 30 ms stagger, respects `prefers-reduced-motion`. Reads from `recentCompletions` store. |
| `VisualTimer` | 33 | Compact visual timer pill used inside MicroSteps and the float window. |

8
docs/architecture-map/01-frontend/design-system.md
View File

@@ -9,14 +9,14 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Design system
**Plain English summary.** Reference material. The runtime styles live in `src/app.css`. Everything under `src/design-system/` is brand documentation, preview pages, JSX UI kits, and ground truth source for the magnotia-design Claude skill. None of it is imported by the runtime SvelteKit app.
**Plain English summary.** Reference material. The runtime styles live in `src/app.css`. Everything under `src/design-system/` is brand documentation, preview pages, JSX UI kits, and ground truth source for the lumotia-design Claude skill. None of it is imported by the runtime SvelteKit app.
## At a glance
- **Path:** `src/design-system/`
- **Files:**
- `README.md`. Brand and content rules. (Magnotia by CORBEL.)
- `SKILL.md`. magnotia-design skill manifest (`user-invocable: true`). The skill copies assets out and writes throwaway HTML or production code on demand.
- `README.md`. Brand and content rules. (Lumotia by CORBEL.)
- `SKILL.md`. lumotia-design skill manifest (`user-invocable: true`). The skill copies assets out and writes throwaway HTML or production code on demand.
- `colors_and_type.css`. Mirror of the runtime `@theme` tokens for buildless preview pages. Intentional duplication, kept in sync by hand.
- `preview/`. 20 buildless HTML spec cards.
- `ui_kits/`. JSX recreations (`DictationPage.jsx`, `OtherPages.jsx`, `Sidebar.jsx`) plus an `index.html` and a README.
@@ -52,7 +52,7 @@ Three `.jsx` files plus `index.html` and a README. Reproduce the desktop pages i
## Why it lives in `src/`
The design system files sit under `src/` so the magnotia-design skill (which runs from this repo) can read ground-truth Svelte source from `magnotia-source/` (a sibling import). The runtime build does not include this folder; it is a reference root.
The design system files sit under `src/` so the lumotia-design skill (which runs from this repo) can read ground-truth Svelte source from `lumotia-source/` (a sibling import). The runtime build does not include this folder; it is a reference root.
## Watch outs

42
docs/architecture-map/01-frontend/frontend-tauri-bridge.md
View File

@@ -15,8 +15,8 @@ last_verified: 2026/05/09
- **Direction in (Rust → frontend):** events listed under "Tauri events listened to".
- **Direction out (frontend → Rust):** all `invoke()` commands listed under "Tauri commands invoked".
- **DOM-only events:** `magnotia:*` `CustomEvent`s on `window`. These never cross the Rust boundary.
- **Cross-window event:** `magnotia:preferences-changed` is the only one that goes through `emit()`.
- **DOM-only events:** `lumotia:*` `CustomEvent`s on `window`. These never cross the Rust boundary.
- **Cross-window event:** `lumotia:preferences-changed` is the only one that goes through `emit()`.
## Tauri commands invoked (alphabetical)
@@ -91,10 +91,10 @@ Plus any commands invoked by `saveMarkdown.ts` via the dialog/file-write plugin
| Event | Listener |
|---|---|
| `magnotia:hotkey-pressed` | `routes/+layout.svelte:177` (evdev backend) |
| `magnotia:llm-download-progress` | `pages/SettingsPage.svelte:873` |
| `magnotia:open-wind-down` | `routes/+layout.svelte:251` (tray menu hook) |
| `magnotia:preferences-changed` | `routes/+layout.svelte:263`, `routes/float/+layout@.svelte`, `routes/viewer/+layout@.svelte`, `routes/preview/+layout@.svelte:41` |
| `lumotia:hotkey-pressed` | `routes/+layout.svelte:177` (evdev backend) |
| `lumotia:llm-download-progress` | `pages/SettingsPage.svelte:873` |
| `lumotia:open-wind-down` | `routes/+layout.svelte:251` (tray menu hook) |
| `lumotia:preferences-changed` | `routes/+layout.svelte:263`, `routes/float/+layout@.svelte`, `routes/viewer/+layout@.svelte`, `routes/preview/+layout@.svelte:41` |
| `model-download-progress` | `pages/SettingsPage.svelte:864`, `pages/FirstRunPage.svelte:46`, `components/ModelDownloader.svelte:31` |
| `parakeet-download-progress` | `pages/SettingsPage.svelte:880`, `pages/FirstRunPage.svelte:50` |
| `preview-cleanup` | `routes/preview/+page.svelte:141` |
@@ -109,28 +109,28 @@ Plus any commands invoked by `saveMarkdown.ts` via the dialog/file-write plugin
| Event | Emitter | Purpose |
|---|---|---|
| `magnotia:preferences-changed` | `stores/preferences.svelte.ts` (`broadcastPreferences`) | Cross-window preference sync. |
| `lumotia:preferences-changed` | `stores/preferences.svelte.ts` (`broadcastPreferences`) | Cross-window preference sync. |
| `preview-append` | `pages/DictationPage.svelte:165` | Stream partial text to overlay window. |
| `preview-listening` | `pages/DictationPage.svelte:381` | Tell overlay to enter listening state. |
| `preview-cleanup` | `pages/DictationPage.svelte:531` | Tell overlay to enter cleanup state. |
| `preview-final` | `pages/DictationPage.svelte:539` | Tell overlay to render final text. |
| `preview-hide` | `pages/DictationPage.svelte:606` | Tell overlay to dismiss. |
## DOM-only `magnotia:*` window events (intra-frontend bus)
## DOM-only `lumotia:*` window events (intra-frontend bus)
| Event | Dispatcher | Listener(s) |
|---|---|---|
| `magnotia:focus-timer-cancelled` | `stores/focusTimer.svelte.ts` | `completionStats` (indirectly), components subscribed to focus timer. |
| `magnotia:focus-timer-complete` | `stores/focusTimer.svelte.ts` | Same as above. |
| `magnotia:implementation-rules-changed` | `stores/implementationIntentions.svelte.ts` | `ImplementationRulesEditor`. |
| `magnotia:microstep-generated` | `stores/nudgeBus.svelte.ts` (around micro step generation) | `MicroSteps.svelte`. |
| `magnotia:morning-triage-finished` | `MorningTriageModal.svelte` | `nudgeBus`. |
| `magnotia:start-timer` | `WipTaskList.svelte`, `MicroSteps.svelte` | `FocusTimer.svelte` + `focusTimer` store. |
| `magnotia:step-completed` | `MicroSteps.svelte` | `completionStats` refresh. |
| `magnotia:task-completed` | `stores/page.svelte.ts` (`completeTask`) | `completionStats`. |
| `magnotia:task-deleted` | `stores/page.svelte.ts` (`deleteTask`) | `completionStats`. |
| `magnotia:task-uncompleted` | `stores/page.svelte.ts` (`uncompleteTask`) | `completionStats`. |
| `magnotia:toggle-recording` | `routes/+layout.svelte` (after hotkey debounce, both backends) | `pages/DictationPage.svelte`. |
| `lumotia:focus-timer-cancelled` | `stores/focusTimer.svelte.ts` | `completionStats` (indirectly), components subscribed to focus timer. |
| `lumotia:focus-timer-complete` | `stores/focusTimer.svelte.ts` | Same as above. |
| `lumotia:implementation-rules-changed` | `stores/implementationIntentions.svelte.ts` | `ImplementationRulesEditor`. |
| `lumotia:microstep-generated` | `stores/nudgeBus.svelte.ts` (around micro step generation) | `MicroSteps.svelte`. |
| `lumotia:morning-triage-finished` | `MorningTriageModal.svelte` | `nudgeBus`. |
| `lumotia:start-timer` | `WipTaskList.svelte`, `MicroSteps.svelte` | `FocusTimer.svelte` + `focusTimer` store. |
| `lumotia:step-completed` | `MicroSteps.svelte` | `completionStats` refresh. |
| `lumotia:task-completed` | `stores/page.svelte.ts` (`completeTask`) | `completionStats`. |
| `lumotia:task-deleted` | `stores/page.svelte.ts` (`deleteTask`) | `completionStats`. |
| `lumotia:task-uncompleted` | `stores/page.svelte.ts` (`uncompleteTask`) | `completionStats`. |
| `lumotia:toggle-recording` | `routes/+layout.svelte` (after hotkey debounce, both backends) | `pages/DictationPage.svelte`. |
## Window APIs
@@ -151,8 +151,8 @@ Plus any commands invoked by `saveMarkdown.ts` via the dialog/file-write plugin
## Watch outs
- The truncated grep returned `tts_s...` as a unique prefix. Verify every TTS command name (`tts_speak`, possibly `tts_stop`) against `lib.rs` to make sure the table above is exhaustive.
- The "preview-*" events have two flavours: `magnotia:` namespaced (`preferences-changed`) and bare (`preview-listening`, `preview-cleanup`, `preview-hide`, `preview-append`, `preview-final`). The bare names are scoped to the overlay window's two-way handshake. Do not rename.
- `magnotia:open-wind-down` listener is in `+layout.svelte` so the page opens regardless of which window the tray click came from. If you ever isolate windows further, this assumption breaks.
- The "preview-*" events have two flavours: `lumotia:` namespaced (`preferences-changed`) and bare (`preview-listening`, `preview-cleanup`, `preview-hide`, `preview-append`, `preview-final`). The bare names are scoped to the overlay window's two-way handshake. Do not rename.
- `lumotia:open-wind-down` listener is in `+layout.svelte` so the page opens regardless of which window the tray click came from. If you ever isolate windows further, this assumption breaks.
- `task-window-focus` is the only event sent specifically to the float window.
- DOM `CustomEvent` handlers do not survive across windows (they are window-local). The tasks list refresh trick on focus relies on this.

6
docs/architecture-map/01-frontend/i18n.md
View File

@@ -38,7 +38,7 @@ export const SUPPORTED_LOCALES: { code: Locale; label: string }[] = [
{ code: "de", label: "Deutsch" },
];
const STORAGE_KEY = "magnotia_locale";
const STORAGE_KEY = "lumotia_locale";
register("en", () => import("./locales/en.json"));
register("es", () => import("./locales/es.json"));
@@ -49,7 +49,7 @@ function detectInitialLocale(): Locale { /* localStorage → navigator.language
Public exports:
- `initI18n()`. Idempotent. Called from every layout's `onMount`-ish path (`+layout.svelte:38` and the float/viewer/preview break layouts).
- `setLocale(code)`. Writes to `magnotia_locale` and updates the svelte-i18n store.
- `setLocale(code)`. Writes to `lumotia_locale` and updates the svelte-i18n store.
- `currentLocale`. A derived store that components subscribe to via `$currentLocale`.
- `SUPPORTED_LOCALES` constant for the picker.
@@ -65,7 +65,7 @@ Public exports:
## Watch outs
- Adding a new locale is one `register("xx", () => import("./locales/xx.json"))` call plus a `SUPPORTED_LOCALES` entry.
- Cross window: each window initialises i18n independently via its layout. Locale change persists to `localStorage["magnotia_locale"]`. Float and viewer pick up the new locale on the next mount, not live. Worth wiring a Tauri event if live cross-window translation is needed.
- Cross window: each window initialises i18n independently via its layout. Locale change persists to `localStorage["lumotia_locale"]`. Float and viewer pick up the new locale on the next mount, not live. Worth wiring a Tauri event if live cross-window translation is needed.
- The "British English" toggle in `settings.britishEnglish` is a transcription post-processing flag (slice 04 territory), not a UI locale. Not wired through svelte-i18n.
- Default locale is detected from `navigator.language`. In Tauri, this is the OS locale.

4
docs/architecture-map/01-frontend/pages-overview.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Pages overview
**Plain English summary.** Magnotia has seven main window pages and three secondary window pages. The main window picks which to show by reading `page.current` (a string in the `page` store) and rendering the matching component. The secondary windows are routed by URL (`/float`, `/viewer`, `/preview`).
**Plain English summary.** Lumotia has seven main window pages and three secondary window pages. The main window picks which to show by reading `page.current` (a string in the `page` store) and rendering the matching component. The secondary windows are routed by URL (`/float`, `/viewer`, `/preview`).
## At a glance
@@ -31,7 +31,7 @@ last_verified: 2026/05/09
| Tasks | `src/lib/pages/TasksPage.svelte` | 725 | Inbox/today/soon/later board with energy chips, lists, completion sparkline. |
| Files | `src/lib/pages/FilesPage.svelte` | 263 | Drop or browse audio/video files. Calls `transcribe_file`. |
| First run | `src/lib/pages/FirstRunPage.svelte` | 337 | Hardware probe (`probe_system`), model recommendation, model download. Auto exits to dictation. |
| Shutdown ritual | `src/lib/pages/ShutdownRitualPage.svelte` | 169 | Evening wind down ritual. Triggered from the tray menu via `magnotia:open-wind-down`. |
| Shutdown ritual | `src/lib/pages/ShutdownRitualPage.svelte` | 169 | Evening wind down ritual. Triggered from the tray menu via `lumotia:open-wind-down`. |
### Secondary windows (URL routed)

4
docs/architecture-map/01-frontend/pages/dictation.md
View File

@@ -39,12 +39,12 @@ last_verified: 2026/05/09
### Lifecycle
- `onMount`. Loads `runtimeCapabilities` (`DictationPage.svelte:134`). Sets up the global hotkey custom event listener (`magnotia:toggle-recording`, dispatched from the `+layout.svelte` hotkey path).
- `onMount`. Loads `runtimeCapabilities` (`DictationPage.svelte:134`). Sets up the global hotkey custom event listener (`lumotia:toggle-recording`, dispatched from the `+layout.svelte` hotkey path).
- `onDestroy`. Tears down listeners and timers.
### Recording flow (high level)
1. Toggle from the mic button or the `magnotia:toggle-recording` window event.
1. Toggle from the mic button or the `lumotia:toggle-recording` window event.
2. If model not ready, ensure model: check `check_engine`, `check_parakeet_engine`, `check_llm_model`, then load via `load_model` / `load_parakeet_model` / `load_llm_model` as required (`DictationPage.svelte:241-272`).
3. Open two `Channel<message>` instances (`DictationPage.svelte:341-342`) and call `start_live_transcription_session` with the channel handles.
4. As the backend pushes status and partial result messages, append text to `transcript`, update `segments`, and broadcast `preview-append` to the preview overlay window (`DictationPage.svelte:165, 381, 385`). If the preview is enabled and not already open, `open_preview_window` is invoked.

2
docs/architecture-map/01-frontend/pages/first-run.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → First run
**Plain English summary.** What the user sees the first time they launch Magnotia, before any model is on disk. Probes hardware, recommends a Whisper model size, and downloads the chosen model (Whisper or Parakeet). On success, transitions to the dictation page.
**Plain English summary.** What the user sees the first time they launch Lumotia, before any model is on disk. Probes hardware, recommends a Whisper model size, and downloads the chosen model (Whisper or Parakeet). On success, transitions to the dictation page.
## At a glance

4
docs/architecture-map/01-frontend/pages/settings.md
View File

@@ -47,13 +47,13 @@ Built from `SettingsGroup` accordions. Top level groups (line refs are anchors i
- `audioDevices`, `downloadedModels`, `parakeetOk`, `parakeetDownloaded`, `pasteBackends`, `systemInfo`, `runtimeCapabilities`, `llmLoaded`, `llmModels`, `llmStatuses`, `ttsVoices`.
- Search query (`X`/`Search` icons) drives a force open mode for `SettingsGroup` (`SettingsPage.svelte:432-477`).
- Three concurrent download progress listeners: Whisper (`model-download-progress`), Parakeet (`parakeet-download-progress`), LLM (`magnotia:llm-download-progress`) (`SettingsPage.svelte:864-880`).
- Three concurrent download progress listeners: Whisper (`model-download-progress`), Parakeet (`parakeet-download-progress`), LLM (`lumotia:llm-download-progress`) (`SettingsPage.svelte:864-880`).
## Tauri command surface
Audio: `list_audio_devices`. Models (Whisper): `list_models`, `download_model`, `load_model`, `check_engine`. Models (Parakeet): `check_parakeet_engine`, `check_parakeet_model`, `download_parakeet_model`, `load_parakeet_model`. Models (LLM): `recommend_llm_tier`, `check_llm_model`, `download_llm_model`, `load_llm_model`, `unload_llm_model`, `delete_llm_model`, `test_llm_model`, `get_llm_status`. Capabilities: `get_runtime_capabilities`, `probe_system`, `detect_paste_backends`. TTS: `tts_list_voices`, `tts_speak`. Diagnostics: `generate_diagnostic_report`, `save_diagnostic_report`. Plus the implicit `save_preferences` invoked by the preferences store on every accessibility toggle.
Events listened to: `model-download-progress`, `parakeet-download-progress`, `magnotia:llm-download-progress`.
Events listened to: `model-download-progress`, `parakeet-download-progress`, `lumotia:llm-download-progress`.
## Watch outs

4
docs/architecture-map/01-frontend/pages/tasks.md
View File

@@ -43,7 +43,7 @@ last_verified: 2026/05/09
### Events
- Listens implicitly to: `magnotia:task-completed`, `magnotia:task-uncompleted`, `magnotia:task-deleted`, `magnotia:step-completed` are emitted from store helpers and consumed by `completionStats.svelte.ts` to refresh the sparkline.
- Listens implicitly to: `lumotia:task-completed`, `lumotia:task-uncompleted`, `lumotia:task-deleted`, `lumotia:step-completed` are emitted from store helpers and consumed by `completionStats.svelte.ts` to refresh the sparkline.
## Tauri command surface (direct)
@@ -54,7 +54,7 @@ The store helpers used here call into Rust through `add_task_cmd`, `complete_tas
## Watch outs
- Drag and drop is heavy on this page. Reorder mutations should always go via the store helpers; do not manipulate `tasks` directly or you will desync the SQLite source of truth.
- The sparkline is gated on `settings.showMomentumSparkline` (true by default). It re renders on the four `magnotia:task-*` events, plus window focus for date rollover.
- The sparkline is gated on `settings.showMomentumSparkline` (true by default). It re renders on the four `lumotia:task-*` events, plus window focus for date rollover.
- "Pop out" deliberately does not pass any state. The float window reads the same store, which is shared via store hydration on mount and `localStorage` for `settings`.
- Sort, filter, search are not persisted. Reload returns to defaults.

28
docs/architecture-map/01-frontend/stores.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Stores
**Plain English summary.** Reactive state. Magnotia uses Svelte 5 runes (`$state`, `$derived`, `$effect`) instead of legacy stores. Each file under `src/lib/stores/` exports one (or more) `$state` objects plus the helper functions that read or mutate them. Components import the state directly and Svelte tracks reactivity automatically. Two persistence channels: `localStorage` for settings, profiles, task lists, templates; Tauri (`save_preferences`) for accessibility preferences.
**Plain English summary.** Reactive state. Lumotia uses Svelte 5 runes (`$state`, `$derived`, `$effect`) instead of legacy stores. Each file under `src/lib/stores/` exports one (or more) `$state` objects plus the helper functions that read or mutate them. Components import the state directly and Svelte tracks reactivity automatically. Two persistence channels: `localStorage` for settings, profiles, task lists, templates; Tauri (`save_preferences`) for accessibility preferences.
## At a glance
@@ -17,8 +17,8 @@ last_verified: 2026/05/09
- **Files:** 10 (4 085 LOC across stores + utils + types).
- **Cross window sync:**
- `localStorage` `storage` event in the float window for settings.
- Tauri `emit("magnotia:preferences-changed")` for preferences (handled by every layout).
- **Persistence keys:** `magnotia_settings`, `magnotia_profiles`, `magnotia_task_lists`, `magnotia_templates`, `magnotia_locale`, plus a viewer handoff key.
- Tauri `emit("lumotia:preferences-changed")` for preferences (handled by every layout).
- **Persistence keys:** `lumotia_settings`, `lumotia_profiles`, `lumotia_task_lists`, `lumotia_templates`, `lumotia_locale`, plus a viewer handoff key.
## The stores
@@ -26,7 +26,7 @@ last_verified: 2026/05/09
Owns:
- `page` (`PageState`): `current`, `status`, `statusColor`, `activeProfile`, `recording`, `timerText`, `handedness`, `taskSidebarOpen`. Initial: `current = "dictation"`.
- `settings` (`SettingsState`). Persisted to `localStorage["magnotia_settings"]` via `utils/settingsMigrations.ts`. Defaults at line 60 onward. Includes engine choice, model size, language, device, format mode, fillers, anti hallucination, British English, auto copy/paste, transcription preview, meeting auto capture (+ apps list), sound cues + volume, timestamps, theme, font size, AI tier, LLM model id and prompt preset, GPU concurrency, prewarm flag, save audio, output folder, global hotkey, sidebar collapsed, microphone device, energy state, match my energy, TTS voice + rate, rituals (morning/evening + time), launch at login, ritualsPromptSeen, nudges (enabled/muted/speakAloud), showMomentumSparkline.
- `settings` (`SettingsState`). Persisted to `localStorage["lumotia_settings"]` via `utils/settingsMigrations.ts`. Defaults at line 60 onward. Includes engine choice, model size, language, device, format mode, fillers, anti hallucination, British English, auto copy/paste, transcription preview, meeting auto capture (+ apps list), sound cues + volume, timestamps, theme, font size, AI tier, LLM model id and prompt preset, GPU concurrency, prewarm flag, save audio, output folder, global hotkey, sidebar collapsed, microphone device, energy state, match my energy, TTS voice + rate, rituals (morning/evening + time), launch at login, ritualsPromptSeen, nudges (enabled/muted/speakAloud), showMomentumSparkline.
- `profiles`, `templates`, `taskLists` arrays.
- `tasks` and `history` arrays.
@@ -34,7 +34,7 @@ Helpers (selected, with line refs):
- `addToHistory` → `add_transcript` (`page.svelte.ts:234`).
- `mapTranscriptRow`, `saveTranscriptMeta` → `update_transcript` (`page.svelte.ts:272`).
- `deleteFromHistoryById` → `delete_transcript` (`page.svelte.ts:320`).
- `addTask`, `completeTask`, `uncompleteTask`, `deleteTask`, `setTaskEnergy`, `updateTask` → matching `*_task_cmd` Rust commands. `completeTask` and friends emit `magnotia:task-completed | -uncompleted | -deleted` window events (line 470 onward).
- `addTask`, `completeTask`, `uncompleteTask`, `deleteTask`, `setTaskEnergy`, `updateTask` → matching `*_task_cmd` Rust commands. `completeTask` and friends emit `lumotia:task-completed | -uncompleted | -deleted` window events (line 470 onward).
- Task lists: `addTaskList`, `renameTaskList`, `deleteTaskList`, `moveTaskList`, `sortTaskLists`, `moveTaskToList`, `moveTaskListToProfile`.
- Profile mutators: `addProfileTaskList`, `removeProfileTaskList`.
- `saveSettings`, `saveProfiles`, `saveTemplates` write to `localStorage`.
@@ -45,7 +45,7 @@ Owns the `Preferences` shape: `theme` ("light" | "dark" | "system"), `zone` ("de
- DOM is the source of truth at runtime: `readFromDOM()` reads `<html>` data attributes and CSS variables; `applyToDOM(prefs)` writes them.
- Persists via `invoke("save_preferences", { preferences: JSON.stringify(prefs) })` with a debounce. Failure shows a single toast per process (`preferences.svelte.ts:101-120`).
- Cross window: `broadcastPreferences` calls `emit("magnotia:preferences-changed", { source, prefs })`. Receivers in `+layout.svelte` and the secondary `+layout@.svelte` files apply external prefs after a label check.
- Cross window: `broadcastPreferences` calls `emit("lumotia:preferences-changed", { source, prefs })`. Receivers in `+layout.svelte` and the secondary `+layout@.svelte` files apply external prefs after a label check.
- Exposes `getPreferences`, `updatePreferences`, `updateAccessibility`, `applyExternalPreferences`, `PREFERENCES_CHANGED_EVENT` constant.
- Font families resolved from a constant map (Lexend, Atkinson, OpenDyslexic).
@@ -74,14 +74,14 @@ Tracks the LLM lifecycle pill. State is one of `idle | loading | generating | do
Phase 8 gamification. Owns `recentCompletions` (`DailyCompletionCount[]`) and a `todayCount` derivation.
Refresh triggers (no polling): module load, `magnotia:task-completed`, `magnotia:step-completed`, `magnotia:task-uncompleted`, `magnotia:task-deleted`, window focus (for midnight rollover).
Refresh triggers (no polling): module load, `lumotia:task-completed`, `lumotia:step-completed`, `lumotia:task-uncompleted`, `lumotia:task-deleted`, window focus (for midnight rollover).
### `focusTimer.svelte.ts` (238 LOC).
Owns the floating focus timer. State: target ms, started at, label, taskId, paused.
- `setInterval` at 250 ms (`TICK_INTERVAL_MS`).
- Triggered by `magnotia:start-timer` window events. Emits `magnotia:focus-timer-cancelled` and `magnotia:focus-timer-complete` on transitions.
- Triggered by `lumotia:start-timer` window events. Emits `lumotia:focus-timer-cancelled` and `lumotia:focus-timer-complete` on transitions.
### `implementationIntentions.svelte.ts` (260 LOC).
@@ -90,7 +90,7 @@ Owns the floating focus timer. State: target ms, started at, label, taskId, paus
- 30 second `setInterval` (`TIME_RULE_POLL_MS`) checks time based rules.
- On match, can route `page.current = "tasks"` (lines 125, 136, 142) and call `tts_speak` if speak aloud is enabled (line 170).
- Uses `delete_implementation_rule` to remove a rule (line 82).
- Emits `magnotia:implementation-rules-changed` after writes.
- Emits `lumotia:implementation-rules-changed` after writes.
- Lifecycle: `startImplementationIntentions`, `stopImplementationIntentions` from `+layout.svelte`.
### `nudgeBus.svelte.ts` (292 LOC).
@@ -101,7 +101,7 @@ Owns the nudge engine. Two `setInterval` handles:
- Plus a `microStepTimers` Map for per task delayed notifications.
Key commands: `deliver_nudge` (line 112), `tts_speak` (line 119).
Emits `magnotia:morning-triage-finished` after the modal closes.
Emits `lumotia:morning-triage-finished` after the modal closes.
Lifecycle: `startNudgeBus`, `stopNudgeBus` from `+layout.svelte`.
### `speaker.svelte.ts` (10 LOC).
@@ -111,9 +111,9 @@ Tiny. Holds `speakingId` so `SpeakerButton` instances can debounce / cancel each
## Cross store traffic
- `DictationPage.completeRecording()` → `addToHistory` (page) → `add_transcript` Rust → push to history.
- `MicroSteps` "start timer" button → `magnotia:start-timer` → `focusTimer` store transitions → `FocusTimer` component renders ring.
- `TasksPage.addTask` → `tasks` store → emits `magnotia:task-completed/...` → `completionStats` refreshes → `CompletionSparkline` re renders.
- `SettingsPage` accessibility toggle → `updatePreferences` → DOM write + `save_preferences` invoke + `magnotia:preferences-changed` emit → secondary windows mirror.
- `MicroSteps` "start timer" button → `lumotia:start-timer` → `focusTimer` store transitions → `FocusTimer` component renders ring.
- `TasksPage.addTask` → `tasks` store → emits `lumotia:task-completed/...` → `completionStats` refreshes → `CompletionSparkline` re renders.
- `SettingsPage` accessibility toggle → `updatePreferences` → DOM write + `save_preferences` invoke + `lumotia:preferences-changed` emit → secondary windows mirror.
- Float window settings sync uses `localStorage` `storage` event, not the Tauri preference event. Drift candidate.
## Watch outs
@@ -121,7 +121,7 @@ Tiny. Holds `speakingId` so `SpeakerButton` instances can debounce / cancel each
- `page.svelte.ts` is doing a lot. Splitting transcripts, tasks, task lists, settings, profiles into separate stores would help but is outside this map's job.
- `settings` and `preferences` overlap (theme, font size, `transcriptSize`). Settings are localStorage only; preferences are Tauri persisted. Race possible during the migration `$effect`.
- `nudgeBus` and `implementationIntentions` both run timers. They are torn down in `+layout.svelte` `onDestroy`. Only the main window starts them.
- `completionStats` listens on the DOM `window` for events; it does not subscribe to `tasks` directly. Adding a new task mutation that does not emit one of the `magnotia:task-*` events will silently break the sparkline.
- `completionStats` listens on the DOM `window` for events; it does not subscribe to `tasks` directly. Adding a new task mutation that does not emit one of the `lumotia:task-*` events will silently break the sparkline.
## See also

12
docs/architecture-map/01-frontend/windows-and-routes.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Windows and routes
**Plain English summary.** Magnotia is a single SvelteKit build that runs as multiple desktop windows. The Rust side opens four webviews (main, tasks float, transcript viewer, transcription preview) and points each one at a different SvelteKit route. The frontend uses SvelteKit's `+layout@.svelte` "break" trick so secondary windows skip the main shell (sidebar, titlebar, toast viewport) and render a focused, single purpose UI.
**Plain English summary.** Lumotia is a single SvelteKit build that runs as multiple desktop windows. The Rust side opens four webviews (main, tasks float, transcript viewer, transcription preview) and points each one at a different SvelteKit route. The frontend uses SvelteKit's `+layout@.svelte` "break" trick so secondary windows skip the main shell (sidebar, titlebar, toast viewport) and render a focused, single purpose UI.
## At a glance
@@ -45,7 +45,7 @@ Responsibilities:
- Detect Tauri runtime (`hasTauriRuntime`) and OS (`loadOsInfo`). Linux uses native KWin/Mutter decorations; macOS and Windows render the custom `Titlebar` plus invisible `ResizeHandles`. Default `useCustomChrome = false` to avoid a flash on Linux (`+layout.svelte:49`).
- Hotkey backend selection. On Wayland, attempt the evdev backend (`check_hotkey_access`). Otherwise fall back to `tauri-plugin-global-shortcut`. Falls back to "unavailable" if neither path works (`+layout.svelte:76-102`).
- Hotkey registration. Only the `main` window owns the global shortcut. The function debounces evdev autorepeat at 120 ms (Handy issue #1143 referenced in comments, `+layout.svelte:171-186`).
- Cross window listeners: `magnotia:hotkey-pressed` (evdev path), `magnotia:open-wind-down` (tray menu), `magnotia:preferences-changed` (sync prefs across windows). Apply external preferences if the source label differs from our own.
- Cross window listeners: `lumotia:hotkey-pressed` (evdev path), `lumotia:open-wind-down` (tray menu), `lumotia:preferences-changed` (sync prefs across windows). Apply external preferences if the source label differs from our own.
- Theme migration `$effect`. Reads `settings.theme` (legacy "Light" / "Dark" / "System") and writes `preferences.theme` ("light" / "dark" / "system"). See README debt note 2.
- Font size CSS variable `--font-size-transcript` set on `<body>` from `settings.fontSize`.
- Global error capture. `window.onerror` and `unhandledrejection` forward to `log_frontend_error` Rust command. Best effort, swallow throws.
@@ -80,11 +80,11 @@ Tasks float window. Self contained quick add, list filter, sort menu, completed
### `src/routes/viewer/+layout@.svelte` (77 LOC)
Same break layout pattern. Mounts `Titlebar`, `ToastViewport`, applies preferences sync via `magnotia:preferences-changed`, applies theme.
Same break layout pattern. Mounts `Titlebar`, `ToastViewport`, applies preferences sync via `lumotia:preferences-changed`, applies theme.
### `src/routes/viewer/+page.svelte` (606 LOC)
Transcript editor. Hydrates from a transcript ID handed off via `localStorage` (`magnotia:viewer-handoff` style key, see file). Fetches the full row from SQLite via `get_transcript`. Renders an `<audio>` element using `convertFileSrc()` to map the saved audio path to a webview URL. Provides per segment editing, debounced autosave through `saveTranscriptMeta`, virtual scrolling via `VirtualSegmentList`, playback speed control (`PLAYBACK_SPEEDS`), starring and tagging.
Transcript editor. Hydrates from a transcript ID handed off via `localStorage` (`lumotia:viewer-handoff` style key, see file). Fetches the full row from SQLite via `get_transcript`. Renders an `<audio>` element using `convertFileSrc()` to map the saved audio path to a webview URL. Provides per segment editing, debounced autosave through `saveTranscriptMeta`, virtual scrolling via `VirtualSegmentList`, playback speed control (`PLAYBACK_SPEEDS`), starring and tagging.
### `src/routes/preview/+layout@.svelte` (68 LOC)
@@ -98,8 +98,8 @@ Live transcription overlay. Listens for `preview-listening`, `preview-cleanup`,
- Window creation: Rust opens four webviews and routes them to `/`, `/float`, `/viewer`, `/preview`. The same JS bundle loads in each.
- Cross window state:
- `localStorage` carries `magnotia_settings` and the viewer handoff payload. Float window listens on the browser `storage` event to mirror settings.
- Tauri events carry preferences (`magnotia:preferences-changed`), tray driven navigation (`magnotia:open-wind-down`), and float window focus (`task-window-focus`).
- `localStorage` carries `lumotia_settings` and the viewer handoff payload. Float window listens on the browser `storage` event to mirror settings.
- Tauri events carry preferences (`lumotia:preferences-changed`), tray driven navigation (`lumotia:open-wind-down`), and float window focus (`task-window-focus`).
- Hotkey: only the main window registers, but every window's layout includes the migration `$effect`. The label guard at `+layout.svelte:115-121` prevents secondary windows from re registering.
- First run gating: only the main window evaluates and sets `page.current = "first-run"`. The float/viewer/preview windows skip the shell altogether.

12
docs/architecture-map/02-tauri-runtime/README.md
View File

@@ -9,17 +9,17 @@ last_verified: 2026/05/12
> **Where you are:** [Architecture map](../README.md) → Tauri runtime
**Plain English summary.** The Tauri runtime is the bridge between Magnotia's Svelte frontend and the Rust workspace crates. It owns app startup (database init, panic hook, plugin wiring, preferences injection), the system tray, the secondary windows (task float, transcript viewer, transcription preview), and the entire `#[tauri::command]` surface that the frontend invokes for audio capture, transcription, LLM cleanup, task and transcript CRUD, paste, TTS, hotkeys, diagnostics, and more. Everything that runs on the host process but is not pure crate logic lives here.
**Plain English summary.** The Tauri runtime is the bridge between Lumotia's Svelte frontend and the Rust workspace crates. It owns app startup (database init, panic hook, plugin wiring, preferences injection), the system tray, the secondary windows (task float, transcript viewer, transcription preview), and the entire `#[tauri::command]` surface that the frontend invokes for audio capture, transcription, LLM cleanup, task and transcript CRUD, paste, TTS, hotkeys, diagnostics, and more. Everything that runs on the host process but is not pure crate logic lives here.
## At a glance
- Path: `src-tauri/`
- Total LOC (Rust + Cargo + JSON, excluding `gen/`): ~8,690.
- Tauri version: `2` (see `src-tauri/Cargo.toml:44`).
- Bundle identifier: `uk.co.corbel.magnotia` (`src-tauri/tauri.conf.json:5`).
- Bundle identifier: `uk.co.corbel.lumotia` (`src-tauri/tauri.conf.json:5`).
- Plugins (always-on): `tauri-plugin-opener`, `tauri-plugin-dialog`, `tauri-plugin-notification`.
- Plugins (desktop-only, gated `cfg(not(target_os = "android"))`): `tauri-plugin-global-shortcut`, `tauri-plugin-autostart` (LaunchAgent), `tauri-plugin-window-state`. The `tray-icon` Tauri feature is also desktop-only.
- Workspace crates pulled in: `magnotia-core`, `magnotia-audio`, `magnotia-transcription` (default-features off, `whisper` re-enabled here), `magnotia-ai-formatting`, `magnotia-storage`, `magnotia-cloud-providers`, `magnotia-hotkey`, `magnotia-llm`.
- Workspace crates pulled in: `lumotia-core`, `lumotia-audio`, `lumotia-transcription` (default-features off, `whisper` re-enabled here), `lumotia-ai-formatting`, `lumotia-storage`, `lumotia-cloud-providers`, `lumotia-hotkey`, `lumotia-llm`.
- Tauri commands exposed via `invoke_handler` in `src-tauri/src/lib.rs:321`: 71 commands.
- Capability files: `src-tauri/capabilities/main.json` (main window) and `src-tauri/capabilities/secondary-windows.json` (task float, transcript viewer, transcription preview).
- Command modules: 22 `#[tauri::command]` modules plus 3 utility modules (`mod.rs`, `power.rs`, `security.rs`).
@@ -47,9 +47,9 @@ Individual command pages (linked from the commands index):
## How this slice connects to others
- **Frontend (slice 01).** Every `#[tauri::command]` is invoked from Svelte via `@tauri-apps/api/core` `invoke()`. Events emitted via `app.emit(...)` are consumed via `listen()` in the frontend. Live transcription uses typed `tauri::ipc::Channel` instead of plain events; the channel pair is created on the JS side and passed in as command args.
- **Audio + transcription (slice 03).** `commands::audio` calls `magnotia_audio::{MicrophoneCapture, WavWriter, decode_audio_file_limited, resample_to_16khz, probe_audio_duration_secs}`. `commands::transcription` and `commands::live` call `magnotia_transcription::LocalEngine` plus `magnotia_audio::StreamingResampler`. `commands::models` calls `magnotia_transcription::{model_manager, load_whisper, load_parakeet}`.
- **LLM + formatting + MCP (slice 04).** `commands::llm` calls `magnotia_llm::{LlmEngine, model_manager, ContentTags, LlmModelId}` and `magnotia_ai_formatting::{llm_cleanup_text, LlmPromptPreset}`. `commands::tasks` calls `magnotia_llm::prompts::FeedbackExample` and the engine's `decompose_task_with_feedback` / `extract_tasks_with_feedback` / `extract_content_tags`. `commands::transcription` and `commands::live` call `magnotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`. `commands::profiles` calls `magnotia_ai_formatting::extract_corrections` for auto-learned vocabulary.
- **Core + storage + hotkey + build (slice 05).** Everything DB-touching goes through `magnotia_storage` (`init`, `database_path`, `get_setting`, `set_setting`, `prune_error_log`, the full set of CRUD helpers, `app_data_dir`, `crashes_dir`, `logs_dir`, `list_recent_errors`, `log_error`). `commands::hardware` and `commands::models` call `magnotia_core::{hardware, model_registry, recommendation, types, constants}`. `commands::meeting` calls `magnotia_core::process_watch`. `commands::hotkey` is a thin Tauri wrapper around `magnotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent}`. `build.rs` is the build-system half of the slice (CSP regression guard plus ggml multi-definition link arg).
- **Audio + transcription (slice 03).** `commands::audio` calls `lumotia_audio::{MicrophoneCapture, WavWriter, decode_audio_file_limited, resample_to_16khz, probe_audio_duration_secs}`. `commands::transcription` and `commands::live` call `lumotia_transcription::LocalEngine` plus `lumotia_audio::StreamingResampler`. `commands::models` calls `lumotia_transcription::{model_manager, load_whisper, load_parakeet}`.
- **LLM + formatting + MCP (slice 04).** `commands::llm` calls `lumotia_llm::{LlmEngine, model_manager, ContentTags, LlmModelId}` and `lumotia_ai_formatting::{llm_cleanup_text, LlmPromptPreset}`. `commands::tasks` calls `lumotia_llm::prompts::FeedbackExample` and the engine's `decompose_task_with_feedback` / `extract_tasks_with_feedback` / `extract_content_tags`. `commands::transcription` and `commands::live` call `lumotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`. `commands::profiles` calls `lumotia_ai_formatting::extract_corrections` for auto-learned vocabulary.
- **Core + storage + hotkey + build (slice 05).** Everything DB-touching goes through `lumotia_storage` (`init`, `database_path`, `get_setting`, `set_setting`, `prune_error_log`, the full set of CRUD helpers, `app_data_dir`, `crashes_dir`, `logs_dir`, `list_recent_errors`, `log_error`). `commands::hardware` and `commands::models` call `lumotia_core::{hardware, model_registry, recommendation, types, constants}`. `commands::meeting` calls `lumotia_core::process_watch`. `commands::hotkey` is a thin Tauri wrapper around `lumotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent}`. `build.rs` is the build-system half of the slice (CSP regression guard plus ggml multi-definition link arg).
## Open questions / debt

16
docs/architecture-map/02-tauri-runtime/app-lifecycle.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/12
> **Where you are:** [Architecture map](../README.md) → [Tauri runtime](README.md) → App lifecycle
**Plain English summary.** This is the entry point. `main.rs` calls `magnotia_lib::run()` and `lib.rs::run` does everything that has to happen before the user sees a window: initialises tracing, checks the Linux launcher env-var contract, installs the Rust panic hook, registers Tauri plugins, opens the SQLite database, prunes the error log, builds a JS preferences-injection script, configures the WebKit media-permission grant on Linux, wires close-to-tray, populates `AppState` and the per-domain managed states, emits any runtime warnings, sets up the system tray, and finally registers all 71 Tauri commands.
**Plain English summary.** This is the entry point. `main.rs` calls `lumotia_lib::run()` and `lib.rs::run` does everything that has to happen before the user sees a window: initialises tracing, checks the Linux launcher env-var contract, installs the Rust panic hook, registers Tauri plugins, opens the SQLite database, prunes the error log, builds a JS preferences-injection script, configures the WebKit media-permission grant on Linux, wires close-to-tray, populates `AppState` and the per-domain managed states, emits any runtime warnings, sets up the system tray, and finally registers all 71 Tauri commands.
## At a glance
@@ -17,14 +17,14 @@ last_verified: 2026/05/12
- LOC: 5 (main) + 491 (lib).
- Tauri commands exposed directly here: `save_preferences` (string preferences -> SQLite settings table). All other commands live under `commands::*` and are registered via `tauri::generate_handler!`.
- Events emitted directly here: none (runtime warnings are emitted by `commands::models::emit_runtime_warnings`, called from setup).
- Depends on: `tauri`, `sqlx::SqlitePool`, `magnotia_core::types::EngineName`, `magnotia_llm::LlmEngine`, `magnotia_storage::{init, database_path, get_setting, set_setting, prune_error_log}`, `magnotia_transcription::LocalEngine`, plus the `commands::*` and `tray` modules.
- Depends on: `tauri`, `sqlx::SqlitePool`, `lumotia_core::types::EngineName`, `lumotia_llm::LlmEngine`, `lumotia_storage::{init, database_path, get_setting, set_setting, prune_error_log}`, `lumotia_transcription::LocalEngine`, plus the `commands::*` and `tray` modules.
- Called from frontend at: every `invoke()` site in slice 01 lands in the handler list registered here.
## What's in here
### `main.rs`
Single function. Sets `windows_subsystem = "windows"` for release builds (no console window) and calls `magnotia_lib::run()`. (`src-tauri/src/main.rs:1`).
Single function. Sets `windows_subsystem = "windows"` for release builds (no console window) and calls `lumotia_lib::run()`. (`src-tauri/src/main.rs:1`).
### `lib.rs`
@@ -45,9 +45,9 @@ Types managed in Tauri state:
Functions:
- `build_preferences_script(prefs_json: Option<String>) -> String` (`src-tauri/src/lib.rs:38`). Builds an IIFE that reads saved preferences (theme, zone, accessibility settings: font family, font size, letter spacing, line height, transcript size, bionic reading, reduce motion) and applies them to `<html>` before the rest of the document loads. Embeds the JSON via `serde_json::to_string` to keep it safe.
- `save_preferences(state, preferences) -> Result<(), String>` (`src-tauri/src/lib.rs:73`). The single command in `lib.rs`. Persists the preferences blob to the SQLite settings table under key `magnotia_preferences`.
- `save_preferences(state, preferences) -> Result<(), String>` (`src-tauri/src/lib.rs:73`). The single command in `lib.rs`. Persists the preferences blob to the SQLite settings table under key `lumotia_preferences`.
- `init_tracing()` (Linux/macOS/Windows). Initialises the process-wide tracing subscriber once, honours `RUST_LOG`, and writes structured startup/runtime logs to stderr.
- `warn_if_x11_env_unset_on_wayland()` (Linux only). Emits a `magnotia_startup` warning when the launcher has not pre-set `WEBKIT_DISABLE_DMABUF_RENDERER` (always expected on Linux), or `GDK_BACKEND=x11` / `WINIT_UNIX_BACKEND=x11` when `XDG_SESSION_TYPE=wayland`. It does not mutate the process environment; `run.sh` owns the dev-time contract and package wrappers/.desktop files must own the distribution-time contract.
- `warn_if_x11_env_unset_on_wayland()` (Linux only). Emits a `lumotia_startup` warning when the launcher has not pre-set `WEBKIT_DISABLE_DMABUF_RENDERER` (always expected on Linux), or `GDK_BACKEND=x11` / `WINIT_UNIX_BACKEND=x11` when `XDG_SESSION_TYPE=wayland`. It does not mutate the process environment; `run.sh` owns the dev-time contract and package wrappers/.desktop files must own the distribution-time contract.
- `run()`. The Tauri builder pipeline.
### `run()` step-by-step
@@ -58,7 +58,7 @@ Functions:
4. **Plugin wiring (always-on).** `tauri_plugin_opener`, `tauri_plugin_dialog`, `tauri_plugin_notification` (`src-tauri/src/lib.rs:144`).
5. **Plugin wiring (desktop-only).** `tauri_plugin_global_shortcut`, `tauri_plugin_autostart` (LaunchAgent on macOS), `tauri_plugin_window_state` (`src-tauri/src/lib.rs:158`).
6. **Setup hook.** This is where the bulk of startup work lives:
- Initialise SQLite via `magnotia_storage::init(&database_path()).await` using `tauri::async_runtime::block_on` (`src-tauri/src/lib.rs:180`). The `Instant::now()` timing is logged.
- Initialise SQLite via `lumotia_storage::init(&database_path()).await` using `tauri::async_runtime::block_on` (`src-tauri/src/lib.rs:180`). The `Instant::now()` timing is logged.
- Prune `error_log` rows older than 90 days (`src-tauri/src/lib.rs:189`). Best-effort: a failure logs but does not block startup.
- Load saved preferences from the settings table; build the JS injection script (`src-tauri/src/lib.rs:204`).
- Apply the injection script to the main window via `WebviewWindow.eval()` (`src-tauri/src/lib.rs:215`).
@@ -69,7 +69,7 @@ Functions:
- Emit runtime warnings (CPU baseline, Vulkan loader) via `commands::models::emit_runtime_warnings` (`src-tauri/src/lib.rs:312`).
- Setup the system tray on desktop (`src-tauri/src/lib.rs:314`).
7. **Command registration.** `tauri::generate_handler![...]` lists 71 commands (`src-tauri/src/lib.rs:321`). The order in the macro is grouped by domain (preferences, models, LLM, transcription, audio, tasks, feedback, TTS, rituals, nudges, intentions, profiles, transcripts, diagnostics, live, windows, clipboard, fs, paste, meeting, hardware, hotkey, updater).
8. **Run.** `.run(tauri::generate_context!())` blocks the main thread until the app exits. Panics are wrapped with `expect("error while running Magnotia")`.
8. **Run.** `.run(tauri::generate_context!())` blocks the main thread until the app exits. Panics are wrapped with `expect("error while running Lumotia")`.
## Data flow
@@ -81,7 +81,7 @@ Functions:
## Watch-outs
- `tauri::async_runtime::block_on` inside `setup` blocks startup. The DB init and prefs read are explicitly timed and logged so regressions show up. Adding more synchronous async work here directly pushes the time-to-first-paint up.
- The Linux media-permission wire-up is non-fatal: if `with_webview` fails the app still boots, but `getUserMedia` will be silently denied or fall back to a prompt the user cannot answer (no UI). The error path logs a `magnotia_startup` warning.
- The Linux media-permission wire-up is non-fatal: if `with_webview` fails the app still boots, but `getUserMedia` will be silently denied or fall back to a prompt the user cannot answer (no UI). The error path logs a `lumotia_startup` warning.
- Linux rendering env vars are a launcher contract, not a runtime mutation. In development, use `npm run dev:tauri` / `./run.sh`; packaged Linux builds need an equivalent wrapper or `.desktop` `Exec=env` policy. `WEBKIT_DISABLE_DMABUF_RENDERER=0` remains the user opt-out for the DMA-BUF workaround.
- Close-to-tray works only on desktop (the `cfg!(not(target_os = "android"))` block). On Android, closing the activity terminates the process, which is the expected platform behaviour.
- The `prewarm_default_model` call is *not* wired here. `commands::models::prewarm_default_model` exists, but `setup` does not invoke it. The frontend invokes the matching `prewarm_default_model_cmd` command after the main page mounts. If you ever want to shift pre-warm into setup, watch the spawn_blocking ordering against the engine `Arc` clones.

4
docs/architecture-map/02-tauri-runtime/capabilities-and-acl.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../README.md) → [Tauri runtime](README.md) → Capabilities and ACL
**Plain English summary.** Tauri 2 ships a permission-and-capability ACL: every plugin and core API ships permissions, capabilities bind permissions to specific window labels. Magnotia ships two capability files. The main window gets the broad set (dialog, opener, autostart, global shortcuts, notifications, full window control). The three secondary windows (task float, transcript viewer, transcription preview) get a narrow set with no plugin permissions at all and no destructive window APIs. The split is the firewall that prevents a compromised secondary window from launching an installer or registering a global hotkey.
**Plain English summary.** Tauri 2 ships a permission-and-capability ACL: every plugin and core API ships permissions, capabilities bind permissions to specific window labels. Lumotia ships two capability files. The main window gets the broad set (dialog, opener, autostart, global shortcuts, notifications, full window control). The three secondary windows (task float, transcript viewer, transcription preview) get a narrow set with no plugin permissions at all and no destructive window APIs. The split is the firewall that prevents a compromised secondary window from launching an installer or registering a global hotkey.
## At a glance
@@ -57,7 +57,7 @@ Notes:
- The window-control set is granular: there is no `core:window:default`, every action is opted in. `allow-start-dragging` is what the custom Titlebar uses to drag a frameless window.
- `opener:default` lets the frontend open external URLs via `tauri-plugin-opener`. This is how the Settings → About links route out.
- `dialog:default` enables the file/save dialogs used by the import-audio and save-diagnostic-report flows.
- `global-shortcut:allow-register` and `allow-unregister` let the main window manage the dictation hotkey via the cross-platform plugin path. On Linux Magnotia uses the bespoke evdev backend (see `commands::hotkey`), but Settings still talks to the global-shortcut plugin so the same UI works on macOS / Windows.
- `global-shortcut:allow-register` and `allow-unregister` let the main window manage the dictation hotkey via the cross-platform plugin path. On Linux Lumotia uses the bespoke evdev backend (see `commands::hotkey`), but Settings still talks to the global-shortcut plugin so the same UI works on macOS / Windows.
- `autostart:*` lets Settings toggle login-time autostart.
- `notification:*` is what the Phase 6 nudge bus uses; the Rust-side `commands::nudges::deliver_nudge` adds the main-window-only firewall.

26
docs/architecture-map/02-tauri-runtime/cargo-and-features.md
View File

@@ -23,12 +23,12 @@ last_verified: 2026/05/09
### `Cargo.toml`
Package metadata: `name = "magnotia"`, `version = "0.1.0"`, `description = "Magnotia — Think out loud"`, `authors = ["CORBEL Ltd"]`, `edition = "2021"`.
Package metadata: `name = "lumotia"`, `version = "0.1.0"`, `description = "Lumotia — Think out loud"`, `authors = ["CORBEL Ltd"]`, `edition = "2021"`.
Lib stanza (`src-tauri/Cargo.toml:8`):
```
name = "magnotia_lib"
name = "lumotia_lib"
crate-type = ["staticlib", "cdylib", "rlib"]
```
@@ -38,10 +38,10 @@ crate-type = ["staticlib", "cdylib", "rlib"]
```
default = ["whisper"]
whisper = ["magnotia-transcription/whisper"]
whisper = ["lumotia-transcription/whisper"]
```
The `whisper` feature transitively enables `magnotia-transcription/whisper`. The crate-level `default-features = false` on `magnotia-transcription` (`src-tauri/Cargo.toml:33`) means a `--no-default-features` workspace build drops `whisper-rs-sys` entirely; Parakeet still works. `commands::models::load_model_from_disk` returns a clear runtime error for `Engine::Whisper` when the feature is off.
The `whisper` feature transitively enables `lumotia-transcription/whisper`. The crate-level `default-features = false` on `lumotia-transcription` (`src-tauri/Cargo.toml:33`) means a `--no-default-features` workspace build drops `whisper-rs-sys` entirely; Parakeet still works. `commands::models::load_model_from_disk` returns a clear runtime error for `Engine::Whisper` when the feature is off.
#### `[build-dependencies]`
@@ -50,14 +50,14 @@ The `whisper` feature transitively enables `magnotia-transcription/whisper`. The
#### `[dependencies]` — workspace crates
```
magnotia-core
magnotia-audio
magnotia-transcription { default-features = false }
magnotia-ai-formatting
magnotia-storage
magnotia-cloud-providers
magnotia-hotkey
magnotia-llm
lumotia-core
lumotia-audio
lumotia-transcription { default-features = false }
lumotia-ai-formatting
lumotia-storage
lumotia-cloud-providers
lumotia-hotkey
lumotia-llm
```
The `cloud-providers` crate is referenced here even though no command file currently imports it. Likely reserved for the Phase-N upload flow that the diagnostic-report bundler hints at.
@@ -84,7 +84,7 @@ sqlx = { version = "0.8", default-features = false, features = ["runtime-
uuid = { version = "1", features = ["v4"] }
```
The `sqlx` block has `default-features = false` and only opts into `runtime-tokio` and `sqlite`. `magnotia-storage` already pulls the macros / migrate / any / json features via its own re-export, so duplicating them here would just bloat compile time. `sqlx` is named directly because `AppState` types it as `SqlitePool`; naming a transitive dep type still requires the dep be listed.
The `sqlx` block has `default-features = false` and only opts into `runtime-tokio` and `sqlite`. `lumotia-storage` already pulls the macros / migrate / any / json features via its own re-export, so duplicating them here would just bloat compile time. `sqlx` is named directly because `AppState` types it as `SqlitePool`; naming a transitive dep type still requires the dep be listed.
#### `[dev-dependencies]`

8
docs/architecture-map/02-tauri-runtime/commands/audio.md
View File

@@ -21,7 +21,7 @@ last_verified: 2026/05/09
- `stop_native_capture(window, state) -> Result<Vec<f32>, String>` — main-window only. Awaits the worker join barrier (RB-06) and returns the accumulated samples.
- `save_audio(window, app, samples, output_folder: Option<String>) -> Result<String, String>` — main-window only. Writes a fresh WAV to `app_local_data_dir/recordings/` (or a user-chosen folder) and returns its absolute path.
- Events emitted: `native-pcm` (payload `{ samples: Vec<f32> }`, ~0.5 s of 16 kHz mono per emit) — `src-tauri/src/commands/audio.rs:249` and `:274`.
- Depends on: `magnotia_audio::{DeviceInfo, MicrophoneCapture, WavWriter, write_wav}`, `magnotia_core::types::AudioSamples`, `magnotia_core::constants::WHISPER_SAMPLE_RATE`. Plus `tokio::{mpsc, Mutex, JoinHandle, spawn_blocking, sleep}` and `std::sync::{Arc, Mutex, atomic::AtomicBool}`.
- Depends on: `lumotia_audio::{DeviceInfo, MicrophoneCapture, WavWriter, write_wav}`, `lumotia_core::types::AudioSamples`, `lumotia_core::constants::WHISPER_SAMPLE_RATE`. Plus `tokio::{mpsc, Mutex, JoinHandle, spawn_blocking, sleep}` and `std::sync::{Arc, Mutex, atomic::AtomicBool}`.
- Called from frontend at: dictation page (start / stop), Settings → Audio (device list), file-import flow (save_audio).
## What's in here
@@ -75,11 +75,11 @@ Public helper used by `commands::live::start_live_transcription_session`. Resolv
### `recording_filename` (`src-tauri/src/commands/audio.rs:365`)
Deterministic filename: `magnotia-<unix_secs>-<nanos:09>-<counter:04>.wav`. The counter is a process-lifetime `AtomicU64` (`RECORDING_COUNTER`) bumped on each call. The combination defeats wall-clock collisions both across launches (secs change) and within the same nanosecond (counter changes).
Deterministic filename: `lumotia-<unix_secs>-<nanos:09>-<counter:04>.wav`. The counter is a process-lifetime `AtomicU64` (`RECORDING_COUNTER`) bumped on each call. The combination defeats wall-clock collisions both across launches (secs change) and within the same nanosecond (counter changes).
### `persist_audio_samples` and `save_audio` (`src-tauri/src/commands/audio.rs:512`, `:531`)
`save_audio` is the public command. Calls `persist_audio_samples`, which resolves the recording path, then calls `magnotia_audio::write_wav` inside `spawn_blocking`. Returns the absolute path as a string.
`save_audio` is the public command. Calls `persist_audio_samples`, which resolves the recording path, then calls `lumotia_audio::write_wav` inside `spawn_blocking`. Returns the absolute path as a string.
## Data flow
@@ -90,7 +90,7 @@ Deterministic filename: `magnotia-<unix_secs>-<nanos:09>-<counter:04>.wav`. The
## Watch-outs
- The in-memory buffer is capped at 10 minutes. Anything longer relies on the temp WAV; the frontend cannot just `stop_native_capture` and treat the returned vec as ground truth for long sessions. Today's UI assumes short captures, but the cap should be surfaced if you build a long-form recorder.
- The downsampler is naive decimation. Acceptable for speech but not for music. If you ever extend Magnotia to general audio, swap in `magnotia_audio::StreamingResampler` (which is what `commands::live` uses).
- The downsampler is naive decimation. Acceptable for speech but not for music. If you ever extend Lumotia to general audio, swap in `lumotia_audio::StreamingResampler` (which is what `commands::live` uses).
- `start_native_capture` does *not* engage `PowerAssertion` (App Nap pinning). `commands::live::run_live_session` does. If you build a long-form non-live recorder on top of this, add the assertion.
- The worker emits `native-pcm` to the entire app handle (not a specific window). Every webview that listens will receive the chunks. If you ever route audio to a non-main window, double-check this is what you want.
- `stop_worker_awaits_full_termination_no_writes_after_join` (`src-tauri/src/commands/audio.rs:454`) is the regression test for RB-06. Do not change `stop_worker` to a fire-and-forget pattern.

10
docs/architecture-map/02-tauri-runtime/commands/diagnostics.md
View File

@@ -24,7 +24,7 @@ last_verified: 2026/05/09
- `get_os_info() -> OsInfo`.
- Public Rust helper used by `lib.rs::run`: `install_panic_hook()`.
- Events emitted: none.
- Depends on: `magnotia_storage::{app_data_dir, crashes_dir, list_recent_errors, log_error, logs_dir, ErrorLogRow}`, `commands::power::active_assertions_snapshot`, `commands::security::ensure_main_window`. Plus `std::fs`, `std::panic`, `std::time`.
- Depends on: `lumotia_storage::{app_data_dir, crashes_dir, list_recent_errors, log_error, logs_dir, ErrorLogRow}`, `commands::power::active_assertions_snapshot`, `commands::security::ensure_main_window`. Plus `std::fs`, `std::panic`, `std::time`.
- Called from frontend at: global `window.onerror` / `window.unhandledrejection` (`log_frontend_error`); Settings → About → Diagnostics (the bundle commands and `list_*` commands); top-of-app Cmd-vs-Ctrl labelling (`get_os_info`).
## What's in here
@@ -40,7 +40,7 @@ Creates `crashes_dir()` if missing. Replaces the default panic hook with one tha
### `log_frontend_error` (`:86`)
Truncates the stack to 2,000 chars and calls `magnotia_storage::log_error` with context `"frontend"` (or the caller-supplied context), error code `"FRONTEND_ERROR"`, the message, and the stack as metadata.
Truncates the stack to 2,000 chars and calls `lumotia_storage::log_error` with context `"frontend"` (or the caller-supplied context), error code `"FRONTEND_ERROR"`, the message, and the stack as metadata.
### `ErrorLogDto` (`:114`) and `list_recent_errors_command` (`:138`)
@@ -68,11 +68,11 @@ Builds a markdown document with sections:
3. Recent errors (50 rows, redacted).
4. Power assertions (snapshots from `commands::power::active_assertions_snapshot`).
5. Crash dumps (up to 5 most-recent, plus a count of older ones).
6. Log tail (8 KB tail of `logs_dir/magnotia.log`, home-redacted).
6. Log tail (8 KB tail of `logs_dir/lumotia.log`, home-redacted).
### `save_diagnostic_report` (`:513`)
Generates the report, then writes it to `app_data_dir/diagnostic-reports/magnotia-diagnostic-<unix_secs>.md`. Returns the absolute path.
Generates the report, then writes it to `app_data_dir/diagnostic-reports/lumotia-diagnostic-<unix_secs>.md`. Returns the absolute path.
### `OsInfo` and `get_os_info` (`:449`, `:474`)
@@ -83,7 +83,7 @@ OS family label, arch, `uses_cmd` boolean (macOS only), `is_wayland` boolean (Li
```
panic occurs -> install_panic_hook writes crashes_dir/<ts>.crash
window.onerror fires in JS -> invoke('log_frontend_error', context, message, stack)
-> magnotia_storage::log_error
-> lumotia_storage::log_error
-> error_log table
Settings -> About -> Diagnostics

4
docs/architecture-map/02-tauri-runtime/commands/feedback.md
View File

@@ -19,7 +19,7 @@ last_verified: 2026/05/09
- `record_feedback(state, input: RecordFeedbackInput) -> Result<i64, String>` — returns the new row id.
- `list_feedback_examples_cmd(state, target_type, limit, min_rating, profile_id) -> Result<Vec<FeedbackDto>, String>`.
- Events emitted: none.
- Depends on: `magnotia_storage::{record_feedback, list_feedback_examples, FeedbackRow, FeedbackTargetType, RecordFeedbackParams}`.
- Depends on: `lumotia_storage::{record_feedback, list_feedback_examples, FeedbackRow, FeedbackTargetType, RecordFeedbackParams}`.
- Called from frontend at: dictation result panel (thumb up/down + correction-text on cleanup); Tasks page (thumb on extracted tasks and decomposed microsteps).
## What's in here
@@ -56,7 +56,7 @@ Clamps `limit` to `[1, 64]`, defaults 8. Clamps `min_rating` to `[-1, 1]`, defau
```
dictation result thumbs-up -> invoke('record_feedback', { targetType: 'cleanup', rating: +1, originalText, correctedText, contextJson, profileId })
-> magnotia_storage::record_feedback -> row id
-> lumotia_storage::record_feedback -> row id
decomposition thumbs-down + correction -> record_feedback({ targetType: 'microstep', rating: 0, originalText, correctedText: "user's preferred wording", contextJson: {parent_text}, profileId })

16
docs/architecture-map/02-tauri-runtime/commands/hotkey.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Hotkey bridge
**Plain English summary.** The Linux Wayland-compatible global hotkey backend. Tauri's `tauri-plugin-global-shortcut` works on macOS / Windows and on X11 Linux but fails silently on Wayland (the protocol forbids unprivileged keystroke grabs). Magnotia's bespoke evdev backend reads `/dev/input/event*` directly, parses key combos, and emits `magnotia:hotkey-pressed` / `magnotia:hotkey-released` events. Settings on Linux uses these commands instead of the global-shortcut plugin; everywhere else the plugin path is canonical.
**Plain English summary.** The Linux Wayland-compatible global hotkey backend. Tauri's `tauri-plugin-global-shortcut` works on macOS / Windows and on X11 Linux but fails silently on Wayland (the protocol forbids unprivileged keystroke grabs). Lumotia's bespoke evdev backend reads `/dev/input/event*` directly, parses key combos, and emits `lumotia:hotkey-pressed` / `lumotia:hotkey-released` events. Settings on Linux uses these commands instead of the global-shortcut plugin; everywhere else the plugin path is canonical.
## At a glance
@@ -21,8 +21,8 @@ last_verified: 2026/05/09
- `start_evdev_hotkey(app, state, hotkey: String) -> Result<(), String>`. Parses the Tauri-style combo string, stops any existing listener, starts a new one, spawns a forwarder task that converts evdev events to Tauri events.
- `update_evdev_hotkey(state, hotkey: String) -> Result<(), String>`. Updates the combo on a running listener.
- `stop_evdev_hotkey(state) -> Result<(), String>`. Stops cleanly.
- Events emitted: `magnotia:hotkey-pressed` (no payload), `magnotia:hotkey-released` (no payload). Fired from the forwarder task in `start_evdev_hotkey` (`src-tauri/src/commands/hotkey.rs:67`, `:70`).
- Depends on: `magnotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent, check_evdev_access}`. Plus `tokio::sync::{mpsc, Mutex}`.
- Events emitted: `lumotia:hotkey-pressed` (no payload), `lumotia:hotkey-released` (no payload). Fired from the forwarder task in `start_evdev_hotkey` (`src-tauri/src/commands/hotkey.rs:67`, `:70`).
- Depends on: `lumotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent, check_evdev_access}`. Plus `tokio::sync::{mpsc, Mutex}`.
- Called from frontend at: Settings → Hotkey on Linux. Other platforms call the `tauri-plugin-global-shortcut` plugin's JS API directly.
## What's in here
@@ -37,7 +37,7 @@ Returns true if `WAYLAND_DISPLAY` is set or `XDG_SESSION_TYPE=wayland`. Used by
### `check_hotkey_access` (`:32`)
Defers to `magnotia_hotkey::check_evdev_access` — that helper checks the user can read `/dev/input/event*` (typically requires being in the `input` group, or a udev rule). On failure, returns the actionable error string.
Defers to `lumotia_hotkey::check_evdev_access` — that helper checks the user can read `/dev/input/event*` (typically requires being in the `input` group, or a udev rule). On failure, returns the actionable error string.
### `start_evdev_hotkey` (`:41`)
@@ -45,7 +45,7 @@ Defers to `magnotia_hotkey::check_evdev_access` — that helper checks the user
2. Lock the listener mutex; if a listener is already running, stop it and await termination.
3. Build a 64-deep `tokio::sync::mpsc` channel for `HotkeyEvent`s.
4. Call `EvdevHotkeyListener::start(combo, event_tx)`, stash the listener.
5. Spawn a `tokio::spawn` forwarder that reads from the event_rx and emits `magnotia:hotkey-pressed` / `magnotia:hotkey-released` per event variant.
5. Spawn a `tokio::spawn` forwarder that reads from the event_rx and emits `lumotia:hotkey-pressed` / `lumotia:hotkey-released` per event variant.
### `update_evdev_hotkey` (`:81`)
@@ -65,7 +65,7 @@ Settings -> start_evdev_hotkey("Shift+Cmd+Space")
-> stop any prior listener
-> EvdevHotkeyListener spawns its own thread reading /dev/input/event*
-> forwarder spawn: HotkeyEvent -> Tauri event
frontend listens on 'magnotia:hotkey-pressed' / '...-released' and starts/stops dictation
frontend listens on 'lumotia:hotkey-pressed' / '...-released' and starts/stops dictation
Settings -> update_evdev_hotkey("Ctrl+Alt+M") (when user changes binding)
Settings -> stop_evdev_hotkey() (when user disables)
```
@@ -73,8 +73,8 @@ Settings -> stop_evdev_hotkey() (when user disables)
## Watch-outs
- **No `ensure_main_window` guard.** Settings is in the main window. If you ever expose hotkey re-binding in a secondary window, add the guard.
- **Linux only.** macOS and Windows code paths in the frontend talk to `tauri-plugin-global-shortcut` directly — no Rust commands needed because the plugin handles register / unregister via JS. This module compiles and runs on every desktop OS but only *works* on Linux because evdev is Linux-specific (the workspace crate `magnotia_hotkey` has the platform shim).
- **`/dev/input/event*` access requires either:** (a) the user is in the `input` group, or (b) a udev rule grants Magnotia explicit access. The Settings UI walks the user through option (a) on first run; option (b) is documented in `docs/dev-setup.md` for power users.
- **Linux only.** macOS and Windows code paths in the frontend talk to `tauri-plugin-global-shortcut` directly — no Rust commands needed because the plugin handles register / unregister via JS. This module compiles and runs on every desktop OS but only *works* on Linux because evdev is Linux-specific (the workspace crate `lumotia_hotkey` has the platform shim).
- **`/dev/input/event*` access requires either:** (a) the user is in the `input` group, or (b) a udev rule grants Lumotia explicit access. The Settings UI walks the user through option (a) on first run; option (b) is documented in `docs/dev-setup.md` for power users.
- **Channel size of 64** is enough for a key smash burst. If a worker stalls and the channel fills, evdev events would be dropped silently. Consider logging a warning when the channel is at capacity.
- **The forwarder spawn is detached.** No way to stop the spawn task explicitly; it exits when `event_rx.recv().await` returns None (which happens when the listener is dropped). Acceptable.
- **No power assertion.** The evdev listener thread is pinned by the kernel via the file handle; idle CPU is near zero.

6
docs/architecture-map/02-tauri-runtime/commands/intentions.md
View File

@@ -22,7 +22,7 @@ last_verified: 2026/05/09
- `mark_implementation_rule_fired(window, state, id, fired_key) -> Result<ImplementationRuleDto, String>`.
- `delete_implementation_rule(window, state, id) -> Result<(), String>`.
- Events emitted: none.
- Depends on: `magnotia_storage::{insert_implementation_rule, list_implementation_rules, set_implementation_rule_enabled, mark_implementation_rule_fired, delete_implementation_rule, get_task_by_id, ImplementationRuleRow}`, `uuid::Uuid`, `serde_json`. Plus `commands::security::ensure_main_window`.
- Depends on: `lumotia_storage::{insert_implementation_rule, list_implementation_rules, set_implementation_rule_enabled, mark_implementation_rule_fired, delete_implementation_rule, get_task_by_id, ImplementationRuleRow}`, `uuid::Uuid`, `serde_json`. Plus `commands::security::ensure_main_window`.
- Called from frontend at: Settings → Implementation intentions (CRUD); the rule-runner module (`mark_implementation_rule_fired` after firing).
## What's in here
@@ -67,7 +67,7 @@ Settings -> create_implementation_rule(req)
-> validate_request (HH:MM if applicable, action shape, task existence for surface-task)
-> uuid::v4 for id
-> serde_json serialise actions
-> magnotia_storage::insert_implementation_rule
-> lumotia_storage::insert_implementation_rule
-> list/return DTO
frontend rule-runner cron -> evaluates triggers in JS
@@ -78,7 +78,7 @@ frontend rule-runner cron -> evaluates triggers in JS
## Watch-outs
- **Action timer is hard-capped to 300 seconds.** The frontend has to surface this constraint. Future versions will need to widen the validator to accept arbitrary durations.
- **Rule execution lives entirely in the frontend.** If the user closes Magnotia at 08:55 with a 09:00 rule, the rule does not fire. There is no daemon. This is documented in the module header.
- **Rule execution lives entirely in the frontend.** If the user closes Lumotia at 08:55 with a 09:00 rule, the rule does not fire. There is no daemon. This is documented in the module header.
- **Validation is sync against the DB.** `validate_actions` calls `get_task_by_id` for every surface-task action. Multiple actions in one rule = multiple round-trips. Acceptable today; consider batching if a rule grows huge.
- **`mark_implementation_rule_fired` requires a non-empty `fired_key`.** The frontend should always pass an ISO date for daily rules and a per-event key for task-completed rules. Empty key = command rejection.
- **No `PowerAssertion`.** None of these actions run inference. No need.

10
docs/architecture-map/02-tauri-runtime/commands/live.md
View File

@@ -18,10 +18,10 @@ last_verified: 2026/05/09
- Tauri commands exposed:
- `start_live_transcription_session(window, app, state, live_state, config: StartLiveTranscriptionConfig, result_channel: Channel<LiveResultMessage>, status_channel: Channel<LiveStatusMessage>) -> Result<StartLiveTranscriptionResponse, String>` — main-window only.
- `stop_live_transcription_session(window, app, live_state, session_id: u64) -> Result<StopLiveTranscriptionResponse, String>` — main-window only.
- Events emitted: NONE in the conventional `app.emit(...)` sense. This module uses Tauri 2's typed `tauri::ipc::Channel<T>` API instead. The frontend creates the channel pair on the JS side via `new Channel<T>()`, passes it as a command argument, and Magnotia sends typed messages on it from the worker. Two channels:
- Events emitted: NONE in the conventional `app.emit(...)` sense. This module uses Tauri 2's typed `tauri::ipc::Channel<T>` API instead. The frontend creates the channel pair on the JS side via `new Channel<T>()`, passes it as a command argument, and Lumotia sends typed messages on it from the worker. Two channels:
- `Channel<LiveResultMessage>` — per-chunk transcription results (segments, language, duration, raw_text, inference_ms, chunk_id, chunk_start_secs).
- `Channel<LiveStatusMessage>` — tagged enum: `Warning { message }`, `Overload { dropped_audio_ms, message }`, `Error { message }`, `Finished { audio_path, dropped_audio_ms }`.
- Depends on: `magnotia_audio::{AudioChunk, CaptureRuntimeError, MicrophoneCapture, StreamingResampler, WavWriter}`, `magnotia_core::constants::WHISPER_SAMPLE_RATE`, `magnotia_core::types::{AudioSamples, Segment, TranscriptionOptions}`, `magnotia_transcription::LocalEngine`, `magnotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`, `magnotia_storage::{database::get_profile, database::list_profile_terms, DEFAULT_PROFILE_ID}`. Plus `commands::audio::resolve_recording_path`, `commands::build_initial_prompt`, `commands::models::{default_model_id_for_engine, ensure_model_loaded}`, `commands::power::PowerAssertion`, `commands::security::ensure_main_window`.
- Depends on: `lumotia_audio::{AudioChunk, CaptureRuntimeError, MicrophoneCapture, StreamingResampler, WavWriter}`, `lumotia_core::constants::WHISPER_SAMPLE_RATE`, `lumotia_core::types::{AudioSamples, Segment, TranscriptionOptions}`, `lumotia_transcription::LocalEngine`, `lumotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`, `lumotia_storage::{database::get_profile, database::list_profile_terms, DEFAULT_PROFILE_ID}`. Plus `commands::audio::resolve_recording_path`, `commands::build_initial_prompt`, `commands::models::{default_model_id_for_engine, ensure_model_loaded}`, `commands::power::PowerAssertion`, `commands::security::ensure_main_window`.
- Called from frontend at: dictation page (when the user starts and stops a live session — most common entry).
## What's in here
@@ -86,7 +86,7 @@ Methods:
1. `ensure_main_window`.
2. `lifecycle.lock().await` — barrier against concurrent start/stop.
3. Reject if a session is already running.
4. Resolve profile_id, fetch profile + profile_terms from `magnotia_storage`.
4. Resolve profile_id, fetch profile + profile_terms from `lumotia_storage`.
5. Collapse the effective `initial_prompt` via `build_initial_prompt` (so the worker doesn't have to know about profile fallback).
6. Resolve model_id via `default_model_id_for_engine` if absent.
7. `ensure_model_loaded(state, engine, model_id, None)` — `None` means don't enforce sequential-GPU mode (Settings owns that toggle).
@@ -104,7 +104,7 @@ Methods:
### `run_live_session` (`src-tauri/src/commands/live.rs:646`)
The blocking entry. Holds a `PowerAssertion::begin("magnotia live dictation session")` for the entire scope. Constructs and runs `LiveSessionRuntime`. The drop on the power assertion ends the macOS App Nap pin.
The blocking entry. Holds a `PowerAssertion::begin("lumotia live dictation session")` for the entire scope. Constructs and runs `LiveSessionRuntime`. The drop on the power assertion ends the macOS App Nap pin.
### `maybe_dispatch_chunk` (`src-tauri/src/commands/live.rs:753`)
@@ -172,7 +172,7 @@ frontend invoke('stop_live_transcription_session', { session_id })
- **Result-listener-lost path is critical.** Without it, closing the main window without a clean stop would leave the worker spinning forever, holding the GPU memory and the WAV file handle until process exit. The self-asserted stop flag is the safety net.
- **Power assertion only does work on macOS.** On Linux the function is a no-op (see [Power assertions and security](power-and-security.md)). A long live-dictation session on Linux can still be idled by the compositor.
- **The recent-segments history is bounded by time, not count.** A high chunk rate could grow it more than expected; the retention is `DUPLICATE_HISTORY_RETENTION_SECS = 8.0`.
- **Channel back-pressure.** The result channel is the JS-side `Channel<T>` queue. If the frontend stops reading, the queue grows. Magnotia's overload-signalling currently uses the in-buffer `MAX_PENDING_SAMPLES` cap; it does NOT detect a JS-side stalled listener except via the `emit_live_result`-failure path.
- **Channel back-pressure.** The result channel is the JS-side `Channel<T>` queue. If the frontend stops reading, the queue grows. Lumotia's overload-signalling currently uses the in-buffer `MAX_PENDING_SAMPLES` cap; it does NOT detect a JS-side stalled listener except via the `emit_live_result`-failure path.
- **`ensure_model_loaded(state, engine, model_id, None)`** intentionally passes `None` for `concurrent`, so live sessions never trigger the sequential-GPU guard in `commands::models`. If you ever ship a tight-VRAM machine and the user has switched to sequential mode, this could OOM. Today's hardware survey indicates this is uncommon; flag this when revisiting Phase A.4.
## See also

14
docs/architecture-map/02-tauri-runtime/commands/llm.md
View File

@@ -18,7 +18,7 @@ last_verified: 2026/05/09
- Tauri commands exposed (10 total):
- `recommend_llm_tier() -> Result<String, String>`. No window guard — pure hardware probe.
- `check_llm_model(state, model_id) -> Result<LlmModelStatusDto, String>`.
- `download_llm_model(window, app, model_id) -> Result<(), String>`. Main-window only. Emits `magnotia:llm-download-progress`.
- `download_llm_model(window, app, model_id) -> Result<(), String>`. Main-window only. Emits `lumotia:llm-download-progress`.
- `load_llm_model(window, state, model_id, use_gpu, concurrent) -> Result<(), String>`. Main-window only.
- `unload_llm_model(window, state) -> Result<(), String>`. Main-window only.
- `delete_llm_model(window, state, model_id) -> Result<(), String>`. Main-window only.
@@ -26,8 +26,8 @@ last_verified: 2026/05/09
- `test_llm_model(window, state, model_id) -> Result<LlmTestResult, String>`. Main-window only.
- `cleanup_transcript_text_cmd(window, state, transcript, profile_id, preset) -> Result<String, String>`. Main-window only.
- `extract_content_tags_cmd(state, transcript) -> Result<ContentTags, String>`.
- Events emitted: `magnotia:llm-download-progress` (`{ modelId, done, total, percent }`) — `src-tauri/src/commands/llm.rs:76`.
- Depends on: `magnotia_llm::{LlmEngine, LlmModelId, ContentTags, model_manager::{download_model, model_path, model_info, recommend_tier, is_downloaded, delete_model}}`, `magnotia_ai_formatting::{llm_cleanup_text, LlmPromptPreset}`, `magnotia_core::hardware`, `magnotia_storage::database::list_profile_terms`. Plus `commands::power::PowerAssertion`, `commands::security::ensure_main_window`.
- Events emitted: `lumotia:llm-download-progress` (`{ modelId, done, total, percent }`) — `src-tauri/src/commands/llm.rs:76`.
- Depends on: `lumotia_llm::{LlmEngine, LlmModelId, ContentTags, model_manager::{download_model, model_path, model_info, recommend_tier, is_downloaded, delete_model}}`, `lumotia_ai_formatting::{llm_cleanup_text, LlmPromptPreset}`, `lumotia_core::hardware`, `lumotia_storage::database::list_profile_terms`. Plus `commands::power::PowerAssertion`, `commands::security::ensure_main_window`.
- Called from frontend at: Settings → AI page (download / load / unload / delete / test), dictation result panel (`cleanup_transcript_text_cmd`), History page (`extract_content_tags_cmd`).
## What's in here
@@ -42,7 +42,7 @@ Wraps `model_id.parse()` (which goes through the `LlmModelId` parser).
### `recommend_llm_tier` (`:28`)
Probes RAM via `magnotia_core::hardware::probe_system`, multiplies the MB to bytes, then defers to `magnotia_llm::model_manager::recommend_tier(ram, vram)`. No window guard — Settings calls this at first paint to populate the default tier suggestion.
Probes RAM via `lumotia_core::hardware::probe_system`, multiplies the MB to bytes, then defers to `lumotia_llm::model_manager::recommend_tier(ram, vram)`. No window guard — Settings calls this at first paint to populate the default tier suggestion.
### `check_llm_model` (`:40`)
@@ -50,7 +50,7 @@ Combines `model_info(id)` (static metadata), `model_manager::is_downloaded(id)`,
### `download_llm_model` (`:61`)
`ensure_main_window`. Calls `model_manager::download_model(id, progress_cb)` with a closure that emits `magnotia:llm-download-progress` on each chunk. The percent calculation rounds against `total > 0` (avoids division by zero on a server that doesn't return a content-length).
`ensure_main_window`. Calls `model_manager::download_model(id, progress_cb)` with a closure that emits `lumotia:llm-download-progress` on each chunk. The percent calculation rounds against `total > 0` (avoids division by zero on a server that doesn't return a content-length).
### `load_llm_model` (`:90`)
@@ -75,7 +75,7 @@ Pure string classifier. Tested independently. Buckets: `load-failed-vram` (looks
### `cleanup_transcript_text_cmd` (`:362`)
`ensure_main_window`. Resolves `profile_id`. Fetches profile_terms from storage. Resolves the `preset` (Brief item B.1 #15: `Default`, `Email`, `Notes`, `Code`). `spawn_blocking` runs `llm_cleanup_text(&engine, &transcript, &profile_terms, resolved_preset)` inside a `PowerAssertion::begin("magnotia LLM cleanup")` so macOS App Nap doesn't throttle mid-token.
`ensure_main_window`. Resolves `profile_id`. Fetches profile_terms from storage. Resolves the `preset` (Brief item B.1 #15: `Default`, `Email`, `Notes`, `Code`). `spawn_blocking` runs `llm_cleanup_text(&engine, &transcript, &profile_terms, resolved_preset)` inside a `PowerAssertion::begin("lumotia LLM cleanup")` so macOS App Nap doesn't throttle mid-token.
### `extract_content_tags_cmd` (`:407`)
@@ -91,7 +91,7 @@ Eight `classify_llm_load_error` cases cover the four classification buckets and
Settings -> recommend_llm_tier() -> hardware probe -> tier string
Settings -> download_llm_model(model_id) -> model_manager::download_model
-> per-chunk progress events
-> file lands in ~/.magnotia/models/llm/
-> file lands in ~/.lumotia/models/llm/
Settings -> load_llm_model(model_id, use_gpu, concurrent)
-> if concurrent=false: unload whisper + parakeet
-> spawn_blocking(engine.load_model)

2
docs/architecture-map/02-tauri-runtime/commands/mod.md
View File

@@ -51,7 +51,7 @@ Six test cases cover each branch of the precedence rule plus whitespace handling
## Data flow
The helper is called *after* the calling command has read the relevant `ProfileRow` and `ProfileTermRow`s from `magnotia_storage`. The DB I/O lives in the calling command (so the tests in this file stay pure).
The helper is called *after* the calling command has read the relevant `ProfileRow` and `ProfileTermRow`s from `lumotia_storage`. The DB I/O lives in the calling command (so the tests in this file stay pure).
## Watch-outs

6
docs/architecture-map/02-tauri-runtime/commands/models.md
View File

@@ -20,7 +20,7 @@ last_verified: 2026/05/09
- Parakeet: `download_parakeet_model(name)`, `check_parakeet_model(name)`, `list_parakeet_models()`, `load_parakeet_model(name, concurrent)`, `check_parakeet_engine()`.
- Public Rust helpers (used by other command modules): `default_model_id_for_engine`, `ensure_model_loaded`, `prewarm_default_model`, `load_model_from_disk`, `detect_active_compute_device`, `emit_runtime_warnings`.
- Events emitted: `model-download-progress` (whisper), `parakeet-download-progress`, `runtime-warning` (tagged enum: `Avx2Missing`, `VulkanLoaderMissing`, future `CudaFallback`).
- Depends on: `magnotia_transcription::{model_manager, load_whisper, load_parakeet, LocalEngine, Transcriber}`, `magnotia_core::{model_registry, hardware, constants, types}`.
- Depends on: `lumotia_transcription::{model_manager, load_whisper, load_parakeet, LocalEngine, Transcriber}`, `lumotia_core::{model_registry, hardware, constants, types}`.
- Called from frontend at: Settings → Models page (download, load, status), the dictation page boot path (`prewarm_default_model_cmd`), Settings → About (runtime capabilities).
## What's in here
@@ -99,8 +99,8 @@ Five `compose_accelerators` permutations cover the RB-07 regression. Confirm:
- **The `concurrent` flag is a tri-state.** `None` and `Some(true)` keep the legacy parallel-residency behaviour. Only `Some(false)` triggers the unload-the-other-engine guard. Live transcription explicitly passes `None`. If you ever ship a 4 GB-VRAM Settings preset that flips `concurrent=false` by default, also test the live transcription path.
- **`parallel_mode_available` is hard-wired to `false` until Phase A.4 lands a real GPU VRAM probe** (`src-tauri/src/commands/models.rs:509`). Today's frontend reads this and disables the toggle. Flag for follow-up.
- **`prewarm_default_model` only runs whisper.** Parakeet has no warm-up. The Parakeet model is also smaller and loads faster, so the cold-start gap is less obvious. If you swap Magnotia's default to Parakeet, add an equivalent warm-up.
- **Vulkan loader detection is per-platform** (`magnotia_core::hardware::vulkan_loader_available`). The CPU-fallback `reason` strings are user-visible; keep them actionable (the Linux one names `libvulkan1`, the macOS one names the Vulkan SDK runtime).
- **`prewarm_default_model` only runs whisper.** Parakeet has no warm-up. The Parakeet model is also smaller and loads faster, so the cold-start gap is less obvious. If you swap Lumotia's default to Parakeet, add an equivalent warm-up.
- **Vulkan loader detection is per-platform** (`lumotia_core::hardware::vulkan_loader_available`). The CPU-fallback `reason` strings are user-visible; keep them actionable (the Linux one names `libvulkan1`, the macOS one names the Vulkan SDK runtime).
- **Whisper feature gating.** `--no-default-features` builds compile but `load_model_from_disk` returns a runtime error when the user requests a Whisper model. `list_models` will still show whisper models that happened to be downloaded already; consider hiding them when the feature is off if a no-whisper build ever ships to users.
- **Download progress events fire from a closure inside `model_manager::download`.** That closure is called from inside an async `spawn_blocking`-equivalent. The `let _ = app_clone.emit(...)` pattern silently drops emit errors; if a window has been closed mid-download the progress events stop landing but the download itself completes.

8
docs/architecture-map/02-tauri-runtime/commands/paste.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Paste
**Plain English summary.** Auto-insert-at-cursor: copy the transcript onto the clipboard and synthesise the platform's paste keystroke (Ctrl+V / Cmd+V) so the text lands in whatever app the user was already focused on. Adds a replace-with-raw flow that fires undo first. Skips the keystroke when the focused window is a terminal emulator (terminals duplicate the keystroke through the PTY). Hides the always-on-top preview overlay before the keystroke so a Wayland compositor doesn't accidentally route the paste back into Magnotia. Restores the user's prior clipboard 300 ms after the paste to honour the "never silently clobber the user's clipboard" contract.
**Plain English summary.** Auto-insert-at-cursor: copy the transcript onto the clipboard and synthesise the platform's paste keystroke (Ctrl+V / Cmd+V) so the text lands in whatever app the user was already focused on. Adds a replace-with-raw flow that fires undo first. Skips the keystroke when the focused window is a terminal emulator (terminals duplicate the keystroke through the PTY). Hides the always-on-top preview overlay before the keystroke so a Wayland compositor doesn't accidentally route the paste back into Lumotia. Restores the user's prior clipboard 300 ms after the paste to honour the "never silently clobber the user's clipboard" contract.
## At a glance
@@ -48,7 +48,7 @@ Step-by-step:
### `paste_text_replacing` (`src-tauri/src/commands/paste.rs:185`)
Same shape as `paste_text` but with an extra step: after copying and hiding the preview, fire `trigger_undo_keystroke()`, sleep 60 ms, then paste. The undo removes whatever text Magnotia already inserted (the cleaned-up transcript), the paste inserts the raw text. Used by the "replace with raw" frontend button per brief item #17.
Same shape as `paste_text` but with an extra step: after copying and hiding the preview, fire `trigger_undo_keystroke()`, sleep 60 ms, then paste. The undo removes whatever text Lumotia already inserted (the cleaned-up transcript), the paste inserts the raw text. Used by the "replace with raw" frontend button per brief item #17.
### `detect_paste_backends` (`src-tauri/src/commands/paste.rs:258`)
@@ -97,13 +97,13 @@ Replace flow inserts an `undo` keystroke and a 60 ms gap between hide and paste.
## Watch-outs
- **Focus must already be on the target window when the keystroke fires.** The global hotkey flow preserves this naturally; clicking Magnotia's own UI does not. The frontend Settings page surfaces the caveat next to the toggle.
- **Focus must already be on the target window when the keystroke fires.** The global hotkey flow preserves this naturally; clicking Lumotia's own UI does not. The frontend Settings page surfaces the caveat next to the toggle.
- **Wayland focused-window probe is intentionally absent.** No way to do this from an unprivileged Wayland client. Result: terminal detection on Wayland-Kitty users will miss; they fall back to the manual Ctrl+Shift+V they already use.
- **Clipboard restore is best-effort.** If the user copies something else within the 300 ms window, `should_restore` will (correctly) decline to write back. If a slow Wayland compositor delays the keystroke past 300 ms, we restore too early and the synthesised Ctrl+V pastes the user's old clipboard. Tradeoff documented in Handy #921.
- **Linux backend order is session-aware.** A user with `XDG_SESSION_TYPE=wayland` and only xdotool installed will fall through to xdotool with a warning; their X11-app focus on a Wayland session works fine but Wayland-native apps will not see the keystroke.
- **No backend = clipboard-only.** If `trigger_paste_keystroke` fails on Linux (no tools installed), the user still has the transcript on the clipboard; Settings shows the install-wtype hint via `detect_paste_backends`.
- **PowerShell process spawn cost on Windows.** Each paste spawns a fresh PowerShell. Acceptable for one-off paste invocations; if you ever build a streaming-paste mode, switch to native `SendInput` via the `windows` crate.
- **Permissions.** The macOS path requires the user to have granted Accessibility permissions to Magnotia (System Settings → Privacy → Accessibility). Without that, `osascript` returns success but the keystroke is silently dropped. There is no probe today; flag this in onboarding.
- **Permissions.** The macOS path requires the user to have granted Accessibility permissions to Lumotia (System Settings → Privacy → Accessibility). Without that, `osascript` returns success but the keystroke is silently dropped. There is no probe today; flag this in onboarding.
## See also

6
docs/architecture-map/02-tauri-runtime/commands/power-and-security.md
View File

@@ -55,9 +55,9 @@ macOS-only. Wraps `NSProcessInfo::processInfo().beginActivityWithOptions_reason(
### Where `PowerAssertion::begin` is called
- `commands::live::run_live_session` (`live.rs:660`) — `"magnotia live dictation session"`.
- `commands::llm::cleanup_transcript_text_cmd` (`llm.rs:394`) — `"magnotia LLM cleanup"`.
- `commands::llm::extract_content_tags_cmd` (`llm.rs:417`) — `"magnotia LLM content-tag extraction"`.
- `commands::live::run_live_session` (`live.rs:660`) — `"lumotia live dictation session"`.
- `commands::llm::cleanup_transcript_text_cmd` (`llm.rs:394`) — `"lumotia LLM cleanup"`.
- `commands::llm::extract_content_tags_cmd` (`llm.rs:417`) — `"lumotia LLM content-tag extraction"`.
NOT called from `commands::tasks::decompose_and_store` or `commands::tasks::extract_tasks_from_transcript_cmd`, even though both run multi-second LLM inference. Flag for follow-up.

4
docs/architecture-map/02-tauri-runtime/commands/profiles.md
View File

@@ -26,7 +26,7 @@ last_verified: 2026/05/09
- `learn_profile_terms_from_edit_cmd(state, profile_id, original_text, edited_text) -> Result<Vec<ProfileTermDto>, String>`.
- `delete_profile_term_cmd(state, id) -> Result<(), String>`.
- Events emitted: none.
- Depends on: `magnotia_storage::{create_profile, update_profile, delete_profile, list_profiles, get_profile, add_profile_term, list_profile_terms, delete_profile_term, ProfileRow, ProfileTermRow}`, `magnotia_ai_formatting::extract_corrections`.
- Depends on: `lumotia_storage::{create_profile, update_profile, delete_profile, list_profiles, get_profile, add_profile_term, list_profile_terms, delete_profile_term, ProfileRow, ProfileTermRow}`, `lumotia_ai_formatting::extract_corrections`.
- Called from frontend at: Settings → Profiles (full CRUD), profile picker, History viewer (the auto-learn flow runs after the user saves an edit).
## What's in here
@@ -47,7 +47,7 @@ Constant so the auto-learn rows are uniformly tagged.
### `learn_profile_terms_from_edit_cmd` (`:151`)
1. Pull the existing terms (so the diff doesn't propose duplicates).
2. Call `magnotia_ai_formatting::extract_corrections(&original, &edited, &existing_terms)`.
2. Call `lumotia_ai_formatting::extract_corrections(&original, &edited, &existing_terms)`.
3. Persist each new term via `add_profile_term` with the `AUTO_LEARNED_NOTE`.
4. Return the freshly-inserted DTOs.

10
docs/architecture-map/02-tauri-runtime/commands/small-commands.md
View File

@@ -47,11 +47,11 @@ Frontend-facing structs. `SystemInfo` carries `ram_mb`, `cpu_brand`, `cpu_cores`
### `probe_system() -> Result<SystemInfo, String>` (`src-tauri/src/commands/hardware.rs:29`)
Wraps `magnotia_core::hardware::probe_system`. Maps the OS enum to a string and the GPU vendor (if probed) to its `Debug` form.
Wraps `lumotia_core::hardware::probe_system`. Maps the OS enum to a string and the GPU vendor (if probed) to its `Debug` form.
### `rank_models() -> Result<Vec<ModelRecommendation>, String>` (`src-tauri/src/commands/hardware.rs:49`)
Calls `magnotia_core::recommendation::rank_recommendations` and decorates each entry with `magnotia_transcription::is_downloaded`. Used by Settings → Models for the "recommended for your hardware" list.
Calls `lumotia_core::recommendation::rank_recommendations` and decorates each entry with `lumotia_transcription::is_downloaded`. Used by Settings → Models for the "recommended for your hardware" list.
Both commands are unguarded (any window can call). Pure read-only probes.
@@ -65,7 +65,7 @@ Tauri-managed: `lister: Mutex<ProcessLister>`. Holds a long-lived `ProcessLister
Phase 8 meeting auto-capture (single-signal variant). Frontend polls this on an interval with the user's app patterns. On a positive hit, the frontend surfaces a non-modal toast that reminds the user to start recording with their hotkey. We do NOT start recording from this signal — the user decides.
If `patterns` is empty, returns an empty Vec without locking. Otherwise locks the `lister`, snapshots the process list, and runs `magnotia_core::process_watch::match_meeting_patterns` to filter. Returns the matched process names.
If `patterns` is empty, returns an empty Vec without locking. Otherwise locks the `lister`, snapshots the process list, and runs `lumotia_core::process_watch::match_meeting_patterns` to filter. Returns the matched process names.
Watch-out: the `ProcessLister` lock is `std::sync::Mutex`. If the snapshot ever takes meaningful time, switch to async.
@@ -77,7 +77,7 @@ Watch-out: the `ProcessLister` lock is `std::sync::Mutex`. If the snapshot ever
### `deliver_nudge(app, window, input: DeliverNudgeInput) -> Result<(), String>` (`src-tauri/src/commands/nudges.rs:42`)
Phase 6. Main-window only via `ensure_main_window`. Trims title and body; if both are empty, return Ok silently (a blank nudge is worse than no nudge). Defaults the title to `"Magnotia"` if only the body is present. Calls `tauri_plugin_notification::NotificationExt::notification().builder().title(...).body(...).show()`.
Phase 6. Main-window only via `ensure_main_window`. Trims title and body; if both are empty, return Ok silently (a blank nudge is worse than no nudge). Defaults the title to `"Lumotia"` if only the body is present. Calls `tauri_plugin_notification::NotificationExt::notification().builder().title(...).body(...).show()`.
The frontend nudge bus (`nudgeBus.svelte.ts`) owns cadence, suppression, and the hourly cap. This command is a blunt "push it now" primitive — no rate limiting at the Rust layer. Errors propagate verbatim so the bus can log + swallow.
@@ -85,7 +85,7 @@ The frontend nudge bus (`nudgeBus.svelte.ts`) owns cadence, suppression, and the
### Morning-triage sentinel
Frontend owns rendering and logic; this module only persists the "last date the morning triage modal was shown" sentinel under SQLite settings key `magnotia_morning_triage_last_shown`.
Frontend owns rendering and logic; this module only persists the "last date the morning triage modal was shown" sentinel under SQLite settings key `lumotia_morning_triage_last_shown`.
- `get_last_morning_triage(state) -> Result<Option<String>, String>` (`src-tauri/src/commands/rituals.rs:23`).
- `mark_morning_triage_shown(state, date: String) -> Result<(), String>` (`src-tauri/src/commands/rituals.rs:36`). Caller passes a YYYY-MM-DD string in the user's local timezone — Rust deliberately stays timezone-agnostic.

6
docs/architecture-map/02-tauri-runtime/commands/tasks.md
View File

@@ -9,7 +9,7 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Tasks
**Plain English summary.** Eleven commands wrapping the `magnotia_storage` task CRUD plus two LLM-driven actions. Standard CRUD: create / list / update / complete / uncomplete / delete a task, plus subtask CRUD (insert / list / complete) and a daily-completion-counts query for the Phase 8 Tasks-page momentum sparkline. The two LLM actions: `decompose_and_store` (break a parent task into subtasks via the local LLM with HITL feedback as few-shot exemplars) and `extract_tasks_from_transcript_cmd` (extract task lines from a recently-finished transcript, again with feedback exemplars).
**Plain English summary.** Eleven commands wrapping the `lumotia_storage` task CRUD plus two LLM-driven actions. Standard CRUD: create / list / update / complete / uncomplete / delete a task, plus subtask CRUD (insert / list / complete) and a daily-completion-counts query for the Phase 8 Tasks-page momentum sparkline. The two LLM actions: `decompose_and_store` (break a parent task into subtasks via the local LLM with HITL feedback as few-shot exemplars) and `extract_tasks_from_transcript_cmd` (extract task lines from a recently-finished transcript, again with feedback exemplars).
## At a glance
@@ -29,7 +29,7 @@ last_verified: 2026/05/09
- `complete_subtask_cmd(state, subtask_id) -> Result<(), String>`.
- `list_recent_completions_cmd(state, days) -> Result<Vec<DailyCompletionCount>, String>`.
- Events emitted: none.
- Depends on: `magnotia_storage::{insert_task, list_tasks, update_task, complete_task, uncomplete_task, delete_task, set_task_energy, get_task_by_id, insert_subtask, list_subtasks, complete_subtask_and_check_parent, list_recent_completions, list_feedback_examples, FeedbackTargetType, TaskRow, DailyCompletionCount, FeedbackRow}`, `magnotia_llm::prompts::FeedbackExample`, `uuid::Uuid`.
- Depends on: `lumotia_storage::{insert_task, list_tasks, update_task, complete_task, uncomplete_task, delete_task, set_task_energy, get_task_by_id, insert_subtask, list_subtasks, complete_subtask_and_check_parent, list_recent_completions, list_feedback_examples, FeedbackTargetType, TaskRow, DailyCompletionCount, FeedbackRow}`, `lumotia_llm::prompts::FeedbackExample`, `uuid::Uuid`.
- Called from frontend at: Tasks page (CRUD, subtasks, sparkline), dictation result panel ("Extract tasks" button), parent-task expand UI ("Decompose").
## What's in here
@@ -106,7 +106,7 @@ Dictation panel Extract tasks -> extract_tasks_from_transcript_cmd(text, profile
## Watch-outs
- **No `ensure_main_window` guard.** Tasks UI lives in the main window AND in the always-on-top task float (which has the secondary-windows capability). The float can call list / complete / set-energy / list-recent-completions etc. — that's intentional — but it can also fire `decompose_and_store` and `extract_tasks_from_transcript_cmd`, which spend LLM tokens. If you want to lock this down, add the guard to the LLM-spending commands.
- **No `PowerAssertion`.** `decompose_and_store` and `extract_tasks_from_transcript_cmd` both run synchronous LLM inference for several seconds. macOS can App Nap them. Add `PowerAssertion::begin("magnotia LLM task decomposition")` and similar.
- **No `PowerAssertion`.** `decompose_and_store` and `extract_tasks_from_transcript_cmd` both run synchronous LLM inference for several seconds. macOS can App Nap them. Add `PowerAssertion::begin("lumotia LLM task decomposition")` and similar.
- **The patch shape passes `Option<String>` for every column.** Currently the storage layer's `update_task` uses COALESCE: `Some` overwrites, `None` preserves. This means there's no way to clear `notes` or `effort` to empty via `update_task_cmd` — you can only set them to a non-empty string. If a user wants to clear a field, they'd need a fresh task or a dedicated clear command.
- **Decompose stores subtasks one-by-one in a loop** (`:329`). Each iteration is a separate DB transaction. Acceptable for typical 3–7-step decompositions; if a future LLM produces 50 steps, batch the inserts.
- **`extract_tasks_from_transcript_cmd` returns just `Vec<String>` and does NOT insert.** Frontend chooses what to insert. Confusing because the sibling `decompose_and_store` *does* insert. Convention is dictated by UX (decomposition is one-click, extraction reviews-then-inserts).

6
docs/architecture-map/02-tauri-runtime/commands/transcription.md
View File

@@ -20,7 +20,7 @@ last_verified: 2026/05/09
- `transcribe_file(window, state, path, engine: Option<String>, model_id: Option<String>, language, initial_prompt, remove_fillers, british_english, anti_hallucination, format_mode, profile_id) -> Result<serde_json::Value, String>` — main-window only. Decodes the file, picks engine (default whisper), returns the result inline.
- `transcribe_pcm_parakeet(window, state, app, samples, chunk_id, remove_fillers, british_english, anti_hallucination, format_mode, profile_id) -> Result<(), String>` — main-window only. Parakeet PCM. Emits `transcription-result`.
- Events emitted: `transcription-result` (payload: `{ status: "transcription", segments, language, duration, chunk_id, inference_ms, raw_text }`) — fires from `transcribe_pcm` (`src-tauri/src/commands/transcription.rs:208`) and `transcribe_pcm_parakeet` (`:398`).
- Depends on: `magnotia_audio::{decode_audio_file_limited, resample_to_16khz, probe_audio_duration_secs}`, `magnotia_core::types::{AudioSamples, Segment, Transcript, TranscriptionOptions}`, `magnotia_transcription::{LocalEngine, TimedTranscript}`, `magnotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`, `magnotia_storage::{database, DEFAULT_PROFILE_ID}`. Plus `commands::build_initial_prompt`, `commands::models::{default_model_id_for_engine, ensure_model_loaded}`, `commands::security::ensure_main_window`.
- Depends on: `lumotia_audio::{decode_audio_file_limited, resample_to_16khz, probe_audio_duration_secs}`, `lumotia_core::types::{AudioSamples, Segment, Transcript, TranscriptionOptions}`, `lumotia_transcription::{LocalEngine, TimedTranscript}`, `lumotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`, `lumotia_storage::{database, DEFAULT_PROFILE_ID}`. Plus `commands::build_initial_prompt`, `commands::models::{default_model_id_for_engine, ensure_model_loaded}`, `commands::security::ensure_main_window`.
- Called from frontend at: dictation page (PCM commands when not live), file-import flow (transcribe_file), Settings test page (file command for QA).
## What's in here
@@ -55,7 +55,7 @@ Whisper-specific PCM path (no chunking — frontend is expected to keep the buff
1. `ensure_main_window`.
2. Resolve `profile_id` (default `DEFAULT_PROFILE_ID`).
3. Fetch `ProfileRow` and profile term list from `magnotia_storage::database`.
3. Fetch `ProfileRow` and profile term list from `lumotia_storage::database`.
4. Build effective Whisper prompt via `build_initial_prompt(&caller_prompt, &profile.initial_prompt, &profile_terms)`.
5. `spawn_blocking` runs `engine.transcribe_sync` on the samples.
6. Run `post_process_segments` (filler removal, British English conversion, anti-hallucination, format mode, dictionary terms, optional LLM cleanup via `state.llm_engine`).
@@ -67,7 +67,7 @@ Whisper-specific PCM path (no chunking — frontend is expected to keep the buff
2. Resolve profile + terms (same as PCM path).
3. Default engine to `"whisper"`, default model id to `default_model_id_for_engine(&engine_name)`.
4. `ensure_model_loaded(state, engine, model_id, None)` — None = no sequential-GPU guard.
5. Probe audio duration via `magnotia_audio::probe_audio_duration_secs`. If > 2 hours, return a friendly error.
5. Probe audio duration via `lumotia_audio::probe_audio_duration_secs`. If > 2 hours, return a friendly error.
6. `spawn_blocking` decodes the file (`decode_audio_file_limited(path, Some(MAX_FILE_TRANSCRIPTION_SECS))`), resamples to 16 kHz mono, then runs `transcribe_samples_sync`.
7. Run `post_process_segments`.
8. Return a JSON value with `engine`, `modelId`, `segments`, `language`, `duration`, `inference_ms`, `raw_text`.

4
docs/architecture-map/02-tauri-runtime/commands/transcripts.md
View File

@@ -25,7 +25,7 @@ last_verified: 2026/05/09
- `delete_transcript(state, id) -> Result<(), String>`.
- `search_transcripts(state, query) -> Result<Vec<TranscriptDto>, String>` — FTS5; up to 50 best-rank.
- Events emitted: none.
- Depends on: `magnotia_storage::{insert_transcript, list_transcripts_paged, count_transcripts, get_transcript, update_transcript, update_transcript_meta, delete_transcript, search_transcripts, InsertTranscriptParams, TranscriptRow, DEFAULT_PROFILE_ID}`.
- Depends on: `lumotia_storage::{insert_transcript, list_transcripts_paged, count_transcripts, get_transcript, update_transcript, update_transcript_meta, delete_transcript, search_transcripts, InsertTranscriptParams, TranscriptRow, DEFAULT_PROFILE_ID}`.
- Called from frontend at: History page (list / search / get / update / delete), dictation result panel (`add_transcript`), Settings → About (`count_transcripts_command`), History viewer window (`update_transcript_meta_cmd` for star / template / language / llm_tags).
## What's in here
@@ -44,7 +44,7 @@ Patch shape for Task 2.5 / Phase 9 metadata: each field is `Option`. `None` pres
### Commands
- `add_transcript` (`:103`) builds an `InsertTranscriptParams` from the wide request and calls `magnotia_storage::insert_transcript`. The FTS5 index is updated automatically by an SQLite trigger inside the storage crate.
- `add_transcript` (`:103`) builds an `InsertTranscriptParams` from the wide request and calls `lumotia_storage::insert_transcript`. The FTS5 index is updated automatically by an SQLite trigger inside the storage crate.
- `list_transcripts` (`:135`) — paginated with sane defaults.
- `count_transcripts_command` (`:150`).
- `get_transcript` (`:157`).

4
docs/architecture-map/02-tauri-runtime/commands/tts.md
View File

@@ -85,8 +85,8 @@ frontend invoke('tts_stop')
- **Linux `spd-say` is non-blocking** — `tts_stop` cannot kill its synthesis once it has handed off to speech-dispatcher. The `stop_linux` extra call asks speech-dispatcher to flush its own queue, but that's a soft-stop, not a hard kill.
- **Windows path is heavy.** Every speak-call spawns a PowerShell. Acceptable for one-off use; for a streaming TTS pattern you'd want to keep a long-lived child or use the `windows` crate's SAPI bindings directly.
- **Voice id semantics differ per platform.** macOS uses the voice name; Linux uses an spd-say `-t` token; Windows uses the SAPI registered voice token. Frontend treats them as opaque strings, but a saved-voice in Settings will not survive a platform switch.
- **Brand consistency.** `Magnotia` is being renamed to `Lumenote` (per personal memory `project_lumenote_naming.md`). The TTS module currently embeds the string `"magnotia LLM cleanup"` and `"magnotia"`-prefixed temp filenames; rebrand sweep follow-up.
- **No power assertion.** Long read-aloud sessions on macOS could be idled by App Nap. Add `PowerAssertion::begin("magnotia TTS")` to `tts_speak` if longer transcripts ever become a primary use case.
- **Brand consistency.** `Lumotia` is being renamed to `Lumenote` (per personal memory `project_lumenote_naming.md`). The TTS module currently embeds the string `"lumotia LLM cleanup"` and `"lumotia"`-prefixed temp filenames; rebrand sweep follow-up.
- **No power assertion.** Long read-aloud sessions on macOS could be idled by App Nap. Add `PowerAssertion::begin("lumotia TTS")` to `tts_speak` if longer transcripts ever become a primary use case.
## See also

12
docs/architecture-map/02-tauri-runtime/system-tray.md
View File

@@ -17,9 +17,9 @@ last_verified: 2026/05/09
- LOC: 73.
- Compile gate: `#[cfg(not(target_os = "android"))]` — Android has no tray surface (declared at the `mod tray` line in `src-tauri/src/lib.rs:5`).
- Tauri commands exposed: none. The tray is set up imperatively from `lib.rs::run` setup hook.
- Events emitted: `magnotia:open-wind-down` (no payload) when the user clicks the wind-down menu item (`src-tauri/src/tray.rs:51`).
- Events emitted: `lumotia:open-wind-down` (no payload) when the user clicks the wind-down menu item (`src-tauri/src/tray.rs:51`).
- Depends on: `tauri::image::Image`, `tauri::menu::{MenuBuilder, MenuItemBuilder}`, `tauri::tray::TrayIconBuilder`, `tauri::{Emitter, Manager}`. No workspace crates.
- Called from frontend at: the frontend layout listens for `magnotia:open-wind-down` and routes to the wind-down page.
- Called from frontend at: the frontend layout listens for `lumotia:open-wind-down` and routes to the wind-down page.
## What's in here
@@ -31,22 +31,22 @@ Wires three handlers:
- `on_menu_event` (`src-tauri/src/tray.rs:37`):
- `show` → `window.show(); window.set_focus();`
- `wind-down` → show + focus + emit `magnotia:open-wind-down`.
- `wind-down` → show + focus + emit `lumotia:open-wind-down`.
- `quit` → `app.exit(0)`.
- All other ids fall through.
- `on_tray_icon_event` (`src-tauri/src/tray.rs:58`): a left-click brings the main window forward. Right-click is left to the platform default (which opens the menu).
The tray icon's tooltip is `"Magnotia — Ready"`. The status menu item has label `"Ready"` and is disabled (the `enabled(false)` builder call leaves it visible but unclickable).
The tray icon's tooltip is `"Lumotia — Ready"`. The status menu item has label `"Ready"` and is disabled (the `enabled(false)` builder call leaves it visible but unclickable).
## Data flow
Out only: clicks on the tray menu either hide/show the window directly or fire one event to the frontend (`magnotia:open-wind-down`). The tray does not read any state.
Out only: clicks on the tray menu either hide/show the window directly or fire one event to the frontend (`lumotia:open-wind-down`). The tray does not read any state.
## Watch-outs
- The status menu item is hard-coded "Ready". There is no wiring to update it dynamically as the engine moves between idle / loading / recording. If you want a live status, you'll need to retain a `TrayIcon` handle in `AppState` (or somewhere similar) so a command can call `set_tooltip` / update the menu item text.
- The icon comes from `app.default_window_icon()` which is the packaged bundle icon (set in `tauri.conf.json` `bundle.icon`). Replacing the tray icon means re-running `tauri icon` or shipping a separate tray PNG.
- The `magnotia:open-wind-down` event payload is `()` — the frontend just needs to know "navigate to the wind-down page", and the page itself decides whether to render the ritual or a "you have not enabled this yet" stub.
- The `lumotia:open-wind-down` event payload is `()` — the frontend just needs to know "navigate to the wind-down page", and the page itself decides whether to render the ritual or a "you have not enabled this yet" stub.
- Close-to-tray (intercepting `WindowEvent::CloseRequested`) lives in `lib.rs::run` setup hook (`src-tauri/src/lib.rs:282`), not here. The two halves are split because the close-to-tray handler needs the cloned `WebviewWindow`.
## See also

8
docs/architecture-map/02-tauri-runtime/tauri-config.md
View File

@@ -14,7 +14,7 @@ last_verified: 2026/05/09
## At a glance
- Paths: `src-tauri/tauri.conf.json` (43 LOC), `src-tauri/tauri.linux.conf.json` (17 LOC).
- Identifier: `uk.co.corbel.magnotia`.
- Identifier: `uk.co.corbel.lumotia`.
- Tauri version targeted: schema `https://schema.tauri.app/config/2`.
- Main window labels: `main` (defined here), plus `tasks-float`, `transcript-viewer`, `transcription-preview` (built imperatively from `commands::windows`).
- Frontend: `npm run dev:frontend` for dev (port 1420), `npm run build` produces `../build` for release.
@@ -28,9 +28,9 @@ last_verified: 2026/05/09
### `tauri.conf.json`
```
productName: "Magnotia"
productName: "Lumotia"
version: "0.1.0"
identifier: "uk.co.corbel.magnotia"
identifier: "uk.co.corbel.lumotia"
```
#### `build`
@@ -44,7 +44,7 @@ frontendDist: "../build"
#### `app.windows[0]`
The main window. Title `"Magnotia"`, 1020×720 (min 960×600), centred, resizable, **frameless** (`decorations: false`). The Linux overlay flips this to `decorations: true`.
The main window. Title `"Lumotia"`, 1020×720 (min 960×600), centred, resizable, **frameless** (`decorations: false`). The Linux overlay flips this to `decorations: true`.
#### `app.security.csp`

32
docs/architecture-map/03-audio-transcription/README.md
View File

@@ -9,19 +9,19 @@ last_verified: 2026/05/09
> **Where you are:** [Architecture map](../README.md) → Audio + Transcription
**Plain English summary.** Two Rust workspace crates form the backbone of Magnotia's speech-to-text path. `magnotia-audio` captures microphone input via `cpal`, decodes audio files via `symphonia`, resamples to 16 kHz mono via `rubato`, and writes WAV files via `hound`. `magnotia-transcription` loads Whisper or Parakeet models, runs inference, and provides streaming primitives (VAD chunking, LocalAgreement-n commit policy, commit-bounded buffer trim) so live captures stay responsive.
**Plain English summary.** Two Rust workspace crates form the backbone of Lumotia's speech-to-text path. `lumotia-audio` captures microphone input via `cpal`, decodes audio files via `symphonia`, resamples to 16 kHz mono via `rubato`, and writes WAV files via `hound`. `lumotia-transcription` loads Whisper or Parakeet models, runs inference, and provides streaming primitives (VAD chunking, LocalAgreement-n commit policy, commit-bounded buffer trim) so live captures stay responsive.
## At a glance
| Crate | LOC (`src/`) | Purpose |
|---|---|---|
| `magnotia-audio` | 1,533 | Capture, VAD stub, resample, decode, WAV I/O |
| `magnotia-transcription` | 2,266 (incl. tests + build) | Engines, model manager, streaming primitives |
| `lumotia-audio` | 1,533 | Capture, VAD stub, resample, decode, WAV I/O |
| `lumotia-transcription` | 2,266 (incl. tests + build) | Engines, model manager, streaming primitives |
Public crate surface (re-exports from `lib.rs`):
```rust
// magnotia-audio
// lumotia-audio
pub use capture::{AudioChunk, CaptureRuntimeError, DeviceInfo, MicrophoneCapture};
pub use concurrency::decode_and_resample;
pub use decode::{decode_audio_file, decode_audio_file_limited, probe_audio_duration_secs};
@@ -30,7 +30,7 @@ pub use streaming_resample::StreamingResampler;
pub use vad::SpeechDetector;
pub use wav::{read_wav, write_wav, WavWriter};
// magnotia-transcription
// lumotia-transcription
pub use concurrency::run_inference;
#[cfg(feature = "whisper")]
pub use local_engine::load_whisper;
@@ -57,7 +57,7 @@ External deps that matter:
- `tracing 0.1` — backend boundary observability.
- `voice_activity_detector` / `silero-vad-rust` — **deferred** (ort 2.0.0-rc.10 vs 2.0.0-rc.12 conflict; see `audio-vad.md`).
Cargo feature matrix (`magnotia-transcription`):
Cargo feature matrix (`lumotia-transcription`):
| Feature | Default | Gates |
|---|---|---|
@@ -65,7 +65,7 @@ Cargo feature matrix (`magnotia-transcription`):
| `whisper-vulkan` | yes | `whisper-rs/vulkan` (Vulkan GPU offload) |
| Parakeet (`transcribe-rs`) | always on | unconditional dep, no feature flag |
`magnotia-audio` has no Cargo features.
`lumotia-audio` has no Cargo features.
## Map of this slice
@@ -79,7 +79,7 @@ Cargo feature matrix (`magnotia-transcription`):
- [`transcription-whisper.md`](transcription-whisper.md) — `WhisperRsBackend`, `WhisperContext`, params, `initial_prompt`, GPU offload.
- [`transcription-parakeet.md`](transcription-parakeet.md) — `SpeechModelAdapter` + `ParakeetWordGranularity`.
- [`transcription-streaming.md`](transcription-streaming.md) — `VadChunker` trait, `RmsVadChunker`, `LocalAgreement`, `trim_buffer_to_commit_point`.
- [`transcription-model-manager.md`](transcription-model-manager.md) — download flow, SHA verify, `.magnotia-verified` manifest, Range resume.
- [`transcription-model-manager.md`](transcription-model-manager.md) — download flow, SHA verify, `.lumotia-verified` manifest, Range resume.
- [`transcription-concurrency.md`](transcription-concurrency.md) — `run_inference` async wrapper around `spawn_blocking`.
- [`cargo-features.md`](cargo-features.md) — feature matrix, build commands, rationale.
- [`build-tokenizers-guard.md`](build-tokenizers-guard.md) — `build.rs` Windows-MSVC-CRT guard against `tokenizers`.
@@ -90,13 +90,13 @@ Cargo feature matrix (`magnotia-transcription`):
- **Slice 2 (Tauri runtime)** owns `src-tauri/src/commands/{audio,transcription,live,models}.rs`. Those wrappers call into this slice via the `pub use` exports above. The live command in particular drives `MicrophoneCapture` + `StreamingResampler` + `RmsVadChunker` + `LocalAgreement` + `WavWriter` together. This crate publishes the primitives; slice 2 publishes the orchestrator.
- **Slice 4 (LLM + AI formatting)** runs after this slice produces a `Transcript`. It consumes the segment text via the storage layer, never directly. No type traffic flows back into this slice from formatting.
- **Slice 5 (core / storage / hotkey / build)** provides the shared types this slice depends on:
- `magnotia_core::error::{MagnotiaError, Result}` — error envelope.
- `magnotia_core::types::{AudioSamples, Segment, Transcript, TranscriptionOptions, EngineName, ModelId, DownloadProgress, Megabytes}`.
- `magnotia_core::constants::{WHISPER_SAMPLE_RATE, VAD_SPEECH_THRESHOLD}`.
- `magnotia_core::hardware::vulkan_loader_available` — runtime Vulkan probe used by `WhisperRsBackend`.
- `magnotia_core::tuning::{inference_thread_count, Workload}` — power-aware thread count picker.
- `magnotia_core::paths::app_paths` — `models_dir()` / `speech_model_dir()` resolution.
- `magnotia_core::model_registry::{find_model, all_models, ModelEntry, ModelFile}` — declarative model catalogue.
- `lumotia_core::error::{MagnotiaError, Result}` — error envelope.
- `lumotia_core::types::{AudioSamples, Segment, Transcript, TranscriptionOptions, EngineName, ModelId, DownloadProgress, Megabytes}`.
- `lumotia_core::constants::{WHISPER_SAMPLE_RATE, VAD_SPEECH_THRESHOLD}`.
- `lumotia_core::hardware::vulkan_loader_available` — runtime Vulkan probe used by `WhisperRsBackend`.
- `lumotia_core::tuning::{inference_thread_count, Workload}` — power-aware thread count picker.
- `lumotia_core::paths::app_paths` — `models_dir()` / `speech_model_dir()` resolution.
- `lumotia_core::model_registry::{find_model, all_models, ModelEntry, ModelFile}` — declarative model catalogue.
- Storage (slice 5) writes the produced `Transcript` to disk; this slice does not call into it directly.
## Open questions / debt
@@ -116,7 +116,7 @@ Cargo feature matrix (`magnotia-transcription`):
- `docs/whisper-ecosystem/brief.md` — top-level Whisper-ecosystem audit (the items #6, #8, #13, #19, #21, #24, #25, #26 referenced throughout this slice).
- `docs/whisper-ecosystem/workstream-A.md` — VAD / streaming roadmap (the source of `RmsVadChunker` thresholds).
- `docs/whisper-ecosystem/workstream-B.md` — UI commit/tentative contract that drives `LocalAgreement`.
- `docs/whisper-ecosystem/magnotia-context.md` — context summary for the workstreams.
- `docs/whisper-ecosystem/lumotia-context.md` — context summary for the workstreams.
- `docs/code-review-2026-04-22.md` — audit pass that flagged decode.rs RB-09 and `read_wav` filter_map bug (both fixed in tree).
- `docs/issues/decoder-partial-audio-on-error.md` — the RB-09 ticket.
- `docs/issues/native-capture-worker-join.md`, `c1-live-session-race.md`, `run-live-session-monolith.md` — slice 2's live-session debt; they reference primitives in this slice.

Some files were not shown because too many files have changed in this diff Show More