Lumotia/docs/architecture-map/05-core-storage-hotkey-build/storage-crud-profiles.md

name, type, slice, last_verified

name	type	slice	last_verified
Storage profiles and profile_terms CRUD	architecture-map-page	05-core-storage-hotkey-build	2026/05/09

Storage profiles and profile_terms CRUD

Where you are: Architecture map → Core, Storage, Hotkey, Build → Storage profiles CRUD

Plain English summary. Profiles are user-defined contexts (Work, Personal, Game). Each profile has its own initial prompt and a list of custom dictionary terms. The default profile (00000000-0000-0000-0000-000000000001) is seeded by migration v6 and protected by SQL triggers from rename or delete.

At a glance

• Source: crates/storage/src/database.rs:776-1124.
• Public surface: list_profiles, get_profile, create_profile, update_profile, delete_profile, list_profile_terms, add_profile_term, delete_profile_term.
• Public types: ProfileRow, ProfileTermRow.
• Public constant: magnotia_storage::DEFAULT_PROFILE_ID = "00000000-0000-0000-0000-000000000001" at crates/storage/src/lib.rs:7.
• Consumers: slice 2 profiles command, transcript inserts (every transcript carries a profile_id), the LLM prompt builder (slice 4) reads the profile's initial_prompt and profile_terms to condition cleanup.

Public types

ProfileRow — crates/storage/src/database.rs:776

pub struct ProfileRow {
    pub id: String,
    pub name: String,
    pub initial_prompt: String,
    pub created_at: String,
}

ProfileTermRow — crates/storage/src/database.rs:784

pub struct ProfileTermRow {
    pub id: String,
    pub profile_id: String,
    pub term: String,
    pub note: String,
    pub created_at: String,
}

Functions

list_profiles(pool) -> Result<Vec<ProfileRow>> — crates/storage/src/database.rs:950

SELECT ... FROM profiles ORDER BY created_at ASC. Default profile is always first by virtue of being the earliest-created.

get_profile(pool, id) -> Result<Option<ProfileRow>> — crates/storage/src/database.rs:959

Single-row select.

create_profile(pool, id, name, initial_prompt) -> Result<ProfileRow> — crates/storage/src/database.rs:968

UUID is generated by the caller. name has a UNIQUE constraint at the column level (migration v6); a duplicate name returns a friendly MagnotiaError::StorageError("Profile name already exists: ...").

update_profile(pool, id, name, initial_prompt) — crates/storage/src/database.rs:995

Renames the profile and / or rewrites the initial prompt. Updating the default profile's name raises MagnotiaError::StorageError because the trg_protect_default_profile_rename trigger (migration v6) calls RAISE(ABORT, 'cannot rename the default profile') on any UPDATE OF id, name where OLD.id = DEFAULT_PROFILE_ID. Updating only initial_prompt is allowed.

delete_profile(pool, id) -> Result<()> — crates/storage/src/database.rs:1024

Two guards before the DELETE:

1. Application-layer guard: if the profile owns any transcripts, refuse with a friendly error pointing the user at re-assignment. Implemented via transcript_count_for_profile (database.rs:1103).
2. Database-layer guard: trg_protect_default_profile_delete raises RAISE(ABORT, 'cannot delete the default profile') when the id matches.

The cascade on profile_terms.profile_id removes the profile's custom terms automatically.

list_profile_terms(pool, profile_id) -> Result<Vec<ProfileTermRow>> — crates/storage/src/database.rs:1044

SELECT ... FROM profile_terms WHERE profile_id = ? ORDER BY term ASC. Used by the LLM prompt builder.

add_profile_term(pool, profile_id, term, note) -> Result<String> — crates/storage/src/database.rs:1062

Generates a UUID v4 (per crates/storage/Cargo.toml's features = ["v4"]), inserts the row, returns the new id. The Cargo.toml comment claims "v7 random" but the feature flag is v4. Practical effect is identical for our purposes (random unique ids); the comment is the inconsistency to clean up if anyone touches that line.

delete_profile_term(pool, id) -> Result<()> — crates/storage/src/database.rs:1085

DELETE FROM profile_terms WHERE id = ?.

Data flow / contract

• Every transcript references a profile via transcripts.profile_id (FK installed in migration v9). insert_transcript validates the FK at the application layer for a friendlier error.
• The LLM prompt builder loads the active profile's initial_prompt and the matching profile_terms at cleanup time.
• The default profile's id is a pub const &str so frontend code via Tauri commands can also reference it as a known constant (it is stamped into the JSON bridge by the Tauri preferences command).

Watch-outs

• Default profile protection is enforced by triggers, not by code. A future migration that drops or renames the trigger silently removes the protection. There is no head-schema test that asserts the triggers are still present; today only the v6 migration tests assert protection at DML time. Consider adding a head-schema integration test that explicitly attempts to delete the default profile and asserts the failure.
• Profile name UNIQUE-ness is case-sensitive. "Work" and "work" are two different profiles. Worth a discussion about whether case-insensitive uniqueness is the right behaviour; today it is not enforced.
• transcript_count_for_profile is the only application-layer FK guard. Tasks reference no profile (the table predates the profile concept). If task-to-profile FKs land later, delete_profile needs a parallel check.
• No update_profile_term. A user fixing a typo in a term's note has to delete and re-add. Worth adding if the volume of profile terms grows.

Tests

Migration tests cover the v6 trigger protection at crates/storage/src/migrations.rs:977-1015 (migration_v6_trigger_rejects_default_profile_delete, migration_v6_trigger_rejects_default_profile_rename). The CRUD functions themselves do not have dedicated unit tests in database.rs; coverage is via the slice-2 integration tests.

See also

• Schema and migrations (v6, v7, v9)
• Storage overview
• Slice 4 LLM prompt builder — consumer of list_profile_terms.