SanitizeFilename removes or replaces characters that are invalid in filenames.

SanitizeUTF8 replaces invalid UTF-8 bytes with replacement character.

ScheduledAccounts returns accounts with scheduling enabled.

Search performs a Gmail-style search query. Uses direct SQLite connection for FTS5 support when available, falls back to LIKE queries via sqlite_scan

SecureOpenFile opens the named file with specified flag and permissions.

SecureWriteFile writes data to the named file, creating it if necessary.

StoreAttachmentFile stores att.Content on disk under attachmentsDir using content-addressed storage (hash[:2]/hash). It validates existing files when

StripBase64Enabled returns the effective strip_base64 setting. Defaults to true when the field is unset — inline base64 blobs (images, embedded MIME p

StripHTMLEnabled returns the effective strip_html setting. Defaults to true when the field is unset — HTML markup that leaks into body_text tokenizes

StripQuotesEnabled returns the effective strip_quotes setting. Defaults to true when the field is unset.

StripSignaturesEnabled returns the effective strip_signatures setting. Defaults to true when the field is unset.

StripURLTrackingEnabled returns the effective strip_url_tracking setting. Defaults to true when the field is unset — utm_*, fbclid, etc. add no semant

UpdateImessageParticipantDisplayNameByPhone backfills display_name for an iMessage-imported participant, treating the legacy "display_name = phone_num

UpdateParticipantDisplayNameByEmail updates the display_name for an existing participant identified by email address. Only updates if display_name is

UpsertMessageRawWithFormat stores compressed raw data with an explicit format. Unlike UpsertMessageRaw (which hardcodes 'mime'), this accepts the form

ValidateContentHash validates that a content hash is a valid SHA-256 hex string. This prevents path traversal attacks by ensuring the hash contains on

assertAvailable checks the current available tokens.

assertThreadSourceID checks the source_conversation_id for a message's thread.

attachmentRowsForHash counts attachment rows carrying the given content hash. The hash argument is always hashShared in the current suite but kept exp

buildBenchData generates a 100K-message Parquet dataset directly via DuckDB SQL (no Go-side row generation). This produces realistic cardinality: 500

calculateScrollOffset computes the new scroll offset to keep cursor visible within pageSize.

computeThreadID computes the conversation thread ID for a set of participant phones. For 1:1 texts, uses the other party's normalized phone. For group

createAttachmentFixture creates a content-addressed file under dir using the given hash.

drillFilterKey returns the key value from the drillFilter based on drillViewType.

fakeEmbedServer is a tiny stub /v1/embeddings server that returns one zero-vector (with the leading element set to 1) per input at the test dimension.

findScheduledSyncSource resolves the source row for a scheduler identifier. Returns (nil, nil) when no syncable source matches — callers fall back to

getAccountID looks up a source ID by email address. Returns nil if account is empty (no filter), or an error if not found.

getTokenSourceWithReauth tries to get a token source for the given email. If the token exists but is expired/revoked (invalid_grant), it automatically

handleMessageListKeys handles keys in the message list view.

hasSelection returns true if any items are selected.

insertGenerationStatic inserts an index_generations row with the given state. id is used verbatim (not auto-increment).

isGroupChat returns true if the chat represents a group conversation. A chat is a group if group_type > 0 OR if the JID server is "g.us". Some groups

mkV10Mailbox creates a modern V10-style mailbox structure with <GUID>/Data/Messages/ layout.

newIdentifierMatch classifies raw via looksLikeEmail and packages the classification with the raw input. Empty input is permitted (it falls into the n

newVectorSearchTestEnv stands up the CLI prerequisites for a `msgvault search --mode=vector|hybrid` invocation: - a real msgvault.db with InitSchema

openTestStore creates a temporary store for internal tests.

peekTIDFromJWT does a minimal unverified decode of a JWT to extract the "tid" (tenant ID) claim. Used only to determine which OIDC provider URL to con

queryContext runs QueryContext with dialect-aware placeholder rebinding.

rawMIMEWithInlineImage is a convenience wrapper for the common inline case.

reconnect closes the current connection and re-establishes it. Only connection-level state is cleared; per-sync caches (messageListCache, msgIDToLabel

runStartupMigrationsForIngest is the pre-source-create hook for ingest commands. The only startup migration today is MigrateLegacyIdentityConfig, whic

seedMessageWithAttachment creates a source (if new), conversation, message, and attachment row for use in remove-account tests. Returns nothing; calle

seedMsg inserts a row in messages, optionally an attachment, and updates search_fts using the same 'simple' config the fused query uses on its side.

seedPending inserts a pending_embeddings row for (gen, msgID) directly, without going through the worker. The message row is created first to satisfy

tokenPath returns the path to the token file for an email. The email is sanitized to prevent path traversal attacks.

viewTypeAbbrev returns view type name for column headers and top-level breadcrumb.

Common argument helpers for recurring tool option definitions.

writeMultiThreadFixture lays out `n` inbox threads under a DYI root at tmp, each with a single short message. Threads are named "thread_{i}_OK" so tha

Acquire blocks until the required tokens are available. Returns an error if the context is cancelled.

AddMessage inserts a message with its from/to/cc recipients and returns the message ID.

Allow checks if a request from the given key should be allowed.

AssertManifestExecution verifies the persisted execution state of a manifest.

AssertNotCompleted verifies that OnComplete was not called.

BatchDeleteMessages permanently deletes multiple messages (max 1000).

BoolTrueExpr returns a SQL boolean expression that is true when col holds a "true" value. SQLite stores booleans as 0/1 INTEGER so we must emit "col =

BuildHandler constructs the slog handler configured according to Options. It: - creates the logs directory on demand, - rotates the daily file if it

DriverName returns the default sqlite3 driver name since sqlite-vec is not compiled in.

EffectiveTenantID returns the tenant ID, defaulting to "common" (multi-tenant, works for personal + org accounts).

EnsureSeeded guarantees that the building generation gen has had its initial pending_embeddings seed pass committed. If a prior CreateGeneration crash

EscapeTSQueryTerm tokenizes a single user-supplied search term into PostgreSQL `to_tsquery`-safe lexemes. The input is split on every rune that isn't

FirstLine returns the first line of a string, capped at 200 runes. Useful for extracting clean error messages from multi-line outputs where the first

GetRandomMessageIDs returns a random sample of message IDs for a source. Uses reservoir sampling with random offsets for O(limit) performance on large

GetSourceByID returns the source with the given ID, or ErrSourceNotFound (wrapped) if no row matches.

HasAnyActiveSync returns true if any source currently has a running sync. Use this as a safety gate before performing destructive file operations that

HasEmptyTargets returns true if any empty targets are active (set to true).

HasScope checks if the stored token for the given email was authorized with the specified scope. Returns false if the token doesn't exist or doesn't h

IMAPHost returns the correct IMAP hostname for the given email based on the persisted token's scope. Must be called after Authorize completes. Persona

InspectRawDataExists checks that raw MIME data exists for a message.

IsBusyError returns true for SQLITE_BUSY and SQLITE_LOCKED. Matching on the result code is more robust than substring matching: BUSY surfaces as "data

IsSentCopy reports whether this message appears to be the sender-side copy of an outbound email. Three independent signals (OR-combined): - Gmail SENT

LoadVector returns the embedding for a specific message in the active generation. Returns ErrNoActiveGeneration if none exists, or a descriptive error

MaxPageSizeHybridClamp returns the effective per-request limit clamp: zero means "no clamp", a positive value means "clamp to N". Helper exists becaus

MustBeLocal returns an error if remote mode is active. Use this for commands that only work with local database.

MustSearch calls Search and fails the test on error.

NewManagerWithScopes creates an OAuth manager with custom scopes.

NewMockAPI creates a new mock API with empty state.

NextFromOffset reports the stream offset of the next message's "From " line. Valid only after a successful Next() call (or Offset() at end-of-file).

NormalizeIdentifierForCompare returns the comparison-canonical form of an identifier under the same rules as EqualIdentifier and the SQL-side LOWER()

RebuildFTS fully recreates the FTS index from the underlying message tables. Unlike BackfillFTS (DELETE + INSERT), this drops and recreates the FTS ta

RemoveAccountIdentity deletes (source_id, address) rows that match under the helper's case-aware rule. Returns the number of rows deleted (typically 0

RemoveMessageLabels removes specific labels from a message.

RemoveSourcesFromCollection detaches sources. Idempotent. Rejects mutations of the auto-managed default collection.