Jake
26c7307607
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>
102 lines
6.8 KiB
Markdown
102 lines
6.8 KiB
Markdown
---
|
|
name: Power assertions and security helpers
|
|
type: architecture-map-page
|
|
slice: 02-tauri-runtime
|
|
last_verified: 2026/05/09
|
|
---
|
|
|
|
# `commands::power` and `commands::security`
|
|
|
|
> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Power and security
|
|
|
|
**Plain English summary.** Two utility modules that the rest of the command files lean on. `power.rs` is the macOS App Nap power-assertion guard (no-op on Linux and Windows today). `security.rs` is `ensure_main_window`, the one-liner defence-in-depth check that several commands stamp at the top to reject calls from secondary windows even if the ACL ever drifted.
|
|
|
|
## At a glance
|
|
|
|
- Paths: `src-tauri/src/commands/power.rs` (208 LOC), `src-tauri/src/commands/security.rs` (30 LOC).
|
|
- Tauri commands exposed: none. Both are pure Rust utilities.
|
|
- Events emitted: none.
|
|
- Depends on:
|
|
- `power.rs`: macOS only — `objc2::rc::Retained`, `objc2::runtime::ProtocolObject`, `objc2_foundation::{NSActivityOptions, NSObjectProtocol, NSProcessInfo, NSString}`.
|
|
- `security.rs`: nothing.
|
|
- Called from: every long-running command that wants to keep the OS awake (live transcription, LLM cleanup, content-tag extraction, task decomposition); every command that wants the extra firewall (intentions CRUD, nudges, updater stub, lots of Settings-only commands).
|
|
|
|
## `commands::power`
|
|
|
|
### `PowerAssertionSnapshot` (`src-tauri/src/commands/power.rs:28`)
|
|
|
|
Cloneable snapshot for the diagnostics report: `id, reason, backend, acquired`.
|
|
|
|
### `PowerAssertion` (`src-tauri/src/commands/power.rs:41`)
|
|
|
|
A `#[must_use]` guard. Holding it keeps the macOS App Nap pin alive; dropping it ends the assertion. Fields: `id`, `reason`, `backend`, `acquired`, plus a macOS-only `Option<ActivityHandle>`.
|
|
|
|
### `PowerAssertion::begin(reason)` (`src-tauri/src/commands/power.rs:73`)
|
|
|
|
Allocates a new id from a `NEXT_ID: AtomicUsize`, calls into `objc_bridge::begin_activity` on macOS, registers a snapshot in the global `assertion_registry()`. Returns the guard. Errors are logged; failure to acquire still returns a "no-op" guard (so the caller's code path is unchanged) with `acquired = false`.
|
|
|
|
On non-macOS, this is a no-op. The doc comment promises Linux logind inhibitors and Windows `SetThreadExecutionState`, but neither is wired up. See debt note in the slice README.
|
|
|
|
### `Drop for PowerAssertion` (`src-tauri/src/commands/power.rs:124`)
|
|
|
|
End the macOS activity if present, remove the registry entry. Logs the end on macOS so the diagnostics bundle has a breadcrumb.
|
|
|
|
### `assertion_registry()` (`src-tauri/src/commands/power.rs:53`)
|
|
|
|
Process-global `Mutex<HashMap<usize, PowerAssertionSnapshot>>` using `OnceLock`. `active_assertions_snapshot()` (`:58`) returns a sorted vector of clones for the diagnostic-report bundler.
|
|
|
|
### `objc_bridge` module (`src-tauri/src/commands/power.rs:140`)
|
|
|
|
macOS-only. Wraps `NSProcessInfo::processInfo().beginActivityWithOptions_reason(options, reason)` and `endActivity(handle)`. Options: `NSActivityOptions::UserInitiated | NSActivityOptions::LatencyCritical`. The activity object is `Retained<ProtocolObject<dyn NSObjectProtocol>>` and is `unsafe impl Send` (the activity is a process-wide pin and thread-safe).
|
|
|
|
### Tests (`:168`)
|
|
|
|
`power_assertion_is_a_no_op_drop` confirms the registry entry is added on `begin` and removed on `drop`. `multiple_assertions_get_unique_ids` confirms the id allocator works.
|
|
|
|
### Where `PowerAssertion::begin` is called
|
|
|
|
- `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.
|
|
|
|
## `commands::security`
|
|
|
|
### `ensure_main_window(window)` (`src-tauri/src/commands/security.rs:1`)
|
|
|
|
One-liner: `ensure_main_window_label(window.label())`.
|
|
|
|
### `ensure_main_window_label(label)` (`src-tauri/src/commands/security.rs:5`)
|
|
|
|
Returns `Ok(())` when label is `"main"`, `Err("This command is only available from the main window (got <label>).")` otherwise.
|
|
|
|
### Tests (`:15`)
|
|
|
|
`accepts_main_window` and `rejects_secondary_windows` (the latter checks `tasks-float`, `transcript-viewer`, and `transcription-preview` are all rejected).
|
|
|
|
### Where `ensure_main_window` is called
|
|
|
|
Approximately 30 commands. The Settings flows (model loads, LLM lifecycle, hotkey wiring, intentions CRUD), most of the diagnostics report flows, the transcription / live commands, the windows-builder commands, the audio-capture commands, the prefs save, the updater stubs.
|
|
|
|
NOT called from: profiles, transcripts, tasks (most), feedback, hardware, meeting, fs, clipboard, hardware, tts, hotkey-status probe, llm-status probe, llm content-tag extraction, get_os_info. Each omission is intentional today (secondary windows need to call them) but document the choice when adding new commands.
|
|
|
|
## Data flow
|
|
|
|
Both modules are passive utilities. `PowerAssertion` is RAII: hold it for the duration of the work, drop it (explicitly or by leaving scope) to end the pin. `ensure_main_window` is a synchronous gate at the top of a command body.
|
|
|
|
## Watch-outs
|
|
|
|
- **`PowerAssertion` is a no-op on Linux and Windows.** Long sessions on those platforms can be idled. Document this in the user-facing Settings → AI page if you ship without a Linux logind / Windows `SetThreadExecutionState` implementation. The macOS objc2 binding requires `objc2 = "0.6.4"` and `objc2-foundation = "0.3.2"` — bumping them is an ABI move.
|
|
- **The registry is process-wide and locked behind a `Mutex`.** Acquiring or releasing an assertion takes the mutex. Acceptable for single-digit assertions per session; if you ever spam-create assertions, this will contend.
|
|
- **`ensure_main_window` rejects with a static message containing the offending label.** Include the label so debugging via the frontend toast is obvious; do not log the full window or any secret data.
|
|
- **The ACL plus `ensure_main_window` is two layers.** Removing the second layer is "defence-in-depth removal", which the in-repo code review (`docs/code-review-2026-04-22.md`) flags as a non-trivial security regression. Don't.
|
|
|
|
## See also
|
|
|
|
- [App lifecycle](../app-lifecycle.md) — the panic hook and runtime warnings live alongside power.
|
|
- [Diagnostics](diagnostics.md) — the report bundler reads `active_assertions_snapshot()`.
|
|
- [Capabilities and ACL](../capabilities-and-acl.md) — the ACL is the first layer; this is the second.
|
|
- [Live](live.md), [LLM](llm.md) — the main consumers of `PowerAssertion`.
|
|
- [Tests](../tests.md) — `accepts_main_window` and `rejects_secondary_windows` plus `power_assertion_is_a_no_op_drop`.
|