RunOnce drains the queue for the given generation until empty, releasing claimed rows on embed or upsert error so another worker can retry them. Retur

UpsertMessageBody stores the body text and HTML for a message in the separate message_bodies table.

newWorkerFixture creates a main DB with n messages (subject="msg N", body="body N"), opens a real sqlitevec backend, creates a building generation (se

participantNameExpr returns the SQL expression for a participant's display label, falling back through display_name → phone_number → email_address. Us

EnsureParticipant gets or creates a participant by email. Atomic via INSERT … ON CONFLICT … RETURNING id so two goroutines (or two processes against P

Load reads the configuration from the specified file. If path is empty, uses the default location (~/.msgvault/config.toml), which is optional (missin

testMIME returns a simple plain-text MIME message for testing. Returns a fresh byte slice on each call to prevent cross-test mutation.

AddFrom is shorthand for AddRecipient with type "from".

Claim marks up to batch pending rows for gen as claimed by a fresh token, returning the message IDs in ascending order alongside the token to present

padRight pads a string with spaces to fill width terminal cells. Uses lipgloss.Width to correctly handle ANSI codes and full-width characters.

runToolExpectError invokes a handler and asserts it returns an error result.

EnsureLabel gets or creates a label, handling renames and ID changes. For batch operations prefer EnsureLabelsBatch which runs in a single transaction

Create inserts the message into the store and returns its internal ID.

makeDate creates a time.Time for the given month, day in 2024, UTC, zero time.

EnsureConversationParticipant adds a participant to a conversation. Uses INSERT OR IGNORE to be idempotent.

EnsureParticipantByPhone gets or creates a participant by phone number. Phone must start with "+" (E.164 format). Returns an error for empty or invali

NewMessage creates a builder using the fixture's per-test counter for deterministic SourceMessageID values (fixture-msg-1, fixture-msg-2, ...). Uses a

NewQueue returns a Queue bound to db. The caller retains ownership of db; Queue does not close it. rebind translates ?-placeholders to the driver's na

NewServer creates a new API server.

SubAggregate performs aggregation on a filtered subset of messages. This is used for sub-grouping after drill-down, e.g., drilling into "Sender: foo@e

----------------------------------------------------------------------------- Data Factories - create test data with minimal boilerplate -------------

msgIDs generates sequential message IDs like "msg0", "msg1", ..., "msg(n-1)".

sendKey sends a key message to the model and returns the updated concrete Model.

New creates a new Scheduler with the given sync callback.

Complete deletes the claimed rows from the queue. Only rows whose claim_token matches token are removed; any row that was reclaimed or re-claimed unde

FTS5Available returns whether FTS5 full-text search is available.

To sets the To header.

ensureCursorVisible adjusts scroll offset to keep cursor in view. pushBreadcrumb saves the current view state to the navigation history. navigateList

IsPostgreSQL reports whether this store is backed by PostgreSQL. Engine factories use this to choose between the SQLite and PostgreSQL query paths.

applyMessageListKey sends a key through handleMessageListKeys and returns the concrete Model.

newTestServerWithEngine creates a test server with both mock store and mock engine.

MustListMessages calls ListMessages and fails the test on error.

TokensDir returns the path to the OAuth tokens directory.

FailSync marks a sync as failed with an error message.

NewEngine picks the appropriate engine for the given database. isPostgres selects between PostgreSQLQueryDialect (true) and SQLiteQueryDialect (false)

NewTestDataBuilder creates a new typed test data builder.

UpsertMessageRaw stores the compressed raw MIME data for a message.

countEmbeddingRows returns the number of embedding rows belonging to a generation. Used by the delete-on-retire tests to assert that a retired generat

newFusedBackendForTest opens a backend pointing at a main DB seeded with FTS content and the minimum schema FusedSearch needs.

EnsureUTF8 ensures a string is valid UTF-8. If already valid UTF-8, returns as-is. Otherwise attempts charset detection and conversion. Falls back to

GetGmailIDsByFilter returns Gmail message IDs (source_message_id) matching a filter. This is useful for batch operations like staging messages for del

addTable adds a table definition to be written as Parquet.

AddSource adds a source and returns its ID.

--- Assertion helpers --- AssertLabelCount asserts the number of labels attached to a message.

ConfigureSQLLogging sets the process-wide SQL logging behaviour. Call this after slog.SetDefault but before opening a Store.

UpdateSyncCheckpoint saves progress for resumption.

applyModalKey sends a key through handleModalKeys and returns the concrete Model and Cmd.

newIdentityCLITest creates an isolated store and test root command for identity subcommand tests. Returns (store, root, stdout buffer, stderr buffer)

runStartupMigrations pulls legacy identity addresses from the global config and runs the one-time migration. If migration was performed, the notice is

SanitizeTerminal strips ANSI escape sequences and C0/C1 control characters from a string, preventing terminal injection via untrusted data (e.g., What

Search - full-text search using FTS5 (includes message body)

writeJSON writes a JSON response.

AddMessageLabel associates a message with a label.

BuildEngine generates Parquet files and returns a DuckDBEngine. Cleanup is registered via t.Cleanup.

CopySubset copies rowCount most recent messages (and all referenced data) from srcDBPath into a new database in dstDir. The destination schema is init

128 MiB ImportEmlxDir imports .emlx files from an Apple Mail directory tree. Messages are deduplicated by content hash (sha256 of raw MIME). When the

NewClient constructs a Client, applying defaults for Timeout and MaxRetries.

DecodeMojibake reverses Facebook DYI JSON's well-known Latin-1-over-UTF-8 encoding. Facebook's JSON exporter writes UTF-8 bytes as if they were Latin-

ImportDYI imports a Facebook Messenger DYI export into the store.

LinkMessageLabel links a single label to a message. Uses INSERT OR IGNORE — safe to call multiple times.

NewDefaultConfig returns a configuration with default values.

NewEngine creates a new dedup engine.

NewEngine wires a backend, main DB handle, embedding client, and configuration into an Engine.

NewManager creates a deletion manager.

Open opens vectors.db, runs migrations, and retains the main database handle for seed queries. Caller must call Close.

SetHistory configures mock history records and the target history ID for incremental sync tests.

UpsertAttachment stores an attachment record. Idempotency for the common case is enforced by the partial unique index idx_attachments_msg_content_hash

emptyTargets creates an EmptyValueTargets map for testing with the given ViewType(s).

seedAndEmbed inserts any missing message rows into the main DB, creates a fresh generation sized to the first vector, and upserts all supplied vectors

visibleRows returns the number of data rows visible in the viewport. Views reserve one row for the info/notification line, so this is pageSize-1.

AddTo is shorthand for AddRecipient with type "to".

BuildFilter translates a parsed Gmail-syntax query into a vector.Filter by resolving address/label tokens to IDs against the main DB. Matches the sema

ChunkText splits text into windows of at most maxRunes runes each, overlapping by overlapRunes runes between consecutive windows. The goal is twofold:

Embed returns one vector per input, in input order. Empty input is a no-op and returns (nil, nil) without making an HTTP call. Every returned vector i

GetSourceByIdentifier returns a source by its identifier (email address).

ImportMbox imports a single MBOX file into the msgvault database. This is intended for services like HEY.com that provide an export in MBOX format bu

MatchesEmpty returns true if the given ViewType is in EmptyValueTargets.

RetireGeneration marks gen as retired, deleting its embeddings on backends that share an index graph (pgvector) and reaping its pending queue rows. Un

assertMessageCount checks the message count in the store.

dirForStatus returns the directory path for a given status. Uses explicit mapping to decouple Status values from directory names.